@barefootjs/jsx 0.28.1 → 0.30.0

package/src/__tests__/preamble-attr-reactivity.test.ts

@@ -0,0 +1,217 @@
+/**
+ * An attribute reading a `.map()` callback preamble local is reactive — the
+ * #2447 follow-up.
+ *
+ * ## What was broken
+ *
+ * ```tsx
+ * {rows().map(row => {
+ *   const cls = row.done ? 'done' : 'open'
+ *   return <li key={row.id} class={cls}>{row.label}</li>
+ * })}
+ * ```
+ *
+ * `mapArray` reuses a row's DOM node on a same-key item update and re-runs
+ * only the wired slots. `class={cls}` was not one: `classifyReactivity` sees a
+ * bare local, not a signal or loop-param read, so it scored 'none' and the
+ * value was interpolated into the row template instead. Row 1's class stayed
+ * `open` after its item turned `done: true`, while the sibling `{row.label}`
+ * text updated normally — the child-position twin of this had already been
+ * fixed as a `preambleRegion` (#2389); the attribute position had not.
+ *
+ * ## The two halves, and why they are in different passes
+ *
+ *  1. **Phase 1 grants the slot** (`markPreambleAttrSlots`). An attribute is
+ *     only wirable if its element carries a `bf` slot id, and that is decided
+ *     when the element is BUILT — before the enclosing loop's preamble exists.
+ *     The client-JS pass cannot grant one retroactively: the SSR template is
+ *     rendered from this same IR and would not carry the marker.
+ *  2. **The client-JS pass wires it** (`collectLoopChildReactiveAttrs` +
+ *     `stringifyReactiveEffects`), re-running the preamble at the TOP of the
+ *     row effect so the declarations exist before the first write.
+ *
+ * ## The lazy row graph keeps the shape
+ *
+ * `lazyRowEligibility` used to refuse a binding that reads a preamble local,
+ * on the grounds that `applyOuter` could not prime a dependency the local
+ * hides. That refusal is gone: `analyzeLazyPreamble` now reports the
+ * preamble's own free identifiers and `classifyLazyBinding` substitutes them,
+ * so the binding's dependencies are what the INITIALIZER read (`selected`),
+ * and the apply bodies re-run the preamble on demand. Without that, this fix
+ * would have de-optimised the exact row the §9.5 widening was built for. The
+ * DOM behaviour is pinned in
+ * `packages/client/__tests__/runtime/lazy-row-preamble.test.ts`.
+ */
+
+import { describe, test, expect, beforeAll } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { TestAdapter } from '../adapters/test-adapter'
+import { analyzeComponent } from '../analyzer'
+import { jsxToIR } from '../jsx-to-ir'
+import type { IRElement, IRLoop, IRNode } from '../types'
+
+const ROWS = (row: string, preamble = `const cls = row.done ? 'done' : 'open'`) => `
+'use client'
+import { createSignal } from '@barefootjs/client'
+type Row = { id: number; label: string; done: boolean }
+export function Rows(props: { rows: Row[] }) {
+  const [rows, setRows] = createSignal<Row[]>(props.rows)
+  return (
+    <ul>
+      {rows().map(row => {
+        ${preamble}
+        return ${row}
+      })}
+    </ul>
+  )
+}
+`
+
+function clientJs(source: string, file = 'Rows.tsx'): string {
+  const r = compileJSX(source, file, { adapter: new TestAdapter() })
+  const errors = r.errors.filter(e => e.severity !== 'warning')
+  if (errors.length > 0) throw new Error(errors.map(e => `${e.code}: ${e.message}`).join('\n'))
+  const js = r.files.find(f => f.type === 'clientJs')?.content
+  if (!js) throw new Error('no client JS emitted')
+  return js
+}
+
+function findLoop(node: IRNode | null): IRLoop | null {
+  if (!node) return null
+  if (node.type === 'loop') return node
+  const kids = (node as IRElement).children
+  if (!Array.isArray(kids)) return null
+  for (const c of kids) {
+    const hit = findLoop(c)
+    if (hit) return hit
+  }
+  return null
+}
+
+/** The `<li>` row root of the compiled loop. */
+function rowRoot(source: string): IRElement {
+  const loop = findLoop(jsxToIR(analyzeComponent(source, 'Rows.tsx')))
+  if (!loop) throw new Error('no loop in IR')
+  return loop.children[0] as IRElement
+}
+
+beforeAll(() => {
+  // The first analyzeComponent in a process pays TS program setup on its own.
+  analyzeComponent(ROWS(`<li key={row.id}>{row.label}</li>`), 'Warmup.tsx')
+}, 60_000)
+
+describe('Phase 1 — the slot the attribute needs', () => {
+  test('an element whose attribute reads a preamble local gets a slot id', () => {
+    const li = rowRoot(ROWS(`<li key={row.id} class={cls}>{row.label}</li>`))
+    expect(li.slotId).not.toBeNull()
+  })
+
+  test('a row with no preamble-reading attribute is untouched', () => {
+    // The guard against granting slots (and shifting every later slot id) to
+    // rows that do not need one.
+    const li = rowRoot(ROWS(`<li key={row.id} class="static">{row.label}</li>`))
+    expect(li.slotId).toBeNull()
+  })
+
+  test('`key` never counts — it is renamed to data-key and driven by keyFn', () => {
+    const li = rowRoot(ROWS(`<li key={cls}>{row.label}</li>`))
+    expect(li.slotId).toBeNull()
+  })
+
+  test('a nested element gets its own slot, not the row root', () => {
+    const li = rowRoot(ROWS(`<li key={row.id}><span class={cls}>{row.label}</span></li>`))
+    expect(li.slotId).toBeNull()
+    expect((li.children[0] as IRElement).slotId).not.toBeNull()
+  })
+})
+
+describe('client JS — the attribute is wired, and the preamble precedes it', () => {
+  const js = clientJs(ROWS(`<li key={row.id} class={cls}>{row.label}</li>`))
+  const plan = js.slice(js.indexOf('mapArrayLazy('), js.indexOf(`}, 'l0')`))
+
+  test('the attribute is written by a binding, not baked into the row template', () => {
+    const tpl = js.slice(js.indexOf('__tpl_l0.innerHTML'), js.indexOf('mapArrayLazy('))
+    expect(tpl).not.toContain('class=')
+    expect(plan).toContain(`setAttribute('class', String(__v))`)
+  })
+
+  test('applyItem re-runs the preamble ahead of the write', () => {
+    const applyItem = plan.slice(plan.indexOf('applyItem:'))
+    const preambleAt = applyItem.indexOf("const cls = row().done ? 'done' : 'open'")
+    const writeAt = applyItem.indexOf(`setAttribute('class'`)
+    expect(preambleAt).toBeGreaterThanOrEqual(0)
+    expect(writeAt).toBeGreaterThan(preambleAt)
+  })
+
+  test('the row stays on the lazy graph — no per-row reactive resource', () => {
+    expect(js).toContain('mapArrayLazy(')
+    expect(js).not.toMatch(/\bmapArray\(/)
+    expect(plan).not.toContain('createEffect')
+    expect(plan).not.toContain('createRoot')
+  })
+
+  test('this row is item-driven only, so no applyOuter is emitted', () => {
+    // `row.done` is the only dependency. The contrast — a preamble reading an
+    // outer signal, which must reach the prime list — is
+    // `lazy-preamble.test.ts`'s `applyOuter` pair.
+    expect(plan).not.toContain('applyOuter:')
+  })
+})
+
+describe('a STATIC-ARRAY loop must NOT be wired', () => {
+  // Regression: the first cut of this change classified the attribute here
+  // too, and the emitted `static-array-child-init` `forEach` — which has no
+  // per-row body and so no preamble in scope — wrote
+  // `setAttribute('data-active', active ? …)` against a FREE VARIABLE. The
+  // ReferenceError killed the whole component's init, taking any nested child
+  // component's hydration with it. Caught by the gallery-nav e2e (the shells
+  // are exactly this shape and the badges mounted inside them vanished), and
+  // pinned here so the compiler catches it next time.
+  const NAV = `
+'use client'
+const NAV_ITEMS = [
+  { key: 'a', href: '/a', label: 'A' },
+  { key: 'b', href: '/b', label: 'B' },
+]
+export function Nav(props: { current: string }) {
+  return (
+    <nav>
+      {NAV_ITEMS.map(item => {
+        const active = item.key === props.current
+        return <a key={item.key} href={item.href} data-active={active ? 'true' : 'false'}>{item.label}</a>
+      })}
+    </nav>
+  )
+}
+`
+  const js = clientJs(NAV, 'Nav.tsx')
+
+  test('no attribute effect reads the preamble local', () => {
+    // The `data-active` write must not be emitted into the init body at all:
+    // there is no scope there that declares `active`. The sibling `href`
+    // effect IS emitted, which is what makes this a targeted decline rather
+    // than the whole loop going unwired.
+    const init = js.slice(0, js.indexOf(`hydrate('Nav'`))
+    expect(init).not.toContain(`setAttribute('data-active'`)
+    expect(init).toContain(`setAttribute('href'`)
+  })
+
+  test('the value stays baked into the SSR template', () => {
+    expect(js).toContain('data-active=')
+  })
+})
+
+describe('unaffected shapes keep their emission', () => {
+  test('a loop with no preamble emits no preamble statements', () => {
+    const js = clientJs(`
+'use client'
+import { createSignal } from '@barefootjs/client'
+type Row = { id: number; label: string; done: boolean }
+export function Plain(props: { rows: Row[] }) {
+  const [rows, setRows] = createSignal<Row[]>(props.rows)
+  return <ul>{rows().map(row => <li key={row.id} class={row.done ? 'done' : 'open'}>{row.label}</li>)}</ul>
+}
+`, 'Plain.tsx')
+    expect(js).not.toContain('const cls =')
+  })
+})

package/src/__tests__/preamble-declarations.test.ts

@@ -0,0 +1,207 @@
+/**
+ * `.map()` callback preamble → backend-neutral value declarations (#2447).
+ *
+ * ## What was broken
+ *
+ * A block-body `.map()` whose preamble computes a value used in the row
+ * (`const cls = row.done ? 'done' : 'open'`) carried that preamble only as
+ * `segments` — JS text, which a template language cannot execute. Every DSL
+ * adapter emitted the row anyway, reading a name it never assigned: ERB read
+ * `v[:cls]` (an unseeded vars-Hash key), Go read `$.Cls` (a PARENT-struct
+ * field), the rest read a bare undefined local. The class rendered empty, on
+ * eight backends, with no diagnostic — the exact silent divergence the
+ * sound-or-loud invariant forbids.
+ *
+ * ## The two halves pinned here
+ *
+ *  1. **Lowerable → carried.** `MapCallbackPreamble.declarations` holds one
+ *     `{ name, valueParsed }` per declaration, so each adapter emits it in its
+ *     own per-row local syntax through the `ParsedExpr` door it already has.
+ *  2. **Not lowerable → loud.** Anything that is not a sequence of value
+ *     declarations leaves `declarations` unset, and a DSL target refuses with
+ *     the `/* @client *\/` escape rather than emitting a row that reads
+ *     nothing. A JS runtime keeps running the preamble verbatim either way.
+ *
+ * All-or-nothing is the point of the shape assertions below: lowering the
+ * declarable prefix of a mixed preamble and dropping the rest would be a new
+ * silent divergence wearing the fix's clothes.
+ *
+ * The per-adapter emission is asserted end-to-end by the
+ * `loop-preamble-attr-value` conformance fixture (real ERB / Jinja / Twig /
+ * Blade / Kolon / Mojo / minijinja / Go renders vs. the JS reference), not
+ * here; this file pins the IR contract and the gate.
+ */
+
+import { describe, test, expect, beforeAll } from 'bun:test'
+import { analyzeComponent } from '../analyzer'
+import { jsxToIR } from '../jsx-to-ir'
+import { compileJSX } from '../compiler'
+import { TestAdapter } from '../adapters/test-adapter'
+import type { IRElement, IRLoop, IRNode } from '../types'
+
+const ROWS = (preamble: string, row = `<li key={r.id} class={cls}>{r.label}</li>`) => `
+'use client'
+import { createSignal } from '@barefootjs/client'
+type Row = { id: number; label: string; done: boolean }
+export function Rows(props: { rows: Row[] }) {
+  const [rows, setRows] = createSignal<Row[]>(props.rows)
+  return (
+    <ul>
+      {rows().map(r => {
+        ${preamble}
+        return ${row}
+      })}
+    </ul>
+  )
+}
+`
+
+function findLoop(node: IRNode | null): IRLoop | null {
+  if (!node) return null
+  if (node.type === 'loop') return node
+  const kids = (node as IRElement).children
+  if (!Array.isArray(kids)) return null
+  for (const c of kids) {
+    const hit = findLoop(c)
+    if (hit) return hit
+  }
+  return null
+}
+
+function loopOf(source: string): IRLoop {
+  const loop = findLoop(jsxToIR(analyzeComponent(source, 'Rows.tsx')))
+  if (!loop) throw new Error('no loop in IR')
+  return loop
+}
+
+/** Compile against a DSL-tier adapter (one that cannot run a callback body). */
+function dslErrors(source: string): string[] {
+  const adapter = new TestAdapter()
+  adapter.acceptsCallbackBody = () => false
+  return compileJSX(source, 'Rows.tsx', { adapter })
+    .errors.filter(e => e.severity !== 'warning')
+    .map(e => `${e.code}: ${e.message}`)
+}
+
+// The first `analyzeComponent` in a process pays the TS program setup, which
+// alone exceeds the default per-test timeout. Pay it once, outside a test.
+beforeAll(() => {
+  analyzeComponent(ROWS(`const warm = r.label`), 'Warmup.tsx')
+}, 60_000)
+
+describe('preamble value declarations — carried as neutral IR', () => {
+  test('a single ternary declaration', () => {
+    const loop = loopOf(ROWS(`const cls = r.done ? 'done' : 'open'`))
+    expect(loop.preamble?.declarations).toEqual([
+      expect.objectContaining({ name: 'cls', raw: `r.done ? 'done' : 'open'` }),
+    ])
+    expect(loop.preamble?.declarations?.[0].valueParsed.kind).toBe('conditional')
+  })
+
+  test('declarations keep SOURCE order, so a later one can read an earlier one', () => {
+    const loop = loopOf(`
+'use client'
+import { createSignal } from '@barefootjs/client'
+type Row = { id: number; label: string; done: boolean }
+export function Rows(props: { rows: Row[] }) {
+  const [rows, setRows] = createSignal<Row[]>(props.rows)
+  return (
+    <ul>
+      {rows().map(r => {
+        const base = r.done ? 'done' : 'open'
+        const cls = base + ' row'
+        return <li key={r.id} class={cls}>{r.label}</li>
+      })}
+    </ul>
+  )
+}
+`)
+    expect(loop.preamble?.declarations?.map(d => d.name)).toEqual(['base', 'cls'])
+  })
+
+  test('several declarators in one statement each become a declaration', () => {
+    const loop = loopOf(ROWS(`const a = r.label, b = r.id`))
+    expect(loop.preamble?.declarations?.map(d => d.name)).toEqual(['a', 'b'])
+  })
+
+  test('the names are loop-bound for the body, like a loop param', async () => {
+    // `collectLoopBoundNames` is what stops a same-named module const from
+    // inlining over the local the loop just declared.
+    const { collectLoopBoundNames } = await import('../adapters/loop-bound-names.ts')
+    const ctx = analyzeComponent(ROWS(`const cls = r.done ? 'done' : 'open'`), 'Rows.tsx')
+    const root = jsxToIR(ctx)
+    expect(root).not.toBeNull()
+    const names = collectLoopBoundNames({ ...ctx.componentIR!, root: root! })
+    expect(names.has('cls')).toBe(true)
+  })
+})
+
+describe('preamble value declarations — all-or-nothing', () => {
+  // Each of these has SOMETHING declarable in it. Carrying just that part and
+  // dropping the rest would put the missing statement's effect nowhere, with
+  // no diagnostic — so the whole preamble must decline.
+  const notDeclarable: Array<[string, string]> = [
+    ['an assignment after a declaration', `let n = 0\n        n = r.id`],
+    ['an imperative loop', `const out = []\n        for (const c of r.label) out.push(c)`],
+    ['a destructuring binding', `const { label } = r`],
+    ['a declaration with no initializer', `let cls\n        const other = r.label`],
+    [
+      'an initializer the expression subset cannot model',
+      `const cls = (() => r.done)()`,
+    ],
+  ]
+
+  for (const [name, preamble] of notDeclarable) {
+    test(name, () => {
+      const loop = loopOf(ROWS(preamble, `<li key={r.id}>{r.label}</li>`))
+      expect(loop.preamble).toBeDefined()
+      expect(loop.preamble?.declarations).toBeUndefined()
+    })
+  }
+})
+
+describe('the DSL gate — loud, not an empty attribute', () => {
+  test('a declarable preamble compiles clean on a DSL target', () => {
+    expect(dslErrors(ROWS(`const cls = r.done ? 'done' : 'open'`))).toEqual([])
+  })
+
+  test('a non-declarable preamble refuses, with the /* @client */ escape', () => {
+    const errors = dslErrors(
+      ROWS(`let n = 0\n        n = r.id`, `<li key={r.id}>{r.label}</li>`),
+    )
+    expect(errors.length).toBeGreaterThan(0)
+    expect(errors[0]).toMatch(/not a sequence of value declarations/)
+  })
+
+  test('a JS runtime runs the same preamble verbatim — no refusal', () => {
+    // The whole point of the per-backend fidelity model: the price is paid by
+    // the backend that genuinely cannot express the shape.
+    const r = compileJSX(
+      ROWS(`let n = 0\n        n = r.id`, `<li key={r.id}>{r.label}</li>`),
+      'Rows.tsx',
+      { adapter: new TestAdapter() },
+    )
+    expect(r.errors.filter(e => e.severity !== 'warning')).toEqual([])
+  })
+
+  test('/* @client */ silences the DSL refusal', () => {
+    const source = `
+'use client'
+import { createSignal } from '@barefootjs/client'
+type Row = { id: number; label: string; done: boolean }
+export function Rows(props: { rows: Row[] }) {
+  const [rows, setRows] = createSignal<Row[]>(props.rows)
+  return (
+    <ul>
+      {/* @client */ rows().map(r => {
+        let n = 0
+        n = r.id
+        return <li key={r.id}>{r.label}</li>
+      })}
+    </ul>
+  )
+}
+`
+    expect(dslErrors(source)).toEqual([])
+  })
+})

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

@@ -102,6 +102,50 @@ describe('extractSsrDefaults', () => {
     expect(defaults?.n).toEqual({ value: 0 })
   })
 
+  test('aliased destructured prop (#2460): `propName` is the CALLER-facing key, not the local binding', () => {
+    // `{ n: count }` — the caller passes `n`, the template variable (and
+    // stash entry key) is the local binding `count`. The manifest
+    // consumer (`_derive_stash_from_defaults` in the Perl runtime) reads
+    // the caller's props by `propName`, so `propName` must be `n`, not
+    // `count` — using the local name here silently drops the caller's
+    // value (the stash entry falls back to the static `value`, `null`).
+    const metadata = metadataFor(`
+      function Badge({ text, n: count }: { text: string; n: number }) {
+        return <span>{text}:{count}</span>
+      }
+    `)
+
+    const defaults = extractSsrDefaults(metadata)
+    expect(defaults).toBeDefined()
+    // Keyed by the LOCAL binding (the template variable name)...
+    expect(defaults?.count).toEqual({ propName: 'n', value: null })
+    // ...but `propName` is the CALLER-facing key.
+    expect(defaults?.text).toEqual({ propName: 'text', value: null })
+  })
+
+  test('aliased destructured prop with a default (#2460): `propName` still resolves to the source key', () => {
+    const metadata = metadataFor(`
+      function Badge({ n: count = 7 }: { n?: number }) {
+        return <span>{count}</span>
+      }
+    `)
+
+    const defaults = extractSsrDefaults(metadata)
+    expect(defaults?.count).toEqual({ propName: 'n', value: 7 })
+  })
+
+  test('un-aliased destructured prop (regression): `propName` equals the local name', () => {
+    const metadata = metadataFor(`
+      function Badge({ text, n }: { text: string; n: number }) {
+        return <span>{text}:{n}</span>
+      }
+    `)
+
+    const defaults = extractSsrDefaults(metadata)
+    expect(defaults?.n).toEqual({ propName: 'n', value: null })
+    expect(defaults?.text).toEqual({ propName: 'text', value: null })
+  })
+
   test('memo derived from a signal evaluates through the chain', () => {
     const metadata = metadataFor(`
       'use client'

package/src/__tests__/value-references.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Tests for `packages/jsx/src/value-references.ts` — the single-door
+ * "is this identifier a VALUE reference" classifier shared by
+ * `collectExternalImports` (jsx) and `detectStrippedReferences` (cli).
+ *
+ * There was no direct test file for this module before this one. It was
+ * added as a follow-up to #2432: a Copilot review on the original PR
+ * flagged that `ts.PropertyDeclaration` (class field) names were not
+ * excluded, so a class field like `helper` in `class C { helper = 1 }`
+ * was misclassified as a value reference. Harmless for the jsx-side
+ * caller (an extra kept import), but a false BF053 build error for the
+ * cli-side caller when the same name is a stripped import binding.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { collectValueReferencedNames } from '../value-references'
+
+describe('collectValueReferencedNames', () => {
+  test('class field name only is NOT a reference', () => {
+    const result = collectValueReferencedNames('class C { helper = 1 }')
+    expect(result).not.toBeNull()
+    expect(result?.has('helper')).toBe(false)
+  })
+
+  test('static class field name only is NOT a reference', () => {
+    const result = collectValueReferencedNames('class C { static helper = 1 }')
+    expect(result).not.toBeNull()
+    expect(result?.has('helper')).toBe(false)
+  })
+
+  test('computed class field name IS a reference (does not over-exclude)', () => {
+    const result = collectValueReferencedNames('class C { [helper] = 1 }')
+    expect(result).not.toBeNull()
+    expect(result?.has('helper')).toBe(true)
+  })
+
+  test('class method name is NOT a reference', () => {
+    const result = collectValueReferencedNames('class C { helper() {} }')
+    expect(result).not.toBeNull()
+    expect(result?.has('helper')).toBe(false)
+  })
+
+  test('object-literal key is NOT a reference', () => {
+    const result = collectValueReferencedNames('const o = { helper: 1 };')
+    expect(result).not.toBeNull()
+    expect(result?.has('helper')).toBe(false)
+  })
+
+  test('property access name is NOT a reference', () => {
+    const result = collectValueReferencedNames('obj.helper();')
+    expect(result).not.toBeNull()
+    expect(result?.has('helper')).toBe(false)
+  })
+
+  test('shorthand property IS a reference (reads the binding)', () => {
+    const result = collectValueReferencedNames('const o = { helper };')
+    expect(result).not.toBeNull()
+    expect(result?.has('helper')).toBe(true)
+  })
+
+  test('a genuine call IS a reference', () => {
+    const result = collectValueReferencedNames('helper();')
+    expect(result).not.toBeNull()
+    expect(result?.has('helper')).toBe(true)
+  })
+
+  test('new.target: "target" is NOT a reference', () => {
+    const result = collectValueReferencedNames('function f() { return new.target; }')
+    expect(result).not.toBeNull()
+    expect(result?.has('target')).toBe(false)
+  })
+
+  // Both halves of the MetaProperty exclusion are pinned: `new.target`
+  // above, and `import.meta` here — the one Copilot flagged as uncovered
+  // on #2439. `import.meta.url` also incidentally covers the
+  // property-access half (`url` is excluded too).
+  test('import.meta: "meta" is NOT a reference', () => {
+    const result = collectValueReferencedNames('const u = import.meta.url;')
+    expect(result).not.toBeNull()
+    expect(result?.has('meta')).toBe(false)
+    expect(result?.has('url')).toBe(false)
+  })
+
+  test('unparseable text returns null ("cannot answer")', () => {
+    const result = collectValueReferencedNames('const x = ;;; {{{ ]]]')
+    expect(result).toBeNull()
+  })
+})

package/src/adapters/child-scope.ts

@@ -0,0 +1,22 @@
+/**
+ * Whether a child component derives its `bf-s` scope id from its parent
+ * scope + mount slot (`${parentScopeId}_${slotId}`) rather than getting a
+ * freshly randomized one (`${name}_${random}`).
+ *
+ * A component derives from its slot unless it is the DIRECT root of a loop
+ * row (`IRComponent.loopItemRoot`, set once in `jsx-to-ir.ts`'s loop
+ * builder) — a row root owns its own per-row identity, matching Hono's
+ * reference behaviour (#2444). Every backend (Hono, each DSL adapter, and
+ * both CSR template emitters) MUST consult this single predicate instead of
+ * re-deriving the fact from a mutable "am I inside a loop" flag, which is
+ * what caused #2444: such flags stay true for an entire loop subtree and
+ * can't distinguish a row root from a component nested below it.
+ */
+
+import type { IRComponent } from '../types.ts'
+
+export function derivesScopeFromSlot(
+  comp: Pick<IRComponent, 'slotId' | 'loopItemRoot'>
+): boolean {
+  return comp.slotId != null && comp.loopItemRoot !== true
+}

package/src/adapters/loop-bound-names.ts

@@ -50,6 +50,12 @@ export function collectLoopBoundNames(ir: ComponentIR): Set<string> {
         // param (which may differ from the map callback's `param`) before
         // any rename to the loop param happens.
         if (node.filterPredicate) names.add(node.filterPredicate.param)
+        // A `.map()` callback preamble's declarations lower to per-row locals
+        // in the loop body on every DSL adapter (#2447), so a preamble name is
+        // bound in body scope exactly like a param — and must get the same
+        // exclusion, or a same-named module const would inline over the local
+        // the loop just declared.
+        for (const name of node.preamble?.declaredNames ?? []) names.add(name)
         for (const child of node.children) visit(child)
         if (node.childComponent) {
           for (const child of node.childComponent.children) visit(child)

package/src/analyzer-context.ts

@@ -448,6 +448,49 @@ export function typeNodeToTypeInfo(
     return { kind: 'array', raw, elementType: recurse(typeNode.elementType) }
   }
 
+  // Literal types (`'a'`, `42`, `-1`, `true`, `null`) — including as union
+  // members, which is where the absence of this arm hurt: `'a' | 'b'`
+  // members fell to `{kind:'unknown', raw:"'a'"}`, forcing every consumer
+  // that needed the member's family or value to re-parse `raw` with a
+  // regex (the Go adapter's literal-union collapse, #2324's
+  // `unionMemberLiteral`, `rich-type-evidence`'s nullish-arm match — all
+  // three carried one). A literal is structurally a primitive of its
+  // family carrying its value; consumers that only care about the family
+  // see a plain primitive, and the value rides along in `literalValue`
+  // for the ones that need it. `null` inside a union arrives as
+  // `LiteralTypeNode(NullKeyword)` — NOT the bare `NullKeyword` the
+  // switch above catches — which is exactly why nullish union arms were
+  // invisible before.
+  if (ts.isLiteralTypeNode(typeNode)) {
+    const lit = typeNode.literal
+    if (ts.isStringLiteral(lit) || ts.isNoSubstitutionTemplateLiteral(lit)) {
+      return { kind: 'primitive', raw, primitive: 'string', literalValue: lit.text }
+    }
+    if (ts.isNumericLiteral(lit)) {
+      return { kind: 'primitive', raw, primitive: 'number', literalValue: lit.text }
+    }
+    if (
+      ts.isPrefixUnaryExpression(lit) &&
+      lit.operator === ts.SyntaxKind.MinusToken &&
+      ts.isNumericLiteral(lit.operand)
+    ) {
+      return { kind: 'primitive', raw, primitive: 'number', literalValue: `-${lit.operand.text}` }
+    }
+    if (lit.kind === ts.SyntaxKind.TrueKeyword || lit.kind === ts.SyntaxKind.FalseKeyword) {
+      return {
+        kind: 'primitive',
+        raw,
+        primitive: 'boolean',
+        literalValue: lit.kind === ts.SyntaxKind.TrueKeyword ? 'true' : 'false',
+      }
+    }
+    if (lit.kind === ts.SyntaxKind.NullKeyword) {
+      return { kind: 'primitive', raw, primitive: 'null' }
+    }
+    // BigInt and anything newer: opaque, as before.
+    return { kind: 'unknown', raw }
+  }
+
   // Union types
   if (ts.isUnionTypeNode(typeNode)) {
     return { kind: 'union', raw, unionTypes: typeNode.types.map(recurse) }