@barefootjs/jsx 0.31.0 → 0.31.2

package/src/ir-to-client-js/utils.ts

@@ -7,6 +7,7 @@ import ts from 'typescript'
 import type { AttrValue, IRTemplatePart, LoopParamBinding, FreeReference, IRNode } from '../types.ts'
 import type { TopLevelLoop, BranchLoop, LoopOffset } from './types.ts'
 import { buildLoopChainExpr } from '../loop-chain.ts'
+import { templatePartsToJsExpr } from '../template-parts.ts'
 import {
   iterateJsTokens,
   isIdentifierLikeToken,
@@ -73,31 +74,11 @@ export function profileBindingId(componentName: string | undefined, slotId: stri
  * Convert a `template` variant's parts into a JS template-literal string.
  * Shared by both `attrValueToString` and any consumer that wants to flatten
  * a structured template into JS-level concatenation.
+ *
+ * Re-exported from the single renderer in `../template-parts.ts` — the
+ * client bundle is plain JS, so it never passes `typed`.
  */
-export function templatePartsToJsExpr(parts: readonly IRTemplatePart[], opts?: { useTemplate?: boolean }): 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') {
-      // `${MAP[KEY]}` was structurally captured at IR time so SSR
-      // adapters could emit a switch. For client-side JS we rebuild
-      // the equivalent runtime indexed lookup against the resolved
-      // cases — keeps the JSX runtime path semantically identical to
-      // the original `${variantClasses[variant]}` source.
-      const key = (opts?.useTemplate && part.templateKey) ? part.templateKey : part.key
-      const obj = '{' + Object.entries(part.cases).map(
-        ([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`
-      ).join(', ') + '}'
-      result += `\${(${obj})[${key}]}`
-    }
-  }
-  result += '`'
-  return result
-}
+export { templatePartsToJsExpr }
 
 /**
  * Flatten an `AttrValue` to its raw string form, suitable for HTML attribute

package/src/jsx-runtime/index.ts

@@ -45,6 +45,7 @@ import type {
   SVGBaseAttributes,
   SVGPresentationAttributes,
   SVGMarkerReferenceAttributes,
+  SVGSVGAttributes,
 } from '../html-types.ts'
 
 // Stub function types (for type checking only - no runtime implementation)
@@ -208,13 +209,7 @@ export declare namespace JSX {
     // SVG (basic support).
     // Each entry uses `SVGBaseAttributes` so `ref` can be narrowed per-tag.
     // See `SVGBaseAttributes` JSDoc for why plain intersection doesn't work.
-    svg: SVGBaseAttributes & SVGPresentationAttributes & {
-      viewBox?: string
-      xmlns?: string
-      width?: number | string
-      height?: number | string
-      ref?: (element: SVGSVGElement) => void
-    }
+    svg: SVGSVGAttributes
     path: SVGBaseAttributes & SVGPresentationAttributes & SVGMarkerReferenceAttributes & {
       d?: string
       pathLength?: number | string

package/src/jsx-to-ir.ts

@@ -49,6 +49,7 @@ import {
   rewriteBarePropRefs as rewriteBarePropRefsCore,
   collectAstPropRefs,
 } from './prop-rewrite.ts'
+import { buildPropAliasMap } from './props-binding.ts'
 import { resolveFreeRefs, isNameBound as isNameBoundInEnv, type BindingEnvironment } from './free-refs.ts'
 import { computeFileScope } from './ir-to-client-js/component-scope.ts'
 import { createTemplateAwareStringProtector } from './ir-to-client-js/html-template.ts'
@@ -59,6 +60,7 @@ import type { LoweringMatcher } from './lowering-registry.ts'
 import { extractFreeIdentifiersFromNode, initializerShapeContainsJsx, extractMultiReturnJsxBranches, type MultiReturnJsxBranches } from './analyzer.ts'
 import { iterateJsTokens, replaceInExprContexts } from './scanner/js-scanner.ts'
 import { reconstructAsSegments } from './strip-types.ts'
+import { templatePartsToJsExpr } from './template-parts.ts'
 import { toHTMLAttrName, decodeEntities } from '@barefootjs/shared'
 
 // =============================================================================
@@ -91,6 +93,15 @@ interface TransformContext {
   _moduleClientSignalNames?: Set<string>
   /** Cached set of destructured prop names for AST-based rewriting */
   _destructuredPropNames?: Set<string> | null
+  /**
+   * Cached local-name → caller-facing-key (`sourceName ?? name`) map for
+   * `_destructuredPropNames`, entries only for names that actually rename
+   * (`{ n: count }` → `count` → `n`). Built alongside `_destructuredPropNames`
+   * so both stay in lockstep with the same shadow-filtered eligible set —
+   * consumed by `rewriteBarePropRefsCore` to emit `_p.<caller>` instead of
+   * `_p.<local>` (#2524 CSR half: `_p` is always caller-keyed).
+   */
+  _destructuredPropAliases?: Map<string, string> | null
   /** Active loop parameter names for slotId assignment to loop-param-dependent expressions */
   loopParams: Set<string>
   /**
@@ -536,7 +547,8 @@ function rewriteBarePropRefs(text: string, expr: ts.Node, ctx: TransformContext)
   // `_branchScopePropDeps` at branch entry; here we just walk `expr`
   // for references to those locals and union the matching dep sets.
   const extraPropRefs = collectBranchLocalPropRefsViaSubstitution(expr, ctx)
-  return rewriteBarePropRefsCore(dateLowered, expr, propNames, extraPropRefs)
+  const propAliases = getDestructuredPropAliases(ctx)
+  return rewriteBarePropRefsCore(dateLowered, expr, propNames, extraPropRefs, propAliases ?? undefined)
 }
 
 /**
@@ -618,14 +630,26 @@ function getDestructuredPropNames(ctx: TransformContext): Set<string> | null {
         if (!isDestructureFromProps) shadowed.add(c.name)
       }
     }
-    const names = ctx.analyzer.propsParams
-      .map(p => p.name)
-      .filter(n => !shadowed.has(n))
+    const eligible = ctx.analyzer.propsParams.filter(p => !shadowed.has(p.name))
+    const names = eligible.map(p => p.name)
     ctx._destructuredPropNames = names.length > 0 ? new Set(names) : null
+    ctx._destructuredPropAliases = buildPropAliasMap(eligible) ?? null
   }
   return ctx._destructuredPropNames ?? null
 }
 
+/**
+ * Companion to `getDestructuredPropNames`: the local-name → caller-key
+ * alias map for the SAME shadow-filtered eligible set, populated as a
+ * side effect of that call. Always call `getDestructuredPropNames` first
+ * (or accept it may return an empty cache) — the two caches are written
+ * together in one pass.
+ */
+function getDestructuredPropAliases(ctx: TransformContext): Map<string, string> | null {
+  if (ctx._destructuredPropNames === undefined) getDestructuredPropNames(ctx)
+  return ctx._destructuredPropAliases ?? null
+}
+
 function createTransformContext(analyzer: AnalyzerContext): TransformContext {
   return {
     analyzer,
@@ -1278,12 +1302,21 @@ function transformJsxElement(
  *  - `<textarea>` with no children gains a NON-reactive expression child
  *    (the initial value as element content — updates keep flowing through
  *    the `.value` effect, deliberately not a live text slot);
- *  - `<select>` distributes `selected={(value) === 'opt'}` onto each
- *    statically-valued `<option>` (incl. under `<optgroup>`/fragments) —
- *    the exact per-option comparison shape the `select-option-selected`
- *    fixture already proves across every adapter. Options rendered by a
- *    dynamic loop can't be statically distributed and are left to the
- *    hydrate-time effect (tracked with #2466 on the #2464 thread).
+ *  - `<select>` distributes `selected={(value) === optValue}` onto each
+ *    `<option>` (incl. under `<optgroup>`/fragments, and under a `.map()`
+ *    loop body) — the exact per-option comparison shape the
+ *    `select-option-selected` fixture already proves across every adapter.
+ *    A literal `optValue` (e.g. `value="banana"`) compares by
+ *    `JSON.stringify`; an expression `optValue` (a static dynamic value, or
+ *    a loop row reading its item — e.g. `value={o.id}`) compares against
+ *    the expression text directly. For a loop row this makes `selected` an
+ *    ordinary per-item reactive attribute like any other (`o.id`, the row's
+ *    text) — it rides the SAME loop-plan machinery
+ *    (`collectLoopChildReactiveAttrs` → `emitAttrUpdate`, which special-cases
+ *    `selected` as a boolean DOM PROPERTY write, not just an HTML attribute)
+ *    that already reruns per row on item change and per outer-signal change,
+ *    so selectedness is recomputed instead of staying attached to whichever
+ *    physical `<option>` a reorder happened to rewrite in place (#2466).
  */
 function lowerFormControlValueSsr(
   tagName: string,
@@ -1318,21 +1351,47 @@ function lowerFormControlValueSsr(
     return
   }
 
-  const selectedFor = (optValue: string): AttrValue =>
+  const selectedForLiteral = (optValue: string): AttrValue =>
     AttrValueOf.expression(
       `(${expr}) === ${JSON.stringify(optValue)}`,
       templateExpr !== undefined
         ? { templateExpr: `(${templateExpr}) === ${JSON.stringify(optValue)}` }
         : undefined,
     )
+  // An expression-valued `option value` — the shape every `.map()` loop row
+  // uses (`value={o.id}`) since the whole point of the loop is a per-item
+  // value. Compares the controlled value directly against the option's own
+  // value EXPRESSION TEXT (never JSON-stringified — it is JS, not a string
+  // literal). Inside a loop row this expression reads both the row item
+  // (`o.id`) and the outer controlled signal (`expr`, e.g. `val()`), which
+  // is exactly the "reads both" shape `collectLoopChildReactiveAttrs` /
+  // `classifyLazyBinding` already know how to place into both `applyItem`
+  // (row changed) and `applyOuter` (controlled value changed) — no new loop
+  // machinery, just one more per-row reactive attribute (#2466).
+  const selectedForExpr = (optExpr: string, optTemplateExpr: string | undefined): AttrValue =>
+    AttrValueOf.expression(
+      `(${expr}) === (${optExpr})`,
+      templateExpr !== undefined || optTemplateExpr !== undefined
+        ? { templateExpr: `(${templateExpr ?? expr}) === (${optTemplateExpr ?? optExpr})` }
+        : undefined,
+    )
   const distribute = (nodes: IRNode[]): void => {
     for (const n of nodes) {
       if (n.type === 'element' && n.tag === 'option') {
         if (n.attrs.some(a => a.name === 'selected')) continue
         const optValue = n.attrs.find(a => a.name === 'value')
-        if (!optValue || optValue.value.kind !== 'literal') continue
-        n.attrs.push({ name: 'selected', value: selectedFor(optValue.value.value), loc: n.loc })
-      } else if (n.type === 'fragment' || (n.type === 'element' && n.tag === 'optgroup')) {
+        if (!optValue) continue
+        if (optValue.value.kind === 'literal') {
+          n.attrs.push({ name: 'selected', value: selectedForLiteral(optValue.value.value), loc: n.loc })
+        } else if (optValue.value.kind === 'expression') {
+          const selected = selectedForExpr(optValue.value.expr, optValue.value.templateExpr)
+          n.attrs.push({ name: 'selected', value: selected, loc: n.loc })
+        }
+      } else if (
+        n.type === 'fragment' ||
+        n.type === 'loop' ||
+        (n.type === 'element' && n.tag === 'optgroup')
+      ) {
         distribute(n.children)
       }
     }
@@ -6777,8 +6836,8 @@ function processComponentProps(
       // the bare `classes` identifier with no prop refs, so the rewrite
       // no-ops and the module-scope registration template leaks bare
       // destructured props into `renderChild(...)` (#2468).
-      const collapsed = templatePartsToJsString(value.parts)
-      const collapsedTemplate = templatePartsToJsString(value.parts, { useTemplate: true })
+      const collapsed = templatePartsToJsExpr(value.parts)
+      const collapsedTemplate = templatePartsToJsExpr(value.parts, { useTemplate: true })
       value = AttrValueOf.expression(collapsed, {
         parts: value.parts,
         ...(collapsedTemplate !== collapsed && { templateExpr: collapsedTemplate }),
@@ -6820,32 +6879,6 @@ function processComponentProps(
   return props
 }
 
-/**
- * Flatten a structured template-literal's parts back into a JS expression
- * string. Used at IR construction time when a structured `template` variant
- * needs to be collapsed into an `expression` for component-prop forwarding —
- * component props are runtime JS values, not HTML attribute bodies.
- */
-function templatePartsToJsString(parts: readonly IRTemplatePart[], opts?: { useTemplate?: boolean }): 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') {
-      const key = (opts?.useTemplate && part.templateKey) ? part.templateKey : part.key
-      const obj = '{' + Object.entries(part.cases).map(
-        ([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`
-      ).join(', ') + '}'
-      result += `\${(${obj})[${key}]}`
-    }
-  }
-  result += '`'
-  return result
-}
-
 // =============================================================================
 // Helpers
 // =============================================================================

package/src/module-exports.ts

@@ -21,10 +21,19 @@ export function generateModuleExports(
   ir: ComponentIR,
   extraInlineExported: ReadonlySet<string> = new Set(),
   rewriteRelativeImport?: (importPath: string) => string,
+  options?: {
+    /**
+     * Skip `export const` / `export function` value declarations — the
+     * adapter already emitted them inside its module-scope section, in
+     * source order (see `TemplateSections.moduleConstantsIncludeExports`).
+     * `export { … } [from '…']` specifier blocks are still emitted.
+     */
+    skipValueDeclarations?: boolean
+  },
 ): string | null {
   const lines: string[] = []
 
-  for (const constant of ir.metadata.localConstants) {
+  for (const constant of options?.skipValueDeclarations ? [] : ir.metadata.localConstants) {
     if (!constant.isExported) continue
     const keyword = constant.declarationKind ?? 'const'
     if (!constant.value) {
@@ -38,7 +47,7 @@ export function generateModuleExports(
     lines.push(`export ${keyword} ${constant.name} = ${constant.value}`)
   }
 
-  for (const func of ir.metadata.localFunctions) {
+  for (const func of options?.skipValueDeclarations ? [] : ir.metadata.localFunctions) {
     if (!func.isExported) continue
     // Prefer the source-verbatim signature so type predicates and explicit
     // `:unknown` parameter annotations survive — see FunctionInfo.typedParams

package/src/prop-rewrite.ts

@@ -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/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
+}