tutuca 0.9.75 → 0.9.77

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutuca",
-  "version": "0.9.75",
+  "version": "0.9.77",
   "type": "module",
   "description": "Zero-dependency SPA framework with immutable state and virtual DOM",
   "main": "./dist/tutuca.js",

package/skill/tutuca/SKILL.md

@@ -29,10 +29,11 @@ When authoring tutuca code, also load these if available:
 | ---------------------------------------------------------------------------------------------- | ------------------------------- |
 | Authoring `component({...})`, `html\`...\`` views, macros, fields, events, lists, styles | [core.md](./core.md)           |
 | CLI commands, flags, exit codes, full linter rule list                                         | [cli.md](./cli.md)             |
+| `bubble` / `send`-`receive` / async `request`-`response` channels, `$unknown`, request-handler registration | [request-response.md](./request-response.md) |
 | Drag & drop, dynamic bindings (`*x`), pseudo-`x`, custom seq types, Tailwind/MargaUI | [advanced.md](./advanced.md)   |
+| Runtime semantics — path steps, transaction lifecycle, dyn-var teleporting, async key pinning (`livePath`) | [semantics.md](./semantics.md) |
 | Authoring tests — `getTests` shape, calling methods/input/receive/bubble/response/alter handlers, designing handlers for testability | [testing.md](./testing.md) |
 
-Read `core.md` first. Reach for `cli.md`, `advanced.md`, or
-`testing.md` only when the task touches them — all three are
-referenced inline from `core.md` so you'll be pointed there when
-relevant.
+Read `core.md` first. Reach for the others only when the task touches
+them — each is referenced inline from `core.md` so you'll be pointed
+there when relevant.

package/skill/tutuca/core.md

@@ -16,8 +16,10 @@ the `tutuca` CLI.
 > exit codes, and full linter rule list: see [cli.md](./cli.md).
 > Authoring tests — `getTests` shape, calling methods/input/receive/
 > bubble/response/alter handlers, designing for testability: see
-> [testing.md](./testing.md). Read those only when the task touches
-> them.
+> [testing.md](./testing.md). Runtime semantics — path steps, the
+> transaction lifecycle, dyn-var teleporting, and async key pinning
+> (`livePath`): see [semantics.md](./semantics.md). Read those only when
+> the task touches them.
 
 ## Verifying changes
 
@@ -175,9 +177,13 @@ and rebuilds a *positional* `Path` — an array of steps from the root
 to the value the handler should run against. The same `Path` is reused
 verbatim for `ctx.send`, `ctx.bubble`, and `ctx.request` /
 response: because it's positional rather than a captured reference, an
-async response still lands at the right slot even after intervening
-transactions have rebuilt the root. See
-[request-response.md](./request-response.md) for the dispatch APIs.
+async response survives intervening transactions that rebuild the root.
+"The right slot" is exact for named fields and for map entries by key
+(seq-access keys like `.sheets[.selId]` are *pinned* to their
+request-time value by default); a bare list **index** still slides if the
+list reordered. See [request-response.md](./request-response.md) for the
+dispatch APIs and [semantics.md](./semantics.md) for the path/transaction
+model and key pinning.
 
 **Why `alter` is its own table.** Alter handlers are pure, evaluated
 on every render, and produce binds (no state change). `input` /
@@ -924,6 +930,9 @@ export function getTests({ describe, test, expect }) { /*...*/ }      // optiona
 - [advanced.md](./advanced.md) — dynamic bindings (`*x`), pseudo-`@x` for
   `<select>` / `<table>` / `<tr>`, drag & drop, custom seq types, Tailwind /
   MargaUI compilation.
+- [semantics.md](./semantics.md) — runtime semantics: path steps, the
+  transaction lifecycle, dyn-var teleporting, and async key pinning
+  (`livePath`).
 - [testing.md](./testing.md) — `getTests` shape and the handler calling
   convention for tests.
 - [cli.md](./cli.md) — commands, flags, exit codes, and the full linter rule

package/skill/tutuca/request-response.md

@@ -0,0 +1,338 @@
+# Tutuca — Request / Response & Orchestration
+
+The three event-driven orchestration channels beyond local `input`
+handlers: `bubble` (events up the tree), `send` / `receive` (messages
+to a target path), and async `request` / `response` (host-registered
+async work routed back into component state). Read this file when
+wiring `bubble` / `receive` / `response` handlers, calling
+`ctx.bubble` / `ctx.send` / `ctx.request`, or registering request
+handlers with `registerRequestHandlers`. General authoring lives in
+[core.md](./core.md); testing these handlers is in
+[testing.md](./testing.md).
+
+## The four channels
+
+Each channel pairs a trigger with a same-shape handler block:
+
+| Triggered by                                | Handler block       |
+| ------------------------------------------- | ------------------- |
+| DOM event (`click`, `input`, …)             | `input:    { ... }` |
+| `ctx.bubble(name)` — event up the tree      | `bubble:   { ... }` |
+| `ctx.send(name)` — message to a target path | `receive:  { ... }` |
+| `ctx.request(name)` — async request         | `response: { ... }` |
+
+Every handler is called as `handler(...args, ctx)` and returns a
+(possibly updated) instance of `this`; the framework swaps the returned
+value into the dispatch path. `ctx` (an `EventContext`) is always the
+trailing argument and exposes `ctx.send`, `ctx.bubble`, `ctx.request`,
+`ctx.at` (a `PathBuilder`), `ctx.name` (the dispatched name), and —
+inside bubble handlers — `ctx.stopPropagation()`.
+
+`alter` is a fifth handler block, but it isn't event-triggered — the
+renderer invokes alter handlers to produce binds, not to update state.
+See *Mental model* and *Scope Enrichment* in [core.md](./core.md).
+
+## Bubble Events
+
+```js
+input:  { onClick(ctx) { ctx.bubble("treeItemSelected", [this]); return this; } },
+bubble: {
+  treeItemSelected(selected, ctx) {  // ctx.stopPropagation() to halt
+    return this.insertInLogAt(0, `selected ${selected.label}`);
+  },
+}
+```
+
+`ctx.bubble("name", args)` emits an event that walks the dispatch path
+back toward the root. Each ancestor whose component defines
+`bubble.<name>(...args, ctx)` runs it (others are skipped silently);
+bubbling stops at the root or when a handler calls
+`ctx.stopPropagation()`. Ancestors see the event *after* descendants
+have transacted, so bubble handlers are the place for aggregate state
+(logs, selections, totals).
+
+When to bubble: handle the event locally if the current component owns
+the state needed to respond. Bubble when the action belongs to an
+ancestor (a list item's "remove" must reach the list that owns the
+items), or when an ancestor may want to react to or record something
+that happened (selection, logging, analytics). Don't bubble events
+with no consumer.
+
+## Send / Receive
+
+`ctx.send(name, args)` delivers a message to a specific target
+component (addressed by path; on its own `ctx.send` targets `this`).
+The target's `receive.<name>(...args, ctx)` handler runs. There is
+**no built-in lifecycle** — `receive.init` is just a convention; the
+host must dispatch it (typically after `app.start()`) for it to run.
+
+```js
+receive: { init(ctx) { ctx.request("loadData"); return this.setIsLoading(true); } }
+```
+
+Dispatch from anywhere:
+
+```js
+app.sendAtRoot("init");                            // host code, top-level
+ctx.at.field("personalSite").send("init");                 // child by field name
+ctx.at.index("items", 3).send("init");                     // list element at index 3
+ctx.at.key("byKey", "k1").send("init");                    // map entry by key
+ctx.at.field("a").field("b").index("xs", 0).send("ping");  // chain freely
+ctx.send("name");                                          // self
+ctx.bubble("name", [arg]);                                 // bubble up
+```
+
+`ctx.at` returns a `PathBuilder` with `.field(name)`, `.index(name, i)`,
+and `.key(name, k)`. Each call appends a step to the path before
+`.send(...)` / `.bubble(...)` fires; the handler runs inside the child
+instance with `this` bound to it. Paths are positional, not references —
+see *Positional delivery* below and *Mental model* in
+[core.md](./core.md) for why this matters across async boundaries.
+
+When to send: bubble emits an *event* that any ancestor with a
+matching handler can observe; send delivers a *message* to one
+specific target (or to self). Reach for `ctx.at.…send("name")` when
+one component needs to address another by path — e.g. a form telling
+its email field to focus after a failed submit
+(`ctx.at.field("email").send("focus")`), or a list telling item 3 to
+enter edit mode (`ctx.at.index("items", 3).send("startEditing")`).
+Reach for `ctx.send("name")` on self to reuse a handler from multiple
+call sites without duplicating its body — e.g. a "Reload" button and
+`receive.init` both calling `ctx.send("loadData")`. Don't `send` to
+self when a direct method call on the same component would do.
+
+## Integrating with the outside world
+
+A tutuca app talks to the outside world in two directions, and both go
+through handlers — never around them.
+
+- **Outbound** — the app reaches out (fetch, timers, IndexedDB, external
+  SDKs). Use `ctx.request("name", args)`; the host-registered handler does
+  the async work and the result lands back in component state via
+  `response.<name>`. See *Async Requests* below.
+- **Inbound** — the outside world pushes an event in (a WebSocket message,
+  a DOM event fired outside the app, a `postMessage`, a timer, a
+  third-party callback). Use `app.sendAtRoot("name", args)` from the host /
+  glue code. It dispatches a `send` to the **root component**, running its
+  `receive.<name>(...args, ctx)` handler under the same immutable
+  `return this.set…()` contract as every other handler.
+
+```js
+// host / glue code, outside the component tree
+ws.onmessage = (e) => app.sendAtRoot("serverPushed", [JSON.parse(e.data)]);
+
+// root component
+receive: {
+  serverPushed(msg, ctx) { return this.prependEvent(msg); },
+}
+```
+
+This keeps the root component the single owner of how external inbound
+events mutate state — the logic lives in one `receive` block, in the same
+place and shape as the rest of the app's handlers, and is testable like
+any other (see [testing.md](./testing.md)).
+
+⚠️ **Do not** reach into `app.state` and call the raw `State.set(val)` /
+`State.update(fn)` methods to inject external data. That bypasses the
+component handler model, the immutable `return this.set…()` discipline,
+scope enrichment, and the transactor's batching — state mutated that way is
+invisible to the components that own it and easily clobbered by the next
+transaction. Route every inbound event through `app.sendAtRoot` instead.
+
+`sendAtRoot` only targets the root (`Path([])`). To land an inbound event
+on nested state, let the root's `receive` handler forward it with
+`ctx.at.field(...).send(...)` (see *Send / Receive* above) — one entry
+point, still reaching deep. For async/external delivery, anchor on stable
+map keys rather than list indices (see *Positional delivery across async*
+below).
+
+## Async Requests
+
+`ctx.request("name", args)` triggers a host-registered async handler
+and routes the result back to the issuing component's
+`response.<name>(res, err, ctx)`. Use it for fetch / timer / IndexedDB
+work that should land back in component state.
+
+```js
+export function getRequestHandlers() {
+  return {
+    async loadData() {
+      const r = await fetch("https://example.com/data.json");
+      return await r.json();
+    },
+  };
+}
+
+// register at the same scope where you registerComponents
+const scope = app.registerComponents([Comp]);
+scope.registerRequestHandlers(getRequestHandlers());
+```
+
+In a component:
+
+```js
+receive:  { init(ctx) { ctx.request("loadData"); return this.setIsLoading(true); } },
+response: { loadData(res, err, ctx) { return this.setIsLoading(false).setItems(res); } },
+```
+
+### The `err` argument and the error path
+
+The default handler is `response.<name>(res, err, ctx)`. On success the
+host handler's resolved value is `res` and `err` is `null`; on failure
+`res` is `null` and `err` is the thrown / rejected value. Branch on
+`err` when failure needs different state:
+
+```js
+response: {
+  loadData(res, err) {
+    if (err) return this.setIsLoading(false).setError(String(err));
+    return this.setIsLoading(false).setItems(res);
+  },
+}
+```
+
+A **request name that isn't registered** doesn't crash — the runtime
+throws `Request not found: <name>` internally and routes it to the same
+error path, so it arrives as `err`. (A `!name` reference written in a
+*template* is caught earlier by the `UNKNOWN_REQUEST_NAME` lint; a
+`ctx.request("name")` string call is not, so a typo there surfaces only
+at runtime as an `err`.)
+
+### Per-call handler-name overrides — and their signature
+
+The third argument to `ctx.request` overrides which `response` handler
+runs, with three keys:
+
+- `onResName` — base name for **both** outcomes (replaces `<name>`); the
+  handler still takes `(res, err, ctx)`.
+- `onOkName` — name for the **success** path only.
+- `onErrorName` — name for the **error** path only.
+
+⚠️ When `onOkName` / `onErrorName` is used, the split handler receives a
+**single** payload arg — *not* `(res, err, ctx)`:
+
+```js
+methods: {
+  load(ctx) {
+    ctx.request("loadData", [], { onOkName: "loadDataOk", onErrorName: "loadDataErr" });
+    return this.setIsLoading(true);
+  },
+},
+response: {
+  loadDataOk(res, ctx)  { return this.setIsLoading(false).setItems(res); }, // res only
+  loadDataErr(err, ctx) { return this.setIsLoading(false).setError(String(err)); }, // err only
+},
+```
+
+The combined `(res, err, ctx)` shape is only for the default /
+`onResName` case. Mixing them up — a split handler declaring `(res, err)`
+— means the second param is `ctx`, a common bug. (See
+[testing.md](./testing.md) for how this changes the test call.)
+
+### `livePath` — pinning vs following a moving key
+
+The same opts object takes `livePath`. It controls where the response
+lands when the request path addresses a seq-access entry
+(`.sheets[.selId]`): by **default** the resolved key is *pinned* at
+request time, so the response updates the item that issued the request
+even if `.selId` moved while the request was in flight (e.g. the user
+switched tabs). Set `livePath: true` to opt out and re-resolve the key
+live, delivering to whatever the key now points at:
+
+```js
+ctx.request("save", [payload]);                    // pinned: lands on the originating sheet
+ctx.request("refresh", [], { livePath: true });    // live: lands on the currently selected sheet
+```
+
+Pinning only affects field-resolved keys; named fields are already stable
+and list **indices** are not pinned (a reorder still slides them). Full
+model in [semantics.md](./semantics.md) (*Key resolution & async races*).
+
+### Fire-and-forget requests
+
+A request whose result you don't need can omit the `response` handler
+entirely — when no `response.<name>` (and no `$unknown`) matches, the
+result is silently dropped. Idiomatic for side-effect-only work like
+persisting state:
+
+```js
+input: {
+  onApplyFilter(value, ctx) {
+    ctx.request("persistState", [{ key: "sectionFilter", value }]);
+    return this.setFilter(value);
+  },
+}
+```
+
+You can also fire several in one handler
+(`ctx.request(...); ctx.request(...); return ...;`).
+
+### The request-handler contract
+
+Registered request handlers run with **no `this`** (they're invoked as
+`fn.apply(null, args)`), so they can't read component state — pass
+everything they need through `args`
+(`ctx.request("persistState", [{ key, value }])`). They're plain async
+functions or closures. Aggregate handlers from sub-modules with spread:
+
+```js
+export function getRequestHandlers() {
+  return { ...getRequestHandlersA(), ...getRequestHandlersB() };
+}
+```
+
+### Chaining from a response handler
+
+A `response` handler gets the full `ctx`, so it can issue further
+`ctx.request` (request → response → request chains), `ctx.send`, or
+`ctx.bubble`:
+
+```js
+response: {
+  loadUser(user, err, ctx) {
+    if (!err && user) ctx.request("loadUserDetails", [user.id]);
+    return this.setUser(user);
+  },
+  loadUserDetails(details, err) { return this.setUserDetails(details); },
+}
+```
+
+## `$unknown` fallback
+
+`receive` / `bubble` / `response` all share one fallback: when no
+handler matches the dispatched name, the runtime looks for
+`<block>.$unknown(...args, ctx)` and runs that instead; `ctx.name` tells
+it which name was dispatched. Absent both the named handler and
+`$unknown`, the message is silently dropped (the value passes through
+unchanged). Use `$unknown` for a single catch-all (logging, a generic
+router); rely on the silent drop for fire-and-forget requests.
+
+## Positional delivery across async
+
+The path a response (or `send` / `bubble`) is delivered to is
+**positional** — an array of steps from the root, not a captured
+reference. This is why an async response survives intervening
+transactions that rebuilt the root (see *Mental model* in
+[core.md](./core.md)). Per step kind:
+
+- **Map entry by key** (`.sheets[.selId]`) — the resolved key is *pinned*
+  at request time by default, so the response reaches the originating
+  entry even if the key field moved. `livePath: true` opts out (above).
+- **List index** (`.items[3]`) — not pinned: if the list re-sorted so
+  index 3 is now a different item, the response lands on whatever occupies
+  the slot. Anchor on map keys, not list indices, when an async result
+  must reach a specific item.
+
+Full model in [semantics.md](./semantics.md).
+
+## See also
+
+- [core.md](./core.md) — the core mental model, `view` directives, handler
+  blocks overview, and *Conventional Module Exports*.
+- [semantics.md](./semantics.md) — the path/transaction model behind these
+  channels: path steps, the transaction lifecycle, teleporting, and the
+  key-pinning rules `livePath` toggles.
+- [testing.md](./testing.md) — calling `bubble` / `receive` / `response`
+  handlers from tests.
+- [cli.md](./cli.md) — `UNKNOWN_REQUEST_NAME` and the full linter rule list,
+  exit codes, and `render` / `test` flags.

package/skill/tutuca/semantics.md

@@ -0,0 +1,187 @@
+# 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
+  bubbles through every component. Used to drive `ctx.send` / `ctx.bubble`
+  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 and
+iteration entries. 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 bubbling events (and explicit `bubble`) 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 a request's response 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. Cross-transaction ordering and
+fan-out completion are tracked by `Task` (a transaction's `task` resolves
+once its dependency tasks do).
+
+## Dispatch channels, semantically
+
+The authoring API (`ctx.send` / `bubble` / `request`, the handler blocks)
+is in [request-response.md](./request-response.md). Underneath, each maps
+to a `Transaction` subclass:
+
+| Channel             | Transaction      | Notes                                            |
+| ------------------- | ---------------- | ------------------------------------------------ |
+| DOM event → `input` | `InputEvent`     | transacted **synchronously** (`transactInputNow`), not queued |
+| `ctx.send` → `receive` | `SendEvent`   | queued; `skipSelf` runs no self-handler          |
+| `ctx.bubble` → `bubble` | `BubbleEvent` | queued; re-pushes itself at `path.popStep()` until it reaches the root or `stopPropagation` |
+| `ctx.request` → `response` | `ResponseEvent` | queued **after** the async work resolves |
+
+Bubbling is just walking up the dispatch path one `popStep` at a time.
+`targetPath` (the originator's path) stays fixed as `path` shortens, so a
+bubble handler can reply to the originator via `ctx.sendAtPath(ctx.targetPath, …)`.
+
+## Dynamic-var teleporting
+
+A component rendered through `<x render="*sel">` *physically lives* at the
+producer that declared `dynamic: { sel: … }`, not under the consumer that
+wrote the render. The reconstructed dispatch path keeps every intermediate
+component (so bubbling 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 `dynamic` 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 `request`/`response` it is the whole
+problem: between issuing the request and applying the response, the key
+may move (e.g. the user switches the selected tab, so `.selId` changes),
+and a naive re-resolution would deliver the response to **whatever item is
+selected now**, not the one that issued the request.
+
+**Key pinning is the default.** `pushRequest` snapshots the resolved key
+at request 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
+`ResponseEvent`, so the response updates the item that issued the request
+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 request with `livePath: true`:**
+
+```js
+ctx.request("save", [payload], { livePath: true }); // re-resolve the key live
+```
+
+With `livePath`, the response re-evaluates the key at apply time — the old
+"follow the latest selection" behavior. Use it only when the response is
+*meant* to follow wherever the key now points.
+
+Edge cases:
+
+- **Pinned target deleted before the response 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).** A response handler
+  that itself re-dispatches via `ctx.send` / `ctx.request` 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.
+- [request-response.md](./request-response.md) — the dispatch **API**:
+  `bubble` / `send`-`receive` / `request`-`response`, `ctx.at`, `$unknown`,
+  request-handler registration, and the `livePath` request option.
+- [advanced.md](./advanced.md) — dynamic bindings (`*x`) and the authoring
+  view of teleporting.

package/skill/tutuca-source/tutuca.ext.js

@@ -17,6 +17,9 @@ class Step {
   toAbstractPathStep() {
     return this;
   }
+  pinKey(_v) {
+    return this;
+  }
 }
 
 class BindStep extends Step {
@@ -98,6 +101,10 @@ class SeqAccessStep extends Step {
     const key = root?.get(this.keyField, NONE);
     return seq === NONE || key === NONE ? root : root.set(this.seqField, seq.set(key, v));
   }
+  pinKey(v) {
+    const key = v?.get(this.keyField, NONE);
+    return key === NONE ? this : new SeqStep(this.seqField, key);
+  }
 }
 
 class EachBindStep extends Step {
@@ -220,6 +227,20 @@ class Path {
     }
     return new Path(out);
   }
+  pinKeys(root) {
+    let curVal = root;
+    let out = null;
+    for (let i = 0;i < this.steps.length; i++) {
+      const step = this.steps[i];
+      const pinned = step.pinKey(curVal);
+      if (pinned !== step)
+        (out ??= this.steps.slice())[i] = pinned;
+      curVal = step.lookup(curVal, NONE);
+      if (curVal === NONE)
+        break;
+    }
+    return out ? new Path(out) : this;
+  }
   lookup(v, dval = null) {
     let curVal = v;
     for (const step of this.steps) {
@@ -2664,12 +2685,14 @@ class Transactor {
   }
   async pushRequest(path, name, args = [], opts = {}, parent = null) {
     const curRoot = this.state.val;
-    const curLeaf = path.toTransactionPath().lookup(curRoot);
+    const txnPath = path.toTransactionPath();
+    const curLeaf = txnPath.lookup(curRoot);
     const handler = this.comps.getRequestFor(curLeaf, name) ?? mkReq404(name);
     const resHandlerName = opts?.onResName ?? name;
+    const resPath = opts?.livePath ? null : txnPath.pinKeys(curRoot);
     const push = (specificName, baseName, singleArg, result, error) => {
       const resArgs = specificName ? [singleArg] : [result, error];
-      const t = new ResponseEvent(path, this, specificName ?? baseName, resArgs, parent);
+      const t = new ResponseEvent(path, this, specificName ?? baseName, resArgs, parent, resPath);
       this.pushTransaction(t);
     };
     try {
@@ -2744,8 +2767,11 @@ class Transaction {
   getHandlerAndArgs(_root, _instance, _comps) {
     return null;
   }
+  getTransactionPath() {
+    return this.path.toTransactionPath();
+  }
   updateRootValue(curRoot, comps) {
-    const txnPath = this.path.toTransactionPath();
+    const txnPath = this.getTransactionPath();
     const curLeaf = txnPath.lookup(curRoot);
     const newLeaf = this.callHandler(curRoot, curLeaf, comps);
     this._task?.complete?.({ value: newLeaf, old: curLeaf });
@@ -2854,6 +2880,13 @@ class NameArgsTransaction extends Transaction {
 
 class ResponseEvent extends NameArgsTransaction {
   handlerProp = "response";
+  constructor(path, transactor, name, args, parent, txnPath = null) {
+    super(path, transactor, name, args, parent);
+    this._txnPath = txnPath;
+  }
+  getTransactionPath() {
+    return this._txnPath ?? super.getTransactionPath();
+  }
 }
 
 class SendEvent extends NameArgsTransaction {