toiljs 0.0.115 → 0.0.117

package/test/ssr-render.test.ts

@@ -1,197 +0,0 @@
-/**
- * End-to-end guest render: drive the real ToilScript-compiled `render` export
- * of the basic example's server 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.
- *
- * SSR is part of the normal (single-wasm) build now: the example's `/hello`
- * route opts in with `export const ssr = true`, the build extracts its template
- * into `build/client/_ssr/hello.{tmpl,slots,slots.ts}`, and the server
- * `render` (`examples/basic/server/SsrHelloRender.ts`) fills the holes. We drive
- * the same `build/server/release.wasm` the dev server and edge run, and pin the
- * expected coherence hash to the generated `templates.json` so the guest and the
- * deployed template are proven to agree.
- */
-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 EXAMPLE = path.resolve(
-    path.dirname(fileURLToPath(import.meta.url)),
-    '../examples/basic',
-);
-/** Single-wasm SSR: the server `render` lives in the normal server wasm. */
-const SERVER_WASM = path.join(EXAMPLE, 'build/server/release.wasm');
-const SSR_DIR = path.join(EXAMPLE, 'build/client/_ssr');
-const TEMPLATES = path.join(SSR_DIR, 'templates.json');
-
-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 };
-}
-
-/** The hash the build pinned for the `/hello` template (deploy-skew guard). */
-function helloTemplateHash(): Buffer {
-    const index = JSON.parse(fs.readFileSync(TEMPLATES, 'utf8')) as {
-        route: string;
-        name: string;
-        hash: string;
-    }[];
-    const hello = index.find((t) => t.route === '/hello');
-    if (!hello) throw new Error('no /hello template in templates.json');
-    return Buffer.from(hello.hash, 'hex');
-}
-
-// Skip cleanly when the example has not been built (no toolchain in CI): the
-// build is what produces both the wasm and the template artifacts.
-const built = fs.existsSync(SERVER_WASM) && fs.existsSync(TEMPLATES);
-
-describe.skipIf(!built)('edge SSR guest render (real single-wasm build)', () => {
-    const load = (): WasmServerModule => {
-        const m = new WasmServerModule(SERVER_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 deployed template hash and escaped holes', () => {
-        const d = decodeValues(render(load(), '/hello'));
-        expect(d.status).toBe(200);
-        // The guest's compiled-in HASH must equal the deployed template's hash,
-        // or the host rejects the response as a deploy skew.
-        expect(d.hash.equals(helloTemplateHash())).toBe(true);
-
-        // Top-level slots in document order: name (text), blurb (raw), services (repeat).
-        expect(d.slots.map((s) => `${s.slotId}:${s.kind}`)).toEqual([
-            '0:0', // name, text
-            '1:1', // blurb, raw
-            '2:3', // services, repeat
-        ]);
-        // Text hole: the default greeting target.
-        expect(d.slots[0].value.toString('utf8')).toBe('world');
-        // Raw hole: inserted verbatim (NOT escaped).
-        expect(d.slots[1].value.toString('utf8')).toBe(
-            'Rendered at the <strong>edge</strong> from a tiny values envelope.',
-        );
-        // Repeat hole: three stamped rows, each nested hole React-escaped.
-        expect(d.slots[2].value.toString('utf8')).toBe(
-            '<li><strong>record</strong><span class="hello-region">us-east</span></li>' +
-                '<li><strong>unique</strong><span class="hello-region">eu-west</span></li>' +
-                '<li><strong>counter</strong><span class="hello-region">ap-south</span></li>',
-        );
-    });
-
-    it('escapes a text hole derived from the request (?name=)', () => {
-        const d = decodeValues(render(load(), '/hello?name=A<b>%26"x'));
-        expect(d.status).toBe(200);
-        // setText React-escapes: & -> &amp;, <> -> entities, " -> &quot;.
-        // (The query value arrives as the raw bytes after `name=`; only `%26`
-        // is a literal here, so the guest sees `A<b>&"x` after the `&` split is
-        // accounted for — assert the escaping shape rather than the exact bytes.)
-        const v = d.slots[0].value.toString('utf8');
-        expect(v).not.toContain('<b>');
-        expect(v).toContain('&lt;');
-    });
-
-    it('splices into the real built template exactly (guest -> host -> HTML)', () => {
-        const d = decodeValues(render(load(), '/hello'));
-        const tmpl = fs.readFileSync(path.join(SSR_DIR, 'hello.tmpl'));
-        const slotsBin = fs.readFileSync(path.join(SSR_DIR, 'hello.slots'));
-
-        // Read the top-level slot offsets straight from the .slots manifest
-        // (header is 46 bytes; each entry is offset u32, id u16, kind u8, rsvd u8).
-        const nSlots = slotsBin.readUInt16LE(44);
-        const byId = new Map(d.slots.map((s) => [s.slotId, s.value]));
-        const inserts: { offset: number; value: Buffer }[] = [];
-        let o = 46;
-        for (let i = 0; i < nSlots; i++) {
-            const offset = slotsBin.readUInt32LE(o);
-            const id = slotsBin.readUInt16LE(o + 4);
-            inserts.push({ offset, value: Buffer.from(byId.get(id)!) });
-            o += 8;
-        }
-        const out = spliceTemplate(tmpl, inserts).toString('utf8');
-
-        // 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>' +
-                '<p class="hello-blurb"><span>Rendered at the <strong>edge</strong> ' +
-                'from a tiny values envelope.</span></p>' +
-                '<h2>Service snapshot</h2>' +
-                '<ul class="hello-services">' +
-                '<li><strong>record</strong><span class="hello-region">us-east</span></li>' +
-                '<li><strong>unique</strong><span class="hello-region">eu-west</span></li>' +
-                '<li><strong>counter</strong><span class="hello-region">ap-south</span></li>' +
-                '</ul></section>',
-        );
-    });
-
-    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

@@ -1,482 +0,0 @@
-/**
- * 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, attr, __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 attribute holes (attr())', () => {
-    it('is transparent in the browser and a sentinel under the build extractor', () => {
-        // Browser (default): passes the value through unchanged.
-        expect(attr('link', '/u/ada')).toBe('/u/ada');
-        // Build: emits a PUA sentinel token (start codepoint U+E000) carrying the id.
-        __setSsrBuild(true);
-        try {
-            const tok = attr('link', '/u/ada');
-            expect(tok).not.toBe('/u/ada');
-            expect(tok.charCodeAt(0)).toBe(0xe000);
-            expect(tok).toContain('link');
-        } finally {
-            __setSsrBuild(false);
-        }
-    });
-
-    it('extracts an attr slot whose guest stamp reproduces React attribute output byte-for-byte', () => {
-        // Render with the attr() hole in an attribute position, in build mode.
-        __setSsrBuild(true);
-        let built: string;
-        try {
-            built = renderToStaticMarkup(<a href={attr('link', 'IGNORED_AT_BUILD')}>x</a>);
-        } finally {
-            __setSsrBuild(false);
-        }
-        const { tmpl, slots } = extractFromHtml(built);
-        expect(slots).toHaveLength(1);
-        expect(slots[0]).toMatchObject({ id: 'link', kind: 'attr' });
-        expect(kindByte(slots[0].kind)).toBe(2);
-        // The .tmpl carries the attribute with the hole stripped to an empty value.
-        expect(tmpl.toString('utf8')).toBe('<a href="">x</a>');
-
-        // Guest stamp: setAttr React-escapes (identical to text); splice at the offset.
-        const value = '/u/ada?q="a"&b<c>';
-        const stamped = spliceTemplate(tmpl, [
-            { offset: slots[0].offset, value: Buffer.from(reactEscapeHtml(value), 'utf8') },
-        ]).toString('utf8');
-
-        // Byte-identical to what React renders for the same attribute value (clean hydration).
-        expect(stamped).toBe(renderToStaticMarkup(<a href={value}>x</a>));
-    });
-});
-
-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.
-        // `<!--$-->` / `<!--/$-->` 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>',
-        );
-        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 });
-        }
-    });
-
-    it('bakes the route SEO (title/description/og incl og:image) into the template <head>', () => {
-        const art = extractRouteTemplate({
-            name: 'profile',
-            Page: ProfilePage,
-            layouts: [Layout],
-            loaderData: sample,
-            loaderContext: LoaderDataContext,
-            setSsrBuild: __setSsrBuild,
-            shell: SHELL,
-            seo: {
-                url: 'https://ex.com',
-                title: 'Site',
-                openGraph: { siteName: 'Site', image: 'https://ex.com/og.png' },
-            },
-            metadata: {
-                title: 'Profile',
-                description: 'A user profile',
-                openGraph: { title: 'Profile OG' },
-            },
-            pattern: '/u/ada',
-        });
-        const tmpl = art.tmpl.toString('utf8');
-        // The route's own title replaces the shell's, and its metadata + the site SEO are in <head>,
-        // so an SSR route serves the same per-page tags a crawler would get from <route>/index.html.
-        expect(tmpl).toContain('<title>Profile</title>');
-        expect(tmpl).not.toContain('<title>t</title>');
-        expect(tmpl).toContain('<meta name="description" content="A user profile" />');
-        expect(tmpl).toContain('<meta property="og:title" content="Profile OG" />');
-        expect(tmpl).toContain('<meta property="og:image" content="https://ex.com/og.png" />');
-        // Per-route canonical / og:url point at THIS route, not the site root.
-        expect(tmpl).toContain('<link rel="canonical" href="https://ex.com/u/ada" />');
-        expect(tmpl).toContain('<meta property="og:url" content="https://ex.com/u/ada" />');
-        // The baked head is inside art.tmpl, so it is covered by the coherence hash.
-        expect(art.hash).toHaveLength(32);
-        // Holes are unaffected (still body-only).
-        expect(art.slotCount).toBe(3);
-    });
-
-    it('skips SEO injection when no seo config is passed (head unchanged)', () => {
-        const art = extractRouteTemplate({
-            name: 'p',
-            Page: ProfilePage,
-            layouts: [Layout],
-            loaderData: sample,
-            loaderContext: LoaderDataContext,
-            setSsrBuild: __setSsrBuild,
-            shell: SHELL,
-        });
-        const tmpl = art.tmpl.toString('utf8');
-        expect(tmpl).toContain('<title>t</title>'); // shell title untouched
-        expect(tmpl).not.toContain('og:image');
-        expect(tmpl).not.toContain('rel="canonical"');
-    });
-
-    it('bakes the component-level head (useHead/<Head>) the static metadata did not set', () => {
-        const componentHead = {
-            title: 'Layout Title',
-            meta: [
-                { name: 'author', content: 'me' },
-                { name: 'description', content: 'layout desc' },
-            ],
-            link: [{ rel: 'me', href: 'https://x.test' }],
-        };
-        const art = extractRouteTemplate({
-            name: 'p',
-            Page: ProfilePage,
-            layouts: [Layout],
-            loaderData: sample,
-            loaderContext: LoaderDataContext,
-            setSsrBuild: __setSsrBuild,
-            shell: SHELL,
-            seo: { title: 'Site', description: 'site desc' },
-            metadata: { description: 'route desc' }, // route sets a description but NO title
-            pattern: '/p',
-            drainSsrHead: () => componentHead,
-        });
-        const tmpl = art.tmpl.toString('utf8');
-        // Component title wins because the route's static metadata set no title of its own.
-        expect(tmpl).toContain('<title>Layout Title</title>');
-        // A component meta the route SEO didn't carry is added, owned by the client (data-toil-head).
-        expect(tmpl).toContain('<meta data-toil-head name="author" content="me" />');
-        // The component description is deduped (the route SEO already baked one).
-        expect(tmpl.match(/name="description"/g)?.length).toBe(1);
-        // A component link is added too.
-        expect(tmpl).toContain('<link data-toil-head rel="me" href="https://x.test" />');
-    });
-});