@barefootjs/jsx 0.31.6 → 0.31.7

package/dist/compiler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,cAAc,EACd,aAAa,EACb,UAAU,EACX,MAAM,YAAY,CAAA;AAEnB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,EAAE,gBAAgB,EAAyE,MAAM,eAAe,CAAA;AAiBvH;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,cAAc;IAC/D,wDAAwD;IACxD,OAAO,EAAE,eAAe,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAyC5D;AA6hBD,wBAAgB,aAAa,CAC3B,GAAG,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,GACvC,UAAU,CAoCZ;AAMD,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,yBAAyB,GACjC,aAAa,CAuPf;AAMD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,CAAA"}
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../src/compiler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,cAAc,EACd,aAAa,EACb,UAAU,EACX,MAAM,YAAY,CAAA;AAEnB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,EAAE,gBAAgB,EAAyE,MAAM,eAAe,CAAA;AAiBvH;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,cAAc;IAC/D,wDAAwD;IACxD,OAAO,EAAE,eAAe,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAyC5D;AA8hBD,wBAAgB,aAAa,CAC3B,GAAG,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,GACvC,UAAU,CAoCZ;AAMD,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,yBAAyB,GACjC,aAAa,CAwPf;AAMD,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,EAAE,CAAA"}

package/dist/errors.d.ts

@@ -16,6 +16,7 @@ export declare const ErrorCodes: {
     readonly COMPONENT_REQUIRED_PROP_MISSING: 'BF046';
     readonly JSX_BRANCH_LOCAL_IN_CALLBACK: 'BF047';
     readonly SIBLING_COMPONENT_NOT_COMPILED: 'BF048';
+    readonly RICH_TYPE_PROP_NOT_HYDRATABLE: 'BF049';
     readonly SHARED_PROGRAM_REQUIRED: 'BF050';
     readonly WRONG_PACKAGE_IMPORT: 'BF051';
     readonly BUILTIN_REQUIRES_IMPORT: 'BF054';

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,cAAc,EACf,MAAM,YAAY,CAAA;AAMnB,eAAO,MAAM,UAAU;aAErB,kBAAkB,EAAE,OAAO;aAC3B,uBAAuB,EAAE,OAAO;aAGhC,wBAAwB,EAAE,OAAO;aAGjC,uBAAuB,EAAE,OAAO;aAChC,mBAAmB,EAAE,OAAO;aAC5B,0BAA0B,EAAE,OAAO;aACnC,4BAA4B,EAAE,OAAO;aAGrC,mBAAmB,EAAE,OAAO;aAC5B,wBAAwB,EAAE,OAAO;aACjC,qBAAqB,EAAE,OAAO;aAC9B,+BAA+B,EAAE,OAAO;aAUxC,4BAA4B,EAAE,OAAO;aAUrC,8BAA8B,EAAE,OAAO;aAGvC,uBAAuB,EAAE,OAAO;aAChC,oBAAoB,EAAE,OAAO;aAK7B,uBAAuB,EAAE,OAAO;aAQhC,6BAA6B,EAAE,OAAO;aAGtC,mCAAmC,EAAE,OAAO;aAQ5C,iCAAiC,EAAE,OAAO;aAa1C,0BAA0B,EAAE,OAAO;aACnC,4BAA4B,EAAE,OAAO;aACrC,uBAAuB,EAAE,OAAO;aAMhC,2BAA2B,EAAE,OAAO;aAGpC,6BAA6B,EAAE,OAAO;aACtC,mCAAmC,EAAE,OAAO;aAC5C,+BAA+B,EAAE,OAAO;aACxC,iCAAiC,EAAE,OAAO;aAC1C,+BAA+B,EAAE,OAAO;CAChC,CAAA;AAEV,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAA;AAgHpE,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,cAAc,EACnB,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,eAAe,CAAA;CAC7B,GACA,aAAa,CAuBf;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,cAAc,EACnB,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,eAAe,CAAA;CAC7B,GACA,aAAa,CAEf;AAED,wBAAgB,UAAU,CACxB,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,cAAc,EACnB,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,eAAe,CAAA;CAC7B,GACA,aAAa,CAEf;AAMD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,cAAc,EACnB,YAAY,SAAI,GACf,MAAM,CA6BR;AAmBD,wBAAgB,WAAW,CACzB,KAAK,EAAE,aAAa,EACpB,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAChC,MAAM,CA6CR;AAMD;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAId;AAMD,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,cAAc,CAMhB;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,cAAc,GAClB,cAAc,CAMhB"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,cAAc,EACf,MAAM,YAAY,CAAA;AAMnB,eAAO,MAAM,UAAU;aAErB,kBAAkB,EAAE,OAAO;aAC3B,uBAAuB,EAAE,OAAO;aAGhC,wBAAwB,EAAE,OAAO;aAGjC,uBAAuB,EAAE,OAAO;aAChC,mBAAmB,EAAE,OAAO;aAC5B,0BAA0B,EAAE,OAAO;aACnC,4BAA4B,EAAE,OAAO;aAGrC,mBAAmB,EAAE,OAAO;aAC5B,wBAAwB,EAAE,OAAO;aACjC,qBAAqB,EAAE,OAAO;aAC9B,+BAA+B,EAAE,OAAO;aAUxC,4BAA4B,EAAE,OAAO;aAUrC,8BAA8B,EAAE,OAAO;aAUvC,6BAA6B,EAAE,OAAO;aAGtC,uBAAuB,EAAE,OAAO;aAChC,oBAAoB,EAAE,OAAO;aAK7B,uBAAuB,EAAE,OAAO;aAQhC,6BAA6B,EAAE,OAAO;aAGtC,mCAAmC,EAAE,OAAO;aAQ5C,iCAAiC,EAAE,OAAO;aAa1C,0BAA0B,EAAE,OAAO;aACnC,4BAA4B,EAAE,OAAO;aACrC,uBAAuB,EAAE,OAAO;aAMhC,2BAA2B,EAAE,OAAO;aAGpC,6BAA6B,EAAE,OAAO;aACtC,mCAAmC,EAAE,OAAO;aAC5C,+BAA+B,EAAE,OAAO;aACxC,iCAAiC,EAAE,OAAO;aAC1C,+BAA+B,EAAE,OAAO;CAChC,CAAA;AAEV,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,OAAO,UAAU,CAAC,CAAA;AAmHpE,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,cAAc,EACnB,OAAO,CAAC,EAAE;IACR,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,eAAe,CAAA;CAC7B,GACA,aAAa,CAuBf;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,cAAc,EACnB,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,eAAe,CAAA;CAC7B,GACA,aAAa,CAEf;AAED,wBAAgB,UAAU,CACxB,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,cAAc,EACnB,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,eAAe,CAAA;CAC7B,GACA,aAAa,CAEf;AAMD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,cAAc,EACnB,YAAY,SAAI,GACf,MAAM,CA6BR;AAmBD,wBAAgB,WAAW,CACzB,KAAK,EAAE,aAAa,EACpB,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAChC,MAAM,CA6CR;AAMD;;;;;;;GAOG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAId;AAMD,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,cAAc,CAMhB;AAED,wBAAgB,cAAc,CAC5B,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,cAAc,GAClB,cAAc,CAMhB"}

package/dist/index.js

@@ -4154,6 +4154,11 @@ function irToComponentTemplateWithOpts(node, opts) {
     case "expression": {
       if (node.expr === "null" || node.expr === "undefined")
         return "";
+      if (node.clientOnly && node.slotId) {
+        if (node.markerless)
+          return "";
+        return `<!--bf:${node.slotId}--><!--/-->`;
+      }
       const wrapped = transformExpr(node.expr, node.templateExpr);
       const value = node.joinArrayChild ? `Array.isArray(${wrapped}) ? ${wrapped}.join('') : (${wrapped} ?? '')` : wrapped;
       if (node.slotId) {
@@ -5605,6 +5610,7 @@ var ErrorCodes = {
   COMPONENT_REQUIRED_PROP_MISSING: "BF046",
   JSX_BRANCH_LOCAL_IN_CALLBACK: "BF047",
   SIBLING_COMPONENT_NOT_COMPILED: "BF048",
+  RICH_TYPE_PROP_NOT_HYDRATABLE: "BF049",
   SHARED_PROGRAM_REQUIRED: "BF050",
   WRONG_PACKAGE_IMPORT: "BF051",
   BUILTIN_REQUIRES_IMPORT: "BF054",
@@ -5635,6 +5641,7 @@ var errorMessages = {
   [ErrorCodes.COMPONENT_REQUIRED_PROP_MISSING]: "Built-in component is missing a required prop.",
   [ErrorCodes.JSX_BRANCH_LOCAL_IN_CALLBACK]: "JSX-typed local declared inside an `if`-block cannot be referenced from a callback body (ref / event handler). " + "Render it as a child instead: `<div ref={...}>{local}</div>`.",
   [ErrorCodes.SIBLING_COMPONENT_NOT_COMPILED]: "Referenced component did not compile to a template, so this reference would throw " + "`ReferenceError` at render time. Multi-return JSX dispatch (a `switch` or `if`/`else` " + "chain across multiple JSX-returning branches) cannot compile as a component in a " + `'use client' file. Extract it to a separate non-"use client" file (where it is preserved ` + "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.",
   [ErrorCodes.WRONG_PACKAGE_IMPORT]: "Import from wrong package.",
   [ErrorCodes.BUILTIN_REQUIRES_IMPORT]: "Built-in <Async> / <Region> must be imported from '@barefootjs/client'. " + "The compiler recognises these tags by their import (not by tag name), " + "so an unimported tag with this name is treated as an undeclared component.",
@@ -5752,6 +5759,8 @@ var HOST_RICH_TYPE_NAMES = new Set([
   "BigInt",
   "Function"
 ]);
+var JSON_REVIVABLE_RICH_TYPE_NAMES = new Set(["Date", "URL"]);
+var JSON_UNSAFE_RICH_TYPE_NAMES = new Set([...HOST_RICH_TYPE_NAMES].filter((n) => !JSON_REVIVABLE_RICH_TYPE_NAMES.has(n)));
 function baseTypeName(raw) {
   const idx = raw.indexOf("<");
   return (idx === -1 ? raw : raw.slice(0, idx)).trim();
@@ -5784,6 +5793,21 @@ function lookupProperty(objType, propName, meta) {
   const prop = deref.properties?.find((p) => p.name === propName);
   return prop ? stripUnion(prop.type) : null;
 }
+function resolvePropDeclaredType(propName, meta) {
+  return lookupProperty(meta.propsType, propName, meta);
+}
+function jsonUnsafeTypeName(type) {
+  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;
+}
 function resolveReceiverType(expr, meta, bindings) {
   if (expr.kind === "identifier") {
     if (bindings.has(expr.name))
@@ -15574,6 +15598,9 @@ function buildReferencesGraph(ctx, irRoot) {
       addExprEdges(ROOT_SOURCE, event.handler, "init-body");
     }
   }
+  for (const elem of ctx.clientOnlyElements) {
+    addExprEdges(ROOT_SOURCE, elem.expression, "init-body");
+  }
   for (const elem of ctx.loopElements) {
     addExprEdges(ROOT_SOURCE, elem.array, "template-closure");
     addTemplateEdges(ROOT_SOURCE, elem.template, "template-closure");
@@ -20034,9 +20061,15 @@ function lowerDateCallsInReactiveExpr(expr, matcher) {
   }
   return restore(result);
 }
-function emitDynamicTextUpdates(lines, ctx) {
-  const dateLoweringMatcher = getReactiveDateLoweringMatcher(ctx);
+function makeCataloguedCallLowerer(ctx) {
+  const dateMatcher = getReactiveDateLoweringMatcher(ctx);
   const toLocaleMatcher = getReactiveToLocaleMatcher(ctx);
+  if (!dateMatcher && !toLocaleMatcher)
+    return (expr) => expr;
+  return (expr) => lowerToLocaleCallsInReactiveExpr(lowerDateCallsInReactiveExpr(expr, dateMatcher), toLocaleMatcher);
+}
+function emitDynamicTextUpdates(lines, ctx) {
+  const lower = makeCataloguedCallLowerer(ctx);
   const byExpression = new Map;
   for (const elem of ctx.dynamicElements) {
     const key = elem.expression;
@@ -20046,7 +20079,7 @@ function emitDynamicTextUpdates(lines, ctx) {
     byExpression.get(key).push(elem);
   }
   for (const [rawExpr, elems] of byExpression) {
-    const expr = lowerToLocaleCallsInReactiveExpr(lowerDateCallsInReactiveExpr(rawExpr, dateLoweringMatcher), toLocaleMatcher);
+    const expr = lower(rawExpr);
     const conditionalElems = elems.filter((e) => e.insideConditional);
     const normalElems = elems.filter((e) => !e.insideConditional);
     if (normalElems.length > 0 || conditionalElems.length > 0) {
@@ -20083,19 +20116,21 @@ function emitDynamicTextUpdates(lines, ctx) {
   }
 }
 function emitClientOnlyExpressions(lines, ctx) {
+  const lower = makeCataloguedCallLowerer(ctx);
   for (const elem of ctx.clientOnlyElements) {
     const slots = elem.elidedPath ? [{ id: elem.slotId, kind: "text", path: elem.elidedPath, markerless: true }] : [{ id: elem.slotId, kind: "text", path: [] }];
     const writer = claimWriterVarName(slots, varSlotId);
     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("");
   }
 }
 function emitReactiveAttributeUpdates(lines, ctx) {
   if (ctx.reactiveAttrs.length > 0) {
+    const lower = makeCataloguedCallLowerer(ctx);
     const attrsBySlot = new Map;
     for (const attr of ctx.reactiveAttrs) {
       if (!attrsBySlot.has(attr.slotId)) {
@@ -20108,7 +20143,7 @@ function emitReactiveAttributeUpdates(lines, ctx) {
       lines.push(`  createEffect(() => {`);
       lines.push(`    if (_${v}) {`);
       for (const attr of attrs) {
-        const expression = rewriteDestructuredPropsInExpr(attr.expression, ctx);
+        const expression = rewriteDestructuredPropsInExpr(lower(attr.expression), ctx);
         for (const stmt of emitAttrUpdate(`_${v}`, attr.attrName, expression, attr)) {
           lines.push(`      ${stmt}`);
         }
@@ -23871,6 +23906,38 @@ function checkRichTypeMethodCalls(root, metadata, errors) {
   const seen = new Set;
   walkNode2(root, metadata, EMPTY_BINDINGS2, matchers, errors, seen);
 }
+function checkRichTypePropSerialization(root, metadata, errors, declLoc) {
+  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;
+    if (metadata.typeDefinitions.some((d) => d.name === typeName))
+      continue;
+    pushPropSerializationDiagnostic(errors, loc, param.name, typeName, declared.raw);
+  }
+}
+function pushPropSerializationDiagnostic(errors, loc, propName, typeName, declaredRaw) {
+  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, callee, args) {
   return matchers.some((m) => m(callee, args) !== null);
 }
@@ -23887,21 +23954,39 @@ function receiverRootIsProp(expr, bindings) {
     root = root.object;
   return root.kind === "identifier" && !bindings.has(root.name);
 }
+function buildSuggestion(method, receiverPath, receiver, typeName) {
+  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)`;
+  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, seen, loc, method, receiverPath, isProp, typeName) {
   const key = `${loc.start.line}:${loc.start.column}:${receiverPath}.${method}`;
   if (seen.has(key))
     return;
   seen.add(key);
   const receiver = isProp ? `prop '${receiverPath}'` : `'${receiverPath}'`;
-  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
   });
 }
 function checkExpr(expr, loc, meta, bindings, matchers, errors, seen) {
@@ -24146,6 +24231,7 @@ function compileMultipleComponents(source, filePath, componentNames, options) {
     };
     componentIR.metadata.clientAnalysis = analyzeClientNeeds(componentIR);
     checkRichTypeMethodCalls(componentIR.root, componentIR.metadata, errors);
+    checkRichTypePropSerialization(componentIR.root, componentIR.metadata, errors, ctx.propsDestructuring?.loc);
     decideClientOnlyElision(componentIR.root);
     entries.push({ componentIR, ctx });
   }
@@ -24548,6 +24634,7 @@ function compileJSX(source, filePath, options) {
   };
   componentIR.metadata.clientAnalysis = analyzeClientNeeds(componentIR);
   checkRichTypeMethodCalls(componentIR.root, componentIR.metadata, errors);
+  checkRichTypePropSerialization(componentIR.root, componentIR.metadata, errors, ctx.propsDestructuring?.loc);
   decideClientOnlyElision(componentIR.root);
   if (ctx.importedClientSignalNames.size > 0) {
     const sources = new Set;

package/dist/ir-to-client-js/build-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-references.d.ts","sourceRoot":"","sources":["../../src/ir-to-client-js/build-references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAEV,MAAM,EAIN,eAAe,EAChB,MAAM,aAAa,CAAA;AAIpB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAYjD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,CAyU1F;AAMD;;2DAE2D;AAC3D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,CAAC,CAOxE;AAED;0CAC0C;AAC1C,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,CAAC,CAMtE;AAED;6CAC6C;AAC7C,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,CAAC,CAM5E;AAED;;qDAEqD;AACrD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAE3F;AAED;;8CAE8C;AAC9C,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,EACjD,IAAI,EAAE,MAAM,GACX,GAAG,CAAC,MAAM,CAAC,CAQb"}
+{"version":3,"file":"build-references.d.ts","sourceRoot":"","sources":["../../src/ir-to-client-js/build-references.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAEV,MAAM,EAIN,eAAe,EAChB,MAAM,aAAa,CAAA;AAIpB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAYjD,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,eAAe,CA0V1F;AAMD;;2DAE2D;AAC3D,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,CAAC,CAOxE;AAED;0CAC0C;AAC1C,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,CAAC,CAMtE;AAED;6CAC6C;AAC7C,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,CAAC,CAM5E;AAED;;qDAEqD;AACrD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAE3F;AAED;;8CAE8C;AAC9C,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,EACjD,IAAI,EAAE,MAAM,GACX,GAAG,CAAC,MAAM,CAAC,CAQb"}

package/dist/ir-to-client-js/emit-reactive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit-reactive.d.ts","sourceRoot":"","sources":["../../src/ir-to-client-js/emit-reactive.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,aAAa,CAAA;AAEvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAqBjD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE,CAyC7G;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,MAAM,CAqBzF;AAqLD,gFAAgF;AAChF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CAsFlF;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CAgBrF;AAED,kGAAkG;AAClG,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CAyBxF;AAED,+FAA+F;AAC/F,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CAqDpF;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CAgClF"}
+{"version":3,"file":"emit-reactive.d.ts","sourceRoot":"","sources":["../../src/ir-to-client-js/emit-reactive.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,aAAa,CAAA;AAEvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAqBjD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE,CAyC7G;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,MAAM,CAqBzF;AAwMD,gFAAgF;AAChF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CAkFlF;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CAiBrF;AAED,kGAAkG;AAClG,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CA8BxF;AAED,+FAA+F;AAC/F,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CAqDpF;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,eAAe,GAAG,IAAI,CAgClF"}

package/dist/ir-to-client-js/html-template.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html-template.d.ts","sourceRoot":"","sources":["../../src/ir-to-client-js/html-template.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"html-template.d.ts","sourceRoot":"","sources":["../../src/ir-to-client-js/html-template.ts"],"names":[],"mappings":"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"}

package/dist/rich-type-evidence.d.ts

@@ -31,6 +31,68 @@ import type { ParsedExpr } from './expression-parser.ts';
  *     catalogue lookup sees `Timestamp`, not `Date`.
  */
 export declare const HOST_RICH_TYPE_NAMES: ReadonlySet<string>;
+/**
+ * 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 declare const JSON_REVIVABLE_RICH_TYPE_NAMES: ReadonlySet<string>;
+/**
+ * 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 declare const JSON_UNSAFE_RICH_TYPE_NAMES: ReadonlySet<string>;
 /**
  * Strip generic type arguments from a `TypeInfo.raw` string (`Map<string,
  * string>` → `Map`) so a parametrized host type still matches the bare-name
@@ -50,6 +112,30 @@ export declare function stripUnion(type: TypeInfo | null): TypeInfo | null;
  * `{ kind: 'interface', raw }` with no member walk of its own.
  */
 export declare function derefNamedType(type: TypeInfo, meta: EvidenceMetadata): TypeInfo;
+/**
+ * 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 declare function resolvePropDeclaredType(propName: string, meta: EvidenceMetadata): TypeInfo | null;
+/**
+ * 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 declare function jsonUnsafeTypeName(type: TypeInfo | null): string | null;
 /**
  * Resolve the TypeInfo of a receiver expression, using only propsType /
  * propsParams / typeDefinitions and the caller-supplied local bindings.

package/dist/rich-type-evidence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rich-type-evidence.d.ts","sourceRoot":"","sources":["../src/rich-type-evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAgB,QAAQ,EAAE,MAAM,YAAY,CAAA;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAcnD,CAAA;AAEF;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED,KAAK,gBAAgB,GAAG,IAAI,CAAC,UAAU,EAAE,WAAW,GAAG,iBAAiB,GAAG,aAAa,GAAG,iBAAiB,CAAC,CAAA;AAkB7G,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,QAAQ,GAAG,IAAI,CAIjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,gBAAgB,GAAG,QAAQ,CAO/E;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAAC,GAC7C,QAAQ,GAAG,IAAI,CAwBjB"}
+{"version":3,"file":"rich-type-evidence.d.ts","sourceRoot":"","sources":["../src/rich-type-evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAgB,QAAQ,EAAE,MAAM,YAAY,CAAA;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAcnD,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,eAAO,MAAM,8BAA8B,EAAE,WAAW,CAAC,MAAM,CAA4B,CAAA;AAE3F;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,2BAA2B,EAAE,WAAW,CAAC,MAAM,CAE3D,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED,KAAK,gBAAgB,GAAG,IAAI,CAAC,UAAU,EAAE,WAAW,GAAG,iBAAiB,GAAG,aAAa,GAAG,iBAAiB,CAAC,CAAA;AAkB7G,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,QAAQ,GAAG,IAAI,CAIjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,gBAAgB,GAAG,QAAQ,CAO/E;AAgBD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,QAAQ,GAAG,IAAI,CAEjG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAUvE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAAC,GAC7C,QAAQ,GAAG,IAAI,CAwBjB"}

package/dist/rich-type-refusal.d.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,8 +36,21 @@
  *     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 { IRNode, IRMetadata, CompilerError } from './types.ts';
+import type { IRNode, IRMetadata, CompilerError, SourceLocation } from './types.ts';
 /**
  * Walk `root` looking for a method call on a host rich-typed receiver with
  * no catalogued lowering, pushing BF021 into `errors` for each one found.
@@ -32,4 +59,25 @@ import type { IRNode, IRMetadata, CompilerError } from './types.ts';
  * than attaching it, and additionally skips anything under `/* @client *\/`.
  */
 export declare function checkRichTypeMethodCalls(root: IRNode, metadata: IRMetadata, errors: CompilerError[]): void;
+/**
+ * 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 declare function checkRichTypePropSerialization(root: IRNode, metadata: IRMetadata, errors: CompilerError[], declLoc?: SourceLocation): void;
 //# sourceMappingURL=rich-type-refusal.d.ts.map

package/dist/rich-type-refusal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rich-type-refusal.d.ts","sourceRoot":"","sources":["../src/rich-type-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EACV,aAAa,EAKd,MAAM,YAAY,CAAA;AAUnB;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI,CAQ1G"}
+{"version":3,"file":"rich-type-refusal.d.ts","sourceRoot":"","sources":["../src/rich-type-refusal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EACV,aAAa,EACb,cAAc,EAKf,MAAM,YAAY,CAAA;AAiBnB;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI,CAQ1G;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,aAAa,EAAE,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,IAAI,CAe1I"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/jsx",
-  "version": "0.31.6",
+  "version": "0.31.7",
   "description": "JSX compiler for BarefootJS - transforms JSX to server HTML + client JS",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,7 +49,7 @@
     "directory": "packages/jsx"
   },
   "dependencies": {
-    "@barefootjs/shared": "0.31.6"
+    "@barefootjs/shared": "0.31.7"
   },
   "peerDependencies": {
     "@barefootjs/client": ">=0.2.0",