@escape-game-over/atlas 0.1.23 → 0.1.25

package/src/meta/share-image.ts

@@ -3,12 +3,16 @@ import { absoluteUrl, type HttpsUrl } from "../url.ts";
 import { warn } from "../warn.ts";
 import { link, type MetaTag } from "./tag.ts";
 
-export type ImageFormat = "png" | "jpg" | "webp";
+type ImageFormat = "png" | "jpg" | "jpeg" | "webp" | "avif" | "gif" | "svg";
 
 const IMAGE_MIME: Readonly<Record<ImageFormat, string>> = {
     png: "image/png",
     jpg: "image/jpeg",
+    jpeg: "image/jpeg",
     webp: "image/webp",
+    avif: "image/avif",
+    gif: "image/gif",
+    svg: "image/svg+xml",
 };
 
 /**
@@ -74,23 +78,6 @@ export interface ShareImage {
     readonly alt: string;
 }
 
-/**
- * The site's icon: one square asset, used for every icon link.
- *
- * Site-wide rather than per page, because search engines use one favicon per
- * hostname, read from the home page — a per-page icon changes the browser tab
- * and nothing else.
- *
- * One asset rather than a set, because one square PNG already covers every
- * consumer: browsers accept PNG for `rel="icon"`, and Apple scales it for
- * `apple-touch-icon`. A `/favicon.ico` in `public/` is still requested by
- * browsers on its own if you want the legacy fallback.
- *
- * Unlike `og:image`, the href stays as written — root-relative is correct for an
- * icon, and absolutising it would only hard-code the origin.
- */
-export type SiteIcon = ImageAsset;
-
 /** One page's resolved share image. */
 export interface OgImage {
     readonly url: HttpsUrl;
@@ -218,7 +205,7 @@ export function resolveShareImage(
  * already has the page, so root-relative is correct and making it absolute would
  * only hard-code the origin.
  */
-export function iconLinks(icon: SiteIcon): MetaTag[] {
+export function iconLinks(icon: ImageAsset): MetaTag[] {
     const mime = imageMime(icon.format);
     const attrs = {
         href: icon.src,

package/src/meta/tag.ts

@@ -1,11 +1,4 @@
-import type { AnalyticsTag } from "../analytics/index.ts";
-
-/**
- * A head tag as data, not markup.
- *
- * lib does not render HTML — that would tie it to one framework and to one
- * templating syntax. It describes the tags; the consumer spreads them.
- */
+/** A head tag as data; `AtlasDocument` renders it. */
 export type MetaTag =
     | { readonly kind: "title"; readonly text: string }
     | {
@@ -68,43 +61,6 @@ export const link = (attrs: Readonly<Record<string, string>>): MetaTag => ({
     attrs,
 });
 
-/**
- * An analytics tag as a head tag. The two vocabularies overlap but are not the
- * same type: `analytics/` knows nothing of `MetaTag`, which is what keeps this
- * folder free to import it without a cycle.
- *
- * Every kind is named rather than left to a trailing `else`, so that adding one
- * to `AnalyticsTag` and forgetting it here is a *compile* error and not a tag
- * that quietly disappears: `script` narrows to `never` only while the list is
- * complete, and assigning anything else to `never` does not type-check.
- */
-export function asMetaTag(script: AnalyticsTag): MetaTag {
-    if (script.kind === "inline") {
-        return { kind: "script", content: script.content };
-    }
-    if (script.kind === "external") {
-        return {
-            kind: "externalScript",
-            src: script.src,
-            attrs: script.attributes,
-        };
-    }
-    if (script.kind === "noscriptFrame") {
-        return { kind: "noscriptFrame", src: script.src };
-    }
-    if (script.kind === "preconnect") {
-        // A `link` rather than a kind of its own: the head vocabulary already
-        // has the shape, and a preconnect is a link in every sense the renderer
-        // cares about. See `AnalyticsTag` for why no `crossorigin`.
-        return {
-            kind: "link",
-            attrs: { rel: "preconnect", href: script.origin },
-        };
-    }
-    const unhandled: never = script;
-    throw new Error(`Unhandled analytics tag: ${JSON.stringify(unhandled)}`);
-}
-
 const DEFAULT_VIEWPORT = "width=device-width, initial-scale=1";
 
 interface Preamble {

package/src/money.ts

@@ -1,13 +1,168 @@
-import type { Letter } from "./types.ts";
-
 /**
  * An ISO 4217 currency code: `"EUR"`, `"RON"`, `"GBP"`.
  *
- * Three uppercase letters, which is what `priceCurrency` is read as. A symbol —
- * `€`, `lei` — is how a price is *printed* in one place for one audience, and
- * two currencies can share one symbol, so it identifies nothing.
+ * A code rather than a symbol — `€`, `lei` — because two currencies can share a
+ * symbol, and `priceCurrency` is read as a code.
+ *
+ * Circulating currencies from ISO 4217 List One (SIX, published 2026-09-17):
+ * fund, precious-metal, testing and accounting-unit codes left out.
  */
-export type CurrencyCode = `${Letter}${Letter}${Letter}`;
+export type CurrencyCode =
+    | "AED"
+    | "AFN"
+    | "ALL"
+    | "AMD"
+    | "AOA"
+    | "ARS"
+    | "AUD"
+    | "AWG"
+    | "AZN"
+    | "BAM"
+    | "BBD"
+    | "BDT"
+    | "BHD"
+    | "BIF"
+    | "BMD"
+    | "BND"
+    | "BOB"
+    | "BRL"
+    | "BSD"
+    | "BTN"
+    | "BWP"
+    | "BYN"
+    | "BZD"
+    | "CAD"
+    | "CDF"
+    | "CHF"
+    | "CLP"
+    | "CNY"
+    | "COP"
+    | "CRC"
+    | "CUP"
+    | "CVE"
+    | "CZK"
+    | "DJF"
+    | "DKK"
+    | "DOP"
+    | "DZD"
+    | "EGP"
+    | "ERN"
+    | "ETB"
+    | "EUR"
+    | "FJD"
+    | "FKP"
+    | "GBP"
+    | "GEL"
+    | "GHS"
+    | "GIP"
+    | "GMD"
+    | "GNF"
+    | "GTQ"
+    | "GYD"
+    | "HKD"
+    | "HNL"
+    | "HTG"
+    | "HUF"
+    | "IDR"
+    | "ILS"
+    | "INR"
+    | "IQD"
+    | "IRR"
+    | "ISK"
+    | "JMD"
+    | "JOD"
+    | "JPY"
+    | "KES"
+    | "KGS"
+    | "KHR"
+    | "KMF"
+    | "KPW"
+    | "KRW"
+    | "KWD"
+    | "KYD"
+    | "KZT"
+    | "LAK"
+    | "LBP"
+    | "LKR"
+    | "LRD"
+    | "LSL"
+    | "LYD"
+    | "MAD"
+    | "MDL"
+    | "MGA"
+    | "MKD"
+    | "MMK"
+    | "MNT"
+    | "MOP"
+    | "MRU"
+    | "MUR"
+    | "MVR"
+    | "MWK"
+    | "MXN"
+    | "MYR"
+    | "MZN"
+    | "NAD"
+    | "NGN"
+    | "NIO"
+    | "NOK"
+    | "NPR"
+    | "NZD"
+    | "OMR"
+    | "PAB"
+    | "PEN"
+    | "PGK"
+    | "PHP"
+    | "PKR"
+    | "PLN"
+    | "PYG"
+    | "QAR"
+    | "RON"
+    | "RSD"
+    | "RUB"
+    | "RWF"
+    | "SAR"
+    | "SBD"
+    | "SCR"
+    | "SDG"
+    | "SEK"
+    | "SGD"
+    | "SHP"
+    | "SLE"
+    | "SOS"
+    | "SRD"
+    | "SSP"
+    | "STN"
+    | "SVC"
+    | "SYP"
+    | "SZL"
+    | "THB"
+    | "TJS"
+    | "TMT"
+    | "TND"
+    | "TOP"
+    | "TRY"
+    | "TTD"
+    | "TWD"
+    | "TZS"
+    | "UAH"
+    | "UGX"
+    | "USD"
+    | "UYU"
+    | "UZS"
+    | "VED"
+    | "VES"
+    | "VND"
+    | "VUV"
+    | "WST"
+    | "XAF"
+    | "XCD"
+    | "XCG"
+    | "XOF"
+    | "XPF"
+    | "YER"
+    | "ZAR"
+    | "ZMW"
+    | "ZWG";
 
 /**
  * An amount and what it is denominated in, kept together.

package/src/project.ts

@@ -8,16 +8,15 @@ import type {
 } from "./config.ts";
 import type {
     BaseCatalog,
-    MessageOverlayKeys,
     OverrideCatalog,
     ValidateOverrideCatalog,
 } from "./i18n/define.ts";
-import type { SiteIcon, SiteVerification, ThemeColor } from "./meta/index.ts";
+import type { ImageAsset } from "./image.ts";
+import type { SiteVerification, ThemeColor } from "./meta/index.ts";
 import type {
-    RouteOverlayKeys,
-    RouteOverlayShape,
-    RouteOverrideMap,
+    RouteOverrides,
     RouteRegistry,
+    ValidateOverrideSlugDepth,
 } from "./routes/define.ts";
 import type { NoExcessKeys, StringKeys } from "./types.ts";
 import type { HttpsUrl, ValidSiteUrl } from "./url.ts";
@@ -60,7 +59,7 @@ export interface ProjectInput<L extends string, Routes> {
      * from the home page, so a per-page icon would change the browser tab and
      * nothing else.
      */
-    readonly icon: SiteIcon;
+    readonly icon: ImageAsset;
     /**
      * Ownership tokens from Search Console, Bing Webmaster Tools and the like.
      *
@@ -131,7 +130,7 @@ export interface ProjectInput<L extends string, Routes> {
      */
     readonly overrideMessages: OverrideCatalog<L>;
     /** Slug retranslations and page on/off switches. See `overrideMessages`. */
-    readonly overrideRoutes: RouteOverrideMap<L, Routes>;
+    readonly overrideRoutes: RouteOverrides<Routes, L>;
 }
 
 /**
@@ -148,67 +147,88 @@ export interface ProjectInput<L extends string, Routes> {
  *  - unknown top-level fields are rejected, so a typo cannot sit there unread;
  *  - locales named anywhere must be ones the site ships and this project enabled.
  */
+/** Everything a project file must satisfy; see `defineSite`. */
+export type ProjectChecks<
+    L extends string,
+    Catalog,
+    Routes,
+    T extends ProjectInput<L, Routes>,
+> = NoExcessKeys<T, keyof ProjectInput<L, Routes>> & {
+    readonly url: ValidSiteUrl<T["url"]>;
+    readonly overrideRouting?: {
+        readonly defaultLocale?: T["enabledLocales"][number];
+        // Against `enabledLocales` rather than the site's list: a
+        // segment spelled for a language this deployment does not
+        // publish is a word that appears in no URL it builds. Mapped
+        // over the keys written, for the reason `overrideLocaleMeta`
+        // below is.
+        readonly pageSegmentByLocale?: {
+            readonly [K in StringKeys<
+                NonNullable<T["overrideRouting"]>["pageSegmentByLocale"]
+            >]: K extends T["enabledLocales"][number]
+                ? string
+                : LocaleNotEnabled<K>;
+        };
+    };
+    // Two separate checks on the same field: the keys must be messages
+    // the default catalog declares, and the locales inside each must be
+    // ones this project publishes. Copy written for a locale left out of
+    // `enabledLocales` is never built, so it is always a mistake — a
+    // locale removed from the list, or a project copied from another.
+    readonly overrideMessages: NoExcessKeys<
+        T["overrideMessages"],
+        StringKeys<Catalog>
+    > & {
+        readonly [K in StringKeys<T["overrideMessages"]>]: {
+            readonly [L in StringKeys<
+                T["overrideMessages"][K]
+            >]: L extends T["enabledLocales"][number]
+                ? T["overrideMessages"][K][L]
+                : LocaleNotEnabled<L>;
+        };
+    };
+    readonly overrideRoutes: NoExcessKeys<
+        T["overrideRoutes"],
+        StringKeys<Routes>
+    >;
+    // Nested, so that `dir` is rejected inside each locale's entry.
+    // Declaring the field as `Pick<LocaleMeta, "label">` is not enough:
+    // `T` is *inferred* from the literal, so a stray `dir` just becomes
+    // part of `T` and there is no fresh object for excess-property
+    // checking to fire on.
+    readonly overrideLocaleMeta?: {
+        readonly [K in StringKeys<
+            T["overrideLocaleMeta"]
+        >]: K extends T["enabledLocales"][number]
+            ? NoExcessKeys<T["overrideLocaleMeta"][K], keyof LocaleMetaOverride>
+            : LocaleNotEnabled<K>;
+    };
+};
+
+/** The same checks that map the whole override objects, in parameter position. */
+export type ProjectOverrideChecks<
+    L extends string,
+    Catalog,
+    Routes,
+    T extends ProjectInput<L, Routes>,
+> = {
+    readonly overrideMessages: ValidateOverrideCatalog<
+        T["overrideMessages"],
+        Catalog,
+        L
+    >;
+    readonly overrideRoutes: ValidateOverrideSlugDepth<
+        Routes,
+        T["overrideRoutes"]
+    >;
+};
+
 export function defineProject<
     const C extends SiteConfigShape,
     const Catalog extends BaseCatalog<LocalesOf<C>>,
     const Routes extends RouteRegistry<LocalesOf<C>>,
     const T extends ProjectInput<LocalesOf<C>, Routes> &
-        NoExcessKeys<T, keyof ProjectInput<LocalesOf<C>, Routes>> & {
-            readonly url: ValidSiteUrl<T["url"]>;
-            readonly overrideRouting?: {
-                readonly defaultLocale?: T["enabledLocales"][number];
-                // Against `enabledLocales` rather than the site's list: a
-                // segment spelled for a language this deployment does not
-                // publish is a word that appears in no URL it builds. Mapped
-                // over the keys written, for the reason `overrideLocaleMeta`
-                // below is.
-                readonly pageSegmentByLocale?: {
-                    readonly [K in StringKeys<
-                        NonNullable<T["overrideRouting"]>["pageSegmentByLocale"]
-                    >]: K extends T["enabledLocales"][number]
-                        ? string
-                        : LocaleNotEnabled<K>;
-                };
-            };
-            // Two separate checks on the same field: the keys must be messages
-            // the default catalog declares, and the locales inside each must be
-            // ones this project publishes. Copy written for a locale left out of
-            // `enabledLocales` is never built, so it is always a mistake — a
-            // locale removed from the list, or a project copied from another.
-            readonly overrideMessages: MessageOverlayKeys<
-                Catalog,
-                T["overrideMessages"]
-            > & {
-                readonly [K in StringKeys<T["overrideMessages"]>]: {
-                    readonly [L in StringKeys<
-                        T["overrideMessages"][K]
-                    >]: L extends T["enabledLocales"][number]
-                        ? T["overrideMessages"][K][L]
-                        : LocaleNotEnabled<L>;
-                };
-            };
-            // Shared with `defineRouteOverrides` rather than restated — see
-            // `RouteOverlayKeys` for why the two must not drift.
-            readonly overrideRoutes: RouteOverlayKeys<
-                Routes,
-                T["overrideRoutes"]
-            >;
-            // Nested, so that `dir` is rejected inside each locale's entry.
-            // Declaring the field as `Pick<LocaleMeta, "label">` is not enough:
-            // `T` is *inferred* from the literal, so a stray `dir` just becomes
-            // part of `T` and there is no fresh object for excess-property
-            // checking to fire on.
-            readonly overrideLocaleMeta?: {
-                readonly [K in StringKeys<
-                    T["overrideLocaleMeta"]
-                >]: K extends T["enabledLocales"][number]
-                    ? NoExcessKeys<
-                          T["overrideLocaleMeta"][K],
-                          keyof LocaleMetaOverride
-                      >
-                    : LocaleNotEnabled<K>;
-            };
-        },
+        ProjectChecks<LocalesOf<C>, Catalog, Routes, T>,
 >(
     // The first three are read for their types: they are how the locale union,
     // the message keys and the route ids are inferred without type arguments.
@@ -220,16 +240,7 @@ export function defineProject<
     // type in a constraint makes one unrelated mistake fail the argument
     // outright — TypeScript then reports at this call instead of on the line
     // that is wrong.
-    project: T & {
-        readonly overrideMessages: ValidateOverrideCatalog<
-            T["overrideMessages"],
-            Catalog,
-            LocalesOf<C>
-        >;
-        // The same alias `defineRouteOverrides` uses, so writing the overlay
-        // inline is never the weaker option.
-        readonly overrideRoutes: RouteOverlayShape<Routes, T["overrideRoutes"]>;
-    }
+    project: T & ProjectOverrideChecks<LocalesOf<C>, Catalog, Routes, T>
 ): T {
     // Checked at runtime as well as in the type, because the type is not always
     // what fails first. An Astro config is *evaluated* before `astro check`

package/src/routes/define.ts

@@ -1,5 +1,5 @@
 import type { LocalesOf, SiteConfigShape } from "../config.ts";
-import type { IsNever, IsoDate, NoExcessKeys, StringKeys } from "../types.ts";
+import type { IsNever, IsoDate, StringKeys } from "../types.ts";
 
 export type ChangeFreq =
     | "always"
@@ -92,7 +92,7 @@ interface SlugDepthMismatch<Id extends string, L extends string> {
  * here: in parameter position one bad slug widens `T` and every *other* route
  * then reports as malformed.
  */
-type ValidateSlugDepth<T> = {
+export type ValidateSlugDepth<T> = {
     readonly [K in StringKeys<T>]: {
         // Every key of the route is carried through unchanged, and only
         // `slugByLocale` is rewritten. Mapping the whole shape rather than
@@ -149,8 +149,12 @@ export interface RouteOverride<L extends string> {
     readonly sitemap?: RouteSitemap;
 }
 
-export type RouteOverrideMap<L extends string, Base> = Readonly<
-    Partial<Record<StringKeys<Base>, RouteOverride<L>>>
+/**
+ * One project's route overrides, for an overlay kept in its own file:
+ * `{ … } as const satisfies RouteOverrides<typeof defaultRoutes, EnabledLocale>`.
+ */
+export type RouteOverrides<Routes, L extends string> = Readonly<
+    Partial<Record<StringKeys<Routes>, RouteOverride<L>>>
 >;
 
 /** The slug a registry declares for route `K`, if it declares one. */
@@ -253,46 +257,6 @@ export type ValidateOverrideSlugDepth<Base, T> = {
     };
 };
 
-/**
- * Everything a route overlay must satisfy — and the only place it is stated.
- *
- * Two entry points accept an overlay: `defineRouteOverrides`, for one written in
- * its own file, and `defineProject`, for one written inline. They must check it
- * identically, or whichever has the extra check quietly becomes the safer place
- * to write overrides. That is not hypothetical: the depth rule below lived in
- * `defineRouteOverrides` alone for a while, and the inline form was weaker for
- * it with nothing to say so.
- *
- * **Add new overlay checks here, never at a call site.** Both entry points name
- * these two aliases, so anything added reaches both.
- *
- * Split in two because the positions are not interchangeable. Excess keys belong
- * in the *constraint*, where a wrong id reports on that key. The depth rule
- * belongs in the *parameter*: it maps the whole object, and a whole-object
- * mapped type in constraint position makes one unrelated mistake fail the
- * argument outright, moving the error off the offending line.
- */
-export type RouteOverlayKeys<Base, T> = NoExcessKeys<T, StringKeys<Base>>;
-
-/** @see {@link RouteOverlayKeys} — the parameter-position half. */
-export type RouteOverlayShape<Base, T> = ValidateOverrideSlugDepth<Base, T>;
-
-/**
- * Declares a project's route overlay: retranslated slugs and on/off switches.
- *
- * Enforced at compile time: unknown route ids are rejected, a slug override
- * cannot invent a locale the site does not ship, and no override may leave a
- * route sitting at different depths in different languages.
- */
-export function defineRouteOverrides<
-    const C extends SiteConfigShape,
-    const Base extends RouteRegistry<LocalesOf<C>>,
-    const T extends RouteOverrideMap<LocalesOf<C>, Base> &
-        RouteOverlayKeys<Base, T>,
->(_config: C, _base: Base, overrides: T & RouteOverlayShape<Base, T>): T {
-    return overrides;
-}
-
 /** The minimum `EnabledRouteIdFor` needs to know about a registry. */
 export type EnabledFlagSource = Readonly<
     Record<string, { readonly enabled: boolean }>

package/src/routes/resolve.ts

@@ -238,7 +238,7 @@ export function listRouteEntries<L extends string, Id extends string>(
         // until the day someone turns the page on.
         //
         // A backstop rather than the main check: `defineRoutes` and
-        // `defineRouteOverrides` both reject this at compile time. What survives
+        // `defineProject` both reject this at compile time. What survives
         // to here is a slug that was typed as plain `string` — computed, or read
         // from an env var — where the literal comparison passed vacuously.
         const depth = segmentCount(route.slug);

package/src/site/api.ts

@@ -11,11 +11,9 @@ import type {
     ValidateRedirectTargets,
 } from "../redirects.ts";
 import type { RobotsGroup } from "../robots.ts";
-import type { RouteEntry } from "../routes/resolve.ts";
 import type { Sitemap } from "../sitemap.ts";
 import type { HttpsUrl, UrlPath } from "../url.ts";
 import type {
-    Alternate,
     Crumb,
     LinkOptions,
     LocaleLink,
@@ -209,11 +207,8 @@ export interface Site<
      */
     fileUrl(path: PublicFilePath): HttpsUrl;
 
-    /** One entry per published locale, for `hreflang` tags. */
-    alternatesFor(id: RouteId, options?: LinkOptions): readonly Alternate<L>[];
-
     /**
-     * The same, ready to render as a language switcher: each locale's own label
+     * One link per published locale, ready to render as a language switcher: each locale's own label
      * and writing direction, and which one the reader is on.
      *
      * Switching language keeps the page — `about` stays `about`, so `/about-us`
@@ -257,15 +252,10 @@ export interface Site<
      */
     readonly orphanSegments: readonly string[];
 
-    /** Every (route, locale) pair this build emits. Throws on colliding URLs. */
-    readonly entries: readonly RouteEntry<L, RouteId>[];
-
     /**
-     * Every page to generate, as `{ params, props }` for a catch-all route.
-     *
-     * `param` is the name of the rest parameter in the router's filename, e.g.
-     * `"route"` for `[...route].astro`. The root path is emitted as `undefined`,
-     * which is what such routers expect.
+     * Every page to generate, for `src/pages/[...route].astro`:
+     * `export const getStaticPaths = site.getStaticPaths`. The root path is
+     * emitted as `undefined`, which is what a rest parameter expects.
      *
      * When every locale is prefixed nothing owns `/`, and no page is generated
      * for it: `redirects()` claims it with a 301 to the default locale's root
@@ -275,7 +265,7 @@ export interface Site<
      *
      * Returns a fresh mutable array, because SSG routers typically demand one.
      */
-    staticPaths(param: string): StaticPath<L, RouteId>[];
+    getStaticPaths(): StaticPath<L, RouteId>[];
 
     /**
      * The rendered sitemap: `entry` is the file to submit, `files` is everything
@@ -291,14 +281,7 @@ export interface Site<
      */
     robots(groups?: readonly RobotsGroup[]): GeneratedFile;
 
-    /**
-     * Where this site's `llms.txt` is published, or `undefined` if the config
-     * turned it off.
-     *
-     * Public because it is a promise made in two places at once: every page's
-     * head links to this URL, and something has to write a file there. It is
-     * what `siteRoutes` checks so the two cannot disagree.
-     */
+    /** Where this site's `llms.txt` is published, or `undefined` when the config turned it off. */
     readonly llmsUrl: HttpsUrl | undefined;
 
     /**
@@ -364,18 +347,9 @@ export interface Site<
 }
 
 /** The routes a given site builds, read back off the site's own type. */
-export type RouteIdOf<S> =
+type RouteIdOf<S> =
     S extends Site<infer _L, infer _Catalog, infer Id> ? Id : never;
 
-/**
- * `T` when this site builds route `Id`, `never` when it does not.
- *
- * For a value that only makes sense alongside an optional page — a field that
- * should vanish rather than sit there unread once the page is switched off.
- */
-export type WhenEnabled<S, Id extends string, T> =
-    Id extends RouteIdOf<S> ? T : never;
-
 /**
  * A `T` for every route this site builds — and only those.
  *