tutuca 0.11.0 → 0.11.2

package/skill/tutuca/storybook.md

@@ -1,270 +0,0 @@
-# Tutuca — Storybook
-
-Reach this file when authoring `*.dev.js` story modules or running
-`tutuca storybook` — defining `getExamples()` sections, mocking intent handlers per
-example, or rendering a live component catalog. For the framework primer see
-[core.md](./core.md); for the full CLI flag/exit-code table see
-[cli.md](./cli.md); for the `getTests` shape see [testing.md](./testing.md).
-
-## Mental model
-
-`tutuca storybook [dir]` recursively discovers co-located `*.dev.js` modules,
-mounts them via the shipped `tutuca/storybook` library, and serves an ephemeral
-page — no config, no HTML to write. It is **batteries-included by default**:
-before serving it runs each module's `getTests()` in the terminal, the page
-wires margaui styling, and the browser runs `check(app)` — the dev-build lint
-runner, which lints every registered component and logs findings to the
-console (a no-op stub in the core build). Each is individually
-disablable with a `--no-*` flag. All tutuca specifiers resolve to **one
-runtime** — component scope and identity require it.
-
-To embed the same catalog in your own page, use the shipped
-`tutuca/storybook` library: `buildStorybook(modules)` assembles the
-sections from conventional modules, and
-`mountStorybook(selector, modules, opts)` builds, mounts, and starts the
-app in one call.
-
-## The `.dev.js` module
-
-A `*.dev.js` file is a **dev-only module**: it holds stories, tests, and
-development-time helpers for nearby components, and is **never shipped to
-production or the UI**. The `.dev.js` suffix is the contract — your app imports
-its real components directly and never a `.dev.js`, and a production build glob
-can exclude `**/*.dev.js`. Because it follows the full module convention, the
-same file is a valid target for `tutuca lint` / `test` / `render` too. (The
-export shape itself is
-[Conventional Module Exports](./core.md#conventional-module-exports) —
-this table adds what the storybook does with each.)
-
-| Export | Returns | Used for |
-| ------ | ------- | -------- |
-| `getComponents()` | `[Comp, ...]` | stories — return **every** component the module defines, children and helpers included. Components dedup by identity, so re-listing a leaf that another module also lists is safe (a composition module can re-list every leaf it uses). |
-| `getExamples()` | one section, or an array of sections | the catalog cards |
-| `getTests({ describe, test, expect })` | tests | the pre-serve test run (optional) |
-| `getMacros()` | `{ name: macro }` | macros referenced in views (optional) |
-| `getIntentHandlers()` | `{ name: async fn }` | the module's **real** handlers for the `lex` leg (optional) |
-| `getRoot()` | `Root.make({...})` | root state when examples need it (optional) |
-
-## Authoring stories (`getExamples`)
-
-Return one section, or an array of sections to group examples under multiple
-headings. A section is `{ title, description?, group?, items: [...] }`. An array
-of one section behaves exactly like returning that section directly — both go
-through the same `Section.fromData`, which **throws** on a malformed section
-(missing `title`, not an object) rather than rendering a placeholder title.
-
-The optional `group` is a string that clusters sidebar sections under one
-collapsible header: sections sharing a `group` name nest beneath it (across
-modules too), while groups and ungrouped sections interleave alphabetically by
-display key. Omit it (or pass `""`) for a flat top-level section — the default
-and backward-compatible behavior. A non-string `group` is a shape error.
-
-```js
-import { component, html } from "tutuca";
-import { Counter } from "./counter.js";
-
-export function getComponents() {
-  return [Counter];
-}
-export function getExamples() {
-  return {                                    // one section, or an array of these
-    title: "Counter",
-    description: "A button that counts clicks.", // optional
-    items: [
-      { title: "Basic", description: "starts at zero", value: Counter.make({ count: 0 }) },
-      { title: "Pre-filled", value: Counter.make({ count: 5 }) },
-    ],
-  };
-}
-```
-
-To cluster sections in the sidebar, return an array and give related sections
-the same `group`:
-
-```js
-export function getExamples() {
-  return [
-    { group: "Inputs", title: "Counter",  items: [{ title: "Basic", value: Counter.make({ count: 0 }) }] },
-    { group: "Inputs", title: "Slider",   items: [{ title: "Basic", value: Slider.make({ value: 50 }) }] },
-    { group: "Layout", title: "Grid",     items: [{ title: "Basic", value: Grid.make({}) }] },
-    { title: "Misc",                      items: [{ title: "Basic", value: Misc.make({}) }] }, // ungrouped → flat
-  ];
-}
-```
-
-`Counter` and `Slider` nest under a collapsible **Inputs** header, `Grid` under
-**Layout**, and the ungrouped `Misc` sits flat at the top level; headers and
-loose sections interleave alphabetically.
-
-Item fields:
-
-- `title` — required.
-- `description?` — shown under the card title.
-- `value` — required, the instance to render, usually `Comp.make({...})`.
-- `view?` — selects a pushed named view, rendered via `@push-view` in the card.
-- `intentHandlers?` — per-example intent-handler mocks (next section).
-- `on?` — lifecycle hooks; messages sent to `value` as sections are navigated
-  ([Lifecycle hooks](#lifecycle-hooks-on)).
-
-The storybook sorts sections by title and renders a sidebar with a filter, so
-one example item per meaningful state reads as a state matrix.
-
-## Mocking intent handlers per example
-
-An item's optional `intentHandlers` map holds async functions keyed by intent
-name that override the module's real `getIntentHandlers()` handler **for that
-one example instance only** — so two examples of the same component show
-different answers side by side. The three idioms:
-
-```js
-items: [
-  { title: "Loaded", value: Widget.make({ isLoading: true }),
-    intentHandlers: { async load() { return [{ id: 1, name: "Ada" }]; } } },   // fixture
-  { title: "Error", value: Widget.make({ isLoading: true }),
-    intentHandlers: { async load() { throw new Error("boom"); } } },           // error path
-  { title: "Loading", value: Widget.make({ isLoading: true }),
-    intentHandlers: { load() { return new Promise(() => {}); } } },            // never resolves
-  { title: "Default", value: Widget.make() },         // no mock → the real handler, or nothing
-]
-```
-
-How it resolves: the storybook registers one meta-handler per intent name. On
-dispatch it walks the issuing component's path leaf→root to find the nearest
-example carrying a mock for that name (**nearest example wins**), else falls back
-to the module's real handler. With neither, the meta-handler **declines** (`PASS`)
-rather than inventing an error, so the walk runs out and the example hears
-`<name>Unhandled` — "nothing claimed it", not "a handler refused it".
-This is **storybook-only** — at runtime your real `getIntentHandlers()` apply.
-See [messages-and-intents.md](./messages-and-intents.md) for the handler contract (the
-`ctx` is the handler's final argument). `tutuca storybook --dry-run --json`
-lists each example's mocked names.
-
-## Lifecycle hooks (`on`)
-
-An item's optional `on` field declares messages dispatched to the example's
-component (`value`) as the user navigates sections — for examples that need to be
-"kicked" into a state (load data, open a panel, focus an input) rather than
-constructed in it. Three phases:
-
-- **`init`** — the first time a section is displayed, sent to each of its examples.
-- **`resume`** — each subsequent time that section is re-displayed.
-- **`suspend`** — when a section is navigated away from.
-
-```js
-items: [
-  { title: "Loaded", value: Grid.make({}),
-    on: {
-      init:    { intent: [{ name: "load", args: [], opts: { route: ["lex"] } }] }, // fetch on first show
-      resume:  { send:    [{ name: "refresh", args: [] }] },  // re-poll on return
-      suspend: { send:    [{ name: "pause", args: [] }] },    // stop work when hidden
-    } },
-]
-```
-
-Each phase holds **action buckets** — `send` (→ a `receive` handler) and
-`intent` (→ a walk along `opts.route`, answering into a `receive` arm named
-`<name>Ok` / `<name>Error` / `<name>Unhandled`) — each an array of
-`{ name, args?, opts? }`. `args` is a plain array, or a **function** `(self) =>
-[...]` called with the example's component instance:
-
-```js
-on: { init: { send: [{ name: "select", args: (self) => [self.firstId()] }] } }
-```
-
-For ordering **across** kinds, use `do` — an explicit sequence where each item
-carries its own `type`:
-
-```js
-on: { init: { do: [
-  { type: "send",   name: "reset", args: [] },
-  { type: "intent", name: "load",  args: [], opts: { route: ["lex"] } }, // runs after reset
-] } }
-```
-
-`intent` actions on the `lex` leg honor the example's `intentHandlers` mocks. A
-phase message with no matching handler on the component is a silent no-op, and an
-`intent` on the `dyn` leg walks up into the storybook engine rather than into your
-own tree — the visibly-useful shapes are `send` and `intent` on `lex`.
-
-## Stories as tests (`getTests`)
-
-`getTests` runs through the same machinery as `tutuca test`; the storybook runs
-it in the terminal before serving (skip with `--no-tests`). `describe(Comp, fn)`
-auto-tags the suite by `Comp.name`:
-
-```js
-export function getTests({ describe, test, expect }) {
-  describe(Counter, () => {
-    test("starts at zero", () => expect(Counter.make({}).count).toBe(0));
-  });
-}
-```
-
-See [testing.md](./testing.md) for the full `getTests` shape and how to call
-methods / receive / intent / alter handlers.
-
-## Running it
-
-```sh
-tutuca storybook                  # scan + serve the current directory
-tutuca storybook ./packages/ui    # scan + serve another directory
-tutuca storybook --dry-run        # prep + print what would be shown, don't serve (smoke test)
-tutuca storybook --dry-run --json # same, machine-readable for agents
-tutuca storybook --out ./_site    # write a static index.html + bootstrap instead of serving
-tutuca storybook --no-tests       # skip the pre-serve getTests() run
-```
-
-Runtime resolution (convention over configuration): a local
-`node_modules/tutuca` install if present, else the CLI's own `dist`, else the
-version-pinned CDN. `--out` always pins the CDN so the artifact is portable —
-host it from the project root so `/*.dev.js` paths resolve. See [cli.md](./cli.md)
-for the exhaustive flag list and exit codes.
-
-## Themes
-
-The page starts in the theme the URL asks for (`?theme=dracula`), else the one
-the OS prefers, and the sidebar has a switcher for margaui's palettes. Picking
-one sets `?theme=`, so a themed storybook is shareable and survives a reload.
-That OS step is on us, not margaui: its `dark.css` is keyed on
-`[data-theme="dark"]` alone, with **no** `prefers-color-scheme` fallback, so a
-page that only links `theme.css` renders light forever. See
-[margaui.md](./margaui.md).
-
-Embedding the storybook yourself? The switcher is opt-in through the `themes`
-option, which — like `compileCss` — is injected, so the library still never
-imports margaui:
-
-```js
-mountStorybook("#app", modules, {
-  compileCss: (app) => compileClassesToStyleText(app, compile),
-  // The directory your theme.css lives in. Every other palette is a sibling
-  // file there; only the one selected is fetched, and only the first time.
-  themes: { baseUrl: "https://marianoguerra.github.io/margaui/themes/" },
-});
-```
-
-Omit `themes` (what `--no-margaui` does) and no switcher renders — there would
-be no theme CSS to switch to.
-
-## Footguns
-
-- ⚠️ `value` must be a real instance (`Comp.make(...)`), not a plain object or
-  the class itself — examples need an addressable instance for event dispatch.
-- ⚠️ `intentHandlers` mocks are **storybook-only** and per-instance; don't rely
-  on them in `getTests` or production code.
-- ⚠️ Never import a `.dev.js` from app/production code — the suffix is the
-  ship / no-ship boundary.
-- ⚠️ An example whose component raises an intent with no real handler and no
-  per-example mock hears `<name>Unhandled` — and if it declares no answer arm at
-  all, nothing happens and nothing is reported. Declare `<name>Unhandled` (or at
-  least `<name>Error`) while wiring one up.
-- ⚠️ Keep one tutuca runtime — mixed specifiers or installs break scope identity.
-
-## Verify
-
-The standard recipe
-([Verifying changes](./core.md#verifying-changes)) plus a storybook
-dry run: `tutuca lint <module>.dev.js` → `tutuca test <module>.dev.js` →
-`tutuca storybook --dry-run --json <dir>` (smoke-test discovery, counts,
-and mocked names without serving), then `tutuca storybook <dir>` to view
-it live.

package/skill/tutuca/styles.md

@@ -1,48 +0,0 @@
-# Tutuca — Styles
-
-Read this file when authoring `style` / `commonStyle` / `globalStyle`
-blocks or debugging CSS that silently doesn't apply.
-
-```js
-component({
-  style:       css`.mine { color: red; }`,        // scoped to main view
-  commonStyle: css`.shared { color: yellow; }`,   // scoped to all views of this component
-  globalStyle: css`.app-thing { color: green; }`, // global, no scoping
-  views: {
-    two: { view: html`...`, style: css`.mine { color: orange; }` },
-  },
-});
-```
-
-Tagged templates `html` and `css` are just `String.raw` (editor hinting
-only). Plain strings work too.
-
-`style` and `commonStyle` are wrapped in a component-scoped selector
-(`[data-cid="N"]{ … }`), so their CSS lands *inside* a style-rule block.
-
-A useful consequence: **bare declarations with no selector** (e.g.
-`color: red; padding: 1rem;`) land directly inside that wrapper, so they style
-the component's **root element** — the host node carrying `data-cid` (plus
-`data-vid` for a per-view `style`). Reach for this to style a component's own
-outer element without adding a wrapper selector; nested rules with a selector
-(`.mine { … }`) target descendants instead.
-
-Because the CSS sits inside a style-rule block,
-top-level-only constructs break there and the browser silently drops them —
-put them in `globalStyle` (injected verbatim, no wrapper) instead:
-
-- Non-nestable at-rules: `@import`, `@charset`, `@namespace`, `@font-face`,
-  `@keyframes`, `@page`, `@property`, `@counter-style`, `@font-feature-values`,
-  `@font-palette-values`, `@view-transition`. (Conditional group rules —
-  `@media`, `@supports`, `@container`, `@layer`, `@scope`, `@starting-style` —
-  *do* nest and stay in `style`/`commonStyle`.)
-- Rules whose leading selector is `html`, `body`, or `:root`: once scoped they
-  become descendant selectors that never match.
-
-The linter flags both (`TOP_LEVEL_AT_RULE_IN_SCOPED_STYLE`,
-`GLOBAL_SELECTOR_IN_SCOPED_STYLE`). For a genuine false positive, put a
-`/* tutuca-lint-ignore */` comment on the same line as the flagged construct.
-
-For Tailwind / MargaUI utility classes (compiling `class=` literals into
-CSS via the extra build) and the `compileClassesToStyleText` + `injectCss`
-wiring, see [margaui.md](./margaui.md).

package/skill/tutuca/testing.md

@@ -1,346 +0,0 @@
-# Tutuca — Testing
-
-How to author component tests in Tutuca: the `getTests` export shape,
-the calling conventions for methods and handler blocks (`receive`,
-`intent`, `alter`), and the view-handler design
-rule that keeps tests free of fake DOM events. Run them with
-`tutuca test <module-path>` — flags and exit codes are in
-[cli.md](./cli.md). General authoring lives in
-[core.md](./core.md).
-
-## Setup
-
-A module opts into `tutuca test` by exporting `getTests`:
-
-```js
-export function getTests({ describe, test, expect }) {
-  describe(MyComp, () => {
-    test("does the thing", () => {
-      expect(MyComp.make().doTheThing().count).toBe(1);
-    });
-  });
-}
-```
-
-- `expect` is chai, extended with **jest-style matchers** (`toBe`,
-  `toEqual`, `toContain`, `toThrow`, `.not.toBe`, …) — the recommended
-  style. Chai's BDD chain (`expect(x).to.equal(1)`) still works for those
-  who prefer it. Run `tutuca help` for the full matcher list (it's
-  surfaced from code). Asymmetric/mock matchers
-  (`expect.objectContaining`, `toHaveBeenCalled…`, `toMatchSnapshot`) are
-  **not** available — tutuca has no mocking layer.
-- `test` and `describe` are **Tutuca's own** subset of the common
-  Mocha/Jest-style API, injected by `tutuca test` — they are not imported
-  from a test runner, so don't reach for one's extras.
-  Available calls: `describe(title, fn)`, `describe(Component, fn)`,
-  `describe(title, { component }, fn)`, and `test(title, fn)`. There is
-  no `before` / `after` / `beforeEach` / `it` / skip-flag — don't reach
-  for them.
-- `describe(Component, fn)` auto-tags the suite with `Component.name`,
-  so `tutuca test <module> Component` picks it up. Untagged `test(...)`
-  inside a tagged `describe` inherits the tag.
-
-Run with `tutuca test <module-path> [name] [--grep <pattern>] [--bail]`.
-Full flag/format/exit-code reference in [cli.md](./cli.md).
-
-## What to test
-
-Run tests when the change is observable from JS — methods, handlers,
-factories, coercion in `make({...})`. Skip them for pure
-template/styling tweaks; `tutuca render <module>` covers those.
-
-- **Methods** — call directly: `Comp.make({...}).method(args)`. Assert
-  on the *returned* instance (Tutuca state is immutable).
-- **Receive handlers** — call via
-  `Comp.receive.handlerName.call(comp, ...args)` (see *Calling receive
-  handlers* below). One bucket holds every addressed message, so the same
-  call drives a view's `@on.*` name, what a parent sends, and an
-  **answer** to an intent — a handler cannot tell them apart, which is
-  exactly what makes it testable:
-    - `receive.<name>(ctx)` — `ctx` carries `send` / `intent` / `forward`.
-    - `receive.<name>Ok(res, ctx)` / `receive.<name>Error(err, ctx)` /
-      `receive.<name>Unhandled(...intentArgs, ctx)` — the three outcomes
-      of an intent. Each takes **one** payload, so there is no arm that
-      can be handed both a result and an error.
-- **The other handler kinds** (`intent`, `alter`) follow the **same
-  shape**: `Comp.<kind>.handlerName.call(comp, ...declaredArgs)`. Only
-  the arguments differ:
-    - `intent.<name>(payload, ctx)` — `payload` is whatever the sender
-      raised it with. Call `ctx.reply` / `ctx.fail` on a stand-in ctx to
-      assert what it answers.
-    - `alter.<name>(...)` — iteration handlers used by `@when`,
-      `@loop-with`, `@enrich-with`. Each kind has its own signature; see
-      *Testing iteration handlers* below.
-  Pass a plain stand-in for `ctx` (e.g. `{}`) when the handler doesn't
-  read from it; otherwise build the minimal shape it touches.
-- **Factories / coercion** — `Comp.make({...})` shape, defaults, and
-  any deep-coercion you wired up.
-
-## Calling receive handlers
-
-Pattern:
-
-```js
-Comp.receive.handlerName.call(comp, arg1, arg2, /* … */);
-```
-
-- Why `.call`: receive handlers are plain functions stored on the
-  component descriptor. `this` must be bound explicitly to the instance.
-- `comp` is an instance — `Comp.make({...})`.
-- The args after `comp` are exactly what the template would have passed
-  (see next section). The auto-appended `ctx` is *not* required in
-  tests when the handler doesn't read from it; pass `{}` or a stub if
-  it does.
-- Returned value is the next instance.
-
-## Driving a full cascade (`drive`)
-
-Direct `.call(comp, ...)` tests one handler in isolation. When you need a message
-to fan out through real dispatch — a `request` that resolves and feeds its
-an intent's answer, a `send` that triggers more sends — `getTests` also injects an async
-`drive` helper (alongside `describe`, `test`, `expect`):
-
-```js
-export function getTests({ describe, test, expect, drive }) {
-  describe(Grid, () => {
-    test("init loads rows", async () => {
-      const settled = await drive(
-        Grid.make({ rows: [] }),
-        { request: [{ name: "load", args: [] }] }, // an `on`-phase config
-      );
-      expect(settled.rows.size).toBe(3);
-    });
-  });
-}
-```
-
-- `drive(value, phase, opts?)` builds a transactor over `value`, dispatches the
-  phase's actions at the root, awaits the whole cascade (including async
-  requests), and returns the **settled** instance.
-- `drive` **always originates at the root** — there is no `at:`/path option. To
-  exercise a handler on a nested child, call it directly with `.call(child, …)`.
-- `phase` is the same shape as an example's `on.init` (`{ send, intent, do }`;
-  see [storybook.md](./storybook.md#lifecycle-hooks-on)). `args` may be a function
-  `(self) => [...]`, and an `intent` action takes `opts: { route: [...] }`.
-- An `intent` on the **`dyn`** leg has nowhere to walk under `drive`: it
-  originates at the root, and the leg starts at the sender's *parent*. The walk
-  runs out and the sender hears `<name>Unhandled` — which is a result you can
-  assert on. To exercise an `intent` handler itself, call it directly.
-- These are *action kinds*, not methods. `$`-prefixed methods are read-only
-  computations, not an action kind — `on`/`drive` can only reach state through
-  `receive` / `intent` handlers. To put a component into a specific state in a
-  unit test, call the receive recipe directly or drive a message.
-- `intent` actions on the `lex` leg resolve against the module's
-  `getIntentHandlers()`.
-- `opts.onMessage(message, before, after)` observes every committed transaction —
-  `message` is `{ kind, name, args, path }`, `before`/`after` are the root values
-  around its commit — handy for asserting the message/state trace.
-
-## Testing iteration handlers
-
-`alter` handlers run inside `@each` / `@when` / `@loop-with` /
-`@enrich-with` and have three distinct shapes:
-
-- `loopWith(seq, ctx)` — called once with the full collection, returns
-  `{ iterData?, start?, end?, keys? }`: `iterData` is the shared per-loop
-  value (defaults to `{ seq }`); `start`/`end` slice the iteration
-  (`Array.prototype.slice` semantics, original keys preserved); `keys`
-  is an authoritative list of original keys to visit. `this` is the
-  parent component instance. Full return-shape and `ctx` semantics in
-  [iteration.md](./iteration.md).
-- `when(key, value, iterData)` — called per element, returns truthy to
-  keep. `this` is the parent component instance.
-- `enrichWith(binds, key, value, iterData)` — called per kept element;
-  mutates `binds` (which already contains `key` and `value`). `this` is
-  the parent component instance.
-
-You can call each one directly with `.call(comp, ...)`, but in practice
-you want to test them as a pipeline: filter + loop-data + enrichment
-together produce a list of bindings the view sees. Use
-`collectIterBindings` for that — a functional implementation only ships
-in the dev build (`tutuca/dev`); the core `tutuca` build exports a no-op
-stub that returns `[]`. Both commands that run `getTests()` in the
-terminal — `tutuca test` and `tutuca storybook` (including `--dry-run`) —
-redirect the bare `tutuca` import to the dev build automatically, as does
-the browser storybook's import map. So test modules can import it as below:
-
-```js
-import { collectIterBindings } from "tutuca";
-
-const c = MyComp.make({ items: [...] });
-const r = collectIterBindings(MyComp, c, c.items, {
-  loopWith: "loopHandlerName",   // optional
-  when: "whenHandlerName",       // optional
-  enrichWith: "enrichHandlerName", // optional
-});
-// r is Array<{ key, value, ...enrichments }> — one entry per kept item,
-// in iteration order.
-```
-
-- `seq` can be a plain JS Array, a JS `Map`, or a custom collection
-  or keyed seq.
-- Handler names refer to entries in `MyComp.alter`. An unknown name
-  throws — there's no silent fallback.
-- The `compInstance` is `this` for every handler. Pass
-  `MyComp.make({ field: ... })` so handlers that read `this.field` see
-  the value you want.
-- The redirect uses Node's `module.register`, which is how the `tutuca`
-  bin runs. On a runtime without loader-hook support it degrades to the
-  no-op stub — if you see `collectIterBindings` return `[]`, import it
-  from `tutuca/dev` explicitly.
-
-Example:
-
-```js
-const Items = component({
-  name: "Items",
-  fields: { items: [], multiplier: 1 },
-  alter: {
-    loopMeta(seq) { return { iterData: { len: seq.length, doubled: seq.length * 2 } }; },
-    keepEven(k) { return k % 2 === 0; },
-    addLabel(binds, k, v, { len }) { binds.label = `${k}/${len}: ${v}`; },
-  },
-});
-
-test("filters and enriches", () => {
-  const c = Items.make({ items: [10, 20, 30, 40] });
-  const r = collectIterBindings(Items, c, c.items, {
-    loopWith: "loopMeta",
-    when: "keepEven",
-    enrichWith: "addLabel",
-  });
-  expect(r).toEqual([
-    { key: 0, value: 10, label: "0/4: 10" },
-    { key: 2, value: 30, label: "2/4: 30" },
-  ]);
-});
-```
-
-Use this whenever the iteration logic is the subject under test —
-no DOM, no view, no Stack/Renderer needed. For end-to-end checks that
-the view actually wires these handlers correctly, use
-`tutuca render <module>` instead.
-
-## Designing handlers so tests stay simple
-
-Tutuca templates resolve handler args by name (see
-[core.md](./core.md) *Event Handling*). When you author a handler,
-**pick the most specific named args you need; don't take the raw
-event**. With named args, the test passes a literal; with `event`,
-the test must fabricate a DOM-event-shaped object.
-
-An event always names a `receive` handler without a prefix. `$method` is for
-read-only value slots and is rejected in `@on.*`. What matters for testability
-is which named argument the receive handler asks for.
-
-**Bad — receive handler taking the whole event:**
-
-```html
-<input @on.input="setName event" />
-```
-```js
-receive: { setName(draft, event) { draft.name = event.target.value; } }
-```
-
-**Good — receive handler taking the value:**
-
-```html
-<input @on.input="setName value" />
-```
-```js
-receive: { setName(draft, value) { draft.name = value; } }
-```
-
-**Bad — receive handler:**
-
-```html
-<input @on.input="setCount event" />
-```
-```js
-receive: { setCount(draft, event) { draft.count = parseInt(event.target.value, 10); } }
-```
-
-**Good — receive handler:**
-
-```html
-<input @on.input="setCount valueAsInt" />
-```
-```js
-receive: { setCount(draft, n) { draft.count = n; } }
-```
-
-At test time, the "good" forms become trivial:
-
-```js
-const value = MyComp.make();
-expect(produce(value, (draft) => value.setName(draft, "Ada")).name).toBe("Ada");
-expect(produce(value, (draft) => MyComp.receive.setCount.call(value, draft, 42)).count).toBe(42);
-```
-
-The "bad" forms force every test to construct
-`{ target: { value: "42" } }` (or a fuller stub when more fields are
-read), which is brittle and obscures intent.
-
-The built-in named args are listed in [core.md](./core.md) *Event
-Handling*; `ctx` is auto-appended last. Reach for `event` only when no
-narrower arg fits.
-
-## Worked example
-
-A `getTests` export covering two receive handlers (`inc` and `dec`) and a
-receive handler with a named arg (`setCount` taking
-`valueAsInt`):
-
-```js
-import { produce } from "tutuca/immer";
-
-export function getTests({ describe, test, expect }) {
-  describe(Counter, () => {
-    describe("inc", () => {                           // receive handler
-      test("returns a Counter with count + 1", () => {
-        const c = Counter.make();
-        expect(produce(c, (draft) => Counter.receive.inc.call(c, draft)).count).toBe(1);
-      });
-      test("does not mutate the original instance", () => {
-        const c = Counter.make({ count: 7 });
-        produce(c, (draft) => Counter.receive.inc.call(c, draft));
-        expect(c.count).toBe(7);
-      });
-    });
-
-    describe("dec()", () => {                         // receive handler, no args
-      test("returns a Counter with count - 1", () => {
-        const c = Counter.make();
-        const next = produce(c, (draft) => Counter.receive.dec.call(c, draft));
-        expect(next.count).toBe(-1);
-      });
-    });
-
-    describe("setCount()", () => {                    // receive handler, valueAsInt
-      test("sets the count from a parsed int", () => {
-        const c = Counter.make();
-        const next = produce(c, (draft) => Counter.receive.setCount.call(c, draft, 42));
-        expect(next.count).toBe(42);
-      });
-    });
-
-    test("inc and dec round-trip", () => {            // untagged, inherits Counter
-      const c = Counter.make();
-      const next = produce(c, (draft) => {
-        Counter.receive.inc.call(c, draft);
-        Counter.receive.dec.call(c, draft);
-      });
-      expect(next.count).toBe(0);
-    });
-  });
-}
-```
-
-## See also
-
-- [core.md](./core.md) — *Verifying changes*, *Event Handling*,
-  *Component Skeleton*.
-- [messages-and-intents.md](./messages-and-intents.md) — handler signatures for
-  `receive` / `intent`, routes and the three outcomes, `$unknown`.
-- [cli.md](./cli.md) — `test` flags, exit codes, output formats,
-  `--grep` syntax.