@barefootjs/jsx 0.31.6 → 0.31.8

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

package/src/ir-to-client-js/csr-substitute.ts

@@ -452,8 +452,9 @@ export function buildSignalMemoEnv(
   for (const s of signals) {
     // Env signals (#2057) have no static initial value to bake — their getter
     // is a live request-scoped read (`searchParams().get(k)`). Leave it in the
-    // CSR template as a real call, exactly as the pre-#2057 bare `searchParams()`
-    // import was (it was never a substitutable signal).
+    // CSR template as a real call; `emitRegistrationAndHydration`'s
+    // `buildTemplateDefPart` (#2654) gives the template lambda its own
+    // `const [<getter>] = <envFactory>()` prelude so the call resolves.
     if (s.envReader) continue
     substitutions.set(s.getter, {
       kind: 'call',

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}`)
         }

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

@@ -4,7 +4,7 @@
  * and the final hydrate() call emission.
  */
 
-import type { ComponentIR, IRFragment, IRNode, ReferencesGraph } from '../types.ts'
+import type { ComponentIR, IRFragment, IRNode, ReferencesGraph, SignalInfo } from '../types.ts'
 import type { ClientJsContext } from './types.ts'
 import { PROPS_PARAM } from './utils.ts'
 import { computeInlinability, toLegacyInlinability } from './compute-inlinability.ts'
@@ -115,6 +115,54 @@ export function csrInlinableConstantsFromCtx(ctx: ClientJsContext): Map<string,
   return out
 }
 
+/**
+ * Build the `template:` ComponentDef entry text for a generated
+ * `templateHtml` string.
+ *
+ * When the component holds one or more env signals (`createSearchParams()`,
+ * #2057), the template lambda destructures its own copy of each getter in
+ * a block-body prelude before returning the template literal:
+ *
+ *     template: (_p) => { const [sp] = createSearchParams(); return `...` }
+ *
+ * instead of the plain expression-body form:
+ *
+ *     template: (_p) => `...`
+ *
+ * The template lambda runs at module scope (`render()` / `renderChild()`),
+ * but an env-signal getter is otherwise only ever destructured inside
+ * `init...` — so a template that calls the getter directly (`sp()`,
+ * `searchParams()`) ReferenceErrors the moment it runs (#2654). Before
+ * #2057, `searchParams` was a bare module-scope import and the same
+ * template-body call worked by accident; #2057 moved it behind
+ * `const [sp] = createSearchParams()` without updating template emission.
+ *
+ * The prelude is emitted whenever the component HAS an env signal —
+ * never gated on whether `templateHtml` textually mentions the getter.
+ * Scanning already-emitted template HTML for a getter name would be a
+ * string/regex parse of emitted JS, which CLAUDE.md's parse rule forbids.
+ * Unconditional emission is safe because `createSearchParams()`
+ * (`packages/client/src/reactive.ts`) only returns the shared
+ * `searchParamsTuple` module singleton — no side effect — so declaring it
+ * in a prelude the template body doesn't end up using costs nothing.
+ *
+ * `envFactory` is expected to always be set alongside `envReader` (the
+ * analyzer sets both together, #2057) — the `undefined` branch is a
+ * defensive fallback: if it's ever missing, skip that signal's prelude
+ * line entirely rather than guessing a canonical factory name, leaving
+ * that one signal's template reference exactly as unsound as before this
+ * fix (never worse).
+ */
+function buildTemplateDefPart(ctx: ClientJsContext, templateHtml: string): string {
+  const envDecls = ctx.signals
+    .filter((s): s is SignalInfo & { envFactory: string } => Boolean(s.envReader) && Boolean(s.envFactory))
+    .map((s) => `const [${s.getter}] = ${s.envFactory}()`)
+  if (envDecls.length === 0) {
+    return `template: (${PROPS_PARAM}) => \`${templateHtml}\``
+  }
+  return `template: (${PROPS_PARAM}) => { ${envDecls.join('; ')}; return \`${templateHtml}\` }`
+}
+
 /** Emit hydrate() call that registers component, template, and hydrates. */
 /**
  * Generate the closing brace for the init function and the hydrate() call.
@@ -157,7 +205,7 @@ export function emitRegistrationAndHydration(
   if (canGenerateStaticTemplate(_ir.root, propNamesForStaticCheck, inlinableConstants, unsafeLocalNames)) {
     const templateHtml = irToComponentTemplate(_ir.root, inlinableConstants, restSpreadNames, ctx.propsObjectName)
     if (templateHtml) {
-      defParts.push(`template: (${PROPS_PARAM}) => \`${templateHtml}\``)
+      defParts.push(buildTemplateDefPart(ctx, templateHtml))
     }
   } else {
     // CSR fallback: emit for all components that can't generate static templates.
@@ -173,7 +221,7 @@ export function emitRegistrationAndHydration(
       _ir.root, csrInlinableConstants, ctx, restSpreadNames, ctx.propsObjectName, unsafeLocalNames, ctx.deferredChildSlots
     )
     if (templateHtml) {
-      defParts.push(`template: (${PROPS_PARAM}) => \`${templateHtml}\``)
+      defParts.push(buildTemplateDefPart(ctx, templateHtml))
     }
   }
   // No else: top-level-only components skip template entirely (save bytes)

package/src/ir-to-client-js/html-template.ts

@@ -1810,6 +1810,19 @@ function irToComponentTemplateWithOpts(node: IRNode, opts: TemplateOptions): str
 
     case 'expression': {
       if (node.expr === 'null' || node.expr === 'undefined') return ''
+      // `/* @client */` defers the expression to hydrate — init's
+      // clientOnlyElements effect owns the value (#2645). Mirror
+      // `generateCsrTemplateWithOpts`'s identical branch byte-for-byte:
+      // empty marker pair for SSR parity, or nothing at all when the
+      // elision pass dropped the markers (`markerless` — the claim plan
+      // resolves via `elidedPath`, slot unification Step B). Without this,
+      // this builder inlined the (possibly lowered) expression value
+      // directly into the static template, breaking SSR/CSR byte parity —
+      // SSR renders the region empty, this builder rendered it populated.
+      if (node.clientOnly && node.slotId) {
+        if (node.markerless) return ''
+        return `<!--bf:${node.slotId}--><!--/-->`
+      }
       const wrapped = transformExpr(node.expr, node.templateExpr)
       // Stage 3 / D4 — join an element-array child ({out}) built by the preamble.
       const value = node.joinArrayChild
@@ -2404,10 +2417,15 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
         // `elidedPath` (a precomputed child-index path), not a marker
         // scan, so no anchor comment is needed here at all — matches SSR's
         // fully-empty output for this case byte-for-byte (#2617; this is
-        // the second of the two top-level CSR emitters `irToHtmlTemplate`
-        // and `generateCsrTemplateWithOpts` that must each consult
-        // `markerless` — see that function's own check at this file's
-        // `case 'expression'` for why the two aren't collapsed into one).
+        // one of three whole-component/CSR-path emitters — alongside
+        // `irToHtmlTemplate` (loop/conditional bodies) and
+        // `irToComponentTemplateWithOpts` (the static whole-component
+        // template — #2645 added its own identical branch after this
+        // exact gap let a `/* @client */` text expression inline its
+        // value into the static template, breaking SSR/CSR byte parity)
+        // — that must each consult `markerless` — see those functions'
+        // own checks at this file's `case 'expression'` for why the
+        // three aren't collapsed into one).
         if (node.markerless) return ''
         return `<!--bf:${node.slotId}--><!--/-->`
       }

package/src/rich-type-evidence.ts

@@ -48,6 +48,72 @@ export const HOST_RICH_TYPE_NAMES: ReadonlySet<string> = new Set([
   'Function',
 ])
 
+/**
+ * The subset of `HOST_RICH_TYPE_NAMES` whose `toJSON()` output is accepted
+ * by the type's own one-argument constructor, so a value that crossed the
+ * `bf-p` hydration boundary as JSON can be revived with `new T(jsonValue)`
+ * (#2636). `Date.prototype.toJSON()` returns an ISO string `new Date()`
+ * re-parses; `URL.prototype.toJSON()` returns an `href` string `new URL()`
+ * re-parses. Every other host rich type fails this test:
+ *   - `Map` / `Set` / `WeakMap` / `WeakSet` — `JSON.stringify` drops all
+ *     entries, serializing to `{}`; there is no envelope to revive FROM.
+ *   - `URLSearchParams` / `RegExp` / `Promise` / `Error` — likewise
+ *     serialize to `{}` (or, for `Error`, an empty-looking object missing
+ *     `message`/`stack` under most engines' own `toJSON`-less default).
+ *   - `Symbol` / `Function` — dropped entirely by `JSON.stringify` (become
+ *     `undefined` in an object, elided in an array).
+ *   - `BigInt` — `JSON.stringify` throws `TypeError` before a hydrate-time
+ *     revival could ever run.
+ *
+ * Used only to decide which escape suggestion `rich-type-refusal.ts`'s
+ * `pushDiagnostic` may offer: a bare `/* @client *\/` recommendation is
+ * unsound for every host rich type here (see that module's docstring), but
+ * wrapping the receiver in `new T(...)` — `{/* @client *\/ new
+ * Date(createdAt).getUTCFullYear()}` — is a genuine, hydrate-safe escape
+ * for this subset only.
+ *
+ * A GENERAL typed-prop revival mechanism across the rest of
+ * `HOST_RICH_TYPE_NAMES` — a `bf-p` wire envelope reviving `Map`/`Set`/
+ * `URLSearchParams`/`RegExp`/`BigInt` the way `Date`/`URL` revive via their
+ * own constructor — was evaluated and DEFERRED (#2642), not rejected on
+ * technical grounds. Two decisions worth recording here so a future
+ * contributor doesn't re-litigate them from scratch:
+ *   - A value-shaped sentinel envelope (`{ $map: [[k,v],...] }`, detected
+ *     by `parseProps`) was rejected: the type signal lives in the VALUE, so
+ *     a user prop that happens to share the sentinel's shape would be
+ *     silently misrevived on every adapter, not just ones that emit
+ *     envelopes — the only sound fix is a user-data escaping rule
+ *     implemented in all 9 adapters' serializers, which is the actual
+ *     protocol cost, paid by every payload, not just rich-typed ones.
+ *   - If ever built, the sanctioned shape is TYPE-DIRECTED USE-SITE
+ *     REVIVAL — the generalization of `date()` (`packages/client/src/
+ *     runtime/date.ts`): plain-JSON canonical wire shapes per type, with
+ *     the compiler (which already resolves prop types here) emitting a
+ *     revival call at each prop's client-JS extraction site, not a
+ *     value-sniffing `parseProps` reviver.
+ * `WeakMap` / `WeakSet` / `Promise` / `Symbol` / `Function` are excluded
+ * from that future scope permanently, independent of mechanism — they are
+ * structurally impossible to serialize (non-enumerable by spec, not data,
+ * or identity-is-the-semantics), not merely unrevived today.
+ */
+export const JSON_REVIVABLE_RICH_TYPE_NAMES: ReadonlySet<string> = new Set(['Date', 'URL'])
+
+/**
+ * The complement of `JSON_REVIVABLE_RICH_TYPE_NAMES` within `HOST_RICH_TYPE_NAMES`
+ * — every host rich type whose `JSON.stringify` output is NOT revivable via its
+ * own constructor. Used by `checkRichTypePropSerialization`
+ * (`rich-type-refusal.ts`, #2643) to flag a rich-typed prop that a client
+ * reads but that will cross the `bf-p` hydration boundary de-riched or
+ * (for `BigInt`) fail to serialize at all — a distinct failure from the
+ * method-call refusal above: whether or not client code goes on to call a
+ * method on the value is irrelevant here, since the method-call refusal
+ * only walks template-lowered expression positions and never sees a
+ * handler/effect body regardless.
+ */
+export const JSON_UNSAFE_RICH_TYPE_NAMES: ReadonlySet<string> = new Set(
+  [...HOST_RICH_TYPE_NAMES].filter((n) => !JSON_REVIVABLE_RICH_TYPE_NAMES.has(n)),
+)
+
 /**
  * Strip generic type arguments from a `TypeInfo.raw` string (`Map<string,
  * string>` → `Map`) so a parametrized host type still matches the bare-name
@@ -115,6 +181,44 @@ function lookupProperty(objType: TypeInfo | null, propName: string, meta: Eviden
   return prop ? stripUnion(prop.type) : null
 }
 
+/**
+ * Resolve a prop's declared type straight off `propsType` by its SOURCE
+ * name (`lookupProperty`'s public face for `checkRichTypePropSerialization`,
+ * which has no receiver expression to walk — only a `propsParams` entry).
+ */
+export function resolvePropDeclaredType(propName: string, meta: EvidenceMetadata): TypeInfo | null {
+  return lookupProperty(meta.propsType, propName, meta)
+}
+
+/**
+ * The JSON-unsafe type name a declared prop type resolves to, or `null` if
+ * it isn't one. Recognizes:
+ *   - an interface-kind type whose `baseTypeName` is in
+ *     `JSON_UNSAFE_RICH_TYPE_NAMES` (caller must still apply the in-file
+ *     `typeDefinitions` shadow guard — this function has no `meta` to check
+ *     it against, mirroring `checkRichTypeMethodCalls`'s own split between
+ *     type resolution and shadow-checking);
+ *   - the KEYWORD spellings `bigint` / `symbol`, which `typeNodeToTypeInfo`
+ *     lowers to `{ kind: 'unknown', raw: '<keyword>' }` (only the object-form
+ *     `BigInt` / `Symbol` type references reach `kind: 'interface'` and match
+ *     the catalogue above) — an exact-equality check on the AST-derived raw
+ *     text, the same class of raw use as `baseTypeName`, not a type-syntax
+ *     parse. Closes this module's own documented conservative miss, but only
+ *     for THIS check — `HOST_RICH_TYPE_NAMES`/method-call refusal still miss
+ *     the keyword spellings, unchanged.
+ */
+export function jsonUnsafeTypeName(type: TypeInfo | null): string | null {
+  if (!type) return null
+  if (type.kind === 'interface') {
+    const name = baseTypeName(type.raw)
+    return JSON_UNSAFE_RICH_TYPE_NAMES.has(name) ? name : null
+  }
+  if (type.kind === 'unknown' && (type.raw === 'bigint' || type.raw === 'symbol')) {
+    return type.raw
+  }
+  return null
+}
+
 /**
  * Resolve the TypeInfo of a receiver expression, using only propsType /
  * propsParams / typeDefinitions and the caller-supplied local bindings.