@barefootjs/client 0.26.3 → 0.26.4

package/dist/runtime/index.d.ts

@@ -12,6 +12,8 @@ export { reconcileList, type RenderItemFn } from './list.ts';
 export { reconcileElements, getLoopChildren, getLoopNodes } from './reconcile-elements.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';
 export { registerTemplate, getTemplate, hasTemplate, type TemplateFn } from './template.ts';
 export { createComponent, renderChild, getPropsUpdateFn, getComponentProps, parseHTML, escapeAttr, escapeText, } from './component.ts';
 export { applyRestAttrs } from './apply-rest-attrs.ts';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"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"}

package/dist/runtime/index.js

@@ -2387,6 +2387,87 @@ function mapArrayAnchored(accessor, container, getKey, renderItem, markerId, bfI
     }
   }, bfId);
 }
+// src/runtime/patch-leaf.ts
+function patchLeaf(el, html) {
+  const tpl = document.createElement("template");
+  tpl.innerHTML = html;
+  const next = tpl.content.firstElementChild;
+  if (!next)
+    return;
+  if (next.tagName !== el.tagName) {
+    console.warn("[barefootjs] flatMap leaf root tag changed under a stable key " + `(<${el.tagName.toLowerCase()}> -> <${next.tagName.toLowerCase()}>); ` + "give each branch its own key so the node is replaced instead of patched.");
+  }
+  for (const name of el.getAttributeNames()) {
+    if (name === "data-key")
+      continue;
+    if (!next.hasAttribute(name))
+      el.removeAttribute(name);
+  }
+  for (const name of next.getAttributeNames()) {
+    if (name === "data-key")
+      continue;
+    const value = next.getAttribute(name);
+    if (value !== null && el.getAttribute(name) !== value)
+      el.setAttribute(name, value);
+  }
+  el.replaceChildren(...Array.from(next.childNodes));
+}
+// src/runtime/patch-slot-range.ts
+function patchSlotRange(scope, id, html) {
+  const marker = `bf:${id}`;
+  let start = null;
+  const walker = document.createTreeWalker(scope, NodeFilter.SHOW_COMMENT);
+  while (walker.nextNode()) {
+    const comment = walker.currentNode;
+    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 = null;
+  const toRemove = [];
+  let node = start.nextSibling;
+  while (node) {
+    if (node.nodeType === Node.COMMENT_NODE) {
+      const value = node.nodeValue ?? "";
+      if (value.startsWith("bf:")) {
+        depth++;
+      } else if (value === "/") {
+        if (depth === 0) {
+          end = node;
+          break;
+        }
+        depth--;
+      }
+    }
+    toRemove.push(node);
+    node = node.nextSibling;
+  }
+  if (!end) {
+    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);
+}
 // src/runtime/apply-rest-attrs.ts
 import { createEffect as createEffect2 } from "@barefootjs/client/reactive";
 
@@ -2957,6 +3038,8 @@ export {
   qsaChildScope,
   qsa,
   provideContext,
+  patchSlotRange,
+  patchLeaf,
   parseHTML,
   onMount,
   onCleanup,

package/dist/runtime/patch-leaf.d.ts

@@ -0,0 +1,17 @@
+/**
+ * In-place patch for flatMap leaf elements (the descriptor-based
+ * `mapArray` path — see `stringifyPlainLoop`'s flatMap branch in
+ * `@barefootjs/jsx`).
+ *
+ * flatMap leaves carry no per-slot reactive wiring (the compiler refuses
+ * leaves that would need it), so a leaf whose rendered HTML changed under a
+ * stable key is updated wholesale: attributes are synced and children are
+ * replaced from the freshly rendered string. The element's identity is
+ * preserved — `mapArray` holds the node in its keyed scope map, so the
+ * patch must never swap the node itself.
+ *
+ * `data-key` is excluded from attribute sync: reconciliation identity is
+ * owned by `mapArray` (stamped via `setAttribute`), never by leaf content.
+ */
+export declare function patchLeaf(el: Element, html: string): void;
+//# sourceMappingURL=patch-leaf.d.ts.map

package/dist/runtime/patch-leaf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patch-leaf.d.ts","sourceRoot":"","sources":["../../src/runtime/patch-leaf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAyBzD"}

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

@@ -0,0 +1,47 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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/standalone.js

@@ -2792,6 +2792,87 @@ function mapArrayAnchored(accessor, container, getKey, renderItem, markerId, bfI
     }
   }, bfId);
 }
+// src/runtime/patch-leaf.ts
+function patchLeaf(el, html) {
+  const tpl = document.createElement("template");
+  tpl.innerHTML = html;
+  const next = tpl.content.firstElementChild;
+  if (!next)
+    return;
+  if (next.tagName !== el.tagName) {
+    console.warn("[barefootjs] flatMap leaf root tag changed under a stable key " + `(<${el.tagName.toLowerCase()}> -> <${next.tagName.toLowerCase()}>); ` + "give each branch its own key so the node is replaced instead of patched.");
+  }
+  for (const name of el.getAttributeNames()) {
+    if (name === "data-key")
+      continue;
+    if (!next.hasAttribute(name))
+      el.removeAttribute(name);
+  }
+  for (const name of next.getAttributeNames()) {
+    if (name === "data-key")
+      continue;
+    const value = next.getAttribute(name);
+    if (value !== null && el.getAttribute(name) !== value)
+      el.setAttribute(name, value);
+  }
+  el.replaceChildren(...Array.from(next.childNodes));
+}
+// src/runtime/patch-slot-range.ts
+function patchSlotRange(scope, id, html) {
+  const marker = `bf:${id}`;
+  let start = null;
+  const walker = document.createTreeWalker(scope, NodeFilter.SHOW_COMMENT);
+  while (walker.nextNode()) {
+    const comment = walker.currentNode;
+    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 = null;
+  const toRemove = [];
+  let node = start.nextSibling;
+  while (node) {
+    if (node.nodeType === Node.COMMENT_NODE) {
+      const value = node.nodeValue ?? "";
+      if (value.startsWith("bf:")) {
+        depth++;
+      } else if (value === "/") {
+        if (depth === 0) {
+          end = node;
+          break;
+        }
+        depth--;
+      }
+    }
+    toRemove.push(node);
+    node = node.nextSibling;
+  }
+  if (!end) {
+    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);
+}
 // src/runtime/style.ts
 function styleToCss(value) {
   if (value == null)
@@ -3357,6 +3438,8 @@ export {
   qsaChildScope,
   qsa,
   provideContext,
+  patchSlotRange,
+  patchLeaf,
   parseHTML,
   onMount,
   onCleanup,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/client",
-  "version": "0.26.3",
+  "version": "0.26.4",
   "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.3"
+    "@barefootjs/shared": "0.26.4"
   },
   "peerDependencies": {
     "@barefootjs/jsx": ">=0.2.0"

package/src/runtime/index.ts

@@ -82,6 +82,8 @@ export { reconcileList, type RenderItemFn } from './list.ts'
 export { reconcileElements, getLoopChildren, getLoopNodes } from './reconcile-elements.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'
 
 // Template registry
 export { registerTemplate, getTemplate, hasTemplate, type TemplateFn } from './template.ts'

package/src/runtime/patch-leaf.ts

@@ -0,0 +1,41 @@
+/**
+ * In-place patch for flatMap leaf elements (the descriptor-based
+ * `mapArray` path — see `stringifyPlainLoop`'s flatMap branch in
+ * `@barefootjs/jsx`).
+ *
+ * flatMap leaves carry no per-slot reactive wiring (the compiler refuses
+ * leaves that would need it), so a leaf whose rendered HTML changed under a
+ * stable key is updated wholesale: attributes are synced and children are
+ * replaced from the freshly rendered string. The element's identity is
+ * preserved — `mapArray` holds the node in its keyed scope map, so the
+ * patch must never swap the node itself.
+ *
+ * `data-key` is excluded from attribute sync: reconciliation identity is
+ * owned by `mapArray` (stamped via `setAttribute`), never by leaf content.
+ */
+export function patchLeaf(el: Element, html: string): void {
+  const tpl = document.createElement('template')
+  tpl.innerHTML = html
+  const next = tpl.content.firstElementChild
+  if (!next) return
+  if (next.tagName !== el.tagName) {
+    // A root-tag change under a stable key cannot swap the node without
+    // desyncing mapArray's keyed scope. Attributes/children still patch
+    // onto the existing tag; the honest fix is a distinct key per branch.
+    console.warn(
+      '[barefootjs] flatMap leaf root tag changed under a stable key ' +
+        `(<${el.tagName.toLowerCase()}> -> <${next.tagName.toLowerCase()}>); ` +
+        'give each branch its own key so the node is replaced instead of patched.',
+    )
+  }
+  for (const name of el.getAttributeNames()) {
+    if (name === 'data-key') continue
+    if (!next.hasAttribute(name)) el.removeAttribute(name)
+  }
+  for (const name of next.getAttributeNames()) {
+    if (name === 'data-key') continue
+    const value = next.getAttribute(name)
+    if (value !== null && el.getAttribute(name) !== value) el.setAttribute(name, value)
+  }
+  el.replaceChildren(...Array.from(next.childNodes))
+}

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

@@ -0,0 +1,105 @@
+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)
+}