@escape-game-over/atlas 0.1.1

package/src/i18n/define.ts

@@ -0,0 +1,217 @@
+import type { LocalesOf, SiteConfigShape } from "../config.ts";
+import type { IsNever, NoExcessKeys, StringKeys } from "../types.ts";
+import type {
+    EntryPlaceholders,
+    MismatchedLocales,
+    OverridePlaceholderMismatch,
+    PlaceholderMismatch,
+} from "./placeholders.ts";
+
+/**
+ * `true` when `Catalog` declares every key in `Required`; otherwise an object
+ * type naming the ones it does not.
+ *
+ * Annotate a `const … = true` with it. A missing message then fails at that
+ * declaration, and the error text lists exactly which keys are absent, rather
+ * than surfacing later as a page with no `<title>`:
+ *
+ * ```ts
+ * export const routeMessagesAreComplete: CatalogCovers<
+ *     typeof baseMessages,
+ *     `route.${RouteId}.${"nav" | "title"}`
+ * > = true;
+ * ```
+ *
+ * The pattern earns its keep over a plain `Required extends StringKeys<Catalog>`
+ * constraint, which reports only that the constraint was not satisfied and
+ * leaves you to work out which of the keys is missing.
+ *
+ * lib supplies the mechanism and never the key names: which messages a project
+ * considers mandatory is that project's convention to state.
+ */
+export type CatalogCovers<Catalog, Required extends string> =
+    IsNever<Exclude<Required, StringKeys<Catalog>>> extends true
+        ? true
+        : {
+              readonly __MISSING_MESSAGES__: Exclude<
+                  Required,
+                  StringKeys<Catalog>
+              >;
+          };
+
+/** A base message: every locale is mandatory. */
+export type BaseEntry<L extends string> = Readonly<Record<L, string>>;
+export type BaseCatalog<L extends string> = Readonly<
+    Record<string, BaseEntry<L>>
+>;
+
+/** A project override: any subset of locales for an existing key. */
+export type OverrideEntry<L extends string> = Readonly<
+    Partial<Record<L, string>>
+>;
+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, EntryPlaceholders<E>>,
+] extends [never]
+    ? unknown
+    : PlaceholderMismatch<
+          K & string,
+          MismatchedLocales<E, EntryPlaceholders<E>> & string
+      >;
+
+type ValidateBase<T> = { [K in keyof T]: SelfConsistent<T[K], K> };
+
+/**
+ * Rejects locale keys the site does not ship.
+ *
+ * `Record<L, string>` alone does not catch these: the entry type is inferred
+ * from the literal rather than checked against a fixed target, so an extra key
+ * structurally satisfies the constraint and would sit in the catalog unread.
+ */
+type NoExtraLocales<T, L extends string> = {
+    [K in keyof T]: NoExcessKeys<T[K], L>;
+};
+
+/**
+ * Declares the base copy.
+ *
+ * The config argument is what supplies the locale union — pass `site.config.ts`
+ * and the locales follow, with no type arguments to write.
+ *
+ * Enforced at compile time:
+ *  - every key defines every locale the site ships, and no others;
+ *  - every locale of a key uses exactly the same `{placeholders}`.
+ */
+export function defineMessages<
+    const C extends SiteConfigShape,
+    const T extends BaseCatalog<LocalesOf<C>>,
+>(
+    // Read for its type only: it is how `L` is inferred without a type argument.
+    _config: C,
+    catalog: T & ValidateBase<T> & NoExtraLocales<T, LocalesOf<C>>
+): T {
+    return catalog;
+}
+
+/**
+ * Everything a copy overlay must satisfy — and the only place it is stated.
+ *
+ * The mirror of `RouteOverlayKeys` / `RouteOverlayShape`, for the same reason:
+ * `defineMessageOverrides` and `defineProject` both accept an overlay, and a
+ * check added to one and not the other makes that one silently the safer place
+ * to write copy. Both name these, so a new rule reaches both.
+ *
+ * Excess keys go in the constraint, where a typo'd message id reports on that
+ * key; the placeholder and locale rules go in the parameter, because they map
+ * the whole object.
+ */
+export type MessageOverlayKeys<Base, T> = NoExcessKeys<T, StringKeys<Base>>;
+
+/** @see {@link MessageOverlayKeys} — the parameter-position half. */
+export type ValidateOverrideCatalog<
+    T,
+    Base,
+    L extends string,
+> = ValidateOverrides<T, Base> & NoExtraLocales<T, L>;
+
+type ValidateOverrides<T, Base> = {
+    [K in keyof T]: K extends keyof Base
+        ? [MismatchedLocales<T[K], EntryPlaceholders<Base[K]>>] extends [never]
+            ? unknown
+            : OverridePlaceholderMismatch<
+                  K & string,
+                  MismatchedLocales<T[K], EntryPlaceholders<Base[K]>> & string
+              >
+        : unknown;
+};
+
+/**
+ * Declares a project's copy overlay: any subset of keys, any subset of locales.
+ *
+ * Both the message ids and the locales are inferred from the base catalog you
+ * pass in, so overriding one locale of one string needs no type arguments.
+ *
+ * Enforced at compile time:
+ *  - the key must exist in the base catalog, so a typo is rejected rather than
+ *    silently becoming a string nothing reads;
+ *  - the replacement must use exactly the `{placeholders}` of the base message,
+ *    so every existing `t()` call site stays correct.
+ */
+export function defineMessageOverrides<
+    const C extends SiteConfigShape,
+    const Base extends BaseCatalog<LocalesOf<C>>,
+    const T extends OverrideCatalog<LocalesOf<C>> & MessageOverlayKeys<Base, T>,
+>(
+    // Read for its type only, and taken first like every other definer here.
+    // It supplies the locale universe directly rather than having it inferred
+    // from the catalog's entries: `LocalesOfCatalog` reads the locales actually
+    // *used*, which is the same union for a well-formed catalog and a narrower
+    // one for a partial or empty draft.
+    //
+    // Note what this does not do: `config` declares which locales the site has,
+    // not which ones a project publishes. Rejecting copy for a language a given
+    // deployment has switched off is `MessageOverrides`' job, because only the
+    // project knows its own `enabledLocales`.
+    _config: C,
+    _base: Base,
+    overrides: T & ValidateOverrides<T, Base> & NoExtraLocales<T, LocalesOf<C>>
+): T {
+    return overrides;
+}
+
+/**
+ * The shape of one project's copy overrides: known keys, published locales.
+ *
+ * For annotating the object itself, which is what puts the error on the line
+ * that is wrong:
+ *
+ * ```ts
+ * const overrides = {
+ *     "site.cta": { "en-US": "Book a room" },
+ * } satisfies MessageOverrides<typeof defaultMessages, EnabledLocale>;
+ *
+ * export const overrideMessages = defineMessageOverrides(
+ *     config,
+ *     defaultMessages,
+ *     overrides
+ * );
+ * ```
+ *
+ * The two halves do different jobs and both are needed. This type knows the
+ * project's locale set, so it rejects copy for a language that is never built —
+ * but it cannot compare an override's *text* with the default's, so it cannot
+ * see a dropped `{placeholder}`. `defineMessageOverrides` is the reverse: it
+ * reads both texts, and knows nothing about which locales this deployment
+ * publishes. Annotate with one, wrap in the other.
+ */
+export type MessageOverrides<Catalog, L extends string> = {
+    readonly [K in StringKeys<Catalog>]?: Readonly<Partial<Record<L, string>>>;
+};
+
+/** Merges a project's override catalog over the base catalog, locale by locale. */
+export function mergeCatalog<L extends string>(
+    base: BaseCatalog<L>,
+    overrides: OverrideCatalog<L>
+): Readonly<Record<string, Readonly<Record<L, string>>>> {
+    const merged: Record<string, Record<string, string>> = {};
+    for (const [key, entry] of Object.entries(base)) {
+        merged[key] = { ...entry };
+    }
+    for (const [key, entry] of Object.entries(overrides)) {
+        const target = merged[key];
+        // Unreachable via the typed API: override keys are constrained to base keys.
+        if (target === undefined) continue;
+        for (const [locale, text] of Object.entries(entry)) {
+            if (typeof text === "string") target[locale] = text;
+        }
+    }
+    return merged as Readonly<Record<string, Readonly<Record<L, string>>>>;
+}

package/src/i18n/placeholders.ts

@@ -0,0 +1,94 @@
+/**
+ * Placeholder analysis over message templates. Pure types — no locale or copy
+ * data of any kind lives in `lib/`.
+ */
+
+import type { Digit, Letter, StringKeys } from "../types.ts";
+
+/**
+ * One character a placeholder name may be spelled with.
+ *
+ * **This is the type-level half of `PLACEHOLDER` in `translate.ts`, and the two
+ * have to agree.** They are a hundred lines apart in different files and each
+ * reads correct alone, which is how they came to differ: this side used to
+ * accept anything between braces while the regex substituted only these, so a
+ * message written `"Use {b c} here"` compiled into a *required* `t()` parameter
+ * named `"b c"` that the runtime never consumed — the call site was forced to
+ * pass a value and the brace still shipped in the markup. The whole point of
+ * this machinery is that a literal brace cannot reach a page.
+ *
+ * `Letter` is uppercase only, so its lowercase twin is spelled out via
+ * `Lowercase`.
+ */
+type NameChar = Letter | Lowercase<Letter> | Digit | "_";
+
+/** Whether every character of `S` may appear in a placeholder name. */
+type IsName<S extends string> = S extends `${infer Head}${infer Tail}`
+    ? Head extends NameChar
+        ? Tail extends ""
+            ? true
+            : IsName<Tail>
+        : false
+    : false;
+
+/**
+ * Extracts `{placeholder}` names from a message template as a union of literals.
+ *
+ * `Placeholders<'Hi {name}, {n} new'>` -> `'name' | 'n'`
+ * `Placeholders<'Hello'>`              -> `never`
+ * `Placeholders<'Literal {{name}}'>`   -> `never` — the escape, not a name
+ * `Placeholders<string>`               -> `never`
+ *
+ * An escaped brace asks for nothing, which falls out of `IsName` rather than
+ * needing a case of its own: the candidate extracted from `{{name}}` is
+ * `"{name"`, and `{` is not a `NameChar`. The two halves agree by the same rule
+ * from opposite ends.
+ *
+ * What this cannot say is that a *malformed* brace is an error — `render` in
+ * `translate.ts` throws on `"{color: red}"`, and this only declines to ask for
+ * a parameter. That asymmetry is deliberate: the type's job is to get the
+ * call site's arguments right, and the parser's is to refuse copy nobody meant.
+ * Both fail the build, one at compile time and one the first time the message
+ * renders.
+ *
+ * Recursion is per character of the name rather than of the message, so it is
+ * bounded by how long a placeholder is spelled and not by how long the copy runs.
+ */
+export type Placeholders<S extends string> =
+    S extends `${string}{${infer Name}}${infer Rest}`
+        ? (IsName<Name> extends true ? Name : never) | Placeholders<Rest>
+        : never;
+
+/** The message strings present on an entry, as a union of string literals. */
+export type TextOf<E> = Extract<E[keyof E], string>;
+
+/** Every placeholder used by any locale of an entry. */
+export type EntryPlaceholders<E> = Placeholders<TextOf<E>>;
+
+/**
+ * The locales of `E` whose placeholder set differs from `Expected`.
+ *
+ * This is what turns a half-updated translation into a compile error instead of
+ * a literal `{name}` rendered on a production page.
+ */
+export type MismatchedLocales<E, Expected extends string> = {
+    [L in StringKeys<E>]: [
+        | Exclude<Expected, Placeholders<Extract<E[L], string>>>
+        | Exclude<Placeholders<Extract<E[L], string>>, Expected>,
+    ] extends [never]
+        ? never
+        : L;
+}[StringKeys<E>];
+
+/** Editor-facing error when placeholders drift between locales of one message. */
+export interface PlaceholderMismatch<Key extends string, L extends string> {
+    readonly __PLACEHOLDER_MISMATCH__: `Message "${Key}" uses different {placeholders} in locale "${L}" than in its other locales`;
+}
+
+/** Editor-facing error when an override drops or invents a placeholder. */
+export interface OverridePlaceholderMismatch<
+    Key extends string,
+    L extends string,
+> {
+    readonly __OVERRIDE_PLACEHOLDER_MISMATCH__: `Override of "${Key}" in locale "${L}" must use exactly the same {placeholders} as the base message`;
+}

package/src/i18n/translate.ts

@@ -0,0 +1,190 @@
+import type { StringKeys } from "../types.ts";
+import type { EntryPlaceholders } from "./placeholders.ts";
+
+/**
+ * What may be spelled between the braces — the pair of `NameChar` in
+ * `placeholders.ts`, which decides the same thing at the type level.
+ *
+ * Change one and change the other. They answer the same question from opposite
+ * ends, and when they disagreed the type demanded a parameter the runtime never
+ * consumed, so the call site filled it in and the brace shipped anyway. Kept as
+ * a character class rather than a hand-rolled check precisely so it still reads
+ * as the obvious mirror of the union over there.
+ */
+const NAME = /^[a-zA-Z0-9_]+$/;
+
+/**
+ * Splits a template into text and placeholders, and refuses anything else.
+ *
+ * A parser rather than one `replace` over `/\{(name)\}/g`, and the difference
+ * is what happens to a brace that is *not* a placeholder. The pattern simply
+ * did not match one, so `"CSS: {color: red}"` passed through as text — which
+ * looks like an escape hatch and is not one. Nothing declared that brace
+ * literal; it survived because it happened to contain a space. Rename the
+ * example to `{color}` and the same copy starts demanding a parameter.
+ *
+ * So the escape is explicit — `{{` and `}}`, as `format!` and `str.format` use
+ * — and anything else is an error naming the message and telling you to double
+ * the brace. Every brace in a template is now a decision someone made rather
+ * than a decision made for them by a character class.
+ *
+ * A lone `}` stays text. Only `{` opens anything, so there is nothing for an
+ * unmatched closer to be ambiguous about, and rejecting it would fail copy that
+ * is merely writing a bracket.
+ */
+function render(
+    template: string,
+    at: string,
+    value: (name: string, whole: string) => string
+): string {
+    let out = "";
+    let index = 0;
+
+    while (index < template.length) {
+        const char = template[index] as string;
+
+        if (char === "{" && template[index + 1] === "{") {
+            out += "{";
+            index += 2;
+        } else if (char === "}" && template[index + 1] === "}") {
+            out += "}";
+            index += 2;
+        } else if (char === "{") {
+            const close = template.indexOf("}", index + 1);
+            const name = close === -1 ? "" : template.slice(index + 1, close);
+            if (close === -1 || !NAME.test(name)) {
+                throw new Error(
+                    `${at} has a "{" that opens neither a placeholder nor an escape: ${describeBrace(template, index, close)}. A placeholder is {name} — letters, digits and underscores. To write a literal brace, double it: "{{".`
+                );
+            }
+            out += value(name, template.slice(index, close + 1));
+            index = close + 1;
+        } else {
+            out += char;
+            index += 1;
+        }
+    }
+    return out;
+}
+
+/** The offending brace, quoted, so the error points at something findable. */
+function describeBrace(template: string, open: number, close: number): string {
+    const end = close === -1 ? Math.min(open + 20, template.length) : close + 1;
+    return `"${template.slice(open, end)}"`;
+}
+
+export type MergedCatalog<L extends string> = Readonly<
+    Record<string, Readonly<Record<L, string>>>
+>;
+
+/** Untyped translation lookup, wrapped below in a key-aware signature. */
+export type RawTranslate = (
+    key: string,
+    params?: Readonly<Record<string, string>>
+) => string;
+
+export interface RawTranslateOptions<L extends string> {
+    readonly catalog: MergedCatalog<L>;
+    readonly locale: L;
+}
+
+/**
+ * Builds the runtime half of `t()`.
+ *
+ * Every failure here is a build-time failure by design: a static site should not
+ * ship a page with a literal `{name}` in the markup, so a missing message or an
+ * unfilled placeholder throws rather than degrading.
+ */
+export function createRawTranslate<L extends string>(
+    options: RawTranslateOptions<L>
+): RawTranslate {
+    const { catalog, locale } = options;
+
+    return (key, params) => {
+        const entry = catalog[key];
+        if (entry === undefined) {
+            throw new Error(`Unknown message key "${key}".`);
+        }
+        const template = entry[locale];
+        if (typeof template !== "string") {
+            throw new Error(
+                `Message "${key}" has no copy for locale "${locale}".`
+            );
+        }
+        return render(
+            template,
+            `Message "${key}" (${locale})`,
+            (name, whole) => {
+                // `Object.hasOwn` rather than reading the index straight, for the
+                // reason `familyGuard` uses it: `__proto__` is a legal name by the
+                // pattern above, so `params["__proto__"]` finds `Object.prototype`
+                // on any plain object, is not `undefined`, and would be substituted
+                // into the page as "[object Object]" instead of throwing.
+                const value =
+                    params !== undefined && Object.hasOwn(params, name)
+                        ? params[name]
+                        : undefined;
+                if (value === undefined) {
+                    throw new Error(
+                        `Message "${key}" (${locale}) is missing a value for "${whole}".`
+                    );
+                }
+                return value;
+            }
+        );
+    };
+}
+
+/** The `{placeholders}` message `K` needs from the caller. */
+export type MessageParamsOf<
+    Catalog,
+    K extends keyof Catalog,
+> = EntryPlaceholders<Catalog[K]>;
+
+/**
+ * `[key]` for a message with no placeholders, `[key, params]` otherwise.
+ *
+ * The tuple wrappers around `MessageParamsOf` stop the conditional from
+ * distributing, so a union of keys is answered once rather than per member.
+ */
+export type TranslateArgsOf<Catalog, K extends StringKeys<Catalog>> = [
+    MessageParamsOf<Catalog, K>,
+] extends [never]
+    ? [key: K]
+    : [key: K, params: Readonly<Record<MessageParamsOf<Catalog, K>, string>>];
+
+export type TranslateFor<Catalog> = <K extends StringKeys<Catalog>>(
+    ...args: TranslateArgsOf<Catalog, K>
+) => string;
+
+/**
+ * Builds the typed `t()` factory for one catalog type.
+ *
+ * Curried for the usual reason — `Catalog` must be supplied explicitly while the
+ * locale stays inferred, and TypeScript has no partial type-argument inference.
+ * `Catalog` is the *base* catalog's type (it carries the literal strings the
+ * placeholders are read from); the value passed in is the merged runtime
+ * catalog, which only needs to be indexable by key and locale.
+ */
+export function createTranslateFactory<Catalog, L extends string>() {
+    return function createTranslate(
+        catalog: MergedCatalog<L>,
+        locale: L
+    ): TranslateFor<Catalog> {
+        const raw = createRawTranslate({ catalog, locale });
+
+        function t<K extends StringKeys<Catalog>>(
+            ...args: TranslateArgsOf<Catalog, K>
+        ): string {
+            // The conditional tuple cannot be destructured directly; the runtime
+            // shape is always `[key]` or `[key, params]`.
+            const [key, params] = args as [
+                K,
+                Readonly<Record<string, string>>?,
+            ];
+            return raw(key, params);
+        }
+
+        return t;
+    };
+}

package/src/image.ts

@@ -0,0 +1,29 @@
+/**
+ * What a bundled image looks like to this library.
+ *
+ * Its own module because both the head tags and the structured data need it,
+ * and `meta/` already imports from `jsonld/` — leaving it in `meta/` would have
+ * the graph depend on the head to describe a picture.
+ */
+
+/**
+ * A bundled image asset.
+ *
+ * Structurally Astro's `ImageMetadata`, so an imported image assigns directly.
+ * `src` matters: a bundler rewrites imported images to hashed paths like
+ * `/_astro/hero.abc123.png`, which no convention can predict — it must be read
+ * off the asset, never derived.
+ */
+export interface ImageAsset {
+    readonly src: string;
+    /**
+     * Required, and always present on a bundler's own image metadata.
+     *
+     * Crawlers use these to lay out a preview without fetching the image first;
+     * omitting them is a slower, flakier preview. An external URL therefore has
+     * to state its own size rather than being passed as a bare string.
+     */
+    readonly width: number;
+    readonly height: number;
+    readonly format?: string;
+}