@barefootjs/jsx 0.33.1 → 0.33.2

package/src/ir-to-client-js/emit-registration.ts

@@ -10,6 +10,7 @@ import { PROPS_PARAM } from './utils.ts'
 import { computeInlinability, toLegacyInlinability } from './compute-inlinability.ts'
 import { canGenerateStaticTemplate, irToComponentTemplate, generateCsrTemplate, createStringProtector } from './html-template.ts'
 import { nameForRegistryRef } from './component-scope.ts'
+import { resolveRestSpreadNames } from './prop-handling.ts'
 
 /**
  * Resolve chained references within a constants map.
@@ -191,14 +192,29 @@ export function emitRegistrationAndHydration(
   const propNamesForStaticCheck = new Set(ctx.propsParams.map((p) => p.name))
   const { inlinableConstants, unsafeLocalNames } = inlinability ?? buildInlinableConstants(ctx, graph, _ir.root)
 
-  // Build rest spread names: these are rest/props spreads handled by applyRestAttrs, not spreadAttrs
-  const restSpreadNames = new Set<string>()
-  if (ctx.restPropsName) restSpreadNames.add(ctx.restPropsName)
-  if (ctx.propsObjectName) restSpreadNames.add(ctx.propsObjectName)
+  // Build rest spread names: these are rest/props spreads handled by
+  // applyRestAttrs, not spreadAttrs — #2723: includes any `const x__alias
+  // = x` hop onto the rest/props binding (see `resolveRestSpreadNames`'s
+  // docstring in prop-handling.ts).
+  const restSpreadNames = resolveRestSpreadNames(ctx)
 
-  const isCommentScope = (_ir.root.type === 'fragment'
-    && (_ir.root as IRFragment).needsScopeComment)
-    || _ir.root.type === 'component'
+  // Two distinct shapes share the `comment: true` (proxy-scoped) def flag,
+  // but need OPPOSITE runtime treatment of the def's own scope id
+  // (component.ts's `materializeComponent`, #2722):
+  //   - `root.type === 'fragment'`: a genuine fragment root. Its rendered
+  //     markup carries NO scope id of its own (SSR moves it into the
+  //     wrapping `<!--bf-scope:-->` comment, `wrapWithScopeComment` in
+  //     hono-adapter.ts) — CSR mount must generate one just the same, or
+  //     every nested `renderChild()` call loses the parent-prefixed naming
+  //     `_parentScopeId` provides and falls back to a random per-child id
+  //     (#1627's fallback), diverging from SSR/hydrate.
+  //   - `root.type === 'component'`: the render-prop / "root is a single
+  //     child call" case (#2649). The child's OWN markup already carries
+  //     ITS OWN real scope id — the wrapping comment marks a scope with no
+  //     DOM presence of its own, and `materializeComponent` must leave
+  //     `scopeId` null so it doesn't stamp over (or duplicate) the child's.
+  const isFragmentRoot = _ir.root.type === 'fragment' && !!(_ir.root as IRFragment).needsScopeComment
+  const isCommentScope = isFragmentRoot || _ir.root.type === 'component'
 
   // Build ComponentDef object for hydrate()
   const defParts: string[] = [`init: init${name}`]
@@ -232,6 +248,9 @@ export function emitRegistrationAndHydration(
   if (isCommentScope) {
     defParts.push('comment: true')
   }
+  if (isFragmentRoot) {
+    defParts.push('fragmentRoot: true')
+  }
 
   const registryKey = nameForRegistryRef(name)
   // When the registry key was file-scoped (`Name__<8hex>`, for a

package/src/ir-to-client-js/generate-init.ts

@@ -97,7 +97,7 @@ export function generateInitFunction(
   // into the analyzer / IR construction stage and introduce a
   // `PropRewritten<T>` brand type so missing the rewrite becomes a
   // compile-time error. ---
-  let generatedCode = rewritePropsObjectRef(lines.join('\n'), ctx.propsObjectName)
+  let generatedCode = rewritePropsObjectRef(lines.join('\n'), ctx.propsObjectName, ctx.restPropsName)
   generatedCode += '\n' + hydrateLine
 
   // Substitute module-level declarations BEFORE import detection: a

package/src/ir-to-client-js/html-template.ts

@@ -400,7 +400,7 @@ function renderTemplateAttrPart(
   attr: IRAttribute,
   attrName: string,
   wrap: (expr: string) => string,
-  restSpreadNames?: Set<string>,
+  restSpreadNames?: ReadonlySet<string>,
 ): string {
   const v = attr.value
   switch (v.kind) {
@@ -667,7 +667,7 @@ function stripLeafKeyAttr(ir: IRNode): IRNode {
  */
 export function renderFlatMapClientBody(
   cb: Pick<FlatMapCallback, 'segments'>,
-  restSpreadNames?: Set<string>,
+  restSpreadNames?: ReadonlySet<string>,
 ): string {
   return renderPreamble(cb, {
     textVariant: 'client',
@@ -699,7 +699,7 @@ export function flatMapCallbackHasKeyedLeaf(cb: Pick<FlatMapCallback, 'segments'
  */
 export function renderFlatMapProjectionClientBody(
   inner: Extract<IRNode, { type: 'loop' }>,
-  restSpreadNames?: Set<string>,
+  restSpreadNames?: ReadonlySet<string>,
 ): string {
   const chained = applyLoopChain(inner)
   const params = inner.index ? `(${inner.param}, ${inner.index})` : `(${inner.param})`
@@ -747,7 +747,7 @@ function escapeLeafTextExpressions(ir: IRNode): IRNode {
 // docstring (`ir-to-client-js/utils.ts`) for why this stays outside #2482's
 // migration (it's the client-JS-emitter twin of the Go adapter's
 // `loopBindingStack`).
-export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, loopDepth = 0, loopParams?: ReadonlyArray<string | LoopParamSpec>, branchSlotsVar?: string, inHoistedChildren = false): string {
+export function irToHtmlTemplate(node: IRNode, restSpreadNames?: ReadonlySet<string>, loopDepth = 0, loopParams?: ReadonlyArray<string | LoopParamSpec>, branchSlotsVar?: string, inHoistedChildren = false): string {
   const recurse = (n: IRNode): string => irToHtmlTemplate(n, restSpreadNames, loopDepth, loopParams, branchSlotsVar, inHoistedChildren)
   const wrapExpr = (expr: string) => wrapExprWithLoopParams(expr, loopParams)
   const wrapInterpolation = (expr: string): string => branchSlotsVar
@@ -1373,7 +1373,7 @@ function walkSkeletonPathChildren(
  * elements (`<div data-bf-ph="sN"></div>`) instead of renderChild() calls.
  * The placeholders are replaced with real createComponent() elements at runtime.
  */
-export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: Set<string>, loopDepth = 0, loopParams?: ReadonlyArray<string | LoopParamSpec>): string {
+export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: ReadonlySet<string>, loopDepth = 0, loopParams?: ReadonlyArray<string | LoopParamSpec>): string {
   const recurse = (n: IRNode): string => irToPlaceholderTemplate(n, restSpreadNames, loopDepth, loopParams)
   const wrapExpr = (expr: string) => wrapExprWithLoopParams(expr, loopParams)
 
@@ -1637,7 +1637,7 @@ function isSingleRootElement(html: string): boolean {
  */
 export interface TemplateOptions {
   inlinableConstants?: Map<string, string>
-  restSpreadNames?: Set<string>
+  restSpreadNames?: ReadonlySet<string>
   propsObjectName?: string | null
   /**
    * Names that exist only in the init-body scope (or were demoted to unsafe
@@ -1728,7 +1728,7 @@ export interface TemplateOptions {
 export function irToComponentTemplate(
   node: IRNode,
   inlinableConstants?: Map<string, string>,
-  restSpreadNames?: Set<string>,
+  restSpreadNames?: ReadonlySet<string>,
   propsObjectName?: string | null,
   markupSlotIds?: ReadonlySet<string>
 ): string {
@@ -2133,7 +2133,7 @@ export function generateCsrTemplate(
   node: IRNode,
   inlinableConstants: Map<string, string> | undefined,
   ctx: ClientJsContext,
-  restSpreadNames?: Set<string>,
+  restSpreadNames?: ReadonlySet<string>,
   propsObjectName?: string | null,
   unsafeLocalNames?: Set<string>,
   deferredChildSlots?: ReadonlySet<string>,

package/src/ir-to-client-js/index.ts

@@ -19,6 +19,7 @@ import { PROPS_PARAM } from './utils.ts'
 import { buildInlinableConstants, csrInlinableConstantsFromCtx } from './emit-registration.ts'
 import { buildEnvFromCtx } from './compute-inlinability.ts'
 import { nameForRegistryRef } from './component-scope.ts'
+import { resolveRestSpreadNames } from './prop-handling.ts'
 import { IMPORT_PLACEHOLDER, RUNTIME_MODULE, detectUsedImports, collectExternalImports } from './imports.ts'
 import { isInlinableInTemplate } from '../relocate.ts'
 import { buildSourceMapFromIR, type SourceMapV3 } from './source-map.ts'
@@ -255,10 +256,11 @@ function generateTemplateOnlyMount(ir: ComponentIR, ctx: ClientJsContext): strin
   const graph = buildReferencesGraph(ctx, ir.root)
   const { inlinableConstants, unsafeLocalNames } = buildInlinableConstants(ctx, graph, ir.root)
 
-  // Build rest spread names: these are rest/props spreads handled by applyRestAttrs, not spreadAttrs
-  const restSpreadNames = new Set<string>()
-  if (ctx.restPropsName) restSpreadNames.add(ctx.restPropsName)
-  if (ctx.propsObjectName) restSpreadNames.add(ctx.propsObjectName)
+  // Build rest spread names: these are rest/props spreads handled by
+  // applyRestAttrs, not spreadAttrs — #2723: includes any `const x__alias
+  // = x` hop onto the rest/props binding (see `resolveRestSpreadNames`'s
+  // docstring in prop-handling.ts).
+  const restSpreadNames = resolveRestSpreadNames(ctx)
 
   let templateHtml: string | undefined
 

package/src/ir-to-client-js/prop-handling.ts

@@ -6,6 +6,100 @@ import type { ParamInfo, SignalInfo } from '../types.ts'
 import type { ClientJsContext } from './types.ts'
 import type { BindingScope } from '../scope/binding-scope.ts'
 
+/**
+ * Which of the component's two "forwards the caller's leftover props"
+ * bindings `name` ultimately names — `'rest'` for `ctx.restPropsName`
+ * (the destructured `...rest` binding), `'props'` for `ctx.propsObjectName`
+ * (a whole undestructured `(props)` parameter spread whole), or `null` when
+ * `name` is neither, walking through any bare `const x__alias = <name>`
+ * alias chain to get there (#2723's `alias-props` mutation aliases every
+ * destructured binding, the rest parameter included, e.g.
+ * `const props__alias = props`).
+ *
+ * A `{...spread}` attribute is recognised as "forwards the caller's
+ * leftover props" (routed to the `applyRestAttrs` runtime helper /
+ * excluded from the SSR template's `spreadAttrs({...})` merge, and — only
+ * for the `'rest'` case — given the destructured prop names to exclude
+ * from what it forwards) by comparing its source expression against
+ * exactly `ctx.restPropsName` / `ctx.propsObjectName`. Without this
+ * resolver an alias hop makes that comparison fail even though the spread
+ * still forwards the SAME object — `collect-elements.ts` then never
+ * registers the rest-attrs application at all, and `html-template.ts`'s
+ * merge path stops filtering the spread out, folding it into a
+ * `spreadAttrs({...})` call keyed by the alias name instead of the
+ * runtime-visible one.
+ *
+ * Walks the chain hop by hop (not a precomputed set) so a multi-hop alias
+ * (`const p2 = props; const p3 = p2`) resolves through every link; `visited`
+ * guards a constant cycle (`const a = b; const b = a`) the same way
+ * `free-refs.ts`'s `resolveConstantInitializerRefs` does. A constant whose
+ * value isn't a bare identifier already on the chain (e.g. a real computed
+ * object) stops the walk, so a genuinely different spread expression is
+ * never mistaken for the rest object.
+ */
+export function resolveRestSpreadOrigin(ctx: ClientJsContext, name: string): 'rest' | 'props' | null {
+  const byName = localConstantValues(ctx)
+  const visited = new Set<string>()
+  let current: string | undefined = name.trim()
+  while (current !== undefined && !visited.has(current)) {
+    if (ctx.restPropsName && current === ctx.restPropsName) return 'rest'
+    if (ctx.propsObjectName && current === ctx.propsObjectName) return 'props'
+    visited.add(current)
+    current = byName.get(current)?.trim()
+  }
+  return null
+}
+
+/**
+ * `ctx.localConstants` indexed by name, memoized per `ctx`.
+ *
+ * A `Map` rather than the `.find(` this file's other two constant lookups
+ * use, deliberately: those two are SHADOW-GUARDED lookups that
+ * `binding-scope-ratchet.test.ts` deliberately counts, and that ledger is
+ * shrink-only and at its floor. Resolving an alias chain hop-by-hop would
+ * have added a third counted use — and a hot one, since the walk queries
+ * once per hop — so it indexes instead, which is both outside the ledger's
+ * concern and cheaper than a linear scan per hop.
+ */
+const _localConstantValuesCache: WeakMap<ClientJsContext, ReadonlyMap<string, string | undefined>> = new WeakMap()
+
+function localConstantValues(ctx: ClientJsContext): ReadonlyMap<string, string | undefined> {
+  const cached = _localConstantValuesCache.get(ctx)
+  if (cached) return cached
+  const byName = new Map<string, string | undefined>()
+  for (const constant of ctx.localConstants) {
+    if (!byName.has(constant.name)) byName.set(constant.name, constant.value)
+  }
+  _localConstantValuesCache.set(ctx, byName)
+  return byName
+}
+
+/**
+ * Every name that resolves (via `resolveRestSpreadOrigin`) to either of the
+ * component's "forwards the caller's leftover props" bindings — used where
+ * callers need SET membership (`restSpreadNames?.has(...)` in
+ * `html-template.ts`) rather than a per-name resolution. Memoized per
+ * `ctx` (`WeakMap`, mirroring `free-refs.ts`'s `_bindingMapCache`) since
+ * some callers build this once per component and query it while walking
+ * the whole tree.
+ */
+const _restSpreadNamesCache: WeakMap<ClientJsContext, ReadonlySet<string>> = new WeakMap()
+
+export function resolveRestSpreadNames(ctx: ClientJsContext): ReadonlySet<string> {
+  const cached = _restSpreadNamesCache.get(ctx)
+  if (cached) return cached
+
+  const names = new Set<string>()
+  if (ctx.restPropsName) names.add(ctx.restPropsName)
+  if (ctx.propsObjectName) names.add(ctx.propsObjectName)
+  for (const constant of ctx.localConstants) {
+    if (resolveRestSpreadOrigin(ctx, constant.name) !== null) names.add(constant.name)
+  }
+
+  _restSpreadNamesCache.set(ctx, names)
+  return names
+}
+
 /**
  * Expand dynamic prop value by resolving local constants.
  *

package/src/ir-to-client-js/reactivity.ts

@@ -174,11 +174,30 @@ export function decideWrapForChildProp(
  * The signal-getter and memo regexes (`\b<name>\s*\(`) still run against
  * the raw string — those are call-shape patterns, not bare-identifier
  * checks, and are outside the scope of #1267.
+ *
+ * A reference that only reaches a signal/memo/prop through an intervening
+ * `const x__alias = x` hop is walked via `ctx.localConstants` below (#2723)
+ * — see that block's own comment for why this lives here rather than on
+ * `BindingScope` or a new tracking structure.
  */
 export function needsEffectWrapper(
   expr: string,
   ctx: ClientJsContext,
   freeIdentifiers?: ReadonlySet<string>,
+): boolean {
+  return needsEffectWrapperCore(expr, ctx, freeIdentifiers, new Set())
+}
+
+/**
+ * `needsEffectWrapper`'s actual body, with a `visitedConstants` accumulator
+ * threaded through the local-constant recursion below so a cycle
+ * (`const a = b; const b = a`) terminates instead of looping forever.
+ */
+function needsEffectWrapperCore(
+  expr: string,
+  ctx: ClientJsContext,
+  freeIdentifiers: ReadonlySet<string> | undefined,
+  visitedConstants: Set<string>,
 ): boolean {
   for (const signal of ctx.signals) {
     if (identifierCallPattern(signal.getter).test(expr)) {
@@ -209,6 +228,46 @@ export function needsEffectWrapper(
     if (propsAccess.test(expr)) return true
   }
 
+  // #2723: a bare `const x__alias = x` hop between a destructured prop and
+  // its use site breaks every check above — `expr` (or its precomputed
+  // `freeIdentifiers`) names the ALIAS, never the prop it stands for, so
+  // none of the direct prop/signal/memo checks fire even though the value
+  // is exactly as reactive as `x` itself. Phase 1's `isReactiveExpression`
+  // already sees through this (`isPropsReference` / `isSignalOrMemoReference`
+  // in jsx-to-ir.ts recursively walk `ctx.patterns.constants`, the
+  // `TransformContext` twin of this function's `ctx.localConstants`) —
+  // this is that SAME constant-chain walk, ported onto Phase 2's string
+  // expression so its independent wrap decision agrees with Phase 1's
+  // `hasReactiveAttributes` slotId decision instead of silently
+  // disagreeing on whether the attribute gets a `createEffect` at all.
+  //
+  // This is NOT loop/callback binding resolution — `BindingScope` (#2482)
+  // answers "what name is this loop row's own item/index/destructure
+  // binding," a question with no bearing on a component-body `const`
+  // aliasing a prop — so it does not belong there. It also isn't a new ad
+  // hoc tracking structure: `ctx.localConstants` is the existing per-
+  // component constant list this file already reads (see
+  // `expandConstantForReactivity` above), walked here with a `visited`
+  // guard for the same reason `free-refs.ts`'s `resolveConstantInitializerRefs`
+  // carries one — a constant cycle must terminate, not loop forever.
+  //
+  // Constants whose initializer contains an arrow/function expression are
+  // skipped, mirroring `resolveConstantInitializerRefs`'s `containsArrow`
+  // skip: refs inside a function body run when (and if) the function is
+  // invoked, not merely because something reads the bare function value.
+  for (const constant of ctx.localConstants) {
+    if (visitedConstants.has(constant.name)) continue
+    if (constant.value === undefined || constant.containsArrow) continue
+    const referenced = freeIdentifiers
+      ? freeIdentifiers.has(constant.name)
+      : tokenContainsIdent(expr, constant.name)
+    if (!referenced) continue
+    visitedConstants.add(constant.name)
+    if (needsEffectWrapperCore(constant.value, ctx, constant.freeIdentifiers, visitedConstants)) {
+      return true
+    }
+  }
+
   return false
 }
 

package/src/ir-to-client-js/rewrite-props-object.ts

@@ -1,7 +1,8 @@
 /**
- * AST-based rename of the source-level props object name (e.g. `props`
- * or a user-supplied destructure name) → the generated parameter name
- * `_p` across the joined init-body string.
+ * AST-based rename of the source-level props object name(s) (e.g. `props`,
+ * a user-supplied destructure name, or a destructured rest binding like
+ * `...rest`) → the generated parameter name `_p` across the joined
+ * init-body string.
  *
  * Replaces the pre-C2 regex hack `\\b<propsObjectName>\\b` which silently
  * matched contexts that should NOT have been rewritten:
@@ -27,15 +28,54 @@ import { PROPS_PARAM } from './utils.ts'
 import { identifierPattern } from '../identifier-pattern.ts'
 
 /**
- * Rename every value-position reference to `propsObjectName` in `code`
- * to `_p`. No-op when `propsObjectName` is null (destructured-prop mode
- * — the analyzer already pre-rewrites bare prop refs into `templateXxx`
- * fields) or already equals `_p`.
+ * Rename every value-position reference to `propsObjectName` — and,
+ * independently, to `restPropsName` (#2723) — in `code` to `_p`.
+ *
+ * `restPropsName` matters even in destructured-prop mode (where
+ * `propsObjectName` is null and the analyzer already pre-rewrites bare
+ * NAMED-prop refs into `templateXxx` fields, per the historical
+ * `propsObjectName ?? 'props'` fallback this replaces): a destructured
+ * rest binding (`const { className, ...rest } = props` /
+ * `function F({ className, ...rest })`) is not itself a "named prop," so
+ * nothing pre-rewrites a bare reference to it. Such a reference reaches
+ * this pass whenever the init body needs `rest`'s OWN VALUE rather than
+ * just recognising a `{...rest}` spread by name — e.g. a `const
+ * rest__alias = rest` hop (#2723's `alias-props` mutation aliases the
+ * rest parameter along with every named one). A rest binding named
+ * anything but "props" (`...rest`, `...leftover`) left such a reference
+ * dangling as a `ReferenceError`, so the analyzer's actual
+ * `restPropsName` is passed in to remove that guesswork.
+ *
+ * The `propsObjectName ?? 'props'` fallback is KEPT alongside it, not
+ * replaced by it. The two do different jobs, and reading the fallback as
+ * merely a lucky guess at the rest binding's name regressed the
+ * doc-example `StatementExample`: a component that destructures its
+ * parameters can still write `props.itemId` inside a handler body, and
+ * `propsObjectName` is null for exactly that shape — so dropping the
+ * fallback left `props.itemId` in the emitted init, where no `props`
+ * binding exists to satisfy it.
+ *
+ * Each candidate name is rewritten independently and skipped when null,
+ * already `_p`, or a duplicate of one already processed (a component
+ * whose props param IS its own rest destructure target, if that shape
+ * ever arises, would otherwise walk the AST twice for the same name).
  */
-export function rewritePropsObjectRef(code: string, propsObjectName: string | null): string {
-  const srcPropsName = propsObjectName ?? 'props'
-  if (srcPropsName === PROPS_PARAM) return code
+export function rewritePropsObjectRef(
+  code: string,
+  propsObjectName: string | null,
+  restPropsName: string | null = null,
+): string {
+  let result = code
+  const seen = new Set<string>()
+  for (const srcPropsName of [propsObjectName ?? 'props', restPropsName]) {
+    if (srcPropsName === null || srcPropsName === PROPS_PARAM || seen.has(srcPropsName)) continue
+    seen.add(srcPropsName)
+    result = rewriteOneName(result, srcPropsName)
+  }
+  return result
+}
 
+function rewriteOneName(code: string, srcPropsName: string): string {
   // Quick exit when the name doesn't appear at all.
   if (!identifierPattern(srcPropsName).test(code)) return code
 

package/src/jsx-to-ir.ts

@@ -1944,6 +1944,52 @@ function unwrapHoistedFragment(node: IRNode): IRNode {
   return { ...only, needsScope: true }
 }
 
+// #2732: a `needsScopeComment` fragment's five hydration markers move to
+// the wrapping comment, but `data-key` needs to stay on an element (see
+// `IRElement.carriesDataKey`'s docstring for why). Mark the first ELEMENT
+// among `children` — immutably (`{ ...el, carriesDataKey: true }`), matching
+// the rest of this file's post-hoc IR tagging (e.g. `unwrapHoistedFragment`)
+// rather than mutating the child in place.
+function markDataKeyCarrier(children: IRNode[]): IRNode[] {
+  for (let i = 0; i < children.length; i++) {
+    const marked = markCarrierIn(children[i])
+    if (!marked) continue
+    const out = children.slice()
+    out[i] = marked
+    return out
+  }
+  return children
+}
+
+/**
+ * The marked copy of `node` if this subtree can render an element in first
+ * position, or null if it cannot.
+ *
+ * Descends through `conditional` because a fragment whose only top-level
+ * child is a ternary or `&&` is still a single-visual-root row —
+ * `{done ? <li class="done"/> : <li/>}` renders exactly one `<li>`. A flat
+ * `children.findIndex(c => c.type === 'element')` returns -1 there and
+ * silently reproduces #2732's own symptom for a shape the fix was supposed
+ * to cover.
+ *
+ * BOTH branches are marked, not just one: they are mutually exclusive at
+ * render time, so whichever is taken carries the key, and marking only
+ * `whenTrue` would drop it exactly when the condition is false.
+ */
+function markCarrierIn(node: IRNode): IRNode | null {
+  if (node.type === 'element') {
+    return { ...(node as IRElement), carriesDataKey: true }
+  }
+  if (node.type === 'conditional') {
+    const cond = node as IRConditional
+    const whenTrue = markCarrierIn(cond.whenTrue)
+    const whenFalse = markCarrierIn(cond.whenFalse)
+    if (!whenTrue && !whenFalse) return null
+    return { ...cond, whenTrue: whenTrue ?? cond.whenTrue, whenFalse: whenFalse ?? cond.whenFalse }
+  }
+  return null
+}
+
 function transformFragment(
   node: ts.JsxFragment,
   ctx: TransformContext
@@ -1968,7 +2014,7 @@ function transformFragment(
 
   return {
     type: 'fragment',
-    children,
+    children: needsScopeComment ? markDataKeyCarrier(children) : children,
     transparent: isTransparent || undefined,
     needsScopeComment,
     loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),

package/src/types.ts

@@ -347,6 +347,20 @@ export interface IRElement {
   children: IRNode[]
   slotId: string | null
   needsScope: boolean
+  /**
+   * Set on the first ELEMENT among a `needsScopeComment` fragment root's own
+   * top-level children (#2732) — the fragment's five hydration markers
+   * (`bf-s`/`bf-h`/`bf-m`/`bf-r`/`bf-p`) move to the wrapping
+   * `<!--bf-scope:...-->` comment instead of an element attribute, but
+   * `data-key` has to stay on an element because the client runtime's
+   * `mapArray` adopt loop reads it as a DOM attribute
+   * (`primaryEl.dataset.key`, map-array.ts). "First element, not first
+   * node" mirrors the CSR runtime's own resolution of the identical
+   * ambiguity (`component.ts`'s `roots.find(isElement)`, #2735) rather than
+   * inventing a second answer. Always `undefined` when `needsScope` is
+   * true — the two are mutually exclusive ways of carrying the same key.
+   */
+  carriesDataKey?: boolean
   /**
    * Page-lifecycle boundary id for an element lowered from `<Region>`
    * (spec/router.md). Set only on region host elements; adapters emit it as