toiljs 0.0.67 → 0.0.69

package/src/compiler/toil-docs.generated.ts

@@ -5,8 +5,8 @@
 
 /** The framework guides written into `.toil/docs/`, keyed by filename, generated from `docs/`. */
 export const TOIL_DOCS: Record<string, string> = {
-    "index.md": "# toiljs\n\nA full-stack React framework: a Vite-bundled client SPA with file-based routing, plus a\ntoilscript-to-WebAssembly server target.\n\n## Project layout\n\n- `client/`, the app: `routes/` (file-based), `layout.tsx`, `components/`, `styles/`,\n  `public/`, and `toil.tsx` (the entry that calls `Toil.mount`).\n- `server/`, the toilscript → WASM target (`@main` entry), compiled by `toilscript`.\n  `@data`/`@remote`/`@service` here generate the typed client `Server` API (see [server.md](./server.md)).\n- `toil.config.ts`, configuration via `defineConfig` (`toiljs.config.ts` also works).\n- Generated, gitignored, do not edit: `.toil/` (working dir), `toil-env.d.ts` (ambient\n  globals), `toil-routes.d.ts` (typed routes), `shared/server.ts` (the typed RPC module,\n  emitted by the server build; import `@data` classes from `shared/server`).\n\n## Key ideas\n\n- `Toil` is a native global (no import): `Toil.Link`, `Toil.useRouter`, `Toil.useLoaderData`,\n  etc. The IO classes (`FastMap`, `FastSet`, `DataWriter`, `DataReader`), `parseError`, and the\n  generated `Server` RPC surface are globals too.\n- Scripts: `npm run dev` (HMR), `npm run build` (→ `build/client` + `build/server`),\n  `npm start` (self-host the build).\n- Compute tiers: the server can span L1 request (`server/main.ts`, `@rest`/`@service`/`@remote`),\n  L2/L3 stream (`server/main.stream.ts`, `@stream`), and L4 daemon (`server/main.daemon.ts`,\n  `@daemon`/`@scheduled`); each tier compiles into its own artifact. See [tiers.md](./tiers.md).\n\nSee [routing.md](./routing.md), [client.md](./client.md), [styling.md](./styling.md),\n[server.md](./server.md), [ssr.md](./ssr.md), [rpc.md](./rpc.md), [tiers.md](./tiers.md),\n[streams.md](./streams.md), [daemon.md](./daemon.md), [cli.md](./cli.md).\n",
-    "getting-started.md": "# Getting started\n\nA toiljs app has two halves that build and ship together:\n\n- a **server** written in ToilScript, compiled to a single WebAssembly module\n  (`build/server/release.wasm`), and\n- a **client** (Vite + React) that talks to the server through a generated,\n  fully typed `Server` proxy.\n\nThe server runs one fresh wasm instance per request, identically on the dev\nserver and on the edge. There is no Node.js in the request path: your handler is\nwasm.\n\n## Project layout\n\n```\nproject/\n  toilconfig.json          server (wasm) build config: entries, target, AS options\n  toil.config.ts           client config (defineConfig: dev/build/SEO options)\n\n  server/\n    main.ts                wires Server.handler, re-exports the wasm exports + abort\n    routes/*.ts            @rest controllers           (auto-discovered)\n    services/*.ts          @service / @remote          (auto-discovered)\n    core/AppHandler.ts     your top-level ToilHandler\n    models/*.ts            @data / @user classes\n\n  shared/\n    server.ts              GENERATED by the server build (--rpcModule): the typed\n                           client surface (Server proxy, @data codecs, getUser)\n\n  client/\n    routes/*.tsx           file-based pages\n    layout.tsx, 404.tsx    root layout / not-found\n    styles/*.css\n\n  build/\n    server/release.wasm    compiled server (+ release.wat text form)\n    client/                Vite output\n```\n\nThe compiler discovers every `.ts` under `server/` that declares a decorated\nsurface (`@rest`, `@service`, `@remote`, `@data`, `@user`) on its own. Importing\nthose modules from `main.ts` is still good practice: it keeps a direct\n`toilscript` run (which only sees the `toilconfig.json` entries) building the\nexact same server.\n\n## `main.ts`\n\nThree things are required, and the comments in the scaffold say so:\n\n```ts\nimport { Server } from 'toiljs/server/runtime';\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\n\nimport { AppHandler } from './core/AppHandler';\n\n// Pull every decorated surface into a direct `toilscript` build.\nimport './routes/Players';\nimport './services/Stats';\n\n// 1. The handler factory: one fresh handler instance per request.\nServer.handler = () => new AppHandler();\n\n// 2. Re-export the wasm entrypoints (`handle`, `render`).\nexport * from 'toiljs/server/runtime/exports';\n\n// 3. The AssemblyScript trap hook.\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n    revertOnError(message, fileName, line, column);\n}\n```\n\nIf all you need is `@rest` routing, your handler can be `RestHandler` (see\n[Routing](./routing.md)) and you do not have to write an `AppHandler` at all.\n\n## The request lifecycle\n\nFor each request the runtime (`server/runtime/exports`):\n\n1. decodes the request envelope into a [`Request`](./routing.md#request),\n2. publishes it ambiently as `Server.currentRequest` (so `AuthService.getUser()`\n   and friends can read its cookies with no argument),\n3. builds the handler via `Server.handler()` and calls\n   `onRequestStarted` → `handle(req)` → `onRequestCompleted`,\n4. encodes the returned [`Response`](./routing.md#response) and clears the\n   ambient request.\n\nBecause the instance is fresh and memory is wiped between requests, **nothing in\nmodule globals survives across requests.** Anything that must persist (accounts,\nsessions you do not put in a cookie, rate-limit counters) belongs in an external\nstore reached through a host binding.\n\n## CLI\n\nThe `toiljs` CLI drives both halves:\n\n| Command | What it does |\n| --- | --- |\n| `toiljs create [name]` | Scaffold a new app (templates, styling, options). |\n| `toiljs dev` | Dev server with hot reload: watches `server/`, rebuilds the wasm via toilscript, regenerates `shared/server.ts`, and runs Vite for the client. Flags: `--root <dir>`, `--port <n>`, `--host`. |\n| `toiljs build` | Production build: server wasm first (so `shared/server.ts` is fresh), then the Vite client + static prerender. Flags: `--root <dir>`, `--server` (server only). |\n| `toiljs start` | Self-host a built app. Flags: `--root`, `--port`, `--host`. |\n| `toiljs doctor` | Diagnose setup/deps (`--json`, `--fix`). |\n\nIn dev, requests whose method matches a dispatchable verb go into the wasm\nfirst; if the guest reports \"no route matched\" (the `x-toil-unhandled` marker)\nthe request falls through to Vite, so client routes and assets just work\nalongside your API.\n\n## Building the server by hand\n\n`toiljs build` runs toilscript for you, but you can invoke it directly (this is\nwhat the examples do):\n\n```sh\ntoilscript --target release --rpcModule shared/server.ts\n```\n\n`--target release` reads `toilconfig.json` and emits the wasm at\n`targets.release.outFile`; `--rpcModule shared/server.ts` writes the generated\ntyped client (see [RPC](./rpc.md)).\n\n## Next\n\n- [Routing](./routing.md) to expose HTTP endpoints.\n- [Data codec](./data.md) for request/response bodies.\n- [Auth](./auth.md) for login and sessions.\n",
+    "index.md": "# toiljs\n\nA full-stack React framework: a Vite-bundled client SPA with file-based routing, plus a\ntoilscript-to-WebAssembly server target.\n\n## Project layout\n\n- `client/`, the app: `routes/` (file-based), `layout.tsx`, `components/`, `styles/`,\n  `public/`, and `toil.tsx` (the entry that calls `Toil.mount`).\n- `server/`, the toilscript → WASM target (`@main` entry), compiled by `toilscript`.\n  `@data`/`@remote`/`@service` here generate the typed client `Server` API (see [server.md](./server.md)).\n- `toil.config.ts`, configuration via `defineConfig` (`toiljs.config.ts` also works).\n- Generated, gitignored, do not edit: `.toil/` (working dir), `toil-env.d.ts` (ambient\n  globals), `toil-routes.d.ts` (typed routes), `shared/server.ts` (the typed RPC module,\n  emitted by the server build; import `@data` classes from `shared/server`).\n\n## Key ideas\n\n- `Toil` is a native global (no import): `Toil.Link`, `Toil.useRouter`, `Toil.useLoaderData`,\n  etc. The IO classes (`FastMap`, `FastSet`, `DataWriter`, `DataReader`), `parseError`, and the\n  generated `Server` RPC surface are globals too.\n- Scripts: `npm run dev` (HMR), `npm run build` (→ `build/client` + `build/server`),\n  `npm start` (self-host the build).\n- Compute tiers: the server can span L1 request (`server/main.ts`, `@rest`/`@service`/`@remote`),\n  L2/L3 stream (`server/main.stream.ts`, `@stream`), and L4 daemon (`server/main.daemon.ts`,\n  `@daemon`/`@scheduled`); each tier compiles into its own artifact. See [tiers.md](./tiers.md).\n\nSee [routing.md](./routing.md), [client.md](./client.md), [styling.md](./styling.md),\n[server.md](./server.md), [ssr.md](./ssr.md), [rpc.md](./rpc.md), [tiers.md](./tiers.md),\n[streams.md](./streams.md), [daemon.md](./daemon.md), [derive.md](./derive.md), [cli.md](./cli.md).\n",
+    "getting-started.md": "# Getting started\n\nA toiljs app has two halves that build and ship together:\n\n- a **server** written in ToilScript, compiled to a single WebAssembly module\n  (`build/server/release.wasm`), and\n- a **client** (Vite + React) that talks to the server through a generated,\n  fully typed `Server` proxy.\n\nThe server runs one fresh wasm instance per request, identically on the dev\nserver and on the edge. There is no Node.js in the request path: your handler is\nwasm.\n\n## Project layout\n\n```\nproject/\n  toilconfig.json          server (wasm) build config: entries, target, AS options\n  toil.config.ts           client config (defineConfig: dev/build/SEO options)\n\n  server/\n    main.ts                wires Server.handler, re-exports the wasm exports + abort\n    routes/*.ts            @rest controllers           (auto-discovered)\n    services/*.ts          @service / @remote          (auto-discovered)\n    core/AppHandler.ts     your top-level ToilHandler\n    models/*.ts            @data / @user classes\n\n  shared/\n    server.ts              GENERATED by the server build (--rpcModule): the typed\n                           client surface (Server proxy, @data codecs, getUser)\n\n  client/\n    routes/*.tsx           file-based pages\n    layout.tsx, 404.tsx    root layout / not-found\n    styles/*.css\n\n  build/\n    server/release.wasm    compiled server (+ release.wat text form)\n    client/                Vite output\n```\n\nThe compiler discovers every `.ts` under `server/` that declares a decorated\nsurface (`@rest`, `@service`, `@remote`, `@data`, `@user`) on its own. Importing\nthose modules from `main.ts` is still good practice: it keeps a direct\n`toilscript` run (which only sees the `toilconfig.json` entries) building the\nexact same server.\n\n## `main.ts`\n\nThree things are required, and the comments in the scaffold say so:\n\n```ts\nimport { Server } from 'toiljs/server/runtime';\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\n\nimport { AppHandler } from './core/AppHandler';\n\n// Pull every decorated surface into a direct `toilscript` build.\nimport './routes/Players';\nimport './services/Stats';\n\n// 1. The handler factory: one fresh handler instance per request.\nServer.handler = () => new AppHandler();\n\n// 2. Re-export the wasm entrypoints (`handle`, `render`).\nexport * from 'toiljs/server/runtime/exports';\n\n// 3. The AssemblyScript trap hook.\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n    revertOnError(message, fileName, line, column);\n}\n```\n\nIf all you need is `@rest` routing, your handler can be `RestHandler` (see\n[Routing](./routing.md)) and you do not have to write an `AppHandler` at all.\n\n## The request lifecycle\n\nFor each request the runtime (`server/runtime/exports`):\n\n1. decodes the request envelope into a [`Request`](./routing.md#request),\n2. publishes it ambiently as `Server.currentRequest` (so `AuthService.getUser()`\n   and friends can read its cookies with no argument),\n3. builds the handler via `Server.handler()` and calls\n   `onRequestStarted` → `handle(req)` → `onRequestCompleted`,\n4. encodes the returned [`Response`](./routing.md#response) and clears the\n   ambient request.\n\nBecause the instance is fresh and memory is wiped between requests, **nothing in\nmodule globals survives across requests.** Anything that must persist (accounts,\nsessions you do not put in a cookie, rate-limit counters) belongs in an external\nstore reached through a host binding.\n\n## CLI\n\nThe `toiljs` CLI drives both halves:\n\n| Command                | What it does                                                                                                                                                                                  |\n| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `toiljs create [name]` | Scaffold a new app (templates, styling, options).                                                                                                                                             |\n| `toiljs dev`           | Dev server with hot reload: watches `server/`, rebuilds the wasm via toilscript, regenerates `shared/server.ts`, and runs Vite for the client. Flags: `--root <dir>`, `--port <n>`, `--host`. |\n| `toiljs build`         | Production build: server wasm first (so `shared/server.ts` is fresh), then the Vite client + static prerender. Flags: `--root <dir>`, `--server` (server only).                               |\n| `toiljs start`         | Self-host a built app with production uWS/static workers, no Vite. Flags: `--root`, `--port`, `--host`, `--threads`.                                                                          |\n| `toiljs doctor`        | Diagnose setup/deps (`--json`, `--fix`).                                                                                                                                                      |\n\nIn dev, requests whose method matches a dispatchable verb go into the wasm\nfirst; if the guest reports \"no route matched\" (the `x-toil-unhandled` marker)\nthe request falls through to Vite, so client routes and assets just work\nalongside your API.\n\n## Building the server by hand\n\n`toiljs build` runs toilscript for you, but you can invoke it directly (this is\nwhat the examples do):\n\n```sh\ntoilscript --target release --rpcModule shared/server.ts\n```\n\n`--target release` reads `toilconfig.json` and emits the wasm at\n`targets.release.outFile`; `--rpcModule shared/server.ts` writes the generated\ntyped client (see [RPC](./rpc.md)).\n\n## Next\n\n- [Routing](./routing.md) to expose HTTP endpoints.\n- [Data codec](./data.md) for request/response bodies.\n- [Auth](./auth.md) for login and sessions.\n",
     "routing.md": "# Routing\n\ntoiljs routing is decorator-driven. You write a controller class, annotate it\nwith `@rest` and its methods with verb decorators, and the ToilScript compiler\ngenerates the dispatcher. Routes can take a typed body, read path params and the\nraw request through a `RouteContext`, and return either a `Response` or a typed\nvalue that is auto-encoded.\n\n```ts\nimport { Response, RouteContext } from 'toiljs/server/runtime';\n\n@rest('players')\nclass Players {\n  @get('/:id')\n  public get(ctx: RouteContext): Response {\n    const id = ctx.param('id');\n    return Response.json(`{\"id\":\"${id}\"}`);\n  }\n\n  @post('/')\n  public create(input: NewPlayer): Player {\n    // `input` is the decoded request body; returning a @data value JSON-encodes it\n    return Player.from(input);\n  }\n}\n```\n\n## `@rest` controllers\n\n`@rest` marks a class as a route controller and mounts it at a prefix.\n\n```ts\n@rest('api')                              // mounted at /api\n@rest('/')               // or @rest('')  // mounted at the root\n@rest({ stream: DataStream.Binary })      // root mount, binary codec by default\n```\n\n- The string argument is the mount prefix. `\"api\"`, `\"/api\"`, and `\"api/\"` all\n  normalize to `/api`; `\"\"` and `\"/\"` mean the root.\n- The object form sets class-wide defaults. `stream: DataStream.Binary` makes\n  every route in the class use the binary `@data` codec; the default is\n  `DataStream.JSON`. Individual routes override this with `@route`.\n\nThe compiler injects, at module init, a registration that adds the controller to\nthe global `Rest` registry. Controllers dispatch in the order their modules are\nloaded; routes within a controller try in declaration order, first match wins.\n\n## Verb decorators\n\nEach HTTP method has a decorator taking a single path string:\n\n```ts\n@get('/path')   @post('/path')   @put('/path')   @delete('/path')\n@patch('/path') @head('/path')   @options('/path')\n```\n\nThe full path is the controller prefix joined with the route path\n(`prefix=\"/api\"`, `@get(\"/todos/:id\")` → `/api/todos/:id`).\n\n### `@route` (explicit form)\n\n`@route` is the general form; use it when you need to set the stream mode per\nroute or prefer an object:\n\n```ts\n@route({ method: Methods.POST, path: '/upload', stream: DataStream.Binary })\npublic upload(body: FileData): FileResult { /* ... */ }\n```\n\n`method` (from the `Methods` enum) and `path` are required; `stream` is\noptional and overrides the controller default.\n\n## Path parameters\n\nA `:name` segment captures that URL segment. Read it with `ctx.param(\"name\")`:\n\n```ts\n@get('/todos/:id/items/:itemId')\npublic getItem(ctx: RouteContext): Response {\n  const id = ctx.param('id');\n  const itemId = ctx.param('itemId');\n  return Response.json(`{\"todo\":\"${id}\",\"item\":\"${itemId}\"}`);\n}\n```\n\nMatching is segment-exact: the request path must have the same number of\nsegments, static segments must match literally, and `:param` segments capture\nthe value. The query string is stripped before matching.\n\n## Method parameters\n\nA route method takes zero, one, or two parameters, classified by type:\n\n- a `RouteContext` parameter receives the match context (path params, query,\n  headers, raw body);\n- any other type is treated as the **request body**, decoded as a `@data` value.\n\n```ts\n@get('/status')\npublic status(): StatusResponse { /* no body, no context */ }\n\n@get('/user/:id')\npublic getUser(ctx: RouteContext): User { /* context only */ }\n\n@post('/create')\npublic create(input: NewTodo): Todo { /* body only */ }\n\n@post('/user/:id/score')\npublic addScore(input: ScoreDelta, ctx: RouteContext): Player {\n  const id = ctx.param('id'); /* body AND context */\n}\n```\n\nThe body is decoded per the route's stream mode: in JSON mode from\n`JSON.parse(ctx.text())`, in Binary mode from `Body.decode(req.body)`. See\n[Data codec](./data.md).\n\n## Return types\n\nThe compiler encodes the return value by its type:\n\n| Return type | Result |\n| --- | --- |\n| `Response` | Returned as-is. Full control over status, headers, body. |\n| `void` | `204 No Content`. |\n| a `@data` type, JSON stream | `Response.json(value.toJSON().toString())`. |\n| a `@data` type, Binary stream | `Response.bytes(value.encode())`. |\n\nReturning a `Response` lets you set status, headers, cookies, and caching\ndirectly; returning a typed value is the terse path when you just want the data\nserialized.\n\n## Data streams\n\nEach route is either **JSON** (default) or **Binary**:\n\n- **JSON**, the body is `JSON.parse`d and revived via the `@data` type's\n  `fromJSON`; the response is the type's `toJSON()`. 64-bit-and-larger integers\n  cross the wire as decimal strings (exact at any size). Best for endpoints a\n  browser or third party calls directly.\n- **Binary**, the body is `Body.decode(bytes)` and the response is\n  `value.encode()`, using the deterministic `DataWriter`/`DataReader` codec. No\n  precision loss, smaller, faster. Best for app-to-app and anything\n  security-sensitive.\n\nSet the mode on the controller (`@rest({ stream: DataStream.Binary })`) or per\nroute (`@route({ ..., stream: DataStream.Binary })`).\n\n## Dispatch and the 404 fallback\n\nAt runtime the global `Rest` registry tries each controller in order:\n\n```ts\nconst hit = Rest.dispatch(req); // Response | null\nif (hit != null) return hit;    // first matching route's Response\nreturn Response.unhandled();    // no route matched\n```\n\n`RestHandler` is a ready-made handler that does exactly this, so a REST-only app\nneeds no custom handler:\n\n```ts\nimport { RestHandler } from 'toiljs/server/runtime';\nServer.handler = () => new RestHandler();\n```\n\n`Response.unhandled()` is a `404` carrying the `x-toil-unhandled` marker header.\nOn the dev server and edge that marker means \"no route matched here\" and lets\nthe request fall through to the next layer (Vite in dev, static/SSR on the\nedge). A deliberate `Response.notFound()` does **not** carry the marker and is\nsent to the client verbatim.\n\n---\n\n## `Request`\n\nThe decoded incoming request (`server/runtime/request.ts`).\n\n### Fields\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `method` | `Method` | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`, `UNKNOWN`. |\n| `path` | `string` | Path including the query string. |\n| `headers` | `Array<Header>` | Ordered; a `Header` is `{ name, value }`. |\n| `body` | `Uint8Array` | Raw request body bytes. |\n\n### Methods\n\n| Method | Signature | Notes |\n| --- | --- | --- |\n| `header` | `header(name: string): string \\| null` | Case-insensitive lookup, `null` if absent. |\n| `cookies` | `cookies(): CookieMap` | Parses the `Cookie` header (percent-decoded values); cached for the request. |\n| `cookie` | `cookie(name: string): string \\| null` | A single cookie value, or `null`. |\n\nThe `Method` enum and `Header` class are exported from\n`toiljs/server/runtime`.\n\n## `RouteContext`\n\nPassed to any route method that declares a `RouteContext` parameter\n(`server/runtime/rest/RouteContext.ts`).\n\n| Member | Signature | Notes |\n| --- | --- | --- |\n| `request` | `Request` | The raw incoming request. |\n| `param` | `param(name: string): string` | Captured path param; `\"\"` if absent. |\n| `query` | `query(name: string): string` | Query-string value; `\"\"` if absent. Not URL-decoded in v1. |\n| `header` | `header(name: string): string \\| null` | Case-insensitive request header. |\n| `text` | `text(): string` | The request body decoded as UTF-8. |\n\n## `Response`\n\nThe outgoing response builder (`server/runtime/response.ts`). Construct one with\na static factory, then chain instance methods (each returns the same `Response`).\n\n### Constructor\n\n```ts\nnew Response(status: u16, body: Uint8Array, headers: Array<Header> | null = null)\n```\n\n### Static factories\n\n| Factory | Signature | Status | Content-Type |\n| --- | --- | --- | --- |\n| `Response.text` | `text(body: string, status: u16 = 200)` | 200 | `text/plain; charset=utf-8` |\n| `Response.html` | `html(body: string, status: u16 = 200)` | 200 | `text/html; charset=utf-8` |\n| `Response.json` | `json(body: string, status: u16 = 200)` | 200 | `application/json; charset=utf-8` |\n| `Response.bytes` | `bytes(body: Uint8Array, status: u16 = 200)` | 200 | `application/octet-stream` |\n| `Response.empty` | `empty(status: u16)` | custom | (none) |\n| `Response.notFound` | `notFound()` | 404 | text |\n| `Response.badRequest` | `badRequest(msg = 'bad request')` | 400 | text |\n| `Response.internalError` | `internalError(msg = 'internal error')` | 500 | text |\n| `Response.unhandled` | `unhandled()` | 404 | text + `x-toil-unhandled` marker |\n\n`json` takes an already-serialized string; build it with `DataWriter`-free JSON\nor a `@data` type's `toJSON().toString()`. For binary, prefer `bytes`.\n\n### Instance methods\n\n| Method | Signature | Notes |\n| --- | --- | --- |\n| `setHeader` | `setHeader(name: string, value: string): Response` | Appends a header (repeatable). |\n| `setCookie` | `setCookie(cookie: Cookie): Response` | Appends a `Set-Cookie`. Call again for more. |\n| `setCookieKV` | `setCookieKV(name: string, value: string): Response` | Shorthand for `setCookie(new Cookie(name, value))`. |\n| `clearCookie` | `clearCookie(name: string, path = '/', domain = ''): Response` | Emits a deletion `Set-Cookie` (empty value, `Max-Age=0`). |\n| `cache` | `cache(edgeTtlMinutes: u16, browserTtlSeconds: u32 = 0, privateScope: bool = false, allowAuth: bool = false): Response` | Marks the response cacheable. See [Caching](./caching.md). |\n| `cacheFor` | `cacheFor(minutes: u16): Response` | Shorthand for `cache(minutes)` (edge only). |\n\n```ts\nreturn Response.json('{\"id\":42}')\n  .setHeader('x-trace', traceId)\n  .setCookie(Cookie.create('sid', token).httpOnly().secure())\n  .cacheFor(5);\n```\n\nSee [Cookies](./cookies.md) for the cookie builder, and [Caching](./caching.md)\nfor the cache directives.\n",
     "client.md": "# Client runtime\n\nEverything is on the `Toil` global, no imports needed in route files.\n\n## Entry\n\n`client/toil.tsx` imports the route table + global styles and mounts the app:\n\n```tsx\nimport { routes, layout, notFound } from \"toiljs/routes\";\nimport \"./styles/main.css\";\nToil.mount(routes, layout, notFound);\n```\n\n## API (on `Toil`)\n\n- Components: `Link`, `NavLink`, `Head`\n- Navigation: `navigate`, `useRouter`, `useNavigate`\n- Location: `usePathname`, `useSearchParams`, `useParams`, `useNavigationPending`\n- Data: `useLoaderData` (see [routing.md](./routing.md))\n- Head: `useHead`, `useTitle`, `<Head>`, set the `<title>` / meta per route\n- Realtime: `useChannel`, `connectChannel` (WebSocket to the backend at `/_toil`)\n- IO globals (no `Toil.` prefix): `FastMap`, `FastSet`, `DataWriter`, `DataReader`\n- `parseError(err)` global: message from an unknown caught value (handy in `catch`)\n- `Server` global: the typed RPC surface generated from the server (see [server.md](./server.md))\n- `Server.REST.<controller>.<route>(args)`: a working, typed `fetch` client for your\n  `@rest` controllers, e.g. `await Server.REST.todos.getTodo({ params: { id } })` or\n  `await Server.REST.todos.add({ body: new AddTodo(\"milk\") })`. `args` is\n  `{ params?, body?, query?, headers? }`; returns are typed (`@data` classes are parsed for\n  you). The REST client attaches when you import from `shared/server`.\n\n## Head example\n\n```tsx\nToil.useHead({\n    title: \"Blog\",\n    titleTemplate: \"%s, MyApp\",\n    meta: [{ name: \"description\", content: \"...\" }],\n});\n```\n",
     "styling.md": "# Styling\n\nThe app imports one stylesheet from `client/toil.tsx` (e.g. `./styles/main.css`).\n\n## Preprocessors & Tailwind\n\nPick a CSS preprocessor (none / Sass / Less / Stylus) and optionally Tailwind at\n`toiljs create`, or change it later on an existing project:\n\n```sh\ntoiljs configure                 # interactive\ntoiljs configure --tailwind      # add Tailwind\ntoiljs configure --style sass    # switch preprocessor\n```\n\n`configure` installs/removes the right packages and rewrites the imports. Tailwind lives\nin its own `styles/tailwind.css` (`@import \"tailwindcss\";`).\n\n## Imports\n\n`.css` / `.scss` / `.sass` / `.less` / `.styl` and image imports (`.svg`, `.png`, …) are\ntyped via `toil-env.d.ts`.\n",
@@ -14,7 +14,7 @@ export const TOIL_DOCS: Record<string, string> = {
     "ssr.md": "# Server-side rendering (SSR)\n\ntoiljs server-renders a route by splitting it into two halves that the build\nkeeps coherent:\n\n- **the template**, the HTML shell with the dynamic bits punched out (named\n  *holes*). It is React's own `renderToStaticMarkup` output with the holes\n  removed, precompiled at build time and held (mmap'd) by the edge.\n- **the values**, the hole values for one request (text, attributes, repeated\n  rows, headers, status). The wasm guest's `render` entrypoint returns *only*\n  these. The edge splices them into the template.\n\nA 32-byte template **hash** travels with the values so the edge can reject a\nguest that was compiled against a different template than the one deployed.\n\nThis split is the whole point. The guest never re-runs React and never emits the\nstatic page bytes, it stamps a tiny `(slot_id, kind, value)` list, so the wasm\nstays small and a request is served about as fast as a static file, while still\ndelivering real first-paint HTML and SEO. The browser then hydrates the spliced\nmarkup in place with no flash and no client re-render, because the holes are\nescaped exactly the way React escapes them, so the bytes match.\n\nThis page is about server-rendered HTML. JSON / binary API endpoints use\n[Routing](./routing.md) and `@rest` (see [Server](./server.md)) instead.\n\nThe running example throughout is the basic example's `/hello` route:\n\n- `examples/basic/client/routes/hello.tsx`, the route (`ssr = true`, holes, loader)\n- `examples/basic/server/SsrHelloRender.ts`, the server `render` + `Ssr.register`\n- `examples/basic/server/_ssr/hello.slots.ts`, the generated `Slot` + `HASH` (gitignored, never hand-edited)\n\n---\n\n## 1. Authoring an SSR route\n\nOpt a route in with `export const ssr = true`. At build time toiljs renders the\npage ONCE (under its real layout chain, with sample loader data) into the\ntemplate, generates the route's typed `Slot` module, and writes the template\nmanifest the edge serves. Routes without `ssr = true` are untouched and render\npurely on the client as before.\n\nMark the dynamic bits with the four hole markers from `toiljs/client`. They are\n**transparent in the browser**, `<Hole>` renders its children, `<Repeat>`\nrenders `each.map(...)`, `<RawHtml>` renders a `dangerouslySetInnerHTML`\nwrapper, `<Island>` renders its children, so the same component is your normal\nclient UI. Only the build extractor and the server `render` treat them\nspecially.\n\n```tsx\nimport { Hole, Island, RawHtml, Repeat, useLoaderData } from 'toiljs/client';\n\nexport const ssr = true;\n\nexport const loader = ({ params }: { params: Record<string, string> }) => ({\n  name: params.name ?? 'world',\n  blurbHtml: 'Rendered at the <strong>edge</strong>.',\n  services: [{ name: 'record', region: 'us-east' }],\n});\n\nexport default function Hello() {\n  const d = useLoaderData<typeof loader>();\n  return (\n    <section className=\"hello\">\n      <h1>Hello, <Hole id=\"name\">{d.name}</Hole>!</h1>\n\n      <p><RawHtml id=\"blurb\" html={d.blurbHtml} as=\"span\" /></p>\n\n      <ul>\n        <Repeat id=\"services\" each={d.services}>\n          {(s) => (\n            <li>\n              <strong><Hole id=\"svcName\">{s.name}</Hole></strong>\n              <span className=\"hello-region\"><Hole id=\"svcRegion\">{s.region}</Hole></span>\n            </li>\n          )}\n        </Repeat>\n      </ul>\n\n      <Island>\n        <p>Hydrated at {new Date().toLocaleTimeString()}.</p>\n      </Island>\n    </section>\n  );\n}\n```\n\n### The loader at build time\n\nThe build calls your `loader` once with synthesized sample params to obtain\nrepresentative data, then renders the page with it. Only the **shape** of the\ndata matters at build time, it drives which holes exist and (for `<Repeat>`)\ncaptures the row sub-template. The real per-request values come from the\n**server** `render`, not from this loader. Note in particular that `<Repeat>`\nneeds the sample to have **at least one row** so the build can capture the row\nmarkup; an empty array at build time leaves nothing to stamp.\n\n### The four hole markers\n\n| Marker | Prop(s) | Server (build + render) | Browser |\n| --- | --- | --- | --- |\n| `<Hole id>` | `id` | a text insertion point; the guest fills it with the **escaped** value | renders `children` |\n| `<RawHtml id html as?>` | `id`, `html`, `as?` (wrapper tag, default `div`) | emits `<as>…</as>`; the guest fills the inner HTML **verbatim** (you sanitize) | `<as dangerouslySetInnerHTML>` |\n| `<Repeat id each>` | `id`, `each`, child `(item, index) => node` | captures the **one** row sub-template; the guest stamps it per item and concatenates | renders `each.map(children)` |\n| `<Island>` | `children` | renders **nothing** (empty in the server HTML) | renders `children` |\n\n`<RawHtml>` always needs a host element so the server and client DOM agree; that\nis the `as` wrapper (defaults to `div`). The captured `<as>` tag is part of the\ntemplate, only its inner HTML is a hole.\n\n### Attribute holes (`attr()`)\n\nAn attribute value is not a child node, so it cannot be a JSX marker element.\nUse the `attr(id, value)` helper from `toiljs/client` in attribute position\ninstead:\n\n```tsx\nimport { attr } from 'toiljs/client';\n\n<a href={attr('profileUrl', d.url)} class={attr('cls', d.cls)}>…</a>\n```\n\nBrowser: `attr` returns `value` unchanged. Build: it emits an `attr` hole at the\nattribute's byte offset (stripping to an empty value in the `.tmpl`). The server\n`render` fills it with `v.setAttr(Slot.profileUrl, url)` (React-escaped, the same\nas `setText`), and the host splices it between the quotes. It composes with\nliteral text in the same attribute (`` class={`btn ${attr('x', v)}`} ``).\n\n### SSR-safe routes (and `<Island>`)\n\nFor hydration to be byte-clean, the route **and the layouts above it** must\nrender under static markup: use the hole markers and `useLoaderData`, and put\nanything that needs router hooks (`useRouter`, `usePathname`, …) or browser-only\nAPIs (`window`, `Date.now`, …) inside an `<Island>`. An island is empty in the\nfirst paint and appears only after hydration, so it gets no first-paint HTML or\nSEO, which is exactly right for \"client only\" content.\n\nOpting in is always safe: a route (or a layout in its chain) that **throws**\nunder static markup is **skipped at build with a warning** and falls back to\nnormal client rendering. You never get a broken page from adding `ssr = true`;\nworst case you get client rendering and a build warning telling you why.\n\n---\n\n## 2. The server `render`\n\nThe wasm `render(req_ofs, req_len) -> i64` export is surfaced by your\n`server/main.ts` via `export * from 'toiljs/server/runtime/exports'` (the same\nline that surfaces `handle`). At request time it decodes the request, runs the\n`Ssr` router to find a matching render function, serializes that function's\n`SlotValues` into the values envelope, and returns it packed as\n`(ptr << 32) | len`.\n\nA render function takes the `Request`, returns a filled `SlotValues` for a path\nit owns, or `null` to let the next registered renderer try.\n\n```ts\nimport { HtmlBuilder, Request, SlotValues, Ssr } from 'toiljs/server/runtime';\nimport { HASH, Slot } from './_ssr/hello.slots';\n\nfunction renderHello(req: Request): SlotValues | null {\n  // The guest re-derives WHICH route this is from the path (the template name\n  // is not in the request envelope), exactly as a @rest controller matches its\n  // own prefix. req.path includes the query string, so match both forms.\n  if (req.path != '/hello' && !req.path.startsWith('/hello?')) return null;\n\n  const v = new SlotValues(HASH);\n\n  v.setText(Slot.name, greetingName(req));                 // escaped\n  v.setRaw(Slot.blurb, 'Rendered at the <strong>edge</strong>.'); // verbatim\n\n  const rows = new HtmlBuilder();\n  for (let i = 0; i < services.length; i++) {\n    const s = services[i];\n    rows.raw('<li><strong>').text(s.name)\n        .raw('</strong><span class=\"hello-region\">').text(s.region)\n        .raw('</span></li>');\n  }\n  v.setRepeat(Slot.services, rows);\n\n  return v;\n}\n\nSsr.register(renderHello); // side-effect registration\n```\n\n### Registration is manual; the import is load-bearing\n\n`ssr-codegen` generates ONLY the `Slot` enum and the `HASH`, it does **not**\nemit the render body and does **not** auto-register it. You write `renderHello`\nand call `Ssr.register(renderHello)` yourself.\n\nCrucially, `Ssr.register` runs as a **module side effect**, so the module must\nbe imported somewhere the build reaches. Non-surface files (a plain render\nmodule is not a `@rest`/`@service`/`@data` file) are **not** auto-discovered, so\nyou must `import './SsrHelloRender'` in `server/main.ts`. Forgetting the import\nmeans the renderer never registers, `Ssr.dispatch` returns `null`, and the route\nfalls back to the fail-safe 500.\n\n### What `render` does for a request the router misses\n\nIf no registered renderer matches, the `render` export emits a **fail-safe**\nenvelope: status 500 with a **zeroed** 32-byte hash and no slots (a malformed\nrequest envelope yields the same fail-safe with status 400). The edge rejects\nthe zero hash as a coherence mismatch, so a miss surfaces as a clean error\nrather than a corrupt page.\n\n---\n\n## 3. Reference: `SlotValues`\n\nConstruct it with the route's compiled-in hash: `new SlotValues(HASH)`. Each\nsetter targets a slot id (a `Slot` enum member); the **kind** determines how the\nedge splices it. All setters return `this` for chaining.\n\n| Method | Signature | Escaping | Use |\n| --- | --- | --- | --- |\n| `setText` | `setText(slotId, value: string)` | **React-escaped** | text content (safe by default) |\n| `setRaw` | `setRaw(slotId, html: string)` | **none (verbatim)** | raw HTML, *you* sanitize |\n| `setAttr` | `setAttr(slotId, value: string)` | **React-escaped** | an attribute value |\n| `setRepeat` | `setRepeat(slotId, rows: HtmlBuilder)` | per `HtmlBuilder` calls | a repeat region, pre-stamped row by row |\n| `setHeader` | `setHeader(name, value)` |, | a response header (e.g. `Cache-Control`, `Set-Cookie`) |\n| `setStatus` | `setStatus(code)` |, | the HTTP status (default 200) |\n\n`setText` and `setAttr` escape identically (React escapes text and attributes\nthe same way). Slot ids passed are the `Slot` enum members; AS enums are `i32`,\nso they pass without a cast and are narrowed to `u16` only at encode time.\n\n### `HtmlBuilder`\n\nAssembles a repeat region (or any HTML fragment) with the same escaping\nguarantees. Chain `raw` (verbatim template bytes) and `text` / `attr`\n(React-escaped values):\n\n```ts\nconst rows = new HtmlBuilder();\nfor (let i = 0; i < items.length; i++) {\n  rows.raw('<li>').text(items[i]).raw('</li>'); // items[i] is escaped\n}\nv.setRepeat(Slot.list, rows);\n```\n\nYou are hand-writing the row markup, so it must match what `<Repeat>`'s child\nproduces for the same item, the build captured exactly that markup as the row\nsub-template, and the edge inserts your stamped rows verbatim at the region\noffset. Keep the **structure** the same across rows; only the leaf hole values\nvary.\n\n| Method | Signature | Escaping |\n| --- | --- | --- |\n| `raw` | `raw(s: string): HtmlBuilder` | verbatim |\n| `text` | `text(s: string): HtmlBuilder` | React-escaped |\n| `attr` | `attr(s: string): HtmlBuilder` | React-escaped (identical to `text`) |\n\n---\n\n## 4. Escaping (React-exact)\n\n`setText`, `setAttr`, and `HtmlBuilder.text` / `.attr` escape **exactly as\nReact does** (`react-dom/server`'s `escapeTextForBrowser`, regex `/[\"'&<>]/`),\nso the server-rendered markup and the client hydration agree byte-for-byte:\n\n```\n\"  →  &quot;        &  →  &amp;        '  →  &#x27;\n<  →  &lt;          >  →  &gt;\n```\n\nThe detail that bites: `'` becomes `&#x27;` (React's exact choice), **not**\n`&#39;`. If your escaping deviates from this by even one entity, `hydrateRoot`\nsees different markup and React throws a hydration mismatch and re-renders the\nsubtree. The guest's `escapeHtml` and the build's `reactEscapeHtml` are pinned\nto be byte-identical for exactly this reason.\n\n`setRaw` and `HtmlBuilder.raw` do **not** escape, they insert your bytes\nverbatim. That is the right tool for markup you produced or sanitized yourself\n(the same contract as `dangerouslySetInnerHTML`), and the wrong tool for\nanything derived from request input.\n\n---\n\n## 5. The build flow and generated artifacts\n\n`extractTemplates` (driven by `toiljs build`) does, for each `ssr = true` route:\n\n1. loads the route + its layout chain through a short-lived Vite SSR server;\n2. calls the `loader` with sample params to get representative data;\n3. renders the page under its layouts with the markers in **sentinel mode**\n   (`__setSsrBuild(true)`), each marker emits a Private-Use-Area sentinel token\n   instead of rendering normally;\n4. splices that into the built shell's `<div id=\"root\">` and adds the SSR marker\n   `<template id=\"__toil_ssr\"></template>` (this is what the client `mount` looks\n   for to switch to `hydrateRoot`);\n5. strips the sentinel tokens, records their **byte offsets**, and writes the\n   artifacts.\n\n### Where the artifacts land\n\nFor a route named `<name>` (see below), under `build/client/_ssr/`:\n\n| File | Consumer | Contents |\n| --- | --- | --- |\n| `<name>.tmpl` | edge host (mmap'd) | the stripped static HTML shell, holes removed |\n| `<name>.slots` | edge host | the binary manifest (offsets, ids, kinds, tmpl_len, hash) |\n| `<name>.slots.ts` | guest build | the generated `Slot` enum + `HASH` AssemblyScript module |\n| `templates.json` | index | `[{ route, name, hash }]` for every extracted template |\n\nThe `.tmpl` and `.slots` are then **copied** into the edge host bundle at\n`hosts/edge/_tmpl/<name>.{tmpl,slots}`.\n\nThe build also writes the **server-importable** `Slot` + `HASH` module to\n`server/_ssr/<name>.slots.ts`, the one your `render` imports. It is generated\nand gitignored; never hand-edit it (see the two-pass note below).\n\n### Route name derivation (`routeTemplateName`)\n\nThe `<name>` is a file-safe slug of the route pattern: non-alphanumerics collapse\nto `_`, leading/trailing `_` are trimmed, empty → `index`.\n\n| Route pattern | `<name>` |\n| --- | --- |\n| `/hello` | `hello` |\n| `/` | `index` |\n| `/u/:name` | `u_name` |\n| `/blog/[id]` | `blog_id` |\n\n### The two-pass build: no hand-kept slots\n\nThe final extraction runs **after** the Vite client build (the built shell's\nhashed `<script>`/`<link>` tags are part of the template, so they must be in the\n`HASH`), but the server (guest wasm) is compiled **before** it. A naive build\ntherefore can't generate `<name>.slots.ts` in time for the `render` to import\nit. toiljs closes this with a **two-pass** build, so a clean build needs **zero\nhand-maintained slots**:\n\n1. **Slots pre-pass** (before the server build) renders every `ssr = true`\n   route to its `Slot` enum + `HASH` and writes the server-importable module at\n   `server/_ssr/<name>.slots.ts`. This is the file your `render` imports, it is\n   **generated, gitignored, and never hand-edited**.\n2. The server compiles against that module.\n3. The client (Vite) builds.\n4. **Final extraction** re-renders against the real built shell and rewrites\n   `server/_ssr/<name>.slots.ts` with the authoritative `HASH`. If the hash\n   rotated since the pre-pass, the build recompiles the server **once** so the\n   guest bakes the deployed hash.\n\nSo authoring an SSR route is just the route + the `render`; the `Slot` / `HASH`\nmodule is entirely build-managed. (On an unchanged rebuild the pre-pass reuses\nthe prior build's shell, so the hashes already match and step 4's recompile is\nskipped.)\n\n---\n\n## 6. Hash coherence and the values envelope\n\nEvery values envelope carries the guest's compiled-in 32-byte `HASH`. The edge\ncompares it against the deployed template's hash and **rejects a mismatch** with\na fail-safe 500 rather than splicing values into the wrong template. A mismatch\nmeans deploy skew: the guest was built against one version of the template and a\ndifferent one is deployed.\n\nThe hash is `sha256(tmpl || \\0 || canonicalManifest(slots))`, so any change to\nthe static HTML, a hole's id/kind, or the repeat nesting rotates it.\n\nThe guest serializes `SlotValues` to this little-endian, no-padding layout (the\nedge decodes it and splices against the template manifest):\n\n```\nu16  status\n[32] template_hash\nu16  n_headers\n  for each header: u16 name_len, u16 val_len, name bytes, val bytes\nu16  n_slots\n  for each value:  u16 slot_id, u8 kind, u32 value_len, value bytes\n```\n\n`kind` is `0=text, 1=raw, 2=attr, 3=repeat`. The host keys values by `slot_id`\nand inserts each at the **manifest-fixed** offset, so the guest can never choose\n*where* bytes land, only what they are. If a value cannot be represented\n(a count or length overflows its field width, or the hash is the wrong size),\nthe encoder writes the same fail-safe 500/zero-hash envelope instead of corrupt\nbytes.\n\nThe matching `.slots` manifest the host reads is a 46-byte header\n(`\"TSLT\"` magic, u16 version, u16 flags, u32 tmpl_len, 32-byte hash, u16 n_slots)\nfollowed by 8-byte entries (`u32 offset, u16 slot_id, u8 kind, u8 reserved`).\n\n---\n\n## 7. Dev server and testing\n\n`toiljs dev` serves SSR routes the same way the edge does. It runs the **real**\n`render` export (`WasmServerModule.dispatchRender`), decodes the values\nenvelope, and splices the values into the route's template, so you get real\nserver-rendered HTML locally (`curl` a route, or view source), which then\nhydrates in place. The dev template is extracted once at startup against the\nlive (Vite-transformed) dev shell rather than a built one; a route's per-request\n**values** are always live, but a change to its **markup** needs a dev restart\nto re-extract. A fail-safe envelope (no renderer matched) falls back to client\nrendering.\n\nThe end-to-end test (`test/ssr-render.test.ts`) drives the same `dispatchRender`\npath directly: it calls `dispatchRender({ path: '/hello' })`, decodes the\nenvelope, asserts the slots, and splices against the built `hello.tmpl`.\n\n---\n\n## 8. Complete worked example: `/hello`\n\nThis is the full, copy-pasteable chain. All four files are real and tested.\n\n### `client/routes/hello.tsx` (the route)\n\n```tsx\nimport { Hole, Island, RawHtml, Repeat, useLoaderData } from 'toiljs/client';\n\nexport const ssr = true;\n\nexport const metadata: Toil.Metadata = {\n  title: 'Edge SSR',\n  description: 'A server-rendered greeting, filled at the edge.',\n};\n\ninterface Service { name: string; region: string; }\ninterface GreetingData {\n  name: string;\n  blurbHtml: string;\n  services: Service[];\n}\n\n// Build-time sample data, only the SHAPE matters; the real per-request values\n// come from the SERVER render. The repeat sample needs at least one row.\nexport const loader = ({ params }: { params: Record<string, string> }): GreetingData => ({\n  name: params.name ?? 'world',\n  blurbHtml: 'Rendered at the <strong>edge</strong> from a tiny values envelope.',\n  services: [\n    { name: 'record', region: 'us-east' },\n    { name: 'unique', region: 'eu-west' },\n    { name: 'counter', region: 'ap-south' },\n  ],\n});\n\nexport default function Hello(): React.JSX.Element {\n  const d = useLoaderData<typeof loader>();\n  return (\n    <section className=\"hello\">\n      <h1>Hello, <Hole id=\"name\">{d.name}</Hole>!</h1>\n\n      <p className=\"hello-blurb\">\n        <RawHtml id=\"blurb\" html={d.blurbHtml} as=\"span\" />\n      </p>\n\n      <h2>Service snapshot</h2>\n      <ul className=\"hello-services\">\n        <Repeat id=\"services\" each={d.services}>\n          {(s: Service) => (\n            <li>\n              <strong><Hole id=\"svcName\">{s.name}</Hole></strong>\n              <span className=\"hello-region\"><Hole id=\"svcRegion\">{s.region}</Hole></span>\n            </li>\n          )}\n        </Repeat>\n      </ul>\n\n      <Island>\n        <p className=\"hello-island\">\n          Hydrated in your browser at {new Date().toLocaleTimeString()}.\n        </p>\n      </Island>\n    </section>\n  );\n}\n```\n\n### `server/_ssr/hello.slots.ts` (generated by the build; do not edit)\n\n```ts\n// AUTO-GENERATED by toil (edge SSR). Do not edit.\n\n/** Stable hole ids for this route's template (document order). */\nexport enum Slot {\n  name = 0,\n  blurb = 1,\n  services = 2,\n}\n\n/** Coherence hash (32 bytes), written by the build's slots pre-pass; the host\n * rejects a response whose hash != the deployed template. */\nexport const HASH: StaticArray<u8> = [\n  0xcb, 0x12, 0x5e, 0x19, 0x46, 0x32, 0x58, 0x25, 0xd3, 0xf0, 0x44, 0xc5, 0x41, 0x0c, 0x34, 0x3b,\n  0x69, 0xd3, 0x62, 0xb3, 0x24, 0x25, 0x79, 0xc4, 0x76, 0x89, 0xfb, 0x25, 0x6e, 0x35, 0x02, 0x31,\n];\n```\n\n(Only the **top-level** holes get a `Slot` id, `name`, `blurb`, `services`. The\nnested `svcName` / `svcRegion` live inside the repeat row sub-template, which the\nguest stamps with `HtmlBuilder`, so they are not separate slots.)\n\n### `server/SsrHelloRender.ts` (the render)\n\n```ts\nimport { HtmlBuilder, Request, SlotValues, Ssr } from 'toiljs/server/runtime';\nimport { HASH, Slot } from './_ssr/hello.slots';\n\nclass Service {\n  constructor(public name: string, public region: string) {}\n}\n\n/** Pull `?name=...`, defaulting to `world` (matches the route loader default). */\nfunction greetingName(req: Request): string {\n  const q = req.path.indexOf('?');\n  if (q < 0) return 'world';\n  const parts = req.path.substring(q + 1).split('&');\n  for (let i = 0; i < parts.length; i++) {\n    if (parts[i].startsWith('name=')) {\n      const v = parts[i].substring(5);\n      return v.length > 0 ? v : 'world';\n    }\n  }\n  return 'world';\n}\n\nfunction renderHello(req: Request): SlotValues | null {\n  if (req.path != '/hello' && !req.path.startsWith('/hello?')) return null;\n\n  const v = new SlotValues(HASH);\n\n  // Text hole, React-escaped (so ?name=<a>&b is safe).\n  v.setText(Slot.name, greetingName(req));\n\n  // Raw hole, verbatim; a fixed, trusted blurb (no request data).\n  v.setRaw(Slot.blurb, 'Rendered at the <strong>edge</strong> from a tiny values envelope.');\n\n  // Repeat, stamp the captured row markup once per item. The row sub-template\n  // is <li><strong>{svcName}</strong><span class=\"hello-region\">{svcRegion}</span></li>;\n  // .text(...) escapes each nested hole exactly as React does.\n  const services: Service[] = [\n    new Service('record', 'us-east'),\n    new Service('unique', 'eu-west'),\n    new Service('counter', 'ap-south'),\n  ];\n  const rows = new HtmlBuilder();\n  for (let i = 0; i < services.length; i++) {\n    const s = services[i];\n    rows.raw('<li><strong>').text(s.name)\n        .raw('</strong><span class=\"hello-region\">').text(s.region)\n        .raw('</span></li>');\n  }\n  v.setRepeat(Slot.services, rows);\n\n  return v;\n}\n\n// Side-effect registration: main.ts imports this module so the build compiles\n// it in and this renderer joins the SSR router.\nSsr.register(renderHello);\n```\n\n### `server/main.ts` (the load-bearing import)\n\n```ts\nimport { Server } from 'toiljs/server/runtime';\n// ... other surface imports ...\n\n// Edge SSR: importing the render module compiles it in and self-registers its\n// /hello renderer. Without this import the renderer never registers.\nimport './SsrHelloRender';\n\nServer.handler = () => new AppHandler();\n\nexport * from 'toiljs/server/runtime/exports'; // surfaces `handle` AND `render`\n```\n\nThe spliced first-paint HTML for `GET /hello` is byte-identical to what React\nrenders for the same data:\n\n```html\n<section class=\"hello\"><h1>Hello, world!</h1>\n<p class=\"hello-blurb\"><span>Rendered at the <strong>edge</strong> from a tiny values envelope.</span></p>\n<h2>Service snapshot</h2>\n<ul class=\"hello-services\">\n<li><strong>record</strong><span class=\"hello-region\">us-east</span></li>\n<li><strong>unique</strong><span class=\"hello-region\">eu-west</span></li>\n<li><strong>counter</strong><span class=\"hello-region\">ap-south</span></li>\n</ul></section>\n```\n\nThe `<Island>` is empty here (no first paint); it fills in after hydration.\n\n---\n\n## 9. Pitfalls and debugging\n\n- **Route skipped at build (warning, no SSR).** The route or a layout above it\n  threw under static markup, almost always a router hook (`useRouter`,\n  `usePathname`, …) or a browser-only API rendered outside an `<Island>`. The\n  build prints `toil: SSR skipped <pattern> (...)` and the route falls back to\n  client rendering. Move the offending content into an `<Island>`.\n\n- **Hash mismatch / clean 500 after editing a template.** Any change to the\n  page's static markup, a hole id/kind, or the repeat structure rotates the\n  `HASH`. The host rejects a stale guest hash. A normal `toiljs build`\n  regenerates `server/_ssr/<name>.slots.ts` and rebakes the guest, so this only\n  surfaces from a partial or stale deploy (a guest built against a different\n  template than the one deployed), never from hand-copied slots.\n\n- **Hydration mismatch (flash / React re-render in the browser).** Two common\n  causes. (1) The client **loader** does not reproduce the values the server\n  `render` stamped. Hydration re-renders the route with the loader's data, so for\n  any request-derived hole the loader must derive the **same** value the server\n  `render` does (e.g. read the same `?query` / param). The two are separate\n  sources (the client loader is TypeScript; the server `render` is the wasm\n  guest), so keeping them in sync is the author's contract; if the client cannot\n  reproduce a value, put that content in an `<Island>`. (2) A marker (or a\n  non-static node) rendered outside an `<Island>`, or hole escaping that does not\n  match React's (e.g. emitting `&#39;` instead of `&#x27;`, or using `setRaw`\n  where the client would escape). Keep dynamic text in `<Hole>` / `setText` and\n  client-only content in `<Island>`.\n\n- **Route renders client-side only even though `ssr = true`.** You forgot to\n  `import './SsrHelloRender'` in `server/main.ts`, so `Ssr.register` never ran\n  and `Ssr.dispatch` returns `null`. Add the import. (Plain render modules are\n  not auto-discovered the way `@rest`/`@service` files are.)\n\n- **`setRaw` injecting unsanitized request data.** `setRaw` is verbatim, never\n  pass it anything derived from request input you have not sanitized. Use\n  `setText` for request-derived text.\n\n- **Empty `<Repeat>` sample at build.** The build captures the row sub-template\n  from the **first** sample row. If your build-time `loader` returns an empty\n  array for a `<Repeat>`, there is no row to capture. Give the build sample at\n  least one representative row.\n</content>\n</invoke>\n",
     "rpc.md": "# RPC and the generated client\n\nThe server build with `--rpcModule shared/server.ts` scans your decorated\nsurface (`@data`, `@user`, `@service`/`@remote`, `@rest`) and emits one\nTypeScript module: a typed `Server` proxy, the `@data` codec classes, the REST\nfetch client, and the `getUser()` accessor. The client imports that file and\ncalls the server with full type-safety and editor autocomplete. The file is\nregenerated on every server build, so it never drifts from the server.\n\n```sh\ntoilscript --target release --rpcModule shared/server.ts\n```\n\n## `@service` and `@remote`\n\nA `@service` class exposes its `@remote` methods as callable RPC. A top-level\n`@remote` function is exposed directly.\n\n```ts\n@service\nclass Stats {\n  @remote\n  public playerCount(): i32 { return store.size; }\n}\n\n@remote\nfunction ping(n: i32): i32 { return n + 1; }\n```\n\nThe generated client surfaces these on the global `Server` proxy. A service is\nkeyed by its class name with the first letter lowercased (`Stats` → `stats`):\n\n```ts\nawait Server.stats.playerCount(); // Promise<number>\nawait Server.ping(42);            // Promise<number>\n```\n\nArguments and return values are `@data`-typed; scalars map to TS as below.\n\n## The generated `Server` surface\n\n`shared/server.ts` declares a global `Server` whose shape is, schematically:\n\n```ts\ndeclare global {\n  const Server: {\n    // top-level @remote functions\n    ping(n: number): Promise<number>;\n\n    // @service classes (keyed by lowercased name)\n    readonly stats: {\n      playerCount(): Promise<number>;\n    };\n\n    // @rest controllers, under REST\n    readonly REST: {\n      readonly players: {\n        get(args: { params: { id: string | number | bigint }; query?: …; headers?: … }): Promise<Response>;\n        create(args: { body: NewPlayer; query?: …; headers?: … }): Promise<Player>;\n      };\n    };\n  };\n}\n```\n\n### Type mapping (ToilScript → TypeScript)\n\n| ToilScript | TypeScript |\n| --- | --- |\n| `u8`,`u16`,`u32`,`i8`,`i16`,`i32`,`f32`,`f64` | `number` |\n| `u64`,`i64`,`u128`,`i128`,`u256`,`i256` | `bigint` |\n| `bool` | `boolean` |\n| `string` | `string` |\n| a `@data` class `T` | `T` (the emitted class) |\n| `T[]` | `T[]` |\n\n64-bit-and-larger integers are `bigint` on the client and travel as decimal\nstrings on the JSON wire, so they are exact at any magnitude.\n\n### Emitted `@data` classes\n\nEach `@data` (and `@user`) class becomes an exported TS class with the fields, a\ndefaulted constructor, and the matching codec:\n\n```ts\nexport class Player {\n  constructor(public username = '', public admin = false, public score = 0n) {}\n  encodeInto(w: DataWriter): void { /* … */ }\n  encode(): Uint8Array { /* dataId prefix + fields */ }\n  static decodeFrom(r: DataReader): Player { /* … */ }\n  static decode(buf: Uint8Array): Player { /* … */ }\n  static dataId(): number { /* FNV-1a of \"Player\" */ }\n  static fromJSONValue(v: any): Player { /* revive, 64-bit from strings */ }\n  toJSONValue(): any { /* 64-bit as decimal strings */ }\n}\n```\n\nThe codec is byte-compatible with the server's `@data` codec, so binary bodies\nround-trip exactly between client and wasm.\n\n## The REST fetch client\n\nEvery `@rest` route also gets a typed fetch wrapper under `Server.REST.<key>`,\nkeyed by the controller name lowercased. The call argument is an object:\n\n```ts\nServer.REST.players.create({\n  body: new NewPlayer('alice'),     // present iff the route takes a body\n  // params: { id: 7 },             // present iff the path has :params\n  query: { ref: 'home' },           // optional\n  headers: { 'x-trace': traceId },  // optional\n});\n```\n\n- If the route has no params and no body, the whole argument is optional\n  (`args?`).\n- The wrapper builds the URL (substituting `:params`, appending `query`),\n  `fetch`es with `credentials` as configured, throws on a non-2xx status, and\n  decodes the response into the route's return type.\n- A route declared to return `Response` resolves to the raw `fetch` `Response`,\n  so you can stream or inspect headers yourself.\n\n```ts\nconst player = await Server.REST.players.create({ body: new NewPlayer('alice') });\n//    ^? Player\n```\n\n## `getUser()`\n\nWhen the server declares a `@user` class, the generated module also exports a\ntyped, no-argument `getUser()` that reads the readable companion cookie and\ndecodes it with the generated codec:\n\n```ts\nimport { getUser } from './shared/server';\n\nconst user = getUser(); // Account | null, fully typed\n```\n\nThis is **display-only**: the server re-verifies the signed session on every\n`@auth` request. See [Auth](./auth.md) for the full picture.\n\n## Notes\n\n- `shared/server.ts` is generated; never edit it by hand. Re-run the server\n  build (or `toiljs dev`, which does it on save) to refresh it.\n- The `Server` proxy is declared as an ambient global on the client; the runtime\n  implementation is provided by toiljs. The REST client and `getUser` are real\n  exported values in the generated module.\n",
     "tiers.md": "# Deployment tiers\n\nA Toil app's server runs across several deployment **tiers** from one source\ntree. Each tier has a different lifetime and placement on the edge, and compiles\ninto its own WebAssembly artifact. You write one project; `toiljs build` decides\nwhich entries belong to which tier and emits one `.wasm` per tier. You opt into a\ntier purely by adding its entry file and surface decorator; nothing else changes.\n\n## The tiers\n\n| Entry (`server/`) | Surface                          | Artifact                           | Tier             | Lifetime / placement                                                                                                                              |\n| ----------------- | -------------------------------- | ---------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `main.ts`         | `@rest` / `@service` / `@remote` | `build/server/release.wasm`        | **L1** request   | A fresh handler per request, anywhere on the edge.                                                                                                |\n| `main.stream.ts`  | `@stream`                        | `build/server/release-stream.wasm` | **L2/L3** stream | One resident box per connection, pinned to a worker via QUIC connection-id steering; its state survives every event. See [Streams](./streams.md). |\n| `main.daemon.ts`  | `@daemon` / `@scheduled`         | `build/server/release-cold.wasm`   | **L4** daemon    | Exactly one leader-elected box per domain (warm standby, at-most-once failover) firing `@scheduled` tasks. See [Daemon](./daemon.md).             |\n\nThe three tiers differ in how long a box lives and how many of it exist:\n\n- **L1 request** is stateless. A `@rest` handler's fields reset each request,\n  because a fresh box serves each one, anywhere on the edge.\n- **L2/L3 stream** is resident per connection. A `@stream` box is created when a\n  connection opens, lives for its lifetime, and is torn down on close, so its\n  fields persist across every event.\n- **L4 daemon** is a single elected leader per domain - the global coordination\n  tier - running recurring background work on a cadence.\n\n## How the build works\n\n`toiljs build` runs one toilscript pass per tier, handing each pass only the\nentries that belong to it. Tier membership is decided by the surface decorator or\nby the entry naming convention:\n\n- a runtime-export entry that is **not** `*.stream.ts` or `*.daemon.ts` is the\n  **request** entry (`main.ts`), which compiles `@rest` / `@service` / `@remote`;\n- `*.stream.ts` is the **stream** entry, which compiles `@stream`;\n- `*.daemon.ts` is the **daemon** entry, which compiles `@daemon` / `@scheduled`.\n\nPlain `@data` and helper modules carry no tier of their own, so they are shared\ninto every artifact. Routing each entry to exactly one tier is what keeps\n`release.wasm` free of `stream_dispatch` and keeps the daemon artifact free of\nthe request `handle`.\n\nEach entry is a thin file that imports its tier's modules and re-exports the\nright runtime hooks. The stream and request entries re-export the request runtime\nexports; the daemon entry does not, because a cold artifact exposes\n`daemon_start` / `scheduled_tick`, not `handle`:\n\n```ts\n// server/main.stream.ts - the L2/L3 stream entry\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\nimport './streams/Echo';\n\nexport * from 'toiljs/server/runtime/exports';\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n    revertOnError(message, fileName, line, column);\n}\n```\n\n```ts\n// server/main.daemon.ts - the L4 daemon entry\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\nimport './daemon/Jobs';\n\n// NOTE: no `export *` from the request runtime - a cold artifact exposes\n// daemon_start/scheduled_tick, not the request `handle`.\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n    revertOnError(message, fileName, line, column);\n}\n```\n\nA single build produces the artifacts side by side:\n\n```sh\n$ ls build/server/*.wasm\nbuild/server/release.wasm          # L1 request    (exports: handle)\nbuild/server/release-stream.wasm   # L2/L3 stream   (exports: stream_dispatch)\nbuild/server/release-cold.wasm     # L4 daemon      (exports: daemon_start, scheduled_tick)\n```\n\n## Single-artifact default\n\nA project with no `@stream` and no `@daemon` surface keeps the default\nsingle-artifact build - just `build/server/release.wasm`. The stream and daemon\ntiers are opt-in: add `main.stream.ts` (and a `@stream` class) to get\n`release-stream.wasm`, add `main.daemon.ts` (and a `@daemon` class) to get\n`release-cold.wasm`. Existing request-only apps build exactly as before.\n\n## When to use each tier\n\n- **L1 request** for request/response and RPC: `@rest` controllers, `@service` /\n  `@remote` callable surface. The default tier; most code lives here.\n- **L2/L3 stream** for stateful, long-lived connections where per-connection\n  state must survive across events - the resident box is pinned to one worker for\n  the connection's lifetime.\n- **L4 daemon** for scheduled and coordination work: rollups, cleanup, polling an\n  upstream, anything that should run exactly once per domain on a cadence rather\n  than per request.\n\n```ts\n// server/streams/Echo.ts - L2/L3: the box is resident, so `count` persists.\n@stream('echo')\nclass Echo {\n    private count: i32 = 0;\n\n    @connect onConnect(): void {\n        this.count = 0;\n    }\n    @message onMessage(): void {\n        this.count = this.count + 1;\n    }\n    @close onClose(): void {\n        /* box torn down after this hook */\n    }\n}\n```\n\n```ts\n// server/daemon/Jobs.ts - L4: one leader per domain runs this hourly.\n@daemon\nclass Jobs {\n    @scheduled('1h')\n    hourly(): void {\n        // Recurring background work: rollups, cleanup, polling an upstream, ...\n    }\n}\n```\n\n## See also\n\n- [Streams](./streams.md) - the `@stream` surface and the L2/L3 tier.\n- [Daemon](./daemon.md) - the `@daemon` surface and the L4 tier.\n- [Routing](./routing.md) - `@rest` controllers on the L1 request tier.\n- [RPC](./rpc.md) - `@service` / `@remote` and the generated client.\n",
-    "streams.md": "# Streams\n\nA `@stream` declares a long-lived, stateful protocol handler over WebTransport -\nthe **L2/L3** (regional / continental) stream tier of the Toil edge. Unlike a\n`@rest` route, which is a fresh handler per request, a `@stream` is a **resident\nWebAssembly box per connection**: it is created when the connection opens, lives\nfor the whole connection, and is torn down on close. State stored on its fields\n**persists across events**, because it is the same box every time.\n\n```ts\n@stream('echo')\nclass Echo {\n  private count: i32 = 0;\n\n  @connect\n  onConnect(): void {\n    this.count = 0;\n  }\n\n  @message\n  onMessage(): void {\n    this.count = this.count + 1;\n  }\n\n  @close\n  onClose(): void {}\n}\n```\n\n## Declaring a stream\n\n`@stream(name)` marks a class as a stream handler and mounts it at the given\nname/route. The class becomes a resident box; its fields are the connection's\nstate.\n\n```ts\n@stream('echo')            // mounted at /echo\nclass Echo { /* ... */ }\n```\n\nA stream lives on the **L2/L3 stream tier** and its default scope is **Regional\n(L2)**. See [Tiers](./tiers.md) for the full tier model.\n\n## Lifecycle hooks\n\nA stream method is a lifecycle hook, chosen by its decorator. All hooks are\noptional - declare only the ones you need; a missing hook is a no-op.\n\n| Decorator | Fires when |\n| --- | --- |\n| `@connect` | the connection opens (the box has just been created). |\n| `@message` | an inbound frame arrives. |\n| `@close` | the connection closes gracefully (the box is torn down after this hook). |\n| `@disconnect` | the transport is lost abruptly. |\n| `@channel` | an opt-in distributed channel delivers a message (advanced; see below). |\n\nThe `Echo` example above shows why state survives: `count` is set to `0` in\n`@connect`, incremented on every `@message`, and the increments **accumulate**.\nThat is only possible because the same resident box handles every event for the\nconnection. A `@rest` handler's fields would reset on each request, since a\nfresh handler is constructed per request.\n\n`@channel` is an opt-in **distributed** channel (advanced) - a way for boxes to\nexchange messages beyond a single connection. It is mentioned here for\ncompleteness; most streams use only the four connection-lifecycle hooks.\n\n## Placement\n\nA `@stream` is distributed across the eligible L2/L3 stream nodes and pinned to\n**ONE worker** for the connection's lifetime via QUIC connection-id steering. The\nconnection always lands on the same worker, so the box - and the state on its\nfields - survives every event. You do not manage placement; the edge steers each\nconnection to its resident box automatically.\n\n## The entry: `main.stream.ts`\n\nThe stream surface has its own entry, `server/main.stream.ts`, distinct from the\nrequest entry (`server/main.ts`). It re-exports the WASM runtime exports and\nimports the `@stream` classes, which pulls their compiler-generated\n`stream_dispatch` export into the artifact.\n\n```ts\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\n\nimport './streams/Echo';\n\n// Re-export the WASM entry points the host binds, exactly like main.ts.\nexport * from 'toiljs/server/runtime/exports';\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n  revertOnError(message, fileName, line, column);\n}\n```\n\nThis entry compiles into its **own artifact**, `build/server/release-stream.wasm`\n- the resident stream box - separate from the request build,\n`build/server/release.wasm`. Add a stream as you grow by importing it here:\n\n```ts\nimport './streams/Echo';\n```\n\n## Build\n\n`toiljs build` produces `release-stream.wasm` automatically when the project\ndeclares a `@stream` surface. The single build runs one toilscript pass per tier,\nhanding each pass only the entries that belong to it, so `release.wasm` never\ncontains `stream_dispatch` and the stream artifact never contains the request\n`handle`. Plain `@data` and helper modules are shared into every artifact.\n\n```sh\n$ toiljs build\n$ ls build/server/*.wasm\nbuild/server/release.wasm          # L1 request   (exports: handle)\nbuild/server/release-stream.wasm   # L2/L3 stream  (exports: stream_dispatch)\nbuild/server/release-cold.wasm     # L4 daemon     (exports: daemon_start, scheduled_tick)\n```\n\nSee [Tiers](./tiers.md) for how the three artifacts map to the deployment tiers.\n\n## What runs today\n\nThe stream lifecycle hooks (`@connect` / `@message` / `@close` / `@disconnect`)\nrun **today**, and this proves a resident box keeps state across events - that is\nexactly what the `Echo` example demonstrates by counting frames.\n\nReading the inbound frame **bytes** and replying is the **next increment**, not\nyet available. That bridge is the `StreamPacket` / `StreamOutbound` API and the\ntyped `Server.STREAM.echo.connect()` client. The intended shape, once it lands:\n\n```ts\n@message reply(packet: StreamPacket): StreamOutbound {\n  return StreamOutbound.reply(packet.bytes());   // echo the bytes back\n}\n```\n\n```ts\nconst stream = await Server.STREAM.echo.connect();\nstream.send(new TextEncoder().encode('hello'));\n```\n\nUntil then, the hooks run on the connection lifecycle and you observe state\nthrough fields, as `Echo` does. See the comments in\n`examples/streams/server/streams/Echo.ts` for the authoritative note.\n\n---\n\nSee also: [Tiers](./tiers.md), [Daemon](./daemon.md), [Routing](./routing.md).\n",
+    "streams.md": "# Streams\n\nA `@stream` declares a long-lived, stateful protocol handler over WebTransport -\nthe **L2/L3** (regional / continental) stream tier of the Toil edge. Unlike a\n`@rest` route, which is a fresh handler per request, a `@stream` is a **resident\nWebAssembly box per connection**: it is created when the connection opens, lives\nfor the whole connection, and is torn down on close. State stored on its fields\n**persists across events**, because it is the same box every time.\n\n```ts\n@stream('echo')\nclass Echo {\n  private count: i32 = 0;\n\n  @connect\n  onConnect(): void {\n    this.count = 0;\n  }\n\n  @message\n  onMessage(): void {\n    this.count = this.count + 1;\n  }\n\n  @close\n  onClose(): void {}\n}\n```\n\n## Declaring a stream\n\n`@stream(name)` marks a class as a stream handler and mounts it at the given\nname/route. The class becomes a resident box; its fields are the connection's\nstate.\n\n```ts\n@stream('echo')            // mounted at /echo\nclass Echo { /* ... */ }\n```\n\nA stream lives on the **L2/L3 stream tier** and its default scope is **Regional\n(L2)**. See [Tiers](./tiers.md) for the full tier model.\n\n## Lifecycle hooks\n\nA stream method is a lifecycle hook, chosen by its decorator. All hooks are\noptional - declare only the ones you need; a missing hook is a no-op.\n\n| Decorator | Fires when |\n| --- | --- |\n| `@connect` | the connection opens (the box has just been created). |\n| `@message` | an inbound frame arrives. |\n| `@close` | the connection closes gracefully (the box is torn down after this hook). |\n| `@disconnect` | the transport is lost abruptly. |\n| `@channel` | an opt-in distributed channel delivers a message (advanced; see below). |\n\nThe `Echo` example above shows why state survives: `count` is set to `0` in\n`@connect`, incremented on every `@message`, and the increments **accumulate**.\nThat is only possible because the same resident box handles every event for the\nconnection. A `@rest` handler's fields would reset on each request, since a\nfresh handler is constructed per request.\n\n`@channel` is an opt-in **distributed** channel (advanced) - a way for boxes to\nexchange messages beyond a single connection. It is mentioned here for\ncompleteness; most streams use only the four connection-lifecycle hooks.\n\n## Placement\n\nA `@stream` is distributed across the eligible L2/L3 stream nodes and pinned to\n**ONE worker** for the connection's lifetime via QUIC connection-id steering. The\nconnection always lands on the same worker, so the box - and the state on its\nfields - survives every event. You do not manage placement; the edge steers each\nconnection to its resident box automatically.\n\n## The entry: `main.stream.ts`\n\nThe stream surface has its own entry, `server/main.stream.ts`, distinct from the\nrequest entry (`server/main.ts`). It re-exports the WASM runtime exports and\nimports the `@stream` classes, which pulls their compiler-generated\n`stream_dispatch` export into the artifact.\n\n```ts\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\n\nimport './streams/Echo';\n\n// Re-export the WASM entry points the host binds, exactly like main.ts.\nexport * from 'toiljs/server/runtime/exports';\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n  revertOnError(message, fileName, line, column);\n}\n```\n\nThis entry compiles into its **own artifact**, `build/server/release-stream.wasm`\n- the resident stream box - separate from the request build,\n`build/server/release.wasm`. Add a stream as you grow by importing it here:\n\n```ts\nimport './streams/Echo';\n```\n\n## Build\n\n`toiljs build` produces `release-stream.wasm` automatically when the project\ndeclares a `@stream` surface. The single build runs one toilscript pass per tier,\nhanding each pass only the entries that belong to it, so `release.wasm` never\ncontains `stream_dispatch` and the stream artifact never contains the request\n`handle`. Plain `@data` and helper modules are shared into every artifact.\n\n```sh\n$ toiljs build\n$ ls build/server/*.wasm\nbuild/server/release.wasm          # L1 request   (exports: handle)\nbuild/server/release-stream.wasm   # L2/L3 stream  (exports: stream_dispatch)\nbuild/server/release-cold.wasm     # L4 daemon     (exports: daemon_start, scheduled_tick)\n```\n\nSee [Tiers](./tiers.md) for how the three artifacts map to the deployment tiers.\n\n## Reading and replying to messages\n\n`@message` receives the inbound frame as a `StreamPacket` and returns a\n`StreamOutbound`. `StreamPacket.bytes()` is the raw frame payload;\n`StreamOutbound.reply(bytes)` stages one frame back to the client (return an empty\n`StreamOutbound` to accept the frame without replying). The same resident box\nhandles every frame, so state on its fields persists across messages.\n\n```ts\n@message\nreply(packet: StreamPacket): StreamOutbound {\n  return StreamOutbound.reply(packet.bytes());   // echo the bytes back\n}\n```\n\n## Typed messages\n\nBy default a `@message` payload is **raw bytes**. Opt into a decoded `@data` value\nwith `@stream({ message: T })`: the `@message` hook then receives the named `@data`\nclass, decoded from the frame for you. The reply stays raw (`StreamOutbound`).\n\n```ts\n@data\nclass ChatMsg { text: string = ''; }\n\n@stream({ message: ChatMsg })\nclass Chat {\n  @message\n  onMessage(msg: ChatMsg): StreamOutbound {       // decoded @data, not raw bytes\n    return StreamOutbound.reply(new TextEncoder().encode(msg.text));\n  }\n}\n```\n\n## The client\n\nA `@stream` class is reachable from the browser as `Server.Stream.<ClassName>`. The\ntyped client is generated into `shared/server.ts` (the same place `Server.REST`\nlands), so no manual wiring is needed. `connect()` opens a WebSocket to the class's\nroute and resolves a channel:\n\n```ts\nconst chat = await Server.Stream.Chat.connect();\nchat.onMessage((bytes) => { /* a reply frame, always raw bytes */ });\nchat.send(new ChatMsg('hello'));   // a typed stream: send() encodes the @data for you\nchat.onClose((code) => { /* a 0x02xx stream close code */ });\nchat.close();\n```\n\n- The channel key is the **class name** (`Server.Stream.Chat`); it connects to the\n  class's mount route (`/Chat`).\n- A **raw** `@stream` channel sends `Uint8Array`; a **typed** `@stream({ message: T })`\n  channel sends the `@data` class and encodes it on the wire for you.\n- The inbound reply is **always raw bytes** - the server's `StreamOutbound` is raw.\n- `connect()` resolves once the upgrade completes; a `@connect` reject (or any\n  later server close) surfaces through `onClose(code)`.\n\n---\n\nSee also: [Tiers](./tiers.md), [Daemon](./daemon.md), [Routing](./routing.md).\n",
     "daemon.md": "# Daemon\n\n`@daemon` declares a single, leader-elected background worker for your domain -\nthe **L4** (global) coordination tier of the Toil edge. Where a `@rest` handler\nis a fresh instance per request and a `@stream` box is one instance per\nconnection, there is exactly **one** daemon per domain at a time. The edge keeps\na warm standby ready and fails over at-most-once, so the daemon is the right\nplace for work that must happen once globally rather than once per request.\n\n```ts\n@daemon\nclass Jobs {\n  @scheduled('1h')\n  hourly(): void {\n    // Runs once an hour on the elected leader. Put recurring background work\n    // here (rollups, cleanup, polling an upstream, ...).\n  }\n}\n```\n\n## `@daemon` classes\n\n`@daemon` marks a class as the domain's background worker. The class is resident:\nit is created once on the elected leader and lives for as long as that leader\nholds the lease, so its fields persist across scheduled runs (a `@rest`\nhandler's fields would reset every request).\n\nExactly one daemon instance runs per domain at any moment. A second node stays a\nwarm standby and only becomes active if the current leader's lease lapses. You do\nnot start, stop, or place the daemon yourself - the edge elects the leader and\ndrives it.\n\n## `@scheduled`\n\nA `@scheduled` method declares a task that fires on a cadence, always on the\n**elected leader**. The single string argument is the cadence:\n\n```ts\n@scheduled('1h')\nhourly(): void { /* ... */ }\n```\n\n- **Interval strings** like `'1h'` fire on that fixed period.\n- **Cron expressions** are also supported when you need a wall-clock schedule\n  rather than a fixed interval.\n\nA class can declare several `@scheduled` methods; each runs on its own cadence.\nBecause only the leader fires them, a task runs once per domain per tick, not\nonce per node.\n\n## The daemon entry\n\nThe daemon surface has its own entry module, `server/main.daemon.ts`. It imports\nthe `@daemon` classes so the compiler-generated `daemon_start` / `scheduled_tick`\nexports are pulled into the artifact:\n\n```ts\n// server/main.daemon.ts\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\n\nimport './daemon/Jobs';\n\n// The abort hook (the daemon box reports a trap through it). NOTE: unlike main.ts /\n// main.stream.ts, the daemon entry does NOT re-export the request runtime - a cold\n// artifact exposes daemon_start/scheduled_tick, not the request `handle`.\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n  revertOnError(message, fileName, line, column);\n}\n```\n\nNote what is **not** here: unlike `main.ts` and `main.stream.ts`, the daemon\nentry does not `export * from 'toiljs/server/runtime/exports'`. A daemon (cold)\nartifact exposes `daemon_start` and `scheduled_tick`, not the request `handle`.\nAdd a daemon as you grow by importing its module here.\n\n## Build\n\n`toiljs build` runs one toilscript pass per tier and hands each pass only the\nentries that belong to it. When the project declares a `@daemon` / `@scheduled`\nsurface, the daemon pass compiles `server/main.daemon.ts` into its own artifact,\n`build/server/release-cold.wasm`:\n\n```sh\n$ ls build/server/*.wasm\nbuild/server/release.wasm          # L1 request    (exports: handle)\nbuild/server/release-stream.wasm   # L2/L3 stream   (exports: stream_dispatch)\nbuild/server/release-cold.wasm     # L4 daemon      (exports: daemon_start, scheduled_tick)\n```\n\nSo `release.wasm` never contains `scheduled_tick` and the daemon artifact never\ncontains the request `handle`. Plain `@data` and helper modules are shared into\nevery artifact. See [Tiers](./tiers.md) for how the three artifacts are produced\nfrom one source tree.\n\n## Use cases\n\nThe daemon is the once-per-domain tier, so it fits work you want to happen\nglobally on a cadence rather than per request:\n\n- **Periodic rollups** - aggregate counters or events into summaries.\n- **Cleanup** - expire stale rows, prune logs, reclaim resources.\n- **Polling an upstream** - pull from an external API on a schedule.\n- **Global coordination** - any task that must run exactly once across the\n  domain, not once per node.\n\n## Failover\n\nScheduling is **at-most-once**. A `@scheduled` task fires on whichever node\ncurrently holds the leader lease. If that leader fails, the warm standby takes\nover and fires the **subsequent** runs; the edge does not retry or duplicate the\ntick that was in flight when the leader was lost. This trades exactly-once\ndelivery for the guarantee that two nodes never run the same scheduled tick at\nonce, so design tasks to be safe to skip an occasional run and to be idempotent\nwhere a missed run matters.\n\n---\n\nSee also:\n\n- [Tiers](./tiers.md) - the three deployment tiers and how one source tree\n  compiles to a separate artifact per tier.\n- [Streams](./streams.md) - the L2/L3 `@stream` tier (one resident box per\n  connection).\n",
     "data.md": "# Data codec (`@data`)\n\n`@data` turns a plain class into a typed, versionable value with a deterministic\nbinary codec and a JSON codec. It is the backbone of request/response bodies,\nRPC arguments, sessions, and anything you persist. The same class becomes a\nfully typed client type in the generated `shared/server.ts` (see\n[RPC](./rpc.md)).\n\n```ts\n@data\nclass Player {\n  username: string = '';\n  admin: bool = false;\n  score: u64 = 0;\n}\n```\n\nFrom that the compiler synthesizes, on the class:\n\n- `encode(): Uint8Array` / `static decode(buf): T`, the binary codec (with a\n  4-byte type id prefix).\n- `encodeInto(w: DataWriter)` / `static decodeFrom(r: DataReader)`, the codec\n  without the type-id frame, for nesting.\n- `toJSON()` / `static fromJSON(v)`, the JSON codec (64-bit-and-larger integers\n  as decimal strings, so they survive `JSON.parse` exactly).\n- `static dataId(): u32`, a stable FNV-1a hash of the class name, written as the\n  type-id prefix by `encode()`.\n\nFields may be scalars (`u8`..`u256`, `i8`..`i256`, `f32`, `f64`, `bool`),\n`string`, a nested `@data` class, or an array `T[]` of any of these. Give every\nfield a default; the generated decoder and the client constructor use them.\n\n## Using `@data` in routes\n\nIn a **JSON** route, a `@data` parameter is revived from the parsed body and a\n`@data` return value is serialized with `toJSON()`. In a **Binary** route, the\nparameter is `decode`d from the raw body and the return value is `encode`d. The\nroute's stream mode (see [Routing](./routing.md#data-streams)) picks which.\n\n```ts\n@post('/')                       // JSON route\npublic create(input: NewPlayer): Player { /* input from JSON, Player to JSON */ }\n\n@route({ method: Methods.POST, path: '/blob', stream: DataStream.Binary })\npublic blob(input: FileData): FileResult { /* input.decode, result.encode */ }\n```\n\n## The binary codec: `DataWriter` / `DataReader`\n\nWhen you need to lay out bytes yourself, custom bodies, session payloads,\nchallenge messages, use the codec directly. It lives in the `data` module:\n\n```ts\nimport { DataWriter, DataReader } from 'data';\n```\n\nThe codec has a byte-for-byte identical TypeScript implementation in\n`toiljs/io` (`src/io/codec.ts`), so the client can read and write the exact same\nwire format the wasm guest does.\n\n### `DataWriter`\n\nEvery writer method returns the writer for chaining.\n\n| Method | Signature | Wire format |\n| --- | --- | --- |\n| `writeU8` / `writeI8` | `(v): DataWriter` | 1 byte |\n| `writeU16` / `writeI16` | `(v): DataWriter` | 2 bytes, little-endian |\n| `writeU32` / `writeI32` | `(v): DataWriter` | 4 bytes, LE |\n| `writeU64` / `writeI64` | `(v): DataWriter` | 8 bytes, LE |\n| `writeF32` / `writeF64` | `(v): DataWriter` | 4 / 8 bytes, IEEE-754 LE |\n| `writeBool` | `(v): DataWriter` | 1 byte (`1`/`0`) |\n| `writeBytes` | `(b: Uint8Array): DataWriter` | `u32` length (LE) + raw bytes |\n| `writeString` | `(s: string): DataWriter` | `u32` length (LE) + UTF-8 bytes |\n| `writeU128` / `writeI128` | `(v): DataWriter` | two `u64` limbs (lo, hi) |\n| `writeU256` / `writeI256` | `(v): DataWriter` | four `u64` limbs (lo1, lo2, hi1, hi2) |\n| `length` | `(): i32` | bytes written so far |\n| `toBytes` | `(): Uint8Array` | an exact-length copy of the buffer |\n\n### `DataReader`\n\nReads are bounds-safe: an over-read never traps. It returns a zero/empty default\nand sets the public `ok` flag to `false`. Check `ok` after a sequence of reads\nto detect a truncated or malformed buffer.\n\n| Method | Signature | On over-read |\n| --- | --- | --- |\n| `readU8` / `readI8` | `(): u8 / i8` | `0` |\n| `readU16`..`readU64`, `readI16`..`readI64` | `(): integer` | `0` |\n| `readF32` / `readF64` | `(): f32 / f64` | `0` |\n| `readBool` | `(): bool` | `false` |\n| `readBytes` | `(): Uint8Array` | empty array |\n| `readString` | `(): string` | `\"\"` |\n| `readU128`/`readI128`/`readU256`/`readI256` | `(): bignum` | `0` |\n| `remaining` | `(): i32` | bytes left unread |\n| `ok` | `bool` (field) | `false` once any read over-ran |\n\n### Example\n\n```ts\nimport { DataWriter, DataReader } from 'data';\n\n// Write: u8 version, str name, u64 score, bytes blob\nconst out = new DataWriter()\n  .writeU8(1)\n  .writeString('alice')\n  .writeU64(1234)\n  .writeBytes(payload)\n  .toBytes();\n\n// Read it back\nconst r = new DataReader(out);\nconst version = r.readU8();\nconst name = r.readString();\nconst score = r.readU64();\nconst blob = r.readBytes();\nif (!r.ok) return Response.badRequest('truncated');\n```\n\n## Notes\n\n- **Endianness.** The AS guest codec is little-endian. The TypeScript `toiljs/io`\n  codec defaults to little-endian and also accepts a per-call `be` flag for\n  big-endian network formats; keep both ends on the same setting.\n- **Field order is the format.** The binary layout is exactly the field\n  declaration order. Reordering fields, or changing a type, is a breaking format\n  change. Add new fields at the end and bump a leading version byte if you need\n  to evolve a hand-rolled payload.\n- **`encode()` carries a type id.** The 4-byte `dataId()` prefix lets a decoder\n  confirm it is reading the type it expects. `encodeInto`/`decodeFrom` skip the\n  frame for nesting one `@data` value inside another.\n",
     "caching.md": "# Caching\n\ntoiljs can cache a response at the edge (shared, across users) and instruct the\nbrowser to cache it too. You opt in per route, either declaratively with the\n`@cache` decorator or imperatively with `Response.cache(...)`. The edge keys a\ncached entry by host, method, path, and body hash, and honors a per-entry TTL.\n\n## `@cache` decorator\n\nAnnotate a route method; the compiler appends the cache directive to whatever\n`Response` the route returns, so it composes with every return shape (a\n`Response`, a `void` 204, or an auto-encoded `@data` value).\n\n```ts\n@cache(60)              // 60 minutes at the edge\n@cache(60, 300)         // + 5 minutes (300s) in the browser\n@cache(60, 300, true)   // + private scope (per-user caches only)\n@cache(60, 300, true, true) // + cache even for authenticated requests\n@get('/leaderboard')\npublic top(): Standings { /* … */ }\n```\n\nArguments must be integer or boolean literals; a non-literal argument makes the\ndecorator degrade safely to \"not cached\" rather than miscompile.\n\n## `Response.cache(...)`\n\nThe same controls are available imperatively, which is what `@cache` lowers to:\n\n```ts\npublic cache(\n  edgeTtlMinutes: u16,\n  browserTtlSeconds: u32 = 0,\n  privateScope: bool = false,\n  allowAuth: bool = false,\n): Response\n```\n\n```ts\nreturn Response.json(body).cache(60, 300);\n```\n\n`cacheFor(minutes)` is the common shorthand for \"edge only, no browser caching\":\n\n```ts\nreturn Response.bytes(blob).cacheFor(5);\n```\n\n## Parameters\n\n| Parameter | Meaning |\n| --- | --- |\n| `edgeTtlMinutes` | How long the edge may serve the cached response. Clamped to a 24-hour maximum. |\n| `browserTtlSeconds` | `max-age` for the browser. `0` (default) means the browser does not cache. |\n| `privateScope` | Marks the response `private`: only per-user caches (the browser), never a shared edge/CDN cache. |\n| `allowAuth` | Permit caching a response to an authenticated request. Off by default (see safety rails). |\n\n## Safety rails\n\nThe cache layer refuses to store anything unsafe, regardless of the directive:\n\n- **5xx** responses are never cached, a server error is transient, and `@cache`\n  wraps the whole route, so a `@cache`d route that hits a blip returns its 500\n  carrying the directive; caching it would serve the failure for the full TTL.\n  **2xx, 3xx, and 4xx are cacheable** (a redirect or a `404`/`410` is a\n  deterministic function of the request key);\n- a response that sets a **`Set-Cookie`** is never cached;\n- a response to an **authenticated** request is not cached unless you pass\n  `allowAuth = true`, this prevents one user's personalized response from being\n  served to another;\n- the edge TTL is **clamped to 24 hours**.\n\nBecause `@auth` guards and body-decode run before the cache directive is applied,\nan unauthorized request is rejected with 401 before anything is cached, and a\ncached entry is only ever produced from a handler that actually ran.\n\nCaching is **always opt-in.** A response with no `Toil-Cache-Control` directive\n(i.e. no `@cache` / `Response.cache(...)`) is never stored, there is no blind\n\"cache every GET\" mode, because an automatic window cannot tell a personalized\nresponse from a public one and would key it without a per-user component.\n\n## Memory bounds and disk spill\n\nThe edge cache is per-core and hard-capped so it can never exhaust node memory.\nIt has two tiers:\n\n- **RAM tier**, small, short-TTL responses. Bounded by a per-core byte budget\n  (each core holds at most ~128 MB) plus an entry-count cap; an insert that would\n  exceed the budget drops expired entries first, then evicts the soonest-to-expire\n  ones. A response over ~256 KB does not go in the RAM tier.\n- **Disk tier (spill)**, when the operator enables `--spill-dir`, a **big**\n  (over the ~256 KB RAM cap) or **long-TTL** (≥ 10 min) cacheable response is\n  written to disk instead and served back zero-RAM via a memory map, the same way\n  static files are served. This keeps the RAM tier for the hot working set while\n  still caching large bodies and long-lived entries. Writes (and unlinks) are\n  offloaded to a sibling thread so they never stall the request path; a separate\n  per-core disk budget caps total spilled bytes, with the same expiry + eviction.\n  If spill is not enabled, a big response is simply not cached (reported as not\n  stored by the `Toil-Cache` tag).\n\nFrom a tenant's point of view nothing changes: you still just set a\n`Toil-Cache-Control` directive (via `@cache` / `Response.cache(...)`). The edge\ndecides RAM vs disk; both honor the same TTL and the same safety rails above.\nExpiry is enforced on read (a past-TTL entry is a miss) and reclaimed on the next\ninsert that needs room. Nothing persists across a process restart.\n\n## Choosing TTLs\n\n- Public, slow-changing data (a leaderboard, a catalog): a few minutes of edge\n  TTL plus a short browser TTL removes most of the load.\n- Per-user data: set `privateScope` so it never lands in a shared cache, and\n  prefer a small or zero edge TTL.\n- Anything with a `Set-Cookie` or behind `@auth`: leave it uncached unless you\n  have thought through `allowAuth` and are certain the body is identical for\n  every authorized caller.\n",
@@ -25,5 +25,6 @@ export const TOIL_DOCS: Record<string, string> = {
     "cookies.md": "# Cookies\n\nA complete HTTP cookie layer for the toiljs server runtime, covering the full\nRFC 6265bis surface (including `SameSite`, the `Partitioned`/CHIPS attribute, and\nthe `__Host-` / `__Secure-` prefixes) plus cryptographic signing and encryption.\n\n`Cookie`, `Cookies`, `CookieMap`, `SecureCookies`, and the `SameSite` /\n`CookieEncoding` / `CookiePrefix` enums are **ambient globals**: a handler uses\nthem with **no import**, exactly like `crypto`. They are also exported from\n`toiljs/server/runtime` for anyone who prefers an explicit import.\n\n- [How \"global, no import\" works](#how-global-no-import-works)\n- [Quick start](#quick-start)\n- [The `Cookie` builder](#the-cookie-builder)\n- [The `Cookies` parser and codec](#the-cookies-parser-and-codec)\n- [`CookieMap`](#cookiemap)\n- [`SecureCookies` signing and encryption](#securecookies-signing-and-encryption)\n- [`Request` and `Response` integration](#request-and-response-integration)\n- [`base64url` helpers](#base64url-helpers)\n- [Encoding vs encryption](#encoding-vs-encryption)\n- [Security notes](#security-notes)\n- [Spec compliance](#spec-compliance)\n- [Testing](#testing)\n- [API reference](#api-reference)\n\n---\n\n## How \"global, no import\" works\n\nThe cookie types are declared with ToilScript's `@global` decorator and pulled\ninto every server build (re-exported from `toiljs/server/runtime` and\nside-effect-imported by `toiljs/server/runtime/exports`, which every `main.ts`\nre-exports). At compile time the symbols register in the global scope, so a\nhandler can write `Cookie.create(...)` or `req.cookie(...)` without importing\nanything.\n\nFor the editor, `toiljs create` scaffolds `server/toil-server-env.d.ts` with\nambient `declare`s for these globals (the toilscript compiler ignores `.d.ts`;\nit only feeds the language service). If you would rather import them:\n\n```ts\nimport { Cookie, Cookies, SecureCookies, SameSite } from 'toiljs/server/runtime';\n```\n\n---\n\n## Quick start\n\n```ts\nimport { ToilHandler, Request, Response } from 'toiljs/server/runtime';\n\nexport class AppHandler extends ToilHandler {\n    public handle(req: Request): Response {\n        // Read (no import needed for Cookie / Cookies / SameSite, they are global).\n        const sid = req.cookie('sid'); // string | null\n\n        // Write a hardened session cookie.\n        return Response.json('{\"ok\":true}').setCookie(\n            Cookie.create('sid', 'abc123')\n                .httpOnly()\n                .secure()\n                .sameSite(SameSite.Lax)\n                .maxAge(3600)\n                .asHostPrefixed(), // forces Secure + Path=/ + no Domain\n        );\n    }\n}\n```\n\n---\n\n## The `Cookie` builder\n\nA fluent builder that serializes to one `Set-Cookie` field value. Every setter\nreturns the cookie, so calls chain.\n\n```ts\nconst c = Cookie.create('id', 'abc123')\n    .domain('example.com')\n    .path('/app')\n    .maxAge(3600)\n    .secure()\n    .httpOnly()\n    .sameSite(SameSite.Lax);\n\nc.serialize();\n// \"id=abc123; Domain=example.com; Path=/app; Max-Age=3600; SameSite=Lax; Secure; HttpOnly\"\n```\n\n### Fields\n\n| Field | Type | Notes |\n| --- | --- | --- |\n| `name` | `string` | The cookie name (a token; never encoded). |\n| `value` | `string` | The logical value (encoded per `encoding` on serialize). |\n| `encoding` | `CookieEncoding` | Wire encoding for the value. Default `Percent`. |\n\n### Construction\n\n- `new Cookie(name, value)`\n- `Cookie.create(name, value): Cookie`, a builder-style alias.\n\n### Attribute setters\n\n| Method | Attribute |\n| --- | --- |\n| `domain(v: string)` | `Domain` |\n| `path(v: string)` | `Path` (must begin with `/`) |\n| `maxAge(seconds: i64)` | `Max-Age` (`0` / negative expire immediately) |\n| `expires(epochSeconds: i64)` | `Expires`, formatted as an IMF-fixdate (`Sun, 06 Nov 1994 08:49:37 GMT`) |\n| `expiresRaw(date: string)` | `Expires` verbatim (escape hatch) |\n| `secure(on: bool = true)` | `Secure` |\n| `httpOnly(on: bool = true)` | `HttpOnly` |\n| `sameSite(s: SameSite)` | `SameSite` |\n| `partitioned(on: bool = true)` | `Partitioned` (CHIPS) |\n| `priority(p: string)` | `Priority` (`Low` / `Medium` / `High`) |\n| `extension(av: string)` | An arbitrary extension attribute, appended verbatim |\n| `withEncoding(e: CookieEncoding)` | Choose the value wire encoding |\n\n### Prefixes\n\n- `asSecurePrefixed(): Cookie`, prepends `__Secure-` and forces `Secure`.\n- `asHostPrefixed(): Cookie`, prepends `__Host-` and forces `Secure`, `Path=/`, and no `Domain`.\n- `detectedPrefix(): CookiePrefix`, the prefix detected on the current name (case-insensitive).\n\n### Output\n\n- `serialize(strict: bool = false): string`, returns the `Set-Cookie` value. Lenient by\n  default (always returns a best-effort cookie); pass `strict = true` to throw on\n  a hard validation failure. `Secure` is added automatically when `SameSite=None`\n  or `Partitioned` is set; `Max-Age` is clamped to the 400-day cap; control\n  characters are stripped from the name, value, and attributes.\n- `toString(): string`, alias for `serialize()`.\n- `encodedValue(): string`, the value transformed per `encoding`.\n\n### Validation\n\n`validate(): CookieValidation` checks the cookie against RFC 6265bis and returns\na structured result:\n\n```ts\nclass CookieValidation {\n    valid: bool;\n    errors: Array<string>;\n}\n```\n\nIt flags: a non-token name, name+value over 4096 bytes, a `Domain`/`Path` over\n1024 bytes, a `Path` not starting with `/`, a `Raw` value outside `cookie-octet`,\nthe `__Host-` / `__Secure-` prefix requirements, `SameSite=None` or `Partitioned`\nwithout `Secure`, and a `Max-Age` beyond the 400-day cap.\n\n### Attribute serialization order\n\n`name=value` then, when set: `Domain`, `Path`, `Expires`, `Max-Age`, `SameSite`,\n`Secure`, `HttpOnly`, `Partitioned`, `Priority`, then any `extension(...)` values.\n(Attribute order is not significant to user agents; the order is stable so output\nis predictable.)\n\n### Enums\n\n```ts\nenum SameSite { Default, None, Lax, Strict }      // Default omits the attribute\nenum CookieEncoding { Percent, Raw, Base64Url }   // value wire encoding\nenum CookiePrefix { None, Secure, Host }\n```\n\n---\n\n## The `Cookies` parser and codec\n\nStatic helpers for the read side and a one-shot serializer.\n\n| Method | Description |\n| --- | --- |\n| `Cookies.parse(cookieHeader: string): CookieMap` | Parse a request `Cookie` header (`a=1; b=2`). Values are percent-decoded; one layer of surrounding quotes is stripped; malformed pairs and empty names are skipped. On a duplicate name the first wins. |\n| `Cookies.get(cookieHeader: string, name: string): string \\| null` | Parse and return one value. |\n| `Cookies.serialize(name: string, value: string): string` | One-shot `name=value` with no attributes (percent-encoded). For attributes, build a `Cookie`. |\n| `Cookies.parseSetCookie(setCookie: string): Cookie` | Parse a `Set-Cookie` line back into a `Cookie` (for clients, tests, proxies). Kept verbatim (`CookieEncoding.Raw`) so re-serializing reproduces the wire form. |\n| `Cookies.encodeValue(raw: string): string` | Percent-encode a value (the default `Cookie` encoding). |\n| `Cookies.decodeValue(enc: string): string` | Percent-decode a value (the inverse). |\n\n```ts\nconst jar = Cookies.parse('sid=abc123; theme=dark');\njar.get('sid'); // \"abc123\"\n\nCookies.serialize('sid', 'a b'); // \"sid=a%20b\"\n```\n\n---\n\n## `CookieMap`\n\nThe ordered name to value view returned by `Cookies.parse` and `Request.cookies()`.\nBacked by parallel arrays (a request carries a handful of cookies, so a linear\nscan beats hashing and keeps the runtime small).\n\n| Member | Description |\n| --- | --- |\n| `get(name: string): string \\| null` | The value, or `null`. |\n| `has(name: string): bool` | Whether the cookie is present. |\n| `names(): Array<string>` | A copy of the names, in encounter order. |\n| `size: i32` | The number of cookies. |\n| `set(name: string, value: string): void` | Insert unless present (keep-first). Used by `parse`; rarely called directly. |\n\n---\n\n## `SecureCookies` signing and encryption\n\nTamper-proof and confidential cookie values, built on the `crypto` global (no new\nhost functions).\n\n- **`SecureCookies.signed(key)`**: HMAC-SHA256. The value stays readable but is\n  bound to the cookie name, so it cannot be tampered with or moved to another\n  cookie. Sealed form: `base64url(value) \".\" base64url(mac)`.\n- **`SecureCookies.encrypted(key)`**: AES-256-GCM (or AES-128-GCM) with a random\n  96-bit IV and the cookie name as additional authenticated data. The value is\n  confidential and authenticated. Sealed form: `base64url(iv ‖ ciphertext ‖ tag)`.\n\nKeys are caller-supplied raw bytes:\n\n- HMAC: any length (32+ bytes recommended).\n- AES: exactly 16 or 32 bytes (enforced up front; a wrong length is rejected by\n  the factory).\n\n```ts\n// A real app loads a long random secret from config; never hard-code one.\nconst key = Uint8Array.wrap(String.UTF8.encode('0123456789abcdef0123456789abcdef'));\n\n// Signed (readable, tamper-proof)\nconst signer = SecureCookies.signed(key);\nconst sealed = signer.sign('session', 'user-42');\nconst user = signer.unsign('session', sealed); // \"user-42\", or null if tampered\n\n// Encrypted (confidential + authenticated)\nconst box = SecureCookies.encrypted(key);\nresp.setCookie(box.seal(Cookie.create('secret', 'top-secret').httpOnly()));\nconst secret = box.open(req.cookies(), 'secret'); // \"top-secret\", or null\n```\n\n| Method | Description |\n| --- | --- |\n| `SecureCookies.signed(key: Uint8Array)` | HMAC-SHA256 signer/verifier. |\n| `SecureCookies.encrypted(key: Uint8Array)` | AES-GCM (16- or 32-byte key). |\n| `addKey(key: Uint8Array): SecureCookies` | Add a fallback key for rotation: seal with the first, open with any. |\n| `sign(name, value): string` | Sealed signed value. |\n| `unsign(name, sealed): string \\| null` | Verify and recover, or `null`. |\n| `encrypt(name, value): string` | Sealed encrypted value. |\n| `decrypt(name, sealed): string \\| null` | Decrypt, or `null`. |\n| `seal(cookie: Cookie): Cookie` | Seal a cookie's value in place (sign or encrypt per the instance mode) and mark it `Raw`. Returns the same cookie. |\n| `open(jar: CookieMap, name): string \\| null` | Read and open cookie `name` from a parsed jar. |\n\n**Key rotation:** seal with `keys[0]`; `unsign` / `decrypt` try every key in turn,\nso you can add a new key as the first and keep an old one as a fallback while\nexisting cookies age out.\n\n```ts\nconst signer = SecureCookies.signed(newKey).addKey(oldKey);\n```\n\n---\n\n## `Request` and `Response` integration\n\nBecause every handler already has a `Request` and returns a `Response`, the most\ncommon operations live there directly.\n\n**Read (`Request`):**\n\n| Method | Description |\n| --- | --- |\n| `req.cookies(): CookieMap` | All cookies, parsed from the `Cookie` header (cached for the request). |\n| `req.cookie(name: string): string \\| null` | One cookie value. |\n\n**Write (`Response`, builder-style):**\n\n| Method | Description |\n| --- | --- |\n| `resp.setCookie(cookie: Cookie): Response` | Append a `Set-Cookie`. Each call adds its own header (cookies are never folded). |\n| `resp.setCookieKV(name, value): Response` | Shorthand for `setCookie(new Cookie(name, value))`. |\n| `resp.clearCookie(name, path = '/', domain = ''): Response` | Append a deletion cookie (empty value, `Max-Age=0`, epoch `Expires`). `path` / `domain` must match the original. |\n\n---\n\n## `base64url` helpers\n\nUnpadded base64url (RFC 4648 §5), used internally by `SecureCookies` and exported\nfor convenience. Its alphabet (`A-Z a-z 0-9 - _`) is within the `cookie-octet`\ngrammar and invariant under percent-encoding, so encoded values round-trip\ncleanly through the default cookie codec.\n\n| Function | Description |\n| --- | --- |\n| `base64UrlEncode(data: Uint8Array): string` | Encode bytes as unpadded base64url. |\n| `base64UrlDecode(s: string): Uint8Array \\| null` | Decode base64url/base64 (padding and whitespace tolerated); `null` on an invalid character or length. |\n\n---\n\n## Encoding vs encryption\n\nTwo independent layers, easy to mix up:\n\n- **Encoding** (`CookieEncoding`) is transport-only and reversible by anyone. It\n  keeps an arbitrary value inside the `cookie-octet` grammar.\n  - `Percent` (default): `encodeURIComponent`-style; arbitrary UTF-8 is safe.\n  - `Base64Url`: UTF-8 then base64url.\n  - `Raw`: no transformation (the value must already be valid `cookie-octet`).\n- **Signing / encryption** (`SecureCookies`) is cryptographic. Signing keeps the\n  value readable but tamper-proof; encryption makes it unreadable and\n  authenticated. Both require a secret key.\n\n`SecureCookies.seal` sets the value to its sealed (base64url) form and marks the\ncookie `Raw`, so it passes through the default parse path untouched.\n\n---\n\n## Security notes\n\n- **Panic-free verification.** `unsign` and `decrypt` return `null` on a tampered,\n  truncated, or wrong-key value, never a trap. (`decrypt` reads the host return\n  code directly instead of letting the underlying crypto throw, because the\n  server runs with exceptions disabled.) This makes them safe to call on\n  attacker-controlled input.\n- **Name-binding.** Signing MACs `name + \"=\" + value`; encryption uses the name as\n  AAD. A sealed value made for one cookie name will not verify or decrypt under\n  another.\n- **Control characters are stripped** from the name, value, and attribute values\n  on serialize, as a defense-in-depth guard against header injection (CR/LF).\n  Control characters are invalid in all of these per the grammar, so nothing\n  legitimate is lost. The default value encoding already neutralizes CR/LF.\n- **Prefixes.** `asHostPrefixed()` / `asSecurePrefixed()` apply and enforce the\n  browser-recognized guarantees; `validate()` reports a name that carries a prefix\n  without satisfying its requirements.\n- **`SameSite=None` and `Partitioned` imply `Secure`** and are emitted with it\n  automatically.\n- **Lifetime is clamped** to the RFC 400-day cap on serialize; sizes are checked by\n  `validate()`.\n- **Local development.** Browsers treat `http://localhost` as a secure context, so\n  `Secure` and `__Host-` cookies work under `toiljs dev` over plain HTTP.\n\nWhen putting untrusted input into a cookie **name** or **attribute** (rather than\nthe value, which is encoded by default), check `validate()` or use\n`serialize(true)`.\n\n---\n\n## Spec compliance\n\nImplements RFC 6265bis (HTTP State Management) and the `Partitioned` (CHIPS)\ncompanion: the `cookie-name` token and `cookie-value` `cookie-octet` grammars,\nthe `Expires` / `Max-Age` / `Domain` / `Path` / `Secure` / `HttpOnly` /\n`SameSite` / `Partitioned` attributes plus `Priority` and arbitrary extensions,\nthe `__Host-` / `__Secure-` prefixes (matched case-insensitively), the 4096-byte\nname+value and 1024-byte attribute limits, the 400-day lifetime cap, the\n`SameSite=None` ⇒ `Secure` rule, and the requirement that each cookie occupy its\nown `Set-Cookie` header (never folded).\n\n---\n\n## Testing\n\n- Pure cookie logic (builder, parser, codec, validation, `Request` / `Response`\n  integration) is unit-tested with as-pect in `test/assembly/cookie.spec.ts`\n  (`npm run test:server`).\n- `SecureCookies` is exercised end-to-end against the real toilscript-compiled\n  wasm with the Node-backed crypto host in `test/devserver.test.ts`\n  (`npm test`). It is tested there rather than under as-pect because the as-pect\n  compiler does not ship the toilscript crypto standard library.\n\nA live demo (every attribute's serialized output, set/inspect/clear, and an\ninteractive sign/encrypt) is in the example app: run `toiljs dev` in\n`examples/basic` and open `/cookies`. The backend lives in\n`examples/basic/server/core/AppHandler.ts`.\n\n---\n\n## API reference\n\n```ts\n// Globals (also exported from 'toiljs/server/runtime')\n\nenum SameSite { Default, None, Lax, Strict }\nenum CookieEncoding { Percent, Raw, Base64Url }\nenum CookiePrefix { None, Secure, Host }\n\nclass CookieValidation {\n    valid: bool;\n    errors: Array<string>;\n}\n\nclass Cookie {\n    name: string;\n    value: string;\n    encoding: CookieEncoding;\n    static create(name: string, value: string): Cookie;\n    domain(v: string): Cookie;\n    path(v: string): Cookie;\n    maxAge(seconds: i64): Cookie;\n    expires(epochSeconds: i64): Cookie;\n    expiresRaw(date: string): Cookie;\n    secure(on?: bool): Cookie;\n    httpOnly(on?: bool): Cookie;\n    sameSite(s: SameSite): Cookie;\n    partitioned(on?: bool): Cookie;\n    priority(p: string): Cookie;\n    extension(av: string): Cookie;\n    withEncoding(e: CookieEncoding): Cookie;\n    asSecurePrefixed(): Cookie;\n    asHostPrefixed(): Cookie;\n    detectedPrefix(): CookiePrefix;\n    encodedValue(): string;\n    validate(): CookieValidation;\n    serialize(strict?: bool): string;\n    toString(): string;\n}\n\nclass CookieMap {\n    get(name: string): string | null;\n    has(name: string): bool;\n    names(): Array<string>;\n    size: i32;\n    set(name: string, value: string): void;\n}\n\nclass Cookies {\n    static parse(cookieHeader: string): CookieMap;\n    static get(cookieHeader: string, name: string): string | null;\n    static serialize(name: string, value: string): string;\n    static parseSetCookie(setCookie: string): Cookie;\n    static encodeValue(raw: string): string;\n    static decodeValue(enc: string): string;\n}\n\nclass SecureCookies {\n    static signed(key: Uint8Array): SecureCookies;\n    static encrypted(key: Uint8Array): SecureCookies;\n    addKey(key: Uint8Array): SecureCookies;\n    sign(name: string, value: string): string;\n    unsign(name: string, sealed: string): string | null;\n    encrypt(name: string, value: string): string;\n    decrypt(name: string, sealed: string): string | null;\n    seal(cookie: Cookie): Cookie;\n    open(jar: CookieMap, name: string): string | null;\n}\n\nfunction base64UrlEncode(data: Uint8Array): string;\nfunction base64UrlDecode(s: string): Uint8Array | null;\n\n// On Request\nreq.cookies(): CookieMap;\nreq.cookie(name: string): string | null;\n\n// On Response (builder-style)\nresp.setCookie(cookie: Cookie): Response;\nresp.setCookieKV(name: string, value: string): Response;\nresp.clearCookie(name: string, path?: string, domain?: string): Response;\n```\n",
     "crypto.md": "# Web Crypto\n\nThe guest gets a synchronous Web Crypto surface through the ambient `crypto`\nglobal, backed by host functions. It mirrors the browser `crypto` /\n`crypto.subtle` API but **without Promises**, ToilScript has no `async`, so\nevery call returns its result directly. Keys are opaque per-request handles in a\nhost keystore; a `CryptoKey` is valid only for the request that created it.\n\n```ts\nconst mac = crypto.hmacSha256(key, message); // Uint8Array\nconst id  = crypto.randomUUID();             // string\n```\n\nThis is also what [`SecureCookies`](./cookies.md) and\n[`AuthService`](./auth.md) are built on, so most apps use crypto indirectly.\n\n## `crypto` namespace\n\nConvenience helpers (all synchronous):\n\n| Function | Signature | Notes |\n| --- | --- | --- |\n| `getRandomValues` | `(array: Uint8Array): void` | Fill with CSPRNG bytes. |\n| `randomUUID` | `(): string` | RFC 4122 v4 UUID. |\n| `sha1` / `sha256` / `sha384` / `sha512` | `(data: Uint8Array): Uint8Array` | One-shot digests. |\n| `sha1Text` … `sha512Text` | `(s: string): Uint8Array` | UTF-8 encode then digest. |\n| `hmacSha256` | `(key: Uint8Array, msg: Uint8Array): Uint8Array` | One-shot HMAC-SHA256. |\n| `hmacSha256Text` | `(key: Uint8Array, msg: string): Uint8Array` | HMAC-SHA256 over a UTF-8 string. |\n| `toHex` | `(bytes: Uint8Array): string` | Lowercase hex. |\n| `subtle` | `SubtleCrypto` | The full primitive surface (below). |\n\n## `crypto.subtle`\n\n| Method | Signature |\n| --- | --- |\n| `digest` | `digest(algorithm: string, data: Uint8Array): Uint8Array` |\n| `importKey` | `importKey(format: string, keyData: Uint8Array, algorithm: AlgorithmParams, extractable: bool, usages: i32): CryptoKey` |\n| `exportKey` | `exportKey(format: string, key: CryptoKey): Uint8Array` |\n| `encrypt` | `encrypt(algorithm: AlgorithmParams, key: CryptoKey, data: Uint8Array): Uint8Array` |\n| `decrypt` | `decrypt(algorithm: AlgorithmParams, key: CryptoKey, data: Uint8Array): Uint8Array` |\n| `sign` | `sign(algorithm: AlgorithmParams, key: CryptoKey, data: Uint8Array): Uint8Array` |\n| `verify` | `verify(algorithm: AlgorithmParams, key: CryptoKey, signature: Uint8Array, data: Uint8Array): bool` |\n| `deriveBits` | `deriveBits(algorithm: AlgorithmParams, baseKey: CryptoKey, length: i32): Uint8Array` |\n| `deriveKey` | `deriveKey(algorithm, baseKey, lengthBits, derivedKeyAlgorithm, extractable, usages): CryptoKey` |\n\n`digest` takes a named algorithm string (`\"SHA-1\"`, `\"SHA-256\"`, `\"SHA-384\"`,\n`\"SHA-512\"`, `\"SHA3-256\"`, `\"SHA3-384\"`, `\"SHA3-512\"`). `verify` returns a bool\n(it does not throw on a mismatch). Formats are `raw`, `pkcs8`, `spki`; **`jwk`\nis not supported**.\n\n### Algorithm parameter classes\n\n`crypto` and `crypto.subtle` are ambient globals (no import). The params classes\nand the `ALG_*` / `USAGE_*` / `FMT_*` / `CURVE_*` constants and the `CryptoKey`\ntype are imported from the `'crypto'` module:\n\n```ts\nimport { AesGcmParams, HmacImportParams, ALG_SHA_256, USAGE_SIGN } from 'crypto';\n```\n\nEach algorithm has a small params class you pass to `importKey`/`sign`/etc.:\n\n| Class | Constructor |\n| --- | --- |\n| `AesGcmParams` | `(iv, additionalData?, tagLength = 128)` |\n| `AesCbcParams` | `(iv)` |\n| `AesCtrParams` | `(counter, length = 128)` |\n| `HmacImportParams` | `(hash)` |\n| `HmacParams` | `()` |\n| `Pbkdf2Params` | `(hash, salt, iterations)` |\n| `HkdfParams` | `(hash, salt, info?)` |\n| `EcdsaParams` | `(hash)` |\n| `EcKeyImportParams` | `(alg, namedCurve)` |\n| `Ed25519Params` | `()` |\n| `X25519ImportParams` | `()` |\n| `EcdhParams` | `(alg, publicKeyHandle)` |\n\n### Constants\n\n- **Hashes / algorithms:** `ALG_SHA_1`, `ALG_SHA_256`, `ALG_SHA_384`,\n  `ALG_SHA_512`, `ALG_SHA3_256/384/512`, `ALG_AES_GCM`, `ALG_AES_CBC`,\n  `ALG_AES_CTR`, `ALG_HMAC`, `ALG_ECDSA`, `ALG_ED25519`, `ALG_ECDH`, `ALG_HKDF`,\n  `ALG_PBKDF2`.\n- **Key formats:** `FMT_RAW`, `FMT_PKCS8`, `FMT_SPKI` (`FMT_JWK` is rejected).\n- **Usages (bitmask):** `USAGE_ENCRYPT`, `USAGE_DECRYPT`, `USAGE_SIGN`,\n  `USAGE_VERIFY`, `USAGE_DERIVE_KEY`, `USAGE_DERIVE_BITS`, `USAGE_WRAP_KEY`,\n  `USAGE_UNWRAP_KEY`, OR them together.\n- **Named curves:** `CURVE_P256`, `CURVE_P384` (`CURVE_P521` is not supported).\n\n### `CryptoKey`\n\nAn opaque handle plus metadata: `handle: i32`, `type: string`\n(`secret`/`public`/`private`), `extractable: bool`, `algorithm: i32`,\n`usages: i32`, with `algorithmName()` and `hasUsage(u)`. A key is valid only for\nthe request that imported it.\n\n## Examples\n\nHMAC-SHA256 (one-shot):\n\n```ts\nconst mac = crypto.hmacSha256(key, message);\nconst hex = crypto.toHex(mac);\n```\n\nAES-256-GCM via `subtle`:\n\n```ts\nconst key = new Uint8Array(32); crypto.getRandomValues(key);\nconst iv  = new Uint8Array(12); crypto.getRandomValues(iv);\n\nconst k  = crypto.subtle.importKey('raw', key, new AesGcmParams(iv, aad, 128), false, USAGE_ENCRYPT);\nconst ct = crypto.subtle.encrypt(new AesGcmParams(iv, aad, 128), k, plaintext);\n```\n\n## Post-quantum verify\n\nThe host also exposes ML-DSA-44 (FIPS 204) signature verification as\n`crypto.mldsa_verify`. It is verify-only, the host never holds a secret key, and\nunderpins the [auth primitive](./auth.md). Most code reaches it through\n`AuthService.verifyLogin(publicKey, message, signature)` rather than calling the\nimport directly. Public key is 1312 bytes, signature 2420 bytes, with a FIPS 204\ndomain-separation context.\n\n## Limitations\n\n- **No Promises**, every call is synchronous.\n- **No RSA** and **no JWK** key format.\n- **P-521** is not supported (P-256 and P-384 are).\n- Signature *generation* for ML-DSA is client-side only; the server verifies.\n",
     "time.md": "# Time\n\n`Time` is the guest's wall-clock. It is the toiljs-blessed way to read the\ncurrent time, backed by the host's `Date.now()` binding (`env.Date.now`). Both\nthe edge and the dev server provide that binding, so time behaves identically in\n`toiljs dev` and in production.\n\nIt is available as an ambient global (`@global`, no import) and is also exported\nfrom `toiljs/server/runtime`.\n\n```ts\nimport { Time } from 'toiljs/server/runtime'; // optional; Time is also a global\n\nconst ms = Time.nowMillis();   // u64 milliseconds since the Unix epoch\nconst s  = Time.nowSeconds();  // u64 whole seconds since the Unix epoch\n```\n\n## API\n\n| Member | Signature | Description |\n| --- | --- | --- |\n| `Time.nowMillis()` | `static nowMillis(): u64` | Milliseconds since the Unix epoch (the raw host `Date.now()` value). |\n| `Time.nowSeconds()` | `static nowSeconds(): u64` | Whole seconds since the epoch (`nowMillis() / 1000`). The unit used by sessions and login challenges. |\n\n## Semantics\n\n`Time` is **wall-clock, not monotonic**, exactly like browser `Date.now()`. It\ntracks the system clock and can step backward across an NTP correction.\n\n- Use it to stamp and compare absolute instants: session `iat`/`exp`, login\n  challenge expiry, cache ages.\n- Do **not** use it to measure elapsed time or as a high-resolution timer; a\n  backward step would produce a negative or zero interval.\n\n## Relationship to `Date.now()`\n\nToilScript's `Date.now()` lowers to the same `env.Date.now` host import, so you\n*can* call it directly. Prefer `Time`: it makes the host boundary (and the\nsingle millisecond unit) explicit and easy to find, and it gives you\n`nowSeconds()` without an open-coded `/ 1000` cast at every call site.\n\n`AuthService` uses `Time.nowSeconds()` internally for session `iat`/`exp`, so\nsession timing and any timing you do in a handler share one clock.\n",
-    "cli.md": "# CLI\n\n- `toiljs create [name]`, scaffold a project. Flags: `--template app|minimal`,\n  `--style css|sass|less|stylus`, `--tailwind`, `--no-ai`, `-y`/`--yes`.\n- `toiljs dev`, dev server with HMR (`--port`, `--root`). With a `toilconfig.json` it builds\n  the server first, then rebuilds it whenever a `server/` file changes (regenerating\n  `shared/server.ts`, which Vite HMRs into the client); client-only edits just HMR the client.\n- `toiljs build`, production build. With a `toilconfig.json` it builds the server (toilscript,\n  regenerating `shared/server.ts`) first, then the client → `build/client`. `--server` builds\n  only the server. Every `server/` file declaring a surface (`@data`/`@rest`/...) is compiled.\n- `toiljs start`, self-host the built app (hyper-express) with a `/_toil` WebSocket channel.\n- `toiljs configure`, toggle styling features on an existing project (see [styling.md](./styling.md)).\n- `toiljs doctor`, diagnose project setup (`--json` for CI). `--fix` auto-wires the typed-RPC\n  setup (build scripts, tsconfig `shared` + alias, `.gitignore`, toilscript version, and the\n  toilscript prettier plugin) so an existing project upgrades in one command.\n",
+    "cli.md": "# CLI\n\n- `toiljs create [name]`, scaffold a project. Flags: `--template app|minimal`,\n  `--style css|sass|less|stylus`, `--tailwind`, `--no-ai`, `-y`/`--yes`.\n- `toiljs dev`, dev server with HMR (`--port`, `--root`). With a `toilconfig.json` it builds\n  the server first, then rebuilds it whenever a `server/` file changes (regenerating\n  `shared/server.ts`, which Vite HMRs into the client); client-only edits just HMR the client.\n- `toiljs build`, production build. With a `toilconfig.json` it builds the server (toilscript,\n  regenerating `shared/server.ts`) first, then the client → `build/client`. `--server` builds\n  only the server. Every `server/` file declaring a surface (`@data`/`@rest`/...) is compiled.\n- `toiljs start`, self-host the built app with production hyper-express/uWS static workers,\n  SSR/wasm dispatch, daemon support, and a `/_toil` WebSocket channel. Use `--threads <n>`\n  (or `server.threads`) to set the worker count; `1` disables the pool.\n- `toiljs configure`, toggle styling features on an existing project (see [styling.md](./styling.md)).\n- `toiljs doctor`, diagnose project setup (`--json` for CI). `--fix` auto-wires the typed-RPC\n  setup (build scripts, tsconfig `shared` + alias, `.gitignore`, toilscript version, and the\n  toilscript prettier plugin) so an existing project upgrades in one command.\n",
+    "derive.md": "# Derive (materialized views)\n\n`@derive` precomputes a read-optimized **view** from your data so reads stay\nfast and never scan. A request handler (`@get` runs as a *query*, `@post`/`@put`/\n`@delete` as an *action*) is not allowed to scan, reading \"the latest N events\"\nor \"every member of a set\" could fan out across unbounded rows, so those scans\nare barred on the request path. A `@derive` does the scan **off** the request\npath: it folds your event log / counters into a `View`, and your route serves\nthat view with a single keyed read.\n\n```ts\n@database\nclass GuestbookDb {\n  @collection static entries: Events<GuestKey, GuestEntry>;\n  @collection static totals: Counter<GuestKey>;\n  @collection static book: View<GuestKey, GuestbookView>;\n\n  // Recompute the view from the sources. Runs after a signature is written\n  // (and when a box first loads). A derive MAY scan + publish; a route may not.\n  @derive\n  recompute(): void {\n    const key = new GuestKey('main');\n    const view = new GuestbookView();\n    view.total = GuestbookDb.totals.get(key);      // counter read\n    view.entries = GuestbookDb.entries.latest(key, 10); // scan, allowed here\n    GuestbookDb.book.publish(key, view);           // publish the materialized view\n  }\n}\n```\n\n## Why a derive\n\nToilDB gates every data op by the *function kind* it runs under:\n\n- **query** (`@get`/`@head`) and **action** (`@post`/`@put`/`@patch`/`@delete`)\n  may do keyed reads and (actions only) writes, but **not scans**\n  (`events.latest`, `membership.list`).\n- **derive** may do everything a read can, **plus** scans, plus\n  `view.publish`/`append`/`counter.add`.\n\nSo if a page needs \"the 10 newest entries\" or \"the leaderboard\", you cannot read\nthat directly in the `@get`. Instead a `@derive` builds it once into a `View`,\nand the `@get` reads the view by key, which is not a scan.\n\n## Declaring a derive\n\nA derive is a method on your `@database` class, alongside the collections it\nreads and the `View` it writes:\n\n```ts\n@database\nclass MyDb {\n  @collection static events: Events<Key, Fact>;   // a source\n  @collection static home: View<Key, HomePage>;    // the materialized view\n\n  @derive\n  rebuild(): void {\n    // read sources, build the value, publish it\n  }\n}\n```\n\nRules:\n\n- A `@derive` method takes **no arguments and returns `void`**.\n- A `@database` may declare **multiple** `@derive` methods; each is run\n  independently.\n- The view value (`HomePage` above) and the key are ordinary `@data` types, so\n  they round-trip through the codec like any other stored value.\n\n## `View<K, V>`\n\nA `View` is a published, read-optimized projection. Its API:\n\n```ts\nview.get(key)       // V | null   - the published view, or null if none yet\nview.require(key)   // V          - like get, but traps if nothing is published\nview.publish(key, value) // void  - overwrite the view (derive/job only)\n```\n\n`publish` is only allowed from a `@derive` (or a `@job`); the host assigns the\nversion so a later publish always supersedes an earlier one. `get`/`require` are\nplain keyed reads, allowed from any handler, including a `@get` route.\n\n## When derives run\n\nYou never call a derive yourself. The runtime runs it for you:\n\n- **After a write to a source.** When a request writes one of a database's\n  source collections (an `events.append`/`append_once`, a `counter.add`, or a\n  record `create`/`patch`), that database's derives run right after the response\n  is produced, so the view reflects the new data on the next read. Many writes to\n  one database in a single request coalesce into one recompute.\n- **On box load.** When a server box starts or hot-reloads (or the underlying\n  source data changed out of band), the views are rebuilt from their sources\n  before the first read is served. This is also where a value type's `@migrate`\n  runs against old stored events, as the derive re-reads and republishes them.\n\nA derive's own writes (its `view.publish`) never re-trigger it.\n\nThe same code runs under `toiljs dev` (the in-process emulator) and on the\nproduction edge, no flags or wiring to change.\n\n## Reading a view from a route\n\nThe route just reads the view by key, which is a non-scan read and so is legal in\na `@get`:\n\n```ts\n@rest('guestbook')\nclass Guestbook {\n  @get('/')\n  list(): GuestbookView {\n    const key = new GuestKey('main');\n    const view = GuestbookDb.book.get(key);\n    return view == null ? new GuestbookView() : view; // empty until first publish\n  }\n\n  @post('/')\n  sign(input: NewMessage): GuestbookView {\n    const key = new GuestKey('main');\n    GuestbookDb.entries.append(key, new GuestEntry(input.author, input.message, 0));\n    GuestbookDb.totals.add(key, 1);\n    // The @derive republishes `book` right after this action returns, so the\n    // entries list is served by GET. The action just acks with the new total\n    // (a counter read is allowed here; a scan is not).\n    const view = new GuestbookView();\n    view.total = GuestbookDb.totals.get(key);\n    return view;\n  }\n}\n```\n\n## How it fits together (the guestbook)\n\nThe `examples/basic` guestbook is the end-to-end demo:\n\n1. `POST /guestbook` (an action) appends the signature to an `Events` stream and\n   bumps a `Counter`. It returns the running total, but it does **not** read the\n   entry list (that would be a scan).\n2. The runtime then runs `@derive recompute()` under the derive kind: it scans\n   `entries.latest(...)`, reads the `totals` counter, and `publish`es a fresh\n   `GuestbookView`.\n3. `GET /guestbook` (a query) reads `book.get(...)`, a single keyed read, and\n   returns the precomputed total + newest entries.\n\nSign twice and the total climbs across requests, because the data lives in\nToilDB (and its view), not in module memory.\n\n## Notes\n\n- A derive **recomputes** the view from whatever its method reads (here, the\n  latest 10 events). It is a fresh recompute on each trigger, so it suits views\n  built from a bounded read (latest N, a counter total, a small set). Folding an\n  unbounded full event log incrementally is a separate, more advanced pattern.\n- Because publishes are last-writer-wins and a derive recomputes from the source\n  of truth, a view always converges to a correct snapshot of its sources.\n- See also: [`data.md`](data.md) for `@data` value types, and the ToilDB host\n  ABI for the exact `derive_run` / `toildb.derives` contract.\n",
 };

package/src/devserver/daemon/runtime.ts

@@ -0,0 +1,48 @@
+import pc from 'picocolors';
+
+import { DaemonHost, daemonEmulationEnabled } from './index.js';
+import type { ResolvedDaemonConfig } from './host.js';
+
+export interface DaemonRuntimeOptions {
+    readonly coldWasmFile?: string;
+    readonly nodeMode?: string;
+    readonly daemon?: ResolvedDaemonConfig;
+    readonly pollMs?: number;
+}
+
+export interface RunningDaemonRuntime {
+    readonly host: DaemonHost;
+    close(): void;
+}
+
+/** Starts the shared cold-artifact daemon runtime used by both `dev` and `start`. */
+export function startDaemonRuntime(options: DaemonRuntimeOptions): RunningDaemonRuntime | null {
+    const nodeMode = options.nodeMode ?? 'all';
+    if (
+        options.coldWasmFile === undefined ||
+        !daemonEmulationEnabled(nodeMode) ||
+        options.daemon === undefined
+    ) {
+        return null;
+    }
+
+    const host = new DaemonHost(options.coldWasmFile, options.daemon, nodeMode);
+    const pollDaemon = (): void => {
+        try {
+            host.refresh();
+        } catch (e) {
+            process.stdout.write(pc.red(`  x daemon reload failed: ${String(e)}`) + '\n');
+        }
+    };
+    pollDaemon();
+    const timer = setInterval(pollDaemon, options.pollMs ?? 500);
+    timer.unref?.();
+
+    return {
+        host,
+        close: (): void => {
+            clearInterval(timer);
+            host.close();
+        },
+    };
+}

package/src/devserver/db/database.ts

@@ -700,6 +700,7 @@ export class DevDatabase {
         if (outcome.kind === 'unit') {
             this.store.set(sk, value);
             this.stampVersion(coll, sk); // stamp the value type's current schema version
+            this.recordWrite(db, coll);
         }
         this.recordIdemFinish(coll, key, 'C', idem, requestHash, outcome);
         return this.replayRecordOutcome(db, outcome);
@@ -732,6 +733,7 @@ export class DevDatabase {
         if (outcome.kind === 'value') {
             this.store.set(sk, v);
             this.stampVersion(coll, sk); // a patch rewrites the row at the current version
+            this.recordWrite(db, coll);
         }
         this.recordIdemFinish(coll, key, 'P', idem, requestHash, outcome);
         return this.replayRecordOutcome(db, outcome);
@@ -1023,6 +1025,15 @@ export class DevDatabase {
 
     // `delta` is the wasm i64 (a BigInt across the boundary); `BigInt()`
     // normalizes the test's plain-number form too. Saturates like the edge.
+    /** Note a successful write to a SOURCE collection, so the runtime can re-run
+     *  the `@derive` materializers that depend on it after this dispatch. A
+     *  derive's OWN writes run under FunctionKind=Derive and must never
+     *  re-trigger a derive (which would loop), so they are never recorded. */
+    private recordWrite(db: DbDevState, coll: DevCollectionHandle): void {
+        if (db.functionKind === DbFunctionKind.Derive) return;
+        db.writtenCollections.add(coll.name);
+    }
+
     counterAdd(
         ref: MemoryRef,
         db: DbDevState,
@@ -1045,6 +1056,7 @@ export class DevDatabase {
         }
         const sk = storeKey(coll.name, key);
         this.counters.set(sk, satI64((this.counters.get(sk) ?? 0n) + d));
+        this.recordWrite(db, coll);
         return 0;
     }
 
@@ -1086,6 +1098,7 @@ export class DevDatabase {
             log.push(ev);
             (this.eventVersions.get(sk) ?? this.eventVersions.set(sk, []).get(sk)!).push(sv);
         }
+        this.recordWrite(db, coll);
         return 0;
     }
 
@@ -1124,6 +1137,7 @@ export class DevDatabase {
             (this.eventVersions.get(sk) ?? this.eventVersions.set(sk, []).get(sk)!).push(sv);
         }
         seen.add(evid);
+        this.recordWrite(db, coll);
         return 1;
     }
 

package/src/devserver/db/derives.ts

@@ -0,0 +1,121 @@
+import { customSection } from '../wasm/sections.js';
+
+/**
+ * Parses the `toildb.derives` wiring section emitted by toilscript for a
+ * `@database` class with `@derive` materializer methods (see the compiler's
+ * `buildToilDbDerives`). It maps each derive to its owning `@database` class, so
+ * the dev runtime (`runtime/module.ts`) can, after a dispatch writes a source
+ * collection, re-run that database's derives under FunctionKind=Derive. Fails
+ * closed: any malformed byte yields `[]` (no derive runs) rather than throwing.
+ *
+ * Section layout (LE), mirroring `buildToilDbDerives`:
+ *   u16 format_version = 1
+ *   u16 n_derives
+ *   per derive: u16 derive_id, str db_name, str method_name   (str = u32 len + bytes)
+ */
+export interface DeriveEntry {
+    readonly deriveId: number;
+    readonly dbName: string;
+    readonly methodName: string;
+}
+
+const SECTION = 'toildb.derives';
+const VERSION = 1;
+const MAX_SECTION_BYTES = 128 * 1024;
+const MAX_DERIVES = 1024;
+const MAX_NAME_BYTES = 1024;
+const UTF8_DECODER = new TextDecoder('utf-8', { fatal: true });
+
+export function parseDerives(wasm: Buffer): readonly DeriveEntry[] {
+    let section: Buffer | null;
+    try {
+        section = customSection(wasm, SECTION);
+    } catch {
+        return [];
+    }
+    if (section === null) return [];
+    if (section.length > MAX_SECTION_BYTES) return [];
+
+    const r = new Reader(section);
+    const version = r.u16();
+    if (!r.ok || version !== VERSION) return [];
+    const count = r.u16();
+    if (!r.ok || count > MAX_DERIVES) return [];
+
+    const derives: DeriveEntry[] = [];
+    for (let i = 0; i < count && r.ok; i++) {
+        const deriveId = r.u16();
+        const dbName = r.string();
+        const methodName = r.string();
+        if (!r.ok || dbName.length === 0) return [];
+        derives.push({ deriveId, dbName, methodName });
+    }
+    if (!r.ok || r.remaining() !== 0) return [];
+    return derives;
+}
+
+/**
+ * The derives whose owning `@database` had at least one source collection
+ * written during this dispatch. `written` holds "Db/coll" store keys; the
+ * database is the prefix before the first `/`. Each affected derive appears at
+ * most once (coalescing: many writes to one database run its derives once).
+ */
+export function derivesForWrites(
+    derives: readonly DeriveEntry[],
+    written: ReadonlySet<string>,
+): readonly DeriveEntry[] {
+    if (derives.length === 0 || written.size === 0) return [];
+    const dbs = new Set<string>();
+    for (const key of written) {
+        const slash = key.indexOf('/');
+        dbs.add(slash >= 0 ? key.slice(0, slash) : key);
+    }
+    return derives.filter((d) => dbs.has(d.dbName));
+}
+
+class Reader {
+    private pos = 0;
+    ok = true;
+
+    constructor(private readonly bytes: Buffer) {}
+
+    remaining(): number {
+        return this.bytes.length - this.pos;
+    }
+
+    u16(): number {
+        if (!this.ok || this.pos + 2 > this.bytes.length) {
+            this.ok = false;
+            return 0;
+        }
+        const out = this.bytes.readUInt16LE(this.pos);
+        this.pos += 2;
+        return out;
+    }
+
+    u32(): number {
+        if (!this.ok || this.pos + 4 > this.bytes.length) {
+            this.ok = false;
+            return 0;
+        }
+        const out = this.bytes.readUInt32LE(this.pos);
+        this.pos += 4;
+        return out;
+    }
+
+    string(): string {
+        const len = this.u32();
+        if (!this.ok || len > MAX_NAME_BYTES || this.pos + len > this.bytes.length) {
+            this.ok = false;
+            return '';
+        }
+        try {
+            const out = UTF8_DECODER.decode(this.bytes.subarray(this.pos, this.pos + len));
+            this.pos += len;
+            return out;
+        } catch {
+            this.ok = false;
+            return '';
+        }
+    }
+}

package/src/devserver/db/index.ts

@@ -15,4 +15,5 @@ export {
     setDbCatalog,
 } from './database.js';
 export { parseCatalog } from './catalog.js';
+export { type DeriveEntry, derivesForWrites, parseDerives } from './derives.js';
 export { CollectionFamily, DbFunctionKind, type DbDevState, freshDbState } from './types.js';

package/src/devserver/db/types.ts

@@ -50,6 +50,11 @@ export interface DbDevState {
     lastResult: Buffer | null;
     lastResultVersion: number;
     functionKind: DbFunctionKind;
+    /** Names ("Db/coll") of source collections written during this dispatch, so
+     *  the runtime can re-run the affected `@derive` materializers afterward.
+     *  Only populated for non-Derive dispatches (a derive's own writes must not
+     *  re-trigger it - see `database.ts` `recordWrite`). */
+    writtenCollections: Set<string>;
 }
 
 export function freshDbState(): DbDevState {
@@ -58,6 +63,7 @@ export function freshDbState(): DbDevState {
         lastResult: null,
         lastResultVersion: -1,
         functionKind: DbFunctionKind.Job,
+        writtenCollections: new Set<string>(),
     };
 }