@escape-game-over/atlas 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.2",
+    "version": "0.1.3",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -20,6 +20,7 @@
         "./astro/dev-log": "./src/astro/dev-log.ts",
         "./astro/dom": "./src/astro/dom.ts",
         "./astro/element": "./src/astro/element.ts",
+        "./astro/filters": "./src/astro/filters.ts",
         "./astro/meta-tags": "./src/astro/MetaTags.astro"
     },
     "bin": {

package/src/astro/build-cache.ts

@@ -0,0 +1,80 @@
+/**
+ * Astro's build cache, pointed at a volume that outlives a CI run.
+ *
+ * The default — `node_modules/.astro` — sits inside the one directory a CI
+ * install deletes before it starts, so a build there re-optimizes every image
+ * and re-downloads every font on every run, however little changed. A site with
+ * a few hundred images spends minutes of every pipeline regenerating bytes it
+ * already has. Moving `cacheDir` onto a mounted volume is the whole fix, and
+ * Astro offers no environment variable of its own to say it — which is why this
+ * is read here and set through `updateConfig` rather than configured per repo.
+ *
+ * One volume is shared by every site that mounts it, rather than a directory
+ * each. Astro keeps four things under `cacheDir` and they do not want the same
+ * treatment:
+ *
+ * - `assets/` — optimized images, named after a hash of the source bytes and
+ *   the transform. Two sites rendering the same asset at the same size produce
+ *   the same filename holding the same bytes, so a hit one of them takes is a
+ *   hit the next does not pay for.
+ * - `fonts/` — provider downloads, keyed the same way on family, weight and
+ *   subset. Sibling sites share a typeface far more often than not.
+ * - `incremental-build.json` and `dist/` — a per-project route manifest, read
+ *   only when `experimental.incrementalBuild` is on.
+ * - `data-store.json` — the content layer's store, written only by a project
+ *   that has content collections.
+ *
+ * The first two are content-addressed and want to be shared. The last two are
+ * per-project state, and two projects in one directory each overwrite the
+ * other's copy. Both guard themselves — the manifest against a config and
+ * lockfile hash, the store against a digest of the resolved Astro config — so a
+ * collision costs a rebuild rather than serving one project's content to
+ * another. It is still a cache that never hits, and the day a site turns either
+ * one on is the day this wants a per-repository sub-directory instead.
+ *
+ * A caveat that belongs to sharing rather than to this file: Astro writes a
+ * cache entry with a plain write and reads it with a copy, neither atomic, so
+ * two builds first generating the same transform in the same instant can copy a
+ * half-written file. The window is a few milliseconds per file and only opens
+ * on a miss both take together; the cost is one bad image in an output that a
+ * rebuild fixes.
+ */
+
+import { posix } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * The variable CI sets to a cache volume that outlives a single build.
+ *
+ * Named for the environment and not for Astro because that is what it
+ * describes: nothing outside CI sets it, and on a machine that does not, the
+ * default cache is already the right answer.
+ */
+const CACHE_ROOT = "CI_ASTRO_CACHE";
+
+/**
+ * The volume to build in, or `undefined` to leave `cacheDir` alone.
+ *
+ * `undefined` rather than a fallback path is what makes this safe to call
+ * unconditionally: `updateConfig` skips a key whose value is nullish, so an
+ * unset variable leaves the config exactly as it would be if nothing here ran.
+ *
+ * A `URL` and not a string, because this arrives after Astro resolved its own
+ * config: `cacheDir` is a `file:` URL by the time an integration can see it,
+ * and the merge behind `updateConfig` replaces a URL only with another URL. The
+ * trailing separator is load-bearing for the same reason — every reader
+ * composes against it with `new URL("assets/", cacheDir)`, which without one
+ * would resolve into the parent directory instead.
+ */
+export function buildCacheDir(): URL | undefined {
+    const root = process.env[CACHE_ROOT]?.trim();
+    if (!root) {
+        return undefined;
+    }
+
+    // `posix` rather than the platform's own: the value names a path inside the
+    // CI container, and a checkout on Windows reading it would still be
+    // describing that container. Joining the separator is what normalizes a
+    // root written with one, without one, or with several.
+    return pathToFileURL(posix.join(root, posix.sep));
+}

package/src/astro/filters.ts

@@ -0,0 +1,457 @@
+/**
+ * A filtered list's state and its URL — not its markup.
+ *
+ * In `astro/` for the reason `carousel.ts` is: it reaches for `location`,
+ * `history` and `window`, which the core is type-checked without.
+ *
+ * **It draws nothing.** No `hidden`, no `aria-selected`, no counts, no empty
+ * state. It owns which items match and what the address bar says, and calls
+ * `onChange` when either moves; a project does every DOM write, and its markup
+ * contract — however many data attributes that turns out to be — stays where the
+ * markup is. That is the whole split, and it is why one function can serve a
+ * game grid with tabs and a two-input directory.
+ *
+ * Matching is the one place this cannot copy `carousel`. A carousel's entire
+ * state is an integer, so it never needs to know anything about the page. A
+ * predicate needs each item's text, and that text lives in the markup — so the
+ * caller hands it over once, as plain values, rather than the library reaching
+ * into the DOM for it. Keys are strings for the same reason: nothing here holds
+ * an element, and the whole module is testable without a document.
+ *
+ * ```ts
+ * const list = filters({
+ *     fields: {
+ *         q: { kind: "text", param: "q" },
+ *         category: { kind: "choice", param: "category" },
+ *     },
+ *     items: games.map((game) => ({
+ *         key: game.id,
+ *         values: { q: `${game.name} ${game.blurb}`, category: game.category },
+ *     })),
+ *     onChange: ({ matched }) => {
+ *         for (const [key, element] of elements) element.hidden = !matched.has(key);
+ *     },
+ * });
+ *
+ * const detach = list.attach();
+ * ```
+ *
+ * What it owns is the handful of things identical in every filtered list and
+ * quietly wrong in most: folding so a query without accents still matches words
+ * with them, a query and its facets resolved together rather than in two passes,
+ * and a URL that behaves — replaced while typing so one search does not bury the
+ * previous page in history, pushed on a deliberate choice so the back button
+ * undoes it, empty parameters dropped rather than left as `?q=`, and `popstate`
+ * applied rather than ignored.
+ *
+ * Reading the URL in `attach` is also what lets a list work before this script
+ * arrives: a `<form method="get">` submits, the server renders the filtered
+ * page, and the first `onChange` here continues from that state instead of
+ * resetting it.
+ */
+
+/**
+ * What a field is, as data rather than a constructor.
+ *
+ * A plain object because that is all a field is — a kind and, if it belongs in
+ * the URL, a parameter name. Three exported builder functions would add three
+ * very general names to a module a project imports by name (`text` above all)
+ * and would return exactly this.
+ *
+ * The kinds are closed, and deliberately few:
+ *
+ * - `text` — free entry, folded and substring-matched. The search box.
+ * - `choice` — one of a set, or none. Tabs, a `<select>`, a radio group.
+ * - `flag` — a narrowing toggle: off matches everything, on keeps only the
+ *   items that carry it. "Arena only", "In stock".
+ *
+ * `flag` is not a tri-state and should not become one. On, off and *either* is
+ * a `choice` with two values; folding that into a toggle gives a control with a
+ * third position nothing can reach.
+ */
+export type Field =
+    | { readonly kind: "text"; readonly param?: string }
+    | { readonly kind: "choice"; readonly param?: string }
+    | { readonly kind: "flag"; readonly param?: string };
+
+/** The fields of one list, named by the caller. */
+export type FieldMap = Readonly<Record<string, Field>>;
+
+/**
+ * What one field contributes, on an item and in the state.
+ *
+ * One type for both roles because per kind they genuinely coincide, though they
+ * mean different things: on an item a `text` value is everything that field
+ * searches — a name and a blurb joined — while in the state it is what someone
+ * typed. A `flag` is what the item is on one side and what was asked for on the
+ * other.
+ */
+export type FieldValue<F extends Field> = F["kind"] extends "flag"
+    ? boolean
+    : string;
+
+/** Every field's value for one item, derived from the field declaration. */
+export type ItemValues<F extends FieldMap> = {
+    readonly [K in keyof F]: FieldValue<F[K]>;
+};
+
+/** What the list is filtered to right now. */
+export type FilterState<F extends FieldMap> = {
+    readonly [K in keyof F]: FieldValue<F[K]>;
+};
+
+export interface FilterItem<F extends FieldMap> {
+    /**
+     * How the caller finds this item again.
+     *
+     * Opaque here and unique across the list — a duplicate is rejected at
+     * construction, because two items answering to one key make `matched`
+     * unable to say which of them matched.
+     */
+    readonly key: string;
+    readonly values: ItemValues<F>;
+}
+
+export interface FilterChange<F extends FieldMap> {
+    readonly state: FilterState<F>;
+    /**
+     * The keys that survive every field at once.
+     *
+     * A set rather than a filtered list, so a caller renders by asking about the
+     * items it already holds instead of diffing two arrays — and `size` is the
+     * count a "showing N" line wants, with no second pass.
+     */
+    readonly matched: ReadonlySet<string>;
+}
+
+export interface FiltersOptions<F extends FieldMap> {
+    readonly fields: F;
+    /**
+     * The full list, every time — this filters, it does not paginate.
+     *
+     * Fixed for the lifetime of the instance. A list whose contents change is a
+     * new instance, which is one line at the call site and avoids this owning a
+     * second lifecycle it would have to keep in step with `attach`.
+     */
+    readonly items: readonly FilterItem<F>[];
+    /**
+     * Called whenever the state moves, and once on `attach` with whatever the
+     * URL already said.
+     *
+     * Never called for a `set` that changes nothing: re-rendering an unchanged
+     * list on every keystroke that did not alter the query is work a caller
+     * cannot skip on its own, because by then it has been told the state
+     * changed.
+     */
+    onChange(change: FilterChange<F>): void;
+}
+
+export interface SetOptions {
+    /**
+     * Whether this move is worth a step in history.
+     *
+     * Defaults from the kind — `text` replaces, `choice` and `flag` push —
+     * because that is the pairing almost every control wants: typing emits an
+     * event per keystroke and would otherwise fill history with a word being
+     * spelled, while picking a category is one deliberate act the back button
+     * should undo.
+     *
+     * It is an override rather than a fixed rule because the default is really
+     * a fact about the *input*, not the field. A `<select>` that sets a `text`
+     * field, or a preset link, is a deliberate choice and wants `"push"`.
+     */
+    readonly history?: "push" | "replace";
+}
+
+export interface Filters<F extends FieldMap> {
+    readonly state: FilterState<F>;
+    readonly matched: ReadonlySet<string>;
+    set<K extends keyof F>(
+        field: K,
+        value: FieldValue<F[K]>,
+        options?: SetOptions
+    ): void;
+    /** Clears one field, or all of them. Always a push: clearing is deliberate. */
+    reset(field?: keyof F): void;
+    /**
+     * Reads the URL, applies it, and starts listening — returns the undo.
+     *
+     * One lifecycle rather than two, as `carousel.attach` is, and for a reason
+     * that bites harder here: with view transitions on, a module bound at top
+     * level executes once per session rather than once per navigation, so the
+     * incoming page gets a live list and dead controls. Driving this from
+     * `astro:page-load` and calling the returned function on teardown is what
+     * makes that correct — and the listener is aborted by its own undo, so it
+     * cannot outlive the page that added it.
+     *
+     * Nothing writes to the URL before this runs. `attach` is what reads it, and
+     * a `set` on an unattached instance would otherwise overwrite state it never
+     * loaded.
+     */
+    attach(): () => void;
+}
+
+/** Combining marks, left behind by `NFD` once the base character is separated. */
+const DIACRITICS = /[̀-ͯ]/g;
+
+/**
+ * A string reduced to what a query should match against.
+ *
+ * Decompose, drop the marks, lowercase, trim. This is the part every list needs
+ * and few have: without it a reader typing `abilita` is told there is no
+ * *Abilità*, and a Romanian catalogue hides every entry spelled with `ă`, `ș` or
+ * `ț` from anyone whose keyboard does not carry them.
+ */
+function fold(value: string): string {
+    return value.normalize("NFD").replace(DIACRITICS, "").toLowerCase().trim();
+}
+
+/**
+ * How a set flag is spelled in the query string, and the only spelling read
+ * back as set.
+ *
+ * An unset flag is *absent* rather than `=0`. One way to say off keeps the URL
+ * short and means there is a single form to handle; two would both have to be
+ * understood forever, and a reader could not tell which of them a link was
+ * carrying. The cost is that a hand-written `?arena=0` reads as off, which is
+ * the answer it would get anyway.
+ *
+ * `1` and not `true` because that is what the existing lists already emit:
+ * links people have shared or bookmarked resolve to the view they named, and a
+ * spelling change would quietly reset every one of them.
+ */
+const FLAG_ON = "1";
+
+export function filters<const F extends FieldMap>(
+    options: FiltersOptions<F>
+): Filters<F> {
+    const { fields, items, onChange } = options;
+    const names = Object.keys(fields) as (keyof F & string)[];
+
+    // Checks that types cannot express, run once. Both failures are silent
+    // otherwise: a duplicate key makes `matched` ambiguous about which item it
+    // meant, and two fields sharing a parameter means each URL write erases the
+    // other's value, which reads as a filter that will not stay set.
+    const keys = new Set<string>();
+    for (const item of items) {
+        if (keys.has(item.key)) {
+            throw new Error(`Two filter items share the key "${item.key}".`);
+        }
+        keys.add(item.key);
+    }
+    const params = new Set<string>();
+    for (const name of names) {
+        const param = fields[name]?.param;
+        if (param === undefined) continue;
+        if (params.has(param)) {
+            throw new Error(
+                `Two filter fields share the URL parameter "${param}".`
+            );
+        }
+        params.add(param);
+    }
+
+    /**
+     * Every item's searchable text, folded once at construction.
+     *
+     * Folding is four string operations, and doing it per item per keystroke is
+     * the difference between a list that filters as you type and one that
+     * stutters. Only the query is folded per render, and there is one of those.
+     */
+    const haystacks = new Map<string, Map<string, string>>();
+    for (const item of items) {
+        const perField = new Map<string, string>();
+        for (const name of names) {
+            if (fields[name]?.kind !== "text") continue;
+            perField.set(name, fold(item.values[name] as string));
+        }
+        haystacks.set(item.key, perField);
+    }
+
+    const empty = (name: keyof F & string): FieldValue<F[typeof name]> =>
+        (fields[name]?.kind === "flag" ? false : "") as FieldValue<
+            F[typeof name]
+        >;
+
+    const blank = (): FilterState<F> =>
+        Object.fromEntries(
+            names.map((name) => [name, empty(name)])
+        ) as FilterState<F>;
+
+    let state = blank();
+    let matched: ReadonlySet<string> = new Set(items.map((item) => item.key));
+
+    /**
+     * Whether the URL is this instance's to write.
+     *
+     * Gates every write, for the reason `carousel` gates autoplay on the same
+     * flag: an instance that was built but never attached has not read the URL,
+     * so writing to it would replace state that nobody here has loaded.
+     */
+    let attached = false;
+
+    function recompute(): void {
+        // The query folded once per render rather than once per item. The other
+        // kinds compare values as they are, so there is nothing to prepare.
+        const queries = new Map<string, string>();
+        for (const name of names) {
+            if (fields[name]?.kind !== "text") continue;
+            queries.set(name, fold(state[name] as string));
+        }
+
+        const next = new Set<string>();
+        for (const item of items) {
+            let hit = true;
+            for (const name of names) {
+                const kind = fields[name]?.kind;
+                if (kind === "text") {
+                    const query = queries.get(name) ?? "";
+                    if (query === "") continue;
+                    if (
+                        !(haystacks.get(item.key)?.get(name) ?? "").includes(
+                            query
+                        )
+                    ) {
+                        hit = false;
+                        break;
+                    }
+                } else if (kind === "choice") {
+                    const wanted = state[name] as string;
+                    if (wanted === "") continue;
+                    if (item.values[name] !== wanted) {
+                        hit = false;
+                        break;
+                    }
+                } else {
+                    // A flag off is not a filter: it keeps everything, rather
+                    // than keeping the items that are *not* flagged. See `Field`.
+                    if (state[name] !== true) continue;
+                    if (item.values[name] !== true) {
+                        hit = false;
+                        break;
+                    }
+                }
+            }
+            if (hit) next.add(item.key);
+        }
+        matched = next;
+    }
+
+    function readUrl(): void {
+        const search = new URLSearchParams(window.location.search);
+        const next: Record<string, string | boolean> = {};
+        for (const name of names) {
+            const field = fields[name];
+            if (field === undefined) continue;
+            if (field.param === undefined) {
+                // No parameter: the field is state-only, and a reload starts it
+                // empty rather than carrying a value the URL never held.
+                next[name] = empty(name);
+                continue;
+            }
+            const raw = search.get(field.param);
+            next[name] = field.kind === "flag" ? raw === FLAG_ON : (raw ?? "");
+        }
+        state = next as FilterState<F>;
+    }
+
+    function writeUrl(history: "push" | "replace"): void {
+        if (!attached) return;
+
+        // Built from the declaration rather than from the URL that is there, so
+        // a parameter this list owns and no longer needs is dropped instead of
+        // surviving because nobody thought to delete it. Fields are written in
+        // declaration order, so the same state always produces the same URL.
+        const search = new URLSearchParams();
+        for (const name of names) {
+            const field = fields[name];
+            if (field?.param === undefined) continue;
+            if (field.kind === "flag") {
+                if (state[name] === true) search.set(field.param, FLAG_ON);
+                continue;
+            }
+            const value = (state[name] as string).trim();
+            if (value !== "") search.set(field.param, value);
+        }
+
+        const query = search.toString();
+        // The bare path when nothing is set, rather than a trailing `?`: the two
+        // are the same page, and only one of them is worth sharing.
+        const url = query === "" ? window.location.pathname : `?${query}`;
+        if (history === "push") window.history.pushState({}, "", url);
+        else window.history.replaceState({}, "", url);
+    }
+
+    const announce = (): void => onChange({ state, matched });
+
+    recompute();
+
+    return {
+        get state() {
+            return state;
+        },
+        get matched() {
+            return matched;
+        },
+
+        set(field, value, setOptions) {
+            const name = field as keyof F & string;
+            // Nothing changed, so nothing is announced and nothing is pushed.
+            // Typing a character that does not alter a trimmed query, or
+            // re-selecting the tab that is already current, should not put a
+            // step in history for the back button to walk through.
+            if (state[name] === value) return;
+
+            state = { ...state, [name]: value };
+            recompute();
+            const fallback = fields[name]?.kind === "text" ? "replace" : "push";
+            writeUrl(setOptions?.history ?? fallback);
+            announce();
+        },
+
+        reset(field) {
+            if (field === undefined) {
+                state = blank();
+            } else {
+                const name = field as keyof F & string;
+                if (state[name] === empty(name)) return;
+                state = { ...state, [name]: empty(name) };
+            }
+            recompute();
+            writeUrl("push");
+            announce();
+        },
+
+        attach() {
+            const listeners = new AbortController();
+
+            // On `window`, and with the same signal as everything else, so a
+            // detach takes it with them. A `popstate` listener that outlives its
+            // page is the one leak here that has no visible symptom: it keeps
+            // rendering into markup that has been replaced.
+            window.addEventListener(
+                "popstate",
+                () => {
+                    readUrl();
+                    recompute();
+                    announce();
+                },
+                { signal: listeners.signal }
+            );
+
+            attached = true;
+            // Read before the first announcement, not after: the URL may already
+            // carry a state — from a shared link, a reload, or a no-script form
+            // submission the server rendered — and announcing the empty one
+            // first would flash the unfiltered list over it.
+            readUrl();
+            recompute();
+            announce();
+
+            return () => {
+                listeners.abort();
+                attached = false;
+            };
+        },
+    };
+}

package/src/astro/images.ts

@@ -10,6 +10,7 @@ import { getImage } from "astro:assets";
 import type { ImageAsset } from "../image.ts";
 import type { ThemeColor } from "../meta/index.ts";
 import type { Percentage } from "../types.ts";
+import { isUrlPath, type UrlPath } from "../url.ts";
 import { warn } from "../warn.ts";
 
 /**
@@ -313,3 +314,75 @@ export async function photoSet(
         })
     );
 }
+
+/**
+ * What `getImage` takes, less the source.
+ *
+ * A passthrough of Astro's own options, which is a deliberate departure from
+ * `ShareImageOptions` and `PhotoSetOptions` above. Those two are closed shapes
+ * because they are *builders*: each decides a box, and letting a caller reach
+ * past that decision would defeat the point of having made it. This one decides
+ * nothing — it exists to hand back a path instead of an object — so narrowing
+ * the options would only make it strictly less useful than the call it wraps.
+ */
+export type ImagePathOptions = Omit<Parameters<typeof getImage>[0], "src">;
+
+/**
+ * The built URL of an optimised image, for the places that take a path rather
+ * than an `<img>` — a JSON-LD node, a `<link>`, a manifest.
+ *
+ * ```ts
+ * import logo from "~/assets/logo.png";
+ * import { imagePath } from "@escape-game-over/atlas/astro/images";
+ *
+ * const company = organization({
+ *     logo: await imagePath(logo, { width: 512, height: 512, format: "png" }),
+ *     // …
+ * });
+ * ```
+ *
+ * The narrowing is the reason this is a function rather than three lines at
+ * each call site. `getImage().src` is typed `string`, every field it feeds here
+ * is typed `UrlPath`, and a cast at each of those would put the same unchecked
+ * assumption in as many places as there are consumers.
+ *
+ * **Not for entity data.** What comes back is `/_astro/logo.<hash>.png`, and the
+ * hash moves every time the source file is touched. That is right for a page
+ * resource, which is re-fetched from a document that was just re-fetched, and
+ * wrong for anything a search engine stores against an identity — an
+ * `Organization.logo` above all, which is held long after the build that
+ * produced it. Those want a stable path out of `public/`, written as `/logo.png`
+ * and joined to the site's own origin; both examples in this repository do that
+ * deliberately and say so at the call site.
+ *
+ * So the fit is: a `<link rel="preload">`, a manifest icon, an `<img>` built by
+ * hand — resources fetched *with* the page. Long-lived references belong in
+ * `public/`.
+ */
+export async function imagePath(
+    src: ImageMetadata,
+    options: ImagePathOptions = {}
+): Promise<UrlPath> {
+    const image = await getImage({ ...options, src });
+
+    // Thrown rather than warned, and thrown here rather than widened away.
+    //
+    // `UrlPath` is root-relative by definition and the fields this feeds are
+    // typed that way on purpose — a `logo` on an `Organization` node is read by
+    // a crawler that already has the origin. What trips this is not a bad image
+    // but a different deployment: `build.assetsPrefix`, or an image service that
+    // returns absolute URLs. Both are a decision about where the whole site's
+    // assets live, and answering it by loosening one return type would leave
+    // every consumer of `UrlPath` accepting a value it cannot use.
+    //
+    // So this stops at the boundary and says which boundary it is. There is
+    // nothing useful to return: a caller that carried on would put a string into
+    // structured data that no crawler can resolve.
+    if (!isUrlPath(image.src)) {
+        throw new Error(
+            `imagePath produced "${image.src}", which is not root-relative. This build serves assets from somewhere else — build.assetsPrefix, or a remote image service — and the fields this feeds are typed UrlPath, which cannot express that. Serving assets from another origin is a site-wide decision and needs the absolute form carried end to end, not this one return type widened.`
+        );
+    }
+
+    return image.src;
+}

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.
@@ -187,6 +188,19 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
              *   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:
@@ -273,6 +287,7 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
                         prefetchAll: true,
                         defaultStrategy: "viewport",
                     },
+                    cacheDir: buildCacheDir(),
                 };
                 updateConfig(config);
                 // Said out loud: a setting changed from under you is worth a

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/site/create.ts

@@ -322,7 +322,18 @@ export function createSite<
             // Umami only, tagged so the misses read on their own — the point
             // of measuring this page is finding a redirect somebody forgot,
             // not counting the people who mistype. See `notFoundAnalytics`.
-            tags: buildNotFoundMeta(title, project.analytics),
+            //
+            // `checkedIcon()` rather than `project.icon`: the 404 is held to the
+            // same square-and-PNG rules as every other page. It is also the one
+            // page that could plausibly render before any other, so letting it
+            // read the icon unchecked would move where a bad one is caught.
+            tags: buildNotFoundMeta({
+                title,
+                analytics: project.analytics,
+                icon: checkedIcon(),
+                themeColor: project.themeColor,
+                colorScheme: project.colorScheme,
+            }),
             // Nothing. The body channel exists for Tag Manager's `<noscript>`,
             // and no Google tag reaches this page.
             bodyTags: [],