toiljs 0.0.59 → 0.0.61

package/docs/styling.md

@@ -0,0 +1,22 @@
+# Styling
+
+The app imports one stylesheet from `client/toil.tsx` (e.g. `./styles/main.css`).
+
+## Preprocessors & Tailwind
+
+Pick a CSS preprocessor (none / Sass / Less / Stylus) and optionally Tailwind at
+`toiljs create`, or change it later on an existing project:
+
+```sh
+toiljs configure                 # interactive
+toiljs configure --tailwind      # add Tailwind
+toiljs configure --style sass    # switch preprocessor
+```
+
+`configure` installs/removes the right packages and rewrites the imports. Tailwind lives
+in its own `styles/tailwind.css` (`@import "tailwindcss";`).
+
+## Imports
+
+`.css` / `.scss` / `.sass` / `.less` / `.styl` and image imports (`.svg`, `.png`, …) are
+typed via `toil-env.d.ts`.

package/docs/time.md

@@ -11,7 +11,7 @@ from `toiljs/server/runtime`.
 ```ts
 import { Time } from 'toiljs/server/runtime'; // optional; Time is also a global
 
-const ms = Time.nowMillis();   // i64 milliseconds since the Unix epoch
+const ms = Time.nowMillis();   // u64 milliseconds since the Unix epoch
 const s  = Time.nowSeconds();  // u64 whole seconds since the Unix epoch
 ```
 
@@ -19,12 +19,12 @@ const s  = Time.nowSeconds();  // u64 whole seconds since the Unix epoch
 
 | Member | Signature | Description |
 | --- | --- | --- |
-| `Time.nowMillis()` | `static nowMillis(): i64` | Milliseconds since the Unix epoch (the raw host `Date.now()` value). |
+| `Time.nowMillis()` | `static nowMillis(): u64` | Milliseconds since the Unix epoch (the raw host `Date.now()` value). |
 | `Time.nowSeconds()` | `static nowSeconds(): u64` | Whole seconds since the epoch (`nowMillis() / 1000`). The unit used by sessions and login challenges. |
 
 ## Semantics
 
-`Time` is **wall-clock, not monotonic** — exactly like browser `Date.now()`. It
+`Time` is **wall-clock, not monotonic**, exactly like browser `Date.now()`. It
 tracks the system clock and can step backward across an NTP correction.
 
 - Use it to stamp and compare absolute instants: session `iat`/`exp`, login

package/eslint.config.js

@@ -5,7 +5,16 @@ import tseslint from 'typescript-eslint';
 
 export default tseslint.config(
     // toilscript server (WASM) + its ambient std + build output are not part of the TS project.
-    { ignores: ['build/**', 'server/**', 'std/server/**', 'toil-env.d.ts'] },
+    // toil-docs.generated.ts is a build artifact (gitignored, emitted by gen:docs) — not linted.
+    {
+        ignores: [
+            'build/**',
+            'server/**',
+            'std/server/**',
+            'toil-env.d.ts',
+            'src/compiler/toil-docs.generated.ts',
+        ],
+    },
     eslint.configs.recommended,
     ...tseslint.configs.strictTypeChecked,
     {

package/examples/basic/client/components/Header.tsx

@@ -22,6 +22,9 @@ export default function Header() {
                 <Toil.NavLink href="/features" className="nav-center-link">
                     Features
                 </Toil.NavLink>
+                <Toil.NavLink href="/hello" className="nav-center-link">
+                    Edge SSR
+                </Toil.NavLink>
                 <Toil.NavLink href="/search" className="nav-center-link">
                     Search
                 </Toil.NavLink>

package/examples/basic/client/routes/features/actions.tsx

@@ -1,5 +1,3 @@
-// Mutations: a `loader` reads, an action writes, then revalidation refetches the loader so the UI
-// reflects the new state with no manual refetch. Here a module-level counter stands in for a server.
 let serverCount = 0;
 async function wait(ms: number): Promise<void> {
     return new Promise((resolve) => setTimeout(resolve, ms));

package/examples/basic/client/routes/hello.tsx

@@ -1,43 +1,113 @@
 /**
- * An edge-SSR route. `export const ssr = true` opts it into the template
- * extractor: at build time toil renders it once into a template-with-holes
- * (`_ssr/hello.{tmpl,slots}` + a guest `Slot` module); at request time the edge
- * splices the guest's hole values into that template (no per-request render).
+ * An edge-SSR route, server-rendered at the edge with no per-request React.
  *
- * SSR routes must render under static markup: use the hole markers (`Hole`,
- * `Repeat`, `RawHtml`) and `useLoaderData`, and keep router-hook-dependent or
- * client-only bits inside an `<Island>`.
+ * `export const ssr = true` opts it into the template extractor: at build time
+ * toil renders this page (under the real layout chain) ONCE into a
+ * template-with-holes (`build/client/_ssr/hello.{tmpl,slots}` + the guest
+ * `Slot` module), and the matching server `render` (see
+ * `server/SsrHelloRender.ts`) fills only the holes per request. The edge
+ * splices the values into the template, so this page is served about as fast as
+ * a static file while still delivering real first-paint HTML and SEO, and the
+ * browser hydrates it in place.
+ *
+ * The dynamic bits are wrapped in the hole markers from `toiljs/client`, which
+ * are transparent in the browser (they just render their children) but are what
+ * the build extractor and the server `render` key off:
+ *
+ *   - `<Hole>`    a text hole (React-escaped for you)
+ *   - `<RawHtml>` a raw-HTML block (you own sanitisation)
+ *   - `<Repeat>`  a repeated region, the row markup stamped per item
+ *   - `<Island>`  a client-only escape hatch (empty server-side; appears after
+ *                 hydration). Router-hook / browser-only bits live here so the
+ *                 page renders under static markup.
  */
-import { Hole, Repeat, useLoaderData } from 'toiljs/client';
+import { Hole, Island, RawHtml, Repeat, useLoaderData } from 'toiljs/client';
 
 export const ssr = true;
 
-interface HelloData {
+export const metadata: Toil.Metadata = {
+    title: 'Edge SSR',
+    description: 'A server-rendered greeting, filled at the edge from a tiny values envelope.',
+    openGraph: { title: 'Edge SSR, ToilJS', type: 'website' }
+};
+
+interface Service {
+    name: string;
+    region: string;
+}
+
+interface GreetingData {
+    /** Who we are greeting (a text hole). */
     name: string;
-    items: string[];
+    /** A short, pre-sanitised HTML blurb (a raw-HTML hole). */
+    blurbHtml: string;
+    /** A live status snapshot, stamped row by row (a repeat region). */
+    services: Service[];
 }
 
-export const loader = ({ params }: { params: Record<string, string> }): HelloData => ({
-    name: params.name ?? 'world',
-    items: ['alpha', 'beta', 'gamma']
+/**
+ * This loader plays two roles:
+ *
+ *  1. BUILD: it is rendered once (with empty search params) so the extractor
+ *     captures the holes; only the SHAPE matters there.
+ *  2. CLIENT HYDRATION: after the edge serves the server-rendered HTML, the
+ *     browser hydrates by re-rendering this component with THIS loader's data.
+ *     For a byte-clean hydrate, that data must reproduce the values the SERVER
+ *     `render` stamped (see `server/SsrHelloRender.ts`). So the greeting reads
+ *     `?name=` here exactly as the server `render` does; if it didn't,
+ *     `/hello?Bob` would hydrate the server's "Bob" back to the loader default
+ *     and flash. (Holes that the client cannot reproduce belong in an
+ *     `<Island>`.)
+ */
+export const loader = ({ searchParams }: { searchParams: URLSearchParams }): GreetingData => ({
+    name: searchParams.get('name') || 'world',
+    blurbHtml: 'Rendered at the <strong>edge</strong> from a tiny values envelope.',
+    services: [
+        { name: 'record', region: 'us-east' },
+        { name: 'unique', region: 'eu-west' },
+        { name: 'counter', region: 'ap-south' }
+    ]
 });
 
 export default function Hello(): React.JSX.Element {
     const d = useLoaderData<typeof loader>();
     return (
-        <section>
+        <section className="hello">
             <h1>
-                Hello <Hole id="name">{d.name}</Hole>
+                Hello, <Hole id="name">{d.name}</Hole>!
             </h1>
-            <ul>
-                <Repeat id="items" each={d.items}>
-                    {(s: string) => (
+
+            {/* A raw-HTML hole: the server is responsible for sanitising it. */}
+            <p className="hello-blurb">
+                <RawHtml id="blurb" html={d.blurbHtml} as="span" />
+            </p>
+
+            {/* A repeat region: the row markup is captured once and stamped per
+                item. The nested <Hole>s are filled inside each stamped row. */}
+            <h2>Service snapshot</h2>
+            <ul className="hello-services">
+                <Repeat id="services" each={d.services}>
+                    {(s: Service) => (
                         <li>
-                            <Hole id="item">{s}</Hole>
+                            <strong>
+                                <Hole id="svcName">{s.name}</Hole>
+                            </strong>
+                            <span className="hello-region">
+                                <Hole id="svcRegion">{s.region}</Hole>
+                            </span>
                         </li>
                     )}
                 </Repeat>
             </ul>
+
+            {/* A client-only island: empty in the server HTML, rendered after
+                hydration. Anything router-hook / browser-only lives here so the
+                page above stays server-renderable. */}
+            <Island>
+                <p className="hello-island">
+                    Hydrated in your browser at {new Date().toLocaleTimeString()}.
+                </p>
+            </Island>
         </section>
     );
 }

package/examples/basic/client/styles/main.css

@@ -625,3 +625,51 @@ code {
     pointer-events: none;
     z-index: 0;
 }
+
+/* ── Edge SSR demo (/hello) ── */
+.hello {
+    max-width: 640px;
+    margin: 0 auto;
+    padding: 2rem 1rem;
+}
+
+.hello h1 {
+    background: linear-gradient(90deg, var(--accent), var(--accent3));
+    -webkit-background-clip: text;
+    background-clip: text;
+    color: transparent;
+}
+
+.hello-blurb {
+    color: var(--muted);
+}
+
+.hello-services {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    display: grid;
+    gap: 0.5rem;
+}
+
+.hello-services li {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0.6rem 0.9rem;
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+}
+
+.hello-region {
+    color: var(--accent3);
+    font-family: ui-monospace, monospace;
+    font-size: 0.85rem;
+}
+
+.hello-island {
+    margin-top: 1.5rem;
+    color: var(--muted);
+    font-size: 0.85rem;
+}

package/examples/basic/server/SsrHelloRender.ts

@@ -0,0 +1,97 @@
+/**
+ * The edge-SSR `render` for the `/hello` route (`client/routes/hello.tsx`).
+ *
+ * In the single-wasm build, SSR is part of the normal server build: the
+ * compiler renders the opted-in route into a template-with-holes and emits the
+ * typed `Slot` enum + `HASH` as an AUTO-GENERATED module at `server/_ssr/hello.slots.ts`
+ * (gitignored, regenerated every build — never hand-edited); this function
+ * fills only the holes per request, and the edge splices the values into the
+ * template. The host never re-runs React — it just stamps the values envelope
+ * this returns into the precompiled template, so the route serves about as fast
+ * as a static file.
+ *
+ * It derives its data from the request, fills the typed `Slot`s on a
+ * `SlotValues`, and self-registers with the `Ssr` router. `main.ts` imports
+ * this module so the server build discovers it (the side-effect `Ssr.register`
+ * call is what wires it in). A render returns `SlotValues` for a path it owns,
+ * or `null` to let the next registered renderer try.
+ *
+ * Hole escaping mirrors React exactly (`setText`/`HtmlBuilder.text` React-escape
+ * for you; `setRaw` is verbatim, so YOU own its sanitisation), which is what
+ * lets the browser hydrate the spliced markup with no re-render.
+ */
+import { HtmlBuilder, Request, SlotValues, Ssr } from 'toiljs/server/runtime';
+// AUTO-GENERATED by the build (the SSR slots pre-pass renders the route's holes
+// into the `Slot` enum + coherence `HASH`). Lives in `server/_ssr/` next to the
+// generated `_emails.ts`, gitignored and regenerated every build — never edited.
+import { HASH, Slot } from './_ssr/hello.slots';
+
+class Service {
+    constructor(
+        public name: string,
+        public region: string,
+    ) {}
+}
+
+/** Pull the greeting target from `?name=...`, defaulting to `world` (matches the
+ * route loader's default). Kept tiny — the point is to show a real per-request
+ * derivation, not a query parser. */
+function greetingName(req: Request): string {
+    const q = req.path.indexOf('?');
+    if (q < 0) return 'world';
+    const query = req.path.substring(q + 1);
+    const parts = query.split('&');
+    for (let i = 0; i < parts.length; i++) {
+        const kv = parts[i];
+        if (kv.startsWith('name=')) {
+            const v = kv.substring(5);
+            return v.length > 0 ? v : 'world';
+        }
+    }
+    return 'world';
+}
+
+function renderHello(req: Request): SlotValues | null {
+    // The guest re-derives WHICH route this is from the path (the template name
+    // is not in the request envelope), exactly as a @rest controller matches its
+    // own prefix. Match `/hello` with or without a query string.
+    if (req.path != '/hello' && !req.path.startsWith('/hello?')) return null;
+
+    const v = new SlotValues(HASH);
+
+    // A text hole: React-escaped (so e.g. `?name=<a>&b` is safe).
+    v.setText(Slot.name, greetingName(req));
+
+    // A raw-HTML hole: inserted verbatim, so the author owns sanitisation. This
+    // is a fixed, trusted blurb (no request data) — matches the route's sample.
+    v.setRaw(Slot.blurb, 'Rendered at the <strong>edge</strong> from a tiny values envelope.');
+
+    // A repeat region: stamp the captured row markup once per item. The row
+    // sub-template is `<li><strong>{svcName}</strong>` +
+    // `<span class="hello-region">{svcRegion}</span></li>`; `text(...)` escapes
+    // each nested hole exactly as React does, so the stamped rows are byte-
+    // identical to a client render.
+    const services: Service[] = [
+        new Service('record', 'us-east'),
+        new Service('unique', 'eu-west'),
+        new Service('counter', 'ap-south'),
+    ];
+    const rows = new HtmlBuilder();
+    for (let i = 0; i < services.length; i++) {
+        const s = services[i];
+        rows.raw('<li><strong>')
+            .text(s.name)
+            .raw('</strong><span class="hello-region">')
+            .text(s.region)
+            .raw('</span></li>');
+    }
+    v.setRepeat(Slot.services, rows);
+
+    return v;
+}
+
+// Side-effect registration: `main.ts` imports this module so the build compiles
+// it in and this renderer joins the SSR router. (In a fully-generated build the
+// compiler injects this registration for auto-discovered routes; the demo wires
+// it explicitly, the documented escape hatch.)
+Ssr.register(renderHello);

package/examples/basic/server/main.ts

@@ -15,6 +15,11 @@ import './routes/EnvDemo';
 import './services/Stats';
 import './services/remotes';
 
+// Edge SSR: importing the render module compiles it in and self-registers its
+// `/hello` renderer with the `Ssr` router (the route opts in via `export const
+// ssr = true` in client/routes/hello.tsx). See server/SsrHelloRender.ts.
+import './SsrHelloRender';
+
 // DO NOT TOUCH THIS.
 Server.handler = () => {
     // ONLY CHANGE THE HANDLER CLASS NAME.

package/examples/basic/server/migrations/GuestEntry.migration.ts

@@ -0,0 +1,39 @@
+/**
+ * A ToilDB data MIGRATION for the guestbook's `GuestEntry` (see ../models/GuestEntry).
+ *
+ * THE CONVENTION: every `@migrate` lives in a `*.migration.ts` file under a
+ * `migrations/` folder (enforced at compile time). The build auto-discovers this
+ * file - nothing imports it - and weaves its transform into `GuestEntry`'s decoder.
+ *
+ * THE STORY: `GuestEntry` started life with just `author` + `message`. Later we
+ * added an `at` timestamp. Without a migration, every entry already written would
+ * fail to decode (its bytes have no `at`). With this file, an OLD entry is decoded
+ * as its original shape and upgraded on READ - lazily, per row, only when touched.
+ * No backfill, no downtime: rows written under the old layout keep working, and a
+ * read rewrites the converged value back so it is paid for at most once.
+ *
+ * Try it under `toiljs dev`: sign the guestbook, then add a field to `GuestEntry`
+ * + extend this transform + rebuild. The entries already on disk (in `.toil/`)
+ * surface their OLD schema_version, so this `@migrate` runs when you `list()` them.
+ */
+
+import { GuestEntry } from '../models/GuestEntry';
+
+/** The ORIGINAL `GuestEntry` layout (v1): no `at` timestamp. Kept so entries on
+ *  disk written under it still decode. One kept shape per past layout. */
+@data
+export class GuestEntryV1 {
+    author: string = '';
+    message: string = '';
+}
+
+/**
+ * Upgrade a v1 entry to the current `GuestEntry`. The DELTA form `(old, into)`
+ * auto-copies the fields the two layouts SHARE (`author`, `message`); we only fill
+ * the field that is new. A migration is a PURE transform - it may not touch the
+ * database (that is a compile error).
+ */
+@migrate
+export function up(old: GuestEntryV1, into: GuestEntry): void {
+    into.at = 0; // unknown for pre-timestamp entries
+}

package/examples/basic/server/streams/Echo.ts

@@ -0,0 +1,49 @@
+/**
+ * A `@stream` protocol handler mounted at `/echo`, running as a RESIDENT wasm box
+ * per WebTransport connection on the Toil edge - distributed across the eligible
+ * L2/L3 nodes and pinned to ONE worker for the connection's lifetime via QUIC
+ * connection-id steering.
+ *
+ * The defining property of a `@stream` (vs a `@rest` handler): the box is
+ * RESIDENT, so instance state PERSISTS across events on the same connection. Here
+ * `count` survives every `@message` because the box is never reset between events
+ * - unlike a `@rest` handler, which is fresh per request. On the client:
+ *
+ *   const stream = await Server.STREAM.echo.connect();
+ *   stream.send(new TextEncoder().encode('hi'));
+ *
+ * Lifecycle hooks: `@connect` (open), `@message` (an inbound frame), `@close`
+ * (graceful close), `@disconnect` (abrupt transport loss).
+ *
+ * NOTE: reading the inbound frame and replying is the NEXT increment (the
+ * `StreamPacket` / `StreamOutbound` message bridge). The intended shape is:
+ *
+ *   @message reply(packet: StreamPacket): StreamOutbound {
+ *     return StreamOutbound.reply(packet.bytes());   // echo the bytes back
+ *   }
+ *
+ * Until that lands, the hooks run on the connection lifecycle; this example counts
+ * frames to demonstrate that the resident box keeps state across them.
+ */
+@stream('echo')
+class Echo {
+    // Resident per-connection state: survives across events (ResetMode::None).
+    private count: i32 = 0;
+
+    @connect
+    onConnect(): void {
+        // A fresh connection: its dedicated box starts the counter at 0.
+        this.count = 0;
+    }
+
+    @message
+    onMessage(): void {
+        // Persists across frames because the box is resident, not reset per event.
+        this.count = this.count + 1;
+    }
+
+    @close
+    onClose(): void {
+        // Graceful close: the per-connection box is torn down after this hook.
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.59",
+    "version": "0.0.61",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -95,6 +95,8 @@
     },
     "scripts": {
         "watch": "tsc -p tsconfig.json --watch",
+        "prepublishOnly": "npm run build",
+        "gen:docs": "node scripts/gen-toil-docs.mjs",
         "build": "npm run build:shared && npm run build:logger && npm run build:io && npm run build:client && npm run build:backend && npm run build:devserver && npm run build:compiler && npm run build:cli",
         "build:shared": "tsc -p tsconfig.shared.json",
         "build:logger": "tsc -p tsconfig.logger.json",
@@ -102,7 +104,7 @@
         "build:io": "tsc -p tsconfig.io.json",
         "build:backend": "tsc -p tsconfig.backend.json",
         "build:devserver": "tsc -p tsconfig.devserver.json",
-        "build:compiler": "tsc -p tsconfig.compiler.json",
+        "build:compiler": "npm run gen:docs && tsc -p tsconfig.compiler.json",
         "build:cli": "tsc -p tsconfig.cli.json --noEmit && esbuild src/cli/index.ts --bundle --platform=node --format=esm --outfile=build/cli/index.js --external:toiljs/*",
         "test": "vitest run --coverage",
         "test:watch": "vitest",
@@ -111,6 +113,7 @@
         "test:server": "asp --config as-pect.config.js --verbose --no-logo",
         "test:server:ci": "asp --config as-pect.config.js --summary --no-logo",
         "test:all": "npm run test && npm run test:server",
+        "prelint": "npm run gen:docs",
         "lint": "eslint src",
         "docs": "typedoc --out docs --tsconfig tsconfig.json --readme README.md --name TOILJS --plugin typedoc-material-theme --themeColor '#cb9820' src",
         "setup": "npm i && npm run build"
@@ -118,12 +121,12 @@
     "dependencies": {
         "@dacely/hyper-express": "6.17.4",
         "@dacely/noble-post-quantum": "^0.6.1",
-        "@noble/curves": "^2.2.0",
         "@dacely/toilscript-loader": "^0.1.0",
-        "@eslint-react/eslint-plugin": "^5.9.1",
+        "@eslint-react/eslint-plugin": "^5.9.2",
         "@eslint/js": "^10.0.1",
-        "@typescript-eslint/utils": "^8.61.1",
-        "@vitejs/plugin-react": "^6.0.2",
+        "@noble/curves": "^2.2.0",
+        "@typescript-eslint/utils": "^8.62.0",
+        "@vitejs/plugin-react": "^6.0.3",
         "eslint-plugin-react-hooks": "^7.1.1",
         "eslint-plugin-react-refresh": "^0.5.3",
         "hash-wasm": "^4.12.0",
@@ -131,9 +134,9 @@
         "nodemailer": "^9.0.1",
         "picocolors": "^1.1.1",
         "sharp": "^0.35.2",
-        "toilscript": "^0.1.36",
-        "typescript-eslint": "^8.61.1",
-        "vite": "^8.0.16",
+        "toilscript": "^0.1.39",
+        "typescript-eslint": "^8.62.0",
+        "vite": "^8.1.0",
         "vite-imagetools": "^10.0.1",
         "vite-plugin-node-polyfills": "^0.28.0"
     },
@@ -170,7 +173,6 @@
         "eslint": "^10.5.0",
         "jsdom": "^29.1.1",
         "micromatch": "^4.0.8",
-        "playwright": "^1.61.0",
         "prettier": "^3.8.4",
         "react": "^19.2.7",
         "react-dom": "^19.2.7",

package/scripts/gen-toil-docs.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * Build-time generator: turns the human Markdown guides in `docs/` into the agent
+ * documentation map (`TOIL_DOCS`) consumed by the compiler.
+ *
+ * `docs/*.md` is the SINGLE SOURCE for both the human docs (the site) and the agent
+ * docs written into a project's `.toil/docs/` on `toiljs dev` / `build` / `create`.
+ * This script reads every published guide, builds `Record<filename, content>`, and
+ * writes a generated TS module that `src/compiler/docs.ts` imports. The generated
+ * file is gitignored and (re)created before `build:compiler`, so the shipped
+ * compiler never reads the filesystem at a user's build time, and the npm package
+ * does not need to carry `docs/`.
+ *
+ * Run: `node scripts/gen-toil-docs.mjs` (wired into `npm run build`).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, '..');
+const docsDir = path.join(repoRoot, 'docs');
+const outFile = path.join(repoRoot, 'src', 'compiler', 'toil-docs.generated.ts');
+
+/**
+ * Guides excluded from the AGENT doc set (still published as human docs):
+ * - `auth-todo.md`: an internal tracking/roadmap doc, not project guidance.
+ * - `README.md`: the human-site docs index; the agent gets `index.md` instead.
+ */
+const EXCLUDE = new Set(['auth-todo.md', 'README.md']);
+
+/**
+ * Stable order for the agent docs. Files not listed here are appended
+ * alphabetically, so adding a new `docs/*.md` is picked up automatically.
+ */
+const ORDER = [
+    'index.md',
+    'getting-started.md',
+    'routing.md',
+    'client.md',
+    'styling.md',
+    'server.md',
+    'ssr.md',
+    'rpc.md',
+    'data.md',
+    'caching.md',
+    'ratelimit.md',
+    'auth.md',
+    'environment.md',
+    'email.md',
+    'cookies.md',
+    'crypto.md',
+    'time.md',
+    'cli.md',
+];
+
+function collect() {
+    const all = fs
+        .readdirSync(docsDir)
+        .filter((f) => f.endsWith('.md') && !EXCLUDE.has(f))
+        .sort();
+    const ordered = [
+        ...ORDER.filter((f) => all.includes(f)),
+        ...all.filter((f) => !ORDER.includes(f)),
+    ];
+    const out = {};
+    for (const name of ordered) {
+        out[name] = fs.readFileSync(path.join(docsDir, name), 'utf8');
+    }
+    return out;
+}
+
+function emit(map) {
+    const entries = Object.entries(map)
+        .map(([name, content]) => `    ${JSON.stringify(name)}: ${JSON.stringify(content)},`)
+        .join('\n');
+    return (
+        '/* eslint-disable */\n' +
+        '// AUTO-GENERATED by scripts/gen-toil-docs.mjs from docs/*.md, do not edit.\n' +
+        '// `docs/*.md` is the single source for both the human docs and these agent docs.\n' +
+        '// Regenerate with `node scripts/gen-toil-docs.mjs` (runs before `build:compiler`).\n' +
+        '\n' +
+        '/** The framework guides written into `.toil/docs/`, keyed by filename, generated from `docs/`. */\n' +
+        'export const TOIL_DOCS: Record<string, string> = {\n' +
+        entries +
+        '\n};\n'
+    );
+}
+
+const map = collect();
+fs.mkdirSync(path.dirname(outFile), { recursive: true });
+fs.writeFileSync(outFile, emit(map));
+console.log(
+    `gen-toil-docs: wrote ${Object.keys(map).length} doc(s) to ` +
+        `${path.relative(repoRoot, outFile)}`,
+);

package/server/runtime/time.ts

@@ -17,13 +17,13 @@
 @global
 export class Time {
     /** Milliseconds since the Unix epoch (the host `Date.now()` value). */
-    static nowMillis(): i64 {
-        return <i64>Date.now();
+    static nowMillis(): u64 {
+        return Date.now();
     }
 
     /** Whole seconds since the Unix epoch (`nowMillis() / 1000`), the unit used
      *  for session and challenge timestamps. */
     static nowSeconds(): u64 {
-        return <u64>(Date.now() / 1000);
+        return Date.now() / 1000;
     }
 }