@barefootjs/jsx 0.27.0 → 0.28.1

package/src/__tests__/loop-branch-bare-expression-reactive-text.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Emission pin for the loop-branch-stale-text fix.
+ *
+ * `summarizeLoopChildBranch` (ir-to-client-js/collect-elements.ts) used to
+ * collect NO `reactiveTexts` for ANY loop-row conditional branch whose whole
+ * content is a bare `expression` (no wrapping element) — including a plain
+ * property read like `row.label`, which can never construct a live DOM
+ * node. That blanket skip meant a keyed row's branch text silently froze at
+ * its mount-time value whenever the item changed without the conditional's
+ * OWN condition flipping (`insert()`, runtime/insert.ts, correctly no-ops
+ * when its condition is unchanged — branch-internal updates are the effect
+ * system's job).
+ *
+ * The fix narrows the skip to `node.hasFunctionCalls` (jsx-to-ir.ts's
+ * `exprHasFunctionCalls`, a recursive AST walk — catches a call nested
+ * anywhere, not just a top-level one) — a call can return a live DOM node
+ * (a hoisted `renderNode={(n) => <Pill/>}` callback lowered to a component
+ * call, #1211/#1213, pinned by `nested-loop-conditional.test.ts`) and the
+ * compiler cannot tell from syntax whether it does, so that shape must keep
+ * the skip. Everything call-free is provably incapable of yielding a Node
+ * and is now collected.
+ *
+ * The companion half of the fix lives in `transformConditionalBranch`
+ * (jsx-to-ir.ts): a bare loop-item read like `row.label` previously got NO
+ * `slotId` at all (`needsSlot` didn't consider a `render-item` free
+ * reference), so even with the collect-elements.ts skip narrowed there was
+ * nothing for the new effect — or the `<!--bf:sN-->` marker
+ * `irToHtmlTemplate` emits for it — to attach to. Both are exercised here
+ * together because neither half alone reproduces the fix.
+ */
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { TestAdapter } from '../adapters/test-adapter'
+
+const adapter = new TestAdapter()
+
+function clientJsFor(branchTrue: string): string {
+  const source = `
+    'use client'
+    import { createSignal } from '@barefootjs/client'
+    type Props = { format?: (s: string) => string }
+    type Row = { id: number; label: string; done: boolean }
+    export function C(_p: Props) {
+      const [rows] = createSignal<Row[]>([])
+      return <ul>{rows().map(row => <li key={row.id}>{row.done ? ${branchTrue} : 'pending'}</li>)}</ul>
+    }
+  `
+  const result = compileJSX(source, 'C.tsx', { adapter })
+  const errors = result.errors.filter(e => e.severity === 'error')
+  if (errors.length > 0) throw new Error(errors.map(e => e.message).join('\n'))
+  return result.files.find(f => f.type === 'clientJs')!.content
+}
+
+describe('loop-branch-stale-text — reactiveTexts narrowing (collect-elements.ts)', () => {
+  test('a bare property-read branch (no call anywhere) gets its own text effect', () => {
+    const js = clientJsFor('row.label')
+    expect(js).toContain("escapeTextOrNode(row().label)")
+    // And a slotId was actually allocated for it — `transformConditionalBranch`'s
+    // `refsLoopParam` half of the fix, without which the effect above would
+    // have nothing to `lazySlots(...)` claim.
+    expect(js).toMatch(/lazySlots\(__branchScope, \[\{ id: 's\d+', kind: 'markup', path: \[\] \}\]\)/)
+  })
+
+  test('a template-literal branch built from property reads only (no call) also gets a text effect', () => {
+    const js = clientJsFor('`[${row.label}]`')
+    expect(js).toContain('escapeTextOrNode(`[${row().label}]`)')
+  })
+
+  test('a branch with a call ANYWHERE (top-level) keeps the skip — no per-item text effect', () => {
+    const js = clientJsFor('_p.format(row.label)')
+    expect(js).not.toContain('escapeTextOrNode(_p.format(row().label))')
+    // bindEvents for that arm stays empty (mirrors the pre-fix shape exactly).
+    expect(js).toMatch(/bindEvents: \(__branchScope, \{ isFirstRun: __bfFirstRun = false \} = \{\}\) => \{\s*\}/m)
+  })
+
+  test('a branch with a call NESTED inside a template literal also keeps the skip', () => {
+    // The call is not at the top level of the expression — `exprHasFunctionCalls`
+    // is a full recursive AST walk, so this must be caught too.
+    const js = clientJsFor('`${_p.format(row.label)}!`')
+    expect(js).not.toContain("escapeTextOrNode(`${_p.format(row().label)}!`)")
+  })
+
+  test('a branch with a call nested inside a sub-ternary keeps the skip', () => {
+    const js = clientJsFor("row.id > 0 ? _p.format(row.label) : row.label")
+    // The outer branch (itself a nested conditional) is unaffected by this
+    // narrowing — nested conditionals already get their own `insert()` via
+    // `collectLoopChildConditionals`, never through `reactiveTexts`. This
+    // case exists to confirm compilation succeeds and the call-bearing leaf
+    // still doesn't get a bare reactiveTexts effect wrapping the whole
+    // nested-ternary expression text.
+    expect(js).not.toContain('escapeTextOrNode(row.id > 0 ? _p.format(row().label) : row().label)')
+  })
+
+  test('an inert literal branch (no loop-param ref, no call) stays exactly as before — no slotId, no effect', () => {
+    const js = clientJsFor("'yes'")
+    expect(js).not.toContain("escapeTextOrNode('yes')")
+  })
+})

package/src/__tests__/loop-fallback-wrap.test.ts

@@ -58,7 +58,7 @@ describe('Solid-style wrap-by-default fallback for loops (#943)', () => {
     const clientJs = getClientJs(source, 'List.tsx')
     // Dynamic loops emit a `mapArray(` call site. Tighter than
     // `/mapArray|reconcile/` which would fire on any stray mention.
-    expect(clientJs).toContain('mapArray(')
+    expect(clientJs).toMatch(/\bmapArray(Lazy)?\(/)
     expect(clientJs).toContain('items()')
   })
 
@@ -83,7 +83,7 @@ describe('Solid-style wrap-by-default fallback for loops (#943)', () => {
     `
 
     const clientJs = getClientJs(source, 'List.tsx')
-    expect(clientJs).toContain('mapArray(')
+    expect(clientJs).toMatch(/\bmapArray(Lazy)?\(/)
     expect(clientJs).toContain('getItems()')
   })
 
@@ -124,7 +124,11 @@ describe('Solid-style wrap-by-default fallback for loops (#943)', () => {
     `
 
     const clientJs = getClientJs(source, 'List.tsx')
-    expect(clientJs).toMatch(/\bmapArray\s*\(/)
+    // `mapArrayLazy` counts: a keyed, single-root, conditional-free row over a
+    // PROP array is lazy-row-eligible (spec/slot-unification.md §9.4 — props
+    // are the canonical hydration-consistent source), so it takes the lazy
+    // reconciler. What #1586 pins is "reconciles at all", not which family.
+    expect(clientJs).toMatch(/\bmapArray(Lazy)?\s*\(/)
   })
 
   test('unrecognised-call chain with filter now reconciles', () => {
@@ -149,7 +153,7 @@ describe('Solid-style wrap-by-default fallback for loops (#943)', () => {
     `
 
     const clientJs = getClientJs(source, 'DoneList.tsx')
-    expect(clientJs).toContain('mapArray(')
+    expect(clientJs).toMatch(/\bmapArray(Lazy)?\(/)
     expect(clientJs).toContain('computeItems()')
   })
 
@@ -181,7 +185,7 @@ describe('Solid-style wrap-by-default fallback for loops (#943)', () => {
     // Outer reconciles via mapArray. Also assert the inner loop's array
     // expression (`o.children`) appears in the emitted template — without
     // this, the test would pass even if the inner loop were dropped.
-    expect(clientJs).toContain('mapArray(')
+    expect(clientJs).toMatch(/\bmapArray(Lazy)?\(/)
     expect(clientJs).toContain('outer()')
     expect(clientJs).toContain('o.children')
   })
@@ -219,8 +223,13 @@ describe('Solid-style wrap-by-default fallback for loops (#943)', () => {
     // mapArray is emitted (widening now applies). renderItem uses the
     // synthetic `__bfItem` param; references to `cfg` are rewritten
     // inline and no unwrap statement is emitted.
-    expect(clientJs).toContain('mapArray(')
-    expect(clientJs).toContain('(__bfItem, ')
+    expect(clientJs).toMatch(/\bmapArray(Lazy)?\(/)
+    // The synthetic accessor param, in whichever reconciler shape applies:
+    // `mapArray`'s renderItem head `(__bfItem, __idx, __existing) =>`, or a
+    // lazy row plan's `const __bfItem = () => __e.item` binding
+    // (spec/slot-unification.md §9). Either way the destructured references
+    // below must read through the accessor, which is what this pins.
+    expect(clientJs).toMatch(/\(__bfItem, |const __bfItem = \(\) => __e\.item/)
     expect(clientJs).not.toContain('const [, cfg] = __bfItem();')
     expect(clientJs).toContain('__bfItem()[1].color')
   })
@@ -247,7 +256,7 @@ describe('Solid-style wrap-by-default fallback for loops (#943)', () => {
     `
 
     const clientJs = getClientJs(source, 'Shelf.tsx')
-    expect(clientJs).toContain('mapArray(')
+    expect(clientJs).toMatch(/\bmapArray(Lazy)?\(/)
     expect(clientJs).toContain('listOf()')
   })
 
@@ -278,8 +287,13 @@ describe('Solid-style wrap-by-default fallback for loops (#943)', () => {
     `
 
     const clientJs = getClientJs(source, 'TypedLegend.tsx')
-    expect(clientJs).toContain('mapArray(')
-    expect(clientJs).toContain('(__bfItem, ')
+    expect(clientJs).toMatch(/\bmapArray(Lazy)?\(/)
+    // The synthetic accessor param, in whichever reconciler shape applies:
+    // `mapArray`'s renderItem head `(__bfItem, __idx, __existing) =>`, or a
+    // lazy row plan's `const __bfItem = () => __e.item` binding
+    // (spec/slot-unification.md §9). Either way the destructured references
+    // below must read through the accessor, which is what this pins.
+    expect(clientJs).toMatch(/\(__bfItem, |const __bfItem = \(\) => __e\.item/)
     expect(clientJs).not.toContain('const [, cfg] = __bfItem();')
     expect(clientJs).toContain('__bfItem()[1].color')
   })
@@ -309,8 +323,13 @@ describe('Solid-style wrap-by-default fallback for loops (#943)', () => {
     `
 
     const clientJs = getClientJs(source, 'Fields.tsx')
-    expect(clientJs).toContain('mapArray(')
-    expect(clientJs).toContain('(__bfItem, ')
+    expect(clientJs).toMatch(/\bmapArray(Lazy)?\(/)
+    // The synthetic accessor param, in whichever reconciler shape applies:
+    // `mapArray`'s renderItem head `(__bfItem, __idx, __existing) =>`, or a
+    // lazy row plan's `const __bfItem = () => __e.item` binding
+    // (spec/slot-unification.md §9). Either way the destructured references
+    // below must read through the accessor, which is what this pins.
+    expect(clientJs).toMatch(/\(__bfItem, |const __bfItem = \(\) => __e\.item/)
     expect(clientJs).not.toContain('const { label, value } = __bfItem();')
     expect(clientJs).toContain('__bfItem().label')
     expect(clientJs).toContain('__bfItem().value')

package/src/__tests__/loop-hoisted-template.test.ts

@@ -72,16 +72,20 @@ describe('hoisted loop-body skeleton template (perf)', () => {
     `
     const { clientJs, template } = compile(source, 'Bench.tsx')
 
-    // Hoisted declaration present, before the mapArray call.
+    // Hoisted declaration present, before the reconciler call. This row shape
+    // is also lazy-row-eligible (spec/slot-unification.md §9.4), so the
+    // reconciler is `mapArrayLazy` and the clone happens in the row plan's
+    // `createRow` rather than in a `mapArray` renderItem — the hoisting
+    // question this suite pins is orthogonal to which reconciler consumes it.
     const declIdx = clientJs.indexOf('.innerHTML = `<tr')
-    const mapArrayIdx = clientJs.indexOf('mapArray(')
+    const mapArrayIdx = clientJs.search(/\bmapArray(Lazy)?\(/)
     expect(declIdx).toBeGreaterThan(-1)
     expect(mapArrayIdx).toBeGreaterThan(-1)
     expect(declIdx).toBeLessThan(mapArrayIdx)
 
-    // renderItem clones from the hoisted template instead of re-parsing
+    // The row is built by cloning the hoisted template instead of re-parsing
     // innerHTML per row.
-    expect(clientJs).toMatch(/const __el = __existing \?\? __tpl_\w+\.content\.firstElementChild\.cloneNode\(true\)/)
+    expect(clientJs).toMatch(/const __el = __tpl_\w+\.content\.firstElementChild\.cloneNode\(true\)/)
 
     // The hoisted template itself carries no interpolations and no dynamic
     // `class` attribute (that's covered by the reactive-attr createEffect).
@@ -172,7 +176,7 @@ describe('hoisted loop-body skeleton template (perf)', () => {
       }
     `
     const { clientJs } = compile(source, 'SpreadList.tsx')
-    expect(clientJs).toContain('mapArray(')
+    expect(clientJs).toMatch(/\bmapArray(Lazy)?\(/)
     expect(clientJs).not.toMatch(/__tpl_\w+ = document\.createElement\('template'\)/)
   })
 
@@ -195,7 +199,7 @@ describe('hoisted loop-body skeleton template (perf)', () => {
       }
     `
     const { clientJs } = compile(source, 'Dots.tsx')
-    expect(clientJs).toContain('mapArray(')
+    expect(clientJs).toMatch(/\bmapArray(Lazy)?\(/)
     // A `<circle>` root with only dynamic attrs (all covered by reactive-attr
     // createEffects) and a literal `r="4"` is exactly the shape the fast path
     // proves safe — this DOES hoist, and it must wrap in a synthetic `<svg>`

package/src/__tests__/static-loop-csr-materialize.test.ts

@@ -95,7 +95,12 @@ describe('#1247 — static-loop CSR self-heal', () => {
       }
     `
     const clientJs = getClientJs(source, 'PropList.tsx')
-    expect(clientJs).toMatch(/\bmapArray\s*\(/)
+    // Either reconciler shape satisfies the point of this test — the loop must
+    // go through the keyed `mapArray` family, not the static `forEach` path.
+    // A keyed, single-root, conditional-free row over a prop array is
+    // lazy-row-eligible (spec/slot-unification.md §9.4), so it emits
+    // `mapArrayLazy`; widen (don't narrow) the assertion.
+    expect(clientJs).toMatch(/\bmapArray(Lazy)?\s*\(/)
     expect(clientJs).not.toMatch(/\.forEach\s*\(/)
   })
 

package/src/__tests__/type-only-import-leak.test.ts

@@ -0,0 +1,60 @@
+/**
+ * End-to-end compiler pin for issue #2432's minimal reproduction.
+ *
+ * `collectExternalImports` used to decide which imported specifiers to
+ * re-emit into generated client JS with a `\bname\b` text scan over the
+ * generated code, never consulting the PER-SPECIFIER `isTypeOnly` flag
+ * (only the whole-declaration `import type { ... }` flag). So
+ * `import { paperColor, type Theme } from '../lib/theme'` re-emitted
+ * `Theme` as a VALUE import whenever the word "Theme" merely appeared in
+ * the emitted code — here, as an object key (`{ Theme: 'テーマ' }`).
+ *
+ * The CLI's relative-import inliner then places every requested name in
+ * the target module's top-level IIFE `return { … }`. `Theme` is a
+ * type-only export with no runtime binding, so the `return` referenced an
+ * undeclared name — `ReferenceError: Theme is not defined` at load,
+ * which kills the *entire* page's client JS before hydrate ever runs.
+ * The failure is silent from the user's perspective: the SSR-rendered
+ * markup is already on screen, so the page looks fine even though no
+ * interactivity ever wires up. See piconic-ai/barefootjs#2432.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { TestAdapter } from '../adapters/test-adapter'
+
+const adapter = new TestAdapter()
+
+describe('type-only import leak (#2432)', () => {
+  test('a per-specifier type-only import is never re-emitted into client JS', () => {
+    const source = `
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      import { paperColor, type Theme } from '../lib/theme'
+
+      export function ThemedBadge() {
+        const labels = { Theme: 'テーマ' }
+        const [color, setColor] = createSignal(paperColor({ paper: '#fff' }))
+        return <div title={labels.Theme}>{color()}</div>
+      }
+    `
+
+    const result = compileJSX(source, 'ThemedBadge.tsx', { adapter })
+    expect(result.errors.filter(e => e.severity === 'error')).toHaveLength(0)
+
+    const clientJs = result.files.find(f => f.type === 'clientJs')
+    expect(clientJs).toBeDefined()
+    const code = clientJs!.content
+
+    // The value specifier survives as a real import.
+    expect(code).toContain("import { paperColor } from '../lib/theme'")
+
+    // No import statement anywhere in the bundle mentions `Theme` — the
+    // only legal destination for a value import of that name would be a
+    // binding that doesn't exist in the compiled `../lib/theme` module.
+    const importLines = code.split('\n').filter(line => line.trim().startsWith('import'))
+    for (const line of importLines) {
+      expect(line).not.toContain('Theme')
+    }
+  })
+})

package/src/analyzer.ts

@@ -3974,6 +3974,9 @@ function importsBrowserOnlyClientApi(ctx: AnalyzerContext): boolean {
     if (imp.source !== '@barefootjs/client') continue
     if (imp.isTypeOnly) continue
     for (const spec of imp.specifiers) {
+      // A per-specifier type-only import (`import { type onMount }`) is not
+      // a browser-only API use — it has no runtime binding (#2432).
+      if (spec.isTypeOnly) continue
       const importedName = spec.name
       if (BROWSER_ONLY_CLIENT_APIS.has(importedName)) return true
     }

package/src/compiler.ts

@@ -18,7 +18,7 @@ import { stripClientBuiltinImports } from './builtins.ts'
 import { generateClientJs, generateClientJsWithSourceMap, analyzeClientNeeds } from './ir-to-client-js/index.ts'
 import { decideClientOnlyElision } from './ir-to-client-js/client-only-elision.ts'
 import { emitModuleLevelDeclarations } from './ir-to-client-js/emit-module-level.ts'
-import { RUNTIME_MODULE, detectUsedImports as detectUsedImportsFromCode } from './ir-to-client-js/imports.ts'
+import { RUNTIME_MODULE, detectUsedImports as detectUsedImportsFromCode, makeValueUsageTest } from './ir-to-client-js/imports.ts'
 import { setActiveComponentScope, computeFileScope } from './ir-to-client-js/component-scope.ts'
 import { generateModuleExports, collectInlineExportedNames } from './module-exports.ts'
 import { applyCssLayerPrefix } from './css-layer-prefixer.ts'
@@ -583,6 +583,7 @@ export function compileJSX(
       // in the generated body (e.g. an initializer that calls an imported
       // helper: `createSignal(defaultValue())`).
       const externalImportLines: string[] = []
+      const isUsedAsValue = makeValueUsageTest(body)
       for (const imp of ctx.imports) {
         if (imp.isTypeOnly) continue
         if (imp.source === '@barefootjs/client' || imp.source === RUNTIME_MODULE) continue
@@ -591,7 +592,7 @@ export function compileJSX(
           continue
         }
         const used = imp.specifiers
-          .filter(s => !s.isDefault && !s.isNamespace && new RegExp(`\\b${s.alias || s.name}\\b`).test(body))
+          .filter(s => !s.isDefault && !s.isNamespace && !s.isTypeOnly && isUsedAsValue(s.alias || s.name))
           .map(s => s.alias ? `${s.name} as ${s.alias}` : s.name)
         if (used.length > 0) {
           externalImportLines.push(`import { ${used.join(', ')} } from '${imp.source}'`)
@@ -638,6 +639,9 @@ export function compileJSX(
       if (imp.isTypeOnly) continue
       if (!imp.source.startsWith('./') && !imp.source.startsWith('../')) continue
       for (const spec of imp.specifiers) {
+        // A type-only specifier must not force a `.client.js` source
+        // rewrite — it has no runtime binding (#2432).
+        if (spec.isTypeOnly) continue
         if (ctx.importedClientSignalNames.has(spec.alias ?? spec.name)) {
           sources.add(imp.source)
           break

package/src/errors.ts

@@ -53,6 +53,14 @@ export const ErrorCodes = {
   // or an undeclared component — fail loud with the import to add.
   BUILTIN_REQUIRES_IMPORT: 'BF054',
 
+  // A relative `.ts` module inlined into a client bundle (`resolveRelativeImports`'s
+  // top-level IIFE wrap) was asked for a name it does not export. The IIFE's
+  // `return { … }` has no binding for that name, so the reference throws
+  // `ReferenceError: <name> is not defined` at load — killing the page's
+  // client JS before hydrate. Fail the build instead of shipping the
+  // dangling reference (#2432).
+  INLINED_IMPORT_MISSING_EXPORT: 'BF055',
+
   // Init statement errors (BF052)
   UNDECLARED_INIT_STATEMENT_REFERENCE: 'BF052',
 
@@ -155,6 +163,9 @@ const errorMessages: Record<ErrorCode, string> = {
   [ErrorCodes.STRIPPED_CLIENT_IMPORT_REFERENCED]:
     "Import was stripped from the client bundle but its binding is still referenced. Client components ('use client' .tsx) are not callable as plain functions from imperative .ts modules — render them as JSX from a 'use client' parent instead. If the flagged name is a local shadow rather than the stripped import, please file an issue.",
 
+  [ErrorCodes.INLINED_IMPORT_MISSING_EXPORT]:
+    'An inlined relative import requests a name the target module does not export. The client bundle would throw ReferenceError at load.',
+
   [ErrorCodes.STAGE_REACTIVE_IN_TEMPLATE]:
     'Reactive binding (signal getter or memo) referenced from template scope. The template lambda runs at module scope without the reactive context, so the value cannot be evaluated at SSR. Wrap the JSX expression in /* @client */ to defer it to hydrate, or restructure so the template uses a prop or static value.',
 

package/src/index.ts

@@ -320,6 +320,10 @@ export {
 // Errors
 export { ErrorCodes, createError, formatError, generateCodeFrame } from './errors.ts'
 
+// Value-reference classifier (#2432) — shared "is this a real value use"
+// door for import-emission sites and the CLI's stripped-reference scan.
+export { isValueReferenceIdentifier, collectValueReferencedNames } from './value-references.ts'
+
 // Expression Parser
 export { parseExpression, tsNodeToParsedExpr, asCallbackMethodCall, CALLBACK_METHODS, sortComparatorFromArrow, serializeParsedExpr, freeVarsInBody, freeIdentifiers, materializeGetterCalls, isSupported, exprToString, stringifyParsedExpr, identifierPath, parseBlockBody, parseBlockBodyTolerant, foldBlockToExpr, predicateTernaryToLogical, containsHigherOrder, extractArrowBodyExpression, parseStyleObjectEntries, hasUnsafeStyleValue, parseProviderObjectLiteral, type ProviderObjectMember, type FoldBlockOptions } from './expression-parser.ts'
 export type { StyleObjectEntry } from './expression-parser.ts'

package/src/ir-to-client-js/collect-elements.ts

@@ -1413,19 +1413,54 @@ function summarizeLoopChildBranch(
     // on the branch root yields exactly this branch's direct bindings
     // without re-collecting what a nested arm already owns (#2347).
     reactiveAttrs: collectLoopChildReactiveAttrs(node, ctx, loopParam, loopParamBindings, true),
-    // Skip when the branch's ENTIRE content is a single bare `expression`
-    // (no wrapping element) — e.g. a hoisted `renderNode={(n) => <Pill/>}`
-    // callback (#1211/#1213). That value is already fully re-evaluated and
-    // spliced via `__bfSlot` whenever `insert()` (re-)mounts this branch;
-    // an *additional* nested createEffect for the same expression re-calls
-    // it and creates a second, independent live element (a JSX-callback
-    // result isn't idempotent to re-invoke the way a plain signal read is),
-    // and the loop-child arm's `$t()`-based anchor lookup — designed for
-    // text nodes — doesn't cleanly displace an already-mounted Element,
-    // so the second instance lands beside the first instead of replacing
-    // it. A text *nested inside* a static wrapper element in the branch
-    // (the element-descent case) is unaffected and still collected below.
-    reactiveTexts: node.type === 'expression'
+    // Skip ONLY when the branch's entire content is a single bare
+    // `expression` (no wrapping element) that MAY yield a live DOM node —
+    // i.e. it contains a call anywhere (`node.hasFunctionCalls`, computed
+    // by the AST walk in `exprHasFunctionCalls`/jsx-to-ir.ts, recursively —
+    // catches a call nested in a template literal or a nested ternary, not
+    // just a top-level call). A call can return an Element (a hoisted
+    // `renderNode={(n) => <Pill/>}` callback lowered to a component call,
+    // #1211/#1213) and the compiler cannot tell from syntax whether it does
+    // — both `renderChild(...)` and `_p.renderCell(...)` are a
+    // `CallExpression` — so this stays conservative for ANY call, not just
+    // ones known to return JSX. Re-evaluating a non-idempotent call inside
+    // an *additional* nested createEffect (on top of the eval already done
+    // for the `__bfSlot`-wrapped splice whenever `insert()` (re-)mounts this
+    // branch) would call it again on every unrelated tick and discard the
+    // previous element's listeners/state.
+    //
+    // Everything else — a property access (`row.label`), an identifier, a
+    // literal, a template literal, string concatenation, or a nested
+    // ternary of those — cannot itself construct a DOM node (only a JSX
+    // literal or a call can, and a JSX literal branch is never `type:
+    // 'expression'` in the first place — see `transformJsxExpression`), so
+    // it is safe to collect. This is the fix for the loop-branch-stale-text
+    // defect: a keyed loop row whose branch is e.g. `row.done ? row.label :
+    // 'pending'` previously had NO update path at all when `row.label`
+    // changed without `row.done` flipping — `insert()` (runtime/insert.ts)
+    // correctly no-ops when its condition is unchanged (branch-internal
+    // updates are deliberately the effect system's job, not DOM
+    // replacement's), but with reactiveTexts always `[]` for this shape,
+    // no effect existed either, so the branch was frozen at its mount-time
+    // value. The stale rationale in a prior version of this comment blamed
+    // "the loop-child arm's `$t()`-based anchor lookup", but `$t()` no
+    // longer exists — it was one of four content mechanisms deleted by the
+    // slot-unification work. The current claim door
+    // (`stringifyLoopChildArm` → `lazySlots(..., kind: 'markup')` →
+    // `writeMarkup`, runtime/claim-slots.ts) clears the claimed range and
+    // splices the Node by identity, so "lands beside the first" cannot
+    // happen through it; only the call's non-idempotence still applies, and
+    // that alone is why the skip narrows rather than disappears.
+    //
+    // Collecting here is necessary but not sufficient: `n.slotId` must also
+    // be set for `collectLoopChildReactiveTexts` (ir-to-client-js/
+    // reactivity.ts) to do anything — see `transformConditionalBranch`'s
+    // `refsLoopParam` check (jsx-to-ir.ts) for the matching half of this fix
+    // that gives a bare loop-item-reading branch a slotId at all, which also
+    // makes `irToHtmlTemplate` emit its `<!--bf:sN-->…<!--/-->` marker (the
+    // same call builds both the SSR and the CSR/hydration template, so the
+    // two can't disagree on shape).
+    reactiveTexts: node.type === 'expression' && node.hasFunctionCalls
       ? []
       : collectLoopChildReactiveTexts(node, ctx, loopParam, loopParamBindings, true),
   }

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

@@ -18,6 +18,7 @@
 import type { CompositeLoopPlan, LoopChildRefBinding, PreambleRegionPlan } from './loop.ts'
 import type { EventDelegationPlan } from './event-delegation.ts'
 import type { ReactiveEffectsPlan } from './reactive-effects.ts'
+import type { LazyRowPlanData } from './build-lazy-row.ts'
 
 export interface BranchPlainLoopPlan {
   /**
@@ -89,6 +90,11 @@ export interface BranchPlainLoopPlan {
    * renderItem layout, mirroring the top-level plain plan.
    */
   preambleRegions: readonly PreambleRegionPlan[]
+  /**
+   * Lazy row graph plan (`spec/slot-unification.md` §9, L3) — see
+   * `PlainLoopVariant.lazyRow`. Undefined ⇒ today's eager emission.
+   */
+  lazyRow?: LazyRowPlanData
 }
 
 export interface BranchCompositeLoopPlan {

package/src/ir-to-client-js/control-flow/plan/build-branch-loop.ts

@@ -15,6 +15,8 @@ import { buildChainedArrayExpr, varSlotId, wrapLoopParamAsAccessor } from '../..
 import { buildBranchCompositePlan } from './build-composite-loop.ts'
 import { buildBranchLoopDelegationPlan } from './build-event-delegation.ts'
 import { buildReactiveEffectsPlan } from './build-reactive-effects.ts'
+import { buildLazyRowPlan } from './build-lazy-row.ts'
+import type { LazyRowScopeInfo } from './lazy-row-eligibility.ts'
 import { destructureLoopParam, loopKeyFn, buildChildRefBindings, buildPreambleRegionPlans } from '../shared.ts'
 import { renderPreamble, irToHtmlTemplate } from '../../html-template.ts'
 import type {
@@ -23,7 +25,11 @@ import type {
   BranchPlainLoopPlan,
 } from './branch-loop.ts'
 
-export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: string): BranchLoopPlan {
+export function buildBranchLoopPlan(
+  loop: BranchLoop,
+  profileComponentName?: string,
+  lazyScope?: LazyRowScopeInfo,
+): BranchLoopPlan {
   const containerSlotId = loop.containerSlotId
   const cv = varSlotId(containerSlotId)
   const containerVar = `__loop_${cv}`
@@ -45,6 +51,17 @@ export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: str
 
   // flatMap descriptor mode — see buildPlainLoopPlan (build-loop.ts).
   const fm = loop.flatMapClient
+  const arrayExpr = fm
+    ? `(${buildChainedArrayExpr(loop)}).flatMap(${fm.params} => ${fm.body})`
+    : buildChainedArrayExpr(loop)
+  const indexParam = loop.index || '__idx'
+  const mapPreambleWrapped = loop.preamble
+    ? renderPreamble(loop.preamble, {
+        transformJs: (t) => wrapLoopParamAsAccessor(t, loop.param, loop.paramBindings),
+        renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings }], undefined, true),
+      })
+    : ''
+  const preambleRegions = buildPreambleRegionPlans(loop.preambleRegions, loop.param, loop.paramBindings)
   const plan: BranchPlainLoopPlan = {
     kind: 'plain',
     rowConstruction: 'string-template',
@@ -52,23 +69,29 @@ export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: str
     containerVar,
     markerId: loop.markerId,
     flatMapLeafItem: fm ? true : undefined,
-    arrayExpr: fm
-      ? `(${buildChainedArrayExpr(loop)}).flatMap(${fm.params} => ${fm.body})`
-      : buildChainedArrayExpr(loop),
+    arrayExpr,
     keyFn: fm
       ? (fm.keyed ? '(__bfD, __bfI) => String(__bfD.k ?? __bfI)' : 'null')
       : loopKeyFn(loop),
     paramHead,
     paramUnwrap,
-    indexParam: loop.index || '__idx',
+    indexParam,
     // Wrap loop-param references to signal-accessor form so the preamble
     // matches the template literal's already-wrapped reads (#1065).
-    mapPreambleWrapped: loop.preamble
-      ? renderPreamble(loop.preamble, {
-          transformJs: (t) => wrapLoopParamAsAccessor(t, loop.param, loop.paramBindings),
-          renderLeaf: (ir) => irToHtmlTemplate(ir, undefined, 1, [{ param: loop.param, bindings: loop.paramBindings }], undefined, true),
-        })
-      : '',
+    mapPreambleWrapped,
+    // Lazy row graph (§9, L3) — undefined for every ineligible loop.
+    lazyRow: buildLazyRowPlan({
+      loop,
+      arrayExpr,
+      indexParam,
+      paramUnwrap,
+      mapPreambleWrapped,
+      preambleRegionCount: preambleRegions.length,
+      callSite: 'branch-plain',
+      flatMapLeafItem: Boolean(fm),
+      anchored: false,
+      scope: lazyScope,
+    }) ?? undefined,
     template: loop.template,
     reactiveEffects: hasReactiveEffects
       ? buildReactiveEffectsPlan({
@@ -82,7 +105,7 @@ export function buildBranchLoopPlan(loop: BranchLoop, profileComponentName?: str
       : null,
     eventDelegation: buildBranchLoopDelegationPlan(loop, cv, profileComponentName),
     childRefs: buildChildRefBindings(loop.bindings.refs, loop.param, loop.paramBindings),
-    preambleRegions: buildPreambleRegionPlans(loop.preambleRegions, loop.param, loop.paramBindings),
+    preambleRegions,
     bodyIsMultiRoot: loop.bodyIsMultiRoot ?? false,
     profileLoopId: profileComponentName ? `${profileComponentName}#binding:${containerSlotId}` : undefined,
   }

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

@@ -14,6 +14,7 @@ import type {
 } from '../../types.ts'
 import { addCondAttrToTemplate } from '../../html-template.ts'
 import { buildBranchLoopPlan } from './build-branch-loop.ts'
+import type { LazyRowScopeInfo } from './lazy-row-eligibility.ts'
 import type {
   InsertPlan,
   InsertArm,
@@ -26,6 +27,12 @@ export interface BuildInsertOptions {
   eventNameMode: 'dom' | 'raw'
   /** Owning component name in profile mode (#1690, SR3) — else undefined. */
   profileComponentName?: string
+  /**
+   * Component-scope name facts for the lazy row graph gate
+   * (`spec/slot-unification.md` §9.4). Threaded down to branch-scoped plain
+   * loops; omitted → those loops keep today's eager emission.
+   */
+  lazyScope?: LazyRowScopeInfo
 }
 
 export function buildInsertPlan(
@@ -88,13 +95,13 @@ function buildArmBody(branch: BranchSummary, options: BuildInsertOptions): ArmBo
       expression: t.expression,
     })),
     // Branch-scoped loops, fully Plan-built (Item 2 final migration).
-    loops: branch.loops.map(l => buildBranchLoopPlan(l, pc)),
+    loops: branch.loops.map(l => buildBranchLoopPlan(l, pc, options.lazyScope)),
     // Nested conditionals are themselves InsertPlans — built recursively so
     // the same stringifier handles arbitrary depth. Their scope is always
     // `__branchScope` (the parent arm's bindEvents argument), regardless of
     // the outer scope; only the eventNameMode is inherited.
     conditionals: branch.conditionals.map(c =>
-      buildInsertPlan(c, { scope: { kind: 'branchScope' }, eventNameMode: options.eventNameMode, profileComponentName: pc }),
+      buildInsertPlan(c, { scope: { kind: 'branchScope' }, eventNameMode: options.eventNameMode, profileComponentName: pc, lazyScope: options.lazyScope }),
     ),
   }
 }