npm - toiljs - Versions diffs - 0.0.77 → 0.0.79 - Mend

toiljs 0.0.77 → 0.0.79

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 (24) hide show

package/CHANGELOG.md +18 -0
package/build/cli/.tsbuildinfo +1 -1
package/build/client/.tsbuildinfo +1 -1
package/build/client/head/head.d.ts +1 -0
package/build/client/head/head.js +9 -0
package/build/client/index.d.ts +1 -1
package/build/client/index.js +1 -1
package/build/compiler/.tsbuildinfo +1 -1
package/build/compiler/seo.d.ts +1 -0
package/build/compiler/seo.js +1 -1
package/build/compiler/template-build.d.ts +16 -0
package/build/compiler/template-build.js +42 -1
package/build/devserver/.tsbuildinfo +1 -1
package/build/devserver/ssr.js +15 -1
package/examples/basic/client/layout.tsx +4 -1
package/package.json +1 -1
package/server/runtime/ssr/slots.ts +8 -0
package/src/client/head/head.ts +23 -0
package/src/client/index.ts +1 -1
package/src/compiler/seo.ts +1 -1
package/src/compiler/template-build.ts +74 -1
package/src/devserver/ssr.ts +23 -1
package/test/built-ssr.test.ts +50 -0
package/test/ssr-template.test.tsx +33 -0

package/src/compiler/template-build.ts CHANGED Viewed

@@ -46,7 +46,7 @@ import {
 } from './template.js';
 import { createViteConfig } from './vite.js';
 import { extractStaticMetadata, loadTypeScript } from './prerender.js';
-import { injectSeoHtml, routeSeo, type SeoConfig } from './seo.js';
+import { escapeAttr, escapeHtml, injectSeoHtml, routeSeo, type SeoConfig } from './seo.js';
 /** Marker element the client `mount` looks for to switch to `hydrateRoot`. */
 const SSR_MARKER = '<template id="__toil_ssr"></template>';
@@ -88,6 +88,9 @@ export interface RouteRenderInput {
     metadata?: Record<string, unknown> | null;
     /** The route pattern, used for the canonical / `og:url`. */
     pattern?: string;
+    /** Drains the component-level head (`useHead`/`useTitle`/`<Head>`) collected during this route's
+     * render, so it's baked into the SSR `<head>` too. From `toiljs/client`'s `__drainSsrHead`. */
+    drainSsrHead?: () => SsrHead;
 }
 export interface TemplateArtifacts {
@@ -152,6 +155,65 @@ function stripHoistedResourceTags(html: string): string {
         .replace(/<title\b[^>]*>[\s\S]*?<\/title>/gi, '');
 }
+/** The resolved component-level head drained from the client head manager during an SSR-build render
+ * (structurally `ResolvedHead` from `toiljs/client`). */
+interface SsrHead {
+    title?: string;
+    meta: { name?: string; property?: string; content: string; [attr: string]: string | undefined }[];
+    link: { rel: string; href: string; [attr: string]: string | undefined }[];
+}
+/** Render one head `<meta>`/`<link>` to an HTML tag, marked `data-toil-head` so the client head
+ * manager owns it on hydration (it removes + re-emits `[data-toil-head]` tags on every navigation,
+ * exactly as it does for the tags it adds at runtime — so there's no duplication or stale leak). */
+function headTag(tag: 'meta' | 'link', attrs: Record<string, string | undefined>): string {
+    const pairs = Object.entries(attrs)
+        .filter((e): e is [string, string] => e[1] !== undefined)
+        .map(([k, v]) => `${k}="${escapeAttr(v)}"`);
+    return `    <${tag} data-toil-head ${pairs.join(' ')} />`;
+}
+/**
+ * Bake the route's component-level head (layout `<Head>` + a page's `useHead`/`useTitle`, collected
+ * during render) into the document head: the title when the route's static `metadata` set none (the
+ * component title outranks the site default), plus any `<meta>`/`<link>` the route SEO didn't already
+ * carry — so the server HTML reflects the SAME head the client computes, not just the static metadata.
+ */
+function injectComponentHead(
+    html: string,
+    head: SsrHead,
+    routeMetadata: Record<string, unknown> | null,
+): string {
+    let out = html;
+    if (head.title !== undefined && (routeMetadata === null || routeMetadata.title === undefined)) {
+        const tag = `<title>${escapeHtml(head.title)}</title>`;
+        out = /<title>[\s\S]*?<\/title>/i.test(out)
+            ? out.replace(/<title>[\s\S]*?<\/title>/i, tag)
+            : out.replace(/<\/head>/i, `    ${tag}\n  </head>`);
+    }
+    const tags: string[] = [];
+    for (const m of head.meta) {
+        const key =
+            m.name !== undefined
+                ? `name="${m.name}"`
+                : m.property !== undefined
+                  ? `property="${m.property}"`
+                  : null;
+        if (key === null || out.includes(key)) continue; // already covered by the route SEO
+        tags.push(headTag('meta', m));
+    }
+    for (const l of head.link) {
+        if (out.includes(`href="${l.href}"`)) continue;
+        tags.push(headTag('link', l));
+    }
+    if (tags.length > 0) {
+        out = out.includes('</head>')
+            ? out.replace(/<\/head>/i, `${tags.join('\n')}\n  </head>`)
+            : `${tags.join('\n')}\n${out}`;
+    }
+    return out;
+}
 /** Render one route to its template artifacts (pure given its inputs). */
 export function extractRouteTemplate(input: RouteRenderInput): TemplateArtifacts {
     const h = input.createElement ?? createElement;
@@ -165,6 +227,8 @@ export function extractRouteTemplate(input: RouteRenderInput): TemplateArtifacts
         h,
         SuspenseComp,
     );
+    // Clear any specs leaked from a previously-failed route render before collecting this route's.
+    input.drainSsrHead?.();
     input.setSsrBuild(true);
     let routeHtml: string;
     try {
@@ -172,6 +236,9 @@ export function extractRouteTemplate(input: RouteRenderInput): TemplateArtifacts
     } finally {
         input.setSsrBuild(false);
     }
+    // The component-level head (layout <Head> + page useHead/useTitle) was collected during the render
+    // above; drain it now, per route, so it can be baked alongside the static SEO.
+    const componentHead: SsrHead = input.drainSsrHead?.() ?? { meta: [], link: [] };
     let full = injectIntoShell(input.shell, stripHoistedResourceTags(routeHtml));
     // Bake the route's resolved SEO into the template <head>, mirroring the static prerender
     // (prerender.ts / ssg.ts) so an `ssr=true` route serves the SAME per-page metadata (title,
@@ -182,6 +249,10 @@ export function extractRouteTemplate(input: RouteRenderInput): TemplateArtifacts
     if (input.seo) {
         full = injectSeoHtml(full, routeSeo(input.seo, input.metadata ?? null, input.pattern ?? '/'));
     }
+    // Then add the component-level head (a layout's <Head>, a page's useHead/useTitle) that the static
+    // metadata export + site SEO didn't already cover, so the server HTML carries the same head the
+    // client computes.
+    full = injectComponentHead(full, componentHead, input.metadata ?? null);
     const extracted: Extracted = extractFromHtml(full);
     const ids = assignSlotIds(extracted.slots);
     const hash = coherenceHash(extracted.tmpl, extracted.slots);
@@ -295,6 +366,7 @@ async function renderSsrRoutes(cfg: ResolvedToilConfig, shell: string): Promise<
     const client = (await server.ssrLoadModule('toiljs/client')) as unknown as {
         __setSsrBuild: (on: boolean) => void;
         __setSsrLocation: (path: string | null) => void;
+        __drainSsrHead: () => SsrHead;
         LoaderDataContext: Context<unknown>;
     };
@@ -372,6 +444,7 @@ async function renderSsrRoutes(cfg: ResolvedToilConfig, shell: string): Promise<
                     loaderData,
                     loaderContext: client.LoaderDataContext,
                     setSsrBuild: client.__setSsrBuild,
+                    drainSsrHead: client.__drainSsrHead,
                     shell,
                     createElement: react.createElement,
                     renderToString: reactDomServer.renderToString,

package/src/devserver/ssr.ts CHANGED Viewed

@@ -169,6 +169,19 @@ export interface SsrResult {
     html: Uint8Array;
 }
+/** The internal header a guest's `SlotValues.setTitle` rides in: the host splices its value into the
+ * document `<title>` and strips it, so a per-request title never reaches the client as a real header. */
+const SSR_TITLE_HEADER = 'x-toil-ssr-title';
+/** Replace the document `<title>` content (the guest set a per-request title; the value is already
+ * React-escaped). Mirrors the host `assemble` so dev and prod agree. */
+function replaceTitle(html: Uint8Array, title: string): Uint8Array {
+    const out = new TextDecoder()
+        .decode(html)
+        .replace(/<title>[\s\S]*?<\/title>/i, `<title>${title}</title>`);
+    return new TextEncoder().encode(out);
+}
 /**
  * Decode the guest envelope and splice it into `route`'s template. Returns null
  * to fall back to client rendering: a fail-safe envelope (status >= 500, e.g. no
@@ -182,5 +195,14 @@ export function assembleSsr(route: SsrRoute, envelope: Uint8Array): SsrResult |
     const inserts = route.entries
         .map((e) => ({ offset: e.offset, value: decoded.values.get(e.id) ?? new Uint8Array(0) }))
         .sort((a, b) => a.offset - b.offset);
-    return { status: decoded.status, headers: decoded.headers, html: splice(route.tmpl, inserts) };
+    let html = splice(route.tmpl, inserts);
+    // A guest-set per-request <title> (SlotValues.setTitle) rides in an internal header: splice it into
+    // the <title> and strip the header so it never reaches the client.
+    let headers = decoded.headers;
+    const ti = headers.findIndex(([k]) => k.toLowerCase() === SSR_TITLE_HEADER);
+    if (ti >= 0) {
+        html = replaceTitle(html, headers[ti][1]);
+        headers = headers.filter((_, i) => i !== ti);
+    }
+    return { status: decoded.status, headers, html };
 }

package/test/built-ssr.test.ts CHANGED Viewed

@@ -54,6 +54,41 @@ function valuesEnvelope(hash: Buffer, value: string): Buffer {
     return buf;
 }
+/** An envelope with one header (the internal SSR-title header) plus one text slot. */
+function envelopeWithTitle(hash: Buffer, value: string, title: string): Buffer {
+    const name = Buffer.from('x-toil-ssr-title');
+    const titleBytes = Buffer.from(title);
+    const valueBytes = Buffer.from(value);
+    const buf = Buffer.alloc(
+        2 + 32 + 2 + (2 + 2 + name.length + titleBytes.length) + 2 + (2 + 1 + 4 + valueBytes.length),
+    );
+    let o = 0;
+    buf.writeUInt16LE(200, o);
+    o += 2;
+    hash.copy(buf, o);
+    o += 32;
+    buf.writeUInt16LE(1, o); // 1 header
+    o += 2;
+    buf.writeUInt16LE(name.length, o);
+    o += 2;
+    buf.writeUInt16LE(titleBytes.length, o);
+    o += 2;
+    name.copy(buf, o);
+    o += name.length;
+    titleBytes.copy(buf, o);
+    o += titleBytes.length;
+    buf.writeUInt16LE(1, o); // 1 slot
+    o += 2;
+    buf.writeUInt16LE(0, o); // slot id 0
+    o += 2;
+    buf.writeUInt8(0, o); // text kind
+    o += 1;
+    buf.writeUInt32LE(valueBytes.length, o);
+    o += 4;
+    valueBytes.copy(buf, o);
+    return buf;
+}
 describe('built SSR templates', () => {
     it('loads the built shell, including production CSS links, from _ssr artifacts', () => {
         const root = fs.mkdtempSync(path.join(os.tmpdir(), 'toil-built-ssr-'));
@@ -95,4 +130,19 @@ describe('built SSR templates', () => {
         );
         expect(assembleSsr(route, valuesEnvelope(Buffer.alloc(32, 2), 'X'))).toBeNull();
     });
+    it('replaces the <title> from a guest setTitle header, then strips the internal header', () => {
+        const hash = Buffer.alloc(32, 1);
+        const route: SsrRoute = {
+            test: () => true,
+            tmpl: Buffer.from('<title>Static</title>ab'),
+            entries: [{ id: 0, offset: 22 }],
+            hash,
+        };
+        const out = assembleSsr(route, envelopeWithTitle(hash, 'X', 'Dynamic'))!;
+        // the body slot is spliced AND the <title> is replaced with the guest's per-request value
+        expect(Buffer.from(out.html).toString()).toBe('<title>Dynamic</title>aXb');
+        // the internal header never reaches the client
+        expect(out.headers.some(([k]) => k.toLowerCase() === 'x-toil-ssr-title')).toBe(false);
+    });
 });

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

@@ -446,4 +446,37 @@ describe('ssr build orchestration', () => {
         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" />');
+    });
 });