npm - @gusnips/vite - Versions diffs - 0.1.0 - Mend

@gusnips/vite 0.1.0

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

package/package.json ADDED Viewed

@@ -0,0 +1,105 @@
+{
+  "name": "@gusnips/vite",
+  "version": "0.1.0",
+  "description": "The build-time half of a prerendered Vite SPA: head baking, sitemap, robots, the prerender driver, and a shared vite preset.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Gustavo Salomé",
+  "homepage": "https://github.com/gusnips/frontkit/tree/main/vite#readme",
+  "bugs": {
+    "url": "https://github.com/gusnips/frontkit/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./preset": {
+      "types": "./dist/preset.d.ts",
+      "default": "./dist/preset.js"
+    },
+    "./render": {
+      "types": "./dist/render.d.ts",
+      "default": "./dist/render.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "vite",
+    "prerender",
+    "ssg",
+    "sitemap",
+    "open-graph",
+    "seo",
+    "react"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "sync:docs": "cp ../LICENSE .",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build && bun run sync:docs",
+    "release:patch": "bun pm version patch && bun publish --access public",
+    "release:minor": "bun pm version minor && bun publish --access public",
+    "release:major": "bun pm version major && bun publish --access public"
+  },
+  "dependencies": {
+    "@gusnips/react": "0.1.0"
+  },
+  "peerDependencies": {
+    "@tailwindcss/vite": "^4",
+    "@vitejs/plugin-react": "^6",
+    "react": "^19",
+    "react-dom": "^19",
+    "vite": "^8"
+  },
+  "peerDependenciesMeta": {
+    "@tailwindcss/vite": {
+      "optional": true
+    },
+    "@vitejs/plugin-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.2.2",
+    "@types/node": "^24.12.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.1",
+    "vitest": "^4.1.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gusnips/frontkit.git",
+    "directory": "vite"
+  }
+}

package/src/escape.ts ADDED Viewed

@@ -0,0 +1,8 @@
+/** Escaping shared by the head baker and the sitemap writer. Its own file so neither has to
+ *  import the other, and so both stay free of every dependency this package has. */
+/** `&` first, or the ampersands introduced by the later rules get escaped twice. */
+export const escapeAttr = (s: string): string =>
+  s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+export const escapeRegex = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");

package/src/head.test.ts ADDED Viewed

@@ -0,0 +1,258 @@
+import { describe, expect, it } from "vitest";
+import { PRERENDERED_ROUTE_ATTR } from "@gusnips/react";
+import { assertRendered, bakeHead, ogLocale } from "./head.ts";
+/**
+ * Every failure `bakeHead` has is invisible until somebody reads a search result months later
+ * — a canonical that survived onto a 404, an `og:locale` still claiming English on a Portuguese
+ * file, a body that never went in. `assertRendered` checks a written page as a whole; this
+ * checks the branches it cannot see the inside of.
+ */
+/** A template carrying the full donor tag set: OG, Twitter, and the `name="title"` two of the
+ *  three donors ship. */
+const TEMPLATE = `<!doctype html>
+<html lang="en">
+  <head>
+    <title>front</title>
+    <meta name="title" content="front" />
+    <meta name="description" content="front" />
+    <link rel="canonical" href="https://acme.com/" />
+    <meta property="og:title" content="front" />
+    <meta property="og:description" content="front" />
+    <meta property="og:url" content="https://acme.com/" />
+    <meta property="og:image" content="https://acme.com/og.png" />
+    <meta property="twitter:title" content="front" />
+    <meta property="twitter:description" content="front" />
+    <meta property="twitter:url" content="https://acme.com/" />
+    <meta property="twitter:image" content="https://acme.com/og.png" />
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>`;
+/** The leaner set a third donor ships: no `name="title"`, no `twitter:` pair. */
+const LEAN_TEMPLATE = `<!doctype html>
+<html lang="en">
+  <head>
+    <title>front</title>
+    <meta name="description" content="front" />
+    <link rel="canonical" href="https://acme.com/" />
+    <meta property="og:title" content="front" />
+    <meta property="og:description" content="front" />
+    <meta property="og:url" content="https://acme.com/" />
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>`;
+const BASE = { title: "T", description: "D", canonical: "https://acme.com/pricing" };
+describe("bakeHead", () => {
+  it("writes the page's own title, description and share text", () => {
+    const html = bakeHead(TEMPLATE, { ...BASE, ogTitle: "share", ogDescription: "sub" });
+    expect(html).toContain("<title>T</title>");
+    expect(html).toContain('<meta name="description" content="D" />');
+    expect(html).toContain('<meta property="og:title" content="share" />');
+    expect(html).toContain('<meta property="twitter:description" content="sub" />');
+    expect(html).toContain('<link rel="canonical" href="https://acme.com/pricing" />');
+    expect(html).toContain('<meta property="og:url" content="https://acme.com/pricing" />');
+  });
+  it("falls back to the page's own words for the share tags", () => {
+    const html = bakeHead(TEMPLATE, BASE);
+    expect(html).toContain('<meta property="og:title" content="T" />');
+    expect(html).toContain('<meta property="twitter:title" content="T" />');
+  });
+  it("escapes what it writes into an attribute", () => {
+    const html = bakeHead(TEMPLATE, { ...BASE, description: 'a "quote" & <tag>' });
+    expect(html).toContain('content="a &quot;quote&quot; &amp; &lt;tag&gt;"');
+  });
+  // The whole reason `setMeta` throws: editing index.html must fail the build, never ship a
+  // page quietly wearing the front door's description.
+  it("refuses a template missing a tag a crawler depends on", () => {
+    const stripped = TEMPLATE.replace(/<meta property="og:title"[^>]*>/, "");
+    expect(() => bakeHead(stripped, BASE)).toThrow(/og:title/);
+  });
+  // …and the exception: nothing reads `name="title"`, and X reads `og:` when `twitter:` is
+  // absent. A template without them is correct, so demanding them would break a real app.
+  it("skips the optional tags a template does not carry", () => {
+    const html = bakeHead(LEAN_TEMPLATE, BASE);
+    expect(html).toContain('<meta property="og:title" content="T" />');
+    expect(html).not.toContain("twitter:");
+    expect(html).not.toContain('name="title"');
+  });
+  it("strips the canonical and the share URL rather than blanking them", () => {
+    const html = bakeHead(TEMPLATE, { ...BASE, canonical: null, noindex: true });
+    expect(html).not.toContain('rel="canonical"');
+    expect(html).not.toContain('property="og:url"');
+    expect(html).not.toContain('property="twitter:url"');
+    expect(html).toContain('<meta name="robots" content="noindex" />');
+  });
+  // An empty canonical is a claim about "" and an empty og:url is a share card pointing at the
+  // origin root, which is what the strip exists to avoid.
+  it("leaves no blank URL behind on a page with no canonical", () => {
+    const html = bakeHead(TEMPLATE, { ...BASE, canonical: null });
+    expect(html).not.toContain('href=""');
+    expect(html).not.toContain('content=""');
+  });
+  // The card is a picture, not a claim about this address: a dead link that still unfurls the
+  // brand card is fine, and a 404 with no image at all is not better.
+  it("keeps the share card on a page with no canonical", () => {
+    const html = bakeHead(TEMPLATE, { ...BASE, canonical: null });
+    expect(html).toContain('<meta property="og:image" content="https://acme.com/og.png" />');
+  });
+  it("lists every alternate, reciprocally, including this page's own", () => {
+    const html = bakeHead(TEMPLATE, {
+      ...BASE,
+      alternates: [
+        { hreflang: "en", href: "https://acme.com/pricing" },
+        { hreflang: "pt-BR", href: "https://acme.com/pt/pricing" },
+        { hreflang: "x-default", href: "https://acme.com/pricing" },
+      ],
+    });
+    expect(html.match(/rel="alternate"/g)).toHaveLength(3);
+    expect(html).toContain('hreflang="pt-BR" href="https://acme.com/pt/pricing"');
+  });
+  it("marks the file's own language for a crawler and a screen reader", () => {
+    const html = bakeHead(TEMPLATE, { ...BASE, lang: "pt-BR" });
+    expect(html).toContain('<html lang="pt-BR">');
+  });
+  it("refuses a template whose <html> has no lang to rewrite", () => {
+    const stripped = TEMPLATE.replace('<html lang="en">', "<html>");
+    expect(() => bakeHead(stripped, { ...BASE, lang: "pt-BR" })).toThrow(/<html lang>/);
+  });
+  // Invariant 6: absent, `og:locale` does not default to "unknown" — it defaults to en_US, so
+  // a Portuguese page with a Portuguese og:title told every share crawler the card was English.
+  it("states og:locale, and the other languages the page exists in", () => {
+    const html = bakeHead(TEMPLATE, {
+      ...BASE,
+      lang: "pt-BR",
+      alternates: [
+        { hreflang: "en", href: "https://acme.com/pricing" },
+        { hreflang: "pt-BR", href: "https://acme.com/pt/pricing" },
+        { hreflang: "x-default", href: "https://acme.com/pricing" },
+      ],
+    });
+    expect(html).toContain('<meta property="og:locale" content="pt_BR" />');
+    expect(html).toContain('<meta property="og:locale:alternate" content="en_US" />');
+    // Not itself, and not x-default — neither is another language this page exists in.
+    expect(html.match(/og:locale:alternate/g)).toHaveLength(1);
+  });
+  // A template that already carries one would otherwise end up with two, and a crawler reading
+  // the first would get the template's language on every page.
+  it("replaces an og:locale the template already carries", () => {
+    const withLocale = TEMPLATE.replace(
+      "</head>",
+      '  <meta property="og:locale" content="en_US" />\n  </head>',
+    );
+    const html = bakeHead(withLocale, { ...BASE, lang: "pt-BR" });
+    expect(html.match(/property="og:locale"/g)).toHaveLength(1);
+    expect(html).toContain('content="pt_BR"');
+  });
+  it("puts the render inside the root and names the route it is a render of", () => {
+    const html = bakeHead(TEMPLATE, {
+      ...BASE,
+      body: { route: "/pricing", html: "<main>hi</main>" },
+    });
+    expect(html).toContain(
+      `<div id="root" ${PRERENDERED_ROUTE_ATTR}="/pricing"><main>hi</main></div>`,
+    );
+  });
+  it("refuses to bake a page into a page", () => {
+    const once = bakeHead(TEMPLATE, { ...BASE, body: { route: "/", html: "<main>hi</main>" } });
+    expect(() =>
+      bakeHead(once, { ...BASE, body: { route: "/x", html: "<main>x</main>" } }),
+    ).toThrow(/root/);
+  });
+  it("carries structured data through untouched", () => {
+    const html = bakeHead(TEMPLATE, {
+      ...BASE,
+      headExtra: '<script type="application/ld+json">{"@type":"FAQPage"}</script>',
+    });
+    expect(html).toContain('<script type="application/ld+json">{"@type":"FAQPage"}</script>');
+  });
+});
+describe("ogLocale", () => {
+  it("gives en and es the territory Open Graph will not infer", () => {
+    expect(ogLocale("en")).toBe("en_US");
+    expect(ogLocale("es")).toBe("es_ES");
+  });
+  it("respells a tag that already carries its territory", () => {
+    expect(ogLocale("pt-BR")).toBe("pt_BR");
+  });
+});
+describe("assertRendered", () => {
+  const shell = `<html lang="en"><head><title>T</title></head><body><div id="root"></div></body></html>`;
+  const page = (body: string): string => shell.replace('<div id="root"></div>', body);
+  const long = `<main>${"x".repeat(800)}</main>`;
+  it("passes a page with a real body in it", () => {
+    expect(() =>
+      assertRendered("pricing.html", page(`<div id="root">${long}</div>`), shell),
+    ).not.toThrow();
+  });
+  // Invariant 1: a router whose basename does not match its location renders "" with no error
+  // and no warning. Only the bytes catch it.
+  it("catches a root that rendered to nothing", () => {
+    expect(() => assertRendered("pricing.html", shell, shell)).toThrow(/nothing rendered/);
+  });
+  // The size floor is not enough, and a donor proved it: a route rendered its LoadingScreen at
+  // 1,174 bytes, comfortably over the floor, with an element inside the root and a good title.
+  it("catches a file whose body is the loading screen", () => {
+    const spinner = `<div id="root"><div role="status" aria-label="Loading">${"x".repeat(800)}</div></div>`;
+    expect(() => assertRendered("pricing.html", page(spinner), shell)).toThrow(/loading screen/);
+  });
+  // The reason the check slices rather than matching in one pattern: a regex that skips
+  // Suspense markers can backtrack across the whole document and find a `role="status"` 40 KB
+  // down in a perfectly good page.
+  it("does not mistake a status role deep in a real page for a spinner", () => {
+    const deep = `<div id="root"><main>${"x".repeat(2000)}<div role="status">saved</div></main></div>`;
+    expect(() => assertRendered("pricing.html", page(deep), shell)).not.toThrow();
+  });
+  it("sees past React's Suspense comment markers", () => {
+    const suspended = `<div id="root"><!--$--><main>${"x".repeat(800)}</main><!--/$--></div>`;
+    expect(() => assertRendered("pricing.html", page(suspended), shell)).not.toThrow();
+  });
+  it("catches an unsubstituted html placeholder", () => {
+    const raw = page(`<div id="root"><main>%BRAND_NAME% ${"x".repeat(800)}</main></div>`);
+    expect(() => assertRendered("pricing.html", raw, shell)).toThrow(/%BRAND_NAME%/);
+  });
+  // `/caf%C3%A9` contains `%C3%`, and an accented slug is not a broken build.
+  it("does not mistake a percent-encoded link for a placeholder", () => {
+    const link = `<div id="root"><main><a href="/caf%C3%A9">x</a>${"x".repeat(800)}</main></div>`;
+    expect(() => assertRendered("pricing.html", page(link), shell)).not.toThrow();
+  });
+  it("catches a file that is not marked as the language it was baked for", () => {
+    const html = page(`<div id="root">${long}</div>`);
+    expect(() => assertRendered("pt/pricing.html", html, shell, { lang: "pt-BR" })).toThrow(
+      /not marked as pt-BR/,
+    );
+  });
+});

package/src/head.ts ADDED Viewed

@@ -0,0 +1,288 @@
+/**
+ * The head a crawler sees, baked at build time.
+ *
+ * A Vite SPA ships one `index.html` and draws everything else with JavaScript. Nothing that
+ * reads a link for a living runs that bundle — not Google's first pass, not Bing, not an LLM
+ * crawler, not whatever draws the preview card in Slack. So the build rewrites the template
+ * once per route and writes a real file per page, with a real `<head>` AND a real body.
+ *
+ * Pure string work, on purpose: no `node:` import anywhere in this file, so every branch is
+ * unit-testable without a filesystem. The reading and writing lives in `node.ts`.
+ */
+// The `/contract` subpath, not the barrel: the barrel reaches `react-dom/client` through
+// `hydrate.ts`, and a build script asking for one string should not pull the browser renderer
+// into a Node process. That file imports nothing at all.
+import { PRERENDERED_ROUTE_ATTR } from "@gusnips/react/contract";
+import { escapeAttr, escapeRegex } from "./escape.ts";
+/** The empty root a template must carry — `bakeHead` fills it, and refuses a filled one. */
+export const EMPTY_ROOT = '<div id="root"></div>';
+/** `[^>]*` on both sides tolerates the attributes being split across lines, as Vite emits them. */
+const metaRe = (selector: string): RegExp =>
+  new RegExp(`(<meta[^>]*${escapeRegex(selector)}[^>]*content=")[^"]*(")`);
+/**
+ * Replace the `content` of one `<meta …>`. Throws when the tag is missing, so an edit to
+ * `index.html` fails the build instead of silently shipping the front door's description to
+ * every crawler.
+ */
+function setMeta(html: string, selector: string, value: string): string {
+  const re = metaRe(selector);
+  if (!re.test(html)) throw new Error(`prerender: <meta ${selector}> not found in index.html`);
+  return html.replace(re, `$1${escapeAttr(value)}$2`);
+}
+/**
+ * The same, for a tag a template is allowed not to carry.
+ *
+ * Only the `twitter:` pair and `name="title"` get this. X reads the `og:` tags when the
+ * `twitter:` ones are absent, and no crawler reads `name="title"` at all — so a template that
+ * omits them is correct, and demanding them would break an app that never had them. A template
+ * that DOES carry one and gets a stale value is still a bug, which is why they are written
+ * rather than ignored. Everything a crawler actually depends on goes through `setMeta`.
+ */
+function setMetaIfPresent(html: string, selector: string, value: string): string {
+  const re = metaRe(selector);
+  return re.test(html) ? html.replace(re, `$1${escapeAttr(value)}$2`) : html;
+}
+/** One `<link rel="alternate" hreflang>` — this page's address in another language. */
+export interface Alternate {
+  /** A BCP-47 tag, or `x-default` for the address a crawler should show when it has no reason
+   *  to prefer one. */
+  hreflang: string;
+  href: string;
+}
+export interface HeadTags {
+  /** `<title>`, and the share title unless overridden. */
+  title: string;
+  /** `name="description"`, and the share description unless overridden. */
+  description: string;
+  /**
+   * The page's own URL, for `<link rel="canonical">` and the share tags.
+   *
+   * `null` means this page has no canonical URL and must not claim one — the 404 shell, which
+   * is served for every address that does not exist and would otherwise tell a crawler that
+   * all of them are the front page.
+   */
+  canonical: string | null;
+  ogTitle?: string;
+  ogDescription?: string;
+  /** Absolute URL of the share card. Omit where the template carries no `og:image` tag at all
+   *  — setting one there is a build error, by design. */
+  image?: string;
+  /** Markup inserted before `</head>` — structured data, and nothing else so far. Emitted here
+   *  because its only reader is a crawler. */
+  headExtra?: string;
+  /** Keep this page out of every index. Pairs with `canonical: null`. */
+  noindex?: boolean;
+  /**
+   * `<html lang>`, when this page is not in the template's language, and the `og:locale` that
+   * goes with it.
+   *
+   * A crawler and a screen reader both read `lang`, and neither runs the bundle that would
+   * otherwise set it — so a Portuguese file whose `<html>` still says `en` is announced in the
+   * wrong voice and indexed as the wrong language.
+   */
+  lang?: string;
+  /**
+   * Every language this page exists in, INCLUDING this one, plus `x-default`.
+   *
+   * Reciprocal by contract: a crawler ignores the whole set unless each address in it points
+   * back at the others, which is why the caller passes the full list to every page rather than
+   * "the other two".
+   */
+  alternates?: readonly Alternate[];
+  /**
+   * The rendered page, injected into `<div id="root">`, and the route it is a render OF.
+   *
+   * The head alone was never enough. A shipped `<div id="root"></div>` is a page whose entire
+   * content is a description tag — it can be listed, and it can never be read, quoted or
+   * answered from.
+   *
+   * The two travel together because markup alone is not enough to hydrate against. A static
+   * host answers every unpublished address with the nearest `404.html`, and that file has a
+   * rendered body in it — so a route served from the shell would find a full root and hydrate
+   * the not-found page into a page that is not it. The marker is what the browser entry
+   * compares its own route against before deciding to hydrate or to mount fresh.
+   */
+  body?: { route: string; html: string };
+}
+/**
+ * A BCP-47 tag in Open Graph's spelling: underscore, and a TERRITORY it will not infer.
+ *
+ * `og:locale` wants `language_TERRITORY` and quietly ignores anything else, which is the same
+ * outcome as omitting it — the `en_US` default. So a Portuguese page with a Portuguese
+ * `og:title` and no `og:locale` tells every share crawler the card is English. `pt-BR` already
+ * carries its territory; `en` and `es` do not, so one is chosen here rather than left to a
+ * crawler. `es_ES` is not a claim that the copy is peninsular Spanish — it is the most widely
+ * recognised Spanish value, and the tag's job is to be understood, not precise about dialect.
+ */
+export function ogLocale(tag: string): string {
+  const TERRITORY: Record<string, string> = { en: "en_US", es: "es_ES" };
+  return TERRITORY[tag] ?? tag.replace("-", "_");
+}
+/**
+ * One page's `<head>` and body, written into the built template.
+ *
+ * Every tag is SET rather than appended, and `setMeta` throws on a tag the template does not
+ * carry — so the failure mode of editing `index.html` is a red build, never a page quietly
+ * shipping somebody else's description.
+ */
+export function bakeHead(template: string, tags: HeadTags): string {
+  const shareTitle = tags.ogTitle ?? tags.title;
+  const shareDescription = tags.ogDescription ?? tags.description;
+  let html = template.replace(/<title>[^<]*<\/title>/, `<title>${escapeAttr(tags.title)}</title>`);
+  html = setMeta(html, 'name="description"', tags.description);
+  html = setMeta(html, 'property="og:title"', shareTitle);
+  html = setMeta(html, 'property="og:description"', shareDescription);
+  html = setMetaIfPresent(html, 'name="title"', tags.title);
+  html = setMetaIfPresent(html, 'property="twitter:title"', shareTitle);
+  html = setMetaIfPresent(html, 'property="twitter:description"', shareDescription);
+  if (tags.image !== undefined) {
+    html = setMeta(html, 'property="og:image"', tags.image);
+    html = setMetaIfPresent(html, 'property="twitter:image"', tags.image);
+  }
+  if (tags.canonical === null) {
+    // Strip rather than blank: an empty canonical is a claim about "" and an empty og:url is a
+    // share card pointing at the origin root. The image is left alone — it is a picture, not a
+    // claim about this address, and a dead link that still unfurls the brand card is fine.
+    html = html
+      .replace(/\s*<link rel="canonical"[^>]*>/, "")
+      .replace(/\s*<meta property="(?:og|twitter):url"[^>]*>/g, "");
+  } else {
+    html = setMeta(html, 'property="og:url"', tags.canonical);
+    html = setMetaIfPresent(html, 'property="twitter:url"', tags.canonical);
+    html = html.replace(
+      /(<link rel="canonical" href=")[^"]*(")/,
+      `$1${escapeAttr(tags.canonical)}$2`,
+    );
+  }
+  if (tags.alternates?.length) {
+    const links = tags.alternates
+      .map(
+        (alt) =>
+          `    <link rel="alternate" hreflang="${escapeAttr(alt.hreflang)}" href="${escapeAttr(alt.href)}" />`,
+      )
+      .join("\n");
+    html = html.replace("</head>", `${links}\n  </head>`);
+  }
+  if (tags.lang !== undefined) {
+    // `og:locale` is not the same claim as `<html lang>` and is read by different machines.
+    // APPENDED rather than set, because a Vite template carries no such tag — but one that
+    // does would end up with two, and a crawler reading the first would get the template's
+    // language on every page. So drop whatever is there before writing this page's own.
+    html = html.replace(/\s*<meta property="og:locale(?::alternate)?"[^>]*>/g, "");
+    const alternates = (tags.alternates ?? [])
+      .filter((alt) => alt.hreflang !== "x-default" && alt.hreflang !== tags.lang)
+      .map(
+        (alt) =>
+          `    <meta property="og:locale:alternate" content="${escapeAttr(ogLocale(alt.hreflang))}" />`,
+      );
+    html = html.replace(
+      "</head>",
+      `    <meta property="og:locale" content="${escapeAttr(ogLocale(tags.lang))}" />\n${
+        alternates.length ? `${alternates.join("\n")}\n` : ""
+      }  </head>`,
+    );
+  }
+  if (tags.noindex)
+    html = html.replace("</head>", `    <meta name="robots" content="noindex" />\n  </head>`);
+  if (tags.headExtra) html = html.replace("</head>", `    ${tags.headExtra}\n  </head>`);
+  if (tags.lang !== undefined) {
+    const re = /(<html[^>]*\blang=")[^"]*(")/;
+    if (!re.test(html)) throw new Error("prerender: <html lang> not found in index.html");
+    html = html.replace(re, `$1${escapeAttr(tags.lang)}$2`);
+  }
+  if (tags.body !== undefined) {
+    // Empty on purpose in the template, and it must STAY empty there: a second bake over an
+    // already-filled root would nest one render inside another.
+    if (!html.includes(EMPTY_ROOT))
+      throw new Error(`prerender: ${EMPTY_ROOT} not found in index.html`);
+    html = html.replace(
+      EMPTY_ROOT,
+      `<div id="root" ${PRERENDERED_ROUTE_ATTR}="${escapeAttr(tags.body.route)}">${tags.body.html}</div>`,
+    );
+  }
+  return html;
+}
+export interface RenderedChecks {
+  /** The BCP-47 tag this file must be marked with — the same `lang` passed to `bakeHead`. */
+  lang?: string;
+  /** Bytes the page must have gained over the template before it counts as rendered.
+   *  500 is the floor both donor builds ran with. */
+  minGrowth?: number;
+}
+/**
+ * What every written file must be true of before the build is allowed to pass.
+ *
+ * The regression this exists for is a root that renders to nothing. A router whose location
+ * does not match its routes yields empty markup with no error and no warning — it looks fine
+ * in every browser and is invisible to everything that reads a link. Checking the bytes we
+ * actually wrote is the only thing that catches it, and it needs no browser, so it gates the
+ * BUILD rather than sitting in a test suite.
+ *
+ * The loading-screen check is the half a size floor misses. With `lazy()` routes behind one
+ * `<Suspense fallback={<Spinner />}>`, a render that resolves nothing still produces a
+ * plausible body: one donor shipped a 1,174-byte spinner with a perfect title and an element
+ * inside the root. A file whose body is a spinner is WORSE than an empty one, because every
+ * cheap check passes.
+ */
+export function assertRendered(
+  file: string,
+  html: string,
+  template: string,
+  checks: RenderedChecks = {},
+): void {
+  function fail(why: string): never {
+    throw new Error(`prerender: ${file} ${why}`);
+  }
+  // Measured against the template rather than by matching the root's closing tag — the body is
+  // thousands of nested `</div>`s and no regex should be asked to find the right one.
+  // Everything this file has over the shell it was baked from is the page.
+  const floor = checks.minGrowth ?? 500;
+  const grew = html.length - template.length;
+  if (grew < floor) fail(`is only ${String(grew)} bytes bigger than the shell — nothing rendered`);
+  if (/<title>\s*<\/title>/.test(html)) fail("has an empty <title>");
+  if (checks.lang !== undefined && !html.includes(`<html lang="${checks.lang}"`))
+    fail(`is not marked as ${checks.lang}`);
+  // A `%NAME%` the HTML transform never filled in. Three inner characters minimum, because two
+  // is the shape of percent-encoding: `/caf%C3%A9` contains `%C3%`, and an accented slug is not
+  // a broken build.
+  const placeholder = /%[A-Z][A-Z0-9_]{2,}%/.exec(html);
+  if (placeholder) fail(`still carries an unsubstituted placeholder, ${placeholder[0]}`);
+  // What the root ACTUALLY opens with. Sliced rather than matched in one pattern, because a
+  // regex that skips React's `<!--$-->` Suspense markers with `(?:<!--.*?-->|\s)*` can backtrack
+  // across the whole document — it will happily skip 40 KB of real page to find a
+  // `role="status"` further down and report a perfectly good file as a spinner. It did exactly
+  // that in the donor before this was rewritten as a slice.
+  const opened = /<div id="root"[^>]*>/.exec(html);
+  if (!opened) fail("has no root element at all");
+  const start = opened.index + opened[0].length;
+  const head = html
+    .slice(start, start + 600)
+    .replace(/<!--.*?-->/g, "")
+    .trimStart();
+  if (!/^<[a-z]/.test(head)) fail("has no element inside its root");
+  if (/^<[^>]*role="status"/.test(head))
+    fail("rendered the loading screen, not the page — something suspended and never resolved");
+}