@barefootjs/jsx 0.31.5 → 0.31.7

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

@@ -810,6 +810,36 @@ export function irToHtmlTemplate(node: IRNode, restSpreadNames?: Set<string>, lo
       // no-slotId branch below already uses — `elidedPath` (not this
       // string) is what the claim plan resolves against, so no marker
       // anchor is needed here at all.
+      //
+      // This branch evaluates `node.expr` eagerly, while the sibling
+      // top-level emitter (`generateCsrTemplateWithOpts`) emits NOTHING
+      // for its `markerless` case. That difference is safe only because
+      // this branch is UNREACHABLE today, which rests on three facts —
+      // all three must hold, so check them before widening either one:
+      //
+      //   1. `markerless` is only ever set by `markElided`, which
+      //      `client-only-elision.ts` calls exclusively under
+      //      `child.clientOnly && child.slotId`. So today
+      //      `markerless === true` IMPLIES `clientOnly && slotId` — it is
+      //      never some other, eagerly-renderable kind of markerless slot.
+      //   2. That walk never descends into a loop or conditional: its
+      //      `default:` case freezes the level and returns without
+      //      recursing (only `element` recurses).
+      //   3. This function only ever runs ON loop bodies and conditional
+      //      branches (every caller passes `l.children[0]`, a `renderLeaf`,
+      //      or `whenTrue`/`whenFalse`), and by its own docstring "does not
+      //      honour `clientOnly`".
+      //
+      // (2) + (3) mean no marked node reaches here; (1) means that if one
+      // ever did, eager evaluation would be WRONG — it would render a
+      // deferred `/* @client */` read at template time instead of leaving
+      // it to init's createEffect. So if #2483 widens elision to cover
+      // loop/conditional subtrees, this branch stops being dead code and
+      // must gain the same `clientOnly` deferral check the sibling emitter
+      // has; it cannot simply keep evaluating. The two checks were left
+      // separate rather than collapsed into a shared helper precisely
+      // because their `clientOnly` semantics differ — see that function's
+      // own comment (#2617).
       if (node.markerless) {
         const bare = wrapInterpolation(wrapExpr(node.expr))
         return `\${${bare}}`
@@ -1780,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
@@ -2363,6 +2406,27 @@ function generateCsrTemplateWithOpts(node: IRNode, opts: TemplateOptions): strin
         // the SSR adapters' `renderExpression` byte-for-byte (byte parity):
         // empty at CSR mount too, since the expression is evaluated only
         // once init's createEffect runs, same as the SSR case.
+        //
+        // Slot unification Step B (`markerless`, decided once by
+        // `client-only-elision.ts` before this CSR pass runs; mirrors the
+        // nested `if (expr.markerless) return ''` shape all nine SSR
+        // adapters' `renderExpression` use inside their own identical
+        // `clientOnly && slotId` branch — see `spec/slot-unification.md`
+        // §5a): when the marker pair itself was ALSO elided, drop it and
+        // emit nothing. The claim plan resolves the elided slot via
+        // `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
+        // 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,
   })
 }
 

package/src/types.ts

@@ -2192,9 +2192,62 @@ export interface CompilerError {
   suggestion?: ErrorSuggestion
 }
 
+/**
+ * The kind of escape available from a refusal — the way a user gets their
+ * legitimate, in-subset JSX to compile on an adapter that cannot host it
+ * (#2613).
+ *
+ * Lives here, next to `ErrorSuggestion`, because both halves of the
+ * "loud-or-escapable" contract must speak the SAME enum: the diagnostic
+ * CLAIMS kinds (`ErrorSuggestion.escape`) and a conformance fixture
+ * DEMONSTRATES them (`JSXFixture.escapes`, which re-exports this type —
+ * `@barefootjs/adapter-tests` depends on this package, not the reverse).
+ * `escape-coverage.test.ts` then checks claims are a subset of what the
+ * twins prove, which is only meaningful while the two share one union.
+ */
+export type EscapeKind = 'client-directive' | 'prop-precompute' | 'rewrite'
+
+/**
+ * What an escape costs at SSR. `'none'` — full server render, the result
+ * is present in the server HTML. `'client-render'` — the region is EMPTY
+ * in server HTML until hydration.
+ *
+ * Output-equivalence is explicitly NOT the bar for an escape (#2613): a
+ * `/* @client *\/` region is definitionally not equivalent, and that is a
+ * legitimate trade the user chooses. Making the cost typed and visible is
+ * the honest substitute for pretending it doesn't exist — every renderer
+ * that surfaces an escape surfaces its cost from THIS map, so the trade
+ * can never be quietly dropped on the way to a user.
+ */
+export type EscapeSsrCost = 'none' | 'client-render'
+
+export const ESCAPE_SSR_COST: Record<EscapeKind, EscapeSsrCost> = {
+  // `/* @client */` — compiles and hydrates correctly, renders nothing at SSR.
+  'client-directive': 'client-render',
+  // The refused computation moves to an already-computed prop.
+  'prop-precompute': 'none',
+  // The source is restructured into an equivalent in-subset shape.
+  rewrite: 'none',
+}
+
 export interface ErrorSuggestion {
   message: string
   replacement?: string
+  /**
+   * The escape kinds this diagnostic CLAIMS are available, structured
+   * (#2613 increment 3). Additive and one-way: `message` stays
+   * authoritative for humans — several sites have genuinely good
+   * site-specific prose no enum should flatten — while this field is
+   * authoritative for machines (`bf compat`'s legend, the docs matrix,
+   * claim verification). New and edited refusal sites populate it; older
+   * sites migrate opportunistically, so ABSENT means "not yet declared",
+   * never "no escape exists".
+   *
+   * Order carries the recommendation: list a `ssrCost: 'none'` escape
+   * before a `'client-render'` one, matching the prose rule that a
+   * full-SSR way out is offered first.
+   */
+  escape?: ReadonlyArray<{ kind: EscapeKind }>
 }
 
 /**
@@ -2211,6 +2264,30 @@ export interface ConformancePin {
   severity: 'error' | 'warning'
   /** Tracking issue URL (known-limitation label) for this refusal, when one exists. */
   issue?: string
+  /**
+   * Present when THIS adapter has no verified escape yet for this
+   * refusal — the per-adapter half of #2613's "loud-or-escapable" floor
+   * (`packages/compat/src/__tests__/escape-coverage.test.ts`). `issue` is
+   * the tracking pointer for closing the gap (fall back to
+   * https://github.com/piconic-ai/barefootjs/issues/2613 itself when no
+   * more specific issue exists yet).
+   *
+   * Declared here, next to the refusal it qualifies, so an adapter's own
+   * package is the sole place that states what it knows about its own
+   * refusal — no central cross-adapter ledger to keep in sync (that was
+   * the architectural defect increment 1 shipped with: a `packages/compat`
+   * test hardcoding every adapter's id, which made adapters non-additive).
+   *
+   * Absent means the adapter believes an escape is owed here — either
+   * already satisfied (the refused fixture's `escapes` twin compiles
+   * clean, unpinned, non-divergent, and not CSR-skipped on THIS adapter)
+   * or a pending gap the floor test won't let merge silently.
+   *
+   * Shrink-only, same discipline `KNOWN_HOLES` established: once a
+   * working twin exists here, a lingering `unescapable` becomes a STALE
+   * declaration and the floor test fails loudly on it, naming this pin.
+   */
+  unescapable?: { issue: string }
 }
 /** Keyed by shared-fixture id (`JSXFixture.id`). */
 export type ConformancePins = Record<string, ReadonlyArray<ConformancePin>>