@escape-game-over/atlas 0.1.3 → 0.1.4

package/README.md

@@ -140,6 +140,7 @@ explicitly.
 | `Product` JSON-LD        | `product()`                      | name, price table                       |
 | `Article` JSON-LD        | `article()`                      | headline, publication date              |
 | `VideoObject` JSON-LD    | `videoObject()`                  | a video, its stills and date            |
+| `FAQPage` JSON-LD        | `faqPage()`                      | the questions the page itself shows     |
 | Analytics tags           | `metaFor()`, from the project    | ids, via `analytics` in `defineProject` |
 | `PublicFile` union       | `publicFiles()`, from `public/`  | nothing                                 |
 
@@ -251,8 +252,14 @@ const careers: WhenEnabled<typeof site, "careers", Careers> = { ats: "…" };  /
   ".":                  "./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/meta-tags":  "./src/astro/MetaTags.astro"
+  "./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"
 }
 ```
 
@@ -268,6 +275,12 @@ may use `node:` built-ins but not `astro:assets`. `./astro/images` is the
 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
+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).
+
 **The package ships TypeScript source, and there is no build step.**
 `MetaTags.astro` could not go through `tsc` anyway, and Astro's own
 `tsconfigs/base.json` already sets `allowImportingTsExtensions`, so every
@@ -390,6 +403,9 @@ upstream, and each explains a rule that would otherwise read as an oversight.
   how the type tests and runtime tests divide the work.
 - [`docs/share-images.md`](docs/share-images.md) — what each social surface
   crops, and why one 1200×630 image serves all of them.
+- [`docs/client-scripts.md`](docs/client-scripts.md) — the browser half: what
+  each client module owns, why none of them draws anything, the lifetime bug
+  view transitions cause, and how `filters` declares its fields and its URL.
 - [`docs/toolchain.md`](docs/toolchain.md) — the pinned TypeScript, the two
   switches `.astro` support needs from Biome, and the traps.
 - [`docs/NOT-BUILT.md`](docs/NOT-BUILT.md) — what we deliberately do not build,

package/docs/NOT-BUILT.md

@@ -5,8 +5,8 @@ of these looks like an obvious addition until you check — so the check is
 written down once, rather than redone by whoever thinks of it next.
 
 Each answer says what is *not* built and, where it matters, what is still fine
-to build. The two are easy to run together: "no FAQ structured data" is not "no
-FAQ page", and reading it as the second would lose something worth having.
+to build. The two are easy to run together: "no star-rating markup" is not "no
+reviews", and reading it as the second would lose something worth having.
 
 Kept beside the code rather than in the backlog, because a backlog is a list of
 things still to do and every one of these is a thing not to do.
@@ -21,12 +21,25 @@ sites are shaped, and will not change on its own.
 
 ### Should we mark up our FAQ with `FAQPage`?
 
-**Not now — and this one genuinely depends. The page is a fine idea either way.**
+**Built, as of August 2026 — `faqPage()`, opt-in, and nothing emits it for you.
+The reasoning that kept it out for so long is now in `src/jsonld/faq.ts`, and it
+is still the reasoning: read it before adding the node to a page.**
 
-The most conditional answer in this file, so it is worth reading before
-assuming. Three things hold it shut today and the first two could move. Two
-further arguments that *sound* decisive are wrong, and are recorded below so
-they stop being made.
+This was the most conditional answer in the file, and it moved because it was
+asked for rather than because Google moved — if anything Google moved the other
+way, removing FAQ rich results from Search entirely on 7 May 2026. So what stood
+below still stands: the node renders nowhere, a model does not read it out of a
+`<script>` block, and it duplicates the page's own text at several KB per load.
+What is left in its favour is Bing, which has said its LLMs read schema.
+
+Which makes this a call a *site* makes per page, not one lib makes for every
+repo it syncs to — hence a builder that has to be called and passed into a
+graph, rather than anything wired into `metaFor()`. A project that has not
+weighed the payload against a Copilot payoff it can actually measure should keep
+not calling it, which is the same answer this entry always gave.
+
+The two arguments that *sound* decisive and are wrong are recorded below, since
+they will be made again either way.
 
 Google restricted FAQ rich results to *"well-known, authoritative government and
 health websites"* in 2023, then [removed them from Search entirely](https://developers.google.com/search/docs/appearance/structured-data/faqpage)
@@ -45,8 +58,8 @@ content in visible headings and paragraphs is read reliably.
 That is not an argument against the nodes lib does build. Schema is parsed at
 *indexing* time, so it reaches the AI surfaces built on top of a search index —
 AI Overviews, Copilot — even though a chatbot fetching the page directly sees
-only the visible text. It is an argument against adding one that no longer
-renders anywhere and is not read directly either.
+only the visible text. It is an argument against reaching for this one expecting
+a model to pick the answers up, which is the reason it is given every time.
 
 The one cost that counts is the payload. Every other node lib builds is metadata
 *about* the page — an address, a price, a date. This one is a verbatim *copy of*
@@ -64,17 +77,18 @@ against lib itself, and applied evenly it forbids everything already in here.
 Neither survives — which is why what stands above is about what consumes the
 markup and what it costs to send, and not about how much work it is to write.
 
-**What would flip it.** Google reinstating FAQ rich results is the obvious one.
-The likelier one is Bing: it has said outright that its LLMs read schema, which
-is the single live third-party payoff here, so if Copilot visibility ever
-becomes something these venues actually measure rather than speculate about,
-build it. The data is already in config, so it is a small build on the day the
-trigger fires — which is the reason to leave it until then rather than guess now.
+**What would make calling it worthwhile.** Google reinstating FAQ rich results
+is the obvious one, and is not in prospect. The likelier one is Bing: it has
+said outright that its LLMs read schema, which is the single live third-party
+payoff here, so a site measuring Copilot visibility rather than speculating
+about it has a reason. A site that is not measuring it is paying the payload for
+nothing, which is the default answer and always was.
 
 Writing the page is a separate question and the answer there is yes: readers
 want one, and `llms.txt` carries question-and-answer copy unusually well, since
-that is close to the form a model is asked things in. It is content, needs
-nothing from lib, and — today — no structured data.
+that is close to the form a model is asked things in. It is content, and it
+needs nothing from lib — the node is optional on top and does not make the page
+any more findable to the readers who actually want it.
 
 ### The other node types the sibling projects emit — which of them do we want?
 
@@ -114,7 +128,8 @@ answer for each is a fact about Google rather than a preference.
   rather than the sizes. Checked August 2026.
 
 `FAQPage` is above, and has its own entry because it is the one that keeps
-getting asked.
+getting asked — it is now built, opt-in, and the entry says what calling it
+does and does not buy.
 
 ### Should a post say which `articleSection` it is in?
 

package/docs/checks.md

@@ -108,6 +108,7 @@ dependencies at all. Vitest type-checks them itself when it runs them.
 | File                       | What it pins                                                                                                              |
 | -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
 | `meta.test.ts`             | the `robots` tag a policy builds, the pinned `twitter:card`, share-image warnings, length warnings, `fileUrl`             |
+| `not-found.test.ts`        | that a 404 carries the site's icon and theme colour, still names no canonical, and is held to the same icon rules         |
 | `redirects.test.ts`        | rule resolution for all three target kinds, the five rejections, the Cloudflare 2000-rule cap                             |
 | `sitemap.test.ts`          | splitting into an index plus numbered parts, and that the entry keeps its name either way                                 |
 | `merge.test.ts`            | catalog and route overlay precedence — per locale, never per key                                                          |
@@ -122,11 +123,25 @@ dependencies at all. Vitest type-checks them itself when it runs them.
 | `money.test.ts`            | a bare count widened to a band, the span of a table, and the gaps and overlaps that throw                                 |
 | `url.test.ts`              | joining an origin to a path exactly once, and normalising the origin an `@id` is built from                               |
 | `warn.test.ts`             | the shared prefix, and reducing a URL to its path                                                                         |
-
-The fixture carries two nested families for that last one, differing in the only
-way that changes behaviour: `guides` has a route owning its bare slug and `rooms`
-does not, so both the linked and the unlinked section are reachable from one
-site.
+| `filters.test.ts`          | folding both sides of a query, how each kind narrows, the four URL decisions, and attach/detach                           |
+| `filters-view.test.ts`     | the write-back into the input and that it is skipped when unchanged, clear taking focus, and the nesting order            |
+| `build-cache.test.ts`      | that an unset `CI_ASTRO_CACHE` yields nothing, so Astro's own `cacheDir` default survives                                 |
+
+The fixture carries two nested families for `breadcrumbs.test.ts`, differing in
+the only way that changes behaviour: `guides` has a route owning its bare slug
+and `rooms` does not, so both the linked and the unlinked section are reachable
+from one site.
+
+`filters.test.ts` and `filters-view.test.ts` are the two that reach the browser
+half, and both can for the same reason: neither module finds an element.
+`filters` takes item text as data and keys as strings, so it runs against a stub
+of `location`, `history` and one `popstate` listener; `filters-view` is handed
+the elements it writes to, so plain objects with a `hidden` property stand in for
+them. Neither needs a document.
+
+The rest of `src/astro/` — `carousel`, `consent`, `element`, `dom` — has no
+runtime tests at all. Covering them needs a real environment, which this package
+does not carry; see [`client-scripts.md`](client-scripts.md).
 
 ## What a consumer checks
 

package/docs/client-scripts.md

@@ -0,0 +1,307 @@
+# 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
+one rule they all keep.
+
+**They draw nothing.**
+
+No classes, no `aria`, no transforms, no markup. Each owns the part of a
+behaviour that is identical in every implementation and quietly wrong in most,
+calls back, and stops. The project writes every line that touches a pixel.
+
+That is not tidiness. A carousel's arithmetic is the same on a full-bleed hero
+and a three-up logo strip, and the design is not — so the moment a library owns
+the transform, it has to be told about the design, and the next carousel needs an
+option. Owning the half that does not vary is what lets one function serve both
+without growing a configuration surface.
+
+`filters-view` is the one that writes to elements, and the exception is narrow
+enough to state exactly: an input's `value` is the control's own state rather
+than a view of something else, and a `hidden` on a clear button, a no-results
+message or a section with nothing left in it is binary and derived — there is no
+version of "the clear button while the field is empty" that is a matter of taste.
+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`           |
+
+## Lifetimes are the recurring bug
+
+Every module here that binds a listener hands back the undo, and the undo is
+always one `AbortController` rather than a `removeEventListener` per
+`addEventListener`. Those pairs have to match on both the function reference and
+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
+```
+
+`AtlasElement` says the same thing in the shape a custom element needs, because
+an element is constructed once and may be connected many times — moving it in
+the DOM runs `disconnectedCallback` and then `connectedCallback` again:
+
+```ts
+protected setup(): void { … }     // once, ever: what the element is
+protected connect(): void { … }   // every connection: bind with this.signal
+```
+
+**The trap this exists for is view transitions.** A bundled `<script src>` is an
+ES module, cached by URL, so it executes once per session — not once per
+navigation. Bind at module scope with `ClientRouter` on and the incoming page
+gets a live list and dead controls: the markup was swapped, the handlers still
+point at what was there before. Driving `attach` from `astro:page-load` and
+calling its return on teardown is the fix, and it is why none of these modules
+does anything at import time.
+
+Note that the abort half alone does not help. It makes the breakage look
+handled. Without a re-`attach` there is simply nothing wired.
+
+## `filters`
+
+A list already rendered by the server, narrowed in the browser and mirrored in
+the URL. The caller declares fields; the item shape follows from them.
+
+```ts
+const list = filters({
+    fields: {
+        q:        { kind: "text",   param: "q" },
+        category: { kind: "choice", param: "category" },
+        featured: { kind: "flag",   param: "featured" },
+    },
+    items: entries.map((entry) => ({
+        key: entry.id,
+        values: {
+            q: `${entry.title} ${entry.summary}`,
+            category: entry.category,
+            featured: entry.featured,
+        },
+    })),
+    onChange: ({ matched, state }) => { /* the project's DOM writes, all of them */ },
+});
+
+const detach = list.attach();
+```
+
+Fields are plain data rather than `text()` / `choice()` / `flag()` builders:
+three exported names that general — `text` above all — in a module a project
+imports by name, to return exactly this object. `values` is typed *from*
+`fields`, so a `flag` demands a boolean and a mismatch is a compile error rather
+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 |
+| `choice` | one value, `""` | the item's one  | exact; `""` 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    |
+
+**`text` folds both sides** — `NFD`, drop the combining marks, lowercase, trim.
+This is the piece that is missing nearly everywhere, and it is not cosmetic: a
+reader who types `malaga` is otherwise told there is no *Málaga*, and every
+Romanian entry spelled with `ă`, `ș` or `ț` hides from anyone whose keyboard does
+not carry them. Item text is folded once at construction; only the query is
+folded per render.
+
+**`text` matches tokens, not one run.** The query is split on whitespace and every
+word must appear somewhere in the haystack. A haystack is several fields joined,
+and the order they were joined in is an accident of the template — matching the
+whole query as one substring makes that accident load-bearing, so a two-word
+query fails whenever the words are not adjacent.
+
+**`flag` is a narrowing, not a two-way filter.** Off keeps everything rather than
+keeping the items that are *not* flagged — "In stock", unchecked, does not mean
+"out of stock". On, off and *either* is a `choice` with two values; folding that
+into a toggle produces a control with a third position nothing can reach.
+
+Flags are not exclusive. A second toggle is another **field**, not another value
+on the first, and any number can be on at once — every field narrows the same
+pass. What is deliberately absent is one field holding several selected values;
+that is a `choices` kind, and it forces a URL encoding decision (repeated
+parameters or comma-joined) that nothing has needed yet.
+
+`param` is optional. A field without one is state-only and never reaches the URL.
+
+### The four URL decisions
+
+1. **Replace while typing, push on a choice.** An input emits an event per
+   keystroke, and history should not fill with a word being spelled; picking a
+   category is one deliberate act the back button should undo. The default comes
+   from the kind, but it is really a fact about the *input* — a `<select>` or a
+   preset link bound to a `text` field wants `list.set("q", v, { history: "push" })`.
+2. **Empty parameters are dropped**, and an empty state is the bare path rather
+   than a trailing `?`. Both spellings are the same page; one of them is worth
+   sharing.
+3. **`popstate` is applied.** The back button moves the list, rather than moving
+   the URL and leaving the page behind.
+4. **The URL is rebuilt from the declaration**, not edited in place, so a
+   parameter this list owns and no longer needs disappears instead of surviving
+   because nobody deleted it. Fields write in declaration order, so one state
+   always produces one URL.
+
+`attach` reads the URL *before* the first `onChange`. That is what lets a list
+work before this script arrives: a `<form method="get">` submits, the server
+renders the filtered page, and the first announcement continues from that state
+instead of flashing the whole list back. Nothing writes to the URL before
+`attach`, because `attach` is what reads it — a `set` on an unattached instance
+would overwrite state nobody had loaded.
+
+A set flag is written `1` and an unset one is **absent** rather than `=0`. One
+spelling for off keeps the URL short and leaves a single form to parse; the cost
+is that a hand-written `?featured=0` reads as off, which is the answer it would have
+got anyway. `1` and not `true` because that is what the existing lists already
+emit, and links people have shared should keep resolving to the view they named.
+
+### Two things it refuses at construction
+
+Both are silent otherwise:
+
+- **Two items under one key.** `matched` could not say which of them matched.
+- **Two fields on one URL parameter.** Each write erases the other's value, which
+  reads as a filter that will not stay set.
+
+And a `set` to the value already held announces nothing and pushes nothing, so
+re-clicking the current tab does not add a history step to walk back through.
+
+## `filters-view`
+
+Two helpers, and the bar for being here is not "a list might want this" but
+"every list we have already written did, character for character, and getting it
+wrong was silent". Three filtered lists in one consuming project — a catalogue, a
+location directory and an FAQ — agree on exactly these and disagree about
+everything else they draw.
+
+### `searchBox`
+
+The twelve lines every one of the three wrote around its search field, byte for
+byte.
+
+```ts
+const search = searchBox({
+    input: one<HTMLInputElement>("[data-filter-search]"),
+    clear: one("[data-filter-clear]"),
+    empty: one("[data-filter-empty]"),
+});
+
+const list = filters({
+    fields, items,
+    onChange({ state, matched }) {
+        search.render(state.q, matched.size);
+        // …everything this list draws for itself
+    },
+});
+
+const unbind = search.bind(list, "q");
+const detach = list.attach();
+```
+
+`render` is the half worth centralising, and specifically this:
+
+```ts
+if (input != null && input.value !== query) input.value = query;
+```
+
+It exists because `popstate` and `reset` move state without touching the
+keyboard — forget it and the back button leaves a stale query sitting in the box
+while the list shows something else. The inequality is not an optimisation:
+assigning `value` moves the caret to the end, so writing it unconditionally would
+make the field unusable mid-word.
+
+`bind` is a second call rather than part of construction because of an ordering
+knot. `render` runs inside the list's `onChange`, so the box must exist before
+the list; `bind` needs the list. Two `const`s in sequence is the honest shape,
+and the alternative is a `let` the reader has to carry. Its return is the undo,
+like `attach` — so a page-load teardown aborts both.
+
+`TextFieldOf<F>` restricts the second argument to the list's `text` fields, so a
+box pointed at a `flag` is a compile error rather than a filter that silently
+never matches.
+
+Every element is optional and `null` is accepted, because `within(root).one(…)`
+returns `null` and a page may have a search field with no clear button. Handing
+over what a lookup returned, unchecked, is the point.
+
+### `hideEmpty`
+
+Two of the three render their results under headings, and both hit the same
+thing: hide the items and the headings stay, so a search for one word leaves a
+page of section titles with nothing under them. It reads as a broken template
+rather than as a result, which is what makes forgetting it expensive — nothing
+errors, and the page looks wrong in a way that does not point at the filter.
+
+```ts
+onChange({ matched }) {
+    for (const item of items) item.hidden = !matched.has(keyOf(item));
+    hideEmpty(groups, (group) => within(group).all("[data-faq-key]"));
+}
+```
+
+**It reads `hidden` rather than taking the matched set**, because the caller has
+just written it and that is the shortest true description of what survived — and
+because reading it is what lets the helper nest. A country is empty when every
+city in it is hidden; a region is empty when every country in it is hidden,
+*including the ones the previous call just hid*.
+
+**Which makes the order load-bearing: innermost first.**
+
+```ts
+hideEmpty(countries, (c) => within(c).all("[data-city]"));
+hideEmpty(regions,   (r) => within(r).all("[data-country]"));
+```
+
+Run the other way round, the regions are judged against countries nothing has
+hidden yet, and an empty region survives. Nothing errors — the page just keeps a
+heading it should have dropped, which is the failure this exists to prevent.
+`tests/filters-view.test.ts` pins the wrong order too, so the constraint is
+recorded as behaviour rather than only as prose.
+
+A group with no children at all is hidden, by the same rule: there is nothing
+visible in it.
+
+### Why these write instead of calling back
+
+`filters.onChange` is already the callback that hands a consumer the answer and
+gets out of the way, and it is where all three lists do what they each do
+differently. A second callback layer here would hand back `query` and `count`, or
+`group` and `isEmpty`, and leave the same writes spelled out at every call site —
+which is the duplication these were extracted from. A helper whose action is
+fixed and whose decision is trivial earns its place by doing the action; hand
+that back and there is no helper left.
+
+So the layering is three levels, each opt-in:
+
+```ts
+filters({ … })                          // total freedom, and what all three did first
+filters({ … }) + searchBox              // twelve lines gone
+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.
+
+## 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.
+
+`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
+dependency and setting `environment` in `vitest.config.ts` is what that would
+take.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.3",
+    "version": "0.1.4",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -21,6 +21,7 @@
         "./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"
     },
     "bin": {
@@ -32,6 +33,9 @@
         "docs",
         "README.md"
     ],
+    "engines": {
+        "node": ">=22.12.0"
+    },
     "scripts": {
         "test": "npm run test:types && npm run test:unit && npm run test:examples",
         "test:types": "tsc --noEmit && astro check --root checks/astro",
@@ -44,12 +48,14 @@
         "check-fmt": "biome check . --error-on-warnings"
     },
     "peerDependencies": {
-        "astro": ">=7"
+        "@types/node": ">=22",
+        "astro": ">=7",
+        "typescript": ">=5"
     },
     "devDependencies": {
         "@biomejs/biome": "2.5.10",
-        "@types/node": "26.2.0",
-        "astro": "7.2.4",
+        "@types/node": "26.3.0",
+        "astro": "7.2.6",
         "typescript": "6.0.3",
         "vitest": "4.1.11"
     }

package/src/astro/filters-view.ts

@@ -0,0 +1,253 @@
+/**
+ * The DOM writes every filtered list turns out to make, and only those.
+ *
+ * `filters` decides which items match and what the address bar says, and hands
+ * both to `onChange`. Everything a page does about that answer is its own — and
+ * mostly stays that way: three lists in one repository draw their results three
+ * different ways, with tabs and a blurb on one, an exclusive `<details>`
+ * accordion on another, a two-level country roll-up on the third.
+ *
+ * These two helpers are what all three, or two of three, wrote identically. That
+ * is the whole bar for being here: not "a list might want this" but "every list
+ * we have written already did, character for character, and getting it wrong was
+ * silent". Anything the three disagreed about is still theirs.
+ *
+ * **Both take elements, never selectors.** A project decides what its markup is
+ * called and hands over what it found, so no attribute name in this package has
+ * to be matched by any consumer — the reason `filters` itself has no markup
+ * contract, kept intact one layer up.
+ *
+ * These write to elements, which the rest of `astro/` refuses to do, and the
+ * line is worth being exact about. `carousel` will not write a transform because
+ * a transform is a design decision with no single right answer. Everything
+ * written here is the opposite: an input's `value` is the control's own state,
+ * and `hidden` on a clear button, an empty message or a section with nothing
+ * left in it is binary and derived. Nothing here sets a class, a style or an
+ * `aria` attribute, which is where the choices live.
+ *
+ * Two notes for the markup on the other side of that boundary:
+ *
+ * - **`hidden` needs help in a grid.** It is a `display: none` from the user
+ *   agent, and any author rule setting `display: flex` or `grid` beats it. A
+ *   project on Tailwind v4 gets `[hidden] { display: none !important }` from
+ *   preflight and needs nothing; anything else should ship that rule itself, or
+ *   every one of these writes is inert and the list simply never filters.
+ * - **A result count wants `aria-live="polite"`.** Filtering as you type changes
+ *   the page silently for anyone not looking at it. The attribute belongs on the
+ *   element in the template, not here — this package is handed elements and does
+ *   not decide what they are.
+ */
+
+import type { FieldMap, Filters } from "./filters.ts";
+
+/**
+ * The fields of `F` that hold text, so a search box cannot be pointed at a flag.
+ *
+ * `list.set(field, input.value)` hands over a string; aimed at a `flag` that is
+ * a type error worth getting at the call site rather than a filter that silently
+ * never matches.
+ */
+export type TextFieldOf<F extends FieldMap> = {
+    [K in keyof F]: F[K] extends { kind: "text" } ? K : never;
+}[keyof F];
+
+/**
+ * What a search box is made of, as much of it as exists.
+ *
+ * Every part is optional and `null` is accepted, because `within(root).one(…)`
+ * returns `null` and a page is allowed to have a search field with no clear
+ * button, or a list with no empty state. Handing over what a lookup returned,
+ * without checking it first, is the point.
+ */
+export interface SearchBoxElements {
+    readonly input?: HTMLInputElement | null;
+    /** Clears the field. Hidden while the field is already empty. */
+    readonly clear?: HTMLElement | null;
+    /**
+     * The "nothing matched" message.
+     *
+     * Tracks the whole result set rather than this field alone — a list emptied
+     * by a category is as empty as one emptied by a query, and there is one
+     * message either way. It lives here because it is the same line in every
+     * consumer, not because it belongs to the search box.
+     */
+    readonly empty?: HTMLElement | null;
+    /**
+     * How many matched, written as digits and nothing else.
+     *
+     * Two of the three write this, and the same way. Digits only, because the
+     * sentence around them is not ours to build: a list that reads "6 of 42" in
+     * one language reads "6 din 42" in another, and a translated string is not
+     * something to take apart in a browser to get at one number. Give the count
+     * an element of its own and let the copy sit beside it — which is what the
+     * consumer doing this already had to do.
+     *
+     * Same rule as the rest of this file, one field further: derived, and with
+     * no choice in it. Where the number *goes* is still the template's.
+     *
+     * Give it `aria-live="polite"` there. Filtering as you type changes the
+     * page silently for anyone not watching it, and this package is handed
+     * elements rather than deciding what they are.
+     */
+    readonly count?: HTMLElement | null;
+}
+
+export interface SearchBox {
+    /**
+     * Brings the box into line with the state, from inside `onChange`.
+     *
+     * Takes two scalars rather than the change object, so this stays independent
+     * of what the field was named and of which other fields the list has.
+     *
+     * Safe before `bind` and after the undo it returns: this only writes to the
+     * elements it was given, so a box that is no longer wired renders the last
+     * thing it was told rather than throwing.
+     */
+    render(query: string, matchCount: number): void;
+    /**
+     * Points the input and the clear button at one `text` field of a list, and
+     * returns the undo.
+     *
+     * Separate from construction because of an ordering knot rather than a
+     * preference: `render` is called from the list's own `onChange`, so the box
+     * has to exist before the list, and this needs the list. Two calls and a
+     * `const` each way is the honest version of that; the alternative is a `let`
+     * the reader has to hold in their head.
+     *
+     * One `AbortController`, as everywhere else here — see `carousel.attach`.
+     */
+    bind<F extends FieldMap>(
+        list: Filters<F>,
+        field: TextFieldOf<F>
+    ): () => void;
+}
+
+/**
+ * The search input beside a `filters` list, and the two things every one of them
+ * has to remember.
+ *
+ * ```ts
+ * const search = searchBox({
+ *     input: one<HTMLInputElement>("[data-filter-search]"),
+ *     clear: one("[data-filter-clear]"),
+ *     empty: one("[data-filter-empty]"),
+ *     count: one("[data-filter-count]"),
+ * });
+ *
+ * const list = filters({
+ *     fields, items,
+ *     onChange({ state, matched }) {
+ *         search.render(state.q, matched.size);
+ *         // …everything this list draws for itself
+ *     },
+ * });
+ *
+ * const unbind = search.bind(list, "q");
+ * const detach = list.attach();
+ * ```
+ *
+ * It writes rather than calling back, and that is the only reason it exists.
+ * `filters.onChange` is already the callback that hands a consumer the value and
+ * gets out of the way; a second one here would hand back `query` and `count` and
+ * leave the same three writes to be spelled out at every call site, which is the
+ * duplication this was extracted from.
+ */
+export function searchBox(elements: SearchBoxElements): SearchBox {
+    const { input, clear, empty, count } = elements;
+
+    return {
+        render(query, matchCount) {
+            // Guarded by inequality, not written unconditionally. Assigning
+            // `value` while someone is typing in the field moves the caret to
+            // the end, so the one case this exists for — state that moved
+            // without the keyboard, from the back button or a `reset` — must not
+            // cost a caret jump on every other keystroke.
+            if (input != null && input.value !== query) input.value = query;
+            if (clear != null) clear.hidden = query === "";
+            if (empty != null) empty.hidden = matchCount > 0;
+            if (count != null) count.textContent = String(matchCount);
+        },
+
+        bind(list, field) {
+            const listeners = new AbortController();
+            const { signal } = listeners;
+            // The narrowing `TextFieldOf` already did, restated for the
+            // implementation: inside a generic function TypeScript cannot see
+            // that this field's value type is `string`, though every caller can.
+            const name = field as Parameters<typeof list.set>[0];
+
+            input?.addEventListener(
+                "input",
+                () => list.set(name, input.value as never),
+                { signal }
+            );
+
+            clear?.addEventListener(
+                "click",
+                () => {
+                    list.reset(name);
+                    // Focus follows the click, because the button the pointer
+                    // was on has just hidden itself — leaving focus on a
+                    // `hidden` element strands a keyboard reader at a control
+                    // that is no longer there.
+                    input?.focus();
+                },
+                { signal }
+            );
+
+            return () => listeners.abort();
+        },
+    };
+}
+
+/**
+ * Hides each group that has nothing visible left inside it.
+ *
+ * ```ts
+ * onChange({ matched }) {
+ *     for (const item of items) item.hidden = !matched.has(keyOf(item));
+ *     hideEmpty(groups, (group) => within(group).all("[data-faq-key]"));
+ * }
+ * ```
+ *
+ * A filtered list that renders its results under headings has this problem and
+ * nothing else does: hide the items and the headings stay, so a search for one
+ * word leaves a page of section titles with nothing under them. It reads as a
+ * broken template rather than as a result, which is what makes forgetting it
+ * expensive — nothing errors, and the page looks wrong in a way that does not
+ * point at the filter.
+ *
+ * **Reads `hidden`, rather than taking the matched set.** The items were just
+ * hidden by the caller, so their state is the shortest true description of what
+ * survived — and reading it is what lets this nest. A country is empty when
+ * every city in it is hidden; a region is empty when every country in it is
+ * hidden, *including the ones this call just hid*.
+ *
+ * **Which makes the order load-bearing: innermost first.**
+ *
+ * ```ts
+ * hideEmpty(countries, (c) => within(c).all("[data-city]"));
+ * hideEmpty(regions, (r) => within(r).all("[data-country]"));
+ * ```
+ *
+ * Run the other way round, the regions are judged against countries that have
+ * not been hidden yet, and a region with nothing in it survives.
+ *
+ * A group with no children at all is hidden, which is the same answer by the
+ * same rule — there is nothing visible in it.
+ */
+export function hideEmpty<T extends HTMLElement>(
+    groups: Iterable<T>,
+    childrenOf: (group: T) => Iterable<HTMLElement>
+): void {
+    for (const group of groups) {
+        let visible = false;
+        for (const child of childrenOf(group)) {
+            if (!child.hidden) {
+                visible = true;
+                break;
+            }
+        }
+        group.hidden = !visible;
+    }
+}

package/src/astro/filters.ts

@@ -24,9 +24,9 @@
  *         q: { kind: "text", param: "q" },
  *         category: { kind: "choice", param: "category" },
  *     },
- *     items: games.map((game) => ({
- *         key: game.id,
- *         values: { q: `${game.name} ${game.blurb}`, category: game.category },
+ *     items: entries.map((entry) => ({
+ *         key: entry.id,
+ *         values: { q: `${entry.title} ${entry.summary}`, category: entry.category },
  *     })),
  *     onChange: ({ matched }) => {
  *         for (const [key, element] of elements) element.hidden = !matched.has(key);
@@ -63,7 +63,7 @@
  * - `text` — free entry, folded and substring-matched. The search box.
  * - `choice` — one of a set, or none. Tabs, a `<select>`, a radio group.
  * - `flag` — a narrowing toggle: off matches everything, on keeps only the
- *   items that carry it. "Arena only", "In stock".
+ *   items that carry it. "In stock", "Step-free access".
  *
  * `flag` is not a tri-state and should not become one. On, off and *either* is
  * a `choice` with two values; folding that into a toggle gives a control with a
@@ -198,8 +198,8 @@ const DIACRITICS = /[̀-ͯ]/g;
  * A string reduced to what a query should match against.
  *
  * Decompose, drop the marks, lowercase, trim. This is the part every list needs
- * and few have: without it a reader typing `abilita` is told there is no
- * *Abilità*, and a Romanian catalogue hides every entry spelled with `ă`, `ș` or
+ * and few have: without it a reader typing `malaga` is told there is no
+ * *Málaga*, and a Romanian catalogue hides every entry spelled with `ă`, `ș` or
  * `ț` from anyone whose keyboard does not carry them.
  */
 function fold(value: string): string {
@@ -213,7 +213,7 @@ function fold(value: string): string {
  * An unset flag is *absent* rather than `=0`. One way to say off keeps the URL
  * short and means there is a single form to handle; two would both have to be
  * understood forever, and a reader could not tell which of them a link was
- * carrying. The cost is that a hand-written `?arena=0` reads as off, which is
+ * carrying. The cost is that a hand-written `?featured=0` reads as off, which is
  * the answer it would get anyway.
  *
  * `1` and not `true` because that is what the existing lists already emit:
@@ -293,10 +293,18 @@ export function filters<const F extends FieldMap>(
     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.
-        const queries = new Map<string, string>();
+        // 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[]>();
         for (const name of names) {
             if (fields[name]?.kind !== "text") continue;
-            queries.set(name, fold(state[name] as string));
+            const folded = fold(state[name] as string);
+            queries.set(name, folded === "" ? [] : folded.split(/\s+/));
         }
 
         const next = new Set<string>();
@@ -305,13 +313,10 @@ export function filters<const F extends FieldMap>(
             for (const name of names) {
                 const kind = fields[name]?.kind;
                 if (kind === "text") {
-                    const query = queries.get(name) ?? "";
-                    if (query === "") continue;
-                    if (
-                        !(haystacks.get(item.key)?.get(name) ?? "").includes(
-                            query
-                        )
-                    ) {
+                    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;
                     }
@@ -344,9 +349,13 @@ export function filters<const F extends FieldMap>(
             const field = fields[name];
             if (field === undefined) continue;
             if (field.param === undefined) {
-                // No parameter: the field is state-only, and a reload starts it
-                // empty rather than carrying a value the URL never held.
-                next[name] = empty(name);
+                // A state-only field is not in the URL, so the URL has nothing
+                // to say about it — and a back button is the URL speaking.
+                // Clearing it here read "absent from the URL" as "empty", which
+                // wiped a search the reader was in the middle of the moment any
+                // other parameter on the page moved. Left as it is instead: this
+                // function applies the URL, and this field is not in it.
+                next[name] = state[name];
                 continue;
             }
             const raw = search.get(field.param);
@@ -358,11 +367,23 @@ export function filters<const F extends FieldMap>(
     function writeUrl(history: "push" | "replace"): void {
         if (!attached) return;
 
-        // Built from the declaration rather than from the URL that is there, so
-        // a parameter this list owns and no longer needs is dropped instead of
-        // surviving because nobody thought to delete it. Fields are written in
-        // declaration order, so the same state always produces the same URL.
-        const search = new URLSearchParams();
+        // Started from the URL that is there, not from an empty set. A list owns
+        // the parameters it declared and nothing else, and the page around it is
+        // full of parameters that are not its business — `utm_*` on a link
+        // someone shared, a page number, another widget's state. Building from
+        // scratch published a URL with all of them gone, and the loss only
+        // showed up somewhere else: a campaign that stopped being attributed the
+        // first time a visitor typed in the search box.
+        //
+        // Its own are deleted first, then rewritten, so a parameter this list
+        // owns and no longer needs is dropped rather than surviving because
+        // nobody thought to remove it. Deletion and writing both run in
+        // declaration order, so one state still produces one URL.
+        const search = new URLSearchParams(window.location.search);
+        for (const name of names) {
+            const param = fields[name]?.param;
+            if (param !== undefined) search.delete(param);
+        }
         for (const name of names) {
             const field = fields[name];
             if (field?.param === undefined) continue;
@@ -375,13 +396,24 @@ export function filters<const F extends FieldMap>(
         }
 
         const query = search.toString();
-        // The bare path when nothing is set, rather than a trailing `?`: the two
-        // are the same page, and only one of them is worth sharing.
+        // The bare path when nothing is left, rather than a trailing `?`: the
+        // two are the same page, and only one of them is worth sharing. Read
+        // from the merged set, so a page carrying somebody else's parameter
+        // keeps it instead of being reduced to its path.
         const url = query === "" ? window.location.pathname : `?${query}`;
         if (history === "push") window.history.pushState({}, "", url);
         else window.history.replaceState({}, "", url);
     }
 
+    /**
+     * One field's value as the matcher and the URL will read it.
+     *
+     * Only `text` has a form that differs from what was handed over — the other
+     * kinds compare and publish exactly what they hold.
+     */
+    const normalized = (name: keyof F & string, value: unknown): unknown =>
+        fields[name]?.kind === "text" ? (value as string).trim() : value;
+
     const announce = (): void => onChange({ state, matched });
 
     recompute();
@@ -396,11 +428,21 @@ export function filters<const F extends FieldMap>(
 
         set(field, value, setOptions) {
             const name = field as keyof F & string;
-            // Nothing changed, so nothing is announced and nothing is pushed.
-            // Typing a character that does not alter a trimmed query, or
-            // re-selecting the tab that is already current, should not put a
-            // step in history for the back button to walk through.
-            if (state[name] === value) return;
+            // Compared as everything downstream will read it, not as it arrived.
+            // Both the matcher and the URL trim a query, so "sol" and "sol "
+            // filter the same list and publish the same address — but comparing
+            // them raw called that a change, and a trailing space cost a
+            // recompute, a `replaceState` to a URL identical to the current one,
+            // and a full re-render of every item.
+            //
+            // The *raw* value is what gets stored, though, and that asymmetry is
+            // deliberate. A search box mirrors the state back into the input
+            // (see `filters-view`), so normalising here would delete the space a
+            // reader had just typed, from under the caret, every time they
+            // reached for the second word.
+            if (normalized(name, state[name]) === normalized(name, value)) {
+                return;
+            }
 
             state = { ...state, [name]: value };
             recompute();
@@ -411,6 +453,12 @@ export function filters<const F extends FieldMap>(
 
         reset(field) {
             if (field === undefined) {
+                // Short-circuited like the single-field arm below, which it was
+                // not. A "clear all" on a list nobody has filtered yet is a
+                // no-op, and pushing for it puts a step in history that goes
+                // back to the state it is already in — so the back button looks
+                // broken to the one reader who pressed clear twice.
+                if (names.every((name) => state[name] === empty(name))) return;
                 state = blank();
             } else {
                 const name = field as keyof F & string;

package/src/contact-form.ts

@@ -41,7 +41,7 @@ export interface MailEndpoint {
      */
     readonly url: HttpsUrl;
     /**
-     * The account the message is sent on behalf of: `"b2b_cube"`.
+     * The account the message is sent on behalf of, e.g. `"acme_b2b"`.
      *
      * What the API looks the mailbox and the allowed domains up by. A domain
      * that is not registered against it is refused, and nothing configured here

package/src/index.ts

@@ -101,6 +101,8 @@ export {
     breadcrumbList,
     businessId,
     type CatalogEntry,
+    type FaqEntry,
+    faqPage,
     geoCoordinates,
     type JsonLdNode,
     type LocalBusinessInput,

package/src/jsonld/faq.ts

@@ -0,0 +1,105 @@
+import { warn } from "../warn.ts";
+import type { JsonLdNode } from "./node.ts";
+
+/** One question and the answer the page gives for it. */
+export interface FaqEntry {
+    readonly question: string;
+    /**
+     * The answer, as plain text.
+     *
+     * Google accepts a small amount of HTML here — `<p>`, `<br>`, `<ol>`,
+     * `<ul>`, `<li>`, `<a>`, `<b>`, `<strong>`, `<i>`, `<em>` — and drops
+     * everything else. Plain text is what a caller passing a translated string
+     * has anyway, and it cannot be silently half-rendered, so nothing here
+     * builds markup for you. Pass the markup yourself if the answer needs it.
+     *
+     * Checked August 2026.
+     */
+    readonly answer: string;
+}
+
+/**
+ * The questions a page answers, as a `FAQPage`.
+ *
+ * **Read this before calling it: it renders nowhere, and it is not free.** This
+ * node was in `docs/NOT-BUILT.md` until it was asked for, and the reasoning
+ * there is the reason it stays opt-in rather than something `metaFor()` emits.
+ *
+ * Google restricted FAQ rich results to *"well-known, authoritative government
+ * and health websites"* in 2023, then removed them from Search entirely on
+ * 7 May 2026 and archived the documentation. There is no expandable Q&A under a
+ * commercial result any more, and no flag to earn one back.
+ *
+ * **A model does not read it either** — the argument for emitting it anyway,
+ * and it does not hold. JSON-LD sits in a `<script>` block, and the
+ * HTML-to-text pipelines feeding a model routinely drop `<script>` and often
+ * the whole `<head>`. Independent testing through 2025–26 repeatedly found that
+ * content present *only* in structured data goes unextracted, while the same
+ * content in visible headings and paragraphs is read reliably. A FAQ page's
+ * questions are already visible text; that is what gets read.
+ *
+ * **What it can still buy.** Schema is parsed at *indexing* time, so it reaches
+ * the surfaces built on a search index rather than only those fetching the page.
+ * Bing has said outright that its LLMs read schema, which is the live
+ * third-party payoff and the reason this exists at all.
+ *
+ * **The cost, which is the part that decides it.** Every other node here is
+ * metadata *about* a page — an address, a price, a date. This one is a verbatim
+ * *copy of* it: every question and every full answer a second time, in a script
+ * block on the page already showing them. A ten-question FAQ is several KB
+ * duplicated on every load, and page weight is paid per visitor, forever. Call
+ * this where that trade has been made deliberately, not by default.
+ *
+ * **Only questions the page actually shows.** The node is a description of the
+ * page, not a second copy of a FAQ that lives elsewhere: Google's first quality
+ * rule is that the content "must be visible to the user on the source page",
+ * and a node listing answers a reader cannot find is the kind of mismatch that
+ * earns a manual action rather than a warning. A page rendering a subset — the
+ * questions it has answers for, say — passes that subset.
+ *
+ * No `@id`: nothing in a graph refers to a `FAQPage`, and an id is for being
+ * pointed at. See the note at the top of `ids.ts`.
+ *
+ * Throws on an empty list rather than emitting an empty node. `mainEntity` is
+ * required, so a `FAQPage` holding no questions is not a thin node — it is an
+ * invalid one, saying the page is a FAQ and then naming nothing it answers.
+ * Whether a page has questions to show is the caller's to know, and a page with
+ * none should leave the node out of its graph rather than pass an empty list
+ * and hope.
+ *
+ * Reference, now archived rather than current guidance:
+ * <https://developers.google.com/search/docs/appearance/structured-data/faqpage>
+ *
+ * @param at What to name when this is wrong — the page's canonical URL.
+ */
+export function faqPage(entries: readonly FaqEntry[], at: string): JsonLdNode {
+    if (entries.length === 0) {
+        throw new Error(
+            `${at}: a FAQPage needs at least one question. Leave the node out of the graph on a page that shows none, rather than emitting one that answers nothing.`
+        );
+    }
+
+    const seen = new Set<string>();
+    for (const entry of entries) {
+        const key = entry.question.trim().toLowerCase();
+        if (seen.has(key)) {
+            warn(
+                at,
+                `two questions read "${entry.question}". Google merges a repeated question rather than listing it twice, so the second answer is dropped.`
+            );
+        }
+        seen.add(key);
+    }
+
+    return {
+        "@type": "FAQPage",
+        mainEntity: entries.map((entry) => ({
+            "@type": "Question",
+            name: entry.question,
+            acceptedAnswer: {
+                "@type": "Answer",
+                text: entry.answer,
+            },
+        })),
+    };
+}

package/src/jsonld/index.ts

@@ -32,6 +32,7 @@
 export { type ArticleInput, article } from "./article.ts";
 export { type BreadcrumbStep, breadcrumbList } from "./breadcrumb.ts";
 export { type LocalBusinessInput, localBusiness } from "./business.ts";
+export { type FaqEntry, faqPage } from "./faq.ts";
 export {
     type BusinessId,
     businessId,

package/src/jsonld/video.ts

@@ -11,8 +11,8 @@ interface VideoDetails {
      * The site's own origin, which the thumbnails are made absolute against.
      *
      * An origin rather than the page's URL: `joinUrl` puts a path on the end of
-     * what it is given, so handing it `…/challenges/cardio` would produce
-     * `…/challenges/cardio/thumb.png`. The same bargain `localBusiness` strikes,
+     * what it is given, so handing it `…/rooms/blue-room` would produce
+     * `…/rooms/blue-room/thumb.png`. The same bargain `localBusiness` strikes,
      * named for what it actually needs.
      */
     readonly origin: HttpsUrl;