@barefootjs/jsx 0.31.1 → 0.31.3

package/src/prop-rewrite.ts

@@ -14,7 +14,7 @@
  * stack, so `items.map((title) => title.a)` never turns into the
  * syntactically invalid `.map((_p.title) => _p.title.a)` when `title`
  * is also a prop. (Names bound by loop callbacks that ENCLOSE the
- * expression are the caller's job — see the `ctx.loopParams` filter in
+ * expression are the caller's job — see the `ctx.scope` filter in
  * `jsx-to-ir.ts`'s `rewriteBarePropRefs` wrapper, #2222.)
  */
 
@@ -135,7 +135,11 @@ export function collectAstPropRefs(
  * Returns null when `text` does not parse cleanly as an expression —
  * the caller falls back to the legacy regex rewrite.
  */
-function applyScopedPropRefRewrite(text: string, propRefs: Set<string>): string | null {
+function applyScopedPropRefRewrite(
+  text: string,
+  propRefs: Set<string>,
+  propAliases?: ReadonlyMap<string, string>,
+): string | null {
   // Wrap in parens so object literals and arrows parse as expressions.
   const prefix = '('
   const sf = ts.createSourceFile('__bf_prop_rewrite.ts', `${prefix}${text}\n)`, ts.ScriptTarget.Latest, true)
@@ -149,11 +153,15 @@ function applyScopedPropRefRewrite(text: string, propRefs: Set<string>): string
     const start = n.getStart(sf) - prefix.length
     const end = n.getEnd() - prefix.length
     if (start < 0 || end > text.length) return
+    // `_p` is always keyed by the caller-facing name (`sourceName ?? name`
+    // — #2524 CSR half); the local binding (`n.text`) only survives on the
+    // left of a shorthand expansion.
+    const callerKey = propAliases?.get(n.text) ?? n.text
     if (parent && ts.isShorthandPropertyAssignment(parent) && parent.name === n) {
-      edits.push({ start, end, replacement: `${n.text}: ${PROPS_PARAM}.${n.text}` })
+      edits.push({ start, end, replacement: `${n.text}: ${PROPS_PARAM}.${callerKey}` })
       return
     }
-    edits.push({ start, end, replacement: `${PROPS_PARAM}.${n.text}` })
+    edits.push({ start, end, replacement: `${PROPS_PARAM}.${callerKey}` })
   })
 
   if (edits.length === 0) return text
@@ -177,11 +185,14 @@ function applyScopedPropRefRewrite(text: string, propRefs: Set<string>): string
 export function applyRegexPropRefRewrite(
   text: string,
   propRefs: Iterable<string>,
+  propAliases?: ReadonlyMap<string, string>,
 ): string {
   const { protect, restore } = createTemplateAwareStringProtector()
   let result = protect(text)
 
   for (const propName of propRefs) {
+    // `_p` is always keyed by the caller-facing name (#2524 CSR half).
+    const callerKey = propAliases?.get(propName) ?? propName
     const pattern = new RegExp(`(?<!${PROPS_PARAM}\\.)(?<!['"\\w.-])\\b${propName}\\b(?![a-zA-Z0-9_$])`, 'g')
     result = result.replace(pattern, (match, offset, str) => {
       // Skip object literal keys: preceded by { or , and followed by :
@@ -190,7 +201,7 @@ export function applyRegexPropRefRewrite(
         const before = str.slice(0, offset)
         if (/[{,]\s*$/.test(before)) return match
       }
-      return `${PROPS_PARAM}.${propName}`
+      return `${PROPS_PARAM}.${callerKey}`
     })
   }
 
@@ -209,12 +220,18 @@ export function applyRegexPropRefRewrite(
  *   `text` was produced by inlining a branch-local whose initializer
  *   references the prop). The rewrite only touches genuine value
  *   references, so passing an over-broad set is safe.
+ * @param propAliases - Local name → caller-facing key (`sourceName ?? name`)
+ *   for aliased destructured props (`{ n: count }` → `count` → `n`).
+ *   `_p` is always keyed by the caller-facing name (#2524 CSR half); a name
+ *   absent from this map emits `_p.<name>` unchanged (the un-aliased case,
+ *   where `sourceName ?? name` is an identity).
  */
 export function rewriteBarePropRefs(
   text: string,
   node: ts.Node,
   propNames: Set<string>,
   extraPropRefs?: ReadonlySet<string>,
+  propAliases?: ReadonlyMap<string, string>,
 ): string | undefined {
   // Walk AST to find which prop names are actually used as value references
   const foundPropRefs = new Set<string>()
@@ -225,5 +242,8 @@ export function rewriteBarePropRefs(
     }
   }
   if (foundPropRefs.size === 0) return undefined
-  return applyScopedPropRefRewrite(text, foundPropRefs) ?? applyRegexPropRefRewrite(text, foundPropRefs)
+  return (
+    applyScopedPropRefRewrite(text, foundPropRefs, propAliases) ??
+    applyRegexPropRefRewrite(text, foundPropRefs, propAliases)
+  )
 }

package/src/props-binding.ts

@@ -0,0 +1,70 @@
+import ts from 'typescript'
+import type { ParamInfo } from './types.ts'
+
+/**
+ * Authoritative IdentifierName classification for a destructure-pattern
+ * property key, built on TS's own `isIdentifierStart` / `isIdentifierPart`
+ * primitives (Unicode-aware, stays aligned with what TS itself accepts as
+ * a bare property key). Mirrors the `isIdent` precedent in
+ * `jsx-to-ir.ts` (#1244) — a source key like `data-key` or `aria-label`
+ * can't be emitted as a bare `key: local` destructure and must be quoted
+ * (`"data-key": local`).
+ */
+export function isIdentifierName(key: string): boolean {
+  if (key.length === 0) return false
+  for (let i = 0; i < key.length; ) {
+    const cp = key.codePointAt(i)!
+    const ok = i === 0
+      ? ts.isIdentifierStart(cp, ts.ScriptTarget.Latest)
+      : ts.isIdentifierPart(cp, ts.ScriptTarget.Latest)
+    if (!ok) return false
+    i += cp > 0xFFFF ? 2 : 1
+  }
+  return true
+}
+
+/**
+ * The single destructure-binding renderer for a props param, shared by
+ * every JSX-runtime SSR adapter (Hono, TestAdapter). The caller-facing
+ * key is `sourceName ?? name` (ParamInfo's own rule) — `name` is only
+ * ever the LOCAL binding. Emits the plain shorthand when they match
+ * (byte-identical to the pre-rename-aware form); emits a `key: local`
+ * rename otherwise (b4f5075). This also covers the `class` → `className`
+ * rename: a source prop literally named `class` can only reach
+ * `propsParams` via an aliased destructure (`{ class: className }` —
+ * `class` is a reserved word, so it can never be an un-aliased binding),
+ * which sets `sourceName: 'class'` and takes the rename branch
+ * (`class: className`), not a bare `className`.
+ *
+ * One exported implementation, two consumers, zero drift — the
+ * hono/test-adapter pair carrying private copies is exactly the
+ * lockstep-rule duplication #2460/#2524 were about.
+ */
+export function propsDestructureBinding(p: ParamInfo): string {
+  const callerKey = p.sourceName ?? p.name
+  const localName = p.name
+  const binding = callerKey === localName
+    ? localName
+    : `${isIdentifierName(callerKey) ? callerKey : JSON.stringify(callerKey)}: ${localName}`
+  return p.defaultValue ? `${binding} = ${p.defaultValue}` : binding
+}
+
+/**
+ * Local-name → caller-facing-key map for prop-reference rewrites —
+ * entries only for `ParamInfo`s that actually rename (`sourceName` set,
+ * see its docstring in `types.ts`). `_p` is always keyed by the
+ * caller-facing name (#2524 CSR half); an un-aliased prop leaves no
+ * entry, so `map?.get(name) ?? name` degrades to an identity there.
+ * Returns `undefined` when nothing renames, so callers can
+ * short-circuit.
+ */
+export function buildPropAliasMap(params: readonly ParamInfo[]): Map<string, string> | undefined {
+  let map: Map<string, string> | undefined
+  for (const p of params) {
+    if (p.sourceName) {
+      if (!map) map = new Map()
+      map.set(p.name, p.sourceName)
+    }
+  }
+  return map
+}

package/src/relocate.ts

@@ -15,6 +15,7 @@ import type { Scope, BindingKind, IRMetadata } from './types.ts'
 import { isVisibleIn } from './types.ts'
 import type { AnalyzerContext } from './analyzer-context.ts'
 import { PROPS_PARAM } from './ir-to-client-js/utils.ts'
+import { buildPropAliasMap } from './props-binding.ts'
 import type {
   TemplatePrimitiveRegistry,
   TemplateCallAcceptor,
@@ -42,6 +43,15 @@ export interface RelocateEnv {
    * `TransformContext._destructuredPropNames`.
    */
   propsForLift: Set<string>
+  /**
+   * Local prop name → caller-facing key (`sourceName ?? name`), entries
+   * only for `ParamInfo`s that rename (`{ n: count }` → `count` → `n`).
+   * `_p` is always keyed by the caller-facing name (#2524 CSR half) — the
+   * `lift-to-prop` action reads this so `count` lifts to `_p.n`, not
+   * `_p.count`. A name absent from this map is un-aliased, so
+   * `propSourceNames.get(name) ?? name` degrades to an identity there.
+   */
+  propSourceNames: ReadonlyMap<string, string>
   /**
    * Name of the props parameter (e.g. `props`). Used to detect
    * `props.X` member access at lift sites — those are not free refs
@@ -179,8 +189,10 @@ function decideAction(
     if (env.propsObjectName !== null && name === env.propsObjectName) {
       return { action: 'lift-to-prop', rewrittenAs: PROPS_PARAM }
     }
-    // Lift `name` → `_p.name`.
-    return { action: 'lift-to-prop', rewrittenAs: `${PROPS_PARAM}.${name}` }
+    // Lift `name` → `_p.<caller-facing key>` — `_p` is always keyed by
+    // the caller-facing name (#2524 CSR half), not the local binding.
+    const callerKey = env.propSourceNames.get(name) ?? name
+    return { action: 'lift-to-prop', rewrittenAs: `${PROPS_PARAM}.${callerKey}` }
   }
 
   if ((kind === 'init-local' || kind === 'sub-init-local') && toScope === 'template') {
@@ -860,6 +872,10 @@ function buildRelocateEnvFromFields(src: EnvFields): RelocateEnv {
     if (kind === 'prop') propsForLift.add(name)
   }
 
+  // propSourceNames: local prop name → caller-facing key, entries only
+  // for `ParamInfo`s that actually rename. See `RelocateEnv.propSourceNames`.
+  const propSourceNames = buildPropAliasMap(src.propsParams) ?? new Map<string, string>()
+
   // aliasTargets (#2069 R2): one-hop alias resolution table for
   // `isCallAcceptedByAdapter`. A const whose FINAL resolved binding kind
   // is `init-local` or `module-local` (i.e. not a signal/memo/prop-alias
@@ -884,6 +900,7 @@ function buildRelocateEnvFromFields(src: EnvFields): RelocateEnv {
     bindings,
     inlinable: new Map(), // populated by compute-inlinability after analyzer runs
     propsForLift,
+    propSourceNames,
     propsObjectName,
     allowFallback: true,
     aliasTargets,

package/src/scope/binding-scope.ts

@@ -0,0 +1,238 @@
+/**
+ * `BindingScope`: the one shared, immutable, stack-shaped model of "names
+ * bound by a loop callback" (#2482 Stage 0). Six independent ad-hoc
+ * mechanisms across the compiler currently answer this same question —
+ * `ctx.loopParams` (a mutated `Set<string>` in `jsx-to-ir.ts`),
+ * `collectLoopBoundNames` (`adapters/loop-bound-names.ts`),
+ * `resolveStaticLoopSource`'s `isNameShadowed` callback
+ * (`static-literal.ts`), and others — each reimplementing the same
+ * item/index/destructure/preamble-local bookkeeping with its own bugs and
+ * its own blind spots. This module is the single door those mechanisms
+ * migrate onto in later stages (Stage 0 only ships the service + tests;
+ * NO call site is migrated yet).
+ *
+ * Immutability is the point, not an incidental style choice:
+ * `ctx.loopParams` is `.add`/`.delete`-mutated as `jsx-to-ir.ts` walks in
+ * and back out of nested loops, so a caller that forgets (or races) a
+ * `.delete()` — or that holds a reference to the "current" set across a
+ * push/pop it didn't expect — silently observes the WRONG scope. A
+ * restore-bug of that shape is impossible by construction here:
+ * `enterLoopRow`/`enterCallback` never mutate `this`, they return a NEW
+ * `BindingScope` whose parent is untouched, so holding an old reference
+ * always sees the scope as it was, and there is no delete step to forget.
+ *
+ * Filter/sort callback params (`.filter(x => ...)`, `.sort((a, b) => ...)`,
+ * a nested arrow) are bound as `'callback'` frames via `enterCallback` —
+ * never folded into a `'loop-row'` frame's bindings. They are a distinct
+ * scope-introduction shape (an inner function's own parameter list, not a
+ * row's item/index/destructure/preamble names) even though both end up
+ * "just names you can't resolve against component-level state."
+ */
+
+/**
+ * How a name inside a `ScopeFrame` came to be bound — the row shapes
+ * (`'item'`/`'index'`/`'destructure'`/`'preamble'`) for `'loop-row'` frames,
+ * `'param'` for `'callback'` frames. One shared type because both frame
+ * kinds carry the same binding metadata.
+ */
+export type ScopeBindingSource = 'item' | 'index' | 'destructure' | 'preamble' | 'param'
+
+export interface ScopeBinding {
+  readonly source: ScopeBindingSource
+}
+
+export interface ScopeFrame {
+  readonly kind: 'loop-row' | 'callback'
+  readonly bindings: ReadonlyMap<string, ScopeBinding>
+}
+
+/**
+ * Structural pick satisfied by BOTH `IRLoop` (`packages/jsx/src/types.ts`)
+ * and the client-JS `LoopCore` family (`packages/jsx/src/ir-to-client-js/types.ts`)
+ * without importing either — this module stays dependency-free and cannot
+ * form an import cycle with `types.ts` / `ir-to-client-js`.
+ */
+export interface LoopBindingSource {
+  readonly param: string
+  readonly index?: string | null
+  readonly paramBindings?: readonly { readonly name: string }[]
+  readonly preamble?: { readonly declaredNames: readonly string[] } | null
+}
+
+/**
+ * A stack of `ScopeFrame`s, innermost frame at index 0 of the internal
+ * array (i.e. `frames[0]` is what `enterLoopRow`/`enterCallback` most
+ * recently pushed). `lookup`'s `depth` counts from `frames[0]`, so depth 0
+ * always means "the innermost frame," independent of how many ancestor
+ * frames exist.
+ */
+export class BindingScope {
+  static readonly EMPTY: BindingScope = new BindingScope([])
+
+  private constructor(private readonly frames: readonly ScopeFrame[]) {}
+
+  /**
+   * Child scope with a new `'loop-row'` frame for one loop's per-item
+   * bindings. Parent (`this`) is not mutated; the returned scope is a
+   * NEW object with `frames = [newFrame, ...this.frames]`.
+   *
+   * Binding semantics mirror `jsx-to-ir.ts`'s `ctx.loopParams` add site
+   * EXACTLY (verified against lines ~4320-4345 and the matching delete
+   * site ~4695-4710 of `packages/jsx/src/jsx-to-ir.ts`):
+   *
+   *   - When `loop.paramBindings` is non-empty (a destructured callback
+   *     param, e.g. `.map(({ id, name }) => ...)`), each `paramBindings[i].name`
+   *     is bound with source `'destructure'` and the raw `param` text
+   *     (which for a destructured callback holds the ORIGINAL pattern
+   *     source, e.g. `"{ id, name }"`, not a usable identifier) is NOT
+   *     bound. This matches `jsx-to-ir.ts`:
+   *       `if (paramBindings) { for (const b of paramBindings) ctx.loopParams.add(b.name) }`
+   *     — the `else` branch (`ctx.loopParams.add(param)`) is skipped
+   *     entirely when `paramBindings` is present.
+   *   - Otherwise (a plain identifier param, e.g. `.map(item => ...)`),
+   *     `param` itself is bound with source `'item'`.
+   *   - `index` (the second callback param, e.g. `.map((item, i) => ...)`)
+   *     is bound with source `'index'` when non-null/non-undefined.
+   *   - Every name in `preamble.declaredNames` (a `.map()` callback's
+   *     pre-return `const`/`let`/`function` locals, #2447) is bound with
+   *     source `'preamble'`.
+   *
+   *   NOTE on a sibling mechanism this method does NOT mirror:
+   *   `adapters/loop-bound-names.ts`'s `collectLoopBoundNames` adds BOTH
+   *   `node.param` AND every `paramBindings[i].name` unconditionally
+   *   (never skipping `param` in the destructured case) — a deliberately
+   *   coarser, over-inclusive collection used only to subtract names from
+   *   a flat string-typing Set (safe to over-exclude there). This method
+   *   follows the precise `jsx-to-ir.ts` `ctx.loopParams` semantics, since
+   *   that is the mechanism actually doing scope-shadowed name RESOLUTION
+   *   (the behavior `BindingScope` replaces), not coarse exclusion.
+   */
+  enterLoopRow(loop: LoopBindingSource): BindingScope {
+    const bindings = new Map<string, ScopeBinding>()
+    if (loop.paramBindings && loop.paramBindings.length > 0) {
+      for (const b of loop.paramBindings) bindings.set(b.name, { source: 'destructure' })
+    } else {
+      bindings.set(loop.param, { source: 'item' })
+    }
+    if (loop.index != null) bindings.set(loop.index, { source: 'index' })
+    for (const name of loop.preamble?.declaredNames ?? []) bindings.set(name, { source: 'preamble' })
+
+    const frame: ScopeFrame = { kind: 'loop-row', bindings }
+    return new BindingScope([frame, ...this.frames])
+  }
+
+  /**
+   * Child scope with a new `'callback'` frame binding `params` (a filter
+   * predicate's `x`, a sort comparator's `(a, b)`, or a nested arrow's
+   * parameter list) with source `'param'`. Parent is not mutated.
+   */
+  enterCallback(params: readonly string[]): BindingScope {
+    const bindings = new Map<string, ScopeBinding>()
+    for (const name of params) bindings.set(name, { source: 'param' })
+    const frame: ScopeFrame = { kind: 'callback', bindings }
+    return new BindingScope([frame, ...this.frames])
+  }
+
+  /** Innermost-first membership check across every frame in the stack. */
+  isBound(name: string): boolean {
+    for (const frame of this.frames) {
+      if (frame.bindings.has(name)) return true
+    }
+    return false
+  }
+
+  /**
+   * Resolves `name` against the frame stack innermost-first. `depth 0`
+   * means the innermost (most recently entered) frame; `null` when `name`
+   * is not bound in any frame.
+   */
+  lookup(name: string): { readonly depth: number; readonly frame: ScopeFrame; readonly binding: ScopeBinding } | null {
+    for (let depth = 0; depth < this.frames.length; depth++) {
+      const frame = this.frames[depth]
+      const binding = frame.bindings.get(name)
+      if (binding) return { depth, frame, binding }
+    }
+    return null
+  }
+
+  /**
+   * Union of every frame's bound names (every `ScopeBindingSource`), for
+   * migration interop with legacy `Set<string>`-shaped consumers (e.g.
+   * `collectLoopBoundNames`'s return type) as later stages migrate them
+   * onto `BindingScope`.
+   *
+   * This is the SHADOW-GUARD query — see {@link valueBoundNames} for the
+   * other consumer class and why the two must not be conflated.
+   */
+  boundNames(): ReadonlySet<string> {
+    if (this.boundNamesCache) return this.boundNamesCache
+    const names = new Set<string>()
+    for (const frame of this.frames) {
+      for (const name of frame.bindings.keys()) names.add(name)
+    }
+    this.boundNamesCache = names
+    return names
+  }
+
+  // Both name queries are hot (shadow guards, slot/reactivity classifiers,
+  // binding-env memo keying) and the scope is immutable, so each computes
+  // once per instance. Callers receive the cached set as ReadonlySet —
+  // never mutate it.
+  private boundNamesCache: ReadonlySet<string> | undefined
+  private valueBoundNamesCache: ReadonlySet<string> | undefined
+
+  /**
+   * Union of names bound via `'item'`/`'index'`/`'destructure'` sources
+   * only — the loop row's own per-item identity — excluding `'preamble'`
+   * (a `.map()` callback's pre-return `const`/`let`/`function` locals,
+   * #2447) and `'param'` (an `enterCallback` frame's filter/sort/nested-
+   * arrow parameters).
+   *
+   * `BindingScope` has exactly two consumer classes, and conflating them
+   * is the #2482 Stage 1a Commit 2 regression this split exists to
+   * prevent (a `ctx.scope`-wide preamble merge flipped `tag-cloud` and
+   * `preamble-cells` conformance fixtures before this method existed):
+   *
+   *   - SHADOW GUARDS (`tryResolveTemplateSpanFromConst`,
+   *     `tryResolveIdentifierAsTemplateLiteral`, `rewriteBarePropRefs`
+   *     in `jsx-to-ir.ts`) ask "is this name resolved to SOMETHING in
+   *     this scope, so an outer const/prop of the same name must not be
+   *     substituted here at this transform position" — every source
+   *     qualifies, including a preamble local shadowing a module const.
+   *     These call `isBound` / `boundNames()`.
+   *   - REACTIVITY / SLOT-ID CLASSIFIERS (`referencesLoopParam`,
+   *     `hasReactiveAttributes`, and the `BindingEnvironment.loopParams`
+   *     feed built from `makeBindingEnv`, all in `jsx-to-ir.ts`) ask
+   *     "does this expression read a value that changes per row and so
+   *     needs its own patchable slot" — a preamble local already gets
+   *     ITS OWN dedicated slot/region-patch machinery
+   *     (`preambleRegions` / `markPreambleAttrSlots`, #2447), so folding
+   *     it into this classification double-counts it. Worse: widening a
+   *     text child's `reactive` flag this way is read by
+   *     `hasDynamicContent` to decide whether the loop ROW's own root
+   *     element needs a slot — an unrelated, narrower decision that must
+   *     not move just because a preamble local is now scope-visible.
+   *     These call `valueBoundNames()`.
+   */
+  valueBoundNames(): ReadonlySet<string> {
+    if (this.valueBoundNamesCache) return this.valueBoundNamesCache
+    const names = new Set<string>()
+    for (const frame of this.frames) {
+      for (const [name, binding] of frame.bindings) {
+        if (binding.source === 'item' || binding.source === 'index' || binding.source === 'destructure') {
+          names.add(name)
+        }
+      }
+    }
+    this.valueBoundNamesCache = names
+    return names
+  }
+
+  /**
+   * Drop-in for `resolveStaticLoopSource`'s `opts.isNameShadowed`
+   * (`packages/jsx/src/static-literal.ts:112-128`).
+   */
+  asShadowPredicate(): (name: string) => boolean {
+    return (name: string) => this.isBound(name)
+  }
+}

package/src/ssr-defaults.ts

@@ -62,6 +62,76 @@ export interface SsrDefault {
   isRestProps?: boolean
 }
 
+/**
+ * TS twin of the runtime `derive*FromDefaults` family that ships in every
+ * OTHER SSR runtime port (Ruby's `BarefootJS::Context.derive_vars_from_defaults`
+ * — `packages/adapter-erb/lib/barefoot_js.rb:337-360` — plus Python's
+ * `barefootjs.runtime._derive_stash_from_defaults`, PHP's
+ * `Barefoot\BarefootJS::deriveStashFromDefaults`, Perl's
+ * `BarefootJS::_derive_stash_from_defaults`, and Rust's
+ * `barefootjs::manifest::derive_stash_from_defaults`). TypeScript had no such
+ * function — every adapter-tests conformance harness (and 3 production
+ * integration sites) either discarded `SsrDefault.propName` outright or keyed
+ * its seeding loop off the LOCAL template-var name instead of the
+ * caller-facing prop key, which is exactly the #2157 defect class (and its
+ * #2524 SSR-seeding recurrence) restated at
+ * `packages/adapter-erb/src/test-render.ts:276-287`. Any harness or
+ * integration deriving template-stash vars from an `extractSsrDefaults(...)`
+ * map MUST route through this function (or its runtime-language twin, when
+ * one is reachable) instead of hand-flattening `SsrDefault.value` and
+ * merging raw caller props over it — that flattening is precisely what
+ * silently drops the rename.
+ *
+ * Semantics (mirrors `derive_vars_from_defaults`'s observable behavior,
+ * including its edge cases — though not always the identical mechanism;
+ * e.g. Python's `_derive_stash_from_defaults` checks `props.get(prop_name)
+ * is not None` with no separate `in` membership test, relying on `dict.get`
+ * defaulting a missing key to `None` — behaviorally identical to this
+ * function's explicit `propName in props && props[propName] != null` for a
+ * plain dict/object, just expressed differently):
+ *   - A non-object entry (a bare JSON value some callers may still pass,
+ *     e.g. a manifest round-tripped through a generic JSON domain) is used
+ *     AS-IS.
+ *   - `isRestProps` entries: prefer `props[<this entry's own key>]` when the
+ *     caller supplied one (checked via `in`, so an explicit `undefined` /
+ *     `null` value still counts as "supplied" — the rest bag is a
+ *     caller-assembled aggregate, not a single scalar with a meaningful
+ *     "absent" state), else the static `value` fallback (normally `{}`).
+ *   - Otherwise: prefer `props[propName]` when `propName` is set AND the
+ *     caller supplied a NON-NULLISH (`!= null`, so `undefined` and `null`
+ *     both fall through — mirrors every other port's "present and defined"
+ *     check) value for it, else the static `value` fallback. `propName`-less
+ *     entries (signal / memo locals) always use the static value — the
+ *     caller cannot override them by construction.
+ */
+export function deriveStashFromDefaults(
+  defaults: Record<string, SsrDefault>,
+  props: Record<string, unknown>,
+): Record<string, unknown> {
+  const extra: Record<string, unknown> = {}
+  for (const [name, d] of Object.entries(defaults)) {
+    if (d === null || typeof d !== 'object') {
+      // Defensive: every ENTRY `extractSsrDefaults` itself emits is always
+      // the `{ value, propName?, isRestProps? }` shape, but a caller may
+      // feed this a manifest round-tripped through a generic JSON domain
+      // (mirrors every runtime port's own `ref($d) eq 'HASH'` /
+      // `d.is_a?(Hash)` / `isinstance(d, dict)` guard).
+      extra[name] = d
+      continue
+    }
+    if (d.isRestProps) {
+      extra[name] = name in props ? props[name] : d.value
+      continue
+    }
+    if (d.propName !== undefined && d.propName in props && props[d.propName] != null) {
+      extra[name] = props[d.propName]
+    } else {
+      extra[name] = d.value
+    }
+  }
+  return extra
+}
+
 const UNRESOLVED = Symbol('unresolved')
 type EvalResult = unknown | typeof UNRESOLVED
 

package/src/template-parts.ts

@@ -0,0 +1,81 @@
+/**
+ * The single renderer for a structured `template` variant's parts back into
+ * JS template-literal source.
+ *
+ * Three sites used to carry byte-identical copies of this loop — the IR-time
+ * component-prop collapse (`jsx-to-ir.ts`), the client-JS emitter
+ * (`ir-to-client-js/utils.ts`), and the JSX adapters' attribute renderer. They
+ * have to agree: the collapse's output is what a JSX adapter emits verbatim
+ * for a component prop, so a divergence between any two of them is a silent
+ * SSR/CSR mismatch. One door, three callers.
+ */
+
+import type { IRTemplatePart } from './types.ts'
+
+export interface TemplatePartsToJsOptions {
+  /**
+   * Prefer each part's prop-rewritten projection (`templateValue` /
+   * `templateCondition` / `templateKey`, i.e. destructured props rewritten
+   * to `_p.X`) when present. Used by the client-JS / module-registration
+   * template emitters, which run outside the component's destructured scope.
+   */
+  useTemplate?: boolean
+  /**
+   * Emit TypeScript type annotations. Only adapters whose output is
+   * type-checked as .tsx set this — see `JsxAdapterConfig.preserveTypes`.
+   * The neutral (untyped) form is what DSL adapters' expression pipelines
+   * and the client-JS bundle consume, so it must stay plain JS.
+   */
+  typed?: boolean
+}
+
+/**
+ * Render one `lookup` part — `${MAP[KEY]}` structurally captured at IR time
+ * so DSL adapters can emit a switch — as the equivalent runtime indexed
+ * access against the resolved cases.
+ *
+ * Under `typed`, the inlined object literal is annotated
+ * `as Record<string, string>` (#2565). The IR's `key` is the TYPE-STRIPPED
+ * source text of the index expression, so a narrowing assertion written at
+ * the use site — `strokePaths[name as keyof typeof strokePaths]` — is already
+ * gone by the time the record's cases are folded in here. That leaves the
+ * literal's exact key set indexed by the binding's unnarrowed union, which
+ * fails TS7053 ("expression of type 'IconName' can't be used to index type
+ * '{ check: string; … }'") in any consumer that type-checks its compiled
+ * templates. Widening the literal to a string index signature restores the
+ * assertion's effect without reconstructing its text, which may name types
+ * the emitted template never declares (`keyof typeof strokePaths` where
+ * `strokePaths` was localised into a component body). Purely a type-level
+ * annotation — the runtime expression is identical either way.
+ */
+export function lookupPartToJsExpr(
+  part: Extract<IRTemplatePart, { type: 'lookup' }>,
+  opts?: TemplatePartsToJsOptions,
+): string {
+  const key = (opts?.useTemplate && part.templateKey) ? part.templateKey : part.key
+  const obj = '{' + Object.entries(part.cases).map(
+    ([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`
+  ).join(', ') + '}'
+  const typed = opts?.typed ? ' as Record<string, string>' : ''
+  return `(${obj}${typed})[${key}]`
+}
+
+/** Convert a `template` variant's parts into a JS template-literal string. */
+export function templatePartsToJsExpr(
+  parts: readonly IRTemplatePart[],
+  opts?: TemplatePartsToJsOptions,
+): string {
+  let result = '`'
+  for (const part of parts) {
+    if (part.type === 'string') {
+      result += (opts?.useTemplate && part.templateValue) ? part.templateValue : part.value
+    } else if (part.type === 'ternary') {
+      const cond = (opts?.useTemplate && part.templateCondition) ? part.templateCondition : part.condition
+      result += `\${${cond} ? '${part.whenTrue}' : '${part.whenFalse}'}`
+    } else if (part.type === 'lookup') {
+      result += `\${${lookupPartToJsExpr(part, opts)}}`
+    }
+  }
+  result += '`'
+  return result
+}

package/src/types.ts

@@ -93,6 +93,16 @@ export interface ParamInfo {
   type: TypeInfo
   optional: boolean
   defaultValue?: string
+  /**
+   * `defaultValue` parsed into a structured tree, mirroring `SignalInfo.parsed`
+   * (Roadmap A). Attached best-effort by the analyzer (`tsNodeToParsedExpr` on
+   * the binding element's own `initializer` node — no re-parse of the
+   * `defaultValue` text) so adapters can classify a destructure default's
+   * literal shape (`{ count = 3 }`, `{ ratio = 1.5 }`) from structure instead
+   * of regexing `defaultValue`. Absent when the shape isn't supported;
+   * consumers fall back to text-matching `defaultValue`.
+   */
+  parsed?: ParsedExpr
   /** When true, the default value contains an arrow function or function expression (computed from AST). */
   defaultContainsArrow?: boolean
   /** When true, the parameter is a rest spread (`...args`) — emit must prepend `...`. */
@@ -1872,6 +1882,14 @@ export interface ConstantInfo {
   parsed?: ParsedExpr
   /** Value with TypeScript type annotations preserved, for .tsx output */
   typedValue?: string
+  /**
+   * The declaration's explicit type annotation, verbatim from source
+   * (`node.type.getText()`), when the author wrote one. Distinct from
+   * `type`, which is also populated by inference from the initializer —
+   * emitters must only print THIS field, never an inferred type, onto a
+   * declaration (#2589).
+   */
+  typeAnnotation?: string
   valueBranches?: string[]
   declarationKind: 'const' | 'let'
   isExported?: boolean