@escape-game-over/atlas 0.1.23 → 0.1.25

package/src/content/rich.ts

@@ -22,6 +22,7 @@ import {
     joinUrl,
     type UrlPath,
 } from "../url.ts";
+import { escapeXml } from "../xml.ts";
 import { type LinkNames, type ParsedSpan, parseMarks } from "./marks.ts";
 
 /**
@@ -52,7 +53,7 @@ export type Span =
      * edit rather than a sweep through fifty-four deployments' copy.
      */
     | {
-          readonly kind: "styled";
+          readonly kind: "variant";
           readonly text: string;
           readonly variant: string;
       }
@@ -104,12 +105,12 @@ export type Span =
           readonly href: Hash;
       }
     | {
-          readonly kind: "email";
+          readonly kind: "mail";
           readonly text: string;
           readonly href: MailtoUrl;
       }
     | {
-          readonly kind: "phone";
+          readonly kind: "tel";
           readonly text: string;
           readonly href: TelUrl;
       }
@@ -229,7 +230,7 @@ export type RichTextFor<Catalog, RouteId extends string> = <
     ...args: RichArgsOf<Catalog, K, RouteId>
 ) => RichText;
 
-/** `plain()`, keyed and parameterised exactly as `t()` is. */
+/** `site.plain()`, keyed and parameterised exactly as `t()` is. */
 export type PlainTextFor<Catalog> = <K extends StringKeys<Catalog>>(
     ...args: TranslateArgsOf<Catalog, K>
 ) => string;
@@ -285,8 +286,8 @@ function resolve(
         case "text":
         case "bold":
             return { kind: span.kind, text };
-        case "styled":
-            return { kind: "styled", text, variant: span.variant };
+        case "variant":
+            return { kind: "variant", text, variant: span.variant };
         case "link":
             return resolveLink(
                 text,
@@ -295,10 +296,10 @@ function resolve(
                 link,
                 origin
             );
-        case "email":
-            return { kind: "email", text, href: mailto(text, at) };
-        case "phone":
-            return { kind: "phone", text, href: tel(text, at) };
+        case "mail":
+            return { kind: "mail", text, href: mailto(text, at) };
+        case "tel":
+            return { kind: "tel", text, href: tel(text, at) };
     }
 }
 
@@ -473,19 +474,52 @@ function tel(text: string, at: string): TelUrl {
 }
 
 /**
- * The words alone, for everywhere that takes a string rather than markup.
+ * The runs as inline HTML, for a field that takes markup rather than a page.
  *
- * The reason this whole module sits in lib rather than in each project. A meta
- * description, an `llms.txt` summary and a structured-data `description` all
- * want the same sentence the page renders, and every one of them takes a plain
- * string — so without this each project flattens the runs by hand, and they
- * drift. The implementation this replaces did exactly that: a chain of `if`s
- * per kind, `return ""` for the ones it could not render, and a `throw` on
- * anything it had not been taught.
+ * Written for a `FAQPage` answer, whose `text` accepts a handful of tags —
+ * `<a>`, `<strong>`, `<br>` among them. Only those are emitted: a `[v:]` role
+ * is presentation, which structured data has no use for, so it is its words.
  *
- * A `[br]` becomes a space, because that is what it is once the markup is gone,
- * and runs of whitespace collapse — copy split across a line break otherwise
- * arrives with a double space in the middle of a `<meta>` tag.
+ * Links carry their absolute `url`, since nothing reading this has a page to
+ * resolve a path against. An anchor has none, so it is its words too.
+ *
+ * Every piece of copy is escaped: the field is read as HTML, so an `&` or a `<`
+ * in a translation would otherwise be read as markup.
+ */
+export function html(rich: RichText): string {
+    return rich
+        .map((span) => {
+            switch (span.kind) {
+                case "text":
+                case "variant":
+                    return escapeXml(span.text);
+                case "bold":
+                    return `<strong>${escapeXml(span.text)}</strong>`;
+                case "link":
+                    return span.to === "anchor"
+                        ? escapeXml(span.text)
+                        : anchor(span.url, span.text);
+                case "mail":
+                case "tel":
+                    return anchor(span.href, span.text);
+                case "break":
+                    return "<br>";
+                default: {
+                    const unreachable: never = span;
+                    return unreachable;
+                }
+            }
+        })
+        .join("");
+}
+
+function anchor(href: string, text: string): string {
+    return `<a href="${escapeXml(href)}">${escapeXml(text)}</a>`;
+}
+
+/**
+ * The words of runs already built — for a message whose values `rich()` was
+ * given in code. A `[br]` becomes a space and whitespace collapses.
  */
 export function plain(rich: RichText): string {
     return collapse(
@@ -505,14 +539,9 @@ function collapse(parts: readonly string[]): string {
 }
 
 /**
- * The same, straight from a message key — `plain(rich(…))` without the nesting.
- *
- * Which sounds like sugar and is mostly about where it gets used. The callers
- * that want words rather than runs are the ones furthest from a renderer:
- * `llms()`'s `describe`, a `<meta name="description">`, a structured-data
- * `description`. Those are already assembling several strings at once, and
- * `plain(rich("about.intro", { company }))` reads as two operations there when
- * it is one question — what does this message say.
+ * The words of a message alone, for everywhere that takes a string rather than
+ * markup: a meta description, an `llms.txt` summary, a structured-data
+ * `description`. A `[br]` becomes a space and whitespace collapses.
  *
  * It also answers that question for a message with no marks at all, which `t()`
  * would too. That overlap is deliberate: a description built this way keeps

package/src/hours.ts

@@ -164,18 +164,22 @@ export function groupHours(
 }
 
 /**
- * The words a printed week needs, which lib does not have.
- *
- * Day names and "closed" are copy: they are translated, and lib holds no copy.
- * Everything else about the line — which days collapse into a span, what order
- * they come in, where the dashes go — is mechanical and is done here, because
- * otherwise every project rewrites the same joins in a component.
+ * How to print a week. Day names come from `Intl` in `locale`; "closed" is
+ * copy, so the caller translates it.
  */
 export interface HoursFormat {
-    /** What to call a day. Usually a lookup in the project's catalog. */
-    day(day: Weekday): string;
+    /** The language the days are named in, e.g. `"el-GR"`. */
+    locale: string;
+    /** `Mon` or `Monday`. Defaults to `"short"`. */
+    weekday?: "short" | "long";
     /** The word for a day the venue is shut. */
     closed: string;
+    /**
+     * Times print as written (`14:00`) unless this is `"h12"` (`2:00 PM`).
+     * Not the locale's default, which gives Greek a 12-hour clock nobody there
+     * uses on a door.
+     */
+    hourCycle?: "h12";
     /** Between the ends of a span: `Mon–Thu`, `14:00–23:30`. */
     between?: string;
     /** Between spans: `Mon–Thu, Sun`. */
@@ -207,20 +211,53 @@ export function formatHours(
 ): readonly FormattedHours[] {
     const between = format.between ?? "–";
     const and = format.and ?? ", ";
+    // 2024-01-01 was a Monday, so `WEEK[i]` falls on the 1st plus `i`.
+    const names = new Intl.DateTimeFormat(format.locale, {
+        weekday: format.weekday ?? "short",
+        timeZone: "UTC",
+    });
+    const dayName = (day: Weekday): string =>
+        names.format(new Date(Date.UTC(2024, 0, 1 + WEEK.indexOf(day))));
+    const clock =
+        format.hourCycle === "h12"
+            ? new Intl.DateTimeFormat(format.locale, {
+                  hour: "numeric",
+                  minute: "2-digit",
+                  hourCycle: "h12",
+                  timeZone: "UTC",
+              })
+            : undefined;
+    const time = (at: TimeOfDay): string =>
+        clock === undefined
+            ? at
+            : clock.format(
+                  new Date(
+                      Date.UTC(
+                          2024,
+                          0,
+                          1,
+                          Number(at.slice(0, 2)),
+                          Number(at.slice(3, 5))
+                      )
+                  )
+              );
 
     return groupHours(hours, format.weekStart).map((group) => ({
         days: group.runs
             .map(([first, last]) =>
                 first === last
-                    ? format.day(first)
-                    : `${format.day(first)}${between}${format.day(last)}`
+                    ? dayName(first)
+                    : `${dayName(first)}${between}${dayName(last)}`
             )
             .join(and),
         times:
             group.hours === "closed"
                 ? format.closed
                 : group.hours
-                      .map((range) => `${range.opens}${between}${range.closes}`)
+                      .map(
+                          (range) =>
+                              `${time(range.opens)}${between}${time(range.closes)}`
+                      )
                       .join(and),
     }));
 }

package/src/i18n/define.ts

@@ -11,15 +11,15 @@ import type {
  * `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>`:
+ * Check it with `satisfies`. A missing message then fails on that line, 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<
+ * true satisfies CatalogCovers<
  *     typeof baseMessages,
  *     `route.${RouteId}.${"nav" | "title"}`
- * > = true;
+ * >;
  * ```
  *
  * The pattern earns its keep over a plain `Required extends StringKeys<Catalog>`
@@ -67,7 +67,7 @@ type SelfConsistent<E, K> = [MismatchedLocales<E, EntryTokens<E>>] extends [
           MismatchedLocales<E, EntryTokens<E>> & string
       >;
 
-type ValidateBase<T> = { [K in keyof T]: SelfConsistent<T[K], K> };
+export type ValidateBase<T> = { [K in keyof T]: SelfConsistent<T[K], K> };
 
 /**
  * Rejects locale keys the site does not ship.
@@ -76,7 +76,7 @@ type ValidateBase<T> = { [K in keyof T]: SelfConsistent<T[K], K> };
  * 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> = {
+export type NoExtraLocales<T, L extends string> = {
     [K in keyof T]: NoExcessKeys<T[K], L>;
 };
 
@@ -102,21 +102,7 @@ export function defineMessages<
     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. */
+/** What `defineProject` checks an `overrideMessages` against: placeholders and locales. */
 export type ValidateOverrideCatalog<
     T,
     Base,
@@ -135,63 +121,17 @@ type ValidateOverrides<T, Base> = {
 };
 
 /**
- * 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}` and `[marks]` of the
- *    base message, so every existing `t()` and `rich()` 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:
+ * One project's copy overrides — known keys, published locales — for an overlay
+ * kept in its own file:
  *
  * ```ts
- * const overrides = {
+ * export const romeMessages = {
  *     "site.cta": { "en-US": "Book a room" },
- * } satisfies MessageOverrides<typeof defaultMessages, EnabledLocale>;
- *
- * export const overrideMessages = defineMessageOverrides(
- *     config,
- *     defaultMessages,
- *     overrides
- * );
+ * } as const satisfies MessageOverrides<typeof defaultMessages, EnabledLocale>;
  * ```
  *
- * 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.
+ * A dropped `{placeholder}` is not visible to a type like this; `defineProject`
+ * reports it, naming the key and locale.
  */
 export type MessageOverrides<Catalog, L extends string> = {
     readonly [K in StringKeys<Catalog>]?: Readonly<Partial<Record<L, string>>>;

package/src/index.ts

@@ -1,27 +1,19 @@
 /**
  * The public API. A consuming project should need nothing outside this module.
  *
- * The flow is four steps, each inferring its types from the values of the last:
+ * Everything starts from `defineSite`:
  *
  * ```ts
- * // 1. site.config.ts — which languages exist, how URLs are shaped
- * export default defineSiteConfig({ locales: {...}, defaultRouting: {...} })
- *
- * // 2. src/data — the base copy and routes
- * export const baseMessages = defineMessages(config, {...})
- * export const baseRoutes   = defineRoutes(config, {...})
- *
- * // 3. projects/<name>/project.ts — one deployment's overlay
- * export default defineProject(config, baseMessages, baseRoutes, {...})
- *
- * // 4. src/site.ts — the API the pages use
- * export const site = createSite(config, baseMessages, baseRoutes, project)
+ * export const atlas = defineSite({ locales: {...}, defaultRouting: {...} })  // site.config.ts
+ * export const defaultMessages = atlas.messages({...})                        // messages.ts
+ * export const defaultRoutes = atlas.routes({...})                            // routes.ts
+ * export default atlas.project(defaultMessages, defaultRoutes, {...})         // projects/<name>/project.ts
+ * export const site = atlas.site(defaultMessages, defaultRoutes, project)     // site.ts
  * ```
  */
 
 export {
     type AnalyticsSettings,
-    type AnalyticsTag,
     type AnalyticsTags,
     CONSENT_UPDATE_GLOBAL,
     type ConsentDefaults,
@@ -32,14 +24,13 @@ export {
     type UmamiSettings,
     type UmamiTracker,
 } from "./analytics/index.ts";
-export {
-    defineSiteConfig,
-    type LanguageTag,
-    type LocaleMeta,
-    type LocalesOf,
-    type ResolvedLocaleMeta,
-    type RoutingConfig,
-    type SiteConfigShape,
+export type {
+    LanguageTag,
+    LocaleMeta,
+    LocalesOf,
+    ResolvedLocaleMeta,
+    RoutingConfig,
+    SiteConfigShape,
 } from "./config.ts";
 export {
     assertCoordinates,
@@ -72,6 +63,7 @@ export {
 // a slot filled with a route id resolves against nothing there. `site.rich(locale)` is
 // the only way in, and `Span` is what a renderer switches on.
 export {
+    html,
     type LinkTarget,
     type PlainTextFor,
     plain,
@@ -99,13 +91,11 @@ export {
     type Weekday,
     type WeeklyHours,
 } from "./hours.ts";
-export {
-    type BaseCatalog,
-    type CatalogCovers,
-    defineMessageOverrides,
-    defineMessages,
-    type MessageOverrides,
-    type OverrideCatalog,
+export type {
+    BaseCatalog,
+    CatalogCovers,
+    MessageOverrides,
+    OverrideCatalog,
 } from "./i18n/define.ts";
 export type {
     EntryPlaceholders,
@@ -170,10 +160,8 @@ export {
     type ArticleContent,
     buildMeta,
     buildNotFoundMeta,
-    type ImageFormat,
     type MetaContent,
     type MetaTag,
-    type OgImage,
     type OpenGraphType,
     type PageKind,
     type RobotsPolicy,
@@ -196,7 +184,7 @@ export {
     type TieredPrice,
     tierRange,
 } from "./money.ts";
-export { defineProject, type ProjectInput } from "./project.ts";
+export type { ProjectInput } from "./project.ts";
 export {
     buildCloudflareRedirects,
     buildRedirects,
@@ -211,15 +199,14 @@ export {
     type ValidateRedirectTargets,
 } from "./redirects.ts";
 export type { RobotsConfig, RobotsGroup } from "./robots.ts";
-export {
-    type ChangeFreq,
-    defineRouteOverrides,
-    defineRoutes,
-    type EnabledRouteIdFor,
-    type RouteData,
-    type RouteOverride,
-    type RouteRegistry,
-    type RouteSitemap,
+export type {
+    ChangeFreq,
+    EnabledRouteIdFor,
+    RouteData,
+    RouteOverride,
+    RouteOverrides,
+    RouteRegistry,
+    RouteSitemap,
 } from "./routes/define.ts";
 export {
     enableRoutes,
@@ -228,24 +215,21 @@ export {
     type FamilyOptions,
     familyGuard,
     type RouteIdsOf,
-    routeFamily,
 } from "./routes/family.ts";
 export type { RouteEntry } from "./routes/resolve.ts";
-export {
-    type Alternate,
-    type Crumb,
-    createSite,
-    type LinkOptions,
-    type LlmsOptions,
-    type LocaleLink,
-    type PageContent,
-    type PageMeta,
-    type PageProps,
-    type PerRoute,
-    type RouteIdOf,
-    type Site,
-    type StaticPath,
-    type WhenEnabled,
+export { defineSite } from "./site/define.ts";
+export type {
+    Alternate,
+    Crumb,
+    LinkOptions,
+    LlmsOptions,
+    LocaleLink,
+    PageContent,
+    PageMeta,
+    PageProps,
+    PerRoute,
+    Site,
+    StaticPath,
 } from "./site/index.ts";
 export type { Sitemap, SitemapConfig } from "./sitemap.ts";
 export type { IsoDate, Letter, StringKeys } from "./types.ts";

package/src/jsonld/faq.ts

@@ -11,7 +11,8 @@ export interface FaqEntry {
      * `<ul>`, `<li>`, `<a>`, `<b>`, `<strong>`, `<i>`, `<em>` — and drops
      * everything else. Plain text is what a caller passing a translated string
      * has anyway, and it cannot be silently half-rendered, so nothing here
-     * builds markup for you. Pass the markup yourself if the answer needs it.
+     * builds markup for you. An answer with links in it wants `html(rich(…))`,
+     * which emits only tags from that list and escapes the copy.
      *
      * Checked August 2026.
      */

package/src/jsonld/node.ts

@@ -5,6 +5,8 @@
  * kind of node and imports these to do it.
  */
 
+import { literal } from "../analytics/tags.ts";
+
 /** A node in the graph. Deliberately loose: `@type` is what a consumer varies. */
 export interface JsonLdNode {
     readonly "@type": string | readonly string[];
@@ -60,19 +62,7 @@ export function alternateName(
         : { alternateName: alternate };
 }
 
-/**
- * The graph, serialised for a `<script type="application/ld+json">`.
- *
- * Every `<` is replaced by its unicode escape, and that is the whole reason
- * this is a function rather than a `JSON.stringify` at the call site. A script element ends at the first
- * `</script` in its text, so a business name, a room description or an alt text
- * containing one would close the block early and spill the rest of the graph
- * into the page as markup. The escape is invisible to a JSON parser and to
- * anything reading the data.
- */
+/** The graph, serialised for a `<script type="application/ld+json">`. */
 export function serializeJsonLd(nodes: readonly JsonLdNode[]): string {
-    return JSON.stringify({
-        "@context": "https://schema.org",
-        "@graph": nodes,
-    }).replaceAll("<", "\\u003c");
+    return literal({ "@context": "https://schema.org", "@graph": nodes });
 }

package/src/meta/index.ts

@@ -29,6 +29,7 @@ import {
     notFoundAnalytics,
 } from "../analytics/index.ts";
 import type { ResolvedLocaleMeta } from "../config.ts";
+import type { ImageAsset } from "../image.ts";
 import {
     article,
     type BreadcrumbStep,
@@ -42,11 +43,10 @@ import { robotsContent, warnAboutRobots } from "./robots.ts";
 import {
     iconLinks,
     type OgImage,
-    type SiteIcon,
     warnAboutShareImage,
     warnIfClipped,
 } from "./share-image.ts";
-import { asMetaTag, link, type MetaTag, meta, preamble } from "./tag.ts";
+import { link, type MetaTag, meta, preamble } from "./tag.ts";
 import { type SiteVerification, verificationTags } from "./verification.ts";
 
 export type {
@@ -57,13 +57,7 @@ export type {
     ThemeColor,
 } from "./content.ts";
 export type { RobotsDirective, RobotsPolicy } from "./robots.ts";
-export {
-    type ImageFormat,
-    type OgImage,
-    resolveShareImage,
-    type ShareImage,
-    type SiteIcon,
-} from "./share-image.ts";
+export { resolveShareImage, type ShareImage } from "./share-image.ts";
 export type { MetaTag } from "./tag.ts";
 export type { SiteVerification } from "./verification.ts";
 
@@ -155,7 +149,7 @@ interface MetaInputDerived<L extends string> extends ChromeInput {
  */
 export interface ChromeInput {
     /** The site's square icon, used for every icon link. */
-    readonly icon: SiteIcon;
+    readonly icon: ImageAsset;
     /**
      * Tints the browser UI — Android Chrome's bar, iOS Safari, an installed PWA.
      * Two values emit one tag per `prefers-color-scheme`.
@@ -250,8 +244,8 @@ export function buildMeta<L extends string>(input: MetaInput<L>): DocumentTags {
     // that must precede every tag reading them, and a tag that got there first
     // would silently apply the permissive implicit default instead.
     const analytics = analyticsScripts(input.analytics, input.canonical);
-    for (const script of analytics.head) tags.push(asMetaTag(script));
-    const bodyTags: MetaTag[] = analytics.body.map(asMetaTag);
+    tags.push(...analytics.head);
+    const bodyTags: MetaTag[] = [...analytics.body];
 
     if (input.llmsUrl !== undefined) {
         // Points a client at the file describing this page, per llmstxt.org.
@@ -473,7 +467,7 @@ export function buildNotFoundMeta(input: NotFoundInput): MetaTag[] {
             name: "robots",
             content: robotsContent({ index: false, follow: true }),
         }),
-        ...notFoundAnalytics(input.analytics).map(asMetaTag),
+        ...notFoundAnalytics(input.analytics),
         ...chromeTags(input),
     ];
 }