@gusnips/vite 0.8.35 → 0.8.36

package/src/head.ts

@@ -15,7 +15,7 @@
 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. */
+/** The empty root a template must carry. `bakeHead` fills it and refuses a filled one. */
 export const EMPTY_ROOT = '<div id="root"></div>';
 
 /**
@@ -106,7 +106,7 @@ function setMetaIfPresent(html: string, patterns: readonly RegExp[], value: stri
   return rewriteAttr(html, patterns, value) ?? html;
 }
 
-/** One `<link rel="alternate" hreflang>` — this page's address in another language. */
+/** One `<link rel="alternate" hreflang>` for 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. */
@@ -122,17 +122,16 @@ export interface HeadTags {
   /**
    * 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
+   * `null` means this page has no canonical URL and must not claim one, as with 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. */
+  /** Absolute URL of the share card. Omit where the template carries no `og:image` tag. Setting one there is a build error, by design. */
   image?: string;
-  /** Markup inserted before `</head>` — structured data, and nothing else so far. Emitted here
+  /** Markup inserted before `</head>` for 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`. */
@@ -142,8 +141,8 @@ export interface HeadTags {
    * 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.
+   * 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;
   /**
@@ -158,14 +157,14 @@ export interface HeadTags {
    * 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.
+   * 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.
+   * 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 };
 }
@@ -174,18 +173,18 @@ export interface HeadTags {
  * 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.
+ * 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 question and its answer, as the page renders them — pass the same strings, so the
+/** One question and its answer, as the page renders them. Pass the same strings, so the
  *  structured data cannot drift from the copy. One donor's template carried four questions
  *  where the page renders seven, and nothing compared them until the migration. */
 export interface FaqEntry {
@@ -196,11 +195,11 @@ export interface FaqEntry {
 /**
  * FAQ structured data for `headExtra`, with the script-closing sequence escaped.
  *
- * A `</script>` inside an answer ends the element early and ships the rest of the JSON as
- * markup. `<\/` is the same string to a JSON parser and inert to an HTML one, so every `</`
- * becomes `<\/` and `<!--` becomes `<\!--`. `JSON.stringify` never emits `<` outside a string
- * — the structural characters are all brackets, quotes and digits — so the replace only ever
- * touches copy.
+ * A `</script>` inside an answer ends the element early and ships the rest of the JSON as markup.
+ * `<\/` is the same string to a JSON parser and inert to an HTML one, so every `</` becomes `<\/`
+ * and `<!--` becomes `<\!--`. `JSON.stringify` never emits `<` outside a string, since the
+ * structural characters are all brackets, quotes and digits. The replacement only ever touches
+ * copy.
  */
 export function faqJsonLd(faqs: readonly FaqEntry[]): string {
   const data = {
@@ -219,9 +218,9 @@ export function faqJsonLd(faqs: readonly FaqEntry[]): string {
 /**
  * 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.
+ * 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;
@@ -345,7 +344,7 @@ export function bakeHead(template: string, tags: HeadTags): string {
 }
 
 export interface RenderedChecks {
-  /** The BCP-47 tag this file must be marked with — the same `lang` passed to `bakeHead`. */
+  /** The BCP-47 tag this file must be marked with. Pass the same `lang` 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. */
@@ -375,11 +374,11 @@ const RENDERER_ERROR =
 /**
  * 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 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
@@ -455,5 +454,5 @@ export function assertRendered(
   // guard missed it from the other side: it failed a file containing a spinner class its splash
   // does not use. Two checks written for one regression, neither of which could ever fire.
   if (grew < SPLASH_MAX_GROWTH && head.includes('role="status"'))
-    fail("rendered the loading screen, not the page — something suspended and never resolved");
+    fail("rendered the loading screen, not the page. Something suspended and never resolved");
 }

package/src/i18n.ts

@@ -43,7 +43,7 @@ export interface I18nBundle {
   /** The app's `fallbackLng`: the language the others are compared to, and code keys must be in. */
   canonical: string;
   /**
-   * One language's catalogs. A throw fails the check with its message — it never skips the bundle,
+   * One language's catalogs. A throw fails the check with its message. It never skips the bundle,
    * because every other rule compares languages and a missing one would pass them all.
    */
   load: (locale: string) => Catalogs | Promise<Catalogs>;
@@ -388,8 +388,8 @@ async function files(root: string, patterns: readonly string[]): Promise<string[
 export interface MergeOptions {
   /**
    * Refuse two fragments that share a top-level key. Set it when the app merges fragments at
-   * runtime with a spread — `{ ...auth.en, ...nav.en }` — where the second `nav` replaces the
-   * first instead of joining it, and the keys of one fragment vanish with no error anywhere.
+   * runtime with a spread, `{ ...auth.en, ...nav.en }`, where the second `nav` replaces the first
+   * instead of joining it, and the keys of one fragment vanish with no error anywhere.
    */
   ownTopLevel?: boolean;
 }
@@ -446,10 +446,11 @@ function sortTree(tree: Tree): Tree {
 }
 
 /**
- * Fold `dir/*.json` — one file per area, every language side by side, `{ "en": {…}, "pt-BR": {…} }`
- * — into one catalog per language. Fragments exist so that people and agents building screens in
- * parallel do not all edit the same three files. Deterministic: files in name order, keys sorted,
- * so two runs write the same bytes and a derived catalog can be compared with a fresh merge.
+ * Fold `dir/*.json` into one catalog per language. Each file holds one area, with languages side by
+ * side: `{ "en": {…}, "pt-BR": {…} }`. Fragments exist so that people and agents building screens
+ * in parallel do not all edit the same three files. Deterministic: files in name order, keys
+ * sorted, so two runs write the same bytes and a derived catalog can be compared with a fresh
+ * merge.
  */
 export async function mergeFragments(
   dir: string,

package/src/icons.ts

@@ -18,7 +18,7 @@ export type RenderIcon = (svg: string, size: number) => Uint8Array | Promise<Uin
 export type PackIco = (pngs: readonly Uint8Array[]) => Uint8Array | Promise<Uint8Array>;
 
 export interface WriteIconSetOptions {
-  /** Where the files land — `public/` in every donor, so they are served as static files. */
+  /** Where the files land. Every donor uses `public/`, so they are served as static files. */
   outDir: string;
   /** The one master artwork. A single path with no variants is what keeps every size in step. */
   svg: string;
@@ -27,9 +27,9 @@ export interface WriteIconSetOptions {
   /** The file name for one PNG size. Default `` `icon-${size}.png` ``. */
   file?: (size: number) => string;
   /**
-   * The size written as `apple-touch-icon.png`. Default 180 — what the reader's home screen
-   * asks for. Reuses the PNG render when it is already in `pngSizes`, so the common case costs
-   * no extra raster.
+   * The size written as `apple-touch-icon.png`. Defaults to 180, the size the reader's home screen
+   * asks for. Reuses the PNG render when it is already in `pngSizes`, so the common case costs no
+   * extra raster.
    */
   appleTouchSize?: number;
   /** Sizes re-rendered and packed into `favicon.ico`, e.g. `[16, 32, 48]`. */
@@ -44,7 +44,7 @@ export interface WriteIconSetOptions {
  * Render one icon set and write it, plus the multi-size `favicon.ico`.
  *
  * Every size is rendered BEFORE anything is written, so a renderer that throws leaves no
- * half-written set behind — the same order `writeOgCards` keeps for the same reason.
+ * half-written set behind. This is the same order `writeOgCards` keeps for the same reason.
  */
 export async function writeIconSet({
   outDir,
@@ -100,7 +100,7 @@ export interface WebManifestOptions {
   display?: string;
   backgroundColor?: string;
   themeColor?: string;
-  /** At least one — a manifest with no icons fails installability with no error anywhere. */
+  /** At least one icon is required. A manifest with no icons fails installability with no error anywhere. */
   icons: readonly ManifestIcon[];
 }
 
@@ -121,7 +121,7 @@ export function webManifest({
 }: WebManifestOptions): string {
   if (name.trim() === "") throw new Error("manifest: `name` is empty");
   if (icons.length === 0)
-    throw new Error("manifest: `icons` is empty — name what writeIconSet wrote");
+    throw new Error("manifest: `icons` is empty. Name what writeIconSet wrote");
   const manifest: Record<string, unknown> = { name };
   if (shortName !== undefined) manifest["short_name"] = shortName;
   if (description !== undefined) manifest["description"] = description;

package/src/index.ts

@@ -1,10 +1,10 @@
 /**
  * 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.
+ * A Vite SPA ships one `index.html` and draws the rest with JavaScript. Nothing that reads a link
+ * for a living runs that bundle, whether it is a search crawler, an LLM or 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.
@@ -13,9 +13,9 @@
  * otherwise force on everyone: the vite config preset at `@gusnips/vite/preset` (the React and
  * Tailwind plugins), `renderTree` at `@gusnips/vite/render`, the theme pre-paint plugin at
  * `@gusnips/vite/theme` (both React itself), the catalog check at `@gusnips/vite/i18n`, and the
- * contrast gate at `@gusnips/vite/contrast` (tailwindcss) — the last two run in CI and never in
- * a build. Nothing here imports React, vite or tailwindcss, so a prerender script, an OG
- * generator and a repo that only wants a sitemap all install exactly what they use.
+ * contrast gate at `@gusnips/vite/contrast` (tailwindcss). The last two run in CI and never in a
+ * build. Nothing here imports React, vite or tailwindcss, so a prerender script, an OG generator
+ * and a repo that only wants a sitemap all install exactly what they use.
  */
 export { resolveKey } from "./catalog.ts";
 // `headExtra` takes raw markup, so the moment an adopter builds a tag out of its own copy it

package/src/node.ts

@@ -35,7 +35,7 @@ export async function loadTemplate(distDir: string): Promise<string> {
   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 " +
+        "(run `vite build` to regenerate the shell this reads), or the app's root element " +
         "carries attributes, which the baker cannot fill.",
     );
   return template;
@@ -58,16 +58,16 @@ function exportsRenderer<Context>(mod: unknown): mod is { renderPage: PageRender
  * 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.
  *
- * **The calling script has to exit itself.** This import is where the renderer enters your
- * process, and under bun `react-dom/static.browser` — which invariant 1 requires, so every app on
- * this rig loads it — leaves that process alive after its last await. Measured by elimination with
- * no app code at all: `react-dom/server` exits, `static.browser` does not, and
- * `process.getActiveResourcesInfo()` reports nothing either way, so the handle is invisible to
- * everything except the hang. Under node it exits. Nothing here can undo it — a library must not
- * call `process.exit` on its host — so a prerender script ends with `process.exit(0)` once every
- * file is written, and in CI the alternative is a job that does all its work and then runs to its
- * timeout. Five adopters had already written that line against a DIFFERENT holder (an auth client
- * whose token-refresh timer starts at module scope); none of them knew the renderer does it too.
+ * **The calling script has to exit itself.** This import is where the renderer enters your process,
+ * and under bun `react-dom/static.browser`, which invariant 1 requires every app on this rig to
+ * load, leaves that process alive after its last await. Measured by elimination with no app code at
+ * all: `react-dom/server` exits, `static.browser` does not, and `process.getActiveResourcesInfo()`
+ * reports nothing either way, so the handle is invisible to everything except the hang. Under node
+ * it exits. Nothing here can undo it, because a library must not call `process.exit` on its host. A
+ * prerender script ends with `process.exit(0)` once every file is written, and in CI the
+ * alternative is a job that does all its work and then runs to its timeout. Five adopters had
+ * already written that line against a DIFFERENT holder (an auth client whose token-refresh timer
+ * starts at module scope); none of them knew the renderer does it too.
  */
 export async function loadRenderer<Context = unknown>(
   entryFile: string,
@@ -75,7 +75,7 @@ export async function loadRenderer<Context = unknown>(
   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`,
+      `prerender: ${entryFile} does not export renderPage. Run \`vite build --ssr\` first`,
     );
   return mod.renderPage;
 }
@@ -90,14 +90,13 @@ export async function writeDist(distDir: string, file: string, contents: string)
 /** 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}. */
+  /** 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
+  /** Where the cards land. Both donors use `public/og`, 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\``. */
@@ -112,10 +111,10 @@ export interface WriteOgCardsOptions<Page> {
  * 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.
+ * 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
@@ -139,7 +138,7 @@ export async function writeOgCards<Page>({
 
   if (overflows.length > 0)
     throw new Error(
-      `og: ${String(overflows.length)} card(s) cannot hold their copy —\n\n` +
+      `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.",
     );
@@ -201,11 +200,11 @@ async function isFile(path: string): Promise<boolean> {
  * Every share card a built page advertises is a file that exists.
  *
  * Three repos shipped a page whose `og:image` named a card nothing had ever rendered. All three
- * were `404.html`, all three for the same reason: a card generator walks the page registry, and
- * a not-found shell is not in the registry, so a head built from the same template inherits a
- * card address with no card behind it. Every share of a dead link unfurled broken, in one case
- * in three languages, and **nothing in a browser shows it** — the page looks perfect, and the
- * only reader who finds out is whoever the link was sent to.
+ * were `404.html`, all three for the same reason: a card generator walks the page registry, and a
+ * not-found shell is not in the registry, so a head built from the same template inherits a card
+ * address with no card behind it. Every share of a dead link unfurled broken, in one case in three
+ * languages, and **nothing in a browser shows it**. The page looks perfect, and the only reader who
+ * finds out is whoever the link was sent to.
  *
  * `bakeHead` cannot catch it: it is handed an `image` and writes it, and a shell carrying the
  * brand card is correct, so it has no way to tell a right image from a wrong one (invariant 12).
@@ -216,9 +215,9 @@ async function isFile(path: string): Promise<boolean> {
  * await assertOgImages("dist", "https://example.com");
  * ```
  *
- * Cards on another host are somebody else's to serve and are skipped — but a build whose pages
- * all advertise cards and whose origin matches NONE of them has been given the wrong origin,
- * and a check that silently passes is worse than no check, so that is an error too.
+ * Cards on another host are somebody else's to serve and are skipped. But a build whose pages all
+ * advertise cards and whose origin matches NONE of them has been given the wrong origin, and a
+ * check that silently passes is worse than no check, so that is an error too.
  */
 export async function assertOgImages(distDir: string, origin: string): Promise<number> {
   const root = siteOrigin(origin);
@@ -247,7 +246,7 @@ export async function assertOgImages(distDir: string, origin: string): Promise<n
 
   if (missing.length > 0)
     throw new Error(
-      `og: ${String(missing.length)} page(s) advertise a share card that is not in ${distDir} —\n\n` +
+      `og: ${String(missing.length)} page(s) advertise a share card that is not in ${distDir}:\n\n` +
         missing.map((card) => `  · ${card.page} → ${card.url}`).join("\n") +
         "\n\n  Either render the card, or leave `image` out of the head for that page.",
     );

package/src/og.ts

@@ -1,7 +1,7 @@
 /**
  * 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 card's ART, including the palette, lockup and 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.
  *
@@ -19,7 +19,7 @@ export interface OgOverflow {
   /** The string as given. */
   text: string;
   maxLines: number;
-  /** Characters per line at this size — the budget the text blew. */
+  /** Characters per line at this size, the budget the text exceeded. */
   maxChars: number;
   size: number;
 }
@@ -34,11 +34,11 @@ export interface FitOptions {
   /**
    * 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.
+   * 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"`. */
@@ -96,7 +96,7 @@ export function fitText(text: string, options: FitOptions): FitResult {
 /** 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)} ` +
+    `${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/pre-paint.ts

@@ -26,10 +26,10 @@ export interface PrePaintScriptOptions {
   /** The script's full text. It runs alone, so it must not reference anything outside itself. */
   source: string;
   /**
-   * Where the tag goes. `"head"` (the end of `<head>`) when the script reads elements above it —
+   * Where the tag goes. `"head"` (the end of `<head>`) when the script reads elements above it, as
    * the theme reads `<meta name="theme-color">`. `"head-prepend"` when it only needs to run as
-   * early as possible: a classic script after a stylesheet waits for that stylesheet, so the
-   * locale gate goes first and redirects without downloading the page's CSS.
+   * early as possible: a classic script after a stylesheet waits for that stylesheet, so the locale
+   * gate goes first and redirects without downloading the page's CSS.
    */
   position?: "head" | "head-prepend";
 }

package/src/preset.ts

@@ -16,9 +16,9 @@ import type { Plugin, PluginOption, UserConfig } from "vite";
  * `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.
+ * Vite already replaces `%VITE_FOO%` from the environment, and that is the right tool for an
+ * environment value, such as an API URL or 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 {
@@ -34,7 +34,7 @@ export function htmlPlaceholders(values: Readonly<Record<string, string>>): Plug
 }
 
 export interface WebPresetOptions {
-  /** The app folder — the one holding `index.html`. In a `vite.config.ts` that is
+  /** The app folder 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
@@ -48,11 +48,11 @@ export interface WebPresetOptions {
   /**
    * 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.
+   * 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;
   /** More plugins, after the preset's own: `[themeScript(THEME)]`. */

package/src/render.ts

@@ -1,10 +1,10 @@
 /**
  * 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
+ * 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 because 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
@@ -37,9 +37,9 @@ const HOISTED_HEAD = /^(?:<title>[^<]*<\/title>|<meta\b[^>]*\/?>|<link\b[^>]*\/?
  * 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.
+ * `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
@@ -59,7 +59,7 @@ export async function renderTree(tree: ReactNode): Promise<string> {
   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 " +
+      "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;
@@ -68,8 +68,8 @@ export async function renderTree(tree: ReactNode): Promise<string> {
 /**
  * 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` —
+ * `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>;