tutuca 0.9.44 → 0.9.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.44",
+  "version": "0.9.46",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",
@@ -33,7 +33,7 @@
     "fix": "bunx @biomejs/biome check --write src test/*.js",
     "tutuca": "bun tools/tutuca.js",
     "stresstest": "bun scripts/stresstest.js",
-    "smoke-test": "bun tools/tutuca.js ./test/todo.js lint && bun tools/tutuca.js ./test/todo.js render && bun tools/tutuca.js ./test/json.js lint && bun tools/tutuca.js ./test/json.js render"
+    "smoke-test": "bun tools/tutuca.js ./test/todo.js lint && bun tools/tutuca.js ./test/todo.js render && bun tools/tutuca.js ./test/todo.js test && bun tools/tutuca.js ./test/json.js lint && bun tools/tutuca.js ./test/json.js render"
   },
   "sideEffects": false,
   "files": [
@@ -47,6 +47,7 @@
     "skill"
   ],
   "dependencies": {
+    "chai": "^6.2.2",
     "jsdom": "^28.0.0 || ^29.0.0"
   },
   "peerDependencies": {

package/skill/tutuca/advanced.md

@@ -145,7 +145,21 @@ collects the `class=` and `:class=` literals, hands them to a `compile`
 function (any margaui-compatible signature), and returns CSS text. Pair
 with `injectCss(scopeName, css)` to install the result before `start()`.
 
-If a margaui skill is installed in this project (e.g.
-`.claude/skills/margaui/`) load it alongside this one when authoring
-class lists — it lists the available components and their canonical
-class strings, which is what the `compile` step expects.
+If a margaui skill is available, load it alongside this one when
+authoring class lists — it lists the available components and their
+canonical class strings, which is what the `compile` step expects.
+
+**Pitfall: `@if.class` payloads are invisible to the scanner.** Classes
+inside `@then` / `@else` (e.g. `@if.class=".active" @then="'btn-success'"
+@else="'btn-ghost'"`) are not literals in `class=` / `:class=`, so
+`compileClassesToStyleText` skips them and the margaui CSS for those
+classes is never emitted — the conditional class renders unstyled.
+Workaround: add a hidden "decoy" view on the component that lists every
+conditional class as a real literal, so the walker picks them up:
+
+```js
+_margauiClasses: html`<p class="btn-success btn-ghost on off"></p>`,
+```
+
+The view does not need to be rendered anywhere — registration is enough
+for the template walker to find it.

package/skill/tutuca/cli.md

@@ -1,11 +1,11 @@
 # Tutuca CLI Reference
 
-The `tutuca` CLI inspects, documents, lints, and renders any module that
-follows the *Conventional Module Exports* shape (see `core.md`). Reach
-this file when you need command/flag/exit-code details, or when reading
-a lint code out of `lint` output. Otherwise the post-edit recipe in
-`core.md` (run `lint`, then `render --title "<your example>"`) is
-enough.
+The `tutuca` CLI inspects, documents, lints, tests, and renders any
+module that follows the *Conventional Module Exports* shape (see
+`core.md`). Reach this file when you need command/flag/exit-code
+details, or when reading a lint code out of `lint` output. Otherwise
+*Verifying changes* in `core.md` (run `lint`, then `test` for
+behavior changes, then `render --title "<your example>"`) is enough.
 
 ## Install / invoke
 
@@ -36,6 +36,7 @@ prints a one-liner. `tutuca` ↔ `tutuca -h` prints overview.
 | `docs [name]`   | Generate API docs (methods, input handlers, fields with auto-generated accessors) — all or one                         |
 | `lint [name]`   | Run the linter; exits **2** on any error-level finding                                                                 |
 | `render [name]` | Render examples to HTML in a headless DOM. Filter by component name or `--title`/`--view`. Exits **3** on render crash |
+| `test [name]`   | Run tests defined by `getTests({ describe, test, expect })`. Filter by component name, `--grep <pattern>`, or `--bail`. Exits **4** on any failure |
 | `help [cmd]`    | Show usage; the only command that does **not** need a module path                                                      |
 
 ## Global flags
@@ -61,6 +62,7 @@ prints a one-liner. `tutuca` ↔ `tutuca -h` prints overview.
 | `1`  | usage error (bad args, missing module, bad module shape) |
 | `2`  | lint findings at error level                             |
 | `3`  | render crash                                             |
+| `4`  | one or more tests failed                                 |
 
 ## Examples
 
@@ -77,8 +79,77 @@ tutuca ./src/components.js render Button --title "Disabled state"
 tutuca ./src/components.js lint
 tutuca ./src/components.js render --title "Disabled state"
 tutuca ./src/components.js render --title "Disabled state" --pretty
+
+# Component-behavior verification: run the suite for one component, or
+# narrow further with --grep. Add tests next to the component (the
+# getTests() export) when the change isn't observable from render alone.
+tutuca ./src/components.js test Counter
+tutuca ./src/components.js test Counter --grep "inc()"
+tutuca ./src/components.js test --bail
+```
+
+## `test` — running component tests
+
+Use `test` after edits that change attributes, instance methods, input
+handlers, or static factories — anything observable from JS rather than
+from rendered HTML. The module opts in by exporting
+`getTests({ describe, test, expect })`:
+
+- `describe(Component, fn)` tags the suite with `Component.name` so
+  the positional `[name]` filter can pick it.
+- `describe(title, fn)` is untagged; reachable only via `--grep`.
+- `describe(title, { component }, fn)` tags an explicit title with a
+  custom component name.
+- `test(title, fn)` — `fn` may be async; assertions use the injected
+  chai `expect`.
+
+Filters:
+
+- `[name]` — only tests whose tagged `componentName` equals `<name>`.
+- `--grep <p>` — substring match against the full path
+  (e.g. `"Counter > inc() > works on a negative counter"`).
+- `--bail` — stop on first failure; remaining tests reported as `skip`.
+
+Default format is `cli` (a tree with ✓/✗/○ and per-test durations);
+`-f md` and `-f json` work too.
+
+A worked `getTests()` export covering methods, input handlers (called
+via `Comp.input.x.call(inst)`), and immutability:
+
+```js
+export function getTests({ describe, test, expect }) {
+  describe(Counter, () => {
+    describe("inc()", () => {                           // method
+      test("returns a Counter with count + 1", () => {
+        const next = Counter.make().inc();
+        expect(next).to.be.instanceOf(Counter.Class);
+        expect(next.count).to.equal(1);
+      });
+      test("does not mutate the original instance", () => {
+        const c = Counter.make({ count: 7 });
+        c.inc();
+        expect(c.count).to.equal(7);                    // immutability
+      });
+    });
+
+    describe("dec()", () => {                           // input handler
+      test("returns a Counter with count - 1", () => {
+        const next = Counter.input.dec.call(Counter.make());
+        expect(next.count).to.equal(-1);
+      });
+    });
+
+    test("inc and dec round-trip", () => {              // untagged path
+      expect(Counter.input.dec.call(Counter.make().inc()).count).to.equal(0);
+    });
+  });
+}
 ```
 
+`describe(Counter, fn)` auto-tags the suite path with `Counter.name`, so
+`tutuca <module> test Counter` picks it up. Untagged `test(...)` at the
+top of a tagged `describe` inherits the tag.
+
 ## Install skill assets
 
 `tutuca install-skill` copies bundled Claude Code skill files into
@@ -100,7 +171,7 @@ tutuca install-skill --all --force     # overwrite existing files
 
 ## Linter Rules
 
-Codes emitted by `lint`. Source: `tools/core/lint-check.js`.
+Codes emitted by `lint`.
 
 ### Field references
 

package/skill/tutuca/core.md

@@ -15,8 +15,8 @@ the `tutuca` CLI.
 
 ## Verifying changes
 
-After editing a Tutuca module, run two checks before declaring the edit
-done:
+After editing a Tutuca module, run these checks before declaring the
+edit done:
 
 1. **Lint the module** — catches undefined fields/handlers/macros/events
    (all the `*_NOT_DEFINED` / `*_NOT_REFERENCED` codes):
@@ -26,7 +26,21 @@ done:
    Exits `2` on any error-level finding. Pass a component name to scope
    it: `tutuca <module-path> lint Button`.
 
-2. **Render the example(s) that exercise the feature you changed** —
+2. **Test component behavior** — when the edit changes attributes,
+   instance methods, input handlers, or static factories (anything
+   observable from JS, not just the rendered HTML), run the test
+   suite. The module opts in by exporting
+   `getTests({ describe, test, expect })`:
+
+        tutuca <module-path> test
+        tutuca <module-path> test Counter           # one component
+        tutuca <module-path> test --grep "inc()"    # one path
+
+   Exits `4` on any failure. Skip this step when the change is purely
+   templates/styling — `render` already covers that. Full reference,
+   including a worked `getTests()` export, in [cli.md](./cli.md).
+
+3. **Render the example(s) that exercise the feature you changed** —
    confirms the component actually mounts in a headless DOM with the new
    behavior. Pick the example whose `title` matches the feature, or
    filter by component:
@@ -69,11 +83,7 @@ Full reference: [cli.md](./cli.md).
   newline / indent before the first element renders blank silently.
   Use `view: html\`<el ...>` (or `html\`<el<newline>  attr<newline>>...`),
   never `view: html\`<newline>  <el ...>`. Same applies to macro bodies.
-- **Macro registry keys are normalized to lowercase.** The HTML parser
-  lowercases custom tag names, so `<x:Card>` is read as `<x:card>`.
-  `registerMacros({ Card })` is fine — the key is stored as `card`.
-  Registering two different macros under the same lowercased name (e.g.
-  `Card` and `card`) warns via `console.assert`; the later one wins.
+- **Macro registry keys are lowercased.** `<x:Card>` becomes `<x:card>` — see *Macros*.
 
 ## Bootstrap
 
@@ -100,7 +110,63 @@ app.start();
 `app.onChange((info) => ...)` fires after every state change with
 `{ val, old, info, timestamp }` (logging, persistence). `app.stop()`
 removes all listeners and cancels cache eviction; pair with
-`app.start()` for teardown in tests or SPA navigation.
+`app.start()` to remount cleanly in tests or SPA navigation.
+
+## Mental model
+
+Tutuca rests on three invariants: the application state is a single
+immutable root value; the view is a pure function of it; every handler
+takes the old self and returns a new self. The transactor swaps the
+root atomically. Identity-based caching, time-travel-style debugging,
+and the entire dispatch model fall out of these three properties.
+
+**The value tree.** Components are nested immutable Records. Children
+live in fields — a list of `Item`, a map of `User`, a scalar `count`.
+"Updating a deep child" means producing a new root that shares
+structure with the old one along the unchanged spine; the renderer
+keys its cache on `===` identity, so unchanged subtrees skip work.
+Every value carries a hidden tag back to its component class, so the
+runtime never needs `instanceof` — it asks the value what it is.
+
+**Stack: frames vs scopes.** As the renderer walks the AST it pushes
+`BindFrame`s. A *frame* is a barrier: name lookups (`@x`) stop at it,
+so a child component view sees a clean namespace. A *scope* is
+transparent: iteration `key` / `value` and `@enrich-with` binds layer
+onto the surrounding frame and remain visible to handlers attached to
+the same iteration. `it` (the target of `.field` lookups) is set on
+both.
+
+| pushed by                           | kind  | shape                                |
+| ----------------------------------- | ----- | ------------------------------------ |
+| `<x render=".f">` / `<x render-it>` | frame | `it` = child, fresh binds            |
+| `<x render-each>` per iter          | frame | `it` = item, binds `{ key }`         |
+| `<div @each>` per iter              | scope | `it` = item, binds `{ key, value }`  |
+| `<x:scope @enrich-with=…>`          | scope | `it` unchanged, binds = alter result |
+
+For full mechanics see *List Iteration* and *Scope Enrichment*.
+This is why a handler attached to `<div @each>` runs against the
+*parent* component (the scope is transparent — the surrounding frame
+still owns dispatch), while one inside `<x render-it>` runs against
+the *item* (render-it pushed a fresh frame for the child).
+
+**Paths, not references.** The DOM is the only thing that survives
+between render and click, so the renderer leaves breadcrumbs:
+`data-cid` / `data-nid` / `data-eid` on rendered elements, and `§…§`
+HTML comments adjacent to iteration entries. On a DOM event the
+runtime walks from the target up to the root, reads those breadcrumbs,
+and rebuilds a *positional* `Path` — an array of steps from the root
+to the value the handler should run against. The same `Path` is reused
+verbatim for `ctx.send`, `ctx.bubble`, and `ctx.request` /
+response: because it's positional rather than a captured reference, an
+async response still lands at the right slot even after intervening
+transactions have rebuilt the root. See *Bubble Events*, *Send /
+Receive*, *Async Requests* for the dispatch APIs.
+
+**Why `alter` is its own table.** Alter handlers are pure, evaluated
+on every render, and produce binds (no state change). `input` /
+`receive` / `bubble` / `response` are transactional and produce new
+values. Same lookup mechanism, different contracts — keep them
+separate.
 
 ## Notation Reference
 
@@ -316,7 +382,7 @@ consequences:
   custom elements with kebab-case attributes plus lowercased property
   setters (or aliases), and bind via `:kebab-name` from Tutuca templates.
 - Macro registry keys are lowercased on insert for the same reason
-  (see "Macros" section below).
+  (see *Macros* below).
 
 ## Event Handling
 
@@ -384,7 +450,7 @@ fails. `:mapId=".id"` does *not* invoke a `set mapId` setter
 — the HTML parser lowercased the attribute name, so the framework assigns
 to `node.mapid` instead, creating an own property and bypassing the
 setter. Use kebab-case attributes / lowercased setters when authoring
-custom elements for use with Tutuca. See "Attribute Binding" above.
+custom elements for use with Tutuca. See *Attribute Binding* above.
 
 ## Conditional Display
 
@@ -576,6 +642,10 @@ Every handler is called as `handler(...args, ctx)` and returns a
 returned value into the dispatch path. The four sections below cover
 each channel in turn.
 
+`alter` is a fifth handler block, but unlike the four above it isn't
+event-triggered — the renderer invokes alter handlers to produce
+binds, not to update state. See *Mental model* and *Scope Enrichment*.
+
 ## Bubble Events
 
 ```js
@@ -629,7 +699,8 @@ ctx.bubble("name", [arg]);                                 // bubble up
 `ctx.at` returns a `PathBuilder` with `.field(name)`, `.index(name, i)`,
 and `.key(name, k)`. Each call appends a step to the path before
 `.send(...)` / `.bubble(...)` fires; the handler runs inside the child
-instance with `this` bound to it.
+instance with `this` bound to it. Paths are positional, not references —
+see *Mental model* for why this matters across async boundaries.
 
 When to send: bubble emits an *event* that any ancestor with a
 matching handler can observe; send delivers a *message* to one
@@ -775,9 +846,8 @@ import {
 ```
 
 Because every `immutable` export is reachable through `tutuca`, if an
-`immutable-js` skill is installed in this project (e.g.
-`.claude/skills/immutable-js/`) load it alongside this one — its guidance
-applies directly to the values you'll be reading and writing.
+`immutable-js` skill is available, load it alongside this one — its
+guidance applies directly to the values you'll be reading and writing.
 
 ## Conventional Module Exports
 
@@ -797,4 +867,5 @@ export function getExamples()         {
     items: [{ title, description, value, view }],         // value = Comp.make(...)
   };
 }
+export function getTests({ describe, test, expect }) { /*...*/ }      // optional — see cli.md
 ```

package/skill/SKILL.md

@@ -1,46 +0,0 @@
----
-name: tutuca
-description: Authoring or reviewing tutuca components, html`` views, macros, or running the `tutuca` CLI. Covers field types, @-directives, bubble/receive/response handlers, and the post-edit `tutuca <module> lint` + `tutuca <module> render --title …` verification recipe.
----
-
-# Tutuca
-
-Tutuca is an immutable-state SPA framework: components have typed
-`fields`, auto-generated mutators (`setX`, `pushInX`, …), HTML-template
-`view`s with `@`-prefixed directives, and `bubble` / `receive` /
-`response` handlers for orchestration.
-
-## Verifying changes
-
-After editing a tutuca module, run two checks before declaring the edit
-done:
-
-1. **Lint** — catches undefined fields/handlers/macros/events. Exits
-   `2` on any error-level finding.
-
-   ```sh
-   tutuca <module-path> lint
-   ```
-
-2. **Render the example that exercises the feature you changed** —
-   confirms the component mounts in a headless DOM with the new
-   behavior. Exits `3` on render crash.
-
-   ```sh
-   tutuca <module-path> render --title "<example title>"
-   ```
-
-   If no example covers the feature, add one to `getExamples()` first —
-   that's how the feature becomes verifiable.
-
-## Routing
-
-| Task                                                                                           | File                            |
-| ---------------------------------------------------------------------------------------------- | ------------------------------- |
-| Authoring `component({...})`, `html\`...\`` views, macros, fields, events, lists, styles | [core.md](./core.md)           |
-| CLI commands, flags, exit codes, full linter rule list                                         | [cli.md](./cli.md)             |
-| Drag & drop, dynamic bindings (`*x`), pseudo-`x`, custom seq types, Tailwind/MargaUI | [advanced.md](./advanced.md)   |
-
-Read `core.md` first. Reach for `cli.md` or `advanced.md` only when the
-task touches them — both files are referenced inline from `core.md` so
-you'll be pointed there when relevant.

package/skill/advanced.md

@@ -1,146 +0,0 @@
-# Tutuca — Advanced Topics
-
-Reach this file only when the task touches drag & drop, context-style
-"dynamic bindings", pseudo-`x` (the `<x>`-stripping workaround inside
-`<select>`/`<table>`/`<tr>`), registering a custom seq type, or
-compiling Tailwind / MargaUI classes. For everything else, `core.md`
-is the right place.
-
-## Drag and Drop
-
-```html
-<div
-  @each=".items"
-  draggable="true"
-  data-dragtype="my-item"
-  data-droptarget="my-item"
-  @on.drop="onDrop @key dragInfo event"
-></div>
-```
-
-```js
-input: {
-  onDrop(targetKey, dragInfo, e) {
-    const sourceKey = dragInfo.lookupBind("key");   // any bind from source render
-    return this.setItems(this.items.moveKeyBeforeKey(sourceKey, targetKey));
-  },
-}
-```
-
-Tutuca auto-manages two attrs during a drag — style them with CSS:
-
-```css
-[data-dragging="1"] {
-  opacity: 0.5;
-}
-[data-draggingover="my-item"] {
-  outline: 1px dashed;
-}
-```
-
-Touch is wired up too (drag fires after a small move threshold).
-
-## Dynamic Bindings
-
-For passing values "context-style" through nested components without prop
-drilling. Define on the producer; alias on consumers; resolve as `*name`.
-
-```js
-const Theme = component({
-  name: "Theme",
-  fields: { color: "blue" },
-  dynamic: { color: ".color" },
-  on: {
-    stackEnter() {
-      return ["color"];
-    },
-  },
-});
-const Child = component({
-  dynamic: { color: { for: "Theme.color", default: "'gray'" } },
-  view: html`<p :style="color: {*color}"></p>`,
-});
-```
-
-`on.stackEnter()` is required only on the **producer** (the component
-declaring `dynamic: { name: ".field" }` to expose a value). It returns
-the list of dynamic-binding names this component pushes onto the stack
-when entering its render. Consumers (which only alias via
-`{ for: "Producer.name", default: ... }`) don't need it.
-
-## Pseudo-`x` (`@x`)
-
-Tutuca's special operations (`render`, `render-it`, `render-each`, `text`,
-`show`, `hide`, `slot`) live on the `<x>` tag. That works almost
-everywhere, but the browser's HTML parser refuses to keep `<x>` (or any
-unknown tag) as a child of certain elements: `<select>` only allows
-`<option>` / `<optgroup>`, `<table>` only allows `<thead>` / `<tbody>` /
-`<tr>`, `<tr>` only allows `<th>` / `<td>`, etc. Drop `<x render-each>`
-inside one of those and the parser silently strips it.
-
-The escape hatch: prefix the **first** attribute on a *legal* tag with
-`@x`. Tutuca treats that tag as if it were `<x>` and reads the next
-attribute as the special op.
-
-```html
-<!-- ❌ <x> stripped by the HTML parser inside <select> -->
-<select>
-  <x render-each=".items" as="option"></x>
-</select>
-
-<!-- ✅ pseudo-x: <option @x render-each=".items" as="option"> -->
-<select>
-  <option @x render-each=".items" as="option"></option>
-</select>
-```
-
-Notes:
-
-- `@x` must be the **first** attribute; the special op (`render-each`,
-  `render`, `text`, `show`, ...) is the second.
-- The host tag (here `<option>`) is otherwise ignored — only the special
-  op runs. Tutuca produces the rendered children directly.
-- Same trick works inside `<tr>`, `<table>`, `<colgroup>`, `<dl>`,
-  `<details>`, or anywhere else the parser would discard `<x>`.
-
-## Registering a custom seq type
-
-To make `@each` recognize your own collection class, install a
-`SEQ_INFO` walker on its prototype:
-
-```js
-import { SEQ_INFO } from "tutuca";
-
-class MyClass {
-  // ...
-}
-MyClass.prototype[SEQ_INFO] = (seq, visit) => {
-  for (const [k, v] of seq.entries()) visit(k, v, "data-sk");
-};
-```
-
-`SEQ_INFO` is `Symbol.for("tutuca.seqInfo")`, so the same identity
-is shared across module graphs (source vs. bundled tutuca). The
-renderer reads `seq[SEQ_INFO]` directly (no `.constructor` lookup),
-which is why the walker goes on the prototype, not as a static.
-
-The third arg to `visit` is the data attribute used for stable-key
-diffing (typically `"data-sk"` for "sequence key").
-
-## Tailwind / MargaUI Class Compilation (extra build)
-
-```js
-import { compileClassesToStyleText, injectCss, tutuca } from "tutuca/extra";
-import { compile } from "https://esm.sh/margaui";
-
-const app = tutuca("#app");
-app.registerComponents([Comp]);
-const css = await compileClassesToStyleText(app, compile);
-injectCss("myapp", css);
-app.start();
-```
-
-`compileClassesToStyleText` walks every registered component's templates,
-collects the `class=` and `:class=` literals, hands them to a `compile`
-function (any margaui-compatible signature), and returns CSS text. Pair
-with `injectCss(scopeName, css)` to install the result before `start()`.

package/skill/cli.md

@@ -1,117 +0,0 @@
-# Tutuca CLI Reference
-
-The `tutuca` CLI inspects, documents, lints, and renders any module that
-follows the *Conventional Module Exports* shape (see `core.md`). Reach
-this file when you need command/flag/exit-code details, or when reading
-a lint code out of `lint` output. Otherwise the post-edit recipe in
-`core.md` (run `lint`, then `render --title "<your example>"`) is
-enough.
-
-## Install / invoke
-
-```sh
-# project local
-npm i --save-dev tutuca
-npx tutuca <module-path> <command> [name] [flags]
-
-# global
-npm i -g tutuca
-tutuca <module-path> <command> [name] [flags]
-
-# from a checkout of this repo
-bun tools/tutuca.js <module-path> <command> [name] [flags]
-```
-
-The module path comes **first**, the command second, an optional component
-name third. `tutuca help` prints the full reference; `tutuca help <command>`
-prints a one-liner. `tutuca` ↔ `tutuca -h` prints overview.
-
-## Commands
-
-| Command         | Purpose                                                                                                                |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `info`          | Summarize which `getX()` exports are present and counts                                                                |
-| `list`          | List components with their views and fields (name + type)                                                              |
-| `examples`      | Print `getExamples()` content (title, items, per section)                                                              |
-| `docs [name]`   | Generate API docs (methods, input handlers, fields with auto-generated accessors) — all or one                         |
-| `lint [name]`   | Run the linter; exits **2** on any error-level finding                                                                 |
-| `render [name]` | Render examples to HTML in a headless DOM. Filter by component name or `--title`/`--view`. Exits **3** on render crash |
-| `help [cmd]`    | Show usage; the only command that does **not** need a module path                                                      |
-
-## Global flags
-
-```
--f, --format <cli|md|json|html>  output format
-                                 defaults: info/list/examples/lint → cli
-                                           docs/render             → md
-                                 html only valid for render
-                                 json works for every command
--o, --output <file>              write to file instead of stdout
-    --pretty                     pretty-print HTML (md/html) via prettier;
-                                 JSON formatter uses indent 2
-    --module <path>              alternative to first-positional module path
--h, --help                       show help (overview, or for one command)
-```
-
-## Exit codes
-
-| Code | Meaning                                                  |
-| ---- | -------------------------------------------------------- |
-| `0`  | success                                                  |
-| `1`  | usage error (bad args, missing module, bad module shape) |
-| `2`  | lint findings at error level                             |
-| `3`  | render crash                                             |
-
-## Examples
-
-```sh
-tutuca ./src/components.js info                       # quick overview
-tutuca ./src/components.js list                       # components, views, fields
-tutuca ./src/components.js docs Button -f json        # one component, JSON
-tutuca ./src/components.js render -f html --pretty -o out/examples.html
-tutuca ./src/components.js render Button --title "Disabled state"
-
-# Post-edit verification: lint, then render the example for the feature
-# you just changed (add the example first if none covers it). Add
-# --pretty when you need to read the HTML to verify structure.
-tutuca ./src/components.js lint
-tutuca ./src/components.js render --title "Disabled state"
-tutuca ./src/components.js render --title "Disabled state" --pretty
-```
-
-## Linter Rules
-
-Codes emitted by `lint`. Source: `tools/core/lint-check.js`.
-
-### Field references
-
-- `FIELD_VAL_NOT_DEFINED` — `.field` not declared in `fields`.
-
-### Input-handler / method confusion
-
-- `INPUT_HANDLER_NOT_IMPLEMENTED` — bare handler name not in `input`.
-- `INPUT_HANDLER_NOT_REFERENCED` — `input` entry never used.
-- `INPUT_HANDLER_METHOD_NOT_IMPLEMENTED` — `.handler` not in `methods`.
-- `INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD` — bare name resolves to `methods` (use `.name`).
-- `INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER` — `.name` resolves to `input` (drop the dot).
-
-### Iteration helpers (`alter`)
-
-- `ALT_HANDLER_NOT_DEFINED` — `@when` / `@enrich-with` / `@loop-with` name not in `alter`.
-- `ALT_HANDLER_NOT_REFERENCED` — `alter` entry never used.
-
-### Templates / events
-
-- `RENDER_IT_OUTSIDE_OF_LOOP` — `<x render-it>` outside `@each` / `render-each`.
-- `UNKNOWN_EVENT_MODIFIER` — `+mod` not in the recognized modifier set.
-- `UNKNOWN_HANDLER_ARG_NAME` — handler arg name not a built-in / declared component.
-- `DUPLICATE_ATTR_DEFINITION` — same attr set by literal + `:attr` + `@if.attr` on one element.
-- `UNKNOWN_DIRECTIVE` — `@name` directive not recognized (typo or unsupported).
-- `UNKNOWN_X_OP` — first attribute on `<x>` (or pseudo-`@x`) is not a known op.
-- `UNKNOWN_X_ATTR` — extra attribute on `<x op>` not consumed by the op and not a known wrapper (`show`/`hide`).
-
-### Names registered with the app
-
-- `UNKNOWN_REQUEST_NAME` — `!name` not registered.
-- `UNKNOWN_COMPONENT_NAME` — component type not registered.
-- `UNKNOWN_MACRO_ARG` — macro attr not declared in defaults.