@barefootjs/client 0.33.1 → 0.33.3

package/dist/runtime/index.js

@@ -1330,8 +1330,7 @@ function hydrateCommentScope(comment) {
   if (hydratedScopes.has(proxyEl))
     return;
   commentScopeRegistry.set(proxyEl, { commentNode: comment, scopeId });
-  const parsed = parseProps(propsJson || null, `comment scope ${scopeId}`);
-  const props = parsed[name] ?? {};
+  const props = parseProps(propsJson || null, `comment scope ${scopeId}`);
   runInit(proxyEl, def, props);
 }
 function nextElementSibling2(node) {
@@ -1369,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";
@@ -1412,13 +1411,16 @@ function materializeComponent(nameOrDef, props = {}, key, slot, mountAt) {
   });
   const def = getRegisteredDef(name);
   const isCommentWrapper = def?.comment === true;
+  const isFragmentRoot = def?.fragmentRoot === true;
   const derivedScopeId = slot?.parent && slot.mount ? `${slot.parent}_${slot.mount}` : null;
-  const scopeId = isCommentWrapper ? null : derivedScopeId ?? `${def?.name ?? name}_${generateId()}`;
+  const scopeId = isCommentWrapper && !isFragmentRoot ? null : derivedScopeId ?? `${def?.name ?? name}_${generateId()}`;
   const prevParentScopeId = _parentScopeId;
   if (scopeId) {
     _parentScopeId = scopeId;
   } else if (slot?.parent) {
     _parentScopeId = slot.parent;
+  } else if (!_parentScopeId) {
+    _parentScopeId = `${def?.name ?? name}_${generateId()}`;
   }
   let html;
   try {
@@ -1426,12 +1428,18 @@ function materializeComponent(nameOrDef, props = {}, key, slot, mountAt) {
   } finally {
     _parentScopeId = prevParentScopeId;
   }
-  const element = parseHTML(html.trim()).firstChild;
+  const parsedFragment = parseHTML(html.trim());
+  const roots = isFragmentRoot ? Array.from(parsedFragment.childNodes) : parsedFragment.firstChild ? [parsedFragment.firstChild] : [];
+  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, keyAttrName2);
+  }
   if (!element) {
     console.warn(`[BarefootJS] Template returned empty HTML for component: ${name}`);
-    return createPlaceholder(name, key);
+    return createPlaceholder(name, key, keyAttrName2);
   }
-  if (scopeId) {
+  if (scopeId && !isFragmentRoot) {
     element.setAttribute(BF_SCOPE, scopeId);
   }
   if (slot) {
@@ -1440,13 +1448,38 @@ 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}`),
+    end: document.createComment(`${BF_SCOPE_COMMENT_END_PREFIX}${scopeId}`)
+  } : null;
+  if (fragmentComments) {
+    commentScopeRegistry.set(element, { commentNode: fragmentComments.start, scopeId });
   }
   const rootIsDeferredPlaceholder = element.hasAttribute(BF_PLACEHOLDER);
+  let bareFragment = null;
   if (mountAt && !rootIsDeferredPlaceholder) {
-    mountAt.replaceWith(element);
+    if (fragmentComments) {
+      mountAt.replaceWith(fragmentComments.start, ...roots, fragmentComments.end);
+    } else {
+      mountAt.replaceWith(element);
+    }
   } else if (rowMount && !rootIsDeferredPlaceholder) {
-    rowMount.container.insertBefore(element, rowMount.anchor);
+    if (fragmentComments) {
+      rowMount.container.insertBefore(fragmentComments.start, rowMount.anchor);
+      rowMount.container.insertBefore(element, rowMount.anchor);
+      rowMount.container.insertBefore(fragmentComments.end, rowMount.anchor);
+      element.__bfScopeComments = fragmentComments;
+      if (roots.length > 1) {
+        console.warn(`[BarefootJS] Fragment-root component ${name} used as a loop row renders ` + `${roots.length} top-level nodes; only the first element is connected here. ` + "See https://github.com/piconic-ai/barefootjs/issues/2733");
+      }
+    } else {
+      rowMount.container.insertBefore(element, rowMount.anchor);
+    }
+  } else if (fragmentComments && !rootIsDeferredPlaceholder) {
+    bareFragment = document.createDocumentFragment();
+    bareFragment.append(fragmentComments.start, ...roots, fragmentComments.end);
   }
   const prevScope = setCurrentScope(element);
   let placeholderWrapper = null;
@@ -1474,18 +1507,30 @@ function materializeComponent(nameOrDef, props = {}, key, slot, mountAt) {
   }
   setCurrentScope(prevScope);
   hydratedScopes.add(element);
-  return element;
+  return bareFragment ?? element;
+}
+var FIRST_TAG_PATTERN = /<([a-zA-Z][^\s/>]*)/;
+var TAG_HEAD_PATTERN = /^(<[a-zA-Z][^\s/>]*)/;
+function spliceAttrsAfterFirstTag(html, attrs) {
+  const firstElMatch = html.match(FIRST_TAG_PATTERN);
+  if (!firstElMatch)
+    return html;
+  const insertPos = firstElMatch.index;
+  return html.slice(0, insertPos) + html.slice(insertPos).replace(TAG_HEAD_PATTERN, `$1${attrs}`);
 }
 function renderChild(name, props, key, slotSuffix) {
   const templateFn = getTemplate(name);
   const suffix = slotSuffix ? `_${slotSuffix}` : "";
-  const displayName = getRegisteredDef(name)?.name ?? name;
+  const def = getRegisteredDef(name);
+  const displayName = def?.name ?? name;
+  const isFragmentRoot = def?.fragmentRoot === true;
   const scopePrefix = _parentScopeId && slotSuffix ? _parentScopeId : `${displayName}_${generateId()}`;
+  const scopeId = `${scopePrefix}${suffix}`;
   const keyAttr = key !== undefined ? ` ${BF_KEY}="${key}"` : "";
   const slotAttrs = _parentScopeId && slotSuffix ? ` ${BF_HOST}="${_parentScopeId}" ${BF_AT}="${slotSuffix}"` : "";
-  const bfsAttr = `${BF_SCOPE}="${scopePrefix}${suffix}"`;
+  const bfsAttr = `${BF_SCOPE}="${scopeId}"`;
   if (!templateFn) {
-    return `<div ${bfsAttr}${slotAttrs}${keyAttr}></div>`;
+    return isFragmentRoot ? `<!--${BF_SCOPE_COMMENT_PREFIX}${scopeId}--><div></div><!--${BF_SCOPE_COMMENT_END_PREFIX}${scopeId}-->` : `<div ${bfsAttr}${slotAttrs}${keyAttr}></div>`;
   }
   const prevParentScopeId = _parentScopeId;
   _parentScopeId = `${scopePrefix}${suffix}`;
@@ -1496,7 +1541,12 @@ function renderChild(name, props, key, slotSuffix) {
     _parentScopeId = prevParentScopeId;
   }
   let html = raw.trim().replace(PLACEHOLDER_ATTR_PATTERN, _parentScopeId ? ` bf-s="${_parentScopeId}"` : "");
-  const firstElMatch = html.match(/<(\w+)/);
+  if (isFragmentRoot) {
+    const hostSuffix = _parentScopeId && slotSuffix ? `|h=${_parentScopeId}|m=${slotSuffix}` : "";
+    const keyedHtml = keyAttr ? spliceAttrsAfterFirstTag(html, keyAttr) : html;
+    return `<!--${BF_SCOPE_COMMENT_PREFIX}${scopeId}${hostSuffix}-->${keyedHtml}<!--${BF_SCOPE_COMMENT_END_PREFIX}${scopeId}-->`;
+  }
+  const firstElMatch = html.match(FIRST_TAG_PATTERN);
   if (!firstElMatch)
     return html;
   const insertPos = firstElMatch.index;
@@ -1505,20 +1555,20 @@ function renderChild(name, props, key, slotSuffix) {
   if (ROOT_HAS_BFS_PATTERN.test(afterInsert)) {
     if (!extraAttrs)
       return html;
-    return html.slice(0, insertPos) + afterInsert.replace(/^(<\w+)/, `$1${extraAttrs}`);
+    return html.slice(0, insertPos) + afterInsert.replace(TAG_HEAD_PATTERN, `$1${extraAttrs}`);
   }
-  return html.slice(0, insertPos) + afterInsert.replace(/^(<\w+)/, `$1 ${bfsAttr}${extraAttrs}`);
+  return html.slice(0, insertPos) + afterInsert.replace(TAG_HEAD_PATTERN, `$1 ${bfsAttr}${extraAttrs}`);
 }
 var PLACEHOLDER_ATTR_PATTERN = new RegExp(`\\s+bf-s="${BF_PARENT_SCOPE_PLACEHOLDER}"`, "g");
 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;";
@@ -1567,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];
@@ -1628,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");
   }
@@ -1645,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);
@@ -1838,6 +1891,11 @@ function upsertChildItem(primaryEl, name, slotId, props, key, anchorScope) {
 }
 // src/runtime/map-array.ts
 import { createSignal, createEffect, createRoot as createRoot2 } from "@barefootjs/client/reactive";
+function scopeIdOf(start) {
+  const rest = (start.nodeValue ?? "").slice(BF_SCOPE_COMMENT_PREFIX.length);
+  const pipe = rest.indexOf("|");
+  return pipe >= 0 ? rest.slice(0, pipe) : rest;
+}
 function findLoopMarkers2(container, markerId) {
   let start = null;
   let end = null;
@@ -1875,31 +1933,55 @@ function findItemRanges(start, end) {
   const ranges = [];
   let current = null;
   let sawItemMarker = false;
+  let pendingScopeStart = null;
+  let openScopeComments = null;
   let node = start.nextSibling;
   while (node && node !== end) {
-    if (node.nodeType === Node.COMMENT_NODE && node.nodeValue === BF_LOOP_ITEM) {
-      sawItemMarker = true;
-      current = { startMarker: node, primaryEl: null, extras: [] };
-      ranges.push(current);
+    if (node.nodeType === Node.COMMENT_NODE) {
+      const value = node.nodeValue ?? "";
+      if (value === BF_LOOP_ITEM) {
+        sawItemMarker = true;
+        current = { startMarker: node, primaryEl: null, extras: [], scopeComments: null };
+        ranges.push(current);
+      } else if (value.startsWith(BF_SCOPE_COMMENT_PREFIX)) {
+        pendingScopeStart = node;
+      } else if (openScopeComments && value === BF_SCOPE_COMMENT_END_PREFIX + scopeIdOf(openScopeComments.start)) {
+        openScopeComments.end = node;
+        openScopeComments = null;
+      }
     } else if (node.nodeType === Node.ELEMENT_NODE) {
       const el = node;
+      let scopeComments = null;
+      if (pendingScopeStart) {
+        scopeComments = { start: pendingScopeStart, end: null };
+        openScopeComments = scopeComments;
+        pendingScopeStart = null;
+      }
       if (sawItemMarker) {
-        if (!current.primaryEl)
+        if (!current.primaryEl) {
           current.primaryEl = el;
-        else
+          current.scopeComments = scopeComments;
+        } else
           current.extras.push(el);
       } else {
-        ranges.push({ startMarker: null, primaryEl: el, extras: [] });
+        ranges.push({ startMarker: null, primaryEl: el, extras: [], scopeComments });
       }
     }
     node = node.nextSibling;
   }
-  return ranges.filter((r) => r.primaryEl !== null);
+  return ranges.filter((r) => r.primaryEl !== null).map((r) => ({
+    ...r,
+    scopeComments: r.scopeComments?.end ? r.scopeComments : null
+  }));
 }
 function insertScope(scope, target, anchor) {
   if (scope.startMarker)
     target.insertBefore(scope.startMarker, anchor);
+  if (scope.scopeComments)
+    target.insertBefore(scope.scopeComments.start, anchor);
   target.insertBefore(scope.primaryEl, anchor);
+  if (scope.scopeComments)
+    target.insertBefore(scope.scopeComments.end, anchor);
   for (const ex of scope.extras)
     target.insertBefore(ex, anchor);
 }
@@ -1938,19 +2020,24 @@ function longestIncreasingSubsequenceIndices(arr) {
 function removeScope(scope) {
   if (scope.startMarker?.parentNode)
     scope.startMarker.remove();
+  if (scope.scopeComments?.start.parentNode)
+    scope.scopeComments.start.remove();
   if (scope.primaryEl.parentNode)
     scope.primaryEl.remove();
+  if (scope.scopeComments?.end.parentNode)
+    scope.scopeComments.end.remove();
   for (const ex of scope.extras) {
     if (ex.parentNode)
       ex.remove();
   }
 }
-function createItemScope(item, index, renderItem, existingPrimary, existingExtras, existingStart, rowMount) {
+function createItemScope(item, index, renderItem, existingPrimary, existingExtras, existingStart, existingScopeComments, rowMount) {
   let primaryEl;
   let dispose;
   let setItem;
   let extras = [];
   let startMarker = null;
+  let scopeComments = null;
   createRoot2((d) => {
     dispose = d;
     const [itemAccessor, itemSetter] = createSignal(item);
@@ -1973,6 +2060,7 @@ function createItemScope(item, index, renderItem, existingPrimary, existingExtra
     if (existingPrimary) {
       extras = existingExtras ?? [];
       startMarker = existingStart ?? null;
+      scopeComments = existingScopeComments ?? null;
     } else {
       const stashed = primaryEl.__bfExtras;
       if (stashed && stashed.length > 0) {
@@ -1980,15 +2068,19 @@ function createItemScope(item, index, renderItem, existingPrimary, existingExtra
         startMarker = document.createComment(BF_LOOP_ITEM);
       }
       delete primaryEl.__bfExtras;
+      const stashedScopeComments = primaryEl.__bfScopeComments;
+      if (stashedScopeComments)
+        scopeComments = stashedScopeComments;
+      delete primaryEl.__bfScopeComments;
     }
     return;
   });
   if (rowMount && !existingPrimary && extras.length > 0 && primaryEl.parentNode) {
     primaryEl.remove();
   }
-  return { startMarker, primaryEl, extras, dispose, setItem };
+  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;
@@ -2012,24 +2104,26 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
     const anchor = endMarker ?? null;
     if (!hydrated) {
       hydrated = true;
-      const existingRanges = startMarker ? findItemRanges(startMarker, endMarker) : Array.from(container.children).map((el) => ({ startMarker: null, primaryEl: el, extras: [] }));
-      const needsHydration = existingRanges.length > 0 && (!existingRanges[0]?.primaryEl.hasAttribute("data-key") || scopes.size === 0);
+      const existingRanges = startMarker ? findItemRanges(startMarker, endMarker) : Array.from(container.children).map((el) => ({ startMarker: null, primaryEl: el, extras: [], scopeComments: null }));
+      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);
-          const scope = createItemScope(item, i2, renderItem, range.primaryEl, range.extras, range.startMarker);
+          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);
         }
         for (let i2 = existingRanges.length;i2 < items.length; i2++) {
           const item = items[i2];
           const key = getKey ? getKey(item, i2) : String(i2);
-          const scope = createItemScope(item, i2, renderItem, undefined, undefined, undefined, { container, anchor });
-          if (!scope.primaryEl.dataset.key)
-            scope.primaryEl.setAttribute(BF_KEY, key);
+          const scope = createItemScope(item, i2, renderItem, undefined, undefined, undefined, undefined, { container, anchor });
+          if (getKey && !scope.primaryEl.getAttribute(keyAttrName2))
+            scope.primaryEl.setAttribute(keyAttrName2, key);
           scopes.set(key, scope);
           insertScope(scope, container, anchor);
         }
@@ -2037,8 +2131,12 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
           const range = existingRanges[i2];
           if (range.startMarker?.parentNode)
             range.startMarker.remove();
+          if (range.scopeComments?.start.parentNode)
+            range.scopeComments.start.remove();
           if (range.primaryEl.parentNode)
             range.primaryEl.remove();
+          if (range.scopeComments?.end.parentNode)
+            range.scopeComments.end.remove();
           for (const ex of range.extras) {
             if (ex.parentNode)
               ex.remove();
@@ -2048,14 +2146,15 @@ 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: [] }));
+      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,
             primaryEl: range.primaryEl,
             extras: range.extras,
+            scopeComments: range.scopeComments,
             dispose: () => {},
             setItem: () => {}
           });
@@ -2074,7 +2173,7 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
         } else {
           let expectedNodeCount = 0;
           for (const scope of scopes.values()) {
-            expectedNodeCount += 1 + scope.extras.length + (scope.startMarker ? 1 : 0);
+            expectedNodeCount += 1 + scope.extras.length + (scope.startMarker ? 1 : 0) + (scope.scopeComments ? 2 : 0);
           }
           let actualNodeCount = 0;
           for (let node = container.firstChild;node; node = node.nextSibling)
@@ -2106,9 +2205,9 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
         existing.setItem(item);
         desiredOrder.push(existing);
       } else {
-        const scope = createItemScope(item, i2, renderItem, undefined, undefined, undefined, { container, anchor });
-        if (!scope.primaryEl.dataset.key)
-          scope.primaryEl.setAttribute(BF_KEY, key);
+        const scope = createItemScope(item, i2, renderItem, undefined, undefined, undefined, undefined, { container, anchor });
+        if (getKey && !scope.primaryEl.getAttribute(keyAttrName2))
+          scope.primaryEl.setAttribute(keyAttrName2, key);
         scopes.set(key, scope);
         desiredOrder.push(scope);
       }
@@ -2145,7 +2244,7 @@ function mapArray(accessor, container, getKey, renderItem, markerId, bfId) {
       let j = i;
       while (j < desiredOrder.length && !stationary[j])
         j++;
-      const before = j < desiredOrder.length ? desiredOrder[j].startMarker ?? desiredOrder[j].primaryEl : anchor;
+      const before = j < desiredOrder.length ? desiredOrder[j].startMarker ?? desiredOrder[j].scopeComments?.start ?? desiredOrder[j].primaryEl : anchor;
       if (j - i === 1) {
         insertScope(desiredOrder[i], container, before);
       } else {
@@ -2304,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;
@@ -2343,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;
   };
@@ -2366,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);
@@ -3313,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;AAqCH;;;;;;;;;;;;;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;AA8DD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mCAAmC,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CA2B3E;AA2FD;;;;;;;;;;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,CA6RN;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/qsa-item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"qsa-item.d.ts","sourceRoot":"","sources":["../../src/runtime/qsa-item.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AA4CH;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAQnF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,OAAO,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EACrB,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,GAC3B,WAAW,GAAG,IAAI,CAuBpB"}
+{"version":3,"file":"qsa-item.d.ts","sourceRoot":"","sources":["../../src/runtime/qsa-item.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AA4CH;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CAQnF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,OAAO,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EACrB,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,GAC3B,WAAW,GAAG,IAAI,CAyBpB"}

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

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/runtime/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAaxC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAclE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,OAAO,GAAG,IAAI,EAC1B,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,IAAI,CAoCN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EACrB,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,GAC3B,WAAW,GAAG,IAAI,CAgCpB"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/runtime/registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAaxC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAclE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,OAAO,GAAG,IAAI,EAC1B,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,IAAI,CAoCN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EACrB,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,GAC3B,WAAW,GAAG,IAAI,CAmCpB"}