@escape-game-over/atlas 0.1.88 → 0.1.91

package/package.json

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

package/src/i18n/define.ts

@@ -1,6 +1,7 @@
 import type { LocalesOf, SiteConfigShape } from "../config.ts";
 import type { IsNever, NoExcessKeys, StringKeys } from "../types.ts";
 import type {
+    AddedMessageExists,
     EntryTokens,
     MismatchedLocales,
     OverridePlaceholderMismatch,
@@ -137,10 +138,32 @@ 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. */
+/**
+ * What `defineProject` checks an `addMessages` against: each key new to the
+ * base catalog, written for exactly the locales the project publishes, with
+ * the same `{placeholders}` and `[marks]` in each.
+ *
+ * New only, because a key the base already has is copy every project shares,
+ * and rewording it is what `overrideMessages` is for — with its own check that
+ * the placeholders survive. An addition shadowing a base key would get round
+ * that check, and two fields could then say different things about one key.
+ */
+export type ValidateAdditions<T, Base, Published extends string> = {
+    [K in keyof T]: K extends keyof Base
+        ? AddedMessageExists<K & string>
+        : NoExcessKeys<T[K], Published> &
+              Readonly<Record<Published, string>> &
+              SelfConsistent<T[K], K>;
+};
+
+/**
+ * Merges a project's override catalog over the base catalog, locale by locale,
+ * then adds the project's own messages.
+ */
 export function mergeCatalog<L extends string>(
     base: BaseCatalog<L>,
-    overrides: OverrideCatalog<L>
+    overrides: OverrideCatalog<L>,
+    additions: OverrideCatalog<L> = {}
 ): Readonly<Record<string, Readonly<Record<L, string>>>> {
     const merged: Record<string, Record<string, string>> = {};
     for (const [key, entry] of Object.entries(base)) {
@@ -154,5 +177,15 @@ export function mergeCatalog<L extends string>(
             if (typeof text === "string") target[locale] = text;
         }
     }
+    for (const [key, entry] of Object.entries(additions)) {
+        // Unreachable via the typed API, which refuses a base key here; an
+        // Astro config is evaluated before the type check, so say it plainly.
+        if (key in merged) {
+            throw new Error(
+                `addMessages: "${key}" is already in the default catalog. Reword it in overrideMessages instead.`
+            );
+        }
+        merged[key] = { ...entry } as Record<string, string>;
+    }
     return merged as Readonly<Record<string, Readonly<Record<L, string>>>>;
 }

package/src/i18n/placeholders.ts

@@ -112,6 +112,11 @@ export interface PlaceholderMismatch<Key extends string, L extends string> {
     readonly __PLACEHOLDER_MISMATCH__: `Message "${Key}" uses different {placeholders} or [marks] in locale "${L}" than in its other locales`;
 }
 
+/** Editor-facing error when a project adds a message the base already has. */
+export interface AddedMessageExists<Key extends string> {
+    readonly __ADDED_MESSAGE_EXISTS__: `Message "${Key}" is already in the default catalog: reword it in overrideMessages instead of adding it`;
+}
+
 /** Editor-facing error when an override drops or invents one. */
 export interface OverridePlaceholderMismatch<
     Key extends string,

package/src/index.ts

@@ -230,6 +230,7 @@ export {
     tierRange,
 } from "./money.ts";
 export type {
+    AddedCatalog,
     DefinedProject,
     ProjectInput,
     ProjectRouteId,
@@ -262,8 +263,10 @@ export {
     enableRoutes,
     type FamilyMember,
     type FamilyMemberInput,
+    type FamilyMemberSlugs,
     type FamilyOptions,
     familyGuard,
+    familyMemberSlugs,
     type RouteIdsOf,
 } from "./routes/family.ts";
 export type { RouteEntry } from "./routes/resolve.ts";

package/src/project.ts

@@ -10,6 +10,7 @@ import type { Fonts } from "./fonts.ts";
 import type {
     BaseCatalog,
     OverrideCatalog,
+    ValidateAdditions,
     ValidateOverrideCatalog,
 } from "./i18n/define.ts";
 import type { ImageAsset } from "./image.ts";
@@ -139,6 +140,20 @@ export interface ProjectInput<L extends string, Routes> {
      * than the argument.
      */
     readonly overrideMessages: OverrideCatalog<L>;
+    /**
+     * Copy only this project has: keys the default catalog does not declare,
+     * each written for every locale the project publishes and no others.
+     *
+     * For what one deployment says and no other does — a venue's own FAQ, a
+     * house rule — so it goes through `translate` and `rich` like any message,
+     * marks and placeholders included, without the shared catalog carrying it
+     * in languages the venue never publishes. A key the default catalog
+     * already has is refused: reword it in `overrideMessages`.
+     *
+     * Optional, unlike `overrideMessages`: nothing downstream is computed from
+     * it except the catalog's keys, which an absent field leaves as they are.
+     */
+    readonly addMessages?: OverrideCatalog<L>;
     /** Slug retranslations and page on/off switches. See `overrideMessages`. */
     readonly overrideRoutes: RouteOverrides<Routes, L>;
 }
@@ -289,7 +304,20 @@ export type ProjectOverrideChecks<
         Routes,
         T["overrideRoutes"]
     >;
-};
+} & (T extends { readonly addMessages: infer A }
+    ? {
+          readonly addMessages: ValidateAdditions<
+              A,
+              Catalog,
+              T["enabledLocales"][number]
+          >;
+      }
+    : unknown);
+
+/** A project's own messages, as a catalog: none when it adds none. */
+export type AddedCatalog<P> = P extends { readonly addMessages: infer A }
+    ? A
+    : Record<never, never>;
 
 export function defineProject<
     const C extends SiteConfigShape,
@@ -324,5 +352,22 @@ export function defineProject<
             );
         }
     }
+    // The same two rules the type states, for the same reason: the config is
+    // evaluated before the type check runs.
+    for (const [key, entry] of Object.entries(project.addMessages ?? {})) {
+        if (key in _messages) {
+            throw new Error(
+                `Project "${project.siteName}": addMessages "${key}" is already in the default catalog. Reword it in overrideMessages instead.`
+            );
+        }
+        const missing = project.enabledLocales.filter(
+            (locale) => typeof entry[locale] !== "string"
+        );
+        if (missing.length > 0) {
+            throw new Error(
+                `Project "${project.siteName}": addMessages "${key}" has no ${missing.join(", ")}. A message a project adds is written for every locale it publishes.`
+            );
+        }
+    }
     return project;
 }

package/src/routes/define.ts

@@ -204,7 +204,12 @@ type InheritedDepthMismatch<
 > = K extends keyof Base
     ? Base[K] extends { readonly slugByLocale?: infer M }
         ? {
-              [L in keyof M]: L extends OverriddenLocales<T, K>
+              // `-?`: the translations are a `Partial`, and a mapped type keeps
+              // its `?`, so every entry would read `never | undefined` and the
+              // lookup below `undefined` — not `never` — failing every `slug`
+              // override of a route whose translations are optional, family
+              // members among them.
+              [L in keyof M]-?: L extends OverriddenLocales<T, K>
                   ? never
                   : M[L] extends infer V extends string
                     ? SegmentCount<V> extends Depth

package/src/routes/family.ts

@@ -75,6 +75,113 @@ export interface FamilyOptions<L extends string> {
     readonly sitemap?: RouteSitemap;
 }
 
+/** Per-locale translations, keyed by locale. */
+type ByLocale = Readonly<Record<string, string>>;
+
+/** One locale's path: its translated halves where it has them, else the defaults. */
+type JoinedSlug<
+    Prefix extends string,
+    PrefixBy extends ByLocale,
+    Segment extends string,
+    SegmentBy extends ByLocale,
+    K,
+> = `${K extends keyof PrefixBy ? PrefixBy[K] : Prefix}/${K extends keyof SegmentBy
+    ? SegmentBy[K]
+    : Segment}`;
+
+/** What {@link familyMemberSlugs} returns: literal paths, so depth checks still apply. */
+export type FamilyMemberSlugs<
+    Prefix extends string,
+    Segment extends string,
+    PrefixBy extends ByLocale = Record<never, never>,
+    SegmentBy extends ByLocale = Record<never, never>,
+> = { readonly slug: `${Prefix}/${Segment}` } & ([
+    keyof PrefixBy | keyof SegmentBy,
+] extends [never]
+    ? unknown
+    : {
+          readonly slugByLocale: {
+              readonly [K in keyof PrefixBy | keyof SegmentBy]: JoinedSlug<
+                  Prefix,
+                  PrefixBy,
+                  Segment,
+                  SegmentBy,
+                  K
+              >;
+          };
+      });
+
+/**
+ * A family member's paths, in every locale, as {@link routeFamily} composes
+ * them — for a project that gives one member a segment of its own.
+ *
+ * ```ts
+ * overrideRoutes: {
+ *     "rooms-illuminati": {
+ *         enabled: true,
+ *         ...familyMemberSlugs("rooms", "the-da-vinci-code", {
+ *             prefixByLocale: ROOM_PREFIX_BY_LOCALE,
+ *         }),
+ *     },
+ * }
+ * ```
+ *
+ * Overriding only `slug` would move the default locale and leave every
+ * translated path at the family's id, at the same depth, so nothing would
+ * catch it. This restates them all from the same join the family used. Pass
+ * the family's `prefixByLocale`, so the member stays under its siblings in
+ * every locale.
+ */
+export function familyMemberSlugs<
+    const Prefix extends string,
+    const Segment extends string,
+    const PrefixBy extends ByLocale = Record<never, never>,
+    const SegmentBy extends ByLocale = Record<never, never>,
+>(
+    prefix: Prefix,
+    segment: Segment,
+    translations: {
+        readonly prefixByLocale?: PrefixBy;
+        readonly segmentByLocale?: SegmentBy;
+    } = {}
+): FamilyMemberSlugs<Prefix, Segment, PrefixBy, SegmentBy> {
+    const slugByLocale = joinByLocale(
+        prefix,
+        segment,
+        translations.prefixByLocale,
+        translations.segmentByLocale
+    );
+    return {
+        slug: `${prefix}/${segment}`,
+        ...(slugByLocale === undefined ? {} : { slugByLocale }),
+    } as never;
+}
+
+/**
+ * The translated paths of one member, or `undefined` where neither half is
+ * translated. A locale gets one when either half is; the untranslated half
+ * falls back to the default, so every locale sits at the same depth by
+ * construction.
+ */
+function joinByLocale(
+    prefix: string,
+    segment: string,
+    prefixByLocale: Readonly<Partial<Record<string, string>>> | undefined,
+    segmentByLocale: Readonly<Partial<Record<string, string>>> | undefined
+): Record<string, string> | undefined {
+    const locales = new Set([
+        ...Object.keys(prefixByLocale ?? {}),
+        ...Object.keys(segmentByLocale ?? {}),
+    ]);
+    if (locales.size === 0) return undefined;
+    const slugByLocale: Record<string, string> = {};
+    for (const locale of locales) {
+        slugByLocale[locale] =
+            `${prefixByLocale?.[locale] ?? prefix}/${segmentByLocale?.[locale] ?? segment}`;
+    }
+    return slugByLocale;
+}
+
 /**
  * Expands a family into ordinary route entries, ready to spread into
  * `defineRoutes`.
@@ -127,26 +234,19 @@ export function routeFamily<
         const segmentByLocale =
             typeof member === "string" ? undefined : member.segmentByLocale;
 
-        // A locale gets a translated slug when either half is translated; the
-        // untranslated half falls back to what the default slug uses, so the
-        // number of segments is the same in every locale by construction.
-        const locales = new Set([
-            ...Object.keys(options?.prefixByLocale ?? {}),
-            ...Object.keys(segmentByLocale ?? {}),
-        ]);
-        const slugByLocale: Record<string, string> = {};
-        for (const locale of locales) {
-            const localePrefix =
-                options?.prefixByLocale?.[locale as LocalesOf<C>] ?? prefix;
-            const localeSegment =
-                segmentByLocale?.[locale as LocalesOf<C>] ?? id;
-            slugByLocale[locale] = `${localePrefix}/${localeSegment}`;
-        }
+        // The same join `familyMemberSlugs` gives a project, so a member it
+        // moves sits exactly where the family would have put it.
+        const slugByLocale = joinByLocale(
+            prefix,
+            id,
+            options?.prefixByLocale,
+            segmentByLocale
+        );
 
         routes[`${prefix.replaceAll("/", "-")}-${id}`] = {
             slug: `${prefix}/${id}`,
             enabled: options?.enabled ?? true,
-            ...(locales.size > 0
+            ...(slugByLocale !== undefined
                 ? {
                       slugByLocale: slugByLocale as Readonly<
                           Partial<Record<LocalesOf<C>, string>>

package/src/site/create.ts

@@ -22,7 +22,7 @@ import {
     buildNotFoundMeta,
     resolveShareImage,
 } from "../meta/index.ts";
-import type { ProjectInput, ProjectRouteId } from "../project.ts";
+import type { AddedCatalog, ProjectInput, ProjectRouteId } from "../project.ts";
 import {
     buildRedirects,
     type RedirectRule,
@@ -102,7 +102,7 @@ export function createSite<
     project: P & { readonly enabledLocales: readonly Published[] }
 ): Site<
     Published,
-    Catalog,
+    Catalog & AddedCatalog<P>,
     ProjectRouteId<Routes, P>,
     SectionPrefixOf<Routes, P["overrideRoutes"]>,
     OrphanSectionPrefixOf<Routes, P["overrideRoutes"]>
@@ -179,8 +179,15 @@ export function createSite<
     const llmsUrl: HttpsUrl | undefined =
         config_.llms === false ? undefined : joinUrl(siteUrl, `/${llmsName}`);
 
-    const catalog = mergeCatalog<L>(messages, project.overrideMessages);
-    const translateFactory = createTranslateFactory<Catalog, L>();
+    // The project's own messages join the catalog here, typed and resolved like
+    // any other: `Full` is what every reader below knows the keys by.
+    type Full = Catalog & AddedCatalog<P>;
+    const catalog = mergeCatalog<L>(
+        messages,
+        project.overrideMessages,
+        project.addMessages
+    );
+    const translateFactory = createTranslateFactory<Full, L>();
 
     const resolved = mergeRoutes<L, Routes>(routes, project.overrideRoutes);
 
@@ -831,14 +838,14 @@ export function createSite<
 
         translate: (locale) => translateFactory(catalog, locale),
         rich: (locale) =>
-            createRichText<Catalog, L, RouteId>({
+            createRichText<Full, L, RouteId>({
                 catalog,
                 locale,
                 link: richLink(locale),
                 origin: siteUrl,
             }),
         plain: (locale) =>
-            createPlainText<Catalog, L>({
+            createPlainText<Full, L>({
                 catalog,
                 locale,
                 link: richLink(locale),