@barefootjs/client 0.26.4 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/client",
-  "version": "0.26.4",
+  "version": "0.28.0",
   "description": "BarefootJS client package: reactive primitives (SSR-safe) plus browser runtime under the `/runtime` subpath (compiler target)",
   "type": "module",
   "main": "./dist/index.js",
@@ -55,7 +55,7 @@
     "directory": "packages/client"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.26.4"
+    "@barefootjs/shared": "0.28.0"
   },
   "peerDependencies": {
     "@barefootjs/jsx": ">=0.2.0"

package/src/reactive.ts

@@ -319,7 +319,8 @@ export function createSignal<T>(initialValue: T, __bfId?: string): Signal<T> {
 export function createEffect(fn: EffectFn, __bfId?: string, __bfKind: SubscriberKind = 'effect'): void {
   // Note: Nested effects are now allowed. runEffect() properly saves/restores
   // prevEffect, so nested effects correctly track their own dependencies.
-  // This enables synchronous component initialization in reconcileList.
+  // This enables synchronous component initialization inside loop reconcilers
+  // (mapArray/mapArrayAnchored).
 
   const effect: EffectContext = {
     fn,

package/src/runtime/claim-slots.ts

@@ -0,0 +1,647 @@
+/**
+ * Claim-plan interpreter and claimed-slot primitives (slot unification
+ * Steps A2/A3, `spec/slot-unification.md` §4/§5).
+ *
+ * This module is the ONE claim mechanism the spec's §4 target architecture
+ * describes: a compile-time `ClaimPlan` (per-slot child-index paths from a
+ * claim root down to the slot's anchor comment) is resolved ONCE — either
+ * eagerly (`claimSlots`) or lazily on first write (`lazySlots`) — and every
+ * later write goes through the held reference, never re-scanning the DOM.
+ * As of A3 the compiler emits claim plans for every content slot; the
+ * `patchSlotRange` and `updateClientMarker` mechanisms it superseded are
+ * deleted. `$t`/text-effect writes and `__bfText` are ALSO superseded for
+ * every emission site but one — see `dynamic-text.ts`'s docstring for the
+ * one deliberately-deferred case (`emitDynamicTextUpdates`'s
+ * `conditionalElems` path).
+ *
+ * Anchors are still the existing `<!--bf:sN-->…<!--/-->` marker pairs — SSR
+ * bytes are unchanged in Step A (§5, §6) so the new client claims against
+ * known-good SSR output. A path is only required to be valid AT THE MOMENT
+ * OF CLAIM (§2): once a 'text' Text node or a 'markup' boundary pair is
+ * held, subsequent writes never consult the path or the marker again, so a
+ * sibling slot's later variable-length change cannot invalidate anything
+ * already claimed.
+ *
+ * Kind contracts (mirroring the mechanisms being superseded — this is the
+ * "one slot concept with an identity contract" of §4):
+ *   - 'text': held ref is the Text node immediately after the anchor
+ *     comment. The CLAIM is non-mutating: it adopts that node when SSR
+ *     rendered the slot non-empty and otherwise holds the ANCHOR COMMENT
+ *     itself as a stand-in for the not-yet-created node, deferring
+ *     `document.createTextNode` to the first write that actually needs it
+ *     (`materializeText` reads the insertion point off that comment). That
+ *     one-field representation is deliberate — see `ClaimedTextSlot`. What
+ *     lets
+ *     `read` exist — a seed that only compares must be able to inspect a
+ *     slot without leaving an empty Text node behind on every row
+ *     (§9.3(1)). Writes are a `nodeValue` assignment, and once materialized
+ *     the node's identity never changes — the guarantee effect closures and
+ *     `mapArray`'s same-key path rely on.
+ *   - 'markup': held ref is BOTH boundary comments (start = anchor, end =
+ *     the matching `<!--/-->` found by a nesting-depth walk (any further
+ *     `bf:`-prefixed comment along the way opens a nested region). A string
+ *     write clears everything strictly between the boundaries and inserts
+ *     freshly `<template>`-parsed HTML before the end comment; a `Node`
+ *     write clears the range and splices the node in by identity (the
+ *     `__bfText` live-Node case). The boundaries themselves are never
+ *     removed, so the range stays writeable on every later write. Because
+ *     the end ref is already held, a write never needs to re-walk for
+ *     nesting depth — only the CLAIM does.
+ *
+ * Warn-don't-guess (§4, "one ownership rule"): a path that fails to resolve
+ * to its slot's own `bf:sN` comment — out of range, or shape drift where
+ * the path now lands on some other node — falls back to a marker scan
+ * within the claim root, using the same ownership rule as `query.ts`'s `$t`:
+ * a `bf:sN` comment owned by a nested `bf-s` scope (a child component's own
+ * same-numbered slot — ids are
+ * assigned per component, so collisions are expected) is never a candidate
+ * — UNLESS the id is `^`-prefixed (`BF_PARENT_OWNED_PREFIX`), meaning the
+ * marker is content the claiming component itself authored and merely
+ * forwarded through one or more descendants' `children` (see
+ * `findOwnedMarker`'s docstring); for those the ownership walk is skipped
+ * outright, matching `query.ts`'s `$()`. If neither the path nor the
+ * fallback scan finds an owned marker, that one slot is dropped with a
+ * `console.warn` and the rest of the plan still claims — never guess a
+ * boundary, and never let one bad slot sink its siblings. An EMPTY path
+ * (`[]`) skips straight to the scan without that first warning — the
+ * compiler emits `path: []` deliberately when a slot's position can't be
+ * statically pathed (slot unification A3), so a miss there is expected, not
+ * drift; only a non-empty path that fails to resolve signals a real shape
+ * mismatch worth warning about.
+ *
+ * Row-pristine lazy claim (§3(a)): `lazySlots` touches NOTHING until the
+ * first write, and that first write claims the WHOLE plan at once (not just
+ * the slot being written) — so no earlier write into one slot can shift a
+ * sibling slot's still-unclaimed path out from under it. A row that never
+ * updates never pays for a claim at all. `claimSlots` is the eager escape
+ * hatch for callers that cannot honor that invariant (streaming/portal
+ * paths that mutate row content before any write would occur, per §6's
+ * risk note) — it claims every slot in the plan immediately.
+ *
+ * Dedup, no trust-first-run (slot unification A3 follow-up): a 'markup'
+ * slot's write door holds a `last` value alongside its boundary refs. Every
+ * write — INCLUDING THE FIRST — clears-and-inserts unless the new string
+ * equals `last`, in which case the DOM touch is skipped. `last` starts
+ * `undefined`, which never equals a `String(...)`-coerced value, so the
+ * first write can never dedup away; it always patches. A `Node` write is
+ * deduped by identity (mirrors `__bfText`'s `value === current` check) and,
+ * like the string case, is never skipped on the first write — a freshly
+ * `createComponent`-built element is a distinct object from whatever the
+ * SSR markup rendered, so it always splices. 'text' writes stay a plain
+ * `nodeValue` assignment (already idempotent, per §5's design note) — no
+ * dedup state needed.
+ *
+ * The first write is never skipped on the assumption that the claimed
+ * range already matches SSR/CSR content ("trust-first-run") — that
+ * assumption only holds for a preamble-region row whose SSR content and
+ * the effect's mount-time recomputation are both derived from the exact
+ * same source data, so they cannot disagree. It is false in general: any
+ * markup slot whose value comes from client-only state that the server
+ * cannot see — `createSignal(readFromLocalStorage())`, a client-side region
+ * swap adopting HTML the server rendered from a different default — can
+ * genuinely differ from the SSR/CSR content on the very first write, and
+ * skipping that first write would silently leave the stale SSR default on
+ * screen until the NEXT change (regression pin: site/ui's
+ * `admin-gallery.spec.ts` cross-page time-range persistence test). So every
+ * write unconditionally applies unless deduped by value/identity — never
+ * because it happens to be the first one — for every 'markup' caller,
+ * including the preamble-region case (which only loses a same-value
+ * redundant-patch skip on mount, not correctness).
+ */
+
+import { BF_SCOPE, BF_PARENT_OWNED_PREFIX } from '@barefootjs/shared'
+import { commentsInScope } from './query.ts'
+import { commentScopeRegistry } from './scope.ts'
+
+/**
+ * A slot's compile-time descriptor. `path` is the list of child indices
+ * from the claim root to the slot's ANCHOR NODE — in Step A that anchor is
+ * always the existing `<!--bf:sN-->` start comment (markers are still
+ * emitted; Step B may point paths at other node kinds), so resolution
+ * walks `childNodes` by index with no assumption about the target's
+ * `nodeType` until the kind-specific claim inspects it. `id` is kept for
+ * diagnostics and as the marker-scan fallback's search key.
+ */
+export interface SlotSpec {
+  id: string
+  kind: 'text' | 'markup'
+  path: readonly number[]
+  /**
+   * Slot unification Step B (`spec/slot-unification.md` §3(b), §5 Step B):
+   * true when NO `<!--bf:id-->…<!--/-->` marker was emitted for this slot at
+   * all — `path` is then a path to the slot's POSITION itself (the LAST
+   * index is this slot's own index within its parent's `childNodes`, not an
+   * anchor comment to search from). Only ever set for `kind: 'text'` — a
+   * `'markup'` slot always keeps its markers (an empty-able range needs a
+   * physical anchor to splice into; see `spec/slot-unification.md` §3(b)
+   * case (ii)). Resolution CREATES a Text node at that position if SSR
+   * rendered the slot empty (nothing to adopt there yet) — see `claimOne`.
+   * The compiler emits this only when it has already proven the position
+   * safe (`client-only-elision.ts`); the runtime never re-derives it.
+   */
+  markerless?: boolean
+}
+
+export type ClaimPlan = readonly SlotSpec[]
+
+/**
+ * A claimed 'text' slot, represented by ONE field. `ref` is the live Text
+ * node once the slot is materialized, and until then — only possible for a
+ * MARKED slot SSR rendered empty — the slot's anchor Comment, which doubles
+ * as the record of where the Text node must be created. `nodeType`
+ * discriminates the two.
+ *
+ * Claiming a marked text slot therefore never mutates the DOM, which is
+ * what the read door depends on: a seed that only compares must not leave a
+ * trail of empty Text nodes across every row (`spec/slot-unification.md`
+ * §9.3(1)). Markerless slots keep the original eager creation and so always
+ * arrive here already materialized — see `claimMarkerlessText` for why
+ * deferring them would cost more than it saves.
+ *
+ * One field rather than a node-plus-site pair because this object is
+ * allocated once per slot per row: on a 1k-row list every extra field is
+ * paid a thousand times over (measured: +77KB/1k rows for a
+ * node+after+parent+index shape). `materializeText` re-reads the insertion
+ * point off the anchor at creation time rather than capturing it at claim
+ * time, so a sibling slot's write in between cannot stale it.
+ *
+ * Once materialized the node is held by identity forever, exactly as
+ * before: effect closures and `mapArray`'s same-key path rely on that.
+ */
+interface ClaimedTextSlot {
+  readonly kind: 'text'
+  /** Text node once materialized; the anchor Comment until then. */
+  ref: Text | Comment
+}
+
+/**
+ * A claimed 'markup' slot: both boundary comments, held by identity.
+ * Content lives strictly between `start` and `end`; both survive every
+ * write. `last` is the trust-first-run + dedup state (see module docstring)
+ * — `undefined` until the first write, a `string` once a string has been
+ * recorded/patched, or the live `Node` once one has been spliced in.
+ */
+interface ClaimedMarkupSlot {
+  readonly kind: 'markup'
+  readonly start: Comment
+  readonly end: Comment
+  last: string | Node | undefined
+}
+
+type ClaimedSlotRef = ClaimedTextSlot | ClaimedMarkupSlot
+
+/**
+ * The result of claiming a plan: a write door keyed by slot id. Writing an
+ * id that failed to claim (or was never in the plan) warns and no-ops —
+ * one bad/missing slot never breaks any other slot's writes.
+ */
+export interface ClaimedSlots {
+  write(id: string, value: unknown): void
+}
+
+/**
+ * A claimed plan that can be read as well as written. Separate from
+ * {@link ClaimedSlots} because a door is allocated PER ROW: giving every
+ * claim a reader costs an extra closure on every row of a list, read or not
+ * (measured: ~40KB/1k rows). Only the loops that need read-compare-write
+ * seeding (`spec/slot-unification.md` §9.3(1)) ask for this shape. Both
+ * shapes sit on the SAME claim (`claimRefs`) — this is a second accessor
+ * bundle, never a second way to resolve a position (§2's claim-once rule).
+ */
+export interface ClaimedSlotsRW extends ClaimedSlots {
+  /**
+   * Current DOM text of a 'text' slot. `''` when the slot rendered empty,
+   * `null` when the slot cannot answer (not a 'text' slot, or it failed to
+   * claim); `null` MUST be treated by the caller as "differs, write it".
+   */
+  read(id: string): string | null
+}
+
+/** `lazySlots`'s per-write function — the same shape `ClaimedSlots.write` has. */
+export type SlotWriter = (id: string, value: unknown) => void
+
+// --- path resolution ---
+
+/** Walk `childNodes` by index from `root`. No node-kind assumption — the
+ *  caller checks whether the result is actually the expected comment. */
+function resolvePath(root: Node, path: readonly number[]): Node | null {
+  let node: Node = root
+  for (const index of path) {
+    const child: Node | undefined = node.childNodes[index]
+    if (!child) return null
+    node = child
+  }
+  return node
+}
+
+function isSlotComment(node: Node | null, id: string): node is Comment {
+  return node != null && node.nodeType === Node.COMMENT_NODE && (node as Comment).nodeValue === `bf:${id}`
+}
+
+/**
+ * Fallback marker scan, used only when a slot's compile-time path fails to
+ * resolve to its own `bf:sN` comment (shape drift, or a plan built against
+ * a differently-shaped claim root). The ownership rule: a same-id marker
+ * owned by a nested `bf-s` scope (a child component's own slot — ids
+ * collide across components by design) is skipped so the fallback can
+ * never claim into a child's content.
+ *
+ * `commentsInScope` (not a bare `document.createTreeWalker(root, …)`) so a
+ * whole-item loop conditional's claim root (`insert.ts`'s detached
+ * `commentScopeRegistry` proxy for a `<!--bf-loop-i:key-->` anchor, #1665)
+ * resolves correctly: the proxy has no DOM children of its own — the row's
+ * real content lives as SIBLINGS of the registered comment — and
+ * `commentsInScope` already knows to walk that sibling range instead of
+ * `root`'s (empty) descendants. The ownership boundary adapts to match:
+ * every node in a comment-scope's range shares the registered comment's
+ * OWN parent element, so that (not the unreachable proxy `root`) is where
+ * the ancestor walk must stop.
+ *
+ * Parent-owned slots (`^`-prefixed id, `BF_PARENT_OWNED_PREFIX`) skip the
+ * ownership walk entirely — same carve-out as `query.ts`'s `$()` and its
+ * `findText` marker map. A `^sN` id is JSX children the CLAIMING component
+ * itself authored (e.g. `<Button><span>{displayText()}</span></Button>`)
+ * that only physically lands inside descendant components' DOM because it
+ * was forwarded through their `children` prop — every one of those
+ * descendants (Button, its own children, …) legitimately carries its own
+ * `bf-s` scope attribute, but that scope boundary says nothing about who
+ * authored THIS content. Without the carve-out, any slot forwarded more
+ * than zero levels deep is unfindable — every ordinary ancestor bf-s
+ * attribute trips the "nested scope" rejection meant for a same-numbered
+ * marker some unrelated component happens to render for itself.
+ */
+function findOwnedMarker(root: Element, id: string): Comment | null {
+  const marker = `bf:${id}`
+  const parentOwned = id.startsWith(BF_PARENT_OWNED_PREFIX)
+  const registryInfo = commentScopeRegistry.get(root)
+  const boundary = registryInfo ? registryInfo.commentNode.parentElement : root
+  for (const comment of commentsInScope(root)) {
+    if (comment.nodeValue !== marker) continue
+    if (parentOwned) return comment
+    let owned = true
+    for (let el = comment.parentElement; el && el !== boundary; el = el.parentElement) {
+      if (el.hasAttribute(BF_SCOPE)) {
+        owned = false
+        break
+      }
+    }
+    if (owned) return comment
+  }
+  return null
+}
+
+/**
+ * Find the matching `<!--/-->` end comment for a 'markup' slot's start
+ * comment: any further `bf:`-prefixed comment along the way opens a nested
+ * region (a leaf rendered inside this one can carry its own ordinary slot
+ * markers) and increments a depth counter so that region's own `/` doesn't
+ * prematurely close this outer range. Runs once, at claim time — writes
+ * never need this since the end ref is held afterward.
+ */
+function findMarkupEnd(start: Comment): Comment | null {
+  let depth = 0
+  let node: Node | null = start.nextSibling
+  while (node) {
+    if (node.nodeType === Node.COMMENT_NODE) {
+      const value = (node as Comment).nodeValue ?? ''
+      if (value.startsWith('bf:')) {
+        depth++
+      } else if (value === '/') {
+        if (depth === 0) return node as Comment
+        depth--
+      }
+    }
+    node = node.nextSibling
+  }
+  return null
+}
+
+/**
+ * Resolve one slot's anchor comment: try the compile-time path first, fall
+ * back to an owned marker scan on any miss (path resolves to nothing, or to
+ * a node that isn't this slot's own comment — shape drift), and warn on
+ * either the fallback-needed or the total-miss case — EXCEPT when the plan
+ * shipped an empty path (`spec.path.length === 0`, slot unification A3's
+ * "cannot be statically pathed" case, `spec/slot-unification.md` §5-A3):
+ * an empty path is a deliberate "no compile-time path available" marker,
+ * not a claim that index `0` addresses this slot, so going straight to the
+ * scan is the plan's INTENDED behavior, not a drift to warn about. Never
+ * throws — a bad slot returns `null` and the caller drops it from the
+ * claimed set.
+ */
+function resolveAnchor(root: Element, spec: SlotSpec): Comment | null {
+  if (spec.path.length > 0) {
+    const resolved = resolvePath(root, spec.path)
+    if (isSlotComment(resolved, spec.id)) return resolved
+    console.warn(
+      `[barefootjs] claim path for slot ${spec.id} did not resolve to its bf:${spec.id} marker; falling back to a scan`,
+    )
+  }
+
+  const found = findOwnedMarker(root, spec.id)
+  if (!found) {
+    console.warn(`[barefootjs] slot ${spec.id} marker not found; skipping`)
+  }
+  return found
+}
+
+/**
+ * Resolve a `markerless` 'text' slot (slot unification Step B): `path`'s
+ * LAST index is the slot's own position within its parent's `childNodes` —
+ * there is no anchor comment to walk from or scan for, since the compiler
+ * only ever sets `markerless` when it has already proven no marker is
+ * needed (`client-only-elision.ts`). If SSR/CSR rendered the slot non-empty,
+ * a Text node already sits at that position — adopt it. If SSR rendered it
+ * empty (the only case Step B currently elides — `/* @client *\/`
+ * expressions, always empty at claim time), nothing sits there yet — create
+ * one and insert it before whatever currently occupies that index (or at
+ * the end, if the index is past the end of `childNodes`). Never falls back
+ * to a marker scan — there is no marker to find — so a path miss here is a
+ * genuine, loud failure, not the "cannot be statically pathed" case
+ * `resolveAnchor`'s empty-path allowance covers.
+ */
+function claimMarkerlessText(root: Element, spec: SlotSpec): ClaimedTextSlot | null {
+  if (spec.path.length === 0) {
+    console.warn(`[barefootjs] markerless slot ${spec.id} has an empty path; skipping`)
+    return null
+  }
+  const parentPath = spec.path.slice(0, -1)
+  const idx = spec.path[spec.path.length - 1]
+  const parent = resolvePath(root, parentPath)
+  if (!parent) {
+    console.warn(`[barefootjs] markerless claim path for slot ${spec.id} did not resolve to a parent node; skipping`)
+    return null
+  }
+  const existing = parent.childNodes[idx] as Node | undefined
+  if (existing && existing.nodeType === Node.TEXT_NODE) {
+    return { kind: 'text', ref: existing as Text }
+  }
+  // Markerless slots keep the original eager creation. They exist only for
+  // Step B's `/* @client */` elision, which never applies inside a loop, so
+  // no markerless slot is ever a lazy-row seed target — deferring here would
+  // buy nothing and would need the parent+index pair the shape above avoids.
+  const node = document.createTextNode('')
+  parent.insertBefore(node, existing ?? null)
+  return { kind: 'text', ref: node }
+}
+
+/** Claim one slot per its kind's contract. `null` on any failure (already warned). */
+function claimOne(root: Element, spec: SlotSpec): ClaimedSlotRef | null {
+  if (spec.kind === 'text' && spec.markerless) {
+    return claimMarkerlessText(root, spec)
+  }
+  const anchor = resolveAnchor(root, spec)
+  if (!anchor) return null
+
+  if (spec.kind === 'text') {
+    const next = anchor.nextSibling
+    return { kind: 'text', ref: next?.nodeType === Node.TEXT_NODE ? (next as Text) : anchor }
+  }
+
+  const end = findMarkupEnd(anchor)
+  if (!end) {
+    console.warn(`[barefootjs] slot ${spec.id} has no end marker; skipping`)
+    return null
+  }
+  return { kind: 'markup', start: anchor, end, last: undefined }
+}
+
+// --- writes ---
+
+/**
+ * Create the Text node a claim deliberately did not create, at the position
+ * the claim recorded. Reached only from a write against a slot SSR rendered
+ * empty — the one case where the DOM genuinely has nothing to write into.
+ */
+function materializeText(slot: ClaimedTextSlot): Text | null {
+  const anchor = slot.ref as Comment
+  const parent = anchor.parentNode
+  if (!parent) return null
+  const node = document.createTextNode('')
+  parent.insertBefore(node, anchor.nextSibling)
+  slot.ref = node
+  return node
+}
+
+/** Current DOM text of a claimed 'text' slot; `''` while unmaterialized. */
+function readText(slot: ClaimedTextSlot): string {
+  return slot.ref.nodeType === Node.TEXT_NODE ? ((slot.ref as Text).nodeValue ?? '') : ''
+}
+
+function writeText(slot: ClaimedTextSlot, value: unknown): void {
+  const node = slot.ref.nodeType === Node.TEXT_NODE ? (slot.ref as Text) : materializeText(slot)
+  if (!node) return
+  node.nodeValue = String(value ?? '')
+}
+
+/**
+ * Pass a live Node through untouched; coerce anything else with `String`.
+ *
+ * The 'text' door's counterpart to {@link escapeTextOrNode}. A 'text' slot
+ * writes through `nodeValue`, which needs no escaping — routing it through
+ * `escapeText` would double-escape — but it DOES need the Node case
+ * separated out, because a Text node cannot host an element and
+ * `String(node)` destroys it: `[object HTMLDivElement]` in a browser, the
+ * serialized markup rendered as visible text under some DOM shims. Wrong
+ * either way, and silently so, which is why the split lives here rather
+ * than at each call site.
+ *
+ * A Node reaches a content slot whenever a child-position interpolation
+ * calls something that builds one — `props.renderRow(item)` handed an
+ * inline-JSX arrow, which the compiler lifts into a component whose call
+ * returns a real element. Whether such a call returns a string or a Node is
+ * not decidable from the expression's syntax (both are `CallExpression`), so
+ * the decision belongs at runtime, on the value.
+ *
+ * `String(value)`, not `String(value ?? '')`: a non-Node value must coerce
+ * exactly as the previous inline `String(...)` emission did. The nullish
+ * collapse stays where it already was, in {@link writeText}.
+ */
+export function textOrNode(value: unknown): string | Node {
+  if (typeof Node !== 'undefined' && value instanceof Node) return value
+  return String(value)
+}
+
+/**
+ * A Node landed on a slot claimed as 'text'. Promote the claim to the
+ * 'markup' contract in place — the anchor comment becomes `start`, its
+ * matching `<!--/-->` becomes `end` — so this and every later write on the
+ * id goes through {@link writeMarkup}, which already splices Nodes by
+ * identity.
+ *
+ * This is a promotion, not a re-claim: the anchor is the SAME comment the
+ * original claim resolved (§2's claim-once rule holds — no second position
+ * resolution). The Text node the claim adopted or created, if any, sits
+ * inside the new range and `clearMarkupRange` removes it on the write.
+ *
+ * `null` when the slot cannot host a Node — a markerless slot (Step B
+ * elision: no anchor to promote from) or a marked slot whose end comment is
+ * missing. Both warn: refusing loudly beats stringifying an element into
+ * visible `[object HTMLDivElement]`.
+ */
+function promoteTextToMarkup(slot: ClaimedTextSlot, id: string): ClaimedMarkupSlot | null {
+  const anchor = slot.ref.nodeType === Node.COMMENT_NODE
+    ? (slot.ref as Comment)
+    // Materialized: `claimOne` adopts/creates the Text node immediately after
+    // the anchor, so the anchor is its previous sibling — unless the slot is
+    // markerless, where there is no anchor at all and `isSlotComment` says so.
+    : isSlotComment(slot.ref.previousSibling, id) ? slot.ref.previousSibling : null
+  if (!anchor) {
+    console.warn(
+      `[barefootjs] slot ${id} was claimed as text and received a Node, but has no anchor marker to promote from; write ignored`,
+    )
+    return null
+  }
+  const end = findMarkupEnd(anchor)
+  if (!end) {
+    console.warn(
+      `[barefootjs] slot ${id} was claimed as text and received a Node, but has no end marker; write ignored`,
+    )
+    return null
+  }
+  return { kind: 'markup', start: anchor, end, last: undefined }
+}
+
+/** Remove every node strictly between `start` and `end` (both survive). */
+function clearMarkupRange(start: Comment, end: Comment): void {
+  const parent = end.parentNode
+  if (!parent) return
+  let node: Node | null = start.nextSibling
+  while (node && node !== end) {
+    const next = node.nextSibling
+    parent.removeChild(node)
+    node = next
+  }
+}
+
+function writeMarkup(ref: ClaimedMarkupSlot, value: unknown): void {
+  const { start, end } = ref
+  const parent = end.parentNode
+  if (!parent) return
+
+  // Slot markers (`__slot()`, `@barefootjs/client/slot.ts`): a caller-passed
+  // JSX prop that itself contains a component. Leave the server-rendered DOM
+  // untouched entirely — no write, no `last` update either, so a later real
+  // value still gets a correct dedup read. Mirrors `__bfText`'s identical
+  // guard (#1663).
+  if (value != null && (value as { __isSlot?: boolean }).__isSlot) return
+
+  if (typeof Node !== 'undefined' && value instanceof Node) {
+    // Identity dedup, mirrors `__bfText`'s `value === current` check — the
+    // same live node handed back again is a no-op. `ref.last` starts
+    // `undefined`, which no real Node is ever `===` to, so the first Node
+    // write always splices — a freshly rendered Node is never the
+    // SSR-rendered markup by identity.
+    if (value === ref.last) return
+    clearMarkupRange(start, end)
+    parent.insertBefore(value, end)
+    ref.last = value
+    return
+  }
+
+  const text = String(value ?? '')
+  if (text === ref.last) return // dedup: identical string, skip the DOM touch
+  clearMarkupRange(start, end)
+  const tpl = document.createElement('template')
+  tpl.innerHTML = text
+  parent.insertBefore(tpl.content, end)
+  ref.last = text
+}
+
+function writeSlot(refs: Map<string, ClaimedSlotRef>, id: string, value: unknown): void {
+  const ref = refs.get(id)
+  if (!ref) {
+    console.warn(`[barefootjs] no claimed slot for id ${id}; write ignored`)
+    return
+  }
+  if (ref.kind === 'text') {
+    // A 'text' slot cannot represent an element. Promote once, then fall
+    // through to the markup writer — which is also what makes the read door
+    // answer `null` for this id afterwards, i.e. "cannot answer, write it",
+    // the conservative direction.
+    if (typeof Node !== 'undefined' && value instanceof Node) {
+      const promoted = promoteTextToMarkup(ref, id)
+      if (!promoted) return
+      refs.set(id, promoted)
+      writeMarkup(promoted, value)
+      return
+    }
+    writeText(ref, value)
+  } else {
+    writeMarkup(ref, value)
+  }
+}
+
+/**
+ * Read half of the door. `null` means "cannot answer" — the slot is not a
+ * 'text' slot, or it never claimed — and every caller must treat that as
+ * "differs" and write. Conservative, never unsound. Reads are silent: a
+ * slot that failed to claim already warned when it did so.
+ */
+function readSlot(refs: ReadonlyMap<string, ClaimedSlotRef>, id: string): string | null {
+  const ref = refs.get(id)
+  if (!ref || ref.kind !== 'text') return null
+  return readText(ref)
+}
+
+// --- public API ---
+
+/**
+ * Claim every slot in `plan` against `root` NOW. Escape hatch for callers
+ * that cannot honor the row-pristine invariant `lazySlots` relies on
+ * (streaming/portal paths that may mutate row content before any write
+ * would naturally occur, per §6) — claim eagerly there instead.
+ */
+export function claimSlots(root: Element, plan: ClaimPlan): ClaimedSlots {
+  const refs = claimRefs(root, plan)
+  return { write: (id, value) => writeSlot(refs, id, value) }
+}
+
+/** Resolve every slot in `plan`; slots that fail to claim are simply absent. */
+function claimRefs(root: Element, plan: ClaimPlan): Map<string, ClaimedSlotRef> {
+  const refs = new Map<string, ClaimedSlotRef>()
+  for (const spec of plan) {
+    const ref = claimOne(root, spec)
+    if (ref) refs.set(spec.id, ref)
+  }
+  return refs
+}
+
+/**
+ * Lazy wrapper honoring the row-pristine invariant (§3(a)): nothing touches
+ * `root`'s DOM until the first write, and that first write claims the
+ * WHOLE plan at once — so no earlier write into a sibling slot can shift
+ * this row's still-unclaimed paths first. A row that never updates never
+ * pays for a claim at all.
+ */
+export function lazySlots(root: Element, plan: ClaimPlan): SlotWriter {
+  let claimed: ClaimedSlots | null = null
+  return (id: string, value: unknown) => {
+    if (!claimed) claimed = claimSlots(root, plan)
+    claimed.write(id, value)
+  }
+}
+
+/**
+ * The read-capable twin of `lazySlots`: the same deferred claim, exposed as
+ * the full `{ write, read }` door instead of a bare write function.
+ *
+ * Two entry points rather than one door with a `.read` property because the
+ * door is allocated PER ROW: attaching a reader to every writer costs the
+ * extra closures on every row in the list, whether or not it ever reads
+ * (measured: +84KB/1k rows). Loops that need read-compare-write seeding
+ * (`spec/slot-unification.md` §9.3(1)) pay for the reader; every other loop
+ * keeps the single-closure writer. There is still exactly ONE claim
+ * mechanism underneath — every entry point resolves through `claimRefs`,
+ * and the first access of either kind resolves the whole plan while the row
+ * is pristine (§2's claim-once rule; reads never open a second resolution
+ * path).
+ */
+export function lazyClaimSlots(root: Element, plan: ClaimPlan): ClaimedSlotsRW {
+  let refs: Map<string, ClaimedSlotRef> | null = null
+  const ensure = (): Map<string, ClaimedSlotRef> => (refs ??= claimRefs(root, plan))
+  return {
+    write: (id, value) => writeSlot(ensure(), id, value),
+    read: (id) => readSlot(ensure(), id),
+  }
+}