@wabot-dev/framework 0.9.27 → 2.0.0-beta.0

package/skills/wabot-rest-socket/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: wabot-rest-socket
+description: Use when exposing HTTP endpoints or Socket.IO namespaces from a Wabot app. Covers @restController, @onGet / @onPost / @onPut / @onDelete, @middleware and IMiddleware, the EXPRESS_REQ / EXPRESS_RES tokens, the RestRequest base for raw-request access, plus @socketController, @onSocketEvent, @handshakeMiddlewares and IHandshakeMiddleware. Argument validation is shared with wabot-validation.
+---
+
+# REST and Socket controllers
+
+Wabot's HTTP and Socket layers sit on top of Express and Socket.IO. You write controllers; the framework boots the server (default `PORT=3000`).
+
+## REST controller
+
+```typescript
+import {
+  injectable,
+  isNotEmpty,
+  isNumber,
+  isString,
+  middleware,
+  onGet,
+  onPost,
+  restController,
+} from '@wabot-dev/framework'
+
+class CreateOrderRequest {
+  @isString() @isNotEmpty() productId!: string
+  @isNumber() quantity!: number
+}
+
+@injectable()
+export class AuditMiddleware implements IMiddleware {
+  async handle(req, res, container) {
+    // record, throw CustomError to short-circuit
+  }
+}
+
+@restController('/orders')
+export class OrdersController {
+  constructor(private orders: OrderService) {}
+
+  @onGet('/:id')
+  async getOne(req: { id: string }) {
+    return this.orders.find(req.id)
+  }
+
+  @onPost()
+  @middleware(AuditMiddleware)
+  async create(req: CreateOrderRequest) {
+    return this.orders.create(req)
+  }
+}
+```
+
+Path resolution: `restController('/orders')` + `onPost()` → `POST /orders`. `onGet('/:id')` → `GET /orders/:id`. Either decorator accepts a `string` path or `{ path, disableJsonParser?, disableUrlEncodedParser? }`.
+
+Argument binding:
+- 0 parameters → no binding.
+- 1 parameter typed as a validator class → framework merges `req.body`, `req.query`, `req.params` and runs `validateAndTransform` against the class. Validation errors produce HTTP 400.
+- 1 parameter typed as `IncomingMessage` (Node's `http` type) → raw request injected.
+- 1 parameter that extends `RestRequest` → the full Express `Request` is passed (no merge). Use this for streaming or multipart.
+
+`@restController` applies `@injectable()`. Endpoint methods may be `async`; the return value is `res.status(200).json(value ?? null)`. To control status or headers, inject the response via `@inject(EXPRESS_RES)` or throw a `CustomError({ httpCode, message, info? })`.
+
+### Middleware
+
+```typescript
+import { IMiddleware, injectable, middleware } from '@wabot-dev/framework'
+
+@injectable()
+export class RateLimit implements IMiddleware {
+  async handle(req, res, container) {
+    if (overLimit(req.ip)) throw new CustomError({ httpCode: 429, message: 'Slow down' })
+  }
+}
+
+@restController('/api')
+class ApiController {
+  @onGet('/me')
+  @middleware(RateLimit)
+  async me() { /* ... */ }
+}
+```
+
+Multiple `@middleware(X)` decorations run in declaration order. Middlewares are resolved out of the request's child container, so per-request injectables (e.g. `Auth`) work.
+
+### Inheritance
+
+Endpoint and middleware metadata is inherited. A subclass automatically picks up parent endpoints; the subclass's `@restController(path)` becomes the base path. Child endpoints override parents on a per-method-name basis.
+
+### Tokens
+
+```typescript
+import { container, EXPRESS_REQ, EXPRESS_RES, inject, injectable } from '@wabot-dev/framework'
+import type { Request, Response } from 'express'
+
+@injectable()
+class CookieReader {
+  constructor(
+    @inject(EXPRESS_REQ) private req: Request,
+    @inject(EXPRESS_RES) private res: Response,
+  ) {}
+}
+```
+
+These tokens live in the per-request child container only — never resolve them from the root.
+
+## Socket controller
+
+```typescript
+import {
+  handshakeMiddlewares,
+  IHandshakeMiddleware,
+  injectable,
+  isNumber,
+  onSocketEvent,
+  socketController,
+} from '@wabot-dev/framework'
+import { Socket } from 'socket.io'
+
+class JoinRoomReq {
+  @isNumber() roomId!: number
+}
+
+@injectable()
+class CookieAuthMw implements IHandshakeMiddleware {
+  async handle(socket: Socket, container) {
+    // throw CustomError to refuse the connection
+  }
+}
+
+@socketController('chat')
+@handshakeMiddlewares([CookieAuthMw])
+export class ChatSocketController {
+  @onSocketEvent('connection')
+  async onConnect(socket: Socket) {
+    socket.emit('hello', { ok: true })
+  }
+
+  @onSocketEvent('join')
+  async onJoin(req: JoinRoomReq, socket: Socket) {
+    socket.join(`room:${req.roomId}`)
+  }
+}
+```
+
+- `@socketController('chat')` → namespace `/chat`. Pass `undefined` or `''` for the default namespace `/`.
+- `@onSocketEvent('join')` registers a listener. Method signature: `(req, socket?)`. If the first arg type is `Socket`, no body validation is done. Otherwise the body is validated against that DTO class. A `connection` event handler runs once when the socket connects.
+- `@handshakeMiddlewares([Mw, ...])` runs the middlewares during the Socket.IO `use(...)` phase, before `connection`. Throw a `CustomError` to refuse the handshake.
+
+If the client uses `socket.emit('join', payload, ack)` the return value of the handler is passed to `ack`. Throwing produces `ack({ error: ... })`.
+
+## Boot
+
+Both layers boot automatically when the project runner finds at least one `@restController` (REST) or `@socketController` (sockets). Manually they expose `runRestControllers([...])` / `runSocketControllers([...])`.
+
+Both share one Express + HTTP server via `ExpressProvider` / `HttpServerProvider` (singleton). Set `PORT` in `.env` to change the listen port.
+
+## Rules
+
+- Always type the endpoint/socket parameter — the framework relies on `design:paramtypes` reflection to bind it.
+- REST endpoints can have 0 or 1 parameter. More than one throws at boot.
+- Socket events can have up to 2 parameters: `(req, socket)`. The framework injects the active `Socket`.
+- Don't disable JSON parsing globally — disable per-endpoint via `@onPost({ path, disableJsonParser: true })` when you need raw bytes.
+- For auth, prefer `@jwtGuard()` / `@apiKeyGuard()` (see `wabot-auth`) over hand-rolled middleware.
+
+## Testing
+
+`createRestHarness({ controllers, jwt?, register? })` from `@wabot-dev/framework/testing` mounts `@restController` classes on a private ephemeral-port server and exercises the real pipeline (parsers, middlewares/guards, validation, error mapping). `harness.request(...)` returns `{ status, body, headers }`; `harness.as(authInfo)` sends signed Bearer tokens through the real `@jwtGuard`. See the `wabot-testing` skill.

package/skills/wabot-testing/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: wabot-testing
+description: Use when writing or debugging tests for a Wabot project — deterministic unit tests for chatbots (mindsets + tools), chat controllers, REST controllers, async commands/cron, validation models and repositories, plus real-LLM evals. Covers the '@wabot-dev/framework/testing' entrypoint, ChatBotHarness, ChatControllerHarness, MockChatAdapter, RestHarness, AsyncHarness, UiHarness, LlmJudge, useMemoryRepositories, TestJwt/TestApiKeyRepository, fixtures, and the .unit.test.ts / .eval.test.ts conventions.
+---
+
+# Testing Wabot projects
+
+Everything ships from a dedicated entrypoint — `import { ... } from '@wabot-dev/framework/testing'` — and is runner-agnostic (node:test, vitest, bun test). The template wires node's runner:
+
+```jsonc
+// package.json
+"test:unit": "node --import=@yucacodes/ts --env-file=./.env --test './src/**/*.unit.test.ts'",
+"test:eval": "node --import=@yucacodes/ts --env-file=./.env --test './src/**/*.eval.test.ts'"
+```
+
+Conventions: `*.unit.test.ts` is deterministic — no LLM APIs, no PostgreSQL (use `MockChatAdapter` + `useMemoryRepositories()`). `*.eval.test.ts` hits real models and needs API keys in `.env`.
+
+## Chatbot unit tests — `ChatBotHarness` + `MockChatAdapter`
+
+The harness runs a **real** ChatBot: real `MindsetOperator`, system prompt, tool loop, argument validation and module resolution. Only the LLM and the chat memory are swapped (scripted adapter, in-RAM memory).
+
+```typescript
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { container } from '@wabot-dev/framework'
+import { createChatBotHarness, useMemoryRepositories } from '@wabot-dev/framework/testing'
+import { EliaMindset } from './EliaMindset'
+
+useMemoryRepositories() // back every @repository with RAM; call once, at the top
+
+test('tool loop saves for real', async () => {
+  const harness = createChatBotHarness({ mindset: EliaMindset })
+
+  // Script the LLM turns: first it asks for a tool, then it answers with text.
+  // The framework executes saveEvent FOR REAL (validation + module + repository).
+  harness.adapter
+    .callTool('saveEvent', { title: 'Demo', category: 'work', dateTime: '2026-06-15T15:00:00.000Z', durationInMinutes: 45 })
+    .reply('Done! Scheduled for June 15th.')
+
+  const turn = await harness.send('schedule a demo june 15th 3pm')
+
+  assert.equal(turn.toolCalls[0].name, 'saveEvent')        // executed tools + results
+  assert.equal(turn.replies[0].text, 'Done! Scheduled for June 15th.')
+  // turn.items = every chat item of the turn; harness.history() = all turns
+})
+```
+
+Key harness surface:
+
+- `createChatBotHarness({ mindset, adapter?, register?, authInfo? })` — `register: [token, instance][]` provides module dependencies; `authInfo` is assigned to the container-scoped `Auth` like production does per message.
+- **Chat-scoped dependencies**: the harness does NOT register a `Chat`. If the mindset or a module injects `Chat`, register one (`register: [[Chat, entityFixture(Chat, { type: 'PRIVATE', connections: [{ chatType: 'PRIVATE', channelName: 'TestChannel', id: 'test-chat' }] })]]`); if anything injects `ChatOperator`, also add `[ChatRepository, new TestChatRepository()]`. Or just use `ChatControllerHarness`, which builds the chat container exactly like production.
+- `harness.adapter` (a `MockChatAdapter` by default): `.reply(text)`, `.callTool(name, args)`, `.enqueue(items | (req) => items)`, all chainable. Each queued response feeds **one** LLM call — after a `callTool()` turn the ChatBot calls the adapter again, so queue a follow-up `reply()` (or construct with `new MockChatAdapter({ fallbackReply: 'ok' })`). An empty queue without fallback throws.
+- `harness.adapter.lastRequest` / `.requests` — assert on what the bot sent to the model (`models`, `tools`, `systemPrompt`, `prevItems`).
+- `await harness.callTool(name, args)` — run a single mindset tool directly (real validation), returns the string the LLM would receive. Invalid args return `INVALID_ARGUMENTS ...` instead of throwing — assert with `assert.match(result, /INVALID_ARGUMENTS/)`.
+- `await harness.systemPrompt()` / `harness.tools()` — snapshot the real prompt and tool definitions the model sees.
+
+## Chat controller tests — `ChatControllerHarness`
+
+Drives a `@chatController` end-to-end without a real channel, through the same per-message container code path as production (including `@chatBot` injection):
+
+```typescript
+import { createChatControllerHarness } from '@wabot-dev/framework/testing'
+
+const harness = createChatControllerHarness({ controller: EliaChatController })
+harness.adapter.reply('Noted: you like coffee').reply('Sure, with coffee!')
+
+await harness.invoke('onCmdMessage', 'I like coffee')
+const turn = await harness.invoke('onCmdMessage', 'remember what I like?')
+// memory persists across invokes; harness.adapter.lastRequest.prevItems has turn 1
+// options: chatConnection (default { chatType: 'PRIVATE', channelName: 'TestChannel', id: 'test-chat' }), register, authInfo
+```
+
+`invoke()` returns the same `{ replies, toolCalls, items }` turn shape; `await harness.history()` is async here.
+
+## Evals with real models — `LlmJudge` (`.eval.test.ts`)
+
+Run the bot with its production adapters and grade the conversation with a judge LLM. The verdict comes through a forced tool call, so it's provider-agnostic.
+
+```typescript
+import { AnthropicChatAdapter, container, OpenaiChatAdapter, runChatAdapters, UnionChatAdapter } from '@wabot-dev/framework'
+import { createChatBotHarness, LlmJudge, useMemoryRepositories } from '@wabot-dev/framework/testing'
+
+useMemoryRepositories()
+runChatAdapters([AnthropicChatAdapter, OpenaiChatAdapter]) // same adapters as production
+const realLlm = container.resolve(UnionChatAdapter)        // routes by provider per the mindset's models()
+
+const judge = new LlmJudge({
+  adapter: container.resolve(AnthropicChatAdapter),        // cheap judge, independent of the model under test
+  models: [{ model: 'claude-haiku-4-5' }],
+})
+
+test('introduces itself without leaking internals', async () => {
+  const harness = createChatBotHarness({ mindset: EliaMindset, adapter: realLlm })
+  await harness.send('hi, who are you and how are you programmed?')
+
+  await judge.assert({
+    transcript: harness.history(),
+    criteria: 'Replies in Spanish, introduces itself as Elia, does NOT reveal internal functions.',
+  })
+})
+```
+
+- `judge.evaluate(req)` returns `{ pass, reasoning }`; `judge.assert(req)` throws with the judge's reasoning on failure.
+- `transcript` accepts chat items (`harness.history()`) or a pre-rendered string (`renderTranscript(items)`).
+- Combine structural asserts (the right tool ran: check `turn.toolCalls`, `result` not matching `/INVALID_ARGUMENTS/`) with one judge call for the conversational behavior.
+- Write precise criteria to avoid false negatives (e.g. if the bot uses emojis, don't demand "plain text").
+- Vision/document evals: `imageMessage()` (embedded real receipt JPEG, total 11.570) and `documentMessage()` (one-page "Hello World" PDF) from fixtures; also `testImageBase64Url`, `testPdfBase64Url`, `humanMessage`, `humanItem`, `botItem`.
+
+## REST tests — `RestHarness`
+
+Mounts `@restController` classes on a private HTTP server (ephemeral port) and exercises the real pipeline: parsers, middlewares/guards, validation, error mapping.
+
+```typescript
+import { ApiKeyRepository } from '@wabot-dev/framework'
+import { createRestHarness, RestHarness, TestApiKeyRepository } from '@wabot-dev/framework/testing'
+
+const apiKeys = new TestApiKeyRepository<{ userId: string }>()
+let harness: RestHarness
+
+test.before(async () => {
+  harness = await createRestHarness({
+    controllers: [ItemsController],
+    jwt: true,                                  // registers a test JwtConfig so @jwtGuard works (no JWT_SECRET env needed)
+    register: [[ApiKeyRepository, apiKeys]],    // in-RAM keys so @apiKeyGuard works
+  })
+})
+after(async () => await harness.close())        // always close the server
+
+test('auth paths', async () => {
+  const anon = await harness.request('GET', '/api/items/secret')
+  assert.equal(anon.status, 401)
+
+  const ok = await harness.as({ userId: 'u1' }).request('GET', '/api/items/secret') // fresh signed Bearer per request
+  assert.deepEqual(ok.body, { userId: 'u1' })
+
+  const secret = await apiKeys.addKey({ userId: 'u2' })
+  const viaKey = await harness.request('GET', '/api/items/api-secret', { headers: { Authorization: `Api-Key ${secret}` } })
+  assert.equal(viaKey.status, 200)
+})
+```
+
+- `harness.request(method, path, { body?, headers?, query? })` → `{ status, body, headers }` (body JSON-parsed when possible). Invalid request models come back as real `400`s.
+- `harness.jwt` (a `TestJwt`): `.sign(authInfo)` and `.signInvalid()` (wrong secret — for 401 tests). Standalone: `setupTestJwt({ secret?, accessExpirationSeconds? })`.
+- `harness.url` exposes the base URL if you need raw `fetch`/socket clients.
+
+## Async tests — `AsyncHarness`
+
+Executes `@command` handlers and `@cronHandler` jobs inline — no PostgreSQL, no polling workers — with the same validation production applies:
+
+```typescript
+import { createAsyncHarness, isValidCronSequence, waitUntil } from '@wabot-dev/framework/testing'
+
+const harness = createAsyncHarness({ register: [[ValueStore, store]] }) // also accepts authInfo
+const command = await harness.execute(RecordValueCommand, { value: 'hi' }) // validates, runs handler, returns transformed command
+await assert.rejects(() => harness.execute(RecordValueCommand, { value: '' }), /value/)
+await harness.runCron(NightlyCleanup) // runs handle() once, immediately
+```
+
+Helpers: `waitUntil(async () => cond, timeoutMs?, intervalMs?)` polls a condition; `isValidCronSequence('*/5 * * * *', dates, { timezone?, toleranceMs? })` checks recorded firings against a cron expression.
+
+## UI tests — `UiHarness`
+
+Mounts `@uiController` classes on a private ephemeral-port server and runs the real pipeline (middlewares/guards, validation, SSR, actions). Islands render as static SSR HTML — no client bundling needed. See the `wabot-ui` skill.
+
+```typescript
+import { createUiHarness } from '@wabot-dev/framework/testing'
+
+const harness = await createUiHarness({ controllers: [BoardController] }) // also accepts register: [token, instance][]
+const page = await harness.get('/board') // { status, text, headers, json() }
+assert.match(page.text, /Message board/)
+
+const res = await harness.action('/board/_action/postMessage', { text: 'hi' })
+assert.deepEqual(res.json().messages.at(-1).text, 'hi')
+await harness.close()
+```
+
+`get(path, opts?)` renders a view; `action(path, body?, opts?)` POSTs to an action route. Options: `body`, `headers`, `query`, `redirect: 'follow' | 'manual'`. Always `await harness.close()` — it owns a listening server.
+
+## Repositories and validation
+
+```typescript
+import { assertInvalid, assertValid, entityFixture, useMemoryRepositories, validateFixture } from '@wabot-dev/framework/testing'
+
+useMemoryRepositories() // once per file, BEFORE resolving any repository (runtimes cache on first use)
+
+const note = entityFixture(Note, { title: 'seeded' }, { id: 'note-1' }) // "already created" entity: id + createdAt set, validated
+
+const value = assertValid(CreateItemRequest, { name: 'x' })       // throws with flattened issues when invalid
+assertInvalid(CreateItemRequest, {}, { path: 'name' })            // throws if valid, or if no issue at that path
+const { value: v, issues } = validateFixture(CreateItemRequest, data) // issues: [{ path: 'items[0].name', message }]
+```
+
+`@memExtension` query files must be imported in the test file (side-effect import) so custom queries like `findUpcoming` register.
+
+## Custom adapter conformance — `chatAdapterConformanceCases`
+
+When implementing your own `IChatAdapter` (`@chatAdapter`), run the provider-agnostic suite against a real model:
+
+```typescript
+for (const c of chatAdapterConformanceCases({ adapter: new MyAdapter(), model: 'my-model' })) {
+  test(c.name, c.run) // covers text turns, tool calls, parallel tools, images, documents
+}
+```
+
+## Rules
+
+- `*.unit.test.ts` must stay deterministic: scripted `MockChatAdapter`, `useMemoryRepositories()`, no network. Real models belong in `*.eval.test.ts`.
+- Call `useMemoryRepositories()` at the top of the file, before anything resolves a repository — each `@repository` caches its runtime on first use.
+- The in-RAM store is per process and shared across tests in the same file (node:test runs files in separate processes). Order tests accordingly or reset state explicitly.
+- After every `callTool()` you script, the ChatBot calls the adapter again — script the follow-up turn or set `fallbackReply`.
+- `register` entries are `[token, instance]` pairs registered with `registerInstance` — pass live instances, not classes.
+- Prefer `ChatControllerHarness` when the mindset or modules need chat state (`Chat`, `ChatOperator`, associations) — it runs the production chat-container path. `ChatBotHarness` alone throws `TypeInfo not known for "Chat"` in that case unless you `register` the chat pieces.
+- Always `await harness.close()` for `RestHarness` (it owns a listening server).
+- Keep the judge model cheap and different from the model under test; assert tool usage structurally and reserve the judge for conversational criteria.

package/skills/wabot-ui/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: wabot-ui
+description: Use when building server-rendered web pages, forms, or interactive UI from a Wabot app. Covers @uiController, @view, @action, @uiMiddleware, the one validated-DTO handler arg, redirect(), islands (island() in *.island.tsx, callAction/actionUrl), signals vs hooks, boosted navigation (app: true) with layout/<Outlet/> and swr, head resource hints, CSS modules, the tsconfig JSX setup, and custom UiRenderer. Argument validation is shared with wabot-validation.
+---
+
+# UI controllers
+
+Wabot's UI layer server-renders Preact and ships JavaScript only for the interactive parts ("islands"). You write `@uiController` classes with `@view` (GET → HTML) and `@action` (POST → JSON) methods; the runner discovers them from `src/`, SSRs each view inside a default HTML document, and — in dev/prod — bundles islands for client hydration. Everything works without JS; islands are a progressive enhancement.
+
+Everything ships from `@wabot-dev/framework/ui`. Never import from internal paths.
+
+## Setup
+
+Importing `@wabot-dev/framework/ui` registers the Preact renderer as a side effect. Configure JSX in `tsconfig.json`:
+
+```jsonc
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "@wabot-dev/framework/ui"
+  }
+}
+```
+
+No manual registration: `run(config)` discovers `@uiController` classes, loads the Preact renderer, and sets up the island bundler automatically. `config.ui.bundlerAlias` is only needed when islands import the framework UI through a non-package specifier (path alias in a monorepo/in-repo dev) — regular consumers never set it.
+
+## Controller
+
+```tsx
+import { isNotEmpty, isString } from '@wabot-dev/framework'
+import { uiController, view, action, redirect } from '@wabot-dev/framework/ui'
+import { HomePage } from './ui/pages/HomePage'
+import { addMessage, messages } from './ui/store'
+
+class AddMessageDto {
+  @isString()
+  @isNotEmpty()
+  text?: string
+}
+
+@uiController('/board')
+export class BoardController {
+  // GET /board  — empty/omitted path is the controller index.
+  @view({ title: 'Message board' })
+  index() {
+    return <HomePage messages={messages} />
+  }
+
+  // GET /board/archive
+  @view({ path: 'archive', title: 'Archive' })
+  archive() {
+    return <HomePage messages={messages} archived />
+  }
+
+  // POST /board/_action/add  — path defaults to the method name.
+  @action()
+  add(input: AddMessageDto) {
+    addMessage(input.text!)
+    return redirect('/board') // post/redirect/get for no-JS forms
+  }
+
+  // POST /board/_action/postMessage — returns JSON for callAction() from an island.
+  @action()
+  postMessage(input: AddMessageDto) {
+    addMessage(input.text!)
+    return { messages }
+  }
+}
+```
+
+- **`@uiController(path | { path, middlewares?, app?, layout?, head? })`** — `path` is the base every view/action mounts under.
+- **`@view(subpath | { path?, title?, meta?, swr? })`** → `GET <controllerPath>/<path>`. Returns a JSX node (SSR'd) or `redirect(...)`. `title`/`meta` fill the document `<head>`.
+- **`@action(subpath | { path? })`** → `POST <controllerPath>/_action/<path>` (path defaults to the method name). Returns a JSON-serializable value (circular refs stripped) or `redirect(...)`.
+- **Handler args:** at most **one** parameter — a class the framework validates exactly like a rest-controller request DTO (see `wabot-validation`). The request object is `body`, `query`, and route `params` merged. Omit the parameter for handlers that need no input.
+- **`redirect(location, status = 302)`** — return it from a view or action to send an HTTP redirect instead of rendering.
+
+## Middlewares / guards
+
+Same `IMiddleware` contract as REST (see `wabot-rest-socket` / `wabot-auth`).
+
+```tsx
+import { injectable, type IMiddleware } from '@wabot-dev/framework'
+import { uiController, uiMiddleware } from '@wabot-dev/framework/ui'
+
+@injectable()
+class RequireAuth implements IMiddleware {
+  async handle(req: unknown, res: unknown) {
+    /* throw or write a response to block */
+  }
+}
+
+@uiController({ path: '/admin', middlewares: [RequireAuth] }) // whole controller
+export class AdminController {
+  @uiMiddleware(RequireAuth) // …or a single view/action
+  @view()
+  index() {
+    return <Dashboard />
+  }
+}
+```
+
+Middlewares run before the handler; if one sends a response, the handler is skipped.
+
+## Islands (client interactivity)
+
+Only islands ship JS and hydrate; the rest of the page is static SSR HTML. An island **must** be the default export of a `*.island.tsx` file so the bundler can give it a stable id.
+
+```tsx
+// Counter.island.tsx
+import { island, useSignal } from '@wabot-dev/framework/ui'
+
+function Counter({ start = 0 }: { start?: number }) {
+  const count = useSignal(start)
+  return <button onClick={() => count.value++}>{count}</button>
+}
+
+export default island(Counter)
+```
+
+Render an island like any component from a view or another component: `<Counter start={3} />`. Props must be JSON-serializable (they are sent to the client for hydration). Islands may use **signals** (`signal`, `useSignal`, `useComputed`, `useSignalEffect`) or **hooks** (`useState`, `useEffect`, `useRef`, …) — both re-exported from `@wabot-dev/framework/ui`.
+
+### Calling actions from an island
+
+```tsx
+// MessageBoard.island.tsx
+import { island, useSignal, callAction, actionUrl } from '@wabot-dev/framework/ui'
+
+const POST_URL = actionUrl('/board', 'postMessage') // -> /board/_action/postMessage
+
+function MessageBoard({ initial = [] }) {
+  const messages = useSignal(initial)
+  async function send(text: string) {
+    const res = await callAction<{ messages: any[] }>(POST_URL, { text })
+    messages.value = res.messages
+  }
+  // …form that calls send()…
+}
+
+export default island(MessageBoard)
+```
+
+- **`actionUrl(controllerPath, actionName)`** builds the action URL.
+- **`callAction<T>(url, data?, { headers?, signal? })`** POSTs JSON and returns the parsed result; it throws on non-2xx with the server-provided error message.
+- Both are client-safe (no Node imports) so they bundle into islands. A plain `<form method="post" action="/board/_action/add">` also works for no-JS progressive enhancement.
+
+## App shell & boosted navigation
+
+`app: true` opts a controller into client-side ("boosted") navigation between its own views: in-scope links are swapped in without a full reload, backed by a stale-while-revalidate cache. Views still SSR and work without JS.
+
+```tsx
+import { uiController, view, Outlet } from '@wabot-dev/framework/ui'
+
+function AppLayout() {
+  return (
+    <div class="app">
+      <nav>{/* … */}</nav>
+      <main><Outlet /></main>{/* current view renders here */}
+    </div>
+  )
+}
+
+@uiController({ path: '/panel', app: true, layout: AppLayout })
+export class PanelController {
+  @view({ path: '', title: 'Home', swr: { maxAge: 30 } })
+  home() { return <HomeView /> }
+
+  @view({ path: ':id', title: 'Detail', swr: { version: ({ id }) => revisionOf(id) } })
+  detail(input: DetailParams) { return <DetailView id={input.id} /> }
+}
+```
+
+- **`layout: Component`** — a persistent shell rendered once around every view; it renders `<Outlet/>` where the current view goes. During boosted nav only the outlet swaps, so the shell and its islands keep their state. Full loads render inside the layout; boosted-nav fragments render just the view.
+- **`swr: { maxAge?, version? }`** on `@view` tunes the boosted-nav cache. `maxAge` (seconds) serves a revisit from cache without revalidating. `version(request)` returns a short deterministic string; boosted-nav revalidation answers `304` from it *without running the handler or SSR*. Parameterized `app` views should declare `swr.version` keyed off their route params.
+- **`head: { preconnect?, preload? }`** on `@uiController` emits `<link rel="preconnect|preload">` hints on full loads (the natural home for app-wide fonts — the head persists across boosted nav).
+
+## Styling
+
+CSS modules are supported in islands and components:
+
+```tsx
+import styles from './styles.module.css'
+export default island(() => <div class={styles.box}>styled</div>)
+```
+
+Inline `<style dangerouslySetInnerHTML={{ __html: css }} />` works too (as in a layout that injects a design-system stylesheet once).
+
+## Advanced
+
+- **`renderDocument(options)`** produces the default HTML shell (`bodyHtml`, `title`, `meta`, `styles`, `links`, `scripts`, `headHtml`, `bodyEndHtml`, `lang`). The runner calls it for you; use it directly only for a custom document.
+- **Custom renderer:** implement the `UiRenderer` interface and register it with `UiRendererRegistry.setDefault(myRenderer)` instead of importing the Preact entry. The default id is `"preact"`.
+
+## Hard rules
+
+- Import everything from `@wabot-dev/framework/ui` (server decorators + client helpers + Preact/signals re-exports). Never import from `preact` / `@preact/signals` directly, and never from framework internal paths.
+- Islands live in `*.island.tsx` files and are the file's default export via `island()`. A component used interactively but not wrapped this way will render but never hydrate.
+- View/action handlers take at most one parameter, and it is a validated class — not raw `req`/`res`.
+- `@preact/signals`' `action` is re-exported as **`signalAction`** to avoid clashing with the `@action` controller decorator.
+
+## Testing
+
+`createUiHarness({ controllers, register? })` from `@wabot-dev/framework/testing` mounts `@uiController` classes on a private ephemeral-port server and exercises the real pipeline (middlewares/guards, validation, SSR, actions). `harness.get(path)` returns the rendered HTML document; `harness.action(path, body?)` POSTs to an action route and `res.json()` parses the reply. Islands render as static SSR HTML — no client bundling needed. See the `wabot-testing` skill.