@barefootjs/client 0.26.4 → 0.27.0

package/src/runtime/index.ts

@@ -77,13 +77,17 @@ 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'
 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, type SlotSpec, type ClaimPlan, type ClaimedSlots, type SlotWriter } from './claim-slots.ts'
 
 // Template registry
 export { registerTemplate, getTemplate, hasTemplate, type TemplateFn } from './template.ts'
@@ -92,11 +96,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 +114,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)
+}

package/dist/runtime/client-marker.d.ts

@@ -1,21 +0,0 @@
-/**
- * BarefootJS - Client Marker
- *
- * Update text content for @client directive expressions
- * that are evaluated only on the client side.
- */
-/**
- * Update text content for a client marker.
- *
- * Expects comment marker format: <!--bf-client:sX-->
- * Both GoTemplateAdapter and HonoAdapter output this format for @client directives.
- *
- * A zero-width space (\u200B) is used as a prefix to mark text nodes managed by @client.
- * This allows distinguishing managed text nodes from other content.
- *
- * @param scope - The component scope element to search within
- * @param id - The slot ID (e.g., 's5')
- * @param value - The value to display (will be converted to string)
- */
-export declare function updateClientMarker(scope: Element | null, id: string, value: unknown): void;
-//# sourceMappingURL=client-marker.d.ts.map

package/dist/runtime/client-marker.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"client-marker.d.ts","sourceRoot":"","sources":["../../src/runtime/client-marker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAyB1F"}

package/dist/runtime/list.d.ts

@@ -1,21 +0,0 @@
-/**
- * BarefootJS - List Reconciliation
- *
- * Key-based DOM reconciliation for efficient list updates.
- * Delegates to reconcileElements for element-based rendering.
- */
-/**
- * Render function type for list items.
- * Returns an HTMLElement for each item.
- */
-export type RenderItemFn<T> = (item: T, index: number) => HTMLElement;
-/**
- * Reconcile a list container with new items using key-based matching.
- *
- * @param container - The parent element containing list items
- * @param items - Array of items to render
- * @param getKey - Function to extract a unique key from each item (or null to use index)
- * @param renderItem - Function to render an item as HTMLElement
- */
-export declare function reconcileList<T>(container: HTMLElement | null, items: T[], getKey: ((item: T, index: number) => string) | null, renderItem: RenderItemFn<T>): void;
-//# sourceMappingURL=list.d.ts.map

package/dist/runtime/list.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/runtime/list.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,WAAW,CAAA;AAErE;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,GAC1B,IAAI,CAkBN"}

package/dist/runtime/patch-slot-range.d.ts

@@ -1,47 +0,0 @@
-/**
- * In-place patch for a `.map()` preamble-patched loop region — the
- * `<!--bf:sN-->...<!--/-->` marker pair around a loop-body expression child
- * whose free identifiers read a preamble-declared local (`{cells}` in
- * `arr.map(t => { const cells = []; ...; return <tr>{cells}<td>{t.name}</td></tr> })`,
- * #2389). `mapArray` reuses the same row element on a same-key item update
- * via per-item `setItem`, re-running only the row's wired text/attr-slot
- * effects — a preamble-derived region has neither, so without this it
- * freezes at its mount-time content forever. The compiled per-item
- * `createEffect` (see `emitPreambleRegionEffects` in `@barefootjs/jsx`)
- * calls this whenever the re-computed region HTML differs from the
- * last-patched value.
- *
- * Sibling of `patchLeaf` (same "wholesale replace, preserve identity"
- * contract), but scoped to a marker-delimited RANGE inside an element
- * rather than the element itself — a region has no element of its own to
- * hold an identity, only the comment pair.
- *
- * The start comment is located here, per call, rather than by a separate
- * mount-time lookup: the region effect's first run only records the
- * mount-time value, so a row that never changes pays ZERO lookup cost —
- * the scan runs only on an actual content change, over a single (small)
- * row element.
- *
- * Ownership: slot ids are per-component, so a marker under a nested `bf-s`
- * scope (a child component's own `bf:sN`) is never a candidate. Today
- * that's defense in depth — regions are only emitted for the plain
- * loop-plan shape, and `decideLoopRendering` routes any row containing
- * nested components or inner loops to the composite/component shapes,
- * which don't consume `preambleRegions` — but the guard keeps that safety
- * local instead of coupled to routing.
- *
- * A missing start or end marker means the DOM diverged from the compiled
- * template — warn and do nothing (sound-or-loud: never guess a boundary).
- *
- * Range contract: the matching end is the nearest following sibling
- * `<!--/-->` comment at the SAME nesting depth — any `bf:`-prefixed
- * comment along the way opens a FURTHER nested region (a leaf rendered
- * inside this one could carry its own ordinary text-slot markers) and
- * increments a depth counter so that region's own `/` doesn't prematurely
- * close the outer range. Every node strictly between the two markers is
- * removed, then `html` is parsed via a `<template>` and inserted before
- * the end marker. The two markers themselves are never removed — they
- * stay as the region's permanent boundary for the next patch.
- */
-export declare function patchSlotRange(scope: Element, id: string, html: string): void;
-//# sourceMappingURL=patch-slot-range.d.ts.map

package/dist/runtime/patch-slot-range.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"patch-slot-range.d.ts","sourceRoot":"","sources":["../../src/runtime/patch-slot-range.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAyD7E"}

package/dist/runtime/reconcile-elements.d.ts

@@ -1,44 +0,0 @@
-/**
- * BarefootJS - Element-based List Reconciliation
- *
- * Key-based DOM reconciliation for component-based list rendering.
- * Used when renderItem returns HTMLElement (via createComponent).
- */
-/**
- * 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 declare function getLoopChildren(container: HTMLElement, markerId?: string): 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 declare function getLoopNodes(container: HTMLElement, markerId?: string): Node[];
-/**
- * Ensure loop boundary markers exist in a container for SSR-rendered content.
- * SSR HTML doesn't include markers, so we insert them during hydration.
- * Uses itemCount to identify the last N children as loop items (rest are siblings).
- */
-export declare function ensureLoopMarkers(container: HTMLElement, itemCount: number, markerId?: string): void;
-/**
- * Reconcile a list container using HTMLElement mode (for createComponent).
- * Reuses existing elements by key, creates new elements as needed.
- *
- * @param container - The parent element containing list items
- * @param items - Array of items to render
- * @param getKey - Function to extract a unique key from each item (or null to use index)
- * @param renderItem - Function that returns an HTMLElement for each item
- * @param firstElement - Pre-created element for first item (avoids duplicate creation when caller already rendered item 0)
- */
-export declare function reconcileElements<T>(container: HTMLElement | null, items: T[], getKey: ((item: T, index: number) => string) | null, renderItem: (item: T, index: number) => HTMLElement, firstElement?: HTMLElement, markerId?: string): void;
-/**
- * Sync reactive DOM state from a source element to a target element.
- * Copies class names, replaces conditional elements, and syncs text content.
- */
-export declare function syncElementState(target: HTMLElement, source: HTMLElement): void;
-//# sourceMappingURL=reconcile-elements.d.ts.map

package/dist/runtime/reconcile-elements.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"reconcile-elements.d.ts","sourceRoot":"","sources":["../../src/runtime/reconcile-elements.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoEH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,EAAE,CAMxF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,EAAE,CAY9E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAgBpG;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,KAAK,EAAE,CAAC,EAAE,EACV,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,UAAU,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,WAAW,EACnD,YAAY,CAAC,EAAE,WAAW,EAC1B,QAAQ,CAAC,EAAE,MAAM,GAChB,IAAI,CA2JN;AAkCD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAiD/E"}

package/src/runtime/client-marker.ts

@@ -1,46 +0,0 @@
-/**
- * BarefootJS - Client Marker
- *
- * Update text content for @client directive expressions
- * that are evaluated only on the client side.
- */
-
-/**
- * Update text content for a client marker.
- *
- * Expects comment marker format: <!--bf-client:sX-->
- * Both GoTemplateAdapter and HonoAdapter output this format for @client directives.
- *
- * A zero-width space (\u200B) is used as a prefix to mark text nodes managed by @client.
- * This allows distinguishing managed text nodes from other content.
- *
- * @param scope - The component scope element to search within
- * @param id - The slot ID (e.g., 's5')
- * @param value - The value to display (will be converted to string)
- */
-export function updateClientMarker(scope: Element | null, id: string, value: unknown): void {
-  if (!scope) return
-
-  const marker = `bf-client:${id}`
-  const walker = document.createTreeWalker(scope, NodeFilter.SHOW_COMMENT)
-
-  while (walker.nextNode()) {
-    if (walker.currentNode.nodeValue === marker) {
-      const comment = walker.currentNode
-      let textNode = comment.nextSibling
-
-      // Check if next sibling is our managed text node (prefixed with zero-width space)
-      if (textNode?.nodeType !== Node.TEXT_NODE ||
-          !textNode.nodeValue?.startsWith('\u200B')) {
-        // Create new text node with zero-width space marker
-        textNode = document.createTextNode('\u200B' + String(value ?? ''))
-        // Insert after the comment node
-        comment.parentNode?.insertBefore(textNode, comment.nextSibling)
-      } else {
-        // Update existing managed text node
-        textNode.nodeValue = '\u200B' + String(value ?? '')
-      }
-      return
-    }
-  }
-}

package/src/runtime/list.ts

@@ -1,47 +0,0 @@
-/**
- * BarefootJS - List Reconciliation
- *
- * Key-based DOM reconciliation for efficient list updates.
- * Delegates to reconcileElements for element-based rendering.
- */
-
-import { reconcileElements } from './reconcile-elements.ts'
-
-/**
- * Render function type for list items.
- * Returns an HTMLElement for each item.
- */
-export type RenderItemFn<T> = (item: T, index: number) => HTMLElement
-
-/**
- * Reconcile a list container with new items using key-based matching.
- *
- * @param container - The parent element containing list items
- * @param items - Array of items to render
- * @param getKey - Function to extract a unique key from each item (or null to use index)
- * @param renderItem - Function to render an item as HTMLElement
- */
-export function reconcileList<T>(
-  container: HTMLElement | null,
-  items: T[],
-  getKey: ((item: T, index: number) => string) | null,
-  renderItem: RenderItemFn<T>
-): void {
-  if (!container || !items) return
-
-  if (items.length === 0) {
-    container.innerHTML = ''
-    return
-  }
-
-  // Pre-create first element to avoid duplicate creation inside reconcileElements
-  const firstElement = renderItem(items[0], 0)
-
-  reconcileElements(
-    container,
-    items,
-    getKey,
-    renderItem,
-    firstElement
-  )
-}

package/src/runtime/patch-slot-range.ts

@@ -1,105 +0,0 @@
-import { BF_SCOPE } from '@barefootjs/shared'
-
-/**
- * In-place patch for a `.map()` preamble-patched loop region — the
- * `<!--bf:sN-->...<!--/-->` marker pair around a loop-body expression child
- * whose free identifiers read a preamble-declared local (`{cells}` in
- * `arr.map(t => { const cells = []; ...; return <tr>{cells}<td>{t.name}</td></tr> })`,
- * #2389). `mapArray` reuses the same row element on a same-key item update
- * via per-item `setItem`, re-running only the row's wired text/attr-slot
- * effects — a preamble-derived region has neither, so without this it
- * freezes at its mount-time content forever. The compiled per-item
- * `createEffect` (see `emitPreambleRegionEffects` in `@barefootjs/jsx`)
- * calls this whenever the re-computed region HTML differs from the
- * last-patched value.
- *
- * Sibling of `patchLeaf` (same "wholesale replace, preserve identity"
- * contract), but scoped to a marker-delimited RANGE inside an element
- * rather than the element itself — a region has no element of its own to
- * hold an identity, only the comment pair.
- *
- * The start comment is located here, per call, rather than by a separate
- * mount-time lookup: the region effect's first run only records the
- * mount-time value, so a row that never changes pays ZERO lookup cost —
- * the scan runs only on an actual content change, over a single (small)
- * row element.
- *
- * Ownership: slot ids are per-component, so a marker under a nested `bf-s`
- * scope (a child component's own `bf:sN`) is never a candidate. Today
- * that's defense in depth — regions are only emitted for the plain
- * loop-plan shape, and `decideLoopRendering` routes any row containing
- * nested components or inner loops to the composite/component shapes,
- * which don't consume `preambleRegions` — but the guard keeps that safety
- * local instead of coupled to routing.
- *
- * A missing start or end marker means the DOM diverged from the compiled
- * template — warn and do nothing (sound-or-loud: never guess a boundary).
- *
- * Range contract: the matching end is the nearest following sibling
- * `<!--/-->` comment at the SAME nesting depth — any `bf:`-prefixed
- * comment along the way opens a FURTHER nested region (a leaf rendered
- * inside this one could carry its own ordinary text-slot markers) and
- * increments a depth counter so that region's own `/` doesn't prematurely
- * close the outer range. Every node strictly between the two markers is
- * removed, then `html` is parsed via a `<template>` and inserted before
- * the end marker. The two markers themselves are never removed — they
- * stay as the region's permanent boundary for the next patch.
- */
-export function patchSlotRange(scope: Element, id: string, html: string): void {
-  const marker = `bf:${id}`
-  let start: Comment | null = null
-  const walker = document.createTreeWalker(scope, NodeFilter.SHOW_COMMENT)
-  while (walker.nextNode()) {
-    const comment = walker.currentNode as Comment
-    if (comment.nodeValue !== marker) continue
-    let owned = true
-    for (let el = comment.parentElement; el && el !== scope; el = el.parentElement) {
-      if (el.hasAttribute(BF_SCOPE)) {
-        owned = false
-        break
-      }
-    }
-    if (owned) {
-      start = comment
-      break
-    }
-  }
-  const parent = start?.parentNode
-  if (!start || !parent) {
-    console.warn(`[barefootjs] preamble region marker bf:${id} not found in row; skipping patch`)
-    return
-  }
-
-  let depth = 0
-  let end: Comment | null = null
-  const toRemove: Node[] = []
-  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) {
-          end = node as Comment
-          break
-        }
-        depth--
-      }
-    }
-    toRemove.push(node)
-    node = node.nextSibling
-  }
-  if (!end) {
-    // Malformed/unexpected DOM shape — never risk deleting past the
-    // region's intended boundary.
-    console.warn(`[barefootjs] preamble region bf:${id} has no end marker; skipping patch`)
-    return
-  }
-
-  for (const n of toRemove) parent.removeChild(n)
-
-  const tpl = document.createElement('template')
-  tpl.innerHTML = html
-  parent.insertBefore(tpl.content, end)
-}