@barefootjs/jsx 0.31.5 → 0.31.7

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

@@ -311,6 +311,78 @@ describe('ClientJS generation with semantic prop refs', () => {
   })
 })
 
+// Issue #2634 regression test: a prop used ONLY inside a `/* @client */`
+// expression was never extracted from `_p` — the identifier reached
+// `createEffect`'s body unbound, throwing `ReferenceError` at hydrate.
+// `buildReferencesGraph` (build-references.ts) deliberately skips adding a
+// `template-closure` edge for a clientOnly expression (it isn't template-
+// reachable), but was never wired to `ctx.clientOnlyElements` either, so no
+// edge of ANY kind reached `neededProps` and `emitPropsExtraction` had no
+// evidence the prop was used at all.
+describe('Issue #2634 regression', () => {
+  test('a destructured prop used only inside /* @client */ is extracted from _p', () => {
+    const source = `
+      interface Props {
+        label: string
+      }
+
+      export function LabelClientOnly({ label }: Props) {
+        return <div>{/* @client */ label.toUpperCase()}</div>
+      }
+    `
+
+    const result = compileJSX(source, 'LabelClientOnly.tsx', { adapter })
+
+    expect(result.errors).toHaveLength(0)
+    const clientJs = result.files.find((f) => f.type === 'clientJs')
+    expect(clientJs).toBeDefined()
+    // The prop must be bound before the createEffect body reads it.
+    expect(clientJs?.content).toContain('const label = _p.label')
+    // A bare `label` reference with no preceding binding is exactly the
+    // unbound-identifier shape that threw ReferenceError at hydrate.
+    expect(clientJs?.content).toMatch(/const label = _p\.label[\s\S]*label\.toUpperCase\(\)/)
+  })
+
+  test('a props-object member used only inside /* @client */ needs no extraction (already _p.x)', () => {
+    const source = `
+      interface Props {
+        label: string
+      }
+
+      export function LabelClientOnly(props: Props) {
+        return <div>{/* @client */ props.label.toUpperCase()}</div>
+      }
+    `
+
+    const result = compileJSX(source, 'LabelClientOnly.tsx', { adapter })
+
+    expect(result.errors).toHaveLength(0)
+    const clientJs = result.files.find((f) => f.type === 'clientJs')
+    expect(clientJs).toBeDefined()
+    expect(clientJs?.content).toContain('_p.label.toUpperCase()')
+  })
+
+  test('a prop used both in a normal reactive position AND inside /* @client */ is still extracted once', () => {
+    const source = `
+      interface Props {
+        label: string
+      }
+
+      export function LabelBoth({ label }: Props) {
+        return <div><span>{label}</span><span>{/* @client */ label.toUpperCase()}</span></div>
+      }
+    `
+
+    const result = compileJSX(source, 'LabelBoth.tsx', { adapter })
+
+    expect(result.errors).toHaveLength(0)
+    const clientJs = result.files.find((f) => f.type === 'clientJs')
+    expect(clientJs).toBeDefined()
+    const matches = clientJs?.content.match(/const label = _p\.label/g) ?? []
+    expect(matches).toHaveLength(1)
+  })
+})
+
 // Issue #257 regression test: Double props prefix in template literals
 describe('Issue #257 regression', () => {
   test('does NOT double-wrap props.xxx when already prefixed', () => {

package/src/__tests__/rich-type-method-refusal.test.ts

@@ -173,14 +173,78 @@ describe('rich-type method-call refusal — fires (BF021)', () => {
     expect(errors[0].message).toContain("'Map'")
   })
 
-  test('diagnostic carries the @client suggestion', () => {
+  // #2636: bare /* @client */ crashes at hydrate for every rich-type
+  // receiver here (the prop arrives de-riched over the JSON bf-p boundary),
+  // so the suggestion must never recommend it bare. Date/URL (JSON-revivable
+  // via their own one-arg constructor) get an explicit-revival @client form
+  // instead; every other host rich type gets pre-compute only.
+  test('Date generic method: pre-compute lead + explicit-revival @client escape, never a bare @client', () => {
     const errors = bf021(`
       export function Foo({ createdAt }: { createdAt: Date }) {
         return <div>{createdAt.toISOString()}</div>
       }
     `)
     expect(errors[0].severity).toBe('error')
-    expect(errors[0].suggestion?.message).toContain('@client')
+    const message = errors[0].suggestion?.message ?? ''
+    expect(message).toContain('Pre-compute')
+    expect(message).toContain('new Date(createdAt)')
+    expect(message).not.toMatch(/Add \/\* @client \*\//)
+    expect(errors[0].suggestion?.escape).toEqual([{ kind: 'prop-precompute' }, { kind: 'client-directive' }])
+  })
+
+  test('Map method: pre-compute only, explicit no-safe-@client-escape warning', () => {
+    const errors = bf021(`
+      export function Foo({ m }: { m: Map<string, string> }) {
+        return <div>{m.get('x')}</div>
+      }
+    `)
+    const message = errors[0].suggestion?.message ?? ''
+    expect(message).toContain('Pre-compute')
+    expect(message).toContain('NOT a safe escape')
+    expect(message).not.toContain('new Map(')
+    expect(errors[0].suggestion?.escape).toEqual([{ kind: 'prop-precompute' }])
+  })
+
+  // Zero-arg toLocaleDateString() is BF021's one case where the refusal is
+  // deliberately ADAPTER-UNIFORM rather than a DSL-adapter-only gap (unlike
+  // BF101's "JS-runtime executes verbatim" carve-out): `TestAdapter extends
+  // JsxAdapter` (adapter-hono's own base class) here, and it still refuses.
+  // See #2356's decision comment and `date-method-uncatalogued.ts`'s
+  // docstring — a JS-runtime adapter's hydrate leg re-evaluates a
+  // prop-derived expression against a JSON-de-riched receiver (a `Date`
+  // prop arrives as its ISO string), so "the SSR runtime can evaluate the
+  // call" does not make the compiled artifact sound; the compiler doesn't
+  // special-case this adapter class here on purpose.
+  test('zero-arg toLocaleDateString() refuses even on a JsxAdapter (#2356 — adapter-uniform by design)', () => {
+    const errors = bf021(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div>{createdAt.toLocaleDateString()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("'.toLocaleDateString()'")
+    expect(errors[0].message).toContain("'createdAt'")
+    // The suggestion for this specific method+type points at the
+    // literal-locale/timeZone escape (#2324) ahead of the generic
+    // pre-compute-or-revival fallback every other BF021 carries.
+    const message = errors[0].suggestion?.message ?? ''
+    expect(message).toContain('literal locale')
+    // #2636: even this branch's @client escape must be the explicit-revival
+    // form, never a bare /* @client */.
+    expect(message).toContain('new Date(createdAt)')
+    expect(errors[0].suggestion?.escape).toEqual([{ kind: 'rewrite' }, { kind: 'prop-precompute' }, { kind: 'client-directive' }])
+  })
+
+  test('URL generic method: revivable tier applies past Date (#2636)', () => {
+    const errors = bf021(`
+      export function Foo({ href }: { href: URL }) {
+        return <div>{href.toString()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    const message = errors[0].suggestion?.message ?? ''
+    expect(message).toContain('new URL(href)')
+    expect(errors[0].suggestion?.escape).toEqual([{ kind: 'prop-precompute' }, { kind: 'client-directive' }])
   })
 })
 
@@ -194,6 +258,19 @@ describe('rich-type method-call refusal — silent (no BF021)', () => {
     expect(errors).toHaveLength(0)
   })
 
+  // Pins the premise the revivable-tier suggestion (#2636) depends on: a
+  // /* @client */ block that wraps the receiver in `new Date(...)` first is
+  // itself a call-result receiver (resolveReceiverType → null), so it never
+  // fires BF021 — the same reason a bare @client call never fires above.
+  test('/* @client */ with explicit new Date(...) revival wrapper', () => {
+    const errors = bf021(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div>{/* @client */ new Date(createdAt).getUTCFullYear()}</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
   test('/* @client */-wrapped conditional branch', () => {
     const errors = bf021(`
       export function Foo({ d }: { d: Date | null }) {

package/src/__tests__/rich-type-prop-serialization.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Rich-type prop serialization refusal (BF049, #2643).
+ *
+ * Sibling of BF021 (`rich-type-method-refusal.test.ts`) for a DIFFERENT
+ * failure shape: whether or not a method is called is irrelevant here. A
+ * rich-typed prop (`Map`, `Set`, `BigInt`, …) used anywhere in this
+ * component's own client code (a handler, an effect) — merely read, or even
+ * method-called (`data.get(...)`, `tags.has(...)`, below) — is invisible to
+ * BF021 either way, since BF021 only walks template-lowered expression
+ * positions and never analyzes a handler/effect body. But the prop still
+ * crosses the `bf-p` hydration boundary as JSON, where it either arrives
+ * de-riched (`Map`/`Set` → `{}`, entries silently dropped) or fails to
+ * serialize at all (`BigInt` throws at SSR render).
+ *
+ * `checkRichTypePropSerialization` is metadata-driven (mirrors the adapter's
+ * own `propsToSerialize` filter), not a lowering-plugin-aware IR walk, so
+ * this suite doesn't need the plugin-registry snapshot dance
+ * `rich-type-method-refusal.test.ts` uses — no lowering matcher can exempt a
+ * prop from serialization the way one exempts a method call from BF021.
+ */
+
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../compiler'
+import { ErrorCodes } from '../errors'
+import { TestAdapter } from '../adapters/test-adapter'
+
+const adapter = new TestAdapter()
+
+function bf049(source: string, filePath = 'Test.tsx') {
+  const result = compileJSX(source, filePath, { adapter })
+  return result.errors.filter((e) => e.code === ErrorCodes.RICH_TYPE_PROP_NOT_HYDRATABLE)
+}
+
+describe('rich-type prop serialization refusal — fires (BF049)', () => {
+  test('Map prop read in a client event handler (destructured)', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ data }: { data: Map<string, number> }) {
+        return <button onClick={() => console.log(data.get('x'))}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].severity).toBe('error')
+    expect(errors[0].message).toContain("Prop 'data'")
+    expect(errors[0].message).toContain("'Map<string, number>'")
+    expect(errors[0].message).toContain('Map cannot')
+    expect(errors[0].suggestion?.escape).toEqual([{ kind: 'prop-precompute' }])
+  })
+
+  test('Set prop read in a client event handler', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ tags }: { tags: Set<string> }) {
+        return <button onClick={() => console.log(tags.has('x'))}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("Prop 'tags'")
+  })
+
+  test('object-form BigInt prop throws at SSR — message names the consequence', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ n }: { n: BigInt }) {
+        return <button onClick={() => console.log(n)}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain('JSON.stringify throws at SSR render')
+  })
+
+  test('bigint KEYWORD prop also fires — closes the keyword-spelling gap BF021 leaves open', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ n }: { n: bigint }) {
+        return <button onClick={() => console.log(n)}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("'bigint'")
+  })
+
+  test('symbol keyword prop fires', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ s }: { s: symbol }) {
+        return <button onClick={() => console.log(s)}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain('drops the value entirely')
+  })
+
+  test('props-object mode (props.data)', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo(props: { data: Map<string, number> }) {
+        return <button onClick={() => console.log(props.data)}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("Prop 'data'")
+  })
+
+  test('renamed destructured prop ({ data: d }) — bf-p key is the source name', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ data: d }: { data: Map<string, number> }) {
+        return <button onClick={() => console.log(d)}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+    expect(errors[0].message).toContain("Prop 'd'")
+  })
+
+  test('optional Map prop (Map<...> | undefined) still resolves via stripUnion', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ data }: { data?: Map<string, number> }) {
+        return <button onClick={() => console.log(data)}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+  })
+
+  test('RegExp prop client-read fires (loses data on JSON round-trip, not merely "degrades to something")', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ pattern }: { pattern: RegExp }) {
+        return <button onClick={() => console.log(pattern.test('x'))}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+  })
+
+  test('Function-typed (object-form) prop client-read fires', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ cb }: { cb: Function }) {
+        return <button onClick={() => cb()}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(1)
+  })
+})
+
+describe('rich-type prop serialization refusal — silent (no BF049)', () => {
+  test('Map prop never read by client code (server-only component)', () => {
+    const errors = bf049(`
+      export function Foo({ data }: { data: Map<string, number> }) {
+        return <div>hi</div>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('Map prop declared but unused by the client init', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ data, label }: { data: Map<string, number>; label: string }) {
+        return <button onClick={() => console.log(label)}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('Date prop client-read is silent — Date is JSON-revivable, not JSON-unsafe', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <button onClick={() => console.log(createdAt)}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('URL prop client-read is silent — same revivable-subset exemption', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ href }: { href: URL }) {
+        return <button onClick={() => console.log(href)}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('two-arm union (RegExp | string) is silent — the InputOTP pattern-prop shape', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ pattern }: { pattern: RegExp | string }) {
+        return <button onClick={() => console.log(pattern)}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('in-file interface Map shadow', () => {
+    const errors = bf049(`
+      'use client'
+      interface Map { iso: string }
+      export function Foo({ data }: { data: Map }) {
+        return <button onClick={() => console.log(data)}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('on-prefixed prop (a function prop) is silent — excluded from serialization entirely', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ onGo }: { onGo: () => void }) {
+        return <button onClick={onGo}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('plain string/number/array props are silent', () => {
+    const errors = bf049(`
+      'use client'
+      export function Foo({ label, count, items }: { label: string; count: number; items: string[] }) {
+        return <button onClick={() => console.log(label, count, items)}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+
+  test('a local type alias of a rich type is a conservative miss (documented, covered by the runtime backstop)', () => {
+    const errors = bf049(`
+      'use client'
+      type RichMap = Map<string, number>
+      export function Foo({ data }: { data: RichMap }) {
+        return <button onClick={() => console.log(data)}>go</button>
+      }
+    `)
+    expect(errors).toHaveLength(0)
+  })
+})

package/src/compiler.ts

@@ -26,7 +26,7 @@ import { applyCssLayerPrefix, applyCssLayerPrefixToFile } from './css-layer-pref
 import { preprocessInlineJsxCallbacks } from './preprocess-inline-jsx-callbacks.ts'
 import { extractSsrDefaults } from './ssr-defaults.ts'
 import { computeSsrSeedPlan } from './ssr-seed-plan.ts'
-import { checkRichTypeMethodCalls } from './rich-type-refusal.ts'
+import { checkRichTypeMethodCalls, checkRichTypePropSerialization } from './rich-type-refusal.ts'
 import { ErrorCodes, createError } from './errors.ts'
 import { collectComponentNamesFromIR } from './ir-to-client-js/child-components.ts'
 
@@ -160,6 +160,7 @@ function compileMultipleComponents(
 
     componentIR.metadata.clientAnalysis = analyzeClientNeeds(componentIR)
     checkRichTypeMethodCalls(componentIR.root, componentIR.metadata, errors)
+    checkRichTypePropSerialization(componentIR.root, componentIR.metadata, errors, ctx.propsDestructuring?.loc)
 
     // Slot unification Step B — see the single-component path's identical
     // call for why this must run before adapter.generate/generateClientJs.
@@ -777,6 +778,7 @@ export function compileJSX(
   // Pre-compute client JS analysis for adapter optimization
   componentIR.metadata.clientAnalysis = analyzeClientNeeds(componentIR)
   checkRichTypeMethodCalls(componentIR.root, componentIR.metadata, errors)
+  checkRichTypePropSerialization(componentIR.root, componentIR.metadata, errors, ctx.propsDestructuring?.loc)
 
   // Slot unification Step B (`spec/slot-unification.md` §5 Step B): decide
   // marker elision ONCE, mutating `componentIR.root` in place, before either

package/src/errors.ts

@@ -53,6 +53,16 @@ export const ErrorCodes = {
   // helper verbatim instead of compiling it as a component — so this code
   // fires only for the client-component compilation path.
   SIBLING_COMPONENT_NOT_COMPILED: 'BF048',
+  // A prop typed as a host rich type whose `JSON.stringify` output is not
+  // revivable (`Map`, `Set`, `BigInt`, …) is used by this component's own
+  // client code (a handler, an effect) — regardless of whether a method is
+  // called on it, since `checkRichTypeMethodCalls`'s BF021 only walks
+  // template-lowered expression positions and never sees a handler/effect
+  // body either way. The prop still crosses the `bf-p` hydration boundary as
+  // JSON and arrives de-riched (or, for `BigInt`, fails to serialize at all,
+  // throwing at SSR render). Sibling of BF021 for the "client-side use"
+  // shape, which BF021's template-only walk can never reach (#2643).
+  RICH_TYPE_PROP_NOT_HYDRATABLE: 'BF049',
 
   // Import errors (BF050-BF059)
   SHARED_PROGRAM_REQUIRED: 'BF050',
@@ -164,6 +174,9 @@ const errorMessages: Record<ErrorCode, string> = {
     "verbatim, see #932), or rewrite it as a single-return ternary/conditional chain so the " +
     "component pipeline can compile it.",
 
+  [ErrorCodes.RICH_TYPE_PROP_NOT_HYDRATABLE]:
+    'Rich-typed prop cannot cross the bf-p hydration boundary as JSON.',
+
   [ErrorCodes.SHARED_PROGRAM_REQUIRED]:
     'Shared ts.Program required for type-based reactivity classification. This source imports a Reactive<T>-branded library (e.g. @barefootjs/form) whose getters cannot be classified by regex alone. Pass `options.program` (built via `createProgramForCorpus`) so the analyzer can resolve the brand through the TypeChecker.',
 

package/src/index.ts

@@ -57,6 +57,9 @@ export type {
   TypeDefinition,
   SourceLocation,
   CompilerError,
+  ErrorSuggestion,
+  EscapeKind,
+  EscapeSsrCost,
   ConformancePin,
   ConformancePins,
   RenderDivergences,
@@ -186,6 +189,9 @@ export interface BarefootPaths {
 // AttrValue constructors
 export { AttrValueOf } from './types.ts'
 
+// Per-escape-kind SSR cost — the one place every renderer reads the trade from (#2613)
+export { ESCAPE_SSR_COST } from './types.ts'
+
 // CSS Layer Prefixer
 export { applyCssLayerPrefix } from './css-layer-prefixer.ts'
 

package/src/ir-to-client-js/build-references.ts

@@ -129,6 +129,23 @@ export function buildReferencesGraph(ctx: ClientJsContext, irRoot: IRNode): Refe
     }
   }
 
+  // No identifiers.ts precedent — `clientOnlyElements` (Slot unification
+  // Step B) postdates the file this phase mirrors. A `/* @client */`
+  // expression's Phase 3 IR-walk visitor below deliberately adds no edge
+  // at all (never mind which context) so a referenced name isn't
+  // misclassified as template-reachable; without a substitute edge here,
+  // a prop used ONLY inside such an expression never reaches
+  // `neededProps` (`analyzeClientNeeds`/`init-declarations.ts`), so
+  // `emitPropsExtraction` never binds it and the emitted `createEffect`
+  // reads an unbound identifier — a real `ReferenceError` at hydrate,
+  // not a hypothetical (#2634). `'init-body'` is the same context an
+  // event handler's identifiers use (few lines up) — correct here for
+  // the same reason: the expression runs in `initX`'s scope, never the
+  // template closure.
+  for (const elem of ctx.clientOnlyElements) {
+    addExprEdges(ROOT_SOURCE, elem.expression, 'init-body')
+  }
+
   // identifiers.ts L107-135
   for (const elem of ctx.loopElements) {
     addExprEdges(ROOT_SOURCE, elem.array, 'template-closure')

package/src/ir-to-client-js/client-only-elision.ts

@@ -3,11 +3,17 @@
  * marker elision"): decide, EXACTLY ONCE and BEFORE either `adapter.generate`
  * (SSR) or `generateClientJs` (CSR) run, which `/* @client *\/` text slots
  * can drop their `<!--bf:sN-->…<!--/-->` marker pair entirely from both
- * outputs. Every consumer (all nine SSR adapters' `renderExpression`, and
- * the CSR emitters in `html-template.ts`) reads the single
- * `IRExpression.markerless` flag this pass writes — nobody re-derives the
- * decision, per CLAUDE.md's "Never add compiler options/hooks for
- * tool-specific output rewriting" spirit: one door in, everyone reads it.
+ * outputs. Every consumer reads the single `IRExpression.markerless` flag
+ * this pass writes; nobody re-derives the decision, per CLAUDE.md's "Never
+ * add compiler options/hooks for tool-specific output rewriting" spirit:
+ * one door in, everyone reads it.
+ *
+ * The consumers are all nine SSR adapters' `renderExpression`, plus BOTH
+ * top-level CSR emitters in `html-template.ts` — `irToHtmlTemplate`'s
+ * `case 'expression'` and `generateCsrTemplateWithOpts`'s own. The second
+ * of those was wired up only by #2617; the flag shipped with just the
+ * first, which is exactly how the divergence that issue fixed went
+ * unnoticed.
  *
  * Scope — deliberately the NARROWEST slice of §3(b)'s elision rule that is
  * fully sound today, not the general case:

package/src/ir-to-client-js/emit-reactive.ts

@@ -282,10 +282,28 @@ function lowerDateCallsInReactiveExpr(expr: string, matcher: LoweringMatcher | n
   return restore(result)
 }
 
+/**
+ * Bind both catalogued-lowering rewrites (#2292 Date accessors, #2324
+ * literal-locale `toLocaleDateString`) once per emit pass, composed into a
+ * single `(expr) => expr` function — identity when this context carries no
+ * Date evidence (`ctx.propsType` unset). Shared by every reactive-emission
+ * site so a catalogued method call re-evaluated at hydrate routes through
+ * the same runtime helper the static template lowering uses, instead of
+ * splicing the raw call verbatim against a JSON-de-riched receiver
+ * (#2640/#2641 — the `/* @client *\/`-expression and reactive-attribute
+ * sites used to skip this; `emitDynamicTextUpdates` below is the original,
+ * always-correct site this generalizes).
+ */
+function makeCataloguedCallLowerer(ctx: ClientJsContext): (expr: string) => string {
+  const dateMatcher = getReactiveDateLoweringMatcher(ctx)
+  const toLocaleMatcher = getReactiveToLocaleMatcher(ctx)
+  if (!dateMatcher && !toLocaleMatcher) return (expr) => expr
+  return (expr) => lowerToLocaleCallsInReactiveExpr(lowerDateCallsInReactiveExpr(expr, dateMatcher), toLocaleMatcher)
+}
+
 /** Emit createEffect blocks that update text nodes for reactive expressions. */
 export function emitDynamicTextUpdates(lines: string[], ctx: ClientJsContext): void {
-  const dateLoweringMatcher = getReactiveDateLoweringMatcher(ctx)
-  const toLocaleMatcher = getReactiveToLocaleMatcher(ctx)
+  const lower = makeCataloguedCallLowerer(ctx)
   // Group elements by expression to consolidate effects with same dependencies
   const byExpression = new Map<string, typeof ctx.dynamicElements>()
   for (const elem of ctx.dynamicElements) {
@@ -297,10 +315,7 @@ export function emitDynamicTextUpdates(lines: string[], ctx: ClientJsContext): v
   }
 
   for (const [rawExpr, elems] of byExpression) {
-    const expr = lowerToLocaleCallsInReactiveExpr(
-      lowerDateCallsInReactiveExpr(rawExpr, dateLoweringMatcher),
-      toLocaleMatcher,
-    )
+    const expr = lower(rawExpr)
     // Separate conditional vs non-conditional elements
     const conditionalElems = elems.filter(e => e.insideConditional)
     const normalElems = elems.filter(e => !e.insideConditional)
@@ -380,6 +395,7 @@ export function emitDynamicTextUpdates(lines: string[], ctx: ClientJsContext): v
  * already known, so there's nothing to disambiguate from other content).
  */
 export function emitClientOnlyExpressions(lines: string[], ctx: ClientJsContext): void {
+  const lower = makeCataloguedCallLowerer(ctx)
   for (const elem of ctx.clientOnlyElements) {
     // Slot unification Step B: `elem.elidedPath`, when present, was proven
     // safe by `client-only-elision.ts` before this pass ran — use the real
@@ -391,7 +407,7 @@ export function emitClientOnlyExpressions(lines: string[], ctx: ClientJsContext)
     lines.push(`  // @client: ${elem.slotId}`)
     lines.push(`  { const ${writer} = lazySlots(__scope, ${claimPlanLiteral(slots)})`)
     lines.push(`  createEffect(() => {`)
-    lines.push(`    ${writer}('${elem.slotId}', ${elem.expression})`)
+    lines.push(`    ${writer}('${elem.slotId}', ${lower(elem.expression)})`)
     lines.push(`  }${bindingIdArg(ctx, elem.slotId)}) }`)
     lines.push('')
   }
@@ -400,6 +416,7 @@ export function emitClientOnlyExpressions(lines: string[], ctx: ClientJsContext)
 /** Emit createEffect blocks that sync reactive attribute values (class, value, checked, etc.). */
 export function emitReactiveAttributeUpdates(lines: string[], ctx: ClientJsContext): void {
   if (ctx.reactiveAttrs.length > 0) {
+    const lower = makeCataloguedCallLowerer(ctx)
     const attrsBySlot = new Map<string, typeof ctx.reactiveAttrs>()
     for (const attr of ctx.reactiveAttrs) {
       if (!attrsBySlot.has(attr.slotId)) {
@@ -413,7 +430,11 @@ export function emitReactiveAttributeUpdates(lines: string[], ctx: ClientJsConte
       lines.push(`  createEffect(() => {`)
       lines.push(`    if (_${v}) {`)
       for (const attr of attrs) {
-        const expression = rewriteDestructuredPropsInExpr(attr.expression, ctx)
+        // Catalogued-lowering MUST run before the bare-prop-name rewrite:
+        // the matcher needs the source-form receiver (a bare identifier or
+        // `props.x`), the exact two shapes `resolveReceiverType` supports —
+        // same ordering `jsx-to-ir.ts`'s static-template path documents.
+        const expression = rewriteDestructuredPropsInExpr(lower(attr.expression), ctx)
         for (const stmt of emitAttrUpdate(`_${v}`, attr.attrName, expression, attr)) {
           lines.push(`      ${stmt}`)
         }