npm - toiljs - Versions diffs - 0.0.60 → 0.0.62 - Mend

toiljs 0.0.60 → 0.0.62

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (120) hide show

package/.github/workflows/ci.yml +31 -0
package/CHANGELOG.md +17 -0
package/build/cli/.tsbuildinfo +1 -1
package/build/cli/index.js +2 -2
package/build/client/.tsbuildinfo +1 -1
package/build/client/index.d.ts +1 -1
package/build/client/index.js +1 -1
package/build/client/routing/mount.js +11 -26
package/build/client/ssr/markers.d.ts +1 -0
package/build/client/ssr/markers.js +9 -2
package/build/compiler/.tsbuildinfo +1 -1
package/build/compiler/config.d.ts +21 -0
package/build/compiler/config.js +35 -0
package/build/compiler/docs.d.ts +2 -1
package/build/compiler/docs.js +33 -304
package/build/compiler/index.d.ts +13 -0
package/build/compiler/index.js +113 -21
package/build/compiler/template-build.d.ts +23 -3
package/build/compiler/template-build.js +120 -30
package/build/compiler/toil-docs.generated.d.ts +1 -0
package/build/compiler/toil-docs.generated.js +20 -0
package/build/devserver/.tsbuildinfo +1 -1
package/build/devserver/daemon/catalog.d.ts +26 -0
package/build/devserver/daemon/catalog.js +48 -0
package/build/devserver/daemon/cron.d.ts +4 -0
package/build/devserver/daemon/cron.js +50 -0
package/build/devserver/daemon/host.d.ts +37 -0
package/build/devserver/daemon/host.js +94 -0
package/build/devserver/daemon/index.d.ts +34 -0
package/build/devserver/daemon/index.js +241 -0
package/build/devserver/db/catalog.d.ts +2 -1
package/build/devserver/db/catalog.js +44 -44
package/build/devserver/db/database.d.ts +27 -11
package/build/devserver/db/database.js +539 -169
package/build/devserver/db/index.d.ts +1 -1
package/build/devserver/db/index.js +1 -1
package/build/devserver/db/routeKinds.d.ts +8 -0
package/build/devserver/db/routeKinds.js +139 -0
package/build/devserver/db/types.d.ts +64 -1
package/build/devserver/db/types.js +33 -1
package/build/devserver/index.d.ts +10 -0
package/build/devserver/index.js +7 -0
package/build/devserver/mstore/store.d.ts +18 -0
package/build/devserver/mstore/store.js +82 -0
package/build/devserver/runtime/host.d.ts +6 -0
package/build/devserver/runtime/host.js +45 -1
package/build/devserver/runtime/module.d.ts +1 -0
package/build/devserver/runtime/module.js +27 -1
package/build/devserver/server.d.ts +6 -0
package/build/devserver/server.js +59 -0
package/build/devserver/ssr.d.ts +25 -0
package/build/devserver/ssr.js +114 -0
package/build/devserver/wasm/sections.d.ts +2 -0
package/build/devserver/wasm/sections.js +42 -0
package/build/devserver/wasm/surface.d.ts +18 -0
package/build/devserver/wasm/surface.js +41 -0
package/docs/README.md +4 -4
package/docs/auth-todo.md +6 -6
package/docs/caching.md +5 -5
package/docs/cli.md +15 -0
package/docs/client.md +40 -0
package/docs/crypto.md +4 -4
package/docs/data.md +6 -6
package/docs/email.md +28 -28
package/docs/environment.md +10 -10
package/docs/index.md +26 -0
package/docs/ratelimit.md +10 -10
package/docs/routing.md +2 -2
package/docs/server.md +61 -0
package/docs/ssr.md +561 -113
package/docs/styling.md +22 -0
package/docs/time.md +1 -1
package/eslint.config.js +10 -1
package/examples/basic/client/components/Header.tsx +3 -0
package/examples/basic/client/routes/features/actions.tsx +0 -2
package/examples/basic/client/routes/hello.tsx +89 -19
package/examples/basic/client/styles/main.css +48 -0
package/examples/basic/server/SsrHelloRender.ts +97 -0
package/examples/basic/server/main.ts +5 -0
package/examples/basic/server/streams/Echo.ts +49 -0
package/package.json +12 -10
package/scripts/gen-toil-docs.mjs +96 -0
package/src/cli/create.ts +2 -2
package/src/client/index.ts +1 -1
package/src/client/routing/mount.tsx +19 -31
package/src/client/ssr/markers.tsx +33 -4
package/src/compiler/config.ts +88 -2
package/src/compiler/docs.ts +47 -308
package/src/compiler/index.ts +236 -32
package/src/compiler/ssr-codegen.ts +1 -1
package/src/compiler/template-build.ts +271 -53
package/src/compiler/toil-docs.generated.ts +26 -0
package/src/devserver/daemon/catalog.ts +120 -0
package/src/devserver/daemon/cron.ts +87 -0
package/src/devserver/daemon/host.ts +224 -0
package/src/devserver/daemon/index.ts +349 -0
package/src/devserver/db/catalog.ts +61 -53
package/src/devserver/db/database.ts +613 -149
package/src/devserver/db/index.ts +1 -1
package/src/devserver/db/routeKinds.ts +147 -0
package/src/devserver/db/types.ts +65 -2
package/src/devserver/index.ts +12 -0
package/src/devserver/mstore/store.ts +121 -0
package/src/devserver/runtime/host.ts +92 -1
package/src/devserver/runtime/module.ts +35 -1
package/src/devserver/server.ts +101 -0
package/src/devserver/ssr.ts +166 -0
package/src/devserver/wasm/sections.ts +59 -0
package/src/devserver/wasm/surface.ts +88 -0
package/test/daemon-build.test.ts +198 -0
package/test/daemon-catalog.test.ts +265 -0
package/test/daemon-emulation.test.ts +216 -0
package/test/devserver-database.test.ts +396 -5
package/test/email-preview.test.ts +6 -1
package/test/fixtures/daemon-app.ts +56 -0
package/test/global-setup.ts +17 -0
package/test/ssr-hydration.test.tsx +107 -0
package/test/ssr-render.test.ts +96 -27
package/test/ssr-template.test.tsx +47 -2
package/vitest.config.ts +3 -0

package/test/ssr-hydration.test.tsx ADDED Viewed

@@ -0,0 +1,107 @@
+// @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 three 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.
+ */
+import { act } 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 () => {
+                hydrateRoot(rootEl, <Page />, {
+                    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 CHANGED Viewed

@@ -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,77 @@ 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. 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>',
         );
     });

package/test/ssr-template.test.tsx CHANGED Viewed

@@ -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>' +
@@ -313,8 +356,10 @@ 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.
         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/vitest.config.ts CHANGED Viewed

@@ -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/**'],