@barefootjs/cli 0.1.0

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

@@ -0,0 +1,115 @@
+---
+title: Performance Optimization
+description: Strategies to minimize bundle size, reduce hydration cost, and optimize runtime reactivity
+---
+
+# Performance Optimization
+
+## Zero-JS by Default
+
+Components without `"use client"` generate **no client JavaScript**:
+
+```tsx
+// Server-only — 0 bytes of client JS
+export function Header() {
+  return (
+    <header>
+      <h1>My App</h1>
+      <nav>...</nav>
+    </header>
+  )
+}
+```
+
+## Minimal Hydration
+
+Only signals, event handlers, and effects are sent to the client. The HTML structure is never re-created — the server already rendered it.
+
+---
+
+## Reducing Client JS Size
+
+### Use Memos for Derived Values
+
+```tsx
+// ❌ Redundant signal
+const [count, setCount] = createSignal(0)
+const [doubled, setDoubled] = createSignal(0)
+createEffect(() => setDoubled(count() * 2))  // Extra signal + effect
+
+// ✅ Use memo instead
+const [count, setCount] = createSignal(0)
+const doubled = createMemo(() => count() * 2)  // Computed, no extra signal
+```
+
+### Prefer Static Arrays
+
+The compiler detects static arrays and skips reconciliation:
+
+```tsx
+// Static — no reconciliation generated
+const tabs = ['Home', 'About', 'Contact']
+{tabs.map(tab => <Tab label={tab} />)}
+
+// Dynamic — reconcileElements needed
+const [items, setItems] = createSignal([...])
+{items().map(item => <Item key={item.id} data={item} />)}
+```
+
+---
+
+## Optimizing Hydration
+
+### Stable Keys for Lists
+
+```tsx
+// ✅ Stable key — DOM nodes reused when list changes
+{items().map(item => <li key={item.id}>{item.name}</li>)}
+
+// ❌ Index key — DOM nodes recreated on reorder
+{items().map((item, i) => <li key={i}>{item.name}</li>)}
+```
+
+### Focus Preservation
+
+The reconciler preserves focused elements during list updates automatically.
+
+---
+
+## Optimizing Reactivity
+
+### `untrack` for One-Time Reads
+
+```tsx
+createEffect(() => {
+  // Only re-runs when items() changes, not when count() changes
+  const currentCount = untrack(() => count())
+  console.log(`${items().length} items, count was ${currentCount}`)
+})
+```
+
+### Memo Over Effect + Signal
+
+```tsx
+// ❌ Effect → Signal chain (two subscriptions)
+const [total, setTotal] = createSignal(0)
+createEffect(() => setTotal(price() * quantity()))
+
+// ✅ Single memo (one subscription)
+const total = createMemo(() => price() * quantity())
+```
+
+### Guard DOM Updates
+
+```tsx
+createEffect(() => {
+  const cls = isActive() ? 'active' : 'inactive'
+  if (element.className !== cls) {
+    element.className = cls  // Only touches DOM when value changes
+  }
+})
+```
+
+The compiler already generates guarded updates for text content and common attributes. This applies to custom effects only.
+
+

package/dist/docs/core/advanced/xyflow-browser-bundle.md

@@ -0,0 +1,69 @@
+---
+title: xyflow browser bundle
+description: How to serve @barefootjs/xyflow as a pre-built browser chunk via an importmap
+---
+
+# xyflow browser bundle
+
+`@barefootjs/xyflow` ships a pre-minified ESM variant, `dist/xyflow.browser.min.js`, with `@barefootjs/client*` left as externals. Apps that want to serve xyflow as an independently-cached static asset can copy this file instead of re-bundling.
+
+## Why a pre-built variant
+
+Bundling xyflow into a large client entry adds ~270 KB of d3 + wrapper code to every cold-visit payload. Re-bundling it manually as a separate chunk requires remembering three externals:
+
+```
+--external '@barefootjs/client'
+--external '@barefootjs/client/runtime'
+--external '@barefootjs/client/reactive'
+```
+
+Missing any one of them silently inlines a second copy of the reactive primitives, breaking signal propagation across the boundary (fitView becomes a no-op, `FlowContext` reads from the wrong owner, etc.). The pre-built variant has all three applied already.
+
+## Setup
+
+**1. Copy the file into your static output:**
+
+```sh
+cp node_modules/@barefootjs/xyflow/dist/xyflow.browser.min.js \
+   public/static/components/xyflow.js
+
+# Optional: copy the sourcemap for readable DevTools stacks
+cp node_modules/@barefootjs/xyflow/dist/xyflow.browser.min.js.map \
+   public/static/components/xyflow.js.map
+```
+
+**2. Add an importmap to your HTML:**
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "@barefootjs/client":          "/static/components/barefoot.js",
+    "@barefootjs/client/runtime":  "/static/components/barefoot.js",
+    "@barefootjs/client/reactive": "/static/components/barefoot.js",
+    "@barefootjs/xyflow":          "/static/components/xyflow.js"
+  }
+}
+</script>
+```
+
+The three `@barefootjs/client*` entries all pointing at the same file is what makes the browser deduplicate them into a single module instance, so reactive primitives share one `Listener`/`Owner` global.
+
+## package.json fields
+
+The file is also exposed via the `umd` export condition and the `unpkg`/`jsdelivr` top-level fields:
+
+```json
+{
+  "exports": {
+    ".": {
+      "umd":    "./dist/xyflow.browser.min.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "unpkg":    "./dist/xyflow.browser.min.js",
+  "jsdelivr": "./dist/xyflow.browser.min.js"
+}
+```
+
+CDNs like unpkg and jsDelivr resolve the top-level fields automatically, so `https://unpkg.com/@barefootjs/xyflow` serves the pre-built variant.

package/dist/docs/core/advanced.md

@@ -0,0 +1,11 @@
+---
+title: Advanced
+description: Compiler internals, IR schema, error codes, and performance optimization for contributors and adapter authors.
+---
+
+# Advanced
+
+- [IR Schema Reference](./advanced/ir-schema.md) — The intermediate representation node types and metadata
+- [Compiler Internals](./advanced/compiler-internals.md) — Pipeline phases, reactivity analysis, and code generation
+- [Error Codes Reference](./advanced/error-codes.md) — All compiler errors and warnings with solutions
+- [Performance Optimization](./advanced/performance.md) — Best practices for minimal client JS and fast hydration

package/dist/docs/core/components/children-slots.md

@@ -0,0 +1,150 @@
+---
+title: Children & Slots
+description: Accept nested JSX content via the children prop and enable polymorphic rendering with the Slot component.
+---
+
+# Children & Slots
+
+Nested JSX content is passed via the `children` prop. The `Slot` component enables polymorphic rendering with `asChild`.
+
+
+## Children
+
+```tsx
+<Card>
+  <h2>Title</h2>
+  <p>Body text</p>
+</Card>
+```
+
+```tsx
+function Card(props: { children?: Child }) {
+  return <div className="card">{props.children}</div>
+}
+```
+
+`children` is typed as `Child`, which covers JSX elements, strings, numbers, and arrays.
+
+
+## Passing Children Through
+
+```tsx
+function Panel(props: { title: string; children?: Child }) {
+  return (
+    <section>
+      <h2>{props.title}</h2>
+      <div className="panel-body">{props.children}</div>
+    </section>
+  )
+}
+```
+
+Wrapping `children` in a fragment (`<>{props.children}</>`) is **transparent** — the compiler skips the fragment without extra hydration markers. See [Fragment](../rendering/fragment.md).
+
+
+## The `Slot` Component
+
+`Slot` merges props and classes onto its child element, enabling the **`asChild` pattern**:
+
+```tsx
+import { Slot } from './slot'
+
+function Button({ className, asChild, children, ...props }: ButtonProps) {
+  const classes = `btn btn-primary ${className}`
+
+  if (asChild) {
+    return <Slot className={classes} {...props}>{children}</Slot>
+  }
+  return <button className={classes} {...props}>{children}</button>
+}
+```
+
+### How `Slot` Works
+
+`Slot` extracts the child's tag, merges `className` (space-separated), spreads remaining props, and renders the child's tag with the merged result.
+
+```tsx
+// Input
+<Slot className="btn" onClick={handleClick}>
+  <a href="/home">Home</a>
+</Slot>
+
+// Output
+<a href="/home" className="btn" onClick={handleClick}>Home</a>
+```
+
+If `children` is not a valid element (e.g., a string), `Slot` falls back to rendering it inside a fragment.
+
+
+## The `asChild` Pattern
+
+`asChild` delegates rendering to the child element — the component's styling without its default HTML tag.
+
+### Default rendering (no `asChild`)
+
+```tsx
+<Button variant="primary">Click me</Button>
+// Renders: <button className="btn btn-primary">Click me</button>
+```
+
+### With `asChild`
+
+```tsx
+<Button variant="primary" asChild>
+  <a href="/dashboard">Go to Dashboard</a>
+</Button>
+// Renders: <a href="/dashboard" className="btn btn-primary">Go to Dashboard</a>
+```
+
+The `<a>` tag receives Button's classes and props. The component controls styling; the caller controls the element.
+
+### When to Use `asChild`
+
+- Navigation buttons (render `<a>` with button styling)
+- Custom triggers (dialog or dropdown)
+- Semantic elements with reused component styles
+
+```tsx
+// Dialog trigger as a custom element
+<DialogTrigger asChild>
+  <span role="button" tabIndex={0}>Open</span>
+</DialogTrigger>
+```
+
+
+## Compound Components
+
+```tsx
+<Dialog open={open()} onOpenChange={setOpen}>
+  <DialogTrigger>Open</DialogTrigger>
+  <DialogOverlay />
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Confirm</DialogTitle>
+      <DialogDescription>Are you sure?</DialogDescription>
+    </DialogHeader>
+    <DialogFooter>
+      <DialogClose>Cancel</DialogClose>
+      <Button onClick={handleConfirm}>Yes</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+Sub-components read shared state from a context provider. See [Context API](./context-api.md).
+
+
+## List Rendering
+
+```tsx
+{todos().map(todo => (
+  <TodoItem
+    key={todo.id}
+    todo={todo}
+    onToggle={() => handleToggle(todo.id)}
+    onDelete={() => handleDelete(todo.id)}
+  />
+))}
+```
+
+`key` is required for efficient list updates (warning `BF023` if missing).

package/dist/docs/core/components/component-authoring.md

@@ -0,0 +1,207 @@
+---
+title: Component Authoring
+description: Learn how to write server and client components in BarefootJS using JSX functions.
+---
+
+# Component Authoring
+
+Components are functions that return JSX, in two kinds: **server components** and **client components**.
+
+
+## Server Components
+
+Server components render HTML on the server with no client-side JavaScript.
+
+```tsx
+export function Greeting({ name }: { name: string }) {
+  return <h1>Hello, {name}</h1>
+}
+```
+
+Server components can access databases, read files, and use secrets. They produce a template rendered once per request.
+
+
+## Client Components
+
+Client components use reactive primitives and ship JavaScript to the browser. They require the `"use client"` directive:
+
+```tsx
+"use client"
+import { createSignal } from '@barefootjs/client'
+
+export function Counter() {
+  const [count, setCount] = createSignal(0)
+
+  return (
+    <button onClick={() => setCount(n => n + 1)}>
+      Count: {count()}
+    </button>
+  )
+}
+```
+
+The compiler produces a **marked template** (server HTML with `bf-*` attributes) and **client JS** (signals, effects, event handlers). See [How It Works](../core-concepts/how-it-works.md#two-phase-compilation) for details.
+
+### When `"use client"` Is Required
+
+Add `"use client"` when a component uses:
+
+- `createSignal`, `createEffect`, `createMemo`
+- `onMount`, `onCleanup`, `untrack`
+- `createContext`, `useContext`
+- Event handlers (`onClick`, `onChange`, etc.)
+
+Without the directive:
+
+```
+error[BF001]: 'use client' directive required for components with createSignal
+```
+
+
+## Component Naming
+
+Component names must start with an uppercase letter:
+
+```tsx
+// ✅ Component
+function TodoItem() { ... }
+
+// ❌ Error BF042
+function todoItem() { ... }
+```
+
+
+## Compilation Output
+
+**Source:**
+
+```tsx
+"use client"
+import { createSignal } from '@barefootjs/client'
+
+export function Toggle() {
+  const [on, setOn] = createSignal(false)
+
+  return (
+    <button onClick={() => setOn(prev => !prev)}>
+      {on() ? 'ON' : 'OFF'}
+    </button>
+  )
+}
+```
+
+**Marked template:**
+
+<!-- tabs:adapter -->
+<!-- tab:Hono -->
+```tsx
+export function Toggle({ __instanceId, ... }) {
+  const __scopeId = __instanceId || `Toggle_${...}`
+  const on = () => false
+
+  return (
+    <button bf-s={__scopeId} bf="s1">
+      {on() ? <>{bfComment("cond-start:s0")}{'ON'}{bfComment("cond-end:s0")}</>
+            : <>{bfComment("cond-start:s0")}{'OFF'}{bfComment("cond-end:s0")}</>}
+    </button>
+  )
+}
+```
+<!-- tab:Go Template -->
+```go-template
+{{define "Toggle"}}
+<button bf-s="{{bfScopeAttr .}}" bf="s1">
+  {{if .On}}{{bfComment "cond-start:s0"}}{{"ON"}}{{bfComment "cond-end:s0"}}
+  {{else}}{{bfComment "cond-start:s0"}}{{"OFF"}}{{bfComment "cond-end:s0"}}{{end}}
+</button>
+{{end}}
+```
+<!-- /tabs -->
+
+**Client JS:**
+
+```js
+import { $, createSignal, hydrate, insert } from '@barefootjs/client'
+
+export function initToggle(__scope, _p = {}) {
+  if (!__scope) return
+
+  const [on, setOn] = createSignal(false)
+
+  const [_s1, _s0] = $(__scope, 's1', 's0')
+
+  insert(__scope, 's0', () => on(), {
+    template: () => `<!--bf-cond-start:s0-->ON<!--bf-cond-end:s0-->`,
+    bindEvents: (__branchScope) => {}
+  }, {
+    template: () => `<!--bf-cond-start:s0-->OFF<!--bf-cond-end:s0-->`,
+    bindEvents: (__branchScope) => {}
+  })
+
+  if (_s1) _s1.addEventListener('click', () => { setOn(prev => !prev) })
+}
+
+hydrate('Toggle', { init: initToggle, template: ... })
+```
+
+Only the conditional branch bound to `on()` updates when the signal changes. The `insert()` function handles DOM swapping using comment markers as boundaries.
+
+
+## Composition Rules
+
+| From | To | Allowed |
+|------|----|---------|
+| Server component | Server component | ✅ |
+| Server component | Client component | ✅ |
+| Client component | Client component | ✅ |
+| Client component | Server component | ❌ |
+
+Server-only code does not exist in the browser. The compiler emits `BF003` if a client component imports a server component.
+
+```tsx
+// Page.tsx — server component
+import { Counter } from './Counter'    // "use client" ✅
+import { UserList } from './UserList'  // server-only  ✅
+
+export function Page() {
+  return (
+    <div>
+      <UserList />   {/* Server → Server */}
+      <Counter />    {/* Server → Client */}
+    </div>
+  )
+}
+```
+
+```tsx
+// Dashboard.tsx — "use client"
+import { Counter } from './Counter'    // ✅ Client → Client
+import { UserList } from './UserList'  // ❌ BF003: Client → Server
+```
+
+## Ref Callbacks
+
+`ref` callbacks provide imperative DOM access. The callback receives the element after mount:
+
+```tsx
+"use client"
+import { createEffect } from '@barefootjs/client'
+
+export function AutoFocus() {
+  const handleMount = (el: HTMLInputElement) => {
+    el.focus()
+  }
+
+  return <input ref={handleMount} placeholder="Focused on mount" />
+}
+```
+
+Combine with `createEffect` for reactive DOM updates:
+
+```tsx
+const handleMount = (el: HTMLElement) => {
+  createEffect(() => {
+    el.className = isActive() ? 'active' : 'inactive'
+  })
+}
+```