@escape-game-over/atlas 0.1.1

package/src/routes/define.ts

@@ -0,0 +1,412 @@
+import type { LocalesOf, SiteConfigShape } from "../config.ts";
+import type { IsNever, IsoDate, NoExcessKeys, StringKeys } from "../types.ts";
+
+export type ChangeFreq =
+    | "always"
+    | "hourly"
+    | "daily"
+    | "weekly"
+    | "monthly"
+    | "yearly"
+    | "never";
+
+export interface RouteSitemap {
+    readonly priority?: number;
+    readonly changefreq?: ChangeFreq;
+    /**
+     * The day this page's content last changed, as `"2026-03-01"`.
+     *
+     * Omitted means no `<lastmod>` at all, which is the honest default: the
+     * alternative is stamping the build date on every page, which says
+     * "everything changed" on every deploy until crawlers stop believing any of
+     * it. State it only where you know it, and only where it is true.
+     */
+    readonly lastmod?: IsoDate;
+    /** Set true to build the page but keep it out of the sitemap. */
+    readonly exclude?: boolean;
+}
+
+export interface RouteData<L extends string> {
+    /**
+     * The route's URL segment, used for every locale that does not translate it.
+     * No leading or trailing slashes. `""` is the locale root, and nested
+     * segments (`"services/consulting"`) are fine.
+     */
+    readonly slug: string;
+    /** Per-locale translations of `slug`. Locales left out fall back to it. */
+    readonly slugByLocale?: Readonly<Partial<Record<L, string>>>;
+    /** Whether this route is built. Required: a page's presence is never implied. */
+    readonly enabled: boolean;
+    /**
+     * How many pages this route's list runs to, counting the first.
+     *
+     * A property of the route rather than a set of routes, because a page of a
+     * list is not a page of the site: it has no copy of its own, it is not
+     * content a map should list, and Google exempts a sequence from needing
+     * distinct titles. Modelling each one as a route means four messages per
+     * page and a `llms.txt` that presents page 3 as an article.
+     *
+     * `1` or omitted is an ordinary route. Above that, lib emits
+     * `/news/page/2` … `/news/page/n` alongside `/news` — page one is always
+     * the bare slug, never `page/1`, so there is no duplicate to canonicalise
+     * away.
+     *
+     * Usually set per project rather than here: the count is posts divided by
+     * page size, and one venue has more posts than another.
+     */
+    readonly pages?: number;
+    readonly sitemap?: RouteSitemap;
+    // No share image here: an image and its alt text belong to the page being
+    // rendered, and pages can be generated dynamically, so they are passed to
+    // `metaFor` rather than declared in a static registry.
+}
+
+export type RouteRegistry<L extends string> = Readonly<
+    Record<string, RouteData<L>>
+>;
+
+/** A slug split on `/`, as a tuple, so its length can be compared. */
+type Segments<S extends string> = S extends `${infer Head}/${infer Rest}`
+    ? [Head, ...Segments<Rest>]
+    : [S];
+
+/** How deep a slug sits: `"services/consulting"` is 2, `"about"` and `""` are 1. */
+type SegmentCount<S extends string> = Segments<S>["length"];
+
+interface SlugDepthMismatch<Id extends string, L extends string> {
+    readonly __SLUG_DEPTH_MISMATCH__: `Route "${Id}" translates its slug for "${L}" to a different number of path segments; every locale of a route must sit at the same depth`;
+}
+
+/**
+ * Requires every translation of a slug to have the same number of segments.
+ *
+ * A route is one page, and its translations are the same page in another
+ * language — so `"services/consulting"` cannot become `"ypiresies"` in Greek.
+ * Letting it would silently give one locale a page nested under another route's
+ * URL and the other a top-level one, which reads as two different pages to a
+ * crawler however carefully the `hreflang` tags pair them up.
+ *
+ * Stated in the constraint rather than the parameter, like the other checks
+ * here: in parameter position one bad slug widens `T` and every *other* route
+ * then reports as malformed.
+ */
+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
+        // declaring one property is what keeps `enabled` and `sitemap` legal:
+        // an object literal is checked against this type, so a property it does
+        // not mention reads as an excess one.
+        readonly [P in keyof T[K]]: P extends "slugByLocale"
+            ? {
+                  readonly [L in keyof T[K][P]]: T[K] extends {
+                      readonly slug: infer S extends string;
+                  }
+                      ? T[K][P][L] extends infer V extends string
+                          ? SegmentCount<S> extends SegmentCount<V>
+                              ? V
+                              : SlugDepthMismatch<K, L & string>
+                          : T[K][P][L]
+                      : T[K][P][L];
+              }
+            : T[K][P];
+    };
+};
+
+/**
+ * Declares the base routes: one id per page, with its slug and translations.
+ *
+ * The config argument supplies the locale union, so there are no type arguments
+ * to write.
+ */
+export function defineRoutes<
+    const C extends SiteConfigShape,
+    const T extends RouteRegistry<LocalesOf<C>>,
+>(
+    // Read for its type only: it is how `L` is inferred without a type argument.
+    _config: C,
+    routes: T & ValidateSlugDepth<T>
+): T {
+    return routes;
+}
+
+export interface RouteOverride<L extends string> {
+    /** Replace the fallback slug. */
+    readonly slug?: string;
+    /** Replace or add per-locale slugs. Merged over the base translations. */
+    readonly slugByLocale?: Readonly<Partial<Record<L, string>>>;
+    /** Add or remove this page from this project's build. */
+    readonly enabled?: boolean;
+    /**
+     * How many pages this venue's list runs to. See `RouteData.pages`.
+     *
+     * The usual home for it: the count follows from how much this deployment
+     * has published, which the shared table cannot know.
+     */
+    readonly pages?: number;
+    readonly sitemap?: RouteSitemap;
+}
+
+export type RouteOverrideMap<L extends string, Base> = Readonly<
+    Partial<Record<StringKeys<Base>, RouteOverride<L>>>
+>;
+
+/** The slug a registry declares for route `K`, if it declares one. */
+type BaseSlug<Base, K extends PropertyKey> = K extends keyof Base
+    ? Base[K] extends { readonly slug: infer S extends string }
+        ? S
+        : never
+    : never;
+
+/**
+ * The slug route `K` ends up with: the override's if it has one, else the base's.
+ *
+ * `mergeRoutes`' `override?.slug ?? data.slug` said in types, and the two have
+ * to agree — this decides both the depth checks below and, through
+ * `EnabledSlugs`, the section prefixes a consumer is offered to match on.
+ *
+ * The no-override branch matters only to `EnabledSlugs`, which asks about every
+ * enabled route rather than only the overridden ones. `ValidateOverrideSlugDepth`
+ * maps `StringKeys<T>`, so its `K` is always an overlay key and it never reaches
+ * that branch.
+ */
+type EffectiveSlug<Base, T, K extends PropertyKey> = K extends keyof T
+    ? T[K] extends { readonly slug: infer S extends string }
+        ? S
+        : BaseSlug<Base, K>
+    : BaseSlug<Base, K>;
+
+/** The locales this override restates, which therefore replace the base's. */
+type OverriddenLocales<T, K extends PropertyKey> = K extends keyof T
+    ? T[K] extends { readonly slugByLocale?: infer O }
+        ? keyof O
+        : never
+    : never;
+
+/**
+ * The locales whose *inherited* translation would end up at the wrong depth.
+ *
+ * Only the ones this override leaves alone: a locale it retranslates is checked
+ * against the new slug by the `slugByLocale` clause instead, so counting it here
+ * too would reject deepening a route and its translations together.
+ */
+type InheritedDepthMismatch<
+    Base,
+    T,
+    K extends PropertyKey,
+    Depth,
+> = K extends keyof Base
+    ? Base[K] extends { readonly slugByLocale?: infer M }
+        ? {
+              [L in keyof M]: L extends OverriddenLocales<T, K>
+                  ? never
+                  : M[L] extends infer V extends string
+                    ? SegmentCount<V> extends Depth
+                        ? never
+                        : L
+                    : never;
+          }[keyof M]
+        : never
+    : never;
+
+/**
+ * The same depth rule as {@link ValidateSlugDepth}, across the overlay seam.
+ *
+ * Two ways to break it here, and both are checked, because a project sees only
+ * half of what it is changing: a new `slugByLocale` entry has to match whatever
+ * slug the route *ends up* with, and a new `slug` has to match the translations
+ * the base already declared and this project is inheriting.
+ */
+export type ValidateOverrideSlugDepth<Base, T> = {
+    readonly [K in StringKeys<T>]: {
+        readonly [P in keyof T[K]]: P extends "slugByLocale"
+            ? {
+                  readonly [L in keyof T[K][P]]: T[K][P][L] extends infer V extends
+                      string
+                      ? SegmentCount<
+                            EffectiveSlug<Base, T, K>
+                        > extends SegmentCount<V>
+                          ? V
+                          : SlugDepthMismatch<K, L & string>
+                      : T[K][P][L];
+              }
+            : P extends "slug"
+              ? T[K][P] extends infer S extends string
+                  ? [
+                        InheritedDepthMismatch<Base, T, K, SegmentCount<S>>,
+                    ] extends [never]
+                      ? S
+                      : SlugDepthMismatch<
+                            K,
+                            InheritedDepthMismatch<
+                                Base,
+                                T,
+                                K,
+                                SegmentCount<S>
+                            > &
+                                string
+                        >
+                  : T[K][P]
+              : T[K][P];
+    };
+};
+
+/**
+ * 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 }>
+>;
+
+/**
+ * The project's override entry for one route, or `undefined` where it said
+ * nothing.
+ *
+ * The {@link IsNever} guard matters: an override map typed with an index
+ * signature rather than as a literal yields `never` for `O[K]`, and `never`
+ * satisfies every constraint — without the guard, such a map would read as
+ * "every page enabled".
+ */
+type OverrideEntryFor<O, K extends string> = K extends keyof O
+    ? IsNever<O[K]> extends true
+        ? undefined
+        : O[K]
+    : undefined;
+
+/**
+ * Whether route `K` is built: the project's flag if it set one, otherwise the
+ * base registry's. An override that only retranslates a slug falls through,
+ * because `{ slug: … }` does not match `{ enabled: … }`.
+ */
+type EffectiveEnabled<
+    Base extends EnabledFlagSource,
+    O,
+    K extends StringKeys<Base>,
+> =
+    OverrideEntryFor<O, K> extends { readonly enabled: infer E extends boolean }
+        ? E
+        : Base[K]["enabled"];
+
+/**
+ * The first segment of a nested slug. A top-level slug contributes nothing:
+ * there is no group to name if nothing sits under it.
+ */
+type FirstSegment<S extends string> = S extends `${infer Head}/${string}`
+    ? Head
+    : never;
+
+/** The ids this project builds, as keys usable with `Pick`. */
+type EnabledIds<Routes, Overrides> = EnabledRouteIdFor<
+    Routes & EnabledFlagSource,
+    Overrides
+> &
+    keyof Routes;
+
+/**
+ * The slugs of the pages this project actually publishes.
+ *
+ * Filtered to the enabled set, because both types below are about what exists
+ * at build time: a family whose index page a project switched off has no page
+ * to title or link its section, however the shared registry declares it.
+ *
+ * **The untranslated slug, in the language it was declared in.** A section
+ * prefix is an identifier a consumer matches on, and one that changed with the
+ * locale — `challenges` in one file, its Greek translation in another — could
+ * not be matched at all. `llms()` groups on this same untranslated slug for
+ * that reason; only the URLs it produces are localised.
+ *
+ * A slug that is not a literal — computed, or read from an env var — widens
+ * this to `string`, the same graceful degradation the other slug checks have.
+ *
+ * **Per route, the overlay replaces the registry — it does not join it.** The
+ * earlier form unioned every declared slug from both sides, so a project that
+ * retranslated a nested slug kept the *old* prefix in the union alongside the
+ * new one. Nothing valid was rejected, which is why it went unnoticed: what it
+ * cost was the check itself. `sectionHeading` would accept a segment no build
+ * produces, the comparison against it would never match, and the section would
+ * quietly keep its default heading — the exact failure `SectionPrefixOf` is
+ * typed to make impossible, since a bare `string` there would have been the
+ * same silence.
+ */
+type EnabledSlugs<Routes, Overrides> = {
+    [K in EnabledIds<Routes, Overrides>]: EffectiveSlug<Routes, Overrides, K>;
+}[EnabledIds<Routes, Overrides>];
+
+/**
+ * The URL segments that head a group of nested pages — the sections an
+ * `llms.txt` is organised into.
+ *
+ * Derived from the slugs rather than from route ids, because the two do not
+ * match: `routeFamily` builds the id `challenges-red-room` from the slug
+ * `challenges/red-room`, and only the slug knows where the boundary was.
+ */
+export type SectionPrefixOf<Routes, Overrides> = FirstSegment<
+    EnabledSlugs<Routes, Overrides>
+>;
+
+/**
+ * The sections with no page of their own — a prefix that heads a group but is
+ * not itself a slug anything is published at.
+ *
+ * These are the only sections whose link a consumer may choose. Where an index
+ * page exists it is the answer, and offering a second one would invite a
+ * heading that points somewhere other than the page it names.
+ */
+export type OrphanSectionPrefixOf<Routes, Overrides> = Exclude<
+    SectionPrefixOf<Routes, Overrides>,
+    EnabledSlugs<Routes, Overrides>
+>;
+
+/**
+ * The route ids that survive a given override map, computed from literal types.
+ *
+ * The mapped-type-then-index shape is the standard "filter a union" idiom: map
+ * every id to either itself or `never`, then index by the whole key union —
+ * `never` members drop out of the resulting union automatically.
+ *
+ * This is what makes `pathFor()` reject a page the project switched off,
+ * instead of emitting a link to a URL that was never built.
+ */
+export type EnabledRouteIdFor<Base extends EnabledFlagSource, O> = {
+    [K in StringKeys<Base>]: EffectiveEnabled<Base, O, K> extends false
+        ? never
+        : K;
+}[StringKeys<Base>];

package/src/routes/family.ts

@@ -0,0 +1,251 @@
+/**
+ * Route families: many pages that share a URL prefix and a view.
+ *
+ * Forty-odd escape rooms, a handful of paginated pages. Each is an ordinary
+ * route — its own id, its own slug, its own on/off switch, its own copy — so
+ * everything downstream keeps working unchanged: `pathFor` still rejects a typo'd
+ * id, a project can still enable one member and not another, and each member can
+ * still translate its own slug. The family helper only saves the typing.
+ *
+ * Deliberately *not* a dynamic `:param` route. A parameter would collapse the
+ * family to one id, and with it the typo checking, the per-member switch and the
+ * per-member slug translation — three things that already work, traded for
+ * shorter source.
+ */
+
+import type { LocalesOf, SiteConfigShape } from "../config.ts";
+import type { StringKeys } from "../types.ts";
+import type { RouteData, RouteSitemap } from "./define.ts";
+
+/** One member of a family: an id, and optionally its own translated segments. */
+export interface FamilyMember<L extends string> {
+    /** The URL segment and the tail of the route id, e.g. `"all-in"`. */
+    readonly id: string;
+    /**
+     * Per-locale translations of this member's own segment.
+     *
+     * The family prefix is translated once, on the family; this is for the part
+     * that differs per member — a post whose slug reads differently in Greek.
+     */
+    readonly segmentByLocale?: Readonly<Partial<Record<L, string>>>;
+}
+
+/** A member written as a bare id, for the common case of no translations. */
+export type FamilyMemberInput<L extends string> = string | FamilyMember<L>;
+
+type MemberId<M> = M extends string
+    ? M
+    : M extends { readonly id: infer I }
+      ? I
+      : never;
+
+/**
+ * The route ids a family produced.
+ *
+ * ```ts
+ * const challengeRoutes = routeFamily(config, "challenges", challenges);
+ * export type ChallengeRouteId = RouteIdsOf<typeof challengeRoutes>;
+ * ```
+ *
+ * Reading them back off the family means the prefix is written once, in the
+ * call. Spelling the ids out as `` `challenges-${string}` `` would be a second
+ * copy of it, free to drift the day the URL changes.
+ */
+export type RouteIdsOf<Family> = StringKeys<Family>;
+
+/**
+ * A URL prefix as a route-id prefix: `"news/posts"` -> `"news-posts"`.
+ *
+ * The family's id prefix is derived rather than passed, because a second name
+ * would only ever differ cosmetically from the first — and then a reader has to
+ * hold both. Deriving it means a route id can be guessed from a URL and back.
+ */
+type Dashed<S extends string> = S extends `${infer Head}/${infer Rest}`
+    ? `${Head}-${Dashed<Rest>}`
+    : S;
+
+export interface FamilyOptions<L extends string> {
+    /**
+     * Per-locale translation of the shared prefix: `challenges` -> `dokimasies`.
+     * Members inherit it, so one line retranslates the whole family.
+     */
+    readonly prefixByLocale?: Readonly<Partial<Record<L, string>>>;
+    /** Applied to every member. A project can still override one at a time. */
+    readonly enabled?: boolean;
+    readonly sitemap?: RouteSitemap;
+}
+
+/**
+ * Expands a family into ordinary route entries, ready to spread into
+ * `defineRoutes`.
+ *
+ * ```ts
+ * export const defaultRoutes = defineRoutes(config, {
+ *     challenges: { enabled: true, slug: "challenges" },
+ *     ...routeFamily(config, "challenges", CHALLENGE_IDS),
+ * });
+ * ```
+ *
+ * Ids come out as the prefix and the member joined by `-` —
+ * `challenges-all-in`, `news-posts-hello` — which keeps them literal, keeps them
+ * greppable, and gives the copy convention something to hang off:
+ * `route.challenges-all-in.title` needs no new rule.
+ */
+export function routeFamily<
+    const C extends SiteConfigShape,
+    const Prefix extends string,
+    const Members extends readonly FamilyMemberInput<LocalesOf<C>>[],
+    const Options extends FamilyOptions<LocalesOf<C>> = Record<string, never>,
+>(
+    // Read for its type only, as everywhere else: it supplies the locale union.
+    _config: C,
+    prefix: Prefix,
+    members: Members,
+    options?: Options
+): {
+    readonly [M in Members[number] as `${Dashed<Prefix>}-${MemberId<M> &
+        string}`]: {
+        readonly slug: `${Prefix}/${MemberId<M> & string}`;
+        // The literal, not `boolean`. `EnabledRouteIdFor` asks whether this
+        // extends `false`, and `boolean` does not — so widening here would make
+        // every member of every family read as enabled on every project, and
+        // `pathFor` would accept a room the venue does not run. The build still
+        // threw, but only at build time and only if something linked to it.
+        readonly enabled: Options extends {
+            readonly enabled: infer E extends boolean;
+        }
+            ? E
+            : true;
+        readonly slugByLocale?: Readonly<Partial<Record<LocalesOf<C>, string>>>;
+        readonly sitemap?: RouteSitemap;
+    };
+} {
+    const routes: Record<string, RouteData<LocalesOf<C>>> = {};
+
+    for (const member of members) {
+        const id = typeof member === "string" ? member : member.id;
+        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}`;
+        }
+
+        routes[`${prefix.replaceAll("/", "-")}-${id}`] = {
+            slug: `${prefix}/${id}`,
+            enabled: options?.enabled ?? true,
+            ...(locales.size > 0
+                ? {
+                      slugByLocale: slugByLocale as Readonly<
+                          Partial<Record<LocalesOf<C>, string>>
+                      >,
+                  }
+                : {}),
+            ...(options?.sitemap === undefined
+                ? {}
+                : { sitemap: options.sitemap }),
+        };
+    }
+
+    return routes as never;
+}
+
+/**
+ * One override, applied to many members of a family — the overlay counterpart of
+ * {@link routeFamily}.
+ *
+ * ```ts
+ * overrideRoutes: {
+ *     ...enableRoutes("challenges", venueRooms),
+ *     careers: { enabled: true },
+ * }
+ * ```
+ *
+ * Its job is the keys, and that job is load-bearing. A project deriving its
+ * overlay with `Object.fromEntries` gets `Record<string, …>`, whose index
+ * signature answers for *every* route id — so `EnabledRouteIdFor` reads the
+ * project as building every page in the registry, and `pathFor` accepts rooms
+ * the venue does not run. This composes the same ids `routeFamily` composed and
+ * keeps them literal, so the narrowing survives.
+ *
+ * It does not check the members: the list should already be typed against the
+ * family's own ids, so a typo fails in the venue's data file by name rather than
+ * here as an unrecognised key.
+ */
+export function enableRoutes<const Prefix extends string>(
+    prefix: Prefix
+): <
+    const Members extends readonly (string | { readonly id: string })[],
+    const Override extends { readonly enabled?: boolean } = {
+        readonly enabled: true;
+    },
+>(
+    members: Members,
+    override?: Override
+) => {
+    readonly [M in Members[number] as `${Dashed<Prefix>}-${MemberId<M> &
+        string}`]: Override;
+} {
+    return ((
+        members: readonly (string | { readonly id: string })[],
+        override?: { readonly enabled?: boolean }
+    ) => {
+        const applied = override ?? { enabled: true };
+        const out: Record<string, unknown> = {};
+        for (const member of members) {
+            const id = typeof member === "string" ? member : member.id;
+            out[`${prefix.replaceAll("/", "-")}-${id}`] = applied;
+        }
+        return out;
+    }) as never;
+}
+
+/**
+ * A type guard for "is this route id a member of that family?".
+ *
+ * ```ts
+ * const challengeRoutes = routeFamily(config, "challenges", challenges);
+ * export const isChallengeRoute = familyGuard(challengeRoutes);
+ * ```
+ *
+ * One component usually serves a whole family, and it receives the wide
+ * `RouteId` like any other view. This is what puts it back on the family's own
+ * union — which is what lets a templated `t(\`route.${id}.title\`)` resolve its
+ * `{placeholders}`, since a family's copy is uniform and the site's pages are
+ * not.
+ *
+ * **Generic in the input, and that is load-bearing.** Written as
+ * `(id: string) => id is FamilyId`, `Array.filter` cannot narrow with it: the
+ * guarded type must be a subtype of the array's element type, and a family's ids
+ * cover every member the registry declares while a project's `RouteId` covers
+ * only the ones it builds. The filter then returns the array unnarrowed and says
+ * nothing — the caller believes it holds rooms and is holding the whole site.
+ * Intersecting with `T` makes it a subtype by construction.
+ *
+ * **`Object.hasOwn`, not `in`.** `in` walks the prototype chain, so it answers
+ * `true` for `"toString"`, `"constructor"` and `"valueOf"` — ids the family
+ * never declared. Nothing collides with those today, and that is a fact about
+ * the current route tables rather than about this function: it is exported,
+ * generic over any record, and route ids are composed from data a project
+ * supplies. A guard whose correctness rests on nobody naming a route
+ * `constructor` is a guard waiting for the one that does, and it would narrow a
+ * type that the value does not have.
+ */
+export function familyGuard<
+    const Family extends Readonly<Record<string, unknown>>,
+>(family: Family): <T extends string>(id: T) => id is T & StringKeys<Family> {
+    return <T extends string>(id: T): id is T & StringKeys<Family> =>
+        Object.hasOwn(family, id);
+}