@escape-game-over/atlas 0.1.47 → 0.1.49

package/package.json

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

package/src/astro/Document.astro

@@ -13,14 +13,19 @@
  * A site with a lead form passes `rememberCampaign`, so the `utm_*` tags a
  * visit landed with survive to the page the form is on; see `attribution.ts`.
  *
+ * `fonts={site.fonts}` writes the `@font-face` rules and preloads for the
+ * faces `siteFonts(site)` registered in the Astro config.
+ *
  * ```astro
- * <Document meta={meta} html={{ class: "scroll-smooth" }} body={{ class: "…" }}>
+ * <Document meta={meta} fonts={site.fonts} html={{ class: "scroll-smooth" }} body={{ class: "…" }}>
  *     <Fragment slot="head"><link rel="preload" … /></Fragment>
  *     …page…
  * </Document>
  * ```
  */
+import { Font } from "astro:assets";
 import type { HTMLAttributes } from "astro/types";
+import type { Fonts } from "../fonts.ts";
 import type { PageMeta } from "../site/index.ts";
 import MetaTags from "./MetaTags.astro";
 import RememberCampaign from "./RememberCampaign.astro";
@@ -28,6 +33,7 @@ import ScrollRestore from "./ScrollRestore.astro";
 
 interface Props {
     readonly meta: PageMeta;
+    readonly fonts?: Fonts;
     /** `lang` and `dir` are the page's locale's, from `meta`. */
     readonly html?: Omit<HTMLAttributes<"html">, "lang" | "dir">;
     readonly body?: HTMLAttributes<"body">;
@@ -39,6 +45,7 @@ interface Props {
 
 const {
     meta,
+    fonts = {},
     html,
     body,
     restoreScroll = true,
@@ -55,6 +62,9 @@ const {
     <head>
         <slot name="head-start" />
         <MetaTags tags={meta.tags} />
+        {Object.entries(fonts).map(([key, font]) => (
+            <Font cssVariable={`--${key}`} preload={font.preload === true} />
+        ))}
         <slot name="head" />
     </head>
     <body {...body}>

package/src/astro/fonts.ts

@@ -0,0 +1,21 @@
+import type { AstroUserConfig } from "astro";
+import { fontProviders } from "astro/config";
+import type { Fonts } from "../fonts.ts";
+
+/**
+ * `site.fonts` as Astro's `fonts` config: `fonts: siteFonts(site)`.
+ *
+ * `display` defaults to `fallback`, not Astro's `swap`: `swap` paints the
+ * fallback for a frame even when the font is cached, so text jumps on reload.
+ */
+export function siteFonts(site: {
+    readonly fonts: Fonts;
+}): NonNullable<AstroUserConfig["fonts"]> {
+    return Object.entries(site.fonts).map(([key, { preload, ...font }]) => ({
+        display: "fallback",
+        styles: ["normal"],
+        ...font,
+        provider: fontProviders.google(),
+        cssVariable: `--${key}`,
+    }));
+}

package/src/astro/index.ts

@@ -26,6 +26,7 @@
  * `…/astro/document` from a layout, `…/client` from a script.
  */
 
+export { siteFonts } from "./fonts.ts";
 export {
     type PublicFilesOptions,
     publicFiles,

package/src/astro/site-routes.ts

@@ -212,6 +212,7 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
             "astro:config:setup": ({
                 config: current,
                 updateConfig,
+                addWatchFile,
                 logger,
             }) => {
                 /**
@@ -290,6 +291,16 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
                     `updated config: ${JSON.stringify(config, null, 2)}`
                 );
                 reportOrphans();
+
+                // `atlas use` swaps the project by relinking `config/project`,
+                // and nothing Vite watches changes when it does: the files
+                // behind the link are new, but every module already loaded
+                // through it stays cached, so a running `astro dev` keeps
+                // serving the old project — its messages, its routes, a map
+                // from one country with the pins of another. Watching the link
+                // itself turns the relink into a restart. A project without
+                // overlays has no such link, and the watch is simply idle.
+                addWatchFile(new URL("config/project", current.root));
             },
 
             /**

package/src/config.ts

@@ -1,3 +1,4 @@
+import type { Fonts } from "./fonts.ts";
 import type { LlmsConfig } from "./llms.ts";
 import type { RobotsConfig } from "./robots.ts";
 import type { SitemapConfig } from "./sitemap.ts";
@@ -97,6 +98,8 @@ export interface SiteConfigShape {
      * reading this file is not enough to know how one deployment's URLs look.
      */
     readonly defaultRouting: RoutingConfig<string>;
+    /** A project's `overrideFonts` adds to these or replaces one by key. */
+    readonly defaultFonts?: Fonts;
     readonly sitemap?: SitemapConfig;
     readonly robots?: RobotsConfig;
     /** `false` publishes no `llms.txt`, and no page links to one. */

package/src/fonts.ts

@@ -0,0 +1,36 @@
+import type { AstroUserConfig } from "astro";
+
+type FontFamily = NonNullable<AstroUserConfig["fonts"]>[number];
+
+/**
+ * One typeface, self-hosted from Google Fonts. Astro's own family options, less
+ * the two atlas fills in: the provider, and the CSS variable (the key).
+ */
+export type Font = Omit<FontFamily, "provider" | "cssVariable"> & {
+    /** Preloads its files on every page. */
+    readonly preload?: boolean;
+};
+
+/**
+ * Keyed by the CSS variable the face is exposed as, without the dashes:
+ * `raleway` is `--raleway`.
+ */
+export type Fonts = Readonly<Record<string, Font>>;
+
+const CSS_IDENT = /^[a-z][a-z0-9-]*$/;
+
+/** A project's fonts: new keys are added, a key the site has replaces it. */
+export function mergeFonts(
+    base: Fonts | undefined,
+    overrides: Fonts | undefined
+): Fonts {
+    const merged = { ...base, ...overrides };
+    for (const key of Object.keys(merged)) {
+        if (!CSS_IDENT.test(key)) {
+            throw new Error(
+                `Font key "${key}" must be lowercase kebab-case: it becomes the CSS variable --${key}.`
+            );
+        }
+    }
+    return merged;
+}

package/src/index.ts

@@ -85,6 +85,7 @@ export {
 } from "./countries.ts";
 export type { GeneratedFile } from "./file.ts";
 export type { PublicFilePath, PublicFileRegistry } from "./files.ts";
+export type { Font, Fonts } from "./fonts.ts";
 export {
     assertHours,
     type DayHours,

package/src/project.ts

@@ -6,6 +6,7 @@ import type {
     RoutingConfig,
     SiteConfigShape,
 } from "./config.ts";
+import type { Fonts } from "./fonts.ts";
 import type {
     BaseCatalog,
     OverrideCatalog,
@@ -108,6 +109,8 @@ export interface ProjectInput<L extends string, Routes> {
     readonly overrideLocaleMeta?: Readonly<
         Partial<Record<L, LocaleMetaOverride>>
     >;
+    /** Adds to the site's `defaultFonts`, or replaces one by key. */
+    readonly overrideFonts?: Fonts;
     /**
      * Copy overrides: any subset of keys, any subset of locales.
      *

package/src/site/api.ts

@@ -2,6 +2,7 @@ import type { ResolvedLocaleMeta } from "../config.ts";
 import type { PlainTextFor, RichTextFor } from "../content/index.ts";
 import type { GeneratedFile } from "../file.ts";
 import type { PublicFilePath } from "../files.ts";
+import type { Fonts } from "../fonts.ts";
 import type { TranslateFor } from "../i18n/translate.ts";
 import type { LlmsSection } from "../llms.ts";
 import type { ThemeColor } from "../meta/index.ts";
@@ -151,6 +152,8 @@ export interface Site<
      */
     readonly themeColor: ThemeColor;
     readonly localeMeta: Readonly<Record<L, ResolvedLocaleMeta>>;
+    /** The site's `defaultFonts` with this project's `overrideFonts` applied. */
+    readonly fonts: Fonts;
     /**
      * Every route this project builds, in the order the base registry declares
      * them. Derived — a project never lists these. Build menus by filtering it.

package/src/site/create.ts

@@ -11,6 +11,7 @@ import {
 } from "../content/index.ts";
 import type { GeneratedFile } from "../file.ts";
 import type { PublicFilePath } from "../files.ts";
+import { mergeFonts } from "../fonts.ts";
 import { type BaseCatalog, mergeCatalog } from "../i18n/define.ts";
 import { createTranslateFactory } from "../i18n/translate.ts";
 import type { ImageAsset } from "../image.ts";
@@ -158,6 +159,7 @@ export function createSite<
         project.overrideLocaleMeta,
         locales
     );
+    const fonts = mergeFonts(config_.defaultFonts, project.overrideFonts);
     const pathContext: PathContext<L> = {
         defaultLocale,
         prefixDefaultLocale,
@@ -797,6 +799,7 @@ export function createSite<
         siteName: project.siteName,
         themeColor: project.themeColor,
         localeMeta,
+        fonts,
         routes: enabledRouteIds,
 
         translate: (locale) => translateFactory(catalog, locale),