@escape-game-over/atlas 0.1.78 → 0.1.80

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.78",
+    "version": "0.1.80",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -17,6 +17,7 @@
         "./astro/images": "./src/astro/images.ts",
         "./client": "./src/astro/client.ts",
         "./astro/auto-dialog": "./src/astro/AutoDialog.astro",
+        "./astro/background-video": "./src/astro/BackgroundVideo.astro",
         "./astro/consent-banner": "./src/astro/ConsentBanner.astro",
         "./astro/document": "./src/astro/Document.astro",
         "./astro/element": "./src/astro/AtlasElement.astro",

package/src/analytics/storage.ts

@@ -289,6 +289,29 @@ export function compareStoredItems(a: StoredItem, b: StoredItem): number {
     );
 }
 
+/**
+ * Each row with what the project says it is for — a message key, usually,
+ * since the words are the project's and in every locale.
+ *
+ * Throws, naming every row without one, so a vendor switched on, or a row a
+ * new Atlas adds, fails the build until the site has said what it is for: a
+ * notice that lists a cookie without a purpose is the one thing it must not
+ * publish. `purposes` may name rows this deployment does not have; a site
+ * keeps its wording when a vendor is switched off.
+ */
+export function withPurposes<K>(
+    rows: readonly StoredItem[],
+    purposes: Partial<Record<StoredId, K>>
+): readonly (StoredItem & { readonly purpose: K })[] {
+    const missing = rows.filter((row) => purposes[row.id] === undefined);
+    if (missing.length > 0) {
+        throw new Error(
+            `The storage table has no purpose for ${missing.map((row) => `"${row.id}"`).join(", ")}. Add one for each to the purposes given to withPurposes.`
+        );
+    }
+    return rows.map((row) => ({ ...row, purpose: purposes[row.id] as K }));
+}
+
 /**
  * Everything this deployment keeps on a device: Atlas's own keys, then each
  * loaded vendor's.

package/src/astro/BackgroundVideo.astro

@@ -0,0 +1,151 @@
+---
+/**
+ * A decorative, silent loop over its own poster, with the pause control WCAG
+ * 2.2.2 asks for. Playback is `backgroundVideo`'s; this is the markup it needs,
+ * which is where a hero quietly goes wrong:
+ *
+ * - The poster is a `<picture>`, not the `poster` attribute, so each
+ *   orientation gets its own still, cut to size. It is usually the largest
+ *   paint, so it loads eagerly and first.
+ * - `preload="none"`: nothing of the loop is fetched until it starts, which is
+ *   after `load` — `metadata` alone was enough to undo that wait.
+ * - `muted`, `loop`, `playsinline`, and hidden from assistive technology.
+ * - The control stays hidden until a cut suits the viewport, and names what it
+ *   will do — `play` or `pause`, the site's own words.
+ *
+ * The site gives the element its size and position, the control its look, and
+ * its two icons as the `playing` slot (shown while it plays: a pause icon) and
+ * the `paused` slot.
+ *
+ * ```astro
+ * <BackgroundVideo
+ *     sources={[{ src: webm, type: 'video/webm; codecs="vp9"' }]}
+ *     posters={[{ image: portraitStill, media: "(orientation: portrait)" }, { image: still }]}
+ *     play={t("hero.play")}
+ *     pause={t("hero.pause")}
+ *     class="absolute inset-0"
+ *     buttonClass="absolute bottom-4 right-4 …"
+ * >
+ *     <Icon slot="playing" name="lucide:pause" />
+ *     <Icon slot="paused" name="lucide:play" />
+ * </BackgroundVideo>
+ * ```
+ */
+import { getImage } from "astro:assets";
+import type { HTMLAttributes } from "astro/types";
+import type { NonEmpty } from "../types.ts";
+import AtlasElement from "./AtlasElement.astro";
+import type { VideoPoster, VideoSource } from "./background-video.ts";
+import { backgroundVideoElement } from "./background-video-element.ts";
+
+type Props = Omit<HTMLAttributes<"div">, "children"> & {
+    readonly sources: NonEmpty<VideoSource>;
+    /** Stills by viewport, as `<picture>` reads them: the last has no `media`. */
+    readonly posters: NonEmpty<VideoPoster>;
+    /** The control's label while paused. */
+    readonly play: string;
+    /** The control's label while playing. */
+    readonly pause: string;
+    readonly buttonClass?: string;
+    /** For the poster's `srcset`. Defaults to `100vw`, a full-bleed background. */
+    readonly sizes?: string;
+};
+
+const {
+    sources,
+    posters,
+    play,
+    pause,
+    buttonClass,
+    sizes = "100vw",
+    ...attrs
+} = Astro.props;
+
+const fallback = posters[posters.length - 1];
+if (fallback?.media !== undefined) {
+    throw new Error(
+        "BackgroundVideo: the last poster is the fallback, and takes no `media`."
+    );
+}
+if (posters.slice(0, -1).some((poster) => poster.media === undefined)) {
+    throw new Error(
+        "BackgroundVideo: every poster but the last needs a `media`; one without would always win."
+    );
+}
+
+const cut = await Promise.all(
+    posters.map(async (poster) => ({
+        media: poster.media,
+        image: await getImage({
+            src: poster.image,
+            widths: [...(poster.widths ?? [960, 1440, 1920])],
+            format: "webp",
+        }),
+    }))
+);
+const still = cut[cut.length - 1];
+
+// Structural, so inline: the still under the video, both covering the element.
+const cover = "width:100%;height:100%;object-fit:cover";
+---
+
+<script src="./background-video-element.ts" />
+
+<AtlasElement
+    of={backgroundVideoElement}
+    data-play={play}
+    data-pause={pause}
+    {...attrs}
+>
+    <picture>
+        {cut.slice(0, -1).map((poster) => (
+            <source
+                media={poster.media}
+                srcset={poster.image.srcSet.attribute}
+                sizes={sizes}
+            />
+        ))}
+        <img
+            src={still?.image.src}
+            srcset={still?.image.srcSet.attribute}
+            sizes={sizes}
+            alt=""
+            fetchpriority="high"
+            style={`position:absolute;inset:0;${cover}`}
+        >
+    </picture>
+    <video
+        style={`position:relative;${cover}`}
+        muted
+        loop
+        playsinline
+        preload="none"
+        aria-hidden="true"
+        tabindex="-1"
+    >
+        {sources.map((source) => (
+            <source
+                src={source.src}
+                media={source.media}
+                type={source.type}
+            />
+        ))}
+    </video>
+    <button
+        type="button"
+        data-video-toggle
+        hidden
+        aria-label={pause}
+        class={buttonClass}
+    >
+        <span data-video-playing>
+            <slot name="playing" />
+        </span>
+        <span
+            data-video-paused
+            hidden
+        >
+            <slot name="paused" />
+        </span>
+    </button>
+</AtlasElement>

package/src/astro/Document.astro

@@ -30,11 +30,13 @@
 import { Font } from "astro:assets";
 import type { HTMLAttributes } from "astro/types";
 import type { Fonts } from "../fonts.ts";
+import { iconLinks } from "../meta/index.ts";
 import type { PageMeta } from "../site/index.ts";
 import MetaTags from "./MetaTags.astro";
 import RememberCampaign from "./RememberCampaign.astro";
 import RememberLocale from "./RememberLocale.astro";
 import ScrollRestore from "./ScrollRestore.astro";
+import { siteIcons } from "./site-icons.ts";
 
 interface Props {
     readonly meta: PageMeta;
@@ -65,6 +67,9 @@ if (meta.consentVendors.length > 0 && !Astro.slots.has("consent")) {
         `${meta.consentVendors.join(", ")} ${meta.consentVendors.length === 1 ? "needs" : "need"} permission, but this page has no consent banner. Pass one to Document: <ConsentBanner slot="consent" …>.`
     );
 }
+
+// Here rather than in `meta.tags`: cutting the icon to size needs the build.
+const icons = iconLinks(await siteIcons(meta.icon));
 ---
 
 <!doctype html>
@@ -76,6 +81,7 @@ if (meta.consentVendors.length > 0 && !Astro.slots.has("consent")) {
     <head>
         <slot name="head-start" />
         <MetaTags tags={meta.tags} />
+        <MetaTags tags={icons} />
         {rememberLocale && <RememberLocale />}
         {Object.entries(fonts).map(([key, font]) => (
             <Font

package/src/astro/background-video-element.ts

@@ -0,0 +1,38 @@
+// Internal to `BackgroundVideo.astro`: binds its markup to `backgroundVideo`.
+import { type BackgroundVideo, backgroundVideo } from "./background-video.ts";
+import { element } from "./element.ts";
+import { data, ref } from "./ref.ts";
+
+/**
+ * Each root's loop, kept across a re-attach: the reader's pause belongs to the
+ * video, not to one connection of the element.
+ */
+const loops = new WeakMap<HTMLElement, BackgroundVideo>();
+
+export const backgroundVideoElement = element(
+    "atlas-background-video",
+    ({ root, signal }) => {
+        const play = data(root, "play");
+        const pause = data(root, "pause");
+        const button = ref<HTMLButtonElement>(root, "[data-video-toggle]");
+        const whenPlaying = ref<HTMLElement>(root, "[data-video-playing]");
+        const whenPaused = ref<HTMLElement>(root, "[data-video-paused]");
+
+        const loop =
+            loops.get(root) ??
+            backgroundVideo({
+                onChange: ({ playing, playable }) => {
+                    // Nothing to pause where no cut suits this viewport.
+                    button.hidden = !playable;
+                    button.setAttribute("aria-label", playing ? pause : play);
+                    whenPlaying.hidden = !playing;
+                    whenPaused.hidden = playing;
+                },
+            });
+        loops.set(root, loop);
+
+        button.addEventListener("click", () => loop.toggle(), { signal });
+
+        return loop.attach(ref<HTMLVideoElement>(root, "video"));
+    }
+);

package/src/astro/background-video.ts

@@ -1,5 +1,7 @@
 /**
  * A decorative background video's playback — not its markup, and not its button.
+ * `BackgroundVideo.astro` is both, built on this; reach for this directly only
+ * for markup that component cannot write.
  *
  * In `astro/` because it reaches for `matchMedia` and a media element, which the
  * core is type-checked without.
@@ -26,7 +28,12 @@
  * quietly wrong:
  *
  * - **Reduced motion starts it paused.** A reader who asked their system for
- *   less motion should not get a full-width loop behind the headline.
+ *   less motion should not get a full-width loop behind the headline. So does
+ *   Data Saver, where the browser says so: a loop is megabytes nobody asked for.
+ * - **Not before the page has loaded.** A hero loop is the heaviest thing on
+ *   the page, and started at once it shares the connection with the poster —
+ *   usually the largest paint — and with everything else the page needs first.
+ *   It starts on `load`, unless the reader pressed play before that.
  * - **A way to stop it.** WCAG 2.2.2 asks for one on anything that moves for
  *   more than five seconds, and a loop moves forever. The control is the
  *   project's; the state it shows is this.
@@ -45,9 +52,32 @@
  * `aria-hidden="true"` and `tabindex="-1"`. `autoplay` is better left out: this
  * starts the video itself, and without this script there is no control to stop
  * it with, while with the attribute a reduced-motion reader sees the first
- * frames move before this gets to pause them. Left in, everything still works.
+ * frames move before this gets to pause them, and the download starts before
+ * the page has loaded. Left in, everything else still works. `preload="none"`
+ * or `"metadata"` keeps the browser from fetching the loop on its own.
  */
 
+/** One file of a `BackgroundVideo`, as a `<source>`. */
+export interface VideoSource {
+    readonly src: string;
+    /**
+     * With its codecs — `video/webm; codecs="vp9"` — so a browser skips what
+     * it cannot play without fetching it to find out.
+     */
+    readonly type: string;
+    /** The viewports this cut is for; the first matching source wins. */
+    readonly media?: string;
+}
+
+/** One still of a `BackgroundVideo`'s poster, as a `<picture>` source. */
+export interface VideoPoster {
+    readonly image: ImageMetadata;
+    /** The widths to cut, for `srcset`. Defaults to 960, 1440 and 1920. */
+    readonly widths?: readonly number[];
+    /** The viewports this still is for. Absent on the last, the fallback. */
+    readonly media?: string;
+}
+
 export interface BackgroundVideoState {
     /** Whether it is playing now: the element's own `paused`, inverted. */
     readonly playing: boolean;
@@ -99,6 +129,27 @@ export interface BackgroundVideo {
 
 const REDUCED_MOTION = "(prefers-reduced-motion: reduce)";
 
+/**
+ * Whether the video starts paused when the reader has not chosen: they asked
+ * their system for less motion, or for less data. Data Saver is Chromium's,
+ * the only engine that says; elsewhere this is reduced motion alone.
+ */
+function stillByDefault(): boolean {
+    const connection = (
+        navigator as Navigator & { connection?: { saveData?: boolean } }
+    ).connection;
+    return matchMedia(REDUCED_MOTION).matches || connection?.saveData === true;
+}
+
+/** Runs `then` once the page has loaded: now if it has, else on `load`. */
+function whenLoaded(then: () => void, signal: AbortSignal): void {
+    if (document.readyState === "complete") {
+        then();
+        return;
+    }
+    addEventListener("load", then, { once: true, signal });
+}
+
 /**
  * `HTMLMediaElement.NETWORK_NO_SOURCE`, as a literal.
  *
@@ -278,7 +329,19 @@ export function backgroundVideo(
                 );
             }
 
-            apply(chosen ?? !matchMedia(REDUCED_MOTION).matches);
+            if (chosen !== undefined) {
+                apply(chosen);
+            } else if (stillByDefault()) {
+                apply(false);
+            } else {
+                // Not before the page has loaded: a loop of a few megabytes
+                // started now shares the connection with the poster the reader
+                // is waiting for, and on a phone the poster loses.
+                whenLoaded(() => {
+                    // Unless the reader chose meanwhile, or it moved on.
+                    if (video === element && chosen === undefined) apply(true);
+                }, signal);
+            }
             sync();
 
             return () => {

package/src/astro/site-icons.ts

@@ -0,0 +1,61 @@
+/**
+ * The site icon, cut to size. `Document`'s, and in `astro/` because cutting
+ * needs `astro:assets`, which only exists inside the build.
+ */
+
+import { getImage } from "astro:assets";
+import type { ImageAsset } from "../image.ts";
+import type { SiteIcons } from "../meta/index.ts";
+
+/**
+ * The favicon sizes, for `rel="icon"`.
+ *
+ * 48 for the tab: a browser scales it down to 16 or 32 itself, sharply, and 48
+ * is also the smallest Google takes for a search result. 192 for everything
+ * that shows the icon large — a search result on a dense screen, an Android
+ * home screen. A browser picks between them from `sizes`, fetching one.
+ */
+const FAVICON_SIZES = [48, 192] as const;
+
+/** Apple's size for `apple-touch-icon`, which it scales down from. */
+const TOUCH_SIZE = 180;
+
+/**
+ * `icon` at `size` square, as PNG.
+ *
+ * Never larger than the source: Astro's image service does not enlarge, so a
+ * size past the source's comes back as the source, and is reported at its
+ * own width rather than the one asked for.
+ */
+async function cut(icon: ImageAsset, size: number): Promise<ImageAsset> {
+    if (size >= icon.width) return icon;
+    const image = await getImage({
+        src: icon as ImageMetadata,
+        width: size,
+        height: size,
+        format: "png",
+    });
+    return { src: image.src, width: size, height: size, format: "png" };
+}
+
+/**
+ * Every icon a page links, from the project's one square source.
+ *
+ * Cut here rather than linked as given because the source is sized for the
+ * largest use — 480px is common — and a browser fetches a favicon on every
+ * first visit, before anything it actually shows. Linked as-is, that was the
+ * same tens-of-kilobytes PNG for a 16px tab.
+ */
+export async function siteIcons(icon: ImageAsset): Promise<SiteIcons> {
+    const favicons = await Promise.all(
+        FAVICON_SIZES.map((size) => cut(icon, size))
+    );
+    return {
+        // A small source makes two sizes one; linking it twice says nothing.
+        favicons: favicons.filter(
+            (each, index) =>
+                favicons.findIndex((other) => other.src === each.src) === index
+        ),
+        touch: await cut(icon, TOUCH_SIZE),
+    };
+}

package/src/index.ts

@@ -53,6 +53,7 @@ export {
     type StoredItem,
     type StoredItemsOptions,
     storedItems,
+    withPurposes,
 } from "./analytics/storage.ts";
 export type {
     LanguageTag,

package/src/meta/index.ts

@@ -29,7 +29,6 @@ import {
     notFoundAnalytics,
 } from "../analytics/index.ts";
 import type { ResolvedLocaleMeta } from "../config.ts";
-import type { ImageAsset } from "../image.ts";
 import {
     article,
     type BreadcrumbStep,
@@ -41,7 +40,6 @@ import type { HttpsUrl } from "../url.ts";
 import type { MetaContentBase, PageKind, ThemeColor } from "./content.ts";
 import { robotsContent, warnAboutRobots } from "./robots.ts";
 import {
-    iconLinks,
     type OgImage,
     warnAboutShareImage,
     warnIfClipped,
@@ -60,8 +58,10 @@ export type { RobotsDirective, RobotsPolicy } from "./robots.ts";
 export {
     fitDescription,
     fitTitle,
+    iconLinks,
     resolveShareImage,
     type ShareImage,
+    type SiteIcons,
 } from "./share-image.ts";
 export type { MetaTag } from "./tag.ts";
 export type { SiteVerification } from "./verification.ts";
@@ -153,8 +153,6 @@ interface MetaInputDerived<L extends string> extends ChromeInput {
  * from the chrome that they left.
  */
 export interface ChromeInput {
-    /** The site's square icon, used for every icon link. */
-    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`.
@@ -184,18 +182,18 @@ export interface DocumentTags {
 }
 
 /**
- * What the browser dresses its own furniture with: the tab's icon, the tint of
- * the address bar, and which schemes the page renders form controls for.
+ * What the browser dresses its own furniture with: the tint of the address
+ * bar, and which schemes the page renders form controls for. The tab's icon is
+ * furniture too, but it has to be cut to size first, which only the build can
+ * do: `Document` emits it, from `PageMeta.icon`.
  *
  * Pulled out of `buildMeta` because the 404 needs exactly this and nothing else
  * around it. Sharing the code is the point rather than a convenience: these are
- * the tags a reader sees *as* the site — a 404 with a different tab icon looks
- * like it came from somewhere else, which is the opposite of what a 404 is for —
- * and two copies of a four-branch block is how one of them quietly stops
- * matching the other.
+ * the tags a reader sees *as* the site, and two copies of a four-branch block
+ * is how one of them quietly stops matching the other.
  */
 function chromeTags(input: ChromeInput): MetaTag[] {
-    const tags: MetaTag[] = [...iconLinks(input.icon)];
+    const tags: MetaTag[] = [];
 
     if (input.colorScheme !== undefined) {
         tags.push(meta({ name: "color-scheme", content: input.colorScheme }));

package/src/meta/share-image.ts

@@ -222,26 +222,39 @@ export function resolveShareImage(
 }
 
 /**
- * The icon links: one asset, two `rel`s.
+ * The site icon, cut to the sizes its readers ask for — see `siteIcons` in
+ * `astro/`, which cuts them from the one square source a project gives.
+ */
+export interface SiteIcons {
+    /** For `rel="icon"`, smallest first: the tab's, and the search result's. */
+    readonly favicons: readonly ImageAsset[];
+    /** For `apple-touch-icon`, which Apple scales from 180. */
+    readonly touch: ImageAsset;
+}
+
+/**
+ * The icon links: each favicon, and the touch icon.
  *
- * Browsers read `icon`, Apple reads `apple-touch-icon` and scales it, and both
- * point at the same file — so they are built together rather than left to a
- * layout to remember the second one. `sizes` is stated so a browser need not
- * fetch the file to find out what it is choosing between.
+ * Built together rather than left to a layout to remember the second `rel`.
+ * `sizes` is stated so a browser picks without fetching each file to find out
+ * what it is choosing between — which, with the source served as-is, was a
+ * 480px PNG of tens of kilobytes for a 16px tab.
  *
  * The href stays as written. Unlike `og:image` these are read by a browser that
  * already has the page, so root-relative is correct and making it absolute would
  * only hard-code the origin.
  */
-export function iconLinks(icon: ImageAsset): MetaTag[] {
-    const mime = imageMime(icon.format);
-    const attrs = {
-        href: icon.src,
-        sizes: `${icon.width}x${icon.height}`,
-        ...(mime !== undefined ? { type: mime } : {}),
+export function iconLinks(icons: SiteIcons): MetaTag[] {
+    const attrs = (icon: ImageAsset) => {
+        const mime = imageMime(icon.format);
+        return {
+            href: icon.src,
+            sizes: `${icon.width}x${icon.height}`,
+            ...(mime !== undefined ? { type: mime } : {}),
+        };
     };
     return [
-        link({ rel: "icon", ...attrs }),
-        link({ rel: "apple-touch-icon", ...attrs }),
+        ...icons.favicons.map((icon) => link({ rel: "icon", ...attrs(icon) })),
+        link({ rel: "apple-touch-icon", ...attrs(icons.touch) }),
     ];
 }

package/src/site/create.ts

@@ -326,18 +326,17 @@ export function createSite<
             // Umami only, tagged so the misses read on their own — the point
             // of measuring this page is finding a redirect somebody forgot,
             // not counting the people who mistype. See `notFoundAnalytics`.
-            //
-            // `checkedIcon()` rather than `project.icon`: the 404 is held to the
-            // same square-and-PNG rules as every other page. It is also the one
-            // page that could plausibly render before any other, so letting it
-            // read the icon unchecked would move where a bad one is caught.
             tags: buildNotFoundMeta({
                 title,
                 analytics: project.analytics,
-                icon: checkedIcon(),
                 themeColor: project.themeColor,
                 colorScheme: project.colorScheme,
             }),
+            // `checkedIcon()` rather than `project.icon`: the 404 is held to the
+            // same square-and-PNG rules as every other page. It is also the one
+            // page that could plausibly render before any other, so letting it
+            // read the icon unchecked would move where a bad one is caught.
+            icon: checkedIcon(),
             // Nothing. The body channel exists for Tag Manager's `<noscript>`,
             // and no Google tag reaches this page.
             bodyTags: [],
@@ -407,7 +406,6 @@ export function createSite<
             ),
             siteName: project.siteName,
             twitterSite: project.twitterSite,
-            icon: checkedIcon(),
             verification: project.verification,
             analytics: project.analytics,
             llmsUrl,
@@ -419,6 +417,7 @@ export function createSite<
             dir: localeMeta[locale].dir,
             tags: document.head,
             bodyTags: document.body,
+            icon: checkedIcon(),
             consentVendors: consentVendors(project.analytics),
         };
     }

package/src/site/page.ts

@@ -1,3 +1,4 @@
+import type { ImageAsset } from "../image.ts";
 import type { MetaContent, MetaTag } from "../meta/index.ts";
 import type { HttpsUrl, UrlPath } from "../url.ts";
 
@@ -65,6 +66,12 @@ export interface PageMeta {
      * both, and cannot put either in the other's place.
      */
     readonly bodyTags: MetaTag[];
+    /**
+     * The site's square icon, as the project gave it. `Document` cuts it to
+     * each size a browser asks for and links those; the source itself, often
+     * hundreds of pixels across, is never linked.
+     */
+    readonly icon: ImageAsset;
     /** The vendors that need a consent banner on this page; `Document` fails without one. */
     readonly consentVendors: readonly string[];
 }