vantage-md 0.7.1 → 0.8.0

package/dist/react.js

@@ -1,18 +1,18 @@
 import { memo, useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import ReactMarkdown from "react-markdown";
-import remarkGfm from "remark-gfm";
-import remarkMath from "remark-math";
 import rehypeRaw from "rehype-raw";
 import rehypeSanitize, { defaultSchema } from "rehype-sanitize";
 import rehypeHighlight from "rehype-highlight";
 import rehypeKatex from "rehype-katex";
 import rehypeSlug from "rehype-slug";
 import { visit } from "unist-util-visit";
+import remarkGfm from "remark-gfm";
+import remarkMath from "remark-math";
 import YAML from "yaml";
 import { parse } from "smol-toml";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { unified } from "unified";
 import remarkParse from "remark-parse";
+import { unified } from "unified";
 import remarkRehype from "remark-rehype";
 import rehypeStringify from "rehype-stringify";
 //#region src/rehypeVantageAnchors.ts
@@ -127,6 +127,12 @@ const VANTAGE_ALERTS = [
 	"warning",
 	"caution"
 ];
+/**
+* The class on the title element this plugin injects, which
+* `styles/directives.css` styles. Exported because the sanitizer runs after
+* this plugin and admits a `div`'s class only when it is this one.
+*/
+const ALERT_TITLE_CLASS = "vantage-alert-title";
 /** The visible label per kind. Title case, as GitHub renders it. */
 const ALERT_TITLES = {
 	note: "Note",
@@ -150,7 +156,7 @@ const ALERT_TITLES = {
 * anchored test on the first text node is enough, and the plugin does not have
 * to reassemble the marker across siblings.
 */
-const MARKER = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*(?:\r?\n|$)/;
+const ALERT_MARKER = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*(?:\r?\n|$)/;
 /** The first child, if it is an element. */
 function firstElement(node) {
 	const child = node.children.find((c) => c.type === "element" || c.type === "text" && c.value.trim() !== "");
@@ -177,7 +183,7 @@ function rehypeVantageAlerts() {
 			if (paragraph === void 0 || paragraph.tagName !== "p") return;
 			const lead = paragraph.children[0];
 			if (lead === void 0 || lead.type !== "text") return;
-			const match = MARKER.exec(lead.value);
+			const match = ALERT_MARKER.exec(lead.value);
 			if (match === null) return;
 			const kind = match[1].toLowerCase();
 			lead.value = lead.value.slice(match[0].length);
@@ -189,7 +195,7 @@ function rehypeVantageAlerts() {
 			node.children.unshift({
 				type: "element",
 				tagName: "div",
-				properties: { className: ["vantage-alert-title"] },
+				properties: { className: [ALERT_TITLE_CLASS] },
 				children: [{
 					type: "text",
 					value: ALERT_TITLES[kind]
@@ -200,6 +206,10 @@ function rehypeVantageAlerts() {
 }
 //#endregion
 //#region src/vantageDirectives.ts
+/** Whether `name` declares a question, `question` or the deprecated `oq`. */
+function isQuestionDirective(name) {
+	return name === "oq" || name === "question";
+}
 /**
 * The `tone` vocabulary: GitHub's alert words plus `muted`.
 *
@@ -292,13 +302,32 @@ const VANTAGE_STYLE_TARGETS = [
 	"div"
 ];
 /**
-* The tags an `oq` directive may stamp — strictly the tags the review system
-* can resolve an anchor on (`ANCHOR_TAGS` in the app's `MarkdownViewer`, and the
-* block map in `useReviewHighlights`). `ul`, `ol`, `tr`, `hr` and `div` are in
-* neither, so a button on one of them would build an anchor no review pass can
-* find — the "mis-wired button" D6 forbids.
+* The tags a `fallback` directive may **withhold**: `VANTAGE_STYLE_TARGETS`
+* minus the six headings, written as a subtraction so the narrowing stays
+* visible.
 *
-* The gap between this list and `VANTAGE_STYLE_TARGETS` is why an `oq`
+* A heading is refused because it is the document's structure rather than a
+* stand-in for anything: the contents column lists it, other documents link to
+* its slug, and the planning index reads sections under it. A fallback heading
+* would be an anchor that exists on GitHub and nowhere in Vantage. What a
+* fallback holds — a sentence naming the release a drawing needs, a link to
+* the drawing as a file, an ASCII sketch in a fence — is a paragraph, a list,
+* a quote, a code block, a table or a `<div>`, and those are all here.
+*
+* Three callers read it, and they must agree: `rehypeVantageDirectives`, which
+* withholds the block; the planning index's scan, which must not read a
+* question or a link from a block the page never shows; and the checker's
+* `vantage/orphan`, which reports a fallback that withholds nothing.
+*/
+const VANTAGE_FALLBACK_TARGETS = VANTAGE_STYLE_TARGETS.filter((tag) => !/^h[1-6]$/.test(tag));
+/**
+* The tags a question directive, `oq` or `question`, may stamp — strictly the
+* tags the review system can resolve an anchor on (`ANCHOR_TAGS` in the app's
+* `MarkdownViewer`, and the block map in `useReviewHighlights`). `ul`, `ol`,
+* `tr`, `hr` and `div` are in neither, so a button on one of them would build
+* an anchor no review pass can find — the "mis-wired button" D6 forbids.
+*
+* The gap between this list and `VANTAGE_STYLE_TARGETS` is why a question
 * directive at column 0 above a list silently does nothing: the target is the
 * `<ul>`, not the `<li>`. The checker says so.
 */
@@ -317,9 +346,9 @@ const VANTAGE_ANCHOR_TARGETS = [
 ];
 VANTAGE_ANCHOR_TARGETS.filter((tag) => tag !== "pre" && tag !== "table");
 /**
-* The shape of an `oq` directive's `id`: `OQ-` then an optional short uppercase
-* prefix then digits. `OQ-9`, `OQ-TP6` and `OQ-A03` are ids; `OQ-foo`, `OQ-tp6`
-* and a bare `OQ6` are not.
+* The shape of a question directive's `id`, on `oq` and `question` alike:
+* `OQ-` then an optional short uppercase prefix then digits. `OQ-9`, `OQ-TP6`
+* and `OQ-A03` are ids; `OQ-foo`, `OQ-tp6` and a bare `OQ6` are not.
 *
 * The prefix is what keeps ids distinct once one document references another's
 * questions — `trust-paths.md`'s `OQ-4` and a design sketch's `OQ-4` are
@@ -327,10 +356,15 @@ VANTAGE_ANCHOR_TARGETS.filter((tag) => tag !== "pre" && tag !== "table");
 * reference means. It is optional because most documents never leave their own
 * file, and requiring it everywhere would fire on every single-doc sketch.
 *
-* Three consumers read it from here and none of them may re-spell it: the
-* plugin that stamps the anchor, the sanitizer that allowlists the value, and
-* the checker's `vantage/oq-id-format`. A fourth copy is how the checker starts
-* calling a working anchor malformed.
+* Read from here, never re-spelled, by the sanitizer that allowlists the value,
+* by the checker's `collectOqIds` (which feeds `vantage/oq-id-format` and the
+* anchors the checker accepts) and by the planning index. The directive plugin
+* that stamps the anchor deliberately does not test it: it stamps any non-empty
+* id and leaves refusing a malformed one to the sanitizer. A re-spelled copy is
+* how the checker starts calling a working anchor malformed — and the patterns
+* that look for an id in text (`OQ_REFERENCE` and `OQ_EXACT` in the checker's
+* `rules/references.ts`, `OQ_TOKEN` in `planning/scan.ts` and in
+* `FrontmatterDisplay.tsx`) restate this shape, so they change with it.
 */
 const VANTAGE_OQ_ID = /^OQ-(?:[A-Z][A-Z0-9]{0,5})?[0-9]+$/;
 const STYLE_KEYS = {
@@ -343,10 +377,21 @@ const STYLE_KEYS = {
 * Name → key → the closed value set for that key.
 *
 * `section` and `block` share their keys: they differ in *extent*, not in what
-* they can say. `oq`'s two keys are the design's only values with no closed set
-* — `id` is a token an author chose and `leaning` is a sentence (§8.3) — so
-* neither can be value-allowlisted, which is recorded here as `null` rather
-* than left to a caller to guess.
+* they can say. The two question names share theirs too, and they are the
+* design's only values with no closed set — `id` is a token an author chose
+* and `leaning` is a sentence (§8.3) — so neither can be value-allowlisted,
+* which is recorded here as `null` rather than left to a caller to guess.
+*
+* `question` takes exactly `oq`'s keys and nothing more. Starting narrow is
+* the forward-compatible choice: a key added later is one older viewers drop
+* pair by pair, while a key accepted now could never be given a meaning (P0).
+* A `leaning` on a 🔒 or ✅ question is allowed and simply not offered
+* (`questionOffersTake`), so changing a question's state changes only its
+* marker.
+*
+* `fallback` takes no keys: whether a block is withheld is the whole of what
+* it says, and a key added later is dropped pair by pair by this release, as
+* D2 drops any other.
 */
 const DIRECTIVE_VOCABULARY = {
 	section: STYLE_KEYS,
@@ -354,9 +399,59 @@ const DIRECTIVE_VOCABULARY = {
 	oq: {
 		id: null,
 		leaning: null
-	}
+	},
+	question: {
+		id: null,
+		leaning: null
+	},
+	fallback: {}
 };
 /**
+* Merge the question directives of one run — the comments up to the block they
+* land on — into the one question they declare, or `undefined` when the run
+* holds none. Directives of any other name are skipped.
+*
+* A run holding an `oq` is read exactly as a viewer that predates `question`
+* reads it: that viewer drops every `question` and reads the `oq` alone, so
+* the `oq` wins wherever it appears in the run, and only its keys apply — a
+* key only a `question` in the same run sets applies nowhere, in no release.
+* That is the one reading every viewer agrees on (`VANTAGE_QUESTION_NAMES`),
+* so the same bytes file the same Take in 0.7 and in 0.8. Within one name, the
+* last value of a key wins, as `section` and `block` resolve theirs. A pair
+* its name does not accept, or a value outside a closed set, is dropped (D2).
+*
+* One function for every reader of a run: the plugin that stamps the question
+* and the planning index that reads it, which the checker reads a question
+* through, so none can disagree about which leaning or which id a run carries
+* (D5).
+*/
+function mergeQuestionRun(run) {
+	let name;
+	for (const directive of run) {
+		if (!isQuestionDirective(directive.name)) continue;
+		if (name !== "oq") name = directive.name;
+	}
+	if (name === void 0) return void 0;
+	const accepted = DIRECTIVE_VOCABULARY[name] ?? {};
+	const keys = /* @__PURE__ */ new Map();
+	const sources = /* @__PURE__ */ new Map();
+	run.forEach((directive, index) => {
+		if (directive.name !== name) return;
+		for (const pair of directive.pairs) {
+			const values = accepted[pair.key];
+			if (values === void 0) continue;
+			if (values !== null && !values.includes(pair.value)) continue;
+			keys.set(pair.key, pair.value);
+			sources.set(pair.key, index);
+		}
+	});
+	return {
+		name,
+		keys,
+		sources
+	};
+}
+/**
 * `ws` is `[ \t\r\n]` — the design's grammar leaves it undefined, and `\n` has
 * to be in the set because a directive may legally wrap: a multi-line comment
 * is one node whose value contains the newlines.
@@ -462,10 +557,24 @@ function parseVantageDirective(comment) {
 		pairs
 	};
 }
+/**
+* A question directive's `leaning=` value as the page carries it: whitespace
+* runs collapsed to one space, trimmed, and capped at `MAX_LEANING`.
+*
+* A wrapped directive puts newlines and indentation into the value. Two readers
+* need the result and must agree on it: `rehypeVantageDirectives`, which stamps
+* it as `data-vantage-leaning` for the one-click answer, and the planning index,
+* which reports the leaning a question carries. An empty result means the
+* question states no leaning.
+*/
+function normalizeLeaning(raw) {
+	return raw.replace(/\s+/g, " ").trim().slice(0, 500);
+}
 //#endregion
 //#region src/rehypeVantageDirectives.ts
 /**
-* What a `section`/`block` and an `oq` directive may **target**.
+* What a `section`/`block` and a question directive (`oq`, `question`) may
+* **target**.
 *
 * Both lists live in `vantageDirectives.ts`, with the reasoning for each tag,
 * because the CLI checker resolves the same question over mdast and must reach
@@ -475,6 +584,8 @@ function parseVantageDirective(comment) {
 */
 const STYLE_TARGET_TAGS = new Set(VANTAGE_STYLE_TARGETS);
 const ANCHOR_TARGET_TAGS = new Set(VANTAGE_ANCHOR_TARGETS);
+/** What a `fallback` may withhold: every style target but a heading. */
+const FALLBACK_TARGET_TAGS = new Set(VANTAGE_FALLBACK_TARGETS);
 const HEADING_DEPTHS = /* @__PURE__ */ new Map([
 	["h1", 1],
 	["h2", 2],
@@ -515,6 +626,19 @@ const RANGE_PROPERTIES = /* @__PURE__ */ new Map([["tone", "dataVantageTone"], [
 */
 const POINT_PROPERTIES = /* @__PURE__ */ new Map([["badge", "dataVantageBadge"]]);
 const RUN_PROPERTY = "dataVantageRun";
+/**
+* What a question stamps, whichever name declared it: `data-vantage-question`
+* on every question, and `data-vantage-oq` besides on one an `oq` declared
+* (`VANTAGE_QUESTION_ATTRIBUTE`, `VANTAGE_OQ_ATTRIBUTE`).
+*
+* Two attributes, and neither one ever means more than it says. Every release
+* since 0.7 stamps `data-vantage-oq` on an `oq` and on nothing else, so a
+* reader of this package's markup that has ever read it keeps reading exactly
+* what it read; `data-vantage-question` is the one to read for "a question",
+* and the question's state, from its marker, is what decides whether anything
+* offers to answer it (`questionOffersTake`).
+*/
+const QUESTION_PROPERTY = "dataVantageQuestion";
 const OQ_PROPERTY = "dataVantageOq";
 const LEANING_PROPERTY = "dataVantageLeaning";
 /**
@@ -549,8 +673,6 @@ const OQ_ID_PROPERTY = "dataVantageOqId";
 const COLLAPSED_PROPERTY = "dataVantageCollapsed";
 const COLLAPSE_GROUP_PROPERTY = "dataVantageCollapseGroup";
 const COLLAPSE_TOGGLE_PROPERTY = "dataVantageCollapseToggle";
-/** A review-comment body, not prose. Bounds the attribute; 500 is generous. */
-const MAX_LEANING = 500;
 /**
 * Nodes that may sit between a directive and its target.
 *
@@ -684,13 +806,14 @@ function stampStyle(children, targetIndex, name, pairs, state) {
 		}
 	}
 }
-function stampOq(target, pairs) {
-	setProperty(target, OQ_PROPERTY, "true");
+function stampQuestion(target, name, pairs) {
+	setProperty(target, QUESTION_PROPERTY, "true");
+	if (name === "oq") setProperty(target, OQ_PROPERTY, "true");
 	const id = pairs.get("id");
 	if (id !== void 0 && id !== "") setProperty(target, OQ_ID_PROPERTY, id);
 	const leaning = pairs.get("leaning");
 	if (leaning === void 0) return;
-	const text = leaning.replace(/\s+/g, " ").trim().slice(0, MAX_LEANING);
+	const text = normalizeLeaning(leaning);
 	if (text !== "") setProperty(target, LEANING_PROPERTY, text);
 }
 /**
@@ -705,18 +828,14 @@ function stampOq(target, pairs) {
 function stampRun(children, targetIndex, run, state) {
 	const target = children[targetIndex];
 	const style = /* @__PURE__ */ new Map();
-	const oq = /* @__PURE__ */ new Map();
 	let styleName;
-	let hasOq = false;
 	for (const directive of run) if (directive.name === "section" || directive.name === "block") {
 		styleName = directive.name;
 		for (const pair of directive.pairs) style.set(pair.key, pair.value);
-	} else if (directive.name === "oq") {
-		hasOq = true;
-		for (const pair of directive.pairs) oq.set(pair.key, pair.value);
 	}
 	if (styleName !== void 0) stampStyle(children, targetIndex, styleName, style, state);
-	if (hasOq && ANCHOR_TARGET_TAGS.has(target.tagName)) stampOq(target, oq);
+	const question = mergeQuestionRun(run);
+	if (question !== void 0 && ANCHOR_TARGET_TAGS.has(target.tagName)) stampQuestion(target, question.name, question.keys);
 }
 /** A directive comment, or `undefined` for anything else — malformed included. */
 function directiveOf(node) {
@@ -729,7 +848,7 @@ function directiveOf(node) {
 *
 * The whole tree, not just the root: `rehype-raw` leaves comment nodes inside
 * `blockquote`, inside `li`, inside `td` and inline inside `p`, and the real
-* Open Questions layout puts the `oq` directive inside a list item — so a
+* Open Questions layout puts the question directive inside a list item — so a
 * root-only walk finds none of them.
 *
 * Pass order is also what resolves a nested section: an inner heading's
@@ -768,8 +887,66 @@ function processChildren(parent, state) {
 		i = j;
 	}
 }
+/**
+* Remove every block a `fallback` run lands on, with the run itself.
+*
+* A fallback block is written for the renderers that cannot show something
+* Vantage shows — "This drawing needs Vantage 0.8 or later", beside an inline
+* `<svg>`. Every renderer that does not know the name drops the comment and
+* shows the block; this one never renders it, in any mode, in print, or
+* through any of the renderers that share this plugin (D5).
+*
+* The run is found exactly as `processChildren` finds one — the same skip
+* rules, the same first-element target, the same whole-tree walk — and it
+* withholds when any directive in it is a `fallback` and the target is on
+* `VANTAGE_FALLBACK_TARGETS`. Anything else is left for the stamping pass,
+* where a `fallback` is inert.
+*
+* A pass of its own, and first, because a `section` reaches *forward* over its
+* siblings: stamped in one pass, a toned section would count a fallback block
+* after it among its members, give it the run's last `end` marker, and leave
+* the last block anyone sees marked `middle`. Withheld first, the block was
+* never there for any later decision — the section's extent, its run markers,
+* a collapse group's members, a review anchor or an outline entry.
+*/
+function withholdFallbacks(parent) {
+	const children = parent.children;
+	let i = 0;
+	while (i < children.length) {
+		const node = children[i];
+		if (node.type === "element") {
+			withholdFallbacks(node);
+			i++;
+			continue;
+		}
+		const first = directiveOf(node);
+		if (first === void 0) {
+			i++;
+			continue;
+		}
+		let withholds = first.name === "fallback";
+		let j = i + 1;
+		let targetIndex = -1;
+		for (; j < children.length; j++) {
+			const next = children[j];
+			if (next.type === "element") {
+				targetIndex = j;
+				break;
+			}
+			if (!isSkippable(next)) break;
+			if (directiveOf(next)?.name === "fallback") withholds = true;
+		}
+		const target = targetIndex >= 0 ? children[targetIndex] : void 0;
+		if (withholds && target?.type === "element" && FALLBACK_TARGET_TAGS.has(target.tagName)) {
+			children.splice(i, targetIndex - i + 1);
+			continue;
+		}
+		i = j;
+	}
+}
 const rehypeVantageDirectives = () => {
 	return (tree) => {
+		withholdFallbacks(tree);
 		processChildren(tree, { nextGroup: 1 });
 	};
 };
@@ -862,12 +1039,144 @@ const rehypeRestoreMathStamps = () => {
 };
 //#endregion
 //#region src/sanitize.ts
+/** Whether an attribute definition is for `className`. */
+const isClassName = (definition) => (typeof definition === "string" ? definition : definition[0]) === "className";
+/**
+* The value list the default schema gives `className` on `tag`, or an empty
+* list if it gives none.
+*/
+function defaultClasses(tag) {
+	const entry = defaultSchema.attributes?.[tag]?.find(isClassName);
+	return Array.isArray(entry) ? entry.slice(1) : [];
+}
+/**
+* The only classes an element keeps: the ones the pipeline itself emits on it
+* before `rehypeSanitize` runs. Every other element keeps none.
+*
+* **A class is a style by another name.** The app ships Tailwind's utility CSS
+* for its own markup, so `<div class="fixed inset-0 z-50 bg-white">` in a
+* document laid a white sheet over the whole Vantage window, header and
+* sidebar included. That is the overlay `SAFE_STYLE` bans `position` to
+* prevent, spelled as a class instead of a declaration, and `className` used
+* to be admitted with any value on every element. A document could also
+* borrow a class the app's own code looks for: `.overflow-y-auto` is how an
+* anchor link finds the element to scroll when no `data-content-scroll` is in
+* reach, and `.heading-anchor` is what the outline strips from a heading's
+* text. The comment-body sanitizer (`frontend/src/lib/commentMarkdown.ts`)
+* already refused `class` for the same reason.
+*
+* What each entry is for, and who emits it:
+*
+* - `code`: `language-*`, from a fence's info string (`mdast-util-to-hast`).
+*   `rehype-highlight` reads it, `rehype-katex` keys on `language-math`, and
+*   the viewers render `language-mermaid` as a diagram.
+* - `ul`, `ol` and `li`: `contains-task-list` and `task-list-item`, from GFM
+*   task lists. `styles/task-list.css` draws the checkbox from them.
+* - `section`, `h2` and `a`: GFM footnotes (`mdast-util-to-hast`), on the
+*   section, its label and each back-reference.
+* - `div`: `ALERT_TITLE_CLASS`, on the title `rehypeVantageAlerts` injects.
+*
+* `remark-math` also emits `math-display` and `math-inline` on its `code`.
+* They were never kept, because the default schema's `code` entry takes only
+* `language-*`, and nothing needs them: `rehype-katex` keys on `language-math`
+* and tells display from inline by whether the `code` sits in a `pre`.
+*
+* **A class added after the sanitizer needs no entry**, and that is most of
+* the classes the page styles: `rehype-highlight`'s `hljs-*`, KaTeX's output,
+* Mermaid's diagrams, and everything the app's components and hooks add. A
+* document that writes one of those on an element keeps nothing.
+*
+* **Mermaid source is the route this list cannot close.** Mermaid renders
+* after the sanitizer and copies the names a diagram's source gives a node
+* (`:::name`, `class A name`, `classDef`) onto that node, so a diagram can
+* carry any of the app's utilities on its own nodes. The diagram bounds it:
+* `position` does nothing on an SVG group, and the diagram's `svg` clips what
+* is inside it. `frontend/e2e/mermaid.spec.ts` measures that bound. The
+* stylesheet a diagram's source could write did reach past the diagram, and
+* `MERMAID_SECURE_KEYS` in `mermaidLoader.ts` refuses the settings that write
+* it.
+*
+* A document may still write these names on these elements. By the time the
+* sanitizer runs, a hand-written `<li class="task-list-item">` and the one GFM
+* emitted are the same node, and none of the names can lay an element over
+* anything outside the document's scroll container. `styles/task-list.css`
+* floats the checkbox of a `task-list-item` instead of positioning it
+* absolutely, so it stays in the document's flow whatever the item's own
+* `style` does, and the checkbox takes no `style` itself (see
+* `UNSTYLED_TAGS`). The footnote label's class, where a stylesheet defines it,
+* clips its element to a single pixel.
+*
+* **The footnote label's class is read from the default schema, never
+* spelled here, and the tests spell it in halves.** It is a Tailwind utility,
+* and Tailwind generates a utility for every class name it finds in the files
+* it scans, comments included — this directory and all of `frontend/`. The app
+* renders the label as a visible heading only because nothing it scans spells
+* that name. Spelled whole in a test, it generated the rule, and the label
+* would have been hidden from sight as it is on GitHub: a change of rendering,
+* not a sanitizer fix.
+*
+* The list is measured, not remembered. The test "takes no class from
+* anything the pipeline emits" in `frontend/src/lib/sanitize.test.ts` records
+* every class on the tree on both sides of `rehypeSanitize`, over a document
+* that uses every feature that emits one, so a plugin that starts emitting a
+* new class fails there instead of losing it in every renderer.
+*/
+const PIPELINE_CLASSES = {
+	code: [/^language-./],
+	ul: ["contains-task-list"],
+	ol: ["contains-task-list"],
+	li: ["task-list-item"],
+	section: ["footnotes"],
+	h2: defaultClasses("h2"),
+	a: ["data-footnote-backref"],
+	div: [ALERT_TITLE_CLASS]
+};
 /**
-* Sanitization schema for the rendering pipeline.
-* Allows GFM, KaTeX MathML, syntax highlighting classes, and
-* data-source-line attributes while blocking XSS vectors.
-*/
-const DECLARATION = `(?:(?:${[
+* `tag`'s attributes: the default schema's, less any `className`, then its
+* `PIPELINE_CLASSES` entry, then `extra`.
+*
+* **Always a value list, never a bare `"className"`.** `hast-util-sanitize`
+* reads a bare name, or a tuple holding no values, as "any value", and an
+* element's own entry is consulted before `*`'s — the first match wins, and
+* `*` is not consulted when that element's own entry filters a class list down
+* to nothing. An element with no entry has none added.
+*/
+function withClasses(tag, ...extra) {
+	const classes = PIPELINE_CLASSES[tag] ?? [];
+	const own = (defaultSchema.attributes?.[tag] ?? []).filter((definition) => !isClassName(definition));
+	if (classes.length > 0) own.push(["className", ...classes]);
+	return [...own, ...extra];
+}
+/**
+* CSS properties an inline `style` may set.
+*
+* **The only `style` this list ever filters is one a document wrote by hand.**
+* Nothing the pipeline generates reaches it: `rehypeKatex` and `rehypeHighlight`
+* both run *after* `rehypeSanitize` (`pipeline.ts`), so their output is trusted
+* rather than filtered, and `remark-gfm` emits table alignment as an `align`
+* attribute rather than as CSS. So this is a filter on untrusted author HTML and
+* nothing else — which is exactly the hole that made it necessary: `<div
+* style="position:fixed;inset:0">` covered the viewport and
+* `style="background:url(https://…)"` called home on render, both verbatim,
+* because `rehype-sanitize` does not parse CSS. Scripts were never the risk
+* here; layout and network were.
+*
+* The list is therefore deliberately typographic: the styling a prose document
+* has any business asking for. It is *not* sized to KaTeX, and a KaTeX release
+* that starts using a new property is a non-event here — `\pmb` already emits
+* `text-shadow`, which is not on this list and renders anyway.
+*
+* **The design doc used to argue the opposite — that `style` had to be allowed
+* and `position` enumerated because KaTeX needs them — and it was wrong.** The
+* measurement behind it was real (KaTeX does emit `position:relative` on every
+* integral) but the inference was not, because the sanitizer has finished before
+* the first KaTeX span exists. Rebuilding the shipped rehype order with a filter
+* that rejects *every* value leaves all ten of the integral's style attributes
+* untouched. The "Security" section of `docs/reference/inline-markup.md`
+* records the correction; the test that would catch a reordering is in
+* `frontend/src/lib/sanitize.test.ts`.
+*/
+const SAFE_STYLE_PROPERTIES = [
 	"height",
 	"min-height",
 	"max-height",
@@ -922,12 +1231,89 @@ const DECLARATION = `(?:(?:${[
 	"white-space",
 	"vertical-align",
 	"list-style-type",
-	"display",
 	"float",
 	"clear",
 	"opacity",
 	"overflow"
-].join("|")})\\s*:[^;:()"'\\\\]*)`;
+];
+/**
+* A `style` value we will keep, as a whole.
+*
+* One rule beyond the property list does the work: **no parentheses anywhere**,
+* which closes `url(…)` and `expression(…)` in one stroke — the network and
+* legacy-script vectors. Its cost is borne entirely by authors, who lose
+* `calc()`, `rgb()` and `var()` along with them; that is the trade, and it is
+* worth it for a filter this small.
+*
+* **`position` is not on the property list at all**, so every value of it is
+* refused — `static` and `relative` along with `fixed` and `sticky`. It used to
+* be enumerated, on the belief that KaTeX needed `relative`; KaTeX renders after
+* the sanitizer and never meets this regex, so the enumeration was buying
+* nothing but the residual it conceded. Banning the property closes that
+* residual, and it is bigger than "overlaps its neighbors" made it sound:
+* measured in Chrome against the viewer's real ancestor chain, an author's
+* `position:absolute;top:0;left:0;width:100%;height:100%` is sized to the whole
+* content pane (the nearest positioned ancestor is outside the scroll
+* container), is not clipped by the scroller, and survives scrolling to the end
+* of the document. It was `position:fixed` in all but the keyword.
+*
+* Matching is all-or-nothing: one unrecognized declaration drops the whole
+* attribute, and the element renders unstyled rather than partly styled. That
+* is the safe direction to fail, and it degrades to plain text rather than to a
+* broken page.
+*
+* **The grammar must stay unambiguous, and `;` is what keeps it so.** The value
+* class is "anything but the delimiters", which includes whitespace — a value
+* legitimately contains it (`margin: 0 auto`). So if whitespace could *also*
+* end a declaration, both constructs would compete for the same characters and
+* the match would fork at every declaration; on a value that ultimately fails,
+* the engine explores every fork. An earlier form of this regex separated
+* declarations with `\s*;?\s*`, and 200 document-controlled characters took the
+* renderer — and the CLI checker, and therefore CI — 94 seconds. Requiring `;`
+* pins each declaration's extent to the delimiter positions, so there is exactly
+* one way to parse any input and rejection is linear. `VALUE` absorbs the
+* padding on both sides for the same reason: a separate `\\s*` next to it would
+* put the ambiguity straight back. Pinned by the flat-time test in
+* `frontend/src/lib/sanitize.test.ts` — do not loosen the separator.
+*
+* Residual, stated plainly and now genuinely small: negative `margin` still lets
+* an element overlap its neighbors *inside the flow*. That one scrolls with the
+* content and is clipped by the scroll container, and closing it means giving up
+* margins, which prose actually uses. Containment in the stylesheet, not another
+* rule here, is what would close it. `overflow: visible` on an inline `<svg>` is
+* the same residual by another route — see `SVG_ROOT_ATTRIBUTES`.
+*
+* **The app's table of contents is inside that scroll container too**, beside
+* the document column, so a block carried over it took its clicks whenever the
+* block painted in the positioned layer: one with `opacity`, a toned block, a
+* heading, or a link to anywhere. The contents sit at `z-10` for that
+* (`frontend/src/components/TableOfContents.tsx`), and a document cannot climb
+* back over them only because `z-index` is not on the property list.
+*/
+const VALUE = `[^;:()"'\\\\]*`;
+const DISPLAY_DECLARATION = `display\\s*:\\s*(?:${[
+	"none",
+	"block",
+	"inline-block",
+	"inline-flex",
+	"inline-grid",
+	"inline-table",
+	"inline",
+	"flow-root",
+	"flex",
+	"grid",
+	"table-row-group",
+	"table-row",
+	"table-header-group",
+	"table-footer-group",
+	"table-cell",
+	"table-column-group",
+	"table-column",
+	"table-caption",
+	"table",
+	"list-item"
+].join("|")})\\s*(?:!\\s*important\\s*)?`;
+const DECLARATION = `(?:(?:${SAFE_STYLE_PROPERTIES.join("|")})\\s*:${VALUE}|${DISPLAY_DECLARATION})`;
 const SAFE_STYLE = new RegExp(`^\\s*(?:${DECLARATION};\\s*)*${DECLARATION}?$`, "i");
 /**
 * A collapse group id: one or more digits, anchored.
@@ -939,6 +1325,281 @@ const SAFE_STYLE = new RegExp(`^\\s*(?:${DECLARATION};\\s*)*${DECLARATION}?$`, "
 */
 const COLLAPSE_GROUP_ID = /^[0-9]+$/;
 /**
+* Inline SVG, admitted as static drawing and nothing else.
+*
+* The allowlist is shapes, text and grouping. Everything in SVG that can run
+* code, fetch, or reach outside the element is refused: `script`,
+* `foreignObject`, `use` and `image` (both take an `href`), `xlink:href` on
+* `a`, the `animate`/`set` family (which can rewrite an `href` after the
+* sanitizer has looked), `style` elements, and every attribute that takes a
+* `url(…)` reference — `filter`, `mask`, `clip-path`, `marker-*`, `cursor`.
+*
+* Gradients, patterns and `<defs>` are out for a second reason: they are only
+* reachable through `url(#id)`, and the sanitizer prefixes every `id` with
+* `user-content-`, so the reference would dangle even if it were allowed.
+*
+* **Refusing an element is not the same as removing it.** `hast-util-sanitize`
+* *unwraps* an element it does not allow — drops the tag and keeps its
+* children — unless the tag is on `strip`. See `SVG_STRIPPED` for why that
+* matters here, and for the pass that removes those containers instead.
+*
+* `switch` is admitted, as a plain container, because draw.io wraps every label
+* in one: `<switch><foreignObject>…</foreignObject><text>…</text></switch>`. A
+* `switch` renders only its first child whose conditions hold, and with the
+* `foreignObject` removed and the conditional attributes (`requiredFeatures`,
+* `systemLanguage`) refused, that is the `<text>` fallback. Unwrapped instead,
+* it would render *every* branch — including the "Text is not SVG - cannot
+* display" notice draw.io appends for viewers without `foreignObject`.
+*
+* Every child requires an `svg` ancestor, so no shape or text element is
+* admitted into HTML flow on its own.
+*
+* `title` and `desc` are not children at all. They are admitted nowhere, inside
+* a drawing they are removed with their contents (see `SVG_STRIPPED`), and
+* `aria-label` on the root is the drawing's accessible name. Both are HTML
+* integration points — the parser reads what is inside them as HTML — and an
+* `svg` ancestor turned out not to be enough to keep a `<title>` in SVG
+* context. `<math><svg><title>` keeps MathML context, and React hoists any
+* `title` outside SVG context into the page's `<head>`, so the document set the
+* tab title. In `renderMarkdown`'s string output, `<svg><desc><title>`,
+* `<svg><title><title>` and a `title` inside a `foreignObject` all re-parse into
+* an HTML `title`, which is what `document.title` reads on a page that has none
+* of its own.
+*/
+const SVG_CHILD_TAGS = [
+	"g",
+	"path",
+	"rect",
+	"circle",
+	"ellipse",
+	"line",
+	"polyline",
+	"polygon",
+	"text",
+	"tspan",
+	"switch"
+];
+/**
+* Refused SVG elements removed *with their contents* when they sit inside an
+* `<svg>`, rather than unwrapped.
+*
+* Each of these holds children that are never meant to be painted where they
+* stand: a clip region, a mask, a gradient's stops, a marker's arrowhead, a
+* symbol's body, a filter's primitives, an exporter's RDF, the text of a
+* `title` or `desc` (see `SVG_CHILD_TAGS`), or — for `foreignObject` — HTML.
+* Unwrapped, those children land in the drawing as ordinary shapes. A default
+* Figma export ends in `<defs><clipPath><rect fill="white"/>`, and unwrapping
+* it painted that white rect over the whole drawing; a `<marker>` arrowhead
+* became a stray triangle at the origin. The HTML inside a `foreignObject`
+* survived as descendants of `svg`, which React then created as invisible
+* SVG-namespace `div`s and `p`s — the anchor an Open Question button looks for
+* — and which a browser re-parsing `renderMarkdown`'s string output breaks out
+* of the `svg` at, spilling the rest of the drawing into the page.
+*
+* **Only inside an `<svg>`, which is why this is a pass and not the schema's
+* `strip`.** `strip` removes a tag wherever it stands, and most of these names
+* are lowercase in prose too. There a bare `<pattern>` on a line of its own is
+* an HTML element nothing closes, so every Markdown block after it was parsed
+* into it, and stripping it removed the rest of the document — in every
+* renderer, with `vantage-check` silent. Inside a drawing the same container is
+* bounded by the `svg`, because a Markdown paragraph or heading breaks out of
+* SVG. Outside one the sanitizer unwraps these like any tag it does not know:
+* `title` and `desc` are not admitted anywhere, so no `title` element survives
+* to be hoisted, and what they held is text or ordinary sanitized HTML.
+*
+* Names compare case-insensitively. The camel-cased ones are how the HTML
+* parser spells these elements in SVG, but under `<math><svg>` the parser stays
+* in MathML and leaves them lowercase.
+*/
+const SVG_STRIPPED = [
+	"foreignObject",
+	"defs",
+	"clipPath",
+	"mask",
+	"pattern",
+	"marker",
+	"symbol",
+	"linearGradient",
+	"radialGradient",
+	"filter",
+	"metadata",
+	"title",
+	"desc"
+];
+const SVG_STRIPPED_NAMES = new Set(SVG_STRIPPED.map((name) => name.toLowerCase()));
+/**
+* The camel-cased `SVG_STRIPPED` names, which the schema strips on its own.
+*
+* Only an SVG-namespace element carries one of these spellings, so stripping
+* them everywhere costs prose nothing. It keeps the worst of the list — the
+* HTML inside a `foreignObject` — out of a drawing for a consumer who hands
+* `sanitizeSchema` to `rehype-sanitize` without the rest of `buildPipeline`.
+*/
+const SVG_STRIPPED_EVERYWHERE = SVG_STRIPPED.filter((name) => name !== name.toLowerCase());
+function stripSvgContainers(parent, inSvg) {
+	if (inSvg) parent.children = parent.children.filter((child) => child.type !== "element" || !SVG_STRIPPED_NAMES.has(child.tagName.toLowerCase()));
+	for (const child of parent.children) if (child.type === "element") stripSvgContainers(child, inSvg || child.tagName.toLowerCase() === "svg");
+}
+/**
+* Remove every `SVG_STRIPPED` element below an `svg`, with its contents.
+*
+* Runs immediately before `rehypeSanitize` (`pipeline.ts`), and only when the
+* pipeline sanitizes: with the sanitizer off these elements are left to work
+* as SVG defines them.
+*/
+function rehypeStripSvgContainers() {
+	return (tree) => {
+		stripSvgContainers(tree, false);
+	};
+}
+/**
+* A paint value: a keyword, a named color, or a hex color. No parentheses, for
+* the same reason `SAFE_STYLE` refuses them — `fill="url(https://…)"` is a
+* render-time fetch, and `rgb()` is the price of closing it.
+*/
+const SVG_PAINT = /^(?:#[0-9a-f]{3,8}|[a-z]+)$/i;
+/**
+* Attributes any SVG element may carry, drawing and typography alike.
+*
+* **Each entry is a hast property name, which is not always the camel case of
+* the attribute.** `property-information` decides the spelling, and it has
+* `strokeLineCap` for `stroke-linecap` — a naive `strokeLinecap` matches
+* nothing, and the attribute is dropped in every renderer without a word. The
+* table-driven test in `frontend/src/lib/sanitize.test.ts` renders every entry
+* in its written spelling, so a misspelled one fails there.
+*
+* `stroke-dasharray` (and with it `stroke-dashoffset`, which does nothing
+* alone) is refused, because it lets a few bytes buy an unbounded paint. The
+* number of dashes is the path's length over the dash period, both in user
+* units the document chooses. Measured in headless Chromium, fifty 90-byte
+* paths with a 0.0011 dash took 21 s to paint and a hundred took 37 s. A value
+* grammar cannot bound it: refusing sub-unit dashes is undone by scaling the
+* user units, and the same fifty paths with `stroke-dasharray="1.1"` under a
+* `viewBox` a thousand times larger still took 15 s.
+*/
+const SVG_ATTRIBUTES = [
+	["fill", SVG_PAINT],
+	["stroke", SVG_PAINT],
+	"fillOpacity",
+	"fillRule",
+	"strokeOpacity",
+	"strokeWidth",
+	"strokeLineCap",
+	"strokeLineJoin",
+	"opacity",
+	"transform",
+	"fontFamily",
+	"fontSize",
+	"fontWeight",
+	"fontStyle",
+	"letterSpacing",
+	"textAnchor",
+	"dominantBaseline",
+	"x",
+	"y",
+	"x1",
+	"y1",
+	"x2",
+	"y2",
+	"cx",
+	"cy",
+	"r",
+	"rx",
+	"ry",
+	"dx",
+	"dy",
+	"d",
+	"points"
+];
+/**
+* The root `<svg>`'s attributes: `SVG_ATTRIBUTES` less `transform`, plus the
+* viewport, a `role` from a closed list, and the accessible name.
+*
+* `transform` on the root is not an SVG transform at all. The root is an
+* in-flow CSS box, and the attribute becomes a CSS transform of that box, so
+* `<svg width="10" height="10" transform="translate(-300 -300) scale(80)">`
+* laid out as a 10px box and painted as an 800px one over the paragraphs
+* around it. On a child it moves shapes inside the viewport, which clips them.
+*
+* Residual: that clip is the root's `overflow`, which `SAFE_STYLE` lets a
+* document set. `style="overflow:visible"` on the root lets a child with a
+* large `transform` or large coordinates paint over its neighbors — measured in
+* Chromium, the same overlap. It is the negative-`margin` residual described at
+* `SAFE_STYLE` by another route: it stays in the flow, scrolls with the content,
+* and the scroll container clips it.
+*/
+const SVG_ROOT_ATTRIBUTES = [
+	...SVG_ATTRIBUTES.filter((attribute) => attribute !== "transform"),
+	"xmlns",
+	"viewBox",
+	"preserveAspectRatio",
+	[
+		"role",
+		"img",
+		"presentation",
+		"none"
+	],
+	"ariaLabel"
+];
+/** Every element the sanitizer admits. */
+const TAG_NAMES = [
+	...defaultSchema.tagNames || [],
+	"math",
+	"semantics",
+	"mrow",
+	"mi",
+	"mo",
+	"mn",
+	"msup",
+	"msub",
+	"mfrac",
+	"mover",
+	"munder",
+	"msqrt",
+	"mroot",
+	"mtable",
+	"mtr",
+	"mtd",
+	"mtext",
+	"mspace",
+	"annotation",
+	"figure",
+	"figcaption",
+	"summary",
+	"details",
+	"svg",
+	...SVG_CHILD_TAGS
+];
+/**
+* The admitted elements that take no `style`: only `input`, which GFM emits as
+* a task list's checkbox, and never with a style.
+*
+* `styles/task-list.css` draws that checkbox and positions it, so on it `top`
+* and `left` are not the no-ops they are on an element nothing positions, and
+* with `width`, `height` and `background-color` beside them a document laid a
+* box of its own over the page. Measured in Chromium at 1280x800 while the
+* checkbox was positioned absolutely,
+* `top:-3000px;left:-3000px;width:9000px;height:9000px;background-color:white`
+* on it covered the whole content pane. It needed no class written:
+* GFM puts `task-list-item` on the item, and a checkbox typed into the item's
+* text is a child of that item too.
+*
+* **This is why `style` is on each element's own entry, never on `*`.**
+* `hast-util-sanitize` consults `*` whenever an element's own entry yields
+* nothing, so no entry on `input` could refuse a value that `*` admits. An
+* element takes `style` only by being in `TAG_NAMES` and not in this set.
+*/
+const UNSTYLED_TAGS = /* @__PURE__ */ new Set(["input"]);
+/**
+* `attributes`, with `["style", SAFE_STYLE]` added to the entry of every
+* element in `TAG_NAMES` but the `UNSTYLED_TAGS`.
+*/
+function withStyle(attributes) {
+	const styled = { ...attributes };
+	for (const tag of new Set(TAG_NAMES)) if (!UNSTYLED_TAGS.has(tag)) styled[tag] = [...styled[tag] ?? [], ["style", SAFE_STYLE]];
+	return styled;
+}
+/**
 * Never set `allowComments` here.
 *
 * `hast-util-sanitize` drops comment nodes because that boolean defaults to
@@ -952,38 +1613,16 @@ const COLLAPSE_GROUP_ID = /^[0-9]+$/;
 */
 const sanitizeSchema = {
 	...defaultSchema,
-	tagNames: [
-		...defaultSchema.tagNames || [],
-		"math",
-		"semantics",
-		"mrow",
-		"mi",
-		"mo",
-		"mn",
-		"msup",
-		"msub",
-		"mfrac",
-		"mover",
-		"munder",
-		"msqrt",
-		"mroot",
-		"mtable",
-		"mtr",
-		"mtd",
-		"mtext",
-		"mspace",
-		"annotation",
-		"figure",
-		"figcaption",
-		"summary",
-		"details"
-	],
-	attributes: {
+	strip: [...defaultSchema.strip || [], ...SVG_STRIPPED_EVERYWHERE],
+	tagNames: TAG_NAMES,
+	ancestors: {
+		...defaultSchema.ancestors,
+		...Object.fromEntries(SVG_CHILD_TAGS.map((tag) => [tag, ["svg"]]))
+	},
+	attributes: withStyle({
 		...defaultSchema.attributes,
 		"*": [
 			...defaultSchema.attributes?.["*"] || [],
-			"className",
-			["style", SAFE_STYLE],
 			"dataSourceLine",
 			["dataVantageTone", ...VANTAGE_TONES],
 			["dataVantageEmphasis", ...VANTAGE_EMPHASIS],
@@ -993,35 +1632,22 @@ const sanitizeSchema = {
 			["dataVantageCollapseToggle", COLLAPSE_GROUP_ID],
 			["dataVantageRun", ...VANTAGE_RUNS],
 			["dataVantageOq", "true"],
+			["dataVantageQuestion", "true"],
 			["dataVantageOqId", VANTAGE_OQ_ID],
 			["dataVantageAlert", ...VANTAGE_ALERTS],
 			"dataVantageLeaning"
 		],
-		code: [...defaultSchema.attributes?.code || [], "className"],
-		span: [
-			...defaultSchema.attributes?.span || [],
-			"className",
-			["style", SAFE_STYLE]
-		],
-		div: [
-			...defaultSchema.attributes?.div || [],
-			"className",
-			["style", SAFE_STYLE]
-		],
-		a: [
-			...defaultSchema.attributes?.a || [],
-			"id",
-			"className"
-		],
+		...Object.fromEntries(Object.keys(PIPELINE_CLASSES).map((tag) => [tag, withClasses(tag)])),
+		a: withClasses("a", "id"),
 		math: ["xmlns"],
 		annotation: ["encoding"],
 		img: [...defaultSchema.attributes?.img || [], "loading"],
-		td: [...defaultSchema.attributes?.td || [], ["style", SAFE_STYLE]],
-		th: [...defaultSchema.attributes?.th || [], ["style", SAFE_STYLE]]
-	}
+		svg: SVG_ROOT_ATTRIBUTES,
+		...Object.fromEntries(SVG_CHILD_TAGS.map((tag) => [tag, SVG_ATTRIBUTES]))
+	})
 };
 //#endregion
-//#region src/pipeline.ts
+//#region src/remarkPlugins.ts
 /**
 * The mdast half of the chain. Exported on its own because there is a real
 * mdast-only consumer: the CLI checker parses documents without ever running
@@ -1035,6 +1661,8 @@ function buildRemarkPlugins(options = {}) {
 	if (math) plugins.push([remarkMath, { singleDollarTextMath: false }]);
 	return plugins;
 }
+//#endregion
+//#region src/pipeline.ts
 /** The hast half. Deliberately not exported: see `buildPipeline`. */
 function buildRehypePlugins(options = {}) {
 	const { math = true, highlight = true, sourceLines = true, sanitize = true, bodyLineOffset = 0 } = options;
@@ -1042,7 +1670,7 @@ function buildRehypePlugins(options = {}) {
 	if (sourceLines) plugins.push([rehypeSourceLines, { offset: bodyLineOffset }]);
 	plugins.push(rehypeVantageAlerts);
 	plugins.push(rehypeVantageDirectives);
-	if (sanitize) plugins.push([rehypeSanitize, sanitizeSchema]);
+	if (sanitize) plugins.push(rehypeStripSvgContainers, [rehypeSanitize, sanitizeSchema]);
 	plugins.push(rehypeVantageAnchors);
 	plugins.push(rehypeSlug);
 	if (highlight) plugins.push(rehypeHighlight);
@@ -1326,6 +1954,9 @@ const cacheKey = (code, theme) => `${theme}\u0000${code}`;
 function getCachedSvg(code, theme = currentMermaidPalette()) {
 	return svgCache.get(cacheKey(code, theme));
 }
+function hasCachedSvg(code, theme = currentMermaidPalette()) {
+	return svgCache.has(cacheKey(code, theme));
+}
 function setCachedSvg(code, svg, theme = currentMermaidPalette()) {
 	svgCache.set(cacheKey(code, theme), svg);
 }
@@ -1338,6 +1969,43 @@ let mermaidLoading = null;
 * configured for, `null` until loaded.
 */
 let configuredTheme = null;
+/**
+* The configuration keys a diagram's own source may not set, from an `init`
+* directive or from frontmatter: Mermaid's default list, then the three
+* that write a diagram's stylesheet.
+*
+* **A diagram's stylesheet reaches past the diagram.** Mermaid puts every
+* selector of it under the diagram's id, but leaves the names of its
+* `@keyframes` global, so a diagram that defined `flash-update` redefined the
+* animation the viewer plays on a block that just changed. Given
+* `position: fixed` at the size of the window, the next flash laid that block,
+* and the link it held, over the header and the sidebar. The same stylesheet
+* fetched images from any host, which is why `SAFE_STYLE` refuses parentheses.
+*
+* - `themeCSS` is a stylesheet, and Mermaid checks only that its braces pair.
+* - `fontFamily` is copied into `themeVariables` *after* Mermaid's check on
+*   theme variables has run, and lands in the stylesheet as a declaration's
+*   value, where a nested block becomes a rule of its own.
+* - `altFontFamily` lands in a rule the browser parses first, which drops
+*   what does not belong. It is refused anyway: nothing needs it, and that
+*   parse is all that stands in the way.
+*
+* Mermaid applies the list at every depth, so `themeVariables.fontFamily` in
+* a diagram is refused too. The list is spelled whole rather than relying on
+* Mermaid merging it with its default. `frontend/e2e/mermaid.spec.ts` measures
+* all four routes; see "Mermaid" in `docs/reference/inline-markup.md`.
+*/
+const MERMAID_SECURE_KEYS = [
+	"secure",
+	"securityLevel",
+	"startOnLoad",
+	"maxTextSize",
+	"suppressErrorRendering",
+	"maxEdges",
+	"themeCSS",
+	"fontFamily",
+	"altFontFamily"
+];
 function configure(m, palette) {
 	const theme = mermaidThemeOf(palette);
 	m.initialize({
@@ -1345,7 +2013,8 @@ function configure(m, palette) {
 		theme,
 		themeVariables: mermaidThemeVariables(theme),
 		securityLevel: "strict",
-		suppressErrorRendering: true
+		suppressErrorRendering: true,
+		secure: MERMAID_SECURE_KEYS
 	});
 	configuredTheme = palette;
 }
@@ -1388,7 +2057,7 @@ const AlertTriangleIcon = () => /* @__PURE__ */ jsxs("svg", {
 	strokeWidth: "2",
 	strokeLinecap: "round",
 	strokeLinejoin: "round",
-	className: "w-4 h-4 shrink-0",
+	className: "block w-4 h-4 shrink-0",
 	children: [
 		/* @__PURE__ */ jsx("path", { d: "m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3" }),
 		/* @__PURE__ */ jsx("path", { d: "M12 9v4" }),
@@ -1404,7 +2073,7 @@ const ChevronDownIcon = () => /* @__PURE__ */ jsx("svg", {
 	strokeWidth: "2",
 	strokeLinecap: "round",
 	strokeLinejoin: "round",
-	className: "w-3 h-3",
+	className: "block w-3 h-3",
 	children: /* @__PURE__ */ jsx("path", { d: "m6 9 6 6 6-6" })
 });
 const ChevronUpIcon = () => /* @__PURE__ */ jsx("svg", {
@@ -1416,7 +2085,7 @@ const ChevronUpIcon = () => /* @__PURE__ */ jsx("svg", {
 	strokeWidth: "2",
 	strokeLinecap: "round",
 	strokeLinejoin: "round",
-	className: "w-3 h-3",
+	className: "block w-3 h-3",
 	children: /* @__PURE__ */ jsx("path", { d: "m18 15-6-6-6 6" })
 });
 const MaximizeIcon = () => /* @__PURE__ */ jsxs("svg", {
@@ -1428,7 +2097,7 @@ const MaximizeIcon = () => /* @__PURE__ */ jsxs("svg", {
 	strokeWidth: "2",
 	strokeLinecap: "round",
 	strokeLinejoin: "round",
-	className: "w-4 h-4 text-gray-600 dark:text-slate-200",
+	className: "block w-4 h-4 text-gray-600 dark:text-slate-200",
 	children: [
 		/* @__PURE__ */ jsx("polyline", { points: "15 3 21 3 21 9" }),
 		/* @__PURE__ */ jsx("polyline", { points: "9 21 3 21 3 15" }),
@@ -1455,7 +2124,7 @@ const CloseIcon = () => /* @__PURE__ */ jsxs("svg", {
 	strokeWidth: "2",
 	strokeLinecap: "round",
 	strokeLinejoin: "round",
-	className: "w-5 h-5",
+	className: "block w-5 h-5",
 	children: [/* @__PURE__ */ jsx("path", { d: "M18 6 6 18" }), /* @__PURE__ */ jsx("path", { d: "m6 6 12 12" })]
 });
 const PlusIcon = () => /* @__PURE__ */ jsxs("svg", {
@@ -1467,7 +2136,7 @@ const PlusIcon = () => /* @__PURE__ */ jsxs("svg", {
 	strokeWidth: "2",
 	strokeLinecap: "round",
 	strokeLinejoin: "round",
-	className: "w-4 h-4",
+	className: "block w-4 h-4",
 	children: [/* @__PURE__ */ jsx("path", { d: "M5 12h14" }), /* @__PURE__ */ jsx("path", { d: "M12 5v14" })]
 });
 const MinusIcon = () => /* @__PURE__ */ jsx("svg", {
@@ -1479,7 +2148,7 @@ const MinusIcon = () => /* @__PURE__ */ jsx("svg", {
 	strokeWidth: "2",
 	strokeLinecap: "round",
 	strokeLinejoin: "round",
-	className: "w-4 h-4",
+	className: "block w-4 h-4",
 	children: /* @__PURE__ */ jsx("path", { d: "M5 12h14" })
 });
 const ResetIcon = () => /* @__PURE__ */ jsxs("svg", {
@@ -1491,7 +2160,7 @@ const ResetIcon = () => /* @__PURE__ */ jsxs("svg", {
 	strokeWidth: "2",
 	strokeLinecap: "round",
 	strokeLinejoin: "round",
-	className: "w-4 h-4",
+	className: "block w-4 h-4",
 	children: [/* @__PURE__ */ jsx("path", { d: "M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8" }), /* @__PURE__ */ jsx("path", { d: "M3 3v5h5" })]
 });
 const MIN_SCALE = .2;
@@ -1760,8 +2429,9 @@ const MermaidDiagramInner = ({ code }) => {
 					});
 				}
 			} catch (err) {
+				if (!mounted) return;
 				console.error("Mermaid render error:", err);
-				if (mounted) setFailure({
+				setFailure({
 					key,
 					message: extractErrorMessage(err)
 				});
@@ -2019,6 +2689,34 @@ function TagList({ items }) {
 		}, item))
 	});
 }
+/**
+* An `OQ-…` token, shaped as `VANTAGE_OQ_ID` shapes an id and bounded as the
+* planning scan bounds one: by what may not touch it, so an id inside a longer
+* token (`OQ-B12x`, `xOQ-B1`) is not a token at all. The leading bound is a
+* group rather than a lookbehind, which Safari parses only since 16.4.
+*/
+const OQ_TOKEN = /(^|[^A-Za-z0-9])(OQ-(?:[A-Z][A-Z0-9]{0,5})?[0-9]+)(?![A-Za-z0-9])/g;
+/** `text`, with each token in `ids` as a link to its question. */
+function LinkedIds({ text, ids }) {
+	const out = [];
+	let last = 0;
+	for (const match of text.matchAll(OQ_TOKEN)) {
+		const id = match[2];
+		if (id === void 0 || !ids.includes(id)) continue;
+		const start = match.index + match[1].length;
+		if (start > last) out.push(text.slice(last, start));
+		out.push(/* @__PURE__ */ jsx("a", {
+			href: `#${id}`,
+			children: id
+		}, start));
+		last = start + id.length;
+	}
+	if (last < text.length) out.push(text.slice(last));
+	return /* @__PURE__ */ jsx("span", {
+		className: "font-medium",
+		children: out
+	});
+}
 function ValueCell({ value }) {
 	if (isStringArray(value) && value.length > 0) return /* @__PURE__ */ jsx(TagList, { items: value });
 	if (isPlainObject(value)) return /* @__PURE__ */ jsx("pre", {
@@ -2040,7 +2738,7 @@ function flattenEntries(entries) {
 	}
 	return result;
 }
-const FrontmatterDisplayInner = ({ frontmatter }) => {
+const FrontmatterDisplayInner = ({ frontmatter, linkIds }) => {
 	const entries = flattenEntries(Object.entries(frontmatter));
 	const { statusChip } = readVantageFrontmatter(frontmatter);
 	if (entries.length === 0 && statusChip === void 0) return null;
@@ -2066,7 +2764,10 @@ const FrontmatterDisplayInner = ({ frontmatter }) => {
 						children: key
 					}), /* @__PURE__ */ jsx("td", {
 						className: "py-2 text-slate-800 dark:text-slate-200 align-top",
-						children: /* @__PURE__ */ jsx(ValueCell, { value })
+						children: key === "next" && linkIds !== void 0 && typeof value === "string" && !/[\r\n]/.test(value.trim()) && value === frontmatter["next"] ? /* @__PURE__ */ jsx(LinkedIds, {
+							text: value,
+							ids: linkIds
+						}) : /* @__PURE__ */ jsx(ValueCell, { value })
 					})]
 				}, key)) })
 			})
@@ -2342,17 +3043,16 @@ const MarkdownViewerInner = ({ content, currentPath = "", hash = "", baseUrl = "
 		imageApiBase
 	]);
 	const markdownComponents = useMemo(() => ({
-		a({ href, children, ...props }) {
-			const resolvedHref = resolveHref(href);
+		a({ node, href, children, ...props }) {
 			return /* @__PURE__ */ jsx("a", {
-				href: resolvedHref,
+				href: href === void 0 ? void 0 : resolveHref(href),
 				onClick: (e) => href && handleLinkClick(e, href),
 				...props,
 				children
 			});
 		},
 		code(props) {
-			const { children, className: codeClassName, ...rest } = props;
+			const { node, children, className: codeClassName, ...rest } = props;
 			const match = /language-(\w+)/.exec(codeClassName || "");
 			if (match && match[1] === "mermaid") return /* @__PURE__ */ jsx(MermaidDiagram, { code: String(children).replace(/\n$/, "") });
 			return /* @__PURE__ */ jsx("code", {
@@ -2396,61 +3096,8 @@ const MarkdownViewerInner = ({ content, currentPath = "", hash = "", baseUrl = "
 };
 const MarkdownViewer = memo(MarkdownViewerInner, (prevProps, nextProps) => prevProps.content === nextProps.content && prevProps.currentPath === nextProps.currentPath && prevProps.hash === nextProps.hash && prevProps.className === nextProps.className);
 //#endregion
-//#region src/renderMarkdown.ts
-/**
-* Render a markdown string to HTML using the full Vantage pipeline.
-*
-* Features (all enabled by default):
-* - GitHub Flavored Markdown (tables, strikethrough, task lists)
-* - KaTeX math rendering, inline and block ($$...$$ only; single $ is not a delimiter)
-* - Syntax highlighting via highlight.js
-* - `data-source-line` attributes for line anchors
-* - XSS sanitization
-* - Heading slugs/anchors
-* - YAML/TOML frontmatter parsing
-*
-* Mermaid diagrams are NOT rendered server-side (they require a browser).
-* Mermaid code blocks are preserved as `<pre><code class="language-mermaid">`.
-* Use the React `<MarkdownViewer>` component for client-side mermaid rendering.
-*/
-async function renderMarkdown(content, options = {}) {
-	const { gfm = true, math = true, highlight = true, sourceLines = true, sanitize = true, frontmatter: parseFm = true, tree } = options;
-	let parsed;
-	if (parseFm) parsed = parseFrontmatter(content);
-	else parsed = {
-		frontmatter: {},
-		body: content,
-		format: "none",
-		bodyLineOffset: 0
-	};
-	const { remarkPlugins, rehypePlugins } = buildPipeline({
-		gfm,
-		math,
-		highlight,
-		sourceLines,
-		sanitize,
-		bodyLineOffset: parsed.bodyLineOffset
-	});
-	const processor = unified().use(remarkParse).use(remarkPlugins).use(remarkRehype, { allowDangerousHtml: true }).use(rehypePlugins).use(rehypeStringify);
-	const result = tree === void 0 ? String(await processor.process(parsed.body)) : processor.stringify(await processor.run(tree, parsed.body), parsed.body);
-	return {
-		html: String(result),
-		frontmatter: parsed.frontmatter,
-		body: parsed.body
-	};
-}
-//#endregion
 //#region src/renderMermaidBlocks.ts
 /**
-* Client-side utility to find and render mermaid code blocks in a container.
-*
-* After calling `renderMarkdown()`, mermaid blocks come through as
-* `<pre><code class="language-mermaid">...</code></pre>`. This function
-* finds those blocks and replaces them with rendered SVG diagrams.
-*
-* Framework-agnostic — works in any browser environment.
-*/
-/**
 * Find all `<pre><code class="language-mermaid">` blocks in a container
 * and replace them with rendered SVG diagrams.
 *
@@ -2531,6 +3178,104 @@ function replaceWithSvg(preEl, svg, className) {
 	wrapper.innerHTML = svg;
 	preEl.replaceWith(wrapper);
 }
+/** The viewer's parser: the remark half of `buildPipeline`. */
+const fenceParser = unified().use(remarkParse).use(buildRemarkPlugins());
+/**
+* The code of every Mermaid fence in `markdown`, in source order, exactly as
+* a viewer's `MermaidDiagram` receives it: the fence's content, without its
+* container's indentation or its closing newline.
+*
+* A fence is a diagram when its info string's first word begins with the word
+* `mermaid`, which is the test the viewer applies to the `language-…` class
+* the fence renders with (`/language-(\w+)/`). Text that never says
+* `mermaid` is not parsed at all.
+*/
+function mermaidFences(markdown) {
+	if (!markdown.includes("mermaid")) return [];
+	const codes = [];
+	visit(fenceParser.parse(markdown), "code", (node) => {
+		if (/^\w+/.exec(node.lang ?? "")?.[0] === "mermaid") codes.push(node.value);
+	});
+	return codes;
+}
+/** Draws under way, by palette and code, so asking twice draws once. */
+const drawing = /* @__PURE__ */ new Map();
+let drawn = 0;
+/**
+* Draw one diagram into the SVG cache that `MermaidDiagram` reads when it
+* mounts, so a diagram rendered after this has settled is drawn at its full
+* size on its first paint instead of growing into place once Mermaid answers.
+* The planning page draws every diagram of the cards it is about to show this
+* way, before it commits them.
+*
+* Mermaid is loaded through `getMermaid`, so the drawing is configured, and
+* made safe, exactly as every other diagram of the page is. `theme` is the
+* palette key (`currentMermaidPalette`) to draw for; when the page has moved
+* to another palette by the time Mermaid is ready, nothing is cached, since
+* Mermaid now draws for the page's palette and not for `theme`.
+*
+* Resolves once the diagram is in the cache, at once when it already was, and
+* rejects when Mermaid cannot draw it.
+*/
+function prerenderMermaid(code, theme = currentMermaidPalette()) {
+	if (!code.trim() || hasCachedSvg(code, theme)) return Promise.resolve();
+	const key = `${theme}\u0000${code}`;
+	let pending = drawing.get(key);
+	if (pending === void 0) {
+		pending = (async () => {
+			const mermaid = await getMermaid();
+			if (currentMermaidPalette() !== theme) return;
+			const { svg } = await mermaid.render(`mermaid-ahead-${(++drawn).toString(36)}`, code);
+			setCachedSvg(code, svg, theme);
+		})().finally(() => drawing.delete(key));
+		drawing.set(key, pending);
+	}
+	return pending;
+}
+//#endregion
+//#region src/renderMarkdown.ts
+/**
+* Render a markdown string to HTML using the full Vantage pipeline.
+*
+* Features (all enabled by default):
+* - GitHub Flavored Markdown (tables, strikethrough, task lists)
+* - KaTeX math rendering, inline and block ($$...$$ only; single $ is not a delimiter)
+* - Syntax highlighting via highlight.js
+* - `data-source-line` attributes for line anchors
+* - XSS sanitization
+* - Heading slugs/anchors
+* - YAML/TOML frontmatter parsing
+*
+* Mermaid diagrams are NOT rendered server-side (they require a browser).
+* Mermaid code blocks are preserved as `<pre><code class="language-mermaid">`.
+* Use the React `<MarkdownViewer>` component for client-side mermaid rendering.
+*/
+async function renderMarkdown(content, options = {}) {
+	const { gfm = true, math = true, highlight = true, sourceLines = true, sanitize = true, frontmatter: parseFm = true, tree } = options;
+	let parsed;
+	if (parseFm) parsed = parseFrontmatter(content);
+	else parsed = {
+		frontmatter: {},
+		body: content,
+		format: "none",
+		bodyLineOffset: 0
+	};
+	const { remarkPlugins, rehypePlugins } = buildPipeline({
+		gfm,
+		math,
+		highlight,
+		sourceLines,
+		sanitize,
+		bodyLineOffset: parsed.bodyLineOffset
+	});
+	const processor = unified().use(remarkParse).use(remarkPlugins).use(remarkRehype, { allowDangerousHtml: true }).use(rehypePlugins).use(rehypeStringify);
+	const result = tree === void 0 ? String(await processor.process(parsed.body)) : processor.stringify(await processor.run(tree, parsed.body), parsed.body);
+	return {
+		html: String(result),
+		frontmatter: parsed.frontmatter,
+		body: parsed.body
+	};
+}
 //#endregion
 //#region src/resolveLinks.ts
 /**
@@ -2576,6 +3321,6 @@ function resolveLinks(html, options = {}) {
 	});
 }
 //#endregion
-export { DOC_STATUSES, DOC_STATUS_TONES, DocumentStatusChip, FrontmatterDisplay, MarkdownViewer, MermaidDiagram, VANTAGE_FRONTMATTER_KEYS, buildPipeline, buildRemarkPlugins, clearLineAnchorHighlights, isDocStatus, parseFrontmatter, parseLineAnchor, readVantageFrontmatter, rehypeSourceLines, renderMarkdown, renderMermaidBlocks, resolveLinks, sanitizeSchema, scrollToLineAnchor, useLineAnchor };
+export { DOC_STATUSES, DOC_STATUS_TONES, DocumentStatusChip, FrontmatterDisplay, MarkdownViewer, MermaidDiagram, VANTAGE_FRONTMATTER_KEYS, buildPipeline, buildRemarkPlugins, clearLineAnchorHighlights, isDocStatus, mermaidFences, parseFrontmatter, parseLineAnchor, prerenderMermaid, readVantageFrontmatter, rehypeSourceLines, renderMarkdown, renderMermaidBlocks, resolveLinks, sanitizeSchema, scrollToLineAnchor, useLineAnchor };
 
 //# sourceMappingURL=react.js.map