@barefootjs/jsx 0.33.6 → 0.35.0

package/src/__tests__/safe-html-splice-door.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Direct unit tests for `spliceChildValue`'s arm order (#2795 follow-up).
+ *
+ * The door's arm order changed during the #2795 migration:
+ * `node.joinArrayChild` is now checked BEFORE `cx.branchSlotsVar`. Before,
+ * `irToHtmlTemplate` wrapped an array in `__bfSlot` first and joined after —
+ * for an element-array child (`{out}`, built by an arbitrary `.map()`
+ * preamble) rendered INSIDE a conditional branch, that would have handed
+ * `__bfSlot` the whole array-join expression, which stringifies an array
+ * argument via `String(...)`-style coercion internally rather than joining
+ * compiled-leaf HTML — corrupting already-escaped leaf markup. Joining first
+ * (the current order) hands `__bfSlot` a single already-assembled HTML
+ * string instead.
+ *
+ * PR #2858 shipped this reorder without a test exercising the co-occurrence
+ * (join-array-child AND branch-slot at once) — this file is that test,
+ * added directly against the door function rather than a full JSX compile,
+ * since the arm order is entirely `spliceChildValue`'s own concern.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { spliceChildValue } from '../ir-to-client-js/safe-html'
+
+describe('spliceChildValue arm order', () => {
+  test('joinArrayChild wins over branchSlotsVar — the array is joined, not handed to __bfSlot', () => {
+    const result = spliceChildValue(
+      { expr: 'out', slotId: null, joinArrayChild: true },
+      'out',
+      { branchSlotsVar: 'slots' },
+    )
+    expect(result).toBe(`Array.isArray(out) ? out.join('') : (out ?? '')`)
+    expect(result).not.toContain('__bfSlot')
+  })
+
+  test('branchSlotsVar alone (no joinArrayChild) still routes through __bfSlot', () => {
+    const result = spliceChildValue(
+      { expr: 'value', slotId: null, joinArrayChild: false },
+      'value',
+      { branchSlotsVar: 'slots' },
+    )
+    expect(result).toBe('__bfSlot(value, slots)')
+  })
+
+  test('neither joinArrayChild nor branchSlotsVar nor slotId nor children — plain escapeText default', () => {
+    const result = spliceChildValue(
+      { expr: 'label', slotId: null, joinArrayChild: false },
+      'label',
+      {},
+    )
+    expect(result).toBe('escapeText(label)')
+  })
+
+  test('a markup-claimed slotId still escapes-or-unwraps even with joinArrayChild absent', () => {
+    const result = spliceChildValue(
+      { expr: 'title', slotId: 's0', joinArrayChild: false },
+      '(title)',
+      { markupSlotIds: new Set(['s0']) },
+    )
+    expect(result).toBe('escapeTextOrMarkup((title))')
+  })
+})

package/src/__tests__/ssr-defaults.test.ts

@@ -499,6 +499,65 @@ describe('extractSsrDefaults', () => {
     // it does not abort the whole computation.
     expect(defaults?.x).toEqual({ value: [1, null] })
   })
+
+  // #2813 (pullfrog nitpick on the PR fixing it): a bare local-const alias
+  // of a signal getter must be seeded under its OWN name too, alongside
+  // the getter's — a template-stash adapter's `.map()` loop over
+  // `items__alias()` looks up the stash entry by that name, which the
+  // getter-name-only seeding above never creates.
+  test('a bare local-const alias of a signal getter is seeded under the alias name too', () => {
+    const metadata = metadataFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      function C() {
+        const [items] = createSignal([1, 2, 3])
+        const items__alias = items
+        return <ul>{items__alias().map(n => <li key={n}>{n}</li>)}</ul>
+      }
+    `)
+
+    const defaults = extractSsrDefaults(metadata)
+    expect(defaults?.items).toEqual({ value: [1, 2, 3] })
+    expect(defaults?.items__alias).toEqual({ value: [1, 2, 3] })
+  })
+
+  test('a multi-hop local-const alias chain resolves through every link', () => {
+    const metadata = metadataFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      function C() {
+        const [items] = createSignal([1, 2, 3])
+        const hop1 = items
+        const hop2 = hop1
+        return <ul>{hop2().map(n => <li key={n}>{n}</li>)}</ul>
+      }
+    `)
+
+    const defaults = extractSsrDefaults(metadata)
+    expect(defaults?.items).toEqual({ value: [1, 2, 3] })
+    expect(defaults?.hop1).toEqual({ value: [1, 2, 3] })
+    expect(defaults?.hop2).toEqual({ value: [1, 2, 3] })
+  })
+
+  test('a getter alias shares the ORIGIN entry object, including a self-derivation-collision propName shape', () => {
+    // The origin signal's OWN name collides with the prop its initializer
+    // derives from (#2669), so its entry is a propName-carrying prop
+    // entry, not a plain `{ value }` — the alias must share that exact
+    // shape (same object reference), not re-derive a plain value entry.
+    const metadata = metadataFor(`
+      'use client'
+      import { createSignal } from '@barefootjs/client'
+      function C(props: { label?: string }) {
+        const [label] = createSignal(props.label ?? 'Default')
+        const labelAlias = label
+        return <p>{labelAlias()}</p>
+      }
+    `)
+
+    const defaults = extractSsrDefaults(metadata)
+    expect(defaults?.label).toEqual({ propName: 'label', value: null })
+    expect(defaults?.labelAlias).toBe(defaults?.label)
+  })
 })
 
 // TS twin of the Ruby/Python/PHP/Perl/Rust `derive*FromDefaults` runtime

package/src/adapters/parsed-expr-emitter.ts

@@ -35,6 +35,7 @@
 
 import type { ParsedExpr, FlatDepth, TemplatePart, ObjectLiteralProperty } from '../expression-parser.ts'
 import { asCallbackMethodCall } from '../expression-parser.ts'
+import type { LoweringMatcher, LoweringNode } from '../lowering-registry.ts'
 
 export type HigherOrderMethod = 'filter' | 'every' | 'some' | 'find' | 'findIndex' | 'findLast' | 'findLastIndex'
 
@@ -95,6 +96,22 @@ export type SortMethod = 'sort' | 'toSorted'
 
 export type LiteralType = 'string' | 'number' | 'boolean' | 'null'
 
+/**
+ * An adapter's registered-lowering seam for the shared `call` dispatch
+ * (#2843). `matchers` are the same `ctx.state.loweringMatchers`-style list
+ * every adapter already binds at init; `render` maps one matched neutral
+ * node to this adapter's own template syntax (its body is typically what
+ * used to live inline in the adapter's `call()` method before this seam
+ * existed — see `renderLoweringNode` in the Go adapter's `url-builder.ts`
+ * for the shape). Returning null for a `kind`/`helper` this adapter has no
+ * mapping for lets the caller fall through to the ordinary `call()`
+ * dispatch, same as an unmatched call.
+ */
+export interface LoweringEmitter {
+  readonly matchers: readonly LoweringMatcher[]
+  render(node: LoweringNode, emit: (e: ParsedExpr) => string): string | null
+}
+
 /**
  * Adapter-side ParsedExpr lowering surface. One method per
  * `ParsedExpr.kind`. The shared `emitParsedExpr` runner dispatches
@@ -109,6 +126,17 @@ export interface ParsedExprEmitter {
   identifier(name: string): string
   literal(value: string | number | boolean | null, literalType: LiteralType): string
   call(callee: ParsedExpr, args: ParsedExpr[], emit: (e: ParsedExpr) => string): string
+  // Optional (#2843): when present, `emitParsedExpr`'s `call` case tries
+  // every matcher FIRST — before `call()` itself, and before the
+  // higher-order `callbackMethod` recognition — so a registered lowering
+  // plugin's call is recognised no matter where in an expression tree it
+  // sits (a ternary branch, a template-literal interpolation, a binary
+  // operand, …), not only when the adapter's own top-level conversion entry
+  // point happens to consult the registry directly. Omitted entirely by an
+  // adapter that hasn't adopted the seam (e.g. Go, which still consults the
+  // registry inline in its own `call()` per #2842) — behaviour is then
+  // byte-identical to before this field existed.
+  lowering?: LoweringEmitter
   // `optional` is true for a `?.`-written access (`user?.name`); see the
   // `ParsedExpr` `member` variant's docstring in `expression-parser.ts`
   // for the single-hop caveat. Every adapter's `member()` implementation
@@ -340,6 +368,21 @@ export function emitParsedExpr(expr: ParsedExpr, emitter: ParsedExprEmitter): st
     case 'literal':
       return emitter.literal(expr.value, expr.literalType)
     case 'call': {
+      // #2843: a registered lowering plugin's call wins in EVERY value
+      // position this dispatcher reaches, not only an adapter's own
+      // top-level conversion entry point — see `LoweringEmitter`'s doc.
+      // First-match-wins; a matched node whose `render` declines (helper id
+      // this adapter has no mapping for) falls through to the ordinary
+      // dispatch below, same as an unmatched call.
+      if (emitter.lowering) {
+        for (const matcher of emitter.lowering.matchers) {
+          const node = matcher(expr.callee, expr.args)
+          if (!node) continue
+          const rendered = emitter.lowering.render(node, emit)
+          if (rendered !== null) return rendered
+          break
+        }
+      }
       // A higher-order callback call (`arr.filter(p)` / `arr.sort(cmp)` / …)
       // routes to the dedicated `callbackMethod` arm; any other call is generic.
       const cb = asCallbackMethodCall(expr)

package/src/analyzer.ts

@@ -1998,6 +1998,9 @@ const CLIENT_EXPORTS = new Set([
   'forwardProps', 'unwrap', '__slot',
   'createContext', 'useContext', 'provideContext',
   'createPortal', 'isSSRPortal', 'findSiblingSlot', 'cleanupPortalPlaceholder',
+  // Floating-element position tracking (#2848) — same runtime-only shape
+  // as the portal entries above.
+  'trackPosition',
   // Request-scoped environment signal factory (router v0.5) — `createSignal`-
   // shaped, recognised structurally (#2057) so its getter is just a signal
   // getter; the compiler lowers the reader value per adapter via the signal's
@@ -4221,6 +4224,7 @@ export const BROWSER_ONLY_CLIENT_APIS = new Set([
   'isSSRPortal',
   'findSiblingSlot',
   'cleanupPortalPlaceholder',
+  'trackPosition',
 ])
 
 function importsBrowserOnlyClientApi(ctx: AnalyzerContext): boolean {

package/src/expression-parser.ts

@@ -7,6 +7,7 @@
  */
 
 import ts from 'typescript'
+import { loweringNodeChildren, type LoweringMatcher } from './lowering-registry.ts'
 
 // =============================================================================
 // Parsed Expression Types
@@ -1049,7 +1050,7 @@ function convertNode(node: ts.Node, raw: string): ParsedExpr {
             // surface — the depth must be *expressible*, even if not
             // known until render time.
             const parsedDepth = convertNode(depthNode, raw)
-            if (checkSupport(parsedDepth, 'rendered').supported) {
+            if (checkSupport(parsedDepth, 'rendered', []).supported) {
               depthExpr = parsedDepth
               flatDepth = 1 // unused placeholder — consumers must check `depthExpr` first
             } else {
@@ -2419,9 +2420,20 @@ function getUnaryOperatorString(op: ts.PrefixUnaryOperator): string {
  * reaches the page. See {@link isSupportedValue} for the sibling VALUE-
  * position entry point, and `checkSupport`'s `pos` parameter for why the two
  * never converge partway through a tree.
+ *
+ * `opts.loweringMatchers` (#2843), when given, lets a call recognised by a
+ * registered lowering plugin (`queryHref`, or any userland plugin) admit
+ * its params regardless of nesting position — a ternary branch, a
+ * template-literal interpolation, a binary operand, … — matching the
+ * top-level attribute path, which already consulted the same registry
+ * before this gate ever ran. Omit it (every existing caller does) for
+ * byte-identical prior behaviour.
  */
-export function isSupported(expr: ParsedExpr): SupportResult {
-  return checkSupport(expr, 'rendered')
+export function isSupported(
+  expr: ParsedExpr,
+  opts?: { loweringMatchers?: readonly LoweringMatcher[] },
+): SupportResult {
+  return checkSupport(expr, 'rendered', opts?.loweringMatchers ?? [])
 }
 
 /**
@@ -2430,10 +2442,13 @@ export function isSupported(expr: ParsedExpr): SupportResult {
  * assignment, never a render). The one behavioural difference from
  * {@link isSupported}: an `object-literal` anywhere in the tree is admitted
  * when every property value is itself supported, instead of being refused
- * outright.
+ * outright. See {@link isSupported}'s doc for `opts.loweringMatchers`.
  */
-export function isSupportedValue(expr: ParsedExpr): SupportResult {
-  return checkSupport(expr, 'value')
+export function isSupportedValue(
+  expr: ParsedExpr,
+  opts?: { loweringMatchers?: readonly LoweringMatcher[] },
+): SupportResult {
+  return checkSupport(expr, 'value', opts?.loweringMatchers ?? [])
 }
 
 /**
@@ -2453,7 +2468,7 @@ export function isSupportedValue(expr: ParsedExpr): SupportResult {
  */
 type ExprPos = 'rendered' | 'value'
 
-function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
+function checkSupport(expr: ParsedExpr, pos: ExprPos, matchers: readonly LoweringMatcher[]): SupportResult {
   switch (expr.kind) {
     case 'unsupported':
       return { supported: false, reason: expr.reason }
@@ -2471,7 +2486,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
         // A spread entry's SOURCE must itself be supported at `value`
         // position — the same criterion as an explicit property's value,
         // since the spread source is read (not rendered) at merge time.
-        const propSupport = checkSupport(prop.kind === 'spread' ? prop.expr : prop.value, pos)
+        const propSupport = checkSupport(prop.kind === 'spread' ? prop.expr : prop.value, pos, matchers)
         if (!propSupport.supported) return propSupport
       }
       return { supported: true, level: 'L2' }
@@ -2498,7 +2513,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // method, not here, because we can't see which adapter is consuming
       // the IR at this point.
       for (const el of expr.elements) {
-        const elSupport = checkSupport(el, pos)
+        const elSupport = checkSupport(el, pos, matchers)
         if (!elSupport.supported) return elSupport
       }
       return { supported: true, level: 'L2' }
@@ -2518,10 +2533,10 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
         }
       }
       // Receiver/args inherit `pos` (see `ExprPos`'s doc).
-      const objSupport = checkSupport(expr.object, pos)
+      const objSupport = checkSupport(expr.object, pos, matchers)
       if (!objSupport.supported) return objSupport
       for (const arg of expr.args) {
-        const argSupport = checkSupport(arg, pos)
+        const argSupport = checkSupport(arg, pos, matchers)
         if (!argSupport.supported) return argSupport
       }
       // A dynamic `.flat(depth)` carries its depth expression outside
@@ -2532,7 +2547,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // any `array-method`/`flat` node regardless of how it was constructed
       // (e.g. by a rewrite walker).
       if (expr.method === 'flat' && expr.depthExpr) {
-        const depthSupport = checkSupport(expr.depthExpr, pos)
+        const depthSupport = checkSupport(expr.depthExpr, pos, matchers)
         if (!depthSupport.supported) return depthSupport
       }
       return { supported: true, level: 'L2' }
@@ -2540,6 +2555,25 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
 
 
     case 'call': {
+      // #2843: a call a registered lowering plugin recognises (`queryHref`,
+      // or any userland plugin) is admitted regardless of where it sits in
+      // the tree — the neutral node's OWN children (`loweringNodeChildren`)
+      // are re-checked at the current `pos` instead of the call's raw
+      // `args`, so e.g. `queryHref`'s params object literal (refused at
+      // `rendered` position by the `object-literal` case above) doesn't
+      // reach that refusal at all: the plugin already took responsibility
+      // for it. Tried before `asCallbackMethodCall` and the generic per-arg
+      // loop below, matching the precedence the top-level attribute path
+      // already gives the registry.
+      for (const matcher of matchers) {
+        const node = matcher(expr.callee, expr.args)
+        if (!node) continue
+        for (const child of loweringNodeChildren(node)) {
+          const childSupport = checkSupport(child, pos, matchers)
+          if (!childSupport.supported) return childSupport
+        }
+        return { supported: true, level: 'L2' }
+      }
       // Higher-order callback methods (`.filter`/`.sort`/`.reduce`/… with an
       // arrow argument) lower via the runtime evaluator (#2018). Supported iff
       // the receiver and the callback BODY are supported. Recognised before the
@@ -2558,9 +2592,9 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // one (a signal/memo initializer) admits it.
       const cb = asCallbackMethodCall(expr)
       if (cb) {
-        const objSupport = checkSupport(cb.object, pos)
+        const objSupport = checkSupport(cb.object, pos, matchers)
         if (!objSupport.supported) return objSupport
-        const bodySupport = checkSupport(cb.arrow.body, pos)
+        const bodySupport = checkSupport(cb.arrow.body, pos, matchers)
         if (!bodySupport.supported) {
           return {
             supported: false,
@@ -2569,7 +2603,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
           }
         }
         for (const rest of cb.args) {
-          const restSupport = checkSupport(rest, pos)
+          const restSupport = checkSupport(rest, pos, matchers)
           if (!restSupport.supported) return restSupport
         }
         return { supported: true, level: 'L5' }
@@ -2577,7 +2611,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
 
       // Check if callee is supported. Not container contents — inherits
       // the CURRENT `pos` (see `ExprPos`'s doc).
-      const calleeSupport = checkSupport(expr.callee, pos)
+      const calleeSupport = checkSupport(expr.callee, pos, matchers)
       if (!calleeSupport.supported) {
         return calleeSupport
       }
@@ -2610,7 +2644,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // recognised callback/array-method (that path returned above) —
       // inherits the CURRENT `pos` (see `ExprPos`'s doc).
       for (const arg of expr.args) {
-        const argSupport = checkSupport(arg, pos)
+        const argSupport = checkSupport(arg, pos, matchers)
         if (!argSupport.supported) {
           return argSupport
         }
@@ -2620,7 +2654,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
 
     case 'member': {
       // Not container contents — inherits the CURRENT `pos`.
-      const objSupport = checkSupport(expr.object, pos)
+      const objSupport = checkSupport(expr.object, pos, matchers)
       if (!objSupport.supported) {
         return objSupport
       }
@@ -2636,9 +2670,9 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // expression are themselves supported (the index is typically a
       // loop variable or arithmetic over one). #1897 (data-table). Neither
       // is container contents — both inherit the CURRENT `pos`.
-      const objSupport = checkSupport(expr.object, pos)
+      const objSupport = checkSupport(expr.object, pos, matchers)
       if (!objSupport.supported) return objSupport
-      const indexSupport = checkSupport(expr.index, pos)
+      const indexSupport = checkSupport(expr.index, pos, matchers)
       if (!indexSupport.supported) return indexSupport
       return { supported: true, level: 'L2' }
     }
@@ -2646,9 +2680,9 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
     case 'binary': {
       // Operands inherit the CURRENT `pos` (see `ExprPos`'s doc) — a binary
       // operand isn't container contents.
-      const leftSupport = checkSupport(expr.left, pos)
+      const leftSupport = checkSupport(expr.left, pos, matchers)
       if (!leftSupport.supported) return leftSupport
-      const rightSupport = checkSupport(expr.right, pos)
+      const rightSupport = checkSupport(expr.right, pos, matchers)
       if (!rightSupport.supported) return rightSupport
 
       // Comparison operators are L3
@@ -2666,7 +2700,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
 
     case 'unary': {
       // Inherits the CURRENT `pos` — not container contents.
-      const argSupport = checkSupport(expr.argument, pos)
+      const argSupport = checkSupport(expr.argument, pos, matchers)
       if (!argSupport.supported) return argSupport
 
       // Negation is L4
@@ -2683,7 +2717,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
 
     case 'logical': {
       // Operands inherit the CURRENT `pos` — not container contents.
-      const leftSupport = checkSupport(expr.left, pos)
+      const leftSupport = checkSupport(expr.left, pos, matchers)
       if (!leftSupport.supported) return leftSupport
 
       // `x ?? {}` — admit an EMPTY object-literal fallback as the right
@@ -2710,7 +2744,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
         return { supported: true, level: 'L4' }
       }
 
-      const rightSupport = checkSupport(expr.right, pos)
+      const rightSupport = checkSupport(expr.right, pos, matchers)
       if (!rightSupport.supported) return rightSupport
 
       return { supported: true, level: 'L4' }
@@ -2722,11 +2756,11 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // position both branches are themselves rendered — `cond ? {a:1} :
       // {b:2}` stays refused there, not admitted just for being a
       // sub-expression.
-      const testSupport = checkSupport(expr.test, pos)
+      const testSupport = checkSupport(expr.test, pos, matchers)
       if (!testSupport.supported) return testSupport
-      const consSupport = checkSupport(expr.consequent, pos)
+      const consSupport = checkSupport(expr.consequent, pos, matchers)
       if (!consSupport.supported) return consSupport
-      const altSupport = checkSupport(expr.alternate, pos)
+      const altSupport = checkSupport(expr.alternate, pos, matchers)
       if (!altSupport.supported) return altSupport
 
       return { supported: true, level: 'L4' }
@@ -2738,7 +2772,7 @@ function checkSupport(expr: ParsedExpr, pos: ExprPos): SupportResult {
       // object-literal hole has no sensible rendering either way).
       for (const part of expr.parts) {
         if (part.type === 'expression') {
-          const partSupport = checkSupport(part.expr, pos)
+          const partSupport = checkSupport(part.expr, pos, matchers)
           if (!partSupport.supported) return partSupport
         }
       }

package/src/index.ts

@@ -11,10 +11,16 @@ export type { CompileResult, CompileOptions, CompileOptionsWithAdapter, FileOutp
 // SSR template-variable defaults (manifest seeds for stash-based adapters)
 export { extractSsrDefaults, deriveStashFromDefaults } from './ssr-defaults.ts'
 
-// Shared props-destructure binding + alias-map helpers (#2524)
-export { propsDestructureBinding, buildPropAliasMap, isIdentifierName } from './props-binding.ts'
+// Shared props-destructure binding + alias-map helpers (#2524, #2788)
+export { propsDestructureBinding, buildPropAliasMap, isIdentifierName, resolveBodyDestructuredPropAliases } from './props-binding.ts'
 export type { SsrDefault } from './ssr-defaults.ts'
 
+// Bare local-const alias-hop resolution for a signal/memo getter name
+// (`const items__alias = items`) — #2778's CSR-template fix, reused (not
+// re-walked) by SSR-side alias resolution (#2813: DSL stash seeding,
+// Go's zero-arg-call field routing).
+export { resolveGetterAliases, collectAliasableGetterNames } from './ir-to-client-js/csr-substitute.ts'
+
 // Import-alias resolution (#2777 client-JS registry key; #2822 SSR cross-template
 // call names) — a local alias -> declared/exported name map built from
 // `ir.metadata.imports`. DSL adapters build this once per compile and look up
@@ -101,7 +107,7 @@ export { JsxAdapter } from './adapters/jsx-adapter.ts'
 export type { JsxAdapterConfig } from './adapters/jsx-adapter.ts'
 export { rewriteImportsForTemplate, rewriteDynamicImportsInSource } from './adapters/template-imports.ts'
 export { emitParsedExpr, groupBinaryOperand, groupObjectLiteralSegments, isStringTypedOperand, isStringConcatBinary } from './adapters/parsed-expr-emitter.ts'
-export type { ParsedExprEmitter, HigherOrderMethod, ArrayMethod, SortMethod, LiteralType } from './adapters/parsed-expr-emitter.ts'
+export type { ParsedExprEmitter, LoweringEmitter, HigherOrderMethod, ArrayMethod, SortMethod, LiteralType } from './adapters/parsed-expr-emitter.ts'
 export { collectLoopBoundNames } from './adapters/loop-bound-names.ts'
 export { derivesScopeFromSlot } from './adapters/child-scope.ts'
 export { evaluateStaticLiteral, isFullyStaticLiteral, resolveStaticLoopSource } from './static-literal.ts'
@@ -114,6 +120,7 @@ export {
   prepareLoweringMatchers,
   matchLoweringCall,
   isValidHelperId,
+  loweringNodeChildren,
   __resetLoweringPluginsForTest,
   type LoweringPlugin,
   type LoweringNode,

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

@@ -309,7 +309,7 @@ export function collectInnerLoops(
         // Forward destructured bindings (#951) so inner-loop template
         // references to the destructured locals are rewritten.
         const loopParamsForTemplate = outerLoopParam
-          ? [outerLoopParam, { param: n.param, bindings: n.paramBindings }]
+          ? [outerLoopParam, { param: n.param, bindings: n.paramBindings, index: n.index }]
           : undefined
         const template = n.children.map(c => irToPlaceholderTemplate(c, undefined, emitDepth, loopParamsForTemplate)).join('')
         // Check if array expression references the outer loop param
@@ -755,6 +755,18 @@ export function collectElements(
         // avoiding post-hoc regex wrapping that corrupts literal attribute values.
         // Forward destructured bindings (#951) so references like `cfg.color`
         // in the emitted template literal are rewritten to `__bfItem()[1].color`.
+        // NOT `index: l.index` here (#2859 follow-up): this exact template
+        // string is reused verbatim by the LAZY row plan when this loop is
+        // lazy-eligible (`LazyRowPlanData`'s clone source, and — via
+        // `mapPreambleWrapped` — its `preambleStatements`) — `mapArrayLazy`'s
+        // `createRow(entry, index)` still hands the row a plain NUMBER
+        // (map-array-lazy.ts is untouched by #2859), so baking `i()` in here
+        // would call a number. Lazy-row eligibility only refuses a REACTIVE
+        // binding that references the index — a non-reactive use like a
+        // `data-key` built from the index is not gated the same way, so this
+        // can't assume "lazy-eligible ⇒ no index in the template" either.
+        // `buildPlainLoopPlan`/`buildBranchLoopPlan` apply the index wrap
+        // themselves, AFTER lazy eligibility is decided, only when it's `null`.
         const loopParamSpec = [{ param: l.param, bindings: l.paramBindings }]
         template = useElementReconciliation
           ? irToPlaceholderTemplate(l.children[0], resolveRestSpreadNames(ctx), 0, loopParamSpec)
@@ -1165,6 +1177,10 @@ function collectBranchLoops(
       // keeping the template consistent with reactive effect expressions that
       // use `param()` to read the current item value.
       let childTemplate: string
+      // NOT `index: n.index` here — see the identical note on `loopParamSpec`
+      // above; `BranchLoop.template` is reused verbatim by the lazy row plan
+      // too (`callSite: 'branch-plain'`), and `buildBranchLoopPlan` applies
+      // the index wrap itself once lazy eligibility is known (#2859 follow-up).
       const branchLoopParamSpec = [{ param: n.param, bindings: n.paramBindings }]
       if (projectionInner) {
         childTemplate = '' // descriptor renderItem builds from d.h, not a row template
@@ -1478,7 +1494,7 @@ export function collectLoopChildConditionals(
       if (!readsPreamble && classifyReactivity(expanded.expr, ctx, loopParam, loopParamBindings, expanded.freeIds).kind === 'none') return
 
       const loopParamsForCond = loopParam
-        ? [{ param: loopParam, bindings: loopParamBindings }]
+        ? [{ param: loopParam, bindings: loopParamBindings, index: loopIndex }]
         : undefined
       // `__slots` matches the closure variable emitted by
       // `stringifyLoopChildConditional` — Child-position interpolations

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

@@ -11,14 +11,13 @@
  */
 
 import type { BranchLoop } from '../../types.ts'
-import { buildChainedArrayExpr, varSlotId, wrapLoopParamAsAccessor } from '../../utils.ts'
+import { buildChainedArrayExpr, varSlotId } from '../../utils.ts'
 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 { buildPlainRowCore } from './build-plain-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 { loopKeyFn, buildChildRefBindings } from '../shared.ts'
 import type {
   BranchCompositeLoopPlan,
   BranchLoopPlan,
@@ -44,7 +43,6 @@ export function buildBranchLoopPlan(
     return composite
   }
 
-  const { head: paramHead, unwrap: paramUnwrap } = destructureLoopParam(loop.param, loop.paramBindings)
   const hasReactiveEffects = loop.bindings.reactiveAttrs.length > 0
     || loop.bindings.reactiveTexts.length > 0
     || loop.bindings.conditionals.length > 0
@@ -54,14 +52,18 @@ export function buildBranchLoopPlan(
   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),
-      })
-    : ''
-  const preambleRegions = buildPreambleRegionPlans(loop.preambleRegions, loop.param, loop.paramBindings)
+
+  // Shared "wrap item → decide lazy → wrap index" core (#2859 follow-up) —
+  // see `build-plain-row.ts`'s module docstring for the full rationale.
+  const core = buildPlainRowCore({
+    loop,
+    arrayExpr,
+    callSite: 'branch-plain',
+    flatMapLeafItem: Boolean(fm),
+    anchored: false,
+    scope: lazyScope,
+  })
+  const { paramHead, paramUnwrap, indexParam, preambleRegions, lazyRow } = core
   const plan: BranchPlainLoopPlan = {
     kind: 'plain',
     rowConstruction: 'string-template',
@@ -78,21 +80,10 @@ export function buildBranchLoopPlan(
     indexParam,
     // Wrap loop-param references to signal-accessor form so the preamble
     // matches the template literal's already-wrapped reads (#1065).
-    mapPreambleWrapped,
+    mapPreambleWrapped: core.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,
+    lazyRow,
+    template: core.template,
     reactiveEffects: hasReactiveEffects
       ? buildReactiveEffectsPlan({
           attrs: loop.bindings.reactiveAttrs,
@@ -100,11 +91,12 @@ export function buildBranchLoopPlan(
           conditionals: loop.bindings.conditionals,
           loopParam: loop.param,
           loopParamBindings: loop.paramBindings,
+          loopIndex: loop.index,
           profileComponentName,
         })
       : null,
     eventDelegation: buildBranchLoopDelegationPlan(loop, cv, profileComponentName),
-    childRefs: buildChildRefBindings(loop.bindings.refs, loop.param, loop.paramBindings),
+    childRefs: buildChildRefBindings(loop.bindings.refs, loop.param, loop.paramBindings, loop.index),
     preambleRegions,
     bodyIsMultiRoot: loop.bodyIsMultiRoot ?? false,
     profileLoopId: profileComponentName ? `${profileComponentName}#binding:${containerSlotId}` : undefined,