@escape-game-over/atlas 0.1.5 → 0.1.7

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                                        |
@@ -401,6 +447,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

@@ -227,6 +227,73 @@ type could — a property that is not valid for the type it sits on.
 
 ## Answers that will not change on their own
 
+### 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
+carries a `ContentItem[]`.**
+
+This is the shape the sibling B2C template uses, and it is the one thing from
+there that was deliberately not ported — so the reasoning is here, because
+reading those configs is what prompts the question. A paragraph is written as an
+array of `{ type, content }` objects, each `content` a translation key, and the
+renderer concatenates them in the order the array was typed:
+
+```ts
+subtitle: [
+    { type: "text", content: "hero.subtitle_text_1" },
+    { type: "bold", content: "hero.subtitle_text_2" },
+    { type: "text", content: "hero.subtitle_text_3" },
+    // …through _7
+]
+```
+
+**It fixes two things copy is not allowed to fix.** Word order, which differs
+per language — the array says the bold clause comes second, in every locale,
+forever. And the *number of runs*, which differs more: a clause English spends
+four fragments on is one word in Greek, and there is no way to write that in an
+array whose length was decided by whoever typed the English. The extra keys get
+padded with empty strings or the spare ones go untranslated, and either way the
+translator is editing around a data structure instead of writing a sentence.
+
+The `spaceAfter: true` flag on those objects is the tell. It exists because the
+runs are concatenated with nothing between them, so a sentence split across keys
+needs someone to remember which fragments end in a space — a per-fragment
+decision that is invisible until it renders. With one message the spaces are
+just in the copy.
+
+What replaces it is a mark in the message: `"Book [b]up to six[/b] at
+[a:venue]our venue[/a]."`. Each language moves them where its grammar wants
+them, `rich()` returns the runs, and the renderer styles them. The mark set is
+compared across locales by the machinery that already compares `{placeholders}`
+— see `Tokens` in `i18n/placeholders.ts` — so a translation that drops the link
+fails the build rather than the page. That check is the reason marks are safe to
+put in copy at all, and it is what the array shape genuinely did buy: with the
+structure in config, no locale *could* lose a link. Marks had to earn that back.
+
+**A mark names a slot, never a destination**, and that distinction is the second
+thing the array shape got right and the first version of this got wrong. `venue`
+above is a name the call site fills — `rich(key, { venue: "contact" })` — so the
+route id is checked against the route table like every other link in the package,
+it is written once rather than once per language, and an external URL never
+enters a file that translators edit. Copy holding `[a:https://…]` in ten
+languages is ten unchecked copies of an address, and the eleventh is the one
+somebody "corrects".
+
+**What is still fine to build.** Composing runs in code: a `Span[]` is the
+resolved type, already plain strings and finished hrefs, so a project assembling
+a line from config values — a price, a phone number, a room name — builds one
+directly and needs nothing from `rich()`. And a list is still an array: spans are
+inline, so bullets are `readonly RichText[]` in the project's own config, which
+is what the old `bulletList` run should become.
+
+**What is not a reason, and was the strongest argument for porting it.** That
+around 6,300 authored runs across fifty-four deployments would migrate verbatim.
+They would — and they would carry the fragmentation with them into a codebase
+whose whole claim is that a translation cannot silently go wrong. The migration
+is happening once; this is the moment it costs least to fix, and every store
+collapsed to marks is a store whose copy a translator can finally read.
+
 ### Should lib carry the consent *banner* as well as the tags?
 
 **No — and the line between the two halves is the point.**

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.5",
+    "version": "0.1.7",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -39,7 +39,7 @@
     "scripts": {
         "test": "npm run test:types && npm run test:unit && npm run test:examples",
         "test:types": "tsc --noEmit && astro check --root checks/astro",
-        "test:unit": "vitest run",
+        "test:unit": "vitest run --coverage",
         "test:watch": "vitest",
         "test:examples": "npm run test --workspaces",
         "lint": "biome check .",
@@ -55,7 +55,8 @@
     "devDependencies": {
         "@biomejs/biome": "2.5.10",
         "@types/node": "26.3.0",
-        "astro": "7.2.6",
+        "@vitest/coverage-istanbul": "4.1.11",
+        "astro": "7.2.7",
         "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"),