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/src/index.ts ADDED Viewed

@@ -0,0 +1,59 @@
+/**
+ * The build-time half of a prerendered Vite + React SPA.
+ *
+ * A Vite SPA ships one `index.html` and draws the rest with JavaScript. Nothing that reads a
+ * link for a living runs that bundle — not a search crawler, not an LLM, not the thing that
+ * draws the preview card in a chat app. So the build renders every public route to a real file
+ * with a real `<head>` and a real body, and this is the part every app doing that shares.
+ *
+ * Four repos wrote it independently and each learned something the others had not. What is
+ * here is the merge; every non-obvious rule carries the reason it exists.
+ *
+ * Two things live behind their own subpath, because each drags a dependency this barrel would
+ * otherwise force on everyone: the vite config preset at `@gusnips/vite/preset` (the React and
+ * Tailwind plugins) and `renderTree` at `@gusnips/vite/render` (React itself). Nothing here
+ * imports React or vite, so a prerender script, an OG generator and a repo that only wants a
+ * sitemap all install exactly what they use.
+ */
+export {
+  assertRendered,
+  bakeHead,
+  EMPTY_ROOT,
+  ogLocale,
+  type Alternate,
+  type HeadTags,
+  type RenderedChecks,
+} from "./head.ts";
+export {
+  loadRenderer,
+  loadTemplate,
+  writeDist,
+  writeOgCards,
+  type OgCard,
+  type WriteOgCardsOptions,
+} from "./node.ts";
+export {
+  describeOverflow,
+  fitText,
+  OG_CANVAS,
+  type FitOptions,
+  type FitResult,
+  type OgOverflow,
+} from "./og.ts";
+// `renderTree` itself is NOT here — it lives at `@gusnips/vite/render`, because it is the one
+// thing in this package that loads React. Its consumer is `entry-server.tsx`, a different file
+// in a different bundle to the prerender script, and a repo using this only for `sitemapXml`
+// and `robotsTxt` should not have to install a renderer. The TYPE is free: it erases.
+export type { PageRenderer } from "./render.ts";
+export {
+  ogImagePath,
+  pageFile,
+  pageSlug,
+  robotsTxt,
+  siteOrigin,
+  sitemapFor,
+  sitemapXml,
+  type PublicPage,
+  type RobotsOptions,
+  type SitemapEntry,
+} from "./sitemap.ts";

package/src/node.test.ts ADDED Viewed

@@ -0,0 +1,102 @@
+import { mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { loadTemplate, writeOgCards } from "./node.ts";
+const dirs: string[] = [];
+async function tempDist(indexHtml: string): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "frontkit-vite-"));
+  dirs.push(dir);
+  await writeFile(join(dir, "index.html"), indexHtml, "utf8");
+  return dir;
+}
+afterEach(async () => {
+  await Promise.all(dirs.map((dir) => rm(dir, { recursive: true, force: true })));
+  dirs.length = 0;
+});
+describe("loadTemplate", () => {
+  it("reads the built shell", async () => {
+    const dist = await tempDist('<html><body><div id="root"></div></body></html>');
+    await expect(loadTemplate(dist)).resolves.toContain('<div id="root"></div>');
+  });
+  /**
+   * `dist/index.html` is both the template and the front page's destination, so a second run
+   * over a `dist/` the prerender already touched would read a finished page as its blank shell
+   * and nest one render inside another. `vite build` empties `dist/` and normally makes this
+   * impossible; a restored build cache does not.
+   */
+  it("refuses a dist that is already a rendered page", async () => {
+    const dist = await tempDist(
+      '<html><body><div id="root" data-prerendered-route="/"><main>hi</main></div></body></html>',
+    );
+    await expect(loadTemplate(dist)).rejects.toThrow(/already a rendered page/);
+  });
+});
+describe("writeOgCards", () => {
+  const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+  it("writes one card per page", async () => {
+    const out = join(await tempDist("<html></html>"), "og");
+    await writeOgCards({
+      pages: ["/", "/pricing"],
+      outDir: out,
+      file: (path) => `${path === "/" ? "home" : path.slice(1)}.png`,
+      card: () => ({ png }),
+    });
+    expect((await readdir(out)).sort()).toEqual(["home.png", "pricing.png"]);
+  });
+  /**
+   * A card that cannot hold its copy is a product decision, not something to resolve with an
+   * ellipsis — and nothing is written, so a half-updated `public/og` never gets committed.
+   */
+  it("refuses the whole run when one card cannot hold its copy, and writes nothing", async () => {
+    const out = join(await tempDist("<html></html>"), "og");
+    const run = writeOgCards({
+      pages: ["/", "/pricing"],
+      outDir: out,
+      file: (path) => `${path === "/" ? "home" : path.slice(1)}.png`,
+      card: (path) => ({
+        png,
+        overflow:
+          path === "/pricing"
+            ? [
+                {
+                  label: "pricing headline",
+                  text: "far too long",
+                  maxLines: 2,
+                  maxChars: 20,
+                  size: 60,
+                },
+              ]
+            : undefined,
+      }),
+    });
+    await expect(run).rejects.toThrow(/pricing headline/);
+    await expect(readdir(out)).rejects.toThrow();
+  });
+  // Copy lands per locale in batches; a build that dies on the first of six sends its operator
+  // round the loop six times.
+  it("names every bad card in one run", async () => {
+    const out = join(await tempDist("<html></html>"), "og");
+    const run = writeOgCards({
+      pages: ["/a", "/b"],
+      outDir: out,
+      file: (path) => `${path.slice(1)}.png`,
+      card: (path) => ({
+        png,
+        overflow: [
+          { label: `${path} headline`, text: "far too long", maxLines: 2, maxChars: 20, size: 60 },
+        ],
+      }),
+    });
+    await expect(run).rejects.toThrow(/2 card\(s\)/);
+  });
+});

package/src/node.ts ADDED Viewed

@@ -0,0 +1,140 @@
+/**
+ * The whole filesystem surface of this package: read the template, load the SSR bundle, write
+ * files.
+ *
+ * It is one file on purpose. Everything else here is string work that a test can run without a
+ * disk, and keeping the four impure functions together is what lets `head.ts`, `sitemap.ts`,
+ * `render.ts` and `og.ts` stay that way.
+ *
+ * The prerender LOOP is not here. Every donor's loop is different — one walks a registry once,
+ * another walks it per locale, a third writes three separate shells — and all of that is
+ * policy the product owns. What is identical in every one of them is these four functions and
+ * the gate in `assertRendered`, so those ship and the ~40-line loop stays in the app.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { EMPTY_ROOT } from "./head.ts";
+import type { OgOverflow } from "./og.ts";
+import { describeOverflow } from "./og.ts";
+import type { PageRenderer } from "./render.ts";
+/**
+ * The built `index.html`, and a refusal to bake one twice.
+ *
+ * `dist/index.html` is BOTH the template and the front page's destination, so a second run over
+ * a `dist/` the prerender has already touched would read a finished page as its blank shell and
+ * nest one render inside another. `vite build` empties `dist/` and normally makes this
+ * impossible; what does not is a restored build cache, or somebody running the script directly
+ * to debug it. Caught here, by name, rather than as a missing-root error three frames down.
+ */
+export async function loadTemplate(distDir: string): Promise<string> {
+  const file = join(distDir, "index.html");
+  const template = await readFile(file, "utf8");
+  if (!template.includes(EMPTY_ROOT))
+    throw new Error(
+      `prerender: ${file} does not carry ${EMPTY_ROOT}. Either it is already a rendered page ` +
+        "— run `vite build` to regenerate the shell this reads — or the app's root element " +
+        "carries attributes, which the baker cannot fill.",
+    );
+  return template;
+}
+function exportsRenderer<Context>(mod: unknown): mod is { renderPage: PageRenderer<Context> } {
+  return (
+    typeof mod === "object" &&
+    mod !== null &&
+    "renderPage" in mod &&
+    typeof mod.renderPage === "function"
+  );
+}
+/**
+ * The app compiled for the server, imported out of the BUILT bundle.
+ *
+ * The prerender is a script rather than a Vite plugin for exactly this reason: it needs the SSR
+ * bundle, and a plugin running in `closeBundle` is inside the build that would have to have
+ * produced it. So the entry is a path on disk, written by `vite build --ssr src/entry-server.tsx`,
+ * and nothing in the source tree references it.
+ */
+export async function loadRenderer<Context = unknown>(
+  entryFile: string,
+): Promise<PageRenderer<Context>> {
+  const mod: unknown = await import(pathToFileURL(entryFile).href);
+  if (!exportsRenderer<Context>(mod))
+    throw new Error(
+      `prerender: ${entryFile} does not export renderPage — run \`vite build --ssr\` first`,
+    );
+  return mod.renderPage;
+}
+/** Write one file under `dist`, creating the folders a nested route needs. */
+export async function writeDist(distDir: string, file: string, contents: string): Promise<void> {
+  const target = join(distDir, file);
+  await mkdir(dirname(target), { recursive: true });
+  await writeFile(target, contents, "utf8");
+}
+/** One laid-out share card: the bytes, and anything that did not fit. */
+export interface OgCard {
+  png: Uint8Array;
+  /** Copy the layout could not hold. A single one refuses the whole run — see
+   *  {@link writeOgCards}. */
+  overflow?: readonly OgOverflow[];
+}
+export interface WriteOgCardsOptions<Page> {
+  pages: readonly Page[];
+  /** Where the cards land — `public/og` in both donors, so they are committed beside the
+   *  favicons and served as static files. */
+  outDir: string;
+  /** The file name for one page, inside `outDir`. `(page) => \`${pageSlug(page.path)}.png\``. */
+  file: (page: Page) => string;
+  /** Lay one card out and rasterize it. The card's art is the product's; this only drives it. */
+  card: (page: Page) => OgCard | Promise<OgCard>;
+  /** Lay every card out and report, without writing anything. */
+  check?: boolean;
+}
+/**
+ * Walk a page registry and write one share card per page.
+ *
+ * Every card is laid out BEFORE any is written, and a single line that does not fit refuses the
+ * whole run. That order is the point: a card that cannot hold its copy is a product decision,
+ * not something to resolve with an ellipsis — an ellipsis makes every string "fit", so
+ * overgrown copy has no failing case and ships a card missing the end of the one line the card
+ * exists to carry. The reader who finds out is someone else's link unfurl.
+ *
+ * Overflow is collected rather than thrown on the first card, so one run names every bad one:
+ * copy lands per locale in batches, and a build that dies on the first of six sends its
+ * operator round the loop six times.
+ */
+export async function writeOgCards<Page>({
+  pages,
+  outDir,
+  file,
+  card,
+  check = false,
+}: WriteOgCardsOptions<Page>): Promise<string[]> {
+  const laid: { file: string; png: Uint8Array }[] = [];
+  const overflows: OgOverflow[] = [];
+  for (const page of pages) {
+    const { png, overflow } = await card(page);
+    if (overflow?.length) overflows.push(...overflow);
+    laid.push({ file: file(page), png });
+  }
+  if (overflows.length > 0)
+    throw new Error(
+      `og: ${String(overflows.length)} card(s) cannot hold their copy —\n\n` +
+        overflows.map((o) => `  · ${describeOverflow(o)}`).join("\n\n") +
+        "\n\n  Shorten the copy, or change the size ladder deliberately. Nothing was written.",
+    );
+  if (check) return laid.map((entry) => entry.file);
+  await mkdir(outDir, { recursive: true });
+  for (const entry of laid) await writeFile(join(outDir, entry.file), entry.png);
+  return laid.map((entry) => entry.file);
+}

package/src/og.test.ts ADDED Viewed

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { fitText } from "./og.ts";
+const COLUMN = { width: 600, size: 60, advance: 0.5, label: "pricing headline" };
+describe("fitText", () => {
+  it("wraps at the column, not mid-word", () => {
+    const { lines, overflow } = fitText("Everything your team ships, in one place", {
+      ...COLUMN,
+      maxLines: 3,
+    });
+    expect(overflow).toBeUndefined();
+    expect(lines.join(" ")).toBe("Everything your team ships, in one place");
+    expect(lines.length).toBeGreaterThan(1);
+  });
+  it("leaves a line that already fits alone", () => {
+    const { lines, overflow } = fitText("Short line", { ...COLUMN, maxLines: 2 });
+    expect(lines).toEqual(["Short line"]);
+    expect(overflow).toBeUndefined();
+  });
+  // The behaviour this file exists for. Appending `…` made wrapping a total function: every
+  // string "fitted", so copy that outgrew the column had no failing case and shipped a card
+  // missing the end of the one line the card exists to carry.
+  it("reports copy that does not fit instead of quietly cutting it", () => {
+    const tooLong = "A headline written for a search result rather than for a card, "
+      .repeat(3)
+      .trim();
+    const { overflow } = fitText(tooLong, { ...COLUMN, maxLines: 2 });
+    expect(overflow).toBeDefined();
+    expect(overflow?.label).toBe("pricing headline");
+    expect(overflow?.text).toBe(tooLong);
+    expect(overflow?.maxLines).toBe(2);
+  });
+  // Still returned, so a failed run can show what the card WOULD have said.
+  it("still returns the lines it managed, so a report can show them", () => {
+    const { lines } = fitText("word ".repeat(40).trim(), { ...COLUMN, maxLines: 2 });
+    expect(lines).toHaveLength(2);
+    expect(lines[1]?.endsWith("…")).toBe(true);
+  });
+  it("collapses the newlines a catalog string may carry", () => {
+    const { lines } = fitText("one\n  two", { ...COLUMN, maxLines: 3 });
+    expect(lines).toEqual(["one two"]);
+  });
+  it("keeps a word longer than the column rather than dropping it", () => {
+    const { lines } = fitText("supercalifragilisticexpialidocious", { ...COLUMN, maxLines: 1 });
+    expect(lines).toEqual(["supercalifragilisticexpialidocious"]);
+  });
+});

package/src/og.ts ADDED Viewed

@@ -0,0 +1,103 @@
+/**
+ * Fitting copy into a share card.
+ *
+ * The card's ART — the palette, the lockup, the size ladder — is the product, and it stays in
+ * the product. What ships here is the part two independent generators got wrong the same way:
+ * deciding what happens when a headline does not fit.
+ *
+ * Pure math, no `node:` import. The renderer that turns lines into SVG and SVG into a PNG is
+ * the caller's; `writeOgCards` in `node.ts` is the loop around it.
+ */
+/** The canvas every platform crops from. 1200×630 is the Open Graph size, not a brand choice. */
+export const OG_CANVAS = { width: 1200, height: 630 } as const;
+/** Copy that did not fit its column. */
+export interface OgOverflow {
+  /** Which line of which card, so an operator can act on the report without grepping. */
+  label: string;
+  /** The string as given. */
+  text: string;
+  maxLines: number;
+  /** Characters per line at this size — the budget the text blew. */
+  maxChars: number;
+  size: number;
+}
+export interface FitOptions {
+  /** Pixel width of the column the text has to live in. */
+  width: number;
+  /** Font size, in pixels. */
+  size: number;
+  /** Hard cap on lines. */
+  maxLines: number;
+  /**
+   * Average glyph advance as a fraction of the font size.
+   *
+   * Character-budget estimation rather than real metrics: an SVG rasterizer gives no measuring
+   * API, and card copy is short enough that the estimate never drifts more than a word. Measure
+   * it off a rendered card and round UP — a budget that is too generous overflows the column,
+   * while one that is too mean only breaks a line early. Donor values: ~0.5 for a display face
+   * at headline sizes, ~0.46 for body copy.
+   */
+  advance: number;
+  /** Names this line in an overflow report. `"pricing headline"`, not `"line 1"`. */
+  label: string;
+}
+export interface FitResult {
+  lines: readonly string[];
+  /** Set when the copy did not fit. See {@link fitText} for why this is reported rather than
+   *  quietly truncated. */
+  overflow?: OgOverflow;
+}
+/**
+ * Greedy word wrap into a column, hard-capped at `maxLines`.
+ *
+ * Overflow is REPORTED, not truncated. The donor used to append `…`, which made wrapping a
+ * total function: every string "fitted", so copy that outgrew the column had no failing case to
+ * observe and shipped a card missing the end of the one line the card exists to carry. The
+ * reader who finds out is someone else's link unfurl. Cutting a headline to win an argument
+ * with a long sentence is a decision nobody reviewed; the size ladder is one somebody did.
+ *
+ * The truncated lines still come back, so a report can show what the card would have said, and
+ * so a `--check` run can lay every card out before refusing. One run names every bad card: copy
+ * lands per locale in batches, and a build that dies on the first of six sends its operator
+ * round the loop six times.
+ */
+export function fitText(text: string, options: FitOptions): FitResult {
+  const { width, size, maxLines, advance, label } = options;
+  const maxChars = Math.max(8, Math.floor(width / (size * advance)));
+  const flat = text.replace(/\s+/g, " ").trim();
+  const lines: string[] = [];
+  let line = "";
+  let overflowed = false;
+  for (const word of flat.split(" ").filter(Boolean)) {
+    const candidate = line ? `${line} ${word}` : word;
+    if (candidate.length <= maxChars || !line) line = candidate;
+    else if (lines.length < maxLines - 1) {
+      lines.push(line);
+      line = word;
+    } else {
+      overflowed = true;
+      line = `${candidate.slice(0, maxChars - 1).trimEnd()}…`;
+      break;
+    }
+  }
+  if (line) lines.push(line);
+  return overflowed
+    ? { lines, overflow: { label, text: flat, maxLines, maxChars, size } }
+    : { lines };
+}
+/** One overflow, as the line an operator reads in a failed build. */
+export function describeOverflow(overflow: OgOverflow): string {
+  return (
+    `${overflow.label} — ${String(overflow.maxLines)} lines of ~${String(overflow.maxChars)} ` +
+    `chars at ${String(overflow.size)}px, ${String(overflow.text.length)} chars given\n` +
+    `    ${JSON.stringify(overflow.text)}`
+  );
+}

package/src/preset.ts ADDED Viewed

@@ -0,0 +1,78 @@
+/**
+ * The `vite.config.ts` every app in this stack was writing by hand.
+ *
+ * Its own entry point (`@gusnips/vite/preset`) rather than the barrel, because it imports the
+ * React and Tailwind plugins: a prerender script that only wants `bakeHead` would otherwise
+ * load a build toolchain it never uses. Same reason the four packages are split at all.
+ */
+import tailwindcss from "@tailwindcss/vite";
+import react from "@vitejs/plugin-react";
+import path from "node:path";
+import type { Plugin, UserConfig } from "vite";
+/**
+ * Substitute `%NAME%` placeholders in `index.html`.
+ *
+ * `index.html` cannot import TypeScript, so a brand name or tagline written there is a literal
+ * that drifts from the one the app renders. This injects them from the module that owns them.
+ *
+ * Vite already replaces `%VITE_FOO%` from the environment, and that is the right tool when the
+ * value IS environment — an API URL, a build id. It is the wrong one for brand identity, which
+ * belongs in a typed module the app imports, not in a `.env` nobody reviews.
+ */
+export function htmlPlaceholders(values: Readonly<Record<string, string>>): Plugin {
+  return {
+    name: "frontkit:html-placeholders",
+    transformIndexHtml(html: string) {
+      return Object.entries(values).reduce(
+        (out, [name, value]) => out.replaceAll(`%${name}%`, value),
+        html,
+      );
+    },
+  };
+}
+export interface WebPresetOptions {
+  /** The app folder — the one holding `index.html`. In a `vite.config.ts` that is
+   *  `import.meta.dirname`. `@` resolves to `<root>/src`. */
+  root: string;
+  /** Dev server port. Two apps in one repo must not share one, which is why it has no clever
+   *  default beyond Vite's own. */
+  port?: number;
+  /** Preview server port. Defaults to `port - 1000`, the pairing both donors landed on
+   *  (5173/4173, 5174/4174). */
+  previewPort?: number;
+  /** `{ BRAND_NAME: "Acme" }` replaces `%BRAND_NAME%` in `index.html`. */
+  placeholders?: Readonly<Record<string, string>>;
+  /**
+   * The workspace scope to bundle into the SSR build, as in `"@acme"`.
+   *
+   * INSURANCE, not a fix. Measured: Vite already bundles linked workspace dependencies in an
+   * SSR build — one donor runs without this declaration and its SSR output has zero bare
+   * imports. It is here because workspace packages are consumed as TypeScript SOURCE through
+   * subpath exports, and leaving them external would hand the runtime `.ts` files with
+   * Vite-only semantics in them (aliases, `?raw`, `define`) if that behaviour ever changed.
+   */
+  ssrScope?: string;
+}
+export function webPreset({
+  root,
+  port,
+  previewPort,
+  placeholders,
+  ssrScope,
+}: WebPresetOptions): UserConfig {
+  const preview = previewPort ?? (port === undefined ? undefined : port - 1000);
+  return {
+    plugins: [react(), tailwindcss(), ...(placeholders ? [htmlPlaceholders(placeholders)] : [])],
+    resolve: {
+      alias: { "@": path.resolve(root, "src") },
+    },
+    ...(ssrScope && {
+      ssr: { noExternal: [new RegExp(`^${ssrScope.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/`)] },
+    }),
+    ...(port !== undefined && { server: { port } }),
+    ...(preview !== undefined && { preview: { port: preview } }),
+  };
+}

package/src/render.test.ts ADDED Viewed

@@ -0,0 +1,67 @@
+import { createElement, lazy, Suspense, type ReactNode } from "react";
+import { describe, expect, it } from "vitest";
+import { renderTree } from "./render.ts";
+/** A route that arrives one tick late, like every `lazy()` route in a real app. */
+const Late = lazy(() =>
+  Promise.resolve({ default: () => createElement("main", null, "the real page") }),
+);
+const behindSuspense = (): ReactNode =>
+  createElement(
+    Suspense,
+    { fallback: createElement("div", { role: "status" }, "Loading…") },
+    createElement(Late),
+  );
+describe("renderTree", () => {
+  /**
+   * Invariant 1, and the reason this helper exists at all. `renderToString` renders the
+   * FALLBACK here — it would write a loading screen into every file and pass every gate that
+   * only asks whether the root has children.
+   */
+  it("waits for a lazy route instead of rendering the fallback", async () => {
+    const html = await renderTree(behindSuspense());
+    expect(html).toContain("the real page");
+    expect(html).not.toContain('role="status"');
+  });
+  /**
+   * React 19 hoists in-tree `<title>`/`<meta>`/`<link>` to the FRONT of the server stream, for
+   * a caller assembling a whole document. We are filling one `<div>`, so they would land inside
+   * the body — invalid there, and a duplicate of the head the prerender bakes.
+   */
+  it("drops the head tags React hoists to the front of the stream", async () => {
+    const html = await renderTree(
+      createElement(
+        "main",
+        null,
+        createElement("title", null, "hoisted"),
+        createElement("meta", { name: "description", content: "hoisted" }),
+        "body copy",
+      ),
+    );
+    expect(html.startsWith("<main")).toBe(true);
+    expect(html).toContain("body copy");
+  });
+  it("keeps a script the page itself carries", async () => {
+    const html = await renderTree(
+      createElement("main", null, createElement("script", { type: "application/ld+json" }, "{}")),
+    );
+    expect(html).toContain("application/ld+json");
+  });
+  // `renderToString` answers "" for a router whose basename does not match its location — no
+  // error, no warning. A build must not be allowed to write that file.
+  it("refuses a tree that rendered to nothing", async () => {
+    await expect(renderTree(null)).rejects.toThrow(/rendered to nothing/);
+  });
+  it("fails the build when a component throws", async () => {
+    const Boom = (): ReactNode => {
+      throw new Error("boom");
+    };
+    await expect(renderTree(createElement(Boom))).rejects.toThrow(/boom/);
+  });
+});

package/src/render.ts ADDED Viewed

@@ -0,0 +1,75 @@
+/**
+ * One page, as the markup that goes inside `<div id="root">`.
+ *
+ * This is the build-time half of `main.tsx`, and the app's `entry-server.tsx` is expected to
+ * be four lines around it: the same `<App />` and the same route table the browser runs, with
+ * a `StaticRouter` in place of the history the build does not have. `main.tsx` is deliberately
+ * NOT reused — it reads `window.location`, registers listeners and starts analytics at module
+ * scope, none of which mean anything here.
+ *
+ * No `node:` import: this file is bundled into the SSR build by Vite, and it is React's own
+ * static renderer plus two string rules.
+ */
+import type { ReactNode } from "react";
+// `static.browser`, not `static`. Three donor entry-servers converged on it independently, and
+// the reason is resolution rather than behaviour: `react-dom/static` is condition-resolved into
+// four different files (node, edge-light, workerd, browser) and an SSR bundler picks the
+// condition, not us. `.browser` is one implementation everywhere. Measured, `prerender` hands
+// back a Web `ReadableStream` from every one of them — which is what `new Response()` below
+// wants — so this pins a resolution, it does not fix a stream type.
+import { prerender } from "react-dom/static.browser";
+/**
+ * React 19 hoists `<title>`, `<meta>` and `<link>` rendered anywhere in the tree into the
+ * document head — and on the server it does that by emitting them at the FRONT of the stream,
+ * for a caller that is expected to be assembling a whole document. We are not: we are filling
+ * one `<div>`, so an in-tree SEO component's tags would land inside the body, where that markup
+ * is invalid and duplicates the head the prerender bakes.
+ *
+ * They are dropped rather than lifted, because the page registry is the one source of that head
+ * by contract and the baked copy is the half that exists before React runs. `<style>` and
+ * `<script>` are deliberately NOT in this pattern: if one appears here it belongs to the page
+ * and must survive.
+ */
+const HOISTED_HEAD = /^(?:<title>[^<]*<\/title>|<meta\b[^>]*\/?>|<link\b[^>]*\/?>|\s+)+/;
+/**
+ * Render a tree to markup with `prerender` from `react-dom/static`.
+ *
+ * **Never `renderToString`.** With `lazy()` routes behind a `<Suspense fallback={<Spinner />}>`,
+ * `renderToString` renders the FALLBACK — it would write a loading screen into every file and
+ * pass every gate that only asks whether the root has children. `prerender` waits for the tree
+ * to settle, which is also why this is async and why the whole renderer contract is.
+ *
+ * Two more halves of the same lesson are here too: `onError` is captured and rethrown, so a
+ * render failure fails the build rather than shipping a partial page; and an empty result is
+ * refused, because a router whose basename does not match its location answers `""` with no
+ * error and no warning.
+ */
+export async function renderTree(tree: ReactNode): Promise<string> {
+  let failure: unknown;
+  const { prelude } = await prerender(tree, {
+    onError(error: unknown) {
+      failure ??= error;
+    },
+  });
+  const html = await new Response(prelude).text();
+  if (failure !== undefined) throw failure;
+  const markup = html.replace(HOISTED_HEAD, "");
+  if (markup.trim() === "")
+    throw new Error(
+      "renderTree: the tree rendered to nothing — usually a router whose location or basename " +
+        "matches no route, which React reports as an empty string rather than an error",
+    );
+  return markup;
+}
+/**
+ * What an SSR entry exports, and what {@link loadRenderer} looks for.
+ *
+ * `context` is opaque on purpose. A multi-locale app builds its i18n instance per call — three
+ * languages render in one process and a shared singleton would have them racing for one `lng` —
+ * while a single-locale app ignores the argument and keeps its singleton.
+ */
+export type PageRenderer<Context = unknown> = (route: string, context?: Context) => Promise<string>;