toiljs 0.0.68 → 0.0.70

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

@@ -5,7 +5,7 @@
 
 /** 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",
+    "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",
@@ -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\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\nDistributed stream channels are not part of the live v1 ABI. The edge rejects\nstream artifacts that declare a channel hook until the channel fan-out runtime\nexists.\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",
@@ -26,4 +26,5 @@ export const TOIL_DOCS: Record<string, string> = {
     "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 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/compiler/vite.ts

@@ -51,6 +51,10 @@ const FONT_EXT = /^(woff|woff2|eot|ttf|otf)$/i;
  */
 function sharedResolverPlugin(cfg: ResolvedToilConfig): PluginOption {
     const sharedDir = path.join(cfg.root, 'shared');
+    const serverModule = path.join(sharedDir, 'server.ts');
+    // Posix-normalized: Vite hands `transform` forward-slash module ids while path.join is OS-native, so a
+    // raw `===` would silently never match on Windows (the surface would regress to "client not loaded").
+    const routesModule = path.join(cfg.toilDir, 'routes.ts').replace(/\\/g, '/');
     return {
         name: 'toiljs:shared-resolver',
         enforce: 'pre',
@@ -70,6 +74,18 @@ function sharedResolverPlugin(cfg: ResolvedToilConfig): PluginOption {
             }
             return null;
         },
+        transform(code: string, id: string) {
+            // Guarantee the generated client surface (shared/server.ts: __toilRest/__toilRpc/__toilStream
+            // + globalThis.Server) is EVALUATED. Otherwise it is dead unless some route happens to
+            // value-import a @data type - a type-only import is erased and never attaches, so
+            // `Server.<rpc>()` / `Server.REST` / `Server.Stream` would throw "client not loaded". Inject a
+            // side-effect import from the always-loaded route manifest; idempotent and a no-op for a
+            // client-only project (no shared/server.ts).
+            if ((id.split('?')[0] ?? id).replace(/\\/g, '/') === routesModule && fs.existsSync(serverModule)) {
+                return { code: `import 'shared/server';\n${code}`, map: null };
+            }
+            return null;
+        },
     };
 }
 

package/src/devserver/daemon/host.ts

@@ -1,13 +1,12 @@
 /**
  * Host-import surface for the dev daemon (cold) box, mirroring the production
- * edge's `daemon.*` + `mstore.*` imports. DAEMON path only (streams are Phase 4).
+ * edge's `daemon.*` imports. DAEMON path only (streams are Phase 4).
  *
  * Per RECONCILIATION:
  *   - Part 4 `daemon.*`: is_leader / current_epoch / yield / sleep_ms / task_count
- *     / next_fire_ms / http_call / remote_call. In a single dev process the leader
+ *     / next_fire_ms / http_call. In a single dev process the leader
  *     stub is always true and the lease never expires (section 5.2). Fenced DB
  *     writes are TRANSPARENT (no `daemon.db_write_fenced` import).
- *   - Part 4 `mstore.*`: handleless, ttl_secs, inline drain (section 7.4).
  *   - Part 3 error bridge: a u16 subsystem code `c` is returned as `-(0x10000 + c)`;
  *     the buffer sentinels `-1` (TOO_SMALL) / `-2` (ABSENT) are unchanged.
  *
@@ -19,14 +18,8 @@
  */
 
 import { buildDatabaseImports, type DbDevState, freshDbState } from '../db/index.js';
-import { type DevMemoryStore } from '../mstore/store.js';
 import { buildCryptoImports, type CryptoState, freshCryptoState } from '../runtime/crypto.js';
-import {
-    buildEnvImports,
-    type MemoryRef,
-    readBytes,
-    writeBytesOut,
-} from '../runtime/host.js';
+import { buildEnvImports, type MemoryRef } from '../runtime/host.js';
 
 /**
  * Resolved daemon (L4) config the dev scheduler reads. Structurally identical to
@@ -43,12 +36,8 @@ export interface ResolvedDaemonConfig {
     readonly maxTasks: number;
 }
 
-/** RECONCILIATION Part 3 u16 error registry (the subset the daemon/mstore use). */
+/** RECONCILIATION Part 3 u16 error registry (the subset the daemon imports use). */
 export const enum AbiError {
-    MstoreNotFound = 0x0301,
-    MstoreNotANumber = 0x0306,
-    MstoreScanBusy = 0x0307,
-    MstoreConflict = 0x0304,
     DaemonScheduleRejected = 0x0403,
     DaemonCallFailed = 0x0405,
 }
@@ -75,88 +64,6 @@ export interface DaemonRuntime {
  *  `number | bigint` individually, matching the existing db/crypto import maps). */
 type HostFnMap = Record<string, (...args: number[]) => number | bigint>;
 
-/** Build the `mstore.*` host imports, backed by `store`. Handleless; keys are read
- *  from guest memory and auto-scoped to the single dev host/region. */
-export function buildMstoreImports(ref: MemoryRef, store: DevMemoryStore): HostFnMap {
-    const key = (p: number, l: number): string => readBytes(ref, p, l).toString('utf8');
-    return {
-        'mstore.get': (keyPtr: number, keyLen: number, outPtr: number, outCap: number): number => {
-            const v = store.get(key(keyPtr, keyLen));
-            if (v === null) return encodeAbiError(AbiError.MstoreNotFound);
-            return writeBytesOut(ref, v, outPtr, outCap);
-        },
-        'mstore.set': (
-            keyPtr: number,
-            keyLen: number,
-            valPtr: number,
-            valLen: number,
-            ttlSecs: number,
-        ): number => {
-            store.set(key(keyPtr, keyLen), readBytes(ref, valPtr, valLen), ttlSecs);
-            return 0;
-        },
-        'mstore.delete': (keyPtr: number, keyLen: number): number =>
-            store.delete(key(keyPtr, keyLen)) ? 0 : encodeAbiError(AbiError.MstoreNotFound),
-        'mstore.incr': (
-            keyPtr: number,
-            keyLen: number,
-            delta: number | bigint,
-            ttlSecs: number,
-        ): bigint => {
-            const d = typeof delta === 'bigint' ? delta : BigInt(delta);
-            const next = store.incr(key(keyPtr, keyLen), d, ttlSecs);
-            return next === null ? BigInt(encodeAbiError(AbiError.MstoreNotANumber)) : next;
-        },
-        'mstore.cas': (
-            keyPtr: number,
-            keyLen: number,
-            expectPtr: number,
-            expectLen: number,
-            newPtr: number,
-            newLen: number,
-            ttlSecs: number,
-        ): number => {
-            const expect = expectLen === 0 ? null : readBytes(ref, expectPtr, expectLen);
-            const ok = store.cas(
-                key(keyPtr, keyLen),
-                expect,
-                readBytes(ref, newPtr, newLen),
-                ttlSecs,
-            );
-            return ok ? 0 : encodeAbiError(AbiError.MstoreConflict);
-        },
-        'mstore.expire': (keyPtr: number, keyLen: number, ttlSecs: number): number =>
-            store.expire(key(keyPtr, keyLen), ttlSecs)
-                ? 0
-                : encodeAbiError(AbiError.MstoreNotFound),
-        'mstore.scan': (
-            prefixPtr: number,
-            prefixLen: number,
-            cursor: number | bigint,
-            outPtr: number,
-            outCap: number,
-        ): bigint => {
-            const cur = typeof cursor === 'bigint' ? cursor : BigInt(cursor);
-            const res = store.scan(key(prefixPtr, prefixLen), cur);
-            if (res === null) return BigInt(encodeAbiError(AbiError.MstoreScanBusy));
-            // Frame: u32 count, then per key (u32 len + bytes).
-            let total = 4;
-            for (const k of res.keys) total += 4 + Buffer.byteLength(k, 'utf8');
-            const frame = Buffer.alloc(total);
-            let o = frame.writeUInt32LE(res.keys.length, 0);
-            for (const k of res.keys) {
-                const kb = Buffer.from(k, 'utf8');
-                o = frame.writeUInt32LE(kb.length, o);
-                kb.copy(frame, o);
-                o += kb.length;
-            }
-            const len = writeBytesOut(ref, frame, outPtr, outCap);
-            if (len < 0) return BigInt(len); // TOO_SMALL sentinel
-            return (res.next << 32n) | BigInt(len);
-        },
-    };
-}
-
 /** Build the `daemon.*` host imports, closing over the resident `DaemonRuntime`.
  *  These imports do not read guest memory (they answer from the resident scheduler
  *  state), so they take no `MemoryRef`. */
@@ -170,9 +77,11 @@ export function buildDaemonNamespace(rt: DaemonRuntime): HostFnMap {
         'daemon.task_count': (): number => rt.taskCount(),
         'daemon.next_fire_ms': (taskId: number): bigint => {
             const at = rt.nextFireMs(taskId);
-            return at === null ? BigInt(encodeAbiError(AbiError.DaemonScheduleRejected)) : BigInt(at);
+            return at === null
+                ? BigInt(encodeAbiError(AbiError.DaemonScheduleRejected))
+                : BigInt(at);
         },
-        // Outbound call stubs: dev returns a "call failed" sentinel rather than
+        // Outbound HTTP call stub: dev returns a "call failed" sentinel rather than
         // performing real network I/O from a synchronous wasm import (section 5.4).
         'daemon.http_call': (
             _reqPtr: number,
@@ -180,13 +89,6 @@ export function buildDaemonNamespace(rt: DaemonRuntime): HostFnMap {
             _outPtr: number,
             _outCap: number,
         ): bigint => BigInt(encodeAbiError(AbiError.DaemonCallFailed)),
-        'daemon.remote_call': (
-            _svcId: number,
-            _reqPtr: number,
-            _reqLen: number,
-            _outPtr: number,
-            _outCap: number,
-        ): bigint => BigInt(encodeAbiError(AbiError.DaemonCallFailed)),
     };
 }
 
@@ -203,14 +105,13 @@ export function freshDaemonState(): DaemonState {
 /**
  * The full `env` import object for the cold daemon box: the request-surface env
  * MINUS the response/stream functions (built by `buildEnvImports`), PLUS the
- * `daemon.*` and `mstore.*` namespaces. The cold box has no `handle` entry and no
- * response surface.
+ * `daemon.*` namespace. The cold box has no `handle` entry and no response
+ * surface.
  */
 export function buildDaemonImports(
     ref: MemoryRef,
     state: DaemonState,
     rt: DaemonRuntime,
-    store: DevMemoryStore,
 ): WebAssembly.Imports {
     return {
         env: {
@@ -218,7 +119,6 @@ export function buildDaemonImports(
             ...buildCryptoImports(ref, state.crypto),
             ...buildDatabaseImports(ref, state.db),
             ...buildDaemonNamespace(rt),
-            ...buildMstoreImports(ref, store),
         },
     };
 }

package/src/devserver/daemon/index.ts

@@ -22,7 +22,6 @@ import fs from 'node:fs';
 import pc from 'picocolors';
 
 import { type MemoryRef } from '../runtime/host.js';
-import { devMemoryStore } from '../mstore/store.js';
 import { parseSurface } from '../wasm/surface.js';
 import {
     type CronMasks,
@@ -100,6 +99,14 @@ export class DaemonHost implements DaemonRuntime {
         return this.catalog?.tasks ?? [];
     }
 
+    /** Test/dev introspection for fixtures that export scalar counters. */
+    callI32Export(name: string): number | null {
+        const fn = (this.exports as unknown as Record<string, unknown> | null)?.[name];
+        if (typeof fn !== 'function') return null;
+        const value = (fn as () => number)();
+        return Number.isFinite(value) ? value : null;
+    }
+
     // --- DaemonRuntime (the daemon.* host imports read these) ---
     isLeader(): boolean {
         return true; // single dev process is always the leader
@@ -146,14 +153,20 @@ export class DaemonHost implements DaemonRuntime {
             this.loadedMtimeMs = mtimeMs;
             return false;
         }
-        if (surface.targetMode !== 'cold')
+        if (surface.targetMode !== 'cold') {
             this.log(
                 pc.yellow('  ! ') +
                     pc.dim('cold slot holds a hot-mode artifact; ignoring daemon emulator') +
                     '\n',
             );
+            if (this.running) this.stop();
+            this.module = null;
+            this.catalog = null;
+            this.loadedMtimeMs = mtimeMs;
+            return false;
+        }
         const catalog = parseDaemonCatalog(bytes);
-        const declaresDaemon = surface.flags.daemon || (catalog?.hasDaemon ?? false);
+        const declaresDaemon = surface.flags.daemon && (catalog?.hasDaemon ?? false);
 
         // A restart: stop the old box (timers + instance), bump epoch, start fresh.
         if (this.running) this.stop();
@@ -179,11 +192,11 @@ export class DaemonHost implements DaemonRuntime {
         if (this.module === null || this.catalog === null) return;
         const ref: MemoryRef = { memory: null };
         this.state = freshDaemonState();
-        const imports = buildDaemonImports(ref, this.state, this, devMemoryStore);
+        const imports = buildDaemonImports(ref, this.state, this);
 
         // Fail-closed up front, with names, when the cold box imports anything outside its allowed
-        // surface (the request env subset + crypto + @data + daemon.* + mstore.*; NO response/
-        // stream functions). Mirrors `WasmServerModule.assertImportSurface` (section 7.1).
+        // surface (the request env subset + crypto + @data + daemon.*; NO response/stream
+        // functions). Mirrors `WasmServerModule.assertImportSurface` (section 7.1).
         const provided = new Set(Object.keys((imports as { env: Record<string, unknown> }).env));
         const missing = WebAssembly.Module.imports(this.module)
             .filter((i) => i.kind === 'function' && (i.module !== 'env' || !provided.has(i.name)))

package/src/devserver/db/database.ts

@@ -728,7 +728,7 @@ export class DevDatabase {
             return start.outcome ? this.replayRecordOutcome(db, start.outcome) : start.status;
         const sk = storeKey(coll.name, key);
         const outcome: RecordOutcome = this.store.has(sk)
-            ? { kind: 'value', value: v, schemaVersion: -1 }
+            ? { kind: 'value', value: v, schemaVersion: this.currentSchemaVersion(coll) }
             : { kind: 'not_found' };
         if (outcome.kind === 'value') {
             this.store.set(sk, v);

package/src/devserver/db/routeKinds.ts

@@ -7,7 +7,13 @@ export interface RouteKindEntry {
     readonly pattern: string;
 }
 
+export interface RpcKindEntry {
+    readonly methodId: number;
+    readonly kind: DbFunctionKind;
+}
+
 const SECTION = 'toildb.route_kinds';
+const RPC_SECTION = 'toildb.rpc_kinds';
 const VERSION = 1;
 const MAX_SECTION_BYTES = 128 * 1024;
 const MAX_ROUTES = 2048;
@@ -67,6 +73,44 @@ export function routeKindForRequest(
     return null;
 }
 
+export function parseRpcKinds(wasm: Buffer): readonly RpcKindEntry[] {
+    let section: Buffer | null;
+    try {
+        section = customSection(wasm, RPC_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_ROUTES) return [];
+
+    const methods: RpcKindEntry[] = [];
+    for (let i = 0; i < count && r.ok; i++) {
+        const methodId = r.u32();
+        const kindByte = r.u8();
+        const kind =
+            kindByte === 0 ? DbFunctionKind.Query : kindByte === 1 ? DbFunctionKind.Action : null;
+        if (!r.ok || kind === null) return [];
+        methods.push({ methodId, kind });
+    }
+    if (!r.ok || r.remaining() !== 0) return [];
+    return methods;
+}
+
+/** DB kind for an RPC method id (the `toil-rpc` header). An id absent from rpc_kinds is read-only
+ *  (Query) - the safe default for RPC, matching the host gate. */
+export function rpcKindForId(methods: readonly RpcKindEntry[], methodId: number): DbFunctionKind {
+    for (const m of methods) {
+        if (m.methodId === methodId) return m.kind;
+    }
+    return DbFunctionKind.Query;
+}
+
 function validPattern(pattern: string): boolean {
     if (pattern.length === 0 || !pattern.startsWith('/')) return false;
     for (let i = 0; i < pattern.length; i++) {

package/src/devserver/index.ts

@@ -41,4 +41,3 @@ export { cronMatches, cronNeverFires, nextCronFireMs } from './daemon/cron.js';
 export { parseSurface } from './wasm/surface.js';
 export type { Surface, SurfaceFlags } from './wasm/surface.js';
 export { customSection } from './wasm/sections.js';
-export { DevMemoryStore, devMemoryStore } from './mstore/store.js';