@barefootjs/cli 0.31.5 → 0.31.6

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.
@@ -201,6 +209,8 @@ 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.
 
+<a id="bf023"></a>
+
 ### BF023 — Missing Key in List
 
 **Trigger:** `.map()` loop without `key` prop.
@@ -219,8 +229,56 @@ backend cannot compute, and dies at render time the same way.
 
 ---
 
+## 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–BF044)
 
+<a id="bf043"></a>
+
 ### BF043 — Props Destructuring (Warning)
 
 **Trigger:** Props destructured in function parameter.
@@ -257,6 +315,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 +333,8 @@ function Child({ initialCount }: Props) {
 <Child count={count()} />
 ```
 
+<a id="bf054"></a>
+
 ### BF054 — Built-in `<Async>` / `<Region>` Used Without Import
 
 **Trigger:** A bare `<Async>` or `<Region>` tag is used without importing it

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

@@ -4963,6 +4963,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}--><!--/-->`;
       }
       {
@@ -9328,7 +9329,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 +9401,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"
+    };
   }
 });
 
@@ -29240,6 +29249,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 +29440,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.6",
   "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.6",
+    "@barefootjs/shared": "0.31.6"
   },
   "devDependencies": {
-    "@barefootjs/jsx": "0.31.5",
-    "@barefootjs/vite": "0.31.5",
+    "@barefootjs/jsx": "0.31.6",
+    "@barefootjs/vite": "0.31.6",
     "@happy-dom/global-registrator": "^20.0.11",
     "@types/node": "^22.0.0",
     "happy-dom": "^20.0.11"