toiljs 0.0.60 → 0.0.62

package/build/compiler/docs.js

@@ -1,5 +1,37 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { TOIL_DOCS } from './toil-docs.generated.js';
+export { TOIL_DOCS };
+const DOC_SUMMARIES = {
+    'index.md': 'overview and project layout',
+    'getting-started.md': 'the two halves, build/dev, and the request lifecycle',
+    'routing.md': 'file-based routing, nested layouts, loading / error files',
+    'client.md': 'the `Toil` global, Link / NavLink, router hooks',
+    'styling.md': 'CSS / Sass / Less / Stylus / Tailwind (via `toiljs configure`)',
+    'server.md': 'the toilscript server target, `@data` / `@remote` / `@rest`',
+    'ssr.md': 'server-side rendering (`ssr = true`, hole markers, the server `render`)',
+    'rpc.md': '`@service` / `@remote` and the generated typed client',
+    'data.md': 'the `@data` decorator and the binary codec',
+    'caching.md': 'the `@cache` decorator and `Response.cache(...)`',
+    'ratelimit.md': 'the `@ratelimit` decorator',
+    'auth.md': '`@auth` guards, `@user`, sessions, the client half',
+    'environment.md': '`Environment.get` / `getSecure` config + secrets',
+    'email.md': '`EmailService`, templates, provider config',
+    'cookies.md': 'the `Cookie` builder, `SecureCookies`, signing / encryption',
+    'crypto.md': 'the synchronous `crypto` global and `crypto.subtle`',
+    'time.md': '`Time.nowMillis()` / `Time.nowSeconds()`',
+    'cli.md': 'toiljs CLI commands',
+};
+function docTitle(content) {
+    const m = content.match(/^#\s+(.+)$/m);
+    return m ? m[1].trim() : '';
+}
+const DOC_POINTERS = Object.keys(TOIL_DOCS)
+    .map((name) => {
+    const summary = DOC_SUMMARIES[name] ?? docTitle(TOIL_DOCS[name]);
+    return `- \`.toil/docs/${name}\`${summary ? `, ${summary}` : ''}`;
+})
+    .join('\n');
 const POINTER_BODY = `# toiljs, AI assistant guide
 
 This is a **toiljs** project, a full-stack React framework (React + Vite client, file-based
@@ -8,13 +40,7 @@ routing, and a toilscript→WebAssembly server).
 **Before editing this project, read the generated documentation in \`.toil/docs/\`.** It describes
 the conventions you must follow:
 
-- \`.toil/docs/index.md\`, overview and project layout
-- \`.toil/docs/routing.md\`, file-based routing, nested layouts, loading / error files
-- \`.toil/docs/client.md\`, the \`Toil\` global, Link / NavLink, router hooks
-- \`.toil/docs/styling.md\`, CSS / Sass / Less / Stylus / Tailwind (via \`toiljs configure\`)
-- \`.toil/docs/server.md\`, the toilscript server target
-- \`.toil/docs/ssr.md\`, server-side rendering (\`ssr = true\`, hole markers, the server \`render\`)
-- \`.toil/docs/cli.md\`, toiljs CLI commands
+${DOC_POINTERS}
 
 \`.toil/docs/\` is regenerated by toiljs; do not edit it by hand. This pointer file is yours to edit.
 `;
@@ -43,303 +69,6 @@ export function aiHelperFiles(ids) {
     }
     return out;
 }
-function doc(lines) {
-    return lines.join('\n') + '\n';
-}
-export const TOIL_DOCS = {
-    'index.md': doc([
-        '# toiljs',
-        '',
-        'A full-stack React framework: a Vite-bundled client SPA with file-based routing, plus a',
-        'toilscript-to-WebAssembly server target.',
-        '',
-        '## Project layout',
-        '',
-        '- `client/`, the app: `routes/` (file-based), `layout.tsx`, `components/`, `styles/`,',
-        '  `public/`, and `toil.tsx` (the entry that calls `Toil.mount`).',
-        '- `server/`, the toilscript → WASM target (`@main` entry), compiled by `toilscript`.',
-        '  `@data`/`@remote`/`@service` here generate the typed client `Server` API (see `server.md`).',
-        '- `toil.config.ts`, configuration via `defineConfig` (`toiljs.config.ts` also works).',
-        '- Generated, gitignored, do not edit: `.toil/` (working dir), `toil-env.d.ts` (ambient',
-        '  globals), `toil-routes.d.ts` (typed routes), `shared/server.ts` (the typed RPC module,',
-        '  emitted by the server build; import `@data` classes from `shared/server`).',
-        '',
-        '## Key ideas',
-        '',
-        '- `Toil` is a native global (no import): `Toil.Link`, `Toil.useRouter`, `Toil.useLoaderData`,',
-        '  etc. The IO classes (`FastMap`, `FastSet`, `DataWriter`, `DataReader`), `parseError`, and the',
-        '  generated `Server` RPC surface are globals too.',
-        '- Scripts: `npm run dev` (HMR), `npm run build` (→ `build/client` + `build/server`),',
-        '  `npm start` (self-host the build).',
-        '',
-        'See `routing.md`, `client.md`, `styling.md`, `server.md`, `ssr.md`, `cli.md`.',
-    ]),
-    'routing.md': doc([
-        '# Routing',
-        '',
-        'File-based, under `client/routes/`. A file path maps to a URL.',
-        '',
-        '## Route files',
-        '',
-        '- `index.tsx` → `/`, `about.tsx` → `/about`, `blog/index.tsx` → `/blog`',
-        '- `[id].tsx` → dynamic `/:id`, read with `Toil.useParams<{ id: string }>()`',
-        '- `[...slug].tsx` → catch-all (1+ segments); `[[...slug]].tsx` → optional catch-all (0+)',
-        '- `(group)/` → route group: groups files / scopes a layout, adds no URL segment',
-        '',
-        '## Special files',
-        '',
-        '- `layout.tsx`, wraps the routes beneath it. Root `client/layout.tsx` wraps everything;',
-        '  nested `routes/**/layout.tsx` compose inside it.',
-        '- `loading.tsx`, Suspense fallback shown while a route (chunk + loader) loads',
-        '- `error.tsx`, error boundary; receives `{ error, reset }` (`Toil.RouteErrorProps`)',
-        '- `client/404.tsx`, shown when no route matches',
-        '',
-        '## Data loaders',
-        '',
-        'Export `loader` from a route; it runs on navigation, in parallel with the chunk, and the',
-        'page suspends until it resolves (so `loading.tsx` shows). Read it with `useLoaderData`:',
-        '',
-        '    export const loader = async ({ params, searchParams }: Toil.LoaderArgs) => {',
-        '        return fetch(`/api/post/${params.id}`).then((r) => r.json());',
-        '    };',
-        '    export default function Post() {',
-        '        const post = Toil.useLoaderData<{ title: string }>();',
-        '        return <h1>{post.title}</h1>;',
-        '    }',
-        '',
-        '`Toil.useRouter().refresh()` re-runs loaders.',
-        '',
-        '## Server rendering',
-        '',
-        'Add `export const ssr = true` to render a route on the server (real first-paint HTML + SEO,',
-        'then hydration) with near-static speed. See `ssr.md`.',
-        '',
-        '## Navigation',
-        '',
-        '- `Toil.Link` / `Toil.NavLink` (adds an active class) / `Toil.useRouter()`',
-        '  (push / replace / back / forward / refresh / prefetch)',
-        '- `Toil.useParams`, `usePathname`, `useSearchParams`, `useNavigationPending`',
-        '- Hrefs are type-checked against your routes, a typo is a compile error.',
-    ]),
-    'client.md': doc([
-        '# 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:',
-        '',
-        '    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`)',
-        '- 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.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',
-        '',
-        '    Toil.useHead({',
-        '        title: "Blog",',
-        '        titleTemplate: "%s, MyApp",',
-        '        meta: [{ name: "description", content: "..." }],',
-        '    });',
-    ]),
-    'styling.md': doc([
-        '# 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:',
-        '',
-        '    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`.',
-    ]),
-    'server.md': doc([
-        '# Server (toilscript → WebAssembly)',
-        '',
-        '`server/` is the toilscript source, compiled to WebAssembly by `toilscript`.',
-        '',
-        '- `server/main.ts`, the `@main` entry, exported as the WASM `main`.',
-        '- `server/index.ts`, your functions.',
-        '- `server/tsconfig.json`, extends `toilscript/std/assembly.json` (AssemblyScript/toilscript',
-        '  globals like `i32`, not the DOM), so editors resolve server types correctly.',
-        '- `npm run build:server` (or `npm run build`) emits `build/server/release.wasm` and',
-        '  regenerates `shared/server.ts` (the typed client RPC module).',
-        '',
-        '## Typed RPC (`@data` / `@remote` / `@service`)',
-        '',
-        'Tag server code and the build generates a typed client `Server` surface:',
-        '',
-        '- `@data class X {}`, a serializable struct. Generates a client class with the same fields',
-        '  plus `encode`/`decode`; construct it on the client: `import { X } from "shared/server"`.',
-        '- `@remote function f(a: T): R`, a client-callable endpoint, becomes `Server.f(a)`.',
-        '- `@service class S { @remote m(...) {} }`, namespaces methods: `Server.s.m(...)`.',
-        '',
-        'On the client, `Server` is a global (no import) and fully typed; every call is async',
-        '(`Promise<R>`). Inputs/outputs are scalars, arrays, or `@data` classes, both directions.',
-        '',
-        'Note: the client↔server transport is not wired yet, so calling a `Server` method throws',
-        'until it lands; the typed surface + codec are generated and ready.',
-        '',
-        '## HTTP REST (`@rest` / `@route`)',
-        '',
-        'Tag a class `@rest` and its methods with a verb to expose a real HTTP API. Unlike RPC,',
-        'the generated client is working `fetch` code (it is just HTTP).',
-        '',
-        '- `@rest("api") class Todos {}`, mounts the controller at `/api` (bare `@rest` → `/`).',
-        '- `@get("/todos/:id")` / `@post` / `@put` / `@del` / `@patch` / `@head` / `@options`, verb',
-        '  shortcuts; or `@route({ method: Methods.GET, path: "/todos", stream: DataStream.JSON })`.',
-        '- A method takes an optional `@data` body + an optional `ctx: RouteContext` (path params via',
-        '  `ctx.param("id")`, `ctx.query(...)`, `ctx.header(...)`). It returns either a `@data` type,',
-        '  which the compiler encodes per `stream` (`DataStream.JSON` default, or `DataStream.Binary`,',
-        '  lossless for large `u64`/bignum), or a `Response` for full control - custom status and',
-        '  headers, e.g. `Response.json(value.toJSON().toString()).setHeader("cache-control", "no-store")`',
-        '  or `Response.notFound()`. (The editor sees the compiler-injected `@data` `toJSON`/`encode`',
-        '  members via the toilscript plugin, so serializing into a `Response` is editor-clean.)',
-        '',
-        'Each `@rest` class self-registers; dispatch them from your handler - it composes, it never',
-        'takes over `handle()`:',
-        '',
-        '```ts',
-        'import { ToilHandler, Request, Response, Rest } from "toiljs/server/runtime";',
-        'export class App extends ToilHandler {',
-        '    public handle(req: Request): Response {',
-        '        const hit = Rest.dispatch(req); // try every @rest controller',
-        '        if (hit != null) return hit;',
-        '        return Response.notFound();     // your own logic / static fallback',
-        '    }',
-        '}',
-        '```',
-        '',
-        'For a REST-only project, `Server.handler = () => new RestHandler()` does the same with no',
-        'boilerplate. On the client: `Server.REST.todos.getTodo({ params: { id } })` (see client.md).',
-    ]),
-    'ssr.md': doc([
-        '# Server-side rendering (SSR)',
-        '',
-        'Opt a route into SSR with `export const ssr = true`. toiljs renders the page ONCE at build',
-        'time into a template with holes; at request time the server fills only the dynamic holes and',
-        'serves the page, then the browser hydrates it in place. The page is never re-rendered per',
-        'request, so an SSR route is served about as fast as a static file while still delivering real',
-        'first-paint HTML and SEO.',
-        '',
-        '## Marking the holes',
-        '',
-        'Wrap the dynamic bits of the page in hole markers from `toiljs/client`. They are transparent',
-        'in the browser (they just render their children); only the build and the server treat them',
-        'specially, so the same component is your normal client UI.',
-        '',
-        '- `<Hole id="name">{value}</Hole>`, a text hole (the value is HTML-escaped for you).',
-        '- `<RawHtml id="bio" html={s} />`, a raw-HTML block (you own sanitisation, like',
-        '  `dangerouslySetInnerHTML`).',
-        '- `<Repeat id="rows" each={items}>{(item) => <li>...</li>}</Repeat>`, a repeated region (a',
-        '  list); the row markup is captured once and stamped per item.',
-        '- `<Island>{...}</Island>`, a client-only escape hatch: empty in the server HTML, rendered',
-        '  after hydration (so it gets no first paint or SEO). Put router-hook-driven or otherwise',
-        '  non-server-safe bits here.',
-        '',
-        '    import { Hole, Repeat, RawHtml, useLoaderData } from "toiljs/client";',
-        '    export const ssr = true;',
-        '    export const loader = ({ params }: Toil.LoaderArgs) => loadProfile(params.name);',
-        '    export default function Profile() {',
-        '        const d = useLoaderData<typeof loader>();',
-        '        return (',
-        '            <main>',
-        '                <h1>@<Hole id="username">{d.username}</Hole></h1>',
-        '                <RawHtml id="bio" html={d.bioHtml} />',
-        '                <ul>',
-        '                    <Repeat id="posts" each={d.posts}>',
-        '                        {(p) => <li><Hole id="title">{p.title}</Hole></li>}',
-        '                    </Repeat>',
-        '                </ul>',
-        '            </main>',
-        '        );',
-        '    }',
-        '',
-        '## The server render',
-        '',
-        'For each SSR route the build emits a typed `Slot` enum and a coherence hash (a',
-        '`<route>.slots.ts` module). In the server you write a `render(req)` that fills each slot from',
-        'the request and data, using the `SlotValues` API, and register it with `Ssr`:',
-        '',
-        '```ts',
-        'import { Request, SlotValues, HtmlBuilder, Ssr } from "toiljs/server/runtime";',
-        'import { Slot, HASH } from "./profile.slots";',
-        '',
-        'function renderProfile(req: Request): SlotValues | null {',
-        '    if (!req.path.startsWith("/u/")) return null; // not this route',
-        '    const v = new SlotValues(HASH);',
-        '    v.setText(Slot.username, usernameFor(req));   // escaped',
-        '    v.setRaw(Slot.bio, bioHtml);                  // verbatim',
-        '    const rows = new HtmlBuilder();',
-        '    for (let i = 0; i < posts.length; i++) rows.raw("<li>").text(posts[i]).raw("</li>");',
-        '    v.setRepeat(Slot.posts, rows);                // stamped rows',
-        '    return v;',
-        '}',
-        'Ssr.register(renderProfile);',
-        '```',
-        '',
-        '`SlotValues`: `setText` (escaped), `setRaw` (verbatim), `setAttr` (attribute value),',
-        '`setRepeat` (a stamped `HtmlBuilder`), plus `setHeader` and `setStatus`. The hole values you',
-        'return are filled into the template and the page is served; the browser then hydrates against',
-        'the same data, so the markup matches with no client re-render.',
-        '',
-        '## Rules of thumb',
-        '',
-        '- An SSR route (and the layouts above it) must render under static markup. Use the hole',
-        '  markers and `useLoaderData`; move anything that needs router hooks or browser-only APIs into',
-        '  an `<Island>`. A route that cannot render this way is skipped at build (with a warning) and',
-        '  simply falls back to normal client rendering.',
-        '- Hole values are HTML-escaped exactly as React escapes them, so hydration is byte-for-byte',
-        "  clean. Keep a repeat row's structure the same across items (only the leaf hole values vary).",
-        '- Build output for an SSR route lands in `build/client/_ssr/` (the template + its manifest)',
-        '  alongside the generated `Slot` module; routes without `ssr = true` are unaffected.',
-    ]),
-    'cli.md': doc([
-        '# 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`).',
-        '- `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.',
-    ]),
-};
 export function writeDocs(toilDir) {
     const dir = path.join(toilDir, 'docs');
     fs.mkdirSync(dir, { recursive: true });

package/build/compiler/index.d.ts

@@ -1,5 +1,18 @@
 import { type ViteDevServer } from 'vite';
 import type { RunningBackend } from 'toiljs/backend';
+export declare const SURFACE_DECORATOR: RegExp;
+export declare function buildServer(root: string): Promise<void>;
+interface SurfaceSplit {
+    readonly hasDaemon: boolean;
+    readonly cold: string[];
+    readonly hot: string[];
+}
+export declare function splitSurfaceFiles(root: string, files: string[]): SurfaceSplit;
+export interface ServerArtifacts {
+    readonly hot: string;
+    readonly cold: string;
+}
+export declare function serverArtifacts(root: string): ServerArtifacts;
 export interface ToilCommandOptions {
     readonly root?: string;
     readonly port?: number;

package/build/compiler/index.js

@@ -9,9 +9,9 @@ import { loadConfig } from './config.js';
 import { renderEmails } from './emails.js';
 import { generate, TOIL_SERVER_ENV_DTS } from './generate.js';
 import { prerenderStaticParams } from './ssg.js';
-import { extractTemplates } from './template-build.js';
+import { extractDevSsrTemplates, extractServerSlots, extractTemplates, } from './template-build.js';
 import { createViteConfig } from './vite.js';
-const SURFACE_DECORATOR = /^[ \t]*@(data|rest|service|remote)\b/m;
+export const SURFACE_DECORATOR = /^[ \t]*@(data|rest|service|remote|stream|daemon|scheduled)\b/m;
 function toilconfigEntries(root) {
     try {
         const cfg = JSON.parse(fs.readFileSync(path.join(root, 'toilconfig.json'), 'utf8'));
@@ -76,7 +76,7 @@ function serverEntryFiles(root) {
         visit(dir, 0);
     return [...result].sort();
 }
-async function buildServer(root) {
+export async function buildServer(root) {
     if (!fs.existsSync(path.join(root, 'toilconfig.json')))
         return;
     for (const dir of serverDirs(root)) {
@@ -87,37 +87,83 @@ async function buildServer(root) {
         catch {
         }
     }
+    const binJs = resolveToilscriptBin(root);
+    const files = serverEntryFiles(root);
+    const split = splitSurfaceFiles(root, files);
+    if (split.hasDaemon) {
+        const artifacts = serverArtifacts(root);
+        await runToilscriptPass(root, binJs, split.cold, {
+            mode: 'cold',
+            outFile: artifacts.cold,
+            withRpc: false,
+        });
+        if (split.hot.length > 0)
+            await runToilscriptPass(root, binJs, split.hot, {
+                mode: 'hot',
+                outFile: serverWasmFile(root),
+                withRpc: true,
+            });
+        return;
+    }
+    await runToilscriptPass(root, binJs, files, { mode: null, outFile: null, withRpc: true });
+}
+function resolveToilscriptBin(root) {
     const require = createRequire(path.join(root, 'package.json'));
-    let binJs;
     try {
         const pkgPath = require.resolve('toilscript/package.json');
         const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
         const binRel = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.toilscript;
         if (!binRel)
             throw new Error('toilscript declares no bin');
-        binJs = path.join(path.dirname(pkgPath), binRel);
+        return path.join(path.dirname(pkgPath), binRel);
     }
     catch {
         throw new Error("toiljs: this project has a server target (toilconfig.json) but 'toilscript' is not " +
             'installed. Run `npm i -D toilscript`, or remove toilconfig.json for a client-only build.');
     }
-    const files = serverEntryFiles(root);
-    const args = [
-        binJs,
-        ...files,
-        '--target',
-        'release',
-        '--rpcModule',
-        'shared/server.ts',
-        '--disableWarning',
-        '235',
-    ];
-    await new Promise((resolve, reject) => {
+}
+const COLD_DECORATOR = /^[ \t]*@(daemon|scheduled)\b/m;
+const HOT_DECORATOR = /^[ \t]*@(rest|route|stream|service|remote)\b/m;
+export function splitSurfaceFiles(root, files) {
+    let hasDaemon = false;
+    const cold = [];
+    const hot = [];
+    for (const rel of files) {
+        let src = '';
+        try {
+            src = fs.readFileSync(path.join(root, rel), 'utf8');
+        }
+        catch {
+            cold.push(rel);
+            hot.push(rel);
+            continue;
+        }
+        const isCold = COLD_DECORATOR.test(src);
+        const isHot = HOT_DECORATOR.test(src);
+        if (isCold)
+            hasDaemon ||= /^[ \t]*@daemon\b/m.test(src);
+        if (!(isCold && !isHot))
+            hot.push(rel);
+        if (!(isHot && !isCold))
+            cold.push(rel);
+    }
+    return { hasDaemon, cold, hot };
+}
+function runToilscriptPass(root, binJs, files, opts) {
+    const args = [binJs, ...files, '--target', 'release'];
+    if (opts.mode !== null)
+        args.push('--targetMode', opts.mode);
+    if (opts.outFile !== null)
+        args.push('--outFile', opts.outFile);
+    if (opts.withRpc)
+        args.push('--rpcModule', 'shared/server.ts');
+    args.push('--disableWarning', '235');
+    return new Promise((resolve, reject) => {
         const child = spawn(process.execPath, args, { cwd: root, stdio: 'inherit' });
         child.on('error', reject);
         child.on('close', (code) => code === 0
             ? resolve()
-            : reject(new Error(`toilscript server build failed (exit ${String(code)})`)));
+            : reject(new Error(`toilscript ${opts.mode ?? 'release'} build failed (exit ${String(code)})`)));
     });
 }
 function watchServer(cfg, watcher) {
@@ -209,6 +255,27 @@ function serverWasmFile(root) {
     }
     return path.resolve(root, outFile);
 }
+export function serverArtifacts(root) {
+    let out = 'build/server/release.wasm';
+    let hot;
+    let cold;
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(root, 'toilconfig.json'), 'utf8'));
+        out = cfg.targets?.release?.outFile ?? out;
+        hot = cfg.targets?.release?.hotFile;
+        cold = cfg.targets?.release?.coldFile;
+    }
+    catch {
+    }
+    const ins = (mode) => {
+        const ext = path.extname(out);
+        return out.slice(0, ext ? -ext.length : undefined) + '-' + mode + (ext || '.wasm');
+    };
+    return {
+        hot: path.resolve(root, hot ?? ins('hot')),
+        cold: path.resolve(root, cold ?? ins('cold')),
+    };
+}
 async function freeLoopbackPort() {
     return new Promise((resolve, reject) => {
         const probe = net.createServer();
@@ -242,10 +309,12 @@ export async function dev(opts = {}) {
     if (hasServer)
         process.stdout.write(pc.dim('  building the server (toilscript)…') + '\n');
     await renderEmails(cfg);
+    generate(cfg);
+    if (hasServer)
+        await extractServerSlots(cfg);
     await buildServer(cfg.root);
     if (hasServer)
         process.stdout.write(pc.green('  ✓ ') + pc.dim('server built') + '\n');
-    generate(cfg);
     if (!hasServer) {
         const server = await createServer(await createViteConfig(cfg));
         await server.listen();
@@ -260,13 +329,31 @@ export async function dev(opts = {}) {
     });
     const server = await createServer(viteConfig);
     await server.listen();
+    let ssrTemplates = [];
+    try {
+        const rawIndex = fs.readFileSync(path.join(cfg.toilDir, 'index.html'), 'utf8');
+        const devShell = await server.transformIndexHtml('/', rawIndex);
+        ssrTemplates = await extractDevSsrTemplates(cfg, devShell);
+        if (ssrTemplates.length > 0) {
+            process.stdout.write(pc.green('  ✓ ') +
+                pc.dim(`edge SSR: ${String(ssrTemplates.length)} route(s) server-rendered`) +
+                '\n');
+        }
+    }
+    catch (e) {
+        process.stdout.write(pc.yellow('  ! ') + pc.dim(`SSR dev extraction skipped: ${String(e)}`) + '\n');
+    }
     const { startDevServer } = await import('toiljs/devserver');
     const front = await startDevServer({
         root: cfg.root,
         port: cfg.port,
         wasmFile: serverWasmFile(cfg.root),
+        coldWasmFile: serverArtifacts(cfg.root).cold,
+        nodeMode: cfg.nodeMode,
+        daemon: cfg.daemon,
         vite: { host: '127.0.0.1', port: vitePort },
         email: cfg.email ?? undefined,
+        ssrTemplates,
     });
     server.httpServer?.once('close', () => {
         void front.close();
@@ -293,15 +380,20 @@ export async function build(opts = {}) {
     if (hasServer && !opts.serverOnly)
         process.stdout.write(pc.dim('  building the server (toilscript)…') + '\n');
     await renderEmails(cfg);
+    generate(cfg);
+    const priorServerSlots = hasServer ? await extractServerSlots(cfg) : new Map();
     await buildServer(cfg.root);
     if (opts.serverOnly)
         return;
     if (hasServer)
         process.stdout.write(pc.green('  ✓ ') + pc.dim('server built; building the client (vite)…') + '\n');
-    generate(cfg);
     await viteBuild(await createViteConfig(cfg));
     await prerenderStaticParams(cfg);
-    await extractTemplates(cfg);
+    const ssr = await extractTemplates(cfg, 'edge', priorServerSlots);
+    if (ssr.serverSlotsChanged) {
+        process.stdout.write(pc.dim('  SSR template changed; recompiling the server with the new hash…') + '\n');
+        await buildServer(cfg.root);
+    }
 }
 export async function start(opts = {}) {
     const cfg = await loadConfig(opts);

package/build/compiler/template-build.d.ts

@@ -1,5 +1,5 @@
 import { type ComponentType, type Context, createElement, type ReactNode } from 'react';
-import { renderToStaticMarkup } from 'react-dom/server';
+import { renderToString } from 'react-dom/server';
 import { type ResolvedToilConfig } from './config.js';
 export interface RouteRenderInput {
     name: string;
@@ -12,7 +12,7 @@ export interface RouteRenderInput {
     setSsrBuild: (on: boolean) => void;
     shell: string;
     createElement?: typeof createElement;
-    renderToStaticMarkup?: typeof renderToStaticMarkup;
+    renderToString?: typeof renderToString;
 }
 export interface TemplateArtifacts {
     name: string;
@@ -28,5 +28,25 @@ export declare function assembleRouteElement(Page: ComponentType, layouts: Compo
 export declare function injectIntoShell(shell: string, routeHtml: string): string;
 export declare function extractRouteTemplate(input: RouteRenderInput): TemplateArtifacts;
 export declare function writeTemplateArtifacts(ssrDir: string, art: TemplateArtifacts): void;
+export declare function serverSlotsDir(root: string): string;
+export declare function writeServerSlotsModules(root: string, modules: {
+    name: string;
+    slotsModule: string;
+}[]): Map<string, string>;
+export declare function extractServerSlots(cfg: ResolvedToilConfig): Promise<Map<string, string>>;
+export interface DevSsrTemplate {
+    pattern: string;
+    name: string;
+    tmpl: Buffer;
+    entries: {
+        id: number;
+        offset: number;
+    }[];
+}
+export declare function extractDevSsrTemplates(cfg: ResolvedToilConfig, shell: string): Promise<DevSsrTemplate[]>;
 export declare function routeTemplateName(pattern: string): string;
-export declare function extractTemplates(cfg: ResolvedToilConfig, hostName?: string): Promise<string[]>;
+export interface ExtractResult {
+    readonly generated: string[];
+    readonly serverSlotsChanged: boolean;
+}
+export declare function extractTemplates(cfg: ResolvedToilConfig, hostName?: string, priorServerSlots?: Map<string, string>): Promise<ExtractResult>;