tutuca 0.11.2 → 0.12.0

package/skill/tutuca/core.md

@@ -0,0 +1,918 @@
+# Tutuca — Core
+
+Tutuca is an immutable-state web framework powered by Immer: components have
+typed `fields`, native JavaScript collections, HTML-template `view`s with
+`@`-prefixed directives, and `receive` / `intent` handlers for
+orchestration. Read this file when authoring or reviewing
+`component({...})` definitions, `view: html\`...\`` templates, macros, or
+the `tutuca` CLI.
+
+> Load the topic files only when the task touches them (the routing
+> table in [SKILL.md](./SKILL.md) has the full descriptions):
+> [iteration.md](./iteration.md) · [macros.md](./macros.md) ·
+> [styles.md](./styles.md) · [messages-and-intents.md](./messages-and-intents.md) ·
+> [component-design.md](./component-design.md) · [testing.md](./testing.md) ·
+> [storybook.md](./storybook.md) · [cli.md](./cli.md) ·
+> [semantics.md](./semantics.md) · [advanced.md](./advanced.md) ·
+> [margaui.md](./margaui.md) · [patterns/README.md](./patterns/README.md).
+
+## Verifying changes
+
+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):
+
+        tutuca lint <module-path>
+
+   Exits `2` on any error-level finding. Pass a component name to scope
+   it: `tutuca lint <module-path> Button`.
+
+2. **Test component behavior** — when the edit changes attributes,
+   instance methods, receive 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 test <module-path>
+        tutuca test <module-path> Counter           # one component
+        tutuca test <module-path> --grep "inc()"    # one path
+
+   Exits `4` on any failure. Skip this step when the change is purely
+   templates/styling — `render` already covers that. Authoring patterns
+   (handler calling convention, designing handlers for testability,
+   worked `getTests` export) in [testing.md](./testing.md); CLI flags
+   and exit codes 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:
+
+        tutuca render <module-path> --title "Disabled state"
+        tutuca render <module-path> Button
+
+   Exits `3` if any render crashes. If no example covers the feature
+   you're adding, add one to `getExamples()` first — that's how the
+   feature becomes verifiable. Add `--pretty` when you need to read the
+   emitted HTML to verify structure (attributes, nesting, text); omit it
+   when you only care that the render didn't crash.
+
+4. **Smoke-test the whole project** — when you've touched several
+   `*.dev.js` modules, or are about to launch the storybook, do a
+   project-wide dry run instead of opening a browser:
+
+        tutuca storybook --dry-run
+        tutuca storybook --dry-run --json    # machine-readable for agents
+
+   It does everything the server would do up front — discovers every
+   co-located `*.dev.js`, imports and normalizes each (catching a missing
+   `getComponents()` or a malformed `getExamples()` shape), runs their
+   `getTests()`, and resolves the runtime import map — then prints what
+   it *would* show instead of serving. A broken module is reported in
+   place (an `error` line, or `modules[].error` in `--json`) while the
+   others still report, so one bad module never hides the rest. This is
+   the fast "is the whole catalog wired up correctly?" check; steps 1–3
+   stay the per-module loop.
+
+Full reference: [cli.md](./cli.md).
+
+The Tutuca CLI only catches Tutuca-specific issues. For generic JS
+problems, pair it with a general linter/formatter — e.g. set up Biome
+once with `npx -y @biomejs/biome init` and use its `lint`, `check`,
+and `format` subcommands. Run `npx @biomejs/biome -h` for usage help.
+
+## Common pitfalls
+
+- **`.field` reads a field, `$method` calls a no-arg method.** The two are
+  distinct prefixes: `.count` reads field `count`, `$inc` calls method
+  `inc`. Using the wrong one is a lint error that tells you to swap the
+  prefix.
+- **Paths are not allowed in values.** `.foo` resolves a single field on
+  `this` — `@text=".foo.bar"`, `:value=".user.name"`, `@show=".item.isOpen"`
+  all fail. To reach into nested data: render the child as a component
+  (`<x render=".foo">` then `@text=".bar"` inside), add a method
+  (`fullName() { return this.user.name; }` and use `$fullName`), or use
+  `@enrich-with` for scope-level derivation. The one exception: a
+  **binding** may read exactly one **binding member** —
+  `@text="@value.title"` inside `@each` works (any `@`-binding, one level
+  only; a binding member read like `@value.a.b` is a lint error, and
+  render targets still reject it).
+- **State writes happen on the handler's first `draft` argument.** `this` is
+  the frozen pre-transaction snapshot. Arrays, objects, Map, and Set use their
+  normal JavaScript mutation APIs on `draft`.
+- **Multiple `@if.<attr>` on one element.** Every `@then`/`@else` after
+  the first must name the attr (`@then.title`, `@else.title`) — HTML
+  disallows duplicate attrs, so the second `@then=` is dropped silently.
+- **Bare unquoted multi-word strings return `null`.** Either quote
+  (`'flex gap-3'`) or use a `$'…'` string template (`$'flex gap-3 {.color}'`).
+- **`<x>` is stripped inside `<select>` / `<table>` / `<tr>`.** Use the
+  `@x` pseudo-x trick (see [advanced.md](./advanced.md)).
+- **`receive.init` is a convention, not a lifecycle hook.** Nothing calls it
+  automatically — dispatch via `app.sendAtRoot("init")` or from
+  another handler.
+- **`app.state.set(...)` takes a component instance**, not plain data.
+  Build with `Comp.make({...})`.
+- **`html\`` templates must start with the opening tag.** A leading
+  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 lowercased.** `<x:Card>` becomes `<x:card>` — see [macros.md](./macros.md).
+
+## Bootstrap
+
+```js
+import { component, html, tutuca } from "tutuca";
+
+const Counter = component({
+  name: "Counter",
+  fields: { count: 0 },
+  receive: {
+    inc(draft) {
+      draft.count++;
+    },
+  },
+  view: html`<button @on.click="inc" @text=".count"></button>`,
+});
+
+const app = tutuca("#app");
+app.registerComponents([Counter]);
+app.state.set(Counter.make({}));
+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()` to remount cleanly in tests or SPA navigation.
+
+## Mental model
+
+Tutuca rests on three invariants: application state is one deeply frozen root;
+the view is a pure function of it; and every dispatched handler receives an
+Immer draft as its first argument while `this` remains the immutable current
+snapshot. The transactor commits the produced root atomically.
+
+**The value tree.** Components are generated Immer-draftable classes. Children
+live in fields — an array of `Item`, a native `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.
+
+Because children are ordinary frozen values held in fields, **handlers
+and methods are ordinary JS with full read access to nested child
+state** — `this.child.count`, `this.items[i].done`,
+`this.byKey.get(k).label`. Reading *down* the tree is direct and needs
+no channel: an ancestor that owns a list already holds every child's
+state and can read it for an aggregate decision. The single-level
+`.field` restriction (no `.foo.bar`) is a **view-template** rule, not a
+JS one — it's why a derivation like `userName() { return this.user.name; }`
+is written as a method (see *Methods as Predicates & Computed Values*).
+Reading is free; **mutating** a child still flows through the model — mutate
+the addressed draft or message the child with `ctx.send`. Don't reach in to
+mutate the frozen snapshot,
+and prefer letting a child own and render its own state — reach down to
+read only when the ancestor genuinely needs it. See
+[component-design.md](./component-design.md) and "When to send" in
+[messages-and-intents.md](./messages-and-intents.md).
+
+**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` reads and `$method`
+calls) 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 }`  |
+| `<div @enrich-with=…>` (no `@each`) | scope | `it` unchanged, binds = alter result |
+
+For full mechanics see [iteration.md](./iteration.md).
+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` and `ctx.intent`: because it's positional rather
+than a captured reference, an async answer survives intervening
+transactions that rebuild the root.
+"The right slot" is exact for named fields and for map entries by key
+(seq-access keys like `.sheets[.selId]` are *pinned* to their
+dispatch-time value by default); a bare list **index** still slides if the
+list reordered. See [messages-and-intents.md](./messages-and-intents.md) for the
+dispatch APIs and [semantics.md](./semantics.md) for the path/transaction
+model and key pinning.
+
+**Why `alter` is its own table.** Alter handlers are pure, evaluated
+on every render, and produce binds (no state change). `receive` and
+`intent` are transactional and produce new values. Same lookup mechanism, different contracts — keep them
+separate.
+
+## Notation Reference
+
+Views are name-based: there is no arithmetic expression syntax in
+values, and no Vue- or Mustache-style `{{ … }}` placeholders. Every
+value slot — conditions (`@show`, `@if`), iteration (`@each`,
+`render-each`, `@when`), enrichment (`@enrich-with`, `@loop-with`), template
+expansion (`{…}`, `:attr`, `@text`) — names a field, method, macro, or
+handler defined on the component (or registered with the app). Logic
+lives in `methods` / `alter` / `receive` / `intent` and is referenced by
+name; the template itself only routes
+data and events.
+
+The one exception is **boolean predicates** in conditional slots
+(`@show`, `@hide`, `@if.<attr>`): a closed set of operators applied to
+a value, written predicate-first like a handler call —
+`empty?`, `truthy?`, `falsy?`, `null?`, `equals?`. E.g.
+`@hide="empty? .items"`, `@show="truthy? .query"`. A conditional slot
+otherwise accepts the same value forms as `@text` — a plain field
+(`@show=".isOpen"`), a no-arg method (`@show="$canSubmit"`), or a loop/scope
+`@binding` (`@show="@isSelected"`, `@hide="@hasDesc"`) — read as a boolean.
+
+`equals?` takes two args and is the idiomatic way to show/hide by name,
+e.g. `@show="equals? .view 'detail'"`. Predicate args (and handler
+args) accept string literals: `'detail'`, or `'two words'` for a
+literal with spaces (escape an interior quote as `\'`).
+
+| Prefix   | Means                                     | Example               |
+| -------- | ----------------------------------------- | --------------------- |
+| `.x`     | field on `this` (single-level — no `.foo.bar` paths) | `.count`, `.title` |
+| `$x`     | no-arg method call on `this` (a method reference) | `$inc`, `$canSubmit` |
+| `@x`     | local binding (loop / scope)              | `@key`, `@value`      |
+| `^x`     | macro parameter                           | `^label`              |
+| `*x`     | dynamic binding — see [advanced.md](./advanced.md) | `*theme`          |
+| `Name`   | component type (PascalCase)               | `Item`, `JsonNull`    |
+| `name`   | bare identifier — meaning depends on slot | `dec`, `value`        |
+| `'str'`  | string literal                            | `'btn btn-success'`   |
+| `$'…'`   | string template (`{expr}` interpolation)  | `$'Hi {.name}'`       |
+| `.s[.k]` | sequence/map item access                  | `.byKey[.currentKey]` |
+| `pred? .x` | boolean predicate in a conditional slot | `empty? .items`, `equals? .view 'detail'` |
+
+`.x` and `$x` are not interchangeable: `.x` only reads a field, `$x`
+only calls a method. The linter flags a mismatch and tells you which
+prefix to use.
+
+A bare `name` (no prefix) in `@on.<event>="<handler> <arg> <arg>..."`
+resolves by slot:
+
+- **First slot** — handler name looked up in `receive` / `alter` (use
+  `$name` for `methods`).
+- **Subsequent slots** — built-in handler argument name (full list in
+  *Event Handling*); anything else triggers a lint warning.
+
+```html
+<button @on.click="addItem JsonSelector">+</button>
+<!--                ↑ handler ↑ Type -->
+```
+
+`ctx` (an `EventContext`) is auto-appended as the trailing arg, so the
+handler is called as `addItem(JsonSelector, ctx)`. Don't list `ctx` in
+the template — it's always passed.
+
+## Quoting & String Literals
+
+A string template is written `$'…'` — a single-quoted run with a leading
+`$`, holding `{expr}` interpolations. `:attr=` and other text slots accept
+`$'…'` templates; `@if`, `@each`, `<x render=>` do not.
+
+| Form                | Example                   | Where it works                                   |
+| ------------------- | ------------------------- | ------------------------------------------------ |
+| `'string'`          | `@then="'btn ok'"`        | anywhere a value is allowed                      |
+| `$'…'` template     | `:class="$'btn {.kind}'"` | `:attr=`, `@text`, `@title`, macro dynamic attrs |
+| Bare without quotes | `flex gap-3`              | **never** — returns `null`                       |
+| Bare identifier     | `dec`, `value`            | name slots only (handler/arg, not as a value)    |
+
+```html
+<!-- ✅ -->
+<p :class="'flex gap-3'">x</p>
+<p :class="$'flex {.color}'">x</p>         <!-- $'…' string template -->
+<p :class="$'static-classes {\'\'}'">x</p> <!-- folds to a const -->
+
+<!-- ❌ -->
+<p :class="flex gap-3">x</p>               <!-- null: no quotes -->
+<p :class="flex {.color}">x</p>            <!-- null: unquoted {…} is not a template -->
+<x render="'foo bar'"></x>                 <!-- @render rejects string templates -->
+```
+
+## Component Skeleton
+
+The object passed to `component({...})` is the **component spec** — the
+linter warns on unknown spec keys. The full shape:
+
+```js
+component({
+  name: "MyComp",
+  fields: {                    // see "Field Types"
+    count: 0,
+    items: [],
+    nullable: null,
+  },
+  view: html`<p @text=".count"></p>`,    // default view (named "main")
+  views: {                                // additional views
+    edit: html`<input :value=".count" @on.input="setCount e.valueAsInt" />`,
+    big: {
+      view: html`<h1 @text=".count"></h1>`,
+      style: css`h1 { font-size: 4rem; }`,
+    },
+  },
+  style:        css`p { color: blue; }`,         // scoped to main view
+  commonStyle:  css`p { font-family: sans-serif; }`, // scoped to all views of this component
+  globalStyle:  css`body { margin: 0; }`,        // injected globally, no scoping
+  methods: {
+    doubled() { return this.count * 2; },
+  },
+  alter:   { filterItem(_k, item) { return item.length > 0; } },
+  // ADDRESSED: this component's own @on.* names, what a parent sends it, and the
+  // answers to intents it raised — one bucket, and nothing tells them apart.
+  receive: {
+    inc(draft)             { draft.count++; },
+    setCount(draft, value) { draft.count = value; },
+    onClick(draft)         { draft.count++; },
+    init(_draft, ctx)      { ctx.intent("loadData", [], { route: ["lex"] }); },
+    loadDataOk(draft, res) { draft.items = res; },
+    loadDataError(draft, err) { draft.error = String(err); },
+  },
+  // ROUTED: what this component answers for somebody who did not address it.
+  intent:  { itemPicked(draft, item) { draft.selected = item; } },
+  statics: { fromData(d) { return this.make({ count: d.n ?? 0 }); } },
+  // provide: { ... }, lookup: { ... }   // see advanced.md
+});
+```
+
+`Comp.make({...})` builds and deeply freezes an instance. Arrays, plain objects,
+native `Map`, and native `Set` stay native. Wrap nested component data with
+`Child.make({...})` when it needs component identity and its own view/handlers.
+
+## Field Types
+
+`fields: { name: defaultValue }` — type inferred from the default.
+
+| Default | Field type | Draft update example |
+| --- | --- | --- |
+| `"hi"` | text | `draft.x = value` |
+| `42` | float | `draft.x++` |
+| `{ type: "int", defaultValue: 0 }` | int | `draft.x = Math.trunc(value)` |
+| `true` | bool | `draft.x = !draft.x` |
+| `null` | any | `draft.x = value` |
+| `[]` | list | `draft.x.push(value)`, `draft.x.splice(i, 1)` |
+| `{}` | object | `draft.x.key = value` |
+| `new Map()` | map | `draft.x.set(key, value)` |
+| `new Set()` | set | `draft.x.add(value)`, `draft.x.delete(value)` |
+
+Fields do not generate setters or collection mutators. Define only the named
+handlers your view/API needs; the linter reports a field/method name collision.
+
+Emptiness / truthiness / null checks are not generated as methods — use
+the boolean predicates `empty?`, `truthy?`, `falsy?`, `null?`, `equals?`
+in a conditional slot instead (e.g. `@hide="empty? .x"`,
+`@show="equals? .view 'detail'"`).
+
+Explicit field types via `classFromData`:
+
+```js
+fields: {
+  count: { type: "int", defaultValue: 10 },       // text/int/float/bool/list/object/map/set/any
+  child: { component: "Item", args: { ... } },    // deferred reference by name
+  child2: Item.make({ name: "" }),                // direct default if Item is in scope
+}
+```
+
+The `{ component, args }` form is for when the referenced component is **not
+available** at field-definition time (forward reference, circular import).
+`component` must be the component **name as a string** — passing the class
+itself is a common mistake and is flagged by lint code
+`COMP_FIELD_BAD_SHAPE`. When the component class **is** in scope, prefer
+`ComponentName.make({...})` as the default value — no string indirection.
+
+## Methods as Predicates & Computed Values
+
+A no-arg method called via `$name` is invoked and its return value is
+used. Works anywhere a value is read — `@text`, `:attr`, `@show` /
+`@hide`, `@if.<attr>`, and `{…}` interpolation. (`.name` is a field
+read and never invokes; `$name` is the method call.)
+
+```js
+methods: {
+  canSubmit()   { return this.title.length > 0 && !this.isLoading; },
+  buttonClass() { return this.isActive ? "btn btn-primary" : "btn"; },
+  fullName()    { return `${this.first} ${this.last}`; },
+}
+```
+
+```html
+<button @show="$canSubmit" :class="$buttonClass">Save</button>
+<p :title="$'Hello, {$fullName}'" @text="$fullName"></p>
+```
+
+The boolean predicates (`empty?`, `truthy?`, `falsy?`, `null?`,
+`equals?`) cover single-field checks in conditional slots; reach for a
+method when the condition spans multiple fields or needs derivation. The
+method takes no args.
+
+Tutuca expressions resolve a **single** name on `this` — there is no
+path syntax. `@text=".user.name"` does not navigate; it fails. When the
+value lives behind a field, your options are:
+
+- **Render the child as a component** — `<x render=".user">` then
+  `@text=".name"` inside the child's view. Best when the nested thing is
+  already (or could be) a component.
+- **Add a method** — `userName() { return this.user.name; }` then
+  `@text="$userName"`. Best for one-off derivations or formatting.
+- **Use `@enrich-with`** — exposes computed values as `@`-bindings to a
+  subtree without putting them on the component. See *Scope Enrichment*
+  in [iteration.md](./iteration.md).
+
+Exceptions: `@each` / `render-each` accept `.field` or `*dynamic` only
+(not a `$method` — a method result has no addressable path for event
+dispatch, so `$m` is rejected there at parse time), and `<x render>`
+expects a component instance — for a derived list, store it in a field
+or use `@when` with `alter`.
+
+## Statics
+
+`statics: {...}` adds methods to the component **class**, not instances.
+`component({...})` returns that class directly — the component IS the class,
+with its metadata (fields, views, handlers, spec) attached behind
+`tutuca`'s well-known `COMPONENT` symbol. Statics are available as
+`Comp.<name>(...)` alongside the auto-generated `Comp.make(...)`. Inside a
+static, `this` is the class itself.
+
+Common use: a `fromData` factory that recursively builds instances from
+plain JS data:
+
+```js
+statics: {
+  fromData({ items = [] }) {
+    return this.make({ items: items.map((v) => Item.fromData(v)) });
+  },
+}
+// usage: TreeRoot.fromData([...])
+```
+
+> **Scopes own the component.** A component is bound to a scope at
+> `registerComponents` time — that scope owns its component, tag,
+> and scope-bound `make`/statics — so a given component object is live in
+> one scope at a time. Each app/registry is a separate scope; the same
+> *object* registered into two of them rebinds (last wins). To run the
+> same definition in two genuinely separate registries at once, build an
+> independent copy with `component(Comp.spec)` (new id ⇒ separately
+> compiled CSS + separate identity — the price of isolation, not a way to
+> dedupe within one app). For reuse inside one scope, register the single
+> object once and re-export it.
+
+**Multi-scope caveat for statics.** A static like `fromData` that builds
+a *different* child type by naming the imported const directly
+(`Item.fromData(v)` above) hardcodes the child's *original* scope.
+Fine in a single-scope app; across scopes, resolve the child through the
+caller's scope instead — `this.scope.lookupComponent("Item")` — so it
+deserializes into the right one. Recursion into the *same* type needs no
+lookup: `this.fromData(v)` / `this.make` already target the caller's scope.
+
+## Text Rendering
+
+```html
+<span @text=".str"></span>          <!-- prepend text into span -->
+<x text=".bool"></x>                <!-- text-only, no DOM element -->
+<x text="$getStrUpper"></x>         <!-- $ calls a method -->
+<x text="@value"></x>               <!-- loop binding -->
+```
+
+Use `@text` when you already have a host element to put the text in; use
+`<x text=…>` for bare text with no wrapping element (e.g. text interleaved with
+other inline content, or a loop binding). Both take the same value forms
+(`.field`, `$method`, `@binding`).
+
+## Attribute Binding
+
+```html
+<input :value=".str" @on.input="setStr e.value" />
+<a :href=".url" :title="$'Hi {.name}'">link</a>       <!-- string template -->
+<button :class="$'btn {.color}'">x</button>
+```
+
+Plain attrs are static. `:attr="..."` is a dynamic expression. Boolean
+HTML attributes (`disabled`, `checked`, `hidden`, …) are auto-recognized;
+pass a boolean field.
+
+A static `class="…"` and a dynamic `:class`/`@if.class` **cannot coexist on the
+same element** — setting one attribute two ways is a lint error
+(`DUPLICATE_ATTR_DEFINITION`), and at runtime the dynamic value wins and the
+static class is dropped. Fold any structural classes into the bound expression,
+e.g. `:class="$'btn {.color}'"` (note `btn` is part of the template, not a
+separate `class="btn"`). The same applies to other attributes — see the
+duplicate-attribute note below.
+
+The HTML parser lowercases attribute names before Tutuca sees them, so
+`:mapId` arrives as `:mapid` and `<x:Card>` becomes `<x:card>`. Three
+consequences:
+
+- SVG attributes are case-sensitive. Tutuca special-cases `:viewbox` →
+  `viewBox` so SVG roots work; for other camelCased SVG attrs, wrap them
+  in components that emit raw markup.
+- Custom-element property setters defined in camelCase **will not fire**.
+  `:mapId=".mapId"` runs `node.mapid = value`; if the
+  element defined `set mapId(...)`, the lookup misses and JS silently
+  creates an own data property `mapid` on the element instead of invoking
+  the setter — no error, no warning, the bound state stays null. Author
+  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.md](./macros.md)).
+
+Tutuca auto-namespaces by subtree: elements inside `<svg>` get the SVG
+namespace and elements inside `<math>` get MathML, with spec-cased local
+names preserved (`linearGradient`, `viewBox`). A `<foreignObject>` switches
+its children back to the HTML namespace. Customised built-in elements work
+via `is="..."` (e.g. `<button is="x-fancy">`); `is` is applied when the
+element is created, so it must be a static attribute — setting it later
+does not upgrade the element.
+
+### When nothing renders (or renders unstyled)
+
+A few mistakes fail quietly — no error, just a blank or unstyled result, which
+is the slowest kind to debug. **Run `tutuca lint <module>` first**: it catches
+several of these. The usual suspects:
+
+- **Unparseable attribute value** → the attribute is silently dropped. A bare
+  multi-word value isn't a string — quote it (`:label="'two words'"`) or make it
+  a template (`:label="$'{.a} {.b}'"`). Lint flags this as `BAD_VALUE`.
+- **camelCase attribute on a custom element** → setter no-op (see the lowercasing
+  note above). Use kebab-case attributes. Not lintable — the HTML parser
+  lowercases the name before either Tutuca or the linter sees it.
+- **Forgotten margaui `_palette`/decoy view** → classes assembled in methods or
+  interpolations render unstyled. See [margaui.md](./margaui.md). Not lintable.
+- **A whitespace-only `html\`\``** → blank render. A *leading* newline before the
+  root element is fine (the parser trims it); a template with no element at all
+  is not.
+
+## Event Handling
+
+```html
+<!-- every event names a receive handler (no prefix) -->
+<button @on.click="inc">+</button>
+<button @on.click="dec">-</button>
+
+<!-- pass args by name -->
+<input @on.input="setStr e.value" />
+<input @on.input="setN e.valueAsInt" />
+<button @on.click="pick @key e.altKey">pick</button>
+<button @on.click="addItem JsonSelector">+</button>     <!-- type as arg -->
+<button @on.click="loadAnotherWay">load</button>        <!-- ctx auto-appended -->
+```
+
+Every `@on.<event>` handler receives an `EventContext` as its trailing
+arg automatically — written args come first, `ctx` last. So
+`loadAnotherWay` is called as `loadAnotherWay(draft, ctx)`, and
+`pick @key e.altKey` is called as `pick(draft, key, isAlt, ctx)`. You can still
+write `ctx` in the template (it resolves to a fresh `EventContext`), but it is
+redundant.
+
+Handler argument forms:
+
+- **Event-member reads** — `e.value`, `e.key`, `e.altKey`, `e.target`, plus
+  dotted paths into the event: `e.target.dataset.slot`, `e.target.id`,
+  `e.detail.x`. Null-safe at every link; a missing member reads as null.
+- **Computed conveniences** with no single-property form — `e.valueAsInt`,
+  `e.valueAsFloat`, `e.isCtrl`/`e.isCmd` (mac-aware), `e.isUpKey`, `e.isDownKey`,
+  `e.isSend`, `e.isCancel`, `e.isTabKey`, and on drags `e.dragInfo`/
+  `e.dragKey`/`e.dragValue`/`e.dragType`. Resolved only as a one-level path;
+  nothing composes through them (`e.target.isUpKey` is null).
+- **Channel args** — `ctx` (the `EventContext`) and `dragInfo`.
+
+The content of `e.value` depends on the event source:
+
+| Source                      | What `e.value` resolves to                       |
+|-----------------------------|--------------------------------------------------|
+| `<input type="checkbox">`   | `event.target.checked` (boolean)                 |
+| `CustomEvent`               | `event.detail`                                   |
+| anything else               | `event.target.value` (string), or null if absent |
+
+For numeric inputs, prefer `e.valueAsInt` / `valueAsFloat` to skip the
+string parse.
+
+Ask for the most granular arg the handler actually uses — `e.value` /
+`e.valueAsInt` / `e.key`, not the raw event object — when the specific value is
+all you need. A handler that takes `event` forces every test and
+storybook story to fabricate a DOM-event-shaped object
+(`{ target: { value: … } }`); one that takes `value` is called with a
+plain literal. (Genuine exceptions exist — e.g. a file input needs
+`event` to reach `event.target.files`.) See
+[testing.md](./testing.md) *Designing handlers so tests stay simple*.
+
+### Event Modifiers
+
+`@on.<event>+<mod>+<mod>=...`
+
+Guards — run the handler only when they hold:
+
+- All events: `+ctrl`, `+cmd`/`+meta`, `+alt`
+- `keydown` only: `+send` (Enter), `+cancel` (Escape)
+
+Effects — act on the DOM event, on all events:
+
+- `+prevent` → `event.preventDefault()`
+- `+stop` → `event.stopPropagation()`
+
+```html
+<input @on.keydown+send="submit e.value" @on.keydown+cancel="reset" />
+<button @on.click+ctrl="soloOnly">ctrl-click</button>
+<form @on.submit+prevent="save">…</form>
+<input @on.keydown+send+prevent="submit e.value" />
+```
+
+Effects apply only when every guard on the same handler passed, whatever
+order they are written in: `+send+prevent` prevents on Enter and nothing
+else. They run from the app's root listener, which is where tutuca listens
+— that is invisible to `+prevent` (the default action happens after the
+event finishes propagating) but it makes `+stop` narrower than it looks:
+it stops listeners *outside* the app root only. DOM ancestors between the
+target and the root have already seen the event, and tutuca runs a single
+handler per event anyway, so `+stop` never suppresses another `@on`.
+
+### Web Components & Custom Events
+
+Custom elements just work, and any `CustomEvent` they fire is reachable
+via `@on.<event-name>`. The event's `detail` surfaces as `value`:
+
+```js
+import "https://cdn.jsdelivr.net/npm/emoji-picker-element/+esm";
+
+receive: { onPick(draft, detail) { draft.current = detail.unicode; } }
+view: html`<emoji-picker @on.emoji-click="onPick e.value"></emoji-picker>`,
+```
+
+Handle these events declaratively with `@on.<event-name>` in the view —
+don't grab the node from host/glue code and `addEventListener` on it. A
+listener attached from outside the component runs outside the handler
+model: no draft transaction, no transactor batching, and the mutation
+is invisible to the component that owns the state (the same hazard as
+reaching into `app.state` directly). For any event with a real element in
+the tree, `@on.` is the only entry point you need. Genuinely external
+inbound sources (WebSocket, `postMessage`, timers) have no element to bind
+— route those through `app.sendAtRoot` instead (see
+[messages-and-intents.md](./messages-and-intents.md)).
+
+Pitfall: binding a camelCase JS property on a custom element silently
+fails — see the lowercasing rules in *Attribute Binding* above.
+
+## Conditional Display
+
+```html
+<div @show=".isLoading">Loading...</div>
+<div @hide=".isLoading">content</div>
+
+<!-- boolean predicates; equals? compares against a string literal -->
+<div @show="equals? .view 'detail'">detail view</div>
+
+<!-- @show / @hide also work as directives on `<x>` render ops:
+     wraps the produced node, no extra DOM element. Allowed on
+     text / render / render-it / render-each. First attr in
+     source order becomes the outermost wrapper. -->
+<x text=".name" @show=".isOpen"></x>
+<x render-it @hide=".isHidden"></x>
+<x render-each=".items" @when="filter" @show=".isOpen"></x>
+
+<!-- Single @if: shorthand @then/@else (attr inferred) -->
+<button @if.class=".isActive" @then="'btn btn-success'" @else="'btn btn-ghost'">
+  ...
+</button>
+
+<!-- Multiple @if on same element: name the attr explicitly -->
+<button
+  @if.class=".isActive"
+  @then="'on'"
+  @else="'off'"
+  @if.title=".isActive"
+  @then.title="'On'"
+  @else.title="'Off'"
+>
+  ...
+</button>
+```
+
+> HTML disallows duplicate attrs, so with multiple `@if.<attr>` on one
+> element every `@then`/`@else` after the first **must** include the attr
+> name — otherwise the parser drops it before tutuca sees it.
+
+## List Iteration & Scope Enrichment
+
+```html
+<li @each=".items"><span @text="@key"></span>: <x text="@value"></x></li>
+<x render-each=".items"></x>
+```
+
+Auto-bound names inside a loop are `@key` and `@value`. Iteration
+(`@each` / `render-each`), filtering (`@when`), item and scope
+enrichment (`@enrich-with`), pagination and the `@loop-with` return
+shape, and the `@each` lifecycle: see [iteration.md](./iteration.md).
+
+## Rendering Components
+
+```html
+<x render=".item"></x>                          <!-- default ("main") view -->
+<x render=".item" as="edit"></x>                <!-- specific view (literal) -->
+<x render=".item" as=".mode"></x>               <!-- view chosen by a field at runtime -->
+<x render-it></x>                               <!-- only inside @each / render-each -->
+<x render=".byIndex[.currentIndex]"></x>        <!-- list item access -->
+<x render=".byKey[.currentKey]"></x>            <!-- map item access -->
+<x render="*active"></x>                        <!-- dynamic binding — see advanced.md -->
+<x render=".item" @show=".isOpen"></x>          <!-- conditional wrap, see "Conditional Display" -->
+```
+
+The top-level `view` is registered under `"main"` (the default); extras
+go under `views: { name: html\`...\` }`. `as` selects which view of the
+rendered component to use, falling back to `main` if absent. It accepts the
+same dynamic values as `@push-view` (a literal name like `edit`, or `.field`,
+`*dyn`, `@bind`, `$method`, `$'…{x}…'`), evaluated against the **host**
+component at render time. `as` only applies to the **direct** component — for
+whole-subtree control, use `@push-view` (next section). For `render-each` the
+selector is evaluated once against the host, so every item gets the same view.
+
+## Multiple Views & View Stack
+
+```js
+component({
+  view:  html`<p @text=".title"></p>`,                              // "main"
+  views: { edit: html`<input :value=".title" @on.input="setTitle e.value" />` },
+});
+```
+
+```html
+<!-- @push-view pushes a name onto the rendering stack;
+     descendants resolve to first matching view, falling back to "main" -->
+<div @push-view=".view"><x render-each=".items"></x></div>
+```
+
+| Directive          | Scope                                                                    |
+|--------------------|--------------------------------------------------------------------------|
+| `as="edit"` / `as=".mode"` | One `<x render>` element only. Literal or dynamic (like `@push-view`), evaluated against the host. |
+| `@push-view=".v"`  | Every component rendered recursively under the host (children + descendants). Each picks the first stack entry it has a matching view for; falls back to `"main"`. Inner `@push-view`s nest, extending the outer ones. |
+
+## Styles
+
+`style` is scoped to the main view, `commonStyle` to all views of the
+component, `globalStyle` is injected unscoped (see the *Component
+Skeleton* above). Scoping mechanics, styling the root element with bare
+declarations, and the at-rules that must live in `globalStyle`: see
+[styles.md](./styles.md). Tailwind / MargaUI utility classes:
+[margaui.md](./margaui.md).
+
+## Triggers and Handlers
+
+Tutuca has **two** dispatch channels, and one question separates them:
+*does the sender know who handles this?*
+
+| Triggered by                                     | Handler block      | Use for                                          |
+| ------------------------------------------------ | ------------------ | ------------------------------------------------ |
+| DOM event (`click`, `input`, …)                  | `receive: { ... }` | the component handling its own events            |
+| `ctx.send(name)` — message to a target path      | `receive: { ... }` | addressing one known component (or self)         |
+| an answer to an intent this component raised     | `receive: { ... }` | `<name>Ok` / `<name>Error` / `<name>Unhandled`   |
+| `ctx.intent(name, args, opts)` — walks a route   | `intent:  { ... }` | a job the sender does not address                |
+
+The first three rows are one bucket and **nothing tells them apart** — a
+component that answered its own click differently from the identical
+`ctx.send` from its parent could be driven neither from a test nor from a
+parent.
+
+An intent carries a **route**: `["dyn"]` walks the ancestors, `["lex"]`
+walks the handlers registered on the scope, and the default `["dyn","lex"]`
+tries both. The verb does not decide which scope answers — the route does,
+written at the call site.
+
+Every dispatched `receive` or `intent` handler is called as
+`handler(draft, ...args, ctx)`. `this` is the immutable current instance;
+`draft` is its Immer draft; `ctx` is always trailing. Mutate `draft` and
+return nothing (or return `draft`) to commit. Return any other value to swap
+the addressed component for that value. Mutating the draft and returning a
+replacement in the same handler is an error. An unchanged recipe preserves
+the current identity. Routes,
+`ctx.reply` / `ctx.fail` / `ctx.forward` / `ctx.stop`, the three
+outcomes, `ctx.at`, the `$unknown` fallback, and intent-handler
+registration are in [messages-and-intents.md](./messages-and-intents.md);
+worked snippets in
+[patterns/coordinate-components.md](./patterns/coordinate-components.md).
+
+`alter` is a third handler block, but it isn't event-triggered — the
+renderer invokes alter handlers with their existing read-only signature to
+produce binds, not state changes
+(see *Mental model*, and *Scope Enrichment* in
+[iteration.md](./iteration.md)).
+
+## Macros
+
+Pure template expansion — `macro({ params }, html\`...\`)` definitions
+called as `<x:name>`, with `^param` references, slots, and named slots:
+see [macros.md](./macros.md). Registry keys are lowercased —
+`<x:Card>` resolves as `<x:card>`.
+
+## Raw HTML (escape hatch)
+
+```html
+<div @dangerouslysetinnerhtml=".trustedHtml"></div>
+```
+
+Bypasses all escaping; children of the element are ignored when active.
+
+## Immer Utilities
+
+Tutuca uses Immer internally but does not add Immer's API to the root export.
+Import recipe utilities explicitly when tests or host code need them:
+
+```js
+import { produce, immerable } from "tutuca/immer";
+```
+
+Generated component classes are already draftable. Add `[immerable] = true`
+to custom classes stored in state. Native `Map` and `Set` support is enabled by
+the `tutuca/immer` entry point.
+
+## Conventional Module Exports
+
+Examples and the storybook glue follow this shape so files compose freely
+and the `tutuca` CLI can introspect any module without per-app glue:
+
+```js
+export function getComponents()       { return [Comp, ...]; }
+export function getMacros()           { return { name: macro }; }      // optional
+export function getIntentHandlers()  { return { name: async fn }; }    // optional
+export function getRoot()             { return Root.make({...}); }
+export function getExamples()         {
+  // Return one section, or an array of sections.
+  return {
+    title: "...",
+    description: "...",
+    // value = Comp.make(...); intentHandlers (optional) mocks this example's requests
+    items: [{ title, description, value, view, intentHandlers }],
+  };
+}
+export function getTests({ describe, test, expect }) { /*...*/ }      // optional — see cli.md
+```
+
+An example item may carry an optional **`intentHandlers`** map — per-example
+mocks (keyed by request name) that override the module's real
+`getIntentHandlers()` for that one instance, so two examples of the same
+component show different responses side by side. Return a fixture, `throw` for
+the error path, or never resolve to hold a loading state. Full treatment, plus
+the `on` lifecycle hooks, in [storybook.md](./storybook.md).
+
+Best practice: have `getComponents()` return **every** component the module
+defines — child and helper components included — and give each one at least
+one item in `getExamples()`. A component left out of `getComponents()` is
+invisible to `tutuca lint`/`render`/`test`, so it silently loses linting and
+render coverage. If your components already live behind a differently named
+export, alias it instead of teaching tools a new name:
+
+```js
+export { allMyComponents as getComponents } from "./app.js";
+```
+
+Put these exports in a co-located **`*.dev.js`** file (a dev-only module
+holding stories + tests, never shipped) and `tutuca storybook` auto-discovers
+and renders them with no setup — see [cli.md](./cli.md). The same shape is
+consumed by the shipped `tutuca/storybook` library if you want to embed a
+storybook in your own page — see [storybook.md](./storybook.md).
+
+## See also
+
+- [iteration.md](./iteration.md) — `@each` / `render-each`, `@when`,
+  `@enrich-with`, `@loop-with` pagination, and the loop lifecycle.
+- [macros.md](./macros.md) — `macro()` definitions, `<x:name>` calls,
+  slots, and registration.
+- [styles.md](./styles.md) — `style` / `commonStyle` / `globalStyle`
+  scoping mechanics and pitfalls.
+- [component-design.md](./component-design.md) — design judgment for shaping a
+  feature into components: responsibilities, where state lives, which channel to
+  reach for, and a curated do's & don'ts list.
+- [messages-and-intents.md](./messages-and-intents.md) — addressed
+  `send`-`receive` vs routed `intent`, the `ctx.at` `PathBuilder`, `$unknown`, and
+  request-handler registration.
+- [advanced.md](./advanced.md) — dynamic bindings (`*x`), pseudo-`@x` for
+  `<select>` / `<table>` / `<tr>`, drag & drop, custom seq types.
+- [margaui.md](./margaui.md) — setting up MargaUI styling: install
+  (CDN / npm / vendoring), theme CSS, and `compileClassesToStyleText`.
+- [semantics.md](./semantics.md) — runtime semantics: path steps, the
+  transaction lifecycle, dyn-var teleporting, and async key pinning
+  (`livePath`).
+- [testing.md](./testing.md) — `getTests` shape and the handler calling
+  convention for tests.
+- [storybook.md](./storybook.md) — authoring `*.dev.js` story modules and
+  running / embedding the storybook.
+- [cli.md](./cli.md) — commands, flags, exit codes, and the full linter rule
+  list.
+- [patterns/README.md](./patterns/README.md) — task-oriented recipes ("how do I
+  iterate / filter / paginate / show-hide / build tabs / share state / …"),
+  each linking back here and to a runnable example.