@barefootjs/jsx 0.33.4 → 0.34.0

package/src/jsx-to-ir.ts

@@ -40,7 +40,7 @@ import {
 } from './types.ts'
 import { type AnalyzerContext, type MultiReturnJsxInfo, getSourceLocation, collectReactiveGetterNames } from './analyzer-context.ts'
 import { parseExpression, isSupported, parseBlockBody, foldBlockToExpr, predicateTernaryToLogical, tsNodeToParsedExpr, sortComparatorFromArrow, stringifyParsedExpr, cssKebabCase, CALLBACK_METHODS, type ParsedExpr } from './expression-parser.ts'
-import type { IRLoopSort, FunctionInfo } from './types.ts'
+import type { IRLoopSort, FunctionInfo, ConstantInfo } from './types.ts'
 import { formatParamWithType } from './module-exports.ts'
 import { createError, ErrorCodes, internalInvariant } from './errors.ts'
 import { CLIENT_BUILTIN_SOURCE, isClientBuiltinName, type ClientBuiltinTag } from './builtins.ts'
@@ -49,7 +49,7 @@ import {
   rewriteBarePropRefs as rewriteBarePropRefsCore,
   collectAstPropRefs,
 } from './prop-rewrite.ts'
-import { buildPropAliasMap, resolveRestSpreadOriginCore } from './props-binding.ts'
+import { boundPropLocalNames, buildPropAliasMap, resolveAliasOrigin, resolveRestSpreadOriginCore } 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'
@@ -73,6 +73,7 @@ import { identifierPattern, identifierCallPattern } from './identifier-pattern.t
 interface ReactivityPatterns {
   signals: { getter: string; pattern: RegExp }[]
   memos: { name: string; pattern: RegExp }[]
+  /** For regex `props.<key>` detection only — for exact-name binding checks read `TransformContext.boundPropNames` instead (#2835). */
   props: { name: string; pattern: RegExp }[]
   constants: { name: string; value: string | undefined; pattern: RegExp }[]
 }
@@ -85,6 +86,14 @@ interface TransformContext {
   isRoot: boolean
   insideComponentChildren: boolean
   patterns: ReactivityPatterns
+  /**
+   * Local names actually bound by the props parameter (#2835) — unlike
+   * `patterns.props`, which for a whole `(props: Props)` parameter holds
+   * every TYPE-MEMBER name (needed so its regex `pattern` still matches
+   * `props.<key>` accesses), this is empty in that shape since none of
+   * those names are local bindings a shadow check could ever see.
+   */
+  boundPropNames: ReadonlySet<string>
   /** Shortcut for analyzer.getJS(node) */
   getJS(node: ts.Node): string
   /** getJS + rewrite destructured prop refs for client JS templates (#807) */
@@ -93,8 +102,20 @@ interface TransformContext {
   _reactiveGetterNames?: Set<string>
   /** Cached set of module-scope @client signal/memo names. */
   _moduleClientSignalNames?: Set<string>
-  /** Cached `localConstants` index for `forwardsCallerRestProps`'s alias walk */
-  _restSpreadConstantValues?: ReadonlyMap<string, string | undefined>
+  /**
+   * Cached `localConstants` index (name → value text), shared by every
+   * `resolveAliasOrigin` walk in this file — `forwardsCallerRestProps`'s
+   * rest/props-spread alias walk and `isArrayExprDirectPropRef`'s
+   * direct-prop-array alias walk (#2724).
+   */
+  _constantValuesByName?: ReadonlyMap<string, string | undefined>
+  /**
+   * Cached `localConstants` index (name → full `ConstantInfo`), for
+   * lookups that need more than the value text — e.g.
+   * `isArrayExprDirectPropRef` reading a constant's structured `.parsed`
+   * to recognize `const arr = props.items` (#2724).
+   */
+  _constantsByName?: ReadonlyMap<string, ConstantInfo>
   /** Cached set of destructured prop names for AST-based rewriting */
   _destructuredPropNames?: Set<string> | null
   /**
@@ -668,6 +689,10 @@ function getDestructuredPropAliases(ctx: TransformContext): Map<string, string>
 }
 
 function createTransformContext(analyzer: AnalyzerContext): TransformContext {
+  // Shared by `patterns.props` (regex matching) and `boundPropNames`
+  // (exact-name binding checks, #2835) so both agree on which prop
+  // params are in play — `children` excluded from both the same way.
+  const propsParamsForMatching = analyzer.propsParams.filter(p => p.name !== 'children')
   return {
     analyzer,
     sourceFile: analyzer.sourceFile,
@@ -681,6 +706,7 @@ function createTransformContext(analyzer: AnalyzerContext): TransformContext {
     insideComponentChildren: false,
     scope: BindingScope.EMPTY,
     loopDepth: 0,
+    boundPropNames: boundPropLocalNames({ propsParams: propsParamsForMatching, propsObjectName: analyzer.propsObjectName }),
     patterns: {
       signals: analyzer.signals.map(s => ({
         getter: s.getter,
@@ -690,9 +716,7 @@ function createTransformContext(analyzer: AnalyzerContext): TransformContext {
         name: m.name,
         pattern: identifierCallPattern(m.name),
       })),
-      props: analyzer.propsParams
-        .filter(p => p.name !== 'children')
-        .map(p => ({ name: p.name, pattern: identifierPattern(p.name) })),
+      props: propsParamsForMatching.map(p => ({ name: p.name, pattern: identifierPattern(p.name) })),
       constants: analyzer.localConstants.map(c => ({
         name: c.name,
         value: c.value,
@@ -5479,8 +5503,8 @@ function buildFlatMapCallback(
     // Template variant per segment, like buildPreambleSegments: the hydrate
     // registration template is module scope (`template: (_p) => ...`), so a
     // bare destructured-prop reference must rewrite to `_p.xxx` there —
-    // `applyPropsRewrite` can't do it (destructured components have no props
-    // object name).
+    // `rewritePropsObjectRef` can't do it (destructured components have no
+    // props object name to rewrite from).
     const tpl = rewriteBarePropRefs(piece.js, body, ctx)
     return tpl !== undefined && tpl !== piece.js
       ? { kind: 'js', text: piece.js, templateText: tpl }
@@ -7393,10 +7417,7 @@ function expressionWrapsJsx(node: ts.Expression): boolean {
  * Refuse a component prop whose initializer is a ternary/array literally
  * wrapping JSX (#2667) — see `expressionWrapsJsx`'s docstring and the call
  * site above for why this can't fall through to the plain `expression`
- * AttrValue path (raw JSX syntax would splice into the emitted client
- * JS) and why the fragment-wrap escape is NOT offered here (BF021 message
- * below explains the unsoundness inline; see #2667's tracking issue for
- * the full door-inventory finding).
+ * AttrValue path (raw JSX syntax would splice into the emitted client JS).
  */
 function reportNakedJsxWrapperProp(
   ctx: TransformContext,
@@ -7411,15 +7432,21 @@ function reportNakedJsxWrapperProp(
         `Prop '${propName}' is ${shape} wrapping JSX (${jsxExpr.getText(ctx.sourceFile)}). ` +
         `This shape is not compiled — only a JSX element/fragment given DIRECTLY as the prop value is.`,
       suggestion: {
-        message:
-          `Move the conditional/array out of the prop position: compute it in a local ` +
-          `const and pass it as the component's children instead of a named prop ` +
-          `(e.g. const ${propName} = ${jsxExpr.getText(ctx.sourceFile)}; <Comp>{${propName}}</Comp>). ` +
-          `Wrapping the ternary/array in a fragment at the prop position ` +
-          `(${propName}={<>{${jsxExpr.getText(ctx.sourceFile)}}</>}) is NOT a safe escape here: it compiles, ` +
-          `but the child's own reactive prop getter receives the branch's HTML unbranded and re-escapes it as ` +
-          `text on the child's very next reactive run, corrupting the DOM (a narrower gap #2651's door ` +
-          `inventory left open — tracked separately).`,
+        message: ts.isConditionalExpression(jsxExpr)
+          ? `Move the conditional out of the prop position: compute it in a local const and pass it as ` +
+            `the component's children instead of a named prop ` +
+            `(e.g. const ${propName} = ${jsxExpr.getText(ctx.sourceFile)}; <Comp>{${propName}}</Comp>). ` +
+            `Wrapping the ternary in a fragment at the prop position ` +
+            `(${propName}={<>{${jsxExpr.getText(ctx.sourceFile)}}</>}) is also a safe escape (#2702): the ` +
+            `compiler brands each JSX branch individually, so the child's reactive prop getter unwraps it ` +
+            `correctly instead of re-escaping it as text.`
+          : `Move the array out of the prop position: compute it in a local const and pass it as the ` +
+            `component's children instead of a named prop ` +
+            `(e.g. const ${propName} = ${jsxExpr.getText(ctx.sourceFile)}; <Comp>{${propName}}</Comp>). ` +
+            `Wrapping the array in a fragment at the prop position is NOT a safe escape here: it compiles, ` +
+            `but flattens to more than one part, which the child's reactive prop getter has no branding ` +
+            `contract for (a multi-part jsx-children shape, tracked separately from #2702's single-` +
+            `conditional fix).`,
         escape: [{ kind: 'rewrite' }],
       },
     }),
@@ -7474,14 +7501,13 @@ function processComponentProps(
       // plain `expression` path below, which stringifies the initializer's
       // SOURCE TEXT — literal JSX syntax spliced into the emitted client
       // JS (invalid at runtime; the #2651 door inventory's discovery).
-      // Refuse loudly instead of guessing a lowering: the fragment-wrap
-      // escape this diagnostic once considered recommending turns out to
-      // be unsound for the same shape (`isSingleElementJsxChildren`'s
-      // docstring in `ir-to-client-js/collect-elements.ts` — a
-      // conditional-in-fragment reaches `initChild`'s getter UNbranded,
-      // corrupting the child's DOM the moment its own reactive effect
-      // first reads the prop), so only the children-passthrough escape is
-      // offered.
+      // Refuse loudly instead of guessing a lowering. The fragment-wrap
+      // escape IS safe for the ternary shape (#2702: `jsxChildrenPropGetterExpr`,
+      // `ir-to-client-js/html-template.ts`, brands each JSX branch after the
+      // fragment hoists the conditional) — `reportNakedJsxWrapperProp`
+      // offers it for that case. It stays unsafe for the array-literal
+      // shape (a multi-part jsx-children value has no branding contract),
+      // so only the children-passthrough escape is offered there.
       if (
         (ts.isConditionalExpression(jsxExpr) || ts.isArrayLiteralExpression(jsxExpr)) &&
         expressionWrapsJsx(jsxExpr)
@@ -7844,31 +7870,152 @@ function checkBareSignalOrMemoIdentifier(
  * Structural AST check: is the array expression a direct prop reference?
  *
  * Returns true only when arrayExpr is:
- * (a) An Identifier that is a destructured prop binding (e.g. `toggleItems`)
- * (b) A PropertyAccessExpression rooted at the props object (e.g. `props.items`)
+ * (a) An Identifier that is a destructured prop binding (e.g. `toggleItems`),
+ *     OR reaches one through a bare `x = y` local-alias-hop chain (e.g.
+ *     `const toggleItems__alias = toggleItems`, any number of hops, `const`
+ *     or `let`, #2724 — see `propAliasHopCandidates`'s docstring for why
+ *     `let` stays eligible)
+ * (b) A PropertyAccessExpression rooted at the props object (e.g. `props.items`),
+ *     OR one whose object reaches the props object through the same kind of
+ *     alias-hop chain as (a) (e.g. `const p = props; p.items`, #2724 review)
  *
  * Unlike the regex-based `isPropsReference`, this avoids false positives from
  * unrelated identifiers that happen to share a prop name (e.g. `state.items`
- * when `items` is also a prop).
+ * when `items` is also a prop) — the alias-hop walk only ever follows a
+ * constant's own bare-identifier value text or its structured `.parsed`
+ * shape, never a substring/regex match against arbitrary expression text.
+ * `propAliasHopCandidates` additionally restricts which constants are
+ * eligible hop sources (see its docstring). A name that merely COLLIDES
+ * with a prop's name without being bound to it (a module constant sharing a
+ * whole-`props`-object type's member name) is excluded by the terminal
+ * (`isDirectPropBindingName` reads `ctx.boundPropNames`, not the wider
+ * `ctx.patterns.props` — #2835).
+ *
+ * This is more than a "prop reference somewhere in the expression" check
+ * (`isPropsReference`'s regex semantics): the return value also feeds
+ * `IRLoop.isPropDerivedArray`, which the Go adapter uses to decide whether a
+ * nested component's field is literally the loop's prop-sourced data — a
+ * false positive there would misclassify DSL-adapter codegen, not just add
+ * one extra `mapArray`. So the alias walk stays structural (AST-derived
+ * `ConstantInfo.parsed`), not a second regex-based implementation of
+ * `isPropsReference`/`isSignalOrMemoReference`'s chain walk.
  */
 function isArrayExprDirectPropRef(arrayExpr: ts.Expression, ctx: TransformContext): boolean {
-  const propNames = new Set(ctx.patterns.props.map(p => p.name))
   const propsObjName = ctx.analyzer.propsObjectName
 
   if (ts.isIdentifier(arrayExpr)) {
-    return propNames.has(arrayExpr.text)
+    return resolveAliasOrigin(propAliasHopCandidates(ctx), arrayExpr.text, name => (isDirectPropBindingName(name, ctx) ? true : null)) === true
   }
 
   if (ts.isPropertyAccessExpression(arrayExpr) && propsObjName) {
     const obj = arrayExpr.expression
-    if (ts.isIdentifier(obj) && obj.text === propsObjName) {
-      return true
+    if (ts.isIdentifier(obj)) {
+      return resolveAliasOrigin(propAliasHopCandidates(ctx), obj.text, name => (name === propsObjName ? true : null)) === true
     }
   }
 
   return false
 }
 
+/**
+ * Does the local name `name` itself directly denote a prop — either a
+ * destructured prop binding, or a local constant whose value is a bare
+ * `<propsObjName>.<key>` member access (`const arr = props.items`)? The
+ * alias-hop walk in `isArrayExprDirectPropRef` calls this at every hop; it
+ * never inspects arbitrary expression text itself, only a single constant's
+ * name (against the destructured-prop set) or its own structured `.parsed`
+ * (against the props-object shape) — same "structural, not regex" guarantee
+ * `isArrayExprDirectPropRef`'s docstring makes.
+ *
+ * Shadow-guarded FIRST (pullfrog review finding): `propAliasHopCandidates`
+ * only keeps a shadowed name out of the map `resolveAliasOrigin` hops
+ * INTO — it does nothing for `name` itself on the very first call, which
+ * reads the separate, shadow-unaware `constantsByName(ctx)` index directly.
+ * Without this guard, `rows.map((list, ri) => list.map(...))`'s inner
+ * `list` — an arbitrary row value with no relation to props — would
+ * resolve via an unrelated, shadowed outer `const list = props.entries`
+ * the moment that outer constant's OWN value happens to be a
+ * member-access-on-props shape, defeating the shadow guard entirely
+ * (`propAliasHopCandidates`'s own `rows.map((list) => list.map(...))`
+ * docstring example, just with a member-access-valued outer const instead
+ * of an identifier-valued one — confirmed to reach real Go `isPropDerived`
+ * codegen the same way, since Go's BF101 gate explicitly skips a
+ * scope-bound array name).
+ *
+ * Reads `ctx.boundPropNames`, not `ctx.patterns.props` (#2835): for a whole
+ * `(props: Props)` parameter, `patterns.props` holds every TYPE-MEMBER name
+ * (needed so its regex still matches `props.<key>`) rather than local
+ * bindings, so a same-named module const was matching here as if it were
+ * the prop itself.
+ */
+function isDirectPropBindingName(name: string, ctx: TransformContext): boolean {
+  if (ctx.scope.isBound(name)) return false
+  if (ctx.boundPropNames.has(name)) return true
+  const propsObjName = ctx.analyzer.propsObjectName
+  if (!propsObjName) return false
+  const parsed = constantsByName(ctx).get(name)?.parsed
+  return !!parsed && parsed.kind === 'member' && !parsed.computed && parsed.object.kind === 'identifier' && parsed.object.name === propsObjName
+}
+
+/**
+ * `constantValuesByName(ctx)`, narrowed to the constants an alias-hop walk
+ * may legitimately continue into when resolving whether a loop's array (or
+ * a property access's object) ultimately denotes a prop (#2724 review
+ * finding — a second pass after the initial fix landed found two false
+ * positives the unrestricted map let through):
+ *
+ * - Never a MODULE-scope constant (`isModule`) — a module constant cannot,
+ *   by definition, be an alias of any one component instance's props, so
+ *   hopping into one can only ever be a coincidental name match. Same
+ *   exclusion `resolveGetterAliases` (csr-substitute.ts, #2778) already
+ *   makes for its own alias-hop walk.
+ * - Never a name currently SHADOWED by an active loop/callback binding
+ *   (`ctx.scope.isBound`) — `rows.map((list) => list.map(...))`'s inner
+ *   `list` must resolve to the OUTER LOOP'S ROW VALUE, never an unrelated
+ *   outer-scope `const list = someProp` the row happens to shadow. Same
+ *   shadow-guard shape as `tryResolveTemplateSpanFromConst`'s guard
+ *   (#2222-family) — `isBound()` (all binding sources), not
+ *   `valueBoundNames()`: this is that guard's consumer class, not the
+ *   reactivity/slot-ID classifier one (`BindingScope.valueBoundNames`'s
+ *   docstring, #2482 Stage 1a Commit 2). This map only half-delivers that
+ *   guarantee — it stops `resolveAliasOrigin` from hopping INTO a shadowed
+ *   name's value, but the FIRST call (`name` itself, before any hop) goes
+ *   straight to the terminal (`isDirectPropBindingName`), which has its own
+ *   matching `ctx.scope.isBound` check for exactly this reason (pullfrog
+ *   review finding on this PR — a shadowed outer const whose OWN value is a
+ *   member-access-on-props shape resolved as prop-derived on the very first
+ *   hop, before this map's filter ever applied).
+ *
+ * `let` is deliberately NOT excluded, despite being reassignable — this was
+ * tried during review and reverted (second review pass): `isStaticArray`
+ * (jsx-to-ir.ts's derivation) treats "not recognized as prop-derived" as
+ * STATIC, not dynamic, so excluding `let` doesn't move a `let`-aliased prop
+ * array to the safe/over-reconciling side — it reproduces #2724's exact
+ * silent-divergence shape (the array silently stays on the static
+ * `qsaChildScopes` path, so a CSR-only mount never wires up the row's
+ * child). A `let` reassigned before use could in principle make this hop
+ * resolve against a stale declaration-time value — but that only risks the
+ * SAFE direction (an extra `mapArray` on a loop that turns out not to be
+ * prop-derived after all), matching this file's existing `hasCalls`
+ * over-reconciliation-is-cheap philosophy, and Go's `renderLoop` BF101 gate
+ * independently refuses any bare-identifier loop array that resolves to a
+ * non-module local variable (`let` or `const` alike) before
+ * `isPropDerivedArray` would ever drive real Go codegen off it.
+ *
+ * A NARROWED VIEW, not a change to `constantValuesByName` itself — that
+ * function is also `forwardsCallerRestProps`'s rest/props-spread alias
+ * walk, whose existing (wider) hop set this deliberately leaves alone.
+ */
+function propAliasHopCandidates(ctx: TransformContext): ReadonlyMap<string, string | undefined> {
+  const bound = ctx.scope.boundNames()
+  const candidates = new Map<string, string | undefined>()
+  for (const constant of ctx.analyzer.localConstants) {
+    if (constant.isModule || bound.has(constant.name)) continue
+    if (!candidates.has(constant.name)) candidates.set(constant.name, constant.value)
+  }
+  return candidates
+}
+
 /**
  * Check if array expression is a signal or memo getter call.
  * Used to determine if a loop needs mapArray for dynamic DOM updates.
@@ -8046,7 +8193,7 @@ function isPropsReference(expr: string, ctx: TransformContext, visited?: Set<str
 function forwardsCallerRestProps(attrs: IRAttribute[], ctx: TransformContext): boolean {
   for (const attr of attrs) {
     if (attr.value.kind !== 'spread') continue
-    const constants = restSpreadConstantValues(ctx)
+    const constants = constantValuesByName(ctx)
     for (const name of new Set([attr.value.expr, attr.value.templateExpr])) {
       if (!name) continue
       if (resolveRestSpreadOriginCore(ctx.analyzer, constants, name) !== null) return true
@@ -8055,14 +8202,25 @@ function forwardsCallerRestProps(attrs: IRAttribute[], ctx: TransformContext): b
   return false
 }
 
-/** `ctx.analyzer.localConstants` indexed by name, memoized per component walk. */
-function restSpreadConstantValues(ctx: TransformContext): ReadonlyMap<string, string | undefined> {
-  if (ctx._restSpreadConstantValues) return ctx._restSpreadConstantValues
+/** `ctx.analyzer.localConstants` indexed by name → value text, memoized per component walk. */
+function constantValuesByName(ctx: TransformContext): ReadonlyMap<string, string | undefined> {
+  if (ctx._constantValuesByName) return ctx._constantValuesByName
   const byName = new Map<string, string | undefined>()
   for (const constant of ctx.analyzer.localConstants) {
     if (!byName.has(constant.name)) byName.set(constant.name, constant.value)
   }
-  ctx._restSpreadConstantValues = byName
+  ctx._constantValuesByName = byName
+  return byName
+}
+
+/** `ctx.analyzer.localConstants` indexed by name → full `ConstantInfo`, memoized per component walk. */
+function constantsByName(ctx: TransformContext): ReadonlyMap<string, ConstantInfo> {
+  if (ctx._constantsByName) return ctx._constantsByName
+  const byName = new Map<string, ConstantInfo>()
+  for (const constant of ctx.analyzer.localConstants) {
+    if (!byName.has(constant.name)) byName.set(constant.name, constant)
+  }
+  ctx._constantsByName = byName
   return byName
 }
 

package/src/lowering-registry.ts

@@ -141,6 +141,27 @@ export function matchLoweringCall(
   return null
 }
 
+/**
+ * The child expressions a plugin took responsibility for inside a matched
+ * call (#2843) — the base + every triple's value/guard for a `guard-list`,
+ * or the args for a `helper-call`. Shared by the support gate
+ * (`checkSupport`'s `call` arm in `expression-parser.ts`, which recurses
+ * into these instead of refusing the call's raw argument shapes — a
+ * `guard-list`'s params object literal, for instance, would otherwise be
+ * refused before any adapter ever sees the recognised node) and any future
+ * walker that needs the same "what did this plugin actually consume"
+ * answer, so the two can't drift on what counts as consumed.
+ */
+export function loweringNodeChildren(node: LoweringNode): ParsedExpr[] {
+  if (node.kind === 'helper-call') return [...node.args]
+  const children: ParsedExpr[] = [node.base]
+  for (const t of node.triples) {
+    if (t.guard) children.push(t.guard)
+    children.push(t.value)
+  }
+  return children
+}
+
 /**
  * Whether a `LoweringNode.helper` id is safe to splice directly into an
  * adapter's runtime-helper naming convention (`bf_${helper}` in Go,

package/src/prop-rewrite.ts

@@ -132,6 +132,16 @@ export function collectAstPropRefs(
  * (`{ org }` → `{ org: _p.org }`) so the result stays syntactically
  * valid.
  *
+ * `replacementFor` overrides the substitution text for a value
+ * reference (default `${PROPS_PARAM}.<callerKey>`) — e.g. the reactive
+ * client-JS emit path (`emit-reactive.ts`'s `rewriteDestructuredPropsInExpr`)
+ * wraps it in a `(_p.x ?? <default>)` fallback for a prop with a
+ * destructure default. Kept as a caller override rather than a
+ * duplicate AST walk in that module, per the "one decision, one
+ * implementation" rule (CLAUDE.md) — this walk is already the one place
+ * that correctly distinguishes a value reference from an object-literal
+ * key / property-access name / shorthand property / binding name.
+ *
  * Returns null when `text` does not parse cleanly as an expression —
  * the caller falls back to the legacy regex rewrite.
  */
@@ -139,6 +149,7 @@ function applyScopedPropRefRewrite(
   text: string,
   propRefs: Set<string>,
   propAliases?: ReadonlyMap<string, string>,
+  replacementFor?: (localName: string, callerKey: string) => string,
 ): string | null {
   // Wrap in parens so object literals and arrows parse as expressions.
   const prefix = '('
@@ -157,11 +168,12 @@ function applyScopedPropRefRewrite(
     // — #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
+    const value = replacementFor ? replacementFor(n.text, callerKey) : `${PROPS_PARAM}.${callerKey}`
     if (parent && ts.isShorthandPropertyAssignment(parent) && parent.name === n) {
-      edits.push({ start, end, replacement: `${n.text}: ${PROPS_PARAM}.${callerKey}` })
+      edits.push({ start, end, replacement: `${n.text}: ${value}` })
       return
     }
-    edits.push({ start, end, replacement: `${PROPS_PARAM}.${callerKey}` })
+    edits.push({ start, end, replacement: value })
   })
 
   if (edits.length === 0) return text
@@ -186,6 +198,7 @@ export function applyRegexPropRefRewrite(
   text: string,
   propRefs: Iterable<string>,
   propAliases?: ReadonlyMap<string, string>,
+  replacementFor?: (localName: string, callerKey: string) => string,
 ): string {
   const { protect, restore } = createTemplateAwareStringProtector()
   let result = protect(text)
@@ -193,6 +206,7 @@ export function applyRegexPropRefRewrite(
   for (const propName of propRefs) {
     // `_p` is always keyed by the caller-facing name (#2524 CSR half).
     const callerKey = propAliases?.get(propName) ?? propName
+    const value = replacementFor ? replacementFor(propName, callerKey) : `${PROPS_PARAM}.${callerKey}`
     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 :
@@ -201,7 +215,7 @@ export function applyRegexPropRefRewrite(
         const before = str.slice(0, offset)
         if (/[{,]\s*$/.test(before)) return match
       }
-      return `${PROPS_PARAM}.${callerKey}`
+      return value
     })
   }
 
@@ -225,6 +239,9 @@ export function applyRegexPropRefRewrite(
  *   `_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).
+ * @param replacementFor - Override the substitution text for a value
+ *   reference (default `${PROPS_PARAM}.<callerKey>`) — see
+ *   `applyScopedPropRefRewrite`'s docstring.
  */
 export function rewriteBarePropRefs(
   text: string,
@@ -232,6 +249,7 @@ export function rewriteBarePropRefs(
   propNames: Set<string>,
   extraPropRefs?: ReadonlySet<string>,
   propAliases?: ReadonlyMap<string, string>,
+  replacementFor?: (localName: string, callerKey: string) => string,
 ): string | undefined {
   // Walk AST to find which prop names are actually used as value references
   const foundPropRefs = new Set<string>()
@@ -243,7 +261,7 @@ export function rewriteBarePropRefs(
   }
   if (foundPropRefs.size === 0) return undefined
   return (
-    applyScopedPropRefRewrite(text, foundPropRefs, propAliases) ??
-    applyRegexPropRefRewrite(text, foundPropRefs, propAliases)
+    applyScopedPropRefRewrite(text, foundPropRefs, propAliases, replacementFor) ??
+    applyRegexPropRefRewrite(text, foundPropRefs, propAliases, replacementFor)
   )
 }

package/src/props-binding.ts

@@ -69,6 +69,31 @@ export function buildPropAliasMap(params: readonly ParamInfo[]): Map<string, str
   return map
 }
 
+/**
+ * The props-parameter shape needed to answer "is `name` an actual local
+ * binding introduced by the props parameter" — as opposed to
+ * `ctx.patterns.props`, which for a whole `(props: Props)` parameter holds
+ * every TYPE-MEMBER name (`extractPropsFromTypeMembers`) for regex prop-
+ * access matching, not real bindings.
+ */
+export interface PropsParamBindings {
+  propsParams: readonly ParamInfo[]
+  propsObjectName: string | null
+}
+
+/**
+ * Local names actually bound by the props parameter. Empty for a whole
+ * `(props: Props)` parameter: `propsParams` there is type-member names
+ * (nothing local to shadow with), and `props` itself is `propsObjectName`,
+ * checked separately by callers.
+ */
+export function boundPropLocalNames(b: PropsParamBindings): ReadonlySet<string> {
+  if (b.propsObjectName !== null) return EMPTY_SET
+  return new Set(b.propsParams.filter(p => !p.isRest).map(p => p.name))
+}
+
+const EMPTY_SET: ReadonlySet<string> = new Set()
+
 /**
  * The two component bindings that forward the caller's leftover props:
  * the destructured `...rest` binding and a whole undestructured `(props)`
@@ -82,10 +107,52 @@ export interface RestSpreadBindings {
 }
 
 /**
- * Which of `bindings` the name `name` ultimately reaches, walking through
- * any bare `const x__alias = <name>` hop recorded in `constantValues`
- * (name → initializer text). `'rest'` for the destructured rest binding,
- * `'props'` for the whole props object, `null` for anything else.
+ * Walks a bare `const x__alias = <name>` hop chain recorded in
+ * `constantValues` (name → initializer text) until `terminal` recognizes
+ * the current name, returning what it recognized. `null` when the chain
+ * runs out (a constant whose value isn't a bare identifier — a real
+ * computed object — stops the walk) or degenerates into a cycle.
+ *
+ * The one alias-hop walker in the compiler, shared by every caller that
+ * needs "does this name ultimately reach some fixed binding" rather than
+ * a bespoke copy per caller — `resolveRestSpreadOriginCore` below,
+ * `resolveGetterAliases` (`csr-substitute.ts`, #2778), and
+ * `isArrayExprDirectPropRef` (`jsx-to-ir.ts`, #2724, called directly rather
+ * than through a `*Core`-style wrapper) are its callers, differing only in
+ * what `terminal` recognizes as a hit — and, for `isArrayExprDirectPropRef`,
+ * in also narrowing `constantValues` itself (`propAliasHopCandidates`)
+ * before passing it in. `terminal` is checked BEFORE the constant-value
+ * lookup so a name that is itself a target take priority over any
+ * same-named local shadowing it (preserves `resolveRestSpreadOriginCore`'s
+ * original hop order) — a caller whose `terminal` can itself be fooled by a
+ * shadowed name (e.g. a scope-unaware lookup keyed only by name) must guard
+ * that inside `terminal`, since this walker has no scope/binding awareness
+ * of its own to do it centrally.
+ *
+ * `visited` guards a constant cycle (`const a = b; const b = a`); walking
+ * hop by hop (not a precomputed set) is what lets a multi-hop alias
+ * (`const p2 = props; const p3 = p2`) resolve through every link.
+ */
+export function resolveAliasOrigin<T>(
+  constantValues: ReadonlyMap<string, string | undefined>,
+  name: string,
+  terminal: (name: string) => T | null,
+): T | null {
+  const visited = new Set<string>()
+  let current: string | undefined = name.trim()
+  while (current !== undefined && !visited.has(current)) {
+    const hit = terminal(current)
+    if (hit !== null) return hit
+    visited.add(current)
+    current = constantValues.get(current)?.trim()
+  }
+  return null
+}
+
+/**
+ * Which of `bindings` the name `name` ultimately reaches. `'rest'` for the
+ * destructured rest binding, `'props'` for the whole props object, `null`
+ * for anything else.
  *
  * The single definition of "this `{...spread}` forwards the caller's
  * leftover props", shared by the two phases that must agree on it: Phase 1
@@ -96,26 +163,15 @@ export interface RestSpreadBindings {
  * `spreadAttrs({...})` merge. Two copies of the rule would let an element
  * qualify for one and not the other, which is exactly the silent-drop
  * shape #2754 reports.
- *
- * Walks hop by hop (not a precomputed set) so a multi-hop alias
- * (`const p2 = props; const p3 = p2`) resolves through every link;
- * `visited` guards a constant cycle (`const a = b; const b = a`). A
- * constant whose value isn't a bare identifier on the chain (a real
- * computed object) stops the walk, so a genuinely different spread
- * expression is never mistaken for the rest object.
  */
 export function resolveRestSpreadOriginCore(
   bindings: RestSpreadBindings,
   constantValues: ReadonlyMap<string, string | undefined>,
   name: string,
 ): 'rest' | 'props' | null {
-  const visited = new Set<string>()
-  let current: string | undefined = name.trim()
-  while (current !== undefined && !visited.has(current)) {
+  return resolveAliasOrigin(constantValues, name, (current) => {
     if (bindings.restPropsName && current === bindings.restPropsName) return 'rest'
     if (bindings.propsObjectName && current === bindings.propsObjectName) return 'props'
-    visited.add(current)
-    current = constantValues.get(current)?.trim()
-  }
-  return null
+    return null
+  })
 }

package/src/types.ts

@@ -594,7 +594,9 @@ export interface IRLoop {
   isStaticArray: boolean
 
   /**
-   * True when the array is a direct prop reference promoted to mapArray (#1586).
+   * True when the array is a direct prop reference promoted to mapArray
+   * (#1586) — including one reached only through a bare `const x = y`
+   * alias-hop chain (`isArrayExprDirectPropRef`, jsx-to-ir.ts, #2724).
    * Adapters use this to include the array in JSON serialization (bf-p)
    * even though isStaticArray is false — the client's mapArray needs the
    * initial data for hydration, unlike signal-backed arrays.
@@ -1548,10 +1550,9 @@ export interface SignalInfo {
    * `templateCondition` fields on other IR positions. Destructured mode
    * only (`propsObjectName === null`); undefined when no rewrite was
    * needed (no destructured prop referenced) or the component is in
-   * object-props mode (there, `rewritePropsObjectRef`/`applyPropsRewrite`
-   * handle `props.x` → `_p.x` on the final joined/substituted string
-   * instead, since a bare `props.x` textual match works without an
-   * AST-level pre-rewrite).
+   * object-props mode (there, `rewritePropsObjectRef` handles `props.x` →
+   * `_p.x` on the final joined/substituted string instead, since a bare
+   * `props.x` textual match works without an AST-level pre-rewrite).
    */
   templateInitialValue?: string
   /**