@barefootjs/jsx 0.31.6 → 0.31.7

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/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.

package/src/rich-type-refusal.ts

@@ -1,17 +1,31 @@
 /**
- * Rich-type method-call refusal (#2273).
+ * Rich-type refusals: two sibling checks over a prop typed as a built-in
+ * "host rich type" (`Date`, `Map`, …), for the two distinct ways such a
+ * value breaks that have nothing to do with each other structurally.
  *
- * A method call on a prop typed as a built-in "host rich type" (`Date`,
- * `Map`, …) has no catalogued lowering — no adapter can emit `.toISOString()`
- * into a template. Left unchecked, such a call transliterates into the
- * target template's own dot-call syntax and dies at request time (a Go
- * template `.CreatedAt.ToISOString` panic, a Jinja `AttributeError`, …),
- * once per adapter, only once someone renders the page. This module makes
- * that gap loud at compile time instead: `checkRichTypeMethodCalls` walks
- * every expression position the compiler already treats as template-lowered
- * and pushes BF021 for any call this build has no evidence a lowering plugin
+ * `checkRichTypeMethodCalls` (#2273, BF021): a METHOD CALL on the receiver
+ * has no catalogued lowering — no adapter can emit `.toISOString()` into a
+ * template. Left unchecked, such a call transliterates into the target
+ * template's own dot-call syntax and dies at request time (a Go template
+ * `.CreatedAt.ToISOString` panic, a Jinja `AttributeError`, …), once per
+ * adapter, only once someone renders the page. This module makes that gap
+ * loud at compile time instead: `checkRichTypeMethodCalls` walks every
+ * expression position the compiler already treats as template-lowered and
+ * pushes BF021 for any call this build has no evidence a lowering plugin
  * (or `/* @client *\/`) will handle.
  *
+ * `checkRichTypePropSerialization` (#2643, BF049): a rich-typed prop is used
+ * anywhere in this component's own CLIENT code (a handler, an effect) —
+ * regardless of whether a method is ever called on it. `checkRichTypeMethodCalls`
+ * only walks expression positions reachable through template lowering (JSX
+ * text/attribute positions rendered at SSR); a handler or effect body is a
+ * different code path it never analyzes, so even a method call there (e.g.
+ * `data.get(...)` inside an `onClick`) is just as invisible to it as a bare
+ * read. Either way the prop still crosses the `bf-p` hydration boundary as
+ * JSON: it arrives de-riched (`Map`/`Set` → `{}`) or fails to serialize
+ * (`BigInt` throws at SSR render). See that function's own doc for
+ * why this is metadata-driven rather than an IR walk.
+ *
  * Deliberately conservative in both directions:
  *   - `resolveReceiverType` (rich-type-evidence.ts) returns `null` — no
  *     opinion — for any receiver shape it can't prove a type for, so an
@@ -22,6 +36,19 @@
  *     claims (`prepareLoweringMatchers`) is exempt — the seam #2274 and
  *     later plugins use to catalogue a rich-type API without touching this
  *     module.
+ *
+ * Every receiver this module can prove a type for is rooted at `propsType`
+ * (`resolveReceiverType` only resolves a bare prop, a `props.x` chain, or a
+ * loop item of a prop array) — so it always crosses the `bf-p` hydration
+ * boundary as JSON. That means `/* @client *\/`, the escape this module used
+ * to recommend unconditionally, is UNSOUND on its own: the receiver arrives
+ * de-riched (a `Date` prop as an ISO string, a `Map`/`Set` as `{}`), so the
+ * spliced call throws or silently misbehaves at hydrate (#2636).
+ * `buildSuggestion` never offers a bare `/* @client *\/` for this reason —
+ * only a pre-compute-server-side escape (sound for every host rich type)
+ * and, for `Date`/`URL` only, a `/* @client *\/` block that explicitly
+ * revives the receiver first (`new Date(createdAt)...`), since those two
+ * types' `toJSON()` output round-trips through their own constructor.
  */
 
 import type {
@@ -32,12 +59,20 @@ import type {
   TypeInfo,
   AttrValue,
   IRTemplatePart,
+  EscapeKind,
 } from './types.ts'
 import type { ParsedExpr } from './expression-parser.ts'
 import { parseExpression } from './expression-parser.ts'
 import { prepareLoweringMatchers, type LoweringMatcher } from './lowering-registry.ts'
 import { ErrorCodes } from './errors.ts'
-import { resolveReceiverType, baseTypeName, HOST_RICH_TYPE_NAMES } from './rich-type-evidence.ts'
+import {
+  resolveReceiverType,
+  baseTypeName,
+  HOST_RICH_TYPE_NAMES,
+  JSON_REVIVABLE_RICH_TYPE_NAMES,
+  resolvePropDeclaredType,
+  jsonUnsafeTypeName,
+} from './rich-type-evidence.ts'
 
 type Bindings = ReadonlyMap<string, TypeInfo | null>
 const EMPTY_BINDINGS: Bindings = new Map()
@@ -59,6 +94,72 @@ export function checkRichTypeMethodCalls(root: IRNode, metadata: IRMetadata, err
   walkNode(root, metadata, EMPTY_BINDINGS, matchers, errors, seen)
 }
 
+/**
+ * BF049 (#2643): flag a prop typed as a JSON-unsafe host rich type
+ * (`Map`, `Set`, `BigInt`, …) that this component's own client code reads —
+ * regardless of whether a method is ever called on it, since
+ * `checkRichTypeMethodCalls` 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: it arrives de-riched
+ * (`Map`/`Set` → `{}`, every entry silently
+ * dropped) or fails to serialize at all (`BigInt` throws `TypeError` at SSR
+ * render, killing the whole page).
+ *
+ * Metadata-driven, not an IR walk — the fire condition is "this prop WILL BE
+ * SERIALIZED into bf-p", which is exactly what `ir.metadata.clientAnalysis`
+ * (`analyzeClientNeeds`) already decided, and what every adapter's own
+ * prop-serialization step (e.g. Hono's `propsToSerialize` filter in
+ * `hono-adapter.ts`) reads off the SAME metadata. Mirroring that filter here
+ * — rather than re-walking JSX attribute positions — means this check fires
+ * in lockstep with what actually gets serialized, on every adapter, without
+ * duplicating per-adapter serialization logic into the compiler.
+ */
+export function checkRichTypePropSerialization(root: IRNode, metadata: IRMetadata, errors: CompilerError[], declLoc?: SourceLocation): void {
+  if (!metadata.propsType || !metadata.clientAnalysis?.needsInit) return
+  const usedProps = new Set(metadata.clientAnalysis.usedProps)
+  const loc = declLoc ?? root.loc
+  for (const param of metadata.propsParams) {
+    if (param.isRest || param.name.startsWith('on') || param.name.startsWith('__')) continue
+    if (!usedProps.has(param.name)) continue
+    const declared = resolvePropDeclaredType(param.sourceName ?? param.name, metadata)
+    const typeName = jsonUnsafeTypeName(declared)
+    if (!typeName) continue
+    // In-file shadow guard, mirroring `checkExpr`'s identical check for the
+    // method-call refusal — a local `interface Map { … }` wins.
+    if (metadata.typeDefinitions.some((d) => d.name === typeName)) continue
+    pushPropSerializationDiagnostic(errors, loc, param.name, typeName, declared!.raw)
+  }
+}
+
+function pushPropSerializationDiagnostic(
+  errors: CompilerError[],
+  loc: SourceLocation,
+  propName: string,
+  typeName: string,
+  declaredRaw: string,
+): void {
+  const consequence =
+    typeName === 'bigint' || typeName === 'BigInt'
+      ? "JSON.stringify throws at SSR render ('Do not know how to serialize a BigInt'), failing the whole page"
+      : typeName === 'symbol' || typeName === 'Symbol' || typeName === 'Function'
+        ? 'JSON.stringify drops the value entirely, so the client reads undefined at hydrate'
+        : 'it serializes de-riched (e.g. a Map or Set becomes {} with every entry silently dropped), so the client hydrates against corrupt data'
+  errors.push({
+    code: ErrorCodes.RICH_TYPE_PROP_NOT_HYDRATABLE,
+    severity: 'error',
+    message: `Prop '${propName}' is typed '${declaredRaw}' and is read by this component's own client code, so it must cross the bf-p hydration boundary as JSON — and ${typeName} cannot: ${consequence}.`,
+    loc,
+    suggestion: {
+      message:
+        'Pre-compute a JSON-serializable value server-side — a string, number, boolean, array, or plain object ' +
+        '(e.g. pass [...map.entries()] and rebuild the Map client-side where needed) — and pass that as the prop ' +
+        'instead. /* @client */ is NOT an escape here: the prop still crosses the bf-p boundary as JSON and arrives ' +
+        'de-riched (#2636).',
+      escape: [{ kind: 'prop-precompute' }],
+    },
+  })
+}
+
 function isLoweringClaimed(matchers: readonly LoweringMatcher[], callee: ParsedExpr, args: readonly ParsedExpr[]): boolean {
   return matchers.some((m) => m(callee, args) !== null)
 }
@@ -83,6 +184,69 @@ function receiverRootIsProp(expr: ParsedExpr, bindings: Bindings): boolean {
   return root.kind === 'identifier' && !bindings.has(root.name)
 }
 
+/**
+ * Build this refusal's escape suggestion (#2636).
+ *
+ * Every receiver `checkRichTypeMethodCalls` can flag is prop-rooted (see the
+ * module docstring's `resolveReceiverType` note), so it crosses the `bf-p`
+ * hydration boundary as JSON with no type-aware revival — a bare
+ * `/* @client *\/` recommendation is unsound for ALL of them: the receiver
+ * arrives at hydrate de-riched (a `Date` prop as its ISO string, a `Map`/`Set`
+ * as `{}`), so the spliced-verbatim call throws or silently misbehaves. This
+ * function therefore never recommends a bare `/* @client *\/`. Two real
+ * escapes exist instead:
+ *   - Pre-compute server-side and pass the result as an already-serializable
+ *     prop — sound for every host rich type, always offered first
+ *     (`ssrCost: 'none'` before `'client-render'`, per `ErrorSuggestion`).
+ *   - For `Date` / `URL` only (`JSON_REVIVABLE_RICH_TYPE_NAMES`), a
+ *     `/* @client *\/` block that explicitly REVIVES the receiver —
+ *     `new Date(createdAt).getUTCFullYear()` — is genuinely hydrate-safe,
+ *     because both types' `toJSON()` output round-trips through their own
+ *     one-arg constructor. Every other host rich type has no such escape:
+ *     the suggestion says so, rather than staying silent about it.
+ */
+function buildSuggestion(
+  method: string,
+  receiverPath: string,
+  receiver: string,
+  typeName: string,
+): { message: string; escape: ReadonlyArray<{ kind: EscapeKind }> } {
+  const revivalExpr =
+    receiverPath === '<expression>'
+      ? `wrapping the receiver in new ${typeName}(...) before calling .${method}()`
+      : `{/* @client */ new ${typeName}(${receiverPath}).${method}(...)}`
+  const revivalReason = `a bare /* @client */ crashes at hydrate because ${receiver} crosses the bf-p boundary as JSON and arrives as a plain string, not a ${typeName} instance (#2636)`
+
+  // `toLocaleDateString` has a catalogued explicit-input form (#2324 slice
+  // 2) — point the fix at it instead of the generic escape hatches alone.
+  // The implicit-environment forms (zero-arg, locale-only, non-literal
+  // locale, an unverifiable timeZone literal) stay refused by design;
+  // canonical IANA zone literals compile since #2344.
+  if (method === 'toLocaleDateString' && typeName === 'Date') {
+    return {
+      message:
+        "Pass a literal locale and an explicit literal timeZone — .toLocaleDateString('ja-JP', { timeZone: 'UTC' }), a fixed '±HH:MM' offset, or a canonical IANA zone ID like 'Asia/Tokyo' (exact case; #2344) — to compile it to the format_date helper; for a runtime locale, resolve the pattern in your i18n layer and use formatDate(date, pattern, tz) from @barefootjs/client. " +
+        `Alternatively pre-compute server-side, or evaluate client-only by ${revivalExpr} — ${revivalReason}.`,
+      escape: [{ kind: 'rewrite' }, { kind: 'prop-precompute' }, { kind: 'client-directive' }],
+    }
+  }
+
+  if (JSON_REVIVABLE_RICH_TYPE_NAMES.has(typeName)) {
+    return {
+      message: `Pre-compute the value server-side and pass it as a prop. Alternatively, evaluate client-only by ${revivalExpr} — ${revivalReason}.`,
+      escape: [{ kind: 'prop-precompute' }, { kind: 'client-directive' }],
+    }
+  }
+
+  return {
+    message:
+      `Pre-compute the value server-side and pass the result — a string, number, array, or plain object — as a prop. ` +
+      `/* @client */ is NOT a safe escape here: ${receiver} cannot cross the bf-p hydration boundary as JSON — it arrives de-riched ` +
+      `(e.g. a Map or Set serializes to {}), so the call throws or silently returns the wrong result at hydrate (#2636).`,
+    escape: [{ kind: 'prop-precompute' }],
+  }
+}
+
 function pushDiagnostic(
   errors: CompilerError[],
   seen: Set<string>,
@@ -96,23 +260,13 @@ function pushDiagnostic(
   if (seen.has(key)) return
   seen.add(key)
   const receiver = isProp ? `prop '${receiverPath}'` : `'${receiverPath}'`
-  // `toLocaleDateString` has a catalogued explicit-input form (#2324 slice
-  // 2) — point the fix at it instead of the generic escape hatches alone.
-  // The implicit-environment forms (zero-arg, locale-only, non-literal
-  // locale, an unverifiable timeZone literal) stay refused by design;
-  // canonical IANA zone literals compile since #2344.
-  const suggestion =
-    method === 'toLocaleDateString' && typeName === 'Date'
-      ? "Pass a literal locale and an explicit literal timeZone — .toLocaleDateString('ja-JP', { timeZone: 'UTC' }), a fixed '±HH:MM' offset, or a canonical IANA zone ID like 'Asia/Tokyo' (exact case; #2344) — to compile it to the format_date helper; for a runtime locale, resolve the pattern in your i18n layer and use formatDate(date, pattern, tz) from @barefootjs/client. Alternatively add /* @client */ or pre-compute server-side."
-      : 'Add /* @client */ to evaluate this expression on the client only, or pre-compute the value server-side.'
+  const suggestion = buildSuggestion(method, receiverPath, receiver, typeName)
   errors.push({
     code: ErrorCodes.UNSUPPORTED_JSX_PATTERN,
     severity: 'error',
     message: `Expression cannot be compiled to marked template: method '.${method}()' on ${receiver} of host type '${typeName}' has no catalogued lowering.`,
     loc,
-    suggestion: {
-      message: suggestion,
-    },
+    suggestion,
   })
 }