@barefootjs/jsx 0.33.2 → 0.33.4

package/src/ir-to-client-js/control-flow/stringify/component-loop.ts

@@ -49,11 +49,18 @@ export function stringifyComponentLoop(lines: string[], plan: ComponentLoopPlan)
     nestedComps,
     childConditionalEffects,
     profileLoopId,
+    mapPreambleWrapped,
   } = plan
 
   const loopBfId = profileLoopId ? `, ${JSON.stringify(profileLoopId)}` : ''
   lines.push(`  mapArray(() => ${arrayExpr}, ${containerVar}, ${keyFn}, (${paramHead}, ${indexParam}, __existing) => {`)
   if (paramUnwrap) lines.push(`    ${paramUnwrap}`)
+  // The preamble's consts are referenced by componentPropsExpr's getters
+  // below, in BOTH the `initChild` (hydration-reuse) and `createComponent`
+  // (fresh row) branches — a row rebuild and a hydration-reused row must
+  // read the same preamble-computed value, so it can't be hoisted into only
+  // one branch.
+  if (mapPreambleWrapped) lines.push(`    ${mapPreambleWrapped}`)
 
   const scopedComp = nameForRegistryRef(componentName)
 

package/src/ir-to-client-js/control-flow/stringify/inner-loop.ts

@@ -31,7 +31,7 @@
  *     <indent>}) }
  */
 
-import { keyAttrName, profileBindingId, varSlotId } from '../../utils.ts'
+import { keyAttrName, mapArrayKeyArgs, profileBindingId, varSlotId } from '../../utils.ts'
 import { emitComponentAndEventSetup } from '../shared.ts'
 import { emitAttrUpdate } from '../../emit-reactive.ts'
 import { emitMultiRootTemplateCloneLines, namespaceWrapForTemplate } from './template-parse.ts'
@@ -157,7 +157,11 @@ function emitReactive(lines: string[], inner: InnerLoopPlan, indent: string, pc:
     bodyIsMultiRoot: emit.bodyIsMultiRoot,
   })
   lines.push(`${indent}  return __innerEl${uid}`)
-  lines.push(`${indent}}, '${inner.markerId}'${profileBindingId(pc, inner.slotId)}) }`)
+  // #2753 Shape B: the runtime's own fallback stamp (a row whose renderItem
+  // didn't already set a key attribute — see `map-array.ts`) has no depth
+  // concept, so a nested keyed loop must tell it which name to check/write
+  // instead of the default `data-key`.
+  lines.push(`${indent}}, '${inner.markerId}'${mapArrayKeyArgs(profileBindingId(pc, inner.slotId), !!emit.wrappedKey, inner.keyDepth)}) }`)
 }
 
 function emitStatic(lines: string[], inner: InnerLoopPlan, indent: string, pc: string | undefined): void {

package/src/ir-to-client-js/control-flow/stringify/loop-child-arm.ts

@@ -11,7 +11,7 @@
  * every nesting depth.
  */
 
-import { varSlotId, DATA_BF_PH, keyAttrName, profileBindingId } from '../../utils.ts'
+import { varSlotId, DATA_BF_PH, keyAttrName, mapArrayKeyArgs, profileBindingId } from '../../utils.ts'
 import { emitComponentAndEventSetup } from '../shared.ts'
 import { emitAttrUpdate } from '../../emit-reactive.ts'
 import { namespaceWrapForTemplate } from './template-parse.ts'
@@ -180,7 +180,10 @@ export function stringifyBranchInnerLoops(
       stringifyLoopChildConditionals(lines, inner.nestedConditionals, `${indent}  `, pc)
     }
     lines.push(`${indent}  return __bel${uid}`)
-    lines.push(`${indent}}, '${inner.markerId}'${profileBindingId(pc, inner.slotId)}) }`)
+    // #2753 Shape B: see the identical comment in `inner-loop.ts` —
+    // `keyDepth` is always 1 for a branch-arm inner loop, so this only ever
+    // widens the trailing args when the loop is also keyed.
+    lines.push(`${indent}}, '${inner.markerId}'${mapArrayKeyArgs(profileBindingId(pc, inner.slotId), !!inner.wrappedKey, inner.keyDepth)}) }`)
   }
 }
 

package/src/ir-to-client-js/control-flow.ts

@@ -86,6 +86,18 @@ export function emitLoopUpdates(lines: string[], ctx: ClientJsContext, unsafeLoc
       !(elem.preamble && elem.preamble.builderNames.length > 0 && plan.rowConstruction === 'dom-ops'),
       `loop variant '${plan.kind}' declares dom-ops row construction but received a JSX-bearing preamble — add a Phase-1 refusal (or wire renderPreamble support) for this shape`,
     )
+    // #2797's hole, generalized: a JS-only preamble (no JSX leaf, so the
+    // check above doesn't fire) can still be silently dropped if a variant
+    // just never reads `elem.preamble` at all — which is exactly what
+    // happened to the 'component' variant before it grew
+    // `mapPreambleWrapped`. A variant that doesn't declare that field can't
+    // be checked here (nothing to read), so this only catches a variant
+    // that declares it but leaves it unpopulated for a preamble that has
+    // names to declare.
+    internalInvariant(
+      !(elem.preamble && elem.preamble.declaredNames.length > 0 && 'mapPreambleWrapped' in plan && plan.mapPreambleWrapped === ''),
+      `loop variant '${plan.kind}' has a preamble with declared names (${elem.preamble?.declaredNames.join(', ')}) but its plan's mapPreambleWrapped is empty — wire it up or the emitted call site references a name nothing declares`,
+    )
     stringifyLoop(lines, plan)
     emitLoopEventDelegation(lines, elem, plan.kind, ctx.profile ? ctx.componentName : undefined)
   }

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

@@ -2,7 +2,7 @@
  * IR → HTML template string generation and validation.
  */
 
-import type { AttrValue, FlatMapCallback, IRAttribute, IRNode, IRProp, MapCallbackPreamble } from '../types.ts'
+import type { AttrValue, FlatMapCallback, IRAttribute, IRElement, IRExpression, IRNode, IRProp, MapCallbackPreamble } from '../types.ts'
 import { isBooleanAttr } from '../html-constants.ts'
 import { toHtmlAttrName, attrValueToString, quotePropName, PROPS_PARAM, DATA_BF_PH, keyAttrName, loopStartMarker, loopEndMarker, loopItemMarker, freeIdsFromRefs, setIntersects, wrapExprWithLoopParams } from './utils.ts'
 import type { LoopParamSpec } from './utils.ts'
@@ -319,6 +319,16 @@ function escapeAttrValueExpr(valExpr: string): string {
  * bytes. Bare `${...}` interpolations — `{children}` passthrough and
  * `renderChild(...)` output — are pre-rendered HTML and must NOT be
  * escaped, so this is applied only at the four text-marker emit sites.
+ * The no-`slotId` fallthrough (every `case 'expression'` branch's final
+ * `return` in this file) is shared by several unrelated shapes besides
+ * `{children}` passthrough — an `escapeLeafTextExpressions`-wrapped
+ * preamble leaf, `lowerFormControlValueSsr`'s textarea initial value, an
+ * inlined constant, a `''`/`undefined` deferred placeholder — every one of
+ * which is either already escaped or a literal, and must reach the
+ * template untouched. `bareSpliceExpr` below is that branch's single door
+ * — the one place the fallthrough's decision is made — and it is what
+ * picks the genuine `{children}` reference back out for `markupOrEmpty`'s
+ * nullish guard (#2775); see its own docstring.
  * Hono escapes text content with the same set as attribute values
  * (`& " ' < >`), so `escapeText` delegates to the same operation.
  *
@@ -339,6 +349,73 @@ function escapeTextSlotExpr(innerExpr: string, isMarkup = false): string {
   return `${isMarkup ? 'escapeTextOrMarkup' : 'escapeText'}(${innerExpr})`
 }
 
+/**
+ * Recognizes a JSX child-position expression that is exactly a reference to
+ * the reserved `children` prop — bare `children` (destructured) or
+ * `<receiver>.children` for any single-identifier receiver (`props.children`,
+ * a custom props-param name, a loop-scoped alias closing over props, ...).
+ * Checked against `node.expr` — the ORIGINAL source text, never a
+ * transformed/wrapped form — so it stays accurate regardless of which
+ * builder is asking, and regardless of any earlier pass
+ * (`escapeLeafTextExpressions`, `lowerFormControlValueSsr`) that may have
+ * wrapped an unrelated leaf.
+ *
+ * Deliberately LOOSER than `isTransparentFragment` (`jsx-to-ir.ts`), which
+ * answers the same underlying question one level up. That function runs on
+ * the TS AST and compares the expression text against an EXACT set —
+ * `children`, `props.children`, and the analyzer-resolved
+ * `${ctx.analyzer.propsObjectName}.children`. This layer works on IR and has
+ * no analyzer, so the resolved props name is not reachable here; matching any
+ * single-identifier receiver is the available approximation, chosen — not an
+ * inherited convention.
+ *
+ * The looseness costs nothing measurable. An unrelated `.children` member —
+ * a tree node's own `children` array, say — does not even arrive here: a
+ * reactive member expression is given a `slotId` and takes the escaped
+ * text-slot branch above, so it never reaches the bare-splice fallthrough
+ * this gates. And were one to arrive, the outcome is still benign: the
+ * branch never escaped its value either way, a non-nullish value is
+ * returned untouched, and a nullish one rendering `''` instead of the
+ * literal `"undefined"` is an improvement in its own right.
+ *
+ * Both the ORIGINAL source text and the RESOLVED expression are tested,
+ * because either one alone misses a shape. `node.expr` is the only form
+ * that does not vary between the four builders, so it stays the primary
+ * test; but it is the pre-substitution text, which for a
+ * destructured-and-renamed children (`const { children: kids } = props`)
+ * reads `kids` and matches nothing — while the resolved expression the
+ * emitter is about to splice already reads `(_p.children)`. Testing both
+ * closes that (#2786) without giving up `node.expr`'s stability.
+ */
+function isChildrenPassthroughExpr(expr: string): boolean {
+  return /^([A-Za-z_$][\w$]*\.)?children$/.test(expr.trim())
+}
+
+/**
+ * The single door for the bare (no-`slotId`) expression splice — the
+ * counterpart to `escapeTextSlotExpr` for the branch that must NOT escape.
+ * All four `case 'expression'` builders in this file route through here so
+ * this decision exists in exactly one place: four copies that agree today
+ * are four that can drift apart tomorrow, and this file is where that has
+ * already happened (#2753 -> #2762).
+ *
+ * Only a genuine `{children}` passthrough gets `markupOrEmpty`'s nullish
+ * guard (#2775). Everything else this fallthrough hosts — an
+ * `escapeLeafTextExpressions`-wrapped preamble leaf,
+ * `lowerFormControlValueSsr`'s textarea initial value, an inlined constant,
+ * a `''`/`undefined` deferred placeholder — reaches the template exactly as
+ * it arrived, already escaped or a literal. Escaping is never correct here:
+ * the value is pre-rendered HTML, per `escapeTextSlotExpr`'s docstring.
+ */
+function bareSpliceExpr(node: IRExpression, valueExpr: string): string {
+  // Strip the parens the emitter wraps a substituted expression in, so the
+  // resolved form is comparable to the bare source text.
+  const resolved = valueExpr.trim().replace(/^\(+|\)+$/g, '')
+  const isChildren =
+    isChildrenPassthroughExpr(node.expr) || isChildrenPassthroughExpr(resolved)
+  return !node.joinArrayChild && isChildren ? `markupOrEmpty(${valueExpr})` : valueExpr
+}
+
 /**
  * `dangerouslySetInnerHTML={{ __html: E }}` makes the element's content its
  * raw innerHTML — the intentional, React-style escape hatch. Returns the
@@ -470,6 +547,25 @@ export interface MergeContext {
   honorClientOnly: boolean
 }
 
+/**
+ * The client-template twin of `IRElement.keyAttr`'s SSR-side decision
+ * (`jsx-to-ir.ts`'s `extractLoopKey`/`applyLoopKeyAttr`) — #2763. A raw
+ * `key={}` JSX attribute survives on `.attrs` regardless of whether the
+ * loop/relay actually recognized it as a row key (a fragment-bodied loop
+ * row before #2763's fix, or heterogeneous keys across conditional
+ * branches) — baking `data-key` from the mere presence of that attribute
+ * would disagree with every SSR adapter, which all gate on `keyAttr`
+ * instead. Returns the resolved attribute name only when `node.keyAttr` is
+ * actually set; `null` otherwise, so the caller drops the raw `key`
+ * attribute entirely rather than emitting a `data-key` no SSR adapter
+ * agrees with. `keyAttr.name` and `keyAttrName(loopDepth)` are already the
+ * same value (both derive from `@barefootjs/shared`'s `keyAttrName`, see
+ * `IRElement.keyAttr`'s docstring) — this only decides WHETHER to use it.
+ */
+function resolvedKeyAttrName(node: IRElement, loopDepth: number): string | null {
+  return node.keyAttr ? keyAttrName(loopDepth) : null
+}
+
 /** Return true if this attribute should participate in the merge object. */
 function isMergeableAttr(a: IRAttribute, ctx: MergeContext): boolean {
   if (ctx.honorClientOnly && a.clientOnly) return false
@@ -757,13 +853,21 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: ReadonlySet<str
   switch (node.type) {
     case 'element': {
       // Merge context shared with `irToComponentTemplate` /
-      // `generateCsrTemplate`. `irToHtmlTemplate` does not honour
-      // `clientOnly` (templates here are for conditionals / loops only),
-      // and its spread rest-name detector uses `v.expr` directly (no
-      // `templateExpr` fallback — those live on the SSR template path).
+      // `generateCsrTemplate`. Its spread rest-name detector uses
+      // `v.expr` directly (no `templateExpr` fallback — those live on
+      // the SSR template path).
+      //
+      // Why not path-local `clientOnly`: this builder emits the row /
+      // branch markup that a freshly built row gets, while a row REUSED
+      // by hydration carries the SSR adapter's markup instead. So the
+      // two representations must agree, and `clientOnly` ("SSR omits it;
+      // the effect owns it") is the same statement on both sides. Baking
+      // the attribute in here made a rebuilt row carry an attribute an
+      // SSR-reused row never has — visible the moment a row-count change
+      // makes reused and rebuilt rows coexist in one list (#2756).
       const mergeCtx: MergeContext = {
         isFilteredSpread: (v) => !!restSpreadNames?.has(v.expr),
-        honorClientOnly: false,
+        honorClientOnly: true,
       }
       const useMerge = shouldUseSpreadAttrsMerge(node.attrs, mergeCtx)
       const firstMergeableIdx = useMerge
@@ -780,15 +884,22 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: ReadonlySet<str
 
       const attrParts = node.attrs
         .map((a, idx) => {
+          // Deferred to the row's own `createEffect`, which the loop-row
+          // reactive-attr collector already registers for every
+          // `clientOnly` attr (`collect-elements.ts`). Emitting it here
+          // too would be redundant on a rebuilt row and absent on a
+          // hydrate-reused one (#2756).
+          if (a.clientOnly) return ''
           if (useMerge && isMergeableAttr(a, mergeCtx)) {
             // Only the first mergeable attr emits the merge call; the
             // others are already represented inside the merge object.
             return idx === firstMergeableIdx ? mergeCall! : ''
           }
-          const attrName = a.name === '...'
-            ? '...'
-            : (a.name === 'key' ? keyAttrName(loopDepth) : toHtmlAttrName(a.name))
-          return renderTemplateAttrPart(a, attrName, wrapExpr, restSpreadNames)
+          if (a.name === 'key') {
+            const attrName = resolvedKeyAttrName(node, loopDepth)
+            return attrName ? renderTemplateAttrPart(a, attrName, wrapExpr, restSpreadNames) : ''
+          }
+          return renderTemplateAttrPart(a, toHtmlAttrName(a.name), wrapExpr, restSpreadNames)
         })
         .filter(Boolean)
 
@@ -853,11 +964,19 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: ReadonlySet<str
       // separate rather than collapsed into a shared helper precisely
       // because their `clientOnly` semantics differ — see that function's
       // own comment (#2617).
+
+      // Escape only when the IR says so (`escapeInClientTemplate`) — most
+      // `${...}` here is already pre-rendered HTML. Never take
+      // `templateExpr` wholesale instead: it rebinds to `_p.xxx`, dropping
+      // the `?? {}` prop-defaulting guard in this builder's init scope
+      // (`client-js-generation.test.ts`).
+      const escapeForClient = (e: string): string =>
+        node.escapeInClientTemplate ? `escapeText(${e})` : e
       if (node.markerless) {
-        const bare = wrapInterpolation(wrapExpr(node.expr))
+        const bare = escapeForClient(wrapInterpolation(wrapExpr(node.expr)))
         return `\${${bare}}`
       }
-      const inner = wrapInterpolation(wrapExpr(node.expr))
+      const inner = escapeForClient(wrapInterpolation(wrapExpr(node.expr)))
       // Stage 3 / D4 — an element-array child ({out}) built by an arbitrary
       // .map() preamble is an array of HTML strings; join it rather than let
       // `${[...]}` `String`-comma-collapse it. Only reached on a JS-runtime
@@ -876,7 +995,8 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: ReadonlySet<str
         const slotted = branchSlotsVar || node.joinArrayChild ? valueExpr : escapeTextSlotExpr(valueExpr)
         return `<!--bf:${node.slotId}-->\${${slotted}}<!--/-->`
       }
-      return `\${${valueExpr}}`
+      // Bare-splice fallthrough (no `slotId`, not an array-child join).
+      return `\${${bareSpliceExpr(node, valueExpr)}}`
     }
 
     case 'conditional': {
@@ -1089,7 +1209,9 @@ export function buildLoopSkeletonTemplate(node: IRNode, safe: LoopSkeletonSafeSl
         if (a.name === '...') return null
         if (a.name === 'dangerouslySetInnerHTML') return null
         if (a.name === 'key') {
-          attrParts.push(`${keyAttrName(0)}=""`)
+          if (resolvedKeyAttrName(node, 0)) {
+            attrParts.push(`${keyAttrName(0)}=""`)
+          }
           continue
         }
         const v = a.value
@@ -1381,9 +1503,15 @@ export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: Readonly
     case 'element': {
       const attrParts = node.attrs
         .map((a) => {
-          const attrName = a.name === '...'
-            ? '...'
-            : (a.name === 'key' ? keyAttrName(loopDepth) : toHtmlAttrName(a.name))
+          // Same deferral as `irToHtmlTemplate` — this builder is the
+          // composite-row twin of it, so a row it builds must carry the
+          // same attributes a hydration-reused row does (#2756).
+          if (a.clientOnly) return ''
+          if (a.name === 'key') {
+            const attrName = resolvedKeyAttrName(node, loopDepth)
+            return attrName ? renderTemplateAttrPart(a, attrName, wrapExpr, restSpreadNames) : ''
+          }
+          const attrName = a.name === '...' ? '...' : toHtmlAttrName(a.name)
           return renderTemplateAttrPart(a, attrName, wrapExpr, restSpreadNames)
         })
         .filter(Boolean)
@@ -1416,7 +1544,11 @@ export function irToPlaceholderTemplate(node: IRNode, restSpreadNames?: Readonly
       if (node.slotId) {
         return `<!--bf:${node.slotId}-->\${${node.joinArrayChild ? value : escapeTextSlotExpr(wrapped)}}<!--/-->`
       }
-      return `\${${value}}`
+      // Bare-splice fallthrough (no `slotId`) — this builder's composite-row
+      // twin of `irToHtmlTemplate`'s `escapeForClient`, same "why not
+      // templateExpr" reasoning (#2765).
+      const spliced = bareSpliceExpr(node, value)
+      return `\${${node.escapeInClientTemplate ? `escapeText(${spliced})` : spliced}}`
     }
 
     case 'conditional': {
@@ -1903,7 +2035,8 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
         const isMarkup = opts.markupSlotIds?.has(node.slotId) ?? false
         return `<!--bf:${node.slotId}-->\${${node.joinArrayChild ? value : escapeTextSlotExpr(wrapped, isMarkup)}}<!--/-->`
       }
-      return `\${${value}}`
+      // Bare-splice fallthrough (no `slotId`).
+      return `\${${bareSpliceExpr(node, value)}}`
     }
 
     case 'conditional': {
@@ -2441,9 +2574,26 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
             if (mergeCtx.isFilteredSpread(v)) return ''
             return `\${spreadAttrs(${transformExpr(v.expr, v.templateExpr)})}`
           }
-          const attrName = a.name === 'key'
-            ? keyAttrName(loopDepth)
-            : toHtmlAttrName(a.name)
+          if (a.name === 'key') {
+            const keyName = resolvedKeyAttrName(node, loopDepth)
+            if (!keyName) return ''
+            switch (v.kind) {
+              case 'boolean-attr':
+                return keyName
+              case 'literal':
+                return `${keyName}="${escapeHtml(v.value)}"`
+              case 'expression':
+                return templateAttrExpr(keyName, transformExpr(v.expr, v.templateExpr), v.presenceOrUndefined)
+              case 'template': {
+                const valueStr = attrValueToString(v, { useTemplate: true })
+                return valueStr ? templateAttrExpr(keyName, transformExpr(valueStr)) : ''
+              }
+              case 'boolean-shorthand':
+              case 'jsx-children':
+                return ''
+            }
+          }
+          const attrName = toHtmlAttrName(a.name)
           switch (v.kind) {
             case 'boolean-attr':
               return attrName
@@ -2527,7 +2677,8 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
           const isMarkup = opts.markupSlotIds?.has(node.slotId) ?? false
           return `<!--bf:${node.slotId}-->\${${node.joinArrayChild ? value : escapeTextSlotExpr(expr, isMarkup)}}<!--/-->`
         }
-        return `\${${value}}`
+        // Bare-splice fallthrough (no `slotId`).
+        return `\${${bareSpliceExpr(node, value)}}`
       }
 
     case 'conditional': {

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

@@ -2,6 +2,7 @@
  * Import detection and DOM import management.
  */
 
+import ts from 'typescript'
 import type { ComponentIR, IRNode } from '../types.ts'
 import { isClientBuiltinName } from '../builtins.ts'
 import { collectValueReferencedNames } from '../value-references.ts'
@@ -29,6 +30,9 @@ export const RUNTIME_IMPORT_CANDIDATES = [
   // the compiler-built HTML at the producer (renderChild / initChild props);
   // `escapeTextOrMarkup` unwraps it at the claim-plan-'markup' template slot.
   'bfMarkup', 'escapeTextOrMarkup',
+  // Nullish guard for a bare `{children}` passthrough splice (#2775) — the
+  // value is already-stringified markup, never escaped, just nullish-safe.
+  'markupOrEmpty',
   'qsa', 'qsaItem', 'qsaChildScope', 'qsaChildScopes', 'upsertChildItem', '__slot', '__bfSlot', '__bfText',
   // Claim-plan interpreter (slot unification A2/A3, spec/slot-unification.md)
   // — the "one claim mechanism" that replaced `patchSlotRange` and
@@ -148,6 +152,168 @@ export function makeValueUsageTest(generatedCode: string): (localName: string) =
   }
 }
 
+/**
+ * Render already-filtered-to-used specifier fragments for one import source
+ * into one or two legal import declaration lines. Shared by every call site
+ * that re-serializes an `ImportInfo`'s specifiers into client-JS import
+ * text — `collectExternalImports` below and the state-only-file client-JS
+ * path (`compiler.ts`'s single-component early return for a `.tsx` with no
+ * JSX return but exported `@client` module signals) — so the
+ * default/namespace handling lives in exactly one place.
+ *
+ * A default or namespace specifier needs its own import syntax
+ * (`import X from '...'` / `import * as X from '...'`), never the
+ * named-import braces a plain specifier gets — a plain `import { lock }
+ * from '...'` for a DEFAULT-imported `lock` compiles to a real, silently-
+ * wrong ESM import (no such named export) that only surfaces once a
+ * bundler actually resolves it (#2767 follow-up: a server component's own
+ * compiled init previously never reached a real Rollup graph, so this was
+ * unreachable until that gap closed).
+ *
+ * `import Default, { a, b } from '...'` is the only legal single-line
+ * pairing — a namespace specifier can't combine with named ones, but
+ * multiple import declarations for the same source are legal ESM, so a
+ * used namespace specifier always gets its own line.
+ */
+export function renderUsedImportLines(
+  source: string,
+  usedDefault: string | null,
+  usedNamespace: string | null,
+  usedNamed: string[],
+): string[] {
+  const lines: string[] = []
+  const defaultAndNamed = [
+    usedDefault,
+    usedNamed.length > 0 ? `{ ${usedNamed.join(', ')} }` : null,
+  ].filter((part): part is string => part !== null).join(', ')
+  if (defaultAndNamed) lines.push(`import ${defaultAndNamed} from '${source}'`)
+  if (usedNamespace) lines.push(`import * as ${usedNamespace} from '${source}'`)
+  return lines
+}
+
+/**
+ * Merge multiple sibling components' compiled client-JS blobs (one file
+ * with several `export function`s, e.g. `compileMultipleComponents`'s two
+ * `.client.js` outputs) into one conflict-free block.
+ *
+ * Real top-level `ImportDeclaration` statements are found via a
+ * `ts.createSourceFile` AST walk — never a text/regex line scan — so a
+ * string or template-literal VALUE that merely contains a line starting
+ * with `import ` (a docs component embedding a code sample, say) can never
+ * be torn out of its literal and hoisted into the imports block. This
+ * mirrors `combine-client-js.ts`'s `parseAndMerge`, the established
+ * precedent for exactly this shape of parse (see that file's docstring
+ * and issue #1702, the regression it exists to prevent) — CLAUDE.md
+ * requires it for "compiled client JS" specifically. Reaching a bundler
+ * for the FIRST time is precisely what a plain server component newly
+ * promoted to a Rollup entry by `needsClientEntry` (#2767) now does, so a
+ * line-based scan here carries real risk, not just a style violation.
+ *
+ * Differs from `parseAndMerge` in two ways required by this call site:
+ * (1) default and named specifiers from the same source fold into ONE
+ * declaration via `renderUsedImportLines`'s rule, rather than surviving
+ * as separate verbatim, exact-string-deduped lines — the fold is what
+ * prevents the duplicate-binding `SyntaxError` two sibling components can
+ * otherwise produce for a shared default import (#2767 follow-up); (2) an
+ * unresolved `@bf-child:` placeholder import is KEPT (deduped by exact
+ * text, same as any other side-effect import), never dropped — unlike
+ * `parseAndMerge`'s parent-child inlining case, this merge runs inside
+ * `compileMultipleComponents`, BEFORE `@barefootjs/vite`'s `resolveId`
+ * gets a chance to rewrite the placeholder into a real module reference.
+ *
+ * Returns the fully assembled `<imports>\n\n<code…>` block ready to use
+ * as a `.client.js` file's content.
+ */
+export function mergeCompiledClientJsImports(codeBlobs: string[]): string {
+  const sourceOrder: string[] = []
+  const namedBySource = new Map<string, Set<string>>()
+  const defaultBySource = new Map<string, string>()
+  const otherImports: string[] = []
+  const seenOther = new Set<string>()
+  const codeSections: string[] = []
+
+  const ensureSource = (source: string): Set<string> => {
+    if (!namedBySource.has(source)) {
+      namedBySource.set(source, new Set())
+      sourceOrder.push(source)
+    }
+    return namedBySource.get(source)!
+  }
+
+  for (const content of codeBlobs) {
+    const sourceFile = ts.createSourceFile(
+      'combine.js',
+      content,
+      ts.ScriptTarget.Latest,
+      /*setParentNodes*/ false,
+      ts.ScriptKind.JS,
+    )
+    const importSpans: Array<[number, number]> = []
+
+    for (const stmt of sourceFile.statements) {
+      if (!ts.isImportDeclaration(stmt)) continue
+      const start = stmt.getStart(sourceFile)
+      const end = stmt.getEnd()
+      importSpans.push([start, end])
+
+      const clause = stmt.importClause
+      const bindings = clause?.namedBindings
+      const specifier = ts.isStringLiteral(stmt.moduleSpecifier) ? stmt.moduleSpecifier.text : ''
+      const isNamespace = !!bindings && ts.isNamespaceImport(bindings)
+      const isNamed = !!bindings && ts.isNamedImports(bindings)
+
+      // A namespace binding (`import * as NS from '…'`, or a combined
+      // `import Default, * as NS from '…'`) is never folded — it always
+      // falls through to the verbatim-keep branch below, same as
+      // `parseAndMerge`'s. Checking `isNamespace` FIRST (not just `!isNamed`)
+      // matters for the combined-with-default shape specifically: a naive
+      // `clause?.name || isNamed` would route it into the fold branch below
+      // on the strength of the default clause alone and silently drop the
+      // namespace half, since only `isNamed` is read there. No current
+      // producer of `clientJs` output emits that combined shape
+      // (`renderUsedImportLines` always splits a used default+namespace
+      // pair into two separate lines), but the classification must stay
+      // correct independent of that invariant.
+      if (!isNamespace && (clause?.name || isNamed)) {
+        // Default and/or named specifiers — fold by source.
+        const set = ensureSource(specifier)
+        if (clause?.name && !defaultBySource.has(specifier)) {
+          defaultBySource.set(specifier, clause.name.text)
+        }
+        if (isNamed) {
+          for (const el of (bindings as ts.NamedImports).elements) {
+            set.add(el.propertyName ? `${el.propertyName.text} as ${el.name.text}` : el.name.text)
+          }
+        }
+      } else {
+        // Namespace or side-effect import (including an unresolved
+        // `@bf-child:` placeholder) — kept verbatim, deduped by exact text.
+        const stmtText = content.slice(start, end)
+        if (!seenOther.has(stmtText)) {
+          seenOther.add(stmtText)
+          otherImports.push(stmtText)
+        }
+      }
+    }
+
+    let code = ''
+    let cursor = 0
+    for (const [start, end] of importSpans) {
+      code += content.slice(cursor, start)
+      cursor = end
+    }
+    code += content.slice(cursor)
+    code = code.trim()
+    if (code) codeSections.push(code)
+  }
+
+  const mergedImports = sourceOrder.flatMap(source =>
+    renderUsedImportLines(source, defaultBySource.get(source) ?? null, null, [...namedBySource.get(source)!]),
+  )
+
+  return [...mergedImports, ...otherImports, '', ...codeSections].join('\n')
+}
+
 /**
  * Collect external (non-DOM, non-component) imports that are used in generated code.
  * These are third-party libraries like @barefootjs/form, zod, etc. that need to be
@@ -171,23 +337,30 @@ export function collectExternalImports(ir: ComponentIR, generatedCode: string, l
 
     // Check which specifiers are actually used in the generated code.
     // Skip component names — they are rendered via initChild(), not imported directly.
-    const usedSpecs: string[] = []
+    const usedNamed: string[] = []
+    let usedDefault: string | null = null
+    let usedNamespace: string | null = null
     for (const spec of imp.specifiers) {
       // Per-specifier `import { type Foo }` has no value binding — #2432.
       if (spec.isTypeOnly) continue
       const localName = spec.alias || spec.name
       if (componentNames.has(localName)) continue
-      if (isUsedAsValue(localName)) {
-        usedSpecs.push(spec.alias ? `${spec.name} as ${spec.alias}` : spec.name)
+      if (!isUsedAsValue(localName)) continue
+      if (spec.isDefault) {
+        usedDefault = localName
+      } else if (spec.isNamespace) {
+        usedNamespace = localName
+      } else {
+        usedNamed.push(spec.alias ? `${spec.name} as ${spec.alias}` : spec.name)
       }
     }
 
-    if (usedSpecs.length > 0) {
+    if (usedDefault || usedNamespace || usedNamed.length > 0) {
       let source = imp.source
       if (ir.metadata.clientSignalImportSources?.has(source)) {
         source = source.replace(/\.tsx?$/, '') + '.client.js'
       }
-      importLines.push(`import { ${usedSpecs.join(', ')} } from '${source}'`)
+      importLines.push(...renderUsedImportLines(source, usedDefault, usedNamespace, usedNamed))
     }
   }
   return importLines

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

@@ -217,6 +217,11 @@ function needsClientJs(ctx: ClientJsContext): boolean {
     ctx.conditionalElements.length > 0 ||
     ctx.loopElements.length > 0 ||
     ctx.refElements.length > 0 ||
+    // An element forwarding the caller's leftover props needs `init` to
+    // run `applyRestAttrs` against it — that call is the ONLY thing that
+    // applies those attributes on a pure CSR mount, since neither template
+    // can carry a bag whose keys are unknown at compile time (#2754).
+    ctx.restAttrElements.length > 0 ||
     ctx.childInits.length > 0 ||
     ctx.reactiveAttrs.length > 0 ||
     ctx.clientOnlyElements.length > 0 ||