@escape-game-over/atlas 0.1.24 → 0.1.25

package/README.md

@@ -61,7 +61,7 @@ Linking to a page the active deployment switched off is a compile error, not a
 One file per deployment, saying only what differs:
 
 ```ts
-export default defineProject(config, defaultMessages, defaultRoutes, {
+export default atlas.project(defaultMessages, defaultRoutes, {
   url: "https://acme.example",
   siteName: "Acme Rome",
   icon,
@@ -92,22 +92,22 @@ never writes a type argument:
 
 ```ts
 // 1. which languages exist, how URLs are shaped
-export default defineSiteConfig({ locales: {...}, defaultRouting: {...} })
+export const atlas = defineSite({ locales: {...}, defaultRouting: {...} })
 
 // 2. the base copy and routes
-export const baseMessages = defineMessages(config, {...})
-export const baseRoutes   = defineRoutes(config, {...})
+export const baseMessages = atlas.messages({...})
+export const baseRoutes   = atlas.routes({...})
 
 // 3. one deployment
-export default defineProject(config, baseMessages, baseRoutes, {...})
+export default atlas.project(baseMessages, baseRoutes, {...})
 
 // 4. the API the pages use
-export const site = createSite(config, baseMessages, baseRoutes, project)
+export const site = atlas.site(baseMessages, baseRoutes, project)
 ```
 
 Step 4 returns `t()`, `rich()`, `plain()`, `pathFor()`, `urlFor()`, `fileUrl()`,
-`alternatesFor()`, `localeLinksFor()`, `metaFor()`, `breadcrumbFor()`,
-`staticPaths()`, `routes`, `entries`, `sitemap()`, `robots()`, `llms()` and
+`localeLinksFor()`, `metaFor()`, `breadcrumbFor()`,
+`getStaticPaths()`, `routes`, `sitemap()`, `robots()`, `llms()` and
 `redirects()` already wired.
 
 `t()` is bound to a locale and knows each message's `{placeholders}` from its
@@ -233,7 +233,7 @@ worded.
 The same question answers it every time: *would this differ between two pages of
 the same site?*
 
-| Per page — passed to `metaFor()` | Site-level — declared in `defineProject()` |
+| Per page — passed to `metaFor()` | Site-level — declared in `atlas.project()` |
 | -------------------------------- | ------------------------------------------ |
 | `title`, `description`           | `siteName`, `twitterSite`                  |
 | `image` (asset **and** its alt)  | `icon`, `themeColor`, `colorScheme`        |
@@ -251,16 +251,9 @@ actually renders, and why `twitter:card` is pinned.
 
 A project switches routes off. Anything defined *alongside* a route then has two
 ways to rot: the page is built and its config is missing, or the page is gone and
-its config lingers. Two types, differing only in how many routes they speak for:
+its config lingers. `PerRoute<typeof site, T>` rejects both.
 
-|                       | `PerRoute<typeof site, T>`           | `WhenEnabled<typeof site, "careers", T>`         |
-| --------------------- | ------------------------------------ | ------------------------------------------------ |
-| Shape                 | a table keyed by route id            | a single value                                   |
-| Says                  | "every built route has one of these" | "this value belongs to *that* page"              |
-| When the route is off | that key is rejected                 | the type is `never` — the field cannot be filled |
-| Use with              | `satisfies`                          | a normal annotation                              |
-
-`PerRoute` must be used with `satisfies`, not as an annotation: excess-property
+It must be used with `satisfies`, not as an annotation: excess-property
 checking is what catches the stale half, and only an object literal checked
 against a known target gets it.
 
@@ -269,8 +262,6 @@ const heroes = {
     home: { variant: "wide" },
     about: { variant: "tall" },
 } satisfies PerRoute<typeof site, Hero>;   // ✗ if `about` is off, ✗ if `contact` is on
-
-const careers: WhenEnabled<typeof site, "careers", Careers> = { ats: "…" };  // ✗ if off
 ```
 
 ## The rules this package keeps
@@ -299,16 +290,8 @@ const careers: WhenEnabled<typeof site, "careers", Careers> = { ats: "…" };  /
   ".":                  "./src/index.ts",
   "./astro":                  "./src/astro/index.ts",
   "./astro/images":           "./src/astro/images.ts",
-  "./astro/background-video": "./src/astro/background-video.ts",
-  "./astro/carousel":         "./src/astro/carousel.ts",
-  "./astro/consent":          "./src/astro/consent.ts",
-  "./astro/dev-log":          "./src/astro/dev-log.ts",
-  "./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"
+  "./astro/document":         "./src/astro/Document.astro",
+  "./client":                 "./src/astro/client.ts"
 }
 ```
 
@@ -324,27 +307,27 @@ 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`,
-`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
+`./client` is the browser half — `carousel`, `filters`, `filters-view`,
+`youtube`, `background-video`, `consent`, `element` — one path
+for all of it. 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
+`Document.astro` could not go through `tsc` anyway, and Astro's own
 `tsconfigs/base.json` already sets `allowImportingTsExtensions`, so every
 consumer gets it for free.
 
 ## The `atlas` command
 
 ```bash
-atlas use <project>          # copies config/projects/<name> -> config/project
+atlas use <project>          # links config/project -> config/projects/<name>
 atlas use --fallback rome    # only when nothing else named one
 ```
 
-The whole directory is copied, so extra files and nested folders come along
-without touching the tool — the contract is just that it contains `project.ts`.
+A link, not a copy: an edit made through `config/project` lands in the real
+file. A directory junction on Windows, which needs no admin rights. Ignore it with
+`**/config/project` — no trailing slash, since git sees a link as a file. The
+contract is just that the project contains `project.ts`.
 It resolves paths from the working directory, so a workspace's own
 `package.json` passes nothing. A deployment pipeline can skip it and write its
 own `config/project`.
@@ -358,7 +341,7 @@ command whose output gets deployed has to say what it is building.
 ```txt
 src/            the package — see the export map above for what is reachable
   index.ts        the public API
-  site/           createSite() and the Site it returns
+  site/           defineSite(), createSite() and the Site it returns
   meta/           head tags: canonical, hreflang, Open Graph, Twitter, robots
   jsonld/         the @graph — one file per node, each linked to Google's docs
   i18n/           defineMessages(), t(), placeholder extraction
@@ -400,9 +383,9 @@ proves the package is genuinely independent of anything consuming it.
 
 The `astro check` pass covers `src/astro/`, the one directory that cannot meet
 that bar. It needs `astro/client` for `astro:assets` and `ImageMetadata`, and
-`MetaTags.astro` needs a checker that can parse `.astro` at all — `tsc` reads
-zero `.astro` files no matter how they are globbed. Without this pass the one
-component the package ships is checked by nothing: `astro check` in
+the `.astro` components need a checker that can parse `.astro` at all — `tsc` reads
+zero `.astro` files no matter how they are globbed. Without this pass the
+components the package ships are checked by nothing: `astro check` in
 `test:examples` only ever walks an example's own `src/`, so it never reaches it,
 and a type error there passes the entire gate.
 
@@ -412,7 +395,7 @@ practical reason: `astro check` writes a `.astro/` types directory and a
 publish both. The `tsconfig.json` there adds nothing — it extends
 `src/astro/tsconfig.json` and only widens the glob, so the rules stay in one
 place. `src/astro/tsconfig.json` is what an editor finds; without it, opening
-`MetaTags.astro` resolves against the root config, which supplies no ambient
+`Document.astro` resolves against the root config, which supplies no ambient
 types, and every prop degrades to `any`.
 
 `test:examples` **builds every deployment**, not just type-checks one, and both

package/bin/use-project.mjs

@@ -1,16 +1,19 @@
 #!/usr/bin/env node
 /**
- * Copies a project overlay into `config/project`, the folder the whole build
+ * Links `config/project` to one project overlay, the folder the whole build
  * reads from. Run automatically before `dev`, `build` and `check`.
  *
+ * A link rather than a copy, so an edit made through `config/project` — where
+ * an editor's go-to-definition lands — is an edit to the real file. A
+ * junction on Windows, which needs no admin rights; a symlink elsewhere.
+ *
  *   atlas use acme
  *   PROJECT=acme npm run build
  *
- * The entire project directory is copied, so extra files and nested folders come
- * along automatically. A deployment pipeline can skip this command and write its
- * own `config/project` — the contract is just that it contains `project.ts`.
+ * A deployment pipeline can skip this command and write its own
+ * `config/project` — the contract is just that it contains `project.ts`.
  */
-import { cp, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { lstat, readdir, rm, stat, symlink, unlink } from "node:fs/promises";
 import { join } from "node:path";
 
 /**
@@ -26,10 +29,7 @@ import { join } from "node:path";
 const ROOT = process.cwd();
 const PROJECTS_DIR = join(ROOT, "config", "projects");
 const TARGET_DIR = join(ROOT, "config", "project");
-/**
- * Only an entry-point check — the whole directory is copied recursively, so a
- * project can add files and folders freely without touching this script.
- */
+/** Only an entry-point check: a project can add files and folders freely. */
 const ENTRY_FILE = "project.ts";
 
 /**
@@ -122,10 +122,15 @@ if (!(await exists(join(sourceDir, ENTRY_FILE)))) {
     process.exit(1);
 }
 
-await rm(TARGET_DIR, { recursive: true, force: true });
-await cp(sourceDir, TARGET_DIR, { recursive: true });
-await writeFile(join(TARGET_DIR, ".project"), `${name}\n`, "utf8");
+// Only the link goes, never what it points at. A real directory is a copy left
+// by an older version of this command.
+const existing = await lstat(TARGET_DIR).catch(() => undefined);
+if (existing?.isSymbolicLink()) await unlink(TARGET_DIR);
+else if (existing !== undefined) await rm(TARGET_DIR, { recursive: true });
+
+// "junction" is Windows' no-admin directory link, and ignored everywhere else.
+await symlink(sourceDir, TARGET_DIR, "junction");
 
 console.log(
-    `Using project "${name}" (config/projects/${name} -> config/project)`
+    `Using project "${name}" (config/project -> config/projects/${name})`
 );

package/docs/NOT-BUILT.md

@@ -230,7 +230,7 @@ type could — a property that is not valid for the type it sits on.
 ### Should a paragraph be authored as an array of translation keys?
 
 **No. One sentence is one message, and the styling lives in the copy as
-`[marks]`. `content/` carries the parser, the runs and `plain()`; nothing
+`[marks]`. `content/` carries the parser, the runs and `site.plain()`; nothing
 carries a `ContentItem[]`.**
 
 This is the shape the sibling B2C template uses, and it is the one thing from

package/docs/client-scripts.md

@@ -32,33 +32,26 @@ 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                        |
-| `./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`          | registering a custom element, and ending what it started        | what the element does while it is on the page   |
-| `./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
-banner has to know — but it can only answer once it has been downloaded, so a
-project that asks it alone ships the banner's script to every page to be told,
-three requests later, that there was nothing to ask about. `consentRequired()`
-from the package root is the same question at build time: false, and the banner
-never reaches the HTML. Gate the render on that and keep the runtime check for
-the banner that is rendered. See NOT-BUILT.md on where the halves divide.
-
-**A script imports one path: `@escape-game-over/atlas/client`**, which re-exports
-every module above. All of it exists to touch a live document, so it belongs in
-a `<script src>` and not in frontmatter or `astro.config.ts`. A component's
-contract is the one thing both halves need, and it stays on `./astro/markup`,
-which touches nothing.
+| Module             | Owns                                                           | Leaves to the project                           |
+| ------------------ | -------------------------------------------------------------- | ----------------------------------------------- |
+| `carousel`         | which slide is current: modulo, swipe, autoplay, the move lock | the transform, dots, arrows, `aria`             |
+| `filters`          | which items match, and what the address bar says               | every DOM read and write                        |
+| `filters-view`     | the two DOM writes every filtered list turned out to share     | finding the elements, and everything else drawn |
+| `youtube`          | the swap from poster to player, on the click and not before    | the poster, the button, the iframe's classes    |
+| `background-video` | playing or paused, playable or not, and which cut is loaded    | the play/pause control, its icons and its label |
+| `consent`          | remembering an answer, expiring it, handing it to Google       | the banner — its wording, its buttons, its law  |
+| `element`          | registering a custom element, and ending what it started       | what the element does while it is on the page   |
+
+`consent` is the one module that ships its own behaviour: `<ConsentBanner
+analytics={…}>` (`@escape-game-over/atlas/astro/consent-banner`) renders the
+site's markup as its children, skips itself — script included — when the
+analytics need no permission, and remembers, expires and applies the answer. The
+markup spreads `consent.accept` and `consent.decline` on its buttons, and
+`consent.reopen` on the control that brings it back.
+
+**Browser code has one import path: `@escape-game-over/atlas/client`**, which
+re-exports every module above. None of it touches the DOM at import, so an
+element's contract can be imported in frontmatter from the same path.
 
 ## Lifetimes are the recurring bug
 
@@ -75,21 +68,17 @@ const detach = loop.attach(video);            // background-video: the <video>
 const detach = trailer.attach(button, box);   // youtube: what is pressed, what it replaces
 ```
 
-`defineElement` says the same thing in the shape a custom element needs. One
-function per element: it runs when the element enters the page, `signal` ends
-what it registered when the element leaves, and what it returns is the undo for
-everything else.
+`element` says the same thing in the shape a custom element needs: its function
+runs when the element enters the page, `signal` ends what it registered when the
+element leaves, and what it returns is the undo for everything else.
 
 ```ts
-defineElement(thing, (host, signal) => {
-    host.addEventListener("click", open, { signal });   // ends with the visit
-    return loop.attach(host);                           // and so does this
+export const thing = element("go-thing", { button: marker }, (host, { button }, signal) => {
+    button.one()?.addEventListener("click", open, { signal });   // ends with the visit
+    return loop.attach(host);                                     // and so does this
 });
 ```
 
-It takes the component rather than a tag name, so the element it registers and
-the roles it hands the function are the same contract the template spread.
-
 An element can enter the page more than once — moving it in the DOM runs the
 undo and then the function again — so it has to be able to run twice. State that
 must survive a move goes in a `WeakMap` keyed by `host`, which is what the
@@ -114,9 +103,9 @@ 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" },
+        q:        { kind: "text" },
+        category: { kind: "choice" },
+        featured: { kind: "flag" },
     },
     items: entries.map((entry) => ({
         key: entry.id,
@@ -186,7 +175,7 @@ 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.
+`param` defaults to the field's name. `param: false` keeps a field state-only, out of the URL.
 
 ### Facet counts: `matchedWithout`
 
@@ -278,25 +267,23 @@ 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);
+    onChange({ matched }) {
         // …everything this list draws for itself
     },
 });
-
-const unbind = search.bind(list, "q");
 const detach = list.attach();
+const unbind = searchBox(list, "q", {
+    input: one<HTMLInputElement>("[data-filter-search]"),
+    clear: one("[data-filter-clear]"),
+    empty: one("[data-filter-empty]"),
+});
 ```
 
-`render` is the half worth centralising, and specifically this:
+It paints the list's current state at once, then repaints on every change
+through `list.subscribe`, after the page's own `onChange`. The part worth
+centralising is this:
 
 ```ts
 if (input != null && input.value !== query) input.value = query;
@@ -306,19 +293,13 @@ 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.
+make the field unusable mid-word. Its return is the undo, like `attach`.
 
 `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(…)`
+Every element is optional and `null` is accepted, because a role's `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.
 
@@ -333,7 +314,7 @@ 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]"));
+    hideEmpty(groups, (group) => rowsIn.get(group) ?? []);
 }
 ```
 
@@ -346,8 +327,8 @@ city in it is hidden; a region is empty when every country in it is hidden,
 **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]"));
+hideEmpty(countries, (c) => citiesIn.get(c) ?? []);
+hideEmpty(regions,   (r) => countriesIn.get(r) ?? []);
 ```
 
 Run the other way round, the regions are judged against countries nothing has
@@ -380,37 +361,39 @@ 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`
+## `element`
 
 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.
+the facet simply never matches. `element` names every attribute a script and its
+template share, types the values in them, and registers the behaviour.
 
 ```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 },
+// faq.ts — imported by the template, and loaded by the page's script
+export const faq = element("go-faq", {
+    row: { key: { kind: "text" }, status: { kind: "choice", of: ["open", "soon"] } },
+    search: marker,
+}, (host, { row, search }, signal) => {
+    for (const { element, values } of row.all()) {
+        values.status; // "open" | "soon"
+    }
+    const input = search.one<HTMLInputElement>(); // a marker role is the element itself
 });
-export const search = markup("network-search");
 ```
 
 ```astro
-<a {...row.attrs({ key, status: "open", state: store.state })}>
-<input {...search.attrs()} type="search">
-```
+<script src="./faq.ts"></script>
 
-```ts
-for (const { element, values } of row.all(this)) {
-    values.status; // "open" | "soon"
-}
-const input = search.require<HTMLInputElement>(this).element;
+<go-faq {...faq.root}>
+    <input {...faq.search.attrs()} type="search">
+    <details {...faq.row.attrs({ key, status: "open" })}>…</details>
+</go-faq>
 ```
 
+It registers itself when loaded in a browser and does nothing in Node, so the
+template imports the same file for the contract.
+
 - **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.
@@ -460,67 +443,16 @@ 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 {...faq.root}>
-    <input {...faq.search.attrs()} type="search">
-    <details {...faq.row.attrs({ key, text })}>…</details>
-</faq.tag>
-```
-
-```ts
-defineElement(faq, (host, signal, { row }) => {
-    for (const { element, values } of row.all()) { … }
-});
-```
-
 - **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 the
-  component itself is what `defineElement` registers the behaviour under. A contract stays inert either
-  way: it names things, and nothing in it touches a document, which is why
-  frontmatter can import it.
-- **The names are checked in the editor.** A tag without a hyphen, or a role
-  that is not camelCase, is a compile error where it is written — the rules are
-  types, character by character, as in `i18n/placeholders.ts`. Nothing is
-  validated at run time, because a name that reached the browser malformed would
-  already have been refused there: by `setAttribute`, by `querySelectorAll`, or
-  by `customElements.define`.
-- **Most roles carry nothing**, and say so: `search: marker` rather than
-  `search: {}`, which reads like options somebody forgot to fill in.
-
-- **The roles arrive bound to the instance.** `defineElement` takes the
-  component, so `all`, `one` and `require` need no root: there is no way to
-  write `faq.row.all(document)`, which compiles and returns the roles belonging
-  to no instance at all.
+  field, and the browser refuses to define one tag twice, so two elements cannot
+  share an attribute.
+- **Lookups stay in their instance.** A nested copy of the element keeps its
+  own roles.
 - **The root says it is one.** `{...faq.root}` writes `data-atlas-root`, so a
-  project gives every root a display in one stylesheet rule rather than a class
-  per component. Forget it and the element says so on the dev server.
-
-`tag` and `root` 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`.
+  project gives every root a display in one stylesheet rule. Forget it and the
+  element says so on the dev server.
+- **Names are checked in the editor.** A tag without a hyphen, or a role that is
+  not camelCase, is a compile error where it is written.
 
 ## `youtube`
 
@@ -664,7 +596,7 @@ right properties is a faithful stand-in.
   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
+`carousel`, `consent` and `element` 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/docs/rich-text.md

@@ -29,10 +29,10 @@ Five marks, one void mark, two escapes. That is the whole vocabulary.
 | Written          | Short for   | Run                                | Argument | Notes                                        |
 | ---------------- | ----------- | ---------------------------------- | -------- | -------------------------------------------- |
 | `[b]…[/b]`       | **b**old    | `{ kind: "bold" }`                 | —        | `<strong>` — emphasis, not a font weight     |
-| `[v:name]…[/v]`  | **v**ariant | `{ kind: "styled", variant }`      | required | the renderer maps `name` to classes          |
+| `[v:name]…[/v]`  | **v**ariant | `{ kind: "variant", variant }`     | required | the renderer maps `name` to classes          |
 | `[a:slot]…[/a]`  | **a**nchor  | `{ kind: "link", to, href, url? }` | required | the **call site** says where `slot` goes     |
-| `[mail]…[/mail]` | `mailto:`   | `{ kind: "email", href }`          | —        | the wrapped text must be the address         |
-| `[tel]…[/tel]`   | `tel:`      | `{ kind: "phone", href }`          | —        | the wrapped text must be the number          |
+| `[mail]…[/mail]` | `mailto:`   | `{ kind: "mail", href }`           | —        | the wrapped text must be the address         |
+| `[tel]…[/tel]`   | `tel:`      | `{ kind: "tel", href }`            | —        | the wrapped text must be the number          |
 | `[br]`           | **br**eak   | `{ kind: "break" }`                | —        | wraps nothing, closed by nothing             |
 | `[[` and `]]`    | an escape   | literal `[` and `]`                | —        | the escapes, matching `{{` and `}}` in `t()` |
 
@@ -192,7 +192,7 @@ what to do:
 
 ```txt
 Message "about.intro" (en-US) carries marks, and t() can only print them.
-Read it with rich(), or with plain(rich(…)) for the words alone.
+Read it with rich(), or with site.plain() for the words alone.
 ```
 
 A malformed mark fails there too, with the same error it would give anywhere
@@ -215,10 +215,8 @@ const plainText = site.plain(locale);
 plainText("about.intro", { company })      // no `venue`, no `ask`
 ```
 
-`plain(rich(…))` is the same answer when the runs are already in hand.
-
 Reach for `t()` when the copy is structurally plain and should stay that way — a
-button label, an `aria-label`. Reach for `plain()` when the answer is prose: it
+button label, an `aria-label`. Reach for `site.plain()` when the answer is prose: it
 keeps working on the day someone adds emphasis to the sentence, where `t()` would
 start throwing.
 
@@ -236,20 +234,15 @@ faqPage([{ question, answer: html(rich("faq.city.a", { network: "network" })) }]
 
 ## The renderer half
 
-lib decides which runs exist and what they say; the project decides what they
-look like. A renderer is a `switch` over `kind` and nothing else — every string
-is already translated, every `href` already resolved.
+`@escape-game-over/atlas/astro/rich-text` renders the runs. The site supplies the
+look — a class per `[v:name]` and one for links — usually in a small wrapper
+([`examples/b2c/src/components/RichText.astro`](../examples/b2c/src/components/RichText.astro)):
 
-Make the `switch` exhaustive. `Span` is a closed union, so `satisfies never` on
-the fallthrough turns a run type added in lib into a compile error in the
-project, which is the failure a `default: return null` cannot have — a new kind
-rendering as nothing at all, on every page, silently.
+```astro
+<RichText spans={rich("about.intro", { venue: "contact" })} variants={{ accent: "…" }} link="…" />
+```
 
-[`examples/b2c/src/components/RichText.astro`](../examples/b2c/src/components/RichText.astro)
-is one to copy and restyle. The part worth keeping is its `VARIANTS` map: it is
-the only place a role becomes a colour, so a rebrand is that object rather than a
-sweep through every deployment's sentences. It falls back to no classes for a
-variant it does not know — losing the sentence is the worse failure.
+A variant with no class still renders its words, and warns at build.
 
 ## What fails, and where
 
@@ -270,4 +263,4 @@ variant it does not know — losing the sentence is the worse failure.
 | `[tel]` around a local number                       | build error — write it with a country code                            |
 | `http://` as a link target                          | build error — an `http://` link is a downgrade                        |
 | `"contact#"` — a fragment that names nothing        | build error                                                           |
-| A marked message read with `t()`                    | build error, pointing at `rich()` and `plain()`                       |
+| A marked message read with `t()`                    | build error, pointing at `rich()` and `site.plain()`                  |