@escape-game-over/atlas 0.1.16 → 0.1.18

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

@@ -32,17 +32,18 @@ the referrer policy — and everything that does, classes above all, comes from
 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`           |
+| 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
@@ -362,17 +363,259 @@ 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.
+
+### `component`: roles owned by one custom element
+
+`markup` leaves two things to the project, and both bite: a name per role, which
+two components can pick alike, and scope, since `querySelectorAll` from an
+element also finds everything inside a nested copy of that element. `component`
+ties every role to a custom element and settles both.
+
+```ts
+export const faq = component("go-faq", {
+    row: { key: { kind: "text" }, text: { kind: "text" } },
+    search: {},
+});
+```
+
+```astro
+<faq.tag>
+    <input {...faq.search.attrs()} type="search">
+    <details {...faq.row.attrs({ key, text })}>…</details>
+</faq.tag>
+```
+
+```ts
+class Faq extends AtlasElement {
+    protected connect(): void {
+        for (const { element, values } of faq.row.all(this)) { … }
+    }
+}
+faq.define(Faq);
+```
+
+- **Names come from the tag.** Every attribute is `data-<tag>-<role>` plus the
+  field, and the browser refuses to define one tag twice, so two components
+  cannot share an attribute. Two roles of one component that would write the
+  same attribute — `search` with a field `clear`, and a role `searchClear` — are
+  refused when the component is created.
+- **Lookups stay in their instance.** `all`, `one` and `require` return only
+  elements whose nearest ancestor with this tag is the root's. A nested copy
+  keeps its elements, and a lookup from an element inside the instance, like a
+  dropdown's own panel, still counts as that instance. Elements are filtered
+  before they are read, so a broken nested copy cannot fail the outer lookup.
+- **The tag is written once.** `faq.tag` is what the template renders and
+  `faq.define` registers the class under it.
+
+`tag` and `define` are the component's own keys, so no role may take them. A role
+that lives outside every instance, such as a footer button that reopens a
+banner, is still plain `markup`.
+
+## `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.
+- `tests/component.test.ts` builds a small element tree with parents and
+  `closest`, and pins the scoping: a nested instance, two side by side, a root
+  inside the instance, and a broken nested element that must not be read.
+  `type-tests/component.ts` pins the role types and the reserved keys.
 
 `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.16",
+    "version": "0.1.18",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -23,6 +23,7 @@
         "./astro/element": "./src/astro/element.ts",
         "./astro/filters": "./src/astro/filters.ts",
         "./astro/filters-view": "./src/astro/filters-view.ts",
+        "./astro/markup": "./src/astro/markup.ts",
         "./astro/meta-tags": "./src/astro/MetaTags.astro",
         "./astro/youtube": "./src/astro/youtube.ts"
     },

package/src/astro/markup.ts

@@ -0,0 +1,574 @@
+/**
+ * A markup contract: the attributes a template writes and a script reads,
+ * named once, typed on both sides.
+ *
+ * In `astro/` because the reading half takes elements. The writing half runs in
+ * an Astro template at build time, and both halves come off the one object —
+ * which is the entire point.
+ *
+ * ```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 },
+ * });
+ *
+ * // StoreRow.astro
+ * <a {...row.attrs({ key, status: "open", state: store.state })}>
+ *
+ * // network.ts
+ * for (const { element, values } of row.all(this)) {
+ *     values.status; // "open" | "soon"
+ * }
+ * ```
+ *
+ * **Why it exists.** A client script and the template it enhances agree on
+ * attribute names, and nothing checks the agreement. `data-filter-regoin` in a
+ * template and `dataset.filterRegion` in a script compile, build and ship; the
+ * facet never matches, and the page reads as a filter with no results rather
+ * than as a typo. A shared constant pins the name of one attribute. This pins
+ * all of them, and their values with them:
+ *
+ * - **Names are derived, never spelled.** `data-network-row` marks the element
+ *   and `data-network-row-status` holds a field. Neither side writes either
+ *   string, so a rename is one edit, and a field that does not exist is a
+ *   compile error in the template and in the script alike.
+ * - **Values are typed on the way in.** `attrs` takes each field's own type, so
+ *   a missing required field, or a status outside its list, fails `astro check`.
+ * - **And checked on the way out.** A script cannot trust markup it did not
+ *   write — a page cached from before a deploy, a template that spread the wrong
+ *   role — so `read` parses every field and throws, naming the element and the
+ *   attribute, rather than handing back an `undefined` that filters to nothing.
+ *
+ * The rule in docs/client-scripts.md still holds, and this is the reading of it
+ * that admits a lookup. It finds only what carries its own marker, writes only
+ * its own attributes, and has no opinion about classes, `aria` or `hidden`. The
+ * names come from the project: nothing in this package has to be matched.
+ */
+
+/**
+ * What one field is, as data rather than a constructor — the choice `filters`
+ * makes, for the same reason: builder functions would put names as general as
+ * `text` into every module that imports this.
+ *
+ * - `text` — any string, the empty one included.
+ * - `number` — finite only; `NaN` and the infinities have no attribute form
+ *   that reads back as themselves.
+ * - `list` — several words, space-separated, as `class` is. No item may be
+ *   empty or contain whitespace, which is checked when it is written.
+ * - `choice` — one of `of`. Out-of-list values fail on both sides: at compile
+ *   time in the template, at run time when read.
+ * - `flag` — present or absent. Off is the attribute left out, not `"false"`,
+ *   so a stylesheet can select it with a bare `[data-…]`.
+ *
+ * `optional` lets a field be left off, and reads back `undefined` when it was.
+ * A `flag` has no `optional`: absent is already one of its two values.
+ */
+export type MarkupField =
+    | { readonly kind: "text"; readonly optional?: boolean }
+    | { readonly kind: "number"; readonly optional?: boolean }
+    | { readonly kind: "list"; readonly optional?: boolean }
+    | {
+          readonly kind: "choice";
+          readonly of: readonly [string, ...string[]];
+          readonly optional?: boolean;
+      }
+    | { readonly kind: "flag" };
+
+/** The fields of one role, named by the caller. */
+export type MarkupFields = Readonly<Record<string, MarkupField>>;
+
+/** The value a field holds when present. */
+type Held<F extends MarkupField> = F extends { kind: "text" }
+    ? string
+    : F extends { kind: "number" }
+      ? number
+      : F extends { kind: "list" }
+        ? readonly string[]
+        : F extends { kind: "choice"; of: readonly (infer V)[] }
+          ? V
+          : boolean;
+
+/** Whether a template may leave the field out. */
+type Omittable<F extends MarkupField> = F extends { kind: "flag" }
+    ? true
+    : F extends { optional: true }
+      ? true
+      : false;
+
+/** One field's value as a script reads it. */
+export type MarkupValue<F extends MarkupField> = F extends { optional: true }
+    ? Held<F> | undefined
+    : Held<F>;
+
+/** Every field's value, as a script reads it. */
+export type MarkupValues<F extends MarkupFields> = {
+    readonly [K in keyof F]: MarkupValue<F[K]>;
+};
+
+type RequiredKeys<F extends MarkupFields> = {
+    [K in keyof F]-?: Omittable<F[K]> extends true ? never : K;
+}[keyof F];
+
+type Flatten<T> = { [K in keyof T]: T[K] };
+
+/**
+ * What a template hands `attrs`: every required field, and any of the rest.
+ *
+ * The optional ones accept `undefined` as well as being left out, so a value
+ * that is itself optional — `store.state` — can be passed straight through
+ * without a conditional spread, whatever `exactOptionalPropertyTypes` says.
+ */
+export type MarkupInput<F extends MarkupFields> = Flatten<
+    { readonly [K in RequiredKeys<F>]: Held<F[K]> } & {
+        readonly [K in Exclude<keyof F, RequiredKeys<F>>]?:
+            | Held<F[K]>
+            | undefined;
+    }
+>;
+
+/** One marked element, and what its attributes say. */
+export interface Marked<T extends Element, F extends MarkupFields> {
+    readonly element: T;
+    readonly values: MarkupValues<F>;
+}
+
+export interface Markup<F extends MarkupFields> {
+    /**
+     * `[data-<name>]`: what finds this role.
+     *
+     * For the lookups the methods below do not cover — `closest`, a
+     * `matches` in an event handler — so those do not spell it either.
+     */
+    readonly selector: string;
+
+    /**
+     * The attribute one field lives in.
+     *
+     * For the rare consumer that needs the name as a string, such as a
+     * `MutationObserver`'s `attributeFilter`. A stylesheet cannot use it —
+     * Tailwind has to see its selectors as literals in the source — so a
+     * styling hook still spells the attribute once, in a class; see the docs.
+     */
+    attribute(field: keyof F & string): string;
+
+    /**
+     * The attributes to spread onto an element, in a template.
+     *
+     * Always includes the marker. A role with nothing required may be called
+     * with no argument at all.
+     */
+    attrs(
+        ...values: [RequiredKeys<F>] extends [never]
+            ? [values?: MarkupInput<F>]
+            : [values: MarkupInput<F>]
+    ): Record<string, string>;
+
+    /**
+     * One element's values, parsed.
+     *
+     * Throws when the element does not carry this role, or when any field is
+     * missing or malformed — naming the element and the attribute, because an
+     * `undefined` returned here would only resurface later as a list that
+     * silently matches nothing.
+     */
+    read(element: Element): MarkupValues<F>;
+
+    /** Every element under `root` carrying this role, each with its values. */
+    all<T extends Element = HTMLElement>(root: ParentNode): Marked<T, F>[];
+
+    /** The first element under `root` carrying this role, or `null`. */
+    one<T extends Element = HTMLElement>(root: ParentNode): Marked<T, F> | null;
+
+    /** The first, or a thrown error naming the marker nobody carried. */
+    require<T extends Element = HTMLElement>(root: ParentNode): Marked<T, F>;
+
+    /**
+     * Writes some of this role's fields back onto an element.
+     *
+     * For state a stylesheet reads — a dropdown that is blocked, a card that is
+     * selected — so the script sets it through the same names the template
+     * wrote. A field set to `undefined`, or a flag set to `false`, removes the
+     * attribute; fields left out of `values` are not touched.
+     */
+    write(element: Element, values: Partial<MarkupInput<F>>): void;
+}
+
+/** Lowercase words joined by single hyphens: what follows `data-`. */
+const NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+/**
+ * camelCase, so the hyphenated form below is unambiguous.
+ *
+ * `aB` → `a-b` is one-to-one only while a field cannot contain a hyphen of its
+ * own: allowing `a-b` too would give two fields one attribute, and each write
+ * would erase the other.
+ */
+const FIELD = /^[a-z][a-zA-Z0-9]*$/;
+
+const hyphenate = (field: string): string =>
+    field.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+
+/** A value for the error messages, quoted when it is a string. */
+const show = (value: unknown): string =>
+    typeof value === "string" ? `"${value}"` : String(value);
+
+/**
+ * One field's value as its attribute, or `undefined` to leave it off.
+ *
+ * Checked although the types already were: a template can reach here with a
+ * value typed as `string` that came from an env var or a cast, and this runs at
+ * build time, where a throw fails the build instead of shipping a page whose
+ * script will throw on every visit.
+ */
+function encode(
+    field: MarkupField,
+    value: unknown,
+    attribute: string
+): string | undefined {
+    if (field.kind === "flag") return value === true ? "" : undefined;
+    if (value === undefined && field.optional === true) return undefined;
+
+    const refuse = (why: string): never => {
+        throw new Error(`${attribute} cannot hold ${show(value)}: ${why}`);
+    };
+
+    switch (field.kind) {
+        case "text":
+            return typeof value === "string"
+                ? value
+                : refuse("it is a text field");
+        case "number":
+            return typeof value === "number" && Number.isFinite(value)
+                ? String(value)
+                : refuse("only a finite number reads back as itself");
+        case "choice":
+            return typeof value === "string" && field.of.includes(value)
+                ? value
+                : refuse(`expected one of ${field.of.join(", ")}`);
+        case "list": {
+            if (!Array.isArray(value)) return refuse("it is a list field");
+            for (const item of value) {
+                if (
+                    typeof item !== "string" ||
+                    item === "" ||
+                    /\s/.test(item)
+                ) {
+                    refuse(
+                        `the item ${show(item)} is empty or contains whitespace, which separates items`
+                    );
+                }
+            }
+            return value.join(" ");
+        }
+    }
+}
+
+/** An attribute's value as its field's, or a thrown error saying why not. */
+function decode(
+    field: MarkupField,
+    raw: string | null,
+    attribute: string
+): unknown {
+    if (field.kind === "flag") return raw !== null;
+    if (raw === null) {
+        if (field.optional === true) return undefined;
+        throw new Error(`${attribute} is missing`);
+    }
+
+    switch (field.kind) {
+        case "text":
+            return raw;
+        case "number": {
+            const value = Number(raw);
+            // `Number("")` is 0, so a blank attribute would read as a zero.
+            if (raw.trim() === "" || !Number.isFinite(value)) {
+                throw new Error(`${attribute} is ${show(raw)}, not a number`);
+            }
+            return value;
+        }
+        case "choice":
+            if (!field.of.includes(raw)) {
+                throw new Error(
+                    `${attribute} is ${show(raw)}, expected one of ${field.of.join(", ")}`
+                );
+            }
+            return raw;
+        case "list":
+            return raw.split(/\s+/).filter((item) => item !== "");
+    }
+}
+
+/**
+ * Declares one role: a marker attribute, and a typed attribute per field.
+ *
+ * `name` becomes `data-<name>`, and each field `data-<name>-<field>` with the
+ * field hyphenated. Both are checked here, at construction, because a name that
+ * is not a valid attribute would otherwise surface as a `querySelector` syntax
+ * error in the browser, far from the line that caused it.
+ *
+ * Two roles whose names make one a prefix of the other can collide:
+ * `markup("card")` with a field `title` and `markup("card-title")` both write
+ * `data-card-title`. Name roles so they do not.
+ */
+export function markup<const F extends MarkupFields = Record<never, never>>(
+    name: string,
+    fields?: F
+): Markup<F> {
+    if (!NAME.test(name)) {
+        throw new Error(
+            `markup(${show(name)}): a name is lowercase words joined by single hyphens, as in "store-row"`
+        );
+    }
+
+    const marker = `data-${name}`;
+    const selector = `[${marker}]`;
+
+    const entries = Object.entries(fields ?? {}).map(([key, field]) => {
+        if (!FIELD.test(key)) {
+            throw new Error(
+                `markup(${show(name)}): the field ${show(key)} must be camelCase — it becomes the last part of the attribute`
+            );
+        }
+        return { key, field, attribute: `${marker}-${hyphenate(key)}` };
+    });
+
+    const describe = (element: Element): string =>
+        `<${element.localName} ${marker}>`;
+
+    const read = (element: Element): MarkupValues<F> => {
+        if (!element.hasAttribute(marker)) {
+            throw new Error(
+                `<${element.localName}> does not carry ${marker}, so it has none of its fields`
+            );
+        }
+        const values: Record<string, unknown> = {};
+        for (const { key, field, attribute } of entries) {
+            try {
+                values[key] = decode(
+                    field,
+                    element.getAttribute(attribute),
+                    attribute
+                );
+            } catch (error) {
+                const reason =
+                    error instanceof Error ? error.message : String(error);
+                throw new Error(`${describe(element)}: ${reason}`, {
+                    cause: error,
+                });
+            }
+        }
+        return values as MarkupValues<F>;
+    };
+
+    const mark = <T extends Element>(element: T): Marked<T, F> => ({
+        element,
+        values: read(element),
+    });
+
+    const one = <T extends Element = HTMLElement>(
+        root: ParentNode
+    ): Marked<T, F> | null => {
+        const found = root.querySelector<T>(selector);
+        return found === null ? null : mark(found);
+    };
+
+    return {
+        selector,
+
+        attribute(key) {
+            const entry = entries.find((each) => each.key === key);
+            if (entry === undefined) {
+                throw new Error(`${marker} has no field ${show(key)}`);
+            }
+            return entry.attribute;
+        },
+
+        attrs(...[values]) {
+            const given = (values ?? {}) as Record<string, unknown>;
+            const out: Record<string, string> = { [marker]: "" };
+            for (const { key, field, attribute } of entries) {
+                const raw = encode(field, given[key], attribute);
+                if (raw !== undefined) out[attribute] = raw;
+            }
+            return out;
+        },
+
+        read,
+
+        all: <T extends Element = HTMLElement>(root: ParentNode) =>
+            [...root.querySelectorAll<T>(selector)].map(mark),
+
+        one,
+
+        require<T extends Element = HTMLElement>(root: ParentNode) {
+            const found = one<T>(root);
+            if (found === null) {
+                throw new Error(
+                    `nothing here carries ${marker} — is the script still a deferred module, and does the template spread its attrs?`
+                );
+            }
+            return found;
+        },
+
+        write(element, values) {
+            // Checked like `read` is: writing a role's fields onto an element
+            // that is not that role leaves it half-marked, and nothing reads it.
+            if (!element.hasAttribute(marker)) {
+                throw new Error(
+                    `<${element.localName}> does not carry ${marker}, so its fields cannot be written to it`
+                );
+            }
+            const given = values as Record<string, unknown>;
+            for (const { key, field, attribute } of entries) {
+                if (!Object.hasOwn(given, key)) continue;
+                const raw = encode(field, given[key], attribute);
+                if (raw === undefined) element.removeAttribute(attribute);
+                else element.setAttribute(attribute, raw);
+            }
+        },
+    };
+}
+
+/** A component's roles, by name: each is the fields of one `markup` role. */
+export type ComponentRoles = Readonly<Record<string, MarkupFields>>;
+
+/** Keys the component object uses itself, so no role may take them. */
+type Reserved = "tag" | "define";
+
+export type Component<Tag extends string, R extends ComponentRoles> = {
+    /** The custom element's name: what the template renders. */
+    readonly tag: Tag;
+    /** Registers the element's class under `tag`. */
+    define(element: CustomElementConstructor): void;
+} & { readonly [K in keyof R]: Markup<R[K]> };
+
+/** A custom element name, as far as a pattern can check it: needs a hyphen. */
+const TAG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/;
+
+/**
+ * A custom element and the roles inside it, with lookups scoped to one
+ * instance.
+ *
+ * ```ts
+ * export const faq = component("go-faq", {
+ *     row: { key: { kind: "text" }, text: { kind: "text" } },
+ *     search: {},
+ * });
+ *
+ * // template: <faq.tag> … <details {...faq.row.attrs({ key, text })}>
+ * // script:   faq.row.all(this); faq.define(Faq);
+ * ```
+ *
+ * Two things `markup` alone leaves to the project:
+ *
+ * - **Names.** Every attribute is `data-<tag>-<role>[-<field>]`. The browser
+ *   refuses to define one tag twice, so two components cannot share an
+ *   attribute, and clashes inside one component are refused here.
+ * - **Scope.** A lookup returns only elements owned by the same instance as
+ *   its root — the owner being the nearest ancestor with this tag. A nested
+ *   instance keeps its elements to itself, and the root may be any element
+ *   inside the instance, not only the instance itself.
+ *
+ * Roles outside any instance, like a footer button that reopens a banner, are
+ * what plain `markup` is still for.
+ */
+export function component<
+    const Tag extends string,
+    const R extends ComponentRoles & { readonly [K in Reserved]?: never },
+>(tag: Tag, roles: R): Component<Tag, R> {
+    if (!TAG.test(tag)) {
+        throw new Error(
+            `component(${show(tag)}): a custom element name is lowercase words with at least one hyphen, as in "go-faq"`
+        );
+    }
+
+    // Every attribute the component writes, so two that coincide are refused
+    // rather than left to overwrite each other.
+    const claimed = new Map<string, string>();
+    const claim = (attribute: string, by: string): void => {
+        const earlier = claimed.get(attribute);
+        if (earlier !== undefined) {
+            throw new Error(
+                `component(${show(tag)}): ${by} and ${earlier} would both write ${attribute}`
+            );
+        }
+        claimed.set(attribute, by);
+    };
+
+    /** The instance a root belongs to; `null` for the document. */
+    const ownerOf = (root: ParentNode): Element | null =>
+        "closest" in root && typeof root.closest === "function"
+            ? root.closest(tag)
+            : null;
+
+    const scoped = (
+        role: string,
+        fields: MarkupFields
+    ): Markup<MarkupFields> => {
+        if (role === "tag" || role === "define") {
+            throw new Error(
+                `component(${show(tag)}): ${show(role)} is taken by the component itself`
+            );
+        }
+        if (!FIELD.test(role)) {
+            throw new Error(
+                `component(${show(tag)}): the role ${show(role)} must be camelCase — it becomes part of the attribute`
+            );
+        }
+
+        const base = markup(`${tag}-${hyphenate(role)}`, fields);
+        claim(base.selector.slice(1, -1), `the role ${show(role)}`);
+        for (const field of Object.keys(fields)) {
+            claim(base.attribute(field), `${role}.${field}`);
+        }
+
+        // Filtered before anything is read, so a malformed element in a nested
+        // instance cannot fail a lookup that was never going to return it.
+        const mine = <T extends Element>(root: ParentNode): T[] => {
+            const owner = ownerOf(root);
+            return [...root.querySelectorAll<T>(base.selector)].filter(
+                (element) => element.closest(tag) === owner
+            );
+        };
+
+        const one = <T extends Element = HTMLElement>(
+            root: ParentNode
+        ): Marked<T, MarkupFields> | null => {
+            const [found] = mine<T>(root);
+            return found === undefined
+                ? null
+                : { element: found, values: base.read(found) };
+        };
+
+        return {
+            ...base,
+            all: <T extends Element = HTMLElement>(root: ParentNode) =>
+                mine<T>(root).map((element) => ({
+                    element,
+                    values: base.read(element),
+                })),
+            one,
+            require<T extends Element = HTMLElement>(root: ParentNode) {
+                const found = one<T>(root);
+                if (found === null) {
+                    throw new Error(
+                        `nothing in this <${tag}> carries ${base.selector.slice(1, -1)} — does the template spread its attrs inside the element?`
+                    );
+                }
+                return found;
+            },
+        };
+    };
+
+    const built: Record<string, unknown> = {
+        tag,
+        define: (element: CustomElementConstructor) =>
+            customElements.define(tag, element),
+    };
+    for (const [role, fields] of Object.entries(roles)) {
+        built[role] = scoped(role, fields);
+    }
+    return built as Component<Tag, R>;
+}