toiljs 0.0.60 → 0.0.61

package/test/ssr-render.test.ts

@@ -1,11 +1,19 @@
 /**
  * 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
+ * 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';
@@ -16,10 +24,14 @@ 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(
+const EXAMPLE = path.resolve(
     path.dirname(fileURLToPath(import.meta.url)),
-    '../examples/basic/build/server/ssr.wasm',
+    '../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;
@@ -72,9 +84,25 @@ function decodeValues(buf: Uint8Array): DecodedValues {
     return { status, hash, headers, slots };
 }
 
-describe.skipIf(!fs.existsSync(SSR_WASM))('edge SSR guest render (real wasm)', () => {
+/** 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(SSR_WASM);
+        const m = new WasmServerModule(SERVER_WASM);
         m.refresh();
         return m;
     };
@@ -86,36 +114,75 @@ describe.skipIf(!fs.existsSync(SSR_WASM))('edge SSR guest render (real wasm)', (
             body: new Uint8Array(0),
         });
 
-    it('produces a values envelope with the compiled-in hash and escaped holes', () => {
+    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 HASH baked into greeting.slots.ts: bytes 0x00..0x1f.
-        expect([...d.hash]).toEqual(Array.from({ length: 32 }, (_, i) => i));
+        // 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', // greeting, text
-            '1:3', // count, repeat
+            '0:0', // name, text
+            '1:1', // blurb, raw
+            '2:3', // services, 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.
+        // 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(
-            '<li>a &amp; b</li><li>&lt;c&gt;</li><li>d</li>',
+            '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 a template exactly (full guest -> host -> HTML chain)', () => {
+    it('splices into the real built template exactly (guest -> host -> HTML)', () => {
         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>',
+        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.
+        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>',
         );
     });
 

package/test/ssr-template.test.tsx

@@ -20,7 +20,7 @@ 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 { Hole, Island, RawHtml, Repeat, attr, __setSsrBuild } from '../src/client/ssr/markers';
 import { LoaderDataContext, useLoaderData } from '../src/client/routing/loader';
 import {
     extractRouteTemplate,
@@ -265,6 +265,49 @@ describe('ssr guest codegen (Slot enum + HASH)', () => {
     });
 });
 
+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>' +

package/vitest.config.ts

@@ -6,6 +6,9 @@ export default defineConfig({
     test: {
         globals: true,
         environment: 'node',
+        // Generate src/compiler/toil-docs.generated.ts (gitignored, imported by
+        // docs.ts) before the suite, so a fresh checkout can test without a build.
+        globalSetup: ['./test/global-setup.ts'],
         include: ['test/**/*.test.ts', 'test/**/*.test.tsx', 'test/**/*.spec.ts'],
         // test/assembly holds toilscript specs run by as-pect, not vitest.
         exclude: [...configDefaults.exclude, 'test/assembly/**'],