# Project Agents.md Guide This is a [MoonBit](https://docs.moonbitlang.com) project — a port of [tutuca](https://github.com/marianoguerra/tutuca). References below to JS files like `src/vdom.js`, `src/path.js`, `tools/core/test.js`, or `docs/examples/*.js` point at that upstream repo, not at files in this one. You can browse and install extra skills here: ## Project Structure - MoonBit packages are organized per directory; each directory contains a `moon.pkg` file listing its dependencies. Each package has its files and blackbox test files (ending in `_test.mbt`) and whitebox test files (ending in `_wbtest.mbt`). - In the toplevel directory, there is a `moon.mod` file listing module metadata. The toplevel package itself is intentionally minimal (just the `README.mbt.md` doctest) — the foundational value language + path/dispatch runtime lives in `core/` (imported everywhere as `@tutuca` via `"marianoguerra/tutuca/core" @tutuca`). It is one package by necessity: its `value_*` and `path_*` types form a single dependency cycle that can't be split across an import edge (see `core/spec.mbt`). ## Coding convention - MoonBit code is organized in block style, each block is separated by `///|`, the order of each block is irrelevant. In some refactorings, you can process block by block independently. - Try to keep deprecated blocks in file called `deprecated.mbt` in each directory. - Files named `*_gen.mbt` are GENERATED and checked in; never hand-edit one. Change its source and rerun the task that produces it (`gen-views` for a `*_view_gen.mbt` from its `.html`; `skill-embed` for `cli/skill_assets_gen.mbt` from `skill/tutuca/`). `moon fmt` owns the layout of the `*_view_gen.mbt` pair, so the `gen-views` task formats after generating — run the task, not the CLI directly, and the checked-in files stay reproducible. (`cli/skill_assets_gen.mbt` is the exception: it is NOT fmt-stable, so revert it after a `moon fmt` and regenerate through `skill-embed`. Since `gen-views` and `fmt` both end in `moon fmt`, run `skill-embed` after either of them before checking for drift.) - `dyncomp/` has four documents, and they divide as: `DESIGN.md` is the contract and how it maps onto tutuca; `SECURITY.md` is what a loaded bundle can and cannot do, with the file/line evidence for each claim; `ARCHITECTURE.md` is the plan for the universal UI and the agent runtime on top; and `docs/agent-runtime.md` is the tool surface a language model addresses. Changing the WIT means checking `SECURITY.md`'s "What to check when changing this" — two of its three findings were fields nobody thought were a channel. - The guest binding trees under `guests/counter/` and `guests/todo/` are generated and checked in the same way, by `gen-guest-bindings`, from the ONE WIT in the repo (`dyncomp/wit/tutuca-component.wit` — no guest keeps a copy, and the Rust guest's `generate!` macro reads it too). `wit-bindgen`'s raw output has to be normalized before it can be checked in meaningfully: it emits its FFI shims in HASH order, which differs between two runs on the same input. `guests/gen-bindings.mjs` sorts them (MoonBit `///|` blocks are order-irrelevant) and drops the `moon.pkg.json` twins of the hand-maintained package files, which is what makes the drift check honest. It also copies `guests/sdk.mbt` — the ONE guest SDK, for the same reason there is one WIT — into every guest tree, and writes one formatted copy back, since the canonical is in no moon module and `moon fmt` would never reach it. The one handwritten file left in those trees is the component source (`counter.mbt`, `todo.mbt`, …); its name is one wit-bindgen never emits, so regeneration leaves it alone. ## Tooling ### Task runner (`cmd/dev`) Common workflows are collected in a MoonBit task runner instead of loose commands. It is the single place tasks live (the `dev/` package holds the task list; `cmd/dev` is the native shell that runs it): ``` moon run --target native cmd/dev -- ``` | Task | Does | |------------|------------------------------------------------------------------| | `check` | `moon check` for default, js and native targets | | `fmt` | `moon fmt` then `moon info` (format + regenerate `.mbti`) | | `test` | `moon test` for default, native, and js browser adapters | | `build` | `moon build` for wasm-gc, native CLI, and js | | `coverage` | `moon coverage analyze` | | `setup` | `npm install` (happy-dom for js tests) + enable the git hooks | | `ci` | `gen-views` drift check, then `check`, the example/skill/guest-template checks, `test` and `build` | | `dist` | build all targets and assemble a self-contained runnable `dist/` | | `gen-views` | regenerate the checked-in `*_view_gen.mbt` from their `.html` sources (`viewgen/`); formats after generating, then drift-checks the generated modules — a stale one type-checks and tests green, so this is what catches it | | `gen-guest-bindings` | regenerate the checked-in MoonBit guest bindings (every guest in `guests/guests.mjs`) from the ONE WIT (`dyncomp/wit/tutuca-component.wit`), copy in the ONE SDK (`guests/sdk.mbt`), then drift-check them | | `skill-embed` | regenerate `cli/skill_assets_gen.mbt` from `skill/tutuca/` (the embedded assets `tutuca install-skill` writes out; `dist` runs it first) | | `guest-template-embed` | regenerate `cli/guest_template_gen.mbt` — the guest tree `tutuca new-guest` writes out — from `guests/counter` (bindings + SDK) + `dyncomp/wit` (the contract) + `guests/template` (the overlay that carries the `{{name}}` placeholders); `dist` runs it beside `skill-embed` | | `check-guest-template` | scaffold a guest with that embed and `moon check --deny-warn` it; part of `ci`, and the only coverage `new-guest` has (CI never builds a real guest — `guests` needs wasm-tools and jco) | | `check-skill` | compile-check the MoonBit snippets in `skill/tutuca/` and check every one against the `.mbti` files for names that no longer exist; part of `ci` | | `css-bundle` | regenerate `css/{tailwind,margaui}_bundle_gen.mbt` from the pinned `tailwindcss` npm release + a margaui clone (needs network); see "Styling" below | | `npm-pack` | stage + `npm pack` the playground's two npm packages from an assembled `dist/` (manifests in `playground/npm/`); packs only — publishing is manual, see CONTRIBUTING.md | While editing views, `tutuca watch [path…]` regenerates them on every save (mizchi/fswatch; native only, since the watcher is the shell's job). It manages the `.html` files that already have a generated sibling, so pointing it at a project root does not try to compile `index.html`. Add `--tailwind-css`/`--margaui-css ` and it rewrites that stylesheet too, once per settled batch over every watched view. The `playground` task ends with `playground/build/check-viewgen-tab.mjs`: the View tab generates a MoonBit module in the browser and feeds it to the in-browser compiler, and nothing else exercises that path — the generated module compiles in a package with no `moon.pkg`, where `@tutuca` is the module-root facade rather than `core/`. It drives generate → compile → link headlessly against the assembled payload, for every standalone-playground starter example with a View tab (`playground/web/starter.js` — covered here and nowhere else) AND every landing-site example pair (`playground/site/examples/.{mbt,html}`, which the embedded `` elements compile in a visitor's browser). The cheaper `check-examples` task covers the same examples through `moon check` instead, generating their views with the same generator built to js. `check-skill` reuses that same js generator for the bundled skill. Nothing else compiles `skill/tutuca/`, and it rots: `specs=` / `@component.FieldSpec` outlived the parameter's removal by two releases in five files, and the skill ships inside the CLI binary, so a wrong snippet is what an agent reads before writing any tutuca code. A recipe that shows both halves — an ```` ```html ```` view file then the ```` ```moonbit ```` that uses it — gets the view half generated and the pair compiled together, per markdown SECTION (snippets in one section refer to each other; snippets in different sections are unrelated components that would collide). Fences are load-bearing: bare ```` ```moonbit ```` is compiled, `moonbit fragment` is wrapped in a `fn` first, and `moonbit nocheck` is skipped but **must** carry a `// nocheck: ` line. Most blocks are bucket-argument fragments that no wrapper makes compilable, so they are `nocheck` — which is why every block, `nocheck` included, additionally goes through an identifier check against the checked-in `.mbti` files. That second pass is the one that catches a removed parameter, and it is the reason the task is worth having at all. Nothing in the playground shell resolves a fetched URL against the page. `runtime.js`'s `playgroundConfig` derives the four of them — the worker, the compiler blob, `manifest.json`, `fs/` — from the calling module's own `import.meta.url`, and `makeCompiler` hands them to the worker **absolutely**, so the worker resolves nothing against its own location either. That is what lets the payload sit somewhere other than the shell (a different folder, package, or origin — a cross-origin worker gets a same-origin blob shim, since a `Worker` script must be same-origin), and what lets a host serve their own `@moonbit/moonc-worker` rather than a copy of the 5.5 MB blob: `globalThis.MB_PLAYGROUND = { payloadBase, compilerUrl, workerUrl }` (all optional) before the first compile. A host-supplied compiler is checked against `manifest.mooncWorker` when npm's `package.json` sits beside it — the payload and the compiler are one pair, and a mismatch otherwise surfaces as nonsense about the user's code (`playground/vendor/README.md`). `dist` produces `dist/index.html` (a landing page with run instructions), `dist/counter/` (the **js** counter demo with its bundle, `