@barefootjs/cli 0.1.2 → 1.0.0

package/dist/docs/core/{README.md → README.mdx}

@@ -2,7 +2,7 @@
 
 ## Table of Contents
 
-### 1. [Introduction](./introduction.md)
+### 1. [Introduction](./introduction.mdx)
 
 - What is BarefootJS?
 - Why BarefootJS?
@@ -19,8 +19,8 @@
 - [Backend Freedom](./core-concepts/backend-freedom.md) — How adapters let the same JSX run on any server
 - [MPA-style Development](./core-concepts/mpa-style.md) — Server-rendering by default, JS only where marked
 - [Fine-grained Reactivity](./core-concepts/reactivity.md) — Signals, effects, memos — no virtual DOM needed
-- [AI-native Development](./core-concepts/ai-native.md) — Testable IR, CLI discovery, AI-assisted workflows
-- [How It Works](./core-concepts/how-it-works.md) — Two-phase compilation, hydration markers, clean overrides
+- [AI-native Development](./core-concepts/ai-native.md) — Testable IR, CLI discovery, agent skill (Claude Code / Codex), AI-assisted workflows
+- [How It Works](./core-concepts/how-it-works.mdx) — Two-phase compilation, hydration markers, clean overrides
 
 ### 4. [Reactivity](./reactivity.md)
 
@@ -31,6 +31,7 @@
 - [`onCleanup`](./reactivity/on-cleanup.md) — Register cleanup for effects and lifecycle
 - [`untrack`](./reactivity/untrack.md) — Read signals without tracking dependencies
 - [Props Reactivity](./reactivity/props-reactivity.md) — Gotchas with destructuring
+- [Shared State Patterns](./reactivity/shared-state.md) — Cross-file state sharing: consolidation, custom events, server props
 
 ### 5. [Templates & Rendering](./rendering.md)
 
@@ -40,7 +41,7 @@
 
 ### 6. [Components](./components.md)
 
-- [Component Authoring](./components/component-authoring.md) — Server components, client components, and the compilation model
+- [Component Authoring](./components/component-authoring.mdx) — Server components, client components, and the compilation model
 - [Props & Type Safety](./components/props-type-safety.md) — Typing props, defaults, and rest spreading
 - [Children & Slots](./components/children-slots.md) — Children prop, the `Slot` component, and the `asChild` pattern
 - [Context API](./components/context-api.md) — Sharing state with `createContext` / `useContext`
@@ -69,16 +70,10 @@ Code examples use **switchable tabs** for adapter output and package manager com
 
 **Adapter** — Hono (default) or Go Template:
 
-<!-- tabs:adapter -->
-- Hono (default)
-- Go Template
+<Tabs id="adapter" labels="Hono (default),Go Template" />
 
 **Package Manager** — npm (default), bun, pnpm, or yarn:
 
-<!-- tabs:pm -->
-- npm (default)
-- bun
-- pnpm
-- yarn
+<Tabs id="pm" labels="npm (default),bun,pnpm,yarn" />
 
 > Sections marked with 💡 explain JSX and TypeScript concepts for developers from Go, Python, or other backend languages.

package/dist/docs/core/components/{component-authoring.md → component-authoring.mdx}

@@ -40,7 +40,7 @@ export function Counter() {
 }
 ```
 
-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.
+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.mdx#two-phase-compilation) for details.
 
 ### When `"use client"` Is Required
 
@@ -92,8 +92,9 @@ export function Toggle() {
 
 **Marked template:**
 
-<!-- tabs:adapter -->
-<!-- tab:Hono -->
+<Tabs id="adapter" default="Hono">
+<Tab label="Hono" />
+
 ```tsx
 export function Toggle({ __instanceId, ... }) {
   const __scopeId = __instanceId || `Toggle_${...}`
@@ -107,7 +108,9 @@ export function Toggle({ __instanceId, ... }) {
   )
 }
 ```
-<!-- tab:Go Template -->
+
+<Tab label="Go Template" />
+
 ```go-template
 {{define "Toggle"}}
 <button bf-s="{{bfScopeAttr .}}" bf="s1">
@@ -116,7 +119,8 @@ export function Toggle({ __instanceId, ... }) {
 </button>
 {{end}}
 ```
-<!-- /tabs -->
+
+</Tabs>
 
 **Client JS:**
 

package/dist/docs/core/components/context-api.md

@@ -234,3 +234,10 @@ const theme = useContext(ThemeContext)
 ```
 
 Use for optional contexts with a sensible fallback.
+
+
+## Cross-File Context Does Not Work
+
+`createContext()` and all components that use it must be in the **same file**. Importing a context from another file does not work — the compiler does not currently support cross-file context sharing.
+
+This is why compound components (Accordion, Dialog, Select, Tabs) define all sub-components in a single file. For sharing state across components in separate files, see [Shared State Patterns](../reactivity/shared-state.md).

package/dist/docs/core/components.md

@@ -11,7 +11,7 @@ For the `"use client"` directive and the server/client boundary, see [Backend Fr
 
 | Topic | Description |
 |-------|-------------|
-| [Component Authoring](./components/component-authoring.md) | Server components, client components, and the compilation model |
+| [Component Authoring](./components/component-authoring.mdx) | Server components, client components, and the compilation model |
 | [Props & Type Safety](./components/props-type-safety.md) | Typing props, defaults, and rest spreading |
 | [Children & Slots](./components/children-slots.md) | Children prop, the `Slot` component, and the `asChild` pattern |
 | [Context API](./components/context-api.md) | Sharing state across compound components with `createContext` / `useContext` |

package/dist/docs/core/core-concepts/ai-native.md

@@ -66,6 +66,25 @@ When nothing in the registry fits, `bf gen component <name> <comps...>` scaffold
 
 **Visual preview**: hosted previews live at [ui.barefootjs.dev/components/&lt;name&gt;](https://ui.barefootjs.dev). Standalone `bf preview` for npm-installed projects is tracked in [#885](https://github.com/piconic-ai/barefootjs/issues/885).
 
+## Agent Skill
+
+BarefootJS publishes an agent skill that gives AI deep knowledge of the compiler, IR, CLI, and component system. Install it and the agent can build, test, and debug BarefootJS projects autonomously.
+
+**Claude Code:**
+
+```sh
+/plugin marketplace add piconic-ai/barefootjs
+/plugin install barefootjs@barefootjs
+```
+
+**Codex:**
+
+```
+install the barefootjs skill from piconic-ai/barefootjs
+```
+
+With the skill active, the agent understands `bf` CLI commands, IR test patterns, signal graphs, adapter output, and error codes — no manual prompting needed.
+
 ## Agent Loop
 
 The same workflow driven by an AI agent — say, "add a settings form":

package/dist/docs/core/core-concepts/{how-it-works.md → how-it-works.mdx}

@@ -51,8 +51,9 @@ The IR records:
 
 Marked template (Phase 2a):
 
-<!-- tabs:adapter -->
-<!-- tab:Hono -->
+<Tabs id="adapter" default="Hono">
+<Tab label="Hono" />
+
 ```tsx
 export function Counter({ __instanceId, ... }) {
   const __scopeId = __instanceId || `Counter_${Math.random().toString(36).slice(2, 8)}`
@@ -65,7 +66,9 @@ export function Counter({ __instanceId, ... }) {
   )
 }
 ```
-<!-- tab:Go Template -->
+
+<Tab label="Go Template" />
+
 ```go-template
 {{define "Counter"}}
 <button bf-s="{{bfScopeAttr .}}" bf="s1">
@@ -73,7 +76,8 @@ export function Counter({ __instanceId, ... }) {
 </button>
 {{end}}
 ```
-<!-- /tabs -->
+
+</Tabs>
 
 Client JS (Phase 2b):
 

package/dist/docs/core/{introduction.md → introduction.mdx}

@@ -28,8 +28,9 @@ export function Counter() {
 
 This single file compiles into two outputs:
 
-<!-- tabs:adapter -->
-<!-- tab:Hono -->
+<Tabs id="adapter" default="Hono">
+<Tab label="Hono" />
+
 **Marked template** — Renders static HTML with hydration markers:
 
 ```tsx
@@ -45,7 +46,8 @@ export function Counter({ __instanceId, ... }) {
 }
 ```
 
-<!-- tab:Go Template -->
+<Tab label="Go Template" />
+
 **Marked template** — Go `html/template` with hydration markers:
 
 ```go-template
@@ -56,7 +58,7 @@ export function Counter({ __instanceId, ... }) {
 {{end}}
 ```
 
-<!-- /tabs -->
+</Tabs>
 
 **Client script** — Wires up only the interactive parts:
 
@@ -84,4 +86,3 @@ hydrate('Counter', {
   template: (_p) => `<button bf="s1"> Count: <!--bf:s0-->${(0)}<!--/--></button>`
 })
 ```
-

package/dist/docs/core/llms.txt

@@ -18,6 +18,7 @@
 - [onCleanup](https://barefootjs.dev/docs/reactivity/on-cleanup.md): Registers a cleanup function that runs when the owning effect re-runs or the component is destroyed.
 - [onMount](https://barefootjs.dev/docs/reactivity/on-mount.md): Runs a callback once when the component initializes, without tracking signal dependencies.
 - [Props Reactivity](https://barefootjs.dev/docs/reactivity/props-reactivity.md): How prop access patterns determine whether reactive updates propagate in BarefootJS components.
+- [Shared State Patterns](https://barefootjs.dev/docs/reactivity/shared-state.md): Patterns for sharing reactive state between components in separate files, and when to use each.
 - [untrack](https://barefootjs.dev/docs/reactivity/untrack.md): Executes a function without tracking signal dependencies in the current reactive context.
 
 ## Rendering

package/dist/docs/core/quick-start.mdx

@@ -147,6 +147,7 @@ This runs `bf build`, generates the final `uno.css`, and calls `wrangler deploy`
 
 ## Next steps
 
+- **[Agent Skill](./core-concepts/ai-native.md#agent-skill)** — Install the BarefootJS skill for Claude Code or Codex and let the agent build components, write IR tests, and debug signals for you.
 - **[Core Concepts](./core-concepts.md)** — the four design principles behind BarefootJS: backend freedom, MPA-style rendering, fine-grained reactivity, and AI-native workflows.
 - **[`createSignal`](./reactivity/create-signal.md)** and **[`createMemo`](./reactivity/create-memo.md)** — the reactivity primitives you just used.
 - **[Client Directive](./rendering/client-directive.md)** — exactly what `"use client"` does and when to reach for it.

package/dist/docs/core/reactivity/shared-state.md

@@ -0,0 +1,233 @@
+---
+title: Shared State Patterns
+description: Patterns for sharing reactive state between components in separate files, and when to use each.
+---
+
+# Shared State Patterns
+
+The [Context API](../components/context-api.md) shares state between components in the **same file** (compound components like Accordion, Dialog, Tabs). But the compilation model — one `.tsx` file produces one `.client.js` bundle — means context **cannot cross file boundaries**.
+
+This guide covers patterns for sharing reactive state between components in **separate files**.
+
+
+## Why Context Doesn't Work Across Files
+
+Each `.client.js` bundle is independent. When the compiler processes two files that both reference the same `createContext()`, each bundle gets its own call — producing a unique `Symbol` id. The provider's context and the consumer's context are different objects:
+
+```
+PlaybackProvider.client.js  →  createContext()  →  Symbol(#1)
+Player.client.js            →  createContext()  →  Symbol(#2)
+                                                    ↑ different identity
+```
+
+`useContext` in Player walks the DOM looking for `Symbol(#2)`, but PlaybackProvider set `Symbol(#1)`. No match — the value is never found.
+
+
+## Pattern 1: Consolidate Into One File
+
+The simplest solution. If components are tightly coupled, put them in the same file:
+
+```tsx
+"use client"
+import { createContext, useContext, createSignal, createEffect } from '@barefootjs/client'
+
+interface PlaybackContextValue {
+  elapsedMs: () => number
+  playing: () => boolean
+  seek: (ms: number) => void
+  toggle: () => void
+}
+
+const PlaybackContext = createContext<PlaybackContextValue>()
+
+export function PlaybackProvider(props: { children?: unknown }) {
+  const [elapsedMs, setElapsedMs] = createSignal(0)
+  const [playing, setPlaying] = createSignal(false)
+
+  const seek = (ms: number) => setElapsedMs(ms)
+  const toggle = () => setPlaying(p => !p)
+
+  return (
+    <PlaybackContext.Provider value={{ elapsedMs, playing, seek, toggle }}>
+      {props.children}
+    </PlaybackContext.Provider>
+  )
+}
+
+export function Player(props: { children?: unknown }) {
+  const handleMount = (el: HTMLElement) => {
+    const ctx = useContext(PlaybackContext)
+    createEffect(() => {
+      el.textContent = `${Math.floor(ctx.elapsedMs() / 1000)}s`
+    })
+  }
+  return <div ref={handleMount}>{props.children}</div>
+}
+
+export function TimelineBar(props: { duration: number }) {
+  const handleMount = (el: HTMLElement) => {
+    const ctx = useContext(PlaybackContext)
+    el.addEventListener('click', (e) => {
+      const rect = el.getBoundingClientRect()
+      const ratio = (e.clientX - rect.left) / rect.width
+      ctx.seek(ratio * props.duration)
+    })
+  }
+  return <div ref={handleMount} className="timeline" />
+}
+```
+
+**When to use:** Components share a tight contract and are always used together (like Select + SelectTrigger + SelectContent).
+
+| Pros | Cons |
+|------|------|
+| Full reactivity via signals | All components in one file |
+| Type-safe | File grows with component count |
+| Works with Context API | Not suitable for loosely coupled components |
+
+
+## Pattern 2: Custom DOM Events
+
+Use the browser's native event system. One component dispatches events, others listen. No shared module state needed.
+
+Player (`components/Player.tsx`):
+
+```tsx
+"use client"
+import { createSignal, createEffect, onCleanup } from '@barefootjs/client'
+
+export function Player() {
+  const [elapsedMs, setElapsedMs] = createSignal(0)
+
+  const handleMount = (el: HTMLElement) => {
+    createEffect(() => {
+      el.dispatchEvent(new CustomEvent('playback:timeupdate', {
+        bubbles: true,
+        detail: { elapsedMs: elapsedMs() },
+      }))
+    })
+
+    const onSeek = ((e: CustomEvent) => {
+      setElapsedMs(e.detail.ms)
+    }) as EventListener
+
+    document.addEventListener('playback:seek', onSeek)
+    onCleanup(() => document.removeEventListener('playback:seek', onSeek))
+  }
+
+  return <div ref={handleMount} />
+}
+```
+
+TimelineBar (`components/TimelineBar.tsx`):
+
+```tsx
+"use client"
+import { onCleanup } from '@barefootjs/client'
+
+export function TimelineBar(props: { duration: number }) {
+  const handleMount = (el: HTMLElement) => {
+    const onTimeUpdate = ((e: CustomEvent) => {
+      const ratio = e.detail.elapsedMs / props.duration
+      el.style.setProperty('--progress', String(ratio))
+    }) as EventListener
+
+    document.addEventListener('playback:timeupdate', onTimeUpdate)
+    onCleanup(() => document.removeEventListener('playback:timeupdate', onTimeUpdate))
+
+    el.addEventListener('click', (e) => {
+      const rect = el.getBoundingClientRect()
+      const ratio = (e.clientX - rect.left) / rect.width
+      el.dispatchEvent(new CustomEvent('playback:seek', {
+        bubbles: true,
+        detail: { ms: ratio * props.duration },
+      }))
+    })
+  }
+
+  return <div ref={handleMount} className="timeline" />
+}
+```
+
+**When to use:** Components are in separate files and communicate through a shared parent in the DOM.
+
+| Pros | Cons |
+|------|------|
+| Works across any file boundary | Not reactive — imperative dispatch/listen |
+| No shared imports needed | No type safety on event payloads (use a shared type file to mitigate) |
+| Familiar browser API | Requires manual cleanup |
+| SSR-safe (listeners only run on client) | Event naming conventions needed |
+
+### Type-safe event helpers
+
+Define event types in a shared `src/` file to get type safety without sharing runtime state:
+
+```ts
+export interface PlaybackTimeUpdateDetail {
+  elapsedMs: number
+}
+
+export interface PlaybackSeekDetail {
+  ms: number
+}
+
+export function dispatchTimeUpdate(el: Element, detail: PlaybackTimeUpdateDetail) {
+  el.dispatchEvent(new CustomEvent('playback:timeupdate', { bubbles: true, detail }))
+}
+
+export function dispatchSeek(el: Element, detail: PlaybackSeekDetail) {
+  el.dispatchEvent(new CustomEvent('playback:seek', { bubbles: true, detail }))
+}
+```
+
+`src/` utility files are inlined at compile time. Type definitions and `CustomEvent` constructors don't carry mutable state, so inlining is safe — each bundle gets its own copy of the helper functions, but they produce identical events.
+
+
+## Pattern 3: Server-Mediated Props
+
+For state that originates on the server (database, session, URL params), pass it as props from the server route. No client-side sharing needed:
+
+```tsx
+import { Player } from '@/components/Player'
+import { TimelineBar } from '@/components/TimelineBar'
+
+app.get('/player/:id', async (c) => {
+  const track = await db.getTrack(c.req.param('id'))
+  return c.render(
+    <main>
+      <Player trackId={track.id} initialPosition={track.lastPosition} />
+      <TimelineBar duration={track.durationMs} />
+    </main>
+  )
+})
+```
+
+Each component hydrates independently with its own signals. User interactions that need to cross components use Pattern 2 (custom events).
+
+**When to use:** Initial state comes from the server; components only need to sync on user-driven actions.
+
+| Pros | Cons |
+|------|------|
+| SSR-friendly — state is in HTML | Real-time sync still needs custom events |
+| No shared client state | Server round-trip for state changes |
+| Each component is independently testable | |
+
+
+## Choosing a Pattern
+
+```
+Is all state server-derived?
+  └─ Yes → Pattern 3 (Server-Mediated Props)
+  └─ No
+      ├─ Are components tightly coupled (always used together)?
+      │   └─ Yes → Pattern 1 (Consolidate Into One File)
+      └─ No → Pattern 2 (Custom DOM Events)
+```
+
+| | Context (same file) | Consolidate | Custom Events | Server Props |
+|---|---|---|---|---|
+| Cross-file | No | No (one file) | Yes | Yes |
+| Reactive | Yes | Yes | No | No (initial only) |
+| Type-safe | Yes | Yes | With helpers | Yes |
+| SSR-safe | Yes | Yes | Yes | Yes |
+| Testable | IR test | IR test | E2E | IR test + E2E |

package/dist/docs/core/reactivity.md

@@ -26,3 +26,4 @@ import { createSignal, createEffect, createMemo, onMount, onCleanup, untrack } f
 ## Guides
 
 - [Props Reactivity](./reactivity/props-reactivity.md) — How props stay reactive, and when destructuring breaks it
+- [Shared State Patterns](./reactivity/shared-state.md) — Sharing state across components in separate files