llms-full.txt

# wcstack — complete authoring guide for LLMs

> Everything needed to generate correct wcstack (v4.0.0) apps: workflow, exact data-wcs
> syntax, the full wcs-* I/O node catalog with source-verified timing notes, and the
> silent-failure matrix. Generated from the wcstack-app skill (github.com/wcstack/wcstack-skill),
> whose content is verified against the wcstack monorepo at v4.0.0.

Note: the guide below refers to three reference files (references/state-binding.md,
router-and-scaffold.md, io-node-catalog.md). All three are included IN THIS FILE after
the main guide — no external fetches are needed.

---


# Building apps with wcstack

## Overview

wcstack is a family of "standards-first, zero-config, buildless" Web Components packages. An app is correctly a **single HTML file + one-line CDN loads** — do not introduce bundlers, build steps, or npm install unless the user explicitly asks for them.

Content verified against **wcstack v4.0.0** (READMEs, examples, and source as of 2026-10). **The rules here are for wcstack 4.0**, which replaced the `@wcstack/state` engine behind the same markup (`<wcs-state>`, `data-wcs`, `{{ }}`, `for` / `if`, path getters, the `$` APIs, `bind-component`, `mount=`, the package entries). What a 4.0 author writes differently:

- **Configuration is split.** `bootstrapState()` takes only how the page spells the markup (`bindAttributeName`, `tagNames`, the anchor-comment prefixes) plus `locale` and `enableContractAnalyzer`; behaviour switches live in each root state as `$behavior: { enableMustache, sameValueGuard, enableDirectionalInitialSync }`. **Every package's `bootstrapXxx(config)` throws on an option it does not have** (`/auto` passes none).
- **Bubbling `on*:` events are delegated to the root** — `event.currentTarget` is the root, not the element. `on*#direct:` keeps a listener on the element.
- **`for:` takes no filters** — return the filtered list from a getter. **Writing a list element replaces the value at that position**; reorder by assigning a new array.
- **Volumes (`mount=`) hold data, getters and lifecycle callbacks only** — `$watch` / `$listKeys` / `$renderedCallback` go on the root state, and a volume takes no injections. Mounted components run `$listKeys`, tokens, `$on` and `$errorCallback` for their own bindings.
- **Removed:** `$scan`, the names 3.2 renamed (`uc`, `inc`, `$trackDependency`, `$streams`, …), the `substr` filter, and the `bootstrapState()` options `debug` / `commentTextPrefix` / `enablePropagationContext`.
- **Comment bindings (`<!--@@: expr-->`) are the FOUC-free text form**, and bind even with `$behavior.enableMustache: false`.
- **A failed `<wcs-state>` reports once (`#49` / `#50`) and rejects `connectedCallbackPromise`**; SSR server and client move together.

Reading or upgrading 3.x code: `references/state-binding.md` §16 and `docs/migration-v4.md` in the wcstack repo. If the installed/CDN version is much newer, spot-check syntax against the package READMEs.

Generated-code accuracy lives in the exact syntax. **This file holds only the workflow, a cheat sheet, and the failure-mode matrix**; full syntax is split into references/ next to this file. Read the matching reference before entering each phase:

| File | Read before |
|---|---|
| `references/state-binding.md` | writing `<wcs-state>` / `data-wcs` / comment bindings / filters / events + `#direct` / command- & event-tokens / `$behavior` / `$listKeys` / `$watch` / `$eq` family (keyed selection) / `$recursion` + `**` (trees) / accumulation over time (§15) / DCC vs `bind-component` / mounts (`state: path`) / CSP + SRI loading / split entries (`/core`, `dist/split/auto.js`, `$features`) / headless page tests / 3.x code (§16) |
| `references/router-and-scaffold.md` | writing SPA routing / autoloader / index.html scaffold / server |
| `references/io-node-catalog.md` | wiring I/O nodes (52 wcs-* tags) or writing a signals app |

## Workflow

### 1. Pick the stack (state vs signals)

- **`@wcstack/state` (default)** — UI and state connected through `data-wcs` path strings in HTML; no reactive primitives appear in JS. Forms, lists, CRUD, and general apps go here.
- **`@wcstack/signals`** — write `signal()` / `computed()` / `effect()` / `h()` directly in JS. Choose it when the user wants no DSL, logic-heavy code, or typed signals. It has no deep path tracking (that is state's job). When the app owns its I/O nodes, reach for `mountNode(tag)` or bind a `XxxCore` directly instead of `whenDefined` + `bindNode` — see the decision table in `references/io-node-catalog.md` §3.
- The two **coexist** (not rivals), but pick one per app as a rule.

### 2. HTML scaffold (CDN loading rules)

```html
<!-- state family: one /auto line per package. @wcstack/state/auto goes LAST —
     module scripts execute in document order, so every wcs-* element is defined
     before state wires anything to it. -->
<script type="module" src="https://esm.run/@wcstack/fetch/auto"></script>
<script type="module" src="https://esm.run/@wcstack/router/auto"></script>
<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
```

- **State loads last — this is a real rule, not tidiness.** A property/spread binding on a not-yet-defined element is deferred via `customElements.whenDefined` and applied with the latest value, so nothing is lost there (inside `for:` / `if:` rows too). **A command-token emit is never replayed**: its subscription is deferred the same way, so if state is wired first and a slow (or failed) CDN fetch leaves an I/O element undefined, a click that fires `$command.x.emit()` inside that window reaches zero subscribers and is silently dropped. Loading state last closes the window. `@wcstack/devtools/auto`, if used, goes before state too — that one lint enforces as `wcs/script-order`; the I/O-node case is not lint-checked, so it is on you.
- **When you cannot control the order** — a snippet pasted into a larger page, or tags arriving via `@wcstack/autoloader` — gate the emitting control with `<wcs-defined>` (load `@wcstack/defined/auto` too):

  ```html
  <wcs-defined tags="wcs-tilt,wcs-accelerometer" timeout="5000"
    data-wcs="defined: sensorsReady; pending: sensorsPending; missing: sensorsMissing"></wcs-defined>
  <button data-wcs="onclick: startGame; disabled: sensorsResolving">Start</button>
  <!-- get sensorsResolving() { return this.sensorsPending.length > 0; } -->
  ```

  Gate on **`pending`**, not `defined`: a timed-out package lands in `missing`, which should usually release the control into a degraded mode rather than lock the user out (a late arrival is still promoted out of `missing`). Do **not** `await customElements.whenDefined(tag)` inside the handler instead — it never rejects for a tag that is never registered, so a failed import parks the handler forever, and the handler stops being synchronous (which breaks iOS gesture-gated permission calls).
- signals apps import **only from the single `@wcstack/signals/dom` entry** (mixing `.` and `.dom` on a CDN page duplicates the reactive core and breaks reactivity at the seam; lint: `wcs/signals-dual-entry`).
- An SPA **must have `<base href="/">` in `<head>`** (otherwise deep links break: basename gets misderived from the URL).
- **Always set `<html lang>`** — it is the default locale for the locale-dependent filters (`locale` / `date` / `time` / `datetime`), read when `@wcstack/state` is evaluated (an explicit `bootstrapState({ locale })` still wins). Changing the locale later re-renders nothing, so the language must be in the markup (or set by a synchronous `<head>` script) before state loads.
- The bare-name `wcstack` npm package is the **SPA-core bundle**: `wcstack/auto` = state + router + fetch + storage + autoloader pre-linked into one self-contained file (one request, one SRI hash). Use it when the app uses the SPA core anyway; per-package `/auto` tags stay the default (they fetch in parallel — no waterfall) and pay only for what the page uses. Loading both is safe (first evaluated copy wins; the other is inert). **Never merge files yourself via jsDelivr `/combine/`** — concatenated minified ESM does not even parse (top-level identifier collisions), and jsDelivr itself forbids SRI on it.
- **`esm.run/@wcstack/<pkg>/auto` follows the npm `latest` release.** The rules in this skill are 4.0's; a page that must stay on 3.x pins the major on every wcstack line (`https://esm.run/@wcstack/state@3/auto`, likewise `wcstack@3/auto`) and follows the 3.x documentation instead (§16 of `references/state-binding.md` lists what differs).
- **`@wcstack/state/core` + `features/*`, or the split auto entry `dist/split/auto.js`, is an opt-in for byte-conscious pages, not the default** — `/auto` carries every feature. Use it only when the user asks, from version-pinned **plain jsDelivr file paths**, **never `esm.run`** (`+esm` re-bundles each entry with its own copy of the engine, so features install into a copy the core never sees). The split auto entry needs no import map: one `<script type="module" src="…/@wcstack/state@<version>/dist/split/auto.js">`, the root `<wcs-state features="scopes diagnostics">` for what must exist before any state starts (and dev aids), and `$features: ["temporal", "formats"]` in each state for what that state needs. Without `features/diagnostics`, messages print as a code and a number (`[wcs/filter-unknown] #501 "uc"`) — keep it while developing. Recipe and entry table: `references/state-binding.md` §1.
- **Production / CSP** — only when the user asks for hardening; `esm.run` stays the default for demos and prototypes. Pin the version and use the direct jsDelivr path so `integrity` works: `<script type="module" src="https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/auto.min.js" integrity="sha384-…">`. `dist/auto.min.js` has zero static imports, so one hash covers the whole runtime; digests ship in the GitHub Release (`sri.json`), never taken from the CDN's own API. `esm.run` cannot be hashed (it redirects to a re-bundling `+esm` endpoint) and costs two CSP hosts. **The one CSP fact that silently breaks a working page: the inline `<script type="module">` inside `<wcs-state>` is imported through a `blob:` URL, which a strict policy refuses unless the `<script>` that loads state carries the page nonce (`<script type="module" nonce="{RANDOM}" src="…/dist/auto.min.js">` — the `blob:` import inherits it) or the policy opens `script-src blob:`. Where no nonce can be issued (static hosting), move the state to `src="./state.js"` — the preferred form under a strict CSP anyway.** The browser also evaluates that inner module itself, so its top-level code can run twice: keep side effects out of it (`references/state-binding.md` §2). Route guards go through `blob:` too and have no `src=` form: the nonce on the router's `<script>` admits them; without one they need `script-src blob:` (router also retries through a `data:` URL, so `script-src data:` would pass too — do not open it; it is the riskier source). Under Trusted Types enforcement, `html:` / `innerHTML:` bindings and `<wcs-fetch target>` need a sanitizing policy you install; `<wcs-layout>` / `<wcs-worker>` need `trusted-types wcstack`. Details in `references/state-binding.md` §1–2.

### 3. State design (state family)

State is a plain object `export default`. Computed values are getters keyed by dot-path strings (`get "cart.total"()`, wildcard `get "users.*.fullName"()`). Decide up front:

- **Getters read only through `this`.** The cache is invalidated solely via the dependency graph, and the graph records only `this` reads — a getter reading `Date.now()`, the DOM, or a module variable keeps its **first value forever** with no warning. Put the untracked input into state and assign to it (`this.now = Date.now()` on a timer), or use `$dependOn` / `$postUpdate`. Details: `references/state-binding.md` §6.
- **Declare every key you write.** Writing a top-level key the state does not have creates it, so a typo in a write (`this.cuont = 1`) is silent; reading a missing key throws `[wcs/binding-path-missing]`. `defineState` / `wcs-tsc` typing catches the typo.
- One state slot per I/O node (`listFetch: { value: null, loading: false, error: null, status: 0 }`)
- `for:` requires an array — wrap nullable sources in a derived getter: `get rows() { return this["listFetch.value"] ?? []; }`. **A filtered or sorted view is a getter too** — `for:` takes no filters (`for: items|take(2)` fails initialization with `[wcs/binding-syntax]` #121): `get firstTwo() { return this.items.slice(0, 2); }` + `for: firstTwo`.
- Never seed convenient initial values into output-only element properties (the element is the authority; seed real initial values like `null` / `false`)
- **Behaviour switches belong to the state, not to `bootstrapState()`**: `$behavior: { enableMustache: false }` (also `sameValueGuard`, `enableDirectionalInitialSync`; booleans, each `true` by default). Each root state that needs one declares it — the page's root, a root `<wcs-state>` in a shadow root, a mounted component, a DCC; nothing is inherited, a volume cannot declare it, and a re-set may not change it (`#45`). An unknown key or a non-boolean throws `#44`. Works on `/auto` pages and in JSON states.
- **Declare `$listKeys` for any list that is refetched *and* whose rows hold DOM state the bindings do not own** — focus, IME composition, `<details>` open/closed, in-row scroll, `<canvas>`, `<video>.currentTime`. A `fetch().json()` refresh produces all-new objects, so identity-based row matching fails and that state is shuffled between rows, not merely lost: `$listKeys: { items: "id" }` keeps the row objects and writes only the changed fields. Skip it for plain text lists.
- **React to a state change nothing renders with `$watch`** — `$renderedCallback` only reports paths whose live DOM bindings were applied, so "when this value changes, do X" without a binding belongs in `$watch: { path(cur, prev) {...} }`. It also watches computed getters, wildcard ones included (they turn eager). Row watches (`"items.*.price"`) are headless — no `for` or `$listKeys` needed; a whole-array assignment fires only the rows that entered the list (after a `fetch().json()` refresh, every row — `$listKeys` narrows that to the changed fields). A `$`-path (`$streamStatus.<n>`) cannot be a key — mirror it through a non-`$` getter. Declare it on the **root** state (a volume declaring it is not grafted). Full contract: `references/state-binding.md` §10.
- **An accumulation that must outlive a stream restart, or span events, is a key you own, written from a `$watch` or `$on` handler** — a `$stream` `fold` resets to `initial` on every restart, and there is no `$scan`. Seed it (`feed: { items: [], pages: [] }`), fold in `$watch: { pageResult(chunk) { … } }` (a state path) or `$on: { message: (state, e) => { … } }` (an event token), and write only a changed value. Keep an idempotency key — the handler runs **once per landing, not once per page**, and a Retry after `done` or a re-attached page lands the page again; **never derive the stream's `args` from the feed** (it reloads every page with no sentinel — keep the cursor a plain property advanced from an event); keep it bounded. Contract: `references/state-binding.md` §15.
- **Getter reads track exactly the path you spell**: `this.form.name` registers `form` only, so the getter never re-runs when a bound input edits `form.name` — read `this["form.name"]` (lint / VS Code: `wcs/getter-untracked-read`). Reads inside a setter are untracked, and the same-value guard skips primitives only. Table: `references/state-binding.md` §6.
- **A tree whose depth is decided by the data needs `$recursion`** — a path's depth is fixed in its string, so `nodes.*.children.*.total` never stretches to three levels. Declare `$recursion: { "nodes.*": "children.*" }` (anchor → repeating sub-path, exactly one per state, root-only) and one `get "nodes.**.total"()` covers every depth. Inside it an **index-omitted** `$getAll("nodes.**.children.*.total")` is bound to the depth being evaluated (the correct fold); an explicit `$getAll(path, [])` unions **every** depth, and unioning something that already aggregates its subtree silently double-counts. `$setAll(path, [], value)` broadcasts; recursive getters are read-only at every spelling. `**` never appears in markup — a tree is drawn by a self-referential component. Full contract, diagnostics and the two component traps: `references/state-binding.md` §14.
- **Surface binding failures in the page with `$errorCallback(error, { path, bindingType, node })` on the root state** — a throwing getter / filter / structural directive is isolated (the rest of the batch applies, nothing is rolled back) and otherwise only reaches `console.error`. Canonical shape: write the message into state and render it with an ordinary `textContent:` bind. A mounted component's own `$errorCallback` receives the failures of its own bindings; a volume's is not run. It does not cover `$watch` or `$connectedCallback` failures. `info.node` is `null` for a list no `for:` renders.
- **`$connectedCallback` runs after the page's bindings are built** — a defined element already has its bound inputs and its command tokens wired, so it may emit or read at once. An element whose package may load later gets its property / command / event-token bindings when it is defined.
- **Replacing the whole state at runtime** — `stateEl.setInitialState(next)` on an initialized element re-applies every established binding to the new state before it returns (scalars, getters, row getters, `for` and `if` alike), and a binding the new state cannot serve is reported as a failed apply. It is **not** a write: no `$watch`, no `$stream` restart, no `$renderedCallback`. Lists are matched by **array identity**, so put a *new* array in the state you hand over whenever a list changed. Repeat the `$behavior` declaration in it (a changed one throws `#45`). It throws on a tree that already has grafted volumes or mounted components, on a `mount=` volume element (write those paths on the root instead), and on an element that failed to initialize. Contract: `references/state-binding.md` §11.
- **A "selected row" flag belongs in `$eqPath` / `$eqIndex`** — `get "items.*.selected"() { return this["items.*.id"] === this.selectedId; }` makes every row depend on `selectedId`, so one click re-evaluates the whole list. `return this.$eqPath("selectedId", "items.*.id");` subscribes each row under its own id, and a write re-evaluates only the old and the new row; `$eqIndex("selectedIndex")` keys on the row's position instead, `$eq(path, key)` on any key you pass. Point `path` at the written state (`selectedId`) — a getter path falls back to a tracked read (correct, but every row re-evaluates). Keys compare without coercion: an `<input>` writes strings — `value|number: selectedId`. Contract: `references/state-binding.md` §6.

### 4. Bindings → I/O wiring → routing

Read the references, then write. Four wiring forms between state and I/O nodes:

1. Property binding: `data-wcs="value: users; loading: busy"`
2. Spread: `data-wcs="...: listFetch"` (all wcBindable properties + inputs; commands/events excluded)
3. Command-token (state → element): `data-wcs="command.fetch: $command.refresh"` + `$commandTokens`
4. Event-token (element → state): `data-wcs="eventToken.value: responded"` + `$eventTokens` + `$on`

Positive rules with no failure-mode row below: use `<wcs-link to="...">` instead of raw `<a>` (basename handling + `active` class + `aria-current="page"`); wire live handles (MediaStream etc.) element-to-element via `eventToken` → `$command.attachStream`, never through state; `trigger` is a momentary input property, not a command — any truthy write fires (no edge detection, and it bypasses `manual`), so seed its slot with `false`. Exception: on `wcs-debounce`/`wcs-throttle`, `trigger` IS a command. For animations: **enter** is plain CSS (`@starting-style` on the inserted element — no package needed); only **leave and move** need `<wcs-view-transition>` (a policy node, one per document — `for="router"` keeps state's drain timing untouched, `naming="auto"` names list rows for `::view-transition-*` CSS; see `references/io-node-catalog.md`). For routing: a route that must not appear with empty content loads in its **guard** — return an object and it lands in `<wcs-router>.data` (`data: routeData`) together with the params, return a string to redirect dynamically (`/login?next=…`), any falsy return still cancels to `guard=`; the third argument `{ params, typedParams, searchParams, routeName }` is the match being entered (`references/router-and-scaffold.md` §4). **Wrap text `{{ }}` directly under `<wcs-route>` or a layout template in an element** — the router hands state only elements, so bare text binds on the landing route only; wrapping the whole route body in one element (`<wcs-route path="/v"><article>…</article></wcs-route>`) works in every combination (`references/router-and-scaffold.md` §1).

**Text: `{{ }}` inside templates, comment bindings or `textContent:` at page level.** `{{ expr }}` in page-level text shows the raw braces until state has loaded (lint: `wcs/template-syntax` info). `<p>Hello, <!--@@: user.name--></p>` (or `<!--@@wcs-text: user.name|upper-->`) renders nothing before binding, adds no element, takes filters, and binds even with `$behavior.enableMustache: false`. Not inside `<textarea>` / `<title>` (the browser parses that content as text — bind `textContent:` / `value:` there).

**Grammar the runtime refuses** — each fails when the bindings are set up, with the same `[wcs/<code>]` the lint reports; at page level the whole `<wcs-state>` then fails to initialize (4.0 preview behaviour, still under review — `references/state-binding.md` §3 / §11). One `#` with comma-separated modifiers (`onclick#prevent,stop:`, never `onclick#prevent#stop:`); structural keywords bare (`else:` with nothing after it; no modifier or filter on `for` / `if` / `elseif` / `else` / `...` themselves — right-side filters such as `if: count|gt(0)` stay valid, but **`for:` takes none**); a structural binding alone in its `data-wcs`; no surplus filter arguments, no empty filter (`x|`), closed quotes, `|` between filters (`n|toFixed(2)|upper`); no empty path segment on the right (`a.`, `a..b`; a *leading* dot is the loop shorthand); a left side that names a property; no `__proto__` / `prototype` segment; `outerHTML:` / `outerText:` only outside `for:` / `if:` templates; a `*` in a row only for the list its `for:` renders (`b.*.y` inside `for: a` is `[wcs/wildcard-rank]`). Filter arguments are typed: unquoted `true` / `false` / `null` / numbers are values, quoted ones strings (`eq('admin')`). `""` or `null` for "no text" (display surfaces empty on both); `undefined` into an element input is skipped. `$resolve(path, indexes)` reads, `$resolve(path, indexes, value)` writes.

**Events are delegated in 4.0.** `on*:` bindings of `click`, `dblclick`, `input`, `change`, `submit`, `keydown`, `keyup`, `mousedown`, `mouseup`, `pointerdown`, `pointerup` share one listener per type on the root the state binds (the document, a shadow root, or a Light DOM component's host), innermost handler first. So **never read `event.currentTarget` in a plain `on*:` handler** — it is the root: use `event.target.closest("li")` or the loop index the handler receives (`remove(event, index)`). Write **`on*#direct:`** only where the listener must sit on the element: pointer capture (`e.currentTarget.setPointerCapture(…)`), the element's own rect, a `#stop` that must stop your own `addEventListener` on an ancestor (a clickable card), an ancestor whose code calls `stopPropagation()` (a modal keeping clicks from its overlay), an element moved under another root (a dialog moved out of a shadow root to `document.body`). An outer `#direct` handler runs before the delegated handlers inside it, so an inner `#stop` cannot stop it unless the inner binding is `#direct` too (`onclick#direct,stop:`). Two-way bindings and other event types stay on the element (`references/state-binding.md` §8; lint `wcs/delegated-current-target`).

**Never let user content become markup the page scan reads.** Every `{{ … }}`, `data-wcs` and `<!--@@: … -->` in the page when state binds it (and in route content handed to state) is a binding — including inside text your server template inserted. HTML-escaping does not neutralize `{{ }}`, turning mustache off does not stop comment bindings, and 4.0 has no opt-out attribute. Put user content in state and render it with `textContent:` / `{{ }}` (values are text), or `innerHTML:` / `html:` only after sanitizing. State does not sanitize values: validate URLs you bind to `href:` / `src:` / `attr.href:` (`javascript:`), never bind handler strings to `attr.on*:`, and keep `'unsafe-inline'` out of `script-src` (`references/state-binding.md` §2).

**Filtered and reordered lists.** Reorder or filter by assigning a **new array** (`toSorted`, `filter`, a swapped copy) — rows are matched to its elements by identity and move with them. Writing an element (`this["items.0"] = b`, `$resolve("items.*", [0], b)`) replaces the value at that position; the row stays where it is. A `for:` over a getter that returns the list itself passes row writes (`checked: .done`) to the source list; over a getter that returns a **filtered copy**, a write below one row does not reach the source list's row bindings (known 4.0 limitation, #365) — toggle from a handler that reassigns the source: `toggle(e, i) { const id = this.shown[i].id; this.todos = this.todos.map((t) => t.id === id ? { ...t, done: !t.done } : t); }` (`references/state-binding.md` §4).

Two shapes that sit outside those four forms:

- **Giving a custom element its own state** — pick exactly one mechanism, they are exclusive and combining them errors: **DCC** (`data-wc-definition`, HTML only, declares `$bindables` + `$commands: ["bumpBy"]` so the parent can `command.bumpBy: $command.bump`) when there is no JS class, **`bind-component`** (path mapping, no `wcBindable`, so no spread and no command tokens *into* it) when you are already writing one. For bind-component, prefer the **whole-object mount**: `data-wcs="state: user"` mounts the subtree as the component's root (`name` inside IS `user.name`), and `state: .` mounts the current row inside a `for` — instead of per-property `state.x: y` lines. The host **must** wire a Light DOM component this way, a component's own data keys stay private (rule R1), an explicit mapping wins over a component default of the same name, and `state#ro: …` makes the entry read-only for the component. Its **getters are exported at the mount point** — the host reads `user.display` from the component's `get display()`, per row under a `for`, and a self-recursive component (`<tree-node>` inside `<tree-node>`) closes its derivation one level at a time with `$getAll("children.*.total")`; the first host read may be `undefined` until the component registers, so write `(x ?? 0)`. Inside, the component runs `$listKeys`, `$commandTokens` / `$eventTokens` / `$on` and `$errorCallback` on its own lists and bindings; `$watch` / `$stream` / `$renderedCallback` are not run there (a warning), and `$recursion` throws — declare those on the root state. Decision table and mount rules: `references/state-binding.md` §12.
- **`@wcstack/audio`** — markup nesting *is* the signal graph. Only numeric params are bindable; `id` / `out` / `param` / `note` / `poly` are structural, and changing one **rebuilds the graph and audibly cuts every sounding voice**. Read `references/io-node-catalog.md` §1.1 before writing a patch.

### 5. Server and verification

- **The lint loop is a completion gate, not a suggestion (MUST).** Do not present the app as finished until `npx @wcstack/lint --errors-only <every html file> <sidecars>` exits `0`. The loop is generate → lint → fix → re-lint; wcstack's whole failure model is "wrong wiring fails silently" (see the matrix below), and in 4.0 a page-level markup error stops the whole `<wcs-state>`, so a page you have only eyeballed is unverified by definition. If lint cannot run (offline, no npx), say so explicitly instead of skipping it silently. Use the 4.0 lint (`@wcstack/lint` 4.x, VS Code extension 2.x) for 4.0 pages — `@wcstack/lint@3.5` and the 1.21.x extension stay with 3.x projects, because the 4.0 rules report forms 3.x accepts.
- **When the state is a TypeScript file (`<wcs-state src="./state.ts">` or a build that emits `state.js` from it), generate the sidecar `stateSchema` so lint checks paths against the real types**: `npx wcs-schema emit src/state.ts` (from `@wcstack/typescript`; `typescript` is a peer) writes `wcstack.manifest.json`, which `wcs-validate` and the VS Code extension discover automatically (nearest one walking up from the HTML — do not pass it as an argument unless you want it to replace discovery). With a `stateSchema` declared, a path the type lacks is `wcs/path-nonexistent` (**error**, exit 1) and `for:` on a non-array is `wcs/path-type-mismatch`; paths under a `Date` / `Map` / `Record<string, T>` (a bare `{}` in the schema) stay silent, and inline-script methods / getters still count. The regex analyzer cannot read `users: [] as { name: string }[]` — without the schema that is a false `wcs/binding-path-missing` warning and a real typo is only a warning too. The manifest is derived: gate CI with `npx wcs-schema check src/state.ts && npx wcs-validate --strict index.html`, and re-run `emit --merge` after changing the type. Keep hand-written `stateSchema`s only for states you do not generate (`--merge` replaces the named state wholesale).
- **To type-check the inline `<script type="module">` inside `<wcs-state>` in CI (npm + tsc projects only)**: `npx wcs-tsc --noEmit` (also `@wcstack/typescript`; optional peers `@volar/typescript@~2.4.0` + `@volar/language-core@~2.4.0`). It is vue-tsc's mechanism over `.html`: the same language plugin the VS Code extension uses gives `this` its type, wraps a bare `export default {}` in `defineState`, and strips `@wcstack/state` imports (bare or CDN URL), so `this.coutn++` fails as `index.html(9,14): error TS2551 … Did you mean 'count'?` — the check that catches the write typo 4.0 would otherwise turn into a new key. The tsconfig must reach HTML (`include` covering `**/*.html`, `noImplicitThis`, `allowJs`, `checkJs`, and a `target`/`lib` of ES2015+ — the default ES5 lib silently degrades the `this` typing); `wcs-tsc` warns about what is missing, and `--wcs-defaults` runs with a temporary config that adds it. Other CDN imports (`https://esm.run/lodash-es`) are `any` by default (`--url-imports=error` to forbid). It complements lint, it does not replace it: `wcs-validate` checks the HTML side (paths, filters, tag members), `wcs-tsc` checks the script side.
- **Lint every generated HTML file before browser testing**. During authoring, keep warnings visible:

  ```bash
  npx @wcstack/lint index.html
  ```

  Pass every generated HTML file and `wcstack.manifest.json` sidecar as separate arguments when the app has more than one file. **External state files referenced by `<wcs-state src="...">` (`.json` / `.js` / `.ts`) are resolved automatically** — relative to the HTML, never URLs or absolute paths — so do not pass them as arguments. The lint cannot read a **volume** loaded with `src=`, so a root `$watch` key or a binding under that mount path (`cart.total`) gets `wcs/watch-path-missing` / `wcs/binding-path-missing` warnings although it works — expect them there (`--strict` turns them into CI failures). Read the stable `wcs/*` diagnostic codes and `source:line:col` ranges, fix all errors and actionable warnings, then rerun. What the CLI checks:
  - **Syntax and paths** — `data-wcs` syntax (`wcs/binding-syntax`, `wcs/template-syntax` — including filters on `for:`, `outerHTML:` in a template, `#direct` on a non-event binding, a structural binding sharing its `data-wcs`), filters (`wcs/filter-unknown` names the replacement for a removed 3.x name, `wcs/filter-arity`, `wcs/filter-arg-type`), state paths (`wcs/binding-path-missing`, with a `stateSchema` `wcs/path-nonexistent`), `wcs/wildcard-rank`, `wcs/index-arity`, `wcs/index-param-range`, `wcs/getter-cycle`, `wcs/getter-untracked-read`.
  - **The script** — the non-reactive assignment family `wcs/nested-assign` / `wcs/array-mutation` / `wcs/array-index-assign` (**errors**: they always drop the update); `wcs/delegated-current-target` (warning: a handler of a delegated event reads `currentTarget`); removed names (`wcs/name-alias`, `wcs/declaration-alias`, `wcs/scan-declaration-invalid`, errors); `$watch` (`wcs/watch-declaration-invalid` error, `wcs/watch-path-missing` warning — a `$watch` typo does not fail visibly, it just never fires); `wcs/updated-callback-unbound` (`$renderedCallback` testing a path nothing binds); `$recursion` / `**` (`wcs/recursion-*`, errors).
  - **4.0 configuration and scopes** — `wcs/behavior-invalid`, `wcs/feature-unknown`, `wcs/features-invalid`, `wcs/volume-declaration` (`$watch` / `$listKeys` / `$renderedCallback` / `$stream` in a volume), `wcs/second-root`, `wcs/bind-component-source`, `wcs/mount-path-invalid`, `wcs/named-state-deprecated`.
  - **Tags and page** — wcs-* tag members (`wcs/tag-member-unknown`, `command.` / `eventToken.` keys included, with typo suggestions), `wcs/on-prefixed-member` (write `.once:`), `wcs/spread-no-bindable`, `wcs/token-*`, `wcs/trigger-seeded-truthy`, `wcs/storage-seed-clobber`, `wcs/base-href-missing`, `wcs/script-order`, `wcs/signals-dual-entry`, `wcs/aria-attr-unknown`.

  The analyzer follows `$listKeys` for **list paths only** (so `for: items.*.children` validates even when `items` starts `[]`). The row shape of a list that starts `[]` comes from the row literals in the assignments that add or replace rows (`this.items = this.items.concat({ id, kind: "general" })`, `.toSpliced(i, n, { … })`, `.with(i, { … })`, `[...this.items, { … }]`), anywhere in the script; a row passed as a variable (`concat(row)`) is invisible, so inline the literal or declare a `stateSchema` — otherwise `.kind` inside the `for` is `wcs/binding-path-missing`. The lint does **not** see `bootstrapXxx()` options, `#stop` / `stopPropagation()` around delegated handlers, moved elements, element writes used to reorder rows, `[data-wcs]` selectors, or SSR post-processing.
- **Runtime errors echo the lint loop**: messages carry the same `[wcs/<code>]` as the lint, many with a number (`#501`); with the `diagnostics` feature (in `@wcstack/state` and `/auto`) they add the sentence, a did-you-mean, the replacement for a removed 3.x name, and `Validate statically: npx @wcstack/lint <file>.`; on `/core` without it they print `[wcs/<code>] #<number> <values>` (look the number up in the wcstack repo's `docs/state-errors.md`). A bracketed code means lint reproduces the finding with a `source:line:col` range — run it and fix every instance, not just the one that threw. A bound path that provably does not resolve gets one `console.warn` (`wcs/binding-path-missing`, with did-you-mean) from the diagnostics feature; the check under-approximates on purpose (`null` parents, rows of an empty list, intermediate getter returns, mapped `bind-component` children and `$` namespaces stay silent), so **no warning proves nothing** — only lint checks exhaustively. Every package's `bootstrapXxx(config)` throws on an option it does not have (`[@wcstack/fetch] bootstrapFetch: "tagName" is not one of its options, or not of the option's type.`); the lint cannot see those calls.
- **A `<wcs-state>` that fails to initialize reports once and rejects `connectedCallbackPromise`**: `console.error` with the element and its source (`<wcs-state src="./state.js"> failed to initialize.`, `#49`), then the error. Causes: a throwing or removed `$` declaration, a source that cannot load (`src="*.json"` HTTP error `#13`, `state="<id>"` with no `<script type="application/json">` of that id `#16`), a second root `<wcs-state>` (`#47`, refused alone), and — in 4.0, still under review — a page-level markup error (syntax, unknown filter, wildcard rank: the bindings after it are not attached). `initializePromise` still resolves; `getBindingsReady(root)` rejects only when every `<wcs-state>` on that root failed before building its bindings; `setInitialState()` on a failed element throws (`#14` — replace the element). A `$connectedCallback` that throws or rejects **after** the bindings are built is `… $connectedCallback failed.` (`#50`): `connectedCallbackPromise` rejects, but `getBindingsReady()` resolves (the page is bound). A volume that is refused still resolves its promise; `renderToString()` and `@wcstack/testing`'s `mount()` reject with the cause.
- **Two console messages point at the page, not at wcstack**: `render chain depth limit exceeded (100 drains that rendering itself started); bindings for this batch were not applied.` is a render loop — a row element's output, a `$renderedCallback` or a `$watch` keeps writing a new value into something the same render reads; break the cycle, or write only when the value really changes (`updates did not settle after 32 passes`, `#11`, is the same within one update). `The host row of <x-row> was removed.` is a component's method or a kept `this` (a timer, a continuation after `await`) outliving its `for:` row — check the row is still there, and clear timers in `$disconnectedCallback`.
- **Mount private keys are invisible to `keys()` / `read()`** — the devtools State pane's **Overlays** section is the one place they surface, per mount record, with the component's exported getters under `exports`. A runtime without the protocol member simply hides the section.
- **When wiring is silent and lint is clean, use the devtools coverage tab**: load `@wcstack/devtools/auto` (before state; on a split auto page add `devtools` to `features=`) and open the wiring pane's coverage view. It joins declared against measured — `$watch` paths (fired ×N / never), command/event tokens (emitted ×N / never), and bindings (attached / never-attached) — which is exactly the "declared but silently dead" class the matrix below describes. Its *prerequisite-missing* note on a row watch whose list has no `for` and no `$listKeys` is a 3.x rule; under 4.0 such a watch fires (read it as "not fired yet"). <!-- 4.0: @wcstack/devtools still applies the 3.x prerequisite check (DevtoolsCore.ts); drop this sentence if devtools is updated for 4.0 row watches -->
- **Use the quiet form only as the final CI gate**:

  ```bash
  npx @wcstack/lint --errors-only index.html
  ```

  Append other HTML files and `wcstack.manifest.json` only when they exist. `--strict` exits `1` on warning-severity findings too (severities unchanged, only the threshold moves) — the right gate once every `<wcs-state src>` resolves and a `stateSchema` exists, since it fails CI on a path typo that is otherwise only a warning (and on `wcs/filter-unknown` / `wcs/wildcard-rank`, warnings the runtime throws on); it combines with `--errors-only` (output stays error-only, exit code reflects warnings). `--errors-only` (alias `--quiet`) hides warning/info lines but does not change their counts or the exit code. Exit `0` means no error-severity diagnostics, `1` one or more errors, `2` invalid usage or a file-read failure. Messages follow the environment locale; `--lang=ja` / `--lang=en` force it. In VS Code, the WcStack IntelliSense extension shows the same diagnostics inline, plus hover, go-to-definition (F12 from a path into the state script; `$command.<n>` jumps to `$commandTokens`), find-references and inlay hints, and resolves `<wcs-state src>`. It also ships `wcs.html-data.json` (HTML custom data from the wcBindable catalog) — other editors get `wcs-*` tag/attribute completion by listing it under `html.customData`.
- **Headless page tests (npm projects)**: a wcstack page is plain DOM, so it tests under vitest + happy-dom with no browser. `@wcstack/testing` packages the recipe as one import — `mount(html)` (registers elements, waits for router + every binding), `app.state().write(s => {...})`, `fire(el, "click")`, `settle()`. Details and the bare no-package recipe: `references/state-binding.md` §13.
- A static single page needs no server (recommend a tiny server if it fetches).
- An SPA needs the fallback "every extensionless non-API GET returns index.html" (implementation in router-and-scaffold.md §7).
- **SSR (`enable-ssr` + `@wcstack/server`'s `renderToString()`)**: deploy `@wcstack/server` and the client at the same major.minor — a 4.0 client discards a 3.x server's snapshot and renders the page on the client (a 4.0 server with a 3.x client is unsupported) — and keep the HTML comments in the output (text bindings and row / branch markers are comments; a minifier's `removeComments` breaks hydration and lets `{{ }}` in values be read as bindings). Details: `references/state-binding.md` §11, `references/router-and-scaffold.md` §5.
- After finishing, do a minimal run in a browser or via a tiny server. For working references, see `examples/` (multi-package demos) and `packages/*/examples/` (single-package demos) in the wcstack repo.
- **When the user wants automated tests, the page is testable headlessly with vitest + happy-dom — no test-only API, no build.** Setup file: `bootstrapState(); URL.createObjectURL = undefined as any;` (the second line routes inline `<script type="module">` state through the `data:` loader; without it the state never finishes loading under Node). Test: `document.body.innerHTML = html` → `await stateEl.connectedCallbackPromise` → `await getBindingsReady(document)` → assert → `await stateEl.createStateAsync("writable", async (s) => { s.count = 42; })` (or `button.click()` for a handler) → `await new Promise(r => setTimeout(r, 0))` → assert. Use `json=` or the inline script for state; write arrays reactively (`s.items = [...s.items, x]`, never `push`). `renderToString()` from `@wcstack/server` gives a snapshot test. Bare Node: `installGlobals()` from `@wcstack/server`, then dynamic-import `@wcstack/state` **after** it. **As one import**: `@wcstack/testing` (peers `@wcstack/state`, `@wcstack/server`) — `const app = await mount(html)` registers the elements and waits for every element and binding (a `<wcs-router>`'s first route too; add `bootstrap: [async () => (await import("@wcstack/router")).bootstrapRouter()]`), then `app.state().write(s => …)` / `app.state().read(s => …)`, `fire(el, "click")`, `await settle()`, `app.unmount()`. It also shims two happy-dom edges the bare recipe hits: inline-script state loading, and `textContent = 0` rendering as `""` instead of `"0"`. Example suite: `examples/state-testing-todo/`.

### 6. Embedding wcs-* nodes in a React / Vue / Svelte / Solid app

This is a supported path (`docs/framework-adapter-integration.md`): every I/O node implements wc-bindable, so a thin adapter (`@wc-bindable/react`, `/vue`, `/svelte`, `/solid`, …) maps an element's outputs into framework state with no per-element glue. Three rules carry it — nothing here uses `data-wcs` or `@wcstack/state`.

1. **Use `@wc-bindable/*` 0.9 or later, and import the definition before the app renders anyway.** From 0.9 the adapters wait for a late definition (`syncOn: "define"`, their default) and bind when it lands; up to 0.8 they checked `isWcBindable(el)` once on mount and never retried, so an element that upgraded later stayed silently unbound — no error, no log. A static import at the entry (`import "@wcstack/websocket/auto";` in `main.tsx`) works with every version. With a 0.8 adapter and a definition that genuinely arrives late (autoloader, CDN tag, code-split), gate the mount on `customElements.whenDefined("wcs-ws")`. A `syncOn` of your own replaces the default — keep `"define"` in it. `connectedCallbackPromise` is not a substitute — it covers connection, not definition.
2. **Pass object-valued inputs as properties, not attributes.** Attributes hold only strings, and several frameworks fall back to attributes when the property is not on the element yet, which stringifies the payload. Use `.prop` (Vue), `prop:` (Solid), `.prop=` (Lit), or assign through a ref.
3. **Unwrap reactive proxies before handing values in.** Vue `reactive`, Svelte `$state`, Solid stores, MobX and Qwik `useStore` wrap plain objects in proxies, and a proxy cannot cross a structured-clone boundary — `<wcs-worker>` / `<wcs-broadcast>` report a `DataCloneError` into `error` rather than sending. Pass `toRaw()` / `$state.snapshot()` / `unwrap()` results. Cores deliberately do not unwrap for you (that would mean a framework dependency).

Live handles such as `<wcs-camera>`'s `MediaStream` are deliberately not snapshot state — take them off the element event via a ref. Angular templates and JSX cannot bind event names containing a colon, so `addEventListener` / `Renderer2.listen` is the portable path for `wcs-*:*` events. Working demos: `examples/websocket-chat` (React 19 and Vue 3 against the same server as the vanilla / state / signals variants).

## Cheat sheet (most-used bindings)

```html
<div data-wcs="textContent: user.name"></div>            <!-- text -->
<p>Hello, <!--@@: user.name--></p>                        <!-- page-level text, no FOUC -->
<input data-wcs="value: form.email">                     <!-- two-way -->
<input type="checkbox" data-wcs="checked: done">
<div data-wcs="class.active: isActive; style.color: color; attr.href: url"></div>
<!-- class.* wants a boolean (|truthy to coerce); undefined/null remove it -->
<button data-wcs="onclick: save; disabled: saving">Save</button>   <!-- delegated: currentTarget is the root -->
<form data-wcs="onsubmit#prevent: submit">
<div data-wcs="onpointerdown#direct: dragStart"></div>    <!-- needs event.currentTarget: listener on the element -->
<template data-wcs="if: items.length|gt(0)">...</template>
<template data-wcs="else:">...</template>                <!-- trailing colon required -->
<template data-wcs="for: items"><li>{{ $1|add(1) }}. <span data-wcs="textContent: .name"></span></li></template>
<!-- never children inside a textContent:/innerHTML:/html: element — they are not bound -->
<template data-wcs="for: openItems">...</template>       <!-- for: takes no filters — loop over a getter -->
<user-card data-wcs="state: user"></user-card>                      <!-- mount subtree as component root -->
<wcs-fetch data-wcs="...: usersFetch"></wcs-fetch>                  <!-- spread -->
<wcs-fetch data-wcs="command.fetch: $command.reload"></wcs-fetch>   <!-- command-token -->
<my-el data-wcs="eventToken.value: responded"></my-el>              <!-- event-token -->
```

```javascript
export default {
  // $behavior: { enableMustache: false },                     // behaviour switches (each defaults to true) live here, never in bootstrapState()
  items: [],
  usersFetch: { value: null, loading: false, error: null, status: 0 },
  loadError: "",
  selectedId: null,
  log: [],                                                     // an accumulation is a key you own
  get rows() { return this["usersFetch.value"] ?? []; },       // for: needs an array
  get openItems() { return this.items.filter((i) => !i.done); },   // a filtered view is a getter
  get "items.*.label"() { return this["items.*.name"]; },      // wildcard computed
  get "items.*.selected"() { return this.$eqPath("selectedId", "items.*.id"); },  // keyed selection (selectedId: a primitive)
  add() { this.items = this.items.concat({ id: Date.now(), name: "new" }); },     // new array + path assignment
  remove(e, i) { this.items = this.items.toSpliced(i, 1); },   // (event, ...loopIndexes) — not e.currentTarget
  toggleAll(e) { this.$setAll("items.*.done", [], e.target.checked); },  // bulk write, keeps the array
  $commandTokens: ["reload"],
  $eventTokens: ["responded"],
  $on: { responded(state, ev) { /* check ev.detail.status first */ state.log = [...state.log.slice(-19), ev.detail]; } },  // fold events here, bounded
  $listKeys: { items: "id" },   // keep row DOM state across a refetch
  $watch: { "items.*.name"(cur, prev, i) { /* headless — fires with no DOM binding */ } },
  $errorCallback(error, { path }) { this.loadError = `${path}: ${error.message}`; },  // in-page error boundary
  $recursion: { "nodes.*": "children.*" },  // a tree whose depth is data — then get "nodes.**.total"()
};
```

Full syntax (modifiers, 47 built-in filters, nested loops, `$getAll` / `$resolve`, spread rules): `references/state-binding.md`.

## Failure-mode matrix (most of these break without an error)

Run `npx @wcstack/lint` without `--errors-only` first (§5), fix its actionable warnings, then self-review against this table:

| Mistake / combination | Symptom | Correct form |
|---|---|---|
| `this.user.name = v` (nested property mutation) | DOM stays stale; lint reports `wcs/nested-assign` (**error** — fails CI) | Path assignment: `this["user.name"] = v` |
| `push` / `splice` / `sort` or `this.items[0] = v` on arrays | DOM stays stale; lint reports `wcs/array-mutation` or `wcs/array-index-assign` (**error**) | Reassign a new array (`toSpliced` / `concat` / `filter` / `toSorted`), or use `this["items.0"] = v` / `this.items = this.items.with(0, v)` |
| A write to a top-level key the state does not declare (`this.cuont = 1`) | 4.0 creates the key; nothing renders it, no error | Declare every key in the state; `defineState` / `wcs-tsc` typing catches the typo |
| `event.currentTarget` in a plain `on*:` handler of a delegated event (`click`, `input`, `change`, `submit`, key / mouse / pointer down and up) | It is the root (document, shadow root, Light DOM host) — `setPointerCapture`, `getBoundingClientRect`, `new FormData(e.currentTarget)` act on the wrong node; lint `wcs/delegated-current-target` (warning) | `event.target.closest(…)` or the loop index; `on*#direct:` where the element itself is needed |
| `onclick#stop:` meant to stop your own `addEventListener` on an ancestor; page code calling `stopPropagation()` on an ancestor; a bound element moved under another root (a dialog moved out of a shadow root to `document.body`) | The ancestor listener still runs; the inner handler never runs; the moved element's handler stops running — nothing reported, the lint cannot see it | `on*#direct:` on those bindings (`onclick#direct,stop: save`) |
| An outer `on*#direct:` around an inner delegated `onclick#stop:` | The outer handler runs first, so the `#stop` cannot stop it | Make the inner binding `#direct` too (`onclick#direct,stop:`) |
| Reordering rows by writing list elements (`$resolve("items.*", [0], b)`, `this["items.0"] = c`) | The value at that position is replaced and the row stays put — focus, typed text and `<details>` state stay with the position, not the value | Assign a new array (a swapped copy, `toSorted`) — rows move with their objects |
| A `for:` over a getter returning a **filtered copy**, with a two-way binding or leaf write inside its rows (TodoMVC `checked: .done` in `for: shown`) | The object changes, but the source list's row bindings and row getters do not follow (known 4.0 limitation, #365) | Toggle from a handler that reassigns the source list with a new row object (`this.todos = this.todos.map(…)`); a getter returning the list itself is fine |
| One object at two positions (`items: [o, o]`), or reachable from two lists | A write below one row does not reach the other row's bindings (#365) | Give each position its own object |
| CSS or test selectors on row / branch elements by `[data-wcs…]` | Never match — 4.0 removes `data-wcs` from the elements it clones for rows and branches | A class or a `data-*` attribute of your own |
| `{{ }}` / `data-wcs` / templates inside an element whose content a binding sets (`textContent:`, `text:`, `innerText:`, `innerHTML:`, `html:`), or inside `<noscript>` / `<iframe>` | Left literal — those children are never bound | Put markup that needs bindings in a separate element |
| User content in the page markup (a server template inserting a comment body, a profile name) containing `{{ … }}` or `<!--@@: … -->` | Read as a binding by the page scan (client-side template injection) — HTML-escaping does not neutralize `{{ }}`, `enableMustache: false` does not stop comment bindings, 4.0 has no opt-out attribute | Deliver user content through state and render it with `textContent:` / `{{ }}`; sanitize before `innerHTML:` / `html:` |
| `{{ }}` at page level | Raw braces flash until state loads (FOUC; lint `wcs/template-syntax` info) | `<!--@@: path-->` or `textContent:` at page level; `{{ }}` inside `<template>`s |
| Getter reading `Date.now()`, the DOM, or a module variable | Keeps its **first value forever** — the cache is invalidated only through the dependency graph, which records reads through `this` alone | Put the input into state and assign to it, or `$dependOn(path)` / `$postUpdate(path)` |
| Getter reading `this.form.name` (nested property access) | Tracks `form` only — editing `form.name` through a binding never re-runs it; lint / VS Code report `wcs/getter-untracked-read` | Read `this["form.name"]` |
| `for:` bound to a null / non-array path | List breaks | Derived getter with `?? []` |
| `for: items\|take(2)` (any filter on `for:`) | **Throws** `[wcs/binding-syntax]` #121 — at page level the `<wcs-state>` fails to initialize | A getter returning the filtered list, `for: firstTwo` |
| Arguments on `onclick:` | Cannot pass arguments | Zero-arg wrapper method per variant, or read the loop index argument |
| Bare name on command binding (`command.fetch: reload`) | Throws `[wcs/token-misconfigured]` #1201 | `$command.reload` (the `$command.` prefix is mandatory) |
| Raw DOM event name as `eventToken.` key | Throws `[wcs/token-misconfigured]` #1204 (no such property) once the element is defined | Use the **wcBindable property name** |
| Expecting spread (`...:`) to wire commands/events | They stay unwired | Wire `command.` / `eventToken.` explicitly |
| Right-hand filter on spread (`...: slot\|f`) | Throws `[wcs/binding-syntax]` #105 | Filters go on individual property bindings |
| `{{ }}` text directly under `<wcs-route>` or a layout template (not inside an element) | Bound on the landing route only; entered by navigation it stays literal | Wrap it in an element (`references/router-and-scaffold.md` §1) |
| A `for:` / `if:` template at the top of a `<wcs-head>` | Not rendered, `[wcs/template-syntax]` #204 on the console | Wrap it in an element |
| `data-wcs="attr.aria-label: ..."` on `<wcs-link>` | Never reaches the generated `<a>` — `aria-*` is copied once at anchor creation, and dynamic changes are not tracked | Write `aria-*` on `<wcs-link>` as **static attributes** (they are forwarded, along with `title` / `rel` / `target` / `download` / `hreflang` / `lang` / `dir`) |
| `@wcstack/state/auto` loaded **before** an I/O package | A `$command.x.emit()` fired in the load window reaches zero subscribers and is dropped (tokens are never replayed; property bindings are fine) | Put every I/O-node `/auto` before `state/auto` |
| `await customElements.whenDefined(tag)` as a readiness gate | Hangs forever if the package never loads (`whenDefined` never rejects) — takes the fallback path down with it | `<wcs-defined timeout>` bound to `disabled:` via its **`pending`** output |
| SPA without `<base href="/">` | Deep links break (basename misderived) | Add `<base href="/">` to `<head>` |
| Assuming `wcs-fetch:response` means success | Fires on HTTP/network errors too | Check `event.detail.status` in `$on` |
| Expecting a repeated identical value on a **`state`** output to fire again | The same-value guard skips the set, the dependency walk, the DOM apply and `$renderedCallback` | Take it from the occurrence surface instead — `eventToken.` + `$on`. (Properties declared `semantics: "event"` — `message` / `result` / `fired` / … — are exempt from the guard; the catalog §0 lists all 20) |
| Awaiting an async `$on` handler, or relying on it to sequence work | Dispatch never awaits handlers; a rejection is caught and reported via `console.error` but never propagates | Keep `$on` synchronous, or have the async work write its own state slot when it settles |
| Storage slot seeded with `""` / `null` | Initial write-back clobbers the saved value | Seed the bound slot with `undefined`, or bind `value#init=element: slot` (the element's loaded value wins the initial sync, then normal two-way resumes) |
| Seeding truthy initials into output-only properties | Element authority overwrites them | Seed real initial values (`null` / `false`) |
| Seeding `true` into a `trigger`-bound slot | Fires/starts at bind, even with `manual` (no edge detection) | Seed `false`; write `true` to fire |
| `send` / `post` before connected / opened / started | Dropped silently into `error` — not queued, no throw | Gate on `connected` / `running`, and bind `error` |
| Changing an attribute after connect to reconfigure | Most inputs are frozen (connect-time or next-command read) — change silently ignored | Check the catalog's live/frozen notes; re-invoke the command or replace the element |
| Writing `undefined` to an element input | Write is skipped silently (write-skip) | Assign `null` to clear |
| Binding an element property whose name starts with `on` (`once:` on `<wcs-timer>`, `online:` on your own element) | It becomes an event binding (listens for `"ce"` / `"line"`) and the value never arrives — silently; lint `wcs/on-prefixed-member` | The explicit property form: `.once:` / `.online:` |
| `class.NAME:` bound to a non-boolean (`class.on: user.label`, a count) | Throws on every apply (`[wcs/binding-type-expectation]` #401) — that binding fails | `class.on: count\|gt(0)`, or `class.on: label\|truthy`; `undefined` / `null` remove the class |
| Missing trailing colon on `else` | Parse fails | `data-wcs="else:"` |
| `for:` / `if:` / `elseif:` / `else:` sharing one `data-wcs` with any other binding (`<template data-wcs="for: items; class.on: x">`) | Throws `[wcs/template-syntax]` #201 — the `<wcs-state>` fails to initialize | A structural binding must be **alone** in its `data-wcs`; put other bindings on elements inside the template |
| `bootstrapState({ enableMustache: false })` (or `sameValueGuard`, `enableDirectionalInitialSync`, `debug`, any unknown key, a value of another type) | **Throws** `#44` before anything is applied — the page never binds | `$behavior: { enableMustache: false }` in each root state that needs it; `bootstrapState()` takes notation only |
| An unknown option to any `bootstrapXxx(config)` (`bootstrapFetch({ tagName })`, the autoloader's `scanImportmap`) | **Throws** — the package never registers | Pass only the documented options; `/auto` passes none |
| `$watch` / `$listKeys` / `$renderedCallback` / `$behavior` / `$features` in a volume (`<wcs-state mount>`), or an injection on the volume element (`data-wcs="state.taxRate: …"`) | The volume is **not grafted** (one `console.error`) — everything under its mount path reads `undefined`; its `connectedCallbackPromise` still resolves | Declare them on the root state with full paths (`"cart.total"`); read cross-module values in a root getter |
| Mixing `@wcstack/signals` and `@wcstack/signals/dom` on a CDN page | Two reactive cores, broken seams | Import everything from the single `/dom` entry |
| Custom filter registration | No public API | Compose the 47 built-in filters, or compute in a getter |
| Strict CSP + the inline `<script type="module">` state form, loaded by a `<script>` without the page nonce | State never initializes; next to the browser's CSP report, state logs `failed to initialize.` with `The inline <script> of <wcs-state> was blocked by Content-Security-Policy …` (`#42`) or `Failed to evaluate the inline <script> of <wcs-state>: …` (`#43`, when no violation was seen — usually a syntax error) | Put the page nonce on the `<script>` that loads state (the `blob:` import inherits it); where no nonce can be issued, move the state to `src="./state.js"`, or open `script-src blob:` deliberately |
| Side effects (`fetch`, logging, assignments to globals) at the top level of the inline `<script type="module">` inside `<wcs-state>` | They run **twice** — the browser evaluates that module itself as well as state's own `blob:` import | Keep the top level to `export default { … }`; do the work in methods or `$connectedCallback` |
| Refetching a list (`fetch().json()`) whose rows hold focus / IME / `<details>` / `<canvas>` / `<video>` state | Rows are rebuilt, and that state is **shuffled onto other rows** rather than just lost | Declare `$listKeys: { items: "id" }` so rows are matched by key and only changed fields are written |
| Using `$renderedCallback` as a headless watcher | Never fires for a path with no live DOM binding; lint `wcs/updated-callback-unbound` | It is binding-driven — declare `$watch: { path(cur, prev) {...} }` instead, which fires with no binding at all |
| A row watch (`$watch: { "items.*.price": … }`) over a list refreshed with `fetch().json()` | Every row fires on every refresh, with `prev` `undefined` — all the row objects are new, so every row "entered" the list | Declare `$listKeys: { items: "id" }`: the refresh becomes per-field writes, and only changed rows fire, with a real `prev` |
| Expecting a row watch to fire after mutating rows in place and re-assigning the same array (or a copy, or `$postUpdate("items")`) | Nothing fires — kept rows did not change by identity (getters do read the new values) | Write the row paths (`this["items.0.price"] = 5`), or replace the changed rows with new objects |
| Watching `$streamStatus.<name>` / any `$`-path in `$watch` | Rejected at declaration (`$` is reserved); lint reports `wcs/watch-declaration-invalid` | Mirror through a non-`$` getter — `get streamStatus() { return this["$streamStatus.x"]; }` — and watch that; a watched getter is evaluated eagerly even when nothing renders it |
| `$watch` / `$stream` / `$renderedCallback` declared in a **mounted** `bind-component` scope | Not run, with a one-time `[wcs/mount-dollar-declaration]` warning (`$recursion` there throws) | Declare them on the root state |
| DCC and `bind-component` on the same component (e.g. `<wcs-state bind-component>` inside a `data-wc-definition` host) | Error (they are exclusive) | One mechanism per component — no JS class → DCC, class already written → `bind-component` |
| A page with only `<wcs-state mount=...>` volumes and no root | Loud error — the root `<wcs-state>` is required (it may be empty) | Add `<wcs-state></wcs-state>` (or the root `src`) alongside the volumes |
| A plain, unwired Light DOM `<wcs-state bind-component>` | Fails loudly with the fix — an independent tree cannot share the parent's root | Add `attachShadow`, or mount it from the host (`state: user` / `state.message: user.name`) |
| `setInitialState()` re-set on a tree that already has volumes or mounts, or with a different `$behavior` | Throws (`#45` for `$behavior`) | Write the individual paths you want to change; repeat the `$behavior` declaration in a re-set state |
| Re-setting with an array you mutated in place (`s.items.push(x); el.setInitialState(s)`) | Lists are matched by **array identity**, so the added or removed rows never reach the page — nothing is reported | Put a new array in the state you hand over (`{ ...s, items: [...s.items, x] }`), or write the path instead of re-setting |
| `setInitialState()` on a `<wcs-state mount="…">` element to refresh a volume | Throws — a volume's data is copied into the root tree once, when it grafts | Write the paths under the mount path on the **root** state |
| Duplicate name in `$bindables` / `$commands` | Definition-time error | Deduplicate; `$commands` lists methods only, `$bindables` value properties only |
| `page++` on each `<wcs-intersect>` edge with a `$stream` fetch | A second edge aborts page N and jumps to N+1 — a page is skipped | Derive it from the rows already in the feed: `page = floor(feed.items.length / pageSize) + 1`, written from the sentinel's `$on`; repeated edges then rewrite the same value and no-op |
| Expecting an auto-fetch after the url passes through empty/`undefined` and back | Skipped — the guard holds the last url *actually fetched*, which an empty url does not update | Explicit `command.fetch` / `trigger`, which bypass the guard |
| `data-bind` params read in the `connectedCallback` of a custom element that is **not yet defined** when the route renders | `this.props.userId` is `undefined` there — params land after `whenDefined()` resolves, which is after the upgrade | Read them in the `props` / `states` / attribute setter or `attributeChangedCallback`, define the element before `@wcstack/router` renders, or bind `typedParams` on `<wcs-router>` into state |
| A getter / filter / structural directive that throws while a binding applies | That binding is isolated and the report goes to `console.error` only — the page shows a stale node and no message | Declare `$errorCallback(error, { path, bindingType, node })` on the **root** state (a mounted component's covers its own bindings) and render the message from state |
| Host binding `user.display` where `display` is a getter of the component mounted at `user` | Exported — but the first read may be `undefined` (the parent evaluates before the child registers); a tree key of the same name wins and warns `wcs/mount-export-shadowed` | Write derived expressions defensively (`?? 0`) and do not declare the key on the tree too; a wildcard-local accessor (`get "children.*.label"()`) is never exported — mount a component per row |
| A component in a `for:` row whose method continues after an `await`, or that keeps `this` in a timer | Once the row is gone it throws `The host row of <x-row> was removed.` | Check the row is still there; clear timers in `$disconnectedCallback`, which can still write the component's own keys |
| `matches:` bound on `<wcs-media-query>` | Never updates — the output is named `matched`, because `Element.prototype.matches()` exists on every element | `data-wcs="matched: isDark"` |
| `$getAll("nodes.**.total", [])` to total a tree | Too big, with no diagnostic — every node's total already folds its own subtree, and the union adds each one again | Union raw values (`nodes.**.value`) or sum the roots (`nodes.*.total`). Inside the recursive getter the same slip surfaces as `wcs/getter-cycle` |
| `**` in `data-wcs` / mustache, a `$watch` or `$listKeys` key, `$resolve` / `$postUpdate` / `$dependOn`, or an assignment | Refused (`wcs/recursion-unsupported`) — `**` is authoring notation for the state definition only, and means nothing without a `$recursion` declaration | Bind concrete paths; draw the tree with a self-referential component (`references/state-binding.md` §14) |
| Reading `this["nodes.**.value"]` from the top level, or from a plain getter a recursive getter calls | `wcs/recursion-context` — a bound `**` takes its depth from the innermost evaluation frame only | Read it inside the recursive (or row) getter and pass the value on, or pass `[]` to union every depth |
| Two rows sharing one `children` array instance | Under `$recursion` refused as `wcs/recursion-shared-list`; elsewhere both rows show the same child rows | Give every node its own array (sharing an empty one is harmless) |
| A self-referential component that declares its own key for the data it is mounted over, or builds its shadow in the constructor | The child renders its own default and never descends (`wcs/mount-own-key-shadow`); a constructor `innerHTML` recurses forever where `<template>` content is not inert | Leave the mounted keys out of `state`, and fill the shadow in `connectedCallback` |
| Numeric keys under a plain object (`sales.2024.total`, `usersById.42.name`) read or written from the script | Markup renders them, but `this["sales.2024.total"]` reads `undefined` and a write throws `no row for …` (known 4.0 limitation) | Read `this.sales[2024].total`; write a new object to the top-level key (`this.sales = { ...this.sales, 2024: { … } }`), or use non-numeric keys |
| A write past the end of a list (`this["items.5.v"] = 1`) | Throws `no row for "items.*.v"` (`#3`); a read returns `undefined` | Grow the list by assigning a new array first |
| Accumulating a feed in a `$stream` `fold` | Resets to `initial` on every restart — the list empties the moment `page` changes | Own the feed as a plain key and fold each landing in a `$watch` on the stream's value (`$watch: { pageResult(chunk) { … this.feed = { … }; } }`): it outlives restarts and reconnects |
| A feed fold that appends without a key | The same page appears twice after a Retry once it is `done`, or after the state element is re-attached — the handler runs once per landing, not once per page | Keep an idempotency key in the feed (`if (this.feed.pages.includes(chunk.page)) return;`) |
| A stream's `args` reading a getter derived from its own feed (`get page() { return Math.floor(this.feed.items.length / 20) + 1; }`) | The stream restarts on its own result and loads every page with no sentinel | Keep the cursor a plain property and advance it from an event (`$on`) |
| A render that writes something new every time — a row element's output bound to the key the list's getter reads, a `$renderedCallback` that bumps a bound value on every render, a `$watch` that feeds a list's getter from its rows' output | Cut off after 100 links with one `render chain depth limit exceeded …` — the values stay in state, the DOM stops at the cut | Break the cycle: write only when the value really changes, and never feed a row element's output into the key its own list is derived from |
| Stripping comments from SSR output (html-minifier `removeComments`), or a 3.x `@wcstack/server` in front of a 4.0 client | Hydration breaks and `{{ }}` inside values may be read as bindings; with a 3.x server the client discards the snapshot and re-renders everything (`<wcs-ssr version="3.x.y"> does not match 4.0.0 …`) | Keep comments in the output; deploy `@wcstack/server` and the client at the same version, and purge HTML cached from 3.x |
| SSR state holding a `Date` / `Set` / `Map` / class instance | The JSON snapshot turns it into a string or a plain object that overwrites the client value | Keep JSON values in SSR state and derive the rest in getters (`get created() { return new Date(this.createdIso); }`) |
| `html:` / `innerHTML:` binding or `<wcs-fetch target>` under `require-trusted-types-for 'script'` with no policy installed | Blocked; reported once, then the binding fails like any failed apply | Install a sanitizing policy via `globalThis[Symbol.for("wcstack.trustedTypes.policy")]` (or `setTrustedTypesPolicy()`); `<wcs-layout>` / `<wcs-worker>` additionally need `trusted-types wcstack` in the CSP |
| Binding a structural audio attribute (`out` / `param` / `note` / `poly`) from state | Every write rebuilds the graph and cuts sounding voices | Bind only numeric params; declare structure in markup |

## Minimal template (starting point)

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <script type="module" src="https://esm.run/@wcstack/state/auto"></script>
</head>
<body>
<wcs-state>
  <script type="module">
    export default {
      count: 0,
      countUp() { this.count++; }
    };
  </script>
</wcs-state>
<p>Count: <!--@@: count--></p>
<button data-wcs="onclick: countUp">+1</button>
</body>
</html>
```

For a full SPA with fetch wiring and layouts, start from the router-spa skeleton in `references/router-and-scaffold.md` §7.


---

# Reference: data-wcs binding syntax (state family)

<!-- source: wcstack-skill/skills/wcstack-app/references/state-binding.md -->

# @wcstack/state Reference

Sources: the 4.0 engine — wcstack `packages/state/src` and its README, `docs/migration-v4.md`, `docs/state-errors.md` (message numbers) and the 4.0.0 CHANGELOG entry — plus what 4.0 keeps from the 3.x documentation: `packages/state/README.ja.md`, `packages/state/examples/*`, `packages/fetch/examples/users-crud`, `docs/csp.md` / `docs/sri.md` / `docs/state-list-key-design.md` / `docs/state-watch-hook-design.md` / `docs/timing-and-firing-contract.md`. All verified against real code at v4.0.0, and the 4.0 rules against the 4.0 engine source. **The rules are 4.0's.** A form from 3.x code and what replaced it: §16.

## 1. CDN Loading

```html
<!-- Auto-initialization (the one-liner used in all real examples) -->
<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
```

```html
<!-- Manual initialization -->
<script type="module">
  import { bootstrapState } from 'https://esm.run/@wcstack/state';
  bootstrapState();   // options: notation only (§11 Configuration) — an unknown key throws #44
</script>
```

### Production loading — pin the version and add `integrity`

```html
<script type="module"
        src="https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/auto.min.js"
        integrity="sha384-…"></script>
```

`dist/auto.min.js` is a **self-contained bundle with zero static imports**, so the usual ESM caveat — `integrity` covers the entry but not what it imports — does not apply: one hash covers every line of wcstack that runs. Rules that make it work:

- **Use the version-pinned direct path on `cdn.jsdelivr.net`.** `esm.run` redirects to the `+esm` endpoint, which re-bundles server-side, so a fixed digest can never match there. jsDelivr's plain path does not resolve `package.json` `exports`, so name the real file (`/npm/@wcstack/state/auto` is a 404; `@<version>/dist/auto.min.js` is a 200).
- **`crossorigin` is not needed** — `type="module"` is always fetched in CORS mode.
- **Get digests from the GitHub Release** (a table in the body, plus a machine-readable `sri.json` asset), computed from the published tree. Never from jsDelivr's data API: the point of SRI is not trusting the CDN, so letting it self-report is circular.
- **Not covered, by design**: your state definition (inline `<script>` or `src="./state.js"`), route guard scripts, and autoloader-resolved components — all page-supplied code that is dynamically imported at runtime. Named imports from `dist/index.esm.js` need import-map `integrity` (Chrome 127 / Safari 18; not Firefox).

### Loading only the features a page uses — split entries

`/auto` (or `@wcstack/state` + `bootstrapState()`) ships every feature and **stays the default**: a page that uses everything is smaller as one file than as core plus features, and the one-hash SRI story above holds only for `auto.min.js`. Use a split form only when the user asks for fewer bytes and the page deliberately leaves features out. Two forms:

**The split auto entry** — one tag, no import map:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/split/auto.js"></script>
<wcs-state features="scopes diagnostics">          <!-- the document's root <wcs-state> -->
  <script type="module">
    export default {
      $features: ["temporal", "formats"],           // what THIS state needs
      price: 1200,
      $watch: { price(cur) { /* … */ } },
    };
  </script>
</wcs-state>
<p>{{ price|locale }}</p>
```

- **`features="…"`** on the document's root `<wcs-state>` (the first one without `mount` and `bind-component`) is read once, before `<wcs-state>` is defined: the place for `scopes` (`bind-component`, `mount=`, DCC — it must exist before any `<wcs-state>` starts) and for development aids (`diagnostics`, `devtools`). Only the split auto entry reads it; on another `<wcs-state>` lint warns `wcs/features-invalid`.
- **`$features: ["temporal", "formats"]`** names what a state needs; the split auto entry loads the missing ones before it builds that state, the other entries only check they are installed (`[wcs/feature-not-installed]`). A value that is not an array throws `#46`; a volume may not declare it.
- Names: `formats`, `diagnostics`, `temporal`, `list-keys`, `scopes`, `recursion`, `ssr`, `devtools`. Any other name fails with `[wcs/feature-unknown]` (lint: the same code). Features load from `./features/<name>.js` beside `auto.js`, so only those eight files can ever be imported.
- Load it from a version-pinned plain `/npm/` path, **never `esm.run`**. It is not in `exports`; with a bundler use the import-map form's imports.

**Core plus features through an import map** (or a bundler):

```html
<script type="importmap">
{
  "imports": {
    "@wcstack/state/core": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/split/core.js",
    "@wcstack/state/features/temporal": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/split/features/temporal.js",
    "@wcstack/state/features/formats": "https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/split/features/formats.js"
  }
}
</script>
<script type="module">
  import { bootstrapState, installFeatures } from '@wcstack/state/core';
  import temporal from '@wcstack/state/features/temporal';  // $watch / $stream
  import formats from '@wcstack/state/features/formats';    // the formatting filters
  installFeatures([temporal, formats]);                      // before bootstrapState()
  bootstrapState();
</script>
```

| Entry | Adds |
|---|---|
| `@wcstack/state/core` | `data-wcs`, `{{ }}` and comment bindings, `for` / `if`, path getters, events (`#direct` included), `$command` / `$on`, `$eq*`, `$errorCallback`, the core filters (`eq ne not lt le gt ge`, `add sub mul div mod abs clamp`, `int float boolean number string nullIfEmpty`, `truthy falsy defaults coalesce`), `bootstrapState`, `installFeatures`, `getBindingsReady` |
| `…/features/formats` | the formatting filters: `toFixed locale upper lower capitalize trim slice padStart padEnd repeat reverse truncate join round floor ceil percent unit date time datetime ymd hms` (§7) |
| `…/features/temporal` | `$watch`, `$stream` |
| `…/features/list-keys` | `$listKeys` (outside the core in 4.0) |
| `…/features/scopes` | `bind-component`, `mount=` volumes, a mounted component's exported getters, DCC (`data-wc-definition`) |
| `…/features/recursion` | `$recursion` and `**` |
| `…/features/ssr` | `enable-ssr` (server rendering and hydration) |
| `…/features/devtools` | the DevTools hook source |
| `…/features/diagnostics` | the sentences of the numbered messages (did-you-mean, the replacement for a removed 3.x name), the bound / `$watch` path warnings (`wcs/binding-path-missing`), the CSP / Trusted Types explanations |
| `@wcstack/state/define` | `defineState` and the types — no runtime |

- **Never load the split form through `esm.run`.** Its `+esm` endpoint re-bundles each entry and inlines the shared core chunk into every one, so each entry carries its own engine and a feature installs into a copy the core never sees — the page throws `[wcs/feature-not-installed]` although `installFeatures` ran. Use the version-pinned plain jsDelivr path (it does not read `exports`: name the file under `dist/split/`) or a bundler; then every relative import resolves to the same chunk URL and the engine is evaluated once. Chunk file names under `dist/split/chunks/` carry a content hash — take them from the version you pin when you list them (preload, import-map `integrity`, Chrome 127 / Safari 18; not Firefox — `docs/sri.md` §5).
- **Under a CSP the split files need only the delivery host** in `script-src`, like `auto.min.js` (no `eval`; the inline-state `blob:` rule of §2 still applies). The split auto entry carries no inline script; the import-map recipe carries **two** — the import map and the bootstrap module — and each needs the page nonce or a hash. `docs/csp.md` §2.1.
- **A missing feature is loud**: a declaration that needs one throws `[wcs/feature-not-installed] <key> needs the add-on @wcstack/state/features/<name>` when the state loads (`$watch` / `$stream` → temporal, `$listKeys` → list-keys, `$recursion` → recursion, `bind-component` / `mount=` → scopes, `enable-ssr` → ssr), and a formatting filter without `formats` throws `[wcs/filter-unknown] … "upper" is in the formats add-on — install it …` when the bindings are planned. **The one silent omission is `features/diagnostics`**: without it messages print as `[wcs/<code>] #<number> <values>` (look the number up in the wcstack repo's `docs/state-errors.md`) and a mistyped bound path gets no console warning at all. Keep it (or `/auto`) while developing, and rely on lint either way.
- `installFeatures` is idempotent (a feature already installed is skipped); call it before `bootstrapState()` — a state that declares a feature's key before that feature is installed fails with `[wcs/feature-not-installed]`.

## 2. `<wcs-state>` State Definition (6 methods)

Resolution order: `state` attribute → `src` (.json/.js) → `json` attribute → inner `<script>` → wait for `setInitialState()`.

```html
<!-- 1. Reference a <script type="application/json"> by id -->
<script type="application/json" id="state">{ "count": 0 }</script>
<wcs-state state="state"></wcs-state>

<!-- 2. Inline JSON attribute -->
<wcs-state json='{ "count": 0 }'></wcs-state>

<!-- 3. External JSON -->
<wcs-state src="./data.json"></wcs-state>

<!-- 4. External JS module (export default {...}) -->
<wcs-state src="./state.js"></wcs-state>

<!-- 5. Inline script (most common. export default with type="module") -->
<wcs-state>
  <script type="module">
    export default { count: 0 };
  </script>
</wcs-state>

<!-- 6. Programmatic API -->
<script>
  const el = document.createElement('wcs-state');
  el.setInitialState({ count: 0 });
  document.body.appendChild(el);
</script>
```

`<wcs-state>` attributes: `mount` (graft this state onto the root tree at that path — see below) / `state` / `src` / `json` / `bind-component` (Web Component binding) / `enable-ssr` / `features` (root only, split auto entry — §1). `src` resolves against the **document base URL** — so with `<base href="/ja/">` (the i18n basename pattern), a relative `src="./state.js"` fetches `/ja/state.js` and 404s. **Under a `<base>`, write the URL root-absolute**: `src="/state.js"`.

A source that cannot load fails the element (§11): `state="<id>"` reads only a `<script type="application/json">` with that id and rejects when there is none (`#16`); a `src="*.json"` that cannot be fetched (`#13`, with the HTTP status) or parsed rejects too. `name=` and `path@name` (v1) are gone: `@` in a path is `#32` with the replacement, lint `wcs/named-state-deprecated` (error).

### Under a Content-Security-Policy the load path decides the directives

| Method | What it does | CSP needed |
|---|---|---|
| `state="<id>"` / `json='{...}'` / `setInitialState()` | `JSON.parse` | **nothing extra** (data blocks are not executed) |
| `src="./state.js"` | normal `import(url)` | `script-src <origin>` |
| `src="./data.json"` | `fetch(url)` | `connect-src <origin>` |
| inner `<script type="module">` (method 5 — the default in every example) | text is extracted and imported through a **`blob:` URL** | **the page nonce on the `<script>` that loads state**, or **`script-src blob:`** |

**The page's nonce rescues method 5 — on the `<script>` that loads state, not on the inner one.** A module's `import()` inherits the nonce of the `<script>` that loaded that module, so `<script type="module" nonce="{RANDOM}" src="https://cdn.jsdelivr.net/npm/@wcstack/state@4.0.0/dist/auto.min.js">` admits the `blob:` import under a policy without `blob:` (the browser's rule, not a wcstack feature — checked on Chromium, Firefox and WebKit). A hash cannot do this: a `blob:` module is fetched as an external script, so no inline hash ever matches it. Where no nonce can be issued (static hosting), it is `src="./state.js"` or `script-src blob:`, and opening `script-src blob:` means "allow all dynamically generated scripts", which gives away most of the reason for having a CSP. **Under a strict CSP, `src="./state.js"` stays the preferred form** — it needs neither `blob:` nor the nonce hand-off, and the double run below does not happen. Other consequences worth knowing before you write the policy:

- **The browser evaluates the inner `<script type="module">` too.** Being a child of `<wcs-state>` does not stop it (only a `<template>` does). Its export goes nowhere, so state is unaffected, but with no CSP — or with the nonce on that inner `<script>` as well — **its top-level code runs twice**: once by the browser, once through state's `blob:` import. Under a CSP without a nonce on it, the browser's run is refused and the console shows one violation; state still loads. Either way, **keep side effects out of the top level** (no `fetch`, logging or assignments to globals next to `export default { … }`); do that work in methods or `$connectedCallback`.
- **`<wcs-guard-handler>` goes through `blob:` too, and has no `src=` form.** The nonce on the `<script>` that loads router admits it the same way. Without a nonce, using guards forces `script-src blob:` (router also retries through a `data:` URL, so `script-src data:` would pass too — do not open it; it is the riskier source) — control access on the route-content side instead if the policy must stay strict.
- **`esm.run` needs two hosts** (`https://esm.run` *and* `https://cdn.jsdelivr.net`) because CSP re-checks the redirect target. The version-pinned direct path needs one.
- **Inline import maps need a nonce** (`@wcstack/autoloader` depends on one) and cannot take `integrity`.
- **`class.` / `style.` bindings do NOT need `style-src`** — they are CSSOM property assignments, not attribute parsing or `<style>` injection. And `data-wcs` is never evaluated: no `eval`, no `new Function` anywhere.
- **Trusted Types (`require-trusted-types-for 'script'`).** **Author-written strings are signed** by a shared identity policy named `wcstack` — `<wcs-layout>` templates and `new Worker(src)` — so add `trusted-types wcstack` to the policy **only if the page uses `<wcs-layout>` or `<wcs-worker>`**. **Remote and state data are never signed** — the `html:` / `innerHTML:` / `outerHTML:` / `srcdoc:` bindings (an `<iframe>`'s `attr.srcdoc:` too) and `<wcs-fetch target>` responses need a sanitizing policy *you* install, before the first fetch / layout / worker: `globalThis[Symbol.for("wcstack.trustedTypes.policy")] = trustedTypes.createPolicy("my-app", { createHTML: (s) => DOMPurify.sanitize(s, { RETURN_TRUSTED_TYPE: true }), createScriptURL: (s) => s })` from a nonced head script (bundles: `setTrustedTypesPolicy()` from `@wcstack/state` / `router` / `fetch` / `worker` — same slot). Without one those sinks stay blocked: the diagnostics feature explains it once, and the write fails like any binding (`$errorCallback`, or `binding "…" failed to apply.`). DCC definition has no sink (it clones nodes). Chromium-only — elsewhere every path is a pass-through. Full sink table: `docs/csp.md` §7.
- **Diagnosing it**: a CSP-blocked dynamic `import()` only rejects with `Failed to fetch dynamically imported module` (Chromium; Firefox: `error loading dynamically imported module`). State subscribes to `securitypolicyviolation` and says `The inline <script> of <wcs-state> was blocked by Content-Security-Policy … give the page's nonce to the <script> that loads @wcstack/state, or allow blob: in script-src …` (`#42`) only when a violation was actually observed; `Failed to evaluate the inline <script> of <wcs-state>: <message>` (`#43`) means none was seen — usually a syntax error in your state module. Router says `loadGuardHandler: failed to import guard script …` with the original error in `cause`.

### Security — values, URLs and user content

- **State does not sanitize values.** Text bindings (`textContent:`, `{{ }}`, comment bindings) write text, so a value never becomes markup there. `innerHTML:` / `html:` write HTML: sanitize user content first (and under Trusted Types, through your policy).
- **Validate URLs you bind** to `href:` / `src:` / `attr.href:` — a `javascript:` URL runs on click. Never bind handler strings to `attr.on*:` (state does not refuse it); keep `'unsafe-inline'` out of `script-src` so such a string cannot run.
- **User content must not become page markup.** When state binds the page it reads every `{{ … }}`, `data-wcs` and `<!--@@: … -->` / `<!--@@wcs-text: … -->` under the root (and in route content the router hands it) as a binding — client-side template injection when a non-SSR server template or your own code put user text there. HTML-escaping does not neutralize `{{ }}` (braces are not HTML-special); `$behavior.enableMustache: false` does not stop comment bindings; 4.0 has **no opt-out attribute** (a `data-wcs-ignore` is planned for a later 4.x). Deliver user content through state — `json=` / `src=` / `setInitialState()` / a fetch — and render it with a text binding.
- **SSR output**: keep its comments (§11) — stripping them also lets `{{ }}` inside rendered values be read as bindings on the client.

### Mounting additional state (`mount=`) — volumes

There is **one state tree per rootNode** (document or shadowRoot). To split state across modules, mount a **volume**: its data is grafted onto the root tree at the mount path, and bindings read it by prefix.

```html
<wcs-state src="./app.js"></wcs-state>               <!-- the root: exactly one per rootNode, required -->
<wcs-state mount="cart" src="./cart.js"></wcs-state> <!-- a volume grafted at `cart` -->
<div data-wcs="textContent: cart.total"></div>
<button data-wcs="onclick: cart.add">Add</button>     <!-- a volume's methods are reachable by path -->
```

| In a volume | 4.0 |
|---|---|
| Data, getters (relative to the mount path), methods (`onclick: cart.add`, `this["cart.add"]`), `$connectedCallback` / `$disconnectedCallback` | supported |
| `$watch`, `$listKeys`, `$renderedCallback` | **refused**: the volume is not grafted, `console.error` (`$watch is not run in a volume — declare it on the root state.`) |
| `$stream`, `$recursion` / `**` getters, `$behavior`, `$features` | refused (not grafted) |
| `$commandTokens`, `$eventTokens`, `$on`, `$errorCallback` | not run, `console.warn` — declare them on the root |
| An injection on the volume element (`data-wcs="state.taxRate: settings.taxRate"`) | **refused** (not grafted): read both paths in a root getter — `get cartTotalWithTax() { return this["cart.subtotal"] * (1 + this["settings.taxRate"]); }` |

- **Declare `$watch` / `$listKeys` / `$renderedCallback` on the root state with full paths** (`$watch: { "cart.total"(cur) { … } }`). Inside the root's handlers `this` is the root state. The root's `$renderedCallback(paths, indexes)` receives the paths of the whole tree (`cart.items.*.name`) — filter by prefix: `paths.filter((p) => p.startsWith("cart."))`.
- A refused volume still resolves its `connectedCallbackPromise`; everything under its mount path reads `undefined`. Lint: `wcs/volume-declaration`, `wcs/behavior-invalid`, `wcs/features-invalid`. The lint cannot read a volume loaded with `src=`, so a root `$watch` key or a binding under that mount path gets `wcs/watch-path-missing` / `wcs/binding-path-missing` warnings although it works.
- The **root `<wcs-state>` is required** and may be empty (`<wcs-state></wcs-state>`). Volumes with no root are a loud error. A second root on one root node is refused alone (`#47`; lint `wcs/second-root`).
- **Load order does not matter.** A volume connected before the root is grafted when the root registers; reads under a not-yet-loaded volume return `undefined` and are *not* reported as missing paths. If the root fails to initialize, volumes waiting for it settle with a report of their own — final: fix the root and reload. A volume that settles without grafting releases its mount slot, so a replacement element on the same path grafts.
- **`setInitialState()` on a loaded volume element throws** — the graft copies the volume's data into the root tree once. Write the paths under the mount path on the **root** state instead.
- The mount path is **static and dotted** (`settings.theme` is fine). `*`, `$`, `#`, `@` and empty segments are rejected — at runtime (not grafted) and as `wcs/mount-path-invalid` (error) in lint. Changing `mount` after initialization does nothing. A path the root state already has, or one another volume holds, is refused (`will not graft: the root state already has "…"`); replacing a mount point's parent wholesale from the root (`this.settings = {...}` under `mount="settings.theme"`) throws.
- A volume written as a `class` grafts its prototype accessors and methods; an own data key still shadows a prototype getter. Any `data-wcs` on the volume element counts as an injection (refused).
- A `<wcs-state mount>` inside the shadow root of a component that is wired to its host is refused (`will not graft: its component is wired to its host.`) — a wired component reads the host's tree, so put that data in the host's state.
- Cross-module reads are ordinary paths: a root getter reading `this["cart.total"]` tracks the dependency like any other.

## 3. `data-wcs` Binding Syntax

```
property[#modifier[,modifier...]][|input filter...]: path[|output filter...]
```

- Multiple bindings are **separated by `;`**: `data-wcs="textContent: count; class.over: count|gt(10)"`. `;`, `|`, `:` and the filter parentheses split only **outside quotes**, so a quoted argument may contain them (`tags|join('; ')`, `value|defaults('00:00'): .startTime`, `join(')')`).
- There is **no `@state` selector** — `@` in a path is a parse error (`#32`). Read another module's state through its mount prefix (`cart.total`, §2).
- Filters on the left side (property side) apply in the **DOM→state input direction**: `<select data-wcs="value|number: selectedProductId">`
- Right-side filters apply in the state→DOM output direction.
- Multiple modifiers are comma-separated after a single `#`: `value#ro,init=none: path`
- **Refused when the bindings are set up** — `[wcs/binding-syntax]` (`#1xx`) / `[wcs/template-syntax]` (`#2xx`) / `[wcs/filter-arity]`, the same codes the lint reports as errors. At page level the `<wcs-state>` then fails to initialize and the bindings after the error are not attached (4.0 preview behaviour, still under review); inside a `for:` / `if:` row an error found while attaching goes to `$errorCallback` as that binding's failure:

  | Refused | Write |
  |---|---|
  | A second `#` (`value#ro#wo`) | `value#ro,wo` |
  | A value after `else:`; modifiers or left-side filters on `for` / `if` / `elseif` / `else` / `...` (`if#ro:`, `for\|f:`) | The bare keyword (right-side filters such as `if: count\|gt(0)` stay valid) |
  | **Any filter on `for:`** (`for: items\|take(2)`, #121) | A getter that returns the filtered list (§4) |
  | `for` / `if` / `elseif` / `else` sharing one `data-wcs` with another binding (#201); `elseif:` / `else:` not after an `if:` (#202) | A structural binding alone on its `<template>` |
  | `outerHTML:` / `outerText:` inside a `for:` / `if:` template (#203) | `innerHTML:` on a wrapper element |
  | An unterminated quote, an empty filter (`x\|`, `x\|\|y`), text after a filter's `)` (`n\|toFixed(2)upper`) | Closed quotes; `n\|toFixed(2)\|upper` |
  | More filter arguments than the filter takes, or fewer than it needs | The filter's own arity (§7) |
  | An empty path segment on the right (`textContent: a.`, `a..b`) | The real path — a **leading** dot is the loop shorthand (`.name`, `state: .`) |
  | A left side that names no property (`": x"`, `"#ro: x"`); a dotted namespace word (`.class:`, `.attr:`, `.style:`, `.command:`, `.eventToken:`, `.state:`) | Name the property; the namespaces are undotted |
  | A `__proto__` / `prototype` segment anywhere in a path (#120 — in writes, `$resolve`, `$setAll` and reads too) | — |
  | A path over 512 segments | Real paths are under ten |
  | A `*` in a row that ranges over another list than the enclosing `for:` (`{{ b.*.y }}` inside `for: a`, `[wcs/wildcard-rank]` #1403); `state: .` or a `.`-path outside any `for:` (#1402) | Read the other list's row in a getter with `$resolve(path, indexes)` |
- **A modifier never changes the kind of binding:** `radio#ro:` / `checkbox#ro:` stay radio / checkbox bindings.
- **Empty values:** display surfaces — `textContent` / `innerText` / `innerHTML`, `{{ }}` and comment bindings, `attr.*`, `style.*`, `class.*` — treat `undefined` and `null` alike: the text is emptied, the attribute or style removed, the class taken off. Element inputs (every other property, spread) skip `undefined` (the element keeps its own default) and clear on `null`. The formatting filters `upper` / `lower` / `capitalize` / `trim` / `slice` / `padStart` / `padEnd` / `repeat` / `reverse` / `truncate` / `unit` pass `undefined` / `null` through. The filters for which an absent value *is* the input (`defaults` / `coalesce` / `nullIfEmpty` / `boolean` / `truthy` / `falsy` / `not` / `eq` / `ne`) read it as such; the conversions and the number / date / array families do not pass it through — a filter that requires a number, a date or an array throws (`#28`–`#30`), confined to that binding and routed to `$errorCallback`.

### What is bound, and in which order

- **The children of an element whose content a binding sets are never bound** — `textContent:`, `text:`, `innerText:`, `innerHTML:`, `html:` (and `outerHTML:` / `outerText:`, which replace the element): `{{ }}`, `data-wcs` and templates in them stay literal, also when `#init=element` / `#init=none` leaves the children you wrote in place. Put markup that needs bindings in a separate element.
- **The children of `<noscript>` and `<iframe>` are not bound** (nor of `<script>` / `<style>`); the element's own `data-wcs` (`srcdoc:`, `attr.src:`) still binds.
- **At page level an element's children are bound before the element's own bindings** — a custom element's first property writes, and the order in which `$errorCallback` receives failures, run children first. Inside templates the order is document order.
- What a binding puts into the page is a value, not markup: rendered text, `innerHTML:` content and a custom element's own rendering are never scanned for bindings.

### Property types

| Property | Description |
|---|---|
| `value` | Element value (two-way for input/select/textarea) |
| `checked` | checkbox/radio checked state (two-way) |
| `textContent` / `text` | Text (`text` is an alias) |
| `html` | innerHTML |
| `class.NAME` | CSS class on/off. **The value must be a `boolean`** — a truthy string or number throws `[wcs/binding-type-expectation]` #401 on every apply. Write `class.on: count\|gt(0)`, or `class.on: label\|truthy` when you really mean "coerce". `undefined` / `null` remove the class |
| `style.PROP` | CSS style property — the DOM name (`style.backgroundColor`) or the CSS name (`style.background-color`, a custom property `style.--gap`); `undefined` / `null` remove it |
| `attr.NAME` | Attribute setting (SVG namespace supported) |
| `radio` | Radio group → single value (two-way) |
| `checkbox` | Checkbox group → array (two-way) |
| `onclick`, `on*` | Event handlers (§8) |

In addition, any DOM property name can be used (e.g. `disabled: createFetch.loading`).

**A name starting with `on` is always an event binding.** `online: x` listens for a `"line"` event, and `once: flag` on `<wcs-timer>` / `<wcs-raf>` / `<wcs-resize>` / `<wcs-intersect>` listens for `"ce"`. In both cases the value never arrives, silently. **Put a dot in front to bind the property** — `.online: isOnline`, `.once: flag`. The dotted form is the same binding as the undotted one, except that it is never an event: `.value:` is two-way, and modifiers and input filters apply. Lint reports an undotted `on*` member of a built-in tag as `wcs/on-prefixed-member` (warning).

### Modifiers

| Modifier | Description |
|---|---|
| `#ro` | Read-only (disables two-way binding) |
| `#prevent` | `event.preventDefault()` |
| `#stop` | `event.stopPropagation()` |
| `#direct` | Put the `on*:` listener on the element instead of delegating it to the root — §8. On a binding that is not an event binding, lint warns `wcs/template-syntax` |
| `#onchange` | Two-way binding on the `change` event instead of `input` |
| `#init=state\|element\|auto\|none` | Binding authority for wcBindable elements: decides ONLY who wins the initial sync — two-way members flow both ways afterwards. `#init=element` is the declarative load-before-bind form: `<wcs-storage data-wcs="value#init=element: todos">` keeps the persisted value at bind, then writes back normally. Needs `enableDirectionalInitialSync` (on by default; `#31` when a state turned it off) |
| `#sync=call\|connect` | Snapshot read timing under element authority (`connect` also holds state→element writes until the initial conflict resolves) |

### Two-way binding (auto-enabled)

`<input>` (value/checked/valueAsNumber/valueAsDate), `<select>` (value, change event), `<textarea>` (value). `<input type="button">` is excluded.

### Text: `{{ }}` and comment bindings

```html
<p>Hello, {{ user.name }}!</p>                   <!-- mustache: shows the braces until state binds (FOUC) -->
<p>Hello, <!--@@: user.name-->!</p>              <!-- comment binding: renders nothing until bound -->
<p>Total: <!--@@wcs-text: total|locale--></p>    <!-- the same, with the wcs-text keyword -->
```

- Both are the same text binding — filters included, at page level and inside templates; the comment is replaced by a text node at its position. The expression may span lines.
- **At page level prefer the comment binding (or `textContent:`)**: `{{ }}` outside a `<template>` is visible until state has loaded (lint: `wcs/template-syntax`, info). Inside `<template>`s (`for:` / `if:` rows) `{{ }}` is fine — template content is inert until rendered.
- `{{ }}` follows `$behavior.enableMustache` (on by default); **comment bindings bind even with `enableMustache: false`**.
- The keyword is empty or `wcs-text` — nothing else (no renaming option exists). A comment inside `<textarea>` or `<title>` is not bound (the browser parses that content as text): bind `value:` / `textContent:` there.

## 4. List Rendering (`for`)

```html
<template data-wcs="for: users">
  <div>
    <span data-wcs="textContent: users.*.name"></span>  <!-- full path -->
    <span data-wcs="textContent: .name"></span>          <!-- dot shorthand -->
  </div>
</template>
```

- No key attribute needed (identity-based diffing). Arrays must **always be reassigned as new arrays** (`concat`/`toSpliced`/`filter`/`toSorted`/`toReversed`/`with`). The runtime does not observe `push`/`splice`/`sort` or direct index writes such as `this.items[0] = value`; lint reports these as `wcs/array-mutation` / `wcs/array-index-assign` (errors).
- Dot shorthand: `.name` → `users.*.name`, `.` → `users.*` (element value for primitive arrays); `.name|upper` also works. `{{ .name }}` also works inside rows.
- **Row identity is the element value** — for objects, the reference. When you assign a new array, rows are matched to its elements by identity and move with them; every non-destructive array method preserves references, so sorting and filtering are structurally keyed.
- **`for:` takes no filters** (`for: items|take(2)` → `[wcs/binding-syntax]` #121). A row of `for: items` is `items.<index>`, so the rows of a filtered array would name other elements. Declare a getter that returns the filtered or sorted list and loop over it: `get firstTwo() { return this.items.slice(0, 2); }` + `for: firstTwo`.
- **Writing a list element replaces the value at that position.** `this["items.0"] = c` and `$resolve("items.*", [0], c)` keep the row where it is, with its `$1` and the DOM state bindings do not own (focus, text typed into an unbound input, `<details>` open state); everything derived below the row is computed again, and `$watch("items.*")` fires for that position. **To move rows with their values, assign a new array** (a swapped copy, `toSorted`):

  ```js
  const items = this.items.slice();
  [items[0], items[1]] = [items[1], items[0]];
  this.items = items;
  ```
- **Replacing an element updates every read below it**: `this["items.0"] = { ...this["items.0"], name: "z" }` — the form `wcs/array-index-assign` tells you to write — makes `this["items.0.name"]`, `$getAll("items.*.name", [])` and row getters read the new object, with or without a `for:`.
- **An index past the end**: a write (`this["items.5.v"] = 1`, `$resolve("items.*.v", [5], 1)`) throws `no row for "items.*.v"` (`#3`) and changes nothing; a read returns `undefined`. Grow the list by assigning a new array first.
- **`data-wcs` is removed from the elements cloned for rows (and `if:` branches)** — CSS or test selectors such as `[data-wcs*="items"]` do not match them. Use a class or a `data-*` attribute of your own.
- **A `for:` over a getter.** When the getter returns the list itself (`get shown() { return this.todos; }`), writes through its rows — a two-way `checked: .done`, `this["shown.0.done"] = true` — reach the source list, its readers and `$getAll`, and other `for:`s over it. When it returns a **filtered copy**, the row objects are reachable from two lists, and a write below one row does not reach the other list's row bindings and row getters (known 4.0 limitation, #365). For the TodoMVC shape, toggle from a handler that reassigns the source list with a new row object — `toggle(e, i) { const id = this.shown[i].id; this.todos = this.todos.map((t) => t.id === id ? { ...t, done: !t.done } : t); }` (`i` is the position in `shown`) — so the filter getter, the count and every `for:` recompute from the new array.
- **One object at two positions** (`items: [o, o]`) has the same limitation: a write through `items.0.name` does not reach `items.1`'s bindings; plain reads, root getters and `$getAll` see the new value. Give each position its own object.

### `$listKeys` — identity across a refetch

The exception to identity is **data that arrives as freshly created objects**: `(await fetch(...)).json()`, `JSON.parse` out of storage, a full-snapshot WebSocket/SSE push, a worker `postMessage`. No row matches by reference, so every row is torn down and rebuilt — and DOM state the bindings do not own (focus, an in-progress IME composition, `<details>` open/closed, in-row scroll position, `<canvas>` pixels, `<video>.currentTime`) is not merely lost but **shuffled between rows**. Declare a key and rows survive the refresh:

```javascript
{
  items: [],
  $listKeys: {
    "items": "id",                          // field name
    "items.*.children": (row) => row.uid,   // function, for composite keys
  },
}
// rows are all-new objects, but they are matched by id: DOM, focus and
// <details> state are kept and only the fields that actually changed are written
this.items = await (await fetch("/api/items")).json();
```

- **Opt-in and per-path.** Undeclared lists behave exactly as before at zero extra cost. Nesting is opt-in too — only declared paths are key-matched.
- **An unchanged refresh is free**: no field writes, no DOM work. A keyed refresh fires `$watch` only for the fields that changed, with a real `prev` (§10).
- **Rows must be plain objects**, and keys must exist and be unique. A duplicate, missing, or class-instance key is an immediate error. The declaration is validated when the state is installed: empty paths, empty segments, a trailing `*` (declare `items`, not `items.*`), non-flat key field names (no `.`/`*`), and `Object.prototype` names are rejected.
- **A field that disappears from a row is cleared to `null`** — `null` is this package's explicit "clear" vocabulary, while `undefined` means "no value" and skips the write.
- **The stored array is rebuilt from the matched row objects**, so after assignment `this.items !== theArrayYouAssigned`.
- Declare it on the **root** state or in a mounted component (its own lists); a volume declaring it is not grafted. On `/core` install `features/list-keys`.
- `@wcstack/lint` and the VS Code extension follow the declaration, so `for: items.*.children` completes and validates even when `items` starts as `[]`.

### Nested loops

```html
<template data-wcs="for: regions">
  <template data-wcs="for: .states">        <!-- .states → regions.*.states -->
    <span data-wcs="textContent: .name"></span> <!-- → regions.*.states.*.name -->
  </template>
</template>
```

An inner array held by several outer rows (`const inner = […]; groups: [{ items: inner }, { items: inner }]`) is drawn and written consistently — writes land on the element written, and every list that renders it follows — except where one object is reached through two arrays (the limitation above). Copy per row (`groups.map(g => ({ ...g, items: [...g.items] }))`) when rows must diverge.

### Loop index

- Inside getters/handlers: `this.$1` (outer), `this.$2` (inner), ... — `$1`…`$128`; `$0` / `$129` / `$01` throw `[wcs/index-param-range]`.
- Inside templates: `{{ $1|add(1) }}` (1-based row number); an outer index inside a nested template follows its row after a reorder.
- `.length` paths also work: `data-wcs="if: cart.items.length|gt(0)"`

## 5. Conditional Rendering (`if` / `elseif` / `else`)

```html
<template data-wcs="if: count|gt(0)"><p>Positive</p></template>
<template data-wcs="elseif: count|lt(0)"><p>Negative</p></template>
<template data-wcs="else:"><p>Zero</p></template>
```

- `else:` **requires the trailing colon** (no right side). Nested `if` is allowed. The condition is coerced with `Boolean()`, so a falsy non-boolean (`0`, `""`, `undefined`, `null`) shows the `else:` branch, and `|not` accepts any value.
- **A structural binding must be the only binding in its `data-wcs`** (#201); put other bindings on elements inside the template.

## 6. computed (path getters) and the Proxy API

**Getters on a plain object**, not class syntax. Dot-path string keys + `*` wildcard:

```javascript
export default {
  users: [{ id: 1, firstName: "Alice", lastName: "Smith" }],
  get total() { return this.price * (1 + this.tax); },          // top level
  get "cart.totalPrice"() { /* nested computed */ },
  get "users.*.fullName"() {                                     // wildcard
    return this["users.*.firstName"] + " " + this["users.*.lastName"];
  },
  set "users.*.fullName"(value) { /* path setter, two-way capable */ },
  get "categories.*.items.*.label"() { /* multiple wildcards */ },
};
```

- Inside a getter, `this["users.*.firstName"]` auto-resolves to the current loop element. Automatic dependency tracking, per-address caching.
- **Numeric indexes are ordinary path segments**: `this["users.0.name"]`, `` this[`cart.items.${i}.quantity`] += 1 ``, `{{ users.1.name }}`, `groups.0.items.1.v`, `for: groups.0.items` — they read, write and follow writes on any list, rendered or not. A `$watch` key with a numeric index (`"items.0.v"`) fires only when the value at that index changes.
- **Numeric keys under a plain object** (`sales.2024.total`, `usersById.42.name`) are the exception (known 4.0 limitation): markup renders them, but a script read (`this["sales.2024.total"]`, also inside a getter) gives `undefined`, `$eq` on such a path is always false, a write throws `no row for "sales.*.total"`, and a two-way write-back fails. Read `this.sales[2024].total`, and write by assigning a new object to the top-level key (`this.sales = { ...this.sales, 2024: { ...this.sales[2024], total: 10 } }`) — or use keys that are not numbers.
- **Writing a top-level key the state does not have creates it** (reading one throws `[wcs/binding-path-missing]`). Declare every key; a write typo is otherwise silent.
- Chaining into a getter's returned object works: `this["cart.items.*.product.price"]`.

### Getters must be pure with respect to state

The cache is invalidated **only** through the dependency graph, and the graph records only what the getter read **through `this`**. Everything else is invisible to invalidation, so the first value computed is the value you keep — forever, with no warning:

```javascript
get stamp() { return `${this.label} @ ${Date.now()}`; }  // ❌ Date.now() untracked — never recomputes
get theme() { return document.body.dataset.theme; }       // ❌ the DOM is untracked
get total() { return this.price * exchangeRate; }         // ❌ a module variable is untracked
```

The rule: **read only through `this`; never write state or touch the DOM from a getter.** When an untracked input genuinely must participate, put it into state and assign to it (`now: Date.now()` seeded, then `this.now = Date.now()` on a timer in `$connectedCallback`), or use the escape hatches — `$dependOn(path)` (register an extra dependency), `$postUpdate(path)` (announce an untracked change from outside), `$untracked(fn)` (read without registering). Getters that throw are not swallowed: the exception surfaces where the getter was evaluated (a binding apply, a `$watch` evaluation, or your own read). Mutually-recursive getters are a reported cycle (`[wcs/getter-cycle]` #701).

### Dependency tracking boundaries

Three rules decide what the graph sees. None matters until you cross one, and the symptom is always *a value that stops updating with no error*:

| Rule | What it looks like when crossed |
|---|---|
| **Only path reads through `this` are tracked.** `this.form` tracks `form`; `this["form.name"]` tracks `form.name`; **`this.form.name` tracks `form` only** — the `.name` is a plain property access on the object that came back | A getter reading `this.form.name` does not re-run when a bound `<input data-wcs="value: form.name">` changes — read `this["form.name"]`. `wcs-validate` and the VS Code extension report **`wcs/getter-untracked-read`** (warning) when a getter reads `this.form.name` and the document writes `form.name` somewhere; a root that is only ever replaced wholesale is left alone, and so are array roots (`this.items[0].name` — `items` suffices) |
| **Reads inside a setter are not tracked.** A setter is an imperative assignment, not a derivation | A setter that reads `this.a` to decide what to write does not run again when `a` changes — only a getter re-runs. `$untracked(fn)` applies this rule to a getter on purpose |
| **The same-value guard is primitive-only.** An `Object.is`-equal primitive write is dropped before anything is enqueued; an object or array write always passes, even the same reference | Assigning the same string again fires nothing; assigning the same object again re-fires its bindings and `$watch` (`semantics: "event"` properties are exempt either way). `$behavior: { sameValueGuard: false }` turns the guard off for that tree |

The storage "persist a form as one object" recipe (`io-node-catalog.md` §2) is where the first rule bites most often: the accessor pair's getter must read `this["form.name"]`, not `this.form.name`.

### Demand roots — what makes a getter run

Path getters are **lazy**; "does this getter run?" depends on where demand comes from, and there are exactly **three roots**: a **live DOM binding** (demand disappears with the element!), a **`$watch` declaration** (headless), and a **`$stream` `args` function** (evaluated on start and every restart). **`$renderedCallback` is not a root** — it reports what the bindings did. Logic that must not depend on what is rendered belongs on `$watch` or `args`; a display-only element that is secretly the only demand root is the accident `wcs/updated-callback-unbound` catches statically.

### Proxy API (via `this`)

| API | Description |
|---|---|
| `this.$getAll(path, indexes?)` | Get all values of a wildcard path as an array (for aggregation). `indexes` is a **prefix** over the path's wildcards — missing levels expand fully, `[]` always means "every match"; **more than the `*` count throws `wcs/index-arity`**. **Omitting `indexes` defaults to the enclosing loop context** — `this.$getAll("regions.*.prefectures.*.population")` inside a `regions.*` getter narrows to the current region. If the path shares **no** wildcard level with a loop context that holds indexes, it throws (`#6`) rather than silently reading everything — pass `[]` explicitly there. A non-array `indexes` throws |
| `this.$setAll(path, indexes, value, options?)` | Write to **every** address a wildcard path matches, in place — see below |
| `this.$resolve(path, indexes, value?)` | Read/write at specific indexes. The index count must match the path's `*` count **exactly** (`wcs/index-arity`). **The argument count decides** — two arguments read, three write (`undefined` included). On a readonly proxy (`createState("readonly", …)`) a write throws `This state is readonly.` (`#8`), and so does `$setAll` |
| `this.$postUpdate(path)` | Manually emit an update notification (reaches keyed-selection rows too) |
| `this.$dependOn(path)` / `this.$untracked(fn)` | Manually register / suppress dependencies |
| `this.$eq(path, key)` / `this.$eqPath(path, keyPath)` / `this.$eqIndex(path, level?)` | Keyed subscription — "is `path` equal to this row's key?" without a dependency on `path` from every row. See below |
| `this.$stateElement` | IStateElement access |
| `this.$1`, `this.$2`, ... | Loop indexes, `$1`…`$128` (`$129` / `$0` / `$01` throw `wcs/index-param-range`) |

### `$setAll` — bulk writes that keep the array

The write-side counterpart of `$getAll`. The point is not brevity but **list identity**: `this.users = this.users.map(...)` throws away row identity, per-row getter caches, and the render diff; `$setAll` decomposes into in-place per-row writes, so the array survives.

```javascript
this.$setAll("users.*.selected", [], e.target.checked);            // broadcast (same value everywhere)
this.$setAll("users.*.selected", [], cur => !cur);                 // mapper: (current, ...indexes)
this.$setAll("users.*.score", [], (cur, i) => i < 3 ? cur * 2 : undefined);  // undefined = skip this row
this.$setAll("matrix.*.*", [0], 0);                                // indexes prefix: row 0 only
this.$setAll("users.*", [], rows, { spread: true });               // one entry per address, in match order
```

- Three forms: a **function** is a mapper; **anything else broadcasts** (arrays included — the target may itself be array-valued); an array **plus `{ spread: true }`** hands one entry per matched address, and a length mismatch throws (`#10`) rather than misaligning.
- `undefined` is never written ("skip this address" in all three forms — a mapper that forgets to `return` wipes nothing); use `null` to clear. Returns the number of addresses written.
- `indexes` is a prefix exactly as in `$getAll` but **required** (`#9`) — writes get no implicit loop context, so inside a `for` template `$setAll("users.*.selected", [], true)` still means *every* user, never the current row.
- Not a shortcut for the dependency walk: each write is enqueued individually (cost matches the hand-written loop); rendering still coalesces into one batch.

**A path's depth is fixed in its string.** `nodes.*.children.*.total` is depth 2 and nothing stretches it to 3. For a tree whose depth is decided by the data, declare `$recursion` and write `**` — §14.

### Keyed selection — `$eq` / `$eqPath` / `$eqIndex`

A row getter that answers "is this row the selected one?" is where dependency tracking scales worst: `get "items.*.selected"() { return this.$1 === this.selectedIndex; }` (or `this["items.*.id"] === this.selectedId`) makes **every** row depend on the selection path, so one click re-evaluates the whole list. The keyed forms read the selection path **without** a dependency and subscribe each row under **its own key**, so a write to the path re-evaluates only the row that was selected and the row that becomes selected:

| API | Key | Selection follows | Notes |
|---|---|---|---|
| `this.$eq(path, key)` | any value you pass | the key | Pass a tracked read (`this["items.*.id"]`) when the key itself can change, `this.$untracked(() => …)` when it cannot |
| `this.$eqPath(path, keyPath)` | the value at `keyPath` (its wildcards resolve to this row) | the id | Reads the key untracked too, so reordering or replacing the list never re-evaluates the rows. **Survives sorting and removal** — the default choice |
| `this.$eqIndex(path, level = 1)` | this row's index (`$1`; `level` picks the wildcard in a nested list) | the position | Unlike reading `$1`, the getter is not recorded as index-dependent — removing a row re-evaluates at most two rows |

```javascript
export default {
  items: [],
  selectedId: null,
  get "items.*.selected"() { return this.$eqPath("selectedId", "items.*.id"); },   // by id
  select(e, i) { this.selectedId = this[`items.${i}.id`]; },          // (event, ...listIndexes)
};
```
```html
<template data-wcs="for: items">
  <li data-wcs="class.selected: .selected; onclick: select; textContent: .name"></li>
</template>
```

Rules:

- **What reaches the rows** — a write to `path` of any value, objects included (`this.selected = row` with `$eq("selected", this["items.*"])`), a write that replaces an object above it (`this.selection = { id }` under `$eqPath("selection.id", …)`), and `$postUpdate(path)`: the row that was selected and the row that becomes selected.
- **A getter as `path`**, a path under one, or a path with a numeric index falls back to an ordinary tracked read: the selection is correct, but a change re-evaluates every row — point `path` at the written state (`selectedId`) to keep the two-row cost.
- **Keys compare like `Map` keys** (`Object.is`, except `+0`/`-0` and `NaN`/`NaN` count as equal), so no type coercion: a selection written as the string `"2"` by an `<input>` / `<select>` never matches numeric ids — convert on the way in (`value|number: selectedId`).
- `$eqPath` reads the key without a dependency, so a row whose key changes **in place** is not re-evaluated by that change — use it for identities that do not change (ids), and `$eq` with a tracked key read when the key itself is live.
- They subscribe only when evaluated inside a getter; called from a method or a handler, `$eq` / `$eqPath` just return the comparison. `$eqIndex` needs a list row: in a getter outside a row it throws `$eqIndex("…") needs a list row scope.` (`#7`). A row's subscription is dropped when the list diff removes the row.
- Inside a `mount=` volume or a `bind-component` scope they resolve against that scope, like `$getAll` / `$setAll` / `$resolve` / `$postUpdate`.
- **DevTools:** the State pane counts the subscriptions per path under **Keyed selection** and marks a path that fell back to a tracked read with a `tracked` badge.

### Iron rule of state updates

```javascript
this["user.name"] = "Bob";   // ✅ path assignment → DOM update
this.user.name = "Bob";      // ❌ runtime ignores it; lint wcs/nested-assign (error)
```

## 7. Filters (47 built-ins; no public registration API)

- Comparison: `eq` `ne` `not` `lt` `le` `gt` `ge`
- Arithmetic: `add` `sub` `mul` `div` `mod` `abs` `clamp`
- Number formatting: `toFixed` `round` `floor` `ceil` `locale` `percent` `unit`
- String: `upper` `lower` `capitalize` `trim` `slice` `padStart` `padEnd` `repeat` `reverse` `truncate` `join`
- Type conversion: `int` `float` `boolean` `number` `string` `nullIfEmpty`
- Date: `date` `time` `datetime` `ymd` `hms`
- Truthy/default: `truthy` `falsy` `defaults` `coalesce`

The comparison, arithmetic (except the number formatting), conversion and truthy/default families are the core set; the formatting filters come from `features/formats` (`/auto` and the full entry install both — §1). There is no `substr` (write `slice(start, start + length)`; `slice` takes the end index) and none of the 3.x short names (`uc`, `inc`, `fix`, `pad`, `null`, … — §16): an unknown name throws `[wcs/filter-unknown]` #501, and for a removed 3.x name the diagnostics feature names the replacement instead of a did-you-mean.

With arguments: `gt(10)`, `slice(0,10)`, `padStart(5)` or `padStart(5,'0')` — quote the pad character, since an unquoted `0` is a typed *number* and lint reports `wcs/filter-arg-type` — `locale(ja-JP)`, `date(ja-JP)`, `ymd(/)`, `eq('admin')` (quotes allowed, bare allowed, comma-separated). Chaining: `price|mul(1.1)|round(2)|locale(ja-JP)`. Do transformations the built-ins cannot express in a getter.

**Filter arguments are typed.** Unquoted `true` / `false` / `null` / numbers are typed literals, quoted arguments are strings: `done|eq(true)` matches `true`, `eq('true')` does not, `eq(null)` matches `null`; a non-string literal compares as itself (a number never equals `null` or `true`), and a form value `"1"` still matches `eq(1)`. `defaults(v)` returns the typed value (`defaults(0)` → `0`; `defaults('0')` for the text). `truthy` / `falsy` / `defaults` use JavaScript truthiness (`0n` is falsy). Still prefer binding a boolean directly (`class.done: done`, `hidden: done|not`). `coalesce(v)` replaces only `null` / `undefined` while `defaults(v)` replaces every falsy value (`0`, `false`, `""` included) — pick `coalesce` for a count that may legitimately be `0`. `add` / `sub` require their argument.

**Arity is checked** (`[wcs/filter-arity]`, the bounds lint uses): `join(a,b)` throws "accepts at most 1 argument(s)"; `date` / `time` / `datetime` / `locale` / `toFixed` / `round` / `floor` / `ceil` / `percent` / `join` / `ymd` / `hms` take 0–1, `slice` / `padStart` / `padEnd` / `truncate` 1–2, `clamp` 2. `Object.prototype` names (`|toString`, `|valueOf`) are `wcs/filter-unknown`.

Contracts worth knowing:

- `abs` — `Math.abs`; number input required.
- `clamp(min, max)` — both arguments required; saturates into `[min, max]`. Same family as `round`/`floor`: a wire conversion, so it belongs on the binding, not in state.
- `unit(u)` — appends any suffix: `width|unit(px)` → `"40px"`. **Accepts strings as well as numbers on purpose** — the useful chains run through `toFixed`/`percent`, which return strings. `null`/`undefined` pass through untouched (never `"undefinedpx"`). The canonical style-binding chain that keeps presentation out of state: `style.height: samples.*.cpu|clamp(0,100)|toFixed(0)|unit(%)`.
- `join(sep?)` — array → string; default separator is `", "`.
- `truncate(n, suffix?)` — `n` counts **kept characters** (matching the `slice(0, n)` reading), suffix defaults to one `…` (U+2026); a string at or below the limit is returned untouched.
- `hms(sep?)` — the counterpart of `ymd`: fixed zero-padded `HH:MM:SS` from a Date, locale-independent, separator defaults to `:`.
- `padStart`'s default pad character is `0` while `padEnd`'s is a space (deliberately not symmetric — `padStart` exists for zero-padding).
- Whitespace inside quotes is literal: `padStart(5, ' ')` pads with a space and `join(' / ')` works.

**The default locale is `<html lang>`, read when `@wcstack/state` is evaluated**, falling back to `'en'`. The four locale-dependent filters — `locale`, `date`, `time`, `datetime` — use it. Always set `<html lang>` in the markup; an explicit `bootstrapState({ locale })` still wins; a tag `Intl` does not take is reported (`#48`) and `'en'` is used. **Changing the locale later re-renders nothing** (it is a page setting, not state). Per-call overrides (`price|locale(fr-FR)`) are fixed at bind time. For pages that switch language without reloading, translations belong on a path, not in a filter (`docs/i18n-design.md`).

## 8. Event Handling

```html
<button data-wcs="onclick: handleClick">Click</button>
<form data-wcs="onsubmit#prevent: handleSubmit">...</form>
```

```javascript
export default {
  items: ["A", "B", "C"],
  handleClick(event) { /* this = state proxy */ },
  removeItem(event, index) {        // (event, ...listIndexes) when inside a loop
    this.items = this.items.toSpliced(index, 1);
  }
};
```

- Signature: `(event, ...listIndexes)`. Inside loops, the enclosing loop indexes are appended after the event.
- **`onclick:` binds a method name only and cannot pass arguments** — for argument variants, define zero-argument wrapper methods (e.g. `filterAll() { this.filterBy(""); }`), or read the loop index.
- Writing `$command.<name>` on the right side emits directly: `<button data-wcs="onclick: $command.refreshList">`.
- Two `on*:` bindings of one type on one element (`onclick: a; onclick: b`) both run.

### Delegation and `#direct`

`on*:` bindings for `click`, `dblclick`, `input`, `change`, `submit`, `keydown`, `keyup`, `mousedown`, `mouseup`, `pointerdown` and `pointerup` are **delegated**: one listener per event type sits on the root the state binds — the document, a shadow root, or, inside a Light DOM mounted component, the host element — and it runs the handlers of the elements the event passed, innermost first. Other event types, and an event a custom element dispatches with `bubbles: false`, are heard on the element. Two-way bindings (`value:`, `checked:`, radio, checkbox) keep their listener on the element.

| | Delegated `on*:` | `on*#direct:` |
|---|---|---|
| `event.currentTarget` in the handler | **the root** (document, shadow root, Light DOM host) | the element |
| `#stop` on an inner binding | stops the outer delegated handlers | stops them, **and** your own `addEventListener` listeners on ancestors |
| Your code calls `stopPropagation()` on an ancestor (a modal's content keeping clicks from the overlay) | the inner handler **never runs** | it runs |
| The element is moved under another root (a dialog moved from a shadow root to `document.body`) | its handler **does not run** | it runs |

- **Do not read `event.currentTarget` in a plain `on*:` handler.** Prefer `event.target.closest("li")` or the loop index the handler receives. Lint reports a delegated-event handler that reads `currentTarget` from its event parameter as `wcs/delegated-current-target` (warning); it cannot see `stopPropagation()` in your own code or elements moved between roots.
- **Write `on*#direct:` only where the listener must sit on the element** — pointer capture (`e.currentTarget.setPointerCapture(…)`), the element's own rect, `new FormData(e.currentTarget)`, a `#stop` meant to stop your own listener on an ancestor, an ancestor that calls `stopPropagation()`, an element you move to another root. It combines with `#prevent` and `#stop` (`onclick#direct,stop:`). Inside `for:` / `if:` it is attached per row and removed with the row.
- **Order:** handlers run where the DOM puts them. An outer `#direct` handler runs on its element, before the delegated handlers inside it run at the root, so an inner delegated `#stop` cannot stop it — `<li data-wcs="onclick#direct: select">` around `<button data-wcs="onclick#stop: remove">` runs `select` and then `remove`. When an outer binding is `#direct`, make the inner `#stop` binding `#direct` too (`onclick#direct,stop: remove`).

## 9. command-token / event-token

### command token (state → element method invocation)

```html
<wcs-state>
  <script type="module">
    export default {
      $commandTokens: ["refreshList"],
      onClick() { this.$command.refreshList.emit("/api/users", { method: "GET" }); }
    };
  </script>
</wcs-state>
<!-- Subscriber side. The right side must be $command.<name> (bare names throw #1201) -->
<wcs-fetch data-wcs="command.fetch: $command.refreshList"></wcs-fetch>
```

- Declare with `$commandTokens: string[]` → `this.$command.<name>.emit(...args)`. Arguments are forwarded verbatim to the subscribing element's method (not awaited; wait on Promises with `Promise.all(token.emit(...))`).
- One token fans out to multiple elements; subscribe order is preserved. An undeclared `$command.<name>` in markup throws `[wcs/token-undeclared]` #1302; a method the element does not declare throws `[wcs/token-misconfigured]` #1203. A subscriber that throws is reported (`#17`) and the others still run.

### event token (element → state)

```html
<wcs-state>
  <script type="module">
    export default {
      users: [],
      $eventTokens: ["userCreated"],
      $on: {
        userCreated(state, event) {          // state is the first argument, not this
          state.users = state.users.concat(event.detail);
        },
        // emitter inside a loop: (state, event, ...listIndexes)
      }
    };
  </script>
</wcs-state>
<!-- The key is the wcBindable property name (not the raw event name). The token name is bare (no $) -->
<my-form data-wcs="eventToken.created: userCreated"></my-form>
```

- The event-token surface fires on **every** dispatch, including a repeat of the same payload — it is the occurrence channel, so prefer it over a property binding whenever "it happened again" is the thing you care about. (On I/O nodes, properties declared `semantics: "event"` are also exempt from the same-value guard; see `io-node-catalog.md` §0.)
- **`$on` handlers are not awaited.** An async handler which rejects is caught and reported through `console.error` naming the state and the handler; it is neither propagated nor awaited, so never sequence work on the return value — let the async work write its own state slot when it settles. Synchronous throws still propagate as programmer errors.
- Declaration errors are loud: a non-array or duplicate token list (`#18`–`#21`), an `$on` entry not in `$eventTokens` (`#23`) or not a function (`#24`), an `eventToken.` name not in `$eventTokens` (`[wcs/token-undeclared]` #1301), an element with no such wcBindable property (`#1204`).
- **Where they run**: on the root state; in a **mounted component**, on the component's own bindings (`$commandTokens` / `$eventTokens` / `$on` run there); in a volume they are not run (`console.warn`). Re-attaching the root `<wcs-state>` keeps both registries; nothing fires while it is disconnected, and a re-set replaces the `$on` subscriptions.

### state ↔ wcs-fetch working example (skeleton of the users-crud example)

```html
<script type="module" src="https://esm.run/@wcstack/fetch/auto"></script>
<script type="module" src="https://esm.run/@wcstack/state/auto"></script>

<wcs-state>
  <script type="module">
    export default {
      $commandTokens: ["refreshList"],
      $eventTokens: ["userResponded"],
      // 1 fetch = 1 state slot. For outputs the element is the authority, so seed with real initial values (null)
      listFetch: { value: null, loading: false, error: null, status: 0 },
      createFetch: { url: "/api/users", method: "POST", manual: true,
                     body: { name: "" }, value: null, error: null, loading: false, status: 0 },
      get "listFetch.url"() { return "/api/users"; },   // compute the URL with a nested getter inside the slot
      get listRows() { return this["listFetch.value"] ?? []; }, // for: requires an array, so null-guard
      $on: {
        userResponded: (state, event) => {
          const status = event.detail?.status ?? 0;
          if (status < 200 || status >= 300) return;   // wcs-fetch:response also fires on errors
          state.$command.refreshList.emit();
        },
      },
    };
  </script>
</wcs-state>

<wcs-fetch data-wcs="...: listFetch; command.fetch: $command.refreshList"></wcs-fetch>
<wcs-fetch data-wcs="...: createFetch; eventToken.value: userResponded">
  <wcs-fetch-header name="Content-Type" value="application/json"></wcs-fetch-header>
</wcs-fetch>
```

### spread binding (`...`)

- `...: target` wires all wcBindable properties + inputs at once. `commands`/event tokens are excluded (explicit wiring required).
- Inside for: `...: storesFetches.*` (recommended) or `...: .`.
- Last-wins override: `...: usersFetch; status: alternateStatus`.
- Right-side filters are an **error** (`#105`). Elements without a wcBindable declaration are an **error** (`[wcs/spread-no-bindable]` #1501) — statically caught for the built-in helper tags (`wcs-fetch-header` / `wcs-fetch-body` / `wcs-infinite-scroll` / `wcs-voice`). An empty-but-declared contract (`wcs-noise`) is legal: it expands to zero props.
- `undefined` state paths are write-skipped for the property (the element default survives). Clear by assigning `null`.
- **wc-bindable elements inside `for:` rows** work in both load orders: an output-only member (`<wcs-fetch>`'s `value` / `loading`, `<wcs-intersect>`'s `intersecting`, …) or a two-way member with `#init=element` takes its initial value from the row's own element, and a spread onto a not-yet-defined element waits for its definition (the rows render at once). In a shadow root with a scoped `CustomElementRegistry`, row elements wait on that registry. A value an element writes to its own row (`value: .`, `status: .`) updates that row only.

## 10. `$watch` — headless change subscription

`$renderedCallback` is binding-driven: a value nothing renders is invisible to it. **`$watch` fires on state changes whether or not the path has a DOM binding.**

```javascript
export default {
  isLoading: false,
  items: [],
  $listKeys: { items: "id" },          // optional: a keyed refetch fires only the changed fields, with a real prev
  $watch: {
    // edge detection is yours: compare cur/prev in the handler
    isLoading(cur, prev) {
      if (cur === true && prev === false) { this.startedAt = Date.now(); }
    },
    // wildcard paths fire once per changed row; trailing args are this scope's indexes
    "items.*.price"(cur, prev, index) {
      this.lastPriceChange = `#${index}: ${prev} → ${cur}`;
    },
  },
};
```

- **Handler contract**: `(cur, prev, ...indexes)`, `this` = **writable** state proxy (writes land in the next update batch); the return value is ignored and never awaited. `cur` is the settled value at drain time; `prev` is the value at the start of the batch (first-write-wins).
- **`prev` comes only with a primitive write** (for a getter: its previous evaluation) — it is `undefined` when the *new* value is a reference type, for `$postUpdate`, and for a row that entered the list.
- **No firing condition of its own**: it fires for whatever landed in the batch — a write of its path or of an object above it in the same row, a change that reached its getter, a row that entered its list. Equal primitive writes are already dropped before enqueue (effectively change-only firing), but a `semantics: "event"` occurrence write is *not* dropped and fires with `cur === prev`.
- **Rows are headless**: a wildcard row watch needs neither a `for` binding nor `$listKeys` — the watch keeps its lists synced itself. A whole-array assignment fires only the rows that **entered** the list (`prev` undefined); a row kept by identity did not change and does not fire; an in-place mutation announced with the same array, a copy, or `$postUpdate("items")` fires nothing (getters still read the new values). After a `fetch().json()` refresh every row is new, so every row fires — declare `$listKeys` to turn that into per-field writes that fire only what changed, with a real `prev`.
- **Watching a getter makes it eager** — wildcard getters included: evaluated at connect and again at the end of every batch touching its dependencies (`prev` = previous evaluation). A change that reaches the getter fires the watch whether or not its value changed (no condition of its own); a wildcard getter fires per row the change reached. You pay that evaluation per batch, and exceptions inside the getter surface through the watch. A row getter on a row a list assignment or re-sort kept fires only when its value changed — unless the same batch changed something it read outside its row (`now`, `items.length`, a root getter over them).
- **A numeric-index key** (`"items.0.v"`) fires only when the value at that index changes.
- **Ordering** at the end of a drain is fixed: bindings applied → `$renderedCallback` → binding failures (`$errorCallback`, or the console) → `$watch` handlers (declaration order; ascending indexes between rows of one path) → `$stream` restarts. A `<wcs-view-transition>` accepting the `state` participant puts binding application — and with it `$renderedCallback` — on a **frame**, while `$watch` and the `$stream` restart stay on the original microtask, so the order becomes `$watch` → `$stream` restart → `$renderedCallback` while that tag is present (`for="router"` on the tag keeps state's timing untouched).

Key rules (each of these fails silently or surprisingly if ignored):

1. **Scope-relative paths only, declared on the root state** — a key is a path in the root's vocabulary (`"cart.total"` for a volume's value). A volume declaring `$watch` is not grafted; a mounted component's `$watch` is not run (`[wcs/mount-dollar-declaration]` warning).
2. **A key cannot start with `$`** — so `$streamStatus.<name>` / `$streamError.<name>` cannot be watched directly. The idiom: mirror through a one-line non-`$` getter (`get streamStatus() { return this["$streamStatus.pageResult"]; }`) and watch that — the eager-getter rule is exactly what makes it work unrendered. The accumulation itself belongs in a `$watch` on the stream's value that writes a key you own (§15).
3. **Intermediate values are not observable** — a batch `a → b → c` fires once with `cur = c`, `prev = a` (same contract as binding updates).
4. **Handler exceptions are isolated** — reported to the console (and the devtools timeline as `state:watch-error`), remaining watches and stream restarts still run. This differs from `$connectedCallback`/`$renderedCallback`, which fail loudly.
5. **Write chains are bounded** — a handler's writes form a new batch; a handler fired more than 32 links deep (counted per write: only a handler's write that triggers another handler extends the chain; a `$stream` restart counts like a handler) is cut with a console error (`state:watch-chain-limit` in devtools). Only the handlers and restarts those writes fired are skipped; the batch's other handlers still run. Nothing is rolled back. A loop that goes back through a **render** is the render chain limit's job (§11).
6. **SSR never runs watches** — otherwise handler side effects would execute on both server and client.
7. A re-set (`setInitialState`) is not a write: no handler fires; the new state's declarations arm themselves.

Tooling knows the declaration: `@wcstack/lint` and the VS Code extension validate it — `wcs/watch-declaration-invalid` (error: `@` key, `$`-prefixed key, empty path segment, non-function handler, a whole `$watch` value that is definitely not an object) and `wcs/watch-path-missing` (warning: the key does not exist in the state definition — unlike a binding typo, which visibly fails to render, a `$watch` typo silently never fires). The runtime's own declaration errors carry the same code, and the diagnostics feature warns once for a key that provably does not resolve. The devtools coverage tab joins `state:watch-fired` against the declared keys (*fired ×N* / *never*).

## 11. Other Features

- **Lifecycle**: On the state object: `$connectedCallback` (async allowed, awaited, runs on every reconnection), `$disconnectedCallback` (sync only), `$renderedCallback(paths, indexesListByPath)` (async allowed, not awaited), `$errorCallback(error, info)` (next bullet). On the Web Component side: `async $stateReadyCallback(stateProp)`. **Initialization order**: load the state (on the split auto entry, also the features its `$features` names) → build every binding under the root and apply its initial value, synchronously → resolve `initializePromise` and `getBindingsReady()` → run `$connectedCallback` → resolve `connectedCallbackPromise`. So **`$connectedCallback` may emit a command or read a defined element at once**; an element whose class is not defined yet gets its property / `command.` / `eventToken.` / spread bindings when it is defined (`getBindingsReady()` does not wait for those).
- **`$errorCallback(error, info)` is the in-page error boundary for bindings.** A binding whose application throws (a path getter / filter threw, a structural directive failed) is isolated — the rest of the batch applies, nothing is rolled back — and reported with `console.error` unless the **root** state declares this hook; then the report comes to it instead. `info` = `{ path, bindingType, node }` (`path` as written in `data-wcs`, wildcards intact; `node` is `null` for a list that no `for:` renders); `this` is the writable proxy, so the canonical shape is ``this.loadError = `${path}: ${error.message}` `` and a plain `textContent:` bind. Runs after `$renderedCallback`, not awaited, own exceptions isolated; DevTools still gets `state:binding-apply-error`. A **mounted component**'s `$errorCallback` receives the failures of the component's own bindings; a **volume**'s is not run (`console.warn`). Does **not** cover `$watch` handler failures or exceptions thrown by `$connectedCallback` / `$renderedCallback`.
- **`$renderedCallback` is binding-driven, not write-driven**: `paths` lists only the paths whose **live DOM bindings** were applied in that drain. A state write with no binding never calls it and never appears in `paths`. So it cannot be used as a headless watcher — that job belongs to `$watch` (§10).
- **An element that fails to initialize reports once and rejects.** `console.error` names the element and where its state comes from, then the error: `<wcs-state src="./state.js"> failed to initialize.` (`#49`; it names `state=`, `src=`, `mount=` and `bind-component=` when present). Causes: a throwing or removed `$` declaration (`$scan` `#1`, `$streams` `#1601`, …), an invalid `$behavior` (`#44`) or `$features` (`#46`), a source that cannot load (`#13`, `#16`, a CSP block `#42` / `#43`), a DCC or `bind-component` setup error, a second root `<wcs-state>` (`#47`, refused alone), and — 4.0 preview behaviour, still under review — a page-level markup error (§3). Contract:
  - `connectedCallbackPromise` **rejects** with the error (test the error itself — its type or your own class — never the message text);
  - `initializePromise` still resolves, so one element's mistake does not hold up the rest of the page;
  - `getBindingsReady(root)` rejects only when **every** `<wcs-state>` on that root failed before building its bindings (it resolves at once for a root with none);
  - `setInitialState()` on a failed element throws `this <wcs-state> failed to initialize; create a new one` (`#14`) — replace the element;
  - a `$connectedCallback` that throws or rejects **after** the bindings are built is `<wcs-state …> $connectedCallback failed.` (`#50`): `connectedCallbackPromise` rejects, but `getBindingsReady()` resolves (the page is bound) and `setInitialState()` stays open;
  - a volume never rejects (a refused volume resolves); a mounted component's `<wcs-state bind-component>` rejects when it fails to mount, when the root it is wired to failed (`<tag>.state will not mount: the root state failed to initialize.`), and when a second one connects in one component;
  - `@wcstack/server`'s `renderToString()` and `@wcstack/testing`'s `mount()` wait for every `connectedCallbackPromise` and reject with the cause. Detaching an element while its source is still loading is an interruption, not a failure.
- **A re-set re-renders the page.** `setInitialState(next)` on an **initialized** element replaces the whole state and re-applies every established binding to the new state *before it returns* — scalars, getters, row getters, `for` and `if` alike. A binding that cannot be read from the new state is reported as a **failed apply** (`console.error`, or the new state's `$errorCallback`). A re-set is **not a write**: no `$watch` handler, no `$stream` restart and no `$renderedCallback` (the new declarations arm themselves). Lists are matched by **array identity** — pass a new array when a list changed. **It may not change `$behavior`** (`a re-set state may not change $behavior: create the element again.`, `#45`); a re-set state without `$behavior` is compared with the defaults, so repeat the declaration. It throws on a tree with grafted volumes or mounted components and on a loaded `mount=` volume element. Known 4.0 preview limitation: after a re-set, `Object.keys(this)`, `in`, `delete` and `JSON.stringify(this)` still see the old state.
- **$stream**: `$stream: { name: { args?, source, fold?, initial? } }` — source is `(args, signal) => AsyncIterable|ReadableStream|Promise<same>`, honoring AbortSignal is mandatory, `initial` is required when `fold` is specified. status/error: `$streamStatus.<name>` (`"idle"|"active"|"done"|"error"`) / `$streamError.<name>` — read-only; a getter reading them depends on them. args are synchronous, cannot read wildcards, self-dependency forbidden; writing a dependency several times in one batch restarts once. An entry name that collides with a method / getter / setter on the state raises. Infinite streams require a bounded fold. **Bridging callback APIs (EventSource / WebSocket / DOM events)**: wrap in a `ReadableStream` (enqueue in `start`, release the resource in `cancel()`); the runtime cancels the reader on restart/dispose, so the AbortSignal contract is satisfied automatically. Hand-written async generators must watch `signal` themselves — a generator parked on `await` cannot be force-released from outside. A restart aborts the running run, drops its later chunks and resets the value to `initial`. **Observing a stream without rendering it**: `$watch` its value path — or, for status-driven work, mirror `$streamStatus.<name>` through a non-`$` getter and watch that (§10 rule 2). Root state only (a volume declaring it is not grafted; a mounted component's is not run). **Accumulating across runs**: a stream's `fold` resets to `initial` on every restart — fold the stream's value from a `$watch` on the stream name into a key you own (§15).
- **Runtime messages**: `[@wcstack/state] [wcs/<code>] <sentence>` with the `diagnostics` feature (`@wcstack/state`, `/auto`, `/parser`; `/core` after `installFeatures([diagnostics])`; the split auto entry with `features="diagnostics"`), `[@wcstack/state] [wcs/<code>] #<number> <values>` without it. The code comes from the number's hundreds (1xx `binding-syntax`, 2xx `template-syntax`, 3xx `binding-path-missing`, 4xx `binding-type-expectation`, 5xx `filter-unknown`, 6xx `filter-arity`, …; 1–50 have none); a number keeps its meaning across versions; the wcstack repo's `docs/state-errors.md` lists them. With the feature, a thrown message can add a did-you-mean (edit distance ≤ 2, the lint's criterion), the replacement for a removed 3.x name, a fix, and `Validate statically: npx @wcstack/lint <file>.` for the codes lint detects. Messages without a number (the feature barriers, volumes, components, SSR, `$watch` / `$stream`) are printed in full either way.
- **Unresolved wired paths warn at binding time** (diagnostics feature): a bound path that provably does not resolve (`user.nmae`) gets one `console.warn` with `wcs/binding-path-missing` + did-you-mean; reading a missing top-level key throws `[wcs/binding-path-missing]` (#301). The check **under-approximates**: `null`/`undefined` parents, rows of an empty list, sub-properties of a getter's return, mapped `bind-component` child scopes, and `$` namespaces all stay silent — **no warning proves nothing**; run lint for the exhaustive check.
- **Limits — report and continue; values and DOM are never rolled back.** A failing binding is confined to that binding (the rest of the batch, `$renderedCallback`, `$watch` and `$stream` restarts still run). Watch chains are cut at 32 links (§10). One update that does not settle within 32 passes reports `updates did not settle after 32 passes` (`#11`; devtools `state:render-chain-limit` with `maxDepth: 32`). **A write chain made while rendering is cut off after 100 drains**: some writes happen while bindings are applied — a wc-bindable element in a new `for:` row hands its initial value to state, a `$renderedCallback` writes — and each starts a drain that renders again; if every render writes something new, the 101st drain's bindings are skipped (its values stay in state) with one `render chain depth limit exceeded (100 drains that rendering itself started); bindings for this batch were not applied.` (`#41`; DevTools `state:render-chain-limit`), and the next write from outside renders normally. Drains chained by microtasks count — an element emitting in a microtask and an async `$renderedCallback` are cut too, and a `$stream` restart's writes count toward the chain; a pause between tasks ends it, so a write from a later task (a user action, a timer, an I/O event) starts afresh.
- **The binding grammar is machine-readable** — tooling-facing, never needed in app code: `@wcstack/state/manifest` (and `dist/wcs-manifest.json`) carries the vocabulary (modifiers, `$1..$N`, every binding type, the reserved `$` keys including `$behavior` / `$features`, `behaviorOptions`, `features`), and `@wcstack/state/parser` exposes the canonical binding parser (DOM-free and pure; invalid syntax throws) that the lint CLI, the VS Code extension and devtools consume.
- **Configuration — notation in `bootstrapState()`, behaviour in `$behavior`.**
  - `bootstrapState({ locale, bindAttributeName, tagNames: { state, ssr }, commentForPrefix, commentIfPrefix, commentElseIfPrefix, commentElsePrefix, enableContractAnalyzer })` — how the page spells the markup (the same on the server), the locale default, and the dev-time `analyzeContract()`. It checks every option before applying any and **throws** (`bootstrapState: "<key>" is not one of its options, or not of the option's type.`, `#44`) on an option it does not have (`enableMustache` / `sameValueGuard` / `enableDirectionalInitialSync` add `4.0 moved it to the state's $behavior.`; `debug` / `commentTextPrefix` / `enablePropagationContext` are gone), on a value whose type differs from the default (`null`, an array for an object), on an unknown `tagNames` name, and on a non-string tag name. An `undefined` value is skipped (`bootstrapState({ locale: maybeLocale })`). `/auto` passes none. `getConfig()` reads it.
  - **`$behavior: { enableMustache, sameValueGuard, enableDirectionalInitialSync }`** in the state — three booleans, each `true` by default: `{{ }}` text, the primitive same-value guard, direction-aware initial sync (needed by `#init=` / `#sync=`). It applies to the tree of the `<wcs-state>` that declares it, its volumes included; **each root state that needs it declares its own** — the page's root, a root `<wcs-state>` in a shadow root, a mounted component, a DCC — nothing is inherited from a host, and a volume cannot declare it. Unknown key or non-boolean → `#44`; not an object → `#44` (`state: "$behavior" …`); changing it on a re-set → `#45`. It works on `/auto` pages and in JSON states, and the server reads the same state under SSR. Lint: `wcs/behavior-invalid`.
  - **`$features`** — the add-ons a state needs (§1).
- **TypeScript**: Wrap with `defineState({...})` for `this` type completion (zero runtime cost; a bundle that imports only `defineState` or the types tree-shakes to almost nothing). Keys containing `**` (§14) are typed `any` through a pattern index signature — ordinary dot paths keep their resolved types, and the VS Code extension's preamble declares the same signature so the editor, `wcs-tsc` and `tsc` agree. `@wcstack/state` also exports the type `IStateElement`.
- **SSR**: `<wcs-state enable-ssr>` + `renderToString()` from `@wcstack/server` (`RenderOptions.timeoutMs`, 30 000 ms by default, `0` disables — keep it finite and ≤ 2 147 483 647). The server renders the page and writes `<wcs-ssr version>` (the state's data as JSON, plus the templates); the client **adopts** the server's rows and branches where they are (a custom element in them is connected once, never disconnected and re-connected), applies every binding, nested `for` / `if` included, and does not run `$connectedCallback` (the server ran it). Rules:
  - **Deploy `@wcstack/server` and the client at the same major.minor.** A snapshot of another major.minor — a 3.x server's output, say — is discarded with `<wcs-ssr version="3.5.0"> does not match 4.0.0: its snapshot is discarded, and the page renders on the client from its own state.`: the state loads from its own source, `$connectedCallback` runs on the client, and the page works, but the server's work is redone (output of a 3.x server up to 3.5.2 also loses the filters of page-level text bindings). A 4.0 server with a 3.x client is not supported. When you switch, purge HTML cached from the old version, and do not post-process the output based on its markers.
  - **Keep the comments in the output.** Text bindings and the row / branch markers are comments: removing them (html-minifier's `removeComments` and the like) breaks hydration, and `{{ }}` inside values may be read as bindings on the client.
  - **The snapshot is JSON**: `Date`, `Set`, `Map` and class instances do not survive it. Keep JSON values in SSR state and derive the rest in getters (`get created() { return new Date(this.createdIso); }`).
  - `outerHTML:` / `outerText:` are applied on the client only (the value is not in the HTML search engines and no-JS views see); children that a Light DOM custom element bound at page level renders from a value are rendered by the client; children you wrote stay in the output.
  - A server row that no longer matches its template is rendered again in its place (bound after insertion, unlike a client render); rows and branches the client does not render are removed once the page is bound. `<tr>` rows of a `<table>` written without `<tbody>` stay in the `<tbody>` the parser adds.
  - SSR never runs `$watch`, and streams stay at their initial value on the server.

## 12. Component mechanisms — DCC vs `bind-component` (they are exclusive)

Two mechanisms give a custom element its own state — pick one per component; combining them is an error, and putting `<wcs-state bind-component>` inside a `data-wc-definition` host is a misconfiguration (DCC state belongs to the template and is loaded per instance).

| | DCC (`data-wc-definition`) | `bind-component` |
|---|---|---|
| How the element is defined | HTML only (Declarative Shadow DOM) | your own `class extends HTMLElement` |
| Where the state lives | inline `<script type="module">` in the template, loaded per instance | a property on the component instance (`this.state`) |
| `static wcBindable` | generated from `$bindables` / `$commands` | **none** — it is not a wc-bindable producer |
| Bind a value from the parent | `count: parentCount` (two-way, with change events) | `state.msg: user.name` (path mapping) |
| Invoke a method from the parent | `command.bumpBy: $command.bump` | not possible — expose it on the class and call it yourself |
| Spread (`...: obj`) | works | does not work (needs a `wcBindable` declaration) |
| Read/write from inside | `this.count` on the element | `this.state.msg` |

Rule of thumb: **no JavaScript class → DCC; already writing a class → `bind-component`.** That `bind-component` stays outside the wc-bindable protocol is deliberate — it wires by *path*, not by a declared property surface, and losing spread and command tokens *into* it is the consequence. A DCC or a mounted component that needs a behaviour switch declares its own `$behavior` (nothing is inherited from the host).

### DCC: `$bindables` and `$commands`

```javascript
export default {
  count: 0,
  bumpBy(step) { this.count += step; },
  $bindables: ["count"],     // observable properties (+ my-counter:count-changed events)
  $commands: ["bumpBy"],     // invocable commands
};
```

```html
<button data-wcs="onclick: fire">bump</button>
<my-counter data-wcs="command.bumpBy: $command.bump"></my-counter>
<!-- parent state: $commandTokens: ["bump"], fire() { this.$command.bump.emit(3); } -->
```

- Positional arguments pass through verbatim, so `emit(3)` calls the component state's `bumpBy(3)`.
- Every `commands` entry is declared `async: true` — a DCC method chains onto the inner `<wcs-state>`'s initialization, so the return value is a Promise even when the state method is synchronous.
- Both declarations are validated at definition time with the same strictness as `$commandTokens`. Errors: not an array; a non-string or empty entry; an entry starting with `$`; a **duplicate entry**; a name that does not exist on the state (own properties and the prototype chain are both searched; `$stream` names count as existing); a method listed in `$bindables`, or a value property listed in `$commands`. A DCC definition that fails rejects its `connectedCallbackPromise`.
- Other DCC state keys: `$connectedCallback` / `$disconnectedCallback` / `$renderedCallback` run per instance.

### `bind-component`: whole-object mount — `state: path` (the default)

Instead of wiring property by property, mount a **whole subtree** of the host's state as the component's root; inside the component every path is then relative to the mount point:

```html
<!-- host: name inside the component IS user.name -->
<user-card data-wcs="state: user"></user-card>

<!-- in a loop, mount the row itself: inside, `name` is users.*.name,
     and the component's own `for: tags` runs over users.*.tags.* -->
<template data-wcs="for: users">
  <user-row data-wcs="state: ."></user-row>
</template>
```

- `state: user` mounts the component's root at tree path `user`. Reads, writes (`value: name`, `this.state.name = ...`), getters and `for:` all resolve against the tree; host-side `this.user = {...}` and `this["user.name"] = ...` both reach the component. `state: .` outside any `for:` is refused (`[wcs/wildcard-rank]` #1402).
- **Partial mounts coexist**: `state: user; state.theme: theme` — longest prefix wins, so `theme.mode` inside reads the tree's `theme.mode`. Duplicate inner paths throw at build. Only a one-segment entry marks a key mapped (`state.a.b: outer.b` leaves the rest of `a` private). A component's own **method** wins over a partial mount of the same name (a hidden entry is reported once as `[wcs/mount-own-key-shadow]`).
- **Own keys are private (rule R1)**: a data key the component declares itself (`state = { mode: "view" }`) belongs to the element and is never written to the tree. If it hides a key existing at the mount point, the runtime warns once (`wcs/mount-own-key-shadow`) — remove the default to read the tree, or rename to keep it private. Private-key updates never reach the root's `$renderedCallback`. **An explicit partial mount wins over the component's own key** — a default for a *mapped* key (`state = { message: "" }` next to `state.message: ...`) is unused.
- **`#ro` on a mount**: `state#ro: user` or `state.title#ro: doc.title` lets the component read but not write that entry — `element.state.title = …`, `this.title = …` in a method and `$setAll` / `$resolve` writes throw `[wcs/mount-readonly]`, and a two-way binding inside the component does not write back. The host still writes the path.
- **Mounting an array as the root is not supported** (`state: rows` with `for` over it inside) — mount the row (`state: .`) or the object holding the array (`state: group` + `for: children` inside).
- **No wildcard-terminal accessor over a mounted list**: `get "tags.*"()` on a mounted component raises — put the getter on the host tree, or over the component's own private array.
- `$getAll` / `$setAll` / `$resolve` / `$postUpdate` / `$eq*` / `$dependOn` on `element.state` (and on `this` inside getters and methods) speak the component's own vocabulary: paths are translated onto the mount and the host row's indexes are prepended automatically. A class-based component keeps its prototype accessors (a getter wins inside the component over a tree key of the same name).
- **The component's own code re-renders what it writes**: a method or setter body that writes a private key (`toggle() { this.mode = this.mode === "view" ? "edit" : "view"; }`) goes through the host's write path, also after an `await`. A method taken from `element.state` (`card.state.toggle()`) runs as it does from an event binding — writes re-render, a row mount's call lands on its own row, a synchronous method returns its value and an async one its Promise.
- **Components in a host `for:` row read and write their own row**, keep one set of private keys **per element** (an element write of the host row — `this["users.1"] = obj` — keeps the component element and its private keys), and their `$connectedCallback` / `$disconnectedCallback` read the element's current row. When the row is removed, `$disconnectedCallback` can still read and write the component's own keys (clear the timer id you kept in `this.tid`); reading the row's keys throws `The host row of <x-row> was removed.`, as does a method that resumes after an `await` once its row has left the list.
- **One mount scope per component**: a second `<wcs-state bind-component>` connected in one component rejects (`<tag> already has a connected <wcs-state bind-component="state">.`). A `<wcs-state bind-component>` with `state` / `src` / `json` or an inline script is refused (lint `wcs/bind-component-source`) — the host provides its data.
- **Replacing the component's `<wcs-state bind-component>`** while nodes the old one bound are still there: the new element takes the scope over, those bindings stay, and nodes with bindings added beside them are not bound (a `console.warn` says so). Render the content again with the new element for a fresh bind.

**Declarations in a mounted component (4.0):**

| Declared in a mounted component | 4.0 |
|---|---|
| `$listKeys` | runs on the component's own lists |
| `$commandTokens`, `$eventTokens`, `$on` | run, on the component's own bindings |
| `$errorCallback` | receives the failures of the component's own bindings |
| `$watch`, `$stream`, `$renderedCallback` | not run — one-time `[wcs/mount-dollar-declaration] <tag>: … is not run in a mounted component — declare it on the root state.` |
| `$recursion` | **throws** the same code |

**Exported getters — a component's derived values are readable at its mount point.** A read of a key the tree does **not** have is answered by the getter of the component mounted there; a key the tree *does* have wins (and warns once, `wcs/mount-export-shadowed`); **private data keys and methods are never visible** — R1 still holds, only accessors cross the boundary. With `<user-card data-wcs="state: user">` declaring `get display()`, the host binds `textContent: user.display`.

- **Row mounts export per row**: `$getAll("users.*.display")` on the host and `text: .display` inside the same `for` both read each row component's getter, and dependencies flow through — when `user.name` changes, everything that read `user.display` re-renders.
- **Only accessors whose exported path has the mount point's wildcard count are exported.** `get "children.*.label"()` works inside the component but is *not* exported — mount a component on each child row and give it `get label()`.
- **The parent evaluates before the child registers**, so a host expression's first read may see `undefined` and converges once the component mounts — write derived expressions defensively (`(x ?? 0)`). Binding-sourced missing-path warnings are deferred one macrotask for the same reason; with an autoloader an initial warning can still appear before the component registers even though the binding resolves.
- **Writing** to an exported key from outside runs the accessor's setter, or **throws** when it only has a getter (`#2`) — the tree never grows a key that would hide the getter. `in` does not see exported keys.
- Two components exporting the same key on one instance is a configuration error (`wcs/mount-export-ambiguous`).
- **Self-recursive components become expressible**: a `<tree-node>` that renders `<template data-wcs="for: children"><tree-node data-wcs="state: ."></tree-node></template>` inside itself can define `get total() { return this.value + this.$getAll("children.*.total").reduce((a, b) => a + (b ?? 0), 0); }` — each level's formula closes over one level and the ledger resolves the recursion. DevTools lists exported keys per mount record under `exports` in the Overlays section.

### `bind-component`: rendering the host's list inside the component

`<wcs-state bind-component="state">` goes inside the shadowRoot (or, for a Light DOM component, as a direct child); the host writes `data-wcs="state.message: user.name"`. An array can be bound across the boundary and iterated **inside** the component:

```html
<!-- host -->
<my-list data-wcs="state.items: rows"></my-list>
```
```javascript
// component shadow
this.shadowRoot.innerHTML = `
  <wcs-state bind-component="state"></wcs-state>
  <ul><template data-wcs="for: items">
    <li data-wcs="textContent: .name"></li>
  </template></ul>`;
```

The outer state stays the source of truth: replacing `rows` wholesale, or writing a single row field (`rows.0.name`), both reach the component's rows, and writing `items.*.name` back from inside reaches the host's `rows`. Components stack to arbitrary depth: the base list index composes across every boundary, and an intermediate component that only passes the array through still delivers a row-field write to the rows at the bottom. Loop indexes stay **scope-local**: `$1`, event-handler indexes, `$renderedCallback` and `$getAll` all report the position within the component's own scope.

### `bind-component` in Light DOM

A Light DOM component is written exactly like the Shadow one — `<wcs-state bind-component="state"></wcs-state>` as a direct child. Scope is decided by position in the DOM, so the same Light DOM component can sit on every row of a `for`.

- **The host must wire it.** A plain, unwired Light DOM `bind-component` fails loudly with the fix — an independent tree cannot share the parent's root: add `attachShadow`, or mount it from the host (`state: user` / `state.message: user.name`).
- Inside a Light DOM mounted component, delegated `on*:` handlers run at the **host element** (`event.currentTarget` is the host — §8).
- **`getBindingsReady(root)` covers mounted scopes** once the mount record resolves. Await the component's own `<wcs-state>` when you specifically need its contents rendered.

### Your own `static wcBindable` element: what the two-way binding writes back

A third option is a hand-written class that declares `static wcBindable` itself (it then gets spread, command tokens and event tokens like an I/O node). The one rule that is easy to miss: when the element dispatches `properties[].event`, the value written to state is **`getter(event)`**, and with no `getter` the wc-bindable default is **`(e) => e.detail` — the whole `detail`, as-is**. The declared property is *not* read off the element at that moment (only the initial sync reads it). Dispatching `detail: { value: 7 }` without a `getter` therefore writes the object `{ value: 7 }` to state and the write-back becomes `NaN`. `@wcstack/lint` cannot see it (the payload shape is not static); the runtime warns once per element and property (`wcs/default-getter-mismatch`) for the two shapes it can tell apart at the event — a `detail` that is `undefined` while the element property has a value, and a `detail` object carrying a `<propName>` key while the property is not an object. Any other mismatch still goes through unnoticed, and occurrence properties (`semantics: "event"`) are exempt. Use one of the two conforming shapes:

```javascript
class YenInput extends HTMLElement {
  static wcBindable = {
    protocol: "wc-bindable", version: 1,
    properties: [
      { name: "value", event: "yen-input:value-changed" },                                   // (a) detail IS the value
      // { name: "value", event: "yen-input:value-changed", getter: (e) => e.detail.value }, // (b) detail is an object
      // { name: "value", event: "input",                  getter: (e) => e.target.value },  // (b) reusing a DOM event
    ],
    inputs: [{ name: "value" }],   // declare settable members in BOTH lists (§3 modifiers table, `#init=`)
  };
  #onInput() {
    this.dispatchEvent(new CustomEvent("yen-input:value-changed", { detail: this.value, bubbles: true }));
  }
}
```

**Attributes are yours to reflect.** State writes an input's property only. An `inputs` entry's `attribute` (`{ name: "active", attribute: "active" }`) just names the markup attribute for tooling — state never writes it. If CSS, `attributeChangedCallback` or DevTools should see the value on the attribute, reflect it in the setter with the encoding your element reads: `set active(v) { this.toggleAttribute("active", Boolean(v)); }` for a flag read with `hasAttribute`, `this.setAttribute("limiter", v ? "on" : "off")` for one that is on unless `"off"`. An element that only listens to `attributeChangedCallback` and has no setter will not see state's writes.

Keep `element.value` and the extracted event value the same logical state (initial sync reads the property, later updates read the event). Do not expect the default to change: it is normative for every wc-bindable adapter, and DCC's `$bindables` reading `e.target[name]` is a producer-side `getter` choice, not a different default. A custom element that dispatches a delegated event type (`click`, `input`, …) with `bubbles: false` is heard on the element itself.

## 13. Testing the page headlessly

A `<wcs-state>` page is plain DOM, so it tests under vitest + happy-dom with no browser and no test-only API. The one-import form is **`@wcstack/testing`** (`npm i -D @wcstack/testing @wcstack/state @wcstack/server vitest happy-dom` — state and server are peers):

```javascript
import { mount, settle, fire } from "@wcstack/testing";

const app = await mount(`
  <wcs-state json='{"count": 1}'></wcs-state>
  <p data-wcs="textContent: count"></p>
  <button data-wcs="onclick: up">+1</button>
`);                                                     // registers elements, waits for router + bindings
expect(app.root.querySelector("p").textContent).toBe("1");
await app.state().write((s) => { s.count = 42; });      // what a handler does
await settle();
fire(app.root.querySelector("button"), "click");        // what a user does (bubbles to the delegated root listener)
await settle();
app.unmount();
```

`mount(html, { root: "shadow", bootstrap: [async () => (await import("@wcstack/router")).bootstrapRouter()] })` scopes bindings to a fresh shadow root and registers additional packages. The bare recipe (no `@wcstack/testing`): `URL.createObjectURL = undefined` in setup (Node cannot import `blob:` URLs, so this reroutes inline `<script type="module">` state through the `data:` loader — without it an inline state never finishes loading), and `await stateEl.connectedCallbackPromise` then `await getBindingsReady(document)` before asserting. Writes go through `stateEl.createStateAsync("writable", async (state) => {...})`. Dispatch synthetic events with `bubbles: true` (`new Event("input", { bubbles: true })`; `fire()` and `el.click()` do) — a non-bubbling `click` / `input` never reaches a delegated `on*:` handler on the root (two-way bindings listen on the element itself).

- **A state that fails to initialize fails the test**: `connectedCallbackPromise` rejects with the error, so `mount()`, `renderToString()` and `getBindingsReady(root)` reject with the cause (§11).
- **Snapshot**: `expect(await renderToString(html)).toMatchSnapshot()` — `renderToString` from `@wcstack/server`.
- **Bare Node (no vitest)**: `const restore = installGlobals(new Window({ url: "http://localhost/" }))` from `@wcstack/server`, then **dynamic-import `@wcstack/state` after it** (a static import at the top of the file registers elements happy-dom cannot construct), run the same steps, `restore()`.
- **Blind spots that still need one browser e2e** (Playwright): happy-dom replaces nodes on a late `customElements.define`, and its event timing differs from real browsers.

## 14. Recursive paths — `$recursion` and `**`

A path burns its depth into the string: `nodes.*.children.*.total` is depth 2 and nothing stretches it to 3 when the tree grows a level. `$recursion` declares **where the shape repeats**, and `**` means "however deep this is", so one getter covers every depth.

```javascript
export default {
  $recursion: { "nodes.*": "children.*" },        // anchor → repeating sub-path

  nodes: [ { value: 1, selected: false, children: [ /* …same shape… */ ] } ],

  // One getter, every depth. `**` is bound to the depth being evaluated.
  get "nodes.**.total"() {
    return this["nodes.**.value"]
         + this.$getAll("nodes.**.children.*.total").reduce((a, b) => a + b, 0);  // indexes omitted = this depth
  },
  get treeTotal() {                                // `[]` = union of every depth
    return this.$getAll("nodes.**.value", []).reduce((a, b) => a + b, 0);
  },
  clearSelection() { this.$setAll("nodes.**.selected", [], false); },
};
```

**`**` is authoring notation only — it never reaches the engine.** Reading a concrete path (`nodes.*.children.*.total`) materializes the getter for *that* depth on demand, and everything downstream — the dependency graph, `$1`…`$n`, `$resolve`, the list diff — still sees an ordinary fixed-arity path. On `/core` install `features/recursion`.

### Declaring the recursion point

`$recursion` maps one **anchor** to the **repeating sub-path** one level down. Both name the *element* of a list: a fixed property chain ending in `.*`, never the list itself, and never carrying an index segment (`"nodes.0.items.*"` is refused — the recursion is over the shape of the tree, not one row).

```javascript
$recursion: { "nodes.*": "children.*" }     // nodes[i].children[j].children[k]…
$recursion: { "data.tree.*": "kids.*" }     // a deeper anchor is fine
$recursion: { "nodes.*": "nodes.*" }        // self-similar spelling is fine too
```

The declaration is what gives `**` a meaning at all — with no `$recursion`, `**` is not a path character (`wcs/recursion-unsupported`), so it can never quietly become a descendant search. **Exactly one self-recursive anchor per state**, and it is **root-only**: a volume (`mount=`) declaring `$recursion` or a `**` getter is not grafted, and a mounted `bind-component` scope declaring `$recursion` throws `[wcs/mount-dollar-declaration]`.

### What `**` means where — bound vs union

| Where `**` appears | What it means |
|---|---|
| A getter key — `get "nodes.**.total"()` | Bound to the depth being evaluated |
| A path read inside that getter — `this["nodes.**.value"]` | Bound to the same depth |
| `$getAll(path)`, indexes **omitted** | Bound to that depth; only the wildcards *after* `**` expand |
| `$getAll(path, [])`, **explicit** | **Union of every depth** — depth-first, pre-order, ascending index |
| `$getAll(path, [i, …])` | Refused: a prefix cannot say which depth it applies to (`wcs/recursion-getall-form`) |
| `$setAll(path, [], value)` | Broadcast to every depth, same order |
| `$resolve` / `$postUpdate` / `$dependOn`, `$watch` and `$listKeys` keys, `data-wcs` markup, direct assignment | Refused (`wcs/recursion-unsupported`) |

The **bound** forms need a depth to bind to, so they resolve only **inside** a recursive getter, an ordinary row getter under the anchor, or an event handler bound to such a row. Read `this["nodes.**.value"]` at the top level and you get `wcs/recursion-context`, not a guess. The depth comes from the **innermost evaluation frame only**: a plain getter that a recursive getter calls has no row of its own and gets `wcs/recursion-context` too — read `**` in the recursive getter and pass the value on. The **union** form needs no depth and can be read anywhere.

### Aggregating without counting grandchildren twice

```javascript
get "nodes.**.total"() {                                        // ✅ omitted → direct children only
  return this["nodes.**.value"] + this.$getAll("nodes.**.children.*.total").reduce((a, b) => a + b, 0);
}
get "nodes.**.total"() {                                        // ❌ `[]` → every depth; the getter asks for itself
  return this["nodes.**.value"] + this.$getAll("nodes.**.children.*.total", []).reduce((a, b) => a + b, 0);
}                                                               //    in practice: wcs/getter-cycle
get treeTotalWrong() { return this.$getAll("nodes.**.total", []).reduce((a, b) => a + b, 0); }   // ❌ too big, silently
get treeTotal()      { return this.$getAll("nodes.**.value", []).reduce((a, b) => a + b, 0); }   // ✅ union raw values
get treeFromRoots()  { return this.$getAll("nodes.*.total",  []).reduce((a, b) => a + b, 0); }   // ✅ or sum the roots
```

**Union raw values, or sum the roots — never union something that already aggregates its own subtree.** Whether an aggregate double-counts is not decidable from the path string, so **no diagnostic catches this one**.

### Writing: broadcast only

`$setAll` takes `**` in exactly one form — `[]` plus a plain value — and returns the number of addresses written. Every other form is refused *before* the walk writes anything:

| Refused form | Why |
|---|---|
| a non-empty prefix | A prefix cannot say which depth it applies to (`wcs/recursion-setall-form`) |
| omitted indexes | The write API takes no evaluation context, so there is no depth to bind — `[]` is mandatory |
| a mapper function | `(current, ...indexes)` has a different arity at every depth |
| `{ spread: true }` | Handing a flat array to a tree needs the author to know the walk order |
| the structure itself — `nodes.**`, `.children`, `.children.*`, `.children.length`, `nodes.**.children.0`, and (multi-segment repeat) the object on the way to the list | Writing it invalidates the child addresses this very write already resolved (`wcs/recursion-structural-write`) |
| `nodes.**.total` or a path inside its value | A recursive getter has no setter (`wcs/recursion-readonly`) |

**The read-only rule does not depend on spelling `**`.** A recursive getter's concrete expansions — `nodes.*.total`, `nodes.*.children.*.total`, `nodes.1.total` — are refused at the write entry too, whether the write is a fixed-arity `$setAll`, a `$resolve(path, indexes, value)` or a direct assignment.

### The input has to be a tree

The walk refuses reaching the **same array instance** twice: from an ancestor it is `wcs/recursion-cycle`, otherwise two nodes share one child list (`wcs/recursion-shared-list`). Give every node its own `children` array — sharing an *empty* one is fine. The ceiling is **128 wildcard levels** (`wcs/recursion-depth-exceeded`); it trips before the getter stack's own 128-frame limit (`wcs/getter-depth-exceeded`), so a deep tree is reported as deep instead of accused of a cycle. Nothing is truncated. Replacing row objects while keeping their `children` arrays (`this.nodes = this.nodes.map(n => ({ ...n }))`) keeps the child rows and their aggregates live.

### Rendering the tree

`**` cannot appear in markup and there is no recursive `<template>`. A tree is drawn by a **self-referential component** — one custom element whose shadow mounts itself for each child, so only one level of path is ever used inside a scope (`node.children.*`) and `node.total` resolves through the mount onto the root state's recursive getter.

```html
<template data-wcs="for: nodes"><tree-node data-wcs="state: ."></tree-node></template>
```
```javascript
const TEMPLATE = `
  <wcs-state bind-component="state"></wcs-state>
  <span data-wcs="textContent: label"></span><span data-wcs="textContent: total"></span>
  <button data-wcs="onclick: addChild">+ child</button>
  <template data-wcs="for: children"><tree-node data-wcs="state: ."></tree-node></template>`;

customElements.define("tree-node", class extends HTMLElement {
  state = {                     // ← methods only: `label` / `value` / `children` come from the mount
    addChild() { this.children = [...this.children, { label: "new", value: 5, children: [] }]; },
  };
  constructor() { super(); this.attachShadow({ mode: "open" }); }
  connectedCallback() {                         // ← build the shadow HERE, not in the constructor
    if (this.shadowRoot.childNodes.length === 0) this.shadowRoot.innerHTML = TEMPLATE;
  }
});
```

Two traps, both quiet:

- **The component's `state` must not declare the keys it is mounted over.** Methods and unrelated private keys are fine; a `node` / `children` of its own is not — an own key is private (rule R1, §12), so it hides the mount and the child renders its own default and never descends. The runtime names this one: `wcs/mount-own-key-shadow`.
- **Build the shadow in `connectedCallback`, not the constructor.** Assigning `innerHTML` in the constructor upgrades the elements inside `<template>` on implementations that do not keep template content inert, and a self-referential element then recurses forever in its own constructor.

Fixed depths need none of this: expanded paths are ordinary paths, so nested `for` templates bind `nodes.*.total` like anything else. Working demo: `packages/state/examples/recursive-tree/`.

### Not in this version (each is a diagnostic, never a reinterpretation)

More than one anchor, mutual recursion, a wildcard mid-anchor, a second `**` in one path; recursive **setters**; a `**` getter whose suffix names the structure (`get "nodes.**.children"()`, `.children.*`, `.children.length`); two `**` getters expanding to the same concrete path; a concrete getter with the same name as an expansion (`get "nodes.*.children.*.total"()`); `get "nodes.**"` (that names the node itself); a recursive `<template>`, a `$depth` variable, and a public `maxDepth` option.

**Diagnostics.** `wcs-validate` and the VS Code extension report every statically decidable form under the same codes and stay silent where the declaration cannot be read statically (an identifier reference, a spread, a computed key, a `class` state). **Runtime-only**: `wcs/recursion-context`, `wcs/recursion-shared-list`, `wcs/recursion-cycle`, `wcs/recursion-depth-exceeded`, plus `wcs/getter-depth-exceeded`.

## 15. Accumulation over time — a key you own, folded in `$watch` / `$on`

A getter derives from *current* values; a `$stream` `fold` accumulates *within one run* and resets to `initial` on every restart. A value that has to outlive both — a feed across page runs, a log across events — is **an ordinary state key you seed and write from a handler**: a `$watch` handler for the landings of a state path, an `$on` handler for the events of a token. (There is no `$scan`; rewriting a 3.x one: §16.)

```javascript
export default {
  page: 1,
  pageSize: 20,
  host: "a.example",
  feed: { items: [], pages: [] },              // seeded, owned by you
  log: [],
  $eventTokens: ["message"],
  $stream: { pageResult: { args: (s) => ({ page: s.page, pageSize: s.pageSize }), source: loadPage } },
  // loadPage(args, signal): your async generator, yielding { kind: "success", page, items } per page
  $watch: {
    pageResult(chunk) {                        // one call per landing of the stream's value
      if (chunk?.kind !== "success" || this.feed.pages.includes(chunk.page)) return;   // progress chunks / page key
      this.feed = { items: this.feed.items.concat(chunk.items), pages: [...this.feed.pages, chunk.page] };
    },
    host() { this.log = []; },                 // a reset: write the seed back
  },
  $on: {
    message: (state, event) => { state.log = [...state.log.slice(-49), event.detail]; },   // bounded
  },
};
```
```html
<template data-wcs="for: feed.items"><li data-wcs="textContent: .name"></li></template>
<wcs-sse url="/events" data-wcs="eventToken.message: message"></wcs-sse>
```

- **Once per landing, not once per page.** Each stream chunk is a new object and lands in its own batch, so the watch fires on every landing; a Retry after a page is `done`, or a re-attached state element (the stream restarts on the current page), lands the same page again — keep an idempotency key in the feed.
- **Never derive the stream's `args` from the feed** — directly or through a getter. It restarts the stream on its own result and loads every page with no sentinel. Keep the cursor a plain property and advance it from an event (`$on: { sentinelChanged: (s) => { s.page = Math.floor(s.feed.items.length / s.pageSize) + 1; } }`).
- **Count occurrences on the event surface.** An equal primitive write never lands (the same-value guard), so a `$watch` on a bound element output (`loading`) misses a `true → true`; fold the token (`eventToken.loading: requestStarted` + `$on`).
- **Write only when the fold produced something new**: a plain write of an unchanged object passes the same-value guard (it skips primitives only) and re-fires every `$watch` and binding on it.
- If the state already has a `$watch` / `$on` handler for that path or token, merge the fold into it: in an object literal a later key silently replaces the earlier one.
- Keep the accumulation bounded (`slice(-49)`, a count) — there is no backpressure.
- **Order**: the handler's write lands in the next batch; a `$watch` on the output (`feed(feed) { … }`, e.g. re-arming a sentinel) fires at the end of that batch, after its rows have rendered (without a `<wcs-view-transition>` accepting `state`; with one, bindings apply on a frame and the `$watch` runs first — §10). A reset written from a `$watch` happens at the end of the batch, not at the moment of the triggering write.
- The output is plain state: a re-set (`setInitialState`) replaces it like any other key, and SSR never runs the watch.

Working demo: `examples/state-intersect-scroll/` (its feed).

## 16. If you meet 3.x code

4.0 keeps the markup and the `$` APIs, so most 3.x pages need only the rows below. The path for an existing page is the one in the wcstack repo's `docs/migration-v4.md`: pin the CDN major (`https://esm.run/@wcstack/state@3/auto`), move every package to 3.5 and clear its `[wcs/v4-migration]` console warnings and `wcs/v4-migration` lint infos (all but those for the three options that move to `$behavior`), then move every package — `@wcstack/server` together with the client — to 4.0 at once. Use `@wcstack/lint@3.5` and the VS Code extension 1.21.x on 3.x projects: the 4.0 rules report forms 3.x accepts. Code older than 3.0 (a second `#`, a value after `else:`, unquoted `eq(true)` compared as text, `<wcs-state name>`): `docs/migration-v3.md` first — 4.0 rejects those forms as 3.0 did.

| 3.x form | In 4.0 | Write instead |
|---|---|---|
| Filters `inc` `dec` `fix` `uc` `lc` `cap` `rep` `rev` `pad` `null` | `[wcs/filter-unknown]` #501 at initialization (lint: warning naming the replacement) | `add` `sub` `toFixed` `upper` `lower` `capitalize` `repeat` `reverse` `padStart` `nullIfEmpty` |
| `substr(start, length)` | #501 | `slice(start, start + length)` — a negative start counts from the end in both, but the end differs: check those by hand |
| `this.$trackDependency` / `this.$untrackDependency` | throws when read (`[wcs/name-alias]` #1701) | `$dependOn` / `$untracked` |
| `$updatedCallback` / `$streams` declared | throws when the state loads (`[wcs/declaration-alias]` #1601); reading `this.$streams` is `undefined` (lint `wcs/declaration-alias-read`) | `$renderedCallback` / `$stream` |
| `$scan: { out: { from: "path", initial, fold } }` | throws when the state loads (`$scan was removed (use $watch or $on)`, #1; lint `wcs/scan-declaration-invalid`) | `out: initial` as a key, and `$watch: { path(cur, prev, ...i) { const next = fold(this.out, cur, prev, ...i); if (next !== this.out) this.out = next; } }` |
| `$scan: { out: { on: "token", initial, fold } }` | same | `out: initial`, and `$on: { token: (state, e, ...i) => { const next = fold(state.out, e, ...i); if (next !== state.out) state.out = next; } }` |
| `resetOn: ["p"]` in a `$scan` entry | same | `$watch: { p() { this.out = /* a fresh copy of initial */ []; } }` — declared **after** the fold handler when the reset must win; the reset happens at the end of the batch |
| `bootstrapState({ enableMustache, sameValueGuard, enableDirectionalInitialSync })` | throws `#44` (`4.0 moved it to the state's $behavior.`) | `$behavior: { … }` in **each** root state that needs it (a 3.x option covered the whole page) |
| `bootstrapState({ debug, commentTextPrefix, enablePropagationContext })` | throws `#44` | Remove them; rewrite comment bindings that used a custom keyword as `<!--@@: path-->` / `<!--@@wcs-text: path-->` |
| An unknown option or a wrong-typed value in any `bootstrapXxx(config)`; the autoloader's `scanImportmap` | throws (3.x ignored it, 3.5 warned) | Remove or fix it — `/auto` passes no options |
| `event.currentTarget` in an `on*:` handler of `click` / `dblclick` / `input` / `change` / `submit` / key / mouse / pointer down and up | the root (lint `wcs/delegated-current-target`) | `event.target.closest(…)`, the loop index, or `on*#direct:` (§8) |
| `#stop` meant to stop your own ancestor listeners; inner handlers expected to run when an ancestor calls `stopPropagation()`; handlers on elements moved under another root | no longer so (nothing reports it) | `on*#direct:` on those bindings |
| Reordering rows by writing list elements (`$resolve("items.*", [0], b)`, `this["items.0"] = c`) | replaces the value at the position; rows do not move | Assign a new array (§4) |
| `for: items\|filter(…)` | `[wcs/binding-syntax]` #121 | A getter returning the filtered list (§4) |
| `outerHTML:` / `outerText:` inside `for:` / `if:` templates | `[wcs/template-syntax]` #203 | `innerHTML:` on a wrapper element |
| `{{ b.*.y }}` inside `for: a` | `[wcs/wildcard-rank]` #1403 | A getter reading the other row with `$resolve(path, indexes)` |
| A volume with `$watch` / `$listKeys` / `$renderedCallback` (they ran relative to the mount path) | volume not grafted (`console.error`) | The root state with full paths (`"cart.total"`); filter the root `$renderedCallback`'s paths by the `cart.` prefix |
| A volume injection (`<wcs-state mount="cart" data-wcs="state.taxRate: settings.taxRate">`) | volume not grafted | A root getter reading both paths |
| `$listKeys` / tokens / `$on` / `$errorCallback` in a mounted component (3.x ignored them with a warning) | they run, on the component's own lists and bindings | Keep them if that is what you meant; move them to the root otherwise |
| CSS / test selectors `[data-wcs…]` on row or branch elements | no longer match | A class or a `data-*` attribute |
| A custom element that relied on state writing its input attributes (no setter, or reads inputs only in `attributeChangedCallback`; CSS on `[active="false"]`) | state writes the property only — 3.x also wrote the attribute (`String(value)`) | Reflect in the setter, with the element's own encoding |
| `$watch("items.0.v")` relied on to fire on any row write | fires only when that value changes | — |
| `$watch("items.*.x")` with `$listKeys` added only so the watch fires headless | not needed (row watches are headless); keep `$listKeys` for refetched rows | — |
| A `/core` page using `$listKeys` | `[wcs/feature-not-installed]` | `installFeatures([listKeys])` from `@wcstack/state/features/list-keys` |
| Children inside a `textContent:` / `innerHTML:` element, `<noscript>` / `<iframe>` content, comment bindings inside `<textarea>` / `<title>` | not bound | Separate elements (§3) |
| Output of a 3.x `@wcstack/server` in front of a 4.0 client | snapshot discarded, client render | Deploy server and client together; purge cached 3.x HTML; keep `--` out of text-binding expressions while a 3.x server renders |
| `IStateElement.listPaths` / `getterPaths` / `setterPaths` / `nextVersion()` | removed | — |

What a 3.x page shows that a 4.0 one does not: `[wcs/v4-migration]` console warnings (3.5, full entries only) and `wcs/v4-migration` / `wcs/name-alias` lint infos — each names the 4.0 form in the table above. Workarounds for 3.x bugs (`$postUpdate("mode")` after a mounted component's private-key write, keeping two `for:`s mounted and toggling `hidden`, `this.items.with(…)` instead of an index write on an unrendered list, a wrapper element only to make a top-level route template render) still work in 4.0 and can be dropped.

## Pitfall Checklist

1. The runtime does not observe `this.user.name = "Bob"` — always use `this["user.name"] = "Bob"`; lint reports `wcs/nested-assign` (error).
2. The runtime does not observe destructive array methods or direct index assignment — reassign a new array, use `this["items.0"] = value`, or `this.items = this.items.with(0, value)`; lint reports `wcs/array-mutation` / `wcs/array-index-assign` (errors — `wcs-validate` exits `1`; fix the assignments, not the gate).
3. `onclick:` cannot take arguments — use zero-argument wrapper methods, or read the loop index argument.
4. The `for:` path must be an array — while the fetch `value` is null, interpose a `?? []` derived getter. `for:` takes no filters (#121): loop over a getter that returns the filtered list.
5. Bare names on the command binding right side throw (#1201) — `$command.fetchUsers` is required.
6. The `eventToken.` key is the wcBindable **property name**, not the raw DOM event name.
7. `wcs-fetch:response` (the value event) also fires on HTTP/network errors — check the status in `$on`.
8. Do not seed convenient initial values into output-only wcBindable members (the element's real initial value replaces them).
9. `$stream` sources must not ignore AbortSignal (ReadableStream sources satisfy this automatically via `cancel()`; only hand-written async iterables must watch `signal`).
10. Do not forget the trailing colon on `else:`.
11. Duplicate entries in `$commandTokens`/`$eventTokens` and undeclared keys in `$on` are initialization-time errors. Accessing an undeclared token in script (`this.$command.typo`) yields `undefined`; in markup it throws `[wcs/token-undeclared]`.
12. There is no public filter registration API — do transformations the 47 built-ins cannot express in a getter. The 3.x short names and `substr` are gone (§16).
13. The only valid separator for multiple bindings in `data-wcs` is `;`.
14. A property binding is same-value guarded: an `Object.is`-equal primitive write is skipped entirely (no dependency walk, no DOM apply, no `$renderedCallback`). Take repetition from the event-token surface — or from an I/O-node property declared `semantics: "event"`, which is exempt.
15. `$on` handlers are never awaited. An async handler's rejection is reported via `console.error`, not propagated — do not sequence work on it.
16. Under a strict CSP the default state form (inner `<script type="module">`) is blocked unless the `<script>` that loads state carries the page nonce — it is imported through a `blob:` URL, and that import inherits the loading tag's nonce. Where no nonce can be issued, move the state to `src="./state.js"` (preferred under a strict CSP either way), or open `script-src blob:` knowingly. The browser also evaluates that inner module itself, so its top-level code can run twice — keep side effects out of it (§2).
17. `$renderedCallback` reports only paths whose live DOM bindings were applied. It is not a headless watcher; an unbound write never reaches it — declare `$watch` (§10) for that.
18. A `$listKeys` key is the **list path itself** — `"items"` or the nested `"items.*.children"`, never a path ending in `*`. Rows must be plain objects with keys that exist and are unique; a duplicate/missing key or a class instance raises. Remember `this.items !== theArrayYouAssigned` afterwards. On `/core` it needs `features/list-keys`.
19. DCC and `bind-component` are mutually exclusive per component; a duplicate entry in `$bindables` / `$commands` is an error.
20. `getBindingsReady(root)` resolves when the root's bindings are built (also when `$connectedCallback` then fails) and rejects only when every `<wcs-state>` on that root failed before building them — handle the rejection if you `await` it. It covers mounted scopes once the mount record resolves; await the component's own `<wcs-state>` when its contents specifically matter.
21. `$watch` keys are root-scope paths only: no `@`, no `$`-prefix, no `**`. To react to `$streamStatus.<name>`, mirror it through a non-`$` getter and watch that (a watched getter turns eager, so it evaluates even unrendered).
22. Row watches are headless (no `for` or `$listKeys` needed). A whole-array assignment fires only the rows that entered the list, with `prev` undefined — after a `fetch().json()` refresh that is every row, unless `$listKeys` turns it into per-field writes.
23. `$watch` handler exceptions are isolated (console + devtools, remaining watches still run), write chains are cut at 32 links (counted per write; only the handlers those writes fired are skipped), and SSR never runs watches. A **mounted** `bind-component` scope does not run `$watch` / `$stream` / `$renderedCallback` (one warning); a volume declaring them is not grafted.
24. A structural binding (`for` / `if` / `elseif` / `else`) must be alone in its `data-wcs` (#201) — at page level the whole `<wcs-state>` then fails to initialize.
25. A `[wcs/...]`-prefixed runtime error means the lint CLI reproduces the same finding with a source range — run `npx @wcstack/lint` and fix every instance, not just the throwing one. A `#<number>` without a sentence means the page runs `/core` without `features/diagnostics` (`docs/state-errors.md`).
26. Getters read only through `this` — an untracked read (`Date.now()`, the DOM, a module variable) keeps its first value forever. State the input as state, or use `$dependOn` / `$postUpdate`.
27. `$resolve` requires the index count to match the path's `*` count exactly; `$getAll` treats it as an upper bound. Surplus indexes throw `wcs/index-arity`. Two arguments read, three write.
28. Writing a top-level key the state does not declare creates it — a write typo is silent. Declare every key; `defineState` / `wcs-tsc` catch the typo.
29. The filters' default locale is `<html lang>`, read when state is evaluated — a page that omits `lang` formats in English, and changing the locale after render updates nothing. Set `<html lang>` in the markup.
30. `$setAll` broadcasts arrays by default — replacing each row with successive entries needs `{ spread: true }` (length mismatch throws). `undefined` from a mapper means "skip this row", never "write undefined". Omitted `$getAll` indexes default to the **loop context** — inside a `for`-scoped getter that narrows to the current row; pass `[]` explicitly for "every match".
31. A `stateSchema` in the nearest `wcstack.manifest.json` (generated by `wcs-schema emit src/state.ts`, or hand-written) turns a missing path into `wcs/path-nonexistent` (**error**) and `for:` on a non-array into `wcs/path-type-mismatch` — the discovery walks up from the HTML file, and an explicit manifest argument replaces discovery for the whole run. It carries a single `stateSchema` (one tree per root); a volume contributes a subtree via `--mount=<path>`. Paths under a bare `{}` stay silent; methods, getters and `$listKeys` from the inline script still count, and so do row fields the analyzer reads from `concat({ … })` / `toSpliced` / `with` / spread-array assignments. Gate CI with `wcs-schema check` and regenerate with `emit --merge` after changing the state type.
32. One tree per rootNode: split modules with `mount=` (§2), hand a component a subtree with `state: path` (§12). `name=` / `@name` are gone (`wcs/named-state-deprecated`, error).
33. Mount rules (`state: path`): an array cannot be the mount root — mount the row (`state: .`) or the object holding it. An own key that shadows a mount-point key stays **private and hides the tree value** (rule R1, `wcs/mount-own-key-shadow`); an explicit partial mount beats a default of the same name. One `<wcs-state bind-component>` per component; a wildcard-terminal accessor (`get "tags.*"()`) over a mounted list raises. The component's **getters are exported** at the mount point — private data keys and methods are not; a tree key of the same name wins (`wcs/mount-export-shadowed`); the first host read may be `undefined` until the component registers, so write `(x ?? 0)`.
34. `wcs-validate --strict` exits `1` on **warnings** too. It is the way to make a path typo (`wcs/binding-path-missing`), a removed filter name (`wcs/filter-unknown`) or a wildcard-rank warning — all of which the runtime throws on or drops — fail CI; run it once every `<wcs-state src>` resolves, and expect the false warnings on paths of a volume loaded with `src=`.
35. The **root `<wcs-state>` is required** — a page with only `mount=` volumes is a loud error. `mount` must be a static dotted path; `*` / `$` / `#` / `@` / empty segments are refused and lint as `wcs/mount-path-invalid`. A volume on a path the root already has is not grafted; writing a mount point's parent wholesale from the root throws.
36. `setInitialState()` cannot re-set a tree that already has volumes or mounts on it, cannot re-set a `mount=` volume element itself, and may not change `$behavior` (#45). Write the individual paths, on the root state. Re-setting a plain initialized tree re-renders the page (§11) — hand it a new array when a list changed.
37. A volume (`<wcs-state mount>`) hosts data, getters, methods and the connected/disconnected callbacks **relative to its mount path**. `$watch` / `$listKeys` / `$renderedCallback` / `$stream` / `$recursion` / `$behavior` / `$features` or an injection on the element → the volume is **not grafted** (`console.error`); tokens, `$on` and `$errorCallback` → not run (`console.warn`). Declare them on the root state with full paths.
38. On your own `static wcBindable` element, a two-way binding writes **`getter(event)`** to state, defaulting to the whole **`e.detail`** — never `element[propName]`. Dispatch the value itself as `detail`, or declare `getter: (e) => e.detail.value` / `(e) => e.target.value` (§12).
39. A binding that throws while applying is **isolated and reported to `console.error`** — that node stays stale, nothing else is rolled back. Declare `$errorCallback(error, { path, bindingType, node })` on the **root** state (a mounted component's covers its own bindings; a volume's is not run) to route the report in-page. It does not cover `$watch` handlers or `$connectedCallback` / `$renderedCallback` exceptions.
40. `this.form.name` inside a getter tracks **`form` only** — read `this["form.name"]`; `wcs-validate` / VS Code report `wcs/getter-untracked-read`. Reads inside a setter are never tracked, and the same-value guard skips primitives only (§6).
41. Under `require-trusted-types-for 'script'` the `html:` / `innerHTML:` bindings and `<wcs-fetch target>` need a sanitizing policy you install, and `<wcs-layout>` / `<wcs-worker>` need `trusted-types wcstack` in the CSP (§2).
42. `**` (§14) is **authoring notation for the state definition only** — refused in markup, `$watch` / `$listKeys` keys, `$resolve` / `$postUpdate` / `$dependOn` and assignments (`wcs/recursion-unsupported`), and meaningless without `$recursion`.
43. **Unioning an aggregate double-counts, and nothing catches it.** `$getAll("nodes.**.total", [])` adds every node's total, each of which already folds its own subtree. Union raw values (`nodes.**.value`) or sum the roots (`nodes.*.total`).
44. A **bound** `**` reads its depth from the innermost evaluation frame only — from the top level, or from a plain getter a recursive getter calls, it is `wcs/recursion-context`.
45. A recursive `$setAll` takes **`[]` plus a plain value** and nothing else, and may not target the structure or a recursive getter (read-only at every spelling — `wcs/recursion-readonly`).
46. The recursion input must be a **tree** (`wcs/recursion-shared-list` / `wcs/recursion-cycle`), 128 wildcard levels at most.
47. A self-referential component must not declare its own key for what the mount provides (`wcs/mount-own-key-shadow`), and must build its shadow in `connectedCallback`, not the constructor.
48. An accumulation that must outlive a `$stream` restart is **a key you own**, folded in a `$watch` handler on the stream's value (or an `$on` handler) (§15). Keep it bounded, keep an idempotency key (the handler runs once per landing, not once per page), and never derive the stream's `args` from the feed.
49. **Events are delegated** (§8): `event.currentTarget` in a plain `on*:` handler of a bubbling event is the root — use `event.target.closest(…)` or the loop index. `on*#direct:` where the element itself is needed, where `#stop` must stop your own ancestor listeners, where an ancestor calls `stopPropagation()`, or where the element moves under another root; an outer `#direct` runs before inner delegated handlers.
50. **Writing a list element replaces the value at that position** — rows do not move; reorder by assigning a new array (§4). `data-wcs` is removed from row and branch elements, so select them by class.
51. **A `for:` over a getter returning a filtered copy** (TodoMVC) and **one object at two positions** are the 4.0 limitation (#365): a write below one row does not reach the other list's (or position's) row bindings — reassign the source list with a new row object.
52. **Numeric keys under a plain object** (`sales.2024.total`) read `undefined` from the script and throw on write in 4.0 (known limitation) — read `this.sales[2024].total` and replace the top-level object.
53. **Configuration**: `bootstrapState()` takes notation only and throws `#44` on anything else; `$behavior` in each root state holds `enableMustache` / `sameValueGuard` / `enableDirectionalInitialSync`; every package's `bootstrapXxx(config)` throws on an unknown option (§11).
54. **Initialization failures are loud and final** (§11): `#49` / `#50` once, `connectedCallbackPromise` rejects, `initializePromise` resolves, a failed element cannot be re-armed. In the 4.0 preview a page-level markup error fails the whole `<wcs-state>` — lint before you deploy.
55. **Text at page level**: prefer `<!--@@: path-->` or `textContent:` over `{{ }}` (FOUC). Comment bindings bind even with `enableMustache: false`, not inside `<textarea>` / `<title>`. Children of a content-setting element (`textContent:`, `innerHTML:`, `html:`) and of `<noscript>` / `<iframe>` are never bound (§3).
56. **User content is not markup**: never place user text where the page scan reads it (`{{ }}`, `data-wcs`, comment bindings — HTML-escaping does not neutralize `{{ }}`, and there is no opt-out attribute in 4.0); deliver it through state and render it with a text binding (§2).
57. A "selected row" flag over a long list belongs in `$eqPath` / `$eqIndex` (§6), not in `this["items.*.id"] === this.selectedId`. Point `path` at the written state (a getter path re-evaluates every row); keys compare without coercion, so convert an input's string (`value|number: selectedId`). `$eqIndex` throws outside a list row.
58. **SSR**: server and client at the same major.minor (a mismatched snapshot is discarded and the page re-renders on the client), comments kept in the output, JSON values only in SSR state (§11).
59. The split entries (§1) load from jsDelivr's plain file paths or a bundler, **never `esm.run`**. A missing feature throws `[wcs/feature-not-installed]` / `[wcs/filter-unknown]`; only a missing `features/diagnostics` is silent (numbered messages, no path warnings). When in doubt, use `/auto`.
60. A render that writes something new every time is cut after 100 drains (`render chain depth limit exceeded …`, §11); values written past the cut stay in state. Break the cycle — write only when the value really changes.


---

# Reference: SPA routing and scaffold

<!-- source: wcstack-skill/skills/wcstack-app/references/router-and-scaffold.md -->

# wcstack router / autoloader / app scaffold reference

Sources: `packages/router/README.md` / `README.ja.md`, `packages/autoloader/README.ja.md`, root `README.md`, `examples/README.ja.md`, `examples/router-spa/` (index.html / server.js / README.ja.md), `packages/router/src/`, plus `docs/csp.md` / `docs/sri.md` and, for what `@wcstack/state` 4.0 changes on routes, `docs/migration-v4.md` §3.9 and `packages/state/src/dom/mount.ts`. All verified against the actual files at v4.0.0. The router behaviour 4.0 relies on arrived with router 3.5: a route carries its whole range out and back in (§1), a parameter-only navigation reconnects the route content once (§2), layouts bind on the first navigation (§3). What changes with `@wcstack/state` 4.0 is what state renders inside a route (§1), and `bootstrapRouter(options)` / `bootstrapAutoloader(options)` throw on an option they do not have (§1, §6).

## 1. Minimal SPA scaffold

### CDN loading (one package per line, `/auto` entry)

```html
<script type="module" src="https://esm.run/@wcstack/fetch/auto"></script>
<script type="module" src="https://esm.run/@wcstack/router/auto"></script>
<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
```

`/auto` is a zero-config bootstrap that only performs registration (it passes no options). **List every I/O node package (and `@wcstack/devtools/auto`) before `@wcstack/state/auto`** — module scripts run in document order, so this guarantees the elements are defined before state binds. Property/spread bindings survive a late definition (deferred via `whenDefined`, in `for:` / `if:` rows too), but a **command-token emit is never replayed**, so an emit fired while an element is still undefined is silently dropped.

When you bootstrap the router yourself, `bootstrapRouter({ tagNames: { … }, enableShadowRoot, basenameFileExtensions })` **throws** on an option it does not have, a value of another type, an unknown `tagNames` key or a non-string tag name (`[@wcstack/router] bootstrapRouter: "…" is not one of its options, or not of the option's type.`); every option is checked before any is applied.

### Hardening the same scaffold for production

Swap each `esm.run` line for a version-pinned direct path with an `integrity` attribute; the order rule is unchanged.

```html
<script type="module"
        src="https://cdn.jsdelivr.net/npm/@wcstack/router@4.0.0/dist/auto.min.js"
        integrity="sha384-…"></script>
```

`dist/auto.min.js` has zero static imports, so one hash covers the whole runtime. Digests come from the GitHub Release (`sri.json` asset), not from the CDN's own data API. `esm.run` cannot be hashed at all — it redirects to a re-bundling `+esm` endpoint — and under CSP it also costs two hosts (`https://esm.run` **and** `https://cdn.jsdelivr.net`), because the redirect target is re-checked. When the server issues a CSP nonce, put it on the state and router tags as well (`nonce="{RANDOM}"` next to `integrity`): the inline state and the route guards are imported through `blob:` URLs, and those imports inherit the nonce of the tag that loaded the bundle, so the policy needs no `script-src blob:`. Full directive table and the state-loading caveats: `references/state-binding.md` §1–2.

### Basic router structure

**A `<template>` is required directly under `<wcs-router>`**. Place `<wcs-route>` elements inside it. The render target is `<wcs-outlet>` (auto-generated by the router if not written in the HTML).

```html
<wcs-router>
  <template>
    <wcs-route path="/">
      <wcs-head><title>Home</title></wcs-head>
      <app-home></app-home>
    </wcs-route>
    <wcs-route path="/about">
      <about-page></about-page>
    </wcs-route>
    <wcs-route fallback>
      <error-404></error-404>
    </wcs-route>
  </template>
</wcs-router>
<wcs-outlet></wcs-outlet>
```

- To display a component, **write it directly as a child of `<wcs-route>`**. On match, the children are stamped into `<wcs-outlet>`.
- Static HTML (without `data-wcs`) may also be written directly inside a route.
- **What state renders in a route body.** The router hands state the body's *elements* when it stamps them, declaring that it carries the route's range (the binder's `bind(subtree, { range: true })` — internal to router and state; you pass it only if you write your own inserter):
  - `data-wcs`, `{{ }}` and comment bindings **inside elements** bind on the landing route and on every navigation;
  - a `for:` / `if:` template **directly under `<wcs-route>`** renders with `@wcstack/state` 4.0 and router ≥3.5, and its rows or branch (with its `elseif:` / `else:`) leave and come back with the route. Inside `<wcs-head>`, or in content other code inserts without that declaration, 4.0 does not render it and reports `[wcs/template-syntax] #204` (`… was not rendered … wrap it in an element.`);
  - **text `{{ }}` directly under `<wcs-route>`** (not inside an element) is bound only on the landing route, by state's first scan — never when the route is entered by navigation. Wrap it in an element (`<p>{{ title }}</p>`).

  Wrapping the body in one element works in every combination, and is the simplest thing to generate:

  ```html
  <wcs-route path="/products/:productId(int)">
    <wcs-head><title data-wcs="textContent: product.name"></title></wcs-head>
    <article>
      <h2 data-wcs="textContent: product.name"></h2>
      <ul><template data-wcs="for: product.variants"><li data-wcs="textContent: .name"></li></template></ul>
    </article>
  </wcs-route>
  ```
- **A route carries its range.** A shown body ends with `<!--@@wcs-route-end:<path>-->` (the SSR end marker); leaving takes everything from the route's placeholder to it out of the document — rows state rendered there, nodes your code inserted — and the next entry puts the same nodes back. A top-level node your code removed stays removed; a node you moved out of the route body (a dialog moved to `<body>`) is taken back into it on exit. The outlet has one more child node, but `wcs-outlet:empty` is unaffected.

### `<wcs-route>` attribute list

| Attribute | Description |
|------|------|
| `path` | Absolute path starting with `/` at the top level; relative path when nested. Parameters are `:name`. Catch-all is `*`. Relative paths are not allowed at the top level |
| `index` | Inherits the parent path (matches the parent path itself) |
| `fallback` | Displayed when no route matches |
| `fullpath` | Full path including ancestors (read-only) |
| `name` | For identification |
| `guard` | Enables the guard. The value is the absolute redirect path used when the guard cancels with a falsy return (a non-empty string return redirects there instead — §4) |

Route elements are **detached controllers** after parsing: they are not part of the live DOM, cannot be found with `querySelector`, and cannot be bound with `data-wcs`. Match results (`params` / `typedParams` / `routeName`) are read from the **`<wcs-router>` element** — see §5. `guardHandler` can still be set from JS on a route object obtained before parsing.

### Matching priority

1. More segments → 2. more static segments (`"users"` > `":id"` > `"*"`) → 3. definition order. `/products` and `/products/` are treated as identical.

## 2. Typed path parameters

Syntax: `:paramName(typeName)`

```html
<wcs-route path="/users/:userId(int)"><user-detail data-bind="props"></user-detail></wcs-route>
<wcs-route path="/posts/:date(isoDate)/:slug(slug)"><post-detail data-bind="props"></post-detail></wcs-route>
```

| Type name | Description | Converted type |
|------|------|------|
| `int` | Integer | `number` |
| `float` | Floating-point number | `number` |
| `bool` | `true`/`false`/`0`/`1` | `boolean` |
| `uuid` | UUID v1-5 | `string` |
| `slug` | Lowercase alphanumerics and hyphens | `string` |
| `isoDate` | ISO 8601 date | `Date` |
| `any` | Any string (default) | `string` |

A value that fails the type check **does not match that route** (no error; it falls through to other routes or the fallback route). Unknown type names fall back to `any`.

### How to receive parameters

**(a) From JS**: read the **router element** — `document.querySelector('wcs-router').params.userId` (string) / `.typedParams.userId` (type-converted). (Route elements are detached controllers — they cannot be found with `querySelector`.)

**(b) `data-bind` auto-binding** — automatically injects parameters into elements inside the route:

| `data-bind` value | Behavior |
|------|------|
| `"props"` | Merged into `element.props` |
| `"states"` | Merged into `element.states` |
| `"attr"` | Set via `setAttribute()` |
| `""` (empty string) | Direct property (`element.userId = value`) |

**Timing**: for elements that are *already defined* when the route renders — built-ins, and custom elements whose `define()` ran before the router stamped the content — parameters are assigned **before** `connectedCallback` fires. For a custom element that is **not yet defined**, assignment waits for `customElements.whenDefined()`, which resolves *after* the upgrade — so the `connectedCallback` run by the upgrade does **not** see them yet (autoloader-compatible, but `this.props.userId` read there is `undefined`, with no error). Either read the params in the `props` / `states` / attribute setter (or `attributeChangedCallback`) instead, or make sure the element is defined before the route renders (load its script before `@wcstack/router/auto`). When the params are needed in state anyway, prefer (c). **A parameter-only navigation** (`/users/1` → `/users/2`) takes the route's content out and puts it back in order, so its custom elements' `connectedCallback` runs again — once, with the new parameters, nested routes included.

**(c) From state (via wc-bindable)** — bind `typedParams` / `routeName` on `<wcs-router>` and consume the **parsed** results; no path-string regex needed (see §5 and §7).

## 3. Nested layouts and `<wcs-head>`

### `<wcs-layout>`

Loads a template, inserts its children into `<slot>`, and writes the result out to `<wcs-layout-outlet>`.

| Attribute | Description |
|------|------|
| `layout` | id of the `<template>` used as the layout template |
| `src` | URL of an external file template |
| `name` | Identifier name |
| `enable-shadow-root` / `disable-shadow-root` | Toggles Shadow/Light DOM for the outlet |

### Real example mixing routes and layouts

```html
<wcs-router>
  <template>
    <wcs-route path="/">
      <wcs-layout layout="main-layout">
        <main-header slot="header"></main-header>
        <main-body>
          <wcs-route index>
            <wcs-head><title>Main Page</title></wcs-head>
            <main-dashboard></main-dashboard>
          </wcs-route>
          <wcs-route path="products">          <!-- nested routes use relative paths -->
            <wcs-route index><product-list></product-list></wcs-route>
            <wcs-route path=":productId"><product-item data-bind="props"></product-item></wcs-route>
          </wcs-route>
        </main-body>
      </wcs-layout>
    </wcs-route>
    <wcs-route fallback><error-404></error-404></wcs-route>
  </template>
</wcs-router>
<wcs-outlet></wcs-outlet>

<template id="main-layout">
  <section><h1> Main </h1><slot name="header"></slot></section>
  <section><slot></slot></section>   <!-- route content goes into the default slot -->
</template>
```

### Light DOM limitation

With `disable-shadow-root`, slot substitution applies **only to direct children of `<wcs-layout>`**. Elements with a `slot` attribute inside a `<wcs-route>` are not slotted.

### Layouts and state bindings

`<wcs-layout-outlet>` hands the elements it places to state's binder once they are in the page (the template loads asynchronously), with the same range declaration as a route body, so the layout template's own bindings and the route content in its slots bind on the **first** navigation into the layout. Only elements are handed over: **a `{{ }}` in text directly under the layout template (not inside an element) is not bound on a navigation** — wrap it in an element, as for a route body (§1). With `enable-shadow-root` the template sits in the outlet's shadow root, which the page's state does not bind (the slotted route content is bound).

### `<wcs-head>`

Manages the document `<head>` per route. Stack-based: the last one connected wins. Supported elements: `<title>` `<meta>` `<link>` `<base>` `<script>` `<style>`. When all `<wcs-head>` elements disconnect, the initial state is restored. `<meta>` is identified by `name`/`property`/`http-equiv`; `<link>` by `rel`/`href`.

## 4. Guards, basename, fallback

### Route guards

```html
<wcs-route path="/dashboard" guard="/login">
  <wcs-guard-handler>
    <script type="module">
      export default function(toPath, fromPath) {
        return document.cookie.includes('session=');   // true | false | object | string, or a Promise of one (table below)
      }
    </script>
  </wcs-guard-handler>
  <dashboard-page></dashboard-page>
</wcs-route>
```

`false` cancels → navigates to the path in the `guard` attribute. `<wcs-guard-handler>` is removed from the DOM after parsing. Ignored if placed outside a `<wcs-route>`. Can also be set from JS via `route.guardHandler = fn`.

**Guard return values and the third argument** — the guard is the one async step before the route content swaps, so it doubles as the route's **loader** and **dynamic redirect**:

| Return | Effect |
|---|---|
| `true` | enter |
| an object | enter **and** commit it as `<wcs-router>.data` (output-only, `wcs-router:data-changed`, fires first; nested chain shallow-merged parent → child; `null` on navigations whose guards return no object; same-match keeps it) |
| a non-empty string | cancel and redirect **there** (wins over `guard=`) — e.g. `` return `/login?next=${encodeURIComponent(toPath)}` `` |
| any falsy (`false` / `undefined` / `null` / `""`) | cancel → `guard=` path (unchanged: a forgotten `return` still rejects) |

The third argument is a frozen `{ params, typedParams, searchParams, routeName }` snapshot of the match being entered — the same vocabulary the router exposes after the commit, readable before it. Canonical loader:

```html
<wcs-router data-wcs="data: routeData; typedParams: routeParams">
  <wcs-route path="/users/:id(int)" name="user" guard="/users">
    <wcs-guard-handler><script type="module">
      export default async function (to, from, { typedParams }) {
        const res = await fetch(`/api/users/${typedParams.id}`);
        if (res.status === 404) return "/users";
        if (!res.ok) return false;
        return { user: await res.json() };
      }
    </script></wcs-guard-handler>
    <h1 data-wcs="textContent: routeData.user.name"></h1>
  </wcs-route>
</wcs-router>
```

`data` is the one router output that is **not** frozen (it is the guard's own object) and the router does not cache it — same route with other params loads again. Use it when the page must not show the new route with empty content (a `<wcs-view-transition>` otherwise animates a blank frame). A loader guard is still a guard under CSP: no `src=` form (below).

**Under a CSP, guards need the page nonce on the `<script>` that loads router, or `script-src blob:`.** The handler is evaluated through a `blob:` URL, and that import inherits the nonce of the tag that loaded the router bundle — `<script type="module" nonce="{RANDOM}" src="https://cdn.jsdelivr.net/npm/@wcstack/router@4.0.0/dist/auto.min.js">` runs guards under a policy without `blob:`. Unlike `<wcs-state>` there is **no `src=` form to escape to** — this asymmetry is known and unimplemented — so where no nonce can be issued (static hosting), guards force `script-src blob:` (router also retries through a `data:` URL, so `script-src data:` would pass too — do not open it; it is the riskier source). If that policy must stay strict, drop guards and gate on the route-content side (a `<template data-wcs="if: isAuthed">` swap) instead. A CSP-blocked guard is reported as CSP (on Firefox too), and the message names the nonce fix.

### basename

```html
<wcs-router basename="/app"> ... </wcs-router>
```

Resolution order: (1) `basename` attribute → (2) derived from `<base href>` → (3) empty string. Normalization: prepend leading `/`, collapse consecutive slashes, strip trailing `/`, strip trailing `*.html` (`/app/index.html` → `/app`). Multiple routers can coexist in the same document as long as their basenames differ.

**Multilingual sites: the locale goes in the basename, not a route pattern** (`examples/router-i18n`). Write `<base href="/ja/">` from a synchronous `<head>` script once the locale is known. A `/:lang` route parameter *breaks* the language switch: the router intercepts every same-origin navigation under its basename, so a link to another language would be handled client-side and per-locale modules (dictionary, `Intl` formatters) would never re-evaluate — the language silently does not change. With the locale in the basename, a link to `/en/…` falls outside the router's own path, and the browser performs a real navigation. Consequences: route patterns and in-app links stay locale-free, and **every URL on the page must be absolute** (`<base>` changes relative resolution — including `<wcs-state src>`, which resolves against the document base URL). Repair a locale-less URL in that same head script via `location.replace`, not a route guard (a guard *can* redirect dynamically by returning a string, but the head script runs before any module loads and the basename decision has to be made there anyway).

### Fallback route / catch-all

- `<wcs-route fallback>` — for 404.
- A trailing `*` in `path` matches the entire remaining path; retrieve it via `params['*']`; lowest priority.

## 5. Navigation

### Declarative links: `<wcs-link>` (use this, not a raw `<a>`)

```html
<wcs-link to="/">Products</wcs-link>
<wcs-link to="/about">About</wcs-link>
```

- Converted to an `<a>`. If `to` starts with `/`, it is a route path (basename auto-prepended; a `?query` / `#hash` suffix is kept). A value starting with `?` is a **query-only link** (current pathname + that query). Other values are external URLs.
- The `active` CSS class is applied on current-location match — and `aria-current="page"` alongside it. The comparison is **pathname-only**: `to="/products"` stays active on `/products?page=2`.
- **Attribute forwarding**: at anchor creation, all `aria-*` plus `title` / `rel` / `target` / `download` / `hreflang` / `lang` / `dir` are copied host → anchor (`lang` / `dir` set the announcement language and direction of the link text, so a multilingual nav wants them). Afterwards only those fixed names keep tracking; **dynamic `aria-*` changes never reach the anchor** — including `data-wcs="attr.aria-label: ..."`. Write `aria-*` on `<wcs-link>` as static attributes.
- In browsers with the Navigation API, a plain `<a href="/about">` under the basename is **also** intercepted as an SPA navigation; fallback browsers get SPA behavior only through `<wcs-link>` — so it stays the recommendation.

### Programmatic navigation

**(a) JS API**: the router element's `async navigate(path: string): Promise<void>` (Navigation API, with pushState fallback when unavailable).

**(b) From state** — `<wcs-router>` exposes the whole navigation state over wc-bindable:

```html
<wcs-router data-wcs="path: path; typedParams: routeParams; searchParams: query;
                      routeName: routeName; data: routeData;
                      navigateUrl: navigateUrl; replaceUrl: replaceUrl">
```

| Member | Direction | Notes |
|---|---|---|
| `path` | output | Current route path, basename sliced. Fires **last** on a navigation — doubles as "navigation finished" |
| `params` / `typedParams` | output | Merged params of the matched chain; `typedParams` type-converted (`:id(int)` → number). `{}` on fallback / before init |
| `searchParams` | output | Query as `Record<string,string>`; duplicate keys last-wins, `URLSearchParams` decoding; `{}` when none |
| `routeName` | output | `name` of the deepest matched route (fallback route's `name` on a 404); `""` when unnamed |
| `data` | output | What the current navigation's guards **returned as an object** (§4 loader) — `null` when no guard returned one, including before init; a query-only same-match keeps the previous value. The one member that is **not** frozen: it is the guard's own object, passed through; the router neither copies nor caches it. Fires `wcs-router:data-changed` |
| `navigateUrl` | write (null-idle transient) | Assign a target to **push**-navigate; resets itself to `null` on finish; `null`/`""` writes are no-ops |
| `replaceUrl` | write (null-idle transient) | Same contract, but **replaces** the history entry |
| `basename` | input | Writes the `basename` attribute, which the router reads **once, at initialization** — set it in markup (a later write does not move the routing base). Reads back the basename in effect |

- Outputs are **read** when the binding attaches, then streamed via change events — a binding attaching after the first route resolution misses nothing. On a committed navigation all values commit first, then events fire `data` → `params` → `routeName` → `search` → `path`, each only when changed (`data` by identity); a guard-rejected navigation updates and fires nothing. The exposed objects are **frozen snapshots** — copy, don't mutate (`data` is the exception: it is owned by the guard that returned it).
- **Choosing the write surface**: pagination/tabs (back button should step through) → `navigateUrl = "?page=2"`; search boxes/filters (history should not record keystrokes) → `replaceUrl = "?q=" + …` with `<wcs-debounce>` in front.
- Commands `navigate(path)` / `replace(path)` are also declared (invocable via command tokens).

### Query strings in navigation targets

`navigate()` / `navigateUrl` / `replaceUrl` / `<wcs-link to>` accept `/path` (query **not** carried over), `/path?k=v`, `?k=v` (**query-only**: pathname keeps its value), and `?` (clears the query). Queries never participate in route matching, and a query-only navigation is a **same-match**: guards do not re-run, content is not restamped, no view transition, no announcement, focus/scroll stay. Only `searchParams` and the URL change. The hash is passed through untouched (never routed on).

### Accessibility contract

Default: the router **delegates to the browser** — on the Navigation API path it passes the spec defaults explicitly (`scroll: "after-transition"`, `focusReset: "after-transition"`: push scrolls to top, traverse restores scroll, focus goes to `[autofocus]` or `<body>`); on the fallback path it scrolls to top after a committed push and leaves `popstate` to `history.scrollRestoration`. Opt-in policies — both off by default, never on first load, never on a guard-rejected navigation:

- `<wcs-router focus="heading">` — moves focus to the first **visible** `h1`–`h6` of the **leaf** route's content (adds `tabindex="-1"` if needed; hidden headings are skipped, since focusing them is a no-op). With no visible heading, the router reproduces the spec-default reset itself — first `[autofocus]`, else blur to `<body>` — and only the exact value `"heading"` activates the policy, an empty or unknown value falling back to the browser default. **Two authoring rules**: write exactly `focus="heading"` or omit the attribute, and **give every route a visible heading near the top of its content** (focusing a heading scrolls it into view, but the scroll-to-top after a push wins, so a heading far down ends up focused off-screen).
- `<wcs-router announce="title">` — writes the commit-time `document.title` snapshot into a router-owned live region (`role="status"`). Known limits: a bound `<title data-wcs>` may still be stale at commit; a title change outside navigation is not re-announced; and navigating between two routes that share a title may not be announced at all by some screen reader / browser pairs, because the live-region text never changes — give routes distinct titles.

**Recommended default for an SPA scaffold**: `<wcs-router focus="heading" announce="title">`, plus one `<h1>` and one `<wcs-head><title>` per route. Both policies are inert without that markup, so opting in without the headings and titles buys nothing.

### Route transition animations

Load `@wcstack/view-transition/auto` and put `<wcs-view-transition for="router"></wcs-view-transition>` on the page: route swaps run inside a View Transition, styled in CSS via `::view-transition-old/new(root)`. Guards run first (an awaiting guard does not hold the transition open); the first paint never animates. `for="router"` keeps state's drain timing untouched — see `state-binding.md` §10 for what the default (`for="router state"`) changes.

### Server-side rendering the initial route

`<wcs-router enable-ssr>` + `@wcstack/server`'s `renderToString(html, { url, bootstraps })` renders the request URL's initial route on the server — typed params, nested routes, and structural templates inside route content included. The client router **adopts** the server-rendered DOM instead of re-rendering (state bindings hydrated on those nodes stay live); anything that fails verification falls back silently to client-side rendering. Guarded routes are never server-rendered (guards are authorization and run client-side; the outlet ships empty); `<wcs-layout>` routes fall back on adoption; `<wcs-link>` anchors are server-rendered with `active`/`aria-current` and adopted. Packages whose classes extend `HTMLElement` cannot be imported top-level in plain Node — pass async loaders: `bootstraps: [bootstrapState, async () => (await import('@wcstack/router')).bootstrapRouter()]`.

**Server and client move together.** Deploy `@wcstack/server` and the client at the same major.minor: a 4.0 client discards the snapshot of a 3.x server (`<wcs-ssr version="3.x.y"> does not match 4.0.0 …`) and renders the page on the client from its own state — it works, but the server's work, `$connectedCallback` and its fetches included, is redone; a 4.0 server with a 3.x client is not supported. Purge HTML cached from the old version when you switch. `renderToString(html, { url, bootstraps, timeoutMs })` — `timeoutMs` defaults to 30 000 ms (`0` disables; keep it finite and ≤ 2 147 483 647), so one page that never becomes ready cannot hang the process. Keep the comments in the output (text bindings and the row / branch markers are comments — a minifier's `removeComments` breaks hydration), keep SSR state JSON (`Date` / `Map` / class instances do not survive the snapshot), and expect `outerHTML:` / `outerText:` to be applied on the client only. Hydration adopts the server's rows and branches — nested `for:`s and a `for:` inside an `if:` included — and applies every binding; `$connectedCallback` does not run again on the client. Details: `state-binding.md` §11.

## 6. autoloader

### Import Map + element placement

```html
<script type="importmap">
  {
    "imports": {
      "@components/ui/": "./components/ui/",
      "@components/app/": "./components/app/"
    }
  }
</script>
<script type="module" src="https://esm.run/@wcstack/autoloader/auto"></script>
<body>
  <wcs-autoloader></wcs-autoloader>   <!-- Triggers the load lifecycle. Required -->
  <ui-button></ui-button>    <!-- auto-imports ./components/ui/button.js -->
  <app-header></app-header>  <!-- auto-imports ./components/app/header.js -->
</body>
```

### Resolution rules

**Lazy loading (namespace)** — key ends with `/`: `"@components/<prefix>[|<loader>]/": "<path>"`
- The prefix part of the tag name matches and the remainder becomes the file name: `@components/ui/` + `<ui-button>` → `./components/ui/button.js`
- Slashes inside the prefix are converted to dashes. Loader specification: `"@components/ui|lit/": "./ui/"` (default `vanilla`)

**Eager loading** — key does not end with `/`: `"@components/my-button": "./my-button.js"`, `"@components/fancy-input|vanilla,input": "./fancy-input.js"` (when extends is omitted, it is auto-detected from the prototype)

**Component requirements** (vanilla loader): `.js` extension + `default` export of the custom element class:

```javascript
// components/ui/button.js
export default class UiButton extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' }).innerHTML = '<button><slot></slot></button>';
  }
}
```

- The `is` attribute (customized built-ins) is also auto-detected (the autoloader defines with `{ extends }`).
- Components that fail to load are not retried (failure detection is the responsibility of `@wcstack/defined`). Dynamically added elements are also detected via MutationObserver. Waiters await the load promise itself, which settles on success *or* failure, so one broken component does not stall the other lazy loads.
- **Scoped custom element registries (Chrome/Edge 146+, Safari 26+) are supported**: lazy loading defines into the scanned root's own registry, the in-flight ledger is per registry, and a root whose registry is explicitly `null` is reported instead of silently skipped. On platforms without the feature, behavior is byte-for-byte unchanged. (The same registry resolution applies across wcstack: `<wcs-defined>` watches the registry its subtree resolves against — tags with no governing registry report `missing` immediately rather than pending forever — and every package's `registerComponents(registry?)` can define into a scoped registry; see `docs/scoped-custom-element-registries.md`.)
- **Under a CSP the inline import map needs a `nonce`** (`<script type="importmap" nonce="{RANDOM}">`) — being inline, it cannot take `integrity` — and `script-src` must allow whatever host `@components/` resolves to. Autoloaded components are page-supplied code, so they are outside the wcstack bundle's `integrity` coverage; hash them yourself if that matters.
- **`bootstrapAutoloader(options)`** (only when you bootstrap it yourself — `/auto` passes nothing) throws on an option it does not have or a value of another type (`[@wcstack/autoloader] bootstrapAutoloader: "…" is not one of its options, or not of the option's type.`). There is no `scanImportmap` (the import map is always read; 3.x accepted the option and ignored it).

## 7. Full index.html structure of the real demo (actual examples/router-spa skeleton)

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <!-- Required for deep links: without it, loading /products/3 directly makes that path the basename -->
  <base href="/">
  <title>wcstack: router + state + fetch demo</title>
  <style>/* style active links via a.active */</style>
  <!-- I/O nodes before state: module scripts execute in document order, so every
       element is defined before state binds to it (§9-4). -->
  <script type="module" src="https://esm.run/@wcstack/fetch/auto"></script>
  <script type="module" src="https://esm.run/@wcstack/router/auto"></script>
  <script type="module" src="https://esm.run/@wcstack/state/auto"></script>
</head>
<body>

<nav aria-label="Main">
  <wcs-link to="/">Products</wcs-link>
  <wcs-link to="/about">About</wcs-link>
</nav>

<wcs-state>
  <script type="module">
    export default {
      // Router observation surface: parsed results, no path regex anywhere
      routeParams: {},   // <- typedParams: :productId(int) arrives as a number
      routeName: "",     // <- name attribute of the deepest matched route
      navigateUrl: null,
      productsFetch: { value: null, loading: false, error: null, status: 0 },
      productFetch: { value: null, loading: false, error: null, status: 0 },
      get productId() { return this.routeParams.productId ?? null; },
      get isList() { return this.routeName === "products"; },
      get isDetail() { return this.routeName === "product-detail"; },
      get "productFetch.url"() {
        return this.productId ? "/api/products/" + this.productId : undefined;
      },
      get products() { return this["productsFetch.value"] ?? []; },
      openProduct() { this.navigateUrl = "/products/" + this["products.*.id"]; },
      goToProducts() { this.navigateUrl = "/"; },
    };
  </script>
</wcs-state>

<!-- Router: owns the URL, history, page <title>, and static pages -->
<wcs-router data-wcs="typedParams: routeParams; routeName: routeName; navigateUrl: navigateUrl">
  <template>
    <wcs-route path="/" name="products">
      <wcs-head><title>Products</title></wcs-head>
    </wcs-route>
    <wcs-route path="/products/:productId(int)" name="product-detail">
      <wcs-head><title>Product detail</title></wcs-head>
    </wcs-route>
    <wcs-route path="/about">
      <wcs-head><title>About</title></wcs-head>
      <section><!-- write static content directly (no data-wcs) --></section>
    </wcs-route>
    <wcs-route fallback>
      <wcs-head><title>Not found</title></wcs-head>
      <section>
        <h2>404</h2>
        <p><wcs-link to="/">Back</wcs-link></p>
      </section>
    </wcs-route>
  </template>
</wcs-router>
<wcs-outlet></wcs-outlet>

<!-- Headless fetch nodes (spread all outputs into state slots) -->
<wcs-fetch url="/api/products" data-wcs="...: productsFetch"></wcs-fetch>
<wcs-fetch data-wcs="...: productFetch"></wcs-fetch>

<!-- Data-bound pages live under state-managed <template data-wcs="if:"> (directly under body) -->
<template data-wcs="if: isList">
  <section aria-label="Product list">
    <ul>
      <template data-wcs="for: products">
        <li>
          <button type="button" data-wcs="onclick: openProduct; attr.aria-label: .name">
            <span data-wcs="textContent: .name"></span>
            <span>¥<span data-wcs="textContent: .price|locale('ja-JP')"></span></span>
          </button>
        </li>
      </template>
    </ul>
  </section>
</template>

<template data-wcs="if: isDetail">
  <section aria-label="Product detail">
    <button type="button" data-wcs="onclick: goToProducts">&larr; Back</button>
    <h2 data-wcs="textContent: productFetch.value.name"></h2>
  </section>
</template>

</body>
</html>
```

### Server-side SPA fallback (actual examples/router-spa/server.js)

```javascript
// SPA fallback: every non-API, extensionless GET returns index.html
if (!url.pathname.startsWith("/api/") && extname(url.pathname) === "") {
  const html = await readFile(join(__dirname, "index.html"));
  res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
  res.end(html);
  return true;
}
```

## 8. How to put your own custom elements on a route

- Write the tag directly inside the route and receive parameters via `data-bind` (§2).
- **Defining is outside the router's responsibility** — the autoloader (§6) or a manual `customElements.define()` is required separately.
- Alternative pattern (proven in router-spa): create no custom elements; put only `<wcs-head>` + static content in the routes, and switch the data-bound page DOM via `routeName`-derived getters in `<template data-wcs="if: ...">` directly under body. (Bindings inside routes work, so this is a choice, not a requirement — but it is the pattern the official demo ships.)
- **Pick the shape per page, not per project (router README, "Where route content lives").** The route body is the default: stamped on entry, removed on exit, bindings bound on insertion, and everything the router offers — `<wcs-head>`, `focus="heading"` / `announce=`, the per-route view transition — is keyed to it. Switch to the body-level `<template data-wcs="if: …">` form **when the DOM must stay in the document across the navigation**: leaving a route removes its body and entering puts the same nodes back (not rebuilt), so what the nodes hold survives (a half-filled form) but what needs them connected does not: a playing `<video>`, a list's scroll position (Chromium, WebKit), a component that tears down in `disconnectedCallback`. What the exception costs: `focus="heading"` finds no heading in the empty route body and falls back to the browser-default reset (`announce=` still reads `document.title`), and a view transition wraps the state branch update rather than the route swap. router-spa shows both — About is the default shape, the product pages are the exception.

## 9. Pitfall checklist

1. **Deep links break without `<base href="/">`** (the basename is mis-derived from `document.baseURI`).
2. **The server needs a SPA fallback** — without it, reloads and direct links 404.
3. **Bindings in router-stamped content work** (binder protocol: the router hands inserted subtrees — route content *and* `<wcs-head>` clones — to state, so per-route `<title data-wcs>` binds too). On a page **without** state the router warns about bindings that cannot work; the body-level `<template data-wcs="if:">` architecture remains a perfectly good pattern (router-spa still uses it).
4. **Script order — I/O node packages must come before `@wcstack/state`.** State last closes the window in which a `$command.x.emit()` reaches zero subscribers (command tokens are not replayed). Where the order is out of your hands, gate the emitting control on `<wcs-defined timeout>`'s `pending` output rather than awaiting `customElements.whenDefined()` (which never rejects).
5. In Light DOM layouts, elements with a `slot` attribute are only effective as direct children of `<wcs-layout>`.
6. A type mismatch is not an error but "no match" — `/products/abc` passes through `:productId(int)` and falls to the fallback.
7. Relative paths cannot be written on top-level routes. Nested routes use relative paths.
8. `undefined` is never written to an element (write-skip) — if a getter returns `undefined`, `<wcs-fetch>` stays silent. The auto-fetch guard compares against the last url **actually fetched**, and a state that fetches nothing (empty/`undefined` url) does not update it: leaving a detail route and coming straight back to the same id re-enters with the same url and is **skipped**. Use `command.fetch` when a genuine re-run is wanted.
9. Autoloader load failures are not retried (waiters settle on failure too, so other lazy loads continue).
10. Under a CSP, route guards need the page nonce on the `<script>` that loads router (their `blob:` import inherits it) or `script-src blob:`, and they have no external-file form (§4).
11. **`data-bind` params are invisible to the upgrade-time `connectedCallback` of a not-yet-defined element** — they are assigned after `whenDefined()` resolves, which is after the upgrade (an already-defined element does get them before `connectedCallback`). Read them in a setter / `attributeChangedCallback`, define the element before the router renders, or bind `typedParams` on `<wcs-router>` into state (§2).
12. **A guard that forgets to `return` still rejects** (every falsy value cancels), and an **object return enters the route** — a guard that hands back the fetched record by accident also lets the user in. Do the authorization check first, then return `true` / a string / an object deliberately (§4).
13. **`data` is `null` on any navigation whose guards return no object** — wrap content that reads it in `<template data-wcs="if: routeData">`. The router does not cache it: revisiting the same route with other params loads again, so keep anything worth reusing in your own state.
14. **Text `{{ }}` directly under `<wcs-route>` or a layout template binds on the landing route only** — wrap it in an element (§1, §3). A `for:` / `if:` directly under `<wcs-route>` renders with `@wcstack/state` 4.0, but not at the top of a `<wcs-head>` (#204). Wrapping the whole body in one element works everywhere.
15. **`bootstrapRouter(options)` / `bootstrapAutoloader(options)` throw on an option they do not have** (`scanImportmap` included); `/auto` passes none (§1, §6).
16. **Delegated `on*:` handlers belong to the root they were bound in** (`state-binding.md` §8): a node your code moves under another root — out of a component's shadow root to `document.body` (a dialog) — keeps its bindings but not its delegated handlers; write `on*#direct:` on it. Moving within the document (a route body → `<body>`) keeps them.


---

# Reference: I/O node catalog + signals quick reference

<!-- source: wcstack-skill/skills/wcstack-app/references/io-node-catalog.md -->

# wcstack I/O Node Catalog + signals Quick Reference

Sources: each package's README (ja preferred) plus the `static wcBindable` / `static observedAttributes` declarations in src, `packages/signals/README.ja.md`, `docs/signals-definition-timing.md`, `docs/architecture-hardening/12-wc-bindable-observable-inventory.md`, `docs/audio-tag-design.md`, `docs/midi-tag-design.md`, `docs/timing-and-firing-contract.md`, and `examples/signals-live-search`. Tag surface verified at v4.0.0: **52 tags**, attribute spellings, properties, commands and the timing notes below source-verified. **4.0 changes no I/O node tag, property or command.** Two things an author sees: every package's `bootstrapXxx(config)` **throws** on an option it does not have, a value of another type, an unknown `tagNames` key or a non-string tag name (`[@wcstack/fetch] bootstrapFetch: "tagName" is not one of its options, or not of the option's type.` — `/auto` passes none, so a CDN page is unaffected), and `@wcstack/state` 4.0 delegates `on*:` handlers of bubbling events to the root (`state-binding.md` §8) — I/O-node wiring through property / `command.` / `eventToken.` / spread bindings is unchanged.

History, for reading older pages: `mountNode` and the normative headless Cores arrived in 1.23, observation semantics (§0) in 1.24, `@wcstack/audio` / `@wcstack/midi` in 1.25, scoped-registry support in 1.31, `<wcs-view-transition>` in 1.32, `<wcs-media-query>` in 2.2; no tag, property or command name has changed since it was added. Two wiring shapes needed a minimum `@wcstack/state` on 3.x — the dotted property form (`.once:`) and `class.` / `attr.` / `style.` on a wc-bindable tag from 3.3, I/O nodes inside `for:` rows from 3.4 — and all of them work in 4.0.

## 0. Common Conventions (all I/O nodes)

- **One-line CDN**: `<script type="module" src="https://esm.run/@wcstack/<pkg>/auto"></script>` alongside `@wcstack/state/auto`. **Load every I/O node (and `@wcstack/devtools/auto`) BEFORE `state/auto`** — module scripts run in document order, so this guarantees the elements are defined before state binds. Property/spread bindings survive a late definition (deferred via `whenDefined`, applied with the latest value — in `for:` / `if:` rows too), but a **command-token emit is never replayed** — an emit inside the undefined window is silently dropped. Where the order is out of your hands (autoloader, embedded snippet), gate the emitting control with `<wcs-defined timeout>` on its `pending` output, never with an `await customElements.whenDefined()` inside the handler (that promise never rejects → permanent hang on a failed load).
- **Pre-upgrade property writes are adopted**: assigning an input on a not-yet-defined element (`el.url = "…"`) creates an own data property; every Shell calls `upgradeProperties(this)` first thing in `connectedCallback`, re-running the declared `wcBindable.inputs` through their setters. Declared inputs only, and the command-token asymmetry above is unchanged.
- **wc-bindable**: each tag declares via `static wcBindable` its **properties** (observable outputs; state subscribes) / **inputs** (write surface; the optional `attribute` is the kebab-case markup name) / **commands** (invocable methods). State writes an input's **property only**; each tag reflects its own attributes in its setters (a boolean flag as a present / absent attribute), so `active: isPlaying` on `<wcs-wakelock>` holds the lock only while `isPlaying` is true, and `keepAlive: recording`, `watch:`, `manual:` follow `false` too. (3.x also wrote the attribute itself, as `"false"`, which those inputs read as true.)
- **`null` and `undefined` on an input** (wc-bindable 0.10's producer guidance): `null` clears an attribute-backed input — the attribute goes and the documented default applies, so a boolean that is **on by default** (`<wcs-audio>` `limiter` / `resumeOnGesture`, `<wcs-debounce>` `trailing`, `<wcs-throttle>` `leading`) goes back **on**, not off; `undefined` restores what the markup said. Neither becomes the string `"null"` / `"undefined"`. State never writes `undefined` (write-skip), so in a state app only `null` matters: to switch a default-on flag off, bind `false`, never `null`. Momentary inputs (`trigger`, `notice`, `say`, `send`) ignore both; `<wcs-storage>`'s `value = null` removes the stored key.
- **Observation semantics**: every observable property declares `semantics: "state" | "event" | "handle"`. `state` is a *current value* — the same-value guard applies, so writing an `Object.is`-equal primitive skips the set, the dependency walk, the DOM apply and `$renderedCallback`. **`event` properties are occurrences and bypass that guard**: the same `message` arriving twice updates state twice. The occurrence outputs, worth knowing because they are the ones where repetition carries meaning:

  | tag | occurrence outputs |
  |---|---|
  | `<wcs-ws>` / `<wcs-sse>` / `<wcs-broadcast>` / `<wcs-worker>` | `message` |
  | `<wcs-clipboard>` | `text` `items` `copied` `cut` `pasted` |
  | `<wcs-notify>` | `clicked` `closed` `shown` |
  | `<wcs-speak>` | `charIndex` `spokenWord` |
  | `<wcs-listen>` | `result` |
  | `<wcs-debounce>` / `<wcs-throttle>` | `fired` |
  | `<wcs-recorder>` | `recorded` `dataavailable` |
  | `<wcs-camera>` | `ended` |
  | `<wcs-midi>` | `message` `type` `channel` `note` `velocity` `control` `value` — all seven are derived getters over the one `wcs-midi:message` occurrence |
  | `<wcs-audio>` / `<wcs-analyser>` | `noteOn` `noteOff` / `frame` |

  Everything else — including `error` / `errorInfo` / `loading` / `value` / `trigger` — is `state`. The single `handle` is still `<wcs-camera>`'s `streamReady` (a live `MediaStream`): never route it through state, wire it element-to-element (§2). **`@wcstack/audio` adds zero handles** despite owning a live `AudioNode` graph — the graph is a descriptor, not a value, and the Core owns and disposes it (ADR-14 G2), so the 10 new outputs audio + midi contribute are all `event`.
- **Wiring**: output binding `data-wcs="value: users"` / command-token `data-wcs="command.<method>: $command.<name>"` / event-token `data-wcs="eventToken.<property>: <name>"` / spread `data-wcs="...: slot"`.
- **Common idioms**:
  - `manual` attribute = do not auto-start on connect. **No `manual` does NOT imply auto-start**: idle / tilt / accelerometer / gyroscope / magnetometer / ambient-light-sensor never auto-start — they are inert until the `start` command.
  - `trigger` is a **momentary input property**, not a command (`command.trigger` exists only on `<wcs-debounce>` / `<wcs-throttle>`, which have no trigger property). **No edge detection**: any truthy write fires, then self-resets to `false`, and it bypasses `manual` — a state slot seeded `true` fires at bind. Always seed trigger slots with `false`.
  - **Frozen-after-connect**: most inputs are read at connect or at the next command call only — changing the attribute later is silently ignored. Live (reacting to change): fetch/ws/sse `url`, storage `key`, broadcast `name`, worker `src`, camera constraint attrs, intersect/resize target + geometry, wakelock `active`/`type`, timer `interval` (while running only), media-query `query` (re-subscribes, generation-guarded so a stale list can never write). Frozen surprises: permission `name`, defined `tags`, sensor `frequency`, idle `threshold`, clipboard `monitor`, notify `mode`, listen options while listening, recorder options while recording.
  - **Never-throw**: failures land in the `error` output; nothing throws. Too-early writes are dropped, not queued — ws `send` before connected, broadcast `post` before `open`, worker `post` before `start` all silently divert to `error`. Bind `error` in every app.
  - fullscreen / pip / pointer-lock `target`: re-resolved at each command invocation; default is the first child element, else the element itself.
  - Event names are `<tag-name>:<kind>` (exceptions: screen-orientation uses `wcs-orientation:*`, `<wcs-throttle>` uses `wcs-throttle:*`).
  - Nearly every node has `error` / `errorInfo` outputs (the ones without: timer / raf / debounce / permission / network / media-query / intersection / resize). Sensor-family `error` is sticky — a later successful `start` does not clear it. Omitted from the table.

## 1. Catalog

| package | tag | key attributes / inputs | properties (outputs) | commands |
|---|---|---|---|---|
| **fetch** | `<wcs-fetch>` (helpers: `<wcs-fetch-header name value>` `<wcs-fetch-body type>` `<wcs-infinite-scroll>`) | `url`(live: change re-fetches — in-flight aborted. The auto-fetch guard remembers the last url **actually fetched**, not the previous value, so `"a"→""→"a"` is skipped just like `"a"→"a"`; re-running the same url needs an explicit trigger) `method` `target` `manual` `body`(one-shot: consumed per fetch; a mid-flight write stages for the NEXT fetch) `response-type`(auto/json/text/blob/arrayBuffer) `trigger`(no-op while `url` is empty) | `value` `loading` `error` `status` `objectURL` `trigger` | `fetch` `abort` |
| **storage** | `<wcs-storage>` | `key` `type`(local/session) `value` `manual` `trigger` | `value` `loading` `error` `trigger` (with cross-tab sync) | `load` `save` `remove` (all synchronous) |
| **upload** | `<wcs-upload>` | `url` `method` `field-name` `multiple` `max-size` `accept` `manual` `files`(auto-upload fires on `files` write, NOT on `url` change) `trigger` | `value` `loading` `progress` `error` `status` `files` `trigger` | `upload` `abort` |
| **websocket** | `<wcs-ws>` | `url` `protocols` `auto-reconnect` `reconnect-interval` `max-reconnects` `binary-type` `manual` `trigger` `send` (writing a value sends immediately; objects are auto-JSON-serialized). Options besides `url` are read per `connect`; clearing `url` does not disconnect — `close` does | `message` `connected` `loading` `readyState` `trigger` `send` | `connect` `sendMessage` `close` |
| **sse** | `<wcs-sse>` | `url` `with-credentials` `events` `raw` `manual` `trigger`. Options besides `url` apply only via `close`→`connect` (`connect` to the same url is a no-op) | `message` `connected` `loading` `readyState` `trigger` | `connect` `close` (receive-only) |
| **broadcast** | `<wcs-broadcast>` | `name`(live: change reopens the channel) `manual` | `message` (no self-echo; structured clone) | `open` `post` `close` |
| **worker** | `<wcs-worker>` | `src` `type` `name` `manual` `keep-alive`(thread outlives disconnect — caller must `terminate` or it leaks) `restart-on-error` `max-restarts`(cumulative lifetime budget) `restart-interval` | `message` `running` | `start`(no-op while the same `src` runs — `terminate`→`start` to apply option changes) `post` `terminate` |
| **timer** | `<wcs-timer>` | `interval`(default 1000; live while running only — frozen while stopped/paused) `once` `repeat` `immediate` (all read at `start`) `manual` `trigger` | `tick`(counter) `elapsed`(ms) `running` `trigger` | `start` `stop` `reset` `pause` `resume` (`stop`→`start` continues `tick`/`elapsed` — only `reset` zeroes) |
| **raf** | `<wcs-raf>` | `once` `repeat` (read at `start`) `manual` `trigger` `reduced-motion`(`"run"`(default)/`"pause"` — with `"pause"`, frame delivery stops while `prefers-reduced-motion: reduce` holds and resumes with a `dt = 0` boundary; opt-in because a tick is functional output, not decoration) | `tick` `elapsed` `dt` `running` `suspended`(two causes: hidden tab, or the engaged reduced-motion gate — counters freeze, `running` stays true) `trigger` — `elapsed` counts active time only, not wall-clock | `start` `stop` `reset` `pause` `resume` (`stop`→`start` continues counters — only `reset` zeroes; `pause` is user intent, the reduced-motion gate is environment — `resume` never overrides the OS preference) |
| **debounce** | `<wcs-debounce>` / `<wcs-throttle>` (`wcs-throttle:*` events) | `source` (value-surface input; NO same-value guard — every write restarts the wait, and the initial bind write starts a cycle: throttle emits `value` immediately at startup) `wait` `max-wait` `leading`(debounce: opt-in attr, default off; throttle: default on, opt-out `no-leading`) `trailing`(default on; opt-out `no-trailing` — a bare `trailing` attribute is inert) | `value`(settled value) `fired` `pending` | `trigger` `cancel` `flush` (commands — no momentary trigger property here) |
| **clipboard** | `<wcs-clipboard>` | `monitor` | `text` `items` `loading` `readPermission` `writePermission` `monitoring` `copied` `cut` (both carry the document selection text, not the clipboard payload) `pasted` | `writeText` `write` `readText` `read` `startMonitor` `stopMonitor` (write requires a user gesture) |
| **geolocation** | `<wcs-geo>` | `high-accuracy` `timeout` `maximum-age` `watch` `manual` `trigger` (attributes are read at connect time) | `position` `latitude` `longitude` `accuracy` `coords` `timestamp` `watching` `loading` `permission` | `getCurrentPosition` `watchPosition` `clearWatch` |
| **permission** | `<wcs-permission>` | `name` (one tag, one permission) `user-visible-only` `sysex` | `state`(granted/denied/prompt/unsupported) `granted` `denied` `prompt` `unsupported` | none (monitor-only) |
| **notification** | `<wcs-notify>` | `notice` (reactive display; guarded vs the LAST SHOWN text — first non-empty bind fires; the `notify` command bypasses the guard) `mode`(auto/constructor/sw) `body` `icon` `badge` `tag` `lang` `dir` `require-interaction` `silent` `renotify` `manual`(mutes reactive `notice`; `notify` still works) | `permission` `granted` `denied` `prompt` `unsupported` `clicked` `closed` `shown` | `request` `notify(title, options)` `close` `closeAll` — without `granted`, `notice`/`notify` silently no-op into `error`: call `request` first (for SW use, `wireNotificationClicks()` from `@wcstack/notification/sw`) |
| **intersection** | `<wcs-intersect>` | `target` (default = first child / selector / `self`; non-matching selector → silent no-op, `observing` false) `root` `root-margin` `threshold` (live — but ALL attribute changes are ignored while `manual`) `once` `manual` `trigger`(re-runs `observe`) | `entry` `intersecting` `ratio` `visible` (latched on first intersection) `observing` `trigger` | `observe` `reobserve` `unobserve` `disconnect` `reset` (after `once` fires the observer is disconnected — `reset` alone can't re-latch `visible`, use `reobserve`) |
| **resize** | `<wcs-resize>` | `target` `box` `round` (live — but ignored while `manual`; selector no-match = silent no-op) `once`(fires on the INITIAL size delivery = measure-once) `manual` `trigger`(re-runs `observe`) | `entry` `width` `height` `observing` `trigger` | `observe` `unobserve` `disconnect` |
| **wakelock** | `<wcs-wakelock>` | `active` (desired input — durable intent: a request while hidden waits and auto-re-acquires on return to visible) `type` `manual`(gates only the connect-time auto-acquire) | `held` (actual output; reflects OS release) | `request` `release` |
| **camera** | `<wcs-camera>` | `audio` `facing-mode` `device-id` `width` `height` (live: changing while active re-acquires with the new constraints) `autostart`(connect-time only) `keep-alive` | `active` `permission` `audioPermission` `deviceId` `devices` `streamReady` (raw MediaStream; RE-FIRES with a NEW stream on every re-acquire — switchCamera / constraint change / visibility resume — consumers must re-attach) `ended` | `start` `stop` `switchCamera` |
| **camera** | `<wcs-recorder>` | `mime-type` `timeslice` `audio-bits` `video-bits` (properties `audioBitsPerSecond`/`videoBitsPerSecond`; all read at `start`) | `recording` `paused` `duration` `mimeType` `blob` `objectURL` `recorded` `dataavailable` | `attachStream` `start` `stop` `pause` `resume` (`start` without an attached stream silently errors; re-attaching mid-recording applies to the NEXT `start` only) |
| **speech** | `<wcs-speak>` (TTS) | `say` (reactive speech; guarded vs the LAST SPOKEN text — first non-empty bind speaks) `rate` `pitch` `volume` `voice` `lang` `manual`(mutes reactive `say` — bind it to the listening flag to break the listen→speak echo loop) | `voices` `speaking` `paused` `pending` `charIndex` `spokenWord` `unsupported` | `speak` (imperative; fires even on same value) `cancel` `pause` `resume` |
| **speech** | `<wcs-listen>` (STT) | `lang` `continuous` `interim` `max-restarts`(`continuous` alone still ends at the first silence — set `max-restarts` > 0 to keep the session alive) `manual` `trigger` (options frozen while listening) | `interimTranscript` `finalTranscript` `result` `listening` `permission` `unsupported` `trigger` | `start` `stop` `abort` |
| **defined** | `<wcs-defined>` | `tags` `mode` `timeout` (timeout detects load failure; ALL inputs frozen at connect; empty `tags` → `error`, `defined` stays false) | `defined` `pending` `missing` `count` `total` `error` (invariant: total=count+pending+missing) | none (event-token only; monotonic; terminal) |
| **fullscreen** | `<wcs-fullscreen>` | `target` | `active` | `requestFullscreen` `exitFullscreen` |
| **picture-in-picture** | `<wcs-pip>` | `target` (must resolve to a `<video>` — otherwise `error`) | `active` | `requestPictureInPicture` `exitPictureInPicture` |
| **pointer-lock** | `<wcs-pointer-lock>` | `target` | `active` | `requestPointerLock` `exitPointerLock` |
| **screen-orientation** | `<wcs-screen-orientation>` | (no inputs) | `type` `angle` `portrait` `landscape` (the initial snapshot fires before bindings attach — read the starting orientation in `$connectedCallback`; bound outputs update from the next change) | `lock` `unlock` |
| **idle** | `<wcs-idle>` | `threshold`(default 60000; read at `start` only) | `userState` `screenState` `active` | `requestPermission`(needs a user gesture) `start` `stop` |
| **network** | `<wcs-network>` | (no inputs) | `effectiveType` `downlink` `rtt` `saveData` `supported` (Firefox/Safari: `supported` false, data fields `null` — bindings must handle null) | none (monitor-only) |
| **media-query** | `<wcs-media-query>` | `query` (the one input, mirrored from the attribute; **live** — changing it while connected tears down the old `MediaQueryList` subscription and subscribes to the new one, generation-guarded; removing it = watch nothing → `matched` false; an invalid query does not throw — `media: "not all"`, `matched: false`). No secure-context or permission requirement | `matched` `media` `supported` — all `state`, all derived from one `wcs-media-query:change` snapshot, so a query change that flips `media` and `matched` together arrives as one update. `matched` is a strict boolean (never `null`; `false` whenever there is no live list), `media` the browser-normalized string (`""` with no list), `supported` = `typeof matchMedia === "function"` resolved per subscription (Node/SSR: `false`). **The output is `matched`, not `matches`** — `Element.prototype.matches()` exists on every element. `:state(matched)` / `:state(supported)` are reflected for CSS | none (monitor-only) |
| **share** | `<wcs-share>` | (no inputs) | `value` `loading` `cancelled` (`value` is written only on success — stale after a cancel/failure, check `cancelled`) | `share` (invoking while `loading` is a silent no-op) |
| **contacts** | `<wcs-contacts>` | (no inputs) | `value` `loading` `cancelled` (same no-op-while-loading / stale-`value` rules as share) | `select` |
| **credential** | `<wcs-credential>` | (no inputs) | `value` `loading` `cancelled` (user cancel surfaces as `NotAllowedError`, not `AbortError`) | `get` `store` (they share one in-flight lane — a concurrent call supersedes and silently drops the first) |
| **eyedropper** | `<wcs-eyedropper>` | (no inputs) | `value` `loading` `cancelled` | `open` (a second `open` aborts the prior pick into `cancelled`) `abort` |
| **tilt** | `<wcs-tilt>` | (no inputs) | `alpha` `beta` `gamma` `absolute` `permissionState` | `requestPermission` `start` `stop` (iOS: `start` before `requestPermission` is silently dead — no events, no error) |
| **accelerometer** | `<wcs-accelerometer>` | `frequency` | `x` `y` `z` | `start` `stop` |
| **gyroscope** | `<wcs-gyroscope>` | `frequency` | `x` `y` `z` | `start` `stop` |
| **magnetometer** | `<wcs-magnetometer>` | `frequency` | `x` `y` `z` | `start` `stop` |
| **ambient-light-sensor** | `<wcs-ambient-light-sensor>` | `frequency` | `illuminance` | `start` `stop` |
| **midi** | `<wcs-midi>` | `input`(omitted = every input port; else port id or case-insensitive name prefix) `output`(omitted = first output port) `channel`(1-16; omitted = all — system messages always pass) `sysex`(a separate, more restricted grant — leave off) `auto`(connect + request on connect). `input`/`output`/`channel` are live: they **re-hook the existing access**, never re-request, so no second permission prompt | `message` `type` `channel` `note` `velocity`(**normalized 0-1**) `control`(raw 0-127) `value`(raw 0-127, but **-1..1 for pitch bend**) `devices` `connected` `permission` `granted` `denied` `unsupported` `error` `errorInfo` | `request` `close` `send` |
| **audio** | `<wcs-audio>` — the patch root | `volume` `limiter`(on by default at -18 dBFS as ear protection; `limiter="off"` to measure real amplitudes) `resume-on-gesture`(default on; `"off"` = drive it yourself with `command.resume`). Bound from state as booleans (`limiter: on`), the setter writes `"on"` / `"off"` | `state`(running/suspended/unsupported) `running` `suspended` `unsupported` `voices` `noteOn` `noteOff` `warnings` `error` `errorInfo` | `resume` `suspend` `noteOn(note, velocity)` `noteOff(note)` `allNotesOff` |
| **audio** | node tags `<wcs-osc>`(`type` `frequency` `detune` `glide` `transpose`) `<wcs-noise>` `<wcs-biquad>`(`type` `frequency` `q` `gain` `detune`) `<wcs-gain>`(`gain`) `<wcs-delay>`(`time` `feedback` `mix`) `<wcs-shaper>`(`amount`) `<wcs-env>`(`attack` `decay` `sustain` `release` `depth`) `<wcs-lfo>`(`type` `rate` `depth`) | every numeric attribute above is a bindable input and is **live**; the routing attributes `id` / `out` / `param` / `note` / `master` and `<wcs-voice poly>` are **structural** (a change rebuilds the graph) and are deliberately NOT bindable | none — a node tag is a pure input surface (everything observable belongs to `<wcs-audio>`) | none |
| **audio** | `<wcs-analyser>` | `fft` `smoothing` (+ structural `master`) | `frame` (occurrence — `sample()` returns a **freshly allocated** array, so retaining a frame is safe) | `sample(mode)` — `"wave"` (default) or `"fft"`. It produces data only; drawing is your canvas's job |

### 1.1 `@wcstack/audio` is a graph, not a value (read before writing a patch)

The audio package does not follow the `manual` / `trigger` idioms above — it has a shape of its own:

- **Nesting is the signal chain.** A parent tag's output feeds each nested child; a leaf (no chain children, no `out`) reaches the master output. Anything nesting cannot express is routed by id: `out="bus"` (many-to-one), `out="vcf.frequency"` (drive any `AudioParam`), `param="frequency"` (modulator shorthand for the *parent's* parameter).
- **`<wcs-voice poly="8">` makes its subtree a template** — one fresh graph per held note, with release tails and oldest-note stealing. Outside a voice the graph is live and monophonic.
- **Structure is declared, values are reactive.** Numeric attribute/property writes apply live to every instance including sounding voices; structural attributes (`id` `out` `param` `note` `master` `poly`), and adding/removing/moving an audio tag, **rebuild — which cuts every sounding voice audibly**. Any other DOM change does nothing (a `<div>` added among your sliders must not silence the instrument). Rebuilds coalesce onto a microtask and an unchanged re-submit is free.
- **Writes are accepted synchronously; when they become *audible* is deliberately unspecified** (render quantum + output latency are hardware-dependent). Parameter changes are smoothed over ~20 ms as part of the contract, and the effective value is never read back — a getter returns what you last wrote. This is the cross-cutting rule for any node with an external clock.
- **Audio cannot start before a gesture.** `<wcs-audio>` resumes the shared context on the first click/keypress. The `AudioContext` is shared page-wide (browsers cap concurrent contexts); each root keeps its own master gain and limiter.
- **A voice patch with no `<wcs-env>`** gets an implicit 5 ms attack so it cannot click, and is released on note-off. Voices are reclaimed on the audio clock, never on a timer.
- **Headless**: `new AudioGraphCore()` + `setPatch({nodes:[…]})` takes the same descriptor as a plain object; pass your own `createContext` to render into an `OfflineAudioContext` (no gesture, faster than realtime, deterministic). SSR renders nothing and reports `unsupported`.

### 1.2 `<wcs-view-transition>` is a policy node, not an I/O node

`@wcstack/view-transition` renders nothing, binds no data, and describes no animation — it decides *whether* a DOM change animates and what a collision does; the animation stays in CSS (`::view-transition-*`). **Enter animations never need it** (`@starting-style` on the inserted element); it exists for **leave and move**, which CSS cannot reach (wcstack detaches removed nodes synchronously; a reorder has no intermediate state).

- **Inputs**: `for`(`router` / `state`, space-separated; default both) `mode`(`latest`(default: skip the running transition, animate the newcomer) / `queue` / `exhaust`(apply immediately, drop only the animation)) `naming`(`manual`(default: you bind `style.viewTransitionName`) / `auto`(state names every list row and `if` branch, with `view-transition-class` `wcs-row` / `wcs-branch` for group CSS)) `naming-limit`(default 200) `reduced-motion`(`skip`(default — honors `prefers-reduced-motion` by applying without animating) / `animate`) `types` `disabled`(bindable — a page can switch animation off from state). **Outputs**: `active` `error`. **Commands**: `skip()` (finish the running transition now; its DOM change still lands).
- **The rule everything is subordinate to: a DOM change is applied exactly once, whatever happens to its animation** — unsupported browser, hidden tab, reduced motion, `disabled`, collision, or a throwing `startViewTransition` all still end with the change applied.
- **One per document** (a second warns and stays inert). Requests in the same microtask join one transition (a route change and the state drain it triggers animate together).
- **`for="state"` (on by default) makes the state drain land on a frame** instead of a microtask — and flips the mechanism order to `$watch` → `$stream` restart → `$renderedCallback` (see `state-binding.md` §10). Code that writes state then reads the DOM after `await Promise.resolve()` must wait for the transition. `for="router"` keeps state timing untouched. Participation is per document, not per element.

## 2. Minimal state-integration examples for high-frequency nodes (from each README)

**fetch** — a computed URL drives the fetch (auto re-runs on url change; aborts any in-flight request):
```html
<wcs-fetch data-wcs="url: usersUrl; value: users; loading: listLoading; error: listError"></wcs-fetch>
<ul><template data-wcs="for: users"><li data-wcs="textContent: users.*.name"></li></template></ul>
```

**storage** — two-way persistence of primitive values. The bound state slot is **intentionally initialized to `undefined`** (`""`/`null` would overwrite the stored value on the initial write-back = load-before-bind idiom):
```html
<wcs-storage key="username" data-wcs="value: username"></wcs-storage>
<input data-wcs="value: username">
```
Declarative alternative: `data-wcs="value#init=element: username"` — the element's persisted value wins the initial sync regardless of the slot's seed, then normal two-way write-back resumes.
**Several inputs, one key (the storage README canonical form)**: give the state an **accessor pair** and bind it with `value#init=element` — `get formSnapshot() { return { name: this["form.name"], email: this["form.email"] }; }` / `set formSnapshot(v) { if (v) this.form = { ...this.form, ...v }; }` + `<wcs-storage key="signup-form" data-wcs="value#init=element: formSnapshot">`. On load the stored object goes through the setter once (`null` for an empty key, which then seeds it), typing a field dirties the getter and saves the new object, and the save's own `value` event is recognized as the write confirmation. **Read the fields as `this["form.name"]`, never `this.form.name`** — the latter tracks `form` only, so editing never re-evaluates the getter (`state-binding.md` §6). The on-demand variant — `manual` + a getter of `$dependOn` calls bound to `trigger:` — remains for saving at a moment of your choosing.

**websocket** — receive via `message`; to send, just write a value to `send`:
```html
<wcs-ws url="wss://example.com/ws"
  data-wcs="message: lastMessage; connected: isConnected; send: outgoing"></wcs-ws>
<!-- state side: sendChat() { this.outgoing = { type: "chat", content: this.chatInput }; } -->
```

**timer** — declarative `setInterval` equivalent:
```html
<wcs-timer interval="1000" data-wcs="tick: count; running: isRunning"></wcs-timer>
<!-- one-shot: <wcs-timer interval="3000" once data-wcs="tick: showBanner"> — to bind `once` from state, write `.once: flag`; `once:` without the dot is an event binding -->
```

**media-query** — a media query as a boolean in state, for the cases where the answer has to reach *logic* rather than a stylesheet (a theme default, pausing a loop under `prefers-reduced-motion`, swapping a table for cards below a breakpoint, `(display-mode: standalone)` for a PWA); a styling-only query stays in CSS `@media`:
```html
<wcs-media-query query="(prefers-color-scheme: dark)" data-wcs="matched: isDark"></wcs-media-query>
<main data-wcs="attr.data-theme: theme">…</main>   <!-- get theme() { return this.isDark ? "dark" : "light"; } -->

<wcs-media-query query="(max-width: 600px)" data-wcs="matched: narrow"></wcs-media-query>
<template data-wcs="if: narrow"><ul data-wcs="for: rows">…</ul></template>
<template data-wcs="if: narrow|not"><table>…</table></template>
```
One tag, one query — compose several elements for several queries. The first `wcs-media-query:change` fires synchronously during `connectedCallback`, before state has attached its listeners, and events are not replayed; the value still arrives because every output here is output-only, which makes the default binding authority `element` — the binding **reads the property when it attaches** (directional initial sync, on by default). Only in a state that declares `$behavior: { enableDirectionalInitialSync: false }` is a manual `$connectedCallback` pull needed. `matched` is never `null`, so `|not` is safe. Any node's commands can be driven from it, but for `<wcs-raf>` under `prefers-reduced-motion` prefer its own `reduced-motion="pause"` attribute.

**intersection** — lazy loading (`visible` is latched on first intersection; `once` disconnects):
```html
<wcs-intersect once data-wcs="visible: shown">
  <img data-wcs="src: src" alt="lazy">
</wcs-intersect>
<!-- infinite-scroll edge detection: <wcs-intersect target="self" data-wcs="intersecting: atEnd"> -->
```

**Paginate from the feed's length, not `page++`.** `<wcs-intersect>` reports that visibility *changed*; it cannot schedule, and it has no "qualified re-entry" event. `examples/state-intersect-scroll` is built around a `$stream` entry that owns the page fetch, and the shape it landed on is the one to copy:

- **Derive the requested page from what the feed already holds** — `page = floor(feed.items.length / pageSize) + 1`, written by the sentinel's `$on` handler — instead of incrementing on each edge. Under `$stream`' switchMap restart a blind `page++` is *wrong*: a second edge would abort page N in flight and jump to N+1, silently skipping a page. With the derived form, edges arriving while page N is active or failed write the same primitive, the same-value guard makes the enqueue a no-op, and the stream does not restart. That replaces the hand-written `if (loading) return` exhaust gate entirely. **Keep `page` a plain property**: a getter derived from `feed` and read by the stream's `args` would restart the stream on its own result and load every page with no sentinel.
- **The producer owns retry.** `$stream` is switchMap, not `retryWhen` — no automatic reconnection. Put a finite `1 + maxRetries` attempt loop and an abort-aware delay inside the async generator; final failure surfaces as `$streamStatus.<name> === "error"` + `$streamError.<name>`. Yield the success as `{ kind: "success", page, pageSize, items }` — `pageSize` rides on the success chunk so the fold needs only `feed` and the chunk.
- **"Run the same page again" is an occurrence, and the restart API is value-based** — encode it as a changing dependency (`retryNonce`) read by `args`. A Retry button increments it. This is a real boundary of the current API, not a workaround you can skip.
- **`reobserve()` only after a full page lands**, never on error — from a `$watch` on the feed (below): with the sentinel still visible, a new observer's first callback fires immediately, so error layout becomes an infinite retry scheduler. A partial page sets `feed.noMore` in the fold instead.
- **The feed is a plain key, folded by a `$watch` on the stream's value.** A stream's `fold` resets to `initial` on every restart, so it can only hold the current page; the value that outlives page runs is a key you seed and write (`state-binding.md` §15):

  ```javascript
  feed: { items: [], pages: [], noMore: false },
  $watch: {
    pageResult(chunk) {                          // fires on every landing; nothing has to be bound
      if (chunk?.kind !== "success") return;     // progress chunks and the restart's reset
      const feed = this.feed;
      if (feed.pages.includes(chunk.page)) return;   // page key
      this.feed = { items: feed.items.concat(chunk.items), pages: [...feed.pages, chunk.page],
                    noMore: chunk.items.length < chunk.pageSize };
    },
    feed(feed) { if (!feed.noMore) this.$command.rearm.emit(); },   // re-arm after a full page
  },
  ```

  Bind `for: feed.items` / `if: feed.noMore`. `feed` survives restarts and reconnects and needs nothing bound, so the visible meter stays display-only. **The page key is not optional**: the watch fires once per *landing*, not once per page, and a Retry after `done` (`retryNonce`) or a re-attached page lands the same page again. Commit-before-reobserve is the mechanism order — the `pageResult` watch writes `feed` in one batch, and the `feed` watch fires at the end of the next, after the new rows render (without a `<wcs-view-transition>` accepting `state`; with one, bindings apply on a frame and the watch runs first — `state-binding.md` §10). The status mirror (`get streamStatus() { return this["$streamStatus.pageResult"]; }` plus a `$watch` on it — a `$watch` key cannot start with `$`) remains only to record when an error settles, for the scroll-retry qualification. The demo in this form passes the same e2e suite on 3.4.0, 3.5 and the 4.0 engine. There is no `$scan` in 4.0: an older page's `$scan: { feed: { from: "pageResult", … } }` is exactly the `$watch` above (`state-binding.md` §16).

**clipboard** — copy via command-token (write requires a user gesture):
```html
<wcs-clipboard data-wcs="command.writeText: $command.copy"></wcs-clipboard>
<button data-wcs="onclick: onShare">Share</button>
<!-- state side: $commandTokens: ["copy"], onShare() { this.$command.copy.emit(this.message); } -->
```
Read with `command.readText: $command.paste; text: pasted`; monitor with the `monitor` attribute + `eventToken.pasted: ...`.

**notification** — command-token (display) and event-token (click) coexist on one tag:
```html
<wcs-notify data-wcs="
  command.request: $command.request;
  command.notify:  $command.notify;
  eventToken.clicked: opened"></wcs-notify>
<!-- state side: $commandTokens:["request","notify"], $eventTokens:["opened"],
     send() { this.$command.notify.emit("New message", { body:"...", tag:"chat", data:{room:7} }); },
     $on: { opened: (state, event) => { /* event.detail = {tag,data,action} */ } } -->
```
The reactive form binds the `notice` attribute (with same-value suppression; recommend debounce + `tag` to prevent spam).

**camera/recorder** — a raw MediaStream never enters state; wire elements directly to each other:
```html
<wcs-camera data-wcs="eventToken.streamReady: streamReady"></wcs-camera>
<wcs-recorder data-wcs="command.attachStream: $command.attachStream"></wcs-recorder>
<!-- $on: { streamReady: (state, ev) => state.$command.attachStream.emit(ev.detail) } -->
```
`streamReady` re-fires with a new stream on every re-acquire (switchCamera / constraint change / visibility resume) — this `$on` wiring re-attaches each time. Start the recorder only after a stream is attached (a stream-less `start` silently errors).

**defined** — a declarative readiness gate over tags whose load order you do not control (the correct replacement for `await customElements.whenDefined()` in a handler):
```html
<wcs-defined tags="wcs-tilt,wcs-accelerometer" timeout="5000"
  data-wcs="defined: sensorsReady; pending: sensorsPending; missing: sensorsMissing"></wcs-defined>
<button data-wcs="onclick: startGame; disabled: sensorsResolving; textContent: startLabel"></button>
<!-- state side: sensorsPending seeded with the tag list (so the control is held on first paint),
     get sensorsResolving() { return this.sensorsPending.length > 0; } -->
```
Gate on **`pending`**, not `defined`: `timeout` moves a never-arriving tag to `missing`, which releases the control into a degraded mode instead of locking the user out; a late arrival is still promoted out of `missing`, so a merely slow CDN self-heals. Outputs are monotonic and terminal, and all inputs are frozen at connect.

**midi** — one tag covers both directions (a page holds exactly one `MIDIAccess`). Take notes off the occurrence surface, not off a property:
```html
<wcs-midi auto channel="1" data-wcs="eventToken.message: onMidi; control: cc; value: ccValue"></wcs-midi>
<!-- $eventTokens: ["onMidi"],
     $on: { onMidi: (state, ev) => { const { type, note, velocity } = ev.detail; ... } } -->
```
Nothing starts on connect unless `auto` is set — `requestMIDIAccess()` can prompt — so otherwise fire `command.request` from a gesture. Two normalizations are already applied for you: **a note-on with velocity 0 is reported as `noteoff`** (many controllers never send a real note-off; the raw status byte stays in `message.data[0]`), and **velocity is 0-1** so it multiplies straight into a gain. Chromium-only and secure-context-only — elsewhere `permission` is `"unsupported"` rather than a throw. Device names are not unique; prefer ids when targeting a specific unit.

**audio** — structure in markup, numbers from state; commands carry the notes:
```html
<wcs-audio volume="0.7"
  data-wcs="command.noteOn: $command.play; command.noteOff: $command.stop; voices: activeVoices">
  <wcs-voice poly="8">
    <wcs-osc type="sawtooth" note detune="-7" out="vcf"></wcs-osc>
    <wcs-biquad id="vcf" type="lowpass" data-wcs="frequency: cutoff; q: resonance">
      <wcs-lfo type="sine" rate="4" param="frequency" data-wcs="depth: lfoDepth"></wcs-lfo>
      <wcs-env attack="0.01" decay="0.25" sustain="0.55" release="0.35" out="bus"></wcs-env>
    </wcs-biquad>
  </wcs-voice>
  <wcs-gain id="bus" gain="0.8"><wcs-delay time="0.28" feedback="0.35" mix="0.2"></wcs-delay></wcs-gain>
</wcs-audio>
<input type="range" min="80" max="8000" data-wcs="value: cutoff">
<!-- $commandTokens: ["play","stop"];  this.$command.play.emit(60, 0.9) -->
```
Bind only the numeric params (§1.1) — writing a structural attribute from state rebuilds the graph and cuts every sounding voice. To draw a scope, drive `<wcs-analyser>` from `<wcs-raf>` through the command/event tokens rather than owning a rAF loop:
```html
<wcs-raf data-wcs="eventToken.tick: onTick"></wcs-raf>
<wcs-analyser id="scope" master
  data-wcs="command.sample: $command.grab; eventToken.frame: onFrame"></wcs-analyser>
```

## 3. signals Quick Reference (`@wcstack/signals`)

### Positioning (when to use vs state)

- `@wcstack/state` connects UI and state through **HTML path strings** (`data-wcs`); no reactive primitives appear in code. `@wcstack/signals` conversely **exposes signal/computed/effect directly** (no DSL, no `data-wcs`). The two are not competitors — they **coexist**.
- Out of scope for signals v1: SSR/hydration, deep/proxy reactivity (path-based deep tracking is state's territory), stream backpressure.
- The API is a minimal in-house implementation modeled on the TC39 Signals proposal.

### CDN loading (one-entry-per-page rule)

```html
<script type="importmap">
{ "imports": { "@wcstack/signals/dom": "https://esm.run/@wcstack/signals/dom" } }
</script>
<script type="module">
  import { signal, computed, effect, h, render, For, bindNode, mountNode } from "@wcstack/signals/dom";
</script>
```

> **Known trap**: on the CDN each entry is a self-contained bundle with the core embedded, so importing both `@wcstack/signals` and `@wcstack/signals/dom` on one page causes **reactive core duplication** and reactivity breaks at the seam. On CDN pages import everything from the single `/dom` entry (`/dom` re-exports the entire core). No such constraint with local npm / bundlers.

### Basic API (core)

```js
const count = signal(0);                       // .get()=read+track / .peek()=no tracking / .set(v)
const doubled = computed(() => count.get() * 2); // lazy, memoized, equality short-circuit
effect(() => { console.log(doubled.get()); });   // runs immediately once, then coalesced into a microtask
count.set(1);        // effect re-runs on the next microtask
flushSync();         // synchronous flush (when reading DOM back in tests)
createRoot((dispose) => { /* effects/resources inside are disposed all at once by dispose */ });
onCleanup(fn);       // register cleanup on the current owner
```

### DOM layer (`h` / `render` / `SignalsElement`)

`h(tag, props, ...children)` builds real DOM once; only function/signal props and children update via individual effects (no VDOM). `onXxx` props are event listeners. For custom elements, extend `SignalsElement` and implement only `render()` (mounts on connect; disposes all effects on disconnect).

### Keyed lists — `For` / `Index`

```js
const todos = signal([{ id: 1, text: "a" }, { id: 2, text: "b" }]);
h("ul", null, For(todos, (t, index) => h("li", null, () => `${index()}: ${t.text}`), { key: (t) => t.id }));
// for primitive arrays use Index: each is (item: () => T, index: number)
h("ul", null, Index(nums, (n) => h("li", null, () => String(n() * 2))));
```

A plain reactive child (`() => items.map(render)`) regenerates everything on every change, so always use For/Index for lists. Key default is `===`; duplicate keys throw. `each` returns a single Node.

### Async — `resource` / `streamResource`

```js
const user = resource(
  async (userId, signal) => (await fetch(`/api/users/${userId}`, { signal })).json(),
  { args: () => id.get() },  // when a signal read inside args changes → abort the previous run and restart (switchMap)
); // user.value / user.loading / user.error are read-only signals

const log = streamResource((args, signal) => openLogStream(signal), {
  fold: (acc, chunk) => [...(acc ?? []), chunk], initial: [],
}); // log.value / log.status ("idle"|"active"|"done"|"error") / log.error. No backpressure; keep fold bounded
```

Strong contract: `source` must always honor the `AbortSignal` it is passed (this is what drives restart/dispose).

### wc-bindable bridge — `bindNode` (turn I/O nodes into signals)

```js
const bound = bindNode(fetchEl);              // descriptor is auto-derived from constructor.wcBindable
bound.signals.value.get();                    // output property → read-only signal (same-value guard)
bound.on("fired", { fold, initial });         // event-token stream (fires every time, even on same value)
bound.set("url", v);                          // imperative write to an input
bound.bindInput("url", someSignal);           // reactive reflection of signal → input (loops are guarded)
bound.command("fetch", ...args);              // invoke a command
bound.bindCommand("start", trigger, mapArgs); // invoke command on trigger change (does not fire on the initial value)
bound.dispose();                              // tear down everything (idempotent; inert afterwards)
```

Typing via `bindNode<FetchShape>(el)`. Real-world pattern: `effect(() => bound.set("url", ...))` for the query → `<wcs-fetch>` auto-fetches → read `bound.signals.value` in a `computed` and render with `For` (examples/signals-live-search).

**What a property signal receives** (`bound.signals.x` and `bound.on("x")`): `getter(event)` from the descriptor, and when `getter` is omitted the wc-bindable default `(e) => e.detail` — the same rule as a `data-wcs` two-way binding, so an element behaves identically under `state` and `signals` (fixed in wcstack#238; earlier signals releases read the element property instead). The initial seed is the one property read (`el[name]`, there is no event yet). Every wcs-* node dispatches its value as `detail`, so nothing changes for them; a third-party element whose `detail` is not the property value (`detail: { value }`, or no `detail`) needs an explicit `getter: (e) => e.target.value` in the descriptor you pass to `bindNode`.

**`bindNode` is synchronous, so the class must already be registered when you call it** — it reads the descriptor from `el.constructor.wcBindable`, and an un-upgraded element has none (it throws). This is the structural asymmetry with `data-wcs`: the declarative layer can defer wiring until upgrade, an imperative API that returns values now cannot. Pick the idiom by who loads the node (`docs/signals-definition-timing.md`):

| Situation | Idiom | Failure behavior |
|---|---|---|
| App loads a **required** node | side-effect `import "@wcstack/<pkg>/auto"` + `mountNode(tag)` | module-graph evaluation failure — loud, correct for a node the app cannot run without |
| App loads an **optional** node | `import("@wcstack/<pkg>/auto").then(() => mountNode(tag)).catch(degrade)` | `import()` **rejects** on load failure — a real per-package failure boundary |
| A tag **you do not load** (autoloader, mixed state+signals page, third-party script) | `await customElements.whenDefined(tag)` then `bindNode(el)`, or a `<wcs-defined>` gate | `whenDefined` **never rejects** — pending forever; use `<wcs-defined timeout>` when the UX needs a failure signal |
| Pure-logic node, **JS only** (no element, no `:state()`, no state coexistence) | `bindNode(new XxxCore())` | plain import semantics — **the registry is not involved, so definition timing does not exist** |

`whenDefined` is the last resort for tags you do not own, not the default recipe — no `whenDefined` call remains in any repo demo. **Split static vs dynamic import by what is lost when that import fails**, not by convenience: the first pass at converting `signals-tilt-maze` put `wakelock` on the static import, and one decorative package's CDN failure blanked the entire page again — exactly the failure mode the conversion was meant to remove. Only a node the app cannot exist without belongs on a static import; everything else takes the `import().then(mountNode).catch(degrade)` form (with a `Promise.race` timeout if the UX needs a deadline).

### `mountNode` — create + bind + mount a headless node (`@wcstack/signals/dom`)

```js
import "@wcstack/fetch/auto";                 // defines <wcs-fetch>; the module graph guarantees the order
import { mountNode } from "@wcstack/signals/dom";

const fetcher = mountNode("wcs-fetch", { attrs: { url: "/api/people" } });
fetcher.signals.value.get();                  // the full BoundNode surface
fetcher.el;                                   // the created element (connected)
fetcher.unmount();                            // dispose() + remove the element (idempotent)
```

On a buildless page the side-effect import is what carries the ordering guarantee, so it has to be a real `import` inside the module — add `"@wcstack/fetch/auto": "https://esm.run/@wcstack/fetch/auto"` to the import map (or import the full URL directly). A `<script src=".../auto">` tag in `<head>` also works because module scripts execute in document order, but then the guarantee lives in the HTML rather than in the module graph.

Signature: `mountNode(tagName, { attrs?, parent?, descriptor? })` → `BoundNode & { el, unmount() }`. The internal order **is** the contract: create → set `attrs` → `bindNode` → connect. Attributes land before `connectedCallback` (shells read their config there) and the adapter subscribes before connect, so an event fired from `connectedCallback` cannot be missed. `attrs` follow HTML boolean semantics (`true` → empty attribute, `false` → omitted, everything else stringified); `parent` defaults to `document.body`; the tag name is lower-cased for you. An undefined tag throws a descriptive error immediately instead of hanging. Like `bindNode` it is not tied to a reactive owner — tear down explicitly, or compose `onCleanup(() => m.unmount())`. On a `MountedNode`, **`dispose()` is an alias of `unmount()`** (it owns the element's lifecycle, so the familiar verb never leaves a connected element with live I/O behind).

### Binding a Core directly — no element at all (normative)

Every I/O node splits into a framework-agnostic **Core** and a custom-element **Shell**, and the Core alone is a complete wc-bindable node: it extends `EventTarget`, dispatches on itself by default (`constructor(target?)`, `target ?? this`), exposes observables as public getters, and carries `static wcBindable` — so `bindNode` resolves the descriptor with no second argument:

```js
import { FetchCore } from "@wcstack/fetch";
import { bindNode } from "@wcstack/signals/dom";

const core = new FetchCore();
const bound = bindNode(core);   // descriptor from FetchCore.wcBindable — no element involved
core.fetch("/api/user");        // commands are plain methods
bound.signals.value.get();
```

This surface is normative across every wcstack I/O node (`docs/async-io-node-guidelines.md` §3.9 — audited at 38 Cores, zero deviations; the audit predates v1.25's `AudioGraphCore` / `MidiCore`, both of which ship the same shape) and semver-protected: entry export, `EventTarget` inheritance, self-dispatch default, `static wcBindable`, getter-readable observables, `observe()`/`dispose()`/`ready`, never-throw, and headless construction (`target` always optional). Constructor **config** arguments stay per-package — check that package's README. Trade-off: you drive the lifecycle yourself (`observe()`/`dispose()` or the start/stop commands, e.g. `onCleanup(() => core.dispose())`), and you give up attribute config plus `:state()` CSS reflection (a Shell/ElementInternals feature). Fits pure-logic nodes (fetch / websocket / sse / broadcast / timer / debounce / defined / raf …); element-coupled nodes (intersection & resize targets, camera preview, fullscreen / pip / pointer-lock) keep earning their Shell.

### Stability

The core (signal/computed/effect/createRoot/onCleanup/flushSync) and resource/streamResource are **Stable**. `bindNode`/`nodeSource` and the DOM layer (h/For/Index/SignalsElement/`mountNode`) are **Evolving** (may change in minor releases).