npm - toiljs - Versions diffs - 0.0.60 → 0.0.62 - Mend

toiljs 0.0.60 → 0.0.62

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (120) hide show

package/.github/workflows/ci.yml +31 -0
package/CHANGELOG.md +17 -0
package/build/cli/.tsbuildinfo +1 -1
package/build/cli/index.js +2 -2
package/build/client/.tsbuildinfo +1 -1
package/build/client/index.d.ts +1 -1
package/build/client/index.js +1 -1
package/build/client/routing/mount.js +11 -26
package/build/client/ssr/markers.d.ts +1 -0
package/build/client/ssr/markers.js +9 -2
package/build/compiler/.tsbuildinfo +1 -1
package/build/compiler/config.d.ts +21 -0
package/build/compiler/config.js +35 -0
package/build/compiler/docs.d.ts +2 -1
package/build/compiler/docs.js +33 -304
package/build/compiler/index.d.ts +13 -0
package/build/compiler/index.js +113 -21
package/build/compiler/template-build.d.ts +23 -3
package/build/compiler/template-build.js +120 -30
package/build/compiler/toil-docs.generated.d.ts +1 -0
package/build/compiler/toil-docs.generated.js +20 -0
package/build/devserver/.tsbuildinfo +1 -1
package/build/devserver/daemon/catalog.d.ts +26 -0
package/build/devserver/daemon/catalog.js +48 -0
package/build/devserver/daemon/cron.d.ts +4 -0
package/build/devserver/daemon/cron.js +50 -0
package/build/devserver/daemon/host.d.ts +37 -0
package/build/devserver/daemon/host.js +94 -0
package/build/devserver/daemon/index.d.ts +34 -0
package/build/devserver/daemon/index.js +241 -0
package/build/devserver/db/catalog.d.ts +2 -1
package/build/devserver/db/catalog.js +44 -44
package/build/devserver/db/database.d.ts +27 -11
package/build/devserver/db/database.js +539 -169
package/build/devserver/db/index.d.ts +1 -1
package/build/devserver/db/index.js +1 -1
package/build/devserver/db/routeKinds.d.ts +8 -0
package/build/devserver/db/routeKinds.js +139 -0
package/build/devserver/db/types.d.ts +64 -1
package/build/devserver/db/types.js +33 -1
package/build/devserver/index.d.ts +10 -0
package/build/devserver/index.js +7 -0
package/build/devserver/mstore/store.d.ts +18 -0
package/build/devserver/mstore/store.js +82 -0
package/build/devserver/runtime/host.d.ts +6 -0
package/build/devserver/runtime/host.js +45 -1
package/build/devserver/runtime/module.d.ts +1 -0
package/build/devserver/runtime/module.js +27 -1
package/build/devserver/server.d.ts +6 -0
package/build/devserver/server.js +59 -0
package/build/devserver/ssr.d.ts +25 -0
package/build/devserver/ssr.js +114 -0
package/build/devserver/wasm/sections.d.ts +2 -0
package/build/devserver/wasm/sections.js +42 -0
package/build/devserver/wasm/surface.d.ts +18 -0
package/build/devserver/wasm/surface.js +41 -0
package/docs/README.md +4 -4
package/docs/auth-todo.md +6 -6
package/docs/caching.md +5 -5
package/docs/cli.md +15 -0
package/docs/client.md +40 -0
package/docs/crypto.md +4 -4
package/docs/data.md +6 -6
package/docs/email.md +28 -28
package/docs/environment.md +10 -10
package/docs/index.md +26 -0
package/docs/ratelimit.md +10 -10
package/docs/routing.md +2 -2
package/docs/server.md +61 -0
package/docs/ssr.md +561 -113
package/docs/styling.md +22 -0
package/docs/time.md +1 -1
package/eslint.config.js +10 -1
package/examples/basic/client/components/Header.tsx +3 -0
package/examples/basic/client/routes/features/actions.tsx +0 -2
package/examples/basic/client/routes/hello.tsx +89 -19
package/examples/basic/client/styles/main.css +48 -0
package/examples/basic/server/SsrHelloRender.ts +97 -0
package/examples/basic/server/main.ts +5 -0
package/examples/basic/server/streams/Echo.ts +49 -0
package/package.json +12 -10
package/scripts/gen-toil-docs.mjs +96 -0
package/src/cli/create.ts +2 -2
package/src/client/index.ts +1 -1
package/src/client/routing/mount.tsx +19 -31
package/src/client/ssr/markers.tsx +33 -4
package/src/compiler/config.ts +88 -2
package/src/compiler/docs.ts +47 -308
package/src/compiler/index.ts +236 -32
package/src/compiler/ssr-codegen.ts +1 -1
package/src/compiler/template-build.ts +271 -53
package/src/compiler/toil-docs.generated.ts +26 -0
package/src/devserver/daemon/catalog.ts +120 -0
package/src/devserver/daemon/cron.ts +87 -0
package/src/devserver/daemon/host.ts +224 -0
package/src/devserver/daemon/index.ts +349 -0
package/src/devserver/db/catalog.ts +61 -53
package/src/devserver/db/database.ts +613 -149
package/src/devserver/db/index.ts +1 -1
package/src/devserver/db/routeKinds.ts +147 -0
package/src/devserver/db/types.ts +65 -2
package/src/devserver/index.ts +12 -0
package/src/devserver/mstore/store.ts +121 -0
package/src/devserver/runtime/host.ts +92 -1
package/src/devserver/runtime/module.ts +35 -1
package/src/devserver/server.ts +101 -0
package/src/devserver/ssr.ts +166 -0
package/src/devserver/wasm/sections.ts +59 -0
package/src/devserver/wasm/surface.ts +88 -0
package/test/daemon-build.test.ts +198 -0
package/test/daemon-catalog.test.ts +265 -0
package/test/daemon-emulation.test.ts +216 -0
package/test/devserver-database.test.ts +396 -5
package/test/email-preview.test.ts +6 -1
package/test/fixtures/daemon-app.ts +56 -0
package/test/global-setup.ts +17 -0
package/test/ssr-hydration.test.tsx +107 -0
package/test/ssr-render.test.ts +96 -27
package/test/ssr-template.test.tsx +47 -2
package/vitest.config.ts +3 -0

package/src/compiler/template-build.ts CHANGED Viewed

@@ -14,6 +14,15 @@
  * `Slot` enum + `HASH`. A route (or layout) that throws under static markup
  * (e.g. it uses router hooks outside the supported subset) is skipped with a
  * warning and falls back to pure client rendering.
+ *
+ * The `Slot` enum + `HASH` is also what the SERVER `render` imports, so it must
+ * exist BEFORE the server compiles. The build therefore runs the render in two
+ * passes: a slots PRE-PASS (`extractServerSlots`, before the server build) emits
+ * the server-importable `<server>/_ssr/<name>.slots.ts` so toilscript can compile
+ * the `render`; the FINAL pass (`extractTemplates`, after the Vite client build)
+ * rewrites it against the real built shell so the `HASH` is authoritative, and
+ * reports whether it rotated so the caller can recompile the server once. This is
+ * what makes a clean build need ZERO hand-maintained slots.
  */
 import fs from 'node:fs';
@@ -21,7 +30,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 import { type ComponentType, type Context, createElement, type ReactNode } from 'react';
-import { renderToStaticMarkup } from 'react-dom/server';
+import { renderToString } from 'react-dom/server';
 import { createServer } from 'vite';
 import { type ResolvedToilConfig } from './config.js';
@@ -62,8 +71,10 @@ export interface RouteRenderInput {
      * React copies leaves the hook dispatcher null ("Cannot read properties of
      * null (reading 'useRef')"). */
     createElement?: typeof createElement;
-    /** `renderToStaticMarkup` paired with {@link createElement}'s React. */
-    renderToStaticMarkup?: typeof renderToStaticMarkup;
+    /** `renderToString` paired with {@link createElement}'s React. We use it (NOT
+     * `renderToStaticMarkup`) because hydration needs the `<!-- -->` text-node
+     * boundary markers it emits, so `hydrateRoot` can align "text + hole" runs. */
+    renderToString?: typeof renderToString;
 }
 export interface TemplateArtifacts {
@@ -106,10 +117,25 @@ export function injectIntoShell(shell: string, routeHtml: string): string {
     return shell.replace(ROOT_DIV, `<div id="root">${routeHtml}</div>${SSR_MARKER}`);
 }
+/**
+ * React 19 auto-emits hoistable resource tags into `<head>` on the client (it
+ * adds a `<link rel="preload">` for an `<img>`, and hoists `<title>` / `<meta>`),
+ * but the string renderer emits them INLINE in the route fragment. Left in the
+ * spliced `#root` template they would not appear in the client's hydrated `#root`
+ * (the client puts them in `<head>`), so `hydrateRoot` reports a mismatch. Strip
+ * them from the route fragment; the shell already carries the document head, and
+ * the client re-adds its own resource hints. Only the fragment is stripped. */
+function stripHoistedResourceTags(html: string): string {
+    return html
+        .replace(/<link\b[^>]*>/gi, '')
+        .replace(/<meta\b[^>]*>/gi, '')
+        .replace(/<title\b[^>]*>[\s\S]*?<\/title>/gi, '');
+}
 /** Render one route to its template artifacts (pure given its inputs). */
 export function extractRouteTemplate(input: RouteRenderInput): TemplateArtifacts {
     const h = input.createElement ?? createElement;
-    const render = input.renderToStaticMarkup ?? renderToStaticMarkup;
+    const render = input.renderToString ?? renderToString;
     const element = assembleRouteElement(
         input.Page,
         input.layouts,
@@ -124,7 +150,7 @@ export function extractRouteTemplate(input: RouteRenderInput): TemplateArtifacts
     } finally {
         input.setSsrBuild(false);
     }
-    const full = injectIntoShell(input.shell, routeHtml);
+    const full = injectIntoShell(input.shell, stripHoistedResourceTags(routeHtml));
     const extracted: Extracted = extractFromHtml(full);
     const ids = assignSlotIds(extracted.slots);
     const hash = coherenceHash(extracted.tmpl, extracted.slots);
@@ -146,46 +172,81 @@ export function writeTemplateArtifacts(ssrDir: string, art: TemplateArtifacts):
     fs.writeFileSync(path.join(ssrDir, `${art.name}.slots.ts`), art.slotsModule);
 }
-/** A file-safe, identifier-ish name for a route pattern (`/u/:name` -> `u_name`). */
-export function routeTemplateName(pattern: string): string {
-    const n = pattern.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
-    return n.length > 0 ? n : 'index';
+/**
+ * The server source dir (where toilscript-compiled modules live): the dir of the first toilconfig
+ * entry, else `<root>/server`. Mirrors the same resolution in `emails.ts` (`_emails.ts` lives here).
+ */
+function serverDir(root: string): string {
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(root, 'toilconfig.json'), 'utf8')) as {
+            entries?: unknown;
+        };
+        const first = Array.isArray(cfg.entries)
+            ? cfg.entries.find((e): e is string => typeof e === 'string')
+            : undefined;
+        if (first) return path.dirname(path.resolve(root, first));
+    } catch {
+        // fall through to the default
+    }
+    return path.join(root, 'server');
 }
-/** Synthesize a sample param set for a pattern's dynamic segments. */
-function sampleParams(pattern: string): Record<string, string> {
-    const params: Record<string, string> = {};
-    for (const m of pattern.matchAll(/[:*]+([A-Za-z0-9_]+)/g)) {
-        params[m[1]] = 'sample';
+/**
+ * The build-owned dir that holds the GENERATED, server-importable `<name>.slots.ts` modules
+ * (the `Slot` enum + `HASH` the guest `render` imports). It sits inside the server source tree so
+ * toilscript compiles it, named `_ssr` to match the generated `_emails.ts` convention, and is
+ * gitignored + regenerated every build — never hand-edited. The server `render` imports
+ * `./_ssr/<name>.slots`.
+ */
+export function serverSlotsDir(root: string): string {
+    return path.join(serverDir(root), '_ssr');
+}
+/**
+ * (Re)write the generated `<server>/_ssr/<name>.slots.ts` module(s) the server `render` imports.
+ * Returns the map of `name -> module source` actually on disk afterwards, so the caller can detect
+ * whether a later authoritative extraction changed the `HASH` and a server recompile is needed.
+ * Only rewrites a file whose content actually changed (keeps mtimes stable for the dev watcher).
+ */
+export function writeServerSlotsModules(
+    root: string,
+    modules: { name: string; slotsModule: string }[],
+): Map<string, string> {
+    const dir = serverSlotsDir(root);
+    const written = new Map<string, string>();
+    if (modules.length === 0) return written;
+    fs.mkdirSync(dir, { recursive: true });
+    for (const m of modules) {
+        const file = path.join(dir, `${m.name}.slots.ts`);
+        let prev: string | null = null;
+        try {
+            prev = fs.readFileSync(file, 'utf8');
+        } catch {
+            // first build for this route: no prior module
+        }
+        if (prev !== m.slotsModule) fs.writeFileSync(file, m.slotsModule);
+        written.set(m.name, m.slotsModule);
     }
-    return params;
+    return written;
 }
-interface RouteModule {
-    default: ComponentType;
-    ssr?: boolean;
-    loader?: (args: { params: Record<string, string>; searchParams: URLSearchParams }) => unknown;
+/** A rendered SSR route plus the artifacts the build emits for it. */
+interface RenderedRoute {
+    pattern: string;
+    art: TemplateArtifacts;
 }
 /**
- * Render every `export const ssr = true` route to `<outDir>/_ssr/<name>.{tmpl,
- * slots,slots.ts}` + a `templates.json` index, and copy the `.tmpl`/`.slots`
- * into the edge host bundle at `hosts/<host>/_tmpl/`. Returns the patterns
- * generated. Skips (with a warning) any route that throws under static markup.
+ * Spin up a short-lived Vite SSR server, render every `export const ssr = true` route under its
+ * layout chain (with sample loader data, in sentinel mode) against `shell`, and return the
+ * per-route artifacts. Shared by the pre-pass (`extractServerSlots`, slots only) and the final
+ * `extractTemplates` (full artifacts). A route (or layout) that throws under static markup is
+ * skipped with a warning and omitted from the result, so it falls back to client rendering.
  */
-export async function extractTemplates(
-    cfg: ResolvedToilConfig,
-    hostName = 'edge',
-): Promise<string[]> {
+async function renderSsrRoutes(cfg: ResolvedToilConfig, shell: string): Promise<RenderedRoute[]> {
     const routes = scanRoutes(cfg.routesAbsDir).filter((r) => r.slot === undefined && !r.intercept);
     if (routes.length === 0) return [];
-    const outDir = path.resolve(cfg.root, cfg.outDir);
-    const stashed = path.join(cfg.toilDir, 'shell.html');
-    const shellPath = fs.existsSync(stashed) ? stashed : path.join(outDir, 'index.html');
-    if (!fs.existsSync(shellPath)) return [];
-    const shell = fs.readFileSync(shellPath, 'utf8');
     const warn = (msg: string): void => {
         process.stderr.write(`  toil: SSR ${msg}\n`);
     };
@@ -220,14 +281,10 @@ export async function extractTemplates(
     const appRequire = createRequire(path.join(cfg.root, 'package.json'));
     const react = appRequire('react') as { createElement: typeof createElement };
     const reactDomServer = appRequire('react-dom/server') as {
-        renderToStaticMarkup: typeof renderToStaticMarkup;
+        renderToString: typeof renderToString;
     };
-    const ssrDir = path.join(outDir, '_ssr');
-    const hostsTmplDir = path.join(cfg.root, 'hosts', hostName, '_tmpl');
-    const generated: string[] = [];
-    const index: { route: string; name: string; hash: string }[] = [];
+    const rendered: RenderedRoute[] = [];
     try {
         for (const r of routes) {
             let mod: RouteModule;
@@ -268,20 +325,9 @@ export async function extractTemplates(
                     setSsrBuild: client.__setSsrBuild,
                     shell,
                     createElement: react.createElement,
-                    renderToStaticMarkup: reactDomServer.renderToStaticMarkup,
+                    renderToString: reactDomServer.renderToString,
                 });
-                writeTemplateArtifacts(ssrDir, art);
-                fs.mkdirSync(hostsTmplDir, { recursive: true });
-                fs.copyFileSync(
-                    path.join(ssrDir, `${name}.tmpl`),
-                    path.join(hostsTmplDir, `${name}.tmpl`),
-                );
-                fs.copyFileSync(
-                    path.join(ssrDir, `${name}.slots`),
-                    path.join(hostsTmplDir, `${name}.slots`),
-                );
-                index.push({ route: r.pattern, name, hash: art.hash.toString('hex') });
-                generated.push(r.pattern);
+                rendered.push({ pattern: r.pattern, art });
             } catch (err) {
                 warn(
                     `skipped ${r.pattern} (render failed: ${
@@ -293,6 +339,178 @@ export async function extractTemplates(
     } finally {
         await server.close();
     }
+    return rendered;
+}
+/**
+ * Resolve the HTML shell to splice routes into. The authoritative shell is the BUILT (post-Vite)
+ * `index.html`, whose hashed `<script>`/`<link>` tags are part of the template and therefore the
+ * coherence `HASH`. `preferBuilt` (the final extraction) demands it; the slots PRE-PASS (which runs
+ * before Vite) falls back to the previous build's shell when present (so an unchanged rebuild's
+ * pre-pass `HASH` already matches the final one and no server recompile is needed), and finally to
+ * the un-built `.toil/index.html` template on a first clean build. Returns `null` when no shell
+ * exists at all (no client build yet and no template), so the caller no-ops.
+ */
+function resolveShell(cfg: ResolvedToilConfig, preferBuilt: boolean): string | null {
+    const outDir = path.resolve(cfg.root, cfg.outDir);
+    const builtIndex = path.join(outDir, 'index.html');
+    const stashed = path.join(cfg.toilDir, 'shell.html');
+    const templateIndex = path.join(cfg.toilDir, 'index.html');
+    const order = preferBuilt
+        ? [stashed, builtIndex]
+        : // Pre-pass (before Vite): use a prior build's shell if it exists so the HASH is stable
+          // across rebuilds; otherwise the generated (un-built) template, which still yields the
+          // correct Slot ids (the final pass reconciles the HASH).
+          [builtIndex, stashed, templateIndex];
+    for (const p of order) {
+        if (fs.existsSync(p)) return fs.readFileSync(p, 'utf8');
+    }
+    return null;
+}
+/**
+ * SLOTS PRE-PASS (runs BEFORE the server build): render every `ssr = true` route to its `Slot`
+ * enum + `HASH` and write the server-importable `<server>/_ssr/<name>.slots.ts` module(s), so the
+ * server `render` can import them when toilscript compiles it. On a clean build no `.slots.ts`
+ * exists yet, so this is what bootstraps it; on a rebuild it refreshes them. The `Slot` ids are
+ * always correct (they depend only on the route's hole structure); the `HASH` is final only when a
+ * prior build's shell is reused, so the final `extractTemplates` reconciles it (and the caller
+ * recompiles the server if it rotated). Returns the modules written keyed by route name.
+ */
+export async function extractServerSlots(cfg: ResolvedToilConfig): Promise<Map<string, string>> {
+    const shell = resolveShell(cfg, false);
+    if (shell === null) return new Map();
+    const rendered = await renderSsrRoutes(cfg, shell);
+    return writeServerSlotsModules(
+        cfg.root,
+        rendered.map((r) => ({ name: r.art.name, slotsModule: r.art.slotsModule })),
+    );
+}
+/** One SSR route's in-memory dev template: the spliceable `.tmpl` plus its
+ * top-level slot insertion points (numeric id -> byte offset), parsed from the
+ * `.slots` manifest. Used by the dev server to serve SSR without a prod build. */
+export interface DevSsrTemplate {
+    pattern: string;
+    name: string;
+    tmpl: Buffer;
+    entries: { id: number; offset: number }[];
+}
+/**
+ * Render every `ssr = true` route against the given (live, Vite-transformed) dev
+ * `shell` into an in-memory template + slot offsets, for the dev server to splice
+ * the guest `render` values into. Unlike {@link extractTemplates} this has NO
+ * side effects (it writes nothing and does not touch `server/_ssr` or the host
+ * bundle); the dev server builds together with the guest, so there is no hash to
+ * reconcile. Returns `[]` when no route opts in.
+ */
+export async function extractDevSsrTemplates(
+    cfg: ResolvedToilConfig,
+    shell: string,
+): Promise<DevSsrTemplate[]> {
+    const rendered = await renderSsrRoutes(cfg, shell);
+    return rendered.map(({ pattern, art }) => {
+        // Parse the `.slots` manifest: 46-byte header (n_slots at offset 44),
+        // then 8-byte entries (u32 offset, u16 id, u8 kind, u8 reserved).
+        const bin = art.slotsBin;
+        const n = bin.readUInt16LE(44);
+        const entries: { id: number; offset: number }[] = [];
+        let o = 46;
+        for (let i = 0; i < n; i++) {
+            entries.push({ offset: bin.readUInt32LE(o), id: bin.readUInt16LE(o + 4) });
+            o += 8;
+        }
+        return { pattern, name: art.name, tmpl: art.tmpl, entries };
+    });
+}
+/** A file-safe, identifier-ish name for a route pattern (`/u/:name` -> `u_name`). */
+export function routeTemplateName(pattern: string): string {
+    const n = pattern.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    return n.length > 0 ? n : 'index';
+}
+/** Synthesize a sample param set for a pattern's dynamic segments. */
+function sampleParams(pattern: string): Record<string, string> {
+    const params: Record<string, string> = {};
+    for (const m of pattern.matchAll(/[:*]+([A-Za-z0-9_]+)/g)) {
+        params[m[1]] = 'sample';
+    }
+    return params;
+}
+interface RouteModule {
+    default: ComponentType;
+    ssr?: boolean;
+    loader?: (args: { params: Record<string, string>; searchParams: URLSearchParams }) => unknown;
+}
+/** The outcome of the final {@link extractTemplates} pass. */
+export interface ExtractResult {
+    /** The route patterns that produced a template. */
+    readonly generated: string[];
+    /**
+     * Whether the AUTHORITATIVE `<server>/_ssr/<name>.slots.ts` module(s) just written differ from
+     * the ones the server was already compiled against (`priorServerSlots`). True means the `HASH`
+     * (or `Slot` ids) rotated after the server build, so the server must be recompiled to bake the
+     * correct `HASH` (otherwise the host rejects the guest's stale hash as a deploy skew).
+     */
+    readonly serverSlotsChanged: boolean;
+}
+/**
+ * FINAL pass (runs AFTER the client/Vite build): render every `export const ssr = true` route to
+ * `<outDir>/_ssr/<name>.{tmpl,slots,slots.ts}` + a `templates.json` index, copy the `.tmpl`/`.slots`
+ * into the edge host bundle at `hosts/<host>/_tmpl/`, AND (re)write the server-importable
+ * `<server>/_ssr/<name>.slots.ts` module(s) — now against the real built shell, so the `HASH` is
+ * authoritative. Skips (with a warning) any route that throws under static markup.
+ *
+ * `priorServerSlots` is the module map the slots PRE-PASS wrote (what the server was compiled
+ * against); compared against the authoritative modules here to report whether a server recompile is
+ * needed (see {@link ExtractResult.serverSlotsChanged}).
+ */
+export async function extractTemplates(
+    cfg: ResolvedToilConfig,
+    hostName = 'edge',
+    priorServerSlots: Map<string, string> = new Map(),
+): Promise<ExtractResult> {
+    const shell = resolveShell(cfg, true);
+    if (shell === null) return { generated: [], serverSlotsChanged: false };
+    const rendered = await renderSsrRoutes(cfg, shell);
+    const outDir = path.resolve(cfg.root, cfg.outDir);
+    const ssrDir = path.join(outDir, '_ssr');
+    const hostsTmplDir = path.join(cfg.root, 'hosts', hostName, '_tmpl');
+    const generated: string[] = [];
+    const index: { route: string; name: string; hash: string }[] = [];
+    for (const { pattern, art } of rendered) {
+        writeTemplateArtifacts(ssrDir, art);
+        fs.mkdirSync(hostsTmplDir, { recursive: true });
+        fs.copyFileSync(
+            path.join(ssrDir, `${art.name}.tmpl`),
+            path.join(hostsTmplDir, `${art.name}.tmpl`),
+        );
+        fs.copyFileSync(
+            path.join(ssrDir, `${art.name}.slots`),
+            path.join(hostsTmplDir, `${art.name}.slots`),
+        );
+        index.push({ route: pattern, name: art.name, hash: art.hash.toString('hex') });
+        generated.push(pattern);
+    }
+    // Write the AUTHORITATIVE server-importable slots module(s) (the real built-shell HASH) and
+    // detect whether they changed since the pre-pass the server was compiled against.
+    const authoritative = writeServerSlotsModules(
+        cfg.root,
+        rendered.map((r) => ({ name: r.art.name, slotsModule: r.art.slotsModule })),
+    );
+    let serverSlotsChanged = false;
+    for (const [name, mod] of authoritative) {
+        if (priorServerSlots.get(name) !== mod) serverSlotsChanged = true;
+    }
     if (generated.length > 0) {
         fs.mkdirSync(ssrDir, { recursive: true });
@@ -303,5 +521,5 @@ export async function extractTemplates(
             }\n`,
         );
     }
-    return generated;
+    return { generated, serverSlotsChanged };
 }