@escape-game-over/atlas 0.1.15 → 0.1.17

package/README.md

@@ -296,16 +296,18 @@ const careers: WhenEnabled<typeof site, "careers", Careers> = { ats: "…" };  /
 ```jsonc
 "exports": {
   ".":                  "./src/index.ts",
-  "./astro":            "./src/astro/index.ts",
-  "./astro/images":     "./src/astro/images.ts",
-  "./astro/carousel":   "./src/astro/carousel.ts",
-  "./astro/consent":    "./src/astro/consent.ts",
-  "./astro/dev-log":    "./src/astro/dev-log.ts",
-  "./astro/dom":        "./src/astro/dom.ts",
-  "./astro/element":    "./src/astro/element.ts",
-  "./astro/filters":    "./src/astro/filters.ts",
-  "./astro/meta-tags":  "./src/astro/MetaTags.astro",
-  "./astro/filters-view": "./src/astro/filters-view.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",
+  "./astro/dom":              "./src/astro/dom.ts",
+  "./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/youtube":          "./src/astro/youtube.ts"
 }
 ```
 
@@ -322,7 +324,8 @@ opposite: it runs inside the build, from a page, and is unusable from a config.
 Merging them breaks whichever caller loads first.
 
 The rest of `astro/` is the browser half — `carousel`, `filters`, `filters-view`,
-`consent`, `element`, `dom`, `dev-log` — which runs in a reader's browser rather
+`youtube`, `background-video`, `consent`, `element`, `dom`, `dev-log` — which
+runs in a reader's browser rather
 than in the build, and is separate again for the same reason: none of it can be
 reached from a config, and none of it draws. See
 [`docs/client-scripts.md`](docs/client-scripts.md).

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,25 @@ 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                        |
+| `./astro/filters-view`     | the two DOM writes every filtered list turned out to share     | finding the elements, and everything else drawn |
+| `./astro/markup`           | the attributes a template writes and a script reads, typed     | naming the roles, and everything done with them |
+| `./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 +63,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 +123,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 +171,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
@@ -316,17 +363,208 @@ filters({ … }) + searchBox + hideEmpty  // the roll-up gone too
 A page whose markup wants a class instead of `hidden`, or removal from the DOM,
 skips the helper and writes it in `onChange`. Nothing degrades.
 
+## `markup`
+
+A script that enhances server-rendered markup has to agree with the template on
+attribute names, and nothing checks that agreement. `data-filter-regoin` in the
+template and `dataset.filterRegion` in the script compile, build and ship, and
+the facet simply never matches: the page reads as a filter with no results, not
+as a typo. A shared constant pins one name. `markup` pins every name a script
+and its template share, and the values in them.
+
+```ts
+// network-markup.ts — imported by the template and by the script
+export const row = markup("network-row", {
+    key: { kind: "text" },
+    status: { kind: "choice", of: ["open", "soon"] },
+    state: { kind: "text", optional: true },
+});
+export const search = markup("network-search");
+```
+
+```astro
+<a {...row.attrs({ key, status: "open", state: store.state })}>
+<input {...search.attrs()} type="search">
+```
+
+```ts
+for (const { element, values } of row.all(this)) {
+    values.status; // "open" | "soon"
+}
+const input = search.require<HTMLInputElement>(this).element;
+```
+
+- **Names are derived, never spelled.** `data-network-row` marks the element and
+  `data-network-row-status` holds a field. A field that does not exist is a
+  compile error in the template and in the script.
+- **Values are typed on the way in.** `attrs` takes each field's type: a missing
+  required field, or a status outside its list, fails `astro check`. It also
+  checks at run time, because this runs at build time and a value can arrive as
+  a plain `string` from an env var or a cast; a throw there fails the build
+  rather than shipping a page whose script throws on every visit.
+- **And parsed on the way out.** `read`, `all`, `one` and `require` parse every
+  field and throw, naming the element and the attribute, when one is missing or
+  malformed. A malformed match fails the whole `all` rather than being skipped:
+  a list that quietly loses a row is the failure this exists to prevent.
+
+The kinds are data, not builders, for the reason `filters` gives:
+`text`, `number`, `list`, `choice` and `flag`, the first four optionally
+`optional`. A `flag` is off by being absent, never `"false"`, so a stylesheet can
+select it with a bare attribute.
+
+`write` sets fields back onto an element, for state a stylesheet reads — a
+dropdown that is blocked — so the script uses the names the template did.
+
+**What it still cannot reach is the stylesheet.** Tailwind generates CSS from
+class names it finds as literals in the source, so a variant keyed on one of
+these attributes has to spell it: `group-data-network-dropdown-blocked/dd:`.
+That is the one place a rename is not a compile error. It is also the one place
+a drift is visible, since the style stops applying, where a script reading the
+wrong attribute fails silently. `attribute(field)` returns the name for the
+consumers that can take a computed one, such as an `attributeFilter`.
+
+It keeps the rule at the top of this page in the only reading that admits a
+lookup: it finds only elements carrying its own marker, writes only its own
+attributes, and sets no class, `aria` or `hidden`. The names are the project's,
+so nothing in this package has to be matched.
+
+## `youtube`
+
+A YouTube video that loads nothing from YouTube until a reader asks for it. The
+page renders a poster and a button, drawn however the project likes; the click
+swaps the player in, with `autoplay=1` so the one press already made is the one
+that starts it.
+
+```ts
+const trailer = youtubeEmbed({
+    id: box.dataset.trailer,
+    title: box.dataset.trailerTitle,
+    frame: (iframe) => {
+        iframe.className = "absolute inset-0 h-full w-full";
+    },
+});
+
+const detach = trailer.attach(button, box);
+```
+
+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, per video,
+whether or not anyone presses play. Deferring it is the whole point, and the rest
+is what every embed needs and has no taste in:
+
+- **`youtube-nocookie.com`**, the same player without a cookie until it plays —
+  and here it is only ever loaded to be played.
+- **A title**, which is the frame's accessible name. Refused when blank: a
+  frame without one is announced as "frame" and nothing else.
+- **`allow` with `autoplay`**, or the `autoplay=1` is refused and the reader who
+  pressed play gets a second button to press. The list is YouTube's own.
+- **`allowfullscreen`**, and **`referrerpolicy="strict-origin-when-cross-origin"`**
+  stated rather than inherited: YouTube will not play an embed that arrives with
+  no referrer, so a site sending `Referrer-Policy: no-referrer` would otherwise
+  get a player showing an error where the video should be.
+- **Focus moves to the player.** The button that had it has just left the page,
+  which would drop a keyboard reader back at the top of the document.
+
+`frame` is called after all of that and before the iframe is in the page, so its
+word is the last one and nothing is drawn unstyled first.
+
+**The id is checked at construction.** 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". A shape check cannot say the video
+exists, only that what was handed over is an id and not a URL.
+
+**Two elements, and a click on the first only.** The trigger is what a reader
+presses; the container is what the player replaces, usually the poster and that
+same button together. Listening on the whole container would be simpler and
+wrong, since a caption link inside it would start the video. Once only, and the
+undo removes the listener and nothing else — a player already loaded stays,
+because taking it out would stop a video someone is watching.
+
+It is kept apart from `videoObject` in `jsonld/video.ts`. That one describes the
+video to a crawler at build time and this plays it in a browser; they share
+only an id the caller already holds, and do not even want the same host — Google
+reads the `youtube.com` player as `embedUrl`.
+
+## `background-video`
+
+A muted, looping, decorative `<video>` — a hero loop. It owns whether the video
+plays, whether there is anything to play, and which cut is loaded; the project
+draws its own play/pause control from what `onChange` reports and points the
+control at `toggle`.
+
+```ts
+const loop = backgroundVideo({
+    onChange: ({ playing, playable }) => {
+        button.hidden = !playable;
+        button.setAttribute("aria-label", playing ? pauseLabel : playLabel);
+        playIcon.toggleAttribute("hidden", playing);
+        pauseIcon.toggleAttribute("hidden", !playing);
+    },
+});
+
+button.addEventListener("click", () => loop.toggle(), { signal });
+const detach = loop.attach(video);
+```
+
+What it owns is what every hero loop 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, its icons and its
+  label are the project's; `playing` is what they show.
+- **No control over nothing.** A `<source media>` that matches no viewport
+  leaves the element empty. `playable` says so — `currentSrc` empty, or the
+  element out of sources — and the caller hides the control.
+- **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. This listens to every source's query and calls
+  `load()` when the answer changes — *the answer*, not any crossing: a later
+  source's query flipping while an earlier one still matches chooses the same
+  file, and a reload would restart the loop from its first frame for nothing.
+- **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
+  stopped. `autoplay` is kept equal to what is wanted, which is what a reload
+  consults.
+
+`toggle` reads the element rather than the last press, because the control shows
+what the video is doing and pressing it must do the opposite — including when
+the browser paused it rather than the reader. The reader's choice outranks
+reduced motion once made, and survives a detach, so an element moved in the DOM
+comes back as the reader left it.
+
+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 pauses them. Left in, everything still works. `muted` is also
+set on attach, since no browser will start an unmuted video nobody pressed play
+on.
+
 ## Testing
 
-`filters` and `filters-view` are the only modules here with tests, and both for
-the same reason: neither finds an element. `filters` takes item text as data and
-`filters-view` takes elements it was handed, so both run against stubs rather
-than a document. `tests/filters.test.ts` fakes `location`, `history` and one
-`popstate` listener, covering the matching, the four URL decisions and
-attach/detach; `tests/filters-view.test.ts` fakes plain objects with a `hidden`
-property, pins the write-back guard by counting *writes* — so deleting the guard
-fails rather than passing on an identical value — and pins the nesting order in
-both directions.
+None of these tests has a document, and none needs one: every module under test
+is handed what it touches rather than finding it, so a stub object with the
+right properties is a faithful stand-in.
+
+- `tests/filters.test.ts` fakes `location`, `history` and one `popstate`
+  listener, covering the matching, `matchedWithout`, the four URL decisions and
+  attach/detach.
+- `tests/filters-view.test.ts` fakes plain objects with a `hidden` property,
+  pins the write-back guard by counting *writes* — so deleting the guard fails
+  rather than passing on an identical value — and pins the nesting order in
+  both directions.
+- `tests/youtube.test.ts` fakes the trigger, and a container whose
+  `ownerDocument` makes the iframe — which is why the module reaches the
+  document through the container rather than the global.
+- `tests/background-video.test.ts` stubs `matchMedia` with `vi.stubGlobal`, with
+  `matches` read live as a browser's is, and fakes the `<video>` down to
+  `paused`, `currentSrc`, `networkState`, `autoplay`, `play`, `pause` and `load`,
+  including what resource selection does after a reload.
+- `tests/markup.test.ts` fakes elements down to four attribute methods and a
+  root that answers bare attribute selectors, and round-trips every field kind
+  through `attrs` and `read`. `type-tests/markup.ts` pins the half that is a
+  compile error.
 
 `carousel`, `consent`, `element` and `dom` have none. They need a real DOM and
 this package carries no environment for one; adding `happy-dom` as a dev

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.15",
+    "version": "0.1.17",
     "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,9 @@
         "./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/markup": "./src/astro/markup.ts",
+        "./astro/meta-tags": "./src/astro/MetaTags.astro",
+        "./astro/youtube": "./src/astro/youtube.ts"
     },
     "bin": {
         "atlas": "bin/use-project.mjs"
@@ -53,8 +56,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",