@barefootjs/client 0.27.0 → 0.28.1

package/src/runtime/claim-slots.ts

@@ -25,10 +25,18 @@
  * 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, CREATED if SSR emitted an empty value (`textNodeAfterComment`,
- *     exactly `$t`'s `tAfter` behavior). Writes are a `nodeValue` assignment
- *     — the Text node's identity never changes, which is the guarantee
- *     effect closures and `mapArray`'s same-key path rely on.
+ *     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
@@ -102,7 +110,7 @@
  */
 
 import { BF_SCOPE, BF_PARENT_OWNED_PREFIX } from '@barefootjs/shared'
-import { textNodeAfterComment, commentsInScope } from './query.ts'
+import { commentsInScope } from './query.ts'
 import { commentScopeRegistry } from './scope.ts'
 
 /**
@@ -136,10 +144,34 @@ export interface SlotSpec {
 
 export type ClaimPlan = readonly SlotSpec[]
 
-/** A claimed 'text' slot: the live Text node, held by identity forever. */
+/**
+ * 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'
-  readonly node: Text
+  /** Text node once materialized; the anchor Comment until then. */
+  ref: Text | Comment
 }
 
 /**
@@ -167,6 +199,24 @@ 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
 
@@ -324,11 +374,15 @@ function claimMarkerlessText(root: Element, spec: SlotSpec): ClaimedTextSlot | n
   }
   const existing = parent.childNodes[idx] as Node | undefined
   if (existing && existing.nodeType === Node.TEXT_NODE) {
-    return { kind: 'text', node: existing as Text }
+    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', node }
+  return { kind: 'text', ref: node }
 }
 
 /** Claim one slot per its kind's contract. `null` on any failure (already warned). */
@@ -340,7 +394,8 @@ function claimOne(root: Element, spec: SlotSpec): ClaimedSlotRef | null {
   if (!anchor) return null
 
   if (spec.kind === 'text') {
-    return { kind: 'text', node: textNodeAfterComment(anchor) }
+    const next = anchor.nextSibling
+    return { kind: 'text', ref: next?.nodeType === Node.TEXT_NODE ? (next as Text) : anchor }
   }
 
   const end = findMarkupEnd(anchor)
@@ -353,8 +408,98 @@ function claimOne(root: Element, spec: SlotSpec): ClaimedSlotRef | null {
 
 // --- writes ---
 
-function writeText(ref: ClaimedTextSlot, value: unknown): void {
-  ref.node.nodeValue = String(value ?? '')
+/**
+ * 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). */
@@ -403,19 +548,42 @@ function writeMarkup(ref: ClaimedMarkupSlot, value: unknown): void {
   ref.last = text
 }
 
-function writeSlot(refs: ReadonlyMap<string, ClaimedSlotRef>, id: string, value: unknown): void {
+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 ---
 
 /**
@@ -425,12 +593,18 @@ function writeSlot(refs: ReadonlyMap<string, ClaimedSlotRef>, id: string, value:
  * 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 { write: (id, value) => writeSlot(refs, id, value) }
+  return refs
 }
 
 /**
@@ -447,3 +621,27 @@ export function lazySlots(root: Element, plan: ClaimPlan): SlotWriter {
     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),
+  }
+}

package/src/runtime/component.ts

@@ -25,6 +25,41 @@ export function setParentScopeId(id: string | null): void {
   _parentScopeId = id
 }
 
+/** Where `mapArray` wants a fresh loop row connected before its `init` runs. */
+export type RowMountPoint = { container: Node; anchor: Node | null }
+
+// Ambient mount point for a loop row.
+//
+// A loop row created by `renderItem` has no placeholder to replace, so it
+// cannot use `mountAt` and its `init` runs detached (see the known-limitation
+// docstring in `__tests__/runtime/csr-loop-row-init-connected.test.ts`).
+// `mapArray` sets this around the `renderItem` call so the OUTERMOST
+// `createComponent` inside it connects the row at `container`/`anchor` before
+// running `init` — same guarantee `mountAt` gives the child-slot path.
+//
+// Consumed once (take-and-clear) so nested `createComponent` calls made from
+// the row's own init don't re-use the row's mount point.
+//
+// `setRowMountPoint` returns the previous value so a caller can restore it
+// instead of clearing to `null`. That matters because the ambient is a single
+// slot: a row whose own `init` drives a nested `mapArray` would otherwise have
+// the inner list's teardown blank out an outer mount point that had not been
+// consumed yet. Save-and-restore makes the slot behave like a stack without
+// paying for one.
+let _rowMountPoint: RowMountPoint | null = null
+
+export function setRowMountPoint(p: RowMountPoint | null): RowMountPoint | null {
+  const prev = _rowMountPoint
+  _rowMountPoint = p
+  return prev
+}
+
+function takeRowMountPoint(): RowMountPoint | null {
+  const p = _rowMountPoint
+  _rowMountPoint = null
+  return p
+}
+
 /**
  * Create a component instance with DOM element and initialized state.
  *
@@ -38,6 +73,10 @@ export function setParentScopeId(id: string | null): void {
  * @param name - Component name (e.g., 'TodoItem')
  * @param props - Props to pass to the component
  * @param key - Optional key for list reconciliation
+ * @param slot - Slot-relationship markers stamped as `bf-h` / `bf-m`
+ * @param mountAt - Placeholder this component replaces. When given, the
+ *   element is connected to the document *before* `init` runs — see
+ *   "Connect before init" below.
  * @returns Created DOM element
  *
  * @example
@@ -68,15 +107,49 @@ export function createComponent(
   props: Record<string, unknown> = {},
   key?: string | number,
   slot?: CreateComponentSlotInfo,
+  mountAt?: Element | null,
+): HTMLElement {
+  const element = materializeComponent(nameOrDef, props, key, slot, mountAt)
+  // `mountAt` is an unconditional obligation: callers used to run
+  // `ph.replaceWith(comp)` themselves on every outcome, so every path that
+  // did NOT consume the placeholder still owes the replacement — a missing or
+  // empty template (either mode), and the root-deferred-placeholder shape,
+  // which must stay detached so its self-replacement stays recoverable.
+  // `parentNode` (not `isConnected`) is the right "still unconsumed" probe: it
+  // survives a `mountAt` that was itself detached, which is the normal case
+  // during multi-root loop-body setup.
+  if (mountAt && mountAt.parentNode && element !== mountAt) {
+    mountAt.replaceWith(element)
+  }
+  return element
+}
+
+/**
+ * Build the element, connect it at `mountAt` when there is one, and run
+ * `init` — in that order, which is the whole point (see step 7b).
+ *
+ * Named "materialize" rather than anything with "unmounted" in it because it
+ * DOES mount: the connect has to happen inside, before `init`, and only the
+ * paths that cannot consume the placeholder leave that to `createComponent`.
+ */
+function materializeComponent(
+  nameOrDef: string | ComponentDef,
+  props: Record<string, unknown> = {},
+  key?: string | number,
+  slot?: CreateComponentSlotInfo,
+  mountAt?: Element | null,
 ): HTMLElement {
   // A bare callable shim invoked from user code (e.g. an object-literal
   // value `LOGOS[id]()` whose arrow the compiler hoisted into a component)
   // reaches us with no props (#1663). Normalize to an empty object so the
   // descriptor probes below don't throw on `undefined`.
   if (props == null) props = {}
+  // Take the row mount point BEFORE any template eval / init can run, so the
+  // outermost call for the row is the only one that can consume it.
+  const rowMount = mountAt ? null : takeRowMountPoint()
   // ComponentDef mode: use def directly instead of registry lookup
   if (typeof nameOrDef !== 'string') {
-    return createComponentFromDef(nameOrDef, props, key)
+    return createComponentFromDef(nameOrDef, props, key, mountAt, rowMount)
   }
 
   const name = nameOrDef
@@ -173,6 +246,35 @@ export function createComponent(
     element.setAttribute(BF_KEY, String(key))
   }
 
+  // 7b. Connect before init.
+  //
+  // `initFn` resolves context by DOM position (`useContext` walks
+  // `parentElement` from the current scope) and may measure layout. Both
+  // need this element to be in the document, so when the caller told us
+  // which placeholder we replace, do the replacement NOW rather than
+  // after init. Running init detached made `useContext` fall through to
+  // the global, last-writer-wins context store, so a child materialised
+  // after a sibling provider had run picked up the wrong provider's
+  // value. This aligns the CSR path with the SSR one, where the
+  // doc-order walker only ever inits elements already in the document
+  // (`hydrate.ts`).
+  //
+  // A root-level deferred placeholder is excluded: its init replaces
+  // `element` itself, which the block below recovers via a throwaway
+  // wrapper. Connecting first would make that replacement happen in the
+  // live DOM with no handle on the result, so this shape keeps the
+  // detached behaviour.
+  const rootIsDeferredPlaceholder = element.hasAttribute(BF_PLACEHOLDER)
+  if (mountAt && !rootIsDeferredPlaceholder) {
+    mountAt.replaceWith(element)
+  } else if (rowMount && !rootIsDeferredPlaceholder) {
+    // Loop row: no placeholder exists, so connect at the position `mapArray`
+    // handed down. The reorder step may move the row afterwards; any position
+    // inside the container yields the same ancestor chain, which is all
+    // `useContext`'s parentElement walk needs.
+    rowMount.container.insertBefore(element, rowMount.anchor)
+  }
+
   // 8. Set currentScope so provideContext/useContext are element-scoped.
   // This allows context providers in initFn to store context on this element.
   const prevScope = setCurrentScope(element)
@@ -184,7 +286,6 @@ export function createComponent(
   // `replaceWith` — but a detached root node can't replace itself in
   // place. Park it in a throwaway wrapper so the replacement lands
   // somewhere we can recover, then return the materialised child.
-  const rootIsDeferredPlaceholder = element.hasAttribute(BF_PLACEHOLDER)
   let placeholderWrapper: HTMLElement | null = null
   if (rootIsDeferredPlaceholder) {
     placeholderWrapper = parseHTML('<div></div>').firstChild as HTMLElement
@@ -532,7 +633,9 @@ function insertGetterChildren(element: HTMLElement, children: unknown): void {
 function createComponentFromDef(
   def: ComponentDef,
   props: Record<string, unknown>,
-  key?: string | number
+  key?: string | number,
+  mountAt?: Element | null,
+  rowMount?: { container: Node; anchor: Node | null } | null,
 ): HTMLElement {
   if (!def.template) {
     throw new Error('[BarefootJS] createComponent with ComponentDef requires a template function')
@@ -560,6 +663,16 @@ function createComponentFromDef(
     element.setAttribute(BF_KEY, String(key))
   }
 
+  // Connect before init, for the same reason the registry path does (see
+  // `materializeComponent` step 7b): `def.init` may resolve context by DOM
+  // position or measure layout, and neither works detached. Keeps `mountAt`
+  // one contract across both modes instead of a registry-only guarantee.
+  if (mountAt) {
+    mountAt.replaceWith(element)
+  } else if (rowMount) {
+    rowMount.container.insertBefore(element, rowMount.anchor)
+  }
+
   // Initialize
   def.init(element, props)
 

package/src/runtime/index.ts

@@ -82,12 +82,16 @@ export {
 export { getLoopChildren, getLoopNodes } from './loop-markers.ts'
 export { qsaItem, upsertChildItem } from './qsa-item.ts'
 export { mapArray, mapArrayAnchored } from './map-array.ts'
+// Lazy row graph (slot unification §9, L2) — keyed list rendering with no
+// per-row reactive resources; compiler targets it for eligible plain loops
+// (L3). See ./map-array-lazy.ts for the pinned row-plan contract.
+export { mapArrayLazy, type LazyRowEntry, type LazyRowPlan } from './map-array-lazy.ts'
 export { patchLeaf } from './patch-leaf.ts'
 
 // Claim-plan interpreter (slot unification A2/A3, spec/slot-unification.md)
 // — the ONE content-slot update mechanism, wired up by the compiler in A3.
 // Supersedes (deleted) `patchSlotRange` and `updateClientMarker`.
-export { claimSlots, lazySlots, type SlotSpec, type ClaimPlan, type ClaimedSlots, type SlotWriter } from './claim-slots.ts'
+export { claimSlots, lazySlots, lazyClaimSlots, textOrNode, type SlotSpec, type ClaimPlan, type ClaimedSlots, type ClaimedSlotsRW, type SlotWriter } from './claim-slots.ts'
 
 // Template registry
 export { registerTemplate, getTemplate, hasTemplate, type TemplateFn } from './template.ts'