@barefootjs/client 0.33.2 → 0.33.4

package/dist/csr-adapter.js

@@ -168754,7 +168754,7 @@ Additional information: BADCLIENT: Bad error code, ${badCode} not found in range
 });
 
 // ../jsx/src/compiler.ts
-var import_typescript24 = __toESM(require_typescript(), 1);
+var import_typescript25 = __toESM(require_typescript(), 1);
 
 // ../jsx/src/analyzer.ts
 var import_typescript9 = __toESM(require_typescript(), 1);
@@ -169998,11 +169998,14 @@ var KEYWORDS_AND_GLOBALS = new Set([
 // ../jsx/src/ir-to-client-js/walk-prop-accesses.ts
 var import_typescript14 = __toESM(require_typescript(), 1);
 
+// ../jsx/src/ir-to-client-js/imports.ts
+var import_typescript16 = __toESM(require_typescript(), 1);
+
 // ../jsx/src/value-references.ts
 var import_typescript15 = __toESM(require_typescript(), 1);
 
 // ../jsx/src/relocate.ts
-var import_typescript16 = __toESM(require_typescript(), 1);
+var import_typescript17 = __toESM(require_typescript(), 1);
 
 // ../jsx/src/lowering-registry.ts
 var plugins = [];
@@ -170181,10 +170184,10 @@ function formatDateLocalNames(metadata) {
 }
 
 // ../jsx/src/ir-to-client-js/prune-unused-prop-extractions.ts
-var import_typescript17 = __toESM(require_typescript(), 1);
+var import_typescript18 = __toESM(require_typescript(), 1);
 
 // ../jsx/src/ir-to-client-js/control-flow/plan/lazy-preamble.ts
-var import_typescript18 = __toESM(require_typescript(), 1);
+var import_typescript19 = __toESM(require_typescript(), 1);
 var NO_PREAMBLE = {
   lazySafe: true,
   facts: { declaredNames: new Set, freeNames: new Set }
@@ -170234,7 +170237,7 @@ var INERT_BINDING_GLOBALS = new Set([
 ]);
 
 // ../jsx/src/ir-to-client-js/emit-reactive.ts
-var import_typescript19 = __toESM(require_typescript(), 1);
+var import_typescript20 = __toESM(require_typescript(), 1);
 
 // ../jsx/src/ir-to-client-js/control-flow/stringify/event-delegation.ts
 var NON_BUBBLING_EVENTS = new Set([
@@ -170249,7 +170252,7 @@ var NON_BUBBLING_EVENTS = new Set([
 ]);
 
 // ../jsx/src/ir-to-client-js/rewrite-props-object.ts
-var import_typescript20 = __toESM(require_typescript(), 1);
+var import_typescript21 = __toESM(require_typescript(), 1);
 
 // ../jsx/src/ir-to-client-js/source-map.ts
 var BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
@@ -170340,20 +170343,20 @@ class SourceMapGenerator {
 }
 
 // ../jsx/src/preprocess-inline-jsx-callbacks.ts
-var import_typescript21 = __toESM(require_typescript(), 1);
+var import_typescript22 = __toESM(require_typescript(), 1);
 
 // ../jsx/src/ssr-defaults.ts
-var import_typescript22 = __toESM(require_typescript(), 1);
+var import_typescript23 = __toESM(require_typescript(), 1);
 var UNRESOLVED = Symbol("unresolved");
 var NO_RETURN = Symbol("no-return");
 
 // ../jsx/src/augment-inherited-props.ts
-var import_typescript23 = __toESM(require_typescript(), 1);
+var import_typescript24 = __toESM(require_typescript(), 1);
 
 // ../jsx/src/rich-type-refusal.ts
 var EMPTY_BINDINGS2 = new Map;
 // ../jsx/src/shared-program.ts
-var import_typescript25 = __toESM(require_typescript(), 1);
+var import_typescript26 = __toESM(require_typescript(), 1);
 // ../jsx/src/adapters/interface.ts
 class BaseAdapter {
   renderChildren(children) {
@@ -170635,7 +170638,7 @@ class JsxAdapter extends BaseAdapter {
 }
 
 // ../jsx/src/adapters/template-imports.ts
-var import_typescript26 = __toESM(require_typescript(), 1);
+var import_typescript27 = __toESM(require_typescript(), 1);
 var CLIENT_PACKAGE_SOURCES = new Set([
   "@barefootjs/client",
   "@barefootjs/client/runtime"
@@ -171028,11 +171031,11 @@ function registerBuiltinLoweringPlugins() {
     registerLoweringPlugin(plugin);
 }
 // ../jsx/src/combine-client-js.ts
-var import_typescript27 = __toESM(require_typescript(), 1);
-// ../jsx/src/debug.ts
 var import_typescript28 = __toESM(require_typescript(), 1);
-// ../jsx/src/profiler.ts
+// ../jsx/src/debug.ts
 var import_typescript29 = __toESM(require_typescript(), 1);
+// ../jsx/src/profiler.ts
+var import_typescript30 = __toESM(require_typescript(), 1);
 
 // ../jsx/src/index.ts
 registerBuiltinLoweringPlugins();

package/dist/runtime/component.d.ts

@@ -105,8 +105,8 @@ export interface CreateComponentSlotInfo {
  * `upsertChildItem` (qsa-item.ts) assert nothing — the narrowing is the
  * signature's job, not theirs.
  */
-export declare function createComponent(nameOrDef: string | ComponentDef, props: Record<string, unknown>, key: string | number | undefined, slot: CreateComponentSlotInfo | undefined, mountAt: Element): HTMLElement;
-export declare function createComponent(nameOrDef: string | ComponentDef, props?: Record<string, unknown>, key?: string | number, slot?: CreateComponentSlotInfo, mountAt?: Element | null): HTMLElement | DocumentFragment;
+export declare function createComponent(nameOrDef: string | ComponentDef, props: Record<string, unknown>, key: string | number | undefined, slot: CreateComponentSlotInfo | undefined, mountAt: Element, keyAttrName?: string): HTMLElement;
+export declare function createComponent(nameOrDef: string | ComponentDef, props?: Record<string, unknown>, key?: string | number, slot?: CreateComponentSlotInfo, mountAt?: Element | null, keyAttrName?: string): HTMLElement | DocumentFragment;
 /**
  * Render a child component's template to an HTML string.
  * Used by compiler-generated template functions when a stateless component
@@ -221,6 +221,31 @@ export declare function isBfMarkup(value: unknown): value is BfMarkup;
  * is actually branded.
  */
 export declare function escapeTextOrMarkup(value: unknown): string;
+/**
+ * Nullish guard for a bare `${children}` passthrough splice
+ * (`ir-to-client-js/html-template.ts`'s no-`slotId` `'expression'` branches
+ * — the "bare `${...}` interpolations" the docstring above `escapeTextSlotExpr`
+ * describes) — #2775. The value here is ALREADY-STRINGIFIED MARKUP, not an
+ * arbitrary prop: `materializeComponent` (this file, "Template functions
+ * expect children as an HTML string, not an array") joins a component's
+ * `children` into an HTML string before the template lambda ever runs, so by
+ * the time this function sees the value it is either that HTML string or,
+ * when the caller passed none, simply `undefined` (the key is absent from
+ * the props object entirely). This function's ENTIRE job is that one
+ * nullish case: turn the absent/`null` value into `''`, same as SSR's
+ * `{props.children}` and the DSL adapters' `bf.string(children)` render it.
+ *
+ * Deliberately NOT `escapeTextOrMarkup`: that function falls back to
+ * `escapeText` for anything not `bfMarkup()`-branded, and a `children`
+ * string is never branded (it is a plain string built by
+ * `materializeComponent`, not compiler-escaped piece-by-piece the way a
+ * `bfMarkup()` value is) — routing `children` through it would HTML-escape
+ * real markup into visible `&lt;span&gt;`-style text on every call that
+ * actually has children, trading the no-children bug for a strictly worse
+ * with-children one. So: nullish becomes `''`; every other value is
+ * returned completely unescaped, exactly as it arrived.
+ */
+export declare function markupOrEmpty(value: unknown): string;
 /**
  * `escapeText`'s counterpart for a claimed 'markup' slot's REACTIVE write
  * (slot unification A3 follow-up), where the value is a plain-JS expression

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

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

package/dist/runtime/index.d.ts

@@ -15,7 +15,7 @@ export { mapArrayLazy, type LazyRowEntry, type LazyRowPlan } from './map-array-l
 export { patchLeaf } from './patch-leaf.ts';
 export { claimSlots, lazySlots, lazyClaimSlots, textOrNode, type SlotSpec, type ClaimPlan, type ClaimedSlots, type ClaimedSlotsRW, type SlotWriter } from './claim-slots.ts';
 export { registerTemplate, getTemplate, hasTemplate, type TemplateFn } from './template.ts';
-export { createComponent, mountRowRoot, renderChild, parseHTML, escapeAttr, escapeText, escapeTextOrNode, bfMarkup, isBfMarkup, escapeTextOrMarkup, type BfMarkup, } from './component.ts';
+export { createComponent, mountRowRoot, renderChild, parseHTML, escapeAttr, escapeText, escapeTextOrNode, bfMarkup, isBfMarkup, escapeTextOrMarkup, markupOrEmpty, type BfMarkup, } from './component.ts';
 export { applyRestAttrs } from './apply-rest-attrs.ts';
 export { spreadAttrs } from './spread-attrs.ts';
 export { styleToCss } from './style.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

@@ -1368,25 +1368,25 @@ function mountRowRoot(el) {
   }
   return el;
 }
-function createComponent(nameOrDef, props = {}, key, slot, mountAt) {
-  const element = materializeComponent(nameOrDef, props, key, slot, mountAt);
+function createComponent(nameOrDef, props = {}, key, slot, mountAt, keyAttrName2 = BF_KEY) {
+  const element = materializeComponent(nameOrDef, props, key, slot, mountAt, keyAttrName2);
   if (mountAt && mountAt.parentNode && element !== mountAt) {
     mountAt.replaceWith(element);
   }
   return element;
 }
-function materializeComponent(nameOrDef, props = {}, key, slot, mountAt) {
+function materializeComponent(nameOrDef, props = {}, key, slot, mountAt, keyAttrName2 = BF_KEY) {
   if (props == null)
     props = {};
   const rowMount = mountAt ? null : takeRowMountPoint();
   if (typeof nameOrDef !== "string") {
-    return createComponentFromDef(nameOrDef, props, key, mountAt, rowMount);
+    return createComponentFromDef(nameOrDef, props, key, mountAt, rowMount, keyAttrName2);
   }
   const name = nameOrDef;
   const templateFn = getTemplate(name);
   if (!templateFn) {
     console.warn(`[BarefootJS] Template not found for component: ${name}`);
-    return createPlaceholder(name, key);
+    return createPlaceholder(name, key, keyAttrName2);
   }
   const childrenDescriptor = Object.getOwnPropertyDescriptor(props, "children");
   const childrenIsGetter = childrenDescriptor != null && typeof childrenDescriptor.get === "function";
@@ -1419,6 +1419,8 @@ function materializeComponent(nameOrDef, props = {}, key, slot, mountAt) {
     _parentScopeId = scopeId;
   } else if (slot?.parent) {
     _parentScopeId = slot.parent;
+  } else if (!_parentScopeId) {
+    _parentScopeId = `${def?.name ?? name}_${generateId()}`;
   }
   let html;
   try {
@@ -1431,11 +1433,11 @@ function materializeComponent(nameOrDef, props = {}, key, slot, mountAt) {
   const element = isFragmentRoot ? roots.find((node) => node.nodeType === Node.ELEMENT_NODE) : roots[0];
   if (isFragmentRoot && roots.length > 0 && !element) {
     console.warn(`[BarefootJS] Fragment-root component ${name} rendered no element root; ` + "a scope needs at least one element to attach to. Wrap the content in an element.");
-    return createPlaceholder(name, key);
+    return createPlaceholder(name, key, keyAttrName2);
   }
   if (!element) {
     console.warn(`[BarefootJS] Template returned empty HTML for component: ${name}`);
-    return createPlaceholder(name, key);
+    return createPlaceholder(name, key, keyAttrName2);
   }
   if (scopeId && !isFragmentRoot) {
     element.setAttribute(BF_SCOPE, scopeId);
@@ -1446,7 +1448,7 @@ function materializeComponent(nameOrDef, props = {}, key, slot, mountAt) {
     element.setAttribute(BF_AT, slot.mount);
   }
   if (key !== undefined) {
-    element.setAttribute(BF_KEY, String(key));
+    element.setAttribute(keyAttrName2, String(key));
   }
   const fragmentComments = isFragmentRoot && scopeId ? {
     start: document.createComment(`${BF_SCOPE_COMMENT_PREFIX}${scopeId}`),
@@ -1562,11 +1564,11 @@ var ROOT_HAS_BFS_PATTERN = /^<\w+[^>]*\sbf-s="/;
 function generateId() {
   return Math.random().toString(36).slice(2, 8);
 }
-function createPlaceholder(name, key) {
+function createPlaceholder(name, key, keyAttrName2 = BF_KEY) {
   const el = document.createElement("div");
   el.setAttribute(BF_SCOPE, `${name}_placeholder`);
   if (key !== undefined) {
-    el.setAttribute(BF_KEY, String(key));
+    el.setAttribute(keyAttrName2, String(key));
   }
   el.textContent = `[${name}]`;
   el.style.cssText = "color: red; border: 1px dashed red; padding: 4px;";
@@ -1615,6 +1617,9 @@ function escapeTextOrMarkup(value) {
     return value[BF_MARKUP_BRAND];
   return escapeText(value);
 }
+function markupOrEmpty(value) {
+  return value == null ? "" : value;
+}
 function escapeTextOrNode(value) {
   if (isBfMarkup(value))
     return value[BF_MARKUP_BRAND];
@@ -1676,7 +1681,7 @@ function insertGetterChildren(element, children) {
     element.appendChild(document.createTextNode(String(children)));
   }
 }
-function createComponentFromDef(def, props, key, mountAt, rowMount) {
+function createComponentFromDef(def, props, key, mountAt, rowMount, keyAttrName2 = BF_KEY) {
   if (!def.template) {
     throw new Error("[BarefootJS] createComponent with ComponentDef requires a template function");
   }
@@ -1693,7 +1698,7 @@ function createComponentFromDef(def, props, key, mountAt, rowMount) {
   const scopeId = `${name}_${generateId()}`;
   element.setAttribute(BF_SCOPE, scopeId);
   if (key !== undefined) {
-    element.setAttribute(BF_KEY, String(key));
+    element.setAttribute(keyAttrName2, String(key));
   }
   if (mountAt) {
     mountAt.replaceWith(element);
@@ -2075,7 +2080,7 @@ function createItemScope(item, index, renderItem, existingPrimary, existingExtra
   }
   return { startMarker, primaryEl, extras, scopeComments, dispose, setItem };
 }
-function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
+function mapArray(accessor, container, getKey, renderItem, markerId, bfId, keyAttrName2 = BF_KEY) {
   if (!container)
     return;
   const scopes = new Map;
@@ -2100,13 +2105,15 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
     if (!hydrated) {
       hydrated = true;
       const existingRanges = startMarker ? findItemRanges(startMarker, endMarker) : Array.from(container.children).map((el) => ({ startMarker: null, primaryEl: el, extras: [], scopeComments: null }));
-      const needsHydration = existingRanges.length > 0 && (!existingRanges[0]?.primaryEl.hasAttribute("data-key") || scopes.size === 0);
+      const needsHydration = existingRanges.length > 0;
       if (needsHydration) {
         for (let i2 = 0;i2 < existingRanges.length && i2 < items.length; i2++) {
           const range = existingRanges[i2];
           const item = items[i2];
           const key = getKey ? getKey(item, i2) : String(i2);
-          range.primaryEl.setAttribute(BF_KEY, key);
+          if (getKey && !range.primaryEl.getAttribute(keyAttrName2)) {
+            range.primaryEl.setAttribute(keyAttrName2, key);
+          }
           const scope = createItemScope(item, i2, renderItem, range.primaryEl, range.extras, range.startMarker, range.scopeComments);
           scopes.set(key, scope);
           hydratedScopes.add(range.primaryEl);
@@ -2115,8 +2122,8 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
           const item = items[i2];
           const key = getKey ? getKey(item, i2) : String(i2);
           const scope = createItemScope(item, i2, renderItem, undefined, undefined, undefined, undefined, { container, anchor });
-          if (!scope.primaryEl.dataset.key)
-            scope.primaryEl.setAttribute(BF_KEY, key);
+          if (getKey && !scope.primaryEl.getAttribute(keyAttrName2))
+            scope.primaryEl.setAttribute(keyAttrName2, key);
           scopes.set(key, scope);
           insertScope(scope, container, anchor);
         }
@@ -2141,7 +2148,7 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
     if (scopes.size === 0) {
       const loopRanges = startMarker ? findItemRanges(startMarker, endMarker) : Array.from(container.children).map((el) => ({ startMarker: null, primaryEl: el, extras: [], scopeComments: null }));
       for (const range of loopRanges) {
-        const existingKey = range.primaryEl.dataset?.key;
+        const existingKey = range.primaryEl.getAttribute(keyAttrName2);
         if (existingKey && !scopes.has(existingKey)) {
           scopes.set(existingKey, {
             startMarker: range.startMarker,
@@ -2199,8 +2206,8 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
         desiredOrder.push(existing);
       } else {
         const scope = createItemScope(item, i2, renderItem, undefined, undefined, undefined, undefined, { container, anchor });
-        if (!scope.primaryEl.dataset.key)
-          scope.primaryEl.setAttribute(BF_KEY, key);
+        if (getKey && !scope.primaryEl.getAttribute(keyAttrName2))
+          scope.primaryEl.setAttribute(keyAttrName2, key);
         scopes.set(key, scope);
         desiredOrder.push(scope);
       }
@@ -2396,7 +2403,7 @@ function mapArrayAnchored(accessor, container, getKey, renderItem, markerId, bfI
 }
 // src/runtime/map-array-lazy.ts
 import { createEffect as createEffect2, createSignal as createSignal2, untrack as untrack2 } from "@barefootjs/client/reactive";
-function mapArrayLazy(accessor, container, getKey, plan, markerId, bfId) {
+function mapArrayLazy(accessor, container, getKey, plan, markerId, bfId, keyAttrName2 = BF_KEY) {
   if (!container)
     return;
   const entries = new Map;
@@ -2435,8 +2442,8 @@ function mapArrayLazy(accessor, container, getKey, plan, markerId, bfId) {
       last: null
     };
     entry.primaryEl = untrack2(() => plan.createRow(entry, index));
-    if (!entry.primaryEl.dataset.key)
-      entry.primaryEl.setAttribute(BF_KEY, key);
+    if (getKey && !entry.primaryEl.getAttribute(keyAttrName2))
+      entry.primaryEl.setAttribute(keyAttrName2, key);
     markStranded();
     return entry;
   };
@@ -2458,7 +2465,7 @@ function mapArrayLazy(accessor, container, getKey, plan, markerId, bfId) {
         const shared = Math.min(doms.length, items.length);
         for (let i2 = 0;i2 < shared; i2++) {
           const el = doms[i2];
-          const ssrKey = el.getAttribute(BF_KEY);
+          const ssrKey = el.getAttribute(keyAttrName2);
           const key = ssrKey !== null ? ssrKey : getKey ? getKey(items[i2], i2) : String(i2);
           const entry = { key, primaryEl: el, item: items[i2], refs: null, last: null };
           entries.set(key, entry);
@@ -3405,6 +3412,7 @@ export {
   onMount,
   onCleanup,
   mountRowRoot,
+  markupOrEmpty,
   mapArrayLazy,
   mapArrayAnchored,
   mapArray,

package/dist/runtime/map-array-lazy.d.ts

@@ -159,6 +159,11 @@ export interface LazyRowPlan<T> {
  * @param plan - Compiler-emitted row plan (see {@link LazyRowPlan})
  * @param markerId - Scoped loop marker id (`<!--bf-loop:<id>-->`), see #1087
  * @param bfId - Profiler attribution id for the reconciler effect
+ * @param keyAttrName - The row-key attribute NAME this loop resolved at
+ *                     compile time (`IRElement.keyAttr`/`keyAttrName(loop.depth)`,
+ *                     jsx-to-ir.ts). Defaults to `BF_KEY` (plain `'data-key'`),
+ *                     correct at the outermost loop; only a nested loop's
+ *                     compiled call passes a depth-suffixed name (#2753).
  */
-export declare function mapArrayLazy<T>(accessor: () => T[], container: HTMLElement | null, getKey: ((item: T, index: number) => string) | null, plan: LazyRowPlan<T>, markerId?: string, bfId?: string): void;
+export declare function mapArrayLazy<T>(accessor: () => T[], container: HTMLElement | null, getKey: ((item: T, index: number) => string) | null, plan: LazyRowPlan<T>, markerId?: string, bfId?: string, keyAttrName?: string): void;
 //# sourceMappingURL=map-array-lazy.d.ts.map

package/dist/runtime/map-array-lazy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"map-array-lazy.d.ts","sourceRoot":"","sources":["../../src/runtime/map-array-lazy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AAMH;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,WAAW,CAAA;IACtB,IAAI,EAAE,CAAC,CAAA;IACP,iFAAiF;IACjF,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IACpB,qDAAqD;IACrD,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B;gFAC4E;IAC5E,SAAS,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAAA;IAC7D;;;4EAGwE;IACxE,SAAS,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAA;IACpD;;;;;;;qEAOiE;IACjE,UAAU,CAAC,CAAC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;CAC1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,QAAQ,EAAE,MAAM,CAAC,EAAE,EACnB,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAqSN"}
+{"version":3,"file":"map-array-lazy.d.ts","sourceRoot":"","sources":["../../src/runtime/map-array-lazy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AAMH;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,WAAW,CAAA;IACtB,IAAI,EAAE,CAAC,CAAA;IACP,iFAAiF;IACjF,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IACpB,qDAAqD;IACrD,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B;gFAC4E;IAC5E,SAAS,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAAA;IAC7D;;;4EAGwE;IACxE,SAAS,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAA;IACpD;;;;;;;qEAOiE;IACjE,UAAU,CAAC,CAAC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;CAC1E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,QAAQ,EAAE,MAAM,CAAC,EAAE,EACnB,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,EACpB,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,EACb,WAAW,GAAE,MAAe,GAC3B,IAAI,CA0SN"}

package/dist/runtime/map-array.d.ts

@@ -62,8 +62,18 @@ export declare function longestIncreasingSubsequenceIndices(arr: number[]): numb
  *                     Receives item as signal accessor: item() returns current value.
  *                     When `existing` is passed, initializes the SSR-rendered element and returns it.
  *                     When `existing` is undefined, creates a new element and returns it.
+ * @param keyAttrName - The row-key attribute NAME this loop resolved at
+ *                     compile time (`IRElement.keyAttr`/`keyAttrName(loop.depth)`,
+ *                     jsx-to-ir.ts) — `'data-key'` at the outermost loop,
+ *                     `'data-key-N'` N levels deep. Defaults to `BF_KEY`
+ *                     (plain `'data-key'`), correct for every depth-0 call
+ *                     site; only a nested loop's compiled call passes a
+ *                     depth-suffixed name (#2753 Shape B — see the "Why not
+ *                     stamp unconditionally" note below for why this
+ *                     replaced a hardcoded constant instead of just fixing
+ *                     the value).
  */
-export declare function mapArray<T>(accessor: () => T[], container: HTMLElement | null, getKey: ((item: T, index: number) => string) | null, renderItem: (item: () => T, index: number, existing?: HTMLElement) => HTMLElement, markerId?: string, bfId?: string): void;
+export declare function mapArray<T>(accessor: () => T[], container: HTMLElement | null, getKey: ((item: T, index: number) => string) | null, renderItem: (item: () => T, index: number, existing?: HTMLElement) => HTMLElement, markerId?: string, bfId?: string, keyAttrName?: string): void;
 /**
  * Per-item scoped list rendering for whole-item conditionals (#1665).
  *

package/dist/runtime/map-array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"map-array.d.ts","sourceRoot":"","sources":["../../src/runtime/map-array.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,WAAW,EACtB,QAAQ,CAAC,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,CA+BhD;AAyHD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CA2B3E;AA4GD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,QAAQ,EAAE,MAAM,CAAC,EAAE,EACnB,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,KAAK,WAAW,EACjF,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAuSN;AAqHD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,QAAQ,EAAE,MAAM,CAAC,EAAE,EACnB,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,gBAAgB,GAAG,OAAO,EAC5F,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CA+FN"}
+{"version":3,"file":"map-array.d.ts","sourceRoot":"","sources":["../../src/runtime/map-array.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAkEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,WAAW,EACtB,QAAQ,CAAC,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAAA;CAAE,CA+BhD;AAyHD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CA2B3E;AA4GD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,QAAQ,EAAE,MAAM,CAAC,EAAE,EACnB,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,WAAW,KAAK,WAAW,EACjF,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,EACb,WAAW,GAAE,MAAe,GAC3B,IAAI,CAsUN;AAqHD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAChC,QAAQ,EAAE,MAAM,CAAC,EAAE,EACnB,SAAS,EAAE,WAAW,GAAG,IAAI,EAC7B,MAAM,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,IAAI,EACnD,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,OAAO,KAAK,gBAAgB,GAAG,OAAO,EAC5F,QAAQ,CAAC,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CA+FN"}

package/dist/runtime/standalone.js

@@ -1774,25 +1774,25 @@ function mountRowRoot(el) {
   }
   return el;
 }
-function createComponent(nameOrDef, props = {}, key, slot, mountAt) {
-  const element = materializeComponent(nameOrDef, props, key, slot, mountAt);
+function createComponent(nameOrDef, props = {}, key, slot, mountAt, keyAttrName2 = BF_KEY) {
+  const element = materializeComponent(nameOrDef, props, key, slot, mountAt, keyAttrName2);
   if (mountAt && mountAt.parentNode && element !== mountAt) {
     mountAt.replaceWith(element);
   }
   return element;
 }
-function materializeComponent(nameOrDef, props = {}, key, slot, mountAt) {
+function materializeComponent(nameOrDef, props = {}, key, slot, mountAt, keyAttrName2 = BF_KEY) {
   if (props == null)
     props = {};
   const rowMount = mountAt ? null : takeRowMountPoint();
   if (typeof nameOrDef !== "string") {
-    return createComponentFromDef(nameOrDef, props, key, mountAt, rowMount);
+    return createComponentFromDef(nameOrDef, props, key, mountAt, rowMount, keyAttrName2);
   }
   const name = nameOrDef;
   const templateFn = getTemplate(name);
   if (!templateFn) {
     console.warn(`[BarefootJS] Template not found for component: ${name}`);
-    return createPlaceholder(name, key);
+    return createPlaceholder(name, key, keyAttrName2);
   }
   const childrenDescriptor = Object.getOwnPropertyDescriptor(props, "children");
   const childrenIsGetter = childrenDescriptor != null && typeof childrenDescriptor.get === "function";
@@ -1825,6 +1825,8 @@ function materializeComponent(nameOrDef, props = {}, key, slot, mountAt) {
     _parentScopeId = scopeId;
   } else if (slot?.parent) {
     _parentScopeId = slot.parent;
+  } else if (!_parentScopeId) {
+    _parentScopeId = `${def?.name ?? name}_${generateId()}`;
   }
   let html;
   try {
@@ -1837,11 +1839,11 @@ function materializeComponent(nameOrDef, props = {}, key, slot, mountAt) {
   const element = isFragmentRoot ? roots.find((node) => node.nodeType === Node.ELEMENT_NODE) : roots[0];
   if (isFragmentRoot && roots.length > 0 && !element) {
     console.warn(`[BarefootJS] Fragment-root component ${name} rendered no element root; ` + "a scope needs at least one element to attach to. Wrap the content in an element.");
-    return createPlaceholder(name, key);
+    return createPlaceholder(name, key, keyAttrName2);
   }
   if (!element) {
     console.warn(`[BarefootJS] Template returned empty HTML for component: ${name}`);
-    return createPlaceholder(name, key);
+    return createPlaceholder(name, key, keyAttrName2);
   }
   if (scopeId && !isFragmentRoot) {
     element.setAttribute(BF_SCOPE, scopeId);
@@ -1852,7 +1854,7 @@ function materializeComponent(nameOrDef, props = {}, key, slot, mountAt) {
     element.setAttribute(BF_AT, slot.mount);
   }
   if (key !== undefined) {
-    element.setAttribute(BF_KEY, String(key));
+    element.setAttribute(keyAttrName2, String(key));
   }
   const fragmentComments = isFragmentRoot && scopeId ? {
     start: document.createComment(`${BF_SCOPE_COMMENT_PREFIX}${scopeId}`),
@@ -1968,11 +1970,11 @@ var ROOT_HAS_BFS_PATTERN = /^<\w+[^>]*\sbf-s="/;
 function generateId() {
   return Math.random().toString(36).slice(2, 8);
 }
-function createPlaceholder(name, key) {
+function createPlaceholder(name, key, keyAttrName2 = BF_KEY) {
   const el = document.createElement("div");
   el.setAttribute(BF_SCOPE, `${name}_placeholder`);
   if (key !== undefined) {
-    el.setAttribute(BF_KEY, String(key));
+    el.setAttribute(keyAttrName2, String(key));
   }
   el.textContent = `[${name}]`;
   el.style.cssText = "color: red; border: 1px dashed red; padding: 4px;";
@@ -2021,6 +2023,9 @@ function escapeTextOrMarkup(value) {
     return value[BF_MARKUP_BRAND];
   return escapeText(value);
 }
+function markupOrEmpty(value) {
+  return value == null ? "" : value;
+}
 function escapeTextOrNode(value) {
   if (isBfMarkup(value))
     return value[BF_MARKUP_BRAND];
@@ -2082,7 +2087,7 @@ function insertGetterChildren(element, children) {
     element.appendChild(document.createTextNode(String(children)));
   }
 }
-function createComponentFromDef(def, props, key, mountAt, rowMount) {
+function createComponentFromDef(def, props, key, mountAt, rowMount, keyAttrName2 = BF_KEY) {
   if (!def.template) {
     throw new Error("[BarefootJS] createComponent with ComponentDef requires a template function");
   }
@@ -2099,7 +2104,7 @@ function createComponentFromDef(def, props, key, mountAt, rowMount) {
   const scopeId = `${name}_${generateId()}`;
   element.setAttribute(BF_SCOPE, scopeId);
   if (key !== undefined) {
-    element.setAttribute(BF_KEY, String(key));
+    element.setAttribute(keyAttrName2, String(key));
   }
   if (mountAt) {
     mountAt.replaceWith(element);
@@ -2480,7 +2485,7 @@ function createItemScope(item, index, renderItem, existingPrimary, existingExtra
   }
   return { startMarker, primaryEl, extras, scopeComments, dispose, setItem };
 }
-function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
+function mapArray(accessor, container, getKey, renderItem, markerId, bfId, keyAttrName2 = BF_KEY) {
   if (!container)
     return;
   const scopes = new Map;
@@ -2505,13 +2510,15 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
     if (!hydrated) {
       hydrated = true;
       const existingRanges = startMarker ? findItemRanges(startMarker, endMarker) : Array.from(container.children).map((el) => ({ startMarker: null, primaryEl: el, extras: [], scopeComments: null }));
-      const needsHydration = existingRanges.length > 0 && (!existingRanges[0]?.primaryEl.hasAttribute("data-key") || scopes.size === 0);
+      const needsHydration = existingRanges.length > 0;
       if (needsHydration) {
         for (let i2 = 0;i2 < existingRanges.length && i2 < items.length; i2++) {
           const range = existingRanges[i2];
           const item = items[i2];
           const key = getKey ? getKey(item, i2) : String(i2);
-          range.primaryEl.setAttribute(BF_KEY, key);
+          if (getKey && !range.primaryEl.getAttribute(keyAttrName2)) {
+            range.primaryEl.setAttribute(keyAttrName2, key);
+          }
           const scope = createItemScope(item, i2, renderItem, range.primaryEl, range.extras, range.startMarker, range.scopeComments);
           scopes.set(key, scope);
           hydratedScopes.add(range.primaryEl);
@@ -2520,8 +2527,8 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
           const item = items[i2];
           const key = getKey ? getKey(item, i2) : String(i2);
           const scope = createItemScope(item, i2, renderItem, undefined, undefined, undefined, undefined, { container, anchor });
-          if (!scope.primaryEl.dataset.key)
-            scope.primaryEl.setAttribute(BF_KEY, key);
+          if (getKey && !scope.primaryEl.getAttribute(keyAttrName2))
+            scope.primaryEl.setAttribute(keyAttrName2, key);
           scopes.set(key, scope);
           insertScope(scope, container, anchor);
         }
@@ -2546,7 +2553,7 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
     if (scopes.size === 0) {
       const loopRanges = startMarker ? findItemRanges(startMarker, endMarker) : Array.from(container.children).map((el) => ({ startMarker: null, primaryEl: el, extras: [], scopeComments: null }));
       for (const range of loopRanges) {
-        const existingKey = range.primaryEl.dataset?.key;
+        const existingKey = range.primaryEl.getAttribute(keyAttrName2);
         if (existingKey && !scopes.has(existingKey)) {
           scopes.set(existingKey, {
             startMarker: range.startMarker,
@@ -2604,8 +2611,8 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
         desiredOrder.push(existing);
       } else {
         const scope = createItemScope(item, i2, renderItem, undefined, undefined, undefined, undefined, { container, anchor });
-        if (!scope.primaryEl.dataset.key)
-          scope.primaryEl.setAttribute(BF_KEY, key);
+        if (getKey && !scope.primaryEl.getAttribute(keyAttrName2))
+          scope.primaryEl.setAttribute(keyAttrName2, key);
         scopes.set(key, scope);
         desiredOrder.push(scope);
       }
@@ -2800,7 +2807,7 @@ function mapArrayAnchored(accessor, container, getKey, renderItem, markerId, bfI
   }, bfId);
 }
 // src/runtime/map-array-lazy.ts
-function mapArrayLazy(accessor, container, getKey, plan, markerId, bfId) {
+function mapArrayLazy(accessor, container, getKey, plan, markerId, bfId, keyAttrName2 = BF_KEY) {
   if (!container)
     return;
   const entries = new Map;
@@ -2839,8 +2846,8 @@ function mapArrayLazy(accessor, container, getKey, plan, markerId, bfId) {
       last: null
     };
     entry.primaryEl = untrack(() => plan.createRow(entry, index));
-    if (!entry.primaryEl.dataset.key)
-      entry.primaryEl.setAttribute(BF_KEY, key);
+    if (getKey && !entry.primaryEl.getAttribute(keyAttrName2))
+      entry.primaryEl.setAttribute(keyAttrName2, key);
     markStranded();
     return entry;
   };
@@ -2862,7 +2869,7 @@ function mapArrayLazy(accessor, container, getKey, plan, markerId, bfId) {
         const shared = Math.min(doms.length, items.length);
         for (let i2 = 0;i2 < shared; i2++) {
           const el = doms[i2];
-          const ssrKey = el.getAttribute(BF_KEY);
+          const ssrKey = el.getAttribute(keyAttrName2);
           const key = ssrKey !== null ? ssrKey : getKey ? getKey(items[i2], i2) : String(i2);
           const entry = { key, primaryEl: el, item: items[i2], refs: null, last: null };
           entries.set(key, entry);
@@ -3804,6 +3811,7 @@ export {
   onMount,
   onCleanup,
   mountRowRoot,
+  markupOrEmpty,
   mapArrayLazy,
   mapArrayAnchored,
   mapArray,

package/package.json

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

package/src/runtime/component.ts

@@ -178,6 +178,7 @@ export function createComponent(
   key: string | number | undefined,
   slot: CreateComponentSlotInfo | undefined,
   mountAt: Element,
+  keyAttrName?: string,
 ): HTMLElement
 export function createComponent(
   nameOrDef: string | ComponentDef,
@@ -185,6 +186,7 @@ export function createComponent(
   key?: string | number,
   slot?: CreateComponentSlotInfo,
   mountAt?: Element | null,
+  keyAttrName?: string,
 ): HTMLElement | DocumentFragment
 export function createComponent(
   nameOrDef: string | ComponentDef,
@@ -192,8 +194,9 @@ export function createComponent(
   key?: string | number,
   slot?: CreateComponentSlotInfo,
   mountAt?: Element | null,
+  keyAttrName: string = BF_KEY,
 ): HTMLElement | DocumentFragment {
-  const element = materializeComponent(nameOrDef, props, key, slot, mountAt)
+  const element = materializeComponent(nameOrDef, props, key, slot, mountAt, keyAttrName)
   // `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
@@ -224,6 +227,7 @@ function materializeComponent(
   key?: string | number,
   slot?: CreateComponentSlotInfo,
   mountAt?: Element | null,
+  keyAttrName: string = BF_KEY,
 ): HTMLElement | DocumentFragment {
   // A bare callable shim invoked from user code (e.g. an object-literal
   // value `LOGOS[id]()` whose arrow the compiler hoisted into a component)
@@ -235,7 +239,7 @@ function materializeComponent(
   const rowMount = mountAt ? null : takeRowMountPoint()
   // ComponentDef mode: use def directly instead of registry lookup
   if (typeof nameOrDef !== 'string') {
-    return createComponentFromDef(nameOrDef, props, key, mountAt, rowMount)
+    return createComponentFromDef(nameOrDef, props, key, mountAt, rowMount, keyAttrName)
   }
 
   const name = nameOrDef
@@ -244,7 +248,7 @@ function materializeComponent(
   const templateFn = getTemplate(name)
   if (!templateFn) {
     console.warn(`[BarefootJS] Template not found for component: ${name}`)
-    return createPlaceholder(name, key)
+    return createPlaceholder(name, key, keyAttrName)
   }
 
   // 2. Check for getter children.
@@ -328,11 +332,32 @@ function materializeComponent(
   // #2444's `grandchild-composition` case). A comment wrapper keeps
   // `scopeId === null` and falls through to `slot?.parent`, preserving the
   // hoisted-children placeholder resolution (#1320).
+  //
+  // Third branch (#2757): a root-is-a-child-call wrapper mounted at the TOP
+  // LEVEL has neither. `scopeId` is null by design (step 4 — the parsed
+  // firstChild is the child's own already-scoped element, so we must not
+  // stamp over it) and a top-level `createComponent(name, {})` is passed no
+  // `slot`, so pre-#2757 `_parentScopeId` stayed null for the whole template
+  // eval and `renderChild` fell back to naming the child after ITSELF
+  // (`PairwiseRow_xyz_s2` where SSR and hydration both produce
+  // `PairwiseCase_xyz_s2`, and with no `bf-h`/`bf-m` at all). The wrapper
+  // still HAS a scope identity in the SSR convention — it just has no
+  // element of its own to carry it — so derive one here for threading only.
+  // Same split #2722 made for a genuine fragment root, which keeps a
+  // non-null `scopeId` purely so this threading works and skips only the
+  // ATTRIBUTE write in step 7.
+  //
+  // Why not derive unconditionally: guarded on `!_parentScopeId` so a
+  // wrapper materialized while an OUTER template eval is in flight keeps
+  // inheriting that caller's ambient scope rather than being renamed under a
+  // fresh random id. Only the genuinely-rootless mount is affected.
   const prevParentScopeId = _parentScopeId
   if (scopeId) {
     _parentScopeId = scopeId
   } else if (slot?.parent) {
     _parentScopeId = slot.parent
+  } else if (!_parentScopeId) {
+    _parentScopeId = `${def?.name ?? name}_${generateId()}`
   }
   let html: string
   try {
@@ -385,12 +410,12 @@ function materializeComponent(
       `[BarefootJS] Fragment-root component ${name} rendered no element root; ` +
         'a scope needs at least one element to attach to. Wrap the content in an element.',
     )
-    return createPlaceholder(name, key)
+    return createPlaceholder(name, key, keyAttrName)
   }
 
   if (!element) {
     console.warn(`[BarefootJS] Template returned empty HTML for component: ${name}`)
-    return createPlaceholder(name, key)
+    return createPlaceholder(name, key, keyAttrName)
   }
 
   // 7. Set scope ID and key attributes.
@@ -408,7 +433,7 @@ function materializeComponent(
     element.setAttribute(BF_AT, slot.mount)
   }
   if (key !== undefined) {
-    element.setAttribute(BF_KEY, String(key))
+    element.setAttribute(keyAttrName, String(key))
   }
 
   // 7a. Fragment-root boundary comments + registry (#2722).
@@ -722,8 +747,8 @@ export function renderChild(
     const hostSuffix = (_parentScopeId && slotSuffix) ? `|h=${_parentScopeId}|m=${slotSuffix}` : ''
     // #2732: `data-key` for a fragment-root loop row lands on the row's own
     // first element — the same "first element, not first node" convention
-    // `IRElement.carriesDataKey` uses on the SSR side (jsx-to-ir.ts) — not
-    // on the comment above, which carries scope identity only. This keeps
+    // `IRElement.keyAttr` uses on the SSR side (jsx-to-ir.ts) — not on the
+    // comment above, which carries scope identity only. This keeps
     // `mapArray`'s existing `primaryEl.dataset.key` read (map-array.ts)
     // working unchanged for markup this function pre-builds (the pure-CSR
     // `materializeComponent` template-string path, used when there is no
@@ -769,11 +794,11 @@ function generateId(): string {
 /**
  * Create a placeholder element when template is not found
  */
-function createPlaceholder(name: string, key?: string | number): HTMLElement {
+function createPlaceholder(name: string, key?: string | number, keyAttrName: string = BF_KEY): HTMLElement {
   const el = document.createElement('div')
   el.setAttribute(BF_SCOPE, `${name}_placeholder`)
   if (key !== undefined) {
-    el.setAttribute(BF_KEY, String(key))
+    el.setAttribute(keyAttrName, String(key))
   }
   el.textContent = `[${name}]`
   el.style.cssText = 'color: red; border: 1px dashed red; padding: 4px;'
@@ -949,6 +974,34 @@ export function escapeTextOrMarkup(value: unknown): string {
   return escapeText(value)
 }
 
+/**
+ * Nullish guard for a bare `${children}` passthrough splice
+ * (`ir-to-client-js/html-template.ts`'s no-`slotId` `'expression'` branches
+ * — the "bare `${...}` interpolations" the docstring above `escapeTextSlotExpr`
+ * describes) — #2775. The value here is ALREADY-STRINGIFIED MARKUP, not an
+ * arbitrary prop: `materializeComponent` (this file, "Template functions
+ * expect children as an HTML string, not an array") joins a component's
+ * `children` into an HTML string before the template lambda ever runs, so by
+ * the time this function sees the value it is either that HTML string or,
+ * when the caller passed none, simply `undefined` (the key is absent from
+ * the props object entirely). This function's ENTIRE job is that one
+ * nullish case: turn the absent/`null` value into `''`, same as SSR's
+ * `{props.children}` and the DSL adapters' `bf.string(children)` render it.
+ *
+ * Deliberately NOT `escapeTextOrMarkup`: that function falls back to
+ * `escapeText` for anything not `bfMarkup()`-branded, and a `children`
+ * string is never branded (it is a plain string built by
+ * `materializeComponent`, not compiler-escaped piece-by-piece the way a
+ * `bfMarkup()` value is) — routing `children` through it would HTML-escape
+ * real markup into visible `<span>`-style text on every call that
+ * actually has children, trading the no-children bug for a strictly worse
+ * with-children one. So: nullish becomes `''`; every other value is
+ * returned completely unescaped, exactly as it arrived.
+ */
+export function markupOrEmpty(value: unknown): string {
+  return value == null ? '' : (value as string)
+}
+
 /**
  * `escapeText`'s counterpart for a claimed 'markup' slot's REACTIVE write
  * (slot unification A3 follow-up), where the value is a plain-JS expression
@@ -1073,6 +1126,7 @@ function createComponentFromDef(
   key?: string | number,
   mountAt?: Element | null,
   rowMount?: { container: Node; anchor: Node | null } | null,
+  keyAttrName: string = BF_KEY,
 ): HTMLElement {
   if (!def.template) {
     throw new Error('[BarefootJS] createComponent with ComponentDef requires a template function')
@@ -1097,7 +1151,7 @@ function createComponentFromDef(
   const scopeId = `${name}_${generateId()}`
   element.setAttribute(BF_SCOPE, scopeId)
   if (key !== undefined) {
-    element.setAttribute(BF_KEY, String(key))
+    element.setAttribute(keyAttrName, String(key))
   }
 
   // Connect before init, for the same reason the registry path does (see

package/src/runtime/index.ts

@@ -112,6 +112,7 @@ export {
   bfMarkup,
   isBfMarkup,
   escapeTextOrMarkup,
+  markupOrEmpty,
   type BfMarkup,
 } from './component.ts'
 

package/src/runtime/map-array-lazy.ts

@@ -166,6 +166,11 @@ export interface LazyRowPlan<T> {
  * @param plan - Compiler-emitted row plan (see {@link LazyRowPlan})
  * @param markerId - Scoped loop marker id (`<!--bf-loop:<id>-->`), see #1087
  * @param bfId - Profiler attribution id for the reconciler effect
+ * @param keyAttrName - The row-key attribute NAME this loop resolved at
+ *                     compile time (`IRElement.keyAttr`/`keyAttrName(loop.depth)`,
+ *                     jsx-to-ir.ts). Defaults to `BF_KEY` (plain `'data-key'`),
+ *                     correct at the outermost loop; only a nested loop's
+ *                     compiled call passes a depth-suffixed name (#2753).
  */
 export function mapArrayLazy<T>(
   accessor: () => T[],
@@ -174,6 +179,7 @@ export function mapArrayLazy<T>(
   plan: LazyRowPlan<T>,
   markerId?: string,
   bfId?: string,
+  keyAttrName: string = BF_KEY,
 ): void {
   if (!container) return
 
@@ -249,8 +255,11 @@ export function mapArrayLazy<T>(
    * so it is wrapped in `untrack()`: it writes outer-involving bindings
    * with current values (contract), and those signal reads must not
    * subscribe the reconciler. The returned element is assigned to
-   * `entry.primaryEl`; `data-key` is stamped if `createRow` didn't
-   * (mirrors `mapArray`'s create path).
+   * `entry.primaryEl`; the row's key attribute is stamped if `createRow`
+   * didn't (mirrors `mapArray`'s create path) — only for a KEYED loop
+   * (#2753 Shape A: an unkeyed loop's rows carry no key attribute at all),
+   * using `keyAttrName` (Shape B: a nested loop's name is depth-suffixed,
+   * never the plain default `BF_KEY`).
    */
   const createEntry = (item: T, index: number, key: string): LazyRowEntry<T> => {
     const entry: LazyRowEntry<T> = {
@@ -263,7 +272,7 @@ export function mapArrayLazy<T>(
       last: null,
     }
     entry.primaryEl = untrack(() => plan.createRow(entry, index))
-    if (!entry.primaryEl.dataset.key) entry.primaryEl.setAttribute(BF_KEY, key)
+    if (getKey && !entry.primaryEl.getAttribute(keyAttrName)) entry.primaryEl.setAttribute(keyAttrName, key)
     markStranded()
     return entry
   }
@@ -294,7 +303,9 @@ export function mapArrayLazy<T>(
           const el = doms[i]
           // READ the SSR-rendered key (never write it on adopted rows);
           // positional item pairing is sound by the §9.3(2) eligibility gate.
-          const ssrKey = el.getAttribute(BF_KEY)
+          // `keyAttrName`, not the plain `BF_KEY` default — a nested loop's
+          // rows carry a depth-suffixed name (#2753 Shape B).
+          const ssrKey = el.getAttribute(keyAttrName)
           const key = ssrKey !== null ? ssrKey : getKey ? getKey(items[i], i) : String(i)
           const entry: LazyRowEntry<T> = { key, primaryEl: el, item: items[i], refs: null, last: null }
           entries.set(key, entry)

package/src/runtime/map-array.ts

@@ -412,6 +412,16 @@ function createItemScope<T>(
  *                     Receives item as signal accessor: item() returns current value.
  *                     When `existing` is passed, initializes the SSR-rendered element and returns it.
  *                     When `existing` is undefined, creates a new element and returns it.
+ * @param keyAttrName - The row-key attribute NAME this loop resolved at
+ *                     compile time (`IRElement.keyAttr`/`keyAttrName(loop.depth)`,
+ *                     jsx-to-ir.ts) — `'data-key'` at the outermost loop,
+ *                     `'data-key-N'` N levels deep. Defaults to `BF_KEY`
+ *                     (plain `'data-key'`), correct for every depth-0 call
+ *                     site; only a nested loop's compiled call passes a
+ *                     depth-suffixed name (#2753 Shape B — see the "Why not
+ *                     stamp unconditionally" note below for why this
+ *                     replaced a hardcoded constant instead of just fixing
+ *                     the value).
  */
 export function mapArray<T>(
   accessor: () => T[],
@@ -420,6 +430,7 @@ export function mapArray<T>(
   renderItem: (item: () => T, index: number, existing?: HTMLElement) => HTMLElement,
   markerId?: string,
   bfId?: string,
+  keyAttrName: string = BF_KEY,
 ): void {
   if (!container) return
 
@@ -460,18 +471,46 @@ export function mapArray<T>(
             (el) => ({ startMarker: null, primaryEl: el as HTMLElement, extras: [] as HTMLElement[], scopeComments: null as ScopeCommentPair | null }),
           )
 
-      // SSR elements need initialization when they haven't been adopted into scopes yet.
-      // Check both: elements without data-key (legacy) OR elements with data-key but no scopes
-      // (component loops render data-key in SSR template but haven't been hydrated).
+      // #2753 — why not read the DOM for a hydration signal: this branch
+      // runs at most ONCE per `mapArray` call (guarded by the closure-local
+      // `hydrated` flag, set true on the line above, before anything else
+      // can run), and `scopes` is a closure-local Map that is ALWAYS empty
+      // the first time this line runs — nothing sets it earlier. So "has
+      // this container already been adopted" is already fully answered by
+      // `existingRanges.length > 0` (there is DOM here from SSR/a prior
+      // render) with no attribute read at all. The attribute the old check
+      // read (`hasAttribute('data-key')`) was never a sound signal anyway:
+      // an unkeyed loop's rows legitimately carry no key attribute at all
+      // (Shape A), and a nested loop's rows carry a depth-suffixed name
+      // (`data-key-N`, Shape B) — so the plain-name probe either
+      // misdiagnosed a correctly-unkeyed row as "not yet hydrated", or
+      // missed a correctly-keyed nested row entirely. `scopes.size === 0`
+      // is not a second, independent signal here — it is ALWAYS true at
+      // this line, so the two-part `||` reduced to the first probe being
+      // moot: this is a behavior-preserving simplification, not a new rule.
       const needsHydration = existingRanges.length > 0
-        && (!existingRanges[0]?.primaryEl.hasAttribute('data-key') || scopes.size === 0)
       if (needsHydration) {
         // Hydrate in place: tag keys, create per-item scopes with renderItem(existing)
         for (let i = 0; i < existingRanges.length && i < items.length; i++) {
           const range = existingRanges[i]
           const item = items[i]
           const key = getKey ? getKey(item, i) : String(i)
-          range.primaryEl.setAttribute(BF_KEY, key)
+          // Only a KEYED loop gets a key attribute at all (Shape A) — SSR
+          // (or the static template this row cloned from) already carries
+          // the correct, depth-aware name (Shape B) when it applies, so this
+          // is a defensive backfill for a row that arrived without one, not
+          // the primary writer. A FALSY-value check (`getAttribute`, not
+          // `hasAttribute`) — not just presence — because a compiled
+          // template can bake the attribute PRESENT but empty for a shape
+          // whose key expression isn't ready at clone time (measured on the
+          // csr-mount leg of a keyed top-level loop); `hasAttribute` would
+          // wrongly treat that empty placeholder as "already correct" and
+          // skip the backfill this line exists to make. Reads the SAME name
+          // being written (not `dataset.key`, which only ever reads the
+          // plain, undepth-suffixed name).
+          if (getKey && !range.primaryEl.getAttribute(keyAttrName)) {
+            range.primaryEl.setAttribute(keyAttrName, key)
+          }
 
           const scope = createItemScope(
             item,
@@ -493,7 +532,7 @@ export function mapArray<T>(
           // Final position is known here (append before the loop's trailing
           // anchor), so the row can be mounted at it before its init runs.
           const scope = createItemScope(item, i, renderItem, undefined, undefined, undefined, undefined, { container, anchor })
-          if (!scope.primaryEl.dataset.key) scope.primaryEl.setAttribute(BF_KEY, key)
+          if (getKey && !scope.primaryEl.getAttribute(keyAttrName)) scope.primaryEl.setAttribute(keyAttrName, key)
           scopes.set(key, scope)
           insertScope(scope, container, anchor)
         }
@@ -522,7 +561,10 @@ export function mapArray<T>(
             (el) => ({ startMarker: null, primaryEl: el as HTMLElement, extras: [] as HTMLElement[], scopeComments: null as ScopeCommentPair | null }),
           )
       for (const range of loopRanges) {
-        const existingKey = range.primaryEl.dataset?.key
+        // `getAttribute(keyAttrName)`, not `dataset.key` — `dataset` only
+        // ever reads the plain, undepth-suffixed `data-key`, which misses a
+        // nested loop's `data-key-N` rows entirely (#2753 Shape B).
+        const existingKey = range.primaryEl.getAttribute(keyAttrName)
         if (existingKey && !scopes.has(existingKey)) {
           scopes.set(existingKey, {
             startMarker: range.startMarker,
@@ -612,7 +654,7 @@ export function mapArray<T>(
         // to its final position (it participates in the walk like any other
         // attached scope, so the resulting order is unchanged).
         const scope = createItemScope(item, i, renderItem, undefined, undefined, undefined, undefined, { container, anchor })
-        if (!scope.primaryEl.dataset.key) scope.primaryEl.setAttribute(BF_KEY, key)
+        if (getKey && !scope.primaryEl.getAttribute(keyAttrName)) scope.primaryEl.setAttribute(keyAttrName, key)
         scopes.set(key, scope)
         desiredOrder.push(scope)
       }