@barefootjs/cli 0.31.6 → 0.31.8

package/dist/docs/core/advanced/error-codes.md

@@ -193,13 +193,13 @@ where `d` is a signal) has no evidence and is not flagged.
 #### Workaround
 
 ```tsx
-// ✅ Defer to the client
-{/* @client */ createdAt.toISOString()}
-
-// ✅ Or format in the backend and pass a string prop
+// ✅ Format in the backend and pass a string prop
 function Post({ createdAt }: { createdAt: string }) {
   return <div>{createdAt}</div>
 }
+
+// ✅ Or defer to the client — but revive the receiver first
+{/* @client */ new Date(createdAt).toISOString()}
 ```
 
 The string-prop variant moves the formatting to where full language power
@@ -209,6 +209,16 @@ that a component-body local (`const iso = createdAt.toISOString()`) is NOT a
 workaround: it lowers to a template variable whose value the template
 backend cannot compute, and dies at render time the same way.
 
+The `/* @client */` block must wrap the receiver in `new Date(...)` — a
+BARE `{/* @client */ createdAt.toISOString()}` compiles clean but crashes
+at real hydrate with a `TypeError`. Props cross the hydration boundary as
+JSON with no type-aware revival, so `createdAt` arrives at hydrate as its
+`toJSON()` ISO string, not a `Date` instance; wrapping it in `new Date(...)`
+revives it first, since `Date`'s `toJSON()` output round-trips through its
+own constructor (#2636). This revival trick only works for `Date` and
+`URL` — every other host rich type (`Map`, `Set`, …) has no safe
+`/* @client */` escape at all; pre-compute server-side instead.
+
 <a id="bf023"></a>
 
 ### BF023 — Missing Key in List
@@ -275,7 +285,7 @@ See [JSX Compatibility](../rendering/jsx-compatibility.md) for the full worked e
 
 ---
 
-## Component Errors (BF043–BF044)
+## Component Errors (BF043–BF049)
 
 <a id="bf043"></a>
 
@@ -333,6 +343,55 @@ function Child({ initialCount }: Props) {
 <Child count={count()} />
 ```
 
+<a id="bf049"></a>
+
+### BF049 — Rich-Typed Prop Not Hydratable
+
+**Trigger:** A prop typed as a JSON-unsafe host rich type — `Map`, `Set`,
+`WeakMap`, `WeakSet`, `URLSearchParams`, `RegExp`, `Promise`, `Error`,
+`Symbol`, `BigInt`, `Function` — is used anywhere in this component's own
+client code (an event handler, an effect), regardless of whether a method is
+called on it. This is the sibling of [BF021](#bf021)'s host-rich-type
+refusal for a different shape: BF021 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 BF021 never
+analyzes, so even a method call there (like `data.get(...)` below) is just
+as invisible to it as a bare read. Either way the prop crosses the `bf-p`
+hydration boundary as JSON, where a `Map`/`Set` arrives de-riched (`{}`,
+every entry silently dropped) and a `BigInt` fails to serialize at all
+(`TypeError` at SSR render, failing the whole page).
+
+```tsx
+// ❌ BF049 — a Map prop used by client code cannot survive hydration
+'use client'
+export function Foo({ data }: { data: Map<string, number> }) {
+  return <button onClick={() => console.log(data.get('x'))}>go</button>
+}
+```
+
+**Fix:** Pre-compute a JSON-serializable value server-side and rebuild the
+rich value client-side where it's actually needed.
+
+```tsx
+// ✅ Fixed
+'use client'
+export function Foo({ entries }: { entries: [string, number][] }) {
+  return <button onClick={() => console.log(new Map(entries).get('x'))}>go</button>
+}
+```
+
+> `Date` and `URL` props are exempt — their `toJSON()` output round-trips
+> through their own constructor, so they're not JSON-unsafe (see BF021's
+> host-rich-type section above).
+>
+> This is a compile-time check: it only fires when the prop's type is
+> provable from the component's own props type (same evidence
+> `checkRichTypeMethodCalls` uses). An imported/aliased type alias, or a
+> prop typed too loosely to resolve statically, isn't caught here — on the
+> Hono adapter, an unsound value reaching hydration serialization throws a
+> clear runtime error naming the prop and this code instead of failing
+> silently or with an opaque `JSON.stringify` error.
+
 <a id="bf054"></a>
 
 ### BF054 — Built-in `<Async>` / `<Region>` Used Without Import
@@ -396,4 +455,5 @@ function Component({ checked }: Props) {
 | BF023 | Error | Missing key in list |
 | BF043 | Warning | Props destructuring breaks reactivity |
 | BF044 | Error | Signal/memo getter passed without calling it |
+| BF049 | Error | Rich-typed prop read by client code cannot survive hydration |
 | BF054 | Error | Built-in `<Async>` / `<Region>` used without `@barefootjs/client` import |

package/dist/index.js

@@ -4663,6 +4663,10 @@ function irToComponentTemplateWithOpts(node, opts) {
       return escapeHtml(node.value);
     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 value2 = node.joinArrayChild ? `Array.isArray(${wrapped}) ? ${wrapped}.join('') : (${wrapped} ?? '')` : wrapped;
       if (node.slotId) {
@@ -5907,6 +5911,16 @@ var init_errors = __esm({
       // helper verbatim instead of compiling it as a component — so this code
       // fires only for the client-component compilation path.
       SIBLING_COMPONENT_NOT_COMPILED: "BF048",
+      // A prop typed as a host rich type whose `JSON.stringify` output is not
+      // revivable (`Map`, `Set`, `BigInt`, …) is used by this component's own
+      // client code (a handler, an effect) — regardless of whether a method is
+      // called on it, since `checkRichTypeMethodCalls`'s BF021 only walks
+      // template-lowered expression positions and never sees a handler/effect
+      // body either way. The prop still crosses the `bf-p` hydration boundary as
+      // JSON and arrives de-riched (or, for `BigInt`, fails to serialize at all,
+      // throwing at SSR render). Sibling of BF021 for the "client-side use"
+      // shape, which BF021's template-only walk can never reach (#2643).
+      RICH_TYPE_PROP_NOT_HYDRATABLE: "BF049",
       // Import errors (BF050-BF059)
       SHARED_PROGRAM_REQUIRED: "BF050",
       WRONG_PACKAGE_IMPORT: "BF051",
@@ -5979,6 +5993,7 @@ var init_errors = __esm({
       [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.",
@@ -6032,6 +6047,20 @@ 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(type2) {
+  if (!type2) return null;
+  if (type2.kind === "interface") {
+    const name2 = baseTypeName(type2.raw);
+    return JSON_UNSAFE_RICH_TYPE_NAMES.has(name2) ? name2 : null;
+  }
+  if (type2.kind === "unknown" && (type2.raw === "bigint" || type2.raw === "symbol")) {
+    return type2.raw;
+  }
+  return null;
+}
 function resolveReceiverType(expr, meta, bindings) {
   if (expr.kind === "identifier") {
     if (bindings.has(expr.name)) return stripUnion(bindings.get(expr.name) ?? null);
@@ -6048,7 +6077,7 @@ function resolveReceiverType(expr, meta, bindings) {
   }
   return null;
 }
-var HOST_RICH_TYPE_NAMES;
+var HOST_RICH_TYPE_NAMES, JSON_REVIVABLE_RICH_TYPE_NAMES, JSON_UNSAFE_RICH_TYPE_NAMES;
 var init_rich_type_evidence = __esm({
   "../jsx/src/rich-type-evidence.ts"() {
     "use strict";
@@ -6067,6 +6096,10 @@ var init_rich_type_evidence = __esm({
       "BigInt",
       "Function"
     ]);
+    JSON_REVIVABLE_RICH_TYPE_NAMES = /* @__PURE__ */ new Set(["Date", "URL"]);
+    JSON_UNSAFE_RICH_TYPE_NAMES = new Set(
+      [...HOST_RICH_TYPE_NAMES].filter((n) => !JSON_REVIVABLE_RICH_TYPE_NAMES.has(n))
+    );
   }
 });
 
@@ -15694,6 +15727,9 @@ function buildReferencesGraph(ctx2, irRoot) {
       addExprEdges(ROOT_SOURCE, event.handler, "init-body");
     }
   }
+  for (const elem of ctx2.clientOnlyElements) {
+    addExprEdges(ROOT_SOURCE, elem.expression, "init-body");
+  }
   for (const elem of ctx2.loopElements) {
     addExprEdges(ROOT_SOURCE, elem.array, "template-closure");
     addTemplateEdges(ROOT_SOURCE, elem.template, "template-closure");
@@ -17099,6 +17135,13 @@ function csrInlinableConstantsFromCtx(ctx2) {
   }
   return out;
 }
+function buildTemplateDefPart(ctx2, templateHtml) {
+  const envDecls = ctx2.signals.filter((s) => Boolean(s.envReader) && Boolean(s.envFactory)).map((s) => `const [${s.getter}] = ${s.envFactory}()`);
+  if (envDecls.length === 0) {
+    return `template: (${PROPS_PARAM}) => \`${templateHtml}\``;
+  }
+  return `template: (${PROPS_PARAM}) => { ${envDecls.join("; ")}; return \`${templateHtml}\` }`;
+}
 function emitRegistrationAndHydration(lines, ctx2, _ir, graph, inlinability) {
   const name2 = ctx2.componentName;
   lines.push(`}`);
@@ -17113,7 +17156,7 @@ function emitRegistrationAndHydration(lines, ctx2, _ir, graph, inlinability) {
   if (canGenerateStaticTemplate(_ir.root, propNamesForStaticCheck, inlinableConstants, unsafeLocalNames)) {
     const templateHtml = irToComponentTemplate(_ir.root, inlinableConstants, restSpreadNames, ctx2.propsObjectName);
     if (templateHtml) {
-      defParts.push(`template: (${PROPS_PARAM}) => \`${templateHtml}\``);
+      defParts.push(buildTemplateDefPart(ctx2, templateHtml));
     }
   } else {
     const csrInlinableConstants = csrInlinableConstantsFromCtx(ctx2);
@@ -17127,7 +17170,7 @@ function emitRegistrationAndHydration(lines, ctx2, _ir, graph, inlinability) {
       ctx2.deferredChildSlots
     );
     if (templateHtml) {
-      defParts.push(`template: (${PROPS_PARAM}) => \`${templateHtml}\``);
+      defParts.push(buildTemplateDefPart(ctx2, templateHtml));
     }
   }
   if (isCommentScope) {
@@ -20348,9 +20391,14 @@ function lowerDateCallsInReactiveExpr(expr, matcher) {
   }
   return restore(result2);
 }
-function emitDynamicTextUpdates(lines, ctx2) {
-  const dateLoweringMatcher = getReactiveDateLoweringMatcher(ctx2);
+function makeCataloguedCallLowerer(ctx2) {
+  const dateMatcher = getReactiveDateLoweringMatcher(ctx2);
   const toLocaleMatcher = getReactiveToLocaleMatcher(ctx2);
+  if (!dateMatcher && !toLocaleMatcher) return (expr) => expr;
+  return (expr) => lowerToLocaleCallsInReactiveExpr(lowerDateCallsInReactiveExpr(expr, dateMatcher), toLocaleMatcher);
+}
+function emitDynamicTextUpdates(lines, ctx2) {
+  const lower = makeCataloguedCallLowerer(ctx2);
   const byExpression = /* @__PURE__ */ new Map();
   for (const elem of ctx2.dynamicElements) {
     const key = elem.expression;
@@ -20360,10 +20408,7 @@ function emitDynamicTextUpdates(lines, ctx2) {
     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) {
@@ -20400,19 +20445,21 @@ function emitDynamicTextUpdates(lines, ctx2) {
   }
 }
 function emitClientOnlyExpressions(lines, ctx2) {
+  const lower = makeCataloguedCallLowerer(ctx2);
   for (const elem of ctx2.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(ctx2, elem.slotId)}) }`);
     lines.push("");
   }
 }
 function emitReactiveAttributeUpdates(lines, ctx2) {
   if (ctx2.reactiveAttrs.length > 0) {
+    const lower = makeCataloguedCallLowerer(ctx2);
     const attrsBySlot = /* @__PURE__ */ new Map();
     for (const attr of ctx2.reactiveAttrs) {
       if (!attrsBySlot.has(attr.slotId)) {
@@ -20425,7 +20472,7 @@ function emitReactiveAttributeUpdates(lines, ctx2) {
       lines.push(`  createEffect(() => {`);
       lines.push(`    if (_${v}) {`);
       for (const attr of attrs) {
-        const expression = rewriteDestructuredPropsInExpr(attr.expression, ctx2);
+        const expression = rewriteDestructuredPropsInExpr(lower(attr.expression), ctx2);
         for (const stmt of emitAttrUpdate(`_${v}`, attr.attrName, expression, attr)) {
           lines.push(`      ${stmt}`);
         }
@@ -24308,6 +24355,33 @@ function checkRichTypeMethodCalls(root2, metadata, errors) {
   const seen = /* @__PURE__ */ new Set();
   walkNode2(root2, metadata, EMPTY_BINDINGS2, matchers, errors, seen);
 }
+function checkRichTypePropSerialization(root2, metadata, errors, declLoc) {
+  if (!metadata.propsType || !metadata.clientAnalysis?.needsInit) return;
+  const usedProps = new Set(metadata.clientAnalysis.usedProps);
+  const loc = declLoc ?? root2.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 \u2014 and ${typeName} cannot: ${consequence}.`,
+    loc,
+    suggestion: {
+      message: "Pre-compute a JSON-serializable value server-side \u2014 a string, number, boolean, array, or plain object (e.g. pass [...map.entries()] and rebuild the Map client-side where needed) \u2014 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, args2) {
   return matchers.some((m) => m(callee, args2) !== null);
 }
@@ -24321,20 +24395,38 @@ function receiverRootIsProp(expr, bindings) {
   while (root2.kind === "member" && !root2.computed) root2 = root2.object;
   return root2.kind === "identifier" && !bindings.has(root2.name);
 }
+function buildSuggestion(method2, receiverPath, receiver, typeName) {
+  const revivalExpr = receiverPath === "<expression>" ? `wrapping the receiver in new ${typeName}(...) before calling .${method2}()` : `{/* @client */ new ${typeName}(${receiverPath}).${method2}(...)}`;
+  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 (method2 === "toLocaleDateString" && typeName === "Date") {
+    return {
+      message: `Pass a literal locale and an explicit literal timeZone \u2014 .toLocaleDateString('ja-JP', { timeZone: 'UTC' }), a fixed '\xB1HH:MM' offset, or a canonical IANA zone ID like 'Asia/Tokyo' (exact case; #2344) \u2014 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} \u2014 ${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} \u2014 ${revivalReason}.`,
+      escape: [{ kind: "prop-precompute" }, { kind: "client-directive" }]
+    };
+  }
+  return {
+    message: `Pre-compute the value server-side and pass the result \u2014 a string, number, array, or plain object \u2014 as a prop. /* @client */ is NOT a safe escape here: ${receiver} cannot cross the bf-p hydration boundary as JSON \u2014 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, method2, receiverPath, isProp, typeName) {
   const key = `${loc.start.line}:${loc.start.column}:${receiverPath}.${method2}`;
   if (seen.has(key)) return;
   seen.add(key);
   const receiver = isProp ? `prop '${receiverPath}'` : `'${receiverPath}'`;
-  const suggestion = method2 === "toLocaleDateString" && typeName === "Date" ? "Pass a literal locale and an explicit literal timeZone \u2014 .toLocaleDateString('ja-JP', { timeZone: 'UTC' }), a fixed '\xB1HH:MM' offset, or a canonical IANA zone ID like 'Asia/Tokyo' (exact case; #2344) \u2014 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(method2, receiverPath, receiver, typeName);
   errors.push({
     code: ErrorCodes.UNSUPPORTED_JSX_PATTERN,
     severity: "error",
     message: `Expression cannot be compiled to marked template: method '.${method2}()' on ${receiver} of host type '${typeName}' has no catalogued lowering.`,
     loc,
-    suggestion: {
-      message: suggestion
-    }
+    suggestion
   });
 }
 function checkExpr(expr, loc, meta, bindings, matchers, errors, seen) {
@@ -24565,6 +24657,7 @@ function compileMultipleComponents(source, filePath, componentNames, options2) {
     };
     componentIR.metadata.clientAnalysis = analyzeClientNeeds(componentIR);
     checkRichTypeMethodCalls(componentIR.root, componentIR.metadata, errors);
+    checkRichTypePropSerialization(componentIR.root, componentIR.metadata, errors, ctx2.propsDestructuring?.loc);
     decideClientOnlyElision(componentIR.root);
     entries2.push({ componentIR, ctx: ctx2 });
   }
@@ -24971,6 +25064,7 @@ function compileJSX(source, filePath, options2) {
   };
   componentIR.metadata.clientAnalysis = analyzeClientNeeds(componentIR);
   checkRichTypeMethodCalls(componentIR.root, componentIR.metadata, errors);
+  checkRichTypePropSerialization(componentIR.root, componentIR.metadata, errors, ctx2.propsDestructuring?.loc);
   decideClientOnlyElision(componentIR.root);
   if (ctx2.importedClientSignalNames.size > 0) {
     const sources = /* @__PURE__ */ new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/cli",
-  "version": "0.31.6",
+  "version": "0.31.8",
   "description": "CLI for agent-driven UI component discovery and scaffolding",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,12 +30,12 @@
     "esbuild": "^0.25.0",
     "typescript": "^5.0.0",
     "vite": "^6.0.0",
-    "@barefootjs/client": "0.31.6",
-    "@barefootjs/shared": "0.31.6"
+    "@barefootjs/client": "0.31.8",
+    "@barefootjs/shared": "0.31.8"
   },
   "devDependencies": {
-    "@barefootjs/jsx": "0.31.6",
-    "@barefootjs/vite": "0.31.6",
+    "@barefootjs/jsx": "0.31.8",
+    "@barefootjs/vite": "0.31.8",
     "@happy-dom/global-registrator": "^20.0.11",
     "@types/node": "^22.0.0",
     "happy-dom": "^20.0.11"