From e0185279dbd75dfeae8f67f35e56cd1eacfd8c64 Mon Sep 17 00:00:00 2001
From: Ryan Carniato <ryansolid@gmail.com>
Date: Tue, 29 Sep 2026 08:58:28 -0700
Subject: [PATCH 1/5] =?UTF-8?q?docs:=20design=20fit=20(=C2=A710),=20live-m?=
 =?UTF-8?q?utation=20seed=20(=C2=A79.6),=20and=20the=20examples=20grid=20p?=
 =?UTF-8?q?lan?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Recorded from the fit conversation after the Stage 7 gate, parked while
#3704 was in review; lands now that it has merged. Nothing here touches
code.

Principles §9.6 seeds Stage 9 — mutations through a live connection:
three homes for a rejection in the live quadrant (client, a bounded
sibling's single-flight response, server memory) and which one the
design recommends. §10 answers where server components fit: three
axes (content weight, origin of change, client-owned position density),
five quadrants with each example placed, where a rejection lives per
shape, the advice as rules of thumb, and the candidates to evaluate
against the map with the evidence each needs.

`documentation/plans/examples-grid-plan.md` turns that into the example
set as a whole: one idiomatic app per grid coordinate, the bar every
example meets, per-example dispositions (hackernews' Toggle becomes an
attribute slot; todos-server reshaped; chat rebuilt and board added as
the two flagships; room retired), the verification items that gate the
reshapes, and the order — revised today to least work first, one
example per PR, exact code reviewed before it is written. todos-server's
target is decided: Q5.

Co-authored-by: Claude via Cursor <noreply@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
---
 documentation/plans/examples-grid-plan.md     | 249 +++++++++++++++
 .../server-components-principles.md           | 294 ++++++++++++++++++
 2 files changed, 543 insertions(+)
 create mode 100644 documentation/plans/examples-grid-plan.md

diff --git a/documentation/plans/examples-grid-plan.md b/documentation/plans/examples-grid-plan.md
new file mode 100644
index 000000000..8546c6905
--- /dev/null
+++ b/documentation/plans/examples-grid-plan.md
@@ -0,0 +1,249 @@
+# Examples Plan — one idiomatic app per grid coordinate
+
+_Drafted 2026-09-28, from the fit conversation that produced principles §10
+and §9.6, with Stages 1–8 built and #3704 (attribute slots, second form)
+the last heavy feature. Status: DIRECTION AGREED in conversation; nothing
+here is built. This page is the checklist for the example set as a whole;
+the two flagships get their own plans (linked below) and this page does not
+design them. Design record: `documentation/server-components/
+server-components-principles.md` §10 (fit) and §9.6 (live mutations seed).
+The grid is the one in "The Grand Unifying Architecture of Frontend"
+(dev.to, 2026-09-22): response window on the horizontal axis
+(request/response → persistent), affordance weight on the vertical
+(server-owned markup → client-owned state), and three responsibilities every
+app separates — navigation (client), content (server), affordances
+(client). Owner: Ryan._
+
+## Objective
+
+The examples were built as test beds, one per feature, and that was the
+right way to build the features. Now that the feature set is complete they
+should become **good examples**: one idiomatic app per coordinate on the
+grid, each the app it would be if the framework didn't need proving, with
+`rendering` remaining the one deliberate kitchen sink. Two of them are
+flagships — realistic products, not demos — because the right half of the
+grid is where no one else has a story and an AI chat and a board are the
+two apps people are actually building there.
+
+## The bar (every example)
+
+Priority order; a lower item never overrides a higher one.
+
+1. **One coordinate.** The README's first paragraph names it and names the
+   example's twin (the same app at another coordinate) where one exists.
+2. **The app's own affordances and nothing else.** Every feature present is
+   one the app would have if the competitors didn't exist. Features with no
+   idiomatic home live in specs, not examples — that absence is evidence
+   for principles §10.5, not a gap to fill.
+3. **The three responsibilities visible.** Which elements the compiler
+   claims (navigation), which functions are content (`"use server"`), and
+   what the overlay is (affordances) should be readable from the source
+   without a tour.
+4. **Lead with the affordance that is hardest elsewhere.** Among the app's
+   natural affordances, the README and the polish go to the _layering
+   moment_ — the place where client behaviour on server markup is one line
+   here and a DSL, a controller, or a round trip in Datastar, Turbo +
+   Stimulus, or LiveView. By demonstration only: READMEs stay neutral and
+   name no competitor; the head-to-head is an article.
+
+The trivial case must stay trivial: one client position with no per-item
+data is one line each side (`codeBlock={() => ({ onCopy })}` on the client,
+`onClick={block.onCopy}` on the server). No example may need a fill to be
+more than an object literal; where one does, that is a §9.2.3 ergonomics
+finding to raise, not something example code hides.
+
+## The map
+
+```text
+                 request/response                       persistent
+              ┌──────────────────────────────┬──────────────────────────────┐
+ client-heavy │ hackernews-spa   SPA + JSON  │ board            FLAGSHIP    │
+ (affordances)│ todos            SPA + optim │   live data tier, optimistic │
+              │                              │   store, until, drag,        │
+              │                              │   presence                   │
+              ├──────────────────────────────┼──────────────────────────────┤
+   (islands)  │ notes            RSC coord.  │                              │
+              │   islands + single-flight    │                              │
+              ├──────────────────────────────┼──────────────────────────────┤
+ server-heavy │ hackernews       reads       │ chat             FLAGSHIP    │
+ (markup)     │ todos-server     writes      │   live server components,    │
+              │                              │   durable generation, threads│
+              └──────────────────────────────┴──────────────────────────────┘
+ off-grid: rendering (SSR-mode kitchen sink) · effect (data tier × Effect)
+           · sierpinski (renderer perf) · migrating-element (conditional, §V5)
+ retired:  room (both pages absorbed by the flagships)
+```
+
+Twins: `hackernews` ↔ `hackernews-spa`; `todos-server` ↔ `todos`. The
+realistic pair on the right (`board`, `chat`) mirrors the pedagogical pair
+on the left (`hackernews`, `notes`), and is its own comparison: the same
+primitives with the client owning the markup (`board`) and with the server
+owning it (`chat`).
+
+## Per-example disposition
+
+### `hackernews` — bottom-left, reads. KEEP; one binding change + README
+
+The front door: the simplest server component, navigation over server
+markup, a single stateful client concern. Its layering moment is comment
+collapse — client state on server-rendered elements deep in a tree, surviving
+navigation. Today that is a `Toggle` client component wrapping a markup slot
+(`toggle={p => <Toggle>{p.children}</Toggle>}`); under §9.2.3's placement
+principle a thread exists because the server has comments, so it is server
+markup and the collapse is an attribute slot (`class` and `onClick` bound on
+the server's own elements). Convert it; it is the idiomatic form and the
+example gets smaller. README repositioned to the coordinate and twin.
+
+### `hackernews-spa` — top-left. KEEP as is
+
+The twin; exists only as the comparison. README names the coordinate.
+
+### `notes` — middle-left, the RSC coordinate. KEEP; README only
+
+React's own server-components demo ported: client islands whose state
+survives server updates around them, single-flight mutations by redirect,
+the search field as the idiomatic attribute slot. Its layering moment is the
+editor keeping its draft while the sidebar list refreshes around it — the
+"shared client state preserved" line the HTML-partial tools cannot cross.
+Code unchanged; README repositioned. The overlap with `chat` (both are
+sidebar + viewer + mutations) is intentional: opposite sides of the grid,
+different audience.
+
+### `todos` — top-left. KEEP as is
+
+The SPA control: optimistic store over `refresh`, client-held API mock.
+Twin of `todos-server`; also the pedagogical control for `board`.
+
+### `todos-server` — bottom-left, writes. RESHAPE
+
+Today: the §9.2.3 acceptance gate — seven client-owned positions per row, an
+intent record, a client error map, multi-flight `refresh`. Principles §10
+places it as a widget app wearing collaborative-list clothes; it is not the
+example anyone should learn from and the §9.2.3 record stays as its
+history.
+
+Target: the write side of the HTMX corner, made enviable rather than
+mimicked. Server markup throughout; every mutation a compiler-claimed
+`<form action={x.with(...)}>` that works without JS; **one** attribute slot
+with **one** position (`done`) fed by an optimistic store the action writes
+before it yields; single-flight responses that morph the row back. About
+ten lines of client code, no component beyond the root, instant toggles.
+Failures server-rendered: a rejected action's response carries the row with
+its error and a retry form. Layering moment: the optimistic toggle.
+
+Scope line: toggle, remove, and add are optimistic. If any of them needs
+more than a store write inside its action, it is not slick and it is out
+(the pending-row-for-add markup slot is the first candidate to fall; the
+README may describe it as the increment). Bulk actions stay plain forms.
+Pending feedback, if the router marks a submitting claimed form
+(`aria-busy` / `data-pending`), is CSS only — see V4.
+
+### `chat` — bottom-right FLAGSHIP. REBUILD (own plan)
+
+Plan: `documentation/plans/chat-flagship.md` (to write first). Realistic
+AI chat: threads durable and addressable; generation as a job that outlives
+the request, with the thread a `live` server component projecting durable
+state (close the tab, come back, caught up in one morph; two tabs agree);
+real model with the fake as no-key fallback; structured message parts;
+stop / regenerate / rename / delete as forms; the optimistic user bubble as
+a client element in a markup slot cleared by `until` on the echo; copy
+button as the attribute slot; native `<details>` for collapse. Failed
+generations are facts about the thread — durable, server-rendered with a
+retry. Absorbs `room`'s `/` page. The `usage` projection goes (token usage
+is a number on the finished message), which removes the container tier's
+only example — flagged, consistent with principles §10.5.
+
+### `board` — top-right FLAGSHIP. NEW (own plan)
+
+Plan: `documentation/plans/board-flagship.md`. Pure data tier, no frames:
+one board of lists and cards as a `live` source, reconciled by id into an
+optimistic nested store; moves and reorders as optimistic writes with
+`until`; two tabs converging; rejected moves reverting; presence. Drag
+within and between lists with pointer events, fractional ordering. Scope:
+create / rename / archive, titles only, no card detail. Absorbs `room`'s
+`/live` page. Acceptance bar must name the two identity moments explicitly
+or they will not get built: a card sliding into its new column (same
+element on both sides), and a card being edited inline while another tab
+moves it — focus, caret, and draft arriving in the new column intact
+(one element per card at board level, referenced from whichever list holds
+it). `board` is also the top-right form of `chat`: a live thread read by
+client components into an optimistic store is this architecture with a
+transcript instead of lists, which is why no separate `chat-spa` exists.
+
+### `room` — RETIRE
+
+Stage 8's test bed. `/` becomes `chat`'s thread; `/live` becomes `board`.
+The chaos switch and status pills were apparatus; connection state stays
+visible in both flagships through `onstatus`, as an affordance the apps
+would have anyway. Delete once both flagships exist.
+
+### `migrating-element` — CONDITIONAL on V5
+
+Today a canvas, because the README records that `<video>` pauses on
+migration. The spec and MDN say native media survives a same-task
+remove-and-reinsert; what a plain move resets is iframes, animations,
+focus, popovers — the cases `moveBefore()` (Chrome 133, Firefox 144, not
+Safari) exists for. If V5 finds native video retains, the example becomes
+the mini-player with a `<video>` — the idiomatic case: shrink the player to
+a corner while browsing the list. If `moveBefore()` is adopted in the
+runtime, it becomes the mini-player with an embed and a Safari note. If
+neither, it stays as is.
+
+### `rendering`, `effect`, `sierpinski` — KEEP as is
+
+Off-grid on purpose. `rendering` is the one kitchen sink.
+
+## Verification items (gate the reshapes; none built)
+
+- **V1 — Flight collector carries a result plus regions.** `notes` exercises
+  redirects only. `todos-server`'s server-rendered failures and §9.6 (B)
+  both need a non-redirect action result to travel with the invalidated
+  regions in one response.
+- **V2 — Optimistic settlement lands with the single-flight morph.** The
+  overlay must drop in the same transition the response's morph applies,
+  so `done` never flickers between overlay and markup (§9.2.1
+  convergence).
+- **V3 — `action`'s client half runs for claimed forms in frame content.**
+  Compiled client markup is known to work; server-rendered
+  `<form action={x.with(...)}>` inside a frame must run the action's
+  generator (the optimistic write) before the server call.
+- **V4 — Router pending state on a submitting claimed form.** Whether the
+  router marks the form (`aria-busy` / `data-pending`) for the action's
+  life. If not, a small router feature, not an example hack.
+- **V5 — Media migration.** A playing native `<video>` and a YouTube
+  `<iframe>` moved through the `<Show>` migration path, Chrome and
+  Firefox, with and without `moveBefore()` in place of `insertBefore` in
+  the insert/reconcile path. Decides `migrating-element` and whether the
+  runtime adopts `moveBefore()` behind feature detection (a runtime
+  behaviour change — flagged, no API surface).
+
+## Order
+
+_Revised 2026-09-29, #3704 merged: least work to most, one example per
+PR, and each example's exact code is proposed and reviewed before it is
+written — the shape and its details are the deliverable. Server
+components are unreleased, so the flagships carry no deadline; the
+examples that are already right carry the most value per hour._
+
+1. README pass on the examples that are right today: `notes`,
+   `hackernews-spa`, `todos` (README only); `hackernews` (the `Toggle` →
+   attribute slot change, then README).
+2. `todos-server` reshape (V1–V4 first). Target decided 2026-09-29: the
+   Q5 shape above — single-flight, server-rendered rejections, one
+   attribute slot with one position — not the Q4 wrap.
+3. `chat-flagship.md`, then `chat`.
+4. `board-flagship.md`, then `board`.
+5. Retire `room`.
+6. V5, then the `migrating-element` decision.
+
+## Follow-ups this plan creates
+
+- `moveBefore()` in the insert path, behind feature detection (V5).
+- §9.6 (B) verification — shares V1.
+- Principles §10.6 doc items: "when to reach for it" in
+  `server-components.md`, the ratio note in §9.2.3.
+- The comparison article: the same widget in each of the HTML-partial
+  tools and here, client layer highlighted. The examples are the evidence;
+  the article is the argument.
+- Container tier example home, once `chat` drops `usage` (principles
+  §10.5).
diff --git a/documentation/server-components/server-components-principles.md b/documentation/server-components/server-components-principles.md
index a61609ad3..d03356b16 100644
--- a/documentation/server-components/server-components-principles.md
+++ b/documentation/server-components/server-components-principles.md
@@ -4033,3 +4033,297 @@ as an event stream (a header would put a third answer shape behind
 a URL caches already hold for the second — #3094 — and reads carry
 no transport header — #3406); a server-side `live` declaration may
 cross-check in dev but cannot decide (topology); (f) is the plan's.
+
+### 9.6 Stage 9 seed — mutations through a live connection (2026-09-28)
+
+Recorded from the fit conversation (§10); nothing here is built.
+The question that raised it: in the live quadrant, where does a
+rejected mutation live? The seed answers it, and finds that the
+answer is not the reason to build what the seed describes.
+
+**The observation: per-connection server memory already exists.**
+`examples/room`'s `presence` joins the room in the generator's
+frame and leaves in its `finally` — state that lives exactly as
+long as the connection, held by no store, owned by no request.
+§9.5's "the server remembers nothing" is a rule about RECONNECT
+(any instance answers any reconnect; the resumed render derives
+everything from durable state); it says nothing against a
+connection's own locals, which are the connection's for as long as
+it lives. What does NOT exist is a way for the client to reach that
+memory. Mutations are separate, stateless server functions; a live
+loop learns of them only through shared state (`send` → `post` →
+`notify` → `watchMessages` re-yields). That path carries FACTS
+about the room. A rejection is a fact about a request, and the
+room's feed has no place for it — which is why `room`'s composer
+catches the rejected `send` into a client signal, and why the
+transcript acknowledges the post through `until` on its own echo
+instead of through the mutation's response.
+
+**Three shapes, in order of how much they cost.**
+
+- **(A) Feed echo — today.** The mutation writes shared state; every
+  loop watching that state re-yields. Acknowledgement is the echo
+  (`until` on the authoritative view, never on the tab's own
+  optimistic row). Rejections are client state: one signal, cleared
+  by the next attempt. No mechanism; adequate wherever a rejection
+  is rare and its message is generic.
+- **(B) Sibling response — the recommended shape for rejections,
+  unverified.** The mutation is single-flight into a BOUNDED sibling
+  address — the composer, the form, the row's own editor — not into
+  the live one. Its response carries the rejection as server
+  markup (the Q5 rule in §10.3: a rejection's home is the response
+  that produced it), and the live transcript keeps streaming
+  untouched. No new mechanism, but two things to verify: the flight
+  collector must carry a non-redirect result alongside regions
+  (`notes` exercises redirects only), and the target must never be
+  the live address — §9.5 client-face item 4 makes a single-flight
+  region for a live address a supersession, hence a death, hence a
+  reconnect that would render the rejection away.
+- **(C) Connection inbox — the LiveView shape.** The client sends an
+  event UP the connection's identity (a `POST` to the live address
+  carrying the connection id, or any mutation call carrying it in a
+  header); in the live scope the component reads `inbox()`, an
+  async iterable of what arrived, `for await`s it beside its
+  sources, validates, updates its locals, and re-yields with the
+  rejection — or the "3 people typing", or the per-viewer cursor —
+  rendered into THIS connection's markup only. Combined with
+  attribute slots on the latency-sensitive positions this is
+  LiveView with two things LiveView lacks: HTML-first t = 0 with no
+  socket required to render, and optimistic feel that does not
+  depend on the round trip.
+
+**What (C) costs, honestly.**
+
+1. *Routing.* The event must reach the instance holding the
+   connection: sticky routing or a per-process bus; multi-instance
+   needs a broker. §9.5 deliberately avoided connection registries
+   and "any instance answers any reconnect" is what makes the live
+   tier deployable on ordinary backends. (C) narrows that
+   precondition the way "backends that hold connections" already
+   narrows it — documented like the HTTP/2 one, not hidden.
+2. *Loss on death.* Connection memory dies with the connection. By
+   the re-derivability line (§9.3: if losing the transport loses
+   the value, the value belonged in durable state) only things that
+   are FINE to lose may live there — presence, typing, in-progress
+   validation, the last rejection. A draft is not one of them.
+   Chaos reconnect is the enforcement: it must make visible what
+   state a death dropped.
+3. *Latency.* Acknowledgement is a round trip through the stream —
+   LiveView's known weakness. Attribute slots cover the optimistic
+   positions, so the weakness is confined to server-owned state,
+   which is the state that could not be optimistic anyway.
+4. *Surface.* A server authoring primitive (`inbox()` or its
+   equivalent), a client verb that names a connection, a
+   server-minted connection id the client can present (the SSE
+   `id:` field or a header on the first event is the natural home).
+   Every one of these is public API — flagged.
+
+**Position.** (A) is what ships. (B) is the answer to the question
+that raised this seed, and it needs a verification pass, not a
+design. (C) is a real design and should be gated on an example
+that (A) + (B) cannot express — per-viewer validation as you type,
+shared cursors, typing indicators — never on error handling. Errors
+do not justify (C); if nothing else does either, (C) stays a seed.
+
+**Deliberately absent:** WebSocket (still the carrier where an
+upstream is native; still deferred until (C) is more than a seed),
+any change to stateless reconnect, any cursor protocol.
+
+---
+
+## 10. Fit — where the design sits in the solution space (2026-09-28)
+
+Recorded from the conversation after the Stage 7 gate (§9.2.3), with
+Stages 1–8 built and PR #3704 the last heavy feature. Two questions
+were asked before advising anyone: where do server components fit,
+and which parts of what was built might be unnecessary. This section
+answers the first and frames the second as candidates with the
+evidence each needs. It sits above §9.2.3's placement principle —
+that principle decides where one ELEMENT lives; this section decides
+whether a COMPONENT should be a server component at all.
+
+### 10.1 Three axes, not one
+
+"How interactive is it" is the axis everyone reaches for and it does
+not sort the examples: a chat room and TodoMVC are both interactive
+and land in opposite corners. Three axes do:
+
+1. **Content weight** — how much markup per unit of state. A story
+   list is heavy; a checkbox is a bit.
+2. **Origin of change** — who changes the truth. Server-originated
+   (other users, time, systems) or client-originated (this user).
+   This axis decides *live*.
+3. **Client-owned position density** — on one element, the ratio of
+   positions the client owns (a class condition, a handler, a
+   `checked`) to content the server owns. This axis decides
+   *attribute slot vs client component*, and it is the one TodoMVC
+   fails.
+
+### 10.2 The five quadrants
+
+Each: the shape, the examples that have it, the mechanism that
+serves it, where a rejection lives, and a standing.
+
+**Q1 — Reading surfaces.** Heavy content, server-originated change,
+almost no client positions. Story lists, note lists, docs,
+dashboards, reports. Served by the core (Stages 1–5): single-copy
+HTML (A1), addresses (A3) and sites (A4), navigation as rebind,
+refetch as morph, hover preload isolation as a non-event, `$key`
+survival. The client ships no rendering code and no data layer for
+this content. Rejections: none — the render's own failures reach
+boundaries, `:error` records, and truncation (L1, §5.5). *Standing:
+the unambiguous best case; every axiom earns its keep here.*
+Examples: `hackernews`, `notes`' list.
+
+**Q2 — Feeds.** Heavy content that keeps changing without this
+user: transcripts, rooms, tickers, AI generation, presence. Served
+by live holes (Stage 3), liveness at t = 0 (Stage 4), the `live`
+transport (Stage 8): the document is v0, reconnect is conditional,
+one connection per address. This is the only quadrant where server
+memory legitimately exists — per connection, for the connection's
+life (`presence`'s join/leave). Rejections: a mutation into a feed
+is acknowledged by the feed's echo; the rejection itself has no
+home in the feed — §9.6. *Standing: second-strongest, and the case
+nothing else in the field serves without a client component per
+widget.* Examples: `room`, `chat`.
+
+**Q3 — Annotated server markup.** Heavy content with one or two
+client-owned positions per element: a `selected` class on a nav
+link, a copy button's handler, an expand toggle, `hidden` from a
+client-side filter, a table's sort indicators. Served by attribute
+slots (§9.2.3) with markup slots for the elements that exist only
+because of client state. The ratio is one to ten. Rejections: none
+(behavior only). *Standing: this is what attribute slots are for,
+and the advice writes itself — bind the position, don't lift the
+element.* Examples: `chat`'s `codeBlock`, `notes`' `search` field.
+
+**Q4 — Widgets.** Small data, this user's alone, changing faster
+than a round trip, with dense interaction on every element:
+TodoMVC, forms, editors, drag and drop, canvases. Served by a
+client component — in a markup slot when the shell around it is
+server markup — with the server component as shell and data
+source. Attribute slots CAN carry it (`todos-server` proved it:
+seven client-owned positions per row) and MUST NOT be the
+recommendation. Rejections: client state, trivially. *Standing: not
+a server-component case. The design's answer here predates Stage 7
+and is unchanged by it.* Example: `todos` (the SPA control).
+
+**Q5 — Collaborative lists.** Server truth that others see, mutated
+by this user, with optimistic feedback expected: toggling, voting,
+editing rows of a shared list. Both server- and client-originated
+at once, which is what makes it the hard quadrant. Served by
+single-flight mutations — the response carries the fresh regions
+AND the rejection — with attribute slots on the optimistic
+positions. Multi-flight (a write, then `refresh`) works and cannot
+carry a rejection: a refetch is a pure function of durable state.
+Rejections: in the mutation's response, server-rendered — a
+rejection is per request, not entity state, and its home is the
+response that produced it. Transport failures: client, one generic
+state, never per-row bookkeeping. *Standing: carries the most
+concepts of any quadrant.* `todos-server` is its worst case and not
+representative: it is a Q4 app wearing Q5 clothes. Example: `notes`'
+save/delete (single-flight by redirect); a proper Q5 example is a
+follow-up.
+
+The examples on the map:
+
+```text
+example          quadrant        role
+───────          ────────        ────
+hackernews       Q1              front door for the core
+hackernews-spa   —               client control for hackernews
+notes            Q1 + Q3 + Q5    list + search slot + single-flight mutations
+chat             Q2 + Q3         live generation + attribute slot
+room             Q2              live transport end to end
+todos            Q4              client control for todos-server
+todos-server     Q5 (worst)      acceptance gate for §9.2.3; not advice
+effect           —               data tier, no frames
+```
+
+### 10.3 Where a rejection lives — one rule per shape
+
+- A render's own failure → the boundary (L1, §5.5).
+- A single-flight rejection → the response, as markup (Q5).
+- A multi-flight rejection → nowhere good; the refetch cannot carry
+  it. This is what forced `errors` onto the client in
+  `todos-server`. The shape stays supported and stops being taught
+  for optimism.
+- A transport failure → the client, one generic state.
+- A rejection in the live quadrant → §9.6: today the client (A); the
+  recommended home is a bounded sibling's single-flight response
+  (B); server memory (C) is a design for other things.
+
+### 10.4 The advice, as rules of thumb
+
+1. **If the truth changes without this user, it is live.** Q2 —
+   declare it, and let the document be v0.
+2. **If the client owns more than a couple of positions on an
+   element, or the element exists because of client state, it is a
+   client component.** §9.2.3's placement principle decides this per
+   element; the ratio decides it per component. A server component
+   whose every element fails the ratio is a client component with a
+   server shell.
+3. **If this user changes the truth faster than a round trip, the
+   optimistic state is client-owned** and the server component is
+   the shell and the data source — Q4. When others must see the
+   change, it is Q5: single-flight, response carries the verdict.
+
+### 10.5 Candidates to evaluate against the map
+
+Candidates, not verdicts. Each names what it serves, the evidence
+today, its cost, a proposed disposition, and what would decide it.
+
+- **Multi-flight as the taught optimistic shape.** Serves Q5 by
+  composing plain server functions; required as plumbing. Evidence:
+  `todos-server` is built on it and needed a client error store to
+  compensate. Disposition: demote in the docs and examples, keep
+  the mechanism. Decides: rewrite `todos-server` around single-flight
+  with server-rendered rejections; if the row logic shrinks toward
+  the SPA's, the demotion is right.
+- **Attribute slots on dense elements.** Not a mechanism question.
+  The §9.2.3 record reads as if per-position binding is the default
+  for any server row; it should state the ratio and point Q4 at
+  client components. Disposition: docs.
+- **Container tier (Stage 5, projections across the border).**
+  Serves Q2's value-shaped live state — `chat`'s `usage` store is
+  exactly its case. Cost: ~7.1 KB brotli eager on every SC page
+  (size audit F4; B.2 plans the lazy load behind the server-driven
+  preload seam, §D). Disposition: pay-for-use, already planned. The
+  fit question — does any quadrant need it by DEFAULT — answers no,
+  which makes the packaging fix sufficient and deletion wrong.
+- **Live attribute holes (`data-lha`, Stage 3).** Serves Q2 when an
+  ATTRIBUTE, not content, changes server-side. Evidence: no example
+  is known to depend on it (to verify). Cost: attribute-area capture
+  and re-emission on both faces, plus the morph's handling.
+  Disposition: evaluate; if no example needs it, a candidate for the
+  live tier's pay-for-use split (size audit §E) or removal.
+- **Conditional reconnect (B4 have-list).** Serves Q2 with large
+  transcripts; paid only by `live`. Disposition: keep. The unbuilt
+  document-face ledger seeding (§9.5 client-face item 3) is the part
+  to question: it saves one morph per live frame per page load, and
+  quiet resume already guarantees no fallback flash. Decides:
+  measure the morph on `room` before building it.
+- **Liveness at t = 0 (Stage 4 `sc:live`, §9.5 B3).** Serves Q2
+  being HTML-first. Disposition: keep; re-read for simplification
+  once §9.6 decides whether connection state is a thing the design
+  acknowledges, since an inbox changes what "catch-up" means.
+- **Two mutation shapes.** Collapse to one story per quadrant:
+  single-flight for Q5, feed echo (or §9.6 B) for Q2, multi-flight as
+  plumbing nobody is taught. Disposition: docs.
+- **Behavior across the border (Stage 6 `_bnd`)** — retired by
+  §9.2.3. **`predict` (Stage 7 first form)** — retired by §9.2.2.
+  Nothing left to evaluate.
+
+### 10.6 Follow-ups this section implies
+
+- `server-components.md` gains a "when to reach for it" section
+  derived from 10.2 and 10.4; `11-server-components.md` links it.
+- §9.2.3 gains the ratio note.
+- `todos-server` becomes one of: the Q4 shape (the row as a client
+  component in a markup slot, honestly labelled as the shape for
+  widgets) or a proper Q5 example (single-flight with
+  server-rendered rejections). Its current shape should not be the
+  example anyone learns from. *Decided 2026-09-29: Q5; the per-example
+  plan is `documentation/plans/examples-grid-plan.md`.*
+- `notes` and `chat` become the front door for attribute slots.
+- §9.6 (B) gets its verification pass on the flight collector.

From bdf753bedbee977b90654b6f3abe5136c909a5eb Mon Sep 17 00:00:00 2001
From: Ryan Carniato <ryansolid@gmail.com>
Date: Tue, 29 Sep 2026 11:29:21 -0700
Subject: [PATCH 2/5] =?UTF-8?q?docs:=20examples=20plan=20=E2=80=94=20autho?=
 =?UTF-8?q?ring=20layout,=20binding=20slots,=20and=20the=20gaps=20ahead?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Records where the first example review (hackernews) landed before any
example code moves.

Authoring layout, every example with a server side: one screen is one
file, the server component a function-level "use server" inside its
query, so its name is the server function's name; a route file exports
only what the router reads; src/server/ holds server-only modules behind
the vite plugin's server-only marker, imported by namespace. Checked
against the directive pass (ids from the enclosing binding, server-only
references pruned from the client) and the plugin (component result
transforms and serverComponents independent of directive level).

Gaps, found by writing hackernews in its ideal shape; an example is not
done while one blocks it:

- G2, binding-slot execution: fills run once with component semantics,
  return an object only (type-constrained), per-element effects,
  handlers through assign; AttributeSlot becomes BindingSlot. Template
  slot / binding slot as the vocabulary.
- G1, text positions, after G2.
- G3, server-only modules: resolved by the plugin's marker.

Order changes to the gaps first, then hackernews, then the rest.

Co-authored-by: Claude via Cursor <noreply@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
---
 documentation/plans/examples-grid-plan.md | 193 ++++++++++++++++++----
 1 file changed, 165 insertions(+), 28 deletions(-)

diff --git a/documentation/plans/examples-grid-plan.md b/documentation/plans/examples-grid-plan.md
index 8546c6905..3ca523e5f 100644
--- a/documentation/plans/examples-grid-plan.md
+++ b/documentation/plans/examples-grid-plan.md
@@ -52,6 +52,49 @@ data is one line each side (`codeBlock={() => ({ onCopy })}` on the client,
 more than an object literal; where one does, that is a §9.2.3 ergonomics
 finding to raise, not something example code hides.
 
+**Authoring layout** (decided 2026-09-29, every example with a server
+side, twins included). One screen is one file; the directive marks the
+server part in place:
+
+- A server component is a function-level `"use server"` inside its client
+  wrapper, in the file that uses it:
+  `const getStory = query(async (id: string) => { "use server"; … }, "story")`.
+  The binding is the wrapper, so the name is the server function's name
+  (`getStory`, as any server function is named) and there is no second
+  name to invent. Actions likewise (`action(async (…) => { "use server"; … })`).
+- The route file holds the screen: its query with the server component
+  inline, server-only helpers the component renders (a recursive
+  `Comment`), the slot's type, and the route component with its fills
+  inline. Everything referenced only from `"use server"` bodies is pruned
+  from the client build.
+- A route file exports only what the router reads — its default component
+  and `preload`. The query, helpers and types stay module-private; a query
+  is exported only when another screen shares it.
+- `src/server/` holds only server-only modules (`hn.ts` and its capture,
+  `db.ts`), each beginning `import "server-only";` — the vite plugin's
+  boundary marker, which fails the build if the module reaches a client
+  bundle — and imported by namespace (`hn.getStory`, `db.getTodos`), so
+  the data layer echoing the server function's name reads as intended.
+  Mixed files (the route files) never import the marker. Inline in a mixed
+  file goes only markup and helpers whose leak would be harmless; secrets,
+  server APIs and heavy data live behind the marker.
+- `src/` is otherwise client and flat: `app.tsx`, `routes/`, `types.ts`.
+  No `lib/`, no `api.ts`; `components/` only when there are client
+  components.
+
+Verified against the toolchain (not yet by an example build): the
+directive pass extracts an inline `"use server"` inside `query(…)` and
+names it from the enclosing binding (`getStory-<hash>`, not an anonymous
+ordinal — stable across reordering); a module-level helper and a
+namespace import used only by server bodies are absent from the client
+output (compiler fixtures `nested-functions`, `dead-code-scoped`, and a
+direct run of the route-file shape); `serverFunctions.components` installs
+its result transforms globally and turns on `serverComponents` for every
+SSR compile, so neither depends on the directive's level; a non-exported
+wrapper registers exactly as an exported one. The first example PR
+confirms with its build: passing with the `server-only` markers in place
+(pruning precedes resolution) and failing on a deliberate client import.
+
 ## The map
 
 ```text
@@ -82,30 +125,53 @@ owning it (`chat`).
 
 ## Per-example disposition
 
-### `hackernews` — bottom-left, reads. KEEP; one binding change + README
+### `hackernews` — bottom-left, reads. KEEP; collapse → binding slot, layout, README. Blocked on G1, G2
 
 The front door: the simplest server component, navigation over server
 markup, a single stateful client concern. Its layering moment is comment
 collapse — client state on server-rendered elements deep in a tree, surviving
-navigation. Today that is a `Toggle` client component wrapping a markup slot
-(`toggle={p => <Toggle>{p.children}</Toggle>}`); under §9.2.3's placement
-principle a thread exists because the server has comments, so it is server
-markup and the collapse is an attribute slot (`class` and `onClick` bound on
-the server's own elements). Convert it; it is the idiomatic form and the
-example gets smaller. README repositioned to the coordinate and twin.
-
-### `hackernews-spa` — top-left. KEEP as is
-
-The twin; exists only as the comparison. README names the coordinate.
-
-### `notes` — middle-left, the RSC coordinate. KEEP; README only
+navigation. Today that is a `Toggle` client component wrapping a template
+slot (`toggle={p => <Toggle>{p.children}</Toggle>}`); under §9.2.3's
+placement principle a thread exists because the server has comments, so it
+is server markup and the collapse is a binding slot.
+
+Target shape (reviewed 2026-09-29): the recursive `Comment` is a server
+component and the client never sees the tree — per comment with replies, one
+`props.toggle({ $key: c.id })` call whose properties bind the toggle's
+`open` class, its `onClick`, its label (text position, G1) and the replies'
+`display`. The fill is the SPA twin's `Toggle` almost line for line, under
+G2's execution model: a signal in the fill body (it runs once per
+occurrence), getters over it, `onToggle` as a plain handler; `$key` makes
+the state follow the comment across refetches and die with it, as in the
+SPA. No store, no client components. Markup stays byte-identical to the
+twin's. In the authoring layout the screen is `routes/story.tsx` —
+`getStory` with the server component inline, `Comment`, the `Toggle`
+bindings interface and `ToggleSlot`, the route component with the fill
+inline — over `server/hn.ts`; `lib/`, `views.tsx`, `api.ts` and
+`components/` go. Example-local fixes riding along: `CommentDefinition`
+gains the `id` the data already carries; the README's "`$key` keeps it
+attached" claim becomes true (today no key is passed); the bundle check
+can grep `comment-children` too.
+
+### `hackernews-spa` — top-left. KEEP; layout only
+
+The twin; exists only as the comparison. README names the coordinate. Takes
+the authoring layout: each route file's `query` carries its server function
+inline over `server/hn.ts` (a plain server-only module, no longer a
+module-level `"use server"` file). Diffing the twins then shows the thesis
+at the route file: the same `getStory`, returning JSON in one and markup in
+the other, and client components in one only.
+
+### `notes` — middle-left, the RSC coordinate. KEEP; authoring layout + README
 
 React's own server-components demo ported: client islands whose state
 survives server updates around them, single-flight mutations by redirect,
-the search field as the idiomatic attribute slot. Its layering moment is the
+the search field as the idiomatic binding slot. Its layering moment is the
 editor keeping its draft while the sidebar list refreshes around it — the
 "shared client state preserved" line the HTML-partial tools cannot cross.
-Code unchanged; README repositioned. The overlap with `chat` (both are
+Behavior unchanged; the code moves to the authoring layout (queries and
+actions inline in the files that use them, `server/` for `db.ts`) and the
+README is repositioned. The overlap with `chat` (both are
 sidebar + viewer + mutations) is intentional: opposite sides of the grid,
 different audience.
 
@@ -124,7 +190,7 @@ history.
 
 Target: the write side of the HTMX corner, made enviable rather than
 mimicked. Server markup throughout; every mutation a compiler-claimed
-`<form action={x.with(...)}>` that works without JS; **one** attribute slot
+`<form action={x.with(...)}>` that works without JS; **one** binding slot
 with **one** position (`done`) fed by an optimistic store the action writes
 before it yields; single-flight responses that morph the row back. About
 ten lines of client code, no component beyond the root, instant toggles.
@@ -133,7 +199,7 @@ its error and a retry form. Layering moment: the optimistic toggle.
 
 Scope line: toggle, remove, and add are optimistic. If any of them needs
 more than a store write inside its action, it is not slick and it is out
-(the pending-row-for-add markup slot is the first candidate to fall; the
+(the pending-row-for-add template slot is the first candidate to fall; the
 README may describe it as the increment). Bulk actions stay plain forms.
 Pending feedback, if the router marks a submitting claimed form
 (`aria-busy` / `data-pending`), is CSS only — see V4.
@@ -146,8 +212,8 @@ the request, with the thread a `live` server component projecting durable
 state (close the tab, come back, caught up in one morph; two tabs agree);
 real model with the fake as no-key fallback; structured message parts;
 stop / regenerate / rename / delete as forms; the optimistic user bubble as
-a client element in a markup slot cleared by `until` on the echo; copy
-button as the attribute slot; native `<details>` for collapse. Failed
+a client element in a template slot cleared by `until` on the echo; copy
+button as the binding slot; native `<details>` for collapse. Failed
 generations are facts about the thread — durable, server-rendered with a
 retry. Absorbs `room`'s `/` page. The `usage` projection goes (token usage
 is a number on the finished message), which removes the container tier's
@@ -217,6 +283,75 @@ Off-grid on purpose. `rendering` is the one kitchen sink.
   runtime adopts `moveBefore()` behind feature detection (a runtime
   behaviour change — flagged, no API surface).
 
+## Gaps (found by writing the examples)
+
+Each example is written in its ideal shape first. Where that shape needs
+something the framework lacks, the gap is recorded here and the example is
+not done while it blocks it — no workaround in example code.
+
+Vocabulary (settled 2026-09-29): a server component hands the client one
+of two things, as Solid's compiler splits JSX into templates and bindings.
+A **template slot** (`Slot<Args>`) is placed; the client fills it with
+markup. A **binding slot** (`BindingSlot<Args, Bindings>`, today
+`AttributeSlot`) is called for an object whose properties the server puts
+at positions and never computes with. The name speaks to the server
+author, where the misuse happens: `DataSlot` and `PropsSlot` both read as a
+value to branch on, and a stand-in is always truthy.
+
+- **G2 — Binding-slot execution model.** First, because the rest builds on
+  it. The fill runs in a memo today (`bindDataOccurrence`), which makes a
+  plain-looking body reactive, disposes state created in it on the first
+  eager re-run, and made getters look necessary while one render effect
+  per occurrence made them pointless; handlers are dispatched through a
+  frames-own listener that bypasses delegation. Settled:
+  - A slot is always a function; each call is an occurrence with its own
+    scope, run once, untracked, with live args — as a template slot's
+    fill already runs. Args are optional; the scope is why a no-args slot
+    is still a function.
+  - It returns an object only: plain values (static), getters (reactive),
+    handlers and refs as values. Arrays, DOM nodes, functions and async
+    values are excluded — the existing `fill-shape` finding, and a
+    `SlotError` type constraint on `Bindings` (prototyped: a bad shape
+    fails at the server's use and the client's fill with the reason in
+    the message). The accessor return is deferred: getters are Solid's
+    idiom for a props-like object, `createMemo` in the body covers
+    "compute once, share", and a function return being an error today
+    keeps adding it later non-breaking.
+  - One render effect per consuming element, so a getter's change re-runs
+    only the elements that read it.
+  - Handlers and refs are read once and bound through `assign` /
+    `assignProp` — delegated as client JSX delegates, tuples and the
+    `dispatchAsInteraction` wrap for free; the own listener goes, fan-out
+    stays for merged refs only (duplicate named handlers are last-wins
+    since #3704).
+  - Rename `AttributeSlot` → `BindingSlot` and its diagnostic code.
+
+  Public changes (flagged): an eager plain-object fill stops updating;
+  handlers become delegated; the type is renamed and constrained; the
+  diagnostic code is renamed. Open, in the design
+  (`documentation/plans/binding-slot-execution.md`): the handler-tuple bug
+  (a server-side `onKeyDown={[row.key, 1]}` appears to lose its data —
+  reproduce first); the dev signal for top-level reads that no longer
+  track; an opaque `Bound<T>` server-side view of the bindings (touches
+  `jsx.d.ts`). The comments in `todos-server`'s `rowFor` and `notes`'
+  `searchField.ts` claiming per-position updates become true of getters
+  under this model; `notes`' getters stay (its keys have different
+  sources). Blocks `hackernews`.
+
+- **G1 — Text positions.** `{t.label}` as a child: a binding-slot value at
+  a text position. Today it renders nothing on either face and raises the
+  "placed as TEXT" finding (principles §9.2.3, open). Needs a content
+  marker pair (a parent-element `_s:text` marker so discovery stays in the
+  claim sweep), a text consumer beside G2's per-element consumers, morph
+  ownership of the range, and face parity; primitives only, anything else
+  stays a finding. Server side runtime-only as far as read — the resolver
+  already receives the stand-in. **Changes documented behavior**
+  (flagged). Design reviewed before code, after G2. Blocks `hackernews`;
+  `todos-server`'s count wants it.
+- **G3 — Server-only modules — resolved 2026-09-29.** The vite plugin's
+  `server-only` boundary marker enforces `src/server/` (authoring layout,
+  above). No framework change.
+
 ## Order
 
 _Revised 2026-09-29, #3704 merged: least work to most, one example per
@@ -225,16 +360,18 @@ written — the shape and its details are the deliverable. Server
 components are unreleased, so the flagships carry no deadline; the
 examples that are already right carry the most value per hour._
 
-1. README pass on the examples that are right today: `notes`,
-   `hackernews-spa`, `todos` (README only); `hackernews` (the `Toggle` →
-   attribute slot change, then README).
-2. `todos-server` reshape (V1–V4 first). Target decided 2026-09-29: the
+1. G2 (binding-slot execution), design then code.
+2. G1 (text positions), design then code.
+3. `hackernews` in the reviewed shape, with `hackernews-spa`'s layout.
+4. README and authoring-layout pass: `notes`, `todos` (and anything left
+   of `hackernews-spa`).
+5. `todos-server` reshape (V1–V4 first). Target decided 2026-09-29: the
    Q5 shape above — single-flight, server-rendered rejections, one
-   attribute slot with one position — not the Q4 wrap.
-3. `chat-flagship.md`, then `chat`.
-4. `board-flagship.md`, then `board`.
-5. Retire `room`.
-6. V5, then the `migrating-element` decision.
+   binding slot with one position — not the Q4 wrap.
+6. `chat-flagship.md`, then `chat`.
+7. `board-flagship.md`, then `board`.
+8. Retire `room`.
+9. V5, then the `migrating-element` decision.
 
 ## Follow-ups this plan creates
 

From bd1523bb054e5f5553c6c3e55a7cc30267152fa2 Mon Sep 17 00:00:00 2001
From: Ryan Carniato <ryansolid@gmail.com>
Date: Tue, 29 Sep 2026 12:13:41 -0700
Subject: [PATCH 3/5] docs: binding-slot execution design, and the plan's G2
 decisions

The design for gap G2. A binding slot's fill runs once, untracked,
under its occurrence's owner with live args, as a template fill and a
component body do; it returns an object only (runtime finding plus a
SlotError type constraint); value positions keep one render effect per
occurrence, client JSX's grouping, with text positions (G1) getting
their own effect as inserts do; handlers and refs bind once through
assign, delegated. AttributeSlot becomes BindingSlot.

Decisions: top-level reads in either fill warn through the existing
STRICT_READ_UNTRACKED; a server-side handler tuple becomes a finding;
no Bound<T> type; the diagnostic code is renamed with no alias. The
public changes are listed in the doc.

The plan's G2 entry now points at the design and records the same
decisions.

Co-authored-by: Claude via Cursor <noreply@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
---
 documentation/plans/binding-slot-execution.md | 236 ++++++++++++++++++
 documentation/plans/examples-grid-plan.md     |  39 +--
 2 files changed, 257 insertions(+), 18 deletions(-)
 create mode 100644 documentation/plans/binding-slot-execution.md

diff --git a/documentation/plans/binding-slot-execution.md b/documentation/plans/binding-slot-execution.md
new file mode 100644
index 000000000..dc36c0795
--- /dev/null
+++ b/documentation/plans/binding-slot-execution.md
@@ -0,0 +1,236 @@
+# Binding-slot execution
+
+Status: design for review, 2026-09-29. Gap G2 in
+[`examples-grid-plan.md`](./examples-grid-plan.md). Decisions recorded;
+ready for implementation review.
+
+A server component hands the client one of two slot kinds. A **template
+slot** (`Slot<Args>`) is placed and filled with markup. A **binding slot**
+(`BindingSlot<Args, Bindings>`, today `AttributeSlot`) is called by the
+server; the client's fill returns an object whose properties the server
+binds at positions — attributes, class names, style properties, handlers,
+refs, and text once G1 lands — and never computes with. This doc fixes how
+the binding slot's fill runs on the client.
+
+## What runs today
+
+`bindDataOccurrence` (`packages/web/frames/src/client.ts:384–530`):
+
+- The fill runs inside `createMemo` (line 389). A top-level read in its body
+  tracks, so an eager fill (`const done = toggled() === p.id`) re-runs on
+  every change, and anything the body created — a signal, a memo, an
+  `onCleanup` — is disposed and recreated with it.
+- One `createRenderEffect` per occurrence (lines 420–437) computes every
+  consuming element's positions from the memo's output; `assign` diffs the
+  writes. A getter read there tracks, but its change re-reads every
+  position of the occurrence.
+- Handlers go through a frames-own listener per element (lines 462–491) that
+  reads `output()[key]` at event time and fans out to every key bound at the
+  event. No delegation, no `dispatchAsInteraction` wrap. Refs go through a
+  stable dispatcher (lines 519–533). This replaced direct binding through
+  `assign` in `04a12a069`, for handler fan-out.
+
+The template slot's fill, by contrast, is called once, untracked, under a
+per-occurrence owner, with live props (lines 689–730; `runWithOwner` clears
+`tracking`). Same slot border, two execution models.
+
+So the fill `hackernews` wants — a signal in the body, getters over it, a
+handler — works today only because its memo tracks nothing and never
+re-runs. One eager read added to that body and the signal resets on every
+change. The model below makes the working case the contract.
+
+## The model (settled)
+
+1. **One call, one scope.** A binding slot is always a function. Each call
+   is an occurrence; its fill runs once, untracked, under the occurrence's
+   owner (the one `slotsFor` already creates, lines 605–640), with live
+   args — exactly as a template slot's fill and a component body run. State
+   created in the body lives as long as the occurrence. Args are optional;
+   the scope is why a no-args slot is still a function.
+2. **An object only.** The fill returns a plain object: plain values
+   (static), getters (reactive), handlers and refs as values. Arrays, DOM
+   nodes, functions and async values are excluded — at runtime the existing
+   `fill-shape` finding (lines 391–403), at the type level a constraint on
+   `Bindings` (below). Top-level reads are one-time reads, the same as in a
+   component body; getters are the reactive form, the same as a component's
+   props object.
+3. **One render effect per occurrence** for its value positions, as
+   today (lines 420–437). A getter's change re-reads the occurrence's
+   positions and `assign` writes only what changed. This is client JSX's
+   grouping: a template's dynamic attributes share one effect
+   (`attributeExpressions` fixture), and the cost of the coarser group is
+   re-reading a few getters, not DOM writes. An occurrence can span more
+   than one server template, so it can group more than client JSX would;
+   that costs reads, not effects. Text positions (G1) are the exception,
+   as inserts are in client JSX: each is its own range with its own
+   effect. Rebinds keep today's path (`ctx.onRebind` feeds the effect's
+   consumer list; an element that leaves gets a final empty write).
+4. **Handlers and refs bind once, through `assign`.** Read once when the
+   element binds, untracked, and handed to `assign`/`assignProp`
+   (`packages/web/src/client.ts:2534–2561`), which delegates the events
+   client JSX delegates, binds tuples, wraps with `dispatchAsInteraction`,
+   and removes the previous listener. A handler behind a getter is read
+   once, as `onClick={cond() ? a : b}` is in client JSX. The own listener
+   goes. The internal marker `on:<event>` (2.0 removed the authored `on:`
+   namespace — `MIGRATION.md:580`) maps to `"on" + event`, which
+   `assignProp` lowercases. Fan-out survives for refs only: several keys at
+   one ref position (`_s:ref="occ:a,occ:b"`) keep the stable dispatcher.
+   Handler duplicates are last-wins on the server since #3704, so a handler
+   position names one key.
+5. **Names.** `AttributeSlot` → `BindingSlot<Args, Bindings>`. The name
+   speaks to the server author, where misuse happens: a stand-in is always
+   truthy, so a binding slot's value must never be branched on, computed
+   with or passed along. `DataSlot` and `PropsSlot` both read as a value to
+   use.
+
+### The type constraint
+
+`Bindings` stays `extends object` (an F-bounded `J extends SlotOutput<J>` is
+a circular constraint, TS2313), and the slot's return type becomes
+`SlotOutput<J>`: `J` when valid, else a branded `SlotError<"reason">` that
+fails assignment with the reason in the message.
+
+```ts
+declare const slotError: unique symbol;
+type SlotError<M extends string> = { [slotError]: M };
+type SlotOutput<J> = J extends readonly unknown[]
+  ? SlotError<"binding slot output must be an object, not an array">
+  : J extends Node
+    ? SlotError<"binding slot output must be an object, not a DOM node">
+    : J extends (...args: any[]) => any
+      ? SlotError<"binding slot output must be an object, not a function">
+      : J extends PromiseLike<unknown> | AsyncIterable<unknown>
+        ? SlotError<"binding slot output must be settled, not async">
+        : Extract<keyof J, `$${string}`> extends never
+          ? J
+          : SlotError<`reserved key: ${Extract<keyof J, `$${string}`> & string}`>;
+
+export type BindingSlot<P = {}, J extends object = Record<string, unknown>> = {} extends P
+  ? (props?: P & { $key?: string | number }) => SlotOutput<J>
+  : (props: P & { $key?: string | number }) => SlotOutput<J>;
+```
+
+Prototyped (temp files, removed): `BindingSlot<{}, string[]>` errors with
+the array reason both where the server reads the slot and where the client
+passes its fill; `{ $x; ok }` errors with the reserved key; a valid
+`Toggle` slot is untouched on both sides.
+
+### Deferred: the accessor return
+
+A fill returning an accessor (`() => ({ … })`) would be one effect over a
+whole object. It is not added: getters are Solid's idiom for a props-like
+object, `createMemo` in the body covers "compute once, share across keys",
+and a function return is an error today (runtime finding and type), so
+adding it later is not breaking. Revisit when real fills show getters over
+one source reading as noise.
+
+## Checks made before writing
+
+- **The template fill runs untracked.** Yes: `runWithOwner(fillOwner, …)`
+  at line 726; `runWithOwner` clears `tracking` with the owner (the
+  comment at line 754 relies on it).
+- **The dev signal exists.** 2.0's `STRICT_READ_UNTRACKED`
+  (`08-dev-diagnostics.md:303`) fires for untracked reads in a scope
+  entered with `untrack(fn, label)` (`packages/signals/src/core/core.ts:1601`);
+  dev components use it with their name (`packages/solid/src/client/core.ts:284`),
+  `<Show>`/`<Match>` with theirs (`flow.ts:226`, `317`). The fill runs as
+  `untrack(() => fill(args), IS_DEV && "the \`row\` binding-slot fill")`.
+  No new diagnostic.
+- **Delegation keeps what fills rely on.** The delegated dispatcher calls
+  `handler.call(node, e)` or `handler.call(node, data, e)` and simulates
+  `currentTarget` (`client.ts:2621–2651`), so `this`, `currentTarget` and
+  tuples behave as the own listener's do (spec "a handler position receives
+  tuples…"). A non-delegated event (`myevent` in that spec) takes
+  `addEventListener`. Release is `assignProp(…, undefined, prev)`, which
+  clears the delegated slot or removes the listener.
+- **What relies on the memo re-running.** The examples do not: `todos-server`'s
+  `rowFor` and `notes`' `searchField` return getters over client state and
+  handlers that read lazily; `chat`'s `codeBlock` returns one static
+  handler. One spec does: the first case in
+  `packages/web/test/frames-attribute-slots.spec.tsx` (line 103) computes
+  `done` and `removed` eagerly from a signal and live args and asserts
+  re-runs (`runs`). It is rewritten to getters, and its assertions become
+  "ran once, positions updated". The case at line 878 ("a fill of getters
+  … runs once") already states the model.
+- **Benches.** `spread-slot-walk`, `spread-static-tail` and `border-walk`
+  are server benches (`packages/web/test/server/`); nothing measures the
+  client binding. Effect count is unchanged (decision 5), so none is added.
+
+## Public API changes (flagged)
+
+Each is a change to documented or observable behavior:
+
+1. **An eager plain-object fill stops updating.** A top-level read in the
+   fill body is a one-time read; dev warns `STRICT_READ_UNTRACKED`. Getters
+   are the reactive form.
+2. **State in a fill body lives as long as the occurrence** (today: until
+   the memo's next run).
+3. **Handlers become delegated** for the events client JSX delegates. A
+   binding handler's `e.stopPropagation()` no longer stops a native listener
+   on an ancestor, exactly as in client JSX.
+4. **Handlers and refs are read once.** A getter for a handler no longer
+   re-reads per event.
+5. **`AttributeSlot` → `BindingSlot<Args, Bindings>`**, with the return type
+   constrained (`SlotError`). No alias.
+6. **Diagnostic code `ATTRIBUTE_SLOT_POSITION` → `BINDING_SLOT_POSITION`.**
+7. **Server-side handler tuples become a finding** (decision 1).
+8. **Template fills warn `STRICT_READ_UNTRACKED`** on top-level reads
+   (decision 2).
+
+## Decisions (2026-09-29)
+
+1. **Server-side handler tuples are a finding.** Read, not yet reproduced:
+   `claimEntries` (`packages/web/src/server.ts:5085–5094`) flattens an array
+   at every position. At a handler position `onKeyDown={[row.key, 1]}` emits
+   `_s:on:keydown="occ:key"` and drops `1` silently; `[row.key, row.data]`
+   emits two keys, and the client reads `data` as a second handler and skips
+   it (`typeof h === "function"`). The flatten exists for merged refs
+   (`[[a, b], c]`). Fix: flatten only at `ref`; an array at a handler
+   position is a dev finding (`reason: "tuple"`) pointing at the fill —
+   return `onKeyDown: [handler, data]` from the fill, which `assignProp`
+   binds. The data a server tuple would carry is server data the args
+   already pass. Spec first (server marker, client dispatch).
+2. **Template fills get the same dev signal.** They run untracked with no
+   label today, so a top-level read there silently doesn't track either.
+   Both fills run under `untrack(fn, label)`; a new warning in an existing
+   context (flagged).
+3. **No `Bound<T>`.** It would not close the gap it targets: TypeScript
+   accepts any object in a condition, so `t.open ? a : b` type-checks with
+   an opaque `Bound<boolean>` exactly as with `boolean`, while every
+   attribute type in `jsx.d.ts` would have to accept it and the
+   shared-component idiom (`TodoRow` takes `RowBehavior` on both sides)
+   would need `Bound<RowBehavior> | RowBehavior`. The server's runtime
+   findings catch every coercion that goes through `Symbol.toPrimitive`
+   (comparison, arithmetic, template literal, `String()` —
+   `server.ts:4703–4724`); truthiness has no hook in the language and is
+   caught by nothing but the rule. That remaining hole is recorded, not
+   closed; a type-aware lint rule could reach it.
+4. **Naming.** `ATTRIBUTE_SLOT_POSITION` → `BINDING_SLOT_POSITION`; no
+   `AttributeSlot` alias; the spec file, §9.2.3, the frames skill and
+   `08-dev-diagnostics.md` move to the new vocabulary in the same change.
+
+5. **One effect per occurrence** (model point 3). Per element was
+   considered and dropped: it multiplied effects (four per `todos-server`
+   row) to save getter re-reads, and none of the problems this doc fixes
+   comes from the grouping.
+
+## Implementation
+
+1. Specs first, failing: a fill with a top-level signal read and a signal
+   created in the body (value frozen, state survives, dev warning); a getter
+   change writing only its position; a delegated handler; a release
+   through `assign`; the tuple case (decision 1).
+2. `bindDataOccurrence`: the fill called once under
+   `untrack(…, label)` in the occurrence's owner; the shape finding on its
+   result; the occurrence's one render effect over `consumers()` for value
+   positions through `assign`'s diff; handlers and refs read once when an
+   element binds, outside the effect's tracking.
+3. Server: `claimEntries` per decision 1; the diagnostic rename.
+4. Types: `BindingSlot`, `SlotOutput`, `SlotError` in
+   `packages/web/frames/src/server.ts`; type tests for each rejected shape
+   on both sides.
+5. Docs and skill in the same PR; changeset for `@solidjs/web`; the PR
+   body lists every change above under its own heading.
+
+G1 (text positions) follows: a text position is a consumer with its own
+effect beside the occurrence's value effect.
diff --git a/documentation/plans/examples-grid-plan.md b/documentation/plans/examples-grid-plan.md
index 3ca523e5f..70f60ce6c 100644
--- a/documentation/plans/examples-grid-plan.md
+++ b/documentation/plans/examples-grid-plan.md
@@ -300,10 +300,9 @@ value to branch on, and a stand-in is always truthy.
 
 - **G2 — Binding-slot execution model.** First, because the rest builds on
   it. The fill runs in a memo today (`bindDataOccurrence`), which makes a
-  plain-looking body reactive, disposes state created in it on the first
-  eager re-run, and made getters look necessary while one render effect
-  per occurrence made them pointless; handlers are dispatched through a
-  frames-own listener that bypasses delegation. Settled:
+  plain-looking body reactive and disposes state created in it on the
+  first eager re-run; handlers are dispatched through a frames-own
+  listener that bypasses delegation. Settled:
   - A slot is always a function; each call is an occurrence with its own
     scope, run once, untracked, with live args — as a template slot's
     fill already runs. Args are optional; the scope is why a no-args slot
@@ -317,8 +316,10 @@ value to branch on, and a stand-in is always truthy.
     idiom for a props-like object, `createMemo` in the body covers
     "compute once, share", and a function return being an error today
     keeps adding it later non-breaking.
-  - One render effect per consuming element, so a getter's change re-runs
-    only the elements that read it.
+  - One render effect per occurrence for its value positions, as today —
+    client JSX's grouping (a template's attributes share one effect); a
+    getter's change re-reads the occurrence and `assign` writes only what
+    changed. Text positions get their own effect, as inserts do.
   - Handlers and refs are read once and bound through `assign` /
     `assignProp` — delegated as client JSX delegates, tuples and the
     `dispatchAsInteraction` wrap for free; the own listener goes, fan-out
@@ -326,23 +327,25 @@ value to branch on, and a stand-in is always truthy.
     since #3704).
   - Rename `AttributeSlot` → `BindingSlot` and its diagnostic code.
 
-  Public changes (flagged): an eager plain-object fill stops updating;
-  handlers become delegated; the type is renamed and constrained; the
-  diagnostic code is renamed. Open, in the design
-  (`documentation/plans/binding-slot-execution.md`): the handler-tuple bug
-  (a server-side `onKeyDown={[row.key, 1]}` appears to lose its data —
-  reproduce first); the dev signal for top-level reads that no longer
-  track; an opaque `Bound<T>` server-side view of the bindings (touches
-  `jsx.d.ts`). The comments in `todos-server`'s `rowFor` and `notes`'
-  `searchField.ts` claiming per-position updates become true of getters
-  under this model; `notes`' getters stay (its keys have different
-  sources). Blocks `hackernews`.
+  Design and decisions: `documentation/plans/binding-slot-execution.md` —
+  top-level reads in either fill warn through 2.0's existing
+  `STRICT_READ_UNTRACKED`; a server-side handler tuple (which loses its
+  data today — reproduce first) becomes a finding, the fill returning the
+  tuple instead; no `Bound<T>` type (truthiness on a stand-in stays caught
+  by the rule alone). Public changes (flagged): an eager plain-object fill
+  stops updating; fill state lives with the occurrence; handlers become
+  delegated and are read once; the type is renamed and constrained; the
+  diagnostic code is renamed; template fills gain the untracked-read
+  warning. The comments in `todos-server`'s `rowFor` and `notes`'
+  `searchField.ts` saying each position updates alone are corrected in
+  the README pass: getters re-read with their occurrence and only changed
+  positions are written. Blocks `hackernews`.
 
 - **G1 — Text positions.** `{t.label}` as a child: a binding-slot value at
   a text position. Today it renders nothing on either face and raises the
   "placed as TEXT" finding (principles §9.2.3, open). Needs a content
   marker pair (a parent-element `_s:text` marker so discovery stays in the
-  claim sweep), a text consumer beside G2's per-element consumers, morph
+  claim sweep), a text consumer with its own effect beside G2's, morph
   ownership of the range, and face parity; primitives only, anything else
   stays a finding. Server side runtime-only as far as read — the resolver
   already receives the stand-in. **Changes documented behavior**

From 1ebe184f597b18b320e978e7eae7e0a67840050a Mon Sep 17 00:00:00 2001
From: Ryan Carniato <ryansolid@gmail.com>
Date: Tue, 29 Sep 2026 12:23:54 -0700
Subject: [PATCH 4/5] docs: review fixes for the fit, live-mutation and
 examples-plan text
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

From the second verification pass on this PR:

- §9.6: LiveView renders static HTML before it connects (§9.5 already
  calls that its dead-then-connected cost); what it lacks is
  client-owned interactivity that works before and without the
  connection, and optimism that does not wait on the round trip.
- §9.6: room's presence is an entry in a module-level map whose
  lifetime is the connection, not state held by no store.
- §9 roadmap gains the Stage 9 entry §9.6's heading already names.
- §10: one line mapping its markup/attribute slot names to template
  and binding slots; hackernews leads the binding-slot front door, as
  the plan orders it.
- Plan: the fill rule allows a fill that owns state (signals plus the
  literal), which the hackernews target needs; V4's router feature is
  flagged as public router behaviour; board-flagship.md is marked to
  write first; the design-record path no longer splits inside its code
  span; the article is linked.

Co-authored-by: Claude via Cursor <noreply@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
---
 documentation/plans/examples-grid-plan.md     | 23 +++++++++++--------
 .../server-components-principles.md           | 20 +++++++++++-----
 2 files changed, 27 insertions(+), 16 deletions(-)

diff --git a/documentation/plans/examples-grid-plan.md b/documentation/plans/examples-grid-plan.md
index 70f60ce6c..2de61c4b1 100644
--- a/documentation/plans/examples-grid-plan.md
+++ b/documentation/plans/examples-grid-plan.md
@@ -5,9 +5,10 @@ and §9.6, with Stages 1–8 built and #3704 (attribute slots, second form)
 the last heavy feature. Status: DIRECTION AGREED in conversation; nothing
 here is built. This page is the checklist for the example set as a whole;
 the two flagships get their own plans (linked below) and this page does not
-design them. Design record: `documentation/server-components/
-server-components-principles.md` §10 (fit) and §9.6 (live mutations seed).
-The grid is the one in "The Grand Unifying Architecture of Frontend"
+design them. Design record:
+`documentation/server-components/server-components-principles.md` §10 (fit)
+and §9.6 (live mutations seed). The grid is the one in
+["The Grand Unifying Architecture of Frontend"](https://dev.to/playfulprogramming/the-grand-unifying-architecture-of-frontend-bhk)
 (dev.to, 2026-09-22): response window on the horizontal axis
 (request/response → persistent), affordance weight on the vertical
 (server-owned markup → client-owned state), and three responsibilities every
@@ -48,9 +49,10 @@ Priority order; a lower item never overrides a higher one.
 
 The trivial case must stay trivial: one client position with no per-item
 data is one line each side (`codeBlock={() => ({ onCopy })}` on the client,
-`onClick={block.onCopy}` on the server). No example may need a fill to be
-more than an object literal; where one does, that is a §9.2.3 ergonomics
-finding to raise, not something example code hides.
+`onClick={block.onCopy}` on the server). A stateless fill is the object
+literal; a fill that owns state is its signals plus the literal. No example
+may need more; where one does, that is a §9.2.3 ergonomics finding to
+raise, not something example code hides.
 
 **Authoring layout** (decided 2026-09-29, every example with a server
 side, twins included). One screen is one file; the directive marks the
@@ -221,9 +223,9 @@ only example — flagged, consistent with principles §10.5.
 
 ### `board` — top-right FLAGSHIP. NEW (own plan)
 
-Plan: `documentation/plans/board-flagship.md`. Pure data tier, no frames:
-one board of lists and cards as a `live` source, reconciled by id into an
-optimistic nested store; moves and reorders as optimistic writes with
+Plan: `documentation/plans/board-flagship.md` (to write first). Pure data
+tier, no frames: one board of lists and cards as a `live` source, reconciled
+by id into an optimistic nested store; moves and reorders as optimistic writes with
 `until`; two tabs converging; rejected moves reverting; presence. Drag
 within and between lists with pointer events, fractional ordering. Scope:
 create / rename / archive, titles only, no card detail. Absorbs `room`'s
@@ -275,7 +277,8 @@ Off-grid on purpose. `rendering` is the one kitchen sink.
   generator (the optimistic write) before the server call.
 - **V4 — Router pending state on a submitting claimed form.** Whether the
   router marks the form (`aria-busy` / `data-pending`) for the action's
-  life. If not, a small router feature, not an example hack.
+  life. If not, a small router feature (public router behaviour —
+  flagged), not an example hack.
 - **V5 — Media migration.** A playing native `<video>` and a YouTube
   `<iframe>` moved through the `<Show>` migration path, Chrome and
   Firefox, with and without `moveBefore()` in place of `insertBefore` in
diff --git a/documentation/server-components/server-components-principles.md b/documentation/server-components/server-components-principles.md
index d03356b16..536bca8cc 100644
--- a/documentation/server-components/server-components-principles.md
+++ b/documentation/server-components/server-components-principles.md
@@ -1082,6 +1082,8 @@ retired as a pole and survives only as potential authoring sugar.
    over HTTP/2 is the precondition. The seed's watermark (causal settlement for Stage 7) is retired:
    settlement is convergence (§9.2 amendment), and the two stages are
    independent. Plan: `documentation/plans/stage8-connection-transport.md`.
+9. **Stage 9 — Mutations through a live connection.** Seed recorded
+   2026-09-28 (§9.6); not scheduled.
 
 Ordering note (revised 2026-09-22): Stage 8 now precedes Stage 7,
 and the two are independent. The 08-18 reasoning below still holds
@@ -4043,8 +4045,9 @@ answer is not the reason to build what the seed describes.
 
 **The observation: per-connection server memory already exists.**
 `examples/room`'s `presence` joins the room in the generator's
-frame and leaves in its `finally` — state that lives exactly as
-long as the connection, held by no store, owned by no request.
+frame and leaves in its `finally` — an entry in the room's
+module-level map that lives exactly as long as the connection,
+owned by no request.
 §9.5's "the server remembers nothing" is a rule about RECONNECT
 (any instance answers any reconnect; the resumed render derives
 everything from durable state); it says nothing against a
@@ -4088,9 +4091,9 @@ instead of through the mutation's response.
   rejection — or the "3 people typing", or the per-viewer cursor —
   rendered into THIS connection's markup only. Combined with
   attribute slots on the latency-sensitive positions this is
-  LiveView with two things LiveView lacks: HTML-first t = 0 with no
-  socket required to render, and optimistic feel that does not
-  depend on the round trip.
+  LiveView with two things LiveView lacks: client-owned
+  interactivity that works before and without the connection, and
+  optimistic feel that does not depend on the round trip.
 
 **What (C) costs, honestly.**
 
@@ -4141,6 +4144,10 @@ answers the first and frames the second as candidates with the
 evidence each needs. It sits above §9.2.3's placement principle —
 that principle decides where one ELEMENT lives; this section decides
 whether a COMPONENT should be a server component at all.
+Slot names here predate the 2026-09-29 rename: a *markup slot* is
+a **template slot** (`Slot`) and an *attribute slot* a **binding
+slot** (`BindingSlot`; the code still says `AttributeSlot` until
+`documentation/plans/binding-slot-execution.md` lands).
 
 ### 10.1 Three axes, not one
 
@@ -4325,5 +4332,6 @@ today, its cost, a proposed disposition, and what would decide it.
   server-rendered rejections). Its current shape should not be the
   example anyone learns from. *Decided 2026-09-29: Q5; the per-example
   plan is `documentation/plans/examples-grid-plan.md`.*
-- `notes` and `chat` become the front door for attribute slots.
+- `hackernews`, then `notes` and `chat`, become the front door for
+  binding slots (the plan's order).
 - §9.6 (B) gets its verification pass on the flight collector.

From e2a39ce289364254b632288c49ac541b9e8a8cd5 Mon Sep 17 00:00:00 2001
From: Ryan Carniato <ryansolid@gmail.com>
Date: Tue, 29 Sep 2026 13:17:36 -0700
Subject: [PATCH 5/5] docs: text-positions design, and text joining the
 occurrence's effect

The design for gap G1. A binding-slot value placed as a child becomes a
client-owned position: the server emits a comment pair around it (the
t=0 value inside on the document face, empty on the stream face, as
attributes split), the claim sweep that already tests comments finds
it, the occurrence's one value effect writes it, and the morph skips
owned text ranges (today it would reset them to the server's text).
Primitives only; anything else is a finding. Runtime only.

Decisions: text writes join the occurrence's effect rather than taking
one per position (a primitive write is attribute-shaped; inserts get
their own effect for content generality), corrected in the binding-slot
design and the plan; raw-text parents are a documented rule, since the
SSR compile is shared and a check would cost every SSR output; the
marker spelling stands.

Co-authored-by: Claude via Cursor <noreply@cursor.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
---
 documentation/plans/binding-slot-execution.md |  12 +-
 documentation/plans/examples-grid-plan.md     |  19 ++-
 documentation/plans/text-positions.md         | 139 ++++++++++++++++++
 3 files changed, 157 insertions(+), 13 deletions(-)
 create mode 100644 documentation/plans/text-positions.md

diff --git a/documentation/plans/binding-slot-execution.md b/documentation/plans/binding-slot-execution.md
index dc36c0795..f2873d9fd 100644
--- a/documentation/plans/binding-slot-execution.md
+++ b/documentation/plans/binding-slot-execution.md
@@ -61,9 +61,10 @@ change. The model below makes the working case the contract.
    (`attributeExpressions` fixture), and the cost of the coarser group is
    re-reading a few getters, not DOM writes. An occurrence can span more
    than one server template, so it can group more than client JSX would;
-   that costs reads, not effects. Text positions (G1) are the exception,
-   as inserts are in client JSX: each is its own range with its own
-   effect. Rebinds keep today's path (`ctx.onRebind` feeds the effect's
+   that costs reads, not effects. Text positions (G1) join the same
+   effect: a binding value at a text position is a primitive, so its
+   write is attribute-shaped — client JSX gives an insert its own effect
+   for content generality a binding value never has. Rebinds keep today's path (`ctx.onRebind` feeds the effect's
    consumer list; an element that leaves gets a final empty write).
 4. **Handlers and refs bind once, through `assign`.** Read once when the
    element binds, untracked, and handed to `assign`/`assignProp`
@@ -232,5 +233,6 @@ Each is a change to documented or observable behavior:
 5. Docs and skill in the same PR; changeset for `@solidjs/web`; the PR
    body lists every change above under its own heading.
 
-G1 (text positions) follows: a text position is a consumer with its own
-effect beside the occurrence's value effect.
+G1 (text positions) follows
+([`text-positions.md`](./text-positions.md)): a text position is one more
+value position in the occurrence's effect.
diff --git a/documentation/plans/examples-grid-plan.md b/documentation/plans/examples-grid-plan.md
index 2de61c4b1..dfd15ff97 100644
--- a/documentation/plans/examples-grid-plan.md
+++ b/documentation/plans/examples-grid-plan.md
@@ -322,7 +322,7 @@ value to branch on, and a stand-in is always truthy.
   - One render effect per occurrence for its value positions, as today —
     client JSX's grouping (a template's attributes share one effect); a
     getter's change re-reads the occurrence and `assign` writes only what
-    changed. Text positions get their own effect, as inserts do.
+    changed. Text positions (G1) join that effect.
   - Handlers and refs are read once and bound through `assign` /
     `assignProp` — delegated as client JSX delegates, tuples and the
     `dispatchAsInteraction` wrap for free; the own listener goes, fan-out
@@ -346,13 +346,16 @@ value to branch on, and a stand-in is always truthy.
 
 - **G1 — Text positions.** `{t.label}` as a child: a binding-slot value at
   a text position. Today it renders nothing on either face and raises the
-  "placed as TEXT" finding (principles §9.2.3, open). Needs a content
-  marker pair (a parent-element `_s:text` marker so discovery stays in the
-  claim sweep), a text consumer with its own effect beside G2's, morph
-  ownership of the range, and face parity; primitives only, anything else
-  stays a finding. Server side runtime-only as far as read — the resolver
-  already receives the stand-in. **Changes documented behavior**
-  (flagged). Design reviewed before code, after G2. Blocks `hackernews`;
+  "placed as TEXT" finding (principles §9.2.3, open). Design and decisions:
+  `documentation/plans/text-positions.md` — a comment pair around the value
+  (`<!--_s:t=occ:key-->…<!--/_s:t-->`, the t=0 value inside on the
+  document face, empty on the stream face, as attributes split), found by
+  the claim sweep that already tests comments; the write in G2's
+  per-occurrence effect; the morph skipping owned text ranges (today it
+  would reset them); primitives only, anything else a finding; raw-text
+  parents (`<textarea>`, `<title>`, `<style>`, `<script>`) a documented
+  rule, since the SSR compile is shared. Runtime only, no compiler change.
+  **Changes documented behavior** (flagged). After G2. Blocks `hackernews`;
   `todos-server`'s count wants it.
 - **G3 — Server-only modules — resolved 2026-09-29.** The vite plugin's
   `server-only` boundary marker enforces `src/server/` (authoring layout,
diff --git a/documentation/plans/text-positions.md b/documentation/plans/text-positions.md
new file mode 100644
index 000000000..ae7947484
--- /dev/null
+++ b/documentation/plans/text-positions.md
@@ -0,0 +1,139 @@
+# Text positions
+
+Status: design for review, 2026-09-29. Gap G1 in
+[`examples-grid-plan.md`](./examples-grid-plan.md); builds on
+[`binding-slot-execution.md`](./binding-slot-execution.md) (G2), and lands
+after it. Decisions recorded; ready for implementation review.
+
+A binding slot's value placed as a child — `<a>{t.label}</a>`,
+`<strong>{list.remaining}</strong> items left` — becomes a position the
+client owns, as attributes, class names, style properties, handlers and
+refs already are. Principles §9.2.3 deferred it ("needs a marker pair in
+content, deferred to keep this round to attributes"). `hackernews` needs it
+for the toggle's label; `todos-server`'s count wants it.
+
+## What happens today
+
+- **Server.** A compiled child hole passes the stand-in through `escape`
+  unchanged (non-attribute objects return as-is, `server.ts:5311–5340`), and
+  the resolver's branch for it (`server.ts:5962–5969`) renders nothing on
+  either face and raises the `text` finding (`slotTextPosition`,
+  `4750–4762`): "Text is not a bindable position yet."
+- **Attributes, for comparison.** `slotAttribute` (`4814–4824`) renders the
+  t=0 value on the document face (`sv.f === SLOT_FACE_DATA`), nothing on the
+  stream face, and a marker either way; the client writes the value when it
+  binds. The morph reads the incoming element's markers and leaves owned
+  positions alone (`ownedPositions`, `frame-client.ts:2555–2577`).
+- **The morph and text.** Comments and text nodes are always `compatible`
+  (`frame-client.ts:2522–2526`) and `morphNode` overwrites their data
+  (`2685–2687`). A client-owned text node would be reset to the server's
+  text on every refetch — empty on the stream face — and with no consumer
+  change nothing rewrites it. Skipping owned text in the morph is required,
+  not optional.
+
+## The model
+
+1. **Server emit.** The resolver branch becomes a marker pair around the
+   value: `<!--_s:t=<occurrence>:<key>-->` + text + `<!--/_s:t-->`. On the
+   document face the text is the t=0 value, escaped; on the stream face it
+   is empty — exactly `slotAttribute`'s split. `null`, `undefined` and
+   booleans render empty, as a client insert renders them. A markup-face
+   read (`sv.f === SLOT_FACE_MARKUP`) keeps `slotMarkupRead`'s finding and
+   emits an empty pair. The entry is `slotEntry`'s encoding, whose alphabet
+   has no `>`, so the entry cannot close the comment. After the pair
+   `ssrTextTail` is false: comments already separate text nodes.
+2. **Why a pair.** A single start marker cannot work on either face: on the
+   stream face the value is empty, so there is no text node to find; on the
+   document face the value merges with adjacent static text into one node
+   (`3 items left`). The end marker bounds the range in both cases.
+3. **Discovery.** `collectSlots` (`frame-client.ts:2349–2380`) already
+   visits every child node of server-owned elements, and already tests
+   comments (`slotStartId`). A text start marker registers a consumer
+   position `{ pos: "text", key, start }` on its parent element, beside
+   that element's attribute positions, and the walk continues after the end
+   marker. It never enters slot-range interiors or nested frames, so only
+   server-owned markup can hold one. `consumersEqual` also compares
+   `start`. No parent-element marker is needed: the walk that finds slot
+   ranges finds these at no extra traversal.
+4. **Client write.** The occurrence's one value effect writes a text
+   position as `node.data = String(v)` into the range's one text node,
+   creating it between the markers when absent (the stream face, or an
+   empty t=0 value). Primitives only: a string or number renders; `null`,
+   `undefined` and booleans clear; anything else (an object, array, node,
+   function) is a dev finding (`reason: "text-shape"`) and clears. Markup
+   belongs in a template slot. Client JSX gives an insert its own effect
+   because an insert takes any content (arrays, nodes, components) and
+   reconciles it; a primitive-only text write is attribute-shaped, so it
+   joins the occurrence's effect with the other value positions.
+5. **Morph ownership.** In `reconcileChildren` (`2863–2974`), an incoming
+   text start marker meeting an old one with the same data skips both
+   ranges, keeping the old interior — the text analogue of the
+   same-slot-range skip at `2882–2887`. Any other case falls through to
+   ordinary reconciliation: the incoming pair lands, the sync sees the
+   consumer change, and the owning occurrence writes it. A text position
+   released by the server (its markers gone) is the server's again and gets
+   no final write — the rule `write()` already applies to released value
+   positions (`frames/src/client.ts:447–454`).
+6. **No relocation index.** Slot ranges are indexed frame-wide so a range
+   moved under another parent keeps its live interior. A text range's
+   interior is one text node the client rewrites on rebind, so there is
+   nothing worth carrying: text ranges match sibling-scoped only.
+
+## Checks made before writing
+
+- The compiled server template needs no change for ordinary parents: the
+  hole already reaches the resolver with the stand-in.
+- Occurrence, key and encoding reuse `slotEntry`/`encodeSlotKey`
+  (`server.ts:4794–4805`); the client decodes as `slotPositions` does.
+- Existing server spec to rewrite: `frame-attribute-slots.spec.tsx:963`
+  ("a stand-in placed as text … renders NOTHING at t=0 too"). Its
+  stringified and coerced cases stay findings.
+
+## Public API changes (flagged)
+
+1. **A binding-slot value as a child renders and binds.** Today it renders
+   nothing and warns; afterwards the document face shows the t=0 value and
+   the client owns the text. Documented behavior in §9.2.3 ("a text child
+   — is a dev finding and renders nothing on either face") changes.
+2. **The `text` finding reason is retired**; a new reason, `text-shape`,
+   names a non-primitive value at a text position.
+3. **New wire marker** `<!--_s:t=…-->` / `<!--/_s:t-->` in server
+   component HTML (internal protocol, but visible in the output).
+
+## Decisions (2026-09-29)
+
+1. **The occurrence's effect writes text** (model point 4), not an effect
+   per text position; `binding-slot-execution.md` and the plan are
+   corrected to match.
+2. **Raw-text parents are a documented rule, not a check.** Inside
+   `<textarea>`, `<title>`, `<style>` and `<script>` a comment is literal
+   text, so the markers would land in the text. Nothing can see this
+   cheaply: the resolver does not know the parent, and the SSR compile is
+   one compile — `serverComponents` is a setting on it, not a separate
+   transform — whose child holes in those parents already go through the
+   ordinary `_$ssr` hole (`attributeExpressions` fixture, lines 482 and
+   562), so a compiler check would add a code path to every SSR output
+   for a misuse only server components can make. The rule: a binding
+   value is never the content of a raw-text element — `<textarea>` binds
+   `value=`, a style binds a style property. In `<textarea>` and
+   `<title>` a violation is visible on first render (the markers show as
+   text); in `<style>` and `<script>` it can fail silently, where a client
+   value has no idiomatic use. Revisit if the SSR compile ever needs
+   raw-text awareness for its own reasons.
+3. **Marker spelling** `<!--_s:t=<occurrence>:<key>-->` /
+   `<!--/_s:t-->`, as proposed.
+
+## Implementation, after G2
+
+1. Specs first, failing, on both faces: marker emission and escaped t=0
+   value; nullish and boolean empty; adjacent static text kept separate;
+   stream-face bind; a getter update; a refetch keeping client text;
+   another occurrence taking the same position; server release; a
+   non-primitive finding.
+2. Server: the resolver branch; `slotTextPosition` removed. No compiler
+   change.
+3. Client: discovery in `collectSlots`, `consumersEqual`, the write in the
+   occurrence's computation, the morph skip.
+4. Docs in the same PR: §9.2.3 (text joins the position kinds; the finding
+   list and the open item, and the raw-text rule), the frames skill,
+   `08-dev-diagnostics.md`; changeset for `@solidjs/web`.