@escape-game-over/atlas 0.1.5 → 0.1.6

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.5",
+    "version": "0.1.6",
     "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,6 +55,7 @@
     "devDependencies": {
         "@biomejs/biome": "2.5.10",
         "@types/node": "26.3.0",
+        "@vitest/coverage-istanbul": "4.1.11",
         "astro": "7.2.6",
         "typescript": "6.0.3",
         "vitest": "4.1.11"

package/src/contact.ts

@@ -82,6 +82,30 @@ export function formatPhone(phone: PhoneNumber): string {
     return `+${phone.code} ${phone.number}`;
 }
 
+/**
+ * A number in E.164: a plus, then digits.
+ *
+ * Named for the reason `HttpsUrl` is — so that everything built from one
+ * inherits the guarantee rather than re-stating it. `TelUrl` is a template on
+ * this, so a `tel:` cannot be assembled from a number that never had a country
+ * code, which is the whole thing `e164Of` is checking for.
+ */
+export type E164 = `+${string}`;
+
+/**
+ * A `tel:` link, as a shape.
+ *
+ * Beside `E164` and `EmailAddress` rather than in `url.ts` with `HttpsUrl` and
+ * `UrlPath`: those two are addresses of *pages*, and half of what lib does is
+ * build them from a route table. These are neither — they are the two schemes
+ * this file produces from a phone number and an address, and they belong with
+ * the values they are made of.
+ */
+export type TelUrl = `tel:${E164}`;
+
+/** A `mailto:` link, as a shape. @see {@link TelUrl} */
+export type MailtoUrl = `mailto:${EmailAddress}`;
+
 /**
  * The number as a phone dials it: `tel:+390600000000`.
  *
@@ -93,7 +117,7 @@ export function formatPhone(phone: PhoneNumber): string {
  * and nothing is removed, so this and `formatPhone` are two renderings of one
  * value rather than two opinions about it.
  */
-export function telHref(phone: PhoneNumber): string {
+export function telHref(phone: PhoneNumber): TelUrl {
     return `tel:${e164(phone)}`;
 }
 
@@ -118,14 +142,71 @@ export function telHref(phone: PhoneNumber): string {
  * `replace(/^0+/, "")` also took *every* leading zero rather than one trunk
  * digit, so `007…` became `7…`.
  */
-export function e164(phone: PhoneNumber): string {
+export function e164(phone: PhoneNumber): E164 {
     return `+${phone.code}${phone.number.replace(/\D/g, "")}`;
 }
 
+/**
+ * The same, for a number that arrives already written out: `"+39 06 0000 0000"`
+ * → `"+390600000000"`. `undefined` if it is not in international form.
+ *
+ * Beside `e164` rather than wherever it is called, because the two answer one
+ * question from different inputs and the *rule* is the paragraph above: only
+ * punctuation goes, nothing is added, and no leading zero is touched. Written
+ * out twice, that rule survives in one copy and quietly stops being true in the
+ * other — and the version that stops being true is the one nobody re-reads,
+ * because both keep producing a `tel:` that looks fine.
+ *
+ * The structured form is the one to prefer where there is a choice: `code` and
+ * `number` cannot be run together wrongly, and `formatPhone` renders the same
+ * value for a reader. This is for the case where there is no choice — a number
+ * inside a sentence, where the copy is what holds it.
+ *
+ * **International form is required, and that is the whole check.** A local
+ * number dials from inside the country and silently fails everywhere else,
+ * which for a venue is precisely the visitor worth reaching. It is also
+ * invisible on the page, because the number *reads* correctly — so the refusal
+ * has to happen here, where the `+` either is or is not.
+ */
+export function e164Of(written: string): E164 | undefined {
+    if (!written.trimStart().startsWith("+")) return undefined;
+    return `+${written.replace(/\D/g, "")}`;
+}
+
 /** An email address, which is only ever used whole. */
 export type EmailAddress = `${string}@${string}`;
 
-export function mailtoHref(email: EmailAddress): string {
+/**
+ * The runtime half of `EmailAddress`, written as a guard so the check that
+ * refuses is also the check that narrows — as `isHttpsUrl` is for `HttpsUrl`.
+ *
+ * Needed because an address does not always arrive as a literal. One written
+ * into copy and pulled back out by `rich()` is a `string` as far as the types
+ * are concerned, and without this the call site either casts — asserting what it
+ * has not tested — or invents its own idea of what an address looks like, which
+ * is how two of them end up disagreeing.
+ *
+ * **`includes("@")` is exactly what the type says, and not less.** The shape is
+ * `` `${string}@${string}` ``, whose two halves may each be empty, so it admits
+ * `"@x"` and `"x@"` — and so does this. That is the point rather than a gap:
+ * the pair agree, and a stricter runtime check would start rejecting values the
+ * compiler had already accepted. Validating an address properly is famously not
+ * a regex, and a half-strict one here would only move where the disagreement
+ * lives. The `mailto:` either opens with something in the To: field or it does
+ * not, which is the failure this is guarding against.
+ */
+export function isEmailAddress(value: string): value is EmailAddress {
+    return value.includes("@");
+}
+
+/**
+ * The `mailto:` for an address.
+ *
+ * The return type is narrowed rather than left as `string` so that anything
+ * carrying one — `Span`'s email run, say — can demand a scheme it did not have
+ * to build itself.
+ */
+export function mailtoHref(email: EmailAddress): MailtoUrl {
     return `mailto:${email}`;
 }
 

package/src/content/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Copy that carries styling, without carrying markup.
+ *
+ * A paragraph is one message, marked up in the copy itself — see `marks.ts` for
+ * why it cannot be an array of keys — and this module turns it into runs a
+ * project renders however it likes. Lib owns which runs exist and what they say;
+ * the project owns what they look like.
+ *
+ * ```ts
+ * // config/messages.ts
+ * "about.intro": {
+ *     "en-US": "Book [v:accent]up to six[/v] at [a:venue]our venue[/a].",
+ * }
+ *
+ * // a view
+ * const rich = site.rich(locale);
+ * <RichText spans={rich("about.intro")} />
+ *
+ * // the same sentence, where a string is what fits
+ * description: plain(rich("about.intro"))
+ * ```
+ *
+ * There is no authored `ContentItem[]`. Where a project needs to compose runs
+ * itself — a price, a number pulled from config — it builds `Span[]` directly,
+ * which is already the resolved shape and needs nothing from here.
+ */
+
+export { assertNoMarks, type ParsedSpan, parseMarks } from "./marks.ts";
+export {
+    createPlainText,
+    createRichText,
+    type LinkResolver,
+    type LinkTarget,
+    type PlainTextFor,
+    plain,
+    type RichText,
+    type RichTextFor,
+    type RichTextOptions,
+    type Span,
+} from "./rich.ts";

package/src/content/marks.ts

@@ -0,0 +1,408 @@
+/**
+ * The parser that turns one message into styled runs.
+ *
+ * The whole reason this file exists rather than a `ContentItem[]` in config:
+ * **a sentence is one message**. The shape this replaces authored a paragraph
+ * as an array of translation keys — `hero.subtitle_text_1` through `_7` — and
+ * concatenated them in the order the array was written. That fixes two things
+ * copy is not allowed to fix. Word order, which differs per language, 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 missing fragments get
+ * padded with empty strings or the spare ones get dropped, and either way the
+ * translator is editing around a data structure instead of writing a sentence.
+ *
+ * So the marks live *in the copy*, where the translator can move them:
+ *
+ * ```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].",
+ * }
+ *
+ * rich("about.intro", { venue: "contact" })   // the destination, stated once
+ * ```
+ *
+ * One key, one sentence, and each language orders and splits it however it
+ * needs to. What cannot drift is *which* marks a message uses: the same
+ * machinery that holds `{placeholders}` in step across locales sees these too,
+ * so a translation that loses the link fails the build rather than the page.
+ *
+ * This is deliberately a parser and not a `replace` over a pattern, for the
+ * reason `render` in `i18n/translate.ts` is one: a `[` that opens nothing is a
+ * mistake, not an escape hatch, and it is refused here rather than shipped to
+ * a page as literal text. `[[` and `]]` are the escapes, matching `{{` and `}}`
+ * one file over.
+ */
+
+import type { IsName } from "../i18n/placeholders.ts";
+
+/**
+ * One run of a message, still holding its `{placeholders}`.
+ *
+ * The unresolved half of `Span`: a link knows the *name* of the slot it fills
+ * and nothing about where that goes, because copy does not hold addresses —
+ * see `[a:]` below. `rich.ts` finishes the job.
+ */
+export type ParsedSpan =
+    | { readonly kind: "text"; readonly text: string }
+    | { readonly kind: "bold"; readonly text: string }
+    | {
+          readonly kind: "styled";
+          readonly text: string;
+          readonly variant: string;
+      }
+    | {
+          readonly kind: "link";
+          readonly text: string;
+          /** The slot to fill, e.g. `venue` in `[a:venue]`. Never a URL. */
+          readonly name: string;
+      }
+    | { readonly kind: "email"; readonly text: string }
+    | { readonly kind: "phone"; readonly text: string }
+    | { readonly kind: "break" };
+
+/**
+ * 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.
+ *
+ * `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
+ * screen reader announces, and 952 of the runs in the data this replaced were
+ * exactly it. Everything else that was a *style* — a colour, a size — is `[v:]`
+ * and carries a name the project's renderer maps. See `Span.variant`.
+ */
+const MARKS = {
+    b: "bold",
+    v: "styled",
+    a: "link",
+    mail: "email",
+    tel: "phone",
+} as const;
+
+type MarkName = keyof typeof MARKS;
+
+/** The marks whose meaning is incomplete without an argument. */
+const NEEDS_ARGUMENT: ReadonlySet<string> = new Set<MarkName>(["v", "a"]);
+
+/** Written `[br]`, closed by nothing, and the only mark that wraps no words. */
+const VOID_MARK = "br";
+
+/**
+ * The type-level half of `MARKS`, kept beside it rather than a file away.
+ *
+ * **Change one and change the other**, exactly as `NAME` and `NameChar` say to
+ * — and deliberately not the way they are arranged. Those two decide the same
+ * thing from opposite ends of the package and drifted apart once, which is the
+ * mistake this avoids by keeping the pair in view of each other. The runtime
+ * table is above; the union is here.
+ */
+type OpenMark = "b" | "br" | "mail" | "tel" | `v:${string}` | `a:${string}`;
+
+type CloseMark = "/b" | "/v" | "/a" | "/mail" | "/tel";
+
+/**
+ * Every mark a template uses, as a union of the literal tokens it spells.
+ *
+ * The counterpart of `Placeholders` in `i18n/placeholders.ts`, and there for
+ * exactly the same failure: a message whose translation quietly lost something
+ * structural. That file's whole subject is a `{name}` dropped from one locale
+ * and rendered as a literal brace; this is a translator dropping `[a:venue]`
+ * and the Greek page losing the link altogether — worse, because nothing is
+ * left on the page to notice.
+ *
+ * **The argument is part of the token, on purpose.** `[a:venue]` and
+ * `[a:booking]` are different tokens, so a translation cannot fill a different
+ * slot from the one the other locales fill, and `[v:accent]` cannot become
+ * `[v:inverse]` in one language. Those are decisions the copy makes once, not
+ * per locale.
+ *
+ * An escaped `[[b]]` asks for nothing, and falls out rather than needing a case:
+ * the candidate inferred from it is `"[b"`, which is not a member of either
+ * union. Same trick `Placeholders` plays on `{{name}}`.
+ *
+ * Multiplicity is not carried — two `[b]` runs and one look alike here — which
+ * is the limit `Placeholders` has with two `{name}`s and is worth the same
+ * trade.
+ */
+export type MarkTokens<S extends string> =
+    S extends `${string}[${infer Token}]${infer Rest}`
+        ?
+              | (Token extends OpenMark | CloseMark ? `[${Token}]` : never)
+              | MarkTokens<Rest>
+        : never;
+
+/** Distributes over the token union, which `MarkTokens<S>` would not do inline. */
+type SlotOfToken<T> = T extends `[a:${infer Name}]`
+    ? IsName<Name> extends true
+        ? Name
+        : never
+    : never;
+
+/**
+ * The link slots a message declares, as a union of their names.
+ *
+ * What `rich()` turns into required arguments: `"See [a:venue]us[/a]"` asks the
+ * call site for `{ venue: … }`, and the type of that value is a `LinkTarget`
+ * over the routes this project actually builds. **That is the whole reason
+ * copy names a slot rather than a destination.** A route id written into a
+ * translation is a string until the day that message renders; written at the
+ * call site it is checked against the route table like every other link in the
+ * package, it is stated once instead of once per language, and an external URL
+ * stays out of the copy a translator is editing.
+ *
+ * Read off `MarkTokens` rather than scanning the template again, which is not a
+ * shortcut: the scan is where an escaped `[[a:x]]` gets correctly ignored, and a
+ * second pattern that skipped straight to `[a:` would find the `x` inside it and
+ * demand an argument for a link that does not exist.
+ */
+export type LinkNames<S extends string> = SlotOfToken<MarkTokens<S>>;
+
+/**
+ * The names a `[a:name]` slot may be spelled with.
+ *
+ * Exactly `NAME` in `i18n/translate.ts`, because a slot name is the same kind
+ * of thing a `{placeholder}` name is: a key the *call site* writes, in
+ * `rich(key, { venue: "contact" })`. A hyphen there forces quoting and reads as
+ * a mistake, so it is not allowed, and `LinkNames` below reuses `IsName` rather
+ * than restating the rule — the two cannot drift because there is one of them.
+ *
+ * A character class rather than a hand-rolled check, for the reason `NAME` is
+ * one. Speed is not the argument either way: both run at build time on a word.
+ */
+const SLOT = /^[a-zA-Z0-9_]+$/;
+
+/**
+ * What may be spelled in a `[v:name]` variant.
+ *
+ * **`SLOT` plus the hyphen, and the difference is the point.** A variant is
+ * never written in TypeScript at all — copy spells it and the renderer looks it
+ * up — and what it usually mirrors is a CSS custom property or a design token,
+ * which are kebab by convention. `[v:on-dark]` is the natural spelling and
+ * `[v:on_dark]` is the one that would have to be explained. A slot name is a
+ * call-site key and a variant is not, so they answer the hyphen differently.
+ */
+const VARIANT = /^[a-zA-Z0-9_-]+$/;
+
+/** The offending mark, quoted, so the error points at something findable. */
+function describeMark(template: string, open: number, close: number): string {
+    const end = close === -1 ? Math.min(open + 20, template.length) : close + 1;
+    return `"${template.slice(open, end)}"`;
+}
+
+/**
+ * Splits a message into runs, and refuses anything malformed.
+ *
+ * `at` names the message and locale, exactly as `render` is given it, so a
+ * failure says which string to go and fix rather than only that one is wrong.
+ *
+ * Marks do not nest. `[b]bold [v:accent]and red[/v][/b]` is refused rather than
+ * flattened, because the resolved span is a single kind and there is nowhere
+ * for the second one to go — a run is bold *or* it carries a variant. The shape
+ * this replaced had the same limit and answered it by inventing a `boldUnderline`
+ * kind, which was used once in fifty-four deployments; a renderer that wants the
+ * combination should give a variant both properties and name it once.
+ */
+export function parseMarks(
+    template: string,
+    at: string
+): readonly ParsedSpan[] {
+    const spans: ParsedSpan[] = [];
+    let text = "";
+    let open:
+        | { readonly name: MarkName; readonly argument: string }
+        | undefined;
+    let openedAt = 0;
+    let index = 0;
+
+    /**
+     * Emits whatever has accumulated, as plain text or as the open mark's run.
+     *
+     * Empty runs are dropped rather than emitted: `[b][/b]` is copy someone
+     * half-deleted, and a span with no words renders an empty element that
+     * still takes up a renderer's `switch`.
+     */
+    function flush(): void {
+        if (text === "") return;
+        spans.push(
+            open === undefined ? { kind: "text", text } : run(open, text)
+        );
+        text = "";
+    }
+
+    function run(
+        mark: { readonly name: MarkName; readonly argument: string },
+        content: string
+    ): ParsedSpan {
+        switch (MARKS[mark.name]) {
+            case "bold":
+                return { kind: "bold", text: content };
+            case "styled":
+                return {
+                    kind: "styled",
+                    text: content,
+                    variant: mark.argument,
+                };
+            case "link":
+                return {
+                    kind: "link",
+                    text: content,
+                    name: mark.argument,
+                };
+            case "email":
+                return { kind: "email", text: content };
+            case "phone":
+                return { kind: "phone", text: content };
+        }
+    }
+
+    while (index < template.length) {
+        const char = template[index] as string;
+
+        if (char === "[" && template[index + 1] === "[") {
+            text += "[";
+            index += 2;
+            continue;
+        }
+        if (char === "]" && template[index + 1] === "]") {
+            text += "]";
+            index += 2;
+            continue;
+        }
+        // A lone `]` stays text, for the reason a lone `}` does in `render`:
+        // 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.
+        if (char !== "[") {
+            text += char;
+            index += 1;
+            continue;
+        }
+
+        const close = template.indexOf("]", index + 1);
+        if (close === -1) {
+            throw new Error(
+                `${at} has a "[" that is never closed: ${describeMark(template, index, close)}. To write a literal bracket, double it: "[[".`
+            );
+        }
+        const inner = template.slice(index + 1, close);
+
+        if (inner.startsWith("/")) {
+            const name = inner.slice(1);
+            if (open === undefined) {
+                throw new Error(
+                    `${at} closes [${name}] without opening it: ${describeMark(template, index, close)}.`
+                );
+            }
+            if (name !== open.name) {
+                throw new Error(
+                    `${at} opens [${open.name}] and closes [${name}]: ${describeMark(template, index, close)}. Marks do not nest, so the one that opens is the one that must close.`
+                );
+            }
+            flush();
+            open = undefined;
+            index = close + 1;
+            continue;
+        }
+
+        if (inner === VOID_MARK) {
+            flush();
+            spans.push({ kind: "break" });
+            index = close + 1;
+            continue;
+        }
+
+        const separator = inner.indexOf(":");
+        const name = separator === -1 ? inner : inner.slice(0, separator);
+        const argument = separator === -1 ? "" : inner.slice(separator + 1);
+
+        if (!Object.hasOwn(MARKS, name)) {
+            throw new Error(
+                `${at} has a "[" that opens neither a mark nor an escape: ${describeMark(template, index, close)}. The marks are ${markList()}. To write a literal bracket, double it: "[[".`
+            );
+        }
+        const mark = name as MarkName;
+
+        if (open !== undefined) {
+            throw new Error(
+                `${at} opens [${mark}] inside [${open.name}]: ${describeMark(template, index, close)}. Marks do not nest — close the first, or give one variant both properties and name it once.`
+            );
+        }
+        if (NEEDS_ARGUMENT.has(mark)) {
+            if (argument === "") {
+                throw new Error(
+                    `${at} has ${describeMark(template, index, close)} with nothing after the colon. ${argumentHint(mark)}`
+                );
+            }
+            if (mark === "v" && !VARIANT.test(argument)) {
+                throw new Error(
+                    `${at} has a variant that is not a name: ${describeMark(template, index, close)}. A variant is letters, digits, hyphens and underscores — it is looked up by the renderer, not printed.`
+                );
+            }
+            // Catches the shape this used to *require*: a route id, a path or a
+            // URL written straight into the copy. Naming it here rather than
+            // letting it through as an odd slot name, because a translation
+            // carried over from the old form fails on the address itself.
+            if (mark === "a" && !SLOT.test(argument)) {
+                throw new Error(
+                    `${at} has a link slot that is not a name: ${describeMark(template, index, close)}. ${argumentHint(mark)}`
+                );
+            }
+        } else if (separator !== -1) {
+            throw new Error(
+                `${at} passes an argument to a mark that takes none: ${describeMark(template, index, close)}. Write "[${mark}]".`
+            );
+        }
+
+        flush();
+        open = { name: mark, argument };
+        openedAt = index;
+        index = close + 1;
+    }
+
+    if (open !== undefined) {
+        throw new Error(
+            `${at} opens [${open.name}] and never closes it: ${describeMark(template, openedAt, template.indexOf("]", openedAt))}. Close it with "[/${open.name}]".`
+        );
+    }
+    flush();
+    return spans;
+}
+
+function markList(): string {
+    return `${Object.keys(MARKS)
+        .map((name) => `[${name}]`)
+        .join(", ")} and [${VOID_MARK}]`;
+}
+
+function argumentHint(mark: MarkName): string {
+    return mark === "a"
+        ? `A link names a slot the call site fills, not an address: write "[a:venue]" and pass rich(key, { venue: "contact" }). Copy holds no route ids or URLs — they belong where the route table can check them, and where they are written once rather than once per language.`
+        : `A variant names a style the renderer knows, e.g. "[v:accent]".`;
+}
+
+/**
+ * Refuses a message that carries marks, for the callers that can only print it.
+ *
+ * The parser runs rather than a pattern, so a malformed mark fails here with
+ * the same error it would fail with anywhere else — `"[b]bold"` is a mistake
+ * 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.
+ */
+export function assertNoMarks(template: string, at: string): void {
+    const marked = parseMarks(template, at).some(
+        (span) => span.kind !== "text"
+    );
+    if (marked) {
+        throw new Error(
+            `${at} carries marks, and t() can only print them. Read it with rich(), or with plain(rich(…)) for the words alone.`
+        );
+    }
+}