tutuca 0.11.2 → 0.12.0

package/skill/tutuca/advanced.md

@@ -0,0 +1,212 @@
+# 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>`), or registering a custom seq type. For
+compiling Tailwind / MargaUI classes see [margaui.md](./margaui.md); 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
+receive: {
+  onDrop(draft, targetKey, dragInfo, e) {
+    const sourceKey = dragInfo.lookupBind("key");   // any bind from source render
+    const [item] = draft.items.splice(sourceKey, 1);
+    draft.items.splice(targetKey, 0, item);
+  },
+}
+```
+
+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" to a deep descendant without threading
+them through every component in between. **`provide`** on the producer;
+**`lookup`** on consumers; resolve as `*name`.
+
+> **Best practice:** keep state local to the component and reach for
+> `provide` / `lookup` only when it is genuinely the only solution. Dynamic
+> bindings couple a consumer to a producer that may not be in scope — prefer
+> keeping components as self-contained as possible: let a child render the
+> field it needs from its owner, and lift state only as far up the tree as it
+> actually needs to live.
+
+```js
+const Theme = component({
+  name: "Theme",
+  fields: { color: "blue" },
+  provide: { color: ".color" },
+});
+const Child = component({
+  lookup: { color: { for: "Theme.color", default: "'gray'" } },
+  view: html`<p :style="$'color: {*color}'"></p>`,
+});
+```
+
+A **`provide`** maps an exported name to a field expression. Every
+provide is evaluated and pushed onto the dynamic stack automatically
+when the producer is entered during render — there is no hook to opt in.
+
+A **`lookup`** reads a value the `*name` way: the key is the name used
+in views (`*color`), the value is `"Producer.provideName"`, or
+`{ for: "Producer.provideName", default: ".field" }` to supply a
+fallback when no producer is in scope (default is optional — without it
+a miss resolves to `null`). A `*name` that names the component's own
+`provide` resolves to the nearest provided value (including its own).
+
+### Dynamic vars as render targets
+
+A `*name` dynamic var resolves to a value, so it works anywhere a value
+is read — not just in `:style` / `:class`. In particular it can be a
+component-render target and an iteration source:
+
+```html
+<x render="*selected"></x>           <!-- render the dynamic's component -->
+<x render="*selected" as="edit"></x> <!-- a specific view of it -->
+<div @each="*items"><x render-it></x></div>  <!-- iterate a dynamic seq -->
+```
+
+A `provide` value must be **addressable** — a `.field` or a `.seq[.key]`
+seq-access, nothing else. (It is both read as `*name` *and* used as a
+render-target / teleport path, so a method or constant — which has no
+path — is a lint error.) A `lookup` `default`, by contrast, is only a
+value fallback and accepts the full grammar, including constants like
+`'gray'`. A `provide` can be a sequence/map item access:
+
+```js
+const Root = component({
+  name: "Root",
+  fields: { items: new Map(), selectedKey: "" },
+  provide: {
+    items: ".items",                  // the whole sequence
+    selected: ".items[.selectedKey]", // seq-access to one entry
+  },
+});
+```
+
+There is **no `*name[.key]` form** — a consumer never indexes a dynamic
+var. The seq-access lives in the producer's `provide` declaration; the
+consumer just reads the resolved value as `*name`.
+
+**Teleporting.** The component rendered via `<x render="*selected">`
+physically lives at the producer (e.g. `Root.items`), not under the
+consumer. When an event fires inside that dynamically-rendered subtree,
+the runtime expands the *render* path (consumer → … → the rendered
+node) to reconstruct the handler, but the *transaction* is teleported:
+the mutation skips the intermediate components and lands on the
+producer's data. Editing the entry in the consumer and the same entry
+in the producer's own view update in lock-step.
+
+## 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. Drop `<x render-each>`
+inside one of those and the parser silently strips it.
+
+The parser strips `<x>` only inside the **table family** and **`<select>`**.
+Use pseudo-`@x` when the parent is one of:
+
+`table`, `thead`, `tbody`, `tfoot`, `tr`, `colgroup`, `select`, `optgroup`.
+
+Everywhere else `<x>` is kept and needs no workaround — including `ul`, `ol`,
+`li`, `dl`, `dt`, `dd`, `details`, `summary`, `caption`, `td`, `th`. So
+`<ul><x render-each=".items">…</x></ul>` is fine. (When in doubt, the rule of
+thumb is: any element whose HTML content model only permits *specific* child
+tags — table sections and `<select>` — strips `<x>`.)
+
+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 any of the stripping parents listed above
+  (`<table>`/`<tr>`/`<colgroup>`/`<select>`/…).
+
+## 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";
+import { immerable } from "tutuca/immer";
+
+class MyClass {
+  static [immerable] = true;
+  // ...
+}
+MyClass.prototype[SEQ_INFO] = (seq, visit, start, end) => {
+  for (const [k, v] of seq.entries()) visit(k, v, "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 `immerable` marker lets handlers mutate instances of the custom class
+through a draft while preserving its prototype.
+If rendered entries can receive updates, also implement `get(key, fallback)`
+and a `set(key, value)` method that mutates the drafted instance. Tutuca uses
+those methods to look up and graft a finalized child through a keyed path.
+
+The third arg to `visit` must be `"sk"` (keyed entries) or `"si"`
+(positional indexes): it is the meta key event-path reconstruction
+reads to resolve an event back to its entry — any other value means
+`@key` and keyed steps silently stop resolving inside `@each`.
+
+`start`/`end` are an optional `[start, end)` slice produced by
+`@loop-with` (Array.slice semantics). Walkers may ignore them, in
+which case `@loop-with` ranges simply don't apply to that type.
+
+See `docs/examples/custom-collection.js` for a complete worked
+example: an Immer-draftable keyed list whose walker supports slicing and
+whose entries resolve `@key` in event handlers.
+
+## Tailwind / MargaUI Class Compilation (extra build)
+
+Moved to [margaui.md](./margaui.md) — installing margaui (CDN / npm /
+vendoring), the theme CSS, the `compileClassesToStyleText` + `injectCss`
+wiring, and the assembled-class-names decoy-view pitfall.

package/skill/tutuca/cli.md

@@ -0,0 +1,239 @@
+# Tutuca — CLI Reference
+
+The `tutuca` CLI inspects, documents, lints, tests, and renders any
+module that follows the
+[Conventional Module Exports](./core.md#conventional-module-exports)
+shape. Reach this file when you need command/flag/exit-code
+details, or when reading a lint code out of `lint` output. The
+post-edit verification recipe is in
+[Verifying changes](./core.md#verifying-changes).
+
+## Install / invoke
+
+```sh
+# project local
+npm i --save-dev tutuca
+npx tutuca <command> <module-path> [name] [flags]
+
+# global
+npm i -g tutuca
+tutuca <command> <module-path> [name] [flags]
+
+# from a checkout of this repo
+node tools/tutuca.js <command> <module-path> [name] [flags]
+```
+
+The command comes **first**, the module path second, an optional component
+name third. `tutuca help` prints the full reference; `tutuca help <command>`
+prints a one-liner. `tutuca` ↔ `tutuca -h` prints overview.
+Use `--module=<path>` if the path conflicts with positional parsing.
+
+## Commands
+
+| Command                  | Purpose                                                                                                                |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `get <module>`           | Summarize which `getX()` exports are present and counts                                                                |
+| `list <module> [name] [--limit n]` | List components with their views and fields (name + type). `--limit n` caps; `0` = all                  |
+| `examples <module> [--limit n]` | Print `getExamples()` content (title, items, per section). `--limit n` caps total items; `0` = all                                          |
+| `show <module> [name]`   | Show API docs (methods, receive/intent handlers, and fields) — all or one                             |
+| `lint <module> [name]`   | Run the linter; exits **2** on any error-level finding                                                                 |
+| `render <module> [name]` | Render examples to HTML in a headless DOM. Filter by component name or `--title`/`--view`. Exits **3** on render crash |
+| `test <module> [name]`   | Run tests defined by `getTests({ describe, test, expect })`. Filter by component name, `--grep <pattern>`, or `--bail`. Exits **4** on any failure |
+| `storybook [dir]`        | Serve a live storybook for the project, auto-discovering co-located `*.dev.js` modules. Flags: `--port`, `--out`, `--dry-run` (prep + print, don't serve), `--no-margaui`, `--no-check`, `--no-tests`. No module path needed |
+| `help [cmd]`             | Show usage. No module path needed                                                                                      |
+| `feedback [message]`     | Append a feedback note (positional or stdin) to `~/.tutuca/feedback.jsonl`. No module path needed                      |
+| `install-skill [name]`   | Copy a bundled skill (`tutuca`, `margaui`, or `--all`) into `.claude/skills/`. No module path needed   |
+| `agent-context`          | Print a versioned JSON schema of every command, flag, exit code, and error code. No module path needed                 |
+
+## Global flags
+
+```
+    --json                       shorthand for `--format=json`. Recommended
+                                 for agent/script callers — error envelopes
+                                 are also JSON on stderr (see "Errors" below)
+-f, --format <cli|md|json|html>  output format
+                                 defaults: get/list/examples/lint → cli
+                                           show/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 second-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                                             |
+| `4`  | one or more tests failed                                 |
+
+## Errors
+
+Diagnostics go to **stderr**; structured output goes to **stdout**. Errors
+include "did you mean" suggestions for unknown commands and unknown flags
+(same shape as lint suggestions).
+
+Under `--json`, errors are emitted as a single-line JSON envelope on stderr:
+
+```json
+{"error":{"code":"ERR_USAGE_UNKNOWN_FLAG","message":"Unknown flag '--titel'","suggestion":{"kind":"replace-name","from":"--titel","to":"--title"},"hint":"Valid flags: ..."}}
+```
+
+Stable error codes:
+
+| Code                          | When                                          |
+| ----------------------------- | --------------------------------------------- |
+| `ERR_USAGE_UNKNOWN_COMMAND`   | command name not recognized                   |
+| `ERR_USAGE_UNKNOWN_FLAG`      | flag not recognized for the command           |
+| `ERR_USAGE_BAD_FLAG_VALUE`    | flag rejected the value (e.g. wrong type)     |
+| `ERR_USAGE_MISSING_MODULE`    | command needs a module path but none was given |
+| `ERR_USAGE_MISSING_ARGUMENT`  | required positional/stdin missing             |
+| `ERR_USAGE_MUTUALLY_EXCLUSIVE`| conflicting flags                             |
+| `ERR_FORMAT_UNKNOWN`          | `--format` value not in {cli,md,json,html}    |
+| `ERR_FORMAT_UNSUPPORTED`      | format chosen doesn't support the result kind |
+| `EXAMPLES_SHAPE_MISMATCH`     | module returned a non-conforming shape        |
+| `ERR_SKILL_ASSETS_MISSING`    | bundled skill assets not found                |
+| `ERR_SKILL_TARGET_EXISTS`     | install-skill target exists; use `--force`    |
+
+## Examples
+
+```sh
+tutuca get ./src/components.js                        # quick overview
+tutuca list ./src/components.js                       # components, views, fields
+tutuca show ./src/components.js Button --json         # one component, JSON
+tutuca render ./src/components.js -f html --pretty -o out/examples.html
+tutuca render ./src/components.js 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 lint ./src/components.js
+tutuca render ./src/components.js --title "Disabled state"
+tutuca render ./src/components.js --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 test ./src/components.js Counter
+tutuca test ./src/components.js Counter --grep "inc()"
+tutuca test ./src/components.js --bail
+```
+
+## `test` — running component tests
+
+Use `test` after edits that change attributes, instance methods, receive
+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.
+
+The `getTests` shape and the calling conventions (`inst.computedMethod()`,
+`Comp.receive.x.call(inst, draft, …)`, the `drive` cascade helper, iteration
+handlers) are in [testing.md](./testing.md).
+
+## storybook — live component catalog
+
+`tutuca storybook [dir]` serves a browser storybook with no setup — it
+discovers co-located `*.dev.js` modules, runs their `getTests()`, wires
+margaui, and serves an ephemeral page. Its flags (`--port`, `--out`,
+`--dry-run`, `--no-margaui`, `--no-check`, `--no-tests`) are in the
+Commands table above. Authoring `.dev.js` modules, the example/section shape,
+per-example request mocking, and runtime resolution are all in
+[storybook.md](./storybook.md).
+
+## Install skill assets
+
+`tutuca install-skill` copies bundled Claude Code skill files into
+`.claude/skills/<name>/` so a session in this directory picks them up.
+
+```sh
+tutuca install-skill                   # tutuca skill (default), into ./.claude/skills/tutuca/
+tutuca install-skill --user            # ~/.claude/skills/tutuca/
+tutuca install-skill --margaui-skill   # margaui skill instead of tutuca
+tutuca install-skill --all             # all bundled skills (tutuca + margaui)
+tutuca install-skill --dot-agents      # install into ./.agents/skills/ instead of ./.claude/skills/
+tutuca install-skill --all --force     # overwrite existing files
+tutuca install-skill --dry-run         # print files that would be written, don't touch disk
+```
+
+`--user`/`--project` choose scope (default `--project`).
+`--margaui-skill` and `--all` are mutually exclusive.
+`--dot-agents` swaps the `.claude` base for `.agents` (combines with any scope/selection).
+
+## Record feedback
+
+`tutuca feedback` appends a freeform feedback record to
+`~/.tutuca/feedback.jsonl` (created on first use). Record a note
+whenever the CLI, the bundled skills, this reference, or the library
+itself was confusing, broken, or surprising — capture it in the
+moment instead of reconstructing it later.
+
+```sh
+tutuca feedback "lint code FIELD_VAL_NOT_DEFINED didn't suggest the missing field"
+echo "render --pretty produced different output than -f html --pretty" | tutuca feedback
+tutuca feedback < notes.txt
+```
+
+Each record is one JSON object per line: `{ts, version, message}`.
+No module path is required. Empty input (no positional, no piped
+stdin) exits **1** with a usage error.
+
+## Linter Rules
+
+`lint` reports findings at three levels — **error**, **warn**, **hint** —
+and exits `2` if any finding is at error level.
+
+The codes are not duplicated here, to keep this file from drifting out of
+sync with the implementation. The authoritative, always-current list of
+component-linter codes (code, level, one-line description, grouped by
+category) is available straight from the CLI:
+
+- `tutuca help lint` — human-readable table.
+- `tutuca agent-context` — machine-readable: the `lintCodes` array, each
+  entry `{ code, level, group, summary }`.
+
+Categories include field/method references, receive handlers, iteration
+helpers (`alter`), dynamic bindings (`*name`),
+template/event issues, value-expression errors, and unregistered names.
+Representative codes: `FIELD_VAL_NOT_DEFINED`, `METHOD_VAL_IS_FIELD`,
+`ALT_HANDLER_NOT_DEFINED`, `DYN_VAL_NOT_DEFINED`, `UNKNOWN_DIRECTIVE`,
+`UNSUPPORTED_EXPR_SYNTAX`.
+
+`lint` also runs an HTML structural linter (fragment mode) that emits
+`HTML_*` codes for malformed or misnested template markup; those are
+reported through the same channel. Its messages use WHATWG parser
+vocabulary:
+
+- **foster-parenting** — the parser moves content that isn't allowed
+  inside a table out in front of it.
+- **adoption agency** — the algorithm that reorders misnested formatting
+  tags (`<b><i></b></i>`).
+- **void element** — an element with no close tag (`<br>`, `<img>`); an
+  explicit `</br>` is flagged.
+- **insertion mode** — the parser context named in "not allowed in …"
+  messages (e.g. "in table body").
+- **bogus comment** — malformed markup the parser reinterprets as a
+  comment, dropping its content.

package/skill/tutuca/component-design.md

@@ -0,0 +1,168 @@
+# Tutuca — Component Design
+
+How to *shape* a feature into one or more tutuca components — responsibilities,
+where state lives, which channel to reach for — before you reach for syntax. The
+mechanics live elsewhere: component skeleton, fields, directives, and the
+post-edit verification recipe in [core.md](./core.md); the orchestration channels
+in [messages-and-intents.md](./messages-and-intents.md); dynamic bindings (`provide` /
+`lookup` / `*x`) in [advanced.md](./advanced.md); task recipes in
+[patterns/README.md](./patterns/README.md). This file is a router with judgment
+attached — every rule points at its canonical home rather than restating it.
+Read it when deciding how to split a feature into components, where a piece of
+state should live, how two components should talk, or when reviewing a component
+for design smells.
+
+## Decide in this order
+
+Walk these top-down whenever you add or reshape a component:
+
+1. **What single responsibility is this?** If the answer has an "and" in it, split
+   it into separate components.
+2. **Who owns each piece of state?** The component that reads and mutates a value
+   owns it. Put the field there; let others render or message it.
+3. **How do these components talk?** Pick the narrowest channel that reaches the
+   owner — see the ladder below.
+4. **Where does the outside world cross the boundary?** Outbound I/O goes through
+   `ctx.intent(..., { route: ["lex"] })`; inbound external events go through
+   `app.sendAtRoot` to the root. Keep the logic inside tutuca on both sides.
+
+## Communication decision ladder
+
+This ladder is about *acting across* a component boundary — reaching up,
+messaging a target, doing async work, or mutating state someone else owns. It is
+**not** about merely *reading* a child's state: an ancestor already holds its
+children as frozen fields and can read them directly in any handler or method
+(`this.items[i].done`) — no channel needed. See [core.md](./core.md) "The
+value tree".
+
+Reach for the *narrowest* channel that does the job, and only move further down
+the ladder when the one above can't express it:
+
+- **The component owns the state needed to respond** → mutate its handler
+  **draft**, optionally via a helper method passed that draft. See
+  [core.md](./core.md) Methods.
+- **You know exactly which component must be told** → **`ctx.send` / `receive`**,
+  addressing a specific path with `ctx.at` (defaults to self). See
+  [messages-and-intents.md](./messages-and-intents.md) "When to send".
+- **You do not know who should answer** → **`ctx.intent`**, and the *route* says
+  where to look: `["dyn"]` up the ancestors (an ancestor owning aggregate state —
+  a log, a selection, a total), `["lex"]` the registered scope handlers (async or
+  host-side work — fetch, timer, IndexedDB, an SDK), or the default `["dyn","lex"]`
+  for both. The answer comes back as `<name>Ok` / `<name>Error` /
+  `<name>Unhandled`. See [messages-and-intents.md](./messages-and-intents.md).
+- **An external event pushes *into* the app** (WebSocket, `postMessage`, …) →
+  **`app.sendAtRoot`**, which lands the inbound event on the root. See
+  [messages-and-intents.md](./messages-and-intents.md) "Integrating with the outside world".
+- **A deep descendant needs a value owned far away** and nothing in between should
+  know about it → **`provide` / `lookup` (`*name`)** across the tree — the last
+  resort. See [advanced.md](./advanced.md).
+
+Note what the ladder does **not** ask: *who answers*. That is the route's job,
+written at the call site, so a name can move from being answered locally to being
+answered by an ancestor without the view or the sender changing.
+
+A compact worked version of the first three (`method`, `send`/`receive`, and
+`intent` on each leg) lives in
+[patterns/coordinate-components.md](./patterns/coordinate-components.md).
+
+## Do's & Don'ts
+
+- **Do create single-purpose components. Don't pack multiple responsibilities
+  into one.** A component that draws its own view from its own fields is the unit
+  of reuse and the unit of testing. → [patterns/render-a-child-component.md](./patterns/render-a-child-component.md)
+
+- **Don't add a `kind` / `type` field and branch the view on it. Do make one
+  component per kind and render it with `<x render=".item">`.** Conditional-on-kind
+  views grow into tangled `@if` chains; a component per kind keeps each view flat
+  and each concern isolated. This is also why pathing into nested data is barred —
+  model the nested thing as a component instead. → [core.md](./core.md) "Common
+  pitfalls" (Paths are not allowed in values) and
+  [patterns/render-a-child-component.md](./patterns/render-a-child-component.md)
+
+- **Do keep state in the component that owns and uses it, and lift it only as far
+  up the tree as it needs to live. Don't thread a value through every component in
+  between** (the React "prop drilling" reflex) — let a child render the field it
+  needs from its owner. → [patterns/share-state-across-the-tree.md](./patterns/share-state-across-the-tree.md)
+
+- **Do read a child's state directly when an ancestor needs it for an aggregate
+  decision.** A parent holds its children as frozen fields, so a handler or
+  method can read `this.items[i].done` straight off — children don't have to
+  raise an intent just to be *read*. **Don't reach for a channel to read
+  downward**; `intent` / `send` are for asking someone to act, not for inspecting
+  state you already own. (And don't reach in to mutate a child around the model —
+  that still goes through the owner's draft or `ctx.send`.)
+  → [core.md](./core.md) "The value tree" and
+  [messages-and-intents.md](./messages-and-intents.md) "When to send"
+
+- **Do reach for `provide` / `lookup` (`*name`) last** — only when a deep
+  descendant needs a value owned far away and nothing in between should know about
+  it. Dynamic bindings couple a consumer to a producer that may not be in scope.
+  → [advanced.md](./advanced.md)
+
+- **Do pick the channel by whether you know the answerer (the ladder above).
+  Don't raise an intent nothing consumes, and don't `send` to self when a plain
+  method call would do.** A message is *addressed* and stops at one component; an
+  intent is *routed* and walks until something answers.
+  → [messages-and-intents.md](./messages-and-intents.md) "The two channels"
+
+- **Do keep logic inside the tutuca app when integrating with the outside world.**
+  Route outbound work through `ctx.intent(..., { route: ["lex"] })` and inbound external
+  events through `app.sendAtRoot` to the root (which forwards deeper with `ctx.at`),
+  so handlers stay the single owner of state changes. **Don't mutate `app.state`
+  directly or `addEventListener` outside the model** — state changed that way
+  bypasses the draft-first transaction discipline and is invisible to the
+  component that owns it. → [messages-and-intents.md](./messages-and-intents.md)
+  "Integrating with the outside world" (and its ⚠️ note)
+
+- **Do handle every DOM event with tutuca's built-in `@on.` handlers — including
+  custom events fired by web components.** `@on.click`, `@on.input`,
+  `@on.<custom-event>` (the event `detail` surfaces as `value`) keep the event
+  inside the model, so it flows through a draft-first handler. **Don't
+  reach in from the outside with `addEventListener`** — a listener attached out of
+  band mutates state the owning component can't see and bypasses the transactor.
+  → [core.md](./core.md) "Event Handling" and "Web Components & Custom Events"
+
+- **Do use inline predicates and small explicit handlers.** A single field plus
+  `equals? .activeSection 'todo'` / `empty?` and a handler that assigns
+  `draft.activeSection` often is the whole state machine. → [core.md](./core.md)
+  "Methods as Predicates & Computed Values" and "Field Types"
+
+- **Do remember a rendered child gets a clean namespace.** Parent `@` bindings
+  (`@each`, `@enrich-with`) don't cross a `<x render>` boundary — pass a value
+  across it with `*name`, not by assuming the binding leaks in. → [advanced.md](./advanced.md)
+
+- **Do add a decoy view when a margaui class is assembled at runtime.** The margaui
+  compiler only scans constant class literals — a class built by interpolation or
+  in a method emits no CSS and renders unstyled. → the workaround in
+  [margaui.md](./margaui.md) "Pitfall: assembled class names are invisible to the
+  scanner", and the worked decoy view in `personal-site.js`.
+
+- **Do close the loop after every change** with `tutuca lint <module>` → `test` →
+  `render`. → [core.md](./core.md) "Verifying changes"
+
+## Smells & refactors
+
+- **`is*Selected()` methods → predicate + one explicit handler.** Replace
+  `$isTodoSelected` with `equals? .activeSection 'todo'`; let the click call a
+  small handler that assigns `draft.activeSection`.
+- **A view that `@if`-branches on a `kind` field → one component per kind**, each
+  rendered with `<x render>`.
+- **A value passed down through three components that don't use it → move the
+  state up to the nearest common owner** and let the leaf render it directly; only
+  if nothing in between should know it, use `provide` / `lookup`.
+- **Host code poking `app.state` or attaching a listener → an `app.sendAtRoot`
+  handler on the root**, with the mutation expressed on its draft.
+
+## See also
+
+- [core.md](./core.md) — component skeleton, fields, directives, predicates, the
+  verification recipe, and the "Common pitfalls" list.
+- [messages-and-intents.md](./messages-and-intents.md) — the channels in depth
+  (`send`/`receive`, `intent` and its routes, `sendAtRoot`) and integrating
+  with the outside world.
+- [advanced.md](./advanced.md) — `provide` / `lookup` / `*name` and the
+  clean-namespace boundary.
+- [patterns/coordinate-components.md](./patterns/coordinate-components.md),
+  [patterns/share-state-across-the-tree.md](./patterns/share-state-across-the-tree.md),
+  [patterns/render-a-child-component.md](./patterns/render-a-child-component.md) —
+  runnable recipes for the rules above.