@escape-game-over/atlas 0.1.1 → 0.1.3

package/src/astro/site-routes.ts

@@ -10,6 +10,7 @@ import {
 import type { Sitemap } from "../sitemap.ts";
 import type { HttpsUrl } from "../url.ts";
 import { warn } from "../warn.ts";
+import { buildCacheDir } from "./build-cache.ts";
 
 /**
  * What this integration needs of a site, and no more.
@@ -82,17 +83,19 @@ export interface SiteRoutesOptions {
  * Emits the files a static site owes the outside world.
  *
  * Written into the output directory when the build is done, rather than served
- * by injected routes. Two reasons, and the first is not a preference:
+ * by injected routes. One reason, and it is not the obvious one:
  *
- * - `_redirects` cannot be a page at all. Astro refuses to route anything in
- *   `src/pages` whose name begins with `_`, and URL-escaping does not help —
- *   `%5F` is decoded before the entrypoint is opened.
  * - A route is injected by *entrypoint*, and that file is compiled into the
- *   build's own module graph, where it cannot see a caller's `site`. Reaching it
- *   means naming a module in a string and resolving it through a virtual module
- *   — a lot of machinery, and nothing type-checks the string. None of these
- *   files needs the asset pipeline or a page context, so none of that buys
- *   anything.
+ *   build's own module graph, where it cannot see a caller's `site`. Every way
+ *   of reaching one from there is worse than the staleness it would cure — see
+ *   the entry in `docs/NOT-BUILT.md`, which records what was measured.
+ *
+ * **`_redirects` is not the obstacle, whatever this comment used to say.** What
+ * Astro refuses is a *filename* beginning with `_` in `src/pages`; an injected
+ * route names its pattern and its entrypoint separately, so the underscore
+ * lands only on the URL and the entrypoint is an ordinary module elsewhere.
+ * That was built and served, in dev and in a build, before being taken out
+ * again for the reason above.
  */
 export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
     const { site, redirects, llms, sitemap = true, robots = true } = options;
@@ -102,9 +105,15 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
         `${file.name} (${size(file.body)})`;
 
     // Rebuilt per request in dev and once at the end of a build, rather than
-    // computed here: in dev the site's data changes under the server, and a list
-    // captured when the integration was constructed would serve yesterday's
-    // sitemap until you restarted.
+    // computed here.
+    //
+    // Worth knowing what that does *not* buy: it does not make dev current. The
+    // `site` and the `llms` file this closes over were built when the Astro
+    // config was evaluated, and nothing re-evaluates that until the server
+    // restarts — so rebuilding per request derives the same answer from the same
+    // frozen inputs. Measured: editing a message refreshes the page that renders
+    // it and leaves the same string in `llms.txt` untouched. A build is always
+    // right, since it evaluates the config in a fresh process.
     const generate = (): GeneratedFile[] => {
         const files: GeneratedFile[] = [];
         if (sitemap) files.push(...site.sitemap().files);
@@ -143,11 +152,12 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
         name: "site-routes",
         hooks: {
             /**
-             * The three settings lib's own output would contradict, set here
-             * rather than asked for.
+             * The Astro settings this integration decides, and the one it
+             * refuses.
              *
-             * Not a preference imposed on a consumer — each is the half of a
-             * contract whose other half this library already wrote:
+             * Three are set because lib's own output would contradict them —
+             * each is the half of a contract whose other half this library
+             * already wrote:
              *
              * - `output: "static"`. Every file below is generated once, at
              *   build time, from data known then. There is no request to
@@ -167,12 +177,102 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
              *   refuse a form the host answers with a redirect rather than a
              *   404 — dev stricter than production, which teaches you nothing.
              *
-             * Set instead of validated because there is no way to tell a
-             * deliberate `"directory"` from Astro's default: both arrive here
-             * as the same resolved value, so a check could only warn at
-             * everyone or at no one.
+             * A fourth is set on weaker grounds, and deliberately so:
+             *
+             * - `prefetch`, all links, on `viewport`. Not a contract — nothing
+             *   lib emits contradicts a consumer preferring `hover` — but the
+             *   documents here are small enough that the usual objection does
+             *   not apply: every page of the larger example's 25-item grid is
+             *   around 3 kB gzipped, so prefetching the lot costs under 80 kB,
+             *   and `rel="prefetch"` fetches the HTML alone rather than its
+             *   images. A default worth overriding per site, not a rule —
+             *   though not into `prerender`; see the refusal below.
+             *
+             * A fifth is set only when the environment asks for it:
+             *
+             * - `cacheDir`, moved onto whatever cache volume CI mounted. Not a
+             *   preference — Astro's default sits inside `node_modules`, which
+             *   a CI install deletes before every run, so a build there
+             *   re-optimizes every image and re-downloads every font each time,
+             *   however little changed. Set here rather than per repo because
+             *   Astro exposes no environment variable for it, and `updateConfig`
+             *   is already how this integration says what a site's build looks
+             *   like. Off CI the value is `undefined`, the merge skips the key,
+             *   and the default stays exactly where it was. See
+             *   `build-cache.ts` for what shares the volume and what would not.
+             *
+             * Two are refused rather than set, both because Astro resolves them
+             * to a default a deliberate value is distinguishable from — so the
+             * check fires at whoever asked for it rather than at everyone:
+             *
+             * - `compressHTML: true`, which lib's output does not contradict
+             *   but its *source* does: the templates are written for Astro's
+             *   `"jsx"` whitespace rules, and `true` renders them differently.
+             * - `experimental.clientPrerender: true`, which turns the `prefetch`
+             *   above into `prerender` and runs every script on the page inside
+             *   a document nobody opened.
+             *
+             * The three contracts at the top are set instead of validated for
+             * the opposite reason: there is no way to tell a deliberate
+             * `"directory"` from Astro's default, since both arrive here as the
+             * same resolved value, so a check could only warn at everyone or at
+             * no one.
              */
-            "astro:config:setup": ({ updateConfig, logger }) => {
+            "astro:config:setup": ({
+                config: current,
+                updateConfig,
+                logger,
+            }) => {
+                /**
+                 * `compressHTML: true` is refused rather than overridden.
+                 *
+                 * Unlike the three below, this is not a setting lib's output
+                 * contradicts — both modes produce valid HTML. What it
+                 * contradicts is the *source*: every template here was written
+                 * under `"jsx"`, Astro 7's default, where whitespace around
+                 * elements is dropped and a deliberate space is written `{" "}`.
+                 * `true` keeps whitespace "as needed to maintain the visual
+                 * rendering" instead, so the same markup renders differently.
+                 *
+                 * Thrown at rather than set, because unlike `build.format` a
+                 * deliberate `true` is distinguishable from the default — so a
+                 * check can fire at exactly the person who asked for it, and
+                 * `false` stays available for reading the built HTML.
+                 */
+                if (current.compressHTML === true) {
+                    throw new Error(
+                        "compressHTML: true is not supported. The templates are written for " +
+                            'Astro\'s default "jsx" whitespace rules, where a deliberate space is `{" "}`; ' +
+                            "`true` preserves whitespace differently and renders the same markup " +
+                            'differently. Use "jsx", or `false` while inspecting the built HTML.'
+                    );
+                }
+
+                /**
+                 * `experimental.clientPrerender: true` is refused outright.
+                 *
+                 * It swaps the `rel="prefetch"` behind the default below for
+                 * speculation-rules `prerender`: the browser builds each
+                 * prefetched page in a hidden renderer and runs every script on
+                 * it for a visitor who never opened it. Umami posts a pageview,
+                 * its recorder starts a replay, and a third-party widget does
+                 * whatever it does. Gating that takes `document.prerendering`,
+                 * once per script, and a page is never done gaining scripts.
+                 *
+                 * Thrown rather than warned because none of it errors on its
+                 * own — the numbers just read high, and plausibly. `false` is
+                 * the resolved default, so this fires only at someone who
+                 * asked.
+                 */
+                if (current.experimental.clientPrerender) {
+                    throw new Error(
+                        "experimental.clientPrerender: true is not supported. It prerenders " +
+                            "prefetched pages, running every script on them — analytics and " +
+                            "third-party widgets included — for visitors who never open them. " +
+                            "Which can cause either issues or invalid metrics."
+                    );
+                }
+
                 // Annotated, not just passed: `updateConfig(config)` alone
                 // would not catch a misspelled key, because excess-property
                 // checking fires on a fresh object literal at the call site and
@@ -183,6 +283,11 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
                     output: "static",
                     build: { format: "file" },
                     trailingSlash: "ignore",
+                    prefetch: {
+                        prefetchAll: true,
+                        defaultStrategy: "viewport",
+                    },
+                    cacheDir: buildCacheDir(),
                 };
                 updateConfig(config);
                 // Said out loud: a setting changed from under you is worth a

package/src/astro/tsconfig.json

@@ -0,0 +1,8 @@
+{
+    "extends": ["../../tsconfig.json", "astro/tsconfigs/strict"],
+    "compilerOptions": {
+        "types": ["astro/client"]
+    },
+    "include": ["**/*"],
+    "exclude": ["node_modules", "dist"]
+}

package/src/contact-form.ts

@@ -0,0 +1,177 @@
+import { type HttpsUrl, joinUrl } from "./url.ts";
+
+/**
+ * Posting a contact form to the central mail API, from the browser.
+ *
+ * The API takes the message and decides everything else: which mailbox it goes
+ * to, which template renders it, whether the sending domain is allowed at all.
+ * A form therefore never states a recipient — it states which account it is
+ * writing on behalf of, and the account owns the rest. That is what lets this
+ * ship as a static page with no server of its own.
+ *
+ * One function, and the wire format stays inside it. What a message *is* — which
+ * fields a form asks for, whether a phone number is required, how long is long
+ * enough — is a per-site decision, and the API applies its own rules regardless;
+ * checking them again here would be the same rules written twice, drifting.
+ */
+
+/**
+ * Which template renders the mail, and which mailbox it reaches.
+ *
+ * Both fall back to `default` when the type is unknown, so a typo does not lose
+ * the message — it files it as an ordinary enquiry, which is the failure worth
+ * catching. Hence a closed union rather than `string`.
+ */
+export type ContactFormType =
+    | "default"
+    | "birthday_parties"
+    | "birthday_party"
+    | "board_games"
+    | "group_booking"
+    | "team_building"
+    | "voucher";
+
+/** Where a deployment's contact mail goes. */
+export interface MailEndpoint {
+    /**
+     * The API's send route, without the account.
+     *
+     * `https` because the API reads the browser's `Origin` header and refuses
+     * anything else — see `sendContactMessage`.
+     */
+    readonly url: HttpsUrl;
+    /**
+     * The account the message is sent on behalf of: `"b2b_cube"`.
+     *
+     * What the API looks the mailbox and the allowed domains up by. A domain
+     * that is not registered against it is refused, and nothing configured here
+     * substitutes for that.
+     */
+    readonly account: string;
+    /** Defaults to `"default"`, which every account has. */
+    readonly type?: ContactFormType;
+}
+
+/** A filled-in form, in the words a page uses rather than the API's. */
+export interface ContactMessage {
+    readonly name: string;
+    readonly email: string;
+    readonly subject: string;
+    readonly message: string;
+    /**
+     * Anything else the form asked for: a phone number, a company, a date.
+     *
+     * Free-form because the API stores it as received and its template renders
+     * one titled row per entry — so `estimated_players` arrives as "Estimated
+     * Players" with no change on either side. Blanks are dropped rather than
+     * sent.
+     */
+    readonly additional?: Readonly<Record<string, string | undefined>>;
+}
+
+/**
+ * What happened to a message.
+ *
+ * Three outcomes rather than a boolean, because a form says something different
+ * about each: `rejected` is the API disagreeing and may name fields, while
+ * `unreachable` is nobody's fault and is the one worth printing an email
+ * address next to.
+ */
+export type ContactResult =
+    | { readonly ok: true }
+    | { readonly ok: false; readonly reason: "unreachable" }
+    | {
+          readonly ok: false;
+          readonly reason: "rejected";
+          /** Per field, when the API named any. Keyed as the form names them. */
+          readonly problems: Readonly<Record<string, string>>;
+      };
+
+/**
+ * The account as the API files it: lowercase, dashes as underscores, no spaces.
+ *
+ * The API normalizes what it receives, so this is not needed for a request to
+ * work — it is here so what a project writes and what the mail is filed under
+ * cannot quietly differ.
+ */
+function normalizeAccount(account: string): string {
+    return account.toLowerCase().replaceAll("-", "_").replaceAll(" ", "");
+}
+
+/** The API's field names, mapped back to the ones a form uses. */
+const FIELD_OF: Readonly<Record<string, string>> = {
+    reply_to_name: "name",
+    reply_to_email: "email",
+    subject: "subject",
+    message: "message",
+};
+
+/**
+ * Posts a message, and says what happened.
+ *
+ * **The page must be served over https.** The API reads the `Origin` header and
+ * refuses anything else before it looks at the body, so a form works on a
+ * deployed site and is rejected from `http://localhost`. Preview builds on
+ * `*.pages.dev` are recognised and routed to a development mailbox, which is
+ * the intended way to try one out.
+ *
+ * `fetch` is a parameter so this is testable without a global.
+ */
+export async function sendContactMessage(
+    endpoint: MailEndpoint,
+    message: ContactMessage,
+    fetchImpl: typeof fetch = fetch
+): Promise<ContactResult> {
+    const additional_info: Record<string, string> = {};
+    for (const [key, value] of Object.entries(message.additional ?? {})) {
+        const trimmed = value?.trim();
+        if (trimmed) additional_info[key] = trimmed;
+    }
+
+    const url = joinUrl(
+        endpoint.url,
+        `/${normalizeAccount(endpoint.account)}/${endpoint.type ?? "default"}`
+    );
+
+    let response: Response;
+    try {
+        response = await fetchImpl(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Accept: "*/*" },
+            redirect: "follow",
+            body: JSON.stringify({
+                reply_to_name: message.name.trim(),
+                reply_to_email: message.email.trim(),
+                subject: message.subject.trim(),
+                message: message.message.trim(),
+                additional_info,
+            }),
+        });
+    } catch {
+        return { ok: false, reason: "unreachable" };
+    }
+
+    if (response.ok) return { ok: true };
+
+    // The API answers a refusal with a field-keyed `problems` object, which is
+    // worth showing — but it refuses a disallowed origin or an ignored address
+    // with no fields at all, and those bodies are not always JSON. Either way
+    // the message did not send, so a parse failure is the same outcome with
+    // nothing to add.
+    try {
+        const body: unknown = await response.json();
+        const reported = (() => {
+            if (typeof body !== "object" || body === null) return undefined;
+            if (!("problems" in body)) return undefined;
+            return (body as { problems?: Record<string, string> }).problems;
+        })();
+
+        const problems: Record<string, string> = {};
+        for (const [key, value] of Object.entries(reported ?? {})) {
+            problems[FIELD_OF[key] ?? key] = value;
+        }
+        return { ok: false, reason: "rejected", problems };
+    } catch {
+        return { ok: false, reason: "rejected", problems: {} };
+    }
+}

package/src/index.ts

@@ -53,6 +53,13 @@ export {
     type PostalAddress,
     telHref,
 } from "./contact.ts";
+export {
+    type ContactFormType,
+    type ContactMessage,
+    type ContactResult,
+    type MailEndpoint,
+    sendContactMessage,
+} from "./contact-form.ts";
 export type { GeneratedFile } from "./file.ts";
 export type { PublicFilePath, PublicFileRegistry } from "./files.ts";
 export {

package/src/meta/index.ts

@@ -78,7 +78,7 @@ export type MetaInput<L extends string> = Omit<MetaContentBase, "image"> &
     PageKind &
     MetaInputDerived<L>;
 
-interface MetaInputDerived<L extends string> {
+interface MetaInputDerived<L extends string> extends ChromeInput {
     /** The locale of *this* page, not the site default. */
     readonly locale: L;
     readonly canonical: HttpsUrl;
@@ -119,8 +119,6 @@ interface MetaInputDerived<L extends string> {
      * Graph equivalent to fall back to. Site-level, like `siteName`.
      */
     readonly twitterSite?: string;
-    /** The site's square icon, used for every icon link. */
-    readonly icon: SiteIcon;
     /**
      * Webmaster-tool ownership tokens. Site-level, like `siteName`.
      *
@@ -144,6 +142,20 @@ interface MetaInputDerived<L extends string> {
      * generated — a link to a missing one is worse than no link.
      */
     readonly llmsUrl?: HttpsUrl;
+}
+
+/**
+ * The site's own furniture, as opposed to anything about a page.
+ *
+ * Its own interface because it is what the 404 shares with every real page and
+ * nearly all it shares: that document has no canonical, no description, no
+ * alternates and no share image, but it is still served under the site's name
+ * in the site's tab, and a reader who lands on it should not be able to tell
+ * from the chrome that they left.
+ */
+export interface ChromeInput {
+    /** The site's square icon, used for every icon link. */
+    readonly icon: SiteIcon;
     /**
      * Tints the browser UI — Android Chrome's bar, iOS Safari, an installed PWA.
      * Two values emit one tag per `prefers-color-scheme`.
@@ -172,6 +184,45 @@ export interface DocumentTags {
     readonly body: MetaTag[];
 }
 
+/**
+ * What the browser dresses its own furniture with: the tab's icon, the tint of
+ * the address bar, and which schemes the page renders form controls for.
+ *
+ * Pulled out of `buildMeta` because the 404 needs exactly this and nothing else
+ * around it. Sharing the code is the point rather than a convenience: these are
+ * the tags a reader sees *as* the site — a 404 with a different tab icon looks
+ * like it came from somewhere else, which is the opposite of what a 404 is for —
+ * and two copies of a four-branch block is how one of them quietly stops
+ * matching the other.
+ */
+function chromeTags(input: ChromeInput): MetaTag[] {
+    const tags: MetaTag[] = [...iconLinks(input.icon)];
+
+    if (input.colorScheme !== undefined) {
+        tags.push(meta({ name: "color-scheme", content: input.colorScheme }));
+    }
+    if (typeof input.themeColor === "string") {
+        tags.push(meta({ name: "theme-color", content: input.themeColor }));
+    } else if (input.themeColor !== undefined) {
+        tags.push(
+            meta({
+                name: "theme-color",
+                media: "(prefers-color-scheme: light)",
+                content: input.themeColor.light,
+            })
+        );
+        tags.push(
+            meta({
+                name: "theme-color",
+                media: "(prefers-color-scheme: dark)",
+                content: input.themeColor.dark,
+            })
+        );
+    }
+
+    return tags;
+}
+
 /** Builds the head tags every page needs. */
 export function buildMeta<L extends string>(input: MetaInput<L>): DocumentTags {
     const tags: MetaTag[] = [
@@ -209,29 +260,7 @@ export function buildMeta<L extends string>(input: MetaInput<L>): DocumentTags {
         tags.push(link({ rel: "describedby", href: input.llmsUrl }));
     }
 
-    for (const iconLink of iconLinks(input.icon)) tags.push(iconLink);
-
-    if (input.colorScheme !== undefined) {
-        tags.push(meta({ name: "color-scheme", content: input.colorScheme }));
-    }
-    if (typeof input.themeColor === "string") {
-        tags.push(meta({ name: "theme-color", content: input.themeColor }));
-    } else if (input.themeColor !== undefined) {
-        tags.push(
-            meta({
-                name: "theme-color",
-                media: "(prefers-color-scheme: light)",
-                content: input.themeColor.light,
-            })
-        );
-        tags.push(
-            meta({
-                name: "theme-color",
-                media: "(prefers-color-scheme: dark)",
-                content: input.themeColor.dark,
-            })
-        );
-    }
+    for (const tag of chromeTags(input)) tags.push(tag);
 
     for (const alternate of input.alternates) {
         tags.push(
@@ -400,6 +429,20 @@ export function buildMeta<L extends string>(input: MetaInput<L>): DocumentTags {
     return { head: tags, body: bodyTags };
 }
 
+/**
+ * What a 404 needs, which is the site's furniture and a title and nothing else.
+ *
+ * An object rather than the positional arguments this took before: the two it
+ * gained are both site-level and both optional-looking at a call site, and
+ * `buildNotFoundMeta(title, icon, themeColor, analytics)` is four positions
+ * where three of them are interchangeable to a reader.
+ */
+export interface NotFoundInput extends ChromeInput {
+    readonly title: string;
+    /** Site-level, and only Umami reaches this page — see `notFoundAnalytics`. */
+    readonly analytics?: AnalyticsSettings;
+}
+
 /**
  * Builds the head of a 404 page.
  *
@@ -412,13 +455,16 @@ export function buildMeta<L extends string>(input: MetaInput<L>): DocumentTags {
  * host serves this file at the address that was requested, so what gets
  * recorded is the missing path itself, which is the difference between knowing
  * there are 404s and knowing which redirect to write.
+ *
+ * It also carries the site's chrome, through the same `chromeTags` every real
+ * page goes through. A 404 is the one page a visitor reaches by accident, and
+ * the tab it opens in is how they judge whether they are still on the site they
+ * meant to be on — an unstyled tab showing the browser's default globe reads as
+ * a different origin, or as nothing at all.
  */
-export function buildNotFoundMeta(
-    title: string,
-    analytics?: AnalyticsSettings
-): MetaTag[] {
+export function buildNotFoundMeta(input: NotFoundInput): MetaTag[] {
     return [
-        ...preamble({ title }),
+        ...preamble({ title: input.title }),
         // Through the same builder as every other page, so the one document lib
         // writes for itself cannot spell the tag differently from the ones it
         // writes for a project. Links are still followed: a 404 often carries
@@ -427,6 +473,7 @@ export function buildNotFoundMeta(
             name: "robots",
             content: robotsContent({ index: false, follow: true }),
         }),
-        ...notFoundAnalytics(analytics).map(asMetaTag),
+        ...notFoundAnalytics(input.analytics).map(asMetaTag),
+        ...chromeTags(input),
     ];
 }

package/src/routes/define.ts

@@ -49,7 +49,9 @@ export interface RouteData<L extends string> {
      * `1` or omitted is an ordinary route. Above that, lib emits
      * `/news/page/2` … `/news/page/n` alongside `/news` — page one is always
      * the bare slug, never `page/1`, so there is no duplicate to canonicalise
-     * away.
+     * away. `site.redirects()` then claims `/news/page/1` with a 301 onto the
+     * bare slug, since a URL nothing publishes is still one a reader edits
+     * their way to.
      *
      * Usually set per project rather than here: the count is posts divided by
      * page size, and one venue has more posts than another.

package/src/routes/resolve.ts

@@ -129,6 +129,16 @@ export function pageSegmentFor<L extends string>(
     return ctx.pageSegmentByLocale?.[locale] ?? ctx.pageSegment;
 }
 
+/** A list's base path with a page number hung under the page segment. */
+function underPageSegment(
+    base: UrlPath,
+    segment: string,
+    page: number
+): UrlPath {
+    // The locale root is `/`, and joining onto it would double the slash.
+    return base === "/" ? `/${segment}/${page}` : `${base}/${segment}/${page}`;
+}
+
 /**
  * The path of one page of a route's list.
  *
@@ -144,9 +154,24 @@ export function pagePath<L extends string>(
 ): UrlPath {
     if (page <= 1) return base;
 
-    const segment = pageSegmentFor(locale, ctx);
-    // The locale root is `/`, and joining onto it would double the slash.
-    return base === "/" ? `/${segment}/${page}` : `${base}/${segment}/${page}`;
+    return underPageSegment(base, pageSegmentFor(locale, ctx), page);
+}
+
+/**
+ * The `.../page/1` a list is deliberately *not* published at.
+ *
+ * The counterpart of the rule above: giving page one the bare path leaves the
+ * numbered form unclaimed, and unclaimed is not unasked-for — a reader edits
+ * `/news/page/2` down to `1`, or a crawler assumes a sequence starts where its
+ * segment says. So this is the one path here that exists to be redirected away
+ * from rather than linked, and nothing but `redirects()` should name it.
+ */
+export function pageOneAlias<L extends string>(
+    base: UrlPath,
+    locale: L,
+    ctx: PathContext<L>
+): UrlPath {
+    return underPageSegment(base, pageSegmentFor(locale, ctx), 1);
 }
 
 export function localePrefix<L extends string>(

package/src/site/api.ts

@@ -292,6 +292,18 @@ export interface Site<
      * a retranslated slug moves it too. External targets are `https://` URLs and
      * pass through untouched.
      *
+     * **What comes back is more than what went in.** lib adds the rules the
+     * route table implies, for the URLs its own design leaves unpublished but
+     * reachable: whichever site root the routing mode does not serve — `/` when
+     * every locale is prefixed, `/en-US` when the default locale is not — and
+     * `/news/page/1` for a list whose page one is the bare path. A rule you
+     * state for one of those paths replaces the inferred one, so pass `[]` and
+     * you still get a file worth writing.
+     *
+     * Pages under an unused locale prefix are *not* claimed: that is a rule per
+     * page per language, and it still misses the reader who edits a translated
+     * slug's prefix. See `NOT-BUILT.md`.
+     *
      * Returns the rules as data. Rendering is a separate step —
      * `buildCloudflareRedirects` writes the `_redirects` that Cloudflare and
      * Netlify read, and a host with its own syntax takes these and writes its own.