toiljs 0.0.34 → 0.0.36

package/build/compiler/ssr-codegen.js

@@ -0,0 +1,36 @@
+import { assignSlotIds } from './template.js';
+function hashLiteral(hash) {
+    const bytes = Array.from(hash.values())
+        .map((b) => `0x${b.toString(16).padStart(2, '0')}`)
+        .join(', ');
+    return `[${bytes}]`;
+}
+function isIdent(name) {
+    return /^[A-Za-z_$][\w$]*$/.test(name);
+}
+export function generateSlotsModule(routeName, slots, hash) {
+    if (hash.length !== 32)
+        throw new Error('toil ssr: coherence hash must be 32 bytes');
+    const ids = assignSlotIds(slots);
+    const members = [];
+    for (const [name, id] of ids) {
+        if (!isIdent(name)) {
+            throw new Error(`toil ssr: hole id "${name}" in route "${routeName}" is not a valid identifier ` +
+                `(use [A-Za-z_][\\w]*) so it can be a Slot enum member`);
+        }
+        members.push(`    ${name} = ${id},`);
+    }
+    return `// AUTO-GENERATED by toil (edge SSR). Do not edit.
+// Route: ${routeName}. Slot ids match the deployed .slots manifest; HASH is the
+// coherence hash the host checks against the template (deploy-skew guard).
+
+/** Stable hole ids for this route's template. */
+export enum Slot {
+${members.join('\n')}
+}
+
+/** Coherence hash (32 bytes) baked into the guest and echoed in every values
+ * envelope; the host rejects a response whose hash != the deployed template. */
+export const HASH: StaticArray<u8> = ${hashLiteral(hash)};
+`;
+}

package/build/compiler/template-build.d.ts

@@ -0,0 +1,29 @@
+import { type ComponentType, type Context, type ReactNode } from 'react';
+import { type ResolvedToilConfig } from './config.js';
+export interface RouteRenderInput {
+    name: string;
+    Page: ComponentType;
+    layouts: ComponentType<{
+        children?: ReactNode;
+    }>[];
+    loaderData: unknown;
+    loaderContext: Context<unknown> | null;
+    setSsrBuild: (on: boolean) => void;
+    shell: string;
+}
+export interface TemplateArtifacts {
+    name: string;
+    tmpl: Buffer;
+    slotsBin: Buffer;
+    slotsModule: string;
+    hash: Buffer;
+    slotCount: number;
+}
+export declare function assembleRouteElement(Page: ComponentType, layouts: ComponentType<{
+    children?: ReactNode;
+}>[], loaderData: unknown, loaderContext: Context<unknown> | null): ReactNode;
+export declare function injectIntoShell(shell: string, routeHtml: string): string;
+export declare function extractRouteTemplate(input: RouteRenderInput): TemplateArtifacts;
+export declare function writeTemplateArtifacts(ssrDir: string, art: TemplateArtifacts): void;
+export declare function routeTemplateName(pattern: string): string;
+export declare function extractTemplates(cfg: ResolvedToilConfig, hostName?: string): Promise<string[]>;

package/build/compiler/template-build.js

@@ -0,0 +1,150 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createElement, } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { createServer } from 'vite';
+import { findLayout, findSpecialChain } from './generate.js';
+import { scanRoutes } from './routes.js';
+import { generateSlotsModule } from './ssr-codegen.js';
+import { assignSlotIds, coherenceHash, encodeSlots, extractFromHtml, } from './template.js';
+import { createViteConfig } from './vite.js';
+const SSR_MARKER = '<template id="__toil_ssr"></template>';
+const ROOT_DIV = '<div id="root"></div>';
+export function assembleRouteElement(Page, layouts, loaderData, loaderContext) {
+    let node = createElement(Page);
+    if (loaderContext) {
+        node = createElement(loaderContext.Provider, { value: loaderData }, node);
+    }
+    for (let i = layouts.length - 1; i >= 0; i--) {
+        node = createElement(layouts[i], null, node);
+    }
+    return node;
+}
+export function injectIntoShell(shell, routeHtml) {
+    if (!shell.includes(ROOT_DIV)) {
+        throw new Error('toil ssr: built shell has no empty <div id="root"></div> to splice into');
+    }
+    return shell.replace(ROOT_DIV, `<div id="root">${routeHtml}</div>${SSR_MARKER}`);
+}
+export function extractRouteTemplate(input) {
+    const element = assembleRouteElement(input.Page, input.layouts, input.loaderData, input.loaderContext);
+    input.setSsrBuild(true);
+    let routeHtml;
+    try {
+        routeHtml = renderToStaticMarkup(element);
+    }
+    finally {
+        input.setSsrBuild(false);
+    }
+    const full = injectIntoShell(input.shell, routeHtml);
+    const extracted = extractFromHtml(full);
+    const ids = assignSlotIds(extracted.slots);
+    const hash = coherenceHash(extracted.tmpl, extracted.slots);
+    return {
+        name: input.name,
+        tmpl: extracted.tmpl,
+        slotsBin: encodeSlots(extracted.tmpl.length, hash, extracted.slots, ids),
+        slotsModule: generateSlotsModule(input.name, extracted.slots, hash),
+        hash,
+        slotCount: extracted.slots.length,
+    };
+}
+export function writeTemplateArtifacts(ssrDir, art) {
+    fs.mkdirSync(ssrDir, { recursive: true });
+    fs.writeFileSync(path.join(ssrDir, `${art.name}.tmpl`), art.tmpl);
+    fs.writeFileSync(path.join(ssrDir, `${art.name}.slots`), art.slotsBin);
+    fs.writeFileSync(path.join(ssrDir, `${art.name}.slots.ts`), art.slotsModule);
+}
+export function routeTemplateName(pattern) {
+    const n = pattern.replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+    return n.length > 0 ? n : 'index';
+}
+function sampleParams(pattern) {
+    const params = {};
+    for (const m of pattern.matchAll(/[:*]+([A-Za-z0-9_]+)/g)) {
+        params[m[1]] = 'sample';
+    }
+    return params;
+}
+export async function extractTemplates(cfg, hostName = 'edge') {
+    const routes = scanRoutes(cfg.routesAbsDir).filter((r) => r.slot === undefined && !r.intercept);
+    if (routes.length === 0)
+        return [];
+    const outDir = path.resolve(cfg.root, cfg.outDir);
+    const stashed = path.join(cfg.toilDir, 'shell.html');
+    const shellPath = fs.existsSync(stashed) ? stashed : path.join(outDir, 'index.html');
+    if (!fs.existsSync(shellPath))
+        return [];
+    const shell = fs.readFileSync(shellPath, 'utf8');
+    const warn = (msg) => {
+        process.stderr.write(`  toil: SSR ${msg}\n`);
+    };
+    const server = await createServer({
+        ...(await createViteConfig(cfg)),
+        server: { middlewareMode: true, hmr: false },
+        appType: 'custom',
+        logLevel: 'silent',
+    });
+    const client = (await server.ssrLoadModule('toiljs/client'));
+    const ssrDir = path.join(outDir, '_ssr');
+    const hostsTmplDir = path.join(cfg.root, 'hosts', hostName, '_tmpl');
+    const generated = [];
+    const index = [];
+    try {
+        for (const r of routes) {
+            let mod;
+            try {
+                mod = (await server.ssrLoadModule(r.file));
+            }
+            catch (err) {
+                warn(`skipped ${r.pattern} (${err instanceof Error ? err.message : String(err)})`);
+                continue;
+            }
+            if (mod.ssr !== true)
+                continue;
+            try {
+                const params = sampleParams(r.pattern);
+                const loaderData = typeof mod.loader === 'function'
+                    ? await mod.loader({ params, searchParams: new URLSearchParams() })
+                    : undefined;
+                const layoutFiles = [
+                    ...(findLayout(cfg) ? [findLayout(cfg)] : []),
+                    ...findSpecialChain(cfg, r.file, 'layout', false),
+                ];
+                const layouts = [];
+                for (const lf of layoutFiles) {
+                    const lm = (await server.ssrLoadModule(lf));
+                    layouts.push(lm.default);
+                }
+                const name = routeTemplateName(r.pattern);
+                const art = extractRouteTemplate({
+                    name,
+                    Page: mod.default,
+                    layouts,
+                    loaderData,
+                    loaderContext: client.LoaderDataContext,
+                    setSsrBuild: client.__setSsrBuild,
+                    shell,
+                });
+                writeTemplateArtifacts(ssrDir, art);
+                fs.mkdirSync(hostsTmplDir, { recursive: true });
+                fs.copyFileSync(path.join(ssrDir, `${name}.tmpl`), path.join(hostsTmplDir, `${name}.tmpl`));
+                fs.copyFileSync(path.join(ssrDir, `${name}.slots`), path.join(hostsTmplDir, `${name}.slots`));
+                index.push({ route: r.pattern, name, hash: art.hash.toString('hex') });
+                generated.push(r.pattern);
+            }
+            catch (err) {
+                warn(`skipped ${r.pattern} (render failed: ${err instanceof Error ? err.message : String(err)}) — falls back to client rendering`);
+            }
+        }
+    }
+    finally {
+        await server.close();
+    }
+    if (generated.length > 0) {
+        fs.mkdirSync(ssrDir, { recursive: true });
+        fs.writeFileSync(path.join(ssrDir, 'templates.json'), JSON.stringify(index, null, 2));
+        process.stdout.write(`  ✓ extracted ${String(generated.length)} SSR template${generated.length === 1 ? '' : 's'}\n`);
+    }
+    return generated;
+}

package/build/compiler/template.d.ts

@@ -0,0 +1,22 @@
+export type SlotKind = 'text' | 'raw' | 'attr' | 'repeat';
+export declare function kindByte(kind: SlotKind): number;
+export interface SlotRecord {
+    id: string;
+    kind: SlotKind;
+    offset: number;
+    rowTemplate?: Buffer;
+    rowSlots?: SlotRecord[];
+}
+export interface Extracted {
+    tmpl: Buffer;
+    slots: SlotRecord[];
+}
+export declare function extractFromHtml(html: string): Extracted;
+export declare function assignSlotIds(slots: SlotRecord[]): Map<string, number>;
+export declare function encodeSlots(tmplLen: number, hash: Buffer, slots: SlotRecord[], slotIds: Map<string, number>): Buffer;
+export declare function coherenceHash(tmpl: Buffer, slots: SlotRecord[]): Buffer;
+export declare function reactEscapeHtml(s: string): string;
+export declare function spliceTemplate(tmpl: Buffer, inserts: {
+    offset: number;
+    value: Buffer;
+}[]): Buffer;

package/build/compiler/template.js

@@ -0,0 +1,169 @@
+import { createHash } from 'node:crypto';
+const START = String.fromCharCode(0xe000);
+const END = String.fromCharCode(0xe002);
+export function kindByte(kind) {
+    switch (kind) {
+        case 'text':
+            return 0;
+        case 'raw':
+            return 1;
+        case 'attr':
+            return 2;
+        case 'repeat':
+            return 3;
+    }
+}
+function scan(html) {
+    let out = '';
+    let byteLen = 0;
+    const slots = [];
+    let i = 0;
+    const emit = (chunk) => {
+        out += chunk;
+        byteLen += Buffer.byteLength(chunk, 'utf8');
+    };
+    while (i < html.length) {
+        const start = html.indexOf(START, i);
+        if (start === -1) {
+            emit(html.slice(i));
+            break;
+        }
+        if (start > i)
+            emit(html.slice(i, start));
+        const kindChar = html[start + 1];
+        const tokEnd = html.indexOf(END, start + 2);
+        if (tokEnd === -1)
+            throw new Error('toil ssr: unterminated sentinel token');
+        const id = html.slice(start + 2, tokEnd);
+        const afterTok = tokEnd + 1;
+        if (kindChar === 'R') {
+            const closeTok = START + 'r' + id + END;
+            const closeIdx = html.indexOf(closeTok, afterTok);
+            if (closeIdx === -1) {
+                throw new Error(`toil ssr: unterminated repeat region "${id}"`);
+            }
+            const innerHtml = html.slice(afterTok, closeIdx);
+            const inner = scan(innerHtml);
+            slots.push({
+                id,
+                kind: 'repeat',
+                offset: byteLen,
+                rowTemplate: Buffer.from(inner.text, 'utf8'),
+                rowSlots: inner.slots,
+            });
+            i = closeIdx + closeTok.length;
+            continue;
+        }
+        const kind = kindChar === 't' ? 'text' : kindChar === 'h' ? 'raw' : kindChar === 'a' ? 'attr' : null;
+        if (kind === null) {
+            throw new Error(`toil ssr: unknown sentinel kind "${kindChar ?? ''}"`);
+        }
+        slots.push({ id, kind, offset: byteLen });
+        i = afterTok;
+    }
+    return { text: out, byteLen, slots };
+}
+export function extractFromHtml(html) {
+    const r = scan(html);
+    return { tmpl: Buffer.from(r.text, 'utf8'), slots: r.slots };
+}
+export function assignSlotIds(slots) {
+    const ids = new Map();
+    let next = 0;
+    for (const s of slots) {
+        if (!ids.has(s.id))
+            ids.set(s.id, next++);
+    }
+    return ids;
+}
+export function encodeSlots(tmplLen, hash, slots, slotIds) {
+    if (hash.length !== 32)
+        throw new Error('toil ssr: coherence hash must be 32 bytes');
+    const buf = Buffer.alloc(4 + 2 + 2 + 4 + 32 + 2 + slots.length * 8);
+    let o = 0;
+    buf.write('TSLT', o, 'ascii');
+    o += 4;
+    buf.writeUInt16LE(1, o);
+    o += 2;
+    buf.writeUInt16LE(0, o);
+    o += 2;
+    buf.writeUInt32LE(tmplLen, o);
+    o += 4;
+    hash.copy(buf, o);
+    o += 32;
+    buf.writeUInt16LE(slots.length, o);
+    o += 2;
+    for (const s of slots) {
+        const id = slotIds.get(s.id);
+        if (id === undefined)
+            throw new Error(`toil ssr: no slot id for "${s.id}"`);
+        buf.writeUInt32LE(s.offset, o);
+        o += 4;
+        buf.writeUInt16LE(id, o);
+        o += 2;
+        buf.writeUInt8(kindByte(s.kind), o);
+        o += 1;
+        buf.writeUInt8(0, o);
+        o += 1;
+    }
+    return buf;
+}
+function canonicalManifest(slots) {
+    return JSON.stringify(slots.map((s) => ({
+        id: s.id,
+        kind: s.kind,
+        offset: s.offset,
+        row: s.rowSlots ? canonicalManifest(s.rowSlots) : undefined,
+        rowLen: s.rowTemplate ? s.rowTemplate.length : undefined,
+    })));
+}
+export function coherenceHash(tmpl, slots) {
+    return createHash('sha256')
+        .update(tmpl)
+        .update('\0')
+        .update(canonicalManifest(slots), 'utf8')
+        .digest();
+}
+export function reactEscapeHtml(s) {
+    let out = '';
+    let last = 0;
+    for (let i = 0; i < s.length; i++) {
+        let rep;
+        switch (s.charCodeAt(i)) {
+            case 34:
+                rep = '&quot;';
+                break;
+            case 38:
+                rep = '&amp;';
+                break;
+            case 39:
+                rep = '&#x27;';
+                break;
+            case 60:
+                rep = '&lt;';
+                break;
+            case 62:
+                rep = '&gt;';
+                break;
+            default:
+                continue;
+        }
+        out += s.slice(last, i) + rep;
+        last = i + 1;
+    }
+    return last === 0 ? s : out + s.slice(last);
+}
+export function spliceTemplate(tmpl, inserts) {
+    const parts = [];
+    let prev = 0;
+    for (const ins of inserts) {
+        if (ins.offset > prev)
+            parts.push(tmpl.subarray(prev, ins.offset));
+        if (ins.value.length > 0)
+            parts.push(ins.value);
+        prev = ins.offset;
+    }
+    if (tmpl.length > prev)
+        parts.push(tmpl.subarray(prev));
+    return Buffer.concat(parts);
+}