@escape-game-over/atlas 0.1.6 → 0.1.9

package/README.md

@@ -105,9 +105,10 @@ export default defineProject(config, baseMessages, baseRoutes, {...})
 export const site = createSite(config, baseMessages, baseRoutes, project)
 ```
 
-Step 4 returns `t()`, `pathFor()`, `urlFor()`, `fileUrl()`, `alternatesFor()`,
-`localeLinksFor()`, `metaFor()`, `breadcrumbFor()`, `staticPaths()`, `routes`,
-`entries`, `sitemap()`, `robots()`, `llms()` and `redirects()` already wired.
+Step 4 returns `t()`, `rich()`, `plain()`, `pathFor()`, `urlFor()`, `fileUrl()`,
+`alternatesFor()`, `localeLinksFor()`, `metaFor()`, `breadcrumbFor()`,
+`staticPaths()`, `routes`, `entries`, `sitemap()`, `robots()`, `llms()` and
+`redirects()` already wired.
 
 `t()` is bound to a locale and knows each message's `{placeholders}` from its
 text:
@@ -125,6 +126,49 @@ t("footer.copyright", { company: "A", year: "1", x: "" }) // ✗ {x} is not a pl
 Nothing is auto-injected. Site-wide values are ordinary placeholders, passed
 explicitly.
 
+## A sentence is one message
+
+Copy that needs emphasis, a link or a line break carries **marks**, and stays one
+key — so each language orders and splits it however it needs to, rather than
+around an array of `hero.subtitle_text_1…_7` whose length was fixed by whoever
+typed the English.
+
+```ts
+"about.intro": {
+  "en-US": "Book [v:accent]up to six players[/v] at [a:venue]our venue[/a].",
+  "el-GR": "Κλείσε [a:venue]στον χώρο μας[/a] [v:accent]έως έξι παίκτες[/v].",
+}
+```
+
+```ts
+const rich = site.rich(locale)
+rich("about.intro", { venue: "contact" })  // the destination, stated once
+```
+
+| Mark              | Short for   | Is                                       |
+| ----------------- | ----------- | ---------------------------------------- |
+| `[b]…[/b]`        | **b**old    | `<strong>` — emphasis, not a font weight |
+| `[v:accent]…[/v]` | **v**ariant | a role the project's renderer maps       |
+| `[a:venue]…[/a]`  | **a**nchor  | a link **slot** the call site fills      |
+| `[mail]…[/mail]`  | `mailto:`   | a `mailto:` derived from the words       |
+| `[tel]…[/tel]`    | `tel:`      | a `tel:` derived from the words          |
+| `[br]`            | **br**eak   | a line break                             |
+| `[[` and `]]`     | an escape   | a literal `[` and `]`                    |
+
+Four of the six are HTML's own tags or schemes, so there is little to memorise.
+Only `[v:]` is Atlas's, and it is the one that has to be: HTML has no tag for "a
+role this project names", which is precisely the decision being kept out of the
+copy.
+
+`rich()` returns `Span[]` — translated text with resolved `href`s — and the
+project owns the `switch` that draws them. Copy never holds a colour, a class, a
+route id or a URL. A slot is filled at the call site, where it is checked against
+the routes this deployment builds and written once instead of once per language.
+
+`site.plain(locale)` reads the same message as words alone, for a
+`<meta description>` or `llms.txt`; `t()` refuses a message with marks rather
+than printing the brackets. See [`docs/rich-text.md`](docs/rich-text.md).
+
 ## What the build emits, and who asks for it
 
 | Output                   | Comes from                       | Needs from the project                  |
@@ -159,6 +203,8 @@ regression-tested by an `@ts-expect-error` suite.
 | A locale of a message using different `{placeholders}` than its siblings        | error, naming the locale                     |
 | An override for a key that is not in the default catalog                        | error — typos can't become dead strings      |
 | An override that drops or invents a `{placeholder}`                             | error — existing `t()` calls stay valid      |
+| A locale of a message using different marks than its siblings                   | error — a lost `[a:venue]` fails the build   |
+| Filling a `[a:slot]` with a route this project does not build                   | error at the call site                       |
 | Calling `t()` without a required placeholder, or with a wrong/extra name        | error                                        |
 | A route that does not state `enabled`                                           | error — a page is never built by implication |
 | A slug or message naming a locale the site doesn't ship                         | error                                        |
@@ -313,7 +359,8 @@ src/            the package — see the export map above for what is reachable
   jsonld/         the @graph — one file per node, each linked to Google's docs
   i18n/           defineMessages(), t(), placeholder extraction
   routes/         defineRoutes(), routeFamily(), merging and collisions
-  analytics/      Umami and Google, and the Consent Mode defaults
+  analytics/      Umami and Google, the Consent Mode defaults, and whether a
+                  visitor has to be asked anything at all
   astro/          the only framework-aware code, plus the one component
 bin/            the `atlas` CLI
 tests/          runtime behaviour — what a merge resolves to, what a builder rejects
@@ -401,6 +448,9 @@ upstream, and each explains a rule that would otherwise read as an oversight.
 
 - [`docs/checks.md`](docs/checks.md) — every guarantee, where it is enforced, and
   how the type tests and runtime tests divide the work.
+- [`docs/rich-text.md`](docs/rich-text.md) — every mark copy may carry, what each
+  produces, why a link names a slot rather than an address, and the renderer
+  contract on the other side of `Span`.
 - [`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

package/docs/NOT-BUILT.md

@@ -312,6 +312,13 @@ visitor changes their mind. Those are product and legal decisions that differ
 per deployment, and a template that guessed at them would be guessing at
 somebody's compliance.
 
+**One part of it is lib's, and is built as of August 2026: whether there should
+be a banner at all.** `consentRequired(analytics)`, with the reasoning in
+`src/analytics/index.ts`. It sits here rather than in each project because it is
+a question about *tags* — which lib owns — wearing the costume of a question
+about banners, and because the obvious check is wrong in both directions.
+Everything above about the banner itself still stands.
+
 The seam between the halves is a global — `CONSENT_UPDATE_GLOBAL` — because
 that is the only place they *can* meet: the head script runs before any module
 exists. lib emits an updater covering exactly the signals it defaulted, so a
@@ -326,6 +333,28 @@ Note the shape sibling projects use, and do not copy it: they group
 key. Verification is a `<meta>` proving ownership; analytics is a script. One
 config block, two different kinds of thing.
 
+### Should lib preload the analytics scripts, not just open the connection?
+
+**No — and the connection is already opened, which is the part worth having.**
+`preconnect`, built as of August 2026; see `AnalyticsTag` in
+`src/analytics/tags.ts` for how and why.
+
+The reason to stop there is priority. A preload does not merely start a fetch
+earlier, it raises what that fetch competes with — and what would be raised here
+is a third-party analytics script, against the image the page is judged on. The
+tag would arrive sooner by making the LCP arrive later, which is a worse trade
+than the one being fixed. A handshake has no such cost: it is latency with
+nothing else contending for it, so moving it earlier takes nothing from
+anything.
+
+Two traps live with this, both spelled out where the code is. A preconnect is
+reused only by a request whose CORS mode matches it, so one marked
+`crossorigin` for a classic `<script src>` warms nothing while looking entirely
+correct — fonts are the opposite case, and the two must not be copied between.
+And Tag Manager's loader URL is written *by* the inline block, so nothing in the
+markup names that origin until the script has run, which is what makes the
+connection worth stating rather than leaving to the preload scanner.
+
 ### Should a room be an `Event`?
 
 **No.**

package/docs/checks.md

@@ -105,27 +105,27 @@ They are **excluded from the type check**, because they import `vitest` and that
 command's promise is that the package type-checks with no ambient types and no
 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                                                          |
-| `llms.test.ts`             | section grouping, owners, heading and link precedence, and the undescribed fallback                                       |
-| `public-files.test.ts`     | walking `public/`, what is skipped, and why the declaration must be a module                                              |
-| `breadcrumbs.test.ts`      | the trail, a dropped ancestor, `orphanSegments`, and how a gap is reported                                                |
-| `jsonld/*.test.ts`         | that a `</script>` in any value cannot close the block, each node's shape and `@id`, and how a price table becomes offers |
-| `analytics.test.ts`        | Umami's attributes, its three-state booleans, and the `domains` list that would record nothing                            |
-| `google-analytics.test.ts` | that consent is denied first and precedes every tag, one loader for many ids, and dead `UA-` properties                   |
-| `contact.test.ts`          | the E.164 a `tel:` needs — trunk zero dropped, spacing stripped — and the displayed form kept                             |
-| `hours.test.ts`            | collapsing a week into runs, week start changing the answer, and every impossible week that throws                        |
-| `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                                                                         |
-| `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                                 |
+| 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                                                                                                                                     |
+| `llms.test.ts`             | section grouping, owners, heading and link precedence, and the undescribed fallback                                                                                                                  |
+| `public-files.test.ts`     | walking `public/`, what is skipped, and why the declaration must be a module                                                                                                                         |
+| `breadcrumbs.test.ts`      | the trail, a dropped ancestor, `orphanSegments`, and how a gap is reported                                                                                                                           |
+| `jsonld/*.test.ts`         | that a `</script>` in any value cannot close the block, each node's shape and `@id`, and how a price table becomes offers                                                                            |
+| `analytics.test.ts`        | Umami's attributes, its three-state booleans, the `domains` list that would record nothing, and that `consentRequired` answers exactly when a tag was emitted                                        |
+| `google-analytics.test.ts` | that consent is denied first and precedes every tag, one loader for many ids, dead `UA-` properties, and the preconnect — once, ahead of the block that writes the loader's URL, never `crossorigin` |
+| `contact.test.ts`          | the E.164 a `tel:` needs — trunk zero dropped, spacing stripped — and the displayed form kept                                                                                                        |
+| `hours.test.ts`            | collapsing a week into runs, week start changing the answer, and every impossible week that throws                                                                                                   |
+| `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                                                                                                                                                    |
+| `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

package/docs/client-scripts.md

@@ -35,6 +35,15 @@ attribute name in this package has to be matched by any consumer.
 | `./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.
+
 ## Lifetimes are the recurring bug
 
 Every module here that binds a listener hands back the undo, and the undo is

package/docs/rich-text.md

@@ -0,0 +1,261 @@
+# Rich text: the marks a message may carry
+
+`t()` prints a message. `rich()` reads the marks *in* one and hands back runs —
+so a sentence with emphasis, a link and a line break in it stays **one message**,
+which is the only shape a translator can reorder.
+
+```ts
+"about.intro": {
+    "en-US": "Book [v:accent]up to six players[/v] at [a:venue]our venue[/a].",
+    "el-GR": "Κλείσε [a:venue]στον χώρο μας[/a] [v:accent]έως έξι παίκτες[/v].",
+}
+```
+
+```ts
+const rich = site.rich(locale);
+rich("about.intro", { venue: "contact" })   // the destination, stated once
+```
+
+Greek moves the link to the front and spends fewer runs on the clause. Neither is
+something the copy is allowed to ask permission for, and neither is expressible
+as an array of `hero.subtitle_text_1…_7` keys glued together in the order someone
+typed the English. See [`src/content/marks.ts`](../src/content/marks.ts) for that
+argument at length.
+
+## The marks
+
+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          |
+| `[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          |
+| `[br]`           | **br**eak   | `{ kind: "break" }`                | —        | wraps nothing, closed by nothing             |
+| `[[` and `]]`    | an escape   | literal `[` and `]`                | —        | the escapes, matching `{{` and `}}` in `t()` |
+
+**Four of the six are HTML's own**, which is the whole memorisation trick: `b`,
+`a` and `br` are the tags they replace, and `mail` and `tel` are the schemes they
+produce. Only `v` is Atlas's, and it is the one that has to be — HTML has no tag
+for "a role this project names", because that is exactly the decision being kept
+out of the copy.
+
+They are short because a translator reads past them to the words, and every
+character between `[` and `]` is noise in a sentence someone is trying to keep
+natural. They are not so short as to be unguessable — `[b]` and `[a]` read off a
+sentence the way their tags do, and `[x]` would not.
+
+`[b]` is the one presentational-looking mark lib names outright, and it is not
+presentational — it is `<strong>`, it survives into plain text as emphasis a
+screen reader announces. Everything that is genuinely a *style* is `[v:]`.
+
+## An argument is a role or a slot, never a value
+
+|             | `[v:name]`                                 | `[a:name]`                      |
+| ----------- | ------------------------------------------ | ------------------------------- |
+| Names       | a style the renderer knows                 | a slot the call site fills      |
+| Spelled     | `[a-zA-Z0-9_-]+`                           | `[a-zA-Z0-9_]+` — **no hyphen** |
+| Resolved by | the project's `Record<string, string>` map | `rich(key, { name: … })`        |
+| Never holds | a colour, a class, a size                  | a route id, a path or a URL     |
+
+The hyphen is the difference and it is deliberate. A variant usually mirrors a
+CSS custom property or a design token, which are kebab by convention, and
+`[v:on-dark]` is the natural spelling. A slot name is a key someone writes in
+TypeScript — `rich(key, { venue: "contact" })` — where a hyphen forces quoting
+and reads as a mistake.
+
+**A link names a slot rather than a destination**, which is the rule worth
+understanding before anything else here. A route id written into a translation is
+an unchecked string until the day that message renders, repeated once per
+language, sitting in a file whose reviewers are translators. Written at the call
+site it is checked against the routes this deployment actually builds:
+`{ venue: "contct" }` is a compile error on the line that wrote it, and so is a
+route the project has switched off.
+
+Copy that spells an address gets told so by name:
+
+```txt
+Message "about.intro" (en-US) has a link slot that is not a name: "[a:/contact]".
+A link names a slot the call site fills, not an address: write "[a:venue]" and
+pass rich(key, { venue: "contact" }).
+```
+
+## Every `[` opens a mark or is doubled
+
+There is no third option, and a bracket that means neither is refused rather than
+printed:
+
+```txt
+Message "hours.line" (en-US) has a "[" that opens neither a mark nor an escape:
+"[Mon-Fri]". The marks are [b], [v], [a], [mail], [tel] and [br]. To write a
+literal bracket, double it: "[[".
+```
+
+`"Open [[Mon-Fri]] only."` is what that copy meant, and it renders `Open
+[Mon-Fri] only.` This is the same call `render` makes on a stray `{`: a
+half-written mark is a mistake, not an escape hatch, and shipping it to a page as
+literal text is the failure nobody notices until it is quoted in a search result.
+
+A **lone `]` stays text** — only `[` opens anything, so there is nothing an
+unmatched closer could be ambiguous about, and refusing it would fail copy that
+is merely writing a bracket.
+
+An escaped `[[a:x]]` asks for nothing: it is not a mark, so it demands no slot
+and fills none.
+
+## Marks do not nest
+
+One mark is open at a time. `[b]bold [v:accent]and red[/v][/b]` is refused rather
+than flattened, because a run is bold *or* it carries a variant and there is
+nowhere for the second one to go.
+
+If the combination is wanted, it is a role: give one variant both properties and
+name it once. (The shape this replaces answered the same limit by inventing a
+`boldUnderline` kind, used once in fifty-four deployments.)
+
+`[br]` is the exception that is not one — it wraps nothing, so it splits the run
+without closing the mark:
+
+```ts
+parseMarks("[b]One[br]Two[/b]")
+// [ bold "One", break, bold "Two" ]
+```
+
+An empty run is dropped rather than emitted: `[b][/b]` produces nothing at all,
+because copy someone half-deleted should not render an empty element that still
+takes up a renderer's `switch`.
+
+## Marks are parsed before `{placeholders}` are filled
+
+That order is load-bearing in both directions:
+
+- **A value can never inject a mark.** A venue name, a price or a phone number
+  arriving from config is data, not copy — by the time it lands, the marks are
+  already gone, so `{phone}` can hold a `[` and still renders as text.
+- **A mark can wrap a placeholder.** `"Call us on [tel]{phone}[/tel]"` keeps the
+  number in config where it belongs and still gets a `tel:` link, without copy
+  ever spelling the digits.
+
+## Where a link actually goes
+
+The slot's value is a `LinkTarget`, told apart by its first character:
+
+| Passed                 | `span.to`  | `href`                        | `url`        |
+| ---------------------- | ---------- | ----------------------------- | ------------ |
+| `"contact"`            | `internal` | this locale's path            | absolute     |
+| `"challenges#booking"` | `internal` | that path, fragment appended  | absolute     |
+| `"/press/kit"`         | `internal` | taken as written              | absolute     |
+| `"https://…"`          | `external` | the URL                       | the same URL |
+| `"#booking"`           | `anchor`   | the fragment                  | **absent**   |
+| `"http://…"`           | —          | refused — write it `https://` |              |
+
+Prefer the route id. It is the only form that survives a slug being retranslated
+or a page moving; a raw path is the escape hatch for a URL this project owns no
+route for, and lib has nothing to check it against.
+
+`external` is decided by the shape the target was written in, not by comparing
+hosts — a sibling deployment on the same domain is still leaving this site, and
+the `target`/`rel` decision is the renderer's.
+
+An `anchor` carries **no `url`, and that is not a gap**: `rich()` is given a
+locale, not a route, so it does not know which page a bare `#booking` belongs to.
+A caller that does can build one — `joinUrl(site.urlFor(id, locale), href)`.
+
+`[mail]` and `[tel]` derive their `href` from the words themselves, so the
+address or number is written once. The number must be in international form —
+`"+30 210 0000000"` — because a local one does not dial from abroad.
+
+## What the compiler holds in step
+
+Which marks a message uses is checked across locales by the same machinery that
+holds `{placeholders}` in step, so a translation that quietly loses `[a:venue]`
+fails the build rather than the page.
+
+**The argument is part of the token, on purpose.** `[a:venue]` and `[a:booking]`
+are different tokens, so one language cannot fill a different slot from the
+others, and `[v:accent]` cannot become `[v:inverse]` in the Greek. Those are
+decisions the copy makes once, not per locale.
+
+Multiplicity is not carried — two `[b]` runs and one look alike to the type,
+which is the same limit `Placeholders` has with two `{name}`s and the same trade.
+
+The link slots a message declares become required arguments:
+`"See [a:venue]us[/a]"` asks the call site for `{ venue: LinkTarget }`, typed
+over the routes this project builds.
+
+## `t()` refuses a message with marks in it
+
+`t()` can only print, so it would print the brackets. It throws instead, and says
+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.
+```
+
+A malformed mark fails there too, with the same error it would give anywhere
+else — `"[b]bold"` is a mistake whichever function reads it.
+
+## The same sentence as words
+
+`site.plain(locale)` gives the message with the markup gone: for a
+`<meta name="description">`, an `llms.txt` summary, a structured-data
+`description` — everywhere that takes a string rather than markup. `[br]` becomes
+a space and runs of whitespace collapse, so copy split across a line break does
+not arrive with a double space in the middle of a `<meta>` tag.
+
+**It asks for `{placeholders}` and not for link destinations.** A `tel:` it would
+discard is not worth building, and `llms.txt` should not have to name a route for
+every link in every description in order to throw them all away.
+
+```ts
+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
+keeps working on the day someone adds emphasis to the sentence, where `t()` would
+start throwing.
+
+## 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.
+
+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.
+
+[`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.
+
+## What fails, and where
+
+| Written                                             | Result                                                                |
+| --------------------------------------------------- | --------------------------------------------------------------------- |
+| A locale dropping `[a:venue]`                       | compile error — the marks must match across a message                 |
+| `[a:venue]` in one locale, `[a:booking]` in another | compile error — the argument is part of the token                     |
+| `rich()` without a slot's target                    | compile error, then a build error naming the slot                     |
+| A slot filled with an unbuilt route                 | compile error at the call site                                        |
+| `[Mon-Fri]`                                         | build error, listing the marks and the `[[` escape                    |
+| `[b]` never closed, `[/b]` never opened             | build error naming the message and locale                             |
+| `[b]a[v:x]b[/v][/b]`                                | build error — marks do not nest                                       |
+| `[v:]` or `[a:]` with nothing after the colon       | build error, saying what the argument is                              |
+| `[a:/contact]` — an address in the copy             | build error — a slot is a name                                        |
+| `[v:on dark]` — a variant that is not a name        | build error                                                           |
+| `[b:x]` — an argument on a mark that takes none     | build error                                                           |
+| `[mail]` around text with no `@`                    | build error — a `mailto:` with an empty To: still opens a mail client |
+| `[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()`                       |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.6",
+    "version": "0.1.9",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -53,10 +53,10 @@
         "typescript": ">=5"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.5.10",
-        "@types/node": "26.3.0",
+        "@biomejs/biome": "2.5.12",
+        "@types/node": "26.4.1",
         "@vitest/coverage-istanbul": "4.1.11",
-        "astro": "7.2.6",
+        "astro": "7.2.10",
         "typescript": "6.0.3",
         "vitest": "4.1.11"
     }

package/src/analytics/google.ts

@@ -243,8 +243,42 @@ function consentCalls(defaults: readonly ConsentDefaults[]): string {
 }
 
 /**
- * Google's tags: one inline block and the loader in the head, Tag Manager's
- * `<noscript>` fallback in the body.
+ * The one host every Google tag here is served from.
+ *
+ * Named because it is stated four times below — the loader's `src`, the
+ * container bootstrap written into the inline block, the `<noscript>` iframe,
+ * and the connection opened ahead of all three. The preconnect is only worth
+ * anything while it names the origin the scripts actually use, and three
+ * hand-written copies of a hostname is how it stops.
+ */
+const TAG_ORIGIN = "https://www.googletagmanager.com";
+
+/**
+ * Whether a `google` block comes to any tag at all.
+ *
+ * The condition `googleScripts` returns early on, given a name because two
+ * callers need the same answer. A consumer deciding whether to render a consent
+ * banner is asking exactly this: a block carrying neither `tagIds` nor
+ * `containerIds` emits nothing, sets no cookies, and needs no permission — and
+ * a banner shown for it asks a visitor to agree to something that was never
+ * written. See `consentRequired` in `analytics/index.ts`.
+ *
+ * A type predicate, so the caller below keeps its narrowing: `true` implies
+ * the block is there, which is the only direction anything relies on.
+ */
+export function googleEmits(
+    google: GoogleSettings | undefined
+): google is GoogleSettings {
+    if (google === undefined) return false;
+    return (
+        (google.tagIds ?? []).length > 0 ||
+        (google.containerIds ?? []).length > 0
+    );
+}
+
+/**
+ * Google's tags: a connection and one inline block and the loader in the head,
+ * Tag Manager's `<noscript>` fallback in the body.
  *
  * One block rather than several because `dataLayer` is a queue — consent, the
  * timestamp, every `config` and Tag Manager's own bootstrap can all be pushed
@@ -263,11 +297,10 @@ export function googleScripts(
     at: string
 ): AnalyticsTags {
     const nothing: AnalyticsTags = { head: [], body: [] };
-    if (google === undefined) return nothing;
+    if (!googleEmits(google)) return nothing;
 
     const tags = google.tagIds ?? [];
     const containers = google.containerIds ?? [];
-    if (tags.length === 0 && containers.length === 0) return nothing;
 
     // An id in the wrong field is the silent failure here: it is configured,
     // it is emitted, and it reports nowhere — which reads as a quiet week.
@@ -312,7 +345,7 @@ export function googleScripts(
         // itself, so it runs after the consent calls already queued above.
         ...containers.map(
             (id) =>
-                `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f)})(window,document,'script','dataLayer',${literal(id)});`
+                `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='${TAG_ORIGIN}/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f)})(window,document,'script','dataLayer',${literal(id)});`
         ),
     ].join("");
 
@@ -330,13 +363,18 @@ export function googleScripts(
     const first = tags[0];
     return {
         head: [
+            // Ahead of the inline block, which is the only position that buys
+            // anything: for a container the loader's URL is written *by* that
+            // block, so this is the only mention of the origin the browser can
+            // act on before the script has run. See `AnalyticsTag`.
+            { kind: "preconnect", origin: TAG_ORIGIN },
             { kind: "inline", content: inline },
             ...(first === undefined
                 ? []
                 : [
                       {
                           kind: "external" as const,
-                          src: `https://www.googletagmanager.com/gtag/js?id=${encodeURIComponent(first)}`,
+                          src: `${TAG_ORIGIN}/gtag/js?id=${encodeURIComponent(first)}`,
                           attributes: {},
                       },
                   ]),
@@ -345,7 +383,7 @@ export function googleScripts(
         // fallback, because `gtag.js` is the only way it collects anything.
         body: containers.map((id) => ({
             kind: "noscriptFrame" as const,
-            src: `https://www.googletagmanager.com/ns.html?id=${encodeURIComponent(id)}`,
+            src: `${TAG_ORIGIN}/ns.html?id=${encodeURIComponent(id)}`,
         })),
     };
 }

package/src/analytics/index.ts

@@ -1,5 +1,5 @@
 import type { HttpsUrl } from "../url.ts";
-import { type GoogleSettings, googleScripts } from "./google.ts";
+import { type GoogleSettings, googleEmits, googleScripts } from "./google.ts";
 import type { AnalyticsTag, AnalyticsTags } from "./tags.ts";
 import {
     checkUmamiDomains,
@@ -68,6 +68,43 @@ export function analyticsScripts(
     };
 }
 
+/**
+ * Whether this deployment loads anything a visitor has to be asked about.
+ *
+ * The build-time twin of `consentApplies()` in `astro/consent.ts`, which asks
+ * the same question in the browser by looking for the global the Google tag
+ * defines. That one cannot answer it early enough to be useful: a consent
+ * banner's script has to be downloaded, parsed and run before it can report
+ * that there was nothing to consent to — three requests to learn that none of
+ * them were needed. Asked here, a project leaves the banner out of the HTML.
+ *
+ * Vendor by vendor rather than `analytics.google !== undefined`, because that
+ * is not the question. A `google` block carrying no ids emits no tag and sets
+ * no cookies, and a banner shown for it asks a visitor to agree to something
+ * that was never written — which teaches them their answer does not matter.
+ * `googleEmits` is the same predicate `googleScripts` returns early on, so the
+ * two cannot disagree.
+ *
+ * **`VENDORS` is exhaustive on purpose.** Adding a key to `AnalyticsSettings`
+ * stops this file compiling until someone says whether that vendor needs
+ * permission — which is the failure worth having, since the alternative is a
+ * new vendor silently setting cookies behind a banner that never appears.
+ */
+export function consentRequired(
+    analytics: AnalyticsSettings | undefined
+): boolean {
+    if (analytics === undefined) return false;
+
+    const VENDORS: Readonly<Record<keyof AnalyticsSettings, boolean>> = {
+        // Cookieless by design — nothing to permit, nothing to withdraw.
+        umami: false,
+        // Consent Mode, but only once there is a tag reading it.
+        google: googleEmits(analytics.google),
+    };
+
+    return Object.values(VENDORS).some(Boolean);
+}
+
 /**
  * The tag a 404 grouped under, so the misses can be read on their own.
  *

package/src/analytics/tags.ts

@@ -29,6 +29,33 @@ export type AnalyticsTag =
     | {
           readonly kind: "noscriptFrame";
           readonly src: string;
+      }
+    /**
+     * An origin to open a connection to before anything asks it for bytes.
+     *
+     * Every vendor here is served from a host that is not the site's, so the
+     * first tag to load pays a DNS lookup, a TCP handshake and a TLS
+     * negotiation before a single byte of script arrives. Tag Manager is the
+     * worst case: its loader is written by the inline block above, so the
+     * origin appears nowhere a preload scanner can read it and the connection
+     * cannot begin until that script has run.
+     *
+     * An origin rather than a URL, and `preconnect` rather than `preload`,
+     * because the handshake is the part worth moving and the fetch is not.
+     * Preloading a tag would raise a third-party analytics script to the
+     * priority of the things the page is drawn from — it would arrive sooner
+     * by making the image beside it arrive later.
+     *
+     * **No `crossorigin`, and that is load-bearing.** A preconnect is reused
+     * only by a request whose CORS mode matches it, and every script here is
+     * fetched as a classic `<script src>`, which is not a CORS request. One
+     * carrying `crossorigin` would open a second connection that nothing uses,
+     * warm nothing, and look entirely correct in the markup. Fonts are the
+     * opposite case and do need it, which is why this is worth stating.
+     */
+    | {
+          readonly kind: "preconnect";
+          readonly origin: string;
       };
 
 /**

package/src/analytics/umami.ts

@@ -248,6 +248,11 @@ export function umamiScripts(
     };
 
     return [
+        // Before the script that needs it. A `src.` subdomain reads as
+        // first-party and is not one to the network stack: it is a separate
+        // origin, and the tracker pays its full handshake before it can start.
+        // See `AnalyticsTag` for why this is a preconnect and not a preload.
+        { kind: "preconnect", origin: umami.host },
         {
             kind: "external",
             src: at(umami.tracker?.path ?? "/script.js"),

package/src/content/marks.ts

@@ -65,10 +65,13 @@ export type ParsedSpan =
 /**
  * The marks, and what each produces.
  *
- * Short names because a translator reads past them to the words, and every
- * character between `[` and `]` is noise in a sentence they are trying to keep
- * natural. Long enough to guess at from context, which `[b]` and `[a]` are and
- * `[x]` would not be.
+ * `b` is bold, `v` is variant, `a` is anchor; `mail` and `tel` are the schemes
+ * they produce, and `br` is the break below — four of the six borrowed from HTML
+ * outright, so `v` is the only one anybody has to learn, and it is the one HTML
+ * has no tag for. Short names beyond that because a translator
+ * reads past them to the words, and every character between `[` and `]` is noise
+ * in a sentence they are trying to keep natural. Long enough to guess at from
+ * context, which `[b]` and `[a]` are and `[x]` would not be.
  *
  * `bold` is the one presentational mark lib names outright, because it is not
  * presentational: it is `<strong>`, it survives into plain text as emphasis a
@@ -393,8 +396,10 @@ function argumentHint(mark: MarkName): string {
  * whichever function reads it, and swallowing that to answer a yes-or-no
  * question would leave `t()` printing the bracket it was written to refuse.
  *
- * `"Open [Mon-Fri]"` passes: that is a bracket nobody meant as a mark, `Mon-Fri`
- * is not one of the five, and the parser has already said so.
+ * `"Open [[Mon-Fri]] only"` passes: a doubled bracket is an escape rather than a
+ * mark, so every run is text and `t()` prints it. Undoubled it fails, and fails
+ * in the parser — `[Mon-Fri]` opens neither a mark nor an escape, which is not a
+ * question about who is reading the message.
  */
 export function assertNoMarks(template: string, at: string): void {
     const marked = parseMarks(template, at).some(

package/src/index.ts

@@ -26,6 +26,7 @@ export {
     CONSENT_UPDATE_GLOBAL,
     type ConsentDefaults,
     type ConsentState,
+    consentRequired,
     type GoogleSettings,
     type UmamiReplay,
     type UmamiSettings,

package/src/meta/tag.ts

@@ -92,6 +92,15 @@ export function asMetaTag(script: AnalyticsTag): MetaTag {
     if (script.kind === "noscriptFrame") {
         return { kind: "noscriptFrame", src: script.src };
     }
+    if (script.kind === "preconnect") {
+        // A `link` rather than a kind of its own: the head vocabulary already
+        // has the shape, and a preconnect is a link in every sense the renderer
+        // cares about. See `AnalyticsTag` for why no `crossorigin`.
+        return {
+            kind: "link",
+            attrs: { rel: "preconnect", href: script.origin },
+        };
+    }
     const unhandled: never = script;
     throw new Error(`Unhandled analytics tag: ${JSON.stringify(unhandled)}`);
 }