@barefootjs/client 0.26.4 → 0.28.0

package/src/runtime/component.ts

@@ -2,7 +2,7 @@
  * BarefootJS - Component Creation
  *
  * Functions for dynamically creating component instances at runtime.
- * Used by reconcileList() when rendering components in loops.
+ * Used by mapArray()/mapArrayAnchored() when rendering components in loops.
  */
 
 import { getTemplate } from './template.ts'
@@ -25,14 +25,40 @@ export function setParentScopeId(id: string | null): void {
   _parentScopeId = id
 }
 
-// WeakMap to store props update functions for each component element
-// This allows reconcileList to update props when an element is reused
-const propsUpdateMap = new WeakMap<HTMLElement, (props: Record<string, unknown>) => void>()
-
-// WeakMap to store the current props for each component element
-// Used to pass props to existing elements when they are reused
-const propsMap = new WeakMap<HTMLElement, Record<string, unknown>>()
+/** 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.
@@ -47,6 +73,10 @@ const propsMap = new WeakMap<HTMLElement, Record<string, unknown>>()
  * @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
@@ -77,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
@@ -182,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)
@@ -193,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
@@ -214,14 +306,12 @@ export function createComponent(
     if (materialised && !materialised.hasAttribute(BF_PLACEHOLDER)) {
       // The deferred child was created in place of the placeholder.
       // `materialised` is the child's OWN element, created via
-      // upsertChild -> createComponent, which already registered itself
-      // (hydratedScopes / propsMap / registerPropsUpdate) keyed to the
-      // child with the child's own props. We must NOT re-register it here:
-      // overwriting propsMap/registerPropsUpdate with the *parent's* props
-      // would mis-key the child (e.g. a later getComponentProps would read
-      // the parent's props), and re-running the parent's init on an element
-      // whose placeholder is already gone could not re-materialise. So just
-      // restore the scope and return the already-registered child.
+      // upsertChild -> createComponent, which already marked itself
+      // hydrated with its own props. We must NOT re-run this function's
+      // own registration steps on it here — that would re-run the
+      // *parent's* init on an element whose placeholder is already gone
+      // and could not re-materialise. So just restore the scope and
+      // return the already-registered child.
       // (Parent-scope effects are unaffected: createEffect ownership lives
       // in the EffectContext tree, not the discarded placeholder element.)
       setCurrentScope(prevScope)
@@ -248,51 +338,9 @@ export function createComponent(
   // 12. Mark element as initialized
   hydratedScopes.add(element)
 
-  // 13. Store props and register update function for element reuse in reconcileList
-  propsMap.set(element, props)
-  registerPropsUpdate(element, name, props)
-
   return element
 }
 
-/**
- * Get the props stored for a component element.
- * Used by reconcileList to pass props to an existing element.
- */
-export function getComponentProps(element: HTMLElement): Record<string, unknown> | undefined {
-  return propsMap.get(element)
-}
-
-/**
- * Register a props update function for a component element.
- * When called, this function re-initializes the component with new props.
- */
-function registerPropsUpdate(
-  element: HTMLElement,
-  name: string,
-  _initialProps: Record<string, unknown>
-): void {
-  // Register update function that will be called by reconcileList
-  propsUpdateMap.set(element, (newProps: Record<string, unknown>) => {
-    // Re-initialize the component with new props
-    // This allows the component to capture new values (e.g., todo with editing: true)
-    // and set up new effects that reference the new values
-    const init = getComponentInit(name)
-    if (init) {
-      init(element, newProps)
-    }
-  })
-}
-
-/**
- * Get the props update function for an element.
- * Used by reconcileList to update props when reusing an element.
- */
-export function getPropsUpdateFn(element: HTMLElement): ((props: Record<string, unknown>) => void) | undefined {
-  return propsUpdateMap.get(element)
-}
-
-
 /**
  * Render a child component's template to an HTML string.
  * Used by compiler-generated template functions when a stateless component
@@ -471,18 +519,44 @@ export function escapeAttr(value: unknown): string {
  *
  * A nullish value renders as empty text — the JSX/Solid semantics the Hono
  * SSR reference follows (`{undefined}` / `{null}` produce no text), and
- * what the reactive text-update path already does (`dynamic-text.ts` and
- * `client-marker.ts` both `String(value ?? '')`). Only this initial-render
- * escape site used to stringify `undefined` / `null` into literal
- * "undefined" / "null" text, so a bare `{props.x}` on an absent prop
- * diverged from SSR at first paint (#2137). Non-nullish values (including
- * `0` and `false`) keep their `String()` form, matching the reactive path.
+ * what the reactive text-update path already does (`claim-slots.ts`'s
+ * `writeText`/`writeMarkup` and `dynamic-text.ts` all `String(value ?? '')`).
+ * Only this initial-render escape site used to stringify `undefined` /
+ * `null` into literal "undefined" / "null" text, so a bare `{props.x}` on
+ * an absent prop diverged from SSR at first paint (#2137). Non-nullish
+ * values (including `0` and `false`) keep their `String()` form, matching
+ * the reactive path.
  */
 export function escapeText(value: unknown): string {
   if (value == null) return ''
   return escapeAttr(value)
 }
 
+/**
+ * `escapeText`'s counterpart for a claimed 'markup' slot's REACTIVE write
+ * (slot unification A3 follow-up), where the value is a plain-JS expression
+ * that may resolve to either a string or a live `Node` (e.g. `{cond &&
+ * logo(id)}`, a hoisted `renderNode` callback, #1213). `writeMarkup`
+ * (`claim-slots.ts`) inserts a string via `<template>.innerHTML =`, which —
+ * unlike the old `__bfText`'s plain `Text.nodeValue =` assignment — DOES
+ * interpret HTML, so a raw un-escaped string is an injection/corruption
+ * risk exactly where the initial SSR/CSR TEMPLATE already calls
+ * `escapeText` on the same expression (`html-template.ts`'s
+ * `escapeTextSlotExpr`). A live `Node`, by contrast, must pass through
+ * untouched — `escapeText(node)` would stringify it to garbage, and
+ * `writeMarkup`'s own `instanceof Node` check needs the real object to
+ * splice in by identity. This is the single call every "dynamic JSX/text
+ * slot, value may be a Node" emission site (`emit-reactive.ts`,
+ * `stringify/loop-child-arm.ts`, `stringify/insert.ts`) wraps the value in
+ * before handing it to a 'markup' writer — NOT the preamble-region case
+ * (`stringify/loop.ts`), whose value is already-built HTML from a nested
+ * compiled render and must stay unescaped.
+ */
+export function escapeTextOrNode(value: unknown): string | Node {
+  if (typeof Node !== 'undefined' && value instanceof Node) return value
+  return escapeText(value)
+}
+
 const SVG_NS = 'http://www.w3.org/2000/svg'
 
 /**
@@ -559,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')
@@ -587,14 +663,21 @@ 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)
 
   // Mark as initialized
   hydratedScopes.add(element)
 
-  // Store props for element reuse
-  propsMap.set(element, props)
-
   return element
 }

package/src/runtime/dynamic-text.ts

@@ -1,7 +1,30 @@
 /**
  * Dynamic text/JSX slot updater (#1663).
  *
- * The compiler wraps reactive child expressions (`<div>{expr}</div>`) in a
+ * Slot unification A3 (`spec/slot-unification.md` §5-A3) replaced every
+ * OTHER `__bfText` call site with a claimed 'markup' slot writer
+ * (`claim-slots.ts`'s `writeMarkup` provides the identical Node/text
+ * contract). ONE emission site still calls `__bfText` directly and is
+ * deliberately deferred: `emitDynamicTextUpdates`'s `conditionalElems`
+ * path (`ir-to-client-js/emit-reactive.ts`) — a dynamic text/JSX
+ * expression nested inside a top-level (non-loop) conditional, tracked by
+ * an effect OUTSIDE the conditional's own `insert()` `bindEvents`. That
+ * effect re-resolves its anchor via `$t(__scope, slotId)` on EVERY run
+ * because `insert()` may swap the branch independently of this effect's own
+ * reruns — a cached `lazySlots` claim would go stale across such a swap, and
+ * a 'markup' slot's dedup `last` state can't safely survive being re-claimed
+ * fresh every run either: a fresh claim's `last` always starts `undefined`,
+ * so re-claiming per-run would throw away the dedup skip on every single
+ * run (every write would re-clear-and-reparse even when the value hasn't
+ * changed) — unlike the 'text'-kind conditional cases elsewhere in the
+ * compiler, which have no such state to go stale and so DO re-claim fresh
+ * each run safely. Moving this one case onto the claim-plan model needs the
+ * slot's claim door tied to the branch's OWN activation lifecycle instead of
+ * this separate effect's — real architectural work, not a mechanical swap —
+ * so it stays on `$t`/`__bfText` for now.
+ *
+ * The mechanism itself, for the reader who lands here from that one site:
+ * the compiler wraps reactive child expressions (`<div>{expr}</div>`) in a
  * `createEffect` that writes the value into the text node sitting between
  * the slot's `<!--bf:sX-->` / `<!--/-->` comment markers. That was a pure
  * `nodeValue = String(value)` assignment, which is correct for primitives

package/src/runtime/index.ts

@@ -77,13 +77,21 @@ export {
   type PortalChildren,
 } from './portal.ts'
 
-// List reconciliation
-export { reconcileList, type RenderItemFn } from './list.ts'
-export { reconcileElements, getLoopChildren, getLoopNodes } from './reconcile-elements.ts'
+// Loop boundary marker lookup (used by mapArray/mapArrayAnchored consumers
+// and compiler-generated clearing code — see ./loop-markers.ts docstring)
+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'
-export { patchSlotRange } from './patch-slot-range.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, 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'
@@ -92,11 +100,10 @@ export { registerTemplate, getTemplate, hasTemplate, type TemplateFn } from './t
 export {
   createComponent,
   renderChild,
-  getPropsUpdateFn,
-  getComponentProps,
   parseHTML,
   escapeAttr,
   escapeText,
+  escapeTextOrNode,
 } from './component.ts'
 
 // Spread props helpers
@@ -111,8 +118,14 @@ export { hydrate, rehydrateAll, rehydrateScope, disposeScope, flushHydration, ge
 export { registerComponent, getComponentInit, initChild, upsertChild } from './registry.ts'
 export { insert, type BranchConfig, type BranchTemplateResult } from './insert.ts'
 export { __bfSlot } from './branch-slot.ts'
+// `__bfText` (dynamic-text.ts) and `$t` (query.ts) are kept: one narrow
+// emission site — a `@client`-nested-inside-a-top-level-conditional dynamic
+// text/JSX expression (`emitDynamicTextUpdates`'s `conditionalElems` path in
+// `ir-to-client-js/emit-reactive.ts`) still uses them, deferred from slot
+// unification A3 (see that function's docstring for why the claim-plan
+// model doesn't fit that one case cleanly). `updateClientMarker` had no
+// such holdout and is fully deleted.
 export { __bfText } from './dynamic-text.ts'
-export { updateClientMarker } from './client-marker.ts'
 
 // Hydration state
 export { hydratedScopes } from './hydration-state.ts'

package/src/runtime/insert.ts

@@ -338,7 +338,7 @@ export function insert(
 function autoFocusConditionalElement(region: CondRegion, id: string): void {
   // Use requestAnimationFrame to defer focus until after DOM updates.
   // This is necessary because createComponent() may call insert() before
-  // the element is added to the document by reconcileList().
+  // the element is added to the document by mapArray()/mapArrayAnchored().
   requestAnimationFrame(() => {
     const condEl = region.anchor
       ? findCondElInRange(region.anchor, id)

package/src/runtime/loop-markers.ts

@@ -0,0 +1,100 @@
+/**
+ * BarefootJS - Loop Boundary Marker Lookup
+ *
+ * `<!--bf-loop:<id>-->` / `<!--bf-/loop:<id>-->` comment markers delimit a
+ * loop's rendered range inside its container so `mapArray`/`mapArrayAnchored`
+ * (`./map-array.ts`) can reconcile only that range without disturbing
+ * non-loop siblings. These lookups used to also back the now-removed
+ * `reconcileElements`/`reconcileList` element-reconciler (slot unification
+ * A4); they remain as the compiler-facing marker API.
+ */
+
+import { BF_LOOP_START, BF_LOOP_END, loopStartMarker, loopEndMarker } from '@barefootjs/shared'
+
+/**
+ * Find loop boundary comment markers in a container.
+ *
+ * `markerId` scopes the lookup to `<!--bf-loop:<id>-->` / `<!--bf-/loop:<id>-->`
+ * so sibling loops under the same parent disambiguate (#1087). Without an id,
+ * accepts the legacy unscoped form too — used by tests that build containers
+ * without compiler-emitted markers.
+ */
+function findLoopMarkers(
+  container: HTMLElement,
+  markerId?: string,
+): { startMarker: Comment | null; endMarker: Comment | null } {
+  let startMarker: Comment | null = null
+  let endMarker: Comment | null = null
+  if (markerId) {
+    const startVal = loopStartMarker(markerId)
+    const endVal = loopEndMarker(markerId)
+    for (const node of Array.from(container.childNodes)) {
+      if (node.nodeType !== Node.COMMENT_NODE) continue
+      const value = (node as Comment).nodeValue
+      if (value === startVal) startMarker = node as Comment
+      else if (value === endVal) endMarker = node as Comment
+    }
+  } else {
+    const startPrefix = `${BF_LOOP_START}:`
+    const endPrefix = `${BF_LOOP_END}:`
+    for (const node of Array.from(container.childNodes)) {
+      if (node.nodeType !== Node.COMMENT_NODE) continue
+      const value = (node as Comment).nodeValue ?? ''
+      if (!startMarker && (value === BF_LOOP_START || value.startsWith(startPrefix))) {
+        startMarker = node as Comment
+      } else if (!endMarker && (value === BF_LOOP_END || value.startsWith(endPrefix))) {
+        endMarker = node as Comment
+      }
+    }
+  }
+  if (startMarker && endMarker) return { startMarker, endMarker }
+  return { startMarker: null, endMarker: null }
+}
+
+/** Get all Element nodes between start and end comment markers. */
+function getElementsBetweenMarkers(start: Comment, end: Comment): Element[] {
+  const elements: Element[] = []
+  let node: Node | null = start.nextSibling
+  while (node && node !== end) {
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      elements.push(node as Element)
+    }
+    node = node.nextSibling
+  }
+  return elements
+}
+
+/**
+ * Get loop children from a container, respecting bf-loop boundary markers.
+ * When markers are present, returns only elements between them.
+ * When absent, returns all children (backward compatible).
+ * Exported for use by compiler-generated hydration code.
+ */
+export function getLoopChildren(container: HTMLElement, markerId?: string): HTMLElement[] {
+  const { startMarker, endMarker } = findLoopMarkers(container, markerId)
+  if (startMarker && endMarker) {
+    return getElementsBetweenMarkers(startMarker, endMarker) as HTMLElement[]
+  }
+  return Array.from(container.children) as HTMLElement[]
+}
+
+/**
+ * Like {@link getLoopChildren}, but returns every node between the loop
+ * boundary markers — Comments (per-item `<!--bf-loop-i-->` markers) and
+ * text included. The branch-clearing path needs to remove the per-item
+ * marker comments alongside elements; otherwise stale markers would
+ * accumulate when a branch swap forces mapArray to start over (#1212).
+ */
+export function getLoopNodes(container: HTMLElement, markerId?: string): Node[] {
+  const { startMarker, endMarker } = findLoopMarkers(container, markerId)
+  const nodes: Node[] = []
+  if (startMarker && endMarker) {
+    let node: Node | null = startMarker.nextSibling
+    while (node && node !== endMarker) {
+      nodes.push(node)
+      node = node.nextSibling
+    }
+    return nodes
+  }
+  return Array.from(container.childNodes)
+}