toiljs 0.0.60 → 0.0.61

package/build/devserver/server.js

@@ -2,12 +2,14 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { Server } from '@dacely/hyper-express';
 import pc from 'picocolors';
+import { DaemonHost, daemonEmulationEnabled } from './daemon/index.js';
 import { configureDbPersistence } from './db/index.js';
 import { initEmailService } from './email/index.js';
 import { applyCacheRule, lookupCache } from './http/cache.js';
 import { METHOD_CODES } from './http/envelope.js';
 import { proxyToVite, wireWebsocketProxy } from './http/proxy.js';
 import { WasmServerModule } from './runtime/module.js';
+import { assembleSsr, buildSsrRoutes, pathnameOf, } from './ssr.js';
 const DEFAULT_MAX_BODY_LENGTH = 1024 * 1024 * 8;
 const VITE_PREFIXES = ['/@', '/node_modules/', '/__toil/'];
 const MIME = {
@@ -77,6 +79,23 @@ function sendWasmResponse(response, root, result) {
         response.header('content-type', 'text/plain; charset=utf-8');
     response.send(Buffer.from(result.body.buffer, result.body.byteOffset, result.body.length));
 }
+function sendSsr(response, out, headOnly) {
+    response.status(out.status);
+    let hasContentType = false;
+    for (const [name, value] of out.headers) {
+        if (name.toLowerCase() === 'content-type')
+            hasContentType = true;
+        response.header(name, value);
+    }
+    if (!hasContentType)
+        response.header('content-type', 'text/html; charset=utf-8');
+    response.header('server', 'toil-dev');
+    if (headOnly) {
+        response.send('');
+        return;
+    }
+    response.send(Buffer.from(out.html.buffer, out.html.byteOffset, out.html.length));
+}
 export async function startDevServer(options) {
     const host = options.host ?? '127.0.0.1';
     const root = path.resolve(options.root);
@@ -88,6 +107,10 @@ export async function startDevServer(options) {
         process.stdout.write(pc.yellow('  ! ') + pc.dim(`email off: ${emailInit.note}`) + '\n');
     }
     const module = new WasmServerModule(options.wasmFile);
+    const ssrRoutes = buildSsrRoutes(options.ssrTemplates ?? []);
+    if (ssrRoutes.length > 0) {
+        process.stdout.write(pc.dim(`  edge SSR: ${String(ssrRoutes.length)} route(s) served server-side`) + '\n');
+    }
     configureDbPersistence(path.join(root, '.toil', 'devdata.json'));
     let warnedMissing = false;
     let loadedOnce = false;
@@ -122,6 +145,23 @@ export async function startDevServer(options) {
         });
     });
     wireWebsocketProxy(app, options.vite);
+    const nodeMode = options.nodeMode ?? 'all';
+    let daemonHost = null;
+    let daemonTimer = null;
+    if (options.coldWasmFile !== undefined && daemonEmulationEnabled(nodeMode) && options.daemon) {
+        daemonHost = new DaemonHost(options.coldWasmFile, options.daemon, nodeMode);
+        const pollDaemon = () => {
+            try {
+                daemonHost?.refresh();
+            }
+            catch (e) {
+                process.stdout.write(pc.red(`  ✗ daemon reload failed: ${String(e)}`) + '\n');
+            }
+        };
+        pollDaemon();
+        daemonTimer = setInterval(pollDaemon, 500);
+        daemonTimer.unref?.();
+    }
     app.any('/*', async (request, response) => {
         response.removeHeader('uWebSockets');
         const dispatchable = !isViteInternal(request.url) && METHOD_CODES[request.method] !== undefined;
@@ -150,6 +190,22 @@ export async function startDevServer(options) {
                 response.status(500).send('internal error\n');
                 return;
             }
+            if ((request.method === 'GET' || request.method === 'HEAD') &&
+                ssrRoutes.length > 0) {
+                const route = ssrRoutes.find((r) => r.test(pathnameOf(request.url)));
+                if (route) {
+                    try {
+                        const out = assembleSsr(route, module.dispatchRender(envelopeReq));
+                        if (out !== null) {
+                            sendSsr(response, out, request.method === 'HEAD');
+                            return;
+                        }
+                    }
+                    catch (e) {
+                        process.stdout.write(pc.red(`  ✗ SSR ${request.path}: ${String(e)}`) + '\n');
+                    }
+                }
+            }
         }
         await proxyToVite(request, response, options.vite);
     });
@@ -158,6 +214,9 @@ export async function startDevServer(options) {
         port: options.port,
         host,
         close: async () => {
+            if (daemonTimer !== null)
+                clearInterval(daemonTimer);
+            daemonHost?.close();
             await app.shutdown();
         },
     };

package/build/devserver/ssr.d.ts

@@ -0,0 +1,25 @@
+export interface DevSsrTemplate {
+    pattern: string;
+    name: string;
+    tmpl: Uint8Array;
+    entries: {
+        id: number;
+        offset: number;
+    }[];
+}
+export interface SsrRoute {
+    test: (pathname: string) => boolean;
+    tmpl: Uint8Array;
+    entries: {
+        id: number;
+        offset: number;
+    }[];
+}
+export declare function pathnameOf(url: string): string;
+export declare function buildSsrRoutes(templates: readonly DevSsrTemplate[]): SsrRoute[];
+export interface SsrResult {
+    status: number;
+    headers: [string, string][];
+    html: Uint8Array;
+}
+export declare function assembleSsr(route: SsrRoute, envelope: Uint8Array): SsrResult | null;

package/build/devserver/ssr.js

@@ -0,0 +1,114 @@
+export function pathnameOf(url) {
+    const q = url.indexOf('?');
+    return q < 0 ? url : url.slice(0, q);
+}
+function patternToTest(pattern) {
+    const norm = (p) => (p.length > 1 && p.endsWith('/') ? p.slice(0, -1) : p);
+    let re = '';
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === ':') {
+            i++;
+            while (i < pattern.length && /[A-Za-z0-9_]/.test(pattern[i]))
+                i++;
+            re += '[^/]+';
+        }
+        else if (ch === '*') {
+            re += '.*';
+            i++;
+        }
+        else if (ch === '[') {
+            const end = pattern.indexOf(']', i);
+            const inner = end < 0 ? '' : pattern.slice(i + 1, end);
+            re += inner.startsWith('...') ? '.*' : '[^/]+';
+            i = end < 0 ? pattern.length : end + 1;
+        }
+        else {
+            re += ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            i++;
+        }
+    }
+    const compiled = new RegExp(`^${re}$`);
+    return (pathname) => compiled.test(norm(pathname));
+}
+export function buildSsrRoutes(templates) {
+    return templates.map((t) => ({ test: patternToTest(t.pattern), tmpl: t.tmpl, entries: t.entries }));
+}
+function decodeValues(buf) {
+    const dv = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    let o = 0;
+    const need = (n) => o + n <= buf.byteLength;
+    try {
+        if (!need(2 + 32 + 2))
+            return null;
+        const status = dv.getUint16(o, true);
+        o += 2;
+        o += 32;
+        const nHeaders = dv.getUint16(o, true);
+        o += 2;
+        const headers = [];
+        const dec = new TextDecoder();
+        for (let i = 0; i < nHeaders; i++) {
+            if (!need(4))
+                return null;
+            const nameLen = dv.getUint16(o, true);
+            const valLen = dv.getUint16(o + 2, true);
+            o += 4;
+            if (!need(nameLen + valLen))
+                return null;
+            const name = dec.decode(buf.subarray(o, o + nameLen));
+            o += nameLen;
+            const val = dec.decode(buf.subarray(o, o + valLen));
+            o += valLen;
+            headers.push([name, val]);
+        }
+        if (!need(2))
+            return null;
+        const nSlots = dv.getUint16(o, true);
+        o += 2;
+        const values = new Map();
+        for (let i = 0; i < nSlots; i++) {
+            if (!need(2 + 1 + 4))
+                return null;
+            const id = dv.getUint16(o, true);
+            o += 2;
+            o += 1;
+            const len = dv.getUint32(o, true);
+            o += 4;
+            if (!need(len))
+                return null;
+            values.set(id, buf.subarray(o, o + len));
+            o += len;
+        }
+        return { status, headers, values };
+    }
+    catch {
+        return null;
+    }
+}
+function splice(tmpl, inserts) {
+    const parts = [];
+    let prev = 0;
+    for (const ins of inserts) {
+        if (ins.offset > prev)
+            parts.push(tmpl.subarray(prev, ins.offset));
+        if (ins.value.length > 0)
+            parts.push(ins.value);
+        prev = ins.offset;
+    }
+    if (tmpl.length > prev)
+        parts.push(tmpl.subarray(prev));
+    return Buffer.concat(parts.map((p) => Buffer.from(p.buffer, p.byteOffset, p.byteLength)));
+}
+export function assembleSsr(route, envelope) {
+    const decoded = decodeValues(envelope);
+    if (decoded === null)
+        return null;
+    if (decoded.status >= 500 || decoded.values.size === 0)
+        return null;
+    const inserts = route.entries
+        .map((e) => ({ offset: e.offset, value: decoded.values.get(e.id) ?? new Uint8Array(0) }))
+        .sort((a, b) => a.offset - b.offset);
+    return { status: decoded.status, headers: decoded.headers, html: splice(route.tmpl, inserts) };
+}

package/build/devserver/wasm/sections.d.ts

@@ -0,0 +1,2 @@
+export declare function leb(buf: Buffer, pos: number): [number, number];
+export declare function customSection(wasm: Buffer, want: string): Buffer | null;

package/build/devserver/wasm/sections.js

@@ -0,0 +1,42 @@
+export function leb(buf, pos) {
+    let result = 0;
+    let shift = 0;
+    let p = pos;
+    for (;;) {
+        if (p >= buf.length)
+            throw new RangeError('leb128 past end of buffer');
+        const b = buf[p++];
+        result |= (b & 0x7f) << shift;
+        if ((b & 0x80) === 0)
+            break;
+        shift += 7;
+        if (shift > 35)
+            throw new RangeError('leb128 too long');
+    }
+    return [result >>> 0, p];
+}
+export function customSection(wasm, want) {
+    if (wasm.length < 8 ||
+        wasm[0] !== 0x00 ||
+        wasm[1] !== 0x61 ||
+        wasm[2] !== 0x73 ||
+        wasm[3] !== 0x6d)
+        return null;
+    let pos = 8;
+    while (pos < wasm.length) {
+        const id = wasm[pos++];
+        let size;
+        [size, pos] = leb(wasm, pos);
+        const end = pos + size;
+        if (end > wasm.length || end < pos)
+            return null;
+        if (id === 0) {
+            const [nameLen, namePos] = leb(wasm, pos);
+            if (namePos + nameLen <= end &&
+                wasm.toString('latin1', namePos, namePos + nameLen) === want)
+                return wasm.subarray(namePos + nameLen, end);
+        }
+        pos = end;
+    }
+    return null;
+}

package/build/devserver/wasm/surface.d.ts

@@ -0,0 +1,18 @@
+export interface SurfaceFlags {
+    readonly rest: boolean;
+    readonly stream: boolean;
+    readonly daemon: boolean;
+    readonly scheduled: boolean;
+    readonly database: boolean;
+    readonly render: boolean;
+}
+export interface Surface {
+    readonly targetMode: 'hot' | 'cold';
+    readonly flags: SurfaceFlags;
+    readonly abiVersion: number;
+    readonly buildId: string;
+    readonly fingerprint: number;
+    readonly dataCoherenceHash: number;
+    readonly pairCoherenceHash: number;
+}
+export declare function parseSurface(wasm: Buffer): Surface | 'absent' | 'invalid';

package/build/devserver/wasm/surface.js

@@ -0,0 +1,41 @@
+import { DataReader } from 'toiljs/io';
+import { customSection } from './sections.js';
+export function parseSurface(wasm) {
+    let sec;
+    try {
+        sec = customSection(wasm, 'toil.surface');
+    }
+    catch {
+        return 'invalid';
+    }
+    if (sec === null)
+        return 'absent';
+    const r = new DataReader(sec);
+    r.readU16();
+    const targetMode = r.readU8() === 1 ? 'cold' : 'hot';
+    r.readU8();
+    const f = r.readU32();
+    const abiVersion = r.readU16();
+    const buildId = r.readString();
+    const fingerprint = r.readU32();
+    const dataCoherenceHash = r.readU32();
+    const pairCoherenceHash = r.readU32();
+    if (!r.ok)
+        return 'invalid';
+    return {
+        targetMode,
+        flags: {
+            rest: !!(f & 1),
+            stream: !!(f & 2),
+            daemon: !!(f & 4),
+            scheduled: !!(f & 8),
+            database: !!(f & 16),
+            render: !!(f & 32),
+        },
+        abiVersion,
+        buildId,
+        fingerprint,
+        dataCoherenceHash,
+        pairCoherenceHash,
+    };
+}

package/docs/README.md

@@ -34,7 +34,7 @@ and as a named export from `toiljs/server/runtime`.
   type, `AuthService` (post-quantum login, signed sessions, `getUser()`), and
   the client half.
 - [Environment variables & secrets](./environment.md): `Environment.get` /
-  `getSecure` — per-tenant config + secrets set out of band (GitHub-Actions
+  `getSecure`, per-tenant config + secrets set out of band (GitHub-Actions
   style), so the `.wasm` carries no credentials. Two disjoint buckets, read-only.
 - [Email](./email.md): `EmailService`, `EmailTemplate`, the `emails/` React
   template pipeline, the stateless `TwoFactor` codes, provider config
@@ -52,14 +52,14 @@ and as a named export from `toiljs/server/runtime`.
 
 ## Conventions
 
-- **"Global, no import"** — a symbol marked `@global` in the runtime is in scope
+- **"Global, no import"**, a symbol marked `@global` in the runtime is in scope
   everywhere in a tenant without an `import`, exactly like `crypto`. The
   matching named export exists so editors resolve the type and so the module is
   pulled into every build. Either form works.
-- **Binary, not JSON, on the hot paths** — request/response bodies, sessions,
+- **Binary, not JSON, on the hot paths**, request/response bodies, sessions,
   and cookies use the deterministic `DataWriter`/`DataReader` codec. JSON is
   available for `@rest` routes but binary is the default for anything
   performance- or security-sensitive.
-- **One fresh instance per request** — guest memory is wiped between requests,
+- **One fresh instance per request**, guest memory is wiped between requests,
   so nothing persists in module globals across requests. Use a host-backed store
   for anything that must outlive a single request.

package/docs/auth-todo.md

@@ -24,7 +24,7 @@ imports in `toil-backend` (`crypto.mlkem_decapsulate`, `crypto.voprf_evaluate`),
 
 ---
 
-## Tier 1 — blocks production (cannot run on the edge yet)
+## Tier 1, blocks production (cannot run on the edge yet)
 
 ### 1.1 Storage on toildb (THE blocker) -- "when building toildb, consider this"
 The accounts + login challenges live in the **DEV-ONLY** `kv.*` Map
@@ -72,17 +72,17 @@ in-prod `mldsa_verify` import). Do before trusting in prod.
 
 ---
 
-## Tier 2 — protocol hardening
+## Tier 2, protocol hardening
 
-### 2.6 A properly bound session key — DONE (on main, unreleased)
+### 2.6 A properly bound session key, DONE (on main, unreleased)
 The session key is now `K = HMAC-SHA256(sharedSecret, SESSION_KEY_LABEL || H(M))` and the
 mutual-auth tag is `HMAC-SHA256(K, SERVER_CONFIRM_LABEL || H(M))` (`AuthService.deriveSessionKey`
 + `serverConfirmTag`; client mirrors it with hash-wasm `createHMAC`). REMAINING: binding the
 *session cookie* to the transport (so a stolen cookie is useless on another channel) needs
-the TLS exporter, which the wasm guest cannot see — an edge/transport follow-up, not doable
+the TLS exporter, which the wasm guest cannot see, an edge/transport follow-up, not doable
 purely in the guest.
 
-### 2.7 Bind the KDF params + server key into the transcript — DONE (on main, unreleased)
+### 2.7 Bind the KDF params + server key into the transcript, DONE (on main, unreleased)
 The single `buildLoginMessage` now binds the ML-KEM ciphertext, the Argon2id params
 (mem/iters/par), and `serverKemKeyId = SHA-256(serverKemPublicKey)`. Closes
 key-substitution and param-downgrade confusion. (There is ONE login message format, no
@@ -96,7 +96,7 @@ a reviewable artifact.
 
 ---
 
-## Tier 3 — account lifecycle (missing today)
+## Tier 3, account lifecycle (missing today)
 
 ### 3.1 Password change / key rotation
 Re-derive under a fresh salt while authenticated, re-register the new public key. None

package/docs/caching.md

@@ -59,14 +59,14 @@ return Response.bytes(blob).cacheFor(5);
 
 The cache layer refuses to store anything unsafe, regardless of the directive:
 
-- **5xx** responses are never cached — a server error is transient, and `@cache`
+- **5xx** responses are never cached, a server error is transient, and `@cache`
   wraps the whole route, so a `@cache`d route that hits a blip returns its 500
   carrying the directive; caching it would serve the failure for the full TTL.
   **2xx, 3xx, and 4xx are cacheable** (a redirect or a `404`/`410` is a
   deterministic function of the request key);
 - a response that sets a **`Set-Cookie`** is never cached;
 - a response to an **authenticated** request is not cached unless you pass
-  `allowAuth = true` — this prevents one user's personalized response from being
+  `allowAuth = true`, this prevents one user's personalized response from being
   served to another;
 - the edge TTL is **clamped to 24 hours**.
 
@@ -75,7 +75,7 @@ an unauthorized request is rejected with 401 before anything is cached, and a
 cached entry is only ever produced from a handler that actually ran.
 
 Caching is **always opt-in.** A response with no `Toil-Cache-Control` directive
-(i.e. no `@cache` / `Response.cache(...)`) is never stored — there is no blind
+(i.e. no `@cache` / `Response.cache(...)`) is never stored, there is no blind
 "cache every GET" mode, because an automatic window cannot tell a personalized
 response from a public one and would key it without a per-user component.
 
@@ -84,11 +84,11 @@ response from a public one and would key it without a per-user component.
 The edge cache is per-core and hard-capped so it can never exhaust node memory.
 It has two tiers:
 
-- **RAM tier** — small, short-TTL responses. Bounded by a per-core byte budget
+- **RAM tier**, small, short-TTL responses. Bounded by a per-core byte budget
   (each core holds at most ~128 MB) plus an entry-count cap; an insert that would
   exceed the budget drops expired entries first, then evicts the soonest-to-expire
   ones. A response over ~256 KB does not go in the RAM tier.
-- **Disk tier (spill)** — when the operator enables `--spill-dir`, a **big**
+- **Disk tier (spill)**, when the operator enables `--spill-dir`, a **big**
   (over the ~256 KB RAM cap) or **long-TTL** (≥ 10 min) cacheable response is
   written to disk instead and served back zero-RAM via a memory map, the same way
   static files are served. This keeps the RAM tier for the hot working set while

package/docs/cli.md

@@ -0,0 +1,15 @@
+# CLI
+
+- `toiljs create [name]`, scaffold a project. Flags: `--template app|minimal`,
+  `--style css|sass|less|stylus`, `--tailwind`, `--no-ai`, `-y`/`--yes`.
+- `toiljs dev`, dev server with HMR (`--port`, `--root`). With a `toilconfig.json` it builds
+  the server first, then rebuilds it whenever a `server/` file changes (regenerating
+  `shared/server.ts`, which Vite HMRs into the client); client-only edits just HMR the client.
+- `toiljs build`, production build. With a `toilconfig.json` it builds the server (toilscript,
+  regenerating `shared/server.ts`) first, then the client → `build/client`. `--server` builds
+  only the server. Every `server/` file declaring a surface (`@data`/`@rest`/...) is compiled.
+- `toiljs start`, self-host the built app (hyper-express) with a `/_toil` WebSocket channel.
+- `toiljs configure`, toggle styling features on an existing project (see [styling.md](./styling.md)).
+- `toiljs doctor`, diagnose project setup (`--json` for CI). `--fix` auto-wires the typed-RPC
+  setup (build scripts, tsconfig `shared` + alias, `.gitignore`, toilscript version, and the
+  toilscript prettier plugin) so an existing project upgrades in one command.

package/docs/client.md

@@ -0,0 +1,40 @@
+# Client runtime
+
+Everything is on the `Toil` global, no imports needed in route files.
+
+## Entry
+
+`client/toil.tsx` imports the route table + global styles and mounts the app:
+
+```tsx
+import { routes, layout, notFound } from "toiljs/routes";
+import "./styles/main.css";
+Toil.mount(routes, layout, notFound);
+```
+
+## API (on `Toil`)
+
+- Components: `Link`, `NavLink`, `Head`
+- Navigation: `navigate`, `useRouter`, `useNavigate`
+- Location: `usePathname`, `useSearchParams`, `useParams`, `useNavigationPending`
+- Data: `useLoaderData` (see [routing.md](./routing.md))
+- Head: `useHead`, `useTitle`, `<Head>`, set the `<title>` / meta per route
+- Realtime: `useChannel`, `connectChannel` (WebSocket to the backend at `/_toil`)
+- IO globals (no `Toil.` prefix): `FastMap`, `FastSet`, `DataWriter`, `DataReader`
+- `parseError(err)` global: message from an unknown caught value (handy in `catch`)
+- `Server` global: the typed RPC surface generated from the server (see [server.md](./server.md))
+- `Server.REST.<controller>.<route>(args)`: a working, typed `fetch` client for your
+  `@rest` controllers, e.g. `await Server.REST.todos.getTodo({ params: { id } })` or
+  `await Server.REST.todos.add({ body: new AddTodo("milk") })`. `args` is
+  `{ params?, body?, query?, headers? }`; returns are typed (`@data` classes are parsed for
+  you). The REST client attaches when you import from `shared/server`.
+
+## Head example
+
+```tsx
+Toil.useHead({
+    title: "Blog",
+    titleTemplate: "%s, MyApp",
+    meta: [{ name: "description", content: "..." }],
+});
+```

package/docs/crypto.md

@@ -2,7 +2,7 @@
 
 The guest gets a synchronous Web Crypto surface through the ambient `crypto`
 global, backed by host functions. It mirrors the browser `crypto` /
-`crypto.subtle` API but **without Promises** — ToilScript has no `async`, so
+`crypto.subtle` API but **without Promises**, ToilScript has no `async`, so
 every call returns its result directly. Keys are opaque per-request handles in a
 host keystore; a `CryptoKey` is valid only for the request that created it.
 
@@ -84,7 +84,7 @@ Each algorithm has a small params class you pass to `importKey`/`sign`/etc.:
 - **Key formats:** `FMT_RAW`, `FMT_PKCS8`, `FMT_SPKI` (`FMT_JWK` is rejected).
 - **Usages (bitmask):** `USAGE_ENCRYPT`, `USAGE_DECRYPT`, `USAGE_SIGN`,
   `USAGE_VERIFY`, `USAGE_DERIVE_KEY`, `USAGE_DERIVE_BITS`, `USAGE_WRAP_KEY`,
-  `USAGE_UNWRAP_KEY` — OR them together.
+  `USAGE_UNWRAP_KEY`, OR them together.
 - **Named curves:** `CURVE_P256`, `CURVE_P384` (`CURVE_P521` is not supported).
 
 ### `CryptoKey`
@@ -116,7 +116,7 @@ const ct = crypto.subtle.encrypt(new AesGcmParams(iv, aad, 128), k, plaintext);
 ## Post-quantum verify
 
 The host also exposes ML-DSA-44 (FIPS 204) signature verification as
-`crypto.mldsa_verify`. It is verify-only — the host never holds a secret key — and
+`crypto.mldsa_verify`. It is verify-only, the host never holds a secret key, and
 underpins the [auth primitive](./auth.md). Most code reaches it through
 `AuthService.verifyLogin(publicKey, message, signature)` rather than calling the
 import directly. Public key is 1312 bytes, signature 2420 bytes, with a FIPS 204
@@ -124,7 +124,7 @@ domain-separation context.
 
 ## Limitations
 
-- **No Promises** — every call is synchronous.
+- **No Promises**, every call is synchronous.
 - **No RSA** and **no JWK** key format.
 - **P-521** is not supported (P-256 and P-384 are).
 - Signature *generation* for ML-DSA is client-side only; the server verifies.

package/docs/data.md

@@ -17,13 +17,13 @@ class Player {
 
 From that the compiler synthesizes, on the class:
 
-- `encode(): Uint8Array` / `static decode(buf): T` — the binary codec (with a
+- `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
+- `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
+- `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
+- `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`),
@@ -47,8 +47,8 @@ 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:
+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';