toiljs 0.0.62 → 0.0.63

package/src/compiler/template-build.ts

@@ -29,7 +29,7 @@ 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 { type ComponentType, type Context, createElement, type ReactNode, Suspense } from 'react';
 import { renderToString } from 'react-dom/server';
 import { createServer } from 'vite';
 
@@ -75,6 +75,9 @@ export interface RouteRenderInput {
      * `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 {
@@ -88,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;
 }
@@ -136,12 +146,14 @@ function stripHoistedResourceTags(html: string): string {
 export function extractRouteTemplate(input: RouteRenderInput): TemplateArtifacts {
     const h = input.createElement ?? createElement;
     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;
@@ -259,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>;
     };
 
@@ -279,7 +292,10 @@ 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 {
         renderToString: typeof renderToString;
     };
@@ -303,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 }>[] = [];
@@ -316,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,
@@ -326,6 +347,7 @@ async function renderSsrRoutes(cfg: ResolvedToilConfig, shell: string): Promise<
                     shell,
                     createElement: react.createElement,
                     renderToString: reactDomServer.renderToString,
+                    Suspense: react.Suspense,
                 });
                 rendered.push({ pattern: r.pattern, art });
             } catch (err) {
@@ -334,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 {
@@ -440,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

@@ -4,13 +4,17 @@
  * 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 three things that broke 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 } from 'react';
+import { act, Suspense } from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { describe, expect, it, vi } from 'vitest';
 
@@ -87,9 +91,20 @@ describe('ssr hydration (real hydrateRoot, no mismatch)', () => {
         });
         try {
             await act(async () => {
-                hydrateRoot(rootEl, <Page />, {
-                    onRecoverableError: (e) => recoverable.push(String(e)),
-                });
+                // 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();

package/test/ssr-template.test.tsx

@@ -356,10 +356,12 @@ describe('ssr build orchestration', () => {
 
         const tmpl = art.tmpl.toString('utf8');
         // Full document with the layout + page scaffold spliced into #root, holes removed.
-        // The `<!-- -->` after `@` is React's text-boundary marker (renderToString emits
-        // it so hydrateRoot can align the `username` hole); the hole text itself is stripped.
+        // `<!--$-->` / `<!--/$-->` are the Suspense dehydration markers `assembleRouteElement`
+        // emits by wrapping each layout AND the route in `Suspense` (mirroring the client
+        // Router), so `hydrateRoot` can align its Suspense boundaries. The `<!-- -->` after `@`
+        // is React's text-boundary marker for the `username` hole; the hole text is stripped.
         expect(tmpl).toContain(
-            '<div id="root"><div class="app"><main><h1>@<!-- --></h1><div></div><ul></ul></main></div></div>',
+            '<div id="root"><!--$--><div class="app"><!--$--><main><h1>@<!-- --></h1><div></div><ul></ul></main><!--/$--></div><!--/$--></div>',
         );
         expect(tmpl).toContain('<template id="__toil_ssr"></template>');
         expect(tmpl).toContain('/assets/app-abc123.js'); // bootstrap script preserved

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

@@ -1,49 +0,0 @@
-/**
- * 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.
-    }
-}