tutuca 0.11.2 → 0.12.0

package/skill/tutuca/patterns/file-input.md

@@ -0,0 +1,39 @@
+# Read a picked file
+
+**Problem:** let the user pick a file and show its metadata.
+
+```js
+component({
+  name: "FilePicker",
+  fields: { name: "", size: 0, type: "", hasFile: false },
+  receive: {
+    // e.target is the <input> node; the File is on e.target.files
+    onPickFile(draft, target) {
+      const file = target.files?.[0];
+      draft.hasFile = !!file;
+      if (!file) return;
+      draft.name = file.name;
+      draft.size = file.size;
+      draft.type = file.type;
+    },
+  },
+  view: html`<section>
+    <input type="file" @on.change="onPickFile e.target" />
+    <p @hide=".hasFile">No file selected yet.</p>
+    <dl @show=".hasFile">
+      <dt>Name</dt><dd @text=".name"></dd>
+      <dt>Size</dt><dd @text=".size"></dd>
+      <dt>Type</dt><dd @text=".type"></dd>
+    </dl>
+  </section>`,
+});
+```
+
+Pass `event` (not `value`) to the handler: for a file input `value` is just the
+fake `C:\fakepath\…` string, while `event.target.files` holds the real `File`
+objects. The metadata (`name`/`size`/`type`/`lastModified`) is available
+synchronously; the *contents* are not — read those with the async `File` API
+(`file.text()`, `file.arrayBuffer()`) and feed the result back in through a
+an `intent` or a follow-up `send`. Flatten what you need into fields so
+the view can bind each piece; gate the summary on a `hasFile` flag with
+`@show`/`@hide`.

package/skill/tutuca/patterns/filter-a-list.md

@@ -0,0 +1,25 @@
+# Filter a list
+
+**Problem:** render only the items that match a condition.
+
+```html
+<li @each=".items" @when="filterItem">
+  <span @text="@key"></span>: <x text="@value"></x>
+</li>
+<!-- on <x render-each> the same directive applies: @when="filterItem" -->
+```
+
+```js
+alter: {
+  filterItem(_key, item) {
+    return item.toLowerCase().includes(this.query.toLowerCase());
+  },
+}
+```
+
+`@when` names an `alter` handler called per item as `(key, value, iterData)`;
+return `false` to skip. It filters *after* any `@loop-with` slice, so a page
+can yield fewer than its window. Filtering reads other fields off `this`
+directly (`this.query`) — there are no paths in the template. To filter
+*before* paging, return `keys` from `@loop-with` instead — see
+[filter-and-paginate.md](filter-and-paginate.md).

package/skill/tutuca/patterns/filter-and-paginate.md

@@ -0,0 +1,60 @@
+# Filter and paginate a list
+
+**Problem:** show one page of the items that match a query — filtering
+*before* paging, so page counts reflect the filtered total and a row's
+identity survives editing or deleting across pages — without scanning the
+list more than necessary.
+
+```html
+<section @enrich-with="pageInfo">          <!-- COUNT pass: runs once -->
+  <input :value=".query" @on.input="search e.value" />
+  <li @each=".items" @when="onlyMatches" @loop-with="page">  <!-- COLLECT pass -->
+    <span @text="@key"></span> <x render-it></x>
+    <button @on.click="removeInItemsAt @key">✕</button>
+  </li>
+  <button :disabled="@isFirst" @on.click="prev">‹</button>
+  <button @text="@pageLabel"></button>
+  <button :disabled="@isLast" @on.click="next">›</button>
+</section>
+```
+
+```js
+methods: { matchCount() { /* one scan: how many match this.query */ } },
+alter: {
+  onlyMatches(_key, p) { return matches(p, this.query); },   // the predicate
+  pageInfo() {                                  // scope enrich: the COUNT scan
+    const total = this.matchCount();
+    const { pageCount, currentPage } = clamp(this.page, total, this.pageSize);
+    return { currentPage, isFirst: currentPage <= 0, isLast: currentPage >= pageCount - 1,
+             pageLabel: `Page ${currentPage + 1} of ${pageCount} · ${total}` };
+  },
+  page(seq, { lookup, filter }) {               // @loop-with: the COLLECT scan
+    const start = lookup("currentPage") * this.pageSize, end = start + this.pageSize;
+    const keys = [];
+    let m = 0;
+    for (let i = 0; i < seq.size && m < end; i++)   // early-exit: stops at page end
+      if (filter(i, seq.get(i))) { if (m >= start) keys.push(i); m++; }
+    return { keys };
+  },
+},
+```
+
+Returning **`keys`** (ordered *original* keys) is what makes this work: the
+renderer visits exactly those and does **not** re-apply `@when`, and because
+`@key` stays the original index, deleting row `@key` on page 2 of a filtered
+view hits the right item. The page controls live *outside* the loop, so they
+can't read its `iterData`; instead a scope `@enrich-with` does the one counting
+scan and publishes the clamped page + labels as `@`-bindings. The `@loop-with`
+handler's `ctx` lets it avoid repeating that work: `ctx.lookup` reads the
+clamped page the enrich already computed, and `ctx.filter` reuses the declared
+`@when` predicate — so the collect pass scans just far enough to fill the page.
+Reset `page` to 0 when the query changes.
+
+This is one of three wiring strategies (naive two-scan, shared, coupled
+one-scan) — the trade-offs and the other two are in
+[iteration.md](../iteration.md) *Filter-then-paginate strategies*. Test
+whichever wiring with `collectIterBindings` — pass
+`{ when, loopWith, scopeEnrich }` and assert on the returned keys; see
+[testing.md](../testing.md) *Testing iteration handlers*. See
+[filter-a-list.md](filter-a-list.md) and
+[paginate-a-list.md](paginate-a-list.md) for each half on its own.

package/skill/tutuca/patterns/handle-events.md

@@ -0,0 +1,44 @@
+# Handle events
+
+**Problem:** respond to a DOM event and update state.
+
+```html
+<button @on.click="inc">+</button>
+<button @on.click="dec">-</button>        <!-- bare name = receive handler -->
+
+<!-- pass args by name; ctx is auto-appended last -->
+<input @on.input="setStr e.value" />
+<input @on.input="setN e.valueAsInt" />
+<button @on.click="addItem JsonSelector">+</button>
+
+<!-- guards: keydown +send (Enter) / +cancel (Esc), and +ctrl/+cmd/+alt -->
+<input @on.keydown+send="submit e.value" @on.keydown+cancel="reset" />
+
+<!-- effects on any event: +prevent, +stop (applied only if the guards passed) -->
+<form @on.submit+prevent="save">…</form>
+
+<!-- custom elements: any CustomEvent reaches @on.<name>, detail is `e.value` -->
+<emoji-picker @on.emoji-click="onPick e.value"></emoji-picker>
+```
+
+Event handlers are entries in `receive`: Tutuca passes an Immer draft first,
+the written arguments next, and `ctx` last. Returning nothing commits draft
+changes; returning another component swaps the current component. The first
+slot in `@on.*` is always a bare receive name; `$method` is rejected. Later slots always carry a sigil — event-member reads (`e.value`,
+`e.key`, `e.altKey`, `e.target`, dotted paths like `e.target.dataset.slot`
+or `e.detail.x`, null-safe at every link), one-level computed conveniences
+(`e.valueAsInt`, `e.isCtrl` mac-aware, and on drags `e.dragInfo`/
+`e.dragKey`/`e.dragValue`/`e.dragType`), state fields (`.field`), bindings
+(`@bind`), methods (`$m`), dynamics (`*dyn`). A sigil-less word fails to
+parse.
+`e.value` normalizes the read: `.checked` for a checkbox, `detail` for a
+`CustomEvent`, otherwise `target.value`. Bind events declaratively with `@on.`
+rather than reaching for the node and `addEventListener` — an outside listener
+bypasses the transactor.
+
+Pass the most granular arg the handler needs — `e.value`/`e.valueAsInt`/`e.key`,
+not the raw event object — so tests call it with plain literals; reach for
+`e.target` only when nothing narrower fits (e.g. a file input reading
+`e.target.files`).
+Why this keeps tests simple: [testing.md](../testing.md) *Designing handlers so
+tests stay simple*.

package/skill/tutuca/patterns/iterate-a-list.md

@@ -0,0 +1,18 @@
+# Iterate a list
+
+**Problem:** render one element per item in a list/map field.
+
+```html
+<!-- a host element per item: @key and @value are bound in the loop -->
+<li @each=".items"><span @text="@key"></span>: <x text="@value"></x></li>
+
+<!-- a child component per item -->
+<x render-each=".items"></x>
+<div @each=".items"><x render-it></x></div>
+```
+
+`@each` accepts a `.field` or a `*dynamic` (not a `$method` — a method result
+has no addressable path for event dispatch). `@key`/`@value` are auto-bound on
+host-element loops; under `render-each` / `render-it` each item is rendered as
+its own component (no `@value`). Use `render-each` for lists of components,
+`@each` for plain values.

package/skill/tutuca/patterns/paginate-a-list.md

@@ -0,0 +1,29 @@
+# Paginate a list
+
+**Problem:** show one page at a time without iterating or rendering the
+off-page items.
+
+```html
+<li @each=".items" @loop-with="paginate">
+  <span class="badge" @text="@key"></span> <x text="@value"></x>
+</li>
+```
+
+```js
+fields: { items: [], page: 0, pageSize: 5 },
+alter: {
+  paginate(seq) {           // runs once per render, before iteration
+    const start = this.page * this.pageSize;
+    return { iterData: { total: seq.size }, start, end: start + this.pageSize };
+  },
+}
+```
+
+`@loop-with` returns `{ iterData?, start?, end? }`, all optional. `start`/`end`
+slice with `Array.prototype.slice` semantics (`end` exclusive, negatives count
+from the end). Slicing is positional but **preserves each item's original
+key** — `@key` is the index in the full list, so events and two-way binding
+keep their identity across pages. `iterData` is the shared per-loop value
+handed to `@when` / `@enrich-with`. To paginate a *filtered* list, return
+`keys` instead of `start`/`end` — see
+[filter-and-paginate.md](filter-and-paginate.md).

package/skill/tutuca/patterns/render-a-child-component.md

@@ -0,0 +1,21 @@
+# Render a child component
+
+**Problem:** a component holds another component in a field and wants to render
+it (reaching into nested data is not allowed — `@text=".child.name"` fails).
+
+```js
+fields: { greeting: Greeting.make({ name: "world" }) },
+```
+
+```html
+<x render=".greeting"></x>           <!-- default ("main") view -->
+<x render=".greeting" as="edit"></x> <!-- a named view -->
+<x render=".greeting" as=".mode"></x> <!-- view chosen by a field at runtime -->
+```
+
+The child draws its own view from its own fields, so inside `Greeting`'s view
+`@text=".name"` reads the child's `name`. This is the idiomatic way to display
+nested structure: make the nested thing a component and render it, rather than
+trying to path into it. For a list of children use `render-each` (see the
+iterate-a-list recipe); to flip which view renders, see the switch-between-views
+recipe.

package/skill/tutuca/patterns/reuse-markup-with-macros.md

@@ -0,0 +1,36 @@
+# Reuse markup with macros
+
+**Problem:** the same markup fragment repeats across a view and you want one
+definition — but it has no state of its own.
+
+```js
+import { macro, html } from "tutuca";
+
+const badge = macro(
+  { label: "'New'", kind: "'info'" },                  // defaults are *expressions*
+  html`<span :class="$'badge badge-{^kind}'" @text="^label"></span>`,
+);
+
+const card = macro(
+  { title: "'Card'" },
+  html`<div class="card"><h2 @text="^title"></h2><x:slot></x:slot></div>`,
+);
+
+export function getMacros() { return { badge, card }; }
+```
+
+```html
+<x:badge></x:badge>                  <!-- defaults -->
+<x:badge label="Sale"></x:badge>     <!-- static string (no quotes needed) -->
+<x:badge :label=".status"></x:badge> <!-- bind a field -->
+<x:card title="Hi"><p>body</p></x:card>  <!-- children fill <x:slot> -->
+```
+
+A macro is pure template expansion — no fields, no handlers. Parameters are
+read as `^name`; calls inside the body (`$method`, `.field`) resolve against
+the *host* component. `<x:slot>` (or `<x:slot name="…">` for named slots)
+receives the caller's children. Register with `scope.registerMacros(...)`;
+registry keys are lowercased (`<x:Card>` → `card`). Full semantics (named
+slots, quoting of parameter values) in [macros.md](../macros.md). For repeated
+markup that *does* need state, use a child component instead (see the
+render-a-child-component recipe).

package/skill/tutuca/patterns/share-state-across-the-tree.md

@@ -0,0 +1,38 @@
+# Share state across the tree
+
+**Problem:** a deep descendant needs a value owned by a distant ancestor, and
+you don't want to thread it through every component in between.
+
+> **Reach for this last.** Keep state local to the component and use
+> `provide` / `lookup` only when it is genuinely the only solution — a value
+> owned far away that a deep descendant needs and nothing in between should
+> know about. Dynamic bindings couple a consumer to a producer that may not be
+> in scope, so keep components as self-contained as possible: let a child
+> render the field it needs from its owner, and lift state only as far up the
+> tree as it needs to live.
+
+```js
+// producer — exposes one of its fields under a name
+const Producer = component({
+  name: "EntryEditorAndSelector",
+  fields: { items: [] },
+  provide: { entries: ".items" },
+});
+
+// consumer — forwards to the producer's binding by "Component.name"
+const Consumer = component({
+  name: "Selector",
+  lookup: { entries: { for: "EntryEditorAndSelector.entries", default: ".items" } },
+});
+```
+
+```html
+<!-- read the dynamic with the * prefix — iterate or render it -->
+<option @each="*entries" :value="@value" @text="@label"></option>
+```
+
+`provide` publishes a field under a name; a descendant's `lookup` resolves
+`*name` to the nearest matching producer, falling back to `default` when none
+is in scope. `*name` works wherever a `.field` does for iteration/rendering.
+This is the **read** side; to edit the producer's value through the dynamic,
+see the edit-through-a-dynamic-target recipe.

package/skill/tutuca/patterns/show-or-hide-content.md

@@ -0,0 +1,23 @@
+# Show or hide content
+
+**Problem:** render an element only when a condition holds.
+
+```html
+<div @show=".isOpen">Details</div>
+<p @hide=".isOpen">(hidden when open)</p>
+
+<!-- boolean predicates for one-field checks -->
+<p @show="empty? .items">No results</p>
+<p @show="truthy? .query">Searching…</p>
+<div @show="equals? .view 'detail'">detail view</div>
+
+<!-- on an <x> render op: wraps the produced node, no extra DOM element -->
+<x text=".count" @show=".isOpen"></x>
+```
+
+The closed set of predicates is `empty?`, `truthy?`, `falsy?`, `null?`,
+`equals?` (binary) — semantics in [core.md](../core.md) *Conditional Display*.
+For a condition spanning multiple fields, use a no-arg method instead
+(`@show="$canSubmit"`). `@show`/`@hide` toggle visibility on a host element;
+the wrapper form (`show=` / `hide=` on `<x>`) conditionally emits the node
+with no surrounding element.

package/skill/tutuca/patterns/switch-between-views.md

@@ -0,0 +1,30 @@
+# Switch between views
+
+**Problem:** render the *same* component in a different view (e.g. a read-only
+"main" vs an "edit" form).
+
+```js
+component({
+  view:  html`<p @text=".title"></p>`,                  // "main"
+  views: { edit: html`<input :value=".title" @on.input="setTitle e.value" />` },
+});
+```
+
+```html
+<!-- as= picks the view for one <x render> element only -->
+<x render=".value"></x>
+<x render=".value" as="edit"></x>
+<x render=".value" as=".mode"></x>   <!-- view chosen by a field at runtime -->
+
+<!-- @push-view forces a view on every component rendered under the host -->
+<div @push-view=".view"><x render-each=".items"></x></div>
+```
+
+`as` applies to the direct component only and falls back to `main` if the view
+is absent. It takes the same value forms as `@push-view` — a literal name
+(`as="edit"`) or a dynamic value (`as=".mode"`, `*dyn`, `@bind`, `$method`,
+`$'…'`), evaluated against the host component at render time (for `render-each`,
+once for all items). `@push-view` instead pushes a view name onto the render
+stack so every descendant picks the first matching view (else `main`) — use it
+to flip a whole subtree (e.g. a list) into edit mode at once. To toggle
+*sibling panels* by a field instead, see the tabbed-interface recipe.

package/skill/tutuca/patterns/tabbed-interface.md

@@ -0,0 +1,43 @@
+# Tabbed interface
+
+**Problem:** build tabs — a single `currentView` field decides which panel
+shows, and the active tab button is highlighted.
+
+```html
+<div role="tablist" class="tabs">
+  <button
+    role="tab"
+    @if.class="equals? .currentView 'overview'"
+    @then="'tab tab-active'"
+    @else="'tab'"
+    @on.click="selectView 'overview'"
+  >Overview</button>
+  <button
+    role="tab"
+    @if.class="equals? .currentView 'pricing'"
+    @then="'tab tab-active'"
+    @else="'tab'"
+    @on.click="selectView 'pricing'"
+  >Pricing</button>
+</div>
+
+<div @show="equals? .currentView 'overview'">…overview…</div>
+<div @show="equals? .currentView 'pricing'">…pricing…</div>
+```
+
+```js
+fields: { currentView: "overview" },
+receive: {
+  selectView(draft, view) {
+    draft.currentView = view;
+  },
+},
+```
+
+One string field is the whole state machine. `equals? .currentView 'overview'`
+drives both the panel's `@show` and the active-tab class via `@if.class` /
+`@then` / `@else`. Tab clicks call the draft recipe with a string-literal
+argument (`@on.click="selectView 'pricing'"`). This toggles
+**sibling panels** by predicate; to swap a *component's own* rendered view
+instead, see the switch-between-views recipe. The field name is yours to pick
+(`tab`, `currentView`, …).

package/skill/tutuca/semantics.md

@@ -0,0 +1,195 @@
+# Tutuca — Runtime Semantics (paths · transactions · dispatch)
+
+How a click becomes a state mutation, and what survives across async.
+Read this when reasoning about **why** a handler ran where it did,
+debugging a dispatch or async-timing bug, or changing `src/path.js` /
+`src/transactor.js`. Not needed for ordinary component authoring — for
+that start at [core.md](./core.md).
+
+The step and transaction names below are the ones in the source; confirm
+behavior against `src/path.js` / `src/transactor.js` (or grep the
+`tutuca-source` skill) rather than trusting this doc when they disagree.
+
+## State & identity (in one paragraph)
+
+The application is a single immutable root value; the view is a pure
+function of it; every handler takes the old self and returns a new self,
+and the transactor swaps the root atomically. Updating a deep child
+produces a new root that shares structure with the old one along the
+unchanged spine, so the renderer's `===`-keyed cache skips untouched
+subtrees. Full version: *Mental model* in [core.md](./core.md).
+
+## Paths are positional addresses
+
+A `Path` is an array of `Step`s from the root to the value a handler runs
+against — a **position**, not a captured reference (see *Paths, not
+references* in [core.md](./core.md)). The step kinds:
+
+| Step                | Addresses                          | Source syntax            |
+| ------------------- | ---------------------------------- | ------------------------ |
+| `FieldStep`         | a named field                      | `.field`                 |
+| `SeqStep`           | a sequence entry by **literal** key/index | `.items[2]`       |
+| `SeqAccessStep`     | a sequence entry whose key is **read from another field** | `.sheets[.selId]` |
+| `EachRenderItStep`  | an iterated `render-it` item       | `<x render-it>` per iter |
+| `DynStep` / `DynEachStep` | a dynamic-var (`*x`) render target — a teleport marker | `<x render="*x">` |
+| `BindStep` / `EachBindStep` | nothing — frame-only (carry scope binds, no addressing) | `@each`, `@enrich-with` |
+
+`SeqAccessStep` is the important one for async correctness: it stores the
+field *names* `seqField` and `keyField`, and resolves the key from the
+live data each time it runs — see *Key resolution & async races* below.
+
+### Two derived paths
+
+The reconstructed path is transformed two ways depending on use:
+
+- **`compact()` → the dispatch path.** Drops frame-only steps, keeps one
+  step per crossed component (including `DynStep`s). `popStep()` over it
+  walks every component. Used to drive `ctx.send` / `ctx.intent` and to
+  locate handlers.
+- **`toTransactionPath()` → the transaction path.** Teleports every
+  `DynStep` (drops the steps interior to its producer..consumer span and
+  splices in the producer's own steps) so a mutation lands on the data's
+  real location. A path with no `DynStep` is returned unchanged. Used by
+  `lookup` / `setValue` to read and write state.
+
+## Reconstructing a path from the DOM
+
+The DOM is the only thing that survives between render and click, so the
+renderer leaves breadcrumbs: `data-cid` / `data-nid` / `data-eid` on
+elements, and `§…§` comment "metas" adjacent to component boundaries,
+iteration entries, and scope boundaries (loop-less `@enrich-with`, so
+their custom binds can be replayed). On an event, `Path.fromNodeAndEventName` walks from the
+target up to the root, reads the breadcrumbs, and rebuilds the path. Along
+the way it resolves the handler: normally on the **leaf** component, but
+for DOM-bubbling events it can resolve on an
+**ancestor**, in which case the descending steps below that ancestor are
+dropped so the path resolves to the ancestor's value.
+
+## The transaction lifecycle
+
+Each dispatch is a `Transaction`. The `Transactor` holds a FIFO queue;
+`App` drains it in time-budgeted batches on a `setTimeout(…, 0)` (see
+`src/app.js`), so transactions complete **asynchronously and interleaved**
+— which is exactly why an intent's answer can land after other
+transactions have rebuilt the root.
+
+The core of applying one is `Transaction.updateRootValue`:
+
+```js
+const txnPath = this.getTransactionPath();   // toTransactionPath(), or a pinned path
+const curLeaf = txnPath.lookup(curRoot);      // read the addressed value NOW
+const newLeaf = this.callHandler(curRoot, curLeaf, comps);  // old self → new self
+return curLeaf !== newLeaf ? txnPath.setValue(curRoot, newLeaf) : curRoot;
+```
+
+The root swap is atomic and identity-cheap: unchanged subtrees keep their
+references, so re-render is incremental. Per-dispatch completion is tracked
+by `Completion` (counter-based): `whenSettled()` resolves once a
+transaction's own work finishes, `whenSubtreeSettled()` once the subtree it
+spawned (requests, follow-on sends) settles too.
+
+## Dispatch channels, semantically
+
+The authoring API (`ctx.send` / `ctx.intent`, the handler blocks) is in
+[messages-and-intents.md](./messages-and-intents.md). Underneath there are two
+channels, and one question separates them: **does the sender know who handles
+this?**
+
+| Channel | Transaction | Notes |
+| --- | --- | --- |
+| DOM event → `receive` | `InputEvent` | transacted **synchronously** (`transactInputNow`), not queued; resolves its handler from the compiled view |
+| `ctx.send` → `receive` | `SendEvent` | queued; addressed at one component and stops there |
+| an intent's answer → `receive` | `SendEvent` | queued; named `<name>Ok` / `<name>Error` / `<name>Unhandled`, and indistinguishable from any other message |
+| `ctx.intent` → `intent` | `IntentEvent` per `dyn` hop; no transaction for a `lex` hop | queued; the walk state lives in `IntentWalk`, shared **by reference** across hops |
+
+The `dyn` leg is walking up the dispatch path one `popStep` at a time, starting
+at the sender's **parent**. `targetPath` (the originator's path) stays fixed as
+`path` shortens, so a hop can reach the originator via
+`ctx.sendAtPath(ctx.targetPath, …)`.
+
+The walk object is shared across hops on purpose: that is what makes the
+one-shot **per intent** rather than per hop, so a second `ctx.reply` — from this
+handler or one three hops up — finds the walk already ended.
+
+## Dynamic-var teleporting
+
+A component rendered through `<x render="*sel">` *physically lives* at the
+producer that declared `provide: { sel: … }`, not under the consumer that
+wrote the render. The reconstructed dispatch path keeps every intermediate
+component (so a walk visits them), but `toTransactionPath()` teleports
+the `DynStep`: it pops the steps tagged with the marker's `interiorCids`
+and splices in the producer's own steps (`DynStep.teleportSteps()`). The
+mutation therefore lands on the producer's data, and the consumer's view
+of it updates in lock-step. Authoring view: *Teleporting* in
+[advanced.md](./advanced.md).
+
+When the producer's `provide` value is a seq-access (`.sheets[.selId]`),
+the teleported steps include a `SeqAccessStep` — which is where async key
+races come from.
+
+## Key resolution & async races
+
+A `SeqAccessStep` resolves `keyField` from the live root **every time it
+runs**. For synchronous dispatch this is invisible — the key cannot change
+mid-transaction. For an async intent it is the whole problem: between
+raising the intent and applying its answer, the key may move (e.g. the
+user switches the selected tab, so `.selId` changes), and a naive
+re-resolution would deliver the answer to **whatever item is selected
+now**, not the one that raised the intent.
+
+**Key pinning is the default.** `pushIntent` snapshots the resolved key
+at dispatch time by running `Path.pinKeys(curRoot)` over the transaction
+path — each `SeqAccessStep(seq, keyField)` becomes a literal
+`SeqStep(seq, resolvedKey)`. The pinned path is stored on the
+`IntentWalk`, so the answer updates the item that raised the intent
+regardless of later key changes. (Pinning runs on the transaction path,
+after teleporting, because the `SeqAccessStep` may have come from a
+`DynStep`.)
+
+**Opt out per intent with `livePath: true`:**
+
+```js
+ctx.intent("save", [payload], { route: ["lex"], livePath: true }); // re-resolve live
+```
+
+With `livePath`, the answer re-evaluates the key at apply time — the old
+"follow the latest selection" behavior. Use it only when the answer is
+*meant* to follow wherever the key now points.
+
+Edge cases:
+
+- **Pinned target deleted before the answer arrives** — the pinned
+  `SeqStep` resolves to nothing, the handler runs against a null leaf, and
+  the result equals the input → a safe no-op (root unchanged). With
+  `livePath` it would instead hit the current item.
+- **The `EventContext` path stays live (un-pinned).** An answer arm that
+  itself re-dispatches via `ctx.send` / `ctx.intent` re-resolves
+  against current state — pinning covers the *update*, not nested
+  re-dispatch.
+
+## What "positional delivery" guarantees
+
+Because a path is a position, an async response survives intervening
+transactions that rebuild the root — but "the right slot" means different
+things per step kind:
+
+- **`SeqAccessStep` (`.seq[.key]`)** — the key is **pinned by default**, so
+  the response reaches the entry that issued the request even if the key
+  field moved. Opt out with `livePath: true`.
+- **`SeqStep` with a list index (`.items[3]`)** — the index is literal and
+  **not** pinned to identity: if the list re-sorted or an item was inserted
+  ahead of it, index 3 is now a different item and the response lands
+  there. Anchor on **map keys**, not list indices, when an async result
+  must reach a specific item.
+- **`FieldStep`** — a named field is stable; no ambiguity.
+
+## See also
+
+- [core.md](./core.md) — *Mental model* and *Paths, not references* (the
+  high-level invariants this file expands on), `view` directives, handler
+  blocks.
+- [messages-and-intents.md](./messages-and-intents.md) — the dispatch **API**:
+  addressed `send`-`receive` vs routed `intent`, `ctx.at`, `$unknown`,
+  request-handler registration, and the `livePath` request option.
+- [advanced.md](./advanced.md) — dynamic bindings (`*x`) and the authoring
+  view of teleporting.