@barefootjs/cli 0.1.0

package/dist/docs/core/reactivity/create-memo.md

@@ -0,0 +1,91 @@
+---
+title: createMemo
+description: Creates a cached derived value that recomputes only when its dependencies change.
+---
+
+# createMemo
+
+Creates a cached derived value. Recomputes only when its dependencies change.
+
+```ts
+import { createMemo } from '@barefootjs/client'
+
+const getter = createMemo<T>(fn: () => T): Memo<T>
+```
+
+Returns a read-only getter typed as `Memo<T>` (alias for `Reactive<() => T>`).
+
+
+## Basic Usage
+
+```tsx
+const [count, setCount] = createSignal(2)
+const doubled = createMemo(() => count() * 2)
+
+doubled() // 4
+setCount(5)
+doubled() // 10
+```
+
+
+## When to Use
+
+Use `createMemo` when you have a **derived value** that:
+
+- Depends on one or more signals
+- Is used in multiple places (avoids recalculating)
+- Involves a non-trivial computation
+
+```tsx
+const [todos, setTodos] = createSignal<Todo[]>([])
+const [filter, setFilter] = createSignal<'all' | 'active' | 'done'>('all')
+
+const filteredTodos = createMemo(() => {
+  const list = todos()
+  switch (filter()) {
+    case 'active': return list.filter(t => !t.done)
+    case 'done':   return list.filter(t => t.done)
+    default:       return list
+  }
+})
+
+// Used in multiple effects and JSX expressions
+createEffect(() => console.log(filteredTodos().length))
+```
+
+For simple expressions used once, a memo is unnecessary:
+
+```tsx
+// No memo needed
+<p>{count() * 2}</p>
+```
+
+
+## Chaining Memos
+
+Memos can depend on other memos:
+
+```tsx
+const [count, setCount] = createSignal(1)
+const doubled = createMemo(() => count() * 2)
+const quadrupled = createMemo(() => doubled() * 2)
+
+createEffect(() => {
+  console.log(quadrupled()) // 4
+})
+
+setCount(3) // Logs: 12 (3 → 6 → 12)
+```
+
+Each memo in the chain only recomputes when its direct dependencies change.
+
+
+## Memo vs Effect
+
+| | `createMemo` | `createEffect` |
+|---|---|---|
+| Returns a value | Yes (getter function) | No |
+| Triggers other effects | Yes (acts as a signal) | No |
+| Used for | Derived data | Side effects (DOM, fetch, logging) |
+
+Internally, `createMemo` is sugar over `createSignal` + `createEffect`. A memo behaves like a read-only signal to the rest of the reactive system.

package/dist/docs/core/reactivity/create-signal.md

@@ -0,0 +1,128 @@
+---
+title: createSignal
+description: Creates a reactive getter/setter pair for managing state.
+---
+
+# createSignal
+
+Creates a reactive value. Returns a getter/setter pair.
+
+```ts
+import { createSignal } from '@barefootjs/client'
+
+const [getter, setter] = createSignal<T>(initialValue: T)
+```
+
+**Type:**
+
+```tsx
+type Reactive<T> = T & { readonly __reactive: true }
+
+type Signal<T> = [
+  Reactive<() => T>,                          // getter (carries Reactive brand)
+  (valueOrFn: T | ((prev: T) => T)) => void  // setter
+]
+```
+
+The getter carries the `Reactive<T>` phantom brand — a compile-time marker for reactive expression detection. No runtime cost.
+
+
+## Basic Usage
+
+```tsx
+const [count, setCount] = createSignal(0)
+
+// Read — call the getter
+count() // 0
+
+// Write — pass a value
+setCount(5)
+count() // 5
+
+// Write — pass an updater function
+setCount(n => n + 1)
+count() // 6
+```
+
+The getter is a **function call** — `count()`, not `count`. This is how the reactivity system tracks dependencies.
+
+
+## Equality Check
+
+The setter uses `Object.is` to compare values. Identical values do not trigger effects:
+
+```tsx
+const [name, setName] = createSignal('Alice')
+setName('Alice') // No effect runs — value unchanged
+```
+
+For objects and arrays, this means you need a new reference to trigger an update:
+
+```tsx
+const [todos, setTodos] = createSignal([{ text: 'Buy milk' }])
+
+// ❌ Mutating the same array — no update
+const list = todos()
+list.push({ text: 'Walk dog' })
+setTodos(list) // Same reference, Object.is returns true
+
+// ✅ New array — triggers update
+setTodos([...todos(), { text: 'Walk dog' }])
+```
+
+
+## With Effects
+
+Reading a signal inside an effect subscribes the effect to changes:
+
+```tsx
+const [count, setCount] = createSignal(0)
+
+createEffect(() => {
+  console.log('Count is:', count()) // Runs whenever count changes
+})
+
+setCount(1) // Logs: "Count is: 1"
+setCount(2) // Logs: "Count is: 2"
+```
+
+
+## With JSX
+
+Signal getters in JSX expressions create fine-grained DOM updates:
+
+```tsx
+"use client"
+import { createSignal } from '@barefootjs/client'
+
+export function Counter() {
+  const [count, setCount] = createSignal(0)
+
+  return (
+    <div>
+      <p>{count()}</p>
+      <button onClick={() => setCount(n => n + 1)}>+1</button>
+    </div>
+  )
+}
+```
+
+The compiler generates an effect that updates only the `<p>` text content when `count` changes — the rest of the DOM is untouched.
+
+
+## Type Inference
+
+Type is inferred from the initial value:
+
+```tsx
+const [count, setCount] = createSignal(0)        // Signal<number>
+const [name, setName] = createSignal('Alice')     // Signal<string>
+const [visible, setVisible] = createSignal(false) // Signal<boolean>
+```
+
+For union types or complex types, specify the type parameter:
+
+```tsx
+const [user, setUser] = createSignal<User | null>(null)
+const [filter, setFilter] = createSignal<'all' | 'active' | 'done'>('all')
+```

package/dist/docs/core/reactivity/on-cleanup.md

@@ -0,0 +1,67 @@
+---
+title: onCleanup
+description: Registers a cleanup function that runs when the owning effect re-runs or the component is destroyed.
+---
+
+# onCleanup
+
+Registers a cleanup function. Called when the owning effect re-runs or the component is destroyed.
+
+```tsx
+import { onCleanup } from '@barefootjs/client'
+
+onCleanup(fn: () => void): void
+```
+
+
+## Basic Usage
+
+```tsx
+createEffect(() => {
+  const timer = setInterval(() => console.log('tick'), 1000)
+  onCleanup(() => clearInterval(timer))
+})
+```
+
+On re-run, the cleanup function runs first, clearing the previous interval before creating a new one.
+
+
+## Multiple Cleanups
+
+`onCleanup` can be called multiple times. Cleanups execute in reverse order (last registered, first called):
+
+```tsx
+createEffect(() => {
+  const controller = new AbortController()
+  onCleanup(() => controller.abort())
+
+  const listener = () => setHash(window.location.hash)
+  window.addEventListener('hashchange', listener)
+  onCleanup(() => window.removeEventListener('hashchange', listener))
+})
+// On cleanup: removeEventListener runs first, then abort
+```
+
+
+## With `onMount`
+
+`onCleanup` works inside `onMount` for one-time setup/teardown:
+
+```tsx
+onMount(() => {
+  const handleResize = () => setWidth(window.innerWidth)
+  window.addEventListener('resize', handleResize)
+  onCleanup(() => window.removeEventListener('resize', handleResize))
+})
+```
+
+
+## Where It Works
+
+`onCleanup` must be called within a reactive context:
+
+- Inside `createEffect`
+- Inside `onMount`
+- During component initialization
+
+Calling it outside these contexts has no effect.

package/dist/docs/core/reactivity/on-mount.md

@@ -0,0 +1,70 @@
+---
+title: onMount
+description: Runs a callback once when the component initializes, without tracking signal dependencies.
+---
+
+# onMount
+
+Runs once when the component initializes. Signal accesses inside are **not** tracked.
+
+```tsx
+import { onMount } from '@barefootjs/client'
+
+onMount(fn: () => void): void
+```
+
+
+## Basic Usage
+
+```tsx
+onMount(() => {
+  console.log('Component initialized')
+})
+```
+
+Unlike `createEffect`, this function never re-runs. It executes once at initialization time.
+
+
+## Common Patterns
+
+### Browser state
+
+```tsx
+onMount(() => {
+  const hash = window.location.hash
+  setFilter(hash === '#/active' ? 'active' : 'all')
+})
+```
+
+### Event listeners
+
+```tsx
+onMount(() => {
+  const handleHashChange = () => setFilter(getFilterFromHash())
+  window.addEventListener('hashchange', handleHashChange)
+  onCleanup(() => window.removeEventListener('hashchange', handleHashChange))
+})
+```
+
+### Focus
+
+```tsx
+onMount(() => {
+  inputElement.focus()
+})
+```
+
+
+## How It Works
+
+`onMount` is equivalent to `createEffect(() => untrack(fn))`. The function runs inside an effect context (so `onCleanup` works), but `untrack` prevents dependency tracking.
+
+
+## `onMount` vs `createEffect`
+
+| | `onMount` | `createEffect` |
+|---|---|---|
+| Runs on init | Yes | Yes |
+| Re-runs on signal change | No | Yes |
+| Tracks dependencies | No | Yes |
+| Supports `onCleanup` | Yes | Yes |

package/dist/docs/core/reactivity/props-reactivity.md

@@ -0,0 +1,91 @@
+---
+title: Props Reactivity
+description: How prop access patterns determine whether reactive updates propagate in BarefootJS components.
+---
+
+# Props Reactivity
+
+**How you access props determines whether updates propagate.** The compiler wraps dynamic prop expressions in getters.
+
+
+## Direct Access — Reactive
+
+`props.xxx` maintains reactivity. Each access calls the underlying getter:
+
+```tsx
+function Display(props: { value: number }) {
+  createEffect(() => {
+    console.log(props.value) // Re-runs when parent updates value
+  })
+  return <span>{props.value}</span>
+}
+```
+
+
+## Destructuring — Captures Once
+
+Destructuring calls the getter once and stores the result. The value does not update:
+
+```tsx
+function Display({ value }: { value: number }) {
+  createEffect(() => {
+    console.log(value) // Stale — captured at component init
+  })
+  return <span>{value}</span>
+}
+```
+
+The compiler emits `BF043` when it detects props destructuring in a client component:
+
+```
+warning[BF043]: Props destructuring breaks reactivity
+
+  --> src/components/Display.tsx:1:18
+   |
+ 1 | function Display({ value }: { value: number }) {
+   |                  ^^^^^^^^^
+   |
+   = help: Access props via `props.value` to maintain reactivity
+```
+
+Suppress with `@bf-ignore` when capturing intentionally (e.g., initial values):
+
+```tsx
+// @bf-ignore props-destructuring
+function Counter({ initial }: { initial: number }) {
+  const [count, setCount] = createSignal(initial)
+  return <button onClick={() => setCount(n => n + 1)}>{count()}</button>
+}
+```
+
+
+## When Destructuring Is Safe
+
+Destructuring is safe for **initial values** of local state and for values that never change (`id`, static labels).
+
+
+## Summary
+
+| Pattern | Reactive? | Use when |
+|---------|-----------|----------|
+| `props.value` | Yes | You need live updates from parent |
+| `const { value } = props` | No | Value is used once (e.g., initial state) |
+| `createSignal(props.value)` | `props.value` is reactive, signal is independent | Creating local state from a prop |
+
+
+## How It Works
+
+The compiler transforms dynamic prop expressions into getters:
+
+```tsx
+// Parent
+<Child value={count()} />
+
+// Compiled props object
+{ get value() { return count() } }
+```
+
+- `props.value` → calls getter → calls `count()` → dependency tracked
+- `const { value } = props` → calls getter once → stores the number → no further tracking
+
+This is the same model as SolidJS. If you are coming from React, this is the key behavioral difference.

package/dist/docs/core/reactivity/untrack.md

@@ -0,0 +1,69 @@
+---
+title: untrack
+description: Executes a function without tracking signal dependencies in the current reactive context.
+---
+
+# untrack
+
+Executes a function without tracking signal dependencies.
+
+```tsx
+import { untrack } from '@barefootjs/client'
+
+untrack<T>(fn: () => T): T
+```
+
+Returns the value produced by `fn`.
+
+
+## Basic Usage
+
+```tsx
+const [count, setCount] = createSignal(0)
+const [name, setName] = createSignal('Alice')
+
+createEffect(() => {
+  // count() IS tracked — this effect re-runs when count changes
+  console.log('count:', count())
+
+  // name() is NOT tracked — changing name alone won't trigger this effect
+  console.log('name:', untrack(() => name()))
+})
+
+setCount(1) // Effect re-runs
+setName('Bob') // Effect does NOT re-run
+```
+
+
+## When to Use
+
+### Read without subscribing
+
+```tsx
+createEffect(() => {
+  // Re-run only when items change, not when sortOrder changes
+  const sorted = [...items()].sort(untrack(() => sortOrder()) === 'asc' ? compare : reverseCompare)
+  setDisplayList(sorted)
+})
+```
+
+### Log without dependencies
+
+```tsx
+createEffect(() => {
+  const value = computedResult()
+  console.log('Updated at:', untrack(() => new Date().toISOString()))
+})
+```
+
+### Break circular dependencies
+
+`untrack` breaks cycles where two signals depend on each other through effects:
+
+```tsx
+createEffect(() => {
+  const a = signalA()
+  const b = untrack(() => signalB()) // Read B without tracking
+  setResult(a + b)
+})
+```

package/dist/docs/core/reactivity.md

@@ -0,0 +1,28 @@
+---
+title: Reactivity
+description: Fine-grained reactive primitives inspired by SolidJS, including signals, effects, memos, and lifecycle hooks.
+---
+
+# Reactivity
+
+All reactive primitives are imported from `@barefootjs/client`:
+
+```tsx
+"use client"
+import { createSignal, createEffect, createMemo, onMount, onCleanup, untrack } from '@barefootjs/client'
+```
+
+## API Reference
+
+| API | Description |
+|-----|-------------|
+| [`createSignal`](./reactivity/create-signal.md) | Create a reactive value |
+| [`createEffect`](./reactivity/create-effect.md) | Run side effects when dependencies change |
+| [`createMemo`](./reactivity/create-memo.md) | Create a cached derived value |
+| [`onMount`](./reactivity/on-mount.md) | Run once on component initialization |
+| [`onCleanup`](./reactivity/on-cleanup.md) | Register cleanup for effects and lifecycle |
+| [`untrack`](./reactivity/untrack.md) | Read signals without tracking dependencies |
+
+## Guides
+
+- [Props Reactivity](./reactivity/props-reactivity.md) — How props stay reactive, and when destructuring breaks it

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

@@ -0,0 +1,82 @@
+---
+title: /* @client */ Directive
+description: Mark JSX expressions for client-only evaluation when the compiler cannot translate them to server templates.
+---
+
+# /* @client */ Directive
+
+Marks a JSX expression for **client-only evaluation**. The server renders a placeholder; the browser evaluates the expression at runtime.
+
+```tsx
+{/* @client */ expression}
+```
+
+
+## When to Use
+
+The compiler emits `BF021` for expressions it cannot translate to a marked template. `/* @client */` resolves the error by opting into client-only evaluation.
+
+```
+error[BF021]: Expression cannot be compiled to marked template
+
+  --> src/components/Dashboard.tsx:15:10
+   |
+15 |   {items().reduce((sum, x) => sum + x.price, 0)}
+   |    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: Add /* @client */ to evaluate this expression on the client only
+```
+
+See [JSX Compatibility — Limitations](./jsx-compatibility.md#limitations) for the full list of unsupported patterns.
+
+
+## How It Works
+
+The compiler skips template generation for the expression. The server outputs a comment marker; the client JS evaluates it:
+
+**Server output:**
+
+```html
+<!--bf-client:s2--><!--/-->
+```
+
+**Client JS:**
+
+```js
+// @client: s2
+createEffect(() => {
+  updateClientMarker(__scope, 's2', todos().filter(t => !t.done).length)
+})
+```
+
+
+## Examples
+
+### Unsupported patterns
+
+```tsx
+// Nested higher-order methods
+{/* @client */ items().filter(x => x.tags().filter(t => t.active).length > 0)}
+
+// Unsupported array methods
+{/* @client */ items().reduce((sum, x) => sum + x.price, 0)}
+```
+
+### Explicit client-only evaluation
+
+Even for patterns the compiler supports, you can use `/* @client */` to skip server evaluation. The [TodoApp example](https://github.com/piconic-ai/barefootjs/blob/main/integrations/shared/components/TodoApp.tsx) uses this approach:
+
+```tsx
+// These expressions CAN compile without @client, but the developer
+// chose client-only evaluation here
+checked={/* @client */ todos().every(t => t.done)}
+
+<strong>{/* @client */ todos().filter(t => !t.done).length}</strong>
+```
+
+Compare with the [TodoAppSSR version](https://github.com/piconic-ai/barefootjs/blob/main/integrations/shared/components/TodoAppSSR.tsx), which omits `/* @client */` and lets the compiler generate marked template equivalents for the same expressions.
+
+
+## Trade-off
+
+`/* @client */` means **no server-rendered content** for the expression — users see a placeholder until client JS loads. Omit the directive when the compiler can generate a template equivalent to get server-rendered initial values.

package/dist/docs/core/rendering/fragment.md

@@ -0,0 +1,43 @@
+---
+title: Fragment
+description: Using fragments to render children without a wrapper element, including transparent fragment behavior.
+---
+
+# Fragment
+
+Fragments (`<>...</>`) are supported. They render children without a wrapper element.
+
+```tsx
+<>
+  <h1>Title</h1>
+  <p>Description</p>
+</>
+```
+
+
+## Transparent Fragments
+
+A fragment that passes through `children` is treated as transparent — the compiler skips it and processes the children directly:
+
+```tsx
+<>{children}</>
+<>{props.children}</>
+```
+
+No extra hydration markers are generated for transparent fragments.
+
+
+## Fragments and Hydration
+
+Fragments don't produce a DOM node. For conditional fragments, the compiler uses HTML comment markers as boundaries:
+
+```html
+<!--bf-cond-start:s0-->
+<h1>Title</h1>
+<p>Description</p>
+<!--bf-cond-end:s0-->
+```
+
+The client runtime uses these comment markers to locate and swap the fragment content when the condition changes.
+
+For component roots that return a fragment, each direct child element is marked with `bf-s` so the runtime can find them during hydration.