@barefootjs/cli 0.1.0

package/dist/docs/core/README.md

@@ -0,0 +1,84 @@
+# BarefootJS Documentation
+
+## Table of Contents
+
+### 1. [Introduction](./introduction.md)
+
+- What is BarefootJS?
+- Why BarefootJS?
+- Design Philosophy
+
+### 2. [Quick Start](./quick-start.mdx)
+
+- Scaffold an app with `npm create barefootjs@latest`
+- Run the dev server and edit the starter Counter
+- Tour of the generated project structure
+
+### 3. [Core Concepts](./core-concepts.md)
+
+- [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
+
+### 4. [Reactivity](./reactivity.md)
+
+- [`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
+- [Props Reactivity](./reactivity/props-reactivity.md) — Gotchas with destructuring
+
+### 5. [Templates & Rendering](./rendering.md)
+
+- [JSX Compatibility](./rendering/jsx-compatibility.md) — What works, what doesn't, and what differs
+- [Fragment](./rendering/fragment.md) — Fragment support and hydration behavior
+- [`/* @client */` Directive](./rendering/client-directive.md) — Skip server evaluation for client-only expressions
+
+### 6. [Components](./components.md)
+
+- [Component Authoring](./components/component-authoring.md) — 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`
+- [Portals](./components/portals.md) — Rendering elements outside their parent DOM hierarchy
+
+### 7. [Adapters](./adapters.md)
+
+- [Adapter Architecture](./adapters/adapter-architecture.md) — How adapters work, the `TemplateAdapter` interface, and the IR contract
+- [Hono Adapter](./adapters/hono-adapter.md) — Configuration and output format for Hono / JSX-based servers
+- [Go Template Adapter](./adapters/go-template-adapter.md) — Configuration and output format for Go `html/template`
+- [CSR (Client-Side Rendering)](./adapters/csr.md) — Static-hosting renderer: emit client JS only, no SSR template
+- [Writing a Custom Adapter](./adapters/custom-adapter.md) — Step-by-step guide to implementing your own adapter
+
+### 8. [Advanced](./advanced.md)
+
+- [IR Schema Reference](./advanced/ir-schema.md) — Node types, metadata, hydration markers
+- [Compiler Internals](./advanced/compiler-internals.md) — Pipeline phases, reactivity analysis, code generation
+- [Error Codes Reference](./advanced/error-codes.md) — All BF001–BF043 errors with solutions
+- [Performance Optimization](./advanced/performance.md) — Minimal client JS, fast hydration, efficient reactivity
+
+---
+
+## Documentation Conventions
+
+Code examples use **switchable tabs** for adapter output and package manager commands. Preferences persist across pages.
+
+**Adapter** — Hono (default) or Go Template:
+
+<!-- tabs:adapter -->
+- Hono (default)
+- Go Template
+
+**Package Manager** — npm (default), bun, pnpm, or yarn:
+
+<!-- tabs:pm -->
+- 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/adapters/adapter-architecture.md

@@ -0,0 +1,262 @@
+---
+title: Adapter Architecture
+description: How adapters convert the compiler's IR into server-renderable template formats.
+---
+
+# Adapter Architecture
+
+An adapter converts the compiler's IR into a template format your server can render.
+
+
+## Role
+
+1. **Phase 1** parses JSX → backend-agnostic `ComponentIR` (JSON tree)
+2. **Phase 2a** adapter converts IR → marked template in target language
+3. **Phase 2b** generates client JS from IR (no adapter involved)
+
+```
+ComponentIR (JSON)
+    ↓
+┌───────────────────────────────┐
+│         TemplateAdapter       │
+│                               │
+│  renderElement()              │
+│  renderExpression()           │
+│  renderConditional()          │
+│  renderLoop()                 │
+│  renderComponent()            │
+│  ...                          │
+└───────────────────────────────┘
+    ↓
+Marked Template + optional types
+```
+
+Each IR node is translated into the target template language with hydration markers (`bf-*` attributes).
+
+
+## `TemplateAdapter` Interface
+
+```typescript
+interface TemplateAdapter {
+  name: string       // Adapter identifier (e.g., 'hono', 'go-template')
+  extension: string  // Output file extension (e.g., '.tsx', '.tmpl')
+
+  // Main entry point
+  generate(ir: ComponentIR, options?: AdapterGenerateOptions): AdapterOutput
+
+  // Node rendering — one method per IR node type
+  renderNode(node: IRNode): string
+  renderElement(element: IRElement): string
+  renderExpression(expr: IRExpression): string
+  renderConditional(cond: IRConditional): string
+  renderLoop(loop: IRLoop): string
+  renderComponent(comp: IRComponent): string
+
+  // Hydration markers
+  renderScopeMarker(instanceIdExpr: string): string
+  renderSlotMarker(slotId: string): string
+  renderCondMarker(condId: string): string
+
+  // Optional: type generation for typed languages
+  generateTypes?(ir: ComponentIR): string | null
+}
+```
+
+### `generate()`
+
+```typescript
+interface AdapterOutput {
+  template: string     // The generated template code
+  types?: string       // Optional generated types (Go structs, etc.)
+  extension: string    // File extension for the output
+}
+```
+
+### `AdapterGenerateOptions`
+
+```typescript
+interface AdapterGenerateOptions {
+  skipScriptRegistration?: boolean  // For child components bundled in parent
+  scriptBaseName?: string           // For non-default exports sharing a parent's client JS
+}
+```
+
+### Node rendering methods
+
+| Method | IR Node | Responsibility |
+|--------|---------|----------------|
+| `renderElement()` | `IRElement` | HTML elements with attributes, events, and hydration markers |
+| `renderExpression()` | `IRExpression` | Dynamic expressions (e.g., `{count()}`, `{props.name}`) |
+| `renderConditional()` | `IRConditional` | Ternaries and `&&`/`||` expressions |
+| `renderLoop()` | `IRLoop` | `.map()`, `.filter().map()`, `.sort().map()` chains |
+| `renderComponent()` | `IRComponent` | Nested component invocations |
+| `renderNode()` | `IRNode` | Dispatcher — routes to the correct method based on node type |
+
+### Hydration marker methods
+
+| Method | Marker | Purpose |
+|--------|--------|---------|
+| `renderScopeMarker()` | `bf-s` | Component boundary for scoped hydration |
+| `renderSlotMarker()` | `bf` | Interactive element identifier |
+| `renderCondMarker()` | `bf-c` | Conditional block for DOM switching |
+
+
+## `BaseAdapter` Class
+
+`BaseAdapter` implements the `TemplateAdapter` interface with a `renderChildren()` utility:
+
+```typescript
+abstract class BaseAdapter implements TemplateAdapter {
+  abstract name: string
+  abstract extension: string
+
+  // ... all abstract methods from TemplateAdapter
+
+  renderChildren(children: IRNode[]): string {
+    return children.map(child => this.renderNode(child)).join('')
+  }
+}
+```
+
+Extending `BaseAdapter` is optional.
+
+
+## IR Node Types
+
+Each adapter must handle all IR node types:
+
+### `IRElement`
+
+An HTML element with attributes, events, and children.
+
+```typescript
+{
+  type: 'element'
+  tag: string              // 'div', 'button', 'input', etc.
+  attrs: IRAttribute[]     // Static and dynamic attributes
+  events: IREvent[]        // Event handlers (onClick, onChange, etc.)
+  children: IRNode[]       // Child nodes
+  slotId: string | null    // Hydration slot ID (e.g., 's0')
+  needsScope: boolean      // True if this is the component root
+}
+```
+
+### `IRExpression`
+
+A dynamic expression in the template.
+
+```typescript
+{
+  type: 'expression'
+  expr: string             // The JS expression (e.g., 'count()', 'props.name')
+  reactive: boolean        // True if the expression depends on signals
+  slotId: string | null    // Slot ID for client updates
+  clientOnly?: boolean     // True if wrapped in /* @client */
+}
+```
+
+### `IRConditional`
+
+A ternary or logical expression that produces different output.
+
+```typescript
+{
+  type: 'conditional'
+  condition: string        // The JS condition
+  whenTrue: IRNode         // Rendered when condition is true
+  whenFalse: IRNode        // Rendered when condition is false
+  reactive: boolean        // True if the condition depends on signals
+  slotId: string | null    // Slot ID for DOM switching
+}
+```
+
+### `IRLoop`
+
+An array iteration (`.map()`, optionally chained with `.filter()` or `.sort()`).
+
+```typescript
+{
+  type: 'loop'
+  array: string            // The array expression
+  param: string            // Iterator parameter name
+  index: string | null     // Index parameter name
+  children: IRNode[]       // Loop body
+  isStaticArray: boolean   // True if iterating a prop (not a signal)
+  filterPredicate?: {...}  // For .filter().map() chains
+  sortComparator?: {...}   // For .sort().map() chains
+}
+```
+
+### `IRComponent`
+
+A nested component invocation.
+
+```typescript
+{
+  type: 'component'
+  name: string             // Component name (e.g., 'TodoItem')
+  props: IRProp[]          // Props passed to the component
+  children: IRNode[]       // Children (slots)
+  slotId: string | null    // Slot ID if parent binds event handlers
+}
+```
+
+### Other node types
+
+| Type | Description |
+|------|-------------|
+| `IRText` | Static text content |
+| `IRFragment` | Fragment (`<>...</>`) wrapper |
+| `IRSlot` | `{children}` or `<Slot />` placeholder |
+| `IRIfStatement` | Top-level if/else if/else blocks |
+| `IRProvider` | Context provider wrapper |
+| `IRTemplateLiteral` | Template literal expressions |
+
+
+## Hydration Markers
+
+`bf-*` attributes tell the client JS where to attach behavior:
+
+| Marker | Example | Purpose |
+|--------|---------|---------|
+| `bf-s` | `<div bf-s="Counter_a1b2">` | Component boundary — scopes all queries inside |
+| `bf` | `<p bf="s0">` | Interactive element — target for effects and event handlers |
+| `bf-c` | `<div bf-c="s2">` | Conditional block — target for DOM switching |
+
+
+
+## Script Registration
+
+Adapters register client JS during server rendering to ensure each script loads exactly once:
+
+- **Hono**: `useRequestContext()` collects script paths; `BfScripts` renders the `<script>` tags.
+- **Go Template**: `ScriptCollector` tracks needed scripts; renders `<script>` tags at page end.
+
+
+## Type Generation
+
+For typed backends, `generateTypes()` produces type definitions alongside the template. The Go Template adapter generates:
+
+- **Go structs** for component input and props types
+- **JSON tags** for prop serialization
+- **Constructor functions** like `New{Component}Props()` with default values
+
+```go
+// Generated by GoTemplateAdapter
+type CounterInput struct {
+    Initial int `json:"initial"`
+}
+
+type CounterProps struct {
+    Initial  int    `json:"initial"`
+    ScopeID  string `json:"scopeId"`
+}
+
+func NewCounterProps(input CounterInput) CounterProps {
+    return CounterProps{
+        Initial: input.Initial,
+    }
+}
+```
+
+Dynamically-typed adapters (like Hono) skip this.

package/dist/docs/core/adapters/csr.md

@@ -0,0 +1,78 @@
+---
+title: CSR (Client-Side Rendering)
+description: Render BarefootJS components directly in the browser without a server-rendered template.
+---
+
+# CSR (Client-Side Rendering)
+
+CSR renders BarefootJS components directly in the browser, without any server-rendered initial HTML. Use it when the server can't (or shouldn't) emit the initial markup.
+
+Unlike the other entries in this section, CSR is not an IR→template adapter. It reuses the client-side template function that the compiler generates for each component, and mounts the resulting DOM into a container you pick.
+
+## When to use CSR
+
+Typical case: **static file hosting**. You have an HTML file you drop onto S3, GitHub Pages, or any static CDN — no backend renders the page. CSR lets you add interactive BarefootJS components to that page without setting up a server template.
+
+When you do control the server (Hono, Go, etc.), prefer SSR + hydration instead. It renders faster to first paint and works without JavaScript enabled for static parts.
+
+## Configuration
+
+Use `createConfig` from `@barefootjs/client/build` in `barefoot.config.ts`. It wires the in-package `CSRAdapter` and skips marked template output automatically — no `clientOnly` flag is needed:
+
+```typescript
+// barefoot.config.ts
+import { createConfig } from '@barefootjs/client/build'
+
+export default createConfig({
+  components: ['./components'],
+  outDir: 'dist',
+})
+```
+
+Build output:
+
+```
+dist/
+└── components/
+    ├── barefoot.js        # client runtime bundle
+    └── Counter.client.js  # compiled component
+```
+
+## API
+
+```typescript
+import { render } from '@barefootjs/client/runtime'
+
+render(container, componentName, props?)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `container` | `HTMLElement` | Target element. Its content is replaced. |
+| `componentName` | `string` | Registered component name (same as the exported JSX function). |
+| `props` | `Record<string, unknown>` | Optional props passed to the component. |
+
+The component must be registered first by importing its `.client.js` file — that import triggers the compiler-generated `registerComponent` / `registerTemplate` calls.
+
+## Example
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <script type="importmap">
+    { "imports": { "@barefootjs/client/runtime": "/static/components/barefoot.js" } }
+  </script>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module">
+    import { render } from '@barefootjs/client/runtime'
+    await import('/static/components/Counter.client.js')
+    render(document.getElementById('app'), 'Counter', { initialCount: 0 })
+  </script>
+</body>
+</html>
+```
+
+See [`integrations/csr/`](https://github.com/piconic-ai/barefootjs/tree/main/integrations/csr) for a runnable end-to-end example.