toiljs 0.0.61 → 0.0.63

package/src/compiler/index.ts

@@ -137,30 +137,42 @@ export async function buildServer(root: string): Promise<void> {
     // (optimization, features, runtime) still come from the toilconfig's `release` target.
     const files = serverEntryFiles(root);
 
-    // A project that declares a `@daemon` (cold surface) compiles the ONE source tree into TWO
-    // artifacts via two toilscript passes (one per --targetMode); a project with only the legacy
-    // request surface keeps the single-artifact path (byte-identical to before). The cold pass
-    // runs FIRST (cheap, no client surface); the hot pass runs LAST because it (re)writes
-    // shared/server.ts via --rpcModule, which the downstream client build imports.
+    // A project that declares a `@daemon` (L4 cold surface) and/or a `@stream` (L2/L3 stream
+    // surface) compiles the ONE source tree into SEPARATE artifacts, one per deployment tier, via
+    // one toilscript pass each; a project with only the legacy request surface keeps the
+    // single-artifact path (byte-identical to before). The three tiers:
+    //   - REQUEST (L1)   `server/main.ts`    + `@rest`/`@service`/`@remote` -> `release.wasm`
+    //   - STREAM  (L2/L3) `server/main.stream.ts` + `@stream`              -> `release-stream.wasm`
+    //   - DAEMON  (L4)   `@daemon`/`@scheduled`                            -> `release-cold.wasm`
+    // toilscript's gating matrix HARD-ERRORS a class compiled under the wrong --targetMode, so each
+    // pass is handed only the files eligible for its tier (`@data`/`@database`/plain helpers are
+    // SHARED into every pass). The request pass runs LAST because it (re)writes shared/server.ts via
+    // --rpcModule, which the downstream client build imports.
     const split = splitSurfaceFiles(root, files);
-    if (split.hasDaemon) {
+    if (split.hasDaemon || split.hasStream) {
         const artifacts = serverArtifacts(root);
-        // toilscript's gating matrix HARD-ERRORS a `@daemon`/`@scheduled` class compiled under
-        // `--targetMode hot` (and a `@rest`/`@stream`/`@service`/`@remote` class under cold). So
-        // each pass is handed only the files eligible for that mode: the cold pass drops hot-only
-        // files, the hot pass drops daemon-only files. `@data`/`@database`/plain files are shared.
-        await runToilscriptPass(root, binJs, split.cold, {
-            mode: 'cold',
-            outFile: artifacts.cold,
-            withRpc: false,
-        });
-        // The hot pass writes the legacy `outFile` (= hotFile alias, AN-1) so the request path
-        // and the dev server's `serverWasmFile` are unchanged; the request box loads it as today.
-        // A daemon-only project (no request/stream surface) has no hot files; skip the hot pass so
-        // toilscript is not handed an empty entry set. The request path then stays idle (no
-        // `handle` export), which is correct for a pure background worker.
-        if (split.hot.length > 0)
-            await runToilscriptPass(root, binJs, split.hot, {
+        // DAEMON (cold) pass: --targetMode cold, no client RPC surface.
+        if (split.hasDaemon)
+            await runToilscriptPass(root, binJs, split.cold, {
+                mode: 'cold',
+                outFile: artifacts.cold,
+                withRpc: false,
+            });
+        // STREAM pass: --targetMode hot into its OWN `release-stream.wasm`, no client RPC surface
+        // (a resident stream box exposes `stream_dispatch`, not the request client surface). Driven
+        // by `server/main.stream.ts` + the `@stream` classes; the request box never loads it.
+        if (split.hasStream && split.stream.length > 0)
+            await runToilscriptPass(root, binJs, split.stream, {
+                mode: 'hot',
+                outFile: artifacts.stream,
+                withRpc: false,
+            });
+        // REQUEST pass: the L1 artifact (= the legacy `outFile`, AN-1), WITH the client RPC surface.
+        // A pure daemon/stream project (no request files) skips it so toilscript is not handed an
+        // empty entry set; the request path then stays idle (no `handle` export), correct for a
+        // background-only worker.
+        if (split.request.length > 0)
+            await runToilscriptPass(root, binJs, split.request, {
                 mode: 'hot',
                 outFile: serverWasmFile(root),
                 withRpc: true,
@@ -168,7 +180,7 @@ export async function buildServer(root: string): Promise<void> {
         return;
     }
 
-    // Legacy single-artifact path (no daemon surface): exactly today's invocation.
+    // Legacy single-artifact path (no daemon/stream surface): exactly today's invocation.
     await runToilscriptPass(root, binJs, files, { mode: null, outFile: null, withRpc: true });
 }
 
@@ -191,54 +203,85 @@ function resolveToilscriptBin(root: string): string {
     }
 }
 
-/** Files classified per target mode for the two-pass build. */
+/** Files classified per deployment TIER for the multi-artifact build. */
 interface SurfaceSplit {
-    /** Whether any file declares a `@daemon` (so a cold pass is needed at all). */
+    /** Whether any file declares a `@daemon` (so a cold/daemon pass is needed at all). */
     readonly hasDaemon: boolean;
-    /** Files eligible for the COLD pass (everything except hot-only request files). */
+    /** Whether any file declares a `@stream` (or is a `*.stream.ts` entry), so a stream pass is needed. */
+    readonly hasStream: boolean;
+    /** Files for the DAEMON (cold) pass: `@daemon`/`@scheduled` surfaces + shared helpers. */
     readonly cold: string[];
-    /** Files eligible for the HOT pass (everything except daemon-only cold files). */
-    readonly hot: string[];
+    /** Files for the STREAM pass: `@stream` surfaces + the `*.stream.ts` entry + shared helpers. */
+    readonly stream: string[];
+    /** Files for the REQUEST pass: `@rest`/`@service`/`@remote` surfaces + the request entry + shared helpers. */
+    readonly request: string[];
 }
 
-/** A `@daemon`/`@scheduled` decorator at line start (a cold-only surface). */
+/** A `@daemon`/`@scheduled` decorator at line start (the L4 cold/daemon surface). */
 const COLD_DECORATOR = /^[ \t]*@(daemon|scheduled)\b/m;
-/** A request/stream-surface decorator at line start (a hot-only surface). */
-const HOT_DECORATOR = /^[ \t]*@(rest|route|stream|service|remote)\b/m;
+/** A `@stream` decorator at line start (the L2/L3 stream surface). */
+const STREAM_DECORATOR = /^[ \t]*@stream\b/m;
+/** A request-surface decorator at line start (`@rest`/`@route`/`@service`/`@remote`, the L1 tier). */
+const REQUEST_DECORATOR = /^[ \t]*@(rest|route|service|remote)\b/m;
+/** A server ENTRY re-exports the runtime WASM entry points; this marks `main.ts` / `main.stream.ts`
+ *  (vs a plain `@data`/helper), so each entry is routed to exactly ONE tier and two entries never
+ *  collide on a duplicate `export *` in the same pass. */
+const RUNTIME_ENTRY = /from\s+['"]toiljs\/server\/runtime\/exports['"]/;
+
+/** True for a STREAM-tier entry by the `*.stream.ts` naming convention (e.g. `main.stream.ts`). */
+function isStreamEntryFile(rel: string): boolean {
+    return rel.endsWith('.stream.ts');
+}
+
+/** True for a COLD/daemon-tier entry by the `*.daemon.ts` naming convention (e.g. `main.daemon.ts`). */
+function isDaemonEntryFile(rel: string): boolean {
+    return rel.endsWith('.daemon.ts');
+}
 
 /**
- * Classify each server source file by the surface decorators it declares, so each toilscript pass
- * is handed only the files valid for its `--targetMode` (toilscript HARD-ERRORS a cold class in
- * the hot artifact and vice versa). A file with a cold-only surface (`@daemon`/`@scheduled` and no
- * hot decorator) is dropped from the hot pass; a file with a hot-only surface is dropped from the
- * cold pass. Shared files (`@data`/`@database`/plain helpers, or a file mixing both surfaces) stay
- * in both passes, matching toilscript's class-level gating which admits `@data`/`@database`
- * everywhere.
+ * Classify each server source file by its deployment TIER, so each toilscript pass is handed only
+ * the files valid for its `--targetMode` (toilscript HARD-ERRORS a class compiled under the wrong
+ * mode). Three tiers:
+ *   - COLD/daemon: a file declaring `@daemon`/`@scheduled` -> `release-cold.wasm`.
+ *   - STREAM (L2/L3): a file declaring `@stream`, OR a `*.stream.ts` entry (`main.stream.ts`) ->
+ *     `release-stream.wasm`.
+ *   - REQUEST (L1): a file declaring `@rest`/`@service`/`@remote`, OR a non-`*.stream.ts` runtime
+ *     ENTRY (`main.ts`) -> `release.wasm`.
+ * A file with NONE of these (a plain `@data`/`@database`/helper) is SHARED into every pass, matching
+ * toilscript's class-level gating. Routing each entry to exactly one tier keeps `release.wasm` free
+ * of `stream_dispatch` and stops two entries re-exporting the runtime in the same pass.
  */
 export function splitSurfaceFiles(root: string, files: string[]): SurfaceSplit {
     let hasDaemon = false;
+    let hasStream = false;
     const cold: string[] = [];
-    const hot: string[] = [];
+    const stream: string[] = [];
+    const request: string[] = [];
     for (const rel of files) {
         let src = '';
         try {
             src = fs.readFileSync(path.join(root, rel), 'utf8');
         } catch {
-            // unreadable: keep it in both passes (let toilscript surface the error).
+            // unreadable: keep it in EVERY pass (let toilscript surface the error).
             cold.push(rel);
-            hot.push(rel);
+            stream.push(rel);
+            request.push(rel);
             continue;
         }
-        const isCold = COLD_DECORATOR.test(src);
-        const isHot = HOT_DECORATOR.test(src);
-        if (isCold) hasDaemon ||= /^[ \t]*@daemon\b/m.test(src);
-        // Drop a file from the hot pass only when it is cold-only (cold surface, no hot surface);
-        // a mixed file stays in both (toilscript gates per class, not per file).
-        if (!(isCold && !isHot)) hot.push(rel);
-        // Drop a file from the cold pass only when it is hot-only.
-        if (!(isHot && !isCold)) cold.push(rel);
+        const isCold = COLD_DECORATOR.test(src) || isDaemonEntryFile(rel);
+        const isStream = STREAM_DECORATOR.test(src) || isStreamEntryFile(rel);
+        const isRequest =
+            REQUEST_DECORATOR.test(src) ||
+            (RUNTIME_ENTRY.test(src) && !isStreamEntryFile(rel) && !isDaemonEntryFile(rel));
+        if (isCold) hasDaemon ||= /^[ \t]*@daemon\b/m.test(src) || isDaemonEntryFile(rel);
+        if (isStream) hasStream = true;
+        // A file with no tier-specific surface is a SHARED helper, compiled into every pass.
+        const shared = !isCold && !isStream && !isRequest;
+        if (isCold || shared) cold.push(rel);
+        if (isStream || shared) stream.push(rel);
+        if (isRequest || shared) request.push(rel);
     }
-    return { hasDaemon, cold, hot };
+    return { hasDaemon, hasStream, cold, stream, request };
 }
 
 interface PassOptions {
@@ -417,32 +460,40 @@ function serverWasmFile(root: string): string {
  *  present in the toilconfig `release` target; otherwise derived from `outFile` by inserting the
  *  mode before the extension (`release.wasm` -> `release-hot.wasm` / `release-cold.wasm`). */
 export interface ServerArtifacts {
-    /** Absolute path to the hot (request/stream) artifact. */
+    /** Absolute path to the hot (request) artifact. */
     readonly hot: string;
     /** Absolute path to the cold (daemon) artifact. */
     readonly cold: string;
+    /** Absolute path to the stream (L2/L3 `@stream`) artifact (`release-stream.wasm`). */
+    readonly stream: string;
 }
 export function serverArtifacts(root: string): ServerArtifacts {
     let out = 'build/server/release.wasm';
     let hot: string | undefined;
     let cold: string | undefined;
+    let stream: string | undefined;
     try {
         const cfg = JSON.parse(fs.readFileSync(path.join(root, 'toilconfig.json'), 'utf8')) as {
-            targets?: Record<string, { outFile?: string; hotFile?: string; coldFile?: string }>;
+            targets?: Record<
+                string,
+                { outFile?: string; hotFile?: string; coldFile?: string; streamFile?: string }
+            >;
         };
         out = cfg.targets?.release?.outFile ?? out;
         hot = cfg.targets?.release?.hotFile;
         cold = cfg.targets?.release?.coldFile;
+        stream = cfg.targets?.release?.streamFile;
     } catch {
         // No readable toilconfig: caller already gated on its existence; keep defaults.
     }
-    const ins = (mode: 'hot' | 'cold'): string => {
+    const ins = (mode: 'hot' | 'cold' | 'stream'): string => {
         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')),
+        stream: path.resolve(root, stream ?? ins('stream')),
     };
 }
 

package/src/compiler/template-build.ts

@@ -29,8 +29,8 @@ import fs from 'node:fs';
 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 { type ComponentType, type Context, createElement, type ReactNode, Suspense } from 'react';
+import { renderToString } from 'react-dom/server';
 import { createServer } from 'vite';
 
 import { type ResolvedToilConfig } from './config.js';
@@ -71,8 +71,13 @@ 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;
+    /** React's `Suspense` from the SAME instance as {@link createElement}, so the
+     * Suspense dehydration markers (`<!--$-->`) emitted match the client's. */
+    Suspense?: typeof Suspense;
 }
 
 export interface TemplateArtifacts {
@@ -86,22 +91,29 @@ export interface TemplateArtifacts {
     slotCount: number;
 }
 
-/** Build the route element tree: layouts (outermost first) wrapping the page,
- * under the loader-data provider. The Suspense/RoutePage wrappers the client
- * adds contribute no DOM, so this reproduces the client's markup. */
+/** Build the route element tree, mirroring the client Router so `renderToString`
+ * emits the SAME Suspense dehydration markers (`<!--$-->`) `hydrateRoot` expects.
+ * The page sits under the loader-data provider inside a route `Suspense`, and EACH
+ * layout (outermost first) gets its own `Suspense`, exactly as `renderMatched` +
+ * `Router` wrap them. Without these markers the client's Suspense boundaries have
+ * nothing to align to and hydration regenerates the whole tree. (The ErrorBoundary
+ * / context wrappers the client adds emit no DOM and no markers, so they are
+ * omitted here.) The `Suspense` component must come from the SAME React as `h`. */
 export function assembleRouteElement(
     Page: ComponentType,
     layouts: ComponentType<{ children?: ReactNode }>[],
     loaderData: unknown,
     loaderContext: Context<unknown> | null,
     h: typeof createElement = createElement,
+    SuspenseComp: typeof Suspense = Suspense,
 ): ReactNode {
     let node: ReactNode = h(Page);
     if (loaderContext) {
         node = h(loaderContext.Provider, { value: loaderData }, node);
     }
+    node = h(SuspenseComp, { fallback: null }, node); // route Suspense (mirrors RoutePage's boundary)
     for (let i = layouts.length - 1; i >= 0; i--) {
-        node = h(layouts[i], null, node);
+        node = h(SuspenseComp, { fallback: null }, h(layouts[i], null, node));
     }
     return node;
 }
@@ -115,16 +127,33 @@ 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 SuspenseComp = input.Suspense ?? Suspense;
     const element = assembleRouteElement(
         input.Page,
         input.layouts,
         input.loaderData,
         input.loaderContext,
         h,
+        SuspenseComp,
     );
     input.setSsrBuild(true);
     let routeHtml: string;
@@ -133,7 +162,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);
@@ -242,6 +271,7 @@ async function renderSsrRoutes(cfg: ResolvedToilConfig, shell: string): Promise<
 
     const client = (await server.ssrLoadModule('toiljs/client')) as unknown as {
         __setSsrBuild: (on: boolean) => void;
+        __setSsrLocation: (path: string | null) => void;
         LoaderDataContext: Context<unknown>;
     };
 
@@ -262,9 +292,12 @@ async function renderSsrRoutes(cfg: ResolvedToilConfig, shell: string): Promise<
     // (`useLocation` -> `useRef`) throws. (`ssrLoadModule('react')` can't be used:
     // Vite's SSR runner cannot evaluate the CJS module -> "module is not defined".)
     const appRequire = createRequire(path.join(cfg.root, 'package.json'));
-    const react = appRequire('react') as { createElement: typeof createElement };
+    const react = appRequire('react') as {
+        createElement: typeof createElement;
+        Suspense: typeof Suspense;
+    };
     const reactDomServer = appRequire('react-dom/server') as {
-        renderToStaticMarkup: typeof renderToStaticMarkup;
+        renderToString: typeof renderToString;
     };
 
     const rendered: RenderedRoute[] = [];
@@ -286,8 +319,9 @@ async function renderSsrRoutes(cfg: ResolvedToilConfig, shell: string): Promise<
                         ? await mod.loader({ params, searchParams: new URLSearchParams() })
                         : undefined;
 
+                const rootLayout = findLayout(cfg);
                 const layoutFiles = [
-                    ...(findLayout(cfg) ? [findLayout(cfg)!] : []),
+                    ...(rootLayout ? [rootLayout] : []),
                     ...findSpecialChain(cfg, r.file, 'layout', false),
                 ];
                 const layouts: ComponentType<{ children?: ReactNode }>[] = [];
@@ -299,6 +333,10 @@ async function renderSsrRoutes(cfg: ResolvedToilConfig, shell: string): Promise<
                 }
 
                 const name = routeTemplateName(r.pattern);
+                // Tell location hooks which URL this template is for, so a NavLink's active
+                // class / aria-current render as they will on the client at this route (else
+                // the `/` default mismatches on hydration). Cleared in `finally`.
+                client.__setSsrLocation(samplePath(r.pattern));
                 const art = extractRouteTemplate({
                     name,
                     Page: mod.default,
@@ -308,7 +346,8 @@ async function renderSsrRoutes(cfg: ResolvedToilConfig, shell: string): Promise<
                     setSsrBuild: client.__setSsrBuild,
                     shell,
                     createElement: react.createElement,
-                    renderToStaticMarkup: reactDomServer.renderToStaticMarkup,
+                    renderToString: reactDomServer.renderToString,
+                    Suspense: react.Suspense,
                 });
                 rendered.push({ pattern: r.pattern, art });
             } catch (err) {
@@ -317,6 +356,8 @@ async function renderSsrRoutes(cfg: ResolvedToilConfig, shell: string): Promise<
                         err instanceof Error ? err.message : String(err)
                     }) — falls back to client rendering`,
                 );
+            } finally {
+                client.__setSsrLocation(null);
             }
         }
     } finally {
@@ -423,6 +464,13 @@ function sampleParams(pattern: string): Record<string, string> {
     return params;
 }
 
+/** The concrete pathname for a route pattern, dynamic segments filled with the same `sample`
+ * value {@link sampleParams} uses, so location-dependent markup renders consistently. Static
+ * routes return their pattern unchanged. */
+function samplePath(pattern: string): string {
+    return pattern.replace(/[:*]+([A-Za-z0-9_]+)/g, 'sample');
+}
+
 interface RouteModule {
     default: ComponentType;
     ssr?: boolean;

package/test/daemon-build.test.ts

@@ -84,9 +84,10 @@ describe('serverArtifacts path derivation', () => {
         const a = serverArtifacts(tmp);
         expect(a.hot).toBe(join(tmp, 'build/server/release-hot.wasm'));
         expect(a.cold).toBe(join(tmp, 'build/server/release-cold.wasm'));
+        expect(a.stream).toBe(join(tmp, 'build/server/release-stream.wasm'));
     });
 
-    it('honors explicit hotFile/coldFile when present', () => {
+    it('honors explicit hotFile/coldFile/streamFile when present', () => {
         writeFileSync(
             join(tmp, 'toilconfig.json'),
             JSON.stringify({
@@ -95,6 +96,7 @@ describe('serverArtifacts path derivation', () => {
                         outFile: 'build/server/release.wasm',
                         hotFile: 'out/hot.wasm',
                         coldFile: 'out/cold.wasm',
+                        streamFile: 'out/stream.wasm',
                     },
                 },
             }),
@@ -102,6 +104,7 @@ describe('serverArtifacts path derivation', () => {
         const a = serverArtifacts(tmp);
         expect(a.hot).toBe(join(tmp, 'out/hot.wasm'));
         expect(a.cold).toBe(join(tmp, 'out/cold.wasm'));
+        expect(a.stream).toBe(join(tmp, 'out/stream.wasm'));
     });
 });
 
@@ -131,30 +134,46 @@ describe('splitSurfaceFiles per-pass classification', () => {
         return rels;
     }
 
-    it('drops daemon-only files from the hot pass and hot-only files from the cold pass', () => {
+    it('routes each surface to its tier (request/stream/cold) and shares plain helpers', () => {
         const rels = lay({
             'server/jobs.ts': '@daemon\nclass J { @scheduled("1s") t(): void {} }\n',
             'server/api.ts': '@rest\nclass A {}\n',
+            'server/chat.ts': "@stream('chat')\nclass C {}\n",
             'server/model.ts': '@data\nclass M {}\n',
             'server/util.ts': 'export function helper(): i32 { return 1; }\n',
         });
         const split = splitSurfaceFiles(tmp, rels);
         expect(split.hasDaemon).toBe(true);
-        // hot pass: everything except the daemon-only jobs.ts.
-        expect(split.hot.sort()).toEqual(
-            ['server/api.ts', 'server/model.ts', 'server/util.ts'].sort(),
-        );
-        // cold pass: everything except the hot-only api.ts.
-        expect(split.cold.sort()).toEqual(
-            ['server/jobs.ts', 'server/model.ts', 'server/util.ts'].sort(),
-        );
+        expect(split.hasStream).toBe(true);
+        const shared = ['server/model.ts', 'server/util.ts'];
+        // Each surface goes to ONLY its tier; the @data/helper files are shared into all three.
+        expect(split.cold.sort()).toEqual(['server/jobs.ts', ...shared].sort());
+        expect(split.stream.sort()).toEqual(['server/chat.ts', ...shared].sort());
+        expect(split.request.sort()).toEqual(['server/api.ts', ...shared].sort());
+    });
+
+    it('routes entries by the *.stream.ts / *.daemon.ts naming and the runtime-export request entry', () => {
+        const RT = "export * from 'toiljs/server/runtime/exports';\n";
+        const rels = lay({
+            'server/main.ts': RT, // runtime entry, not *.stream/.daemon -> request
+            'server/main.stream.ts': RT, // *.stream.ts -> stream (not request, despite the runtime export)
+            'server/main.daemon.ts': "import './daemon/Jobs';\n", // *.daemon.ts -> cold
+        });
+        const split = splitSurfaceFiles(tmp, rels);
+        expect(split.hasStream).toBe(true);
+        expect(split.hasDaemon).toBe(true);
+        // Each entry is routed to EXACTLY one tier (so two entries never collide on `export *`).
+        expect(split.request).toEqual(['server/main.ts']);
+        expect(split.stream).toEqual(['server/main.stream.ts']);
+        expect(split.cold).toEqual(['server/main.daemon.ts']);
     });
 
-    it('keeps a file that mixes both surfaces in both passes', () => {
+    it('keeps a file that mixes daemon + request surfaces in both of those passes (not stream)', () => {
         const rels = lay({ 'server/both.ts': '@daemon\nclass J {}\n@rest\nclass A {}\n' });
         const split = splitSurfaceFiles(tmp, rels);
-        expect(split.hot).toContain('server/both.ts');
         expect(split.cold).toContain('server/both.ts');
+        expect(split.request).toContain('server/both.ts');
+        expect(split.stream).not.toContain('server/both.ts');
     });
 });
 

package/test/ssr-hydration.test.tsx

@@ -0,0 +1,122 @@
+// @vitest-environment jsdom
+/**
+ * Real-hydration test: drive the actual build (`extractRouteTemplate`, which now
+ * renders with `renderToString`) -> splice -> `hydrateRoot` path in jsdom and
+ * assert there is NO hydration mismatch and the content is present. This is the
+ * failure users hit ("server rendered HTML didn't match the client"), and it
+ * covers the things that broke it:
+ *   - "text + hole + text" (`Hello, <Hole>{name}</Hole>!`): needs the `<!-- -->`
+ *     text-boundary markers `renderToString` emits.
+ *   - an `<img>`, whose React 19 auto-preload `<link>` must be kept OUT of `#root`.
+ *   - an `<Island>`, which must be empty on the first (hydration) render.
+ *   - the Suspense dehydration markers (`<!--$-->`): `assembleRouteElement` wraps the
+ *     route (and each layout) in `Suspense`, so we hydrate through the SAME `Suspense`
+ *     structure the client Router renders. Remove that wrapping and this test fails
+ *     with "server rendered HTML didn't match the client", the exact regression.
+ */
+import { act, Suspense } from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import { describe, expect, it, vi } from 'vitest';
+
+import { Hole, Island, RawHtml, __setSsrBuild } from '../src/client/ssr/markers';
+import { extractRouteTemplate } from '../src/compiler/template-build';
+import { reactEscapeHtml, spliceTemplate } from '../src/compiler/template';
+
+const NAME = 'world';
+const BLURB = 'Rendered at the <strong>edge</strong>.';
+
+function Page(): React.ReactElement {
+    return (
+        <main>
+            <img src="/images/logo.svg" alt="logo" width={28} height={28} />
+            <h1>
+                Hello, <Hole id="name">{NAME}</Hole>!
+            </h1>
+            <p>
+                <RawHtml id="blurb" html={BLURB} as="span" />
+            </p>
+            <Island>
+                <span className="isle">island-only</span>
+            </Island>
+        </main>
+    );
+}
+
+const SHELL =
+    '<!doctype html><html><head><title>t</title></head><body><div id="root"></div></body></html>';
+
+/** Build the template (renderToString + strip), splice per-slot values, return #root inner HTML. */
+function serverRootHtml(): string {
+    const art = extractRouteTemplate({
+        name: 'hyd',
+        Page,
+        layouts: [],
+        loaderData: null,
+        loaderContext: null,
+        setSsrBuild: __setSsrBuild,
+        shell: SHELL,
+    });
+    const valueFor: Record<number, Buffer> = {
+        0: Buffer.from(reactEscapeHtml(NAME), 'utf8'), // name (text)
+        1: Buffer.from(BLURB, 'utf8'), // blurb (raw)
+    };
+    const nSlots = art.slotsBin.readUInt16LE(44);
+    const inserts: { offset: number; value: Buffer }[] = [];
+    let o = 46;
+    for (let i = 0; i < nSlots; i++) {
+        inserts.push({ offset: art.slotsBin.readUInt32LE(o), value: valueFor[art.slotsBin.readUInt16LE(o + 4)] });
+        o += 8;
+    }
+    const full = spliceTemplate(art.tmpl, inserts).toString('utf8');
+    const m = /<div id="root">([\s\S]*?)<\/div><template id="__toil_ssr">/.exec(full);
+    if (!m) throw new Error('could not isolate #root');
+    return m[1];
+}
+
+describe('ssr hydration (real hydrateRoot, no mismatch)', () => {
+    it('hydrates the spliced server markup cleanly and reveals the island after mount', async () => {
+        const rootInner = serverRootHtml();
+        expect(rootInner).not.toContain('rel="preload"'); // preload hoisted to <head>, not #root
+        expect(rootInner).not.toContain('island-only'); // island empty server-side
+        expect(rootInner).toContain('Hello, '); // text hole filled
+        expect(rootInner).toContain('<strong>edge</strong>'); // raw hole verbatim
+
+        document.body.innerHTML = `<div id="root">${rootInner}</div>`;
+        const rootEl = document.getElementById('root')!;
+
+        const recoverable: string[] = [];
+        const consoleErrors: string[] = [];
+        const spy = vi.spyOn(console, 'error').mockImplementation((...a: unknown[]) => {
+            consoleErrors.push(a.map(String).join(' '));
+        });
+        try {
+            await act(async () => {
+                // Hydrate through the route Suspense `assembleRouteElement` emits (layouts: []
+                // here -> just the route boundary), so the client's Suspense markers line up
+                // with the server's. This is what the real client Router does.
+                hydrateRoot(
+                    rootEl,
+                    (
+                        <Suspense fallback={null}>
+                            <Page />
+                        </Suspense>
+                    ),
+                    {
+                        onRecoverableError: (e) => recoverable.push(String(e)),
+                    },
+                );
+            });
+        } finally {
+            spy.mockRestore();
+        }
+
+        const noise = /hydrat|did not match|server rendered|didn't match/i;
+        expect(recoverable.filter((e) => noise.test(e))).toEqual([]);
+        expect(consoleErrors.filter((e) => noise.test(e))).toEqual([]);
+
+        // Content survived hydration (not regenerated/blanked); the island revealed after mount.
+        expect(rootEl.querySelector('h1')?.textContent).toBe('Hello, world!');
+        expect(rootEl.querySelector('.isle')?.textContent).toBe('island-only');
+        expect(rootEl.querySelector('img')?.getAttribute('src')).toBe('/images/logo.svg');
+    });
+});

package/test/ssr-render.test.ts

@@ -172,9 +172,11 @@ describe.skipIf(!built)('edge SSR guest render (real single-wasm build)', () =>
         }
         const out = spliceTemplate(tmpl, inserts).toString('utf8');
 
-        // The spliced section is well-formed and carries every filled hole.
+        // The spliced section is well-formed and carries every filled hole. The
+        // `<!-- -->` around `world` are React's text-boundary markers (renderToString
+        // emits them so hydrateRoot can align the `name` hole between "Hello, " and "!").
         expect(out).toContain(
-            '<section class="hello"><h1>Hello, world!</h1>' +
+            '<section class="hello"><h1>Hello, <!-- -->world<!-- -->!</h1>' +
                 '<p class="hello-blurb"><span>Rendered at the <strong>edge</strong> ' +
                 'from a tiny values envelope.</span></p>' +
                 '<h2>Service snapshot</h2>' +