@barefootjs/cli 0.26.3 → 0.27.0

package/dist/docs/core/advanced/compiler-internals.md

@@ -195,7 +195,7 @@ createEffect(() => {
 ### 4. Code Generation Order
 
 ```javascript
-import { $, $t, createEffect, createMemo, createSignal, hydrate, onMount } from '@barefootjs/client'
+import { $, createEffect, createMemo, createSignal, escapeTextOrNode, hydrate, lazySlots, onMount } from '@barefootjs/client/runtime'
 
 export function initCounter(__scope, _p = {}) {
   if (!__scope) return
@@ -216,15 +216,16 @@ export function initCounter(__scope, _p = {}) {
   const doubled = createMemo(() => count() * 2)
 
   // 4. Element references (always destructured, always returns array)
-  //    $()  — regular elements:  querySelector('[bf="id"]') within scope
-  //    $t() — text nodes:        find comment marker <!--bf:id-->
+  //    $() — regular elements: querySelector('[bf="id"]') within scope
   const [_s3] = $(__scope, 's3')
-  const [_s0, _s2] = $t(__scope, 's0', 's2')
 
-  // 5. Dynamic text updates
+  // 5. Dynamic content updates — the compiler emits a claim plan (data)
+  //    per slot; lazySlots() claims the <!--bf:id-->…<!--/--> marker
+  //    range once on first write, then writes through the held reference
+  const __bfw_s0 = lazySlots(__scope, [{ id: 's0', kind: 'markup', path: [] }])
   createEffect(() => {
     const __val = count()
-    if (_s0 && !__val?.__isSlot) _s0.nodeValue = String(__val ?? '')
+    __bfw_s0('s0', escapeTextOrNode(__val))
   })
 
   // 6. Reactive attribute updates
@@ -266,7 +267,7 @@ hydrate('Counter', {
 Only used imports are included:
 
 ```javascript
-import { $, $t, createEffect, createMemo, createSignal, hydrate, onMount } from '@barefootjs/client'
+import { $, createEffect, createMemo, createSignal, escapeTextOrNode, hydrate, lazySlots, onMount } from '@barefootjs/client/runtime'
 ```
 
 ### 6. Template Registration

package/dist/docs/core/advanced/performance.md

@@ -51,7 +51,7 @@ The compiler detects static arrays and skips reconciliation:
 const tabs = ['Home', 'About', 'Contact']
 {tabs.map(tab => <Tab label={tab} />)}
 
-// Dynamic — reconcileElements needed
+// Dynamic — keyed reconciliation (mapArray) needed
 const [items, setItems] = createSignal([...])
 {items().map(item => <Item key={item.id} data={item} />)}
 ```

package/dist/docs/core/core-concepts/how-it-works.mdx

@@ -82,7 +82,7 @@ export function Counter({ __instanceId, ... }) {
 Client JS (Phase 2b):
 
 ```js
-import { $, $t, createEffect, createSignal, hydrate } from '@barefootjs/client'
+import { $, createEffect, createSignal, escapeText, escapeTextOrNode, hydrate, lazySlots } from '@barefootjs/client/runtime'
 
 export function initCounter(__scope, _p = {}) {
   if (!__scope) return
@@ -90,11 +90,13 @@ export function initCounter(__scope, _p = {}) {
   const [count, setCount] = createSignal(0)
 
   const [_s1] = $(__scope, 's1')       // element lookup
-  const [_s0] = $t(__scope, 's0')      // text node lookup
 
+  // Content slot: claimed lazily from the <!--bf:s0-->…<!--/--> marker
+  // pair on first write, then updated through the held reference
+  const __bfw_s0 = lazySlots(__scope, [{ id: 's0', kind: 'markup', path: [] }])
   createEffect(() => {
     const __val = count()
-    if (_s0) _s0.nodeValue = String(__val ?? '')
+    __bfw_s0('s0', escapeTextOrNode(__val))
   })
 
   if (_s1) _s1.addEventListener('click', () => { setCount(n => n + 1) })
@@ -102,7 +104,7 @@ export function initCounter(__scope, _p = {}) {
 
 hydrate('Counter', {
   init: initCounter,
-  template: (_p) => `<button bf="s1"> Count: <!--bf:s0-->${(0)}<!--/--></button>`
+  template: (_p) => `<button bf="s1"> Count: <!--bf:s0-->${escapeText((0))}<!--/--></button>`
 })
 ```
 
@@ -135,9 +137,11 @@ Marker-driven hydration attaches behavior to server-rendered HTML.
 4. Init function runs per scope — signals, effects, handlers
 5. Runtime tracks scopes to prevent double initialization
 
-### Scoped Queries
+### Scoped Queries and Slot Claiming
 
-`$()` and `$t()` search within a scope, excluding child component scopes:
+Element lookups (`$()`) and content-slot claims (`claimSlots()` /
+`lazySlots()`) both operate within a scope, excluding child component
+scopes:
 
 ```html
 <div bf-s="TodoApp_x1">
@@ -148,4 +152,16 @@ Marker-driven hydration attaches behavior to server-rendered HTML.
 </div>
 ```
 
-`$(__scope, 's0')` in TodoApp finds `<h1>`, not the `<span>` inside TodoItem. The `~` prefix marks a child scope excluded from parent queries.
+`$(__scope, 's0')` in TodoApp finds `<h1>`, not the `<span>` inside
+TodoItem. The `~` prefix marks a child scope excluded from parent
+queries.
+
+Dynamic *content* (reactive text and markup regions) is not looked up
+per update. Instead the compiler emits a **claim plan** — a data
+description of each slot (`{ id, kind, path }`) — and the runtime claims
+the slot's DOM position **once**: `lazySlots()` scans for the slot's
+`<!--bf:id-->…<!--/-->` marker pair on the first write (skipping child
+scopes, same as `$()`), holds the reference, and every later write goes
+through that held reference with no re-scanning. `claimSlots()` is the
+eager variant used where content may be mutated before the first write
+(streaming, portals).

package/dist/docs/core/introduction.mdx

@@ -63,7 +63,7 @@ export function Counter({ __instanceId, ... }) {
 **Client script** — Wires up only the interactive parts:
 
 ```js
-import { $, $t, createEffect, createSignal, hydrate } from '@barefootjs/client'
+import { $, createEffect, createSignal, escapeText, escapeTextOrNode, hydrate, lazySlots } from '@barefootjs/client/runtime'
 
 export function initCounter(__scope, _p = {}) {
   if (!__scope) return
@@ -71,11 +71,13 @@ export function initCounter(__scope, _p = {}) {
   const [count, setCount] = createSignal(0)
 
   const [_s1] = $(__scope, 's1')       // find element with bf="s1"
-  const [_s0] = $t(__scope, 's0')      // find text node at <!--bf:s0-->
 
+  // Claim the content slot between <!--bf:s0--> and <!--/--> on first
+  // write; later writes reuse the claimed reference (no re-scanning)
+  const __bfw_s0 = lazySlots(__scope, [{ id: 's0', kind: 'markup', path: [] }])
   createEffect(() => {
     const __val = count()
-    if (_s0) _s0.nodeValue = String(__val ?? '')
+    __bfw_s0('s0', escapeTextOrNode(__val))
   })
 
   if (_s1) _s1.addEventListener('click', () => { setCount(n => n + 1) })
@@ -83,6 +85,6 @@ export function initCounter(__scope, _p = {}) {
 
 hydrate('Counter', {
   init: initCounter,
-  template: (_p) => `<button bf="s1"> Count: <!--bf:s0-->${(0)}<!--/--></button>`
+  template: (_p) => `<button bf="s1"> Count: <!--bf:s0-->${escapeText((0))}<!--/--></button>`
 })
 ```

package/dist/docs/core/rendering/client-directive.md

@@ -32,23 +32,40 @@ See [JSX Compatibility — Limitations](./jsx-compatibility.md#limitations) for
 
 ## How It Works
 
-The compiler skips template generation for the expression. The server outputs a comment marker; the client JS evaluates it:
+The compiler skips template generation for the expression: the server can never evaluate it, so the SSR-rendered width is always zero. The client claims a slot for it and writes the real value once the browser evaluates the expression — the general case behind both compiled shapes below (`spec/slot-unification.md` §4).
 
-**Server output:**
+**Claimed slot (the common case):** a marker pair is still emitted so the client has an anchor comment to claim against.
 
 ```html
-<!--bf-client:s2--><!--/-->
+<!-- server output -->
+<!--bf:s0--><!--/--> items left
 ```
 
-**Client JS:**
+```js
+// client JS
+{ const __bfw_s0 = lazySlots(__scope, [{ id: 's0', kind: 'text', path: [] }])
+createEffect(() => {
+  __bfw_s0('s0', todos().filter(t => !t.done).length)
+}) }
+```
+
+**Markerless elision (Step B):** when the expression is the ONLY content of its own element — not adjacent to other text/expressions, and not inside a loop or conditional branch — the compiler proves a static child-index path to the slot's position and drops the marker pair entirely from both SSR and CSR output. `<strong>{/* @client */ todos().filter(t => !t.done).length}</strong>` from the [TodoApp example](https://github.com/piconic-ai/barefootjs/blob/main/integrations/shared/components/TodoApp.tsx) qualifies:
+
+```html
+<!-- server output -->
+<strong bf="s1"></strong>
+```
 
 ```js
-// @client: s2
+// client JS
+{ const __bfw_s0 = lazySlots(__scope, [{ id: 's0', kind: 'text', path: [0, 0], markerless: true }])
 createEffect(() => {
-  updateClientMarker(__scope, 's2', todos().filter(t => !t.done).length)
-})
+  __bfw_s0('s0', todos().filter(t => !t.done).length)
+}) }
 ```
 
+Either way, the claim happens lazily on the first write — nothing is touched until the effect actually runs — and every later write goes through the held reference, never re-scanning the DOM (`packages/client/src/runtime/claim-slots.ts`).
+
 
 ## Examples
 

package/dist/docs/core/rendering/jsx-compatibility.md

@@ -52,6 +52,21 @@ return <div>...</div>
 ))}
 ```
 
+`.flatMap()` expands nested collections into a flat run of keyed elements. A pure projection body — the nested `.map()` as the whole body, expression or single-`return` block — compiles on every adapter; a body with statements before the projection (early returns, `const`s) runs as JS on JS-runtime adapters and needs [`/* @client */`](./client-directive.md) on DSL backends:
+
+```tsx
+// ✅ Projection — works on every adapter
+{todos().flatMap(todo => todo.tags.map(tag => (
+  <li key={`${todo.id}:${tag}`}>{tag}</li>
+)))}
+
+// ✅ Statement body — JS-runtime adapters; /* @client */ on Go/Mojo etc.
+{todos().flatMap(todo => {
+  if (todo.hidden) return []
+  return todo.tags.map(tag => <li key={`${todo.id}:${tag}`}>{tag}</li>)
+})}
+```
+
 `.sort()` and `.toSorted()` can be chained with `.map()` and `.filter()`:
 
 ```tsx
@@ -105,7 +120,9 @@ Some JavaScript expressions cannot be translated into marked template syntax. Wh
 |---|---|---|
 | `.filter()` with destructured param (`({done}) => done`) | works (runs as JS) | **BF101** |
 | `.filter()` with `function` keyword callback | works | **BF101** |
-| `.reduce()`, `.forEach()`, `.flatMap()` | works | **BF101** |
+| `.reduce()`, `.forEach()`, value-returning `.flatMap()` with an off-catalogue projection | works | **BF101** |
+| JSX-returning `.flatMap()` projection (`items.flatMap(it => it.tags.map(tag => <li key={...}/>))`) | works | works |
+| 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** |
 | Sort comparator that's a multi-statement block body or `localeCompare(b, locale, opts)` | works (runs as JS) | **BF021** |