toiljs 0.0.34 → 0.0.37

package/docs/data.md

@@ -0,0 +1,131 @@
+# Data codec (`@data`)
+
+`@data` turns a plain class into a typed, versionable value with a deterministic
+binary codec and a JSON codec. It is the backbone of request/response bodies,
+RPC arguments, sessions, and anything you persist. The same class becomes a
+fully typed client type in the generated `shared/server.ts` (see
+[RPC](./rpc.md)).
+
+```ts
+@data
+class Player {
+  username: string = '';
+  admin: bool = false;
+  score: u64 = 0;
+}
+```
+
+From that the compiler synthesizes, on the class:
+
+- `encode(): Uint8Array` / `static decode(buf): T` — the binary codec (with a
+  4-byte type id prefix).
+- `encodeInto(w: DataWriter)` / `static decodeFrom(r: DataReader)` — the codec
+  without the type-id frame, for nesting.
+- `toJSON()` / `static fromJSON(v)` — the JSON codec (64-bit-and-larger integers
+  as decimal strings, so they survive `JSON.parse` exactly).
+- `static dataId(): u32` — a stable FNV-1a hash of the class name, written as the
+  type-id prefix by `encode()`.
+
+Fields may be scalars (`u8`..`u256`, `i8`..`i256`, `f32`, `f64`, `bool`),
+`string`, a nested `@data` class, or an array `T[]` of any of these. Give every
+field a default; the generated decoder and the client constructor use them.
+
+## Using `@data` in routes
+
+In a **JSON** route, a `@data` parameter is revived from the parsed body and a
+`@data` return value is serialized with `toJSON()`. In a **Binary** route, the
+parameter is `decode`d from the raw body and the return value is `encode`d. The
+route's stream mode (see [Routing](./routing.md#data-streams)) picks which.
+
+```ts
+@post('/')                       // JSON route
+public create(input: NewPlayer): Player { /* input from JSON, Player to JSON */ }
+
+@route({ method: Methods.POST, path: '/blob', stream: DataStream.Binary })
+public blob(input: FileData): FileResult { /* input.decode, result.encode */ }
+```
+
+## The binary codec: `DataWriter` / `DataReader`
+
+When you need to lay out bytes yourself — custom bodies, session payloads,
+challenge messages — use the codec directly. It lives in the `data` module:
+
+```ts
+import { DataWriter, DataReader } from 'data';
+```
+
+The codec has a byte-for-byte identical TypeScript implementation in
+`toiljs/io` (`src/io/codec.ts`), so the client can read and write the exact same
+wire format the wasm guest does.
+
+### `DataWriter`
+
+Every writer method returns the writer for chaining.
+
+| Method | Signature | Wire format |
+| --- | --- | --- |
+| `writeU8` / `writeI8` | `(v): DataWriter` | 1 byte |
+| `writeU16` / `writeI16` | `(v): DataWriter` | 2 bytes, little-endian |
+| `writeU32` / `writeI32` | `(v): DataWriter` | 4 bytes, LE |
+| `writeU64` / `writeI64` | `(v): DataWriter` | 8 bytes, LE |
+| `writeF32` / `writeF64` | `(v): DataWriter` | 4 / 8 bytes, IEEE-754 LE |
+| `writeBool` | `(v): DataWriter` | 1 byte (`1`/`0`) |
+| `writeBytes` | `(b: Uint8Array): DataWriter` | `u32` length (LE) + raw bytes |
+| `writeString` | `(s: string): DataWriter` | `u32` length (LE) + UTF-8 bytes |
+| `writeU128` / `writeI128` | `(v): DataWriter` | two `u64` limbs (lo, hi) |
+| `writeU256` / `writeI256` | `(v): DataWriter` | four `u64` limbs (lo1, lo2, hi1, hi2) |
+| `length` | `(): i32` | bytes written so far |
+| `toBytes` | `(): Uint8Array` | an exact-length copy of the buffer |
+
+### `DataReader`
+
+Reads are bounds-safe: an over-read never traps. It returns a zero/empty default
+and sets the public `ok` flag to `false`. Check `ok` after a sequence of reads
+to detect a truncated or malformed buffer.
+
+| Method | Signature | On over-read |
+| --- | --- | --- |
+| `readU8` / `readI8` | `(): u8 / i8` | `0` |
+| `readU16`..`readU64`, `readI16`..`readI64` | `(): integer` | `0` |
+| `readF32` / `readF64` | `(): f32 / f64` | `0` |
+| `readBool` | `(): bool` | `false` |
+| `readBytes` | `(): Uint8Array` | empty array |
+| `readString` | `(): string` | `""` |
+| `readU128`/`readI128`/`readU256`/`readI256` | `(): bignum` | `0` |
+| `remaining` | `(): i32` | bytes left unread |
+| `ok` | `bool` (field) | `false` once any read over-ran |
+
+### Example
+
+```ts
+import { DataWriter, DataReader } from 'data';
+
+// Write: u8 version, str name, u64 score, bytes blob
+const out = new DataWriter()
+  .writeU8(1)
+  .writeString('alice')
+  .writeU64(1234)
+  .writeBytes(payload)
+  .toBytes();
+
+// Read it back
+const r = new DataReader(out);
+const version = r.readU8();
+const name = r.readString();
+const score = r.readU64();
+const blob = r.readBytes();
+if (!r.ok) return Response.badRequest('truncated');
+```
+
+## Notes
+
+- **Endianness.** The AS guest codec is little-endian. The TypeScript `toiljs/io`
+  codec defaults to little-endian and also accepts a per-call `be` flag for
+  big-endian network formats; keep both ends on the same setting.
+- **Field order is the format.** The binary layout is exactly the field
+  declaration order. Reordering fields, or changing a type, is a breaking format
+  change. Add new fields at the end and bump a leading version byte if you need
+  to evolve a hand-rolled payload.
+- **`encode()` carries a type id.** The 4-byte `dataId()` prefix lets a decoder
+  confirm it is reading the type it expects. `encodeInto`/`decodeFrom` skip the
+  frame for nesting one `@data` value inside another.

package/docs/getting-started.md

@@ -0,0 +1,128 @@
+# Getting started
+
+A toiljs app has two halves that build and ship together:
+
+- a **server** written in ToilScript, compiled to a single WebAssembly module
+  (`build/server/release.wasm`), and
+- a **client** (Vite + React) that talks to the server through a generated,
+  fully typed `Server` proxy.
+
+The server runs one fresh wasm instance per request, identically on the dev
+server and on the edge. There is no Node.js in the request path: your handler is
+wasm.
+
+## Project layout
+
+```
+project/
+  toilconfig.json          server (wasm) build config: entries, target, AS options
+  toil.config.ts           client config (defineConfig: dev/build/SEO options)
+
+  server/
+    main.ts                wires Server.handler, re-exports the wasm exports + abort
+    routes/*.ts            @rest controllers           (auto-discovered)
+    services/*.ts          @service / @remote          (auto-discovered)
+    core/AppHandler.ts     your top-level ToilHandler
+    models/*.ts            @data / @user classes
+
+  shared/
+    server.ts              GENERATED by the server build (--rpcModule): the typed
+                           client surface (Server proxy, @data codecs, getUser)
+
+  client/
+    routes/*.tsx           file-based pages
+    layout.tsx, 404.tsx    root layout / not-found
+    styles/*.css
+
+  build/
+    server/release.wasm    compiled server (+ release.wat text form)
+    client/                Vite output
+```
+
+The compiler discovers every `.ts` under `server/` that declares a decorated
+surface (`@rest`, `@service`, `@remote`, `@data`, `@user`) on its own. Importing
+those modules from `main.ts` is still good practice: it keeps a direct
+`toilscript` run (which only sees the `toilconfig.json` entries) building the
+exact same server.
+
+## `main.ts`
+
+Three things are required, and the comments in the scaffold say so:
+
+```ts
+import { Server } from 'toiljs/server/runtime';
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+
+import { AppHandler } from './core/AppHandler';
+
+// Pull every decorated surface into a direct `toilscript` build.
+import './routes/Players';
+import './services/Stats';
+
+// 1. The handler factory: one fresh handler instance per request.
+Server.handler = () => new AppHandler();
+
+// 2. Re-export the wasm entrypoints (`handle`, `render`).
+export * from 'toiljs/server/runtime/exports';
+
+// 3. The AssemblyScript trap hook.
+export function abort(message: string, fileName: string, line: u32, column: u32): void {
+    revertOnError(message, fileName, line, column);
+}
+```
+
+If all you need is `@rest` routing, your handler can be `RestHandler` (see
+[Routing](./routing.md)) and you do not have to write an `AppHandler` at all.
+
+## The request lifecycle
+
+For each request the runtime (`server/runtime/exports`):
+
+1. decodes the request envelope into a [`Request`](./routing.md#request),
+2. publishes it ambiently as `Server.currentRequest` (so `AuthService.getUser()`
+   and friends can read its cookies with no argument),
+3. builds the handler via `Server.handler()` and calls
+   `onRequestStarted` → `handle(req)` → `onRequestCompleted`,
+4. encodes the returned [`Response`](./routing.md#response) and clears the
+   ambient request.
+
+Because the instance is fresh and memory is wiped between requests, **nothing in
+module globals survives across requests.** Anything that must persist (accounts,
+sessions you do not put in a cookie, rate-limit counters) belongs in an external
+store reached through a host binding.
+
+## CLI
+
+The `toiljs` CLI drives both halves:
+
+| Command | What it does |
+| --- | --- |
+| `toiljs create [name]` | Scaffold a new app (templates, styling, options). |
+| `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`. |
+| `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). |
+| `toiljs start` | Self-host a built app. Flags: `--root`, `--port`, `--host`. |
+| `toiljs doctor` | Diagnose setup/deps (`--json`, `--fix`). |
+
+In dev, requests whose method matches a dispatchable verb go into the wasm
+first; if the guest reports "no route matched" (the `x-toil-unhandled` marker)
+the request falls through to Vite, so client routes and assets just work
+alongside your API.
+
+## Building the server by hand
+
+`toiljs build` runs toilscript for you, but you can invoke it directly (this is
+what the examples do):
+
+```sh
+toilscript --target release --rpcModule shared/server.ts
+```
+
+`--target release` reads `toilconfig.json` and emits the wasm at
+`targets.release.outFile`; `--rpcModule shared/server.ts` writes the generated
+typed client (see [RPC](./rpc.md)).
+
+## Next
+
+- [Routing](./routing.md) to expose HTTP endpoints.
+- [Data codec](./data.md) for request/response bodies.
+- [Auth](./auth.md) for login and sessions.

package/docs/routing.md

@@ -0,0 +1,259 @@
+# Routing
+
+toiljs routing is decorator-driven. You write a controller class, annotate it
+with `@rest` and its methods with verb decorators, and the ToilScript compiler
+generates the dispatcher. Routes can take a typed body, read path params and the
+raw request through a `RouteContext`, and return either a `Response` or a typed
+value that is auto-encoded.
+
+```ts
+import { Response, RouteContext } from 'toiljs/server/runtime';
+
+@rest('players')
+class Players {
+  @get('/:id')
+  public get(ctx: RouteContext): Response {
+    const id = ctx.param('id');
+    return Response.json(`{"id":"${id}"}`);
+  }
+
+  @post('/')
+  public create(input: NewPlayer): Player {
+    // `input` is the decoded request body; returning a @data value JSON-encodes it
+    return Player.from(input);
+  }
+}
+```
+
+## `@rest` controllers
+
+`@rest` marks a class as a route controller and mounts it at a prefix.
+
+```ts
+@rest('api')                              // mounted at /api
+@rest('/')               // or @rest('')  // mounted at the root
+@rest({ stream: DataStream.Binary })      // root mount, binary codec by default
+```
+
+- The string argument is the mount prefix. `"api"`, `"/api"`, and `"api/"` all
+  normalize to `/api`; `""` and `"/"` mean the root.
+- The object form sets class-wide defaults. `stream: DataStream.Binary` makes
+  every route in the class use the binary `@data` codec; the default is
+  `DataStream.JSON`. Individual routes override this with `@route`.
+
+The compiler injects, at module init, a registration that adds the controller to
+the global `Rest` registry. Controllers dispatch in the order their modules are
+loaded; routes within a controller try in declaration order, first match wins.
+
+## Verb decorators
+
+Each HTTP method has a decorator taking a single path string:
+
+```ts
+@get('/path')   @post('/path')   @put('/path')   @delete('/path')
+@patch('/path') @head('/path')   @options('/path')
+```
+
+The full path is the controller prefix joined with the route path
+(`prefix="/api"`, `@get("/todos/:id")` → `/api/todos/:id`).
+
+### `@route` (explicit form)
+
+`@route` is the general form; use it when you need to set the stream mode per
+route or prefer an object:
+
+```ts
+@route({ method: Methods.POST, path: '/upload', stream: DataStream.Binary })
+public upload(body: FileData): FileResult { /* ... */ }
+```
+
+`method` (from the `Methods` enum) and `path` are required; `stream` is
+optional and overrides the controller default.
+
+## Path parameters
+
+A `:name` segment captures that URL segment. Read it with `ctx.param("name")`:
+
+```ts
+@get('/todos/:id/items/:itemId')
+public getItem(ctx: RouteContext): Response {
+  const id = ctx.param('id');
+  const itemId = ctx.param('itemId');
+  return Response.json(`{"todo":"${id}","item":"${itemId}"}`);
+}
+```
+
+Matching is segment-exact: the request path must have the same number of
+segments, static segments must match literally, and `:param` segments capture
+the value. The query string is stripped before matching.
+
+## Method parameters
+
+A route method takes zero, one, or two parameters, classified by type:
+
+- a `RouteContext` parameter receives the match context (path params, query,
+  headers, raw body);
+- any other type is treated as the **request body**, decoded as a `@data` value.
+
+```ts
+@get('/status')
+public status(): StatusResponse { /* no body, no context */ }
+
+@get('/user/:id')
+public getUser(ctx: RouteContext): User { /* context only */ }
+
+@post('/create')
+public create(input: NewTodo): Todo { /* body only */ }
+
+@post('/user/:id/score')
+public addScore(input: ScoreDelta, ctx: RouteContext): Player {
+  const id = ctx.param('id'); /* body AND context */
+}
+```
+
+The body is decoded per the route's stream mode: in JSON mode from
+`JSON.parse(ctx.text())`, in Binary mode from `Body.decode(req.body)`. See
+[Data codec](./data.md).
+
+## Return types
+
+The compiler encodes the return value by its type:
+
+| Return type | Result |
+| --- | --- |
+| `Response` | Returned as-is. Full control over status, headers, body. |
+| `void` | `204 No Content`. |
+| a `@data` type, JSON stream | `Response.json(value.toJSON().toString())`. |
+| a `@data` type, Binary stream | `Response.bytes(value.encode())`. |
+
+Returning a `Response` lets you set status, headers, cookies, and caching
+directly; returning a typed value is the terse path when you just want the data
+serialized.
+
+## Data streams
+
+Each route is either **JSON** (default) or **Binary**:
+
+- **JSON** — the body is `JSON.parse`d and revived via the `@data` type's
+  `fromJSON`; the response is the type's `toJSON()`. 64-bit-and-larger integers
+  cross the wire as decimal strings (exact at any size). Best for endpoints a
+  browser or third party calls directly.
+- **Binary** — the body is `Body.decode(bytes)` and the response is
+  `value.encode()`, using the deterministic `DataWriter`/`DataReader` codec. No
+  precision loss, smaller, faster. Best for app-to-app and anything
+  security-sensitive.
+
+Set the mode on the controller (`@rest({ stream: DataStream.Binary })`) or per
+route (`@route({ ..., stream: DataStream.Binary })`).
+
+## Dispatch and the 404 fallback
+
+At runtime the global `Rest` registry tries each controller in order:
+
+```ts
+const hit = Rest.dispatch(req); // Response | null
+if (hit != null) return hit;    // first matching route's Response
+return Response.unhandled();    // no route matched
+```
+
+`RestHandler` is a ready-made handler that does exactly this, so a REST-only app
+needs no custom handler:
+
+```ts
+import { RestHandler } from 'toiljs/server/runtime';
+Server.handler = () => new RestHandler();
+```
+
+`Response.unhandled()` is a `404` carrying the `x-toil-unhandled` marker header.
+On the dev server and edge that marker means "no route matched here" and lets
+the request fall through to the next layer (Vite in dev, static/SSR on the
+edge). A deliberate `Response.notFound()` does **not** carry the marker and is
+sent to the client verbatim.
+
+---
+
+## `Request`
+
+The decoded incoming request (`server/runtime/request.ts`).
+
+### Fields
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `method` | `Method` | `GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`, `UNKNOWN`. |
+| `path` | `string` | Path including the query string. |
+| `headers` | `Array<Header>` | Ordered; a `Header` is `{ name, value }`. |
+| `body` | `Uint8Array` | Raw request body bytes. |
+
+### Methods
+
+| Method | Signature | Notes |
+| --- | --- | --- |
+| `header` | `header(name: string): string \| null` | Case-insensitive lookup, `null` if absent. |
+| `cookies` | `cookies(): CookieMap` | Parses the `Cookie` header (percent-decoded values); cached for the request. |
+| `cookie` | `cookie(name: string): string \| null` | A single cookie value, or `null`. |
+
+The `Method` enum and `Header` class are exported from
+`toiljs/server/runtime`.
+
+## `RouteContext`
+
+Passed to any route method that declares a `RouteContext` parameter
+(`server/runtime/rest/RouteContext.ts`).
+
+| Member | Signature | Notes |
+| --- | --- | --- |
+| `request` | `Request` | The raw incoming request. |
+| `param` | `param(name: string): string` | Captured path param; `""` if absent. |
+| `query` | `query(name: string): string` | Query-string value; `""` if absent. Not URL-decoded in v1. |
+| `header` | `header(name: string): string \| null` | Case-insensitive request header. |
+| `text` | `text(): string` | The request body decoded as UTF-8. |
+
+## `Response`
+
+The outgoing response builder (`server/runtime/response.ts`). Construct one with
+a static factory, then chain instance methods (each returns the same `Response`).
+
+### Constructor
+
+```ts
+new Response(status: u16, body: Uint8Array, headers: Array<Header> | null = null)
+```
+
+### Static factories
+
+| Factory | Signature | Status | Content-Type |
+| --- | --- | --- | --- |
+| `Response.text` | `text(body: string, status: u16 = 200)` | 200 | `text/plain; charset=utf-8` |
+| `Response.html` | `html(body: string, status: u16 = 200)` | 200 | `text/html; charset=utf-8` |
+| `Response.json` | `json(body: string, status: u16 = 200)` | 200 | `application/json; charset=utf-8` |
+| `Response.bytes` | `bytes(body: Uint8Array, status: u16 = 200)` | 200 | `application/octet-stream` |
+| `Response.empty` | `empty(status: u16)` | custom | (none) |
+| `Response.notFound` | `notFound()` | 404 | text |
+| `Response.badRequest` | `badRequest(msg = 'bad request')` | 400 | text |
+| `Response.internalError` | `internalError(msg = 'internal error')` | 500 | text |
+| `Response.unhandled` | `unhandled()` | 404 | text + `x-toil-unhandled` marker |
+
+`json` takes an already-serialized string; build it with `DataWriter`-free JSON
+or a `@data` type's `toJSON().toString()`. For binary, prefer `bytes`.
+
+### Instance methods
+
+| Method | Signature | Notes |
+| --- | --- | --- |
+| `setHeader` | `setHeader(name: string, value: string): Response` | Appends a header (repeatable). |
+| `setCookie` | `setCookie(cookie: Cookie): Response` | Appends a `Set-Cookie`. Call again for more. |
+| `setCookieKV` | `setCookieKV(name: string, value: string): Response` | Shorthand for `setCookie(new Cookie(name, value))`. |
+| `clearCookie` | `clearCookie(name: string, path = '/', domain = ''): Response` | Emits a deletion `Set-Cookie` (empty value, `Max-Age=0`). |
+| `cache` | `cache(edgeTtlMinutes: u16, browserTtlSeconds: u32 = 0, privateScope: bool = false, allowAuth: bool = false): Response` | Marks the response cacheable. See [Caching](./caching.md). |
+| `cacheFor` | `cacheFor(minutes: u16): Response` | Shorthand for `cache(minutes)` (edge only). |
+
+```ts
+return Response.json('{"id":42}')
+  .setHeader('x-trace', traceId)
+  .setCookie(Cookie.create('sid', token).httpOnly().secure())
+  .cacheFor(5);
+```
+
+See [Cookies](./cookies.md) for the cookie builder, and [Caching](./caching.md)
+for the cache directives.

package/docs/rpc.md

@@ -0,0 +1,149 @@
+# RPC and the generated client
+
+The server build with `--rpcModule shared/server.ts` scans your decorated
+surface (`@data`, `@user`, `@service`/`@remote`, `@rest`) and emits one
+TypeScript module: a typed `Server` proxy, the `@data` codec classes, the REST
+fetch client, and the `getUser()` accessor. The client imports that file and
+calls the server with full type-safety and editor autocomplete. The file is
+regenerated on every server build, so it never drifts from the server.
+
+```sh
+toilscript --target release --rpcModule shared/server.ts
+```
+
+## `@service` and `@remote`
+
+A `@service` class exposes its `@remote` methods as callable RPC. A top-level
+`@remote` function is exposed directly.
+
+```ts
+@service
+class Stats {
+  @remote
+  public playerCount(): i32 { return store.size; }
+}
+
+@remote
+function ping(n: i32): i32 { return n + 1; }
+```
+
+The generated client surfaces these on the global `Server` proxy. A service is
+keyed by its class name with the first letter lowercased (`Stats` → `stats`):
+
+```ts
+await Server.stats.playerCount(); // Promise<number>
+await Server.ping(42);            // Promise<number>
+```
+
+Arguments and return values are `@data`-typed; scalars map to TS as below.
+
+## The generated `Server` surface
+
+`shared/server.ts` declares a global `Server` whose shape is, schematically:
+
+```ts
+declare global {
+  const Server: {
+    // top-level @remote functions
+    ping(n: number): Promise<number>;
+
+    // @service classes (keyed by lowercased name)
+    readonly stats: {
+      playerCount(): Promise<number>;
+    };
+
+    // @rest controllers, under REST
+    readonly REST: {
+      readonly players: {
+        get(args: { params: { id: string | number | bigint }; query?: …; headers?: … }): Promise<Response>;
+        create(args: { body: NewPlayer; query?: …; headers?: … }): Promise<Player>;
+      };
+    };
+  };
+}
+```
+
+### Type mapping (ToilScript → TypeScript)
+
+| ToilScript | TypeScript |
+| --- | --- |
+| `u8`,`u16`,`u32`,`i8`,`i16`,`i32`,`f32`,`f64` | `number` |
+| `u64`,`i64`,`u128`,`i128`,`u256`,`i256` | `bigint` |
+| `bool` | `boolean` |
+| `string` | `string` |
+| a `@data` class `T` | `T` (the emitted class) |
+| `T[]` | `T[]` |
+
+64-bit-and-larger integers are `bigint` on the client and travel as decimal
+strings on the JSON wire, so they are exact at any magnitude.
+
+### Emitted `@data` classes
+
+Each `@data` (and `@user`) class becomes an exported TS class with the fields, a
+defaulted constructor, and the matching codec:
+
+```ts
+export class Player {
+  constructor(public username = '', public admin = false, public score = 0n) {}
+  encodeInto(w: DataWriter): void { /* … */ }
+  encode(): Uint8Array { /* dataId prefix + fields */ }
+  static decodeFrom(r: DataReader): Player { /* … */ }
+  static decode(buf: Uint8Array): Player { /* … */ }
+  static dataId(): number { /* FNV-1a of "Player" */ }
+  static fromJSONValue(v: any): Player { /* revive, 64-bit from strings */ }
+  toJSONValue(): any { /* 64-bit as decimal strings */ }
+}
+```
+
+The codec is byte-compatible with the server's `@data` codec, so binary bodies
+round-trip exactly between client and wasm.
+
+## The REST fetch client
+
+Every `@rest` route also gets a typed fetch wrapper under `Server.REST.<key>`,
+keyed by the controller name lowercased. The call argument is an object:
+
+```ts
+Server.REST.players.create({
+  body: new NewPlayer('alice'),     // present iff the route takes a body
+  // params: { id: 7 },             // present iff the path has :params
+  query: { ref: 'home' },           // optional
+  headers: { 'x-trace': traceId },  // optional
+});
+```
+
+- If the route has no params and no body, the whole argument is optional
+  (`args?`).
+- The wrapper builds the URL (substituting `:params`, appending `query`),
+  `fetch`es with `credentials` as configured, throws on a non-2xx status, and
+  decodes the response into the route's return type.
+- A route declared to return `Response` resolves to the raw `fetch` `Response`,
+  so you can stream or inspect headers yourself.
+
+```ts
+const player = await Server.REST.players.create({ body: new NewPlayer('alice') });
+//    ^? Player
+```
+
+## `getUser()`
+
+When the server declares a `@user` class, the generated module also exports a
+typed, no-argument `getUser()` that reads the readable companion cookie and
+decodes it with the generated codec:
+
+```ts
+import { getUser } from './shared/server';
+
+const user = getUser(); // Account | null, fully typed
+```
+
+This is **display-only**: the server re-verifies the signed session on every
+`@auth` request. See [Auth](./auth.md) for the full picture.
+
+## Notes
+
+- `shared/server.ts` is generated; never edit it by hand. Re-run the server
+  build (or `toiljs dev`, which does it on save) to refresh it.
+- The `Server` proxy is declared as an ambient global on the client; the runtime
+  implementation is provided by toiljs. The REST client and `getUser` are real
+  exported values in the generated module.