@escape-game-over/atlas 0.1.114 → 0.1.116

package/docs/NOT-BUILT.md

@@ -209,10 +209,10 @@ something renders a currency picker, and not before.
 
 `LocalBusinessInput.type` and `ProductInput.alsoA` take bare strings, so
 `"EntertainmentBussiness"` compiles, gets emitted, and is ignored by every
-reader — the silent failure that `RobotsDirective` and `OpenGraphType` were
+reader — the silent failure that `RobotsDirective` was
 tightened to prevent.
 
-They are not the same case. Those two vocabularies are closed; schema.org has
+They are not the same case. That vocabulary is closed; schema.org has
 around 800 types and is still growing. A partial enumeration of an open
 vocabulary rejects types that are perfectly valid, and the response to that is
 to cast past it — at which point the check is theatre. A literal union that

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.114",
+    "version": "0.1.116",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/analytics/storage.ts

@@ -97,7 +97,7 @@ export interface StoredItem {
     readonly consent: ConsentCategory | "none";
 }
 
-export interface StoredItemsOptions {
+export interface StoredItemsOptions<Purpose> {
     /** As passed to `Document`, and with its default: `true`. */
     readonly rememberLocale?: boolean;
     /** As passed to `Document`, and with its default: `false`. */
@@ -109,12 +109,17 @@ export interface StoredItemsOptions {
      */
     readonly booking?: readonly BookingVendor[];
     /**
-     * Rows the site sets first, then by what has to be granted — nothing,
-     * analytics, marketing — and otherwise in catalog order. Off, the rows
-     * come in catalog order: Atlas's own, then each vendor's site row before
-     * its vendor-domain one.
+     * What each row is for, in the project's words — a message key, usually,
+     * since the words are the project's and in every locale.
+     *
+     * Required, and every row this deployment has must be named: a notice
+     * that lists a cookie without a purpose is the one thing it must not
+     * publish, so a vendor switched on, or a row a new Atlas adds, fails the
+     * build until the site says what it is for. Rows this deployment does not
+     * have may be named too; a site keeps its wording when a vendor is
+     * switched off.
      */
-    readonly sort?: boolean;
+    readonly purposes: Readonly<Partial<Record<StoredId, Purpose>>>;
 }
 
 interface Stored {
@@ -264,7 +269,7 @@ type VendorWithOwn = {
         : never;
 }[keyof typeof CATALOG];
 
-/** Catalog order, which is also the order rows come in unsorted. */
+/** Catalog order, which is how rows that sort alike stay ordered. */
 const VENDOR_ORDER: readonly StorageVendor[] = [
     "google-analytics",
     "google-ads",
@@ -372,8 +377,12 @@ const CONSENT_ORDER: readonly StoredItem["consent"][] = [
     "marketing",
 ];
 
-/** The rows the `sort` option puts first come first; ties keep their order. */
-export function compareStoredItems(a: StoredItem, b: StoredItem): number {
+/**
+ * Rows the site sets first, then by what has to be granted — nothing,
+ * analytics, marketing. Ties keep catalog order: Atlas's own, then each
+ * vendor's site row before its vendor-domain one.
+ */
+function compareStoredItems(a: StoredItem, b: StoredItem): number {
     return (
         Number(b.provider === "site") - Number(a.provider === "site") ||
         CONSENT_ORDER.indexOf(a.consent) - CONSENT_ORDER.indexOf(b.consent)
@@ -381,45 +390,22 @@ export function compareStoredItems(a: StoredItem, b: StoredItem): number {
 }
 
 /**
- * Each row with what the project says it is for — a message key, usually,
- * since the words are the project's and in every locale.
- *
- * Throws, naming every row without one, so a vendor switched on, or a row a
- * new Atlas adds, fails the build until the site has said what it is for: a
- * notice that lists a cookie without a purpose is the one thing it must not
- * publish. `purposes` may name rows this deployment does not have; a site
- * keeps its wording when a vendor is switched off.
- */
-export function withPurposes<K>(
-    rows: readonly StoredItem[],
-    purposes: Partial<Record<StoredId, K>>
-): readonly (StoredItem & { readonly purpose: K })[] {
-    const missing = rows.filter((row) => purposes[row.id] === undefined);
-    if (missing.length > 0) {
-        throw new Error(
-            `The storage table has no purpose for ${missing.map((row) => `"${row.id}"`).join(", ")}. Add one for each to the purposes given to withPurposes.`
-        );
-    }
-    return rows.map((row) => ({ ...row, purpose: purposes[row.id] as K }));
-}
-
-/**
- * Everything this deployment keeps on a device: Atlas's own keys, then each
- * loaded vendor's.
+ * Everything this deployment keeps on a device, each row with its purpose:
+ * the site's own rows first, then by what has to be granted.
  *
  * Atlas's rows follow what the page renders, which `Document` decides from
  * its props, so pass the same `rememberLocale` and `rememberCampaign` here.
  * The consent record is listed whenever there is a banner to answer.
  */
-export function storedItems(
+export function storedItems<const Purpose>(
     analytics: AnalyticsSettings | undefined,
-    options: StoredItemsOptions = {}
-): readonly StoredItem[] {
+    options: StoredItemsOptions<Purpose>
+): readonly (StoredItem & { readonly purpose: Purpose })[] {
     const {
         rememberLocale = true,
         rememberCampaign = false,
         booking = [],
-        sort = false,
+        purposes,
     } = options;
     const asked = consentVendors(analytics).length > 0;
 
@@ -506,5 +492,14 @@ export function storedItems(
 
     rows.push(...widgetRows);
 
-    return sort ? rows.toSorted(compareStoredItems) : rows;
+    const missing = rows.filter((row) => purposes[row.id] === undefined);
+    if (missing.length > 0) {
+        throw new Error(
+            `The storage table has no purpose for ${missing.map((row) => `"${row.id}"`).join(", ")}. Add one for each to storedItems' purposes.`
+        );
+    }
+    return rows.toSorted(compareStoredItems).flatMap((row) => {
+        const purpose = purposes[row.id];
+        return purpose === undefined ? [] : [{ ...row, purpose }];
+    });
 }

package/src/astro/images.ts

@@ -331,36 +331,22 @@ export async function photoSet(
 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.
+ * The built URL of an optimised image, for places that take a path rather than
+ * an `<img>`: a CSS `url()` in an inline style or custom property, a
+ * `<link rel="preload">`, a manifest icon.
  *
- * ```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" }),
- *     // …
- * });
+ * ```astro
+ * <section style={`--hero: url(${await imagePath(hero, { width: 1600, format: "webp" })})`}>
  * ```
  *
- * 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.
+ * A function rather than `getImage().src` at each call site because that is
+ * typed `string`, and a path is wanted as `UrlPath`: narrowed once here, with
+ * no cast at every caller.
  *
- * 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/`.
+ * **Not for structured data.** What comes back is `/_astro/hero.<hash>.webp`,
+ * and the hash moves whenever the source changes. Right for a resource fetched
+ * with the page; wrong for an `Organization.logo` or anything else a search
+ * engine stores against an identity, which wants a stable path in `public/`.
  */
 export async function imagePath(
     src: ImageMetadata,

package/src/astro/index.ts

@@ -27,12 +27,5 @@
  */
 
 export { siteFonts } from "./fonts.ts";
-export {
-    type PublicFilesOptions,
-    publicFiles,
-} from "./public-files.ts";
-export {
-    type SiteFiles,
-    type SiteRoutesOptions,
-    siteRoutes,
-} from "./site-routes.ts";
+export { publicFiles } from "./public-files.ts";
+export { siteRoutes } from "./site-routes.ts";

package/src/astro/public-files.ts

@@ -2,13 +2,8 @@ import type { Dirent } from "node:fs";
 import { readdir } from "node:fs/promises";
 import type { AstroIntegration } from "astro";
 
-/**
- * The module the generated union is declared in.
- *
- * Types only, so nothing has to exist at runtime: a consumer reaches it with
- * `import type`, which is erased before anything tries to resolve it.
- */
-const PUBLIC_MODULE = "atlas:public";
+/** The package the generated declaration merges into, as consumers import it. */
+const LIB_MODULE = "@escape-game-over/atlas";
 
 /** Files in `public/` that are not content: editor litter and placeholders. */
 const IGNORED = new Set([".DS_Store", "Thumbs.db", ".gitkeep"]);
@@ -38,13 +33,9 @@ async function walk(dir: URL, prefix = ""): Promise<string[]> {
 }
 
 /**
- * Types every file in `public/`, so linking to one is checked.
- *
- * ```ts
- * import type { PublicFile } from "atlas:public";
- *
- * const statement: PublicFile = "/reports/annual-2026.pdf";
- * ```
+ * Types every file in `public/`, so linking to one is checked: `site.fileUrl()`
+ * and a redirect's `{ file }` target take `PublicFilePath`, which this narrows
+ * from any path to the files that are there.
  *
  * `public/` is the one part of a site the compiler cannot see: files are copied
  * to the output verbatim, so a link to one is a string nothing verifies, and a
@@ -56,45 +47,19 @@ async function walk(dir: URL, prefix = ""): Promise<string[]> {
  * commit or add to a tsconfig. A file added while the dev server runs is picked
  * up when it restarts.
  */
-export interface PublicFilesOptions {
-    /**
-     * How the consuming project imports this package.
-     *
-     * Defaults to the published name, which is what a project installing it
-     * from the registry writes. State it only where that is not the specifier
-     * in the import statements — a path alias, or a fork under another name.
-     *
-     * Needed because the generated file *augments* that module: the union has to
-     * reach `fileUrl` and the redirect target, and a declaration can only be
-     * merged into a module named the way the consumer names it.
-     */
-    readonly libModule?: string;
-}
-
-export function publicFiles(
-    options: PublicFilesOptions = {}
-): AstroIntegration {
-    const libModule = options.libModule ?? "@escape-game-over/atlas";
-
+export function publicFiles(): AstroIntegration {
     return {
         name: "public-files",
         hooks: {
             "astro:config:done": async ({ config, injectTypes, logger }) => {
                 const files = (await walk(config.publicDir)).sort();
-                /**
-                 * The union, one file per line, indented by `spaces`.
-                 *
-                 * A count rather than the whitespace itself: the two call sites
-                 * sit at different depths in the emitted file, and passing the
-                 * indent as a literal means counting spaces by eye in a string
-                 * that looks identical whether it holds eight of them or nine.
-                 */
-                const union = (spaces: number) =>
+                // One file per line, at the depth the declaration sits.
+                const union =
                     files.length === 0
                         ? "never"
                         : files
                               .map((file) => `"${file}"`)
-                              .join(`\n${" ".repeat(spaces)}| `);
+                              .join("\n            | ");
 
                 injectTypes({
                     filename: "public-files.d.ts",
@@ -105,17 +70,11 @@ export function publicFiles(
                     // export lib has.
                     content: `export {};
 
-declare module "${PUBLIC_MODULE}" {
-    /** Every file in \`public/\`, as it is served. */
-    export type PublicFile =
-        | ${union(8)};
-}
-
-declare module "${libModule}" {
+declare module "${LIB_MODULE}" {
     /** Merged so \`fileUrl\` and redirect targets accept only these. */
     interface PublicFileRegistry {
         path:
-            | ${union(12)};
+            | ${union};
     }
 }
 `,

package/src/astro/site-routes.ts

@@ -119,16 +119,11 @@ export function siteRoutes<Id extends string, L extends string>(
     const describe = (file: GeneratedFile): string =>
         `${file.name} (${size(file.body)})`;
 
-    // Rebuilt per request in dev and once at the end of a build, rather than
-    // 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.
+    // Built when the dev server starts and when a build ends. The `site` and
+    // `llms` this closes over are fixed when the Astro config is evaluated, so
+    // in dev these files change only on a restart: editing a message refreshes
+    // the page that renders it, not `llms.txt`. A build is always right, since
+    // it evaluates the config in a fresh process.
     const generate = (): GeneratedFile[] => {
         const files: GeneratedFile[] = [...site.sitemap().files, site.robots()];
         // Every page's head links to it, so one is written unless the config
@@ -352,35 +347,11 @@ export function siteRoutes<Id extends string, L extends string>(
              * them out of the page graph.
              */
             "astro:server:setup": ({ server, logger }) => {
-                /**
-                 * The paths this integration answers on, learned by generating
-                 * once and refreshed whenever we generate again.
-                 *
-                 * Its whole job is to keep `generate()` off the hot path. The
-                 * middleware sees every request the dev server takes — each
-                 * page, each asset, each Vite ping — and regenerating for all
-                 * of them rebuilds the sitemap three times over (once directly,
-                 * once inside `robots()`, once inside `llms()`) to answer a
-                 * request for `/favicon.ico`.
-                 *
-                 * A name that appears only later is the one thing this can
-                 * miss: a sitemap crossing `entryLimit` mid-session gains
-                 * `sitemap-0.xml` and friends, which are not in the set until
-                 * something regenerates. Acceptable because the set is
-                 * refreshed on every hit and the dev server restarts on a
-                 * config change — and because the alternative is paying for a
-                 * full generate on every asset request to catch it.
-                 */
-                const served = new Set<string>();
-                const remember = (files: readonly GeneratedFile[]) => {
-                    served.clear();
-                    for (const file of files) served.add(`/${file.name}`);
-                    return files;
-                };
-
-                remember(generate()).map((file) =>
-                    logger.info(`generated ${describe(file)}`)
-                );
+                const files = new Map<string, GeneratedFile>();
+                for (const file of generate()) {
+                    logger.info(`generated ${describe(file)}`);
+                    files.set(`/${file.name}`, file);
+                }
                 server.middlewares.use((request, response, next) => {
                     const path = (request.url ?? "").split("?")[0] ?? "";
 
@@ -406,23 +377,8 @@ export function siteRoutes<Id extends string, L extends string>(
                         return;
                     }
 
-                    // Nothing of ours sits at this path, so hand it on without
-                    // building anything. This is the check that keeps the cost
-                    // below off every page and asset request in dev.
-                    if (!served.has(path)) {
-                        next();
-                        return;
-                    }
-
-                    // Regenerated per request, so an edit to a route or a
-                    // message shows up on reload rather than at restart.
-                    const file = remember(generate()).find(
-                        (candidate) => `/${candidate.name}` === path
-                    );
+                    const file = files.get(path);
                     if (file === undefined) {
-                        // The set said this was ours and the fresh build
-                        // disagrees — a file that stopped being generated, so
-                        // it is now a 404 like any other missing path.
                         next();
                         return;
                     }

package/src/config.ts

@@ -173,15 +173,6 @@ export function defineSiteConfig<
     return config;
 }
 
-/**
- * What a project may restate about a locale.
- *
- * Only the label: writing direction is a fact about the script a language is
- * written in, not a choice a deployment makes, so it is derived from the tag.
- * The label is the one part that is a matter of taste.
- */
-export type LocaleMetaOverride = Pick<LocaleMeta, "label">;
-
 /**
  * Editor-facing error for a locale this site does not declare at all.
  *
@@ -199,27 +190,27 @@ export interface LocaleNotEnabled<L extends string> {
 }
 
 /**
- * Applies a project's overrides and derives the tag fields from the key.
+ * Each published locale's label, the project's where it gives one, with the
+ * tag fields derived from its key.
  *
  * The locale key is the language tag, and `ogLocale` is that tag with `-`
  * swapped for `_` — Open Graph writes `en_US` where BCP 47 writes `en-US`.
  * `dir` comes from the tag's script, so `ar-EG` and `az-Arab-IR` are
  * right-to-left and `az-AZ` is not.
  */
-export function mergeLocaleMeta<L extends string>(
+export function resolveLocaleMeta<L extends string>(
     base: Readonly<Record<L, LocaleMeta>>,
-    overrides: Readonly<Partial<Record<L, LocaleMetaOverride>>> | undefined,
-    locales: readonly L[]
+    locales: readonly L[],
+    labels: Readonly<Partial<Record<L, string>>>
 ): Readonly<Record<L, ResolvedLocaleMeta>> {
     const merged: Record<string, ResolvedLocaleMeta> = {};
     for (const locale of locales) {
-        const defaults = base[locale];
-        if (defaults === undefined) {
+        const meta = base[locale];
+        if (meta === undefined) {
             throw new Error(`No locale metadata for "${locale}".`);
         }
-        const meta = { ...defaults, ...overrides?.[locale] };
         merged[locale] = {
-            label: meta.label,
+            label: labels[locale] ?? meta.label,
             dir: writingDirection(locale),
             htmlLang: locale,
             ogLocale: locale.replace(/-/g, "_"),

package/src/content/rich.ts

@@ -61,8 +61,8 @@ export type Span =
     /**
      * A link, in the three shapes a destination actually comes in.
      *
-     * **A union rather than an optional `url` and an `external` flag**, for the
-     * reason `PageKind` is one: those two fields could disagree, and `external:
+     * **A union rather than an optional `url` and an `external` flag**: those
+     * two fields could disagree, and `external:
      * true` with no absolute URL is a state that means nothing and would still
      * type-check. Here the discriminant *is* the answer — a consumer that needs
      * an absolute URL narrows on `to` and gets one, or is told plainly that this
@@ -297,16 +297,15 @@ export function createRichText<
 ): RichTextFor<Catalog, RouteId, Links, Values> {
     const { catalog, locale, link, origin, links, values } = options;
 
-    return <K extends StringKeys<Catalog>>(
-        ...args: RichArgsOf<Catalog, K, RouteId, Links, Values>
+    // Untyped inside: the return type is what callers see, keys and params
+    // checked. Placeholder values and link targets are both strings once here —
+    // the distinction they are worth making is entirely a compile-time one.
+    return (
+        key: string,
+        params?: Readonly<Record<string, string>>
     ): RichText => {
-        // The conditional tuple cannot be destructured directly; the runtime
-        // shape is always `[key]` or `[key, params]`. As in `createTranslate`.
-        // Placeholder values and link targets are both strings once here — the
-        // distinction they are worth making is entirely a compile-time one.
-        const [key, params] = args as [K, Readonly<Record<string, string>>?];
-        const at = `Message "${String(key)}" (${locale})`;
-        const template = lookupTemplate(catalog, locale, String(key));
+        const at = `Message "${key}" (${locale})`;
+        const template = lookupTemplate(catalog, locale, key);
 
         return parseMarks(template, at).map((span) =>
             resolve(span, at, params, { links, values }, link, origin)
@@ -379,7 +378,7 @@ function fill(
  * The destination a slot was filled with.
  *
  * `Object.hasOwn` rather than reading the index straight, for the reason
- * `createRawTranslate` uses it: `__proto__` is a legal slot name by `SLOT`, so
+ * `createTranslate` uses it: `__proto__` is a legal slot name by `SLOT`, so
  * a plain object would answer with `Object.prototype` — not `undefined`, and so
  * not caught below.
  *
@@ -620,12 +619,10 @@ export function createPlainText<
 ): PlainTextFor<Catalog, Values> {
     const { catalog, locale, values } = options;
 
-    return <K extends StringKeys<Catalog>>(
-        ...args: TranslateArgsOf<Catalog, K, Values>
-    ): string => {
-        const [key, params] = args as [K, Readonly<Record<string, string>>?];
-        const at = `Message "${String(key)}" (${locale})`;
-        const template = lookupTemplate(catalog, locale, String(key));
+    // Untyped inside, as `rich()`: the return type is what callers see.
+    return (key: string, params?: Readonly<Record<string, string>>): string => {
+        const at = `Message "${key}" (${locale})`;
+        const template = lookupTemplate(catalog, locale, key);
 
         return collapse(
             parseMarks(template, at).map((span) =>

package/src/i18n/catalog.ts

@@ -29,6 +29,8 @@ export interface ProjectCatalog<Base, Published extends string, Override, Add> {
     readonly override: Override;
     /** Messages only this project has. */
     readonly add: Add;
+    /** The project's names for its languages, where the site's do not fit. */
+    readonly labels: Readonly<Partial<Record<Published, string>>>;
 }
 
 /**
@@ -99,7 +101,8 @@ export type OverrideChecks<Base, Published extends string, O> = NoExcessKeys<
  *  - `override` keys exist in the base catalog, keep its `{placeholders}` and
  *    `[marks]`, and are written only for published locales;
  *  - `add` keys are new to the base catalog, written for exactly the published
- *    locales, with the same `{placeholders}` and `[marks]` in each.
+ *    locales, with the same `{placeholders}` and `[marks]` in each;
+ *  - `labels` are for published locales.
  */
 export function defineCatalog<
     const C extends SiteConfigShape,
@@ -119,6 +122,13 @@ export function defineCatalog<
         readonly override: Override &
             ValidateOverrideCatalog<Override, Base, LocalesOf<C>>;
         readonly add?: Add & ValidateAdditions<Add, Base, Published>;
+        /**
+         * A language's name in the language switcher, replacing the site's
+         * label for that locale on this project only. `NoInfer`, so a label
+         * cannot widen the published locales: a locale written here that
+         * `locales` lacks is an error on its own line.
+         */
+        readonly labels?: Readonly<Partial<Record<NoInfer<Published>, string>>>;
     }
 ): ProjectCatalog<Base, Published, Override, Add> {
     // Checked at runtime as well as in the type: an Astro config is evaluated
@@ -144,10 +154,19 @@ export function defineCatalog<
             );
         }
     }
+    const labels = own.labels ?? {};
+    for (const locale of Object.keys(labels)) {
+        if (!own.locales.some((published) => published === locale)) {
+            throw new Error(
+                `labels: "${locale}" is not among this catalog's locales, so its label would never be shown.`
+            );
+        }
+    }
     return {
         base,
         locales: own.locales,
         override: own.override,
         add: add as Add,
+        labels,
     };
 }

package/src/i18n/define.ts

@@ -54,11 +54,6 @@ export type OverrideCatalog<L extends string> = Readonly<
     Record<string, OverrideEntry<L>>
 >;
 
-/** The locale union a catalog covers, read back off its own entries. */
-export type LocalesOfCatalog<Catalog> = StringKeys<
-    Catalog[StringKeys<Catalog>]
->;
-
 type SelfConsistent<E, K> = [MismatchedLocales<E, EntryTokens<E>>] extends [
     never,
 ]