# aihu — Full Documentation

> A zero-dependency Web Components meta-framework. .aihu SFCs compile to vanilla custom elements
> with sub-2 kB reactive primitives. Every component is agent-discoverable and callable as an MCP tool.

> Source: https://aihu.dev | GitHub: https://github.com/fellwork/aihu

---

# Introduction

aihu builds **durable Web Components your AI agent can read and drive — not disposable UI it has to generate.** You author `.aihu` Single-File Components (block-structured: `@state`, `@template`, `@style`, `@agent`, `@route`); a Rust compiler emits standards-compliant Web Components **plus** the machine-readable agent manifest. An agent inspects a real component (llms.txt + MCP) and calls its actions on the live, on-screen instance over a server-mediated capability bridge — the component the user sees is the one the agent drives. Most "agent UI" today is the opposite: disposable HTML/JSON the model regenerates each turn (MCP Apps, generated iframes). Durable components are inspectable, reusable, and trusted, with the server holding auth and policy.

> **Status:** actively developed and shipping in `v1.0.x` releases. The reactive runtime, compiler, router, server, agent surface, CLI, styling engine, and UI primitives all work today; the `v1.0.0` tag is held for a rich-text/markdown plugin.

## What makes aihu different

- **Read and drive, not generate** — an agent inspects a real component and calls its actions on the live, on-screen instance over a server-mediated capability bridge. The component the user sees is the one driven, not disposable UI regenerated each turn (the generative-UI model: MCP Apps, generated iframes). Durable, inspectable, reusable.
- **Agent-native by construction** — the `@agent` block on each SFC declares its exposed state and actions; the compiler emits a matching MCP tool schema + llms.txt entry alongside the Web Component. No separate API gateway. `@aihu/agent` and `@aihu-plugin/agent-readiness` are first-class.
- **Vanilla custom elements output** — no framework lock-in at the consumer boundary, no global context, no hydration step.
- **Sub-2 kB runtime** — `@aihu/signals` (~1.71 kB gz) and `@aihu/arbor` (~2.72 kB gz) together cover signals, computeds, effects, and direct DOM diffing.
- **Dep-free** — zero non-`@aihu/*` runtime dependencies across all packages. Every bundle that ships to a browser or edge runtime is self-contained.
- **Targeted updates** — aihu uses `nodeValue` rather than `textContent` for reactive text nodes, which is 122× faster on targeted updates.

## Why "meta-framework"?

Aihu lets you build whole apps, not just components. `@aihu/signals` (reactive primitive) → `@aihu/arbor` (DOM mounting) → `@aihu/runtime` (custom-element wiring) → `@aihu/router` (file-based routing) → `@aihu/server` (SSR + edge) → `@aihu/app` (the integrated framework). Each layer is usable on its own; stacked they form a complete meta-framework. File-based routing, SSR, loaders, cookies, auth, and data are first-class — not bolt-ons. Cloud adapters are in-tree, not third-party.

## Package overview

| Package | Purpose | Bundle |
|---------|---------|--------|
| `@aihu/signals` | Push-based signals, computeds, effects | 1.71 kB gz |
| `@aihu/arbor` | DOM tree primitives: branch/leaf/mount/hydrate | 2.72 kB gz |
| `@aihu/runtime` | Custom element registration, onMount/onCleanup lifecycle | 3.27 kB gz |
| `@aihu/context` | Async-context-friendly request/SSR context primitives | 248 B gz |
| `@aihu/agent` | Agent/MCP registration primitives | 142 B gz |
| `@aihu/agent-service` | Server-side agent runtime (live signal bindings) | 1.06 kB gz |
| `@aihu/agent-a2a` | A2A (Agent-to-Agent) protocol bindings | 721 B gz |
| `@aihu/agent-acp` | ACP (Agent Control Protocol) bindings | 591 B gz |
| `@aihu-plugin/agent-readiness` | llms.txt, MCP Server Card, robots.txt emitter | build-time |
| `@aihu-plugin/data` | Reactive resource and loader protocol | 774 B gz |
| `@aihu/router` | File-based router with Vite plugin | 2.02 kB gz |
| `@aihu/server` | Request router, SSR, streaming, loaders, cookies | server-only |
| `@aihu/app` | Top-level integration — wires runtime, router, adapters | 764 B gz |
| `@aihu/plugin` | Plugin contract types shared by server and meta-framework | build-time |
| `@aihu/auth` | JWT scope checks, ScopeSignal, server middleware | server-only |
| `@aihu/adapter-cloudflare` | Cloudflare Workers/Pages deployment adapter | build-time |
| `@aihu/adapter-vercel` | Vercel deployment adapter (Edge + Serverless) | build-time |
| `@aihu/cli` | Scaffold CLI — `aihu app`, `page`, `component`, `dev`, `build` | build-time |
| `@aihu/compiler` | Rust SFC compiler — per-platform binary + WASM | build-time |
| `@aihu/css-engine` | CSS engine — Tailwind v4 hard fork, WC-native scoped output, `cn()` + style packs | build-time + tiny runtime |
| `@aihu/primitives` | Headless WAI-ARIA APG behaviors (dialog, tooltip, button, …) as vanilla custom elements, zero CSS | runtime |
| `@aihu/mcp` | MCP server exposing `aihu_example` + `aihu_validate` tools | server-only |
| `@aihu/scraping` | Rate limiter and bot-detection middleware for agent services | server-only |
| `vscode-aihu` | VSCode syntax highlighting, snippets, language support | editor |

---

# Installation

## Prerequisites

aihu requires **one** of the following runtimes:

- **Bun** ≥1.3.0 (recommended — faster installs, native TypeScript, built-in test runner)
- **Node.js** ≥20.18.0 with a package manager of your choice (npm, pnpm, or yarn)

## Scaffold a new application

Use the `@aihu/cli` to generate a new project:

```bash
# Bun (recommended)
bunx @aihu/cli app my-app

# Node.js
npx @aihu/cli app my-app
```

> **Note (TODO-001):** The ≤5 minute quick start is conditional until pre-built
> `aihu-compile` binaries ship. Today the scaffolder builds the Rust SFC compiler
> from source on first run, which adds a one-time toolchain step. Once the
> [GitHub Actions release workflow](https://github.com/fellwork/aihu/blob/main/.github/workflows/release.yml)
> publishes platform binaries, the install becomes a single download and this
> note will be removed.

The scaffolder generates the following files:

```
my-app/
  package.json
  aihu.config.ts
  vite.config.ts
  src/
    pages/
      index.aihu
    layouts/
      default.aihu
```

- **`package.json`** — workspace manifest with `@aihu/runtime`, `@aihu/signals`, `@aihu/arbor`, `@aihu/router`, `@aihu/server`, and `@aihu/agent` as dependencies, plus Vite and `@aihu/cli` as devDependencies.
- **`aihu.config.ts`** — framework config via `defineAihuConfig` (build target, plugins, adapters).
- **`vite.config.ts`** — Vite config with `viteRouterIntegration()` and `viteAgentReadinessIntegration()` wired in.
- **`src/pages/index.aihu`** — the Hello World SFC with `@state`, `@template`, and `@route` blocks.
- **`src/layouts/default.aihu`** — the default layout shell (`<slot />`).

## Install and run

```bash
cd my-app
bun install
bun run dev
```

The dev server starts at `http://localhost:5173` with HMR enabled. Edit `src/pages/index.aihu` and the browser updates automatically — no full reload needed.

## Build for production

```bash
bun run build
bun run preview
```

`bun run build` compiles all `.aihu` files through the Rust SFC compiler, bundles with Vite/Rolldown, and validates against the size budgets defined in `.size-limit.json`.

`bun run preview` serves the production build locally so you can verify the output before deploying.

---

# Getting Started

## Hello World walkthrough

After scaffolding (see [Installation](installation.md)), open `src/pages/index.aihu`. The scaffolded template uses the v2 macro vocabulary:

```
@state {
  $prop: {
    name: { default: 'world', type: 'string' }
  }
}

@template {
  <div>Hello {name}</div>
}

@route {
  path: /
  name: home
}
```

### The `@state` block

`@state` declares the reactive state for the component using the v2 collection-form macro vocabulary. Each macro keyword takes an object whose keys are entry names.

**Props** — declared with `$prop`. Every entry must have at least a `default` or `type` key:

```
@state {
  $prop: {
    name: { default: 'world', type: 'string' }
  }
}
```

Props are reactive and can be set from outside the component as HTML attributes. Add `expose: { read: true, write: true }` to expose a prop to the agent surface.

**Computed values** — declared with `$computed`. The bare form uses a thunk:

```
@state {
  $prop: {
    name: { default: 'world', type: 'string' }
  }

  $computed: {
    greeting: () => `Hello, ${name()}!`
  }
}
```

**Actions** — declared with `$action`. Bare form is a handler function; the wrapped form adds `describe` and `expose` metadata:

```
@state {
  import { signal } from '@aihu/signals'
  const [count, setCount] = signal(0)

  $action: {
    increment: {
      describe: 'Add 1 to the counter',
      expose: { read: true, write: true },
      handler: () => setCount(count() + 1),
    },
  }
}
```

**Effects** — anonymous effects use the bare function form:

```
@state {
  $effect: () => { console.log('count changed') }
}
```

Named effects (with optional dependency pinning) use the collection form:

```
@state {
  $effect: {
    logCount: () => { console.log(count()) },
  }
}
```

### The `@template` block

`@template` defines the component's DOM structure using aihu's template DSL:

- `{expr}` — interpolates a reactive expression. Updates use `nodeValue` for 122× faster targeted writes.
- `$href={expr}` — binds an HTML attribute reactively (`$`-prefixed curly; one per attribute).
- `$on.click="handler"` — attaches an event listener.
- `$show` — toggles visibility based on a boolean signal.
- `$each` — renders a list of items.

> **Amendment 04 (v1.0.8).** Reactive HTML attribute bindings must be `$`-prefixed (`$class={…}`, `$href={…}`). Plain-curly attributes (`class={…}`, error **C306**), the colon-form event/bind aliases (**C305**), and the Vue-shape `:attr=` alias (**C304**) are hard parse errors in v1.0. HTML-tag SFC framing (`<template>`, `<script setup>`) is rejected as **C107**. Run `npx aihu migrate <file>` to upgrade older sources.

### The `@agent` block

`@agent` declares the component's cross-cutting agent metadata. In v2, per-property `describe` and `expose` keys live on the `@state` entries directly. The `@agent` block holds only scope and rate-limit constraints:

```
@agent {
  $scope 'counter'
  $rate-limit 60
}
```

### The `@route` block

`@route` registers the component as a page route:

```
@route {
  path: /
  name: home
}
```

During build, the Rust compiler emits a `.route.json` sidecar alongside each compiled SFC. `viteRouterIntegration()` in `vite.config.ts` reads these sidecars at build time and assembles the route manifest into `virtual:aihu-routes` — route manifests are fully static after build with no filesystem scanning at runtime.

### HMR in development

Edit `src/pages/index.aihu` and the browser updates live — no full reload. Vite watches `.aihu` files; when you save, only the affected reactive subtree is re-evaluated.

## A complete example: live counter

The canonical minimal SFC (from `examples/live-counter/live-counter.aihu`):

```
@state {
  import { signal } from '@aihu/signals'
  const [count, setCount] = signal(0)

  $action: {
    increment: {
      describe: 'Add 1 to the counter',
      expose: { read: true, write: true },
      handler: () => setCount(count() + 1),
    },
    decrement: {
      describe: 'Subtract 1 from the counter',
      expose: { read: true, write: true },
      handler: () => setCount(count() - 1),
    },
    reset: {
      describe: 'Reset the counter to 0',
      expose: { read: true, write: true },
      handler: () => setCount(0),
    },
  }
}

@template {
  <section class="counter">
    <h1>Count: {count}</h1>
    <div class="controls">
      <button $on.click="decrement">-</button>
      <button $on.click="reset">Reset</button>
      <button $on.click="increment">+</button>
    </div>
  </section>
}

@style {
  .counter { display: grid; gap: 0.75rem; padding: 1.5rem; }
  button   { flex: 1; padding: 0.5rem 0.75rem; cursor: pointer; }
}
```

This is ~40 LOC, has an agent surface (all three actions are agent-callable), and uses only signals from `@aihu/signals` directly in `@state`.

## Next steps

- [Authoring Components](authoring-components.md) — full reference for `@state`, `@template`, `@style`, and `@agent` blocks.
- [Reactivity](reactivity.md) — the `signal`, `computed`, and `effect` primitives from `@aihu/signals`.
- [Authoring Agents](authoring-agents.md) — how to expose component state and actions to AI agents via MCP.

---

# Authoring Components

A `.aihu` Single File Component (SFC) is composed of named blocks. Each block uses the `@blockname { ... }` syntax.

## @state block

The `@state` block declares the reactive contract of the component. All macros use the **v2 collection-form**: each macro keyword appears at most once per `@state` block and takes a single object whose keys are entry names.

### Macros

**`$prop`** — a public, reactive property settable from HTML attributes. Always wrapped (bare form forbidden).

```
$prop: {
  name: {
    default: value,
    type?: "TypeAnnotation",   // required when default can't carry the TS type
    describe?: "human-readable description",
    expose?: { read?: true, write?: true }
  }
}
```

Use `expose: { read: true }` to expose the prop value to agents. Add `write: true` to also allow agents to set it.

---

**`$computed`** — a derived, read-only signal. Re-evaluates when dependencies change. Supports bare (no metadata) or wrapped (with metadata) form.

```
$computed: {
  // bare — value-thunk, no metadata
  name: () => expr,
  // wrapped — add describe/expose
  namedWithMeta: { value: () => expr, describe?: "...", expose?: { read?: true } }
}
```

The `type:` key is not valid for `$computed`. Annotate the thunk's return type inline when needed: `value: (): T[] => []`.

---

**`$action`** — a named method on the component. Bare (no metadata) or wrapped.

```
$action: {
  // bare handler
  doSomething: (args) => { /* body */ },
  // wrapped — add describe/expose to surface to agents
  doSomethingExposed: {
    handler: (args) => { /* body */ },
    describe?: "human-readable description",
    expose?: { read?: true, write?: true }
  }
}
```

---

**`$effect`** — runs a side effect when tracked signals change. Two valid forms per `@state` block:

```
// anonymous — macro keyword takes a single function directly
$effect: () => { /* side effect body */ }

// named collection — auto-tracks deps (bare) or explicit deps (wrapped)
$effect: {
  logData: () => { console.log(data()) },                        // bare — auto-tracks
  updateList: { on: [data], value: () => { updateList(data()) } } // wrapped — explicit deps
}
```

Both forms may coexist in the same `@state` block. Two anonymous `$effect:` lines in one block is a parse error.

---

**`$resource`** — binds an async fetcher to a reactive signal. Returns a 3-state loader: `{ pending, value, error }`. Bare or wrapped.

```
$resource: {
  // bare fetcher-thunk
  data: () => fetchUsers(),
  // wrapped — add describe/expose
  user: { value: () => fetchUser(userId), describe?: "...", expose?: { read?: true } }
}
```

---

**`$lifecycle`** — lifecycle hooks. Always bare functions; wrapped form is forbidden.

```
$lifecycle: {
  mount:   () => { /* runs after first DOM mount */ },
  dispose: () => { /* runs on unmount */ }
}
```

Only `mount` and `dispose` are valid keys. `describe`, `expose`, `value`, and `handler` are forbidden on lifecycle entries.

### Complete example

```
@state {
  $prop: {
    count: { default: 0, describe: 'Current counter value', expose: { read: true } }
  }

  $computed: {
    doubled: () => count * 2,
    isHigh: { value: () => count > 100, describe: 'True when count exceeds 100', expose: { read: true } }
  }

  $action: {
    increment: {
      describe: 'Add 1 to the counter',
      expose: { read: true, write: true },
      handler: () => { count++ }
    },
    reset: () => { count = 0 }
  }

  $lifecycle: {
    mount:   () => console.log('mounted'),
    dispose: () => console.log('unmounted')
  }

  $effect: () => { document.title = `Count: ${count}` }
}
```

### `describe:` and `expose:` — agent visibility

`describe:` and `expose:` are per-name keys on `$prop`, `$computed`, `$action`, and `$resource` entries. They replace the old `@agent`-level `$expose` and `$describe` macros (which are C440 errors in v2).

- `describe: "text"` — makes the entry visible in the agent's capability description.
- `expose: { read: true }` — the agent can read this value.
- `expose: { read: true, write: true }` — the agent can read and write this value (props, actions).

## @template block

The `@template` block defines the DOM output using aihu's template DSL.

> **Amendment 04 (v1.0.8) — `$`-prefixed reactive bindings.** Every reactive HTML attribute binding is `$`-prefixed: `$class={…}`, `$href={…}`, `$on.click=…`, `$bind.value=…`. The legacy colon-form event/bind aliases (`$on` + colon + event, error **C305**), the Vue-shape `:attr=` alias (**C304**), and plain-curly attribute bindings (`class={…}` without `$`, **C306**) are hard parse errors in v1.0. Component prop-passing (`<UserCard user={u} />`) keeps the plain-curly form and is unaffected. Run `npx aihu migrate <file>` to mechanically rewrite pre-v1.0.8 sources.

### Text interpolation

- `{expr}` — reactive text node. Uses `nodeValue` for targeted updates (122x faster than `textContent` on targeted nodes).

### Event handlers

- `$on.click="handlerName"` — attach an event listener (quoted identifier reference).
- `$on.click={() => expr}` — attach an inline handler (curly expression).

A dot separates the directive from the event name: `$on.<event>`.

### Two-way binding

- `$bind.value="signalName"` — two-way bind a writable signal to a form element. The name after the dot is the attribute: `$bind.value`, `$bind.checked`, etc.

Signal name must be a quoted identifier reference (not curly form).

### Conditional rendering

- `$if="cond"` — remove/insert element from DOM based on a boolean signal or expression.
- `$if={expr}` — curly expression form for non-signal conditions.
- `$show="cond"` — toggle visibility without removing from DOM.

### List rendering

- `$each="items as item, i"` — render a list. Uses quoted iteration syntax. Pair with `$key` for stable reconciliation:

```html
<li $each="todos as todo" $key="todo.id">{todo.text}</li>
```

### HTML output

- `$html="expr"` — render raw HTML from a signal/identifier reference.
- `$html={expr}` — render raw HTML from an expression.

### Memoization and DOM stability

- `$key="expr"` — key for list reconciliation (use inside `$each`).
- `$memo={expr}` — memoize a subtree; only re-renders when expr changes. Requires curly form.
- `$once` — boolean attribute; renders once and never re-renders.
- `$raw` — boolean attribute; treat content as raw HTML (no escaping).

### Class bindings

- `$class={cond ? 'active' : ''}` — `$`-prefixed curly expression for dynamic classes. Plain `class={…}` (no `$`) is a hard parse error (C306) in v1.0.

### Special elements

**`<$slot>`** — inserts slotted children provided by the parent:

```html
<$slot name="header" />
```

Use `expose` to pass context to slot consumers:

```html
<!-- In UserList.aihu -->
<$slot name="row" expose="user, index">
  <!-- default content -->
</$slot>
```

**`<$suspense>`** — wraps an async resource with a loading fallback:

```html
<!-- Simple: fallback attribute (component name) -->
<$suspense fallback="Skeleton">
  <UserProfile />
</$suspense>

<!-- Context-aware: slot form -->
<$suspense>
  <UserProfile />
  <$slot name="fallback">
    {loadAttempts > 3 ? <SlowConnection /> : <Spinner />}
  </$slot>
</$suspense>
```

The `fallback` attribute takes a component name (quoted string); `fallbackProps` may be added for static props. `fallback` attribute and `<$slot name="fallback">` are mutually exclusive.

**`<$shield>`** — isolates a subtree behind an error boundary:

```html
<$shield>
  <UserProfile />
  <$slot name="fallback">
    <ErrorPage error="shield.error" retry="shield.retry" />
  </$slot>
</$shield>
```

Exposes `shield.error` (Error) and `shield.retry` (function) to the fallback slot.

**`<$guard>`** — conditionally renders based on an auth scope:

```html
<$guard scope="admin" fallback="UnauthorizedPage">
  <AdminPanel />
</$guard>
```

Attributes: `scope` (scope-name), `permissions`, `rateLimit`, `fallback` (component-ref), `redirect` (path), `onDeny` (function-ref). Exposes `guard.user`, `guard.reason`, `guard.path` to the fallback slot.

**`<$warp>`** — renders children into a portal target:

```html
<$warp to="#modal-root">
  <div>Portal content</div>
</$warp>
```

### Attribute value forms

Every attribute value must be in one of two forms — bare unquoted values are forbidden:

```
✗ <button $on.click=save>            ← parse error
✓ <button $on.click="save">          ← quoted identifier reference
✓ <button $on.click={() => save()}>  ← curly expression
```

Some attributes are boolean-only (present-or-absent): `$once`, `$raw`, `disabled`, `required`, etc.

## @style block

The `@style` block defines component-scoped styles with reactive capabilities.

### `$reactive(signal)`

Binds a CSS custom property value to a signal. Updates reactively without JavaScript in the template:

```
@style {
  $global {
    :root {
      --color-primary:    $reactive(primary);
      --color-on-primary: $reactive(onPrimary);
      --color-surface:    $reactive(surface);
    }
  }
  .host { color: $reactive(textColor); }
}
```

`$global { ... }` hoists styles out of the shadow root to the document root.

### `$media(query)`

A responsive breakpoint block. Compiles to a standard `@media` rule but participates in the reactive style system:

```
@style {
  $media(max-width: 480px) {
    label { grid-template-columns: 1fr; }
  }
}
```

### Standard CSS

All standard CSS is valid inside `@style`. Styles are scoped to the component shadow root by default (unless `$global` is used).

## @agent block

The `@agent` block is a vestigial cross-cutting block. Per-name agent metadata (`describe:`, `expose:`) lives on `@state` collection entries, not here.

`@agent` now holds only two cross-cutting declarations:

```
@agent {
  $scope "user:read"     // agent permission scope
  $rate-limit 100        // requests per minute
}
```

Both are optional. The entire block may be omitted. For full agent authoring details — tool exposure, MCP compliance, and the agent capability contract — see [Authoring Agents](authoring-agents.md).

## Common diagnostics

The compiler enforces the v1 grammar with named diagnostics. The hard errors `C304` (Vue-shape `:attr=`), `C305` (colon-form event/bind alias), `C306` (plain-curly attribute binding), and `C107` (HTML-tag SFC framing) are covered by the Amendment 04 callout under [@template](#authoring-components). Three more are easy to hit and worth calling out:

### C205 — reading a `$prop` in a bare `@state` const (the common one)

A plain `@state` `const`/`let` is emitted *before* the prop bindings, so reading a prop there throws at runtime (temporal dead zone). The compiler rejects it with **C205** and steers you to `$computed`, where the read happens inside a thunk:

```
// ✗ C205 — prop read in a plain const
@state {
  $prop: { name: { default: 'world', type: 'string' } }
  const greeting = `Hello, ${name()}!`
}

// ✓ read the prop inside $computed
@state {
  $prop: { name: { default: 'world', type: 'string' } }
  $computed: {
    greeting: () => `Hello, ${name()}!`
  }
}
```

aihu does not re-order codegen to hide this — `$computed` is the supported path for any value derived from a prop.

### C204 — unknown `@block`

The only recognized top-level blocks are `@state`, `@template`, `@style`, `@agent`, `@route` (plus the deprecated `@layout` shorthand). Any other `@<name>` header is an unknown block (**C204**). The most common offender is a v0 `@props` block — the hint steers you to declare props via `$prop:` inside `@state`:

```
// ✗ C204 — there is no @props block
@props { name: { default: 'world' } }

// ✓ declare props via $prop: inside @state
@state {
  $prop: { name: { default: 'world', type: 'string' } }
}
```

### W210 — `$on.<non-event>` (use `$html` for innerHTML)

`$on.<name>` referencing anything that is not a real DOM event compiles to a dead `on<name>` handler that never fires; the compiler warns with **W210**. To set raw HTML reactively, use `$html`, not an `$on` binding:

```
// ✗ W210 — $on.innerHTML is not a DOM event → dead handler
<div $on.innerHTML="markup"></div>

// ✓ use $html
<div $html="markup"></div>
```

For the full v0 → v1 mapping of every diagnostic, see the [Migration guide](migration.md).

---

# Reactivity

`@aihu/signals` provides the reactive foundation for the entire aihu framework. It uses a push-based, synchronous execution model: when a signal is written, all dependent effects run immediately.

## `signal<T>(initialValue)`

Creates a writable reactive cell:

```typescript
import { signal } from '@aihu/signals'

const count = signal(0)

count()       // read: returns 0
count(1)      // write: sets to 1, flushes effects
```

Signals are the atomic unit of state. They are not wrapped in objects or proxies — call them as functions to read or write.

## `computed<T>(fn)`

Derives a read-only signal from other signals:

```typescript
import { signal, computed } from '@aihu/signals'

const count = signal(0)
const doubled = computed(() => count() * 2)

doubled() // 0
count(5)
doubled() // 10
```

Computed signals are lazily evaluated and memoized. They re-evaluate only when a tracked dependency changes.

## `effect(fn)`

Runs a side effect whenever tracked signals change. Returns a dispose function:

```typescript
import { signal, effect } from '@aihu/signals'

const name = signal('world')
const dispose = effect(() => {
  console.log('Hello,', name())
})
// Logs: "Hello, world"

name('aihu')
// Logs: "Hello, aihu"

dispose() // stops the effect
```

Effects run synchronously after each signal write. They auto-track all signals read during their execution.

To clean up resources when an effect re-runs, return a cleanup function:

```typescript
const dispose = effect(() => {
  const id = setInterval(() => tick(), 1000)
  return () => clearInterval(id)  // called before next run or on dispose
})
```

## `batch(fn)`

Defers effect flushes until the batch function returns:

```typescript
import { signal, effect, batch } from '@aihu/signals'

const a = signal(0)
const b = signal(0)

effect(() => console.log(a(), b()))

batch(() => {
  a(1)  // no flush yet
  b(2)  // no flush yet
})
// Now effects flush once with a=1, b=2
```

`batch` is useful when updating multiple signals that drive the same derived computation — it prevents intermediate renders. This is the preferred pattern for atomic multi-signal updates.

## `untrack(fn)`

Reads signals inside `fn` without subscribing to them. Re-entrancy safe:

```typescript
import { signal, effect, untrack } from '@aihu/signals'

const count = signal(0)
const multiplier = signal(2)

effect(() => {
  // Only subscribes to count, not multiplier
  const m = untrack(() => multiplier())
  console.log(count() * m)
})
```

`untrack` is re-entrancy safe — calling it from inside an `effect` or another `untrack` works correctly.

## Lattice signals

Lattice signals are merge-monotone reactive cells. They are useful for collaborative state where multiple sources update the same value and the result should be the "join" of all inputs.

### `latticeSignal<T>(merge, initial)`

General-purpose lattice signal with a custom merge function:

```typescript
import { latticeSignal } from '@aihu/signals'

const versions = latticeSignal<Set<string>>(
  (a, b) => new Set([...a, ...b]),
  new Set()
)
```

### `boolLatticeSignal(initial?)`

Boolean OR-merge lattice signal. Once set to `true`, stays `true`:

```typescript
import { boolLatticeSignal } from '@aihu/signals'

const ready = boolLatticeSignal(false)
ready(true)  // true
ready(false) // still true — OR merge
```

### `maxLatticeSignal(initial?)`

Numeric max-merge lattice signal. Monotonically increases:

```typescript
import { maxLatticeSignal } from '@aihu/signals'

const highScore = maxLatticeSignal(0)
highScore(42)
highScore(10)  // stays 42 — max merge
```

## `$state` accessor

`$state` is a shorthand accessor for the component state bag in SFCs. Inside `@state` blocks, all declared props and computeds are available on `$state` without qualification.

## Reactive patterns

### Computed chains

Computeds can depend on other computeds:

```typescript
const base = signal(10)
const doubled = computed(() => base() * 2)
const quadrupled = computed(() => doubled() * 2)
```

Only `base` is a writable signal; the derived chain updates automatically. Each computed is memoized — intermediate computeds don't re-run unless their own dependencies change.

### Effects with cleanup

Return a cleanup function from `effect` to dispose resources before the next run:

```typescript
const url = signal('/api/data')

effect(() => {
  const controller = new AbortController()
  fetch(url(), { signal: controller.signal })
    .then(r => r.json())
    .then(setData)
  return () => controller.abort()
})
```

The cleanup runs when `url` changes (before the next fetch starts) and when the effect is disposed.

### The `batch` pattern for atomic updates

When multiple signals feed a single derived value, use `batch` to prevent intermediate states:

```typescript
const hue = signal(215)
const saturation = signal(70)
const lightness = signal(55)

const color = computed(() =>
  `hsl(${hue()} ${saturation()}% ${lightness()}%)`
)

// Without batch: color re-computes 3 times
// With batch: color re-computes once
batch(() => {
  hue(0)
  saturation(100)
  lightness(50)
})
```

## Push-based semantics

aihu signals are push-based: effects run synchronously after each signal write (or after a `batch` completes). There is no scheduler, no microtask queue, and no async rendering pipeline. This makes behavior predictable and side effects easy to reason about.

---

# Authoring Agents

aihu is agent-first by design. Every `.aihu` SFC can declare an `@agent` block, and the Rust compiler emits both a Web Component and an MCP tool schema from the same source file. The result is a three-layer stack — component-level `@agent` declarations, the `@aihu/agent` static registry, and the `@aihu/agent-service` live execution engine — that makes every aihu app natively callable by MCP-compatible AI agents.

---

## 1. Overview: aihu's agent-first design

### Three layers

| Layer | Package | Role |
|---|---|---|
| `@agent` block | `.aihu` SFC | Per-component declaration of exposed state and actions |
| Registry | `@aihu/agent` | Compile-time metadata store, keyed by custom-element tag |
| Service | `@aihu/agent-service` | Live-binding dispatch — routes agent tool calls to DOM signal graph |

### Key properties

- **Agent code is fully elided from client builds.** When compiling with `BuildTarget.Client`, the `@agent` block produces a `// [client build] @agent block elided` comment and zero runtime bytes. Agent schemas never reach the browser bundle.
- **The Rust compiler emits a `.mcp.json` sidecar** for every SFC that has an `@agent` block. The schema is derived directly from `describe:` and `expose:` metadata in `@state` entries.
- **Live-binding (v0.3.0+)** wires agent tool calls to the actual signal graph of mounted components, so an AI agent invoking `live-counter/increment` triggers the same reactive path as a user clicking the button.

---

## 2. The `@agent` block (macro-vocabulary v2 syntax)

In macro-vocabulary v2 (RATIFIED 2026-05-05), agent metadata moves _into_ `@state` collection entries. The `@agent` block is now a minimal cross-cutting block that holds only `$scope` and `$rate-limit`.

The old v1 forms (`$expose`, `$expose.write`, agent-bare-`$action`, `$describe`) are rejected by the v2 parser with error code **C440**. Use the codemod to upgrade existing `.aihu` files.

### v2 pattern: metadata on `@state` entries

```
@state {
  import { signal } from '@aihu/signals'
  const [count, setCount] = signal(0)

  $prop: {
    count: {
      default: 0,
      type: "number",
      describe: "The current counter value",
      expose: { read: true },
    }
  }

  $action: {
    increment: {
      describe: "Add 1 to counter",
      expose: { read: true, write: true },
      handler: () => setCount(count() + 1),
    }
    decrement: {
      describe: "Subtract 1 from counter",
      expose: { read: true, write: true },
      handler: () => setCount(count() - 1),
    }
  }
}

@agent {
  $scope "authenticated"
}
```

The `expose:` key accepts `{ read: true }` (read-only tool) or `{ read: true, write: true }` (callable action). The `describe:` key is the human-readable description surfaced in the MCP tool schema.

### `@agent` block grammar (v2)

```
@agent {
  $scope <string-literal>   // optional — access scope claim required in JWT
  $rate-limit <integer>     // optional — requests per minute
}
```

Both directives are optional; the entire block may be omitted if no scope or rate limiting is needed. Exposure and description metadata live on `@state` entries, not inside `@agent`.

### Minimal `@agent` block (scope only)

```
@agent {
  $scope "authenticated"
}
```

### No `@agent` block needed

If you only want MCP tools with no scope or rate-limit enforcement, you do not need to write an `@agent` block at all. Adding `expose:` to `@state` entries is sufficient to generate the MCP tool schema.

### Real example: `live-counter.aihu`

```
@state {
  import { signal } from '@aihu/signals'
  const [count, setCount] = signal(0)

  $action: {
    increment: {
      describe: 'Add 1 to the counter',
      expose: { read: true, write: true },
      handler: () => setCount(count() + 1),
    },
    decrement: {
      describe: 'Subtract 1 from the counter',
      expose: { read: true, write: true },
      handler: () => setCount(count() - 1),
    },
    reset: {
      describe: 'Reset the counter to 0',
      expose: { read: true, write: true },
      handler: () => setCount(0),
    },
  }
}
```

No `@agent` block is needed here — these actions are exposed publicly with no scope restriction.

---

## 3. `@aihu/agent` — the registry layer

The `@aihu/agent` package is the compile-time metadata registry. The Rust compiler emits a `registerAgentMetadata()` call at the top level of every compiled `.aihu` module that has exposed state or actions. Module evaluation populates the registry.

### Public API

```typescript
import {
  registerAgentMetadata, // emitted by compiler — do not call directly
  getAgentMetadata,      // look up a single component by tag
  getAllAgentMetadata,    // enumerate the full registry (used by adapters)
} from '@aihu/agent'
```

### `AgentMetadata` shape

```typescript
interface AgentMetadata {
  tag: string                              // custom-element tag name
  describes?: string                       // top-level description (MCP prompt)
  state?: Record<string, string>           // exposed signal names → descriptions
  actions?: Record<string, ActionSchema>   // exposed action names → schemas
  [key: string]: unknown                   // unknown fields preserved (spec §9.1)
}
```

The compiler emits a frozen object. `getAgentMetadata(tag)` returns it by reference. `getAllAgentMetadata()` returns an array snapshot of all registered entries, used by adapters like `@aihu/agent-a2a` that need the full registry without knowing tags in advance.

### When to call these directly

You typically do not call `registerAgentMetadata` — the compiler does. You may call `getAgentMetadata` or `getAllAgentMetadata` in server code (route handlers, adapters) to read the compile-time manifest.

---

## 4. `@aihu/agent-service` — the execution layer

`@aihu/agent-service` bridges the compile-time `AgentMetadata` registry and the live component instance registry into a single service that MCP clients can call.

### Creating a service

```typescript
import { createAgentService } from '@aihu/agent-service'
import { getAllAgentMetadata } from '@aihu/agent'

const service = createAgentService({
  manifests: getAllAgentMetadata(),
  // Wire live-binding registry from @aihu/arbor (v0.3.0+)
  getRegistry: () => componentInstanceRegistry,
  // Optional: scope enforcement
  authPlugin: myAuthPlugin,
  // Optional: rate limiting
  rateLimitPlugin: myRateLimitPlugin,
})
```

### `AgentServiceOptions`

| Field | Type | Description |
|---|---|---|
| `manifests` | `AgentMetadata[]` | Explicit metadata list. |
| `getRegistry` | `() => Map<string, LiveBinding[]>` | Getter for the live instance registry from `@aihu/arbor/mount`. Required for live dispatch. |
| `authPlugin` | `AuthPlugin` | Scope enforcement. Required when any component uses `$scope`. |
| `rateLimitPlugin` | `RateLimitPlugin` | Rate-limit enforcement. Optional. |

### `AgentService` methods

```typescript
interface AgentService {
  getManifest(): AgentManifest
  handleToolCall(toolName: string, params: unknown, requestContext?: RequestContext): Promise<unknown>
  asMiddleware(): (req: Request) => Promise<Response | null>
}
```

- **`getManifest()`** — returns the aggregated MCP manifest listing all tools.
- **`handleToolCall(toolName, params, ctx)`** — routes `"<tag>/<action>"` to the live binding. Tool name format: `"live-counter/increment"`.
- **`asMiddleware()`** — returns a fetch-API middleware that handles `POST /__aihu/tools/call` with `{ tool, params }` JSON body. Returns `null` for non-matching requests (pass-through compatible).

### Using as middleware

```typescript
import { createRouter, defineRoute } from '@aihu/server'

const router = createRouter({
  routes: [
    defineRoute('/api/*', (req) => service.asMiddleware()(req)),
    ...appRoutes,
  ],
})
```

---

## 5. Live-binding — the `$live` directive

Live-binding (v0.3.0, spec APPROVED 2026-05-05) is the mechanism that makes `@agent` blocks operational rather than decorative.

### What live-binding is

When a component with exposed state or actions mounts, the `mount()` path in `@aihu/arbor` detects the `__agentBinding` export on the server artifact and constructs a `LiveBinding` object. This object is registered in a module-level `componentInstanceRegistry` keyed by the component's tag name.

```typescript
interface LiveBinding {
  rootId: number           // unique mount ID
  tag: string              // component tag
  getSignal(name): unknown
  setSignal(name, value): void
  callAction(name, args): Promise<unknown>
  scope(): string | null
  rateLimit(): string | null
  dispose$: () => boolean  // called on unmount
}
```

When an agent calls `handleToolCall('live-counter/increment', {})`, the service:

1. Looks up `live-counter` in `componentInstanceRegistry`.
2. Checks `$scope` — returns 403 if the JWT lacks the required claim.
3. Checks `$rate-limit` — returns 429 if quota is exhausted.
4. Calls `binding.callAction('increment', [{}])`.
5. The action runs through the same reactive signal path as a user click, and the DOM updates immediately.

### The `$guard` primitive

`$guard` blocks an agent action when a condition fails. Declare it on an action in `@state`:

```
$action: {
  checkout: {
    describe: "Complete the purchase",
    expose: { read: true, write: true },
    handler: () => processCheckout(),
    // guard: cartItems().length > 0  // (v1.1 syntax — see live-binding spec §4)
  }
}
```

Guards are evaluated before the action handler runs. A guard failure returns a structured error to the agent without executing the action.

### SSR and headless considerations

A server-rendered `LiveBinding` is ephemeral — it lives only for the duration of the SSR request. For persistent stateful agent interactions (multi-turn conversations, cart mutations, collaborative state), the component must be client-hydrated. A client-mounted `LiveBinding` is long-lived for the page session.

### Security invariants

- **Error ordering (timing-channel protection):** `handleToolCall` always returns errors in order: 404 (no instance) → 401 (missing auth) → 403 (scope denied) → 429 (rate limited). Reordering is forbidden — serving 429 before 403 would leak binding existence to unauthorized callers.
- **Fail-closed for missing auth:** If `authPlugin` is not registered and a component declares `$scope`, `handleToolCall` returns `{ error: 'AUTH_MISSING' }` (HTTP 401). The component is never served without an active auth plugin.
- **`componentInstanceRegistry` is module-private.** Only the `mount()` call path can register bindings. Plugins and request handlers cannot inject entries.
- **`__agentBinding` is elided from client bundles.** This is a compiler guarantee enforced by the split-bundle compilation (Block Structure Spec §11.5).

---

## 6. `@aihu-plugin/agent-readiness` — discovery and MCP compliance

`@aihu-plugin/agent-readiness` generates the four standard agent-discovery endpoints: `llms.txt`, `llms-full.txt`, `/.well-known/mcp/server-card.json`, and `robots.txt`.

### Router wiring (server/edge)

```typescript
import { createAgentReadinessRoutes } from '@aihu-plugin/agent-readiness'
import { createRouter, defineRoute } from '@aihu/server'

const ar = createAgentReadinessRoutes({
  name: 'My App',
  version: '1.0.0',
  summary: 'What this app does for AI agents',
  endpoint: 'https://myapp.example.com/mcp',
  llmsSections: [
    {
      title: 'Docs',
      links: [
        { title: 'API Reference', url: '/llms-full.txt', description: 'Full API docs' },
      ],
    },
  ],
})

const router = createRouter({
  routes: [
    defineRoute('/llms.txt', ar.llmsTxt),
    defineRoute('/llms-full.txt', ar.llmsFullTxt),
    defineRoute('/.well-known/mcp/server-card.json', ar.mcpServerCard),
    defineRoute('/robots.txt', ar.robotsTxt),
    ...appRoutes,
  ],
})

export default { fetch: router }
```

Each handler is a pure function that generates fresh content on every request. No global state.

### `AgentReadinessConfig` fields

| Field | Type | Description |
|---|---|---|
| `name` | `string` | Required. App name — appears as the H1 in `llms.txt`. |
| `version` | `string` | Semver string for the MCP server card. |
| `summary` | `string` | Blockquote summary in `llms.txt`. |
| `endpoint` | `string` | MCP server URL. Required for `server-card.json` generation. |
| `llmsSections` | `LlmsTxtSection[]` | Custom sections in `llms.txt`. |
| `llmsOptional` | `LlmsTxtLink[]` | Links in the `## Optional` section. |
| `aiAgents` | `'allow-all' \| 'deny-all' \| RobotsRule[]` | AI bot policy for `robots.txt`. Default: `'allow-all'`. |
| `sitemap` | `string` | Sitemap URL appended to `robots.txt`. |
| `auth` | `McpAuthConfig` | Optional OAuth 2.0 config for the MCP server card. |
| `skills` | `AgentSkill[]` | Manually declared MCP skills. |

### With OAuth 2.0 (opt-in)

```typescript
const ar = createAgentReadinessRoutes({
  name: 'My App',
  endpoint: 'https://myapp.example.com/mcp',
  auth: {
    type: 'oauth2',
    authorizationUrl: 'https://auth.example.com/authorize',
    tokenUrl: 'https://auth.example.com/token',
    scopes: ['mcp:read', 'mcp:write'],
  },
})
```

The generated MCP server card includes public OAuth URLs only — client secrets are never emitted.

### Vite integration (dev + build)

Use `viteAgentReadinessIntegration()` for Vite-based apps. In dev, it serves all four endpoints as Vite middleware. In build, it emits them as static assets.

```typescript
// vite.config.ts
import { defineConfig } from 'vite'
import { viteAgentReadinessIntegration } from '@aihu-plugin/agent-readiness'

export default defineConfig({
  plugins: [
    viteAgentReadinessIntegration({
      name: 'My App',
      endpoint: 'https://myapp.workers.dev/mcp',
      summary: 'Component-driven app with agent tools',
    }),
  ],
})
```

Note: `viteAgentReadinessIntegration()` does NOT inject routes into `createRouter` automatically. For server-side route wiring, use `createAgentReadinessRoutes()` separately.

> `agentReadiness()` is a deprecated alias for `viteAgentReadinessIntegration()`. It will be removed in v1.0.

---

## 7. MCP tool schema generation

The Rust compiler emits a `.mcp.json` sidecar alongside the compiled JS for every SFC that has exposed state or actions. The schema is derived from `describe:` and `expose:` metadata in `@state` entries.

### Emitted schema for `live-counter.aihu`

Given the live-counter example from §2, the compiler emits approximately:

```json
{
  "tag": "live-counter",
  "tools": [
    {
      "name": "live-counter/increment",
      "description": "Add 1 to the counter",
      "inputSchema": {
        "type": "object",
        "properties": {}
      }
    },
    {
      "name": "live-counter/decrement",
      "description": "Subtract 1 from the counter",
      "inputSchema": {
        "type": "object",
        "properties": {}
      }
    },
    {
      "name": "live-counter/reset",
      "description": "Reset the counter to 0",
      "inputSchema": {
        "type": "object",
        "properties": {}
      }
    }
  ]
}
```

The `__agentBinding` server export, emitted alongside the client Web Component, wires the schema to the live signal graph:

```typescript
// server artifact — never reaches the client bundle
export const __agentBinding = {
  tag: 'live-counter',
  actions: {
    increment: (args) => increment(),
    decrement: (args) => decrement(),
    reset: (args) => reset(),
  },
  reads: {},
  writes: {},
  scope: undefined,
  rateLimit: undefined,
}
```

This export is completely absent from the client artifact — its absence is validated by CI (check for any `__agentBinding` string reference in client bundle output).

---

## 8. `@aihu/mcp` — the MCP stdio server

`@aihu/mcp` exposes an MCP stdio server with two built-in tools that help AI coding agents work with aihu.

### CLI usage

```bash
aihu mcp serve
```

Starts an MCP stdio server. The process stays alive until stdin closes (the MCP host disconnects).

### Built-in tools

| Tool | Description |
|---|---|
| `aihu_example` | Returns canonical `.aihu` SFC snippets from the cookbook matching a natural-language intent. |
| `aihu_validate` | Compiles a `.aihu` source string using the Rust compiler and returns compiled TypeScript or structured diagnostics. |

### `aihu_example`

```json
{
  "name": "aihu_example",
  "inputSchema": {
    "type": "object",
    "properties": {
      "intent": { "type": "string", "description": "Natural-language description of component pattern" },
      "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional keyword tags" }
    },
    "required": ["intent"]
  }
}
```

Example call: `{ "intent": "counter with signal and action" }` returns the canonical counter SFC.

### `aihu_validate`

```json
{
  "name": "aihu_validate",
  "inputSchema": {
    "type": "object",
    "properties": {
      "source": { "type": "string", "description": "Full .aihu SFC source to compile" },
      "filename": { "type": "string", "description": "Optional virtual filename for diagnostics" }
    },
    "required": ["source"]
  }
}
```

Returns compiled TypeScript on success, or structured diagnostic errors (code, message, line/col) on failure. Use this to verify `.aihu` source before writing to disk.

### Programmatic usage

```typescript
import { createServer, startServer } from '@aihu/mcp'

// Start the server (blocks until stdin closes)
await startServer()

// Or create without connecting (for testing)
const server = createServer()
```

### MCP client configuration

To add the aihu MCP server to Claude Code or another MCP client:

```json
{
  "mcpServers": {
    "aihu": {
      "command": "aihu",
      "args": ["mcp", "serve"]
    }
  }
}
```

---

## 9. A2A and ACP protocol adapters

aihu ships two in-tree protocol adapters for agent-to-agent communication.

### `@aihu/agent-a2a` — Agent-to-Agent protocol

`mountA2aAdapter` wraps an `AgentService` with A2A protocol routes:

```typescript
import { mountA2aAdapter } from '@aihu/agent-a2a'

const a2a = mountA2aAdapter(service, {
  prefix: '',          // URL prefix for all routes. Default: ''
  name: 'my-app',     // Agent name in the discovery card. Default: 'aihu-agent-service'
})

// Wire the middleware
const router = createRouter({
  routes: [
    defineRoute('/*', async (req) => {
      const res = await a2a.asMiddleware()(req)
      return res ?? notFound()
    }),
  ],
})
```

Routes exposed:

| Method | Path | Description |
|---|---|---|
| `GET` | `/.well-known/agent.json` | A2A agent discovery card (capabilities, skills) |
| `POST` | `/a2a/tasks/send` | Submit a task (returns JSON result) |
| `POST` | `/a2a/tasks/sendSubscribe` | Submit a task with SSE streaming response |

### `@aihu/agent-acp` — Agent Communication Protocol

`mountAcpAdapter` wraps an `AgentService` with ACP protocol routes:

```typescript
import { mountAcpAdapter } from '@aihu/agent-acp'

const acp = mountAcpAdapter(service, {
  prefix: '',
  agentId: 'my-app',
})

const router = createRouter({
  routes: [
    defineRoute('/*', async (req) => {
      const res = await acp.asMiddleware()(req)
      return res ?? notFound()
    }),
  ],
})
```

Routes exposed:

| Method | Path | Description |
|---|---|---|
| `GET` | `/.well-known/acp-agent` | ACP agent discovery card |
| `POST` | `/acp/messages` | ACP message routing — routes tool calls from `parts[0].content.tool` or message content |

### Combining adapters

Both adapters coexist on the same service instance:

```typescript
const service = createAgentService({ manifests: getAllAgentMetadata(), getRegistry })
const a2a = mountA2aAdapter(service)
const acp = mountAcpAdapter(service)

const mw = async (req: Request) =>
  (await a2a.asMiddleware()(req)) ??
  (await acp.asMiddleware()(req)) ??
  notFound()
```

---

## 10. Agent compliance checklist

Every aihu application ships these agent-readiness endpoints by contract. Use this checklist before deploying.

| Requirement | Endpoint | Standard |
|---|---|---|
| llms.txt discovery | `GET /llms.txt` | [llmstxt.org](https://llmstxt.org) |
| llms-full.txt | `GET /llms-full.txt` | llmstxt.org |
| MCP Server Card | `GET /.well-known/mcp/server-card.json` | SEP-1649 (MCP 2025-06-18) |
| robots.txt | `GET /robots.txt` | RFC 9309 |
| A2A discovery | `GET /.well-known/agent.json` | A2A protocol |
| ACP discovery | `GET /.well-known/acp-agent` | ACP protocol |
| MCP stdio server | `aihu mcp serve` | MCP SDK |

### isitagentready.com checklist

The full checklist at [isitagentready.com](https://isitagentready.com) verifies:

- `llms.txt` present and parseable (H1 name, optional blockquote, H2 sections, link format)
- `robots.txt` includes explicit `Allow: /` for major AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Googlebot-Extended, CCBot, anthropic-ai, Google-Extended, Bytespider, cohere-ai)
- MCP server card present at `/.well-known/mcp/server-card.json` and valid against the SEP-1649 schema
- MCP endpoint responds to tool calls

### AI bot policy in `robots.txt`

The default `aiAgents: 'allow-all'` policy emits explicit `Allow: /` rules for every bot in `AI_BOT_LIST`. To deny all AI bots:

```typescript
createAgentReadinessRoutes({
  name: 'My App',
  aiAgents: 'deny-all',  // User-agent: *\nDisallow: /
})
```

To customize per-bot:

```typescript
createAgentReadinessRoutes({
  name: 'My App',
  aiAgents: [
    { userAgent: 'GPTBot', allow: ['/'] },
    { userAgent: 'ClaudeBot', allow: ['/'] },
    { userAgent: '*', disallow: ['/private/'] },
  ],
})
```

### Security notes

- `$scope` declarations are a security control, not a DX annotation. Always install `@aihu/auth` when using scoped `@agent` blocks.
- Audit all `@agent` blocks in third-party `.aihu` templates before production deployment. Review `$scope`, `expose: { read: true }`, and `expose: { read: true, write: true }` declarations for privilege escalation risks.
- Client bundles must never contain `__agentBinding`. Add a CI step: `grep '__agentBinding' dist/client/*.js && exit 1` to enforce this.

---

# Styling

aihu styles components with **`@aihu/css-engine`** — a hard fork of Tailwind v4 re-targeted for Web Components. Instead of a single global utility stylesheet, the engine scans your `.aihu` SFCs at build time and folds the utility classes each component actually uses into that component's shadow `<style>`. There is no global utility sheet, no runtime CSS-in-JS, and (for the static case) nothing extra ships to the client.

> **See also:** the [full utility reference](#utility-classes) — the authoritative index of every supported class, variant, and brand token, plus a "Not yet supported" callout.

> **Status:** `@aihu/css-engine@0.1.0` is published. The build-time engine (`compile`, `compileSfc`) currently depends on the `aihu-css-compile` Rust binary built from the workspace (`cargo build --release -p aihu-css-core`); a prebuilt binary ships with the package in a later plan. The runtime helpers (`cn`, `progressive`) are stable and tiny.

## How it works

- **Build-time scanning.** The engine reads `.aihu` SFC source, walks the compiler AST (via `@aihu/compiler`), collects the utility classes referenced in each component, and emits a per-SFC stylesheet.
- **Scoped output, not global.** The emitted CSS is embedded into the component's shadow root: `:host`-level theme tokens, the variant-resolved utility rules for that component, and the authored `@style` block — all folded into one shadow `<style>`. Two components on the same page never share or leak utility rules.
- **Zero-bundle for the static case.** Because utilities resolve to plain CSS at compile time, the static styling path adds no JavaScript to the client. The only runtime code is the optional `cn()` helper and the progressive-feature fallbacks, and only when you import them.

## WC-native variants

On top of the standard Tailwind variant set, the engine adds variants that only make sense inside a shadow root:

| Variant | Targets | Example |
|---------|---------|---------|
| `host:` | the component's `:host` | `host:block` |
| `slotted:` | `::slotted(...)` projected children | `slotted:text-sm` |
| `part-*:` | a named `::part(...)` exposed by the component | `part-label:font-bold` |

These compile to the corresponding shadow-DOM selectors so you can style the host, slotted content, and exposed parts with the same utility vocabulary you use for regular elements.

## Style packs

Component styling resolves against **design tokens** (CSS custom properties): a utility like `bg-primary` emits `var(--color-primary)`, and the *value* comes from a **style pack** (`aihu-default`, `aihu-graphite`, or your own via `defineStylePack()`). The token contract, the two shipped packs, `:root` + `.dark` emission, and how a consumer applies a pack are covered in full on the dedicated [Theming](#theming) page.

## `cn()` — runtime class merge

For the cases where a class string is decided at runtime (consumer overrides, conditional classes), import `cn()` from the dedicated sub-export. It is a separate sub-1 kB gz module so it never pulls in the rest of the engine:

```ts
import { cn } from '@aihu/css-engine/runtime/cn'

cn('p-2', 'p-4')                 // 'p-4'        (last-wins per property group)
cn('a', false && 'b', ['c'])     // 'a c'        (falsy dropped, arrays flattened)
cn('bg-red-500', 'bg-blue-500')  // 'bg-blue-500'
```

`cn()` resolves Tailwind-style conflicts last-wins per property group. The conflict map is **generated at engine build time** from the utility registry (not hand-maintained), so it never drifts from the utility table. Variant prefixes are respected: `hover:p-2` and `hover:p-4` conflict, but `p-2` and `hover:p-4` do not.

> Recipes use static utility strings resolved at compile time. Reach for `cn()` only for the runtime-override case — not as a general styling mechanism.

## Progressive features

Some utilities target modern CSS features (CSS anchor positioning, the Popover API). The engine emits these `@supports`-gated, and ships a tiny optional fallback shim under a separate sub-export:

```ts
import { anchorFallback, popoverFallback, position } from '@aihu/css-engine/runtime/progressive'
```

This is a hand-written ~2 kB floating-ui-style positioning shim (NOT the npm `@floating-ui/dom` package — aihu's thesis is dependency-free). `anchorFallback(anchor, floating, opts)` and `popoverFallback(anchor, panel, opts)` position a floating element with JS only when the native feature is unsupported, and return a cleanup function. It is kept in its own sub-export from `cn` so the lighter merge helper stays under its size budget.

## The component registry (`@aihu/ui` / `aihu add`)

A shadcn-style component registry — copy-in styled components distributed via an `aihu add <component>` CLI command, built on `@aihu/primitives` + the css-engine — is **on the roadmap, not yet published**. It is part of the in-progress SFC-primitives arc; do not depend on `@aihu/ui` or `aihu add` yet. See [Primitives](#primitives) for the headless behaviors that registry will be built on.

## See also

- [Theming](#theming) — design tokens, the `aihu-default` / `aihu-graphite` packs, and `defineStylePack()`
- [Primitives](#primitives) — headless WAI-ARIA behaviors that consume `cn()` + style packs
- [API Reference](#api-reference) — full `@aihu/css-engine` export tables
- [Authoring Components](#authoring-components) — the `@style` block

---

# Theming

aihu themes components with **design tokens** — CSS custom properties that the
`@aihu/css-engine` utility table resolves against. A utility like `bg-primary`
compiles to `background: var(--color-primary)`; the *value* of that token is
supplied by a **style pack**. Swap the pack and every component re-themes with
no markup change, because the token *names* are the contract and the *values*
are interchangeable.

This page is the single source of truth for theming. For the broader styling
model (scoped output, WC-native variants, `cn()`), see [Styling](#styling).

> **Status:** `@aihu/css-engine` ships the two built-in packs three ways, all
> stable and importable: as `defineStylePack()`, as `StylePack` objects from
> `@aihu/css-engine/packs`, and as CSS bundles via `@aihu/css-engine/styles/*.css`.
> See [Applying a pack](#applying-a-pack).

## The design-token contract

A token is a CSS custom property. Throughout this doc and the
`defineStylePack()` API, token **names are given without the leading `--`** —
the engine adds it. The shipped packs declare these token groups:

| Group | Tokens (names without `--`) |
|-------|------------------------------|
| Color | `color-primary`, `color-primary-foreground`, `color-secondary`, `color-secondary-foreground`, `color-accent`, `color-accent-foreground`, `color-surface`, `color-surface-foreground`, `color-background`, `color-foreground`, `color-muted`, `color-muted-foreground`, `color-border`, `color-ring`, `color-destructive`, `color-destructive-foreground` |
| Radius | `radius-sm`, `radius-md`, `radius-lg`, `radius-pill` |
| Spacing | `space-1`, `space-2`, `space-3`, `space-4`, `space-6`, `space-8`, `space-12`, `space-16` |
| Typography | `font-sans`, `font-mono` |

The utility table resolves brand utilities against the color names: `bg-primary`
→ `var(--color-primary)`, `text-accent` → `var(--color-accent)`, and so on. Any
pack that declares this name set works under every recipe with no dangling
`var()`.

## The two shipped packs

Two packs ship with the engine. They declare the **same token names** — only
the values differ — so they are drop-in interchangeable:

- **`aihu-default`** — the aihu brand palette (warm paper + ink, accent
  `#c8543a`), light values in `:root`, dark overrides in `.dark`.
- **`aihu-graphite`** — a neutral monochrome ramp expressed in `oklch()`
  (chroma ≈ 0), same token names, same `:root` + `.dark` structure.

A pack emits a light block under `:root { … }` and an optional dark block under
`.dark { … }`. The consumer toggles dark by putting the `.dark` class on (or
above) the themed subtree; the same token names carry the dark values, so
nothing in component markup changes.

```css
/* shape of a shipped pack (aihu-default) */
:root {
  --color-primary: #1a1d24;
  --color-accent: #c8543a;
  --color-surface: #faf8f4;
  --radius-md: 8px;
  /* …the full token set… */
}
.dark {
  --color-primary: #ede8e0;
  --color-accent: #e8705a;
  --color-surface: #1a1d24;
  /* …dark values, same names… */
}
```

## How tokens reach shadow-scoped components

The css-engine emits per-component CSS into each component's **shadow root**
(see [Styling](#styling)). The utility rules inside a shadow root reference the
tokens as `var(--color-primary)` etc. CSS custom properties **inherit through
the shadow boundary**, so a pack declared once on `:root` (light) flows into
every component on the page. There is no per-component theme wiring.

The `dark:` variant works the same way: a utility like `dark:bg-surface`
compiles to a rule gated on the `.dark` ancestor, and because the `.dark` block
re-declares the *same* token names with dark values, the variant resolves to
the dark token automatically.

## The built-in packs as JS objects

The two built-in packs are exported as ready-made `StylePack` objects from
`@aihu/css-engine/packs`, so you can read their tokens or emit their CSS without
re-declaring anything:

```ts
import { aihuDefault, aihuGraphite } from '@aihu/css-engine/packs'

aihuDefault.tokens['color-accent'] // '#c8543a'
aihuDefault.toCss()                // ':root { … } .dark { … }'
aihuGraphite.toCss()               // the monochrome oklch() bundle
```

These objects are the **source of truth** for the shipped `styles/*.css`
bundles below — the CSS files are generated from them (`pack.toCss()`), so the
two access paths can never drift. They are produced by `defineStylePack()`, the
same API external orgs use, so the built-ins carry no privileged shape.

## `defineStylePack()` — custom packs

External orgs declare their own pack against the same token-name contract with
`defineStylePack()`. This is the stable, importable API (`import { defineStylePack }
from '@aihu/css-engine'`). The built-in packs are themselves expressible through
it — `defineStylePack()` is just the typed, programmatic form of the shipped CSS
bundles.

```ts
import { defineStylePack } from '@aihu/css-engine'

const acme = defineStylePack({
  name: 'acme',
  tokens: { 'color-primary': '#0a7', 'radius-md': '6px' },
  dark: { 'color-primary': '#3fc' },
})

acme.toCss()
// :root {
//   --color-primary: #0a7;
//   --radius-md: 6px;
// }
// .dark {
//   --color-primary: #3fc;
// }
```

`defineStylePack({ name, tokens, dark })` returns a `StylePack` descriptor with:

- `name` — the pack name (used for registration / debugging).
- `tokens` — the light-theme `TokenMap` (the `:root` block).
- `dark` — the dark-theme `TokenMap` (the `.dark` block); empty if you pass none.
- `toCss()` — serialize to a `:root { … }` (+ `.dark { … }`) CSS string in the
  same shape as the shipped bundles.

Token names are normalized whether or not you write the leading `--`
(`'color-accent'` and `'--color-accent'` both emit `--color-accent`). An empty
`name` or empty `tokens` map throws. Only declare the tokens you override —
declare the full contract set (above) if you want a stand-alone pack with no
dangling utilities.

## Applying a pack

A pack is just a `:root { … }` (+ `.dark { … }`) stylesheet. You apply it by
getting that CSS onto the page's `:root`, then toggling `.dark` for dark mode.
Three subpath-exported, verified paths:

**1. Import a built-in CSS bundle directly.** `@aihu/css-engine/styles/aihu-default.css`
and `@aihu/css-engine/styles/aihu-graphite.css` are declared in the package
`exports`, so Vite (and any bundler that handles CSS imports) inlines them into
your app's stylesheet:

```ts
// in your app entry — Vite inlines the CSS, no extra config
import '@aihu/css-engine/styles/aihu-default.css'

// dark mode: toggle the class the pack's `.dark` block targets
document.documentElement.classList.toggle('dark')
```

**2. The built-in packs as JS objects.** Import the ready-made `StylePack`
objects from `@aihu/css-engine/packs` and inject `toCss()` yourself — handy when
you generate the `<style>` at runtime or need to read individual tokens:

```ts
import { aihuDefault } from '@aihu/css-engine/packs'

const style = document.createElement('style')
style.textContent = aihuDefault.toCss()
document.head.appendChild(style)
```

**3. `defineStylePack().toCss()` for a custom pack.** Declare your own token
bundle and inject its CSS the same way:

```ts
import { defineStylePack } from '@aihu/css-engine'
import { appTokens, appDark } from './tokens.ts' // your token maps

const pack = defineStylePack({ name: 'app', tokens: appTokens, dark: appDark })

const style = document.createElement('style')
style.textContent = pack.toCss()
document.head.appendChild(style)
```

> **Source-of-truth note:** the `styles/*.css` bundles are GENERATED from the
> `@aihu/css-engine/packs` objects (`pack.toCss()`), so path #1 and path #2
> emit byte-identical CSS — they cannot drift. The CSS files remain in the
> package `files` list, so they are also on disk at
> `node_modules/@aihu/css-engine/styles/*.css` if you prefer to copy them.

## Aliasing pack tokens

If you layer your own semantic custom properties over the pack's `--color-*`
tokens (e.g. `--surface`, `--ink`), declare the alias under **every theme
selector the pack uses** (`:root` *and* `.dark`) — not just `:root`:

```css
/* ✅ re-resolves per theme */
:root, .dark {
  --surface: var(--color-surface);
  --ink: var(--color-text);
}
```

A `:root`-only alias silently breaks dark mode:

```css
/* ❌ freezes the LIGHT value */
:root {
  --surface: var(--color-surface);
}
```

Custom properties are computed **where they are declared**. A `:root`-only
alias resolves `var(--color-surface)` against the light value once, and that
fixed light value then inherits into `.dark` containers and every shadow root
beneath them. The symptom is a half-dark page: elements using `--color-*`
directly flip to dark, while elements using the alias stay light.

Declaring the alias under both selectors makes it re-resolve in each theme
context — `.dark` on the toggle element picks up the dark `--color-surface`,
and shadow roots inherit the correct per-theme value. The same rule applies to
any extra theme selectors a custom pack targets.

## See also

- [Styling](#styling) — the scoped-output model, WC-native variants, `cn()`
- [API Reference](#api-reference) — full `@aihu/css-engine` export tables
- [Primitives](#primitives) — headless behaviors that consume these tokens

---

# Utility Classes

> Aihu's css-engine ships a focused Tailwind-v4 utility subset compiled at
> build time into per-component scoped CSS. This page is the authoritative
> index of every supported class, every variant, every brand token, and a
> "Not yet supported" callout so you know when to drop to arbitrary values
> or open an issue.

## At a glance

- Compiled by `@aihu/css-engine` from `.aihu` SFCs.
- Output is scoped CSS (shadow DOM by default, light DOM via `shadowMode: 'none'`).
- Unknown classes are silently dropped — there is no "JIT" and no global utility sheet.
- Conflict resolution (`cn()`) is last-wins per property group.

## Class index by family

### Layout (display, position, overflow)

| Class | Declaration |
|-------|-------------|
| `block` / `inline-block` / `inline` | `display: block / inline-block / inline;` |
| `flex` / `inline-flex` | `display: flex / inline-flex;` |
| `grid` / `inline-grid` | `display: grid / inline-grid;` |
| `hidden` | `display: none;` |
| `static` / `relative` / `absolute` / `fixed` / `sticky` | `position: …;` |
| `overflow-auto` / `-hidden` / `-scroll` / `-visible` | `overflow: …;` |

### Flex & Grid alignment

| Class | Declaration |
|-------|-------------|
| `flex-row` / `flex-col` | `flex-direction: row / column;` |
| `flex-wrap` / `flex-nowrap` | `flex-wrap: …;` |
| `items-start` / `-center` / `-end` / `-stretch` | `align-items: …;` |
| `justify-start` / `-center` / `-between` / `-around` / `-end` | `justify-content: …;` |

### Grid templating — NEW

| Class | Declaration |
|-------|-------------|
| `grid-cols-N` | `grid-template-columns: repeat(N, minmax(0, 1fr));` |
| `grid-cols-none` | `grid-template-columns: none;` |
| `grid-rows-N` | `grid-template-rows: repeat(N, minmax(0, 1fr));` |
| `grid-rows-none` | `grid-template-rows: none;` |
| `col-span-N` | `grid-column: span N / span N;` |
| `col-span-full` | `grid-column: 1 / -1;` |
| `col-auto` | `grid-column: auto;` |
| `row-span-N` | `grid-row: span N / span N;` |
| `row-span-full` | `grid-row: 1 / -1;` |
| `row-auto` | `grid-row: auto;` |

`N` is any positive integer.

### Spacing (padding, margin, gap, space-x/y)

Spacing uses the Tailwind scale: each unit is `0.25rem` (so `p-4` → `1rem`),
plus `px` → `1px` and `0` → `0`.

| Class | Declaration |
|-------|-------------|
| `p-*` / `px-*` / `py-*` / `pt-* pr-* pb-* pl-*` | `padding…: <scale>;` |
| `m-*` / `mx-*` / `my-*` / `mt-* mr-* mb-* ml-*` | `margin…: <scale>;` |
| `mx-auto` / `my-auto` / `mt-auto` … — NEW | `margin-inline / margin-block / margin-top: auto;` |
| `gap-*` / `gap-x-*` / `gap-y-*` | `gap…: <scale>;` |
| `space-x-N` — NEW | `& > * + * { margin-inline-start: <scale>; }` |
| `space-y-N` — NEW | `& > * + * { margin-block-start: <scale>; }` |

`space-x/y-*` emit Tailwind's standard sibling-margin recipe as a nested rule
(no margin on the first child; the gap lands on every following sibling).

### Position scale (top/right/bottom/left/inset) — NEW

Inset utilities use the same Tailwind spacing scale as padding/margin (each
unit `0.25rem`, `0` → `0`), plus the `auto` keyword. Prefix the class with `-`
for negative offsets (`-top-4` → `top: -1rem;`). `inset-*` sets all four
sides; `inset-x-*` / `inset-y-*` set the logical inline / block pairs.

| Class | Declaration |
|-------|-------------|
| `top-N` / `right-N` / `bottom-N` / `left-N` | `top / right / bottom / left: <scale>;` |
| `top-auto` / `right-auto` … | `top: auto;` etc. |
| `-top-N` / `-left-N` … (negative) | `top: -<scale>;` etc. |
| `inset-N` | `inset: <scale>;` |
| `inset-0` | `inset: 0;` |
| `inset-x-N` | `inset-inline: <scale>;` |
| `inset-y-N` | `inset-block: <scale>;` |

`N` is any spacing-scale step (e.g. `0`, `2`, `4`, `0.5`). Arbitrary values
still work for one-offs: `top-[3px]`, `inset-[10%]`.

### Sizing (width, height, min/max)

| Class | Declaration |
|-------|-------------|
| `w-*` / `h-*` (scale + fractions) | `width / height: …;` |
| `w-full` / `w-screen` / `w-auto` | `width: 100% / 100vw / auto;` |
| `h-full` / `h-screen` / `h-auto` | `height: 100% / 100vh / auto;` |
| `min-w-*` / `max-w-*` / `min-h-*` / `max-h-*` | min/max sizing |
| `max-w-{xs…7xl}` — NEW | named scale: `20rem … 80rem` |
| `max-w-prose` — NEW | `max-width: 65ch;` |
| `max-w-screen-{sm…2xl}` — NEW | breakpoint widths (`40rem … 96rem`) |
| `max-w-{none,full,min,max,fit}` — NEW | keyword max-widths |

Named `max-w-*` scale: `xs` 20rem, `sm` 24rem, `md` 28rem, `lg` 32rem,
`xl` 36rem, `2xl` 42rem, `3xl` 48rem, `4xl` 56rem, `5xl` 64rem, `6xl` 72rem,
`7xl` 80rem.

### Typography

| Class | Declaration |
|-------|-------------|
| `text-{xs…3xl}` | `font-size` + `line-height` |
| `text-left` / `-center` / `-right` | `text-align: …;` |
| `font-{thin…black}` | `font-weight: …;` |
| `italic` / `not-italic` | `font-style: …;` |
| `underline` / `line-through` / `no-underline` | `text-decoration-line: …;` |
| `uppercase` / `lowercase` / `capitalize` | `text-transform: …;` |
| `truncate` | ellipsis overflow recipe |

#### Leading & tracking scale — NEW

Named line-height (`leading-*`) and letter-spacing (`tracking-*`) scales,
matching the Tailwind v4 defaults. `leading-<n>` (numeric) maps to the spacing
scale (`leading-6` → `1.5rem`); the named steps are unitless multipliers.
Arbitrary values still work: `leading-[1.4]`, `tracking-[.2em]`.

| Class | Declaration |
|-------|-------------|
| `leading-none` | `line-height: 1;` |
| `leading-tight` | `line-height: 1.25;` |
| `leading-snug` | `line-height: 1.375;` |
| `leading-normal` | `line-height: 1.5;` |
| `leading-relaxed` | `line-height: 1.625;` |
| `leading-loose` | `line-height: 2;` |
| `leading-N` | `line-height: <spacing-scale>;` |
| `tracking-tighter` | `letter-spacing: -0.05em;` |
| `tracking-tight` | `letter-spacing: -0.025em;` |
| `tracking-normal` | `letter-spacing: 0em;` |
| `tracking-wide` | `letter-spacing: 0.025em;` |
| `tracking-wider` | `letter-spacing: 0.05em;` |
| `tracking-widest` | `letter-spacing: 0.1em;` |

### Colors (bg, text, border, fill, stroke, ring, outline)

`bg-*`, `text-*`, `border-*`, `fill-*`, `stroke-*` accept both **brand tokens**
(see below) and the **palette** (`bg-red-500`, `text-slate-700`, `bg-white`).
Brand-token classes emit `var(--color-*)`.

### Borders (width incl. directional, radius, color)

| Class | Declaration |
|-------|-------------|
| `border` | `border-width: 1px;` |
| `border-{0,2,4,8}` — NEW | `border-width: 0 / 2px / 4px / 8px;` |
| `border-x-{0,2,4,8}` / `border-y-{…}` — NEW | `border-inline-width` / `border-block-width` |
| `border-t/r/b/l-{0,2,4,8}` — NEW | `border-top/right/bottom/left-width` |
| `rounded` / `-sm` / `-md` / `-lg` / `-full` | `border-radius: …;` |

### Divide (sibling borders)

Borders between adjacent children, reusing the same nested `& > * + *` recipe
as `space-x/y`. The bare form defaults to `1px`.

| Class | Declaration |
|-------|-------------|
| `divide-x` / `divide-y` — NEW | `& > * + * { border-inline-width / border-block-width: 1px; }` |
| `divide-x-{0,2,4,8}` — NEW | `& > * + * { border-inline-width: 0 / 2px / 4px / 8px; }` |
| `divide-y-{0,2,4,8}` — NEW | `& > * + * { border-block-width: 0 / 2px / 4px / 8px; }` |
| `divide-x-reverse` / `divide-y-reverse` — NEW | `& > * + * { --tw-divide-{x,y}-reverse: 1; }` |

Set the border *color* on the same element with the standard color utilities
(e.g. `border-muted`). The `-reverse` tokens keep Tailwind's API surface via the
`--tw-divide-{x,y}-reverse` custom property.

### Effects

| Class | Declaration |
|-------|-------------|
| `shadow` / `-md` / `-lg` / `-none` | `box-shadow: …;` |
| `opacity-*` | `opacity: …;` |

### Ring

A focus ring drawn as a `box-shadow` composed from `--tw-ring-*` custom
properties (the Tailwind v4 recipe), so the ring **width**, **color**, and
**offset** are set independently and layer with a regular `shadow-*`.

| Class | Declaration |
|-------|-------------|
| `ring` — NEW | 3px ring (`box-shadow` from `--tw-ring-*`) |
| `ring-{0,1,2,4,8}` — NEW | ring at that pixel width: `--tw-ring-shadow: … calc({n}px + var(--tw-ring-offset-width)) var(--tw-ring-color);` |
| `ring-inset` — NEW | `--tw-ring-inset: inset;` (draws the ring inside the edge) |
| `ring-offset-{0,1,2,4,8}` — NEW | `--tw-ring-offset-width: {n}px;` (gap between the element and the ring) |
| `ring-<color>` | sets the ring **color**: `--tw-ring-color: var(--color-*);` |

The width side (`ring-{n}`) and the color side (`ring-<color>`) are
complementary — use them together, e.g. `focus:ring-2 ring-blue-500`. The color
path is unchanged; `ring-blue-500`, `ring-primary`, `ring-ring` etc. still emit
`--tw-ring-color`.

### Z-index

`z-0`, `z-10`, `z-20`, `z-30`, `z-40`, `z-50`, `z-auto` → `z-index: …;`.

## Motion — NEW

Round-2 motion utilities cover transforms, transitions, and animations. Each
transform utility (`translate-*`, `rotate-*`, `scale-*`) emits a **single
`transform:` declaration** rather than composing CSS variables — so within one
element the CSS cascade applies last-wins per family. To combine transforms
(e.g. translate *and* rotate) on one element, use an arbitrary value
(`transform-[...]` is not yet wired; compose with a custom `@style` rule).

### transform / translate

| Class | Declaration |
|-------|-------------|
| `transform` | identity baseline (`translate(0,0) rotate(0) … scaleX(1) scaleY(1)`) |
| `transform-none` | `transform: none;` |
| `translate-x-N` / `translate-y-N` | `transform: translateX/Y(<spacing-scale>);` |
| `-translate-x-N` / `-translate-y-N` | negative translate (e.g. `-0.5rem`) |

`translate-*` uses the spacing scale (`translate-x-2` → `0.5rem`). The leading
`-` produces the negative form.

### rotate / scale

| Class | Declaration |
|-------|-------------|
| `rotate-N` | `transform: rotate(Ndeg);` |
| `-rotate-N` | `transform: rotate(-Ndeg);` |
| `scale-N` | `transform: scale(N/100);` (e.g. `scale-105` → `1.05`) |
| `scale-x-N` / `scale-y-N` | `transform: scaleX/Y(N/100);` |

### transition / duration / ease

| Class | Declaration |
|-------|-------------|
| `transition` | default property set + `150ms` + `cubic-bezier(0.4, 0, 0.2, 1)` |
| `transition-none` | `transition-property: none;` |
| `transition-all` | `transition-property: all;` + default timing |
| `transition-colors` | color/bg/border/decoration/fill/stroke + default timing |
| `transition-opacity` | `transition-property: opacity;` + default timing |
| `transition-transform` | `transition-property: transform;` + default timing |
| `duration-N` | `transition-duration: Nms;` |
| `ease-linear` | `transition-timing-function: linear;` |
| `ease-in` / `ease-out` / `ease-in-out` | cubic-bezier easing functions |

### animate

| Class | Declaration |
|-------|-------------|
| `animate-none` | `animation: none;` |
| `animate-spin` | `animation: spin 1s linear infinite;` + `@keyframes spin` |
| `animate-ping` | `animation: ping …;` + `@keyframes ping` |
| `animate-pulse` | `animation: pulse …;` + `@keyframes pulse` |
| `animate-bounce` | `animation: bounce 1s infinite;` + `@keyframes bounce` |

Each `animate-*` (except `animate-none`) emits its **`@keyframes` block as a
top-level sibling rule** alongside the class rule — keyframes cannot be nested
inside a selector body. Re-emitting an identical block is idempotent in CSS.

## Variants

- **Web-Component-native:** `host:`, `slotted:`, `slotted-<tag>:`, `part-<name>:`, `host-context-<name>:`
- **Pseudo:** `hover:`, `focus:`, `focus-visible:`, `active:`, `disabled:`, `visited:`, `checked:`
- **Responsive (min-width):** `sm:` 40rem, `md:` 48rem, `lg:` 64rem, `xl:` 80rem, `2xl:` 96rem (override via `@theme`)
- **Dark mode:** `dark:` (Firefox-safe `[data-theme="dark"]` / `.dark` cascade)
- **Arbitrary selectors:** `[&>li]:`, `[&:has(img)]:`, etc.
- **Stacking:** `md:hover:bg-primary` — left-to-right composition

### aria-\*/data-\* attribute variants

Gate a utility on an ARIA state or a `data-*` attribute. The variant compiles
to an attribute selector appended to the class.

| Variant | Selector | Notes |
|---------|----------|-------|
| `aria-checked:` | `[aria-checked="true"]` | implicit `="true"` |
| `aria-disabled:` | `[aria-disabled="true"]` | |
| `aria-expanded:` | `[aria-expanded="true"]` | |
| `aria-selected:` | `[aria-selected="true"]` | |
| `aria-pressed:` | `[aria-pressed="true"]` | |
| `aria-[expanded=false]:` | `[aria-expanded="false"]` | arbitrary `name=value` |
| `data-[state=open]:` | `[data-state="open"]` | arbitrary `name=value` |
| `data-active:` | `[data-active]` | bare data-* → presence (no `="true"`) |

```
aria-expanded:bg-accent      →  .aria-expanded\:bg-accent[aria-expanded="true"] { background-color: var(--color-accent); }
data-[state=open]:underline  →  .data-\[state\=open\]\:underline[data-state="open"] { text-decoration-line: underline; }
```

Any aria-/data- variant whose base utility is unknown emits nothing — there is
no spurious empty rule.

### Container queries (@container)

Mark an element as a query container with `@container` (or the named
`@container/<name>` form), then size descendants with the `@sm:`/`@md:`/`@lg:`/
`@xl:`/`@2xl:` container-query variants. These wrap the rule in an `@container`
at-rule rather than `@media`, and use Tailwind's container-query scale (which
differs from the viewport breakpoint scale).

| Class / variant | Output |
|-----------------|--------|
| `@container` | `container-type: inline-size;` |
| `@container/sidebar` | `container-type: inline-size; container-name: sidebar;` |
| `@sm:` | `@container (min-width: 24rem) { … }` |
| `@md:` | `@container (min-width: 28rem) { … }` |
| `@lg:` | `@container (min-width: 32rem) { … }` |
| `@xl:` | `@container (min-width: 36rem) { … }` |
| `@2xl:` | `@container (min-width: 42rem) { … }` |

```
<div class="@container">
  <div class="@md:flex">…</div>   →  @container (min-width: 28rem) { .\@md\:flex { display: flex; } }
</div>
```

## Brand tokens (16)

Override any token in a component's `@style` block via
`@theme { --color-primary: oklch(...); }`.

| Token | Token |
|-------|-------|
| `primary` / `primary-foreground` | `secondary` / `secondary-foreground` |
| `accent` / `accent-foreground` | `surface` / `surface-foreground` |
| `destructive` / `destructive-foreground` | `background` / `foreground` |
| `muted` / `muted-foreground` | `border` / `ring` |

Use as `bg-primary`, `text-accent`, `border-muted`, `ring-ring`, etc.

## Palette

22 color families × 11 shades (`50`–`950`), matching the Tailwind v4 palette
(e.g. `bg-red-500`, `text-slate-700`, `border-zinc-200`). See the
[Tailwind v4 color palette](https://tailwindcss.com/docs/colors) for the full
swatch list.

## Arbitrary values

Use `prefix-[value]` to bypass the scale for: `bg`, `text`, `w`, `h`, `min-w`,
`max-w`, `min-h`, `max-h`, `p`, `px`, `py`, `m`, `mx`, `my`, `gap`, `rounded`,
`border`, `leading`, `tracking`, `z`, `top`, `right`, `bottom`, `left`,
`inset`, `fill`, `stroke`, `shadow`.

```
bg-[#1a1d24]   →  background-color: #1a1d24;
w-[34ch]       →  width: 34ch;
top-[1rem]     →  top: 1rem;
```

## Not yet supported

> The following are deliberately out of scope today. Most have an
> arbitrary-value workaround; the rest require variant-parser changes. Open an
> issue if you need one promoted.

- Arbitrary at-rules beyond `@media` / `@container` (e.g. `@supports`)

## Worked examples

One input → output pair per new family.

### `space-y-4` (Spacing)

```html
<ul class="space-y-4"> … </ul>
```

```css
.space-y-4 { & > * + * { margin-block-start: 1rem; } }
```

### `divide-y-2` (Divide — sibling borders)

```html
<ul class="divide-y-2 border-muted"> … </ul>
```

```css
.divide-y-2 { & > * + * { border-block-width: 2px; } }
```

### `mx-auto` (Margin auto)

```html
<div class="mx-auto"> … </div>
```

```css
.mx-auto { margin-inline: auto; }
```

### `max-w-7xl` (Named max-width)

```html
<section class="max-w-7xl"> … </section>
```

```css
.max-w-7xl { max-width: 80rem; }
```

### `grid-cols-3` (Grid templating)

```html
<div class="grid grid-cols-3 gap-4"> … </div>
```

```css
.grid-cols-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
```

### `border-t-4` (Directional border width)

```html
<div class="border-t-4"> … </div>
```

```css
.border-t-4 { border-top-width: 4px; }
```

### `absolute top-4 right-4` (Position scale)

```html
<button class="absolute top-4 right-4"> … </button>
```

```css
.top-4 { top: 1rem; }
.right-4 { right: 1rem; }
```

### `leading-relaxed` (Line-height scale)

```html
<p class="leading-relaxed"> … </p>
```

```css
.leading-relaxed { line-height: 1.625; }
```

### `tracking-wide` (Letter-spacing scale)

```html
<h1 class="tracking-wide"> … </h1>
```

```css
.tracking-wide { letter-spacing: 0.025em; }
```

### `ring-2 ring-blue-500` (Ring width + color)

```html
<button class="focus:ring-2 ring-blue-500"> … </button>
```

```css
.ring-2 {
  --tw-ring-offset-shadow: var(--tw-ring-inset) 0 0 0 var(--tw-ring-offset-width) var(--tw-ring-offset-color);
  --tw-ring-shadow: var(--tw-ring-inset) 0 0 0 calc(2px + var(--tw-ring-offset-width)) var(--tw-ring-color);
  box-shadow: var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow, 0 0 #0000);
}
.ring-blue-500 { --tw-ring-color: var(--color-blue-500); }
```

### `ring-offset-2` (Ring offset width)

```html
<div class="ring-2 ring-offset-2"> … </div>
```

```css
.ring-offset-2 { --tw-ring-offset-width: 2px; }
```

### `hover:scale-105` + `transition-transform` (Motion)

```html
<button class="transition-transform duration-300 hover:scale-105"> … </button>
```

```css
.transition-transform { transition-property: transform; transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1); transition-duration: 150ms; }
.duration-300 { transition-duration: 300ms; }
.hover\:scale-105:hover { transform: scale(1.05); }
```

### `animate-spin` (Animation with hoisted keyframes)

```html
<div class="animate-spin"> … </div>
```

```css
.animate-spin { animation: spin 1s linear infinite; }
@keyframes spin { to { transform: rotate(360deg); } }
```

### `aria-expanded:` (attribute variant)

```html
<button class="aria-expanded:bg-accent"> … </button>
```

```css
.aria-expanded\:bg-accent[aria-expanded="true"] { background-color: var(--color-accent); }
```

### `@container` + `@md:` (container query)

```html
<div class="@container">
  <div class="@md:flex"> … </div>
</div>
```

```css
.\@container { container-type: inline-size; }
@container (min-width: 28rem) {
  .\@md\:flex { display: flex; }
}
```

## See also

- [Styling](#styling) — how the engine scans and scopes utilities
- [Theming](#theming) — design tokens and style packs
- [API Reference](#api-reference) — `@aihu/css-engine` export tables

---

# Primitives

**`@aihu/primitives`** is a set of headless behavior primitives — WAI-ARIA APG patterns implemented as vanilla custom elements. Each primitive emits DOM structure, ARIA wiring, and `data-state` attributes, and owns its state on `@aihu/signals`. It ships **zero CSS**: you style every part yourself, typically with the [css-engine](#styling)'s `cn()` + style packs.

> **Status:** `@aihu/primitives@0.0.1` is published. Behaviors below are available today. The styled component registry built on top of them (`@aihu/ui` / `aihu add`) is roadmap-only — see [the registry note](#styling).

## Why headless

A headless primitive gives you the hard part — focus management, keyboard interaction, ARIA roles/relationships, open/close state — without imposing any look. Each piece reflects `data-state="open"|"closed"` (and friends), so your CSS selectors drive the appearance while the primitive guarantees the accessibility contract. This mirrors the Radix/Ark "root ↔ piece" model: a root element owns the state and provides it via a DOM-walk context; the pieces inject it by walking up the real DOM (across shadow boundaries), nearest-provider-wins.

## Phase-1 components

### Dialog

The WAI-ARIA APG **Modal Dialog** pattern. Pieces: `<aihu-dialog-root>` (state owner), `<aihu-dialog-trigger>`, `<aihu-dialog-content>`, `<aihu-dialog-backdrop>`, `<aihu-dialog-close>`, `<aihu-dialog-title>`, `<aihu-dialog-description>`. Provides focus-trap + return-focus, Escape-to-close, outside-click-to-close (when modal), and `role="dialog"` / `aria-modal` / `aria-labelledby` / `aria-describedby` plus the trigger's `aria-haspopup` / `aria-expanded` / `aria-controls`. Register with `defineDialog()`.

### Tooltip

The WAI-ARIA APG **Tooltip** pattern. Pieces: `<aihu-tooltip-root>`, `<aihu-tooltip-trigger>`, `<aihu-tooltip-content>`. The trigger is `aria-describedby` the content (not labelled-by), the content has `role="tooltip"` and is not focusable, and Escape dismisses. Open/close honors configurable `open-delay` / `close-delay` (default 700 / 300 ms). Placement reuses the css-engine's `position()` shim — the tooltip carries no positioning math and adds no floating-ui dependency. Register with `defineTooltip()`.

### Button

`AihuButton` — a headless button base class implementing the APG **Button** pattern. When the host is not a native `<button>`, it sets `role="button"` + `tabindex="0"` and handles Enter / Space to fire a synthetic click; native `<button>` defers to native semantics. Reflects `aria-pressed` (toggle), `aria-disabled`, and `data-state`, and inherits `disabled` from an ancestor `form-control`. It is a base class, not a pre-registered tag — extend it or register a concrete element with `defineButton(tag)`.

## Phase-0 substrates

The lower-level building blocks the Phase-1 components compose on. Use them directly when building your own primitives.

| Primitive | Subpath | Role |
|-----------|---------|------|
| DOM context | `@aihu/primitives/context` | Live ancestor-traversal context (`createDomContext` / `provideContext` / `injectContext`) — the root↔piece coordination mechanism. Self-contained; does NOT import `@aihu/context`. |
| Presence gate | `@aihu/primitives/presence-gate` | Mount/unmount gate that holds children through an exit transition (the Radix `Presence` pattern). `definePresenceGate()`. |
| Roving focus | `@aihu/primitives/roving-focus` | Roving-`tabindex` focus management for composite widgets, configurable `Orientation`. `defineRovingFocus()`. |
| Collection | `@aihu/primitives/collection` | Ordered registration of descendant items (for lists, menus, etc.). `createCollection()` / `defineCollection()`. |
| Config provider | `@aihu/primitives/config-provider` | Propagates `colorScheme` / `density` / `direction` to descendants via context. `defineConfigProvider()`. |
| Form control | `@aihu/primitives/form-control` | Shared label/description/validity wiring + a `disabled` context that descendants (e.g. button) inherit. `defineFormControl()`. |

## Consumer pattern — `cn()` + a style pack

Primitives are unstyled, so you bring the CSS. The intended pairing is the css-engine: style each `data-state` with utility classes, and merge any runtime overrides with `cn()`.

```ts
import { defineDialog } from '@aihu/primitives/dialog'
import { cn } from '@aihu/css-engine/runtime/cn'

defineDialog()

// merge a base recipe string with a caller-provided override (last-wins)
const contentClass = cn('rounded-lg p-6 bg-surface shadow-lg', userClassName)
contentEl.className = contentClass
```

```html
<aihu-dialog-root>
  <aihu-dialog-trigger>Open</aihu-dialog-trigger>
  <aihu-dialog-backdrop class="fixed inset-0 bg-black/40 data-[state=closed]:opacity-0"></aihu-dialog-backdrop>
  <aihu-dialog-content class="rounded-lg p-6 bg-surface shadow-lg">
    <aihu-dialog-title>Title</aihu-dialog-title>
    <aihu-dialog-description>Body copy.</aihu-dialog-description>
    <aihu-dialog-close>Close</aihu-dialog-close>
  </aihu-dialog-content>
</aihu-dialog-root>
```

The primitive guarantees focus trap, Escape, ARIA, and `data-state`; your utility classes (resolved by the css-engine at build time, or merged at runtime with `cn()`) supply the look.

## See also

- [Styling](#styling) — the css-engine, `cn()`, style packs, scoped output
- [API Reference](#api-reference) — full `@aihu/primitives` export tables

---

# Routing and Layouts

aihu uses file-based routing. Pages live under `src/pages/` and automatically become routes when compiled.

## File-based routing

Any `.aihu` file under `src/pages/` that contains an `@route` block is treated as a page route. The file path determines the default URL pattern:

| File | Default pattern |
|------|----------------|
| `src/pages/index.aihu` | `/` |
| `src/pages/about.aihu` | `/about` |
| `src/pages/users/[id].aihu` | `/users/:id` |

### File-based routing tree example

```
src/
  pages/
    index.aihu          →  /
    about.aihu           →  /about
    users/
      index.aihu         →  /users
      [id].aihu          →  /users/:id
    admin/
      index.aihu         →  /admin
      users.aihu         →  /admin/users
  layouts/
    default.aihu         →  wraps all routes without an explicit layout
    admin.aihu           →  wraps routes with layout: admin
```

## The `@route` block

```
@route {
  path: /admin/users
  name: admin-users
  middleware: [auth, admin]
  ssr: true
  layout: admin
}
```

Fields:

- **`path`** — explicit URL path override. If omitted, the path is derived from the file location.
- **`name`** — route name used in programmatic navigation and the route manifest.
- **`middleware`** — array of middleware names applied to this route.
- **`ssr`** — boolean. `true` enables server-side rendering for this route.
- **`layout`** — layout name to wrap this route's content.

## `.route.json` sidecars

The compiler emits a `.route.json` file alongside each compiled SFC that has an `@route` block. Example:

```json
{
  "pattern": "/admin/users",
  "name": "admin-users",
  "middleware": ["auth", "admin"],
  "ssr": true,
  "layout": "admin"
}
```

Read a sidecar programmatically with `readRouteSidecar(path)` from `@aihu/router/plugin`.

## `viteRouterIntegration()`

`viteRouterIntegration()` is a Vite plugin (from `@aihu/router/plugin`) that scans `src/pages/` at build time, reads all `.route.json` sidecars, and assembles a virtual route manifest module:

```typescript
// vite.config.ts
import { defineConfig } from 'vite'
import { viteRouterIntegration } from '@aihu/router/plugin'

export default defineConfig({
  plugins: [viteRouterIntegration()],
})
```

The virtual module `virtual:aihu-routes` exports the assembled `RouteDefinition[]` array. The runtime `createRouter` consumes it to handle navigation.

`viteRouterPlugin` is a deprecated alias removed at v1.0.

## `createRouter(routes)`

Creates a router instance from an array of route definitions. Typically you pass the virtual module directly:

```typescript
import { createRouter } from '@aihu/router'
import routes from 'virtual:aihu-routes'

const router = createRouter(routes)
```

## Layouts

Layouts live under `src/layouts/`. The default layout is `src/layouts/default.aihu`. A layout wraps the page's rendered output via `<$slot>`:

```
@template {
  <header>My App</header>
  <main>
    <$slot />
  </main>
  <footer>Footer</footer>
}
```

`scanLayouts(dir)` from `@aihu/router/plugin` returns all discovered layout names.

## Router middleware

Middleware is defined with `defineRouterMiddleware` and composed with `composeRouterMiddleware`:

```typescript
import { defineRouterMiddleware, composeRouterMiddleware } from '@aihu/router'

const authMiddleware = defineRouterMiddleware(async (ctx, next) => {
  if (!ctx.params.token) {
    return { kind: 'redirect', location: '/login', status: 302 }
  }
  return next()
})

const loggingMiddleware = defineRouterMiddleware(async (ctx, next) => {
  console.log('navigating to', ctx.url.pathname)
  return next()
})

export const composed = composeRouterMiddleware(loggingMiddleware, authMiddleware)
```

### Stage ordering

Middleware passed to `composeRouterMiddleware` are called in array order. Any middleware that returns a non-void result (e.g. `{ kind: 'redirect' }` or `{ kind: 'cancel' }`) short-circuits the chain — subsequent middleware and the route handler are not called.

Standard stage ordering convention:

1. Logging / tracing
2. Auth / session
3. Redirect rules
4. Render

## Reactive routing primitives

The router exposes reactive primitives for use in SFCs and TypeScript:

| Export | Description |
|--------|-------------|
| `useRoute()` | Reactive accessor returning the current route match |
| `useRouter()` | Access the router instance |
| `navigate(path, opts?)` | Programmatic navigation |
| `createRouteSignal(router)` | Signal bound to the current route |
| `createPrefetcher(router)` | Create a route prefetcher |
| `provideRouteContext(router)` | Provide route context to the component tree |
| `RouteContext` | Context token for the current route |

---

# Data Fetching

aihu provides several primitives for fetching data, ranging from reactive resource signals to server-side loaders and typed client stubs.

## `$resource` macro

In a `@state` block, `$resource` binds an async fetcher to a reactive signal. It uses the v2 collection-form: bare (no metadata) or wrapped (with metadata).

```
@state {
  $prop: {
    userId: { default: 1, type: "number" }
  }

  $resource: {
    // bare — just the fetcher thunk
    user: () => fetchUser(userId),

    // wrapped — add describe/expose to surface to agents
    recentPosts: {
      describe: 'Posts by the current user',
      expose: { read: true },
      value: () => fetchPosts(userId)
    }
  }
}

@template {
  <$suspense fallback="Spinner">
    <div>{user.value.name}</div>
  </$suspense>
}
```

The resource variable is a 3-state loader object:

- `resource.pending` — `true` while the fetch is in-flight.
- `resource.value` — the resolved value (or `undefined` if pending/error).
- `resource.error` — the error (or `undefined` if pending/success).

When any signal read inside the fetcher changes (e.g. `userId`), the resource re-fetches automatically.

### The 3-state loader pattern

All async data in aihu follows the 3-state pattern:

| State | `pending` | `value` | `error` |
|-------|-----------|---------|---------|
| Loading | `true` | `undefined` | `undefined` |
| Success | `false` | data | `undefined` |
| Error | `false` | `undefined` | Error |

Use `<$suspense>` in templates to handle the pending state declaratively:

```html
<$suspense fallback="Spinner">
  <div>{user.value.name}</div>
</$suspense>
```

## `createResource` from `@aihu-plugin/data`

Use `createResource` directly in TypeScript outside of SFCs:

```typescript
import { createResource } from '@aihu-plugin/data'
import { signal } from '@aihu/signals'

const userId = signal(1)
const user = createResource(
  () => userId(),                              // key — reactive; changes trigger refetch
  (id) => fetch(`/api/users/${id}`).then(r => r.json())  // fetcher
)
```

The resource is automatically re-fetched when any signals read inside the key function change.

### Resource store and SSR dehydration

For SSR, use a resource store to cache and dehydrate resources:

```typescript
import { createResource, createResourceStore, createResourceSerializer, data } from '@aihu-plugin/data'

// Register the data plugin in aihu.config.ts:
import { defineAihuConfig } from '@aihu/server'
export default defineAihuConfig({
  plugins: [data()],
})
```

## Server loaders

Server loaders run on the server and provide data to SSR-rendered pages. Define a loader with `defineLoader` from `@aihu/server`:

```typescript
import { defineLoader } from '@aihu/server'

export const loader = defineLoader(async (ctx) => {
  const users = await db.users.findMany()
  return { users }
})
```

The loader receives a `LoaderContext` with the request, params, and URL. The return value is serialized and sent to the client as part of the SSR payload.

## Server loaders → SFC handoff

A loader runs server-side per matched route, but the SFC author still has to consume its result. There are two documented handoff patterns.

### Pattern A — `route.data` prop (default)

The loader payload is delivered as the `data` field on the SFC's `route` prop:

`src/pages/posts/[slug].loader.ts`:

```typescript
import { defineLoader } from '@aihu/server'

export const loader = defineLoader(async (ctx) => {
  return await db.posts.findOne({ slug: ctx.params.slug })
})
```

`src/pages/posts/[slug].aihu`:

```
@route { path: "/posts/[slug]", ssr: true }

@state {
  $prop: {
    route: { type: "{ params: { slug: string }; data: { title: string; body: string } }" }
  }
}

@template {
  <article>
    <h1>{route.data.title}</h1>
    <p>{route.data.body}</p>
  </article>
}
```

The runtime injects the resolved loader payload as `route.data` before mount. During streaming SSR or client-side re-validation, wrap the consumer in `<$suspense>` to declaratively handle the pending state.

### Pattern B — `$resource` + `createServerCall`

If the data needs to be fetched on demand (e.g. on a button click or when a search box changes), use a typed client stub instead:

```typescript
// shared/api.ts
import { createServerCall } from '@aihu/server'
import type { Post } from './types'

export const searchPosts = createServerCall<[query: string], Post[]>('posts/search')
```

```
@state {
  $prop: {
    searchTerm: { default: '', type: "string" }
  }

  $resource: {
    // refetches automatically when searchTerm changes
    matches: () => searchPosts(searchTerm)
  }
}

@template {
  <input $bind.value="searchTerm" />

  <$suspense fallback="Spinner">
    <ul>
      <li $each="matches.value as p" $key="p.slug">{p.title}</li>
    </ul>
  </$suspense>
}
```

Use Pattern A when the data is route-bound and known at request time. Use Pattern B when the data depends on UI state that the user changes after the page loads.

## `$server` macro

In `@state` blocks, `$server` gates code to server-only execution:

```
@state {
  const data = $server.fetchSecretData()
}
```

When compiling with `BuildTarget.Client`, any `$server` references are elided from the output.

## `createServerCall`

`createServerCall` creates a typed fetch stub that calls a server action from client-side code:

```typescript
import { createServerCall } from '@aihu/server'

const getUser = createServerCall<[id: number], User>('users/getUser')

// In an effect or event handler:
const user = await getUser(42)
```

The stub sends a `POST` request to `/_aihu/call/<endpoint>` with the args serialized as JSON.

## Server response helpers

From `@aihu/server`:

| Helper | Description |
|--------|-------------|
| `json(data, status?)` | Return a JSON response |
| `notFound(msg?)` | Return a 404 response |
| `badRequest(msg?)` | Return a 400 response |
| `serverError(msg?)` | Return a 500 response |
| `methodNotAllowed(msg?)` | Return a 405 response |

## Streaming routes

For streaming HTTP responses (e.g. server-sent events), use `defineStreamRoute` from `@aihu/server`:

```typescript
import { defineStreamRoute } from '@aihu/server'

export const events = defineStreamRoute(async (ctx, stream) => {
  stream.write({ event: 'connected' })
  // ...
})
```

---

# SSR and Hydration

aihu supports server-side rendering via `@aihu/server`. The build system supports three targets: `client`, `server`, and `universal`.

## Build targets

Set the build target in `aihu.config.ts`:

```typescript
import { defineAihuConfig } from '@aihu/server'

export default defineAihuConfig({
  build: {
    target: 'universal',
  },
})
```

| Target | Description |
|--------|-------------|
| `client` | Browser bundle only. `@agent` manifest and `$server` refs are elided. |
| `server` | Server bundle only. Full agent manifest and server-only code included. |
| `universal` | Both client and server outputs. Default. |

## The `@route` block and route sidecars

The Rust compiler emits a `.route.json` sidecar alongside each compiled `.aihu` file. This sidecar encodes the route path, name, SSR mode, and loader reference. At build time, `viteRouterIntegration()` reads every `.route.json` in `src/pages/` and assembles the route manifest into the `virtual:aihu-routes` virtual module. The result is a fully static manifest — no filesystem scanning at runtime.

```
@route {
  path: /users
  name: users
  ssr: true
}
```

Setting `ssr: true` enables server-side rendering for that route.

## `createRequestRouter`, `defineRoute`, and `json()`

`@aihu/server` provides a fetch-API-native router. These three exports are the core building blocks:

- **`createRequestRouter(options)`** — builds a fetch-API request handler from an explicit route manifest. The returned `router` function is a standard `(request: Request) => Response | Promise<Response>` and can be passed directly to `Bun.serve`, `Deno.serve`, or exported as a Cloudflare Worker's `fetch` handler.
- **`defineRoute(path, handler)`** — declares a single route. The handler receives a `RouteContext` and must return a `Response`.
- **`json(data, init?)`** — constructs a `Response` with `Content-Type: application/json` and the given data serialized. A thin convenience wrapper over `new Response(JSON.stringify(data), ...)`.

```typescript
import { createRequestRouter, defineRoute, json } from '@aihu/server'
import { createAgentReadinessRoutes } from '@aihu-plugin/agent-readiness'

const ar = createAgentReadinessRoutes({
  name: 'My App',
  endpoint: 'https://myapp.workers.dev/mcp',
  summary: 'An aihu-powered app.',
})

const router = createRequestRouter({
  routes: [
    defineRoute('/llms.txt', ar.llmsTxt),
    defineRoute('/.well-known/mcp/server-card.json', ar.mcpServerCard),
    defineRoute('/robots.txt', ar.robotsTxt),
    defineRoute('/api/hello', () => json({ hello: 'world' })),
  ],
})

// Cloudflare Worker
export default { fetch: router }
// Bun
// Bun.serve({ fetch: router })
// Deno
// Deno.serve(router)
```

Additional server utilities from `@aihu/server`: `badRequest()`, `notFound()`, `serverError()`, `methodNotAllowed()`, `defineApiRoute()`, `composeMiddleware()`, `defineMiddleware()`.

## `renderToStream` and `renderToString`

Stream-render a component to an HTML response:

```typescript
import { renderToStream } from '@aihu/server'

const response = renderToStream(MyComponent, {
  props: { userId: 42 },
  loader: myLoader,
})
```

Returns a `ReadableStream<string>` that emits HTML chunks as the component tree resolves. Suitable for edge runtimes and Node.js streaming responses.

For a complete HTML string (e.g. for pre-rendering):

```typescript
import { renderToString } from '@aihu/server'

const html = await renderToString(async () => {
  const data = await myLoader(ctx)
  return renderMyComponent(data)
})
```

## SSR with loaders

Enable SSR per route with `ssr: true` in the `@route` block. The server runs the associated `defineLoader` and injects the result as props before streaming the component:

```
@route {
  name: users
  ssr: true
}
```

```typescript
// users.loader.ts
import { defineLoader } from '@aihu/server'

export const loader = defineLoader(async (ctx) => {
  return { users: await db.users.findMany() }
})
```

The loader result is serialized into the SSR payload and dehydrated on the client — no second fetch needed.

## Islands

In aihu, "islands" means interactive components embedded in an otherwise static or server-rendered page. The SSR output is inert HTML; each island component re-attaches its reactive signal graph on the client using `hydrate()` rather than `mount()`.

The island pattern gives you SSR performance for the outer shell while preserving full reactivity for interactive regions — without downloading or executing JavaScript for the static parts.

## `hydrate()` vs `mount()` — the distinction

Both functions come from `@aihu/arbor` and return a `MountScope` (with `.dispose()` and `.serialize()` methods). They differ in what happens to the DOM:

- **`mount(component, host)`** — creates DOM elements from scratch and appends them to `host`. Used for pure client-side rendering (no prior SSR output).
- **`hydrate(component, host, snapshot)`** — attaches reactive effects to *existing* DOM nodes under `host` without re-creating elements. It walks the arbor node tree and uses `data-aihu-path` attributes on pre-rendered elements as anchors to wire signal bindings. If a path anchor is missing (DOM mismatch), that subtree falls back to full `_materialize()`.

`hydrate()` is the right choice when the server has already emitted HTML for a component. The `snapshot` parameter is the pre-parsed JSON state previously emitted by `MountScope.serialize()` (typically injected as `window.__aihu_state__[tag]` by the SSR renderer).

```typescript
import { hydrate } from '@aihu/arbor'

// In the browser, for an SSR-rendered island:
const scope = hydrate(
  () => buildCounterTree(),
  document.querySelector('live-counter'),
  window.__aihu_state__['live-counter'] ?? {},
)
```

## Client-build elision

When target is `client`:

- `@agent` blocks are removed from the output. The JS contains: `// [client build] @agent block elided`.
- `$server` macro references are removed. The JS contains: `// [client build] $server macro reference elided`.
- `manifest_json` in `EmitResult` is empty.

This ensures zero server-only code reaches the browser bundle.

---

# Agent Discovery & MCP Compliance

aihu is designed from the ground up for the agentic web. Every aihu application automatically exposes standard discovery endpoints that let AI agents find, understand, and call your components as tools — with no manual configuration.

## How AI agents discover aihu apps

Aihu apps expose four discovery endpoints that agents and crawlers check:

| Endpoint | Purpose |
|---|---|
| `/llms.txt` | Human-readable index of docs and links in llmstxt.org format |
| `/llms-full.txt` | Extended index with full package list, examples, and spec links |
| `/.well-known/mcp/server-card.json` | Machine-readable MCP server card (SEP-1649) |
| `/robots.txt` | Agent-friendly crawl directives (RFC 9309) |

All four are generated automatically by `@aihu-plugin/agent-readiness` from a single config object. The minimum viable setup is:

```ts
import { createAgentReadinessRoutes } from '@aihu-plugin/agent-readiness'
import { createRequestRouter, defineRoute } from '@aihu/server'

const ar = createAgentReadinessRoutes({
  name: 'My App',
  endpoint: 'https://myapp.workers.dev/mcp',
  summary: 'A aihu-powered app.',
})

const router = createRequestRouter({
  routes: [
    defineRoute('/llms.txt', ar.llmsTxt),
    defineRoute('/.well-known/mcp/server-card.json', ar.mcpServerCard),
    defineRoute('/robots.txt', ar.robotsTxt),
  ],
})
```

This works on Cloudflare Workers, Bun, and Deno — anywhere with a fetch-API request handler.

## The MCP Server Card

The MCP Server Card is a machine-readable JSON document at `/.well-known/mcp/server-card.json` that describes your application's agent capabilities per the SEP-1649 schema.

A minimal server card looks like:

```json
{
  "schema_version": "1.0",
  "name": "My App",
  "summary": "A aihu-powered app.",
  "mcp_endpoint": "https://myapp.workers.dev/mcp",
  "skills": [
    {
      "id": "my-counter",
      "name": "Live Counter",
      "description": "Read and increment a counter"
    }
  ]
}
```

The `skills` array is auto-populated from the `@agent` blocks in your SFCs — the compiler emits an MCP tool schema alongside each compiled component, and `@aihu-plugin/agent-readiness` aggregates them at build time.

To configure the server card, pass `AgentReadinessConfig` to `createAgentReadinessRoutes`:

```ts
const ar = createAgentReadinessRoutes({
  name: 'My App',
  version: '1.0.0',
  summary: 'A aihu-powered app.',
  endpoint: 'https://myapp.workers.dev/mcp',
  // Optional: declare skills explicitly (merged with auto-derived from @agent blocks)
  skills: [
    { id: 'counter', name: 'Counter', description: 'Read and set counter value' },
  ],
})
```

### Auth configuration (opt-in)

By default the MCP endpoint is public (no-auth, Option A). To require OAuth 2.0 (Option C per RFC 9728):

```ts
const ar = createAgentReadinessRoutes({
  name: 'My App',
  endpoint: 'https://myapp.workers.dev/mcp',
  auth: {
    type: 'oauth2',
    authorizationUrl: 'https://auth.myapp.com/authorize',
    tokenUrl: 'https://auth.myapp.com/token',
    scopes: ['mcp:read', 'mcp:write'],
  },
})
```

## llms.txt

The `llms.txt` file at the app root follows the [llmstxt.org](https://llmstxt.org) specification. It gives AI coding assistants a structured map of your app's documentation and endpoints.

### Format

The file uses a small Markdown subset:

- First line: `# <Name>` (H1 heading — the app name)
- Optional second non-blank line: `> <tagline>` (blockquote summary)
- Sections: `## <Section Title>` (H2 headings)
- Links: `- [Title](URL)` or `- [Title](URL): Optional description`
- An optional `## Optional` section at the end (for supplementary links)

The `llms-full.txt` variant follows the same format but uses `## More` instead of `## Optional` for the trailing section, and typically includes more links (all packages, examples, spec files).

### LlmsTxtConfig type

`@aihu-plugin/agent-readiness` generates both files from `LlmsTxtConfig`:

```ts
interface LlmsTxtLink {
  readonly title: string
  readonly url: string
  readonly description?: string
}

interface LlmsTxtSection {
  readonly title: string
  readonly links: ReadonlyArray<LlmsTxtLink>
}

interface LlmsTxtConfig {
  readonly name: string
  readonly summary?: string
  readonly sections: ReadonlyArray<LlmsTxtSection>
  readonly optional?: ReadonlyArray<LlmsTxtLink>
}
```

To generate the files programmatically:

```ts
import { generateLlmsTxt, generateLlmsFullTxt } from '@aihu-plugin/agent-readiness'

const config: LlmsTxtConfig = {
  name: 'My App',
  summary: 'A aihu-powered app.',
  sections: [
    {
      title: 'Getting Started',
      links: [
        { title: 'Installation', url: 'https://myapp.com/docs/install' },
        { title: 'Quickstart', url: 'https://myapp.com/docs/quickstart' },
      ],
    },
  ],
  optional: [
    { title: 'Contributing', url: 'https://github.com/org/myapp/blob/main/CONTRIBUTING.md' },
  ],
}

const llmsTxt = generateLlmsTxt(config)      // uses "## Optional"
const llmsFullTxt = generateLlmsFullTxt(config) // uses "## More"
```

The `llmsSections` and `llmsOptional` fields on `AgentReadinessConfig` feed directly into these generators, so you can customize the content without calling the generators manually.

## robots.txt

Aihu generates an agent-friendly `robots.txt` per RFC 9309. The default (`aiAgents: 'allow-all'`) produces directives that permit all compliant AI agents to crawl your app:

```
User-agent: *
Allow: /

User-agent: GPTBot
Allow: /

User-agent: ClaudeBot
Allow: /

User-agent: anthropic-ai
Allow: /
```

To restrict AI agent access, set `aiAgents: 'disallow-all'` or `aiAgents: 'allow-verified'`. You can also add custom rules for specific bots via `standardBots`:

```ts
const ar = createAgentReadinessRoutes({
  name: 'My App',
  endpoint: 'https://myapp.workers.dev/mcp',
  aiAgents: 'allow-all',
  standardBots: [
    { userAgent: 'Googlebot', allow: ['/'], disallow: ['/admin'] },
  ],
  sitemap: 'https://myapp.com/sitemap.xml',
})
```

## Calling aihu components as MCP tools

Agent-callable components are the core proposition of aihu. Here is the end-to-end flow:

**Step 1 — Declare an agent surface in the SFC**

Add an `@agent` block and expose actions from `@state`:

```
@state {
  $prop: {
    count: { default: 0, type: "number", expose: { read: true } }
  }

  $action: {
    increment: {
      describe: "Increment the counter by one",
      expose: { write: true },
      handler: () => setCount(count() + 1),
    },
  }
}

@agent {
  $describe: "A simple counter component"
}
```

**Step 2 — Compiler emits `.mcp.json`**

When the Rust SFC compiler processes this file with `BuildTarget.Server` or `BuildTarget.Universal`, it emits a `.mcp.json` sidecar describing the exposed tools:

```json
{
  "tools": [
    {
      "name": "increment",
      "description": "Increment the counter by one",
      "inputSchema": { "type": "object", "properties": {} }
    }
  ],
  "resources": [
    { "name": "count", "description": "Current counter value", "type": "number" }
  ]
}
```

Note: with `BuildTarget.Client`, the `@agent` block is fully elided — no manifest JSON is emitted and no agent code reaches the browser bundle.

**Step 3 — `@aihu/agent-service` exposes via `aihu mcp serve`**

The `@aihu/agent-service` package reads the aggregated tool schemas and exposes them over the MCP protocol. Run:

```bash
aihu mcp serve
```

This starts an MCP-compatible server that AI agents (Claude, GPT, Gemini, etc.) can connect to and call your component actions as tools.

**Step 4 — Live-binding connects tools to the running component**

When an AI agent calls the `increment` tool, `@aihu/agent-service` uses the live-binding registry (RFC APPROVED) to find the running component instance and call the action against its actual signal graph — the UI updates in real time.

## Testing compliance

All compliance checks are backed by vitest test suites that run as part of `bun run test`. The test files serve as the executable specification:

| Suite | File | Tests |
|---|---|---|
| llms.txt format | `packages/plugin-agent-readiness/tests/compliance/llms-txt-spec.test.ts` | 9 |
| MCP Server Card (SEP-1649) | `packages/plugin-agent-readiness/tests/compliance/mcp-server-card-schema.test.ts` | 14 |
| robots.txt (RFC 9309) | `packages/plugin-agent-readiness/tests/compliance/robots-rfc9309.test.ts` | 7 |
| isitagentready.com checklist | `packages/plugin-agent-readiness/tests/compliance/isitagentready.test.ts` | 7 |
| SSR output structure | `packages/server/tests/compliance/ssr-output.test.ts` | 12 |

Run all compliance checks:

```bash
bun run test       # TS + Rust unit, integration, and compliance suites
bun run test:quality   # Lighthouse gate (≥ 90 on perf/a11y/best-practices/seo)
```

## isitagentready.com

Aihu passes all 7 checks on [isitagentready.com](https://isitagentready.com). The checks are exercised by the compliance test suite at `packages/plugin-agent-readiness/tests/compliance/isitagentready.test.ts`. The seven gates are:

1. `llms.txt` present at root
2. `llms.txt` first line is `# <Name>`
3. `/.well-known/mcp/server-card.json` returns valid JSON
4. MCP server card contains `mcp_endpoint`
5. `robots.txt` present and allows AI agents
6. App sets `X-Agent-Friendly: true` response header
7. MCP endpoint responds to `POST` with a valid tool-list response

---

# Authoring Plugins

aihu plugins extend the compiler with new blocks, macros, component boundaries, and transforms. Every plugin must be explicitly registered — auto-discovery is forbidden per Plugin Contract Spec §7.2.

---

## Defining a plugin

Use `definePlugin` from `@aihu/plugin`:

```typescript
import { definePlugin } from '@aihu/plugin'

export default definePlugin({
  name: 'forms',
  version: '0.1.0',
  namespace: 'forms',
  aihuVersion: '^0.2.0',
  contributes: {
    blocks: ['fields'],
    macros: [
      {
        name: '$field',
        validIn: ['@forms.fields'],
        lowering: lowerField,
        validation: validateField,
      },
    ],
    components: ['<$forms-input>'],
    transforms: [
      { stage: 'after-parse', fn: normalizeFieldDefaults },
    ],
  },
})
```

`definePlugin` brands the config with `__aihu_plugin: true` and returns it as a `Plugin`. It does NOT validate — validation happens at registration (see below).

### Required fields

| Field | Type | Description |
|---|---|---|
| `name` | `string` | Plugin identifier. Non-empty. |
| `version` | `string` | Semver version string. Non-empty. |
| `namespace` | `string` | Unique namespace — alphanumeric, underscores, hyphens; must start with a letter or underscore. |

### Optional fields

| Field | Type | Description |
|---|---|---|
| `aihuVersion` | `string` | Semver range of compatible aihu versions. Checked at registration. Supports `*`, `^`, `~`, and exact versions. |
| `configSchema` | `ConfigSchema` | Declared configuration schema (per spec §3.1). |
| `contributes` | `Contributes` | Block parsers, macros, component names, transforms, server runtime, middleware. |
| `hooks` | `Hooks` | Build and compilation lifecycle hooks. |
| `parsers` | `Record<string, BlockParser>` | Custom block parser functions. |
| `dependencies` | `string[]` | Other plugin namespaces this plugin requires. |
| `serverOnly` | `boolean` | When true, all contributions target the server bundle only. |

### Reserved namespaces

These namespace values are reserved by aihu and MUST NOT be used: `aihu`, `core`, `state`, `template`, `style`, `agent`, `route`.

---

## `contributes` fields

### `blocks`

Declare additional `@blockname { }` block types this plugin handles. The compiler routes these block names to the plugin's parsers.

```typescript
contributes: {
  blocks: ['fields', 'validation'],
}
```

### `macros`

Declare `$macro` names this plugin contributes to specific blocks. Each macro definition requires:

- `name` — must start with `$`
- `validIn` — array of block selectors where the macro is permitted (e.g. `['@state', '@forms.fields']`)
- `lowering` — required; transforms the macro into emitted code
- `validation` — optional; runs at parse time, calls `ctx.error(msg)` on failure

```typescript
contributes: {
  macros: [
    {
      name: '$field',
      validIn: ['@forms.fields'],
      lowering: (ctx, args) => `registerField(${JSON.stringify(args)})`,
      validation: (ctx, args) => {
        if (!args.name) ctx.error('$field requires a name')
      },
    },
  ],
}
```

### `components`

Declare special template elements (e.g. `<$forms-input>`) this plugin provides.

```typescript
contributes: {
  components: ['<$forms-input>', '<$forms-select>'],
}
```

### `transforms`

Build-time AST transform functions. Three stages in order: `after-parse` → `before-lower` → `after-lower`. Within a stage, plugin registration order determines execution order.

```typescript
contributes: {
  transforms: [
    { stage: 'after-parse', fn: normalizeDefaults },
    { stage: 'after-lower', fn: injectValidationRuntime },
  ],
}
```

A transform function receives the current AST node and returns the (optionally modified) AST node.

### `serverRuntime`

Server-only runtime helpers. Keys are helper names; values are module paths relative to the plugin root. These are loaded into the server bundle only, never the client.

```typescript
contributes: {
  serverRuntime: {
    validateForm: './runtime/validate-form.ts',
    sanitizeInput: './runtime/sanitize.ts',
  },
}
```

### `middleware`

Server middleware contributions (PROVISIONAL in v1.0). Declare middleware to be injected into the aihu server pipeline.

```typescript
contributes: {
  middleware: [
    {
      name: 'forms-auth',
      stage: 'before-handler',
      handler: './middleware/auth.ts',
    },
  ],
}
```

Valid stages: `before-handler`, `after-handler`, `on-error`.

---

## Macro lowering

The `lowering` function transforms a macro invocation into emitted code. It receives a `MacroContext` and `MacroArgs`, and returns either a code string (simple case) or a `LoweringResult` (complex emission with imports and hoisted declarations).

```typescript
import type { MacroLowering, LoweringResult } from '@aihu/plugin'

const lowerField: MacroLowering = (ctx, args) => {
  // Simple: return a code string
  return `registerField(${ctx.sfc.componentName}, ${JSON.stringify(args)})`
}

const lowerFieldWithImports: MacroLowering = (ctx, args): LoweringResult => {
  const registerField = ctx.imports('@forms/runtime')
  return {
    code: `${registerField}(${JSON.stringify(args)})`,
    imports: [{ from: '@forms/runtime', names: ['registerField'] }],
    target: 'server', // emit to server bundle only
  }
}
```

`ctx.imports(spec)` returns the local name to use in emitted code. `ctx.runtime(name)` requests a runtime helper by name.

---

## Plugin lifecycle hooks

Hooks let plugins observe and transform the compilation pipeline.

```typescript
import type { Hooks } from '@aihu/plugin'

const hooks: Hooks = {
  beforeCompile: async (ctx) => {
    // Runs once before the full build starts
    console.log(`Building in ${ctx.mode} mode`)
  },

  afterParse: async (ctx, ast) => {
    // Runs after each SFC is parsed; may return a modified AST
    return transformAst(ast)
  },

  transformBlock: async (ctx, block) => {
    // Runs for each block in each SFC; may return modified block AST
    if (ctx.blockType === 'forms.fields') {
      return normalizeFieldBlock(block)
    }
  },

  afterCompile: async (ctx, output) => {
    // Runs after each SFC is compiled; may return modified output
    return injectValidationHelpers(output)
  },
}
```

---

## `serverOnly` plugin

Set `serverOnly: true` to mark a plugin as server-build only. The client build pipeline skips it entirely. Client code that references server-only contributions receives RPC stubs instead of the real implementation.

```typescript
export const loaderPlugin = definePlugin({
  name: 'loader-plugin',
  version: '1.0.0',
  namespace: 'loader',
  serverOnly: true,
  contributes: {
    transforms: [{ stage: 'after-lower', fn: serverLoaderTransform }],
    serverRuntime: { fetchLoader: './runtime/fetch-loader.ts' },
  },
})
```

Individual macros may also declare `serverOnly: true` without making the entire plugin server-only.

---

## Validating a plugin

Call `validatePlugin(plugin)` at build time to verify the plugin definition is structurally correct. `validatePlugin` does NOT throw — it returns a `ValidationResult`.

```typescript
import { validatePlugin } from '@aihu/plugin'

const result = validatePlugin(myPlugin)
if (!result.ok) {
  for (const err of result.errors) {
    console.error(`[${err.code}] ${err.message}`)
  }
  process.exit(1)
}
```

Error codes per spec §8.1:

| Code | Condition |
|---|---|
| `missing-required-field` | `name`, `version`, or `namespace` is empty |
| `invalid-namespace` | Namespace contains illegal characters or starts with a digit |
| `reserved-namespace` | Namespace is one of the reserved values |
| `duplicate-namespace` | Two plugins share the same namespace in one registration pass |
| `aihu-version-mismatch` | Declared `aihuVersion` range is incompatible with the running framework |

The compiler calls `validatePlugin` for each plugin in `defineAihuConfig.plugins` at registration time.

---

## Registering a plugin

Plugins are registered in `defineAihuConfig` in your app's config file:

```typescript
// aihu.config.ts
import { defineAihuConfig } from '@aihu/server'
import { formsPlugin } from './plugins/forms.ts'
import { analyticsPlugin } from './plugins/analytics.ts'

export default defineAihuConfig({
  plugins: [formsPlugin, analyticsPlugin],
  build: {
    target: 'universal',
  },
})
```

Per Plugin Contract Spec §7.2, plugins **must** be listed in the explicit `plugins` array. There is no filesystem scanning, package.json detection, or magic import resolution. This keeps build behavior deterministic and auditable.

---

## Plugin lifecycle (full sequence)

1. `defineAihuConfig` collects all plugins.
2. At build start, `validatePlugin` is called for each registered plugin. Any error aborts the build.
3. `beforeCompile` hooks run once (parallel, then resolved in order).
4. For each `.aihu` file:
   a. The Rust compiler parses blocks. Plugin-declared block names are routed to plugin parsers.
   b. `afterParse` hooks run (sequential, each receives the previous hook's return value).
   c. Macro lowering runs (plugin macros call their `lowering` function).
   d. `transformBlock` hooks run for each block.
   e. `afterCompile` hooks run.
5. Server-only plugins are filtered out before the client build pipeline.
6. `contributes.transforms` are applied as post-parse AST passes in stage order.

---

## Scaffolding a plugin

Use the CLI to scaffold a new plugin package:

```bash
aihu plugin my-plugin
```

This creates:

```
packages/my-plugin/
  package.json               name: "@myorg/aihu-plugin-my-plugin"
                             peerDependencies: { "@aihu/plugin": "^0.2.0" }
  src/
    index.ts                 definePlugin(...) export
    lowering/                macro lowering functions
    transforms/              AST transform functions
  tests/
    plugin.test.ts           validatePlugin smoke test
```

---

## Publishing a plugin

A published aihu plugin package must:

1. List `@aihu/plugin` as a `peerDependency` (not `dependency`):

   ```json
   {
     "peerDependencies": {
       "@aihu/plugin": "^0.2.0"
     }
   }
   ```

2. Export a named `Plugin` instance as the default or named export:

   ```typescript
   // src/index.ts
   import { definePlugin } from '@aihu/plugin'
   export default definePlugin({ ... })
   ```

3. Include only the plugin definition, lowering functions, and transforms. Do not bundle `@aihu/plugin` itself — it is the host's responsibility.

4. Name the package `aihu-plugin-<name>` or `@scope/aihu-plugin-<name>` for discoverability.

Consumers install and register the plugin explicitly:

```typescript
import { defineAihuConfig } from '@aihu/server'
import formsPlugin from 'aihu-plugin-forms'

export default defineAihuConfig({
  plugins: [formsPlugin],
})
```

No magic imports. No auto-discovery. Explicit registration is the contract.

---

# @aihu/context

Zero-dependency, DOM-free context system. Provides a React-style context API for passing values through a call tree without explicit prop-drilling, with first-class SSR support via per-request context maps.

## Install

```bash
npm install @aihu/context
# or
bun add @aihu/context
```

## API overview

| Name | Kind | Description |
|------|------|-------------|
| `createContext` | function | Create a typed context token with optional default |
| `provide` | function | Write a value into the active context map |
| `inject` | function | Read a value from the active context map |
| `setSsrContextMap` | function | Set the active context map (SSR entry point) |
| `clearSsrContextMap` | function | Clear the active context map (SSR teardown) |
| `runWithContext` | function | Run a function with an isolated context map |
| `ContextToken` | interface | Opaque token identifying a context slot |

## Functions

### createContext

```typescript
function createContext<T>(defaultValue?: T): ContextToken<T>
```

Creates a new opaque context token. The token is used with `provide` and `inject` to write and read values. Each call to `createContext` produces a unique token — two tokens created with identical default values are not interchangeable.

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `defaultValue` | `T` | No | Value returned by `inject` when no explicit value has been provided. Defaults to `undefined`. |

**Returns** `ContextToken<T>` — a new unique context token.

---

### provide

```typescript
function provide<T>(token: ContextToken<T>, value: T): void
```

Writes `value` into the currently active context map under `token`. If no context map is active (i.e., `setSsrContextMap` or `runWithContext` has not been called), this is a no-op.

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `token` | `ContextToken<T>` | Yes | The token identifying the context slot. |
| `value` | `T` | Yes | The value to store. |

**Returns** `void`

---

### inject

```typescript
function inject<T>(token: ContextToken<T>): T | undefined
```

Reads the value associated with `token` from the active context map. Falls back to `token._default` if no entry exists for the token or if no map is active.

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `token` | `ContextToken<T>` | Yes | The token identifying the context slot to read. |

**Returns** `T | undefined` — the stored value, or `token._default` if absent.

---

### setSsrContextMap

```typescript
function setSsrContextMap(map: Map<symbol, unknown>): void
```

Sets the module-level active context map. Any subsequent calls to `provide` or `inject` will read from and write to this map. Replaces any previously active map. Prefer `runWithContext` in most SSR scenarios — it guarantees cleanup even on thrown errors.

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `map` | `Map<symbol, unknown>` | Yes | The context map to activate. |

**Returns** `void`

---

### clearSsrContextMap

```typescript
function clearSsrContextMap(): void
```

Clears the active context map, setting it to `null`. Called automatically by `runWithContext` in its `finally` block. Call manually after `setSsrContextMap` if you are not using `runWithContext`.

**Returns** `void`

---

### runWithContext

```typescript
function runWithContext<R>(map: Map<symbol, unknown>, fn: () => R): R
```

Sets `map` as the active context map, executes `fn()`, then clears the map in a `finally` block — even if `fn` throws. This is the recommended SSR entry point: each request gets its own `Map`, making context leakage between concurrent requests impossible.

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `map` | `Map<symbol, unknown>` | Yes | A per-request context map, typically `new Map()`. |
| `fn` | `() => R` | Yes | The function to execute inside the context. |

**Returns** `R` — the return value of `fn()`.

## Types

### ContextToken

```typescript
interface ContextToken<T> {
  readonly _id: symbol
  readonly _default: T | undefined
}
```

Opaque token returned by `createContext`. The `_id` symbol is unique per token and is used as the map key internally. The `_default` field holds the fallback value supplied to `createContext`. Treat both fields as read-only internals — do not construct `ContextToken` objects manually.

**Fields**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `_id` | `symbol` | Yes | Unique symbol key for this context slot. |
| `_default` | `T \| undefined` | Yes | Default value when no explicit value is provided. |

## Subpath exports

### ./ssr

```typescript
import { setSsrContextMap, clearSsrContextMap, runWithContext } from '@aihu/context/ssr'
```

Re-exports only the three SSR-specific functions: `setSsrContextMap`, `clearSsrContextMap`, and `runWithContext`. Use this subpath in server entry files to make the SSR intent explicit and to tree-shake `createContext`, `provide`, and `inject` from your server bundle if they are not needed there.

The `./ssr` subpath does **not** export `createContext`, `provide`, `inject`, or `ContextToken`. Import those from `@aihu/context` (the main entry).

## Usage

### Client-side: passing a theme value

```typescript
import { createContext, provide, inject } from '@aihu/context'

// Define a token once, export it for shared use
export const ThemeToken = createContext<'light' | 'dark'>('light')

// In a parent scope — set the value before rendering children
provide(ThemeToken, 'dark')

// In a child scope — read the value
const theme = inject(ThemeToken) // 'dark'
```

### SSR: per-request context isolation

```typescript
import { createContext, provide, inject, runWithContext } from '@aihu/context'

export const RequestIdToken = createContext<string>()

async function handleRequest(requestId: string): Promise<string> {
  const ctx = new Map<symbol, unknown>()
  return runWithContext(ctx, () => {
    provide(RequestIdToken, requestId)
    // Any code called here can inject(RequestIdToken)
    return inject(RequestIdToken) ?? 'unknown'
  })
}
```

---

# @aihu/agent-a2a

Wraps an `AgentService` with Agent-to-Agent (A2A) protocol routes. The adapter exposes a discovery card and task-dispatch endpoints that comply with the A2A wire format, and integrates with any fetch-API server via a single middleware function.

## Install

```bash
npm install @aihu/agent-a2a
# or
bun add @aihu/agent-a2a
```

`@aihu/agent-service` is a required peer dependency — install it alongside this package.

## API overview

| Name | Kind | Description |
|------|------|-------------|
| `mountA2aAdapter` | function | Create an A2A adapter around an AgentService |
| `A2aAdapter` | interface | Object returned by `mountA2aAdapter` |
| `A2aAdapterOptions` | interface | Options accepted by `mountA2aAdapter` |

## Functions

### mountA2aAdapter

```typescript
function mountA2aAdapter(
  service: AgentService,
  options?: A2aAdapterOptions,
): A2aAdapter
```

Creates an A2A adapter that wraps the given `AgentService`. The returned `A2aAdapter` exposes an `asMiddleware()` method that returns a fetch-API handler function. Calling `asMiddleware()` multiple times on the same adapter is safe — each call returns a new handler closure over the same service and options.

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `service` | `AgentService` | Yes | The agent service instance to wrap. Obtained from `createAgentService` in `@aihu/agent-service`. |
| `options` | `A2aAdapterOptions` | No | Optional configuration. See `A2aAdapterOptions`. |

**Returns** `A2aAdapter` — the configured adapter.

## Types

### A2aAdapter

```typescript
interface A2aAdapter {
  asMiddleware(): (req: Request) => Promise<Response | null>
}
```

The object returned by `mountA2aAdapter`. Call `asMiddleware()` to obtain a handler that processes incoming requests. The handler returns a `Response` for any path it owns, and `null` for paths it does not recognize — allowing you to chain multiple adapters or fall through to a 404 handler.

**Fields**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `asMiddleware` | `() => (req: Request) => Promise<Response \| null>` | Yes | Returns a fetch-API middleware function. |

---

### A2aAdapterOptions

```typescript
interface A2aAdapterOptions {
  prefix?: string
  name?: string
}
```

Configuration options for `mountA2aAdapter`.

**Fields**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `prefix` | `string` | No | URL prefix prepended to all route paths. Default: `''`. |
| `name` | `string` | No | Agent name included in the discovery card response. Default: `'aihu-agent-service'`. |

## Routes

The middleware returned by `asMiddleware()` owns the following paths (relative to `prefix`):

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/.well-known/agent.json` | A2A agent discovery card. Returns JSON with `name`, `version`, `capabilities`, and a `skills` array derived from the service manifest. |
| `POST` | `/a2a/tasks/send` | Submit a task. Body: `{ taskId?, message: string, params? }`. Returns JSON `{ taskId, status, result \| error }`. |
| `POST` | `/a2a/tasks/sendSubscribe` | Submit a task with SSE streaming response. Same request body as `/a2a/tasks/send`. Returns `text/event-stream` ending with `data: [DONE]`. |

All paths not matching one of these three return `null` from the middleware.

## Usage

```typescript
import { createAgentService } from '@aihu/agent-service'
import { getAllAgentMetadata } from '@aihu/agent'
import { mountA2aAdapter } from '@aihu/agent-a2a'
import { defineRoute, createRequestRouter, notFound } from '@aihu/server'

const service = createAgentService({
  manifests: getAllAgentMetadata(),
})

const a2a = mountA2aAdapter(service, {
  prefix: '',
  name: 'my-app',
})

const router = createRequestRouter({
  routes: [
    defineRoute('/*', async (req) => {
      const res = await a2a.asMiddleware()(req)
      return res ?? notFound()
    }),
  ],
})

export default router
```

The `prefix` option is useful when mounting the adapter under a path namespace, e.g. `prefix: '/api'` shifts all routes to `GET /api/.well-known/agent.json`, `POST /api/a2a/tasks/send`, and `POST /api/a2a/tasks/sendSubscribe`.

---

# @aihu/agent-acp

Wraps an `AgentService` with Agent Communication Protocol (ACP) routes. The adapter exposes a discovery card and a message-routing endpoint that comply with the ACP wire format, and integrates with any fetch-API server via a single middleware function.

## Install

```bash
npm install @aihu/agent-acp
# or
bun add @aihu/agent-acp
```

`@aihu/agent-service` is a required peer dependency — install it alongside this package.

## API overview

| Name | Kind | Description |
|------|------|-------------|
| `mountAcpAdapter` | function | Create an ACP adapter around an AgentService |
| `AcpAdapter` | interface | Object returned by `mountAcpAdapter` |
| `AcpAdapterOptions` | interface | Options accepted by `mountAcpAdapter` |
| `AcpMessage` | interface | Minimal ACP message shape consumed by the adapter |

## Functions

### mountAcpAdapter

```typescript
function mountAcpAdapter(
  service: AgentService,
  options?: AcpAdapterOptions,
): AcpAdapter
```

Creates an ACP adapter that wraps the given `AgentService`. The returned `AcpAdapter` exposes an `asMiddleware()` method that returns a fetch-API handler function. Tool name resolution checks `parts[0].content.tool` first, then falls back to the `content` string of the incoming `AcpMessage`.

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `service` | `AgentService` | Yes | The agent service instance to wrap. Obtained from `createAgentService` in `@aihu/agent-service`. |
| `options` | `AcpAdapterOptions` | No | Optional configuration. See `AcpAdapterOptions`. |

**Returns** `AcpAdapter` — the configured adapter.

## Types

### AcpAdapter

```typescript
interface AcpAdapter {
  asMiddleware(): (req: Request) => Promise<Response | null>
}
```

The object returned by `mountAcpAdapter`. Call `asMiddleware()` to obtain a handler that processes incoming requests. Returns a `Response` for paths it owns, and `null` for unrecognized paths — allowing chaining with other adapters or a fallthrough 404 handler.

**Fields**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `asMiddleware` | `() => (req: Request) => Promise<Response \| null>` | Yes | Returns a fetch-API middleware function. |

---

### AcpAdapterOptions

```typescript
interface AcpAdapterOptions {
  prefix?: string
  agentId?: string
}
```

Configuration options for `mountAcpAdapter`.

**Fields**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `prefix` | `string` | No | URL prefix prepended to all route paths. Default: `''`. |
| `agentId` | `string` | No | Agent identifier included in the discovery card response. Default: `'aihu-agent-service'`. |

---

### AcpMessage

```typescript
interface AcpMessage {
  role: string
  content: string
  parts?: Array<{ type: string; content: unknown }>
}
```

The minimal ACP message shape expected by the `POST /acp/messages` endpoint. The adapter reads the tool name from `parts[0].content.tool` when present; otherwise it uses `content` as the tool name directly.

**Fields**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `role` | `string` | Yes | Message role (e.g. `'user'`). |
| `content` | `string` | Yes | Tool name fallback — used when `parts[0].content.tool` is absent or empty. |
| `parts` | `Array<{ type: string; content: unknown }>` | No | Optional message parts. When present, `parts[0].content.tool` is checked first for the tool name. |

## Routes

The middleware returned by `asMiddleware()` owns the following paths (relative to `prefix`):

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/.well-known/acp-agent` | ACP agent discovery card. Returns JSON with `agent_id`, `description`, and a `skills` array derived from the service manifest. |
| `POST` | `/acp/messages` | ACP message routing. Accepts an `AcpMessage` body. Resolves tool name from `parts[0].content.tool` first, then from `content`. Returns `{ role: 'agent', content, parts }`. |

All paths not matching one of these two return `null` from the middleware.

## Usage

```typescript
import { createAgentService } from '@aihu/agent-service'
import { getAllAgentMetadata } from '@aihu/agent'
import { mountAcpAdapter } from '@aihu/agent-acp'
import { defineRoute, createRequestRouter, notFound } from '@aihu/server'

const service = createAgentService({
  manifests: getAllAgentMetadata(),
})

const acp = mountAcpAdapter(service, {
  prefix: '',
  agentId: 'my-app',
})

const router = createRequestRouter({
  routes: [
    defineRoute('/*', async (req) => {
      const res = await acp.asMiddleware()(req)
      return res ?? notFound()
    }),
  ],
})

export default router
```

### Combining A2A and ACP adapters

Both adapters can coexist on the same service instance, checked in order:

```typescript
import { mountA2aAdapter } from '@aihu/agent-a2a'
import { mountAcpAdapter } from '@aihu/agent-acp'

const a2a = mountA2aAdapter(service)
const acp = mountAcpAdapter(service)

const mw = async (req: Request): Promise<Response> =>
  (await a2a.asMiddleware()(req)) ??
  (await acp.asMiddleware()(req)) ??
  notFound()
```

---

# @aihu/cli

Build-time CLI scaffolder for aihu applications. Zero runtime size impact — it is a
dev/build-time tool only and is never included in browser bundles.

## Prerequisites

- Bun ≥ 1.3.0 (or Node.js ≥ 20.18.0)
- A terminal in your project directory

## Quick start — `aihu app`

```bash
npx aihu app my-app
cd my-app
bun install
bun run dev
```

This creates:

```
my-app/
  package.json              # all @aihu/* deps pre-wired
  aihu.config.ts          # defineAihuConfig with target: 'universal'
  vite.config.ts            # viteRouterIntegration + viteAgentReadinessIntegration
  src/
    pages/
      index.aihu          # Hello World page with @state, @template, @route
    layouts/
      default.aihu        # default layout with <slot />
```

## Scaffold commands

### `aihu app <name>`

Scaffold a new application with all aihu integrations wired.

```bash
aihu app my-store
```

Output:
```
✓ Created my-store/
  cd my-store
  bun install
  bun run dev
```

### `aihu page <route>`

Add a page to an existing project. Run from the project root.

```bash
aihu page about
```

Creates `src/pages/about.aihu`:
```
@state {
}

@template {
  <div>about page</div>
}

@route {
  path: /about
  name: about
}
```

### `aihu component <name>`

Scaffold a `.aihu` component.

```bash
aihu component Button
```

Creates `src/components/Button.aihu`:
```
@state {
}

@template {
  <div>Button</div>
}
```

### `aihu plugin <name>`

Scaffold a plugin package skeleton. Creates `<name>/` with a wired `definePlugin` entry.

```bash
aihu plugin my-forms
```

Creates:
```
my-forms/
  package.json    # peerDependencies: { "@aihu/plugin": "latest" }
  src/
    index.ts      # definePlugin({ name, namespace, contributes: {} })
```

### `aihu migrate [files...]`

Mechanically rewrite legacy v0.1.x SFC syntax to the v1.0 canonical forms. The
command runs three passes in order — block framing (v1.0.7), inline attribute
bindings (v1.0.8 / Amendment 04), and package-name renames (v1.0.9 / Naming
Scheme A) — and is idempotent (running it twice produces the same output as
running it once).

```bash
aihu migrate src/components/Counter.aihu
aihu migrate --dry-run src/**/*.aihu
```

Use `--dry-run` to preview changes without writing files.

#### Pass 1 — block framing (v1.0.7)

Convert HTML-tag SFC framing to `@blockname {}` syntax.

| v0.1.x HTML-tag syntax | v1.0 `@blockname` syntax |
|------------------------|--------------------------|
| `<script setup>`       | `@state {`               |
| `<template>`           | `@template {`            |
| `<style>`              | `@style {`               |
| `<agent>`              | `@agent {`               |

#### Pass 2 — inline attribute bindings (v1.0.8 / Amendment 04)

Rewrite the legacy Vue-shape and plain-curly attribute bindings to the
always-`$`-prefixed canonical form. Component prop-passing on capitalized
component tags (`<UserCard user={u} />`) and XML namespace prefixes (`xmlns:`,
`xlink:`) are preserved untouched.

| Legacy form        | v1.0 canonical form                       |
|--------------------|-------------------------------------------|
| `:attr="expr"`     | `$attr={expr}` (or `$bind.attr=` two-way) |
| `@event="fn"`      | `$on.event="fn"` (dot-form per B3c)       |
| `attr={expr}`      | `$attr={expr}`                            |

#### Pass 3 — package-name renames (v1.0.9 / Naming Scheme A)

The two Plugin Contract packages moved out of the framework-core `@aihu/*`
scope into the `@aihu-plugin/*` scope. The migrate tool rewrites `package.json`
dependency keys, static `import`/`export` statements, dynamic `import()` calls,
and JSDoc/Markdown URL references. Core packages (`@aihu/signals`,
`@aihu/arbor`, `@aihu/runtime`, `@aihu/router`, etc.) are NOT renamed.

| Legacy import           | v1.0.9 import                  |
|-------------------------|--------------------------------|
| `@aihu/data`            | `@aihu-plugin/data`            |
| `@aihu/agent-readiness` | `@aihu-plugin/agent-readiness` |

#### Error codes

The v1.0 cutover rejects each legacy form as a hard parse error (no
deprecation-with-warning period). When the compiler reports one of these codes,
run `npx aihu migrate <file>` to obtain the mechanical rewrite.

| Code | Rejected form                                                              | Removed in | Canonical migration target                              |
|------|----------------------------------------------------------------------------|------------|---------------------------------------------------------|
| C107 | `<script setup>` / `<template>` / `<style>` / `<agent>` HTML-tag SFC framing | v1.0.7     | `@state { … }` / `@template { … }` / `@style { … }` / `@agent { … }` |
| C304 | `:attr="expr"` Vue-shape one-way binding alias                              | v1.0.8     | `$attr={expr}` (or `$bind.attr=` for two-way)           |
| C305 | `@event="fn"` Vue-shape event alias                                         | v1.0.8     | `$on.event="fn"` (dot-form)                             |
| C306 | `attr={expr}` plain-curly HTML attribute binding (no `$`)                   | v1.0.8     | `$attr={expr}`                                          |

## Dev → build → preview cycle

```bash
# Start development server
bun run dev

# Production build
bun run build

# Preview production build locally
bun run preview
```

## Programmatic API

All scaffold functions are exported for use in build scripts:

```ts
import {
  scaffoldApp,
  scaffoldPage,
  scaffoldComponent,
  scaffoldPlugin,
  migrateFile,
  migrateFiles,
} from '@aihu/cli'

// Scaffold a new app
scaffoldApp('my-app', '/path/to/projects')

// Migrate a file's contents (pure function — no I/O)
const converted = migrateFile(sfcFileContent)
```

## Design constraints

- Zero external npm dependencies (Node/Bun builtins only)
- Build-time only — never added to size budgets or browser bundles
- Per Learning #49 (v3 dep-free thesis): zero non-`@aihu/*` runtime deps

---

# Migration (v0 → v1)

aihu v1 (shipped 2026-05-03, grammar Amendment 04 at v1.0.8) finalized the `.aihu` SFC grammar. Pre-v1 sources written against the older HTML-tag framing or the v0 macro forms will not compile against the current `@aihu/compiler`. This page consolidates every breaking change and maps each old form to its v1 replacement.

> **Codemod first.** Most of these are mechanical. Run `npx aihu migrate <file>` (or point it at a directory) to rewrite pre-v1.0.8 sources automatically, then read the rest of this page for the cases the codemod flags but cannot resolve. Under the hood this is `migrateFile` / `migrateFiles` from `@aihu/cli`.

## 1. Block framing — no HTML tags (C107)

v0 SFCs used HTML-tag framing (`<template>`, `<script setup>`, `<style>`). v1 uses `@blockname { … }` blocks. HTML-tag framing is rejected as **C107**.

```
// before (v0)
<script setup>
  const [count, setCount] = signal(0)
</script>
<template>
  <button>{count}</button>
</template>

// after (v1)
@state {
  import { signal } from '@aihu/signals'
  const [count, setCount] = signal(0)
}
@template {
  <button>{count}</button>
}
```

The only recognized top-level blocks are `@state`, `@template`, `@style`, `@agent`, `@route` (plus the deprecated-but-valid `@layout` shorthand). Any other `@<name>` block is an unknown-block error (**C204**) — including `@props`, whose hint steers you to declare props via `$prop:` inside `@state`.

## 2. Props — `@props` → `$prop:` inside `@state` (C204)

There is no `@props` block. Declare props with the `$prop:` collection form inside `@state`:

```
// before (v0)
@props {
  name: { default: 'world', type: 'string' }
}

// after (v1)
@state {
  $prop: {
    name: { default: 'world', type: 'string' }
  }
}
```

## 3. Reading a prop — use `$computed`, not a bare const (C205)

This is the migration trap most likely to bite. A prop read inside a plain `@state` `const`/`let` throws at runtime (the prop binding is emitted *after* the plain `@state` body, so the read hits a temporal-dead-zone error). The compiler surfaces this as **C205** and steers you to `$computed`, where the read happens inside a thunk:

```
// before (throws at runtime → C205)
@state {
  $prop: { name: { default: 'world', type: 'string' } }
  const greeting = `Hello, ${name()}!`   // reads a prop in a bare const
}

// after (v1)
@state {
  $prop: { name: { default: 'world', type: 'string' } }
  $computed: {
    greeting: () => `Hello, ${name()}!`   // reads the prop inside a thunk
  }
}
```

aihu deliberately does NOT re-order codegen to paper over this — the supported path is `$computed`.

## 4. Reactive attribute bindings — `$`-prefixed (C304 / C305 / C306)

Amendment 04 requires every reactive HTML attribute binding to be `$`-prefixed. The old aliases are hard parse errors:

| Old form | v1 form | Error if left unmigrated |
|----------|---------|--------------------------|
| `:href="expr"` (Vue-shape colon attr) | `$href={expr}` | **C304** |
| `:on` + colon-form event/bind aliases | `$on.click=…`, `$bind.value=…` | **C305** |
| `class={cond ? 'a' : ''}` (plain curly attr) | `$class={cond ? 'a' : ''}` | **C306** |

Component prop-passing keeps the plain-curly form (`<UserCard user={u} />`) and is unaffected.

## 5. Raw HTML — `$html` (W210)

To set element innerHTML reactively, use the `$html` binding — not an `$on.<name>` handler against a non-event:

```
// wrong — $on.innerHTML is not a DOM event → W210 (dead handler)
<div $on.innerHTML="markup"></div>

// right
<div $html="markup"></div>     // or $html={expr}
```

`$on.<name>` referencing anything that is not a real DOM event compiles to a dead `on<name>` handler that never fires; the compiler warns with **W210**.

## 6. Agent surface — per-name `describe:` / `expose:` (C440)

The v0 `@agent`-level macros are removed. `$expose`, `$expose.write`, agent-bare `$action`, and `$describe` are rejected with **C440**. Agent metadata now lives as per-name keys on the `$prop` / `$computed` / `$action` / `$resource` collection entries:

```
// before (v0 → C440)
@agent {
  $expose count
  $describe "the counter"
}

// after (v1)
@state {
  $action: {
    increment: {
      describe: 'Add 1 to the counter',
      expose: { read: true, write: true },
      handler: () => setCount(count() + 1),
    },
  }
}
```

`@agent` now holds only cross-cutting declarations (`$scope`, `$rate-limit`).

## Diagnostic quick reference

| Code | Meaning | Fix |
|------|---------|-----|
| C107 | HTML-tag SFC framing (`<template>`, `<script setup>`) | use `@state` / `@template` / `@style` blocks |
| C204 | unknown `@block` (e.g. `@props`) | use a recognized block; declare props via `$prop:` in `@state` |
| C205 | prop read in a plain `@state` const/let (TDZ) | read the prop in `$computed: { x: () => prop() }` |
| C304 | Vue-shape `:attr=` alias | `$attr={expr}` |
| C305 | colon-form event/bind alias | `$on.click=…`, `$bind.value=…` |
| C306 | plain-curly attribute binding (`class={…}`) | `$class={…}` |
| C440 | removed v1 agent macros (`$expose`, `$describe`, …) | per-name `describe:` / `expose:` on collection entries |
| W210 | `$on.<non-event>` → dead handler | use `$html` for innerHTML, or a real event |

## See also

- [Authoring Components](#authoring-components) — the full v1 block + binding grammar, with a Common diagnostics section
- [Authoring Agents](#authoring-agents) — the v1 `@agent` surface
- [Getting Started](#getting-started) — a from-scratch v1 SFC

---

# API Reference

## @aihu/signals

| Export | Description |
|--------|-------------|
| `signal<T>(initial)` | Create a writable reactive cell |
| `computed<T>(fn)` | Derive a read-only signal from other signals |
| `effect(fn)` | Run a side-effect; auto-tracks signal reads; returns dispose |
| `batch(fn)` | Defer effect flushes until fn completes |
| `untrack(fn)` | Read signals inside fn without subscribing |
| `latticeSignal<T>(merge, initial)` | Merge-monotone signal with custom merge function |
| `boolLatticeSignal(initial?)` | Boolean lattice signal (OR-merge) |
| `maxLatticeSignal(initial?)` | Numeric lattice signal (max-merge) |
| `$state` | State bag shorthand accessor (SFC-internal) |
| `SignalError` | Base error class for signal errors |
| `SignalCircularError` | Error thrown on circular signal dependencies |

**Types:** `Signal<T>`, `Read<T>`, `Write<T>`, `SignalOptions<T>`, `Dispose`, `EffectFn`, `LatticeSignal<T>`, `ComputedOptions<T>`, `State`

## @aihu/arbor

| Export | Description |
|--------|-------------|
| `branch(tag, attrs, children)` | Create a reactive element branch |
| `leaf(signal)` | Create a reactive text node |
| `mount(root, tree)` | Mount a component tree onto a DOM node |
| `slot(opts, children)` | Slot boundary primitive |
| `hydrate(root, tree)` | Hydrate a server-rendered root |
| `each(list, key, render)` | Keyed list rendering primitive |
| `when(cond, then, else?)` | Conditional rendering primitive |

**Types:** `Branch`, `Leaf`, `Node`, `ChildList`, `AttrMap`, `MountOptions`, `MountScope`, `Snapshot`, `EventHandler`, `ErrorHandler`, `AgentBindingSpec`, `AgentContext`

## @aihu/runtime

| Export | Description |
|--------|-------------|
| `defineComponent(opts)` | Define a custom element component |
| `defineElement(opts)` | Define a base custom element (lower-level) |
| `onMount(fn)` | Register a callback to run after component mounts |
| `onCleanup(fn)` | Register a cleanup callback for component unmount |
| `onAdopt(fn)` | Register a callback when element is adopted into a new document |
| `onAttributeChange(fn)` | Register a callback for attribute changes |
| `createStream(opts)` | Create a lazy-attach streaming primitive for `$stream` collection |
| `announce(message, opts?)` | Accessibility live-region announcement |
| `createFocusTrap(el)` | Create a keyboard focus trap for modals/dialogs |

**Types:** `ComponentOptions`, `DefineOptions`, `PropDef`, `PropSignal`, `PropsConfig`, `Setup`, `SetupContext`, `ShadowMode`, `StreamHandle`, `StreamStatus`

## @aihu/router

| Export | Description |
|--------|-------------|
| `createRouter(routes)` | Create a router from compiler-emitted route definitions |
| `defineRouterMiddleware(fn)` | Define a client-side router middleware |
| `composeRouterMiddleware(...fns)` | Compose router middleware with stage ordering |
| `navigate(path, opts?)` | Programmatically navigate to a path |
| `useRoute()` | Reactive accessor for the current route |
| `useRouter()` | Access the router instance |
| `createRouteSignal(router)` | Create a signal bound to the current route |
| `createPrefetcher(router)` | Create a route prefetcher |
| `provideRouteContext(router)` | Provide route context to the component tree |
| `RouteContext` | Context token for the current route |

**Types:** `RouteDefinition`, `RouteModule`, `Router`, `RouteSegment`, `MatchResult`, `NextFn`, `BeforeGuard`, `AfterGuard`, `RouterMiddleware`, `RouteMatchContext`, `RouterResult`, `NavigateOptions`, `PrefetchMode`, `RouteContextValue`

## @aihu/router/plugin

Build-time Vite plugin. Import from `@aihu/router/plugin` in `vite.config.ts` — never in browser code.

| Export | Description |
|--------|-------------|
| `viteRouterIntegration(opts?)` | Vite plugin: scan `src/pages/`, read `.route.json` sidecars, emit virtual route manifest |
| `scanPages(dir)` | Scan `src/pages/` for `.aihu` files and `.route.json` sidecars |
| `scanLayouts(dir)` | Scan `src/layouts/` for `.aihu` layout files |
| `readRouteSidecar(path)` | Read a `.route.json` sidecar file |
| `viteRouterPlugin` | Deprecated alias for `viteRouterIntegration` (removed at v1.0) |

**Types:** `RouterPluginOptions`, `RouteSidecar`, `LayoutMap`, `MiddlewareScan`

## @aihu/server

| Export | Description |
|--------|-------------|
| `defineRoute(opts)` | Define a server route handler |
| `createRequestRouter(manifest, opts?)` | Create a fetch-API request handler from a route manifest |
| `defineMiddleware(fn)` | Server middleware |
| `composeMiddleware(...fns)` | Compose server middleware |
| `defineApiRoute(opts)` | Define a REST API route |
| `defineLoader(fn)` | Define a server-side data loader |
| `defineAihuConfig(config)` | Define the aihu app configuration |
| `createServerCall<A, R>(endpoint)` | Create a typed client fetch stub for a server action |
| `defineStreamRoute(opts)` | Define a streaming HTTP route (v0.4.0+) |
| `json(data, status?)` | Return a JSON response |
| `notFound(msg?)` | Return a 404 response |
| `badRequest(msg?)` | Return a 400 response |
| `serverError(msg?)` | Return a 500 response |
| `methodNotAllowed(msg?)` | Return a 405 response |
| `renderToStream(component, opts)` | Stream-render a component to HTML |
| `renderToString(loader)` | String-render a server component |

**Types:** `AihuConfig`, `BuildConfig`, `BuildTarget`, `CorsConfig`, `RouteConfig`, `ServerConfig`, `DefinedLoader`, `LoadedRouteContext`, `LoaderFn`, `LoaderResult`, `Route`, `RouteManifest`, `RouteOptions`, `RouterOptions`, `HttpMethod`, `Middleware`, `Next`, `RouteContext`, `RouteHandler`, `ApiHandler`, `ComponentDescription`, `HeadConfig`, `LinkTag`, `MetaTag`, `SsrOptions`, `StreamRouteHandler`, `DataSource`, `StreamOptions`, `AgentReadinessConfig`

## @aihu-plugin/data

| Export | Description |
|--------|-------------|
| `createResource(key, fetcher, opts?)` | Create a reactive async resource (signal-native, backend-agnostic) |
| `createResourceStore()` | Create a resource cache store |
| `createResourceSerializer(store)` | Create an SSR dehydration serializer for a resource store |
| `ResourceStoreToken` | Context token for store injection |
| `data(config?)` | Plugin factory — register `@aihu-plugin/data` in `defineAihuConfig({ plugins: [data()] })` |

**Types:** `Resource<T>`, `ResourceOptions`, `DataState`, `ResourceStore`, `ResourceStoreWithMeta`

## @aihu/context

| Export | Description |
|--------|-------------|
| `createContext<T>(defaultValue?)` | Create a context token with an optional default value |
| `provide<T>(token, value)` | Write a value for a token into the active context map |
| `inject<T>(token)` | Read a value for a token from the active context map |
| `setSsrContextMap(map)` | Set the active context map (SSR entry point) |
| `clearSsrContextMap()` | Clear the active context map (SSR teardown) |
| `runWithContext<R>(map, fn)` | Run fn() with a per-request context map (recommended SSR pattern) |

**Types:** `ContextToken<T>`

## @aihu-plugin/agent-readiness

| Export | Description |
|--------|-------------|
| `viteAgentReadinessIntegration(opts?)` | Vite plugin for MCP/agent readiness routes (canonical name) |
| `agentReadiness(opts?)` | Deprecated alias for `viteAgentReadinessIntegration` |
| `createAgentReadinessRoutes(config)` | Create agent readiness route handlers (framework-agnostic) |
| `generateLlmsTxt(config)` | Generate `llms.txt` content from config |
| `generateLlmsFullTxt(config)` | Generate `llms-full.txt` content from config |
| `generateMcpServerCard(config)` | Generate an MCP Server Card JSON |
| `generateRobotsTxt(config)` | Generate `robots.txt` from config |
| `createContentNegotiationHandler(opts)` | Create a content-negotiation handler for agent endpoints |
| `AI_BOT_LIST` | Known AI crawler user-agent strings |

**Types:** `LlmsTxtConfig`, `LlmsTxtLink`, `LlmsTxtSection`, `AgentReadinessConfig`, `McpAuthConfig`, `AgentSkill`, `McpServerCard`, `McpServerCardConfig`, `ContentNegotiationOptions`, `MarkdownResolver`, `RobotsConfig`, `RobotsRule`

## @aihu/agent

| Export | Description |
|--------|-------------|
| `registerAgentMetadata(opts)` | Register agent metadata for a component |
| `getAgentMetadata(tag)` | Look up registered metadata by element tag |
| `getAllAgentMetadata()` | Return all registered agent metadata entries |

**Types:** `AgentRegistry`

## @aihu/agent-service

| Export | Description |
|--------|-------------|
| `AgentService` | Agent service adapter class |
| `createAgentService(opts)` | Create an agent service instance |

## @aihu/plugin

| Export | Description |
|--------|-------------|
| `definePlugin(opts)` | Define an aihu plugin |
| `validatePlugin(plugin)` | Validate a plugin at build time |

**Types:** `Plugin`, `BuildTarget`

## @aihu/cli

| Export | Description |
|--------|-------------|
| `scaffoldApp(name, dir)` | Scaffold a new aihu application |
| `scaffoldPage(route, dir)` | Add a page to an existing project |
| `scaffoldComponent(name, dir)` | Scaffold a `.aihu` component |
| `scaffoldPlugin(name, dir)` | Scaffold a plugin package skeleton |
| `migrateFile(content)` | Convert HTML-tag SFC content to `@blockname{}` form |
| `migrateFiles(files, dryRun, cwd)` | Migrate files in-place or dry-run |

## @aihu/css-engine

Tailwind v4 hard fork with WC-native scoped output. The main export is the build-time engine; the `runtime/*` subpaths are the tiny client helpers. See [Styling](styling.md) for concepts.

**`@aihu/css-engine`** (main — build-time)

| Export | Description |
|--------|-------------|
| `compile(classes)` | Compile a list of utility class names to CSS |
| `compileSfc(source, id?)` | Compile a `.aihu` SFC source string to scoped, shadow-DOM-embedded CSS (via the compiler AST) |
| `defineStylePack(input)` | Define a custom style pack (token bundle) against the built-in token contract |

**Types:** `StylePack`, `StylePackInput`, `TokenMap`

**`@aihu/css-engine/runtime/cn`** (client, < 1 kB gz)

| Export | Description |
|--------|-------------|
| `cn(...inputs)` | Merge class values, last-wins per Tailwind property group; flattens arrays, drops falsy |

**Types:** `ClassValue`

**`@aihu/css-engine/runtime/progressive`** (client)

| Export | Description |
|--------|-------------|
| `position(anchor, floating, opts?)` | Position a floating element against an anchor; returns the resolved placement |
| `anchorFallback(anchor, floating, opts?)` | JS fallback for the `anchor:` feature; returns a cleanup function |
| `popoverFallback(anchor, panel, opts?)` | JS fallback for the `popover:` feature (portal + position); returns a cleanup function |
| `portal(el)` | Portal an element to a top-layer-emulating container; returns a restore function |

**Types:** `Placement`, `PositionOptions`

**`@aihu/css-engine/packs`** (built-in style packs as JS objects)

| Export | Description |
|--------|-------------|
| `aihuDefault` | The `aihu-default` `StylePack` (warm brand palette). Read `.tokens` / `.dark`, or `.toCss()` |
| `aihuGraphite` | The `aihu-graphite` `StylePack` (monochrome `oklch()` ramp) |
| `builtinPacks` | `Record<string, StylePack>` of all built-in packs, keyed by name |

**Built-in style packs (CSS bundles):** `@aihu/css-engine/styles/aihu-default.css` and `@aihu/css-engine/styles/aihu-graphite.css` are declared in the package `exports`, so a bare `import '@aihu/css-engine/styles/aihu-default.css'` resolves and Vite inlines it. The CSS files are GENERATED from the `@aihu/css-engine/packs` objects (`pack.toCss()`), so the two access paths emit byte-identical CSS and cannot drift. The files also remain in the package `files` list (on disk at `node_modules/@aihu/css-engine/styles/*.css`). See [Theming](theming.md) for the verified access paths.

## @aihu/primitives

Headless WAI-ARIA APG behaviors as vanilla custom elements; zero CSS. Each behavior has a `define*()` registrar and a tree-shakeable subpath. See [Primitives](primitives.md) for usage.

| Subpath | Key exports |
|---------|-------------|
| `@aihu/primitives/dialog` | `defineDialog()`, `AihuDialogRoot` + pieces (`AihuDialogTrigger`, `AihuDialogContent`, `AihuDialogBackdrop`, `AihuDialogClose`, `AihuDialogTitle`, `AihuDialogDescription`), `dialogContext`, `createFocusTrap` |
| `@aihu/primitives/tooltip` | `defineTooltip()`, `AihuTooltipRoot`, `AihuTooltipTrigger`, `AihuTooltipContent`, `tooltipContext` |
| `@aihu/primitives/button` | `AihuButton` (base class), `defineButton(tag)` |
| `@aihu/primitives/context` | `createDomContext()`, `provideContext()`, `injectContext()`, `MissingContextError` |
| `@aihu/primitives/presence-gate` | `definePresenceGate()`, `AihuPresenceGate`, `presenceContext` |
| `@aihu/primitives/roving-focus` | `defineRovingFocus()`, `AihuRovingFocus` |
| `@aihu/primitives/collection` | `createCollection()`, `defineCollection()`, `AihuCollection`, `collectionContext` |
| `@aihu/primitives/config-provider` | `defineConfigProvider()`, `AihuConfigProvider`, `configContext` |
| `@aihu/primitives/form-control` | `defineFormControl()`, `AihuFormControl`, `formControlContext` |

The package root (`@aihu/primitives`) re-exports every primitive's public surface.

**Types:** `DomContext<T>`, `DialogContextValue`, `FocusTrap`, `TooltipContextValue`, `TooltipCoords`, `ButtonType`, `Orientation`, `ColorScheme`, `Density`, `Direction`, `ConfigContextValue`, `CollectionContextValue`, `FormControlContextValue`

> **Roadmap:** the styled component registry (`@aihu/ui`, distributed via the `aihu add` CLI command) is built on these primitives + the css-engine but is **not yet published**. Treat it as coming-soon, not available.

## @state macro collection forms (v2)

The v2 collection-form syntax for `@state` macros. v1 forms produce error C440.

| Macro | Collection-form |
|-------|-----------------|
| `$prop` | `$prop: { name: { default: value, type?: "T", describe?: "...", expose?: { read?: true, write?: true } } }` |
| `$computed` | `$computed: { name: () => expr }` (bare) or `{ name: { value: () => expr, describe?: "...", expose?: { read?: true } } }` (wrapped) |
| `$action` | `$action: { name: (args) => expr }` (bare) or `{ name: { handler: (args) => expr, describe?: "...", expose?: { write?: true } } }` (wrapped) |
| `$resource` | `$resource: { name: () => fetcher() }` (bare) or `{ name: { value: () => fetcher(), describe?: "...", expose?: { read?: true } } }` (wrapped) |
| `$effect` | `$effect: () => { body }` (anonymous) or `$effect: { name: () => { body } }` (named) |
| `$lifecycle` | `$lifecycle: { mount: () => ..., dispose: () => ... }` — always bare, wrapped form forbidden |

## @agent block (v2)

`@agent` holds only cross-cutting declarations. Per-name metadata lives on `@state` entries.

```
@agent {
  $scope "scope-name"   // agent permission scope string
  $rate-limit 100       // requests per minute (positive integer)
}
```

Removed in v2 (C440 errors): `$expose`, `$expose.write`, `$action <bareName>`, `$describe`.

---

# Deployment

## Build for production

```bash
bun run build
bun run preview
```

`bun run build` compiles all `.aihu` SFCs through the Rust compiler, bundles with Vite/Rolldown, and validates against the per-package size budgets in `.size-limit.json`. `bun run preview` serves the production build locally to verify output before deploying.

## `defineAihuConfig`

The app configuration lives in `aihu.config.ts`:

```typescript
import { defineAihuConfig } from '@aihu/server'

export default defineAihuConfig({
  build: {
    target: 'universal',
    outDir: 'dist',
    sourcemap: false,
  },
  plugins: [],
})
```

Build target options: `'client'` (browser bundle only), `'server'` (server bundle only), `'universal'` (both, default).

## Cloudflare Workers

Use `@aihu/adapter-cloudflare` to deploy to Cloudflare Workers or Pages:

```typescript
// aihu.config.ts
import { defineConfig } from '@aihu/app'
import { cloudflare } from '@aihu/adapter-cloudflare'

export default defineConfig({
  adapter: cloudflare({ name: 'my-worker' }),
})
```

The adapter:
- Writes `_worker.js` to the Vite output directory (SPA mode — all page requests served from Cloudflare CDN via the `ASSETS` binding).
- Optionally creates `wrangler.toml` in the project root if absent (never overwrites an existing one).

Adapter options:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `name` | `string` | from `package.json` | Cloudflare Worker name in `wrangler.toml` |
| `mode` | `'workers' \| 'pages'` | `'workers'` | Deployment target |
| `generateWrangler` | `boolean` | `true` | Write `wrangler.toml` if absent |

Deploy after build:

```bash
wrangler deploy --config wrangler.toml
```

For a manual Worker without the adapter, use `@aihu/server`'s request router directly:

```typescript
import { createRequestRouter, defineRoute, json } from '@aihu/server'

const router = createRequestRouter({
  routes: [
    defineRoute('/api/hello', () => json({ hello: 'world' })),
  ],
})

// Cloudflare Worker
export default { fetch: router }
```

## Vercel

Use `@aihu/adapter-vercel` to deploy using the Vercel Build Output API v3:

```typescript
// aihu.config.ts
import { defineConfig } from '@aihu/app'
import { vercel } from '@aihu/adapter-vercel'

export default defineConfig({
  adapter: vercel(),
})
```

The adapter:
- Copies static assets to `.vercel/output/static/`.
- Writes an Edge Function entry (default) or Serverless Function entry.
- Emits `config.json` with the Build Output API v3 routes manifest.

Adapter options:

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `runtime` | `'edge' \| 'serverless'` | `'edge'` | Vercel function runtime |
| `outputDir` | `string` | `'.vercel/output'` | Build Output API output directory |
| `nodeVersion` | `string` | `'nodejs18.x'` | Node.js version for serverless runtime |

Deploy after build:

```bash
vercel deploy --prebuilt
```

## Bun server

Run aihu server-side on Bun using `@aihu/server`'s fetch-API router:

```typescript
import { createRequestRouter, defineRoute, json } from '@aihu/server'
import { createAgentReadinessRoutes } from '@aihu-plugin/agent-readiness'

const ar = createAgentReadinessRoutes({
  name: 'My App',
  endpoint: 'https://myapp.example.com/mcp',
  summary: 'An aihu-powered app.',
})

const router = createRequestRouter({
  routes: [
    defineRoute('/llms.txt', ar.llmsTxt),
    defineRoute('/.well-known/mcp/server-card.json', ar.mcpServerCard),
    defineRoute('/robots.txt', ar.robotsTxt),
    defineRoute('/api/hello', () => json({ hello: 'world' })),
  ],
})

Bun.serve({ fetch: router })
```

## Deno

The same router works on Deno Deploy — aihu uses only Web Standard APIs (Fetch, ReadableStream, URL):

```typescript
import { createRequestRouter, defineRoute, json } from '@aihu/server'

const router = createRequestRouter({
  routes: [
    defineRoute('/api/hello', () => json({ hello: 'world' })),
  ],
})

Deno.serve(router)
```

## Node.js

aihu output is standard ESM. Any Node.js ≥20.18.0 runtime can serve an aihu application:

```bash
npm run build
node dist/server/entry.js
```

The server entry is generated by the universal build and uses `@aihu/server`'s request router.

On supported Node platforms `@aihu/server` lazily loads a native Rust addon to render SSR. Edge runtimes (Cloudflare, Vercel Edge, Deno) automatically skip it and use the TypeScript fallback. To force the fallback on Node — e.g. on an unsupported platform or to debug a parity issue — set `SCRIBE_NATIVE_SKIP=1` in the server environment.

## `viteRouterIntegration()` at build time

The Vite plugin performs these steps at build time:

1. `scanPages(dir)` — discovers all `.aihu` files under `src/pages/`.
2. For each page, reads the `.route.json` sidecar emitted by the Rust compiler.
3. Assembles the route manifest into the `virtual:aihu-routes` module.
4. Emits `dist/routes.json` for runtime consumption.

Route manifests are fully static after build — no filesystem scanning at runtime.

---

# @aihu/adapter-cloudflare

Cloudflare Workers/Pages deployment adapter for `@aihu/app`. A build-time-only tool — it runs during your production build and emits the files Cloudflare needs to serve your app. It is never included in browser bundles and has no runtime size impact.

The adapter writes a `_worker.js` entry into Vite's output directory and, optionally, a `wrangler.toml` in your project root. It supports two deployment targets (Workers and Pages) and two serving modes (SPA-only and SSR + static hybrid).

## Install

```bash
npm install @aihu/adapter-cloudflare
# or
bun add @aihu/adapter-cloudflare
```

This package declares `@aihu/app` and `vite` (>=5.0.0) as peer dependencies — install them alongside it.

## API overview

| Name | Kind | Description |
|------|------|-------------|
| `cloudflare` | function | Create a Cloudflare adapter for use in `aihu.config.ts` |
| `CloudflareAdapterOptions` | interface | Options bag accepted by `cloudflare()` |

The default export of `@aihu/app` returns an `AihuAdapter`; `cloudflare()` is the only value export of this package.

## Functions

### cloudflare

```typescript
function cloudflare(options?: CloudflareAdapterOptions): AihuAdapter
```

Returns an `AihuAdapter` (named `'cloudflare'`) that you pass to `defineConfig({ adapter })`. During the build, its `adapt()` hook runs after Vite finishes and:

1. In SSR mode only, writes `routes-manifest.js` into the output directory before the worker entry.
2. Writes `_worker.js` to the output directory — an SPA entry, or an SSR + static hybrid entry when `ssr: true`.
3. Writes `wrangler.toml` to the project root, but only if no `wrangler.toml` already exists. It never overwrites your file.

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `options` | `CloudflareAdapterOptions` | No | Adapter configuration. All fields are optional. |

**Returns** `AihuAdapter` — the adapter object consumed by `@aihu/app`.

## Types

### CloudflareAdapterOptions

```typescript
interface CloudflareAdapterOptions {
  name?: string
  mode?: 'workers' | 'pages'
  generateWrangler?: boolean
  ssr?: boolean
}
```

All fields are optional.

**Fields**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | `"name"` from your `package.json`, else `'aihu-app'` | Cloudflare Worker name written into the generated `wrangler.toml`. |
| `mode` | `'workers' \| 'pages'` | `'workers'` | Deployment target. `'workers'` serves static assets via the `env.ASSETS` binding; `'pages'` follows the Cloudflare Pages `_worker.js` convention. Both produce the same output, only the deploy target differs. |
| `generateWrangler` | `boolean` | `true` | Whether to write `wrangler.toml` in the project root if it is absent. Set to `false` to manage `wrangler.toml` yourself. An existing file is never overwritten regardless of this value. |
| `ssr` | `boolean` | `false` | Enable SSR + static hybrid mode. When `false` (default), all requests are served from the `ASSETS` binding (SPA-only). |

## Serving modes

### SPA-only (default)

When `ssr` is `false`, the generated `_worker.js` serves every page request from Cloudflare's `ASSETS` binding (the CDN). On a 404 from `ASSETS`, it falls back to `/index.html` so client-side routing works.

### SSR + static hybrid

When `ssr: true`, the worker resolves each request in priority order:

1. **SSR handler** — your aihu server routes (API routes, agent-readiness endpoints, server-rendered pages).
2. **ASSETS** — pre-rendered static files served from the Cloudflare CDN.
3. **`/index.html`** — the SPA shell fallback for client-side-routed pages.

In this mode the adapter also emits a `routes-manifest.js` carrying serializable route metadata (`pattern`, `segments`, `name`, `ssr`). Because page components are not serializable, each manifest route currently uses a placeholder handler that returns 404, letting the worker fall through to the `ASSETS` binding for pre-rendered pages.

## Usage

### Basic configuration

```typescript
// aihu.config.ts
import { defineConfig } from '@aihu/app'
import { cloudflare } from '@aihu/adapter-cloudflare'

export default defineConfig({
  adapter: cloudflare({ name: 'my-worker' }),
})
```

### SSR + static hybrid

```typescript
// aihu.config.ts
import { defineConfig } from '@aihu/app'
import { cloudflare } from '@aihu/adapter-cloudflare'

export default defineConfig({
  adapter: cloudflare({ ssr: true }),
})
```

### Managing wrangler.toml yourself

```typescript
import { defineConfig } from '@aihu/app'
import { cloudflare } from '@aihu/adapter-cloudflare'

export default defineConfig({
  // Don't generate wrangler.toml — you maintain your own.
  adapter: cloudflare({ generateWrangler: false }),
})
```

## Deploy

After building, deploy the output with Wrangler:

```bash
wrangler deploy --config wrangler.toml
```

The generated `wrangler.toml` sets `main = "_worker.js"`, a `compatibility_date`, and an `[assets]` block binding the output directory to `ASSETS`. Edit it freely after generation — the adapter never overwrites an existing file.

## See also

- [@aihu/cli](#packages/cli) — scaffold a new aihu app

---

# @aihu/adapter-vercel

Vercel deployment adapter for `@aihu/app`. Implements the `AihuAdapter` interface and emits a [Vercel Build Output API v3](https://vercel.com/docs/build-output-api/v3) directory (`.vercel/output/`) from a finished Vite build, ready for `vercel deploy --prebuilt`.

## Install

```bash
npm install @aihu/adapter-vercel
# or
bun add @aihu/adapter-vercel
```

Peer dependencies: `@aihu/app` and `vite` (`>=5.0.0`).

## API overview

| Name | Kind | Description |
|------|------|-------------|
| `vercel` | function | Create a Vercel `AihuAdapter` for `defineConfig` |
| `VercelAdapterOptions` | interface | Options for `vercel()` |

## Functions

### vercel

```typescript
function vercel(options?: VercelAdapterOptions): AihuAdapter
```

Returns an `AihuAdapter` (named `'vercel'`) that the `@aihu/app` Vite plugin invokes after the bundle is written. Its `adapt()` step:

1. Cleans and recreates the output directory (removing stale files from prior builds).
2. Copies the Vite output (`context.outDir`) into `.vercel/output/static/`.
3. Writes an Edge or Serverless function entry at `.vercel/output/functions/index.func/index.js`.
4. Writes the function's `.vc-config.json`.
5. Writes `.vercel/output/config.json` with the Build Output API v3 routes manifest.

The generated routes serve `/assets/*` with a long-lived immutable `cache-control` header, send `/api/*` to the function (`/index.func`), and fall back all other requests to `static/index.html` (SPA mode).

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `options` | `VercelAdapterOptions` | No | Adapter configuration. See below. |

**Returns** `AihuAdapter` — pass to the `adapter` field of `defineConfig`.

## Types

### VercelAdapterOptions

```typescript
interface VercelAdapterOptions {
  runtime?: 'edge' | 'serverless'
  outputDir?: string
  nodeVersion?: string
}
```

**Fields**

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `runtime` | `'edge' \| 'serverless'` | No | `'edge'` | `'edge'` targets the Vercel Edge Runtime (V8 isolates, global). `'serverless'` targets a regional Node.js function. |
| `outputDir` | `string` | No | `'.vercel/output'` | Build Output API directory, resolved relative to the project root. |
| `nodeVersion` | `string` | No | `'nodejs18.x'` | Node.js version for the serverless runtime. Ignored when `runtime` is `'edge'`. |

## Usage

### Default (Edge Runtime)

```typescript
// aihu.config.ts
import { defineConfig } from '@aihu/app'
import { vercel } from '@aihu/adapter-vercel'

export default defineConfig({
  adapter: vercel(),
})
```

### Serverless runtime with a pinned Node version

```typescript
// aihu.config.ts
import { defineConfig } from '@aihu/app'
import { vercel } from '@aihu/adapter-vercel'

export default defineConfig({
  adapter: vercel({
    runtime: 'serverless',
    nodeVersion: 'nodejs20.x',
  }),
})
```

After building, deploy the prebuilt output:

```bash
vercel deploy --prebuilt
```

## Notes

- **SPA mode (V0).** The generated function entry handles `/api/**` routes only and currently returns `501 Not Implemented`; all page requests are served as static files from `static/index.html`. Full SSR is planned for V1+.
- The adapter wipes its `outputDir` on every run, so do not point `outputDir` at a directory containing files you want to keep.

## See also

- [@aihu/adapter-cloudflare](#packages/adapter-cloudflare) — deploy the same app to Cloudflare Pages
- [@aihu/cli](#packages/cli) — scaffold a new aihu app
- [Deployment guide](#guides/deployment) — runtime targets and the native-addon fallback

---

# @aihu/agent-server

Server-mediated **capability bridge** for live agent dispatch. The browser mounts the real, visible component and registers a narrow opaque-ID dispatcher (emitted by the compiler — not the raw `__agentBinding`). The server holds all policy — auth, scope, rate-limit — via `@aihu/agent-service`, and forwards only approved action invocations to the browser over a WebSocket bridge. The client dispatcher exposes no policy information, so the server is the sole enforcement point.

## Install

```bash
npm install @aihu/agent-server
# or
bun add @aihu/agent-server
```

`@aihu/agent-service` is a required peer dependency — install it alongside this package.

## API overview

### Server

- `createAgentServer(options)` — the core factory. Mounts a component server-side, exposes its actions to an MCP client through the agent-service security gate, and forwards approved invocations to a connected browser bridge. No MCP SDK import.
- `createComponentMcpServer(options)` / `serveComponentMcp(options)` — wrap the agent server as an MCP endpoint. The MCP SDK is imported lazily, so it is only loaded when you import from this barrel.

### Browser bridge client

- `createBridgeClient(options)` — the browser-side client (T3) that connects to the server bridge, registers the mounted component's opaque-ID dispatcher, and executes approved invocations against the live instance.
- Types: `BridgeClient`, `BridgeClientOptions`, `AgentDispatcher`.

### Opaque IDs

- `opaqueActionId(...)` / `opaqueActionIdForTool(...)` — derive the opaque action identifier the client dispatcher is keyed on (no tag/action/policy leakage).
- `parseToolName(toolName)` — split an MCP tool name into its components.

### Protocol

- `BRIDGE_PROTOCOL_VERSION` plus the bridge message types — the WebSocket contract the browser bridge client implements against.

## Security note

The bridge's security argument is that the server is the *only* thing that can invoke the client-side dispatcher. The opaque-ID dispatcher carries no policy, so the server-side gate (`@aihu/agent-service`) is load-bearing. WS authentication and origin checks for the bridge channel are a planned v1.x hardening follow-up; do not expose an unauthenticated bridge to untrusted networks.

---

# @aihu/auth

JWT scope checks, a reactive `ScopeSignal`, client sign-in/sign-out helpers, and server middleware/routes for aihu auth. The package supplies the `AuthPlugin` that `@aihu/agent-service` uses to gate `$scope`-protected components, plus the cookie-backed session machinery for sign-in flows.

The public surface is split across two entry points: a browser-safe root (`@aihu/auth`) and a server-only subpath (`@aihu/auth/server`) that needs Web Crypto (`crypto.subtle`).

## Install

```bash
npm install @aihu/auth
# or
bun add @aihu/auth
```

`@aihu/signals` is a required peer dependency. `@aihu/agent-service` is an optional peer dependency — install it only when you wire the auth plugin into an agent service for `$scope` enforcement.

## Entry points

| Import | Surface | Notes |
|--------|---------|-------|
| `@aihu/auth` | Browser-safe | Client helpers, the agent-service `AuthPlugin` factory, the `ScopeSignal`, and legacy JWT/middleware helpers. No `crypto.subtle` dependency. |
| `@aihu/auth/server` | Server-only | The `auth()` plugin factory, `createAuthRoutes`, and `getAuthState`. Verifies JWT signatures via `crypto.subtle`. Never import this into a browser bundle. |

## API overview

### Root — `@aihu/auth`

| Name | Kind | Description |
|------|------|-------------|
| `createAuthPlugin` | function | Build an `AuthPlugin` for `createAgentService({ authPlugin })` so `$scope`-gated tool calls are enforced. |
| `signIn` | function | Client POST to the sign-in endpoint; resolves to the authenticated `User`. |
| `signOut` | function | Client POST to the sign-out endpoint; never throws. |
| `useCurrentUser` | function | Reactive getter returning the current `User | null`. |
| `setCurrentScopes` | function | Update the module-level scope signal. |
| `clearCurrentScopes` | function | Reset the current user and scopes to `null` / `[]`. |
| `createScopeSignal` | function | Create a `ScopeSignalHandle` for reactive scope tracking. |
| `getScopeSignal` | function | Reactive getter returning whether a given scope is currently held. |
| `decodeJwt` | function | Legacy: decode a JWT payload (no signature check); returns `JwtClaims | null`. |
| `hasScope` | function | Legacy: test whether decoded `JwtClaims` carry a scope. |
| `requireAuth` | function | Legacy middleware: 401 when no token is present. |
| `requireScope` | function | Legacy middleware: 401 on missing token, 403 on missing scope. |
| `AuthError` | class | Error thrown by client `signIn` on HTTP/parse failures. |

### Server — `@aihu/auth/server`

| Name | Kind | Description |
|------|------|-------------|
| `auth` | function | aihu `Plugin` factory: registers the sign-in/out/refresh routes and exposes `getAuthState` as a server-runtime helper. |
| `createAuthRoutes` | function | Build the three `RouteHandler`s (`signIn`, `signOut`, `refresh`). |
| `getAuthState` | function | Read and verify the session JWT cookie; async, never throws. |

## Functions

### createAuthPlugin

```typescript
function createAuthPlugin(options?: AuthPluginOptions): AuthPlugin
```

Creates an `AuthPlugin` compatible with `@aihu/agent-service`. Its `checkScope(jwt, scope)` decodes the JWT payload and returns `true` when the required scope is present in any standard claim location (`scope`, `scp`, `scopes`). Returns `false` — never throws — for malformed or unsigned tokens. Pass `options.decodeJwt` to inject a custom decoder.

### signIn

```typescript
async function signIn(token: string, signInPath = '/auth/sign-in'): Promise<User>
```

Client helper. POSTs the supplied `token` to the sign-in endpoint, updates the local user/scope signals on success, and resolves to the authenticated `User`. Throws `AuthError` on HTTP or parse failures.

### signOut

```typescript
async function signOut(signOutPath = '/auth/sign-out'): Promise<void>
```

Client helper. POSTs to the sign-out endpoint and clears the local user/scope signals. Never throws.

### useCurrentUser

```typescript
function useCurrentUser(): () => User | null
```

Returns a reactive getter for the current `User | null`, suitable for use inside computeds and effects.

### setCurrentScopes / clearCurrentScopes

```typescript
function setCurrentScopes(scopes: string[]): void
function clearCurrentScopes(): void
```

`setCurrentScopes` writes the active scope list onto the module-level scope signal. `clearCurrentScopes` resets the current user to `null` and scopes to `[]`.

### createScopeSignal / getScopeSignal

```typescript
function createScopeSignal(): ScopeSignalHandle
function getScopeSignal(scope: string): () => boolean
```

`createScopeSignal` returns a `ScopeSignalHandle` for managing the reactive scope set. `getScopeSignal(scope)` returns a reactive getter that is `true` while the named scope is held.

### auth (`/server`)

```typescript
function auth(config: AuthConfig): Plugin
```

Server-only plugin factory. Registers the sign-in, sign-out, and refresh routes (paths from `config.signInPath` / `signOutPath` / `refreshPath`, defaulting to `/auth/sign-in`, `/auth/sign-out`, `/auth/refresh`) and exposes `getAuthState` as a server-runtime helper. Register it in `defineAihuConfig({ plugins: [auth({ jwtSecret })] })`.

### createAuthRoutes (`/server`)

```typescript
function createAuthRoutes(config: AuthConfig): RouteHandlers
```

Returns the three `RouteHandler` objects (`{ signIn, signOut, refresh }`) so you can register them with any fetch-API router. The sign-in handler verifies the token and sets the session cookie; sign-out clears it.

### getAuthState (`/server`)

```typescript
async function getAuthState(ctx: RequestContext, config: AuthConfig): Promise<AuthState>
```

Reads the session JWT cookie from the request, verifies its signature with `crypto.subtle`, and returns `{ user, scopes }`. Never throws — on an absent or invalid cookie it returns `{ user: null, scopes: [] }`.

## Types

| Name | Kind | Description |
|------|------|-------------|
| `User` | interface | `{ id, email?, scopes: string[] }`. |
| `AuthState` | interface | `{ user: User | null, scopes: string[] }` — result of `getAuthState`. |
| `AuthConfig` | interface | `jwtSecret` plus optional `signInPath` / `signOutPath` / `refreshPath`, `cookieName` (default `aihu_session`), and `maxAge` (default `86400`). |
| `RouteHandlers` | interface | `{ signIn, signOut, refresh }` — each a `RouteHandler` from `@aihu/server`. |
| `RequestContext` | type | Alias for the standard `Request`. |
| `AuthError` | class | Carries an optional `statusCode`. |
| `JwtClaims` | interface | Decoded JWT payload shape consumed by `hasScope`. |
| `AuthMiddlewareOptions` | interface | Options for `requireAuth` / `requireScope`. |
| `AuthPluginOptions` | interface | Options for `createAuthPlugin` (`decodeJwt` override). |
| `ScopeSignalHandle` | interface | Handle returned by `createScopeSignal`. |

## Auth on agent endpoints (v1)

The MCP HTTP path — `createAgentService(...).asMiddleware()` — is **auth-capable** via `createAuthPlugin()`. When you pass `authPlugin`, `handleToolCall` enforces `$scope`-gated components: it returns `401 AUTH_MISSING` when no JWT is present and `403 SCOPE_DENIED` when the JWT lacks the required scope (see `packages/agent-service/src/agent-service.ts`). `@aihu/auth` supplies that plugin via `createAuthPlugin()`.

By contrast, the [`@aihu/agent-a2a`](/docs/packages/agent-a2a) and [`@aihu/agent-acp`](/docs/packages/agent-acp) adapters have **no** scope wiring — they are **anonymous-only for v1**. Do not rely on them for access control.

```typescript
import { createAgentService } from '@aihu/agent-service'
import { getAllAgentMetadata } from '@aihu/agent'
import { createAuthPlugin } from '@aihu/auth'

const service = createAgentService({
  manifests: getAllAgentMetadata(),
  authPlugin: createAuthPlugin(),
})

// MCP HTTP middleware now enforces $scope checks:
// 401 AUTH_MISSING when no JWT, 403 SCOPE_DENIED on insufficient scope.
const handler = service.asMiddleware()
```

## How it relates

- [`@aihu/agent-a2a`](/docs/packages/agent-a2a) and [`@aihu/agent-acp`](/docs/packages/agent-acp) — anonymous-only adapters; no auth wiring in v1.
- [`@aihu/scraping`](/docs/packages/scraping) plugs into the same agent-service rate-limit path that `createAuthPlugin()` extends with scope checks.

---

# @aihu/language-server

Cross-editor [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) implementation for `.aihu` Single File Components, built on [Volar](https://volarjs.dev/) (`@volar/language-server@2.4.28`). Ships the runnable `aihu-language-server` binary that any LSP-aware editor (VS Code via `vscode-languageclient`, Neovim, Helix, Zed, …) launches as an out-of-process Node.js child over stdio.

Dev-time tooling only — it never enters browser bundles and has no size-limit row.

> **Status:** held-private workspace package — not yet published to npm. The binary and exports below are available inside the workspace today; the published-package install will follow v1.x ratification.

## Features

- **Diagnostics** — shells out to the `aihu-compile` Rust binary with `--machine-errors` (debounced) and maps the structured compiler errors onto LSP diagnostics.
- **Hover** — Markdown documentation for the aihu macro keywords and block names, aware of `@state` vs `@template` block context, served from a 36-entry hover table.
- **Completion** — `$`-triggered macro-kind snippets (context-filtered) and `@`-triggered top-level block names.
- **Code actions** — QuickFix for the `C440`–`C444` old-spec macro diagnostics, backed by the macro-simplification codemod.
- **Virtual code** — source-mapped virtual-file generation for the `@state` block, so TypeScript-side features resolve positions back to the original `.aihu` source.

## Running the server

The package exposes the `aihu-language-server` bin. Any LSP client config that can launch a stdio command works:

```lua
-- Neovim (vim.lsp.config / lspconfig-style)
{ cmd = { "aihu-language-server" }, filetypes = { "aihu" } }
```

```toml
# Helix languages.toml
[language-server.aihu]
command = "aihu-language-server"
```

The binary binds the Volar connection to `process.stdin`/`process.stdout` explicitly, so it works when launched directly as a command.

## API overview

### Root export (`@aihu/language-server`)

The transport layer — wires the editor-agnostic core onto a Volar connection.

- `startServer()` — create the Volar connection + server, register the aihu language and language-service plugins, and start listening on stdio. This is what the `aihu-language-server` bin calls.
- `createTestServer()` — test seam: returns the Volar server object (without listening) so integration tests can drive `.initialize()` directly.

### Core export (`@aihu/language-server/core`)

Editor-agnostic feature logic — pure functions plus the compiler bridge, with no LSP connection objects. This barrel is the seam a Volar (or any other) integration consumes.

#### Volar plugins

- `createAihuLanguagePlugin()` — the Volar language plugin: recognises `.aihu` sources and produces source-mapped virtual code. Types: `AihuLanguagePlugin`, `AihuSource`, `AihuVirtualCode`.
- `createAihuLanguageServicePlugin()` — the Volar language-service plugin wiring hover, completion, diagnostics, and code actions.

#### Diagnostics

- `compileWithDiagnostics(source, uri)` — invoke the `aihu-compile` binary with `--machine-errors` (source fed on stdin, argv arrays — no shell) and return a `CompileResult`.
- `parseMachineErrors(stderr)` — parse the compiler's machine-error output into `AihuDiagnostic` records (0-based LSP positions).

#### Hover

- `getHoverContent(word, blockContext)` — Markdown hover documentation for a macro or block keyword.
- `getMacroAtPosition(line, character)` — extract the macro token under the cursor.
- `getBlockContext(source, line)` — determine whether a position is inside `@state`, `@template`, etc., so hover entries are context-filtered.

#### Completion

- `BLOCK_COMPLETIONS` — `@`-triggered top-level block-name completions.
- `STATE_MACRO_COMPLETIONS` — `$`-triggered macro-kind snippet completions for the `@state` block. Item type: `LspCompletionItem`.

#### Code actions

- `buildMigrateFix(diagnostic, source)` — build the QuickFix edit (a `MigrateFix`) for an old-spec macro diagnostic.
- `MIGRATE_CODES` — the set of compiler codes (`C440`–`C444`) the QuickFix applies to.

#### Virtual code + source maps

- `generateStateVirtualCode(input)` — generate the source-mapped TypeScript virtual code for a `@state` block (`GeneratorInput` → `GeneratorOutput`).
- `SourceMap`, `mapToOriginal(...)`, `mapToVirtual(...)` — translate positions between the original `.aihu` source and the generated virtual code. Types: `AihuCodeMapping`, `AihuSourcePosition`, `AihuVirtualPosition`.

## Layout

- `src/core/*` — pure logic + the compiler bridge (everything under `/core` above).
- `src/server.ts` — wires the core plugins onto the Volar connection (root export).
- `src/bin.ts` — the runnable `aihu-language-server` stdio entry.

The server runs out-of-process for editor isolation; all feature logic lives in `core` so transports can change without touching it.

---

# @aihu/magna

aihu bridge for Magna GraphQL: a dependency-free fetch wrapper, reactive resource composition over [`@aihu-plugin/data`](/docs/api-reference), and per-request JWT relay. The browser-safe root entry (`@aihu/magna`) carries the runtime helpers; the node-only build-time pipeline lives at the `@aihu/magna/codegen` subpath so the root entry stays free of `node:fs`.

## Install

```bash
npm install @aihu/magna
# or
bun add @aihu/magna
```

Runtime dependencies: `@aihu/signals`, `@aihu/plugin`, `@aihu/context`, and `@aihu-plugin/data`. `@aihu/magna-gqlmin` is an optional dependency used for SDL minification at build time — when it is absent the codegen pipeline gracefully skips minification.

## Entry points

| Import | Surface | Notes |
|--------|---------|-------|
| `@aihu/magna` | Browser-safe | `MagnaFetchToken`, `createMagnaFetch`, `createMagnaResource`, `useMagnaSubscription`, and the public types. |
| `@aihu/magna/codegen` | Node-only (build-time) | `beforeCompile` — the SDL validation/codegen pipeline. Pulls in `node:fs`; do not import from a browser bundle. |

## API overview

| Name | Kind | Entry | Description |
|------|------|-------|-------------|
| `createMagnaFetch` | function | root | Build a typed, dep-free GraphQL POST wrapper with JWT relay. |
| `createMagnaResource` | function | root | Create a reactive `Resource<T>` from an operation + optional variables signal. |
| `useMagnaSubscription` | function | root | Subscription handle. v0.1 degraded shim — no streaming yet. |
| `MagnaFetchToken` | injection token | root | Compiler-emitted `inject(MagnaFetchToken)` token for the fetch wrapper. |
| `magna` | function | `/codegen` (see note) | Plugin factory wiring the SDL pipeline into `beforeCompile`. |
| `beforeCompile` | function | `/codegen` | Build-time SDL validation/codegen hook (advanced). |

The `magna()` plugin factory wires the build pipeline through the `beforeCompile` hook; register it in `defineAihuConfig`. The build-time hook code is exported from the node-only `@aihu/magna/codegen` subpath.

## Functions

### createMagnaFetch

```typescript
function createMagnaFetch(options: MagnaPluginOptions): MagnaFetch
```

Returns a typed GraphQL fetch function bound to `options`. JWT relay: it calls `options.getToken?.()` per request and adds the `Authorization` header when the getter returns a non-null string (omitting it entirely on `null`). Static `options.headers` are merged first so callers can override. Network failures throw; GraphQL-level errors are returned inside the response envelope.

### createMagnaResource

```typescript
function createMagnaResource<T>(
  fetch: MagnaFetch,
  operation: string,
  variables?: Signal<Readonly<Record<string, unknown>> | null>,
  options?: ResourceOptions<T>,
): MagnaResource<T>
```

Creates a reactive Magna GraphQL resource. When the `variables` signal changes, the resource automatically re-fetches; a `null` variables value puts the resource into idle state (no fetch). `options` is forwarded to `createResource` (`initialData`, `dehydrate`, `store`). Returns a `Resource<T>` (`state`, `refetch`, `invalidate`).

### useMagnaSubscription

```typescript
function useMagnaSubscription<T>(): MagnaSubscriptionHandle<T>
```

Returns a degraded subscription handle in v0.1 — `state` always holds `null`, `close` is an idempotent no-op, and `degraded` is always `true`. A warn-once message is emitted on first call. Real WebSocket/SSE streaming arrives in a later release; branch on `handle.degraded` to stay forward-compatible.

### magna (`/codegen`)

```typescript
function magna(options: MagnaPluginOptions): Plugin
```

Plugin factory that wires the SDL validation pipeline into the aihu `beforeCompile` build hook so typed GraphQL bindings are generated (or gracefully skipped) at build time.

## Types

| Name | Description |
|------|-------------|
| `MagnaPluginOptions` | `url`, `schemaPath` (default `schema.graphql`), `headers`, `gitRev`, `getToken: () => string | null` for per-request JWT relay, and a `fetch` override. |
| `MagnaFetch` | The typed GraphQL fetch function returned by `createMagnaFetch`. |
| `MagnaResource<T>` | Alias of `Resource<T>` from `@aihu-plugin/data`. |
| `MagnaSubscriptionHandle<T>` | `{ state, close, degraded }`. `degraded` is always `true` in v0.1. |
| `MagnaBuildContext` | Extended `BuildContext` passed to the `beforeCompile` hook. |
| `MagnaJwtRelay` | Documentation artifact describing SSR `requireAuth → getToken` and client cookie-backed `ScopeSignal` relay. Never instantiated at runtime. |

## Usage

Register the plugin in your aihu config:

```typescript
// aihu.config.ts
import { magna } from '@aihu/magna/codegen'
import { defineAihuConfig } from '@aihu/server'

export default defineAihuConfig({
  plugins: [magna({ url: process.env.MAGNA_GRAPHQL_URL! })],
})
```

Then drive reactive queries at runtime:

```typescript
import { createMagnaFetch, createMagnaResource } from '@aihu/magna'
import { signal } from '@aihu/signals'

const fetch = createMagnaFetch({
  url: 'https://magna.example.com/graphql',
  getToken: () => readSessionToken(), // per-request JWT relay
})

const [vars] = signal({ id: '42' })
const resource = createMagnaResource(fetch, '{ user { id name } }', vars)
```

## How it relates

JWT relay ties into [`@aihu/auth`](/docs/packages/auth): in SSR contexts `requireAuth(req)` yields the token wrapped in a `getToken` closure, and on the client a cookie-backed `ScopeSignal` feeds `getToken` a live value.

---

# @aihu/scraping

An O(1) fixed-window rate limiter and a Fetch-API bot-detection middleware for aihu agent services. The rate limiter plugs into the same `@aihu/agent-service` enforcement path that `@aihu/auth` extends with scope checks; the bot-detection middleware chains ahead of any fetch-API handler.

## Install

```bash
npm install @aihu/scraping
# or
bun add @aihu/scraping
```

Zero runtime dependencies — the package ships no `dependencies` block.

## API overview

| Name | Kind | Description |
|------|------|-------------|
| `createRateLimiter` | function | Build an O(1) fixed-window `RateLimitPlugin` that parses specs like `'100/min'`. |
| `createRateLimitPlugin` | function | Alias of `createRateLimiter`. |
| `createBotDetectionMiddleware` | function | Fetch-API middleware that blocks known-bot User-Agents and (optionally) missing UAs. |

## Functions

### createRateLimiter

```typescript
function createRateLimiter(options?: RateLimiterOptions): RateLimitPlugin
```

Creates an O(1) fixed-window rate limiter satisfying `RateLimitPlugin`. The returned `checkRateLimit(rateSpec, key)` parses specs of the form `'<n>/<unit>'` (units: `sec` | `min` | `hour`, e.g. `'100/min'`) and returns `true` while the key is within its window. Every operation is O(1): no sorted structures, no expiry scans. `createRateLimitPlugin` is an exported alias.

### createBotDetectionMiddleware

```typescript
function createBotDetectionMiddleware(
  options?: BotDetectionOptions,
): (req: Request, next: () => Response | Promise<Response>) => Response | Promise<Response>
```

Returns a fetch-API middleware that inspects the `User-Agent` header. A UA containing any blocked substring (case-insensitive; the default list plus `options.blockList`) yields a `403`. A missing or empty UA yields a `403` unless `options.allowNoUserAgent` is `true`. Otherwise it delegates to `next()`.

## Types

| Name | Description |
|------|-------------|
| `RateLimiterOptions` | `maxKeys?` (max map size, default `100_000`) and `now?` (clock override for testing, default `Date.now`). |
| `RateLimitPlugin` | `{ checkRateLimit(rateSpec: string, key: string): boolean }`. |
| `BotDetectionOptions` | `blockList?: string[]` (appended to the default block list) and `allowNoUserAgent?` (default `false`). |

## Usage

Wire the rate limiter into an agent service for per-component `$rate-limit` enforcement (the limiter is invoked with each component's `rateLimitSpec`):

```typescript
import { createAgentService } from '@aihu/agent-service'
import { getAllAgentMetadata } from '@aihu/agent'
import { createRateLimiter } from '@aihu/scraping'

const service = createAgentService({
  manifests: getAllAgentMetadata(),
  rateLimitPlugin: createRateLimiter(),
})
```

Chain bot detection ahead of a fetch-API handler:

```typescript
import { createBotDetectionMiddleware } from '@aihu/scraping'

const guard = createBotDetectionMiddleware({ blockList: ['my-bad-bot'] })

export default {
  fetch(req: Request): Response | Promise<Response> {
    return guard(req, () => handleRequest(req))
  },
}
```

## How it relates

The rate limiter plugs into the same agent-service auth/rate-limit path documented in [`@aihu/auth`](/docs/packages/auth): pass `createRateLimiter()` as `rateLimitPlugin` alongside `createAuthPlugin()` as `authPlugin`.

---

# @aihu/seo

aihu SEO plugin: `sitemap.xml`, `robots.txt`, and `llms.txt` route handlers plus JSON-LD structured-data injection via the `afterParse` compiler hook. Routes are framework-agnostic `RouteHandler`s, and the `llms.txt` sections compose cleanly into `@aihu-plugin/agent-readiness` (see the [agent discovery guide](/docs/guides/agent-discovery)).

## Install

```bash
npm install @aihu/seo
# or
bun add @aihu/seo
```

Dependencies: `@aihu/plugin`, `@aihu/server`, and `@aihu-plugin/agent-readiness`.

## API overview

| Name | Kind | Description |
|------|------|-------------|
| `seo` | function | Plugin factory. Registers an `afterParse` hook that injects default JSON-LD into SFC compilation output. |
| `createSeoRoutes` | function | Build framework-agnostic `RouteHandler`s for `/sitemap.xml`, `/robots.txt`, and `/llms.txt`. |
| `seoLlmsSections` | function | Produce `LlmsTxtSection[]` for composition into `@aihu-plugin/agent-readiness`'s `llmsSections` field. |

## Functions

### seo

```typescript
function seo(config: SeoConfig): Plugin
```

Plugin factory. Registers an `afterParse` hook that injects a baseline `WebPage` JSON-LD annotation (built from `config.jsonLdDefaults` merged with `config.baseUrl` as the default page URL) into SFC compilation output. Register it in `defineAihuConfig`.

### createSeoRoutes

```typescript
function createSeoRoutes(config: SeoConfig): SeoRoutes
```

Returns `{ sitemapXml, robotsTxt, llmsTxt }` — three `RouteHandler`s you wire into `@aihu/server` via `defineRoute`. `sitemapXml` serves `application/xml`, while `robotsTxt` and `llmsTxt` serve `text/plain`.

### seoLlmsSections

```typescript
function seoLlmsSections(config: SeoConfig): ReadonlyArray<LlmsTxtSection>
```

Returns an array of `LlmsTxtSection` entries derived from the configured sitemap sources. Spread the result into `@aihu-plugin/agent-readiness`'s `llmsSections` field (`llmsSections: [...userSections, ...seoLlmsSections(config)]`) for a richer, composed `llms.txt`.

## Types

| Name | Description |
|------|-------------|
| `SeoConfig` | `siteName`, `baseUrl` (no trailing slash), optional `sitemapSources?`, `jsonLdDefaults?`, and `robotsOptions?`. |
| `SitemapSource` | `path`, optional `lastmod?` (ISO date), `changefreq?`, and `priority?` (0.0–1.0). |
| `JsonLdPage` | `@context` / `@type` plus arbitrary keys (`name`, `description`, `url`, …). |
| `RobotsOptions` | `disallowAiBots?` (default `true`) and `additionalRules?` (per-user-agent allow/disallow). |
| `SeoRoutes` | `{ sitemapXml, robotsTxt, llmsTxt }` — each a `RouteHandler`. |

## Routes

`createSeoRoutes` produces handlers for the three canonical discovery endpoints:

| Method | Path | Content-Type | Source |
|--------|------|--------------|--------|
| `GET` | `/sitemap.xml` | `application/xml` | `config.sitemapSources` rendered to a sitemap. |
| `GET` | `/robots.txt` | `text/plain` | `config.robotsOptions` (AI bots disallowed by default). |
| `GET` | `/llms.txt` | `text/plain` | `seoLlmsSections(config)`. |

## Usage

```typescript
import { createSeoRoutes } from '@aihu/seo'
import { createRequestRouter, defineRoute } from '@aihu/server'

const seoRoutes = createSeoRoutes({
  siteName: 'My App',
  baseUrl: 'https://example.com',
  sitemapSources: [{ path: '/', priority: 1.0 }, { path: '/about' }],
})

const router = createRequestRouter({
  routes: [
    defineRoute('/sitemap.xml', seoRoutes.sitemapXml),
    defineRoute('/robots.txt', seoRoutes.robotsTxt),
    defineRoute('/llms.txt', seoRoutes.llmsTxt),
  ],
})
```

## How it relates

`llms.txt` and `robots.txt` overlap with [agent discovery](/docs/guides/agent-discovery): use `seoLlmsSections(config)` to feed SEO sources into `@aihu-plugin/agent-readiness` rather than maintaining two `llms.txt` generators.

---

# @aihu/ui

The aihu styled-recipe registry. `@aihu/ui` ships **copy-paste `.aihu` recipes distributed as source** via the `aihu add` CLI — there is no runtime bundle and no `.size-limit.json` row. Recipes are styled custom elements built on the headless [`@aihu/primitives`](/docs/api-reference) behaviors and the [`@aihu/css-engine`](/docs/api-reference) `cn()` helper + `@apply`-in-`@style` utilities. You own the source the moment it lands in your project.

## Install

```bash
bun add -D @aihu/ui
```

`@aihu/ui` is a dev dependency: the CLI reads its recipe catalog at add-time and copies source into your project. Nothing from `@aihu/ui` is bundled into your app.

## Quick start — `aihu add`

```bash
aihu add button                 # copy the button recipe into your project
aihu add button card badge      # several at once
aihu add button --prefix acme   # register as <acme-button> instead of <aihu-button>
aihu add button --dry-run       # show what would be written, write nothing
aihu add button --diff          # diff against an existing copy
aihu add button --force         # overwrite an existing copy
aihu list                       # list every available recipe
aihu list --installed           # list recipes already copied into this project
```

`aihu add` resolves the recipe (and any recipe dependencies) from the installed
`@aihu/ui` registry, rewrites the `aihu-` tag prefix to your configured prefix,
and writes the `.aihu` source into `ui.target`. The recipe's `@style` utilities
compile to scoped shadow-DOM CSS on your next build.

## Configuration

Set the registry, copy target, and tag prefix in `aihu.config.ts`:

```typescript
export default defineAihuConfig({
  ui: {
    registry: '@aihu/ui',          // source registry (default)
    target:   './src/components/ui', // where aihu add copies recipes
    style:    'aihu-default',        // active style pack
    prefix:   'aihu',                // custom-element tag prefix
  },
})
```

## Phase 1 recipes

| Recipe | Built on | Notes |
|---|---|---|
| `button` | extends `@aihu/primitives` `AihuButton` | `variant` + `size` matrices, shared Constructable StyleSheet adopted into shadow DOM |
| `card` | presentational | slotted header / body / footer |
| `badge` | presentational | `variant` matrix |
| `separator` | presentational | `orientation` attribute, `role="separator"` |

Recipe metadata (variants, slots, dependencies) lives in each recipe's `@meta`
block; the registry catalog (`registry.json`) is generated from it.

## How it relates

- [`@aihu/primitives`](/docs/api-reference) — the headless behavior layer recipes extend (ARIA, keyboard, focus). A normal versioned dependency.
- [`@aihu/css-engine`](/docs/api-reference) — supplies `cn()`, the style packs, and the `@apply`/scoped-output engine the recipe `@style` blocks compile through.
- [`@aihu/cli`](/docs/packages/cli) — hosts the `aihu add` / `aihu list` commands.

---