@escape-game-over/atlas 0.1.15 → 0.1.16

package/docs/client-scripts.md

@@ -1,7 +1,7 @@
 # Client scripts: what Atlas owns in the browser, and what it refuses to
 
 Everything else in this package runs at build time and emits text. This is the
-other half: seven modules under `src/astro/` that run in a reader's browser, and
+other half: the modules under `src/astro/` that run in a reader's browser, and
 one rule they all keep.
 
 **They draw nothing.**
@@ -25,15 +25,24 @@ It sets no class, no style and no `aria`, which is where the choices live. It
 also never *finds* an element: it is handed the ones a project looked up, so no
 attribute name in this package has to be matched by any consumer.
 
-| Module                 | Owns                                                           | Leaves to the project                             |
-| ---------------------- | -------------------------------------------------------------- | ------------------------------------------------- |
-| `./astro/carousel`     | which slide is current: modulo, swipe, autoplay, the move lock | the transform, dots, arrows, `aria`               |
-| `./astro/filters`      | which items match, and what the address bar says               | every DOM read and write, and the markup contract |
-| `./astro/filters-view` | the two DOM writes every filtered list turned out to share     | finding the elements, and everything else drawn   |
-| `./astro/consent`      | remembering an answer, expiring it, handing it to Google       | the banner — its wording, its buttons, its law    |
-| `./astro/element`      | the two lifetimes a custom element has, and one abort signal   | what the element is and does                      |
-| `./astro/dom`          | scoped `one`/`all` lookups, typed                              | the selectors                                     |
-| `./astro/dev-log`      | a panel a failed wiring can announce itself in, in dev only    | calling it behind `import.meta.env.DEV`           |
+`youtube` is the other exception, and the one that cannot be avoided: the player
+*is* the behaviour, so something has to put an iframe in the page. What it sets
+on it has no taste in it — the address, the title, the permissions, full screen,
+the referrer policy — and everything that does, classes above all, comes from the
+caller through a callback. It too is handed the button and the box rather than
+finding them.
+
+| Module                     | Owns                                                           | Leaves to the project                             |
+| -------------------------- | -------------------------------------------------------------- | ------------------------------------------------- |
+| `./astro/carousel`         | which slide is current: modulo, swipe, autoplay, the move lock | the transform, dots, arrows, `aria`               |
+| `./astro/filters`          | which items match, and what the address bar says               | every DOM read and write, and the markup contract |
+| `./astro/filters-view`     | the two DOM writes every filtered list turned out to share     | finding the elements, and everything else drawn   |
+| `./astro/youtube`          | the swap from poster to player, on the click and not before    | the poster, the button, the iframe's classes      |
+| `./astro/background-video` | playing or paused, playable or not, and which cut is loaded    | the play/pause control, its icons and its label   |
+| `./astro/consent`          | remembering an answer, expiring it, handing it to Google       | the banner — its wording, its buttons, its law    |
+| `./astro/element`          | the two lifetimes a custom element has, and one abort signal   | what the element is and does                      |
+| `./astro/dom`              | scoped `one`/`all` lookups, typed                              | the selectors                                     |
+| `./astro/dev-log`          | a panel a failed wiring can announce itself in, in dev only    | calling it behind `import.meta.env.DEV`           |
 
 `./astro/consent` is the only one of these with a build-time half. Its
 `consentApplies()` reports whether there is a Google tag to consent to, which a
@@ -53,8 +62,10 @@ the options, and when one drifts nothing reports it — a listener added without
 its twin simply survives teardown.
 
 ```ts
-const detach = slider.attach(viewport);   // carousel: one element
-const detach = list.attach();             // filters: no element, only popstate
+const detach = slider.attach(viewport);       // carousel: one element
+const detach = list.attach();                 // filters: no element, only popstate
+const detach = loop.attach(video);            // background-video: the <video>
+const detach = trailer.attach(button, box);   // youtube: what is pressed, what it replaces
 ```
 
 `AtlasElement` says the same thing in the shape a custom element needs, because
@@ -111,7 +122,7 @@ than an item that silently never matches.
 
 | Kind     | State           | Item value      | Matches when                                     | In the URL                      | History |
 | -------- | --------------- | --------------- | ------------------------------------------------ | ------------------------------- | ------- |
-| `text`   | the query       | searchable text | folded query is a substring; empty keeps all     | `?q=…`, dropped if empty        | replace |
+| `text`   | the query       | searchable text | every folded query word appears; empty keeps all | `?q=…`, dropped if empty        | replace |
 | `choice` | one value, `""` | one, or several | the item holds the chosen one; `""` keeps all    | `?category=…`, dropped if empty | push    |
 | `flag`   | boolean         | boolean         | off keeps all; on keeps only items that carry it | `?featured=1`, absent when off  | push    |
 
@@ -159,6 +170,41 @@ parameters or comma-joined) that nothing has needed yet.
 
 `param` is optional. A field without one is state-only and never reaches the URL.
 
+### Facet counts: `matchedWithout`
+
+A dropdown that says how many results each option would give needs a different
+set from `matched`: every field *except its own*. Counted against `matched`, a
+facet whose value is already picked can only ever offer that value — every other
+option reads zero, because the items holding them were just filtered out by the
+very field being asked about.
+
+```ts
+onChange({ matched }) {
+    const rest = list.matchedWithout("country");
+    for (const option of countryOptions) {
+        const value = option.dataset.choice;
+        const count = rows.filter(
+            (row) => rest.has(row.key) && row.country === value
+        ).length;
+        // …the project writes `count` wherever its design puts it
+    }
+}
+```
+
+It runs the list's own matcher — folding, tokens, several-valued choices, flags —
+so a count cannot drift from the list beneath it. That drift is not
+hypothetical: a consumer wrote its own predicate for these counts, folding
+without trimming and matching the query as one run, and it agreed with the list
+only until the list learned to match word by word. Nothing reported it; the
+counts were simply wrong.
+
+Computed on first ask and kept until the state next moves, so a render that asks
+once per option pays one pass per field. A field that is not narrowing anything —
+an empty query, no choice, a flag that is off — answers with `matched` itself.
+Grouping the survivors by option stays with the caller, which already holds each
+item's values; it is safe to call from `onChange`, which never runs during
+construction.
+
 ### The four URL decisions
 
 1. **Replace while typing, push on a choice.** An input emits an event per

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.15",
+    "version": "0.1.16",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -15,6 +15,7 @@
         ".": "./src/index.ts",
         "./astro": "./src/astro/index.ts",
         "./astro/images": "./src/astro/images.ts",
+        "./astro/background-video": "./src/astro/background-video.ts",
         "./astro/carousel": "./src/astro/carousel.ts",
         "./astro/consent": "./src/astro/consent.ts",
         "./astro/dev-log": "./src/astro/dev-log.ts",
@@ -22,7 +23,8 @@
         "./astro/element": "./src/astro/element.ts",
         "./astro/filters": "./src/astro/filters.ts",
         "./astro/filters-view": "./src/astro/filters-view.ts",
-        "./astro/meta-tags": "./src/astro/MetaTags.astro"
+        "./astro/meta-tags": "./src/astro/MetaTags.astro",
+        "./astro/youtube": "./src/astro/youtube.ts"
     },
     "bin": {
         "atlas": "bin/use-project.mjs"
@@ -53,8 +55,8 @@
         "typescript": ">=5"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.5.12",
-        "@types/node": "26.5.0",
+        "@biomejs/biome": "2.5.13",
+        "@types/node": "26.5.1",
         "@vitest/coverage-istanbul": "5.0.0",
         "astro": "7.3.2",
         "typescript": "6.0.3",

package/src/astro/background-video.ts

@@ -0,0 +1,290 @@
+/**
+ * A decorative background video's playback — not its markup, and not its button.
+ *
+ * In `astro/` because it reaches for `matchMedia` and a media element, which the
+ * core is type-checked without.
+ *
+ * **It draws nothing.** No icon, no label, no `hidden`, no `aria`. It owns
+ * whether the video is playing, whether there is anything to play, and which of
+ * its cuts is loaded, and calls `onChange` when the first two move; the project
+ * draws its own play/pause control from that and points the control at
+ * `toggle`.
+ *
+ * ```ts
+ * const loop = backgroundVideo({
+ *     onChange: ({ playing, playable }) => {
+ *         button.hidden = !playable;
+ *         button.setAttribute("aria-label", playing ? pauseLabel : playLabel);
+ *     },
+ * });
+ *
+ * button.addEventListener("click", () => loop.toggle(), { signal });
+ * const detach = loop.attach(video);
+ * ```
+ *
+ * What it owns is the handful of things every looping hero needs and most get
+ * 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.
+ * - **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.
+ * - **No control over nothing.** A `<source media>` that matches no viewport
+ *   leaves the element empty, and a pause button beside an empty element pauses
+ *   nothing. `playable` says so, and the caller hides it.
+ * - **The right cut after a rotation.** A browser chooses among `<source
+ *   media>` once, when the element loads, and never again — so a phone turned
+ *   sideways keeps the portrait cut, cropped across a landscape screen, until
+ *   something reloads it.
+ * - **The reader's pause surviving that reload.** A reload resets the element
+ *   to its markup, and markup that says `autoplay` starts again the video they
+ *   had just stopped.
+ *
+ * The markup wants `muted`, `loop` and `playsinline`, and — being decoration —
+ * `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.
+ */
+
+export interface BackgroundVideoState {
+    /** Whether it is playing now: the element's own `paused`, inverted. */
+    readonly playing: boolean;
+    /**
+     * Whether a source was chosen for this viewport.
+     *
+     * False when no `<source media>` matched, or every one that did failed —
+     * there is nothing on screen to pause, so the control has nothing to do
+     * and should not be offered.
+     */
+    readonly playable: boolean;
+}
+
+export interface BackgroundVideoOptions {
+    /**
+     * Called once on `attach`, and then whenever `playing` or `playable` moves.
+     *
+     * Once on `attach` although nothing moved, because the control's first
+     * state is only known then: whether the viewport matched a source and
+     * whether reduced motion held it still are both read from the page, and the
+     * markup cannot say either in advance. Never called for an event that
+     * changed neither, so a caller can redraw unconditionally.
+     */
+    readonly onChange: (state: BackgroundVideoState) => void;
+}
+
+export interface BackgroundVideo {
+    readonly state: BackgroundVideoState;
+    /** Plays, as the reader's choice: it outlives a reload and a re-attach. */
+    play(): void;
+    /** Pauses, as the reader's choice: it outlives a reload and a re-attach. */
+    pause(): void;
+    /** Whichever of the two the video is not doing now. What a button wants. */
+    toggle(): void;
+    /**
+     * Takes over one `<video>`, and returns the undo.
+     *
+     * Applies the starting state — the reader's earlier choice if they made
+     * one, otherwise playing unless reduced motion is set — and starts
+     * listening to the element and to each of its sources' media queries. The
+     * undo stops listening and leaves the video as it is.
+     *
+     * Before `attach` and after the undo, `play`, `pause` and `toggle` do
+     * nothing: there is no element to act on. The reader's choice is kept
+     * across the gap, as `carousel` keeps its index.
+     */
+    attach(video: HTMLVideoElement): () => void;
+}
+
+const REDUCED_MOTION = "(prefers-reduced-motion: reduce)";
+
+/**
+ * `HTMLMediaElement.NETWORK_NO_SOURCE`, as a literal.
+ *
+ * The state an element settles in when it has run out of sources to try —
+ * none matched, or each that did failed. Written out so nothing global is read
+ * at import, which is when a module like this must do nothing at all.
+ */
+const NETWORK_NO_SOURCE = 3;
+
+/**
+ * The media element events after which either half of the state may differ.
+ *
+ * `emptied` is a reload beginning, `loadstart` a source having been chosen.
+ * `error` is listened to separately, in the capture phase — see `attach`.
+ */
+const EVENTS = ["play", "pause", "emptied", "loadstart"] as const;
+
+export function backgroundVideo(
+    options: BackgroundVideoOptions
+): BackgroundVideo {
+    const { onChange } = options;
+
+    /** The element while attached, and nothing otherwise. */
+    let video: HTMLVideoElement | undefined;
+
+    /**
+     * What the reader chose, once they have chosen.
+     *
+     * Undefined until they press something, and then it outranks reduced
+     * motion: a reader who asked for less motion and then pressed play has
+     * answered the question for this video. Kept across a detach, so an element
+     * moved in the DOM comes back as the reader left it.
+     */
+    let chosen: boolean | undefined;
+
+    let state: BackgroundVideoState = { playing: false, playable: false };
+
+    /**
+     * Whether this attachment has announced yet.
+     *
+     * The first read of an attachment is announced even if it matches the last
+     * state, since the control has never been drawn from it. A flag rather
+     * than a forced call at the end of `attach`, because applying the starting
+     * state can fire `play` on its own — and then the control was told twice.
+     */
+    let fresh = false;
+
+    /** Reads the element, and announces if anything moved. */
+    const sync = (): void => {
+        if (video === undefined) return;
+        const next: BackgroundVideoState = {
+            playing: !video.paused,
+            // Both halves, because neither alone is true. `currentSrc` is empty
+            // until a source is chosen, but is not reliably cleared when a
+            // reload then finds none; `networkState` says an element has run
+            // out of sources, but passes through that state for a moment at
+            // the start of every reload too.
+            playable:
+                video.currentSrc !== "" &&
+                video.networkState !== NETWORK_NO_SOURCE,
+        };
+        if (
+            !fresh &&
+            next.playing === state.playing &&
+            next.playable === state.playable
+        ) {
+            return;
+        }
+        fresh = false;
+        state = next;
+        onChange(state);
+    };
+
+    /**
+     * Puts the element in the wanted state, and makes it stay there.
+     *
+     * `autoplay` is the half that stays. A reload resets the element to paused
+     * and then consults the attribute, so keeping it equal to what is wanted is
+     * what carries a reader's pause — or their play — across one.
+     */
+    const apply = (playing: boolean): void => {
+        if (video === undefined) return;
+        video.autoplay = playing;
+        if (playing) {
+            // Refused when a browser will not autoplay even a muted video —
+            // iOS in low-power mode is the one people meet. The element stays
+            // paused, and the control should say "play".
+            video.play().catch(() => sync());
+        } else {
+            video.pause();
+        }
+    };
+
+    const choose = (playing: boolean): void => {
+        if (video === undefined) return;
+        chosen = playing;
+        apply(playing);
+    };
+
+    return {
+        get state() {
+            return state;
+        },
+        play: () => choose(true),
+        pause: () => choose(false),
+        // From the element rather than from `chosen`. The control shows what
+        // the video is doing, so pressing it must do the opposite of that —
+        // including when the browser paused it rather than the reader.
+        toggle: () => {
+            if (video !== undefined) choose(video.paused);
+        },
+
+        attach(element) {
+            video = element;
+            fresh = true;
+            const listeners = new AbortController();
+            const { signal } = listeners;
+
+            // What decorative means, and what every browser requires before it
+            // will start a video nobody pressed play on.
+            element.muted = true;
+
+            for (const type of EVENTS) {
+                element.addEventListener(type, () => sync(), { signal });
+            }
+            // A `<source>` that is skipped or fails fires `error` at itself, and
+            // `error` does not bubble. The capture phase passes through the
+            // video on the way down, so this hears every source's failure —
+            // the last of which is how an element says it found nothing.
+            element.addEventListener("error", () => sync(), {
+                capture: true,
+                signal,
+            });
+
+            const sources = [...element.querySelectorAll("source")];
+
+            /**
+             * Which source a browser would choose now: the first whose media
+             * matches and whose type it can play.
+             *
+             * Compared before reloading rather than reloading on every change,
+             * because not every crossing changes the answer. A later source's
+             * query flipping while an earlier one still matches picks the same
+             * file, and a reload would only restart the loop from its first
+             * frame for nothing.
+             */
+            const choice = (): number =>
+                sources.findIndex(
+                    (source) =>
+                        (source.media === "" ||
+                            matchMedia(source.media).matches) &&
+                        (source.type === "" ||
+                            element.canPlayType(source.type) !== "")
+                );
+
+            let chosenSource = choice();
+            // One listener per distinct query: two sources sharing one would
+            // otherwise reload twice for a single rotation.
+            const queries = new Set(
+                sources
+                    .map((source) => source.media)
+                    .filter((media) => media !== "")
+            );
+            for (const media of queries) {
+                matchMedia(media).addEventListener(
+                    "change",
+                    () => {
+                        const next = choice();
+                        if (next === chosenSource) return;
+                        chosenSource = next;
+                        // `emptied` and then `loadstart` follow, and `sync`
+                        // hears both — so the control follows without a call
+                        // from here.
+                        element.load();
+                    },
+                    { signal }
+                );
+            }
+
+            apply(chosen ?? !matchMedia(REDUCED_MOTION).matches);
+            sync();
+
+            return () => {
+                listeners.abort();
+                video = undefined;
+            };
+        },
+    };
+}

package/src/astro/filters.ts

@@ -60,7 +60,7 @@
  *
  * The kinds are closed, and deliberately few:
  *
- * - `text` — free entry, folded and substring-matched. The search box.
+ * - `text` — free entry, folded and matched word by word. The search box.
  * - `choice` — one of a set, or none. Tabs, a `<select>`, a radio group. The
  *   control picks one; an item may hold several and answer to any — see
  *   `ItemValue`.
@@ -200,6 +200,29 @@ export interface SetOptions {
 export interface Filters<F extends FieldMap> {
     readonly state: FilterState<F>;
     readonly matched: ReadonlySet<string>;
+    /**
+     * The keys that survive every field *except* this one.
+     *
+     * The question a facet asks of its own options: how many results would
+     * picking each of them give, with everything else as it stands. Counted
+     * against `matched` instead, a dropdown whose value is already set could
+     * only ever offer that value — every other option would read zero, since
+     * the items holding it have just been filtered out by the very field being
+     * asked about.
+     *
+     * The same matcher as `matched`, folding and tokens included, rather than a
+     * second one in the caller. A facet count computed by a hand-written
+     * predicate drifts from the list it is counting the moment either changes —
+     * a count of four above a list of three — and nothing reports it.
+     *
+     * Computed on first ask and kept until the state next moves, so a render
+     * that asks once per option pays one pass per field rather than one per
+     * option. A field that is not narrowing anything answers with `matched`
+     * itself: without it, the rest is exactly what already matched.
+     *
+     * Safe to call from `onChange`, which never runs during construction.
+     */
+    matchedWithout(field: keyof F): ReadonlySet<string>;
     set<K extends keyof F>(
         field: K,
         value: StateValue<F[K]>,
@@ -315,6 +338,17 @@ export function filters<const F extends FieldMap>(
     let state = blank();
     let matched: ReadonlySet<string> = new Set(items.map((item) => item.key));
 
+    /**
+     * Each `text` field's query, folded and split, for the current state.
+     *
+     * Folded once per state rather than once per item. The other kinds compare
+     * values as they are, so there is nothing to prepare for them.
+     */
+    let queries = new Map<string, readonly string[]>();
+
+    /** `matchedWithout` answers for the current state. Emptied when it moves. */
+    const without = new Map<string, ReadonlySet<string>>();
+
     /**
      * Whether the URL is this instance's to write.
      *
@@ -324,61 +358,74 @@ export function filters<const F extends FieldMap>(
      */
     let attached = false;
 
+    /**
+     * Whether a field is narrowing anything in the current state.
+     *
+     * An empty query, no choice and a flag that is off all keep every item —
+     * the flag above all, which keeps everything rather than keeping the items
+     * that are *not* flagged. See `Field`.
+     */
+    const narrows = (name: keyof F & string): boolean => {
+        const kind = fields[name]?.kind;
+        if (kind === "text") return (queries.get(name) ?? []).length > 0;
+        if (kind === "choice") return state[name] !== "";
+        return state[name] === true;
+    };
+
+    /**
+     * Whether one item survives every field but `except`, in the current state.
+     *
+     * The one matcher. `matched` is this with nothing excepted and
+     * `matchedWithout` is this with one field excepted, so a facet count and
+     * the list it counts cannot disagree about what a match is.
+     */
+    function passes(item: FilterItem<F>, except?: keyof F & string): boolean {
+        for (const name of names) {
+            if (name === except || !narrows(name)) continue;
+            const kind = fields[name]?.kind;
+            if (kind === "text") {
+                // Every token must appear, not one run that must appear whole.
+                // A haystack is several things joined (a title, plus its
+                // category, plus its summary), and the order they were joined
+                // in is an accident of whoever wrote the template. Matching
+                // the query as one run made that accident load-bearing:
+                // against "Copper Kettle" in the Kitchen category, "kettle
+                // kitchen" found nothing while "kettle" alone worked, and the
+                // first is what someone narrowing a list types.
+                const tokens = queries.get(name) ?? [];
+                const haystack = haystacks.get(item.key)?.get(name) ?? "";
+                if (!tokens.every((token) => haystack.includes(token))) {
+                    return false;
+                }
+            } else if (kind === "choice") {
+                // An item may sit in several categories while the control
+                // still picks one — see `ItemValue`. One value is the same
+                // question asked of a set of one.
+                const wanted = state[name] as string;
+                const held = item.values[name];
+                const holds = Array.isArray(held)
+                    ? held.includes(wanted)
+                    : held === wanted;
+                if (!holds) return false;
+            } else if (item.values[name] !== true) {
+                return false;
+            }
+        }
+        return true;
+    }
+
     function recompute(): void {
-        // The query folded once per render rather than once per item. The other
-        // kinds compare values as they are, so there is nothing to prepare.
-        // Split into tokens, all of which must appear — not one substring that
-        // must appear whole. A haystack is several things joined (a title, plus
-        // its category, plus its summary), and the order they were joined in is
-        // an accident of whoever wrote the template. Matching the query as one
-        // run made that accident load-bearing: against "Copper Kettle" in the
-        // Kitchen category, "kettle kitchen" found nothing while "kettle" alone
-        // worked, and the first is what someone narrowing a list types.
-        const queries = new Map<string, string[]>();
+        queries = new Map();
         for (const name of names) {
             if (fields[name]?.kind !== "text") continue;
             const folded = fold(state[name] as string);
             queries.set(name, folded === "" ? [] : folded.split(/\s+/));
         }
+        without.clear();
 
         const next = new Set<string>();
         for (const item of items) {
-            let hit = true;
-            for (const name of names) {
-                const kind = fields[name]?.kind;
-                if (kind === "text") {
-                    const tokens = queries.get(name) ?? [];
-                    if (tokens.length === 0) continue;
-                    const haystack = haystacks.get(item.key)?.get(name) ?? "";
-                    if (!tokens.every((token) => haystack.includes(token))) {
-                        hit = false;
-                        break;
-                    }
-                } else if (kind === "choice") {
-                    const wanted = state[name] as string;
-                    if (wanted === "") continue;
-                    // An item may sit in several categories while the control
-                    // still picks one — see `ItemValue`. One value is the same
-                    // question asked of a set of one.
-                    const held = item.values[name];
-                    const holds = Array.isArray(held)
-                        ? held.includes(wanted)
-                        : held === wanted;
-                    if (!holds) {
-                        hit = false;
-                        break;
-                    }
-                } else {
-                    // A flag off is not a filter: it keeps everything, rather
-                    // than keeping the items that are *not* flagged. See `Field`.
-                    if (state[name] !== true) continue;
-                    if (item.values[name] !== true) {
-                        hit = false;
-                        break;
-                    }
-                }
-            }
-            if (hit) next.add(item.key);
+            if (passes(item)) next.add(item.key);
         }
         matched = next;
     }
@@ -467,6 +514,20 @@ export function filters<const F extends FieldMap>(
             return matched;
         },
 
+        matchedWithout(field) {
+            const name = field as keyof F & string;
+            if (!narrows(name)) return matched;
+            const cached = without.get(name);
+            if (cached !== undefined) return cached;
+
+            const rest = new Set<string>();
+            for (const item of items) {
+                if (passes(item, name)) rest.add(item.key);
+            }
+            without.set(name, rest);
+            return rest;
+        },
+
         set(field, value, setOptions) {
             const name = field as keyof F & string;
             // Compared as everything downstream will read it, not as it arrived.

package/src/astro/youtube.ts

@@ -0,0 +1,160 @@
+/**
+ * A YouTube video that loads nothing from YouTube until a reader asks for it.
+ *
+ * In `astro/` because it listens for a click and makes an element, which the
+ * core is type-checked without.
+ *
+ * An embedded player is the heaviest thing most pages carry that nobody asked
+ * for: the iframe fetches the player, its scripts and its tracking on load, once
+ * per video, whether or not anyone presses play. So the page renders a poster
+ * and a button — the project's own markup, drawn however it likes — and this
+ * swaps the player in on the click, with `autoplay=1` so that the one press the
+ * reader already made is the one that starts it.
+ *
+ * ```ts
+ * const trailer = youtubeEmbed({
+ *     id: "dQw4w9WgXcQ",
+ *     title: "Trailer: The Blue Room",
+ *     frame: (iframe) => {
+ *         iframe.className = "absolute inset-0 h-full w-full";
+ *     },
+ * });
+ *
+ * const detach = trailer.attach(button, poster);
+ * ```
+ *
+ * **It draws one element, and decides nothing about how it looks.** Unlike
+ * `carousel` this has to put something into the page — the player is the
+ * behaviour — so it is the second exception to the rule in
+ * `docs/client-scripts.md`, after `filters-view`, and it is drawn as narrowly.
+ * What it sets on the iframe is what every embed needs and has no taste in it:
+ * the address, the title, the permissions, full screen, the referrer policy.
+ * Classes, size and position are the caller's, through `frame`.
+ *
+ * Kept apart from `videoObject` in `jsonld/video.ts` although both are about a
+ * YouTube video: that one describes it to a crawler at build time, this plays
+ * it in a browser, and the only thing they share is an id the caller already
+ * holds. They do not even want the same host — Google reads the `youtube.com`
+ * player as `embedUrl`, and a reader is better served by `youtube-nocookie.com`.
+ */
+
+export interface YouTubeEmbedOptions {
+    /**
+     * The video's id: what follows `v=` in a watch link, or `youtu.be/`.
+     *
+     * Checked at construction, because the tempting mistake is pasting the
+     * whole link, and that fails in the one place nobody looks — inside the
+     * player, after the click, as YouTube's own "video unavailable".
+     */
+    readonly id: string;
+    /**
+     * The iframe's title, which is its accessible name.
+     *
+     * Required and refused when blank: a frame without one is announced as
+     * "frame" and nothing else, and a screen-reader user tabbing into the
+     * player has no way to tell which video it is.
+     */
+    readonly title: string;
+    /**
+     * Anything the project wants on the iframe — classes, above all.
+     *
+     * Called once, after everything this module sets and before the iframe is
+     * in the page, so what it writes is the last word and nothing is drawn
+     * unstyled first.
+     */
+    readonly frame?: (iframe: HTMLIFrameElement) => void;
+}
+
+export interface YouTubeEmbed {
+    /**
+     * Swaps `container`'s contents for the player when `trigger` is clicked,
+     * and returns the undo.
+     *
+     * Two elements rather than one, because they are different things: the
+     * trigger is the button a reader presses, and the container is what the
+     * player replaces — usually the poster and that same button together. A
+     * click anywhere in the container would be simpler and wrong, since a
+     * caption link or a credit inside it would then start the video.
+     *
+     * Once only. The button is gone with the poster, and a second player in
+     * the same box would be two videos playing over each other.
+     *
+     * The undo removes the listener and nothing else. A player already loaded
+     * stays where it is — taking it out would stop a video someone is
+     * watching, and a page swap removes it anyway.
+     */
+    attach(trigger: HTMLElement, container: Element): () => void;
+}
+
+/**
+ * The shape of a YouTube video id.
+ *
+ * Eleven characters from the URL-safe base64 alphabet, which is what every id
+ * has been. A shape check rather than a lookup: it cannot say the video exists,
+ * only that what was handed over is an id and not a link.
+ */
+const VIDEO_ID = /^[\w-]{11}$/;
+
+/**
+ * The permissions YouTube's own embed code asks for.
+ *
+ * `autoplay` is the one that matters here: without it the `autoplay=1` in the
+ * address is refused, and the reader who pressed play gets a second play
+ * button to press.
+ */
+const ALLOW =
+    "accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share";
+
+export function youtubeEmbed(options: YouTubeEmbedOptions): YouTubeEmbed {
+    const { id, title, frame } = options;
+
+    if (!VIDEO_ID.test(id)) {
+        throw new Error(
+            `"${id}" is not a YouTube video id — expected the id alone, as it appears after "v=" or "youtu.be/", not a link.`
+        );
+    }
+    if (title.trim() === "") {
+        throw new Error(
+            `The YouTube embed for "${id}" has no title. It is the frame's accessible name — without one a screen reader announces "frame" and nothing else.`
+        );
+    }
+
+    // `youtube-nocookie.com` rather than `youtube.com`: the same player, which
+    // sets no cookie until the video is played — and here it is only ever
+    // loaded to be played, so nothing is lost by it.
+    const src = `https://www.youtube-nocookie.com/embed/${id}?autoplay=1`;
+
+    return {
+        attach(trigger, container) {
+            const listeners = new AbortController();
+
+            trigger.addEventListener(
+                "click",
+                () => {
+                    const iframe =
+                        container.ownerDocument.createElement("iframe");
+                    iframe.src = src;
+                    iframe.title = title;
+                    iframe.allow = ALLOW;
+                    iframe.allowFullscreen = true;
+                    // Stated rather than inherited. YouTube refuses to play an
+                    // embed that arrives with no referrer at all, and a site
+                    // sending `Referrer-Policy: no-referrer` would otherwise get
+                    // a player that loads and shows an error in place of the
+                    // video. This is the policy YouTube's own embed code sets.
+                    iframe.referrerPolicy = "strict-origin-when-cross-origin";
+                    frame?.(iframe);
+
+                    container.replaceChildren(iframe);
+                    // The button that had focus has just left the page, which
+                    // drops a keyboard reader back at the top of the document.
+                    // The player is where they were, and what they asked for.
+                    iframe.focus();
+                },
+                { once: true, signal: listeners.signal }
+            );
+
+            return () => listeners.abort();
+        },
+    };
+}