@barefootjs/cli 0.31.5 → 0.31.7

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

@@ -24,6 +24,8 @@ error[BF001]: 'use client' directive required for components with createSignal
 
 ## Directive Errors (BF001–BF003)
 
+<a id="bf001"></a>
+
 ### BF001 — Missing `"use client"` Directive
 
 **Trigger:** Reactive APIs used without `"use client"`.
@@ -46,6 +48,8 @@ import { createSignal } from '@barefootjs/client'
 export function Counter() { ... }
 ```
 
+<a id="bf003"></a>
+
 ### BF003 — Client Component Importing Server Component
 
 **Trigger:** Client component imports from a file without `"use client"`.
@@ -56,6 +60,8 @@ export function Counter() { ... }
 
 ## Signal Errors (BF011)
 
+<a id="bf011"></a>
+
 ### BF011 — Module-Level Reactive Declaration
 
 **Trigger:** A `createSignal` or `createMemo` call at module scope without a leading `/* @client */` directive.
@@ -100,6 +106,8 @@ export function Counter() {
 
 ## JSX Errors (BF021–BF023)
 
+<a id="bf021"></a>
+
 ### BF021 — Unsupported JSX Pattern
 
 **Trigger:** Array method chain before `.map()` cannot compile to SSR template.
@@ -185,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
@@ -201,6 +209,18 @@ 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
 
 **Trigger:** `.map()` loop without `key` prop.
@@ -219,7 +239,55 @@ backend cannot compute, and dies at render time the same way.
 
 ---
 
-## Component Errors (BF043–BF044)
+## Template Adapter Errors (BF101)
+
+<a id="bf101"></a>
+
+### BF101 — No Template-Language Lowering
+
+**Trigger:** An expression that a JS-runtime adapter (Hono, CSR) executes verbatim has no lowering on a non-JS template adapter (Go, Mojo, Xslate, Twig, ERB, Blade, Jinja, MiniJinja). Two shapes are permanent known limitations rather than subset widenings:
+
+**A nested `.some()` / `.find()` inside a filter predicate** ([#2320](https://github.com/piconic-ai/barefootjs/issues/2320)) — `find`-family methods return an element, not a boolean, so degrading them to their receiver would silently change predicate semantics:
+
+```tsx
+// ❌ BF101 on Go/Mojo/Xslate/Twig/ERB/Blade/Jinja/MiniJinja
+{items().filter(t => picked().some(p => p.id === t.id)).map(t => <li key={t.id}>{t.name}</li>)}
+```
+
+**A `.map()` loop array bound to a component-scope `const` with a computed initializer** ([#2321](https://github.com/piconic-ai/barefootjs/issues/2321)) — no template adapter binds an arbitrary computed local, only a prop/param it passes straight through:
+
+```tsx
+// ❌ BF101 on Go/Mojo/Xslate/Twig/ERB/Blade/Jinja/MiniJinja
+function ReactionBar(props: { reactions: Record<string, string[]> }) {
+  const entries = Object.entries(props.reactions).filter(([, users]) => users.length > 0)
+  return <div>{entries.map(([emoji, users]) => <span key={emoji}>{emoji}</span>)}</div>
+}
+```
+
+**Escapes** — each verified by a conformance twin that compiles clean on the refusing adapter, listed best-SSR-first:
+
+- **Pass the computed result as a prop** (`prop-precompute`) — available for the loop-source shape, wherever the array is already computable server-side. **Full server render**: the rendered result is present in the server HTML.
+- **`/* @client */`** (`client-directive`) — available for both shapes, and compiles clean on every adapter. **Client-render**: the region is *empty in server HTML until hydration*. That trade is the cost of the escape, not a bug — the twin fixtures pin the empty region in their own committed `expectedHtml`.
+
+```tsx
+// ✅ Best for the loop-source shape: pass the computed array as a prop
+function ReactionBar({ entries }: { entries: [string, string[]][] }) {
+  return <div>{entries.map(([emoji, users]) => <span key={emoji}>{emoji}</span>)}</div>
+}
+
+// ✅ Either shape: defer to the client
+{/* @client */ items().filter(t => picked().some(p => p.id === t.id)).map(t => (
+  <li key={t.id}>{t.name}</li>
+))}
+```
+
+See [JSX Compatibility](../rendering/jsx-compatibility.md) for the full worked examples.
+
+---
+
+## Component Errors (BF043–BF049)
+
+<a id="bf043"></a>
 
 ### BF043 — Props Destructuring (Warning)
 
@@ -257,6 +325,8 @@ function Child({ initialCount }: Props) {
 }
 ```
 
+<a id="bf044"></a>
+
 ### BF044 — Signal/Memo Getter Not Called
 
 **Trigger:** Signal/memo getter passed without calling it.
@@ -273,6 +343,57 @@ 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
 
 **Trigger:** A bare `<Async>` or `<Region>` tag is used without importing it
@@ -334,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/docs/core/rendering/jsx-compatibility.md

@@ -125,6 +125,7 @@ Some JavaScript expressions cannot be translated into marked template syntax. Wh
 | JSX-returning `.flatMap()` with a statement body (early `return`, `const` before the projection) | works (runs as JS) | **BF021** |
 | Nested `.filter()` / `.map()` in a filter predicate (`x => x.tags.filter(...).length > 0`) | works | works |
 | Nested `.some()` / `.find()` / `.reduce()` in a filter predicate | works | **BF101** |
+| `.map()` loop array bound to a component-scope `const` with a computed initializer (e.g. `Object.entries(props.x).filter(...)`) | works | **BF101** |
 | Sort comparator that's a multi-statement block body or `localeCompare(b, locale, opts)` | works (runs as JS) | **BF021** |
 | Sort comparator that's a function reference to an imported/prop identifier, or an alias chain (`const c2 = c1`) | works (runs as JS) | **BF021** |
 | `typeof` in a filter predicate | works (runs as JS) | **BF021** |
@@ -182,6 +183,39 @@ A nested `.some()` / `.find()` / `.reduce()` still has no faithful Go/Mojo lower
 {items().filter(x => x.done)}
 ```
 
+**Computed loop array (`const` with a runtime initializer):**
+
+A `.map()` loop whose array is a bare identifier works when that identifier is a prop or a signal read, but not when it's a component-scope `const` computed from one at render time (`Object.entries(...)`, `.filter(...)`, …) — no template adapter has a binding for an arbitrary computed local, only for a prop/param it can pass straight through:
+
+```tsx
+// ❌ BF101 on Go/Mojo/Xslate/Twig/ERB/Blade/Jinja/MiniJinja; works on Hono
+type Props = { reactions: Record<string, string[]> }
+function ReactionBar(props: Props) {
+  const entries = Object.entries(props.reactions).filter(([, users]) => users.length > 0)
+  return <div>{entries.map(([emoji, users]) => (
+    <span key={emoji}>{emoji}: {String(users.length)}</span>
+  ))}</div>
+}
+
+// ✅ Best: precompute the array in the parent/route handler and pass it as a prop
+type Entry = [string, string[]]
+function ReactionBarByProp({ entries }: { entries: Entry[] }) {
+  return <div>{entries.map(([emoji, users]) => (
+    <span key={emoji}>{emoji}: {String(users.length)}</span>
+  ))}</div>
+}
+
+// ✅ Or defer to the client with /* @client */
+function ReactionBarClientOnly(props: Props) {
+  const entries = Object.entries(props.reactions).filter(([, users]) => users.length > 0)
+  return <div>{/* @client */ entries.map(([emoji, users]) => (
+    <span key={emoji}>{emoji}: {String(users.length)}</span>
+  ))}</div>
+}
+```
+
+The prop-passing form is the better fix — it keeps full SSR output, since the template adapters bind a plain prop array directly. `/* @client */` compiles clean too, but renders **nothing** for that region at SSR — no content until hydration/mount runs the loop client-side.
+
 ### Sort comparators that error on Go / Mojo
 
 **Unsupported sort comparators** (imperative block bodies, unresolved function references) — a JS-runtime adapter (Hono, CSR) runs any of these verbatim; only non-JS template backends refuse them:

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) {
@@ -4963,6 +4967,7 @@ function generateCsrTemplateWithOpts(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}--><!--/-->`;
       }
       {
@@ -5906,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",
@@ -5978,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.",
@@ -6031,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);
@@ -6047,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";
@@ -6066,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))
+    );
   }
 });
 
@@ -9328,7 +9362,7 @@ function pickAttrMetaFromIR(src) {
     ...src.freeIdentifiers !== void 0 && { freeIdentifiers: src.freeIdentifiers }
   };
 }
-var SCOPE_FORBIDDEN, REACTIVE_BINDING_KINDS, AttrValueOf;
+var SCOPE_FORBIDDEN, REACTIVE_BINDING_KINDS, AttrValueOf, ESCAPE_SSR_COST;
 var init_types = __esm({
   "../jsx/src/types.ts"() {
     "use strict";
@@ -9400,6 +9434,14 @@ var init_types = __esm({
         return { kind: "jsx-children", children: children2 };
       }
     };
+    ESCAPE_SSR_COST = {
+      // `/* @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"
+    };
   }
 });
 
@@ -15685,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");
@@ -20339,9 +20384,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;
@@ -20351,10 +20401,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) {
@@ -20391,19 +20438,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)) {
@@ -20416,7 +20465,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}`);
         }
@@ -24299,6 +24348,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);
 }
@@ -24312,20 +24388,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) {
@@ -24556,6 +24650,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 });
   }
@@ -24962,6 +25057,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();
@@ -29240,6 +29336,7 @@ __export(src_exports, {
   BindingScope: () => BindingScope,
   CALLBACK_METHODS: () => CALLBACK_METHODS,
   ENV_SIGNAL_READERS: () => ENV_SIGNAL_READERS,
+  ESCAPE_SSR_COST: () => ESCAPE_SSR_COST,
   ErrorCodes: () => ErrorCodes,
   JsxAdapter: () => JsxAdapter,
   PARSED_EXPR_KINDS: () => PARSED_EXPR_KINDS,
@@ -29430,6 +29527,7 @@ var init_src2 = __esm({
     init_source_map();
     init_combine_client_js();
     init_types();
+    init_types();
     init_css_layer_prefixer();
     init_instrumentation();
     init_errors();

package/dist/tokens.json

@@ -49,6 +49,7 @@
     { "name": "card-foreground", "value": "oklch(0.145 0 0)", "dark": "oklch(0.985 0 0)" },
     { "name": "primary", "value": "oklch(0.205 0 0)", "dark": "oklch(0.35 0 0)" },
     { "name": "primary-foreground", "value": "oklch(0.985 0 0)", "dark": "oklch(0.985 0 0)" },
+    { "name": "link", "value": "oklch(0.205 0 0)", "dark": "oklch(0.75 0 0)" },
     { "name": "secondary", "value": "oklch(0.97 0 0)", "dark": "oklch(0.269 0 0)" },
     { "name": "secondary-foreground", "value": "oklch(0.205 0 0)", "dark": "oklch(0.985 0 0)" },
     { "name": "muted", "value": "oklch(0.97 0 0)", "dark": "oklch(0.269 0 0)" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barefootjs/cli",
-  "version": "0.31.5",
+  "version": "0.31.7",
   "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.5",
-    "@barefootjs/shared": "0.31.5"
+    "@barefootjs/client": "0.31.7",
+    "@barefootjs/shared": "0.31.7"
   },
   "devDependencies": {
-    "@barefootjs/jsx": "0.31.5",
-    "@barefootjs/vite": "0.31.5",
+    "@barefootjs/jsx": "0.31.7",
+    "@barefootjs/vite": "0.31.7",
     "@happy-dom/global-registrator": "^20.0.11",
     "@types/node": "^22.0.0",
     "happy-dom": "^20.0.11"