@barefootjs/jsx 0.31.6 → 0.31.7

package/src/__tests__/client-only-date-lowering.test.ts

@@ -0,0 +1,182 @@
+/**
+ * Catalogued Date/URL calls inside `/* @client *​/` expressions and reactive
+ * attribute bindings (#2640, #2641).
+ *
+ * `emitClientOnlyExpressions` and `emitReactiveAttributeUpdates`
+ * (`ir-to-client-js/emit-reactive.ts`) used to splice a reactive expression's
+ * source text VERBATIM into the emitted `createEffect` body — correct for an
+ * un-catalogued method (BF021 already refused anything else, and the
+ * `/* @client *​/` escape is genuinely just "run this raw"), but wrong for a
+ * CATALOGUED method (`.toISOString()`, an explicit-locale
+ * `.toLocaleDateString(...)`, #2292/#2324): those never fire BF021 (a
+ * registered lowering plugin claims them), yet the receiver still crosses
+ * the `bf-p` hydration boundary as a de-riched JSON value. The sibling
+ * non-`@client` TEXT path (`emitDynamicTextUpdates`) already routed a
+ * catalogued call through the `date`/`formatDate` runtime helper before
+ * hydrate re-evaluates it (#2292) — these two sites now share that same
+ * rewrite via `makeCataloguedCallLowerer`.
+ *
+ * This suite compiles through `../index` (not the bare `../compiler`) so the
+ * built-in lowering plugins (`datePlugin`, `toLocaleDatePlugin`) are
+ * registered as the real package does — a call the registry doesn't know
+ * about would fire BF021 and never reach the reactive-emission sites this
+ * suite is about.
+ */
+import { describe, test, expect } from 'bun:test'
+import { compileJSX } from '../index'
+import { TestAdapter } from '../adapters/test-adapter'
+import { ErrorCodes } from '../errors'
+
+function compile(src: string) {
+  const result = compileJSX(src.trimStart(), 'T.tsx', { adapter: new TestAdapter() })
+  const clientJs = result.files.find((f) => f.type === 'clientJs')!.content
+  const bf021 = result.errors.filter((e) => e.code === ErrorCodes.UNSUPPORTED_JSX_PATTERN)
+  return { clientJs, bf021 }
+}
+
+describe('#2640 — /* @client */ text expressions route catalogued calls through the runtime helper', () => {
+  test('a catalogued zero-arg accessor lowers to date(...), not the raw call', () => {
+    const { clientJs, bf021 } = compile(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div>{/* @client */ createdAt.toISOString()}</div>
+      }
+    `)
+    expect(bf021).toHaveLength(0)
+    expect(clientJs).toContain('date(createdAt, "toISOString")')
+    expect(clientJs).not.toContain('createdAt.toISOString()')
+    expect(clientJs).toMatch(/import\s*\{[^}]*\bdate\b[^}]*\}\s*from\s*'@barefootjs\/client\/runtime'/)
+  })
+
+  test('an explicit-locale toLocaleDateString lowers to formatDate(...)', () => {
+    const { clientJs, bf021 } = compile(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div>{/* @client */ createdAt.toLocaleDateString('ja-JP', { timeZone: 'UTC' })}</div>
+      }
+    `)
+    expect(bf021).toHaveLength(0)
+    expect(clientJs).toContain('formatDate(createdAt, "YYYY/M/D", "UTC")')
+    expect(clientJs).not.toContain(".toLocaleDateString('ja-JP'")
+  })
+
+  test('an UNCATALOGUED method call stays verbatim (only what the matcher claims is rewritten)', () => {
+    const { clientJs, bf021 } = compile(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div>{/* @client */ createdAt.getDay()}</div>
+      }
+    `)
+    expect(bf021).toHaveLength(0)
+    expect(clientJs).toContain('createdAt.getDay()')
+    expect(clientJs).not.toContain('date(')
+  })
+
+  test('a zero-arg toLocaleDateString() (implicit locale) stays verbatim — the deliberate revival-escape case (#2639)', () => {
+    // BF021 refuses this shape outside /* @client */ and recommends the
+    // explicit `new Date(...)` revival wrapper as the sound escape; inside
+    // /* @client */ it never fires (the directive already opts out), and
+    // this suite pins that the compiler does NOT special-case it further —
+    // an implicit-locale call is genuinely the user's own responsibility.
+    const { clientJs, bf021 } = compile(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div>{/* @client */ createdAt.toLocaleDateString()}</div>
+      }
+    `)
+    expect(bf021).toHaveLength(0)
+    expect(clientJs).toContain('createdAt.toLocaleDateString()')
+    expect(clientJs).not.toContain('formatDate(')
+  })
+})
+
+describe('#2641 — reactive attribute bindings route catalogued calls through the runtime helper', () => {
+  test('/* @client */ attribute, destructured-prop style', () => {
+    const { clientJs, bf021 } = compile(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div data-x={/* @client */ createdAt.toISOString()} />
+      }
+    `)
+    expect(bf021).toHaveLength(0)
+    expect(clientJs).toContain('date(_p.createdAt, "toISOString")')
+    expect(clientJs).not.toContain('createdAt.toISOString()')
+  })
+
+  test('/* @client */ attribute, props-object style', () => {
+    const { clientJs, bf021 } = compile(`
+      export function Foo(props: { createdAt: Date }) {
+        return <div data-x={/* @client */ props.createdAt.toISOString()} />
+      }
+    `)
+    expect(bf021).toHaveLength(0)
+    expect(clientJs).toContain('date(_p.createdAt, "toISOString")')
+    expect(clientJs).not.toContain('props.createdAt.toISOString()')
+  })
+
+  test('non-@client reactive attribute, a catalogued call — the broader gap #2641 found: this site has no directive at all, and previously spliced the raw call verbatim too', () => {
+    const { clientJs, bf021 } = compile(`
+      export function Foo({ createdAt, label }: { createdAt: Date; label: string }) {
+        return <time data-iso={createdAt.toISOString()}>{label}</time>
+      }
+    `)
+    expect(bf021).toHaveLength(0)
+    expect(clientJs).toContain('date(_p.createdAt, "toISOString")')
+    expect(clientJs).not.toContain('_p.createdAt.toISOString()')
+  })
+
+  test('an explicit-locale toLocaleDateString in attribute position lowers to formatDate(...)', () => {
+    const { clientJs, bf021 } = compile(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div data-x={/* @client */ createdAt.toLocaleDateString('ja-JP', { timeZone: 'UTC' })} />
+      }
+    `)
+    expect(bf021).toHaveLength(0)
+    expect(clientJs).toContain('formatDate(_p.createdAt, "YYYY/M/D", "UTC")')
+  })
+
+  test('an uncatalogued attribute method call stays verbatim', () => {
+    const { clientJs, bf021 } = compile(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div data-x={/* @client */ createdAt.getDay()} />
+      }
+    `)
+    expect(bf021).toHaveLength(0)
+    expect(clientJs).toContain('createdAt.getDay()')
+    expect(clientJs).not.toContain('date(')
+  })
+
+  test('a non-Date reactive attribute is untouched', () => {
+    const { clientJs, bf021 } = compile(`
+      export function Foo({ label }: { label: string }) {
+        return <div data-x={/* @client */ label.toUpperCase()} />
+      }
+    `)
+    expect(bf021).toHaveLength(0)
+    expect(clientJs).toContain('label.toUpperCase()')
+    expect(clientJs).not.toContain('date(')
+  })
+})
+
+describe('#2645 — /* @client */ text expressions elide in the static/CSR template like SSR', () => {
+  // `irToComponentTemplateWithOpts`'s 'expression' case never checked
+  // `node.clientOnly` — a bare-destructured-prop receiver (`isSimplePropExpression`
+  // treats `createdAt.toISOString()` as "simple") routed to this static
+  // template builder, which had no clientOnly awareness and inlined the
+  // (possibly lowered) value directly, breaking SSR/CSR byte parity: SSR
+  // renders the @client region empty, this builder rendered it populated.
+  test('markerless: the region is fully empty, matching SSR', () => {
+    const { clientJs, bf021 } = compile(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div>{/* @client */ createdAt.toISOString()}</div>
+      }
+    `)
+    expect(bf021).toHaveLength(0)
+    expect(clientJs).toContain('template: (_p) => `<div bf="s1"></div>`')
+  })
+
+  test('marker pair (adjacent static text defeats markerless elision): empty marker pair, no inlined value', () => {
+    const { clientJs, bf021 } = compile(`
+      export function Foo({ createdAt }: { createdAt: Date }) {
+        return <div>ISO: {/* @client */ createdAt.toISOString()}</div>
+      }
+    `)
+    expect(bf021).toHaveLength(0)
+    expect(clientJs).toContain('template: (_p) => `<div bf="s1">ISO: <!--bf:s0--><!--/--></div>`')
+  })
+})

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/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')