toiljs 0.0.34 → 0.0.36

package/test/assembly/ssr.spec.ts

@@ -0,0 +1,94 @@
+// Imports specific SSR modules (not the runtime index, which pulls in the
+// crypto std the as-pect compiler does not ship). These modules are pure
+// (escaping + buffer building + linear-memory encode), so they run under
+// as-pect; the full `render` export is exercised via the example wasm in
+// test/devserver.test.ts.
+import { escapeHtml, escapeJsonForScript } from '../../server/runtime/ssr/escape';
+import { HASH_LEN, HtmlBuilder, SlotKind, SlotValues } from '../../server/runtime/ssr/slots';
+import { encodeValues } from '../../server/runtime/ssr/encode';
+
+function bytesToStr(b: Uint8Array): string {
+    return String.UTF8.decodeUnsafe(changetype<usize>(b.dataStart), b.length);
+}
+
+describe('ssr escape (react-dom byte-identity)', () => {
+    it('passes clean text through unchanged', () => {
+        expect<string>(escapeHtml('hello world')).toStrictEqual('hello world');
+    });
+
+    it('escapes the five React characters with React entities', () => {
+        // React uses &#x27; for the apostrophe and &quot; for the quote.
+        expect<string>(escapeHtml('<a href="x">A&B\'s</a>')).toStrictEqual(
+            '&lt;a href=&quot;x&quot;&gt;A&amp;B&#x27;s&lt;/a&gt;',
+        );
+    });
+
+    it('escapes ampersand first-class (not double-encoding)', () => {
+        expect<string>(escapeHtml('a & b')).toStrictEqual('a &amp; b');
+        expect<string>(escapeHtml('&amp;')).toStrictEqual('&amp;amp;');
+    });
+
+    it('escapes script-context json delimiters', () => {
+        expect<string>(escapeJsonForScript('{"x":"</script>"}')).toStrictEqual(
+            '{"x":"\\u003c/script\\u003e"}',
+        );
+        expect<string>(escapeJsonForScript('{"a":1}')).toStrictEqual('{"a":1}');
+    });
+});
+
+describe('ssr SlotValues', () => {
+    it('escapes text holes and leaves raw holes verbatim', () => {
+        const v = new SlotValues(new StaticArray<u8>(HASH_LEN));
+        v.setText(0, '<b>');
+        v.setRaw(1, '<b>ok</b>');
+        expect<i32>(v.slots.length).toBe(2);
+        expect<i32>(<i32>v.slots[0].kind).toBe(<i32>SlotKind.TEXT);
+        expect<string>(bytesToStr(v.slots[0].bytes)).toStrictEqual('&lt;b&gt;');
+        expect<i32>(<i32>v.slots[1].kind).toBe(<i32>SlotKind.RAW);
+        expect<string>(bytesToStr(v.slots[1].bytes)).toStrictEqual('<b>ok</b>');
+    });
+
+    it('stamps repeat rows by interleaving raw chunks and escaped values', () => {
+        const v = new SlotValues(new StaticArray<u8>(HASH_LEN));
+        const rows = new HtmlBuilder();
+        const items = ['a&b', 'c'];
+        for (let i = 0; i < items.length; i++) {
+            rows.raw('<li>').text(items[i]).raw('</li>');
+        }
+        v.setRepeat(2, rows);
+        expect<i32>(<i32>v.slots[0].kind).toBe(<i32>SlotKind.REPEAT);
+        expect<string>(bytesToStr(v.slots[0].bytes)).toStrictEqual(
+            '<li>a&amp;b</li><li>c</li>',
+        );
+    });
+});
+
+describe('ssr encodeValues wire format', () => {
+    it('round-trips status, hash, and one text slot', () => {
+        const hash = new StaticArray<u8>(HASH_LEN);
+        hash[0] = 0xaa;
+        hash[31] = 0xbb;
+        const v = new SlotValues(hash);
+        v.setStatus(200);
+        v.setText(7, 'hi');
+
+        const buf = new Uint8Array(128);
+        const base = changetype<usize>(buf.dataStart);
+        const n = encodeValues(v, base);
+        // status(2) + hash(32) + n_headers(2) + n_slots(2) + slot[id(2)+kind(1)+len(4)+"hi"(2)]
+        expect<i32>(<i32>n).toBe(2 + 32 + 2 + 2 + 2 + 1 + 4 + 2);
+
+        expect<i32>(<i32>load<u16>(base)).toBe(200); // status
+        expect<i32>(<i32>load<u8>(base + 2)).toBe(0xaa); // hash[0]
+        expect<i32>(<i32>load<u8>(base + 2 + 31)).toBe(0xbb); // hash[31]
+        const afterHash = base + 2 + 32;
+        expect<i32>(<i32>load<u16>(afterHash)).toBe(0); // n_headers
+        expect<i32>(<i32>load<u16>(afterHash + 2)).toBe(1); // n_slots
+        const slot = afterHash + 4;
+        expect<i32>(<i32>load<u16>(slot)).toBe(7); // slot_id
+        expect<i32>(<i32>load<u8>(slot + 2)).toBe(<i32>SlotKind.TEXT); // kind
+        expect<i32>(<i32>load<u32>(slot + 3)).toBe(2); // value_len
+        expect<i32>(<i32>load<u8>(slot + 7)).toBe(0x68); // 'h'
+        expect<i32>(<i32>load<u8>(slot + 8)).toBe(0x69); // 'i'
+    });
+});

package/test/devserver.test.ts

@@ -198,4 +198,46 @@ describe.skipIf(!fs.existsSync(EXAMPLE_WASM))('dispatch into the example server
         const b = get(m, '/json');
         expect(Buffer.from(a.body).toString()).toBe(Buffer.from(b.body).toString());
     });
+
+    // Exercises `SecureCookies` (HMAC-SHA256) end-to-end through the real
+    // toilscript-compiled wasm with the Node-backed `env.crypto.*` host imports:
+    // `/api/cookies/set` seals a signed `__Host-session`, `/api/cookies/inspect`
+    // parses + verifies it. (as-pect cannot compile the crypto std, so this is its coverage.)
+    const sessionCookie = (m: WasmServerModule): string => {
+        const res = get(m, '/api/cookies/set');
+        expect(res.status).toBe(200);
+        const pair = res.headers
+            .filter(([n]) => n === 'set-cookie')
+            .map(([, v]) => v.split(';')[0])
+            .find((v) => v.startsWith('__Host-session='));
+        expect(pair).toBeDefined();
+        return pair!; // "__Host-session=<sealed>"
+    };
+    const inspect = (m: WasmServerModule, cookie: string): string =>
+        Buffer.from(
+            m.dispatch({
+                method: 'GET',
+                path: '/api/cookies/inspect',
+                headers: [
+                    ['host', 'localhost:3000'],
+                    ['cookie', cookie],
+                ],
+                body: new Uint8Array(0),
+            }).body,
+        ).toString();
+
+    it('round-trips a signed cookie (SecureCookies sign -> unsign)', () => {
+        const m = load();
+        expect(inspect(m, sessionCookie(m))).toContain('"session":"user-42"');
+    });
+
+    it('rejects a tampered signed cookie', () => {
+        const m = load();
+        const pair = sessionCookie(m);
+        const eq = pair.indexOf('=');
+        const name = pair.slice(0, eq);
+        const val = pair.slice(eq + 1);
+        const tampered = `${name}=${val[0] === 'A' ? 'B' : 'A'}${val.slice(1)}`;
+        expect(inspect(m, tampered)).toContain('"session":null');
+    });
 });

package/test/ssr-render.test.ts

@@ -0,0 +1,128 @@
+/**
+ * End-to-end guest render: drive the real ToilScript-compiled `render` export
+ * of the SSR example wasm, decode its values envelope, and confirm the guest
+ * produces exactly the bytes the Rust host's `decode_values`/`assemble` expects
+ * (the same wire format proven on the host side in
+ * `toil-backend/src/host/template/assemble.rs`). Closing the loop with the
+ * golden byte-identity test (`ssr-template.test.tsx`), this proves the full
+ * chain: guest values -> splice -> React-identical HTML.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { describe, expect, it } from 'vitest';
+
+import { WasmServerModule } from '../src/devserver/index.js';
+import { spliceTemplate } from '../src/compiler/template.js';
+
+const SSR_WASM = path.resolve(
+    path.dirname(fileURLToPath(import.meta.url)),
+    '../examples/basic/build/server/ssr.wasm',
+);
+
+interface DecodedSlot {
+    slotId: number;
+    kind: number;
+    value: Buffer;
+}
+interface DecodedValues {
+    status: number;
+    hash: Buffer;
+    headers: [string, string][];
+    slots: DecodedSlot[];
+}
+
+/** Mirror of the host `decode_values`: parse the guest values envelope. */
+function decodeValues(buf: Uint8Array): DecodedValues {
+    const b = Buffer.from(buf);
+    let o = 0;
+    const status = b.readUInt16LE(o);
+    o += 2;
+    const hash = b.subarray(o, o + 32);
+    o += 32;
+    const nHeaders = b.readUInt16LE(o);
+    o += 2;
+    const headers: [string, string][] = [];
+    for (let i = 0; i < nHeaders; i++) {
+        const nameLen = b.readUInt16LE(o);
+        o += 2;
+        const valLen = b.readUInt16LE(o);
+        o += 2;
+        const name = b.toString('utf8', o, o + nameLen);
+        o += nameLen;
+        const val = b.toString('utf8', o, o + valLen);
+        o += valLen;
+        headers.push([name, val]);
+    }
+    const nSlots = b.readUInt16LE(o);
+    o += 2;
+    const slots: DecodedSlot[] = [];
+    for (let i = 0; i < nSlots; i++) {
+        const slotId = b.readUInt16LE(o);
+        o += 2;
+        const kind = b.readUInt8(o);
+        o += 1;
+        const valueLen = b.readUInt32LE(o);
+        o += 4;
+        slots.push({ slotId, kind, value: b.subarray(o, o + valueLen) });
+        o += valueLen;
+    }
+    expect(o).toBe(b.length); // no trailing garbage
+    return { status, hash, headers, slots };
+}
+
+describe.skipIf(!fs.existsSync(SSR_WASM))('edge SSR guest render (real wasm)', () => {
+    const load = (): WasmServerModule => {
+        const m = new WasmServerModule(SSR_WASM);
+        m.refresh();
+        return m;
+    };
+    const render = (m: WasmServerModule, p: string): Uint8Array =>
+        m.dispatchRender({
+            method: 'GET',
+            path: p,
+            headers: [['host', 'localhost']],
+            body: new Uint8Array(0),
+        });
+
+    it('produces a values envelope with the compiled-in hash and escaped holes', () => {
+        const d = decodeValues(render(load(), '/hello'));
+        expect(d.status).toBe(200);
+        // The HASH baked into greeting.slots.ts: bytes 0x00..0x1f.
+        expect([...d.hash]).toEqual(Array.from({ length: 32 }, (_, i) => i));
+
+        expect(d.slots.map((s) => `${s.slotId}:${s.kind}`)).toEqual([
+            '0:0', // greeting, text
+            '1:3', // count, repeat
+        ]);
+        // Text hole: React-escaped (& -> &amp;, <> -> entities, mirroring escape.ts).
+        expect(d.slots[0].value.toString('utf8')).toBe('world &amp; &lt;friends&gt;');
+        // Repeat hole: three stamped rows, each escaped.
+        expect(d.slots[1].value.toString('utf8')).toBe(
+            '<li>a &amp; b</li><li>&lt;c&gt;</li><li>d</li>',
+        );
+    });
+
+    it('splices into a template exactly (full guest -> host -> HTML chain)', () => {
+        const d = decodeValues(render(load(), '/hello'));
+        // A template with a greeting hole and a repeat region, holes removed.
+        const tmpl = Buffer.from('<h1>Hello </h1><ul></ul>', 'utf8');
+        const greetingOffset = '<h1>Hello '.length;
+        const repeatOffset = '<h1>Hello </h1><ul>'.length;
+        const out = spliceTemplate(tmpl, [
+            { offset: greetingOffset, value: Buffer.from(d.slots[0].value) },
+            { offset: repeatOffset, value: Buffer.from(d.slots[1].value) },
+        ]);
+        expect(out.toString('utf8')).toBe(
+            '<h1>Hello world &amp; &lt;friends&gt;</h1><ul><li>a &amp; b</li><li>&lt;c&gt;</li><li>d</li></ul>',
+        );
+    });
+
+    it('fails safe (status 500, zero hash, no slots) for an unmatched path', () => {
+        const d = decodeValues(render(load(), '/not-an-ssr-route'));
+        expect(d.status).toBe(500);
+        expect([...d.hash]).toEqual(Array(32).fill(0));
+        expect(d.slots).toHaveLength(0);
+    });
+});

package/test/ssr-template.test.tsx

@@ -0,0 +1,348 @@
+/**
+ * The load-bearing test for edge SSR: prove that the build's
+ * template-with-holes + a guest-style stamp reproduces, BYTE FOR BYTE, what
+ * React renders for the same data. If this holds, the browser's `hydrateRoot`
+ * sees identical markup and hydration is clean.
+ *
+ * Strategy:
+ *   1. Render the component with markers in SENTINEL mode (build) -> strip ->
+ *      `.tmpl` + slot records.
+ *   2. Render the SAME component with REAL data normally -> `expected`.
+ *   3. Simulate the guest: stamp each hole's value (React-escaped text, raw
+ *      verbatim, repeat = stamp the captured row template per real item) and
+ *      splice into the `.tmpl`.
+ *   4. assert stamped === expected.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+
+import { Hole, Island, RawHtml, Repeat, __setSsrBuild } from '../src/client/ssr/markers';
+import { LoaderDataContext, useLoaderData } from '../src/client/routing/loader';
+import {
+    extractRouteTemplate,
+    injectIntoShell,
+    routeTemplateName,
+    writeTemplateArtifacts,
+} from '../src/compiler/template-build';
+import {
+    assignSlotIds,
+    coherenceHash,
+    encodeSlots,
+    extractFromHtml,
+    kindByte,
+    reactEscapeHtml,
+    spliceTemplate,
+    type SlotRecord,
+} from '../src/compiler/template';
+import { generateSlotsModule } from '../src/compiler/ssr-codegen';
+
+interface Post {
+    title: string;
+}
+interface ProfileData {
+    username: string;
+    bioHtml: string;
+    posts: Post[];
+}
+
+function Profile({ d }: { d: ProfileData }): React.ReactElement {
+    return (
+        <main>
+            <h1>
+                @<Hole id="username">{d.username}</Hole>
+            </h1>
+            <RawHtml id="bio" html={d.bioHtml} />
+            <ul>
+                <Repeat id="posts" each={d.posts}>
+                    {(p: Post) => (
+                        <li>
+                            <Hole id="title">{p.title}</Hole>
+                        </li>
+                    )}
+                </Repeat>
+            </ul>
+        </main>
+    );
+}
+
+/** Render under the build sentinel pass (always restores the flag). */
+function renderBuild(el: React.ReactElement): string {
+    __setSsrBuild(true);
+    try {
+        return renderToStaticMarkup(el);
+    } finally {
+        __setSsrBuild(false);
+    }
+}
+
+/** Simulate the guest: produce the bytes for one top-level slot from real data. */
+function stampSlot(slot: SlotRecord, d: ProfileData): Buffer {
+    if (slot.kind === 'text' && slot.id === 'username') {
+        return Buffer.from(reactEscapeHtml(d.username), 'utf8');
+    }
+    if (slot.kind === 'raw' && slot.id === 'bio') {
+        return Buffer.from(d.bioHtml, 'utf8');
+    }
+    if (slot.kind === 'repeat' && slot.id === 'posts') {
+        const rowTmpl = slot.rowTemplate!;
+        const rows: Buffer[] = d.posts.map((p) =>
+            spliceTemplate(
+                rowTmpl,
+                slot.rowSlots!.map((rs) => ({
+                    offset: rs.offset,
+                    value: Buffer.from(reactEscapeHtml(p.title), 'utf8'),
+                })),
+            ),
+        );
+        return Buffer.concat(rows);
+    }
+    throw new Error(`unexpected slot ${slot.id}/${slot.kind}`);
+}
+
+function assemble(tmpl: Buffer, slots: SlotRecord[], d: ProfileData): Buffer {
+    return spliceTemplate(
+        tmpl,
+        slots.map((s) => ({ offset: s.offset, value: stampSlot(s, d) })),
+    );
+}
+
+describe('ssr template extraction', () => {
+    it('strips sentinels and records hole offsets', () => {
+        const sample: ProfileData = {
+            username: 'ada',
+            bioHtml: '<em>hi</em>',
+            posts: [{ title: 'first' }],
+        };
+        const { tmpl, slots } = extractFromHtml(renderBuild(<Profile d={sample} />));
+
+        // Static scaffold = React's own output, holes removed. The <div> from
+        // RawHtml's wrapper is present and empty; the <ul> is empty.
+        expect(tmpl.toString('utf8')).toBe('<main><h1>@</h1><div></div><ul></ul></main>');
+
+        expect(slots.map((s) => `${s.id}:${s.kind}`)).toEqual([
+            'username:text',
+            'bio:raw',
+            'posts:repeat',
+        ]);
+        // Offsets are ascending and land at the right spots.
+        const t = tmpl.toString('utf8');
+        expect(t.slice(0, slots[0].offset)).toBe('<main><h1>@');
+        expect(slots[1].offset).toBe(t.indexOf('<div>') + '<div>'.length);
+        expect(slots[2].offset).toBe(t.indexOf('<ul>') + '<ul>'.length);
+
+        // Repeat captured the single-row sub-template + its nested hole.
+        const posts = slots[2];
+        expect(posts.rowTemplate!.toString('utf8')).toBe('<li></li>');
+        expect(posts.rowSlots!.map((r) => `${r.id}:${r.kind}`)).toEqual(['title:text']);
+        expect(posts.rowSlots![0].offset).toBe('<li>'.length);
+    });
+
+    it('collapses Island to nothing server-side', () => {
+        const html = renderBuild(
+            <div>
+                <Island>
+                    <span>client only</span>
+                </Island>
+            </div>,
+        );
+        expect(extractFromHtml(html).tmpl.toString('utf8')).toBe('<div></div>');
+    });
+});
+
+describe('ssr GOLDEN byte-identity (template+stamp === React render)', () => {
+    const sample: ProfileData = {
+        username: 'ada',
+        bioHtml: '<em>sample</em>',
+        posts: [{ title: 'sample' }],
+    };
+
+    function check(real: ProfileData): void {
+        const { tmpl, slots } = extractFromHtml(renderBuild(<Profile d={sample} />));
+        const stamped = assemble(tmpl, slots, real);
+        const expected = renderToStaticMarkup(<Profile d={real} />);
+        expect(stamped.toString('utf8')).toBe(expected);
+    }
+
+    it('matches for plain data', () => {
+        check({
+            username: 'grace',
+            bioHtml: '<strong>Rear Admiral</strong>',
+            posts: [{ title: 'COBOL' }, { title: 'the bug' }, { title: 'compilers' }],
+        });
+    });
+
+    it('matches when values need React escaping (the &#x27; / &quot; cases)', () => {
+        check({
+            username: `A<b>&"'x`,
+            bioHtml: '<em>raw & <kept></em>', // raw: NOT escaped, verbatim
+            posts: [{ title: 'a & b' }, { title: '<script>' }, { title: `it's "ok"` }],
+        });
+    });
+
+    it('matches for an empty list (zero rows)', () => {
+        check({ username: 'zero', bioHtml: '<i/>', posts: [] });
+    });
+
+    it('matches for a single row', () => {
+        check({ username: 'one', bioHtml: 'x', posts: [{ title: 'only' }] });
+    });
+});
+
+describe('ssr .slots binary manifest', () => {
+    it('encodes the documented layout and round-trips offsets/kinds', () => {
+        const sample: ProfileData = {
+            username: 'ada',
+            bioHtml: '<em>x</em>',
+            posts: [{ title: 't' }],
+        };
+        const { tmpl, slots } = extractFromHtml(renderBuild(<Profile d={sample} />));
+        const ids = assignSlotIds(slots);
+        const hash = coherenceHash(tmpl, slots);
+        const buf = encodeSlots(tmpl.length, hash, slots, ids);
+
+        // Header: magic "TSLT", version 1, flags 0, tmpl_len, hash, n_slots.
+        expect(buf.subarray(0, 4).toString('ascii')).toBe('TSLT');
+        expect(buf.readUInt16LE(4)).toBe(1);
+        expect(buf.readUInt16LE(6)).toBe(0);
+        expect(buf.readUInt32LE(8)).toBe(tmpl.length);
+        expect(buf.subarray(12, 44).equals(hash)).toBe(true);
+        expect(buf.readUInt16LE(44)).toBe(slots.length);
+
+        // Slot entries: offset u32, slot_id u16, kind u8, reserved u8.
+        let o = 46;
+        slots.forEach((s, i) => {
+            expect(buf.readUInt32LE(o)).toBe(s.offset);
+            expect(buf.readUInt16LE(o + 4)).toBe(ids.get(s.id));
+            expect(buf.readUInt8(o + 6)).toBe(kindByte(s.kind));
+            expect(buf.readUInt8(o + 7)).toBe(0);
+            expect(ids.get(s.id)).toBe(i); // document-order numbering
+            o += 8;
+        });
+        expect(o).toBe(buf.length);
+    });
+
+    it('coherence hash changes when the template changes', () => {
+        const a = extractFromHtml(
+            renderBuild(<Profile d={{ username: 'a', bioHtml: 'x', posts: [{ title: 't' }] }} />),
+        );
+        const h1 = coherenceHash(a.tmpl, a.slots);
+        const h2 = coherenceHash(Buffer.concat([a.tmpl, Buffer.from('!')]), a.slots);
+        expect(h1.equals(h2)).toBe(false);
+    });
+});
+
+describe('ssr guest codegen (Slot enum + HASH)', () => {
+    const sample: ProfileData = {
+        username: 'ada',
+        bioHtml: '<em>x</em>',
+        posts: [{ title: 't' }],
+    };
+
+    it('emits a Slot enum matching the .slots numbering and the 32-byte HASH', () => {
+        const { tmpl, slots } = extractFromHtml(renderBuild(<Profile d={sample} />));
+        const ids = assignSlotIds(slots);
+        const hash = coherenceHash(tmpl, slots);
+        const mod = generateSlotsModule('u_name', slots, hash);
+
+        // Enum members use the SAME ids the host .slots carries.
+        expect(mod).toContain('export enum Slot {');
+        expect(mod).toContain(`username = ${ids.get('username')},`);
+        expect(mod).toContain(`bio = ${ids.get('bio')},`);
+        expect(mod).toContain(`posts = ${ids.get('posts')},`);
+        // HASH literal has exactly 32 bytes.
+        const arr = mod.match(/HASH: StaticArray<u8> = \[([^\]]*)\]/)![1];
+        expect(arr.split(',').filter((s) => s.trim().length > 0)).toHaveLength(32);
+        expect(mod).toContain(`0x${hash[0].toString(16).padStart(2, '0')}`);
+    });
+
+    it('rejects a hole id that is not a valid identifier', () => {
+        const bad: SlotRecord[] = [{ id: 'has-dash', kind: 'text', offset: 0 }];
+        expect(() => generateSlotsModule('r', bad, Buffer.alloc(32))).toThrow(/not a valid identifier/);
+    });
+});
+
+describe('ssr build orchestration', () => {
+    const SHELL =
+        '<!doctype html><html><head><title>t</title></head><body><div id="root"></div>' +
+        '<script type="module" src="/assets/app-abc123.js"></script></body></html>';
+
+    // A page that reads its data from the loader context (exercises the provider
+    // path), wrapped in a simple SSR-safe layout.
+    function ProfilePage(): React.ReactElement {
+        const d = useLoaderData<ProfileData>();
+        return <Profile d={d} />;
+    }
+    function Layout({ children }: { children?: React.ReactNode }): React.ReactElement {
+        return <div className="app">{children}</div>;
+    }
+
+    const sample: ProfileData = {
+        username: 'ada',
+        bioHtml: '<em>x</em>',
+        posts: [{ title: 't' }],
+    };
+
+    it('sanitizes route patterns into file-safe names', () => {
+        expect(routeTemplateName('/u/:name')).toBe('u_name');
+        expect(routeTemplateName('/')).toBe('index');
+        expect(routeTemplateName('/blog/[id]')).toBe('blog_id');
+    });
+
+    it('injects rendered route HTML into the shell #root with the SSR marker', () => {
+        const out = injectIntoShell(SHELL, '<main>hi</main>');
+        expect(out).toContain('<div id="root"><main>hi</main></div>');
+        expect(out).toContain('<template id="__toil_ssr"></template>');
+        // the hashed script tag is preserved (so hydration boots)
+        expect(out).toContain('/assets/app-abc123.js');
+    });
+
+    it('renders a route (page + layout + loader data) to template artifacts and writes them', () => {
+        const art = extractRouteTemplate({
+            name: 'profile',
+            Page: ProfilePage,
+            layouts: [Layout],
+            loaderData: sample,
+            loaderContext: LoaderDataContext,
+            setSsrBuild: __setSsrBuild,
+            shell: SHELL,
+        });
+
+        const tmpl = art.tmpl.toString('utf8');
+        // Full document with the layout + page scaffold spliced into #root, holes removed.
+        expect(tmpl).toContain(
+            '<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
+        expect(art.slotCount).toBe(3); // username, bio, posts
+        expect(art.hash).toHaveLength(32);
+
+        // The generated AS Slot module names every hole.
+        expect(art.slotsModule).toContain('export enum Slot {');
+        for (const id of ['username', 'bio', 'posts']) expect(art.slotsModule).toContain(`${id} =`);
+
+        // Write to disk and read back; the .slots header is well-formed and the
+        // tmpl_len in it matches the .tmpl byte length (the host's first check).
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'toil-ssr-'));
+        try {
+            writeTemplateArtifacts(dir, art);
+            const tmplFile = fs.readFileSync(path.join(dir, 'profile.tmpl'));
+            const slotsFile = fs.readFileSync(path.join(dir, 'profile.slots'));
+            const modFile = fs.readFileSync(path.join(dir, 'profile.slots.ts'), 'utf8');
+
+            expect(tmplFile.equals(art.tmpl)).toBe(true);
+            expect(slotsFile.subarray(0, 4).toString('ascii')).toBe('TSLT');
+            expect(slotsFile.readUInt16LE(4)).toBe(1); // version
+            expect(slotsFile.readUInt32LE(8)).toBe(tmplFile.length); // tmpl_len matches .tmpl
+            expect(slotsFile.subarray(12, 44).equals(art.hash)).toBe(true);
+            expect(slotsFile.readUInt16LE(44)).toBe(3); // n_slots
+            expect(modFile).toContain('export const HASH: StaticArray<u8>');
+        } finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});