@barefootjs/client 0.33.1 → 0.33.3

package/src/runtime/component.ts

@@ -11,7 +11,17 @@ import { getRegisteredDef } from './hydrate.ts'
 import { hydratedScopes } from './hydration-state.ts'
 import { untrack } from '@barefootjs/client/reactive'
 import { setCurrentScope } from './context.ts'
-import { BF_SCOPE, BF_KEY, BF_HOST, BF_AT, BF_PARENT_SCOPE_PLACEHOLDER, BF_PLACEHOLDER } from '@barefootjs/shared'
+import { commentScopeRegistry } from './scope.ts'
+import {
+  BF_SCOPE,
+  BF_KEY,
+  BF_HOST,
+  BF_AT,
+  BF_PARENT_SCOPE_PLACEHOLDER,
+  BF_PLACEHOLDER,
+  BF_SCOPE_COMMENT_PREFIX,
+  BF_SCOPE_COMMENT_END_PREFIX,
+} from '@barefootjs/shared'
 import type { ComponentDef } from './types.ts'
 
 // Parent scope ID context for renderChild() inside insert() branch templates.
@@ -137,14 +147,56 @@ export interface CreateComponentSlotInfo {
   mount: string
 }
 
+/**
+ * The `HTMLElement | DocumentFragment` return covers exactly one shape: a
+ * BARE call (no `mountAt`, no ambient row-mount point) for a genuine
+ * fragment-root component (#2722). Every other combination — a normal
+ * component, or a fragment-root one with `mountAt`/row-mount already
+ * telling this function where to connect — still returns the real,
+ * single `HTMLElement`, unchanged (that element stays the caller-visible
+ * proxy even when the fragment root has further sibling roots of its own
+ * — #2735 — those travel alongside it, never in place of it). Only the
+ * no-known-destination case has no single element to hand back: the
+ * fragment root's own `<!--bf-scope:-->` boundary comments PLUS every
+ * top-level node the fragment's template rendered — elements, bare text
+ * and `<!--bf:sN-->` slot markers alike (`materializeComponent` step 7b)
+ * — must travel to wherever the caller inserts the result, and a
+ * `DocumentFragment` is the one `Node` a plain `container.appendChild(...)`
+ * / `el.replaceWith(...)` moves as a unit without the caller needing to
+ * know why.
+ *
+ * The first overload states that in the type system rather than only here:
+ * a call that passes a non-null `mountAt` is telling this function where to
+ * connect, so it can only get the real `HTMLElement` back. Callers on that
+ * overload need no cast, which is why `upsertChild` (registry.ts) and
+ * `upsertChildItem` (qsa-item.ts) assert nothing — the narrowing is the
+ * signature's job, not theirs.
+ */
+export function createComponent(
+  nameOrDef: string | ComponentDef,
+  props: Record<string, unknown>,
+  key: string | number | undefined,
+  slot: CreateComponentSlotInfo | undefined,
+  mountAt: Element,
+  keyAttrName?: string,
+): HTMLElement
+export function createComponent(
+  nameOrDef: string | ComponentDef,
+  props?: Record<string, unknown>,
+  key?: string | number,
+  slot?: CreateComponentSlotInfo,
+  mountAt?: Element | null,
+  keyAttrName?: string,
+): HTMLElement | DocumentFragment
 export function createComponent(
   nameOrDef: string | ComponentDef,
   props: Record<string, unknown> = {},
   key?: string | number,
   slot?: CreateComponentSlotInfo,
   mountAt?: Element | null,
-): HTMLElement {
-  const element = materializeComponent(nameOrDef, props, key, slot, mountAt)
+  keyAttrName: string = BF_KEY,
+): HTMLElement | DocumentFragment {
+  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
@@ -152,7 +204,9 @@ export function createComponent(
   // which must stay detached so its self-replacement stays recoverable.
   // `parentNode` (not `isConnected`) is the right "still unconsumed" probe: it
   // survives a `mountAt` that was itself detached, which is the normal case
-  // during multi-root loop-body setup.
+  // during multi-root loop-body setup. A fragment-root's `DocumentFragment`
+  // return only ever happens when `mountAt` is absent (see above), so it
+  // never reaches this branch.
   if (mountAt && mountAt.parentNode && element !== mountAt) {
     mountAt.replaceWith(element)
   }
@@ -173,7 +227,8 @@ function materializeComponent(
   key?: string | number,
   slot?: CreateComponentSlotInfo,
   mountAt?: Element | null,
-): HTMLElement {
+  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)
   // reaches us with no props (#1663). Normalize to an empty object so the
@@ -184,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
@@ -193,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.
@@ -230,11 +285,22 @@ function materializeComponent(
 
   // 4. Pre-generate the component's scope ID.
   //
-  // `comment: true` components (synthesized inline-JSX-callback wrappers
-  // from #1211) render as transparent shells — the parsed `firstChild` is
-  // already the inner component's root with its own bf-s. Don't overwrite
-  // it (scopeId stays null), or `$c(__scope, 's0')` from the wrapper's
-  // init resolves to null.
+  // `comment: true` components are proxy-scoped — no element of their own
+  // carries `bf-s` directly — but that covers TWO different shapes
+  // (`ComponentDef.fragmentRoot`'s docstring, types.ts) that need OPPOSITE
+  // treatment here:
+  //   - root-is-a-child-call (#1211/#2649, `fragmentRoot` false): the
+  //     parsed `firstChild` IS the child's own already-scoped element.
+  //     Don't overwrite it (scopeId stays null), or `$c(__scope, 's0')`
+  //     from the wrapper's init resolves to null.
+  //   - genuine fragment root (`fragmentRoot` true): the parsed `firstChild`
+  //     carries NO scope of its own (SSR moves it into the wrapping
+  //     `<!--bf-scope:-->` comment) — generate one just the same, so
+  //     `_parentScopeId` below still gets threaded into nested
+  //     `renderChild()` calls and their naming matches SSR/hydrate (#2722:
+  //     leaving this null made every nested child fall back to a random,
+  //     un-prefixed scope id — `Select_xyz` instead of the expected
+  //     `SelectBasicDemo_xyz_s8`).
   //
   // `slot` is only supplied by `upsertChild` / `upsertChildItem` mounting a
   // component nested below a loop row root — the SSR reference (Hono)
@@ -245,11 +311,12 @@ function materializeComponent(
   // random id, matching the reference behaviour.
   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
   // Same as in `renderChild`: `name` is the registry key, which is
   // file-scoped (`Name__<8hex>`) for a non-exported component. The scope ID
   // must carry the plain name — see `ComponentDef.name` (#2518).
-  const scopeId = isCommentWrapper ? null : (derivedScopeId ?? `${def?.name ?? name}_${generateId()}`)
+  const scopeId = (isCommentWrapper && !isFragmentRoot) ? null : (derivedScopeId ?? `${def?.name ?? name}_${generateId()}`)
 
   // 5. Generate HTML from props.
   //
@@ -265,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 {
@@ -278,16 +366,66 @@ function materializeComponent(
     _parentScopeId = prevParentScopeId
   }
 
-  // 6. Create DOM element
-  const element = parseHTML(html.trim()).firstChild as HTMLElement
+  // 6. Create DOM node(s).
+  //
+  // A genuine fragment root's template concatenates EVERY top-level
+  // sibling into one HTML string, so `roots` is the whole ordered list —
+  // `parseHTML(...).firstChild` used to be the only node kept, silently
+  // dropping the rest (#2735). Everything travels, whatever its node
+  // type: a fragment's top level is not only elements. Bare text between
+  // two element roots (`<><h1/>text<p/></>`) is a root, and a reactive
+  // text slot sitting there renders as a `<!--bf:sN-->` marker. Both were
+  // measured being dropped by an element-only walk — the text as a
+  // visible SSR/CSR-mount diff, the marker as something worse, since the
+  // runtime's own slot lookup then finds nothing to bind.
+  //
+  // `element` is the PROXY: the one node threaded through init /
+  // `commentScopeRegistry` / the return value. It must be an Element —
+  // everything downstream calls `setAttribute`/`hasAttribute` on it — so
+  // it is the first ELEMENT among the roots, not simply the first node.
+  // `<>text<p/></>` puts a Text node first, and taking that as the proxy
+  // threw `element.hasAttribute is not a function` at step 7b (measured;
+  // pre-dates #2735's fix, which is why the roots list and the proxy are
+  // chosen separately rather than the proxy being `roots[0]`).
+  //
+  // Only `isFragmentRoot` templates can emit more than one top-level node
+  // (jsx-to-ir.ts's `transformFragment`), so every other shape keeps
+  // exactly the single-node list it always had.
+  const parsedFragment = parseHTML(html.trim())
+  const roots: Node[] = isFragmentRoot
+    ? Array.from(parsedFragment.childNodes)
+    : parsedFragment.firstChild
+      ? [parsedFragment.firstChild]
+      : []
+  const element = (isFragmentRoot
+    ? roots.find(node => node.nodeType === Node.ELEMENT_NODE)
+    : roots[0]) as HTMLElement | undefined
+
+  // A fragment root with no element at all (`<>just text</>`) has nothing
+  // that can carry a scope. Refuse it the same way an empty template is
+  // refused rather than crashing on the first `setAttribute` — loud, not
+  // silent, per the sound-or-loud rule.
+  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, 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.
-  if (scopeId) {
+  //
+  // A genuine fragment root carries its scope id on a WRAPPING comment
+  // pair, never as a `bf-s` attribute on the element itself — matching
+  // `wrapWithScopeComment` (hono-adapter.ts) and `hydrateCommentScope`
+  // (hydrate.ts). `scopeId` is still non-null for this shape (step 4) so
+  // `_parentScopeId` threads correctly; only the ATTRIBUTE is skipped here.
+  if (scopeId && !isFragmentRoot) {
     element.setAttribute(BF_SCOPE, scopeId)
   }
   if (slot) {
@@ -295,7 +433,28 @@ 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).
+  //
+  // `find()`/`$()`/`$c()` (query.ts) resolve a slot or child scope by
+  // walking `commentScopeRegistry`'s stored comment and its boundary
+  // (`getCommentScopeBoundary`, scope.ts) — that walk needs REAL, sibling-
+  // connected comment nodes, not just a registry entry, or `find()`'s
+  // comment-scope branch enumerates zero candidates (worse than the
+  // fallback `querySelectorAll` path a non-fragment scope gets). So these
+  // are built now and threaded through to wherever `element` ends up
+  // connected below, exactly mirroring the SSR/hydrate shape:
+  //   <!--bf-scope:ID-->` + element + `<!--bf-/scope:ID-->`
+  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: scopeId! })
   }
 
   // 7b. Connect before init.
@@ -317,14 +476,76 @@ function materializeComponent(
   // live DOM with no handle on the result, so this shape keeps the
   // detached behaviour.
   const rootIsDeferredPlaceholder = element.hasAttribute(BF_PLACEHOLDER)
+  // A fragment root's boundary comments must land adjacent to `element`
+  // at the SAME moment it connects, in each of the three shapes below —
+  // there is no later hook to attach them once the caller has taken the
+  // return value away (see `createComponent`'s docstring for the fourth,
+  // no-known-destination shape, handled after `init` runs).
+  let bareFragment: DocumentFragment | null = null
   if (mountAt && !rootIsDeferredPlaceholder) {
-    mountAt.replaceWith(element)
+    if (fragmentComments) {
+      mountAt.replaceWith(fragmentComments.start, ...roots, fragmentComments.end)
+    } else {
+      mountAt.replaceWith(element)
+    }
   } else if (rowMount && !rootIsDeferredPlaceholder) {
     // Loop row: no placeholder exists, so connect at the position `mapArray`
     // handed down. The reorder step may move the row afterwards; any position
     // inside the container yields the same ancestor chain, which is all
     // `useContext`'s parentElement walk needs.
-    rowMount.container.insertBefore(element, rowMount.anchor)
+    if (fragmentComments) {
+      rowMount.container.insertBefore(fragmentComments.start, rowMount.anchor)
+      rowMount.container.insertBefore(element, rowMount.anchor)
+      rowMount.container.insertBefore(fragmentComments.end, rowMount.anchor)
+      // Hand the boundary pair to `mapArray`'s row bookkeeping (map-array.ts's
+      // `ItemScope.scopeComments`, #2733) via the same stash-on-the-element
+      // convention `__bfExtras` uses for a multi-root loop BODY's extra
+      // siblings: `createItemScope` reads and deletes this property right
+      // after `renderItem` returns, since there is no other channel back to
+      // the caller once `element` is the only thing returned below. Without
+      // this, a later reorder/removal of the row moves/removes `element`
+      // and leaves the comments behind, orphaned in the container.
+      ;(element as unknown as { __bfScopeComments?: { start: Comment; end: Comment } }).__bfScopeComments =
+        fragmentComments
+      // Deliberately NOT inserting the other roots here (a fragment-root
+      // component whose OWN render has 2+ top-level nodes, used as a loop
+      // row) — connecting them is a separate gap from the boundary-comment
+      // tracking #2733 fixed above: even with `ItemScope` now able to carry
+      // the row's comments, there is still nowhere on `ItemScope` for a
+      // second or third top-level ELEMENT of the row itself (as opposed to
+      // `extras`, which is the multi-root loop BODY's own, unrelated,
+      // per-item marker convention). Not reachable by any currently tracked
+      // fixture (no fragment-root component with 2+ top-level nodes is used
+      // as a loop row in the mutation corpus), so declared rather than grown
+      // here:
+      // https://github.com/piconic-ai/barefootjs/issues/2733
+      //
+      // Loud, not silent: the whole point of the fix above is that
+      // dropping roots without saying so is the failure mode. A gap that
+      // stays quiet is indistinguishable from correctness at the call
+      // site, so the one shape still dropping them says so.
+      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) {
+    // Neither a placeholder nor an ambient row position: the caller owns
+    // connecting the result itself (e.g. the compiler's exported
+    // `export function Name(props, key) { return createComponent(...) }`
+    // shim, called directly with no further composition — the shape
+    // `fixture-host.ts`'s `'csr-mount'` boot script uses). Bundle every
+    // node in one `DocumentFragment` so a plain `container.append(result)`
+    // / `el.replaceWith(result)` moves all of them together —
+    // `createComponent`'s docstring covers why this is the one shape that
+    // can't return a bare `HTMLElement`.
+    bareFragment = document.createDocumentFragment()
+    bareFragment.append(fragmentComments.start, ...roots, fragmentComments.end)
   }
 
   // 8. Set currentScope so provideContext/useContext are element-scoped.
@@ -390,7 +611,36 @@ function materializeComponent(
   // 12. Mark element as initialized
   hydratedScopes.add(element)
 
-  return element
+  // `bareFragment` bundles `element` with its boundary comments for the
+  // one shape with no known destination (7b) — everything else returns
+  // the real, single element unchanged.
+  return bareFragment ?? element
+}
+
+/**
+ * Splice `attrs` (e.g. ` data-key="1"`) onto `html`'s first element's own
+ * tag, wherever that tag starts (templates may open with comment markers
+ * like `<!--bf-cond-start:...-->` before the first real element). No-op —
+ * returns `html` unchanged — if no element tag is found at all.
+ */
+/**
+ * A tag name is not `\\w+`: custom elements are required to contain a
+ * hyphen (`<my-widget>`), and `.` and `:` are legal too. Matching only
+ * `[A-Za-z0-9_]` spliced attributes into the MIDDLE of such a name
+ * (`<my bf-s="…"-widget>`), which the parser then drops entirely — while
+ * SSR, which places the same attributes as a compiler-emitted JSX spread,
+ * kept emitting them correctly. Anchored on a leading letter so the
+ * comment markers a template may open with (`<!--bf-cond-start:…-->`) are
+ * still skipped rather than matched.
+ */
+const FIRST_TAG_PATTERN = /<([a-zA-Z][^\s/>]*)/
+const TAG_HEAD_PATTERN = /^(<[a-zA-Z][^\s/>]*)/
+
+function spliceAttrsAfterFirstTag(html: string, attrs: string): string {
+  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}`)
 }
 
 /**
@@ -425,20 +675,38 @@ export function renderChild(
   // `integrations/shared/e2e/toggle.spec.ts` asserts. The def carries the
   // plain name for exactly this — see `ComponentDef.name`, "Used for scope
   // ID generation" (#2518).
-  const displayName = getRegisteredDef(name)?.name ?? name
+  const def = getRegisteredDef(name)
+  const displayName = def?.name ?? name
+  // A genuine fragment-root child (#2722) carries NO `bf-s`/`bf-h`/`bf-m`
+  // element attributes at all — SSR moves them into a wrapping
+  // `<!--bf-scope:-->` comment instead (`wrapWithScopeComment`, hono-
+  // adapter.ts). Below, `isFragmentRoot` skips the attribute-splicing path
+  // entirely and wraps the child's markup in the same comment shape —
+  // otherwise every fragment-root child rendered inline by a PARENT's own
+  // template (as opposed to a fresh top-level `createComponent()` mount,
+  // `materializeComponent`'s equivalent fix) kept stamping `bf-s` onto an
+  // element the SSR/hydrate reference never puts one on.
+  const isFragmentRoot = def?.fragmentRoot === true
   const scopePrefix = (_parentScopeId && slotSuffix)
     ? _parentScopeId
     : `${displayName}_${generateId()}`
+  const scopeId = `${scopePrefix}${suffix}`
   const keyAttr = key !== undefined ? ` ${BF_KEY}="${key}"` : ''
   // Slot-relationship markers — only emitted when both host and slot are
   // known; top-level renders without parent context omit them.
   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>`
+    // No template registered: same empty-shell fallback either way, but a
+    // fragment-root child still gets its comment pair instead of `bf-s` —
+    // an empty `<div></div>` with no scope marker at all would be
+    // unfindable by any later `$c()` lookup.
+    return isFragmentRoot
+      ? `<!--${BF_SCOPE_COMMENT_PREFIX}${scopeId}--><div></div><!--${BF_SCOPE_COMMENT_END_PREFIX}${scopeId}-->`
+      : `<div ${bfsAttr}${slotAttrs}${keyAttr}></div>`
   }
 
   // Push `_parentScopeId` to THIS child's own derived scope while its
@@ -469,9 +737,29 @@ export function renderChild(
     PLACEHOLDER_ATTR_PATTERN,
     _parentScopeId ? ` bf-s="${_parentScopeId}"` : '',
   )
+
+  // Fragment-root child (#2722): wrap the whole rendered markup in the
+  // SSR/hydrate boundary-comment shape instead of splicing `bf-s`/`bf-h`/
+  // `bf-m` into a first element that, structurally, owns none of them —
+  // `wrapWithScopeComment`'s CSR mirror, same as `materializeComponent`'s
+  // fix for a top-level mount.
+  if (isFragmentRoot) {
+    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.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
+    // SSR content to hydrate against).
+    const keyedHtml = keyAttr ? spliceAttrsAfterFirstTag(html, keyAttr) : html
+    return `<!--${BF_SCOPE_COMMENT_PREFIX}${scopeId}${hostSuffix}-->${keyedHtml}<!--${BF_SCOPE_COMMENT_END_PREFIX}${scopeId}-->`
+  }
+
   // Templates may start with comment markers (e.g. <!--bf-cond-start:...-->)
   // so we find the first element tag rather than assuming index 0.
-  const firstElMatch = html.match(/<(\w+)/)
+  const firstElMatch = html.match(FIRST_TAG_PATTERN)
   if (!firstElMatch) return html
   const insertPos = firstElMatch.index!
   // Dedupe `bf-s` only when the template body's root already carries
@@ -484,10 +772,10 @@ export function renderChild(
   if (ROOT_HAS_BFS_PATTERN.test(afterInsert)) {
     if (!extraAttrs) return html
     return html.slice(0, insertPos) +
-      afterInsert.replace(/^(<\w+)/, `$1${extraAttrs}`)
+      afterInsert.replace(TAG_HEAD_PATTERN, `$1${extraAttrs}`)
   }
   return html.slice(0, insertPos) +
-    afterInsert.replace(/^(<\w+)/, `$1 ${bfsAttr}${extraAttrs}`)
+    afterInsert.replace(TAG_HEAD_PATTERN, `$1 ${bfsAttr}${extraAttrs}`)
 }
 
 // The leading `\s+` is part of the match so dropping the attribute
@@ -506,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;'
@@ -686,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 `&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 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
@@ -810,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')
@@ -834,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/hydrate.ts

@@ -422,8 +422,17 @@ function hydrateCommentScope(comment: Comment): void {
 
   commentScopeRegistry.set(proxyEl, { commentNode: comment, scopeId })
 
-  const parsed = parseProps(propsJson || null, `comment scope ${scopeId}`)
-  const props = (parsed[name] ?? {}) as Record<string, unknown>
+  // The JSON is the scope's OWN flat props object, not namespaced under
+  // the component name — `wrapWithScopeComment` (hono-adapter.ts) emits
+  // `__bfPropsJson` verbatim after the `|`, exactly like `hydrateElementScope`
+  // reads `bf-p` directly below with no unwrap step. An earlier `parsed[name]
+  // ?? {}` here assumed a `{ [name]: props }` shape that no emitter ever
+  // produces, so every root fragment scope with props hydrated against an
+  // empty object (#2721) — invisible whenever `currentComponentHasProps` was
+  // false (no props segment emitted at all, so `{}` was already correct),
+  // which is why this survived until the mutation sweep's fragment-wrap
+  // exercised a component that actually depends on its props at hydration.
+  const props = parseProps(propsJson || null, `comment scope ${scopeId}`)
   runInit(proxyEl, def, props)
 }
 

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)