@barefootjs/jsx 0.29.0 → 0.30.2

package/src/jsx-to-ir.ts

@@ -29,6 +29,7 @@ import {
   type MapCallbackPreamble,
   type PreambleSegment,
   type PreambleRegionSource,
+  type PreambleValueDeclaration,
   tsxSourceText,
   type SourceLocation,
   type TypeInfo,
@@ -945,6 +946,36 @@ function buildIRRoot(analyzer: AnalyzerContext): IRNode | null {
   // build an if-statement chain instead of a single node
   if (analyzer.conditionalReturns.length > 0) {
     const ctx = createTransformContext(analyzer)
+    // #2463: a chain whose conditions are ALL reactive (signal/memo reads)
+    // is semantically the root ternary, and the IRIfStatement contract
+    // ("client JS handles all branches and switches at runtime") demands
+    // the same insert() plan the ternary gets. Lower it through the
+    // conditional path + synthetic scope wrapper. Gated to chains with no
+    // branch-local scope variables — those carry #1409/#1414 machinery
+    // (branch consts, branch-scoped signals) that the conditional plan
+    // has no seat for, so they stay on the IRIfStatement path; a static
+    // or prop-conditioned chain stays there too (its branches cannot
+    // change after render without a re-render, so no runtime switch is
+    // owed). The eligibility check is analysis-only (no transforms run),
+    // so falling through to the statement path never skews slot ids.
+    // `exprCallsReactiveGetters` (signal/memo getter CALLS), not
+    // `isReactiveExpression`: bare destructured-prop reads also count as
+    // "reactive" to the latter, and prop-conditioned chains must stay on
+    // the IRIfStatement path — their branches only change on re-render,
+    // and converting them would churn every #1401-family emission.
+    const allReactiveNoLocals =
+      analyzer.jsxReturn != null &&
+      analyzer.conditionalReturns.every(cr =>
+        cr.scopeVariables.length === 0 &&
+        exprCallsReactiveGetters(cr.condition, ctx),
+      )
+    if (allReactiveNoLocals) {
+      const chain = buildIfStatementChain(analyzer, ctx, { asConditional: true })
+      if (!chain) return null
+      // Degenerate transforms can fall a link back to statement mode; the
+      // wrapper is owed only to a conditional root (the ternary shape).
+      return chain.type === 'conditional' ? wrapInScopeElement(chain) : chain
+    }
     return buildIfStatementChain(analyzer, ctx)
   }
 
@@ -1231,6 +1262,84 @@ function transformJsxElement(
   return transformHtmlElement(node, ctx, tagName)
 }
 
+/**
+ * SSR projection of a controlled form-control `value` (#2464 / #2465).
+ *
+ * `value` is not an attribute on `<textarea>` (its initial value is its
+ * element content) and not an attribute on `<select>` (the selection is
+ * `selected` on the matching `<option>`). Emitting it verbatim ships
+ * invalid HTML that browsers ignore, so no-JS and pre-hydration users see
+ * an empty textarea / the wrong option until the client `.value` effect
+ * snaps it.
+ *
+ * Lowering (shared IR, so every adapter inherits it):
+ *  - the `value` attr is marked `clientOnly` — SSR skips it, the existing
+ *    hydrate-time `.value` property binding is unchanged;
+ *  - `<textarea>` with no children gains a NON-reactive expression child
+ *    (the initial value as element content — updates keep flowing through
+ *    the `.value` effect, deliberately not a live text slot);
+ *  - `<select>` distributes `selected={(value) === 'opt'}` onto each
+ *    statically-valued `<option>` (incl. under `<optgroup>`/fragments) —
+ *    the exact per-option comparison shape the `select-option-selected`
+ *    fixture already proves across every adapter. Options rendered by a
+ *    dynamic loop can't be statically distributed and are left to the
+ *    hydrate-time effect (tracked with #2466 on the #2464 thread).
+ */
+function lowerFormControlValueSsr(
+  tagName: string,
+  attrs: IRAttribute[],
+  children: IRNode[],
+): void {
+  if (tagName !== 'textarea' && tagName !== 'select') return
+  const valueAttr = attrs.find(a => a.name === 'value')
+  if (!valueAttr || valueAttr.clientOnly || valueAttr.value.kind !== 'expression') return
+  const { expr, templateExpr } = valueAttr.value
+
+  valueAttr.clientOnly = true
+
+  if (tagName === 'textarea') {
+    if (children.length > 0) return
+    children.push({
+      type: 'expression',
+      expr,
+      // The client-side registration template interpolates slotless
+      // expression children RAW (no text-slot `escapeText` wrapper), so a
+      // value containing `</textarea>` would break out of the element on
+      // CSR mount. Escape in the client-only template variant; `expr`
+      // stays clean for the SSR adapters, whose template engines (and
+      // hono/jsx) already escape text children natively.
+      templateExpr: `escapeText(${templateExpr ?? expr})`,
+      typeInfo: null,
+      reactive: false,
+      slotId: null,
+      loc: valueAttr.loc,
+      origin: { phase: 'ssr', scope: 'template', effect: 'pure' },
+    })
+    return
+  }
+
+  const selectedFor = (optValue: string): AttrValue =>
+    AttrValueOf.expression(
+      `(${expr}) === ${JSON.stringify(optValue)}`,
+      templateExpr !== undefined
+        ? { templateExpr: `(${templateExpr}) === ${JSON.stringify(optValue)}` }
+        : undefined,
+    )
+  const distribute = (nodes: IRNode[]): void => {
+    for (const n of nodes) {
+      if (n.type === 'element' && n.tag === 'option') {
+        if (n.attrs.some(a => a.name === 'selected')) continue
+        const optValue = n.attrs.find(a => a.name === 'value')
+        if (!optValue || optValue.value.kind !== 'literal') continue
+        n.attrs.push({ name: 'selected', value: selectedFor(optValue.value.value), loc: n.loc })
+      } else if (n.type === 'fragment' || (n.type === 'element' && n.tag === 'optgroup')) {
+        distribute(n.children)
+      }
+    }
+  }
+  distribute(children)
+}
+
 function transformHtmlElement(
   node: ts.JsxElement,
   ctx: TransformContext,
@@ -1246,6 +1355,7 @@ function transformHtmlElement(
   ctx.isRoot = false
 
   const children = transformChildren(node.children, ctx)
+  lowerFormControlValueSsr(tagName, attrs, children)
 
   // Determine if this element needs a slot ID
   // Elements need slotIds if they have: events, dynamic children, reactive attributes, or refs
@@ -1301,6 +1411,8 @@ function transformSelfClosingElement(
   }
 
   const { attrs, events, ref } = processAttributes(node.attributes, ctx)
+  const selfClosingChildren: IRNode[] = []
+  lowerFormControlValueSsr(tagName, attrs, selfClosingChildren)
 
   // Elements need slotIds if they have events, reactive attributes, or refs
   const needsSlot = events.length > 0 || hasReactiveAttributes(attrs, ctx) || ref !== null
@@ -1315,7 +1427,7 @@ function transformSelfClosingElement(
     attrs,
     events,
     ref,
-    children: [],
+    children: selfClosingChildren,
     slotId,
     needsScope,
     loc: getSourceLocation(node, ctx.sourceFile, ctx.filePath),
@@ -3794,6 +3906,27 @@ function branchHasNoElement(node: IRNode): boolean {
  * element ternaries (which always render exactly one element and stay on the
  * legacy `mapArray` path).
  */
+/**
+ * Tag every component that is a loop item root — a DIRECT member of the
+ * loop body, unwrapping through nested conditionals (`cond ? <A/> : <B/>`,
+ * `cond && <A/>`) but NOT through elements or fragments. Mirrors the Hono
+ * reference adapter's `renderConditional` ctx-forwarding exactly:
+ * `isLoopItemRoot` threads through nested conditional branches (a bare
+ * ternary/logical loop body, arbitrarily nested), but `renderElement` /
+ * `renderFragment` never forward it to their children — a component nested
+ * inside a plain element or fragment is never a loop item root, even if
+ * that element/fragment is itself the loop's row. See #2444.
+ */
+function tagLoopItemRootComponents(nodes: readonly IRNode[]): void {
+  for (const node of nodes) {
+    if (node.type === 'component') {
+      node.loopItemRoot = true
+    } else if (node.type === 'conditional') {
+      tagLoopItemRootComponents([node.whenTrue, node.whenFalse])
+    }
+  }
+}
+
 function loopBodyItemConditional(children: IRNode[]): IRConditional | null {
   const real = children.filter(
     (c) => !(c.type === 'text' && typeof c.value === 'string' && !c.value.trim())
@@ -4229,20 +4362,29 @@ function transformMapCall(
           // verbatim.
           preamble = preambleFromValueStatements(pre, ctx)
 
-          // A DSL adapter can't carry a loop-local `const` into a conditional
-          // branch template, so it would render the branches with the local
-          // undefined (silent divergence). Refuse instead — adapter-gated like
-          // the filter/sort sites: a JS-runtime target folds and runs it, a DSL
-          // target errors with the /* @client */ escape (which renders the map
-          // client-only, where the browser runs the preamble). Stage 2 of
-          // spec/callback-fidelity.md.
-          if (!isClientOnly && !(ctx.analyzer.acceptsCallbackBody?.('map') ?? false)) {
+          // Stage 2 of spec/callback-fidelity.md, narrowed by #2447. This used
+          // to refuse EVERY branch preamble on a DSL target, on the premise
+          // that a loop-local can't be carried into a conditional branch
+          // template. That premise stopped holding once `declarations` lower
+          // to a per-row local: the fold emits the conditional INSIDE the loop
+          // body, so a local declared ahead of it is in scope in both arms —
+          // `{{$label := bf_upper .Kind}}{{if .On}}…{{$label}}…{{else}}…`. What
+          // remains true is the original hazard for a preamble that CANNOT be
+          // declared: nothing lowers, both branches read an unassigned name.
+          // So the refusal now keys off the same condition as the single-return
+          // gate below, not off the presence of branches.
+          if (
+            !preamble.declarations &&
+            !isClientOnly &&
+            !(ctx.analyzer.acceptsCallbackBody?.('map') ?? false)
+          ) {
             ctx.analyzer.errors.push(
               createError(ErrorCodes.UNSUPPORTED_JSX_PATTERN, loc, {
                 message:
-                  'A .map() callback body with a `const`/`let` preamble before its ' +
-                  'branches cannot be lowered to a template: the loop-local binding ' +
-                  'cannot be carried into a conditional branch on this backend.',
+                  'A .map() callback body with a preamble before its branches cannot be ' +
+                  'lowered to a template: the preamble is not a sequence of value ' +
+                  'declarations, so this backend has no per-row local to carry into the ' +
+                  'branches.',
                 suggestion: {
                   message: 'Add /* @client */ to evaluate this expression on the client only',
                 },
@@ -4381,6 +4523,37 @@ function transformMapCall(
           }
           if (valueStmts.length > 0) {
             preamble = preambleFromValueStatements(valueStmts, ctx)
+
+            // #2447. A DSL adapter cannot execute `preamble.segments` (JS
+            // text), so it lowers `declarations` — one per-row local each —
+            // and the row markup reads them as locals. When the preamble
+            // isn't fully declarable there is nothing to lower, and the
+            // adapter used to emit the row anyway, reading names it never
+            // assigned: the class rendered empty, on every DSL backend, with
+            // no diagnostic. Refuse loudly instead, with the same
+            // `/* @client */` escape as the branch-preamble, array-builder
+            // and flatMap gates above.
+            if (
+              !preamble.declarations &&
+              !isClientOnly &&
+              !(ctx.analyzer.acceptsCallbackBody?.('map') ?? false)
+            ) {
+              ctx.analyzer.errors.push(
+                createError(
+                  ErrorCodes.UNSUPPORTED_JSX_PATTERN,
+                  getSourceLocation(body, ctx.sourceFile, ctx.filePath),
+                  {
+                    message:
+                      'A .map() callback preamble that is not a sequence of value ' +
+                      'declarations cannot be lowered to a template: this backend can ' +
+                      'declare a per-row local, but cannot run arbitrary statements per row.',
+                    suggestion: {
+                      message: 'Add /* @client */ to evaluate this expression on the client only',
+                    },
+                  },
+                )
+              )
+            }
           }
         }
       }
@@ -4605,6 +4778,15 @@ function transformMapCall(
     preamble = undefined
   }
 
+  // A component that is a DIRECT member of the loop body (the row root, or
+  // one of several flatMap-sibling roots) owns its own per-row identity and
+  // gets a freshly randomized `bf-s` rather than deriving one from parent
+  // scope + slot. Tag it here — the single place that knows which nodes are
+  // direct loop-body members — so every backend can consult
+  // `derivesScopeFromSlot()` instead of re-deriving this fact from a mutable
+  // "am I inside a loop" flag.
+  tagLoopItemRootComponents(children)
+
   // Extract childComponent info if the loop body is a single component
   // This enables createComponent-based rendering with proper prop passing
   let childComponent: IRLoopChildComponent | undefined
@@ -4675,6 +4857,19 @@ function transformMapCall(
     ? collectPreambleRegions(children, new Set(preamble.declaredNames), ctx)
     : undefined
 
+  // #2447 follow-up — the ATTRIBUTE twin of the regions above. `class={cls}`
+  // where the preamble declares `cls` froze at its row-construction value for
+  // the same reason `{cells}` did, and for one extra reason on top: an
+  // attribute only gets wired at all if its element carries a slot id, and
+  // `hasReactiveAttributes` (which decides that at element-build time, before
+  // any loop preamble is known) scores a bare local as non-reactive. So the
+  // slot has to be granted HERE, in the same after-the-fact pass the regions
+  // use — after which `collectLoopChildReactiveAttrs` classifies the attr and
+  // the row effect re-runs the preamble ahead of the write.
+  if (preamble && !isStaticArray) {
+    markPreambleAttrSlots(children, new Set(preamble.declaredNames), ctx)
+  }
+
   // Collect nested components for both static and dynamic arrays.
   // Static arrays: needed for initChild hydration.
   // Dynamic arrays with native root + component descendants: enables
@@ -5061,6 +5256,72 @@ function collectPreambleRegions(
   return regions
 }
 
+/**
+ * Grant a slot id to every loop-body element carrying an attribute that reads
+ * a `.map()` preamble local (#2447 follow-up).
+ *
+ * Only the slot id is decided here; whether the attribute is *wired* is the
+ * client-JS classifier's call (`collectLoopChildReactiveAttrs`, which takes
+ * the same `declaredNames` set). Splitting it that way keeps this pass free of
+ * reactivity policy — it removes the one obstacle the classifier cannot remove
+ * for itself, since `hasReactiveAttributes` already ran when the element was
+ * built and a slot id cannot be granted from the client-JS pass (the SSR
+ * template is rendered from this same IR and would not carry the `bf` marker).
+ *
+ * Mirrors `collectPreambleRegions`' traversal exactly, conditional arms
+ * included — an arm element gets its slot id here too, which costs nothing
+ * when the arm's own wiring declines to use it.
+ */
+function markPreambleAttrSlots(
+  nodes: IRNode[],
+  declared: ReadonlySet<string>,
+  ctx: TransformContext,
+): void {
+  const readsDeclared = (attr: IRAttribute): boolean => {
+    if (attr.name === 'key') return false
+    const value = attr.value
+    if (value.kind !== 'expression' && value.kind !== 'template') return false
+    const refs = attr.freeIdentifiers ?? extractFreeIdentifiersFromText(attrValueText(value))
+    for (const r of refs) if (declared.has(r)) return true
+    return false
+  }
+  const visit = (list: IRNode[]): void => {
+    for (const node of list) {
+      switch (node.type) {
+        case 'element':
+          if (!node.slotId && node.attrs.some(readsDeclared)) node.slotId = generateSlotId(ctx)
+          visit(node.children)
+          break
+        case 'fragment':
+          visit(node.children)
+          break
+        case 'conditional':
+          visit([node.whenTrue, ...(node.whenFalse ? [node.whenFalse] : [])])
+          break
+      }
+    }
+  }
+  visit(nodes)
+}
+
+/**
+ * Expression-bearing source text of an attribute value, for the
+ * free-identifier scan. Only used as a FALLBACK — an attribute normally
+ * carries `freeIdentifiers` from its own AST walk, and this reconstruction
+ * exists for the few IR producers that don't populate it. Static string parts
+ * are dropped so a literal word can never be mistaken for an identifier.
+ */
+function attrValueText(value: AttrValue): string {
+  if (value.kind === 'expression') return value.expr
+  if (value.kind !== 'template') return ''
+  const out: string[] = []
+  for (const p of value.parts) {
+    if (p.type === 'ternary') out.push(p.condition, p.whenTrue, p.whenFalse)
+    else if (p.type === 'lookup') out.push(p.key)
+  }
+  return out.join(' ')
+}
+
 /**
  * Collect the names a binding introduces, recursing through object/array
  * destructuring patterns (`const { id: k } = r`, `const [k, ...rest] = xs`) so
@@ -5118,9 +5379,50 @@ function preambleFromValueStatements(
     declaredNames: [...declared],
     // Value-only preambles accumulate no JSX, so no child needs the array join.
     builderNames: [],
+    declarations: neutralPreambleDeclarations(statements, ctx) ?? undefined,
   }
 }
 
+/**
+ * The DSL SSR half of a value preamble (#2447): every statement as a neutral
+ * {@link PreambleValueDeclaration}, or `null` if any statement is not one.
+ *
+ * All-or-nothing — see `MapCallbackPreamble.declarations`. `null` is what the
+ * Phase-1 gate turns into a loud refusal, so every rejection here must be a
+ * shape a template language genuinely cannot express per row, not a shape this
+ * function merely hasn't got round to.
+ */
+function neutralPreambleDeclarations(
+  statements: readonly ts.Statement[],
+  ctx: TransformContext,
+): PreambleValueDeclaration[] | null {
+  const out: PreambleValueDeclaration[] = []
+  for (const stmt of statements) {
+    // A non-declaration statement (assignment, `for`, a call for its side
+    // effects) has no per-row template form at all.
+    if (!ts.isVariableStatement(stmt)) return null
+    for (const decl of stmt.declarationList.declarations) {
+      // A destructuring binding declares several names from one initializer;
+      // no adapter has a single per-row local form for that.
+      if (!ts.isIdentifier(decl.name)) return null
+      if (!decl.initializer) return null
+      const valueParsed = tsNodeToParsedExpr(decl.initializer)
+      // The same subset gate every other DSL-lowered expression passes
+      // through. An adapter that additionally cannot emit a supported shape
+      // (Go has no array-literal form, say) still records its own BF101 from
+      // its own emitter — this only decides whether the shape is expressible
+      // in principle.
+      if (!isSupported(valueParsed).supported) return null
+      out.push({
+        name: decl.name.text,
+        valueParsed,
+        raw: decl.initializer.getText(ctx.sourceFile),
+      })
+    }
+  }
+  return out.length > 0 ? out : null
+}
+
 /** Drop the trailing separator space from the final js segment. */
 function trimPreambleSegments(segments: PreambleSegment[]): PreambleSegment[] {
   const last = segments[segments.length - 1]
@@ -5772,6 +6074,11 @@ function tryResolveTemplateSpanFromConst(
 ): IRTemplatePart[] | null {
   // ${IDENT}
   if (ts.isIdentifier(expr)) {
+    // #2222-family: inside a loop callback the name may be the loop's
+    // item/index binding shadowing a same-named const — resolving the
+    // const would bake the outer value into every row. Fall back to
+    // the bare-expression path, which sees the loop binding.
+    if (ctx.loopParams.has(expr.text)) return null
     const constInfo = findLocalConst(expr.text, ctx.analyzer)
     if (!constInfo) return null
     const ast = parseConstInitializer(constInfo)
@@ -5785,6 +6092,10 @@ function tryResolveTemplateSpanFromConst(
   // ${IDENT[KEY]}
   if (ts.isElementAccessExpression(expr)) {
     if (!ts.isIdentifier(expr.expression)) return null
+    // Same loop-shadowing guard as the ${IDENT} arm: `tone[k]` inside
+    // `items.map((tone) => …)` must read the row's `tone`, not a
+    // same-named module/component record const.
+    if (ctx.loopParams.has(expr.expression.text)) return null
     const constInfo = findLocalConst(expr.expression.text, ctx.analyzer)
     if (!constInfo) return null
     const ast = parseConstInitializer(constInfo)
@@ -5968,6 +6279,30 @@ function tryResolveIdentifierAsTemplateLiteral(
     return [{ type: 'string', value: ast.text }]
   }
 
+  // `const cls = variantClasses[variant]` (#2477): the initializer IS the
+  // #2300 element-access shape, just not wrapped in a template literal.
+  // Route it through the same span resolver so the one-hop const
+  // (`className={cls}`) lowers to the identical `lookup` part as the
+  // inline form (`className={variantClasses[variant]}`, the #2300 arm in
+  // `getAttributeValue`) and the template-literal hop
+  // (`const cls = \`${variantClasses[variant]}\``, the arm below) — both
+  // of which every adapter already renders. Without this arm the attr
+  // fell through to a bare-expression `cls`, which JSX-runtime SSR
+  // (Hono) evaluates fine but every template backend emits as a
+  // reference to a variable the template never defines, rendering
+  // `class=""` with zero diagnostics. Same dynamic-key guard as the
+  // inline arm: a static-key index (`paths['icon']`) stays on the
+  // bare-expression path (jsx-to-ir regression pin — adapters resolve a
+  // constant-key index already, and it must remain a plain `expression`
+  // attr, not a single-case `lookup`).
+  if (
+    ts.isElementAccessExpression(ast) &&
+    !ts.isStringLiteralLike(ast.argumentExpression) &&
+    !ts.isNumericLiteral(ast.argumentExpression)
+  ) {
+    return tryResolveTemplateSpanFromConst(ast, ctx)
+  }
+
   if (!ts.isTemplateExpression(ast)) return null
 
   // We require at least one structurally-meaningful span (a string
@@ -6433,8 +6768,20 @@ function processComponentProps(
     // (Hono) keep using `expr`. Boolean-attr is also promoted to
     // shorthand (`<X disabled />` → `disabled={true}`).
     if (value.kind === 'template') {
-      value = AttrValueOf.expression(templatePartsToJsString(value.parts), {
+      // Collapse using the raw part values, but also carry the
+      // template-variant projection (parts' `templateValue` /
+      // `templateCondition` / `templateKey`, i.e. destructured-prop refs
+      // rewritten to `_p.X`) as `templateExpr`. Without it, the
+      // `templateExpr` derivation below walks the ORIGINAL initializer AST
+      // — for a const-resolved template (`className={classes}`) that AST is
+      // the bare `classes` identifier with no prop refs, so the rewrite
+      // no-ops and the module-scope registration template leaks bare
+      // destructured props into `renderChild(...)` (#2468).
+      const collapsed = templatePartsToJsString(value.parts)
+      const collapsedTemplate = templatePartsToJsString(value.parts, { useTemplate: true })
+      value = AttrValueOf.expression(collapsed, {
         parts: value.parts,
+        ...(collapsedTemplate !== collapsed && { templateExpr: collapsedTemplate }),
       })
     } else if (value.kind === 'boolean-attr') {
       value = AttrValueOf.booleanShorthand()
@@ -6479,18 +6826,20 @@ function processComponentProps(
  * needs to be collapsed into an `expression` for component-prop forwarding —
  * component props are runtime JS values, not HTML attribute bodies.
  */
-function templatePartsToJsString(parts: readonly IRTemplatePart[]): string {
+function templatePartsToJsString(parts: readonly IRTemplatePart[], opts?: { useTemplate?: boolean }): string {
   let result = '`'
   for (const part of parts) {
     if (part.type === 'string') {
-      result += part.value
+      result += (opts?.useTemplate && part.templateValue) ? part.templateValue : part.value
     } else if (part.type === 'ternary') {
-      result += `\${${part.condition} ? '${part.whenTrue}' : '${part.whenFalse}'}`
+      const cond = (opts?.useTemplate && part.templateCondition) ? part.templateCondition : part.condition
+      result += `\${${cond} ? '${part.whenTrue}' : '${part.whenFalse}'}`
     } else if (part.type === 'lookup') {
+      const key = (opts?.useTemplate && part.templateKey) ? part.templateKey : part.key
       const obj = '{' + Object.entries(part.cases).map(
         ([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`
       ).join(', ') + '}'
-      result += `\${(${obj})[${part.key}]}`
+      result += `\${(${obj})[${key}]}`
     }
   }
   result += '`'
@@ -6875,14 +7224,21 @@ function replaceBranchLocalRefs(
  */
 function buildIfStatementChain(
   analyzer: AnalyzerContext,
-  ctx: TransformContext
-): IRIfStatement {
+  ctx: TransformContext,
+  opts?: { asConditional?: boolean }
+): IRIfStatement | IRConditional | null {
   const conditionalReturns = analyzer.conditionalReturns
+  // #2463: conditional mode builds the same IRConditional links the root
+  // ternary produces (reactive insert() plan). The caller wraps the chain
+  // in the synthetic display:contents scope element, so branches must NOT
+  // claim the root scope themselves — mirror the ternary path's
+  // `ctx.isRoot = false`.
+  const asConditional = opts?.asConditional === true
 
   // Start with the final return (else case) if it exists
   let alternate: IRNode | null = null
   if (analyzer.jsxReturn) {
-    ctx.isRoot = true
+    ctx.isRoot = !asConditional
     alternate = transformNode(analyzer.jsxReturn, ctx)
   }
 
@@ -7010,8 +7366,9 @@ function buildIfStatementChain(
     }
 
     // Transform the JSX return in the then branch
-    // Reset isRoot so each branch gets needsScope=true
-    ctx.isRoot = true
+    // Reset isRoot so each branch gets needsScope=true (statement mode);
+    // in conditional mode (#2463) the synthetic wrapper carries the scope.
+    ctx.isRoot = !asConditional
     let consequent: IRNode | null
     try {
       consequent = transformNode(condReturn.jsxReturn, ctx)
@@ -7062,6 +7419,33 @@ function buildIfStatementChain(
       analyzer.filePath
     )
 
+    if (asConditional && alternate) {
+      // #2463: emit the same node shape `transformConditional` builds for
+      // the root ternary, so the downstream insert() plan, slot wrapping,
+      // and template substitution all apply unchanged. Eligibility
+      // (checked by the caller) guarantees a reactive condition and no
+      // branch scopeVariables.
+      const conditional: IRConditional = {
+        type: 'conditional',
+        condition,
+        templateCondition,
+        conditionType: null,
+        reactive: true,
+        whenTrue: consequent,
+        whenFalse: alternate,
+        slotId: generateSlotId(ctx),
+        loc,
+        origin: {
+          phase: 'tick',
+          scope: 'template',
+          effect: 'pure',
+          freeRefs: resolveFreeRefs(condReturn.condition, makeBindingEnv(ctx)),
+        },
+      }
+      alternate = conditional
+      continue
+    }
+
     // Create the if statement node
     const ifStmt: IRIfStatement = {
       type: 'if-statement',
@@ -7077,6 +7461,7 @@ function buildIfStatementChain(
     alternate = ifStmt
   }
 
-  // The final result should be an IRIfStatement (the first if in the chain)
-  return alternate as IRIfStatement
+  // The final result: the first link of the chain (an IRIfStatement in
+  // statement mode, an IRConditional in #2463's conditional mode).
+  return alternate as IRIfStatement | IRConditional | null
 }