vantage-md 0.5.5 → 0.5.7

package/dist/index.js

@@ -1,1025 +1,1582 @@
-import { unified } from 'unified';
-import remarkParse from 'remark-parse';
-import remarkRehype from 'remark-rehype';
-import rehypeStringify from 'rehype-stringify';
-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 YAML from 'yaml';
-import { parse } from 'smol-toml';
-
-// src/renderMarkdown.ts
-
-// src/rehypeSourceLines.ts
-var BLOCK_TAGS = /* @__PURE__ */ new Set([
-  "p",
-  "h1",
-  "h2",
-  "h3",
-  "h4",
-  "h5",
-  "h6",
-  "li",
-  "blockquote",
-  "pre",
-  "table",
-  "tr",
-  "ul",
-  "ol",
-  "hr",
-  "div"
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import rehypeStringify from "rehype-stringify";
+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 YAML from "yaml";
+import { parse } from "smol-toml";
+//#region src/rehypeSourceLines.ts
+const BLOCK_TAGS = /* @__PURE__ */ new Set([
+	"p",
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"h5",
+	"h6",
+	"li",
+	"blockquote",
+	"pre",
+	"table",
+	"tr",
+	"ul",
+	"ol",
+	"hr",
+	"div"
 ]);
-function visit(node, offset) {
-  if ("children" in node) {
-    for (const child of node.children) {
-      if (child.type === "element") {
-        if (BLOCK_TAGS.has(child.tagName) && child.position?.start?.line) {
-          child.properties = child.properties || {};
-          child.properties["dataSourceLine"] = child.position.start.line + offset;
-        }
-        visit(child, offset);
-      }
-    }
-  }
+function visit$1(node, offset) {
+	if ("children" in node) {
+		for (const child of node.children) if (child.type === "element") {
+			if (BLOCK_TAGS.has(child.tagName) && child.position?.start?.line) {
+				child.properties = child.properties || {};
+				child.properties["dataSourceLine"] = child.position.start.line + offset;
+			}
+			visit$1(child, offset);
+		}
+	}
 }
-var rehypeSourceLines = (options) => {
-  const offset = options?.offset ?? 0;
-  return (tree) => {
-    visit(tree, offset);
-  };
+const rehypeSourceLines = (options) => {
+	const offset = options?.offset ?? 0;
+	return (tree) => {
+		visit$1(tree, offset);
+	};
 };
-var rehypeSourceLines_default = rehypeSourceLines;
-
-// src/vantageDirectives.ts
-var VANTAGE_SENTINEL = "vantage:";
-var DIRECTIVE_NAMES = ["section", "block", "oq"];
-var VANTAGE_TONES = [
-  "note",
-  "tip",
-  "important",
-  "warning",
-  "caution",
-  "muted"
+//#endregion
+//#region src/rehypeVantageAlerts.ts
+/**
+* GFM alerts — `> [!WARNING]` — compiled into `data-vantage-alert`.
+*
+* `remark-gfm` does not implement alerts, so until this plugin existed a
+* `> [!WARNING]` rendered as an ordinary blockquote with the literal marker
+* visible as its first words. Worse than merely unstyled: `@tailwindcss/typography`
+* italicises blockquotes and draws `open-quote`/`close-quote` around the first
+* paragraph, so a callout came out as an italic *quotation* whose opening words
+* were `"[!WARNING]`. That was the "Known gaps" entry in
+* `docs/reference/inline-markup.md` and OQ-10, filed rather than fixed, while
+* `styleGuide.ts` went on telling every agent to write them.
+*
+* The tokens are deliberately the ones the `tone` vocabulary already resolves —
+* an alert *is* the six-colour light/dark treatment `tone` shipped, which is
+* exactly what the gap entry said whoever fixed this should do rather than
+* building a second palette. `[!WARNING]` and `<!-- vantage: block tone=warning -->`
+* therefore agree by construction, and adding a theme still touches one
+* custom-property block.
+*
+* **This runs in the shared pipeline, so all four renderers get it** — the live
+* viewer, the package's exported viewer, the static export and the CLI checker's
+* `renderMarkdown`. That is what makes an injected title element acceptable here
+* where the collapse caret's glyph had to be drawn in CSS: the caret is injected
+* by app JS that may never run, and this is not (D5).
+*
+* ## What it does not do
+*
+* It does not touch a blockquote that carries no marker, and an unrecognised
+* marker (`[!HINT]`) is left exactly as it was — visible literal text, which is
+* the honest rendering of something GitHub also would not style. Silently
+* swallowing it would hide a typo that reads as a callout on neither renderer.
+*/
+/**
+* The five GFM alert kinds, lowercased.
+*
+* Deliberately *not* re-derived from `VANTAGE_TONES`: that list carries a sixth
+* token, `muted`, which is ours and is not an alert word. The overlap is the
+* point — the five that coincide share a palette — but the two vocabularies are
+* closed by different authorities and a change to one must not silently move the
+* other. A test asserts the five are a subset of the tones.
+*/
+const VANTAGE_ALERTS = [
+	"note",
+	"tip",
+	"important",
+	"warning",
+	"caution"
+];
+/** The visible label per kind. Title case, as GitHub renders it. */
+const ALERT_TITLES = {
+	note: "Note",
+	tip: "Tip",
+	important: "Important",
+	warning: "Warning",
+	caution: "Caution"
+};
+/**
+* The marker, anchored and requiring the rest of its line to be empty.
+*
+* GFM puts the marker alone on the blockquote's first line, and holding to that
+* is what keeps a paragraph that merely *begins* with bracketed text from being
+* eaten. The trailing newline is optional only for the degenerate blockquote
+* whose entire content is the marker.
+*
+* Measured against the real chain rather than assumed: `remark-parse` reads
+* `[!TIP]` as a shortcut link reference, and because no definition matches,
+* `mdast-util-to-hast` puts it back as **one** leading text node —
+* `"[!TIP]\nThe generalization: "` — not as a `[`/label/`]` triple. So a single
+* 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|$)/;
+/** 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() !== "");
+	return child?.type === "element" ? child : void 0;
+}
+/**
+* Compile `> [!KIND]` blockquotes into `data-vantage-alert="kind"`.
+*
+* Order in the chain matters twice, and both are stated in `pipeline.ts`:
+*
+* - **after `rehypeSourceLines`**, so the injected title carries no
+*   `data-source-line`. That is what keeps it out of `anchorBlockWithin`, which
+*   filters candidates to those with a finite line — otherwise a review comment
+*   on an alert would anchor to the word "Warning" instead of to the prose.
+* - **before `rehypeSanitize`**, so nothing reaches the DOM the schema has not
+*   passed. `dataVantageAlert` is allowlisted there by name *and* value, like
+*   every other `data-vantage-*` attribute.
+*/
+function rehypeVantageAlerts() {
+	return (tree) => {
+		visit(tree, "element", (node) => {
+			if (node.tagName !== "blockquote") return;
+			const paragraph = firstElement(node);
+			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);
+			if (match === null) return;
+			const kind = match[1].toLowerCase();
+			lead.value = lead.value.slice(match[0].length);
+			if (lead.value === "" && paragraph.children.length === 1) node.children = node.children.filter((c) => c !== paragraph);
+			node.properties = {
+				...node.properties,
+				dataVantageAlert: kind
+			};
+			node.children.unshift({
+				type: "element",
+				tagName: "div",
+				properties: { className: ["vantage-alert-title"] },
+				children: [{
+					type: "text",
+					value: ALERT_TITLES[kind]
+				}]
+			});
+		});
+	};
+}
+//#endregion
+//#region src/vantageDirectives.ts
+/**
+* The directive grammar and the closed vocabulary — one parser, no renderer.
+*
+* A Vantage directive is an ordinary HTML comment carrying a `vantage:`
+* sentinel: `<!-- vantage: section tone=warning -->`. GitHub drops it, every
+* other Markdown renderer drops it, and Vantage compiles it into
+* `data-vantage-*` attributes on the block that follows
+* (`rehypeVantageDirectives`). See `docs/reference/inline-markup.md`, "The carrier and the grammar".
+*
+* This module is deliberately **zero-dependency — not even a type import**, and
+* it knows nothing about hast. Two callers need it and only one of them has a
+* tree: the rehype plugin stamps attributes, and the `vantage-check` CLI
+* validates directives with no rendering at all, importing this file by
+* relative path. A checker with its own copy of the grammar is a checker that
+* disagrees with the renderer, which is the failure D5 names.
+*
+* Everything here is a pure function of a string. Nothing throws, nothing logs
+* (P3): a comment that is not a directive is `null`, and a comment that carries
+* the sentinel but does not parse is `malformed` with a reason only the checker
+* reads.
+*/
+/**
+* The mandatory sentinel — the full word, never a terser `v:`.
+*
+* It is what keeps an ordinary `<!-- TODO: rewrite this -->` from being parsed
+* as markup, and it makes the common case a prefix test rather than a grammar
+* attempt (Ledger OQ-1).
+*/
+const VANTAGE_SENTINEL = "vantage:";
+/**
+* The closed name set. An unknown name drops the **whole** directive: there is
+* no target semantics without a name. An unknown key or value drops only that
+* pair (D2 is per-key).
+*
+* Position picks the target; the name picks the extent. `section` before a
+* heading reaches the heading's whole section, `block` reaches one block, and
+* `oq` marks one answerable question. The name cannot disagree with position —
+* it only says how far the stamp reaches — so §4.2's refusal of a `scope=` key
+* stands.
+*/
+const DIRECTIVE_NAMES = [
+	"section",
+	"block",
+	"oq"
+];
+/**
+* The `tone` vocabulary: GitHub's alert words plus `muted`.
+*
+* Semantic, never chromatic (P2, Ledger OQ-3). A document says what a section
+* *is*; the theme decides what that looks like, which is what lets one document
+* render correctly in light, in dark, and in themes that do not exist yet.
+*/
+const VANTAGE_TONES = [
+	"note",
+	"tip",
+	"important",
+	"warning",
+	"caution",
+	"muted"
+];
+/** How much the block should pull the eye — separate from `tone` on purpose. */
+const VANTAGE_EMPHASIS = [
+	"strong",
+	"normal",
+	"quiet"
 ];
-var VANTAGE_EMPHASIS = ["strong", "normal", "quiet"];
-var VANTAGE_BADGES = [
-  "draft",
-  "stale",
-  "blocked",
-  "done",
-  "wip"
+/** A small chip beside the heading. */
+const VANTAGE_BADGES = [
+	"draft",
+	"stale",
+	"blocked",
+	"done",
+	"wip"
 ];
-var VANTAGE_COLLAPSED = ["true", "false"];
-var VANTAGE_RUNS = ["start", "middle", "end", "only"];
-var VANTAGE_STYLE_TARGETS = [
-  "p",
-  "h1",
-  "h2",
-  "h3",
-  "h4",
-  "h5",
-  "h6",
-  "li",
-  "blockquote",
-  "pre",
-  "table",
-  "tr",
-  "ul",
-  "ol",
-  "hr",
-  "div"
+/**
+* `collapsed` is a token, not a flag: `false` is the default written down.
+*
+* It stamps nothing on its own. Its one real effect is overriding a
+* `collapsed=true` earlier in the same merged directive run — last key wins — so
+* it is in the vocabulary rather than being an unknown value that drops. It
+* cannot cancel an *enclosing* collapsed section: a nested heading is a hidden
+* member of the outer group by design (A3), and the outer run is stamped before
+* any inner directive has been resolved.
+*/
+const VANTAGE_COLLAPSED = ["true", "false"];
+/**
+* Where a block sits in a stamped run, so section-wide CSS can join its members
+* without an adjacent-sibling combinator.
+*
+* Not cosmetic. Review mode inserts comment cards as siblings *inside* a
+* stamped run (`useReviewHighlights`), so `[tone] + [tone]` severs at every
+* commented paragraph and bleeds across the boundary between two adjacent runs
+* of different tone. An attribute survives both.
+*/
+const VANTAGE_RUNS = [
+	"start",
+	"middle",
+	"end",
+	"only"
 ];
-var VANTAGE_ANCHOR_TARGETS = [
-  "p",
-  "h1",
-  "h2",
-  "h3",
-  "h4",
-  "h5",
-  "h6",
-  "li",
-  "blockquote",
-  "pre",
-  "table"
+/**
+* The tags a `section`/`block` directive may stamp.
+*
+* Deliberately `rehypeSourceLines`'s `BLOCK_TAGS`: a stamped block should also
+* be a block with a `data-source-line`, so the styling surface and the anchor
+* surface coincide. It also keeps an inline directive from stamping the `<em>`
+* that happens to follow it inside a paragraph.
+*
+* It lives here rather than in the plugin because the CLI checker has to answer
+* "will this directive stamp anything?" from an mdast tree with no hast in
+* sight. A checker with its own copy of this list is a checker that calls a
+* working directive an orphan, or stays silent about a dead one (D5).
+*/
+const VANTAGE_STYLE_TARGETS = [
+	"p",
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"h5",
+	"h6",
+	"li",
+	"blockquote",
+	"pre",
+	"table",
+	"tr",
+	"ul",
+	"ol",
+	"hr",
+	"div"
 ];
-var VANTAGE_OQ_HOST_TARGETS = VANTAGE_ANCHOR_TARGETS.filter(
-  (tag) => tag !== "pre" && tag !== "table"
-);
-var STYLE_KEYS = {
-  tone: VANTAGE_TONES,
-  emphasis: VANTAGE_EMPHASIS,
-  badge: VANTAGE_BADGES,
-  collapsed: VANTAGE_COLLAPSED
+/**
+* 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 gap between this list and `VANTAGE_STYLE_TARGETS` is why an `oq`
+* directive at column 0 above a list silently does nothing: the target is the
+* `<ul>`, not the `<li>`. The checker says so.
+*/
+const VANTAGE_ANCHOR_TARGETS = [
+	"p",
+	"h1",
+	"h2",
+	"h3",
+	"h4",
+	"h5",
+	"h6",
+	"li",
+	"blockquote",
+	"pre",
+	"table"
+];
+/**
+* The tags a `<!-- vantage: oq … -->` directive actually yields a *button* on —
+* `VANTAGE_ANCHOR_TARGETS` minus `pre` and `table`, written as an explicit
+* subtraction so the narrowing stays visible.
+*
+* Anchorable and button-hosting are different questions, and this is the second
+* one. A comment *can* be anchored on a `<pre>` or a `<table>` — both are in
+* `ANCHOR_TAGS` — but neither can hold the affordance: inside a `<pre>` the
+* button renders as part of the code, and a `<button>` child of `<table>` is not
+* valid HTML at all, so the parser hoists it out.
+*
+* Both consumers read it from here: `OQ_HOST_TAGS` in the app's
+* `useOpenQuestionButtons`, and the `oq` branch of the checker's
+* `vantage/orphan`. They were two hand-written lists that disagreed — the
+* checker called an `oq` above a fence fine while the app rendered no button
+* and said nothing, which is the D5 break this module exists to prevent.
+*/
+const VANTAGE_OQ_HOST_TARGETS = VANTAGE_ANCHOR_TARGETS.filter((tag) => tag !== "pre" && tag !== "table");
+const STYLE_KEYS = {
+	tone: VANTAGE_TONES,
+	emphasis: VANTAGE_EMPHASIS,
+	badge: VANTAGE_BADGES,
+	collapsed: VANTAGE_COLLAPSED
 };
-var DIRECTIVE_VOCABULARY = {
-  section: STYLE_KEYS,
-  block: STYLE_KEYS,
-  oq: { id: null, leaning: null }
+/**
+* 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.
+*/
+const DIRECTIVE_VOCABULARY = {
+	section: STYLE_KEYS,
+	block: STYLE_KEYS,
+	oq: {
+		id: null,
+		leaning: null
+	}
 };
-var WS = /[ \t\r\n]*/y;
-var SENTINEL_PREFIX = /^[ \t\r\n]*vantage:/;
-var NAME = /[a-z][a-z0-9-]*/y;
-var UNQUOTED = /[A-Za-z0-9_.:#-]+/y;
-var QUOTED = /"[^"]*"/y;
+/**
+* `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.
+*/
+const WS = /[ \t\r\n]*/y;
+const SENTINEL_PREFIX = /^[ \t\r\n]*vantage:/;
+const NAME = /[a-z][a-z0-9-]*/y;
+const UNQUOTED = /[A-Za-z0-9_.:#-]+/y;
+/**
+* A quoted value holds anything but a `"`, `--` included: measured through the
+* real chain, `leaning="a--b"` reaches the tree intact, because HTML5 closes a
+* comment on `-->` or `--!>` and on nothing else. There is deliberately **no**
+* `--` restriction here. What a quoted value cannot hold is a terminator: a
+* `-->` inside one ends the comment early and spills the tail into the document
+* as literal text, which is a finding for the checker rather than a rule here —
+* by the time this function runs, the truncation has already happened.
+*/
+const QUOTED = /"[^"]*"/y;
+/**
+* The cheap prefix test. Runs first on every comment in every document, so an
+* ordinary editorial comment never reaches the tokenizer.
+*
+* Note `<!--- vantage: x -->` is *not* a directive: its inner text begins with
+* the extra `-`, and the sentinel must be the first thing in the comment.
+*/
 function hasVantageSentinel(comment) {
-  return SENTINEL_PREFIX.test(comment);
+	return SENTINEL_PREFIX.test(comment);
 }
+/** The whole non-whitespace run at `offset`, capped, for a quotable message. */
 function token(comment, offset) {
-  const rest = comment.slice(offset);
-  const end = rest.search(/[ \t\r\n]/);
-  const word = end === -1 ? rest : rest.slice(0, end);
-  return word.length > 24 ? `${word.slice(0, 24)}\u2026` : word;
+	const rest = comment.slice(offset);
+	const end = rest.search(/[ \t\r\n]/);
+	const word = end === -1 ? rest : rest.slice(0, end);
+	return word.length > 24 ? `${word.slice(0, 24)}…` : word;
 }
+/** The sticky match at `offset`, or `null` if the pattern does not apply. */
 function matchAt(pattern, comment, offset) {
-  pattern.lastIndex = offset;
-  const match = pattern.exec(comment);
-  return match === null ? null : match[0];
+	pattern.lastIndex = offset;
+	const match = pattern.exec(comment);
+	return match === null ? null : match[0];
 }
+/** How much whitespace sits at `offset`. `WS` matches everywhere, empty. */
 function skipWhitespace(comment, offset) {
-  return matchAt(WS, comment, offset)?.length ?? 0;
+	return matchAt(WS, comment, offset)?.length ?? 0;
 }
 function malformed(reason, offset) {
-  return { kind: "malformed", reason, offset };
+	return {
+		kind: "malformed",
+		reason,
+		offset
+	};
 }
+/**
+* Parse one comment's **inner** text — the value of a hast `comment` node, with
+* `<!--` and `-->` already stripped. `null` means "no sentinel, not ours".
+*
+* Hand-rolled rather than one regular expression, because a repeated capture
+* group keeps only its last match and the checker needs an offset per token to
+* point at the character that broke.
+*/
 function parseVantageDirective(comment) {
-  const sentinel = SENTINEL_PREFIX.exec(comment);
-  if (sentinel === null) return null;
-  let at = sentinel[0].length;
-  at += skipWhitespace(comment, at);
-  const nameOffset = at;
-  const name = matchAt(NAME, comment, at);
-  if (name === null) {
-    return malformed("no directive name after `vantage:`", at);
-  }
-  at += name.length;
-  const pairs = [];
-  while (at < comment.length) {
-    const gap = skipWhitespace(comment, at);
-    at += gap;
-    if (at >= comment.length) break;
-    if (gap === 0) {
-      return malformed(`\`${token(comment, at)}\` needs a space before it`, at);
-    }
-    const keyOffset = at;
-    const key = matchAt(NAME, comment, at);
-    if (key === null) {
-      return malformed(
-        `\`${token(comment, at)}\` is not a \`key=value\` pair`,
-        at
-      );
-    }
-    at += key.length;
-    if (comment[at] !== "=") {
-      return malformed(`\`${key}\` is not followed by \`=value\``, at);
-    }
-    at += 1;
-    const valueOffset = at;
-    const quoted = matchAt(QUOTED, comment, at);
-    if (quoted !== null) {
-      at += quoted.length;
-      pairs.push({
-        key,
-        value: quoted.slice(1, -1),
-        keyOffset,
-        valueOffset,
-        quoted: true
-      });
-      continue;
-    }
-    const unquoted = matchAt(UNQUOTED, comment, at);
-    if (unquoted === null) {
-      const found = token(comment, at);
-      return malformed(
-        found === "" ? `\`${key}=\` has no value` : `\`${found}\` is not a valid value for \`${key}\``,
-        at
-      );
-    }
-    at += unquoted.length;
-    pairs.push({ key, value: unquoted, keyOffset, valueOffset, quoted: false });
-  }
-  return { kind: "directive", name, nameOffset, pairs };
+	const sentinel = SENTINEL_PREFIX.exec(comment);
+	if (sentinel === null) return null;
+	let at = sentinel[0].length;
+	at += skipWhitespace(comment, at);
+	const nameOffset = at;
+	const name = matchAt(NAME, comment, at);
+	if (name === null) return malformed("no directive name after `vantage:`", at);
+	at += name.length;
+	const pairs = [];
+	while (at < comment.length) {
+		const gap = skipWhitespace(comment, at);
+		at += gap;
+		if (at >= comment.length) break;
+		if (gap === 0) return malformed(`\`${token(comment, at)}\` needs a space before it`, at);
+		const keyOffset = at;
+		const key = matchAt(NAME, comment, at);
+		if (key === null) return malformed(`\`${token(comment, at)}\` is not a \`key=value\` pair`, at);
+		at += key.length;
+		if (comment[at] !== "=") return malformed(`\`${key}\` is not followed by \`=value\``, at);
+		at += 1;
+		const valueOffset = at;
+		const quoted = matchAt(QUOTED, comment, at);
+		if (quoted !== null) {
+			at += quoted.length;
+			pairs.push({
+				key,
+				value: quoted.slice(1, -1),
+				keyOffset,
+				valueOffset,
+				quoted: true
+			});
+			continue;
+		}
+		const unquoted = matchAt(UNQUOTED, comment, at);
+		if (unquoted === null) {
+			const found = token(comment, at);
+			return malformed(found === "" ? `\`${key}=\` has no value` : `\`${found}\` is not a valid value for \`${key}\``, at);
+		}
+		at += unquoted.length;
+		pairs.push({
+			key,
+			value: unquoted,
+			keyOffset,
+			valueOffset,
+			quoted: false
+		});
+	}
+	return {
+		kind: "directive",
+		name,
+		nameOffset,
+		pairs
+	};
 }
-
-// src/rehypeVantageDirectives.ts
-var STYLE_TARGET_TAGS = new Set(VANTAGE_STYLE_TARGETS);
-var ANCHOR_TARGET_TAGS = new Set(VANTAGE_ANCHOR_TARGETS);
-var HEADING_DEPTHS = /* @__PURE__ */ new Map([
-  ["h1", 1],
-  ["h2", 2],
-  ["h3", 3],
-  ["h4", 4],
-  ["h5", 5],
-  ["h6", 6]
-]);
-var RANGE_PROPERTIES = /* @__PURE__ */ new Map([
-  ["tone", "dataVantageTone"],
-  ["emphasis", "dataVantageEmphasis"]
+//#endregion
+//#region src/rehypeVantageDirectives.ts
+/**
+* What a `section`/`block` and an `oq` directive may stamp.
+*
+* 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
+* the same answer (D5).
+*/
+const STYLE_TARGET_TAGS = new Set(VANTAGE_STYLE_TARGETS);
+const ANCHOR_TARGET_TAGS = new Set(VANTAGE_ANCHOR_TARGETS);
+const HEADING_DEPTHS = /* @__PURE__ */ new Map([
+	["h1", 1],
+	["h2", 2],
+	["h3", 3],
+	["h4", 4],
+	["h5", 5],
+	["h6", 6]
 ]);
-var POINT_PROPERTIES = /* @__PURE__ */ new Map([["badge", "dataVantageBadge"]]);
-var RUN_PROPERTY = "dataVantageRun";
-var OQ_PROPERTY = "dataVantageOq";
-var LEANING_PROPERTY = "dataVantageLeaning";
-var COLLAPSED_PROPERTY = "dataVantageCollapsed";
-var COLLAPSE_GROUP_PROPERTY = "dataVantageCollapseGroup";
-var COLLAPSE_TOGGLE_PROPERTY = "dataVantageCollapseToggle";
-var MAX_LEANING = 500;
+/**
+* Key → hast property, for the keys that treat a whole run.
+*
+* A camelCase hast property serialises to the kebab-case attribute, so
+* `dataVantageTone` is `data-vantage-tone` in every renderer.
+*
+* `tone` and `emphasis` describe what a section *is* and how loud it is, so
+* every block in the range wears them: the tone rule is a slice of one
+* continuous line down the section, and the weight applies to all of its prose.
+*
+* `collapsed` is not here because it is not one property on one block: it puts a
+* toggle on the heading and a collapsed flag plus a group id on every block the
+* heading hides, which `stampStyle` does with the three properties below.
+*/
+const RANGE_PROPERTIES = /* @__PURE__ */ new Map([["tone", "dataVantageTone"], ["emphasis", "dataVantageEmphasis"]]);
+/**
+* Key → hast property, for the keys that mark one block: the directive's target.
+*
+* `badge` is the asymmetry in the vocabulary and the reason this second map
+* exists. It is not a treatment of a run but a single chip — "a small chip after
+* the heading text" (§4.3), drawn as `[data-vantage-badge]::after` — so a
+* section-wide stamp paints the word once per paragraph, list, table and fence
+* under the heading instead of once beside it.
+*
+* The chip is fixed here rather than in the stylesheet, because narrowing the
+* CSS to `:is(h1, …, h6)` would silently draw nothing for the two placements
+* that legitimately badge a non-heading — `block badge=…` on a paragraph, and a
+* `section` that degraded onto one (A1) — and would leave an attribute stamped
+* on every block that says something untrue about it.
+*/
+const POINT_PROPERTIES = /* @__PURE__ */ new Map([["badge", "dataVantageBadge"]]);
+const RUN_PROPERTY = "dataVantageRun";
+const OQ_PROPERTY = "dataVantageOq";
+const LEANING_PROPERTY = "dataVantageLeaning";
+/**
+* The three properties `collapsed=true` stamps across a section.
+*
+* The heading takes a *different* attribute from the blocks it hides, and that
+* asymmetry is the whole design (A3): a nested `###` inside a collapsed `##` is
+* both a hidden member of the outer group and the toggle for its own, so one
+* shared attribute would make it permanently invisible and unreachable by
+* either toggle. There is no `<details>` and no wrapper — the run stays a flat
+* list of siblings, which is what keeps review comment cards, the typography
+* plugin's `h2 + *` margin resets and the anchor surface working.
+*
+* Hiding is CSS, and that CSS is gated on two markers the toggle JS sets — the
+* prose container's readiness, and an armed marker on each block whose group it
+* gave a caret (`docs/reference/inline-markup.md`, "Collapse without a wrapper"). A renderer without the JS
+* — the CLI checker's HTML, an external consumer of this package — shows every
+* block, and so does any block that ended up with no control.
+*/
+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.
+*
+* A whitespace-only `text` node always does — measured, with or without a blank
+* line in the source. Comments do too, and an unrelated `<!-- TODO -->` must not
+* break the chain: it is invisible in every renderer and deleted by the
+* sanitiser, so letting it change a directive's meaning would make behaviour
+* depend on something no reader can see.
+*/
 function isSkippable(node) {
-  if (node.type === "comment" || node.type === "doctype") return true;
-  if (node.type === "text") return node.value.trim() === "";
-  return false;
+	if (node.type === "comment" || node.type === "doctype") return true;
+	if (node.type === "text") return node.value.trim() === "";
+	return false;
 }
 function headingDepth(node) {
-  if (node.type !== "element") return void 0;
-  return HEADING_DEPTHS.get(node.tagName);
+	if (node.type !== "element") return void 0;
+	return HEADING_DEPTHS.get(node.tagName);
 }
 function setProperty(element, property, value) {
-  element.properties = element.properties ?? {};
-  element.properties[property] = value;
+	element.properties = element.properties ?? {};
+	element.properties[property] = value;
 }
+/**
+* Where a member sits in a stamped run: `only` for a lone block, otherwise
+* `start`, `middle`, `end`. See `VANTAGE_RUNS`.
+*/
 function runValue(index, length) {
-  if (length === 1) return "only";
-  if (index === 0) return "start";
-  return index === length - 1 ? "end" : "middle";
+	if (length === 1) return "only";
+	if (index === 0) return "start";
+	return index === length - 1 ? "end" : "middle";
 }
+/** The closed value set for one key, or `undefined` when the key is unknown. */
 function vocabularyOf(name, key) {
-  return DIRECTIVE_VOCABULARY[name]?.[key];
+	return DIRECTIVE_VOCABULARY[name]?.[key];
 }
 function accepts(name, key, value) {
-  const values = vocabularyOf(name, key);
-  if (values === void 0) return false;
-  return values === null || values.includes(value);
+	const values = vocabularyOf(name, key);
+	if (values === void 0) return false;
+	return values === null || values.includes(value);
 }
+/**
+* The nodes one style directive reaches, as indexes into its own parent's
+* children — never outside that array, so a directive inside a blockquote or a
+* list item cannot stamp past it.
+*
+* Position picks the target (the next sibling element); the name picks how far
+* the stamp goes. `section` before a heading takes the heading and every
+* following sibling until the first heading of the same or shallower depth;
+* `section` before anything else degrades to that one block, and `block` is
+* always that one block. A heading nested inside a stamped `blockquote` or
+* `li` does not end the section: the walk never descends.
+*/
 function styleRange(children, targetIndex, name) {
-  const range = [targetIndex];
-  const depth = name === "section" ? headingDepth(children[targetIndex]) : void 0;
-  if (depth === void 0) return range;
-  for (let i = targetIndex + 1; i < children.length; i++) {
-    const node = children[i];
-    const nodeDepth = headingDepth(node);
-    if (nodeDepth !== void 0 && nodeDepth <= depth) break;
-    if (node.type === "element" && STYLE_TARGET_TAGS.has(node.tagName)) {
-      range.push(i);
-    }
-  }
-  return range;
+	const range = [targetIndex];
+	const depth = name === "section" ? headingDepth(children[targetIndex]) : void 0;
+	if (depth === void 0) return range;
+	for (let i = targetIndex + 1; i < children.length; i++) {
+		const node = children[i];
+		const nodeDepth = headingDepth(node);
+		if (nodeDepth !== void 0 && nodeDepth <= depth) break;
+		if (node.type === "element" && STYLE_TARGET_TAGS.has(node.tagName)) range.push(i);
+	}
+	return range;
 }
+/**
+* Whether this directive collapses its section — three ways to say no.
+*
+* `collapsed=false` stamps nothing: it is the default written down, and "not
+* collapsed" is not a thing an attribute can usefully say. Its only effect is
+* upstream of here — `stampRun` merges a run of comments last-key-wins, so a
+* `false` cancels a `true` in the *same* run. It does not cancel an *enclosing*
+* section: `styleRange` walks the outer heading's whole sibling span before any
+* inner directive is resolved, and a nested heading being a hidden member of the
+* outer group is the design (A3), not an oversight.
+*
+* A `block` scope is **dropped**, and so is a `section` that degraded onto
+* a non-heading, because both would hide a lone paragraph with nothing left
+* behind to reveal it — content that is simply gone, which is the P1/D8 failure
+* the readiness gate exists to prevent. Only a heading can be a summary.
+*/
 function collapsesSection(name, pairs, target) {
-  if (name !== "section") return false;
-  if (pairs.get("collapsed") !== "true") return false;
-  return headingDepth(target) !== void 0;
+	if (name !== "section") return false;
+	if (pairs.get("collapsed") !== "true") return false;
+	return headingDepth(target) !== void 0;
 }
 function stampStyle(children, targetIndex, name, pairs, state) {
-  const target = children[targetIndex];
-  if (!STYLE_TARGET_TAGS.has(target.tagName)) return;
-  const rangeStamps = [];
-  const targetStamps = [];
-  for (const [key, value] of pairs) {
-    if (!accepts(name, key, value)) continue;
-    const rangeProperty = RANGE_PROPERTIES.get(key);
-    if (rangeProperty !== void 0) {
-      rangeStamps.push([rangeProperty, value]);
-      continue;
-    }
-    const pointProperty = POINT_PROPERTIES.get(key);
-    if (pointProperty !== void 0) targetStamps.push([pointProperty, value]);
-  }
-  const collapses = collapsesSection(name, pairs, target);
-  if (rangeStamps.length === 0 && targetStamps.length === 0 && !collapses) {
-    return;
-  }
-  const range = styleRange(children, targetIndex, name);
-  const group = collapses && range.length > 1 ? String(state.nextGroup++) : void 0;
-  for (let i = 0; i < range.length; i++) {
-    const element = children[range[i]];
-    for (const [property, value] of rangeStamps) {
-      setProperty(element, property, value);
-    }
-    if (i === 0) {
-      for (const [property, value] of targetStamps) {
-        setProperty(element, property, value);
-      }
-    }
-    if (rangeStamps.length > 0) {
-      setProperty(element, RUN_PROPERTY, runValue(i, range.length));
-    }
-    if (group === void 0) continue;
-    if (i === 0) {
-      setProperty(element, COLLAPSE_TOGGLE_PROPERTY, group);
-    } else {
-      setProperty(element, COLLAPSED_PROPERTY, "true");
-      setProperty(element, COLLAPSE_GROUP_PROPERTY, group);
-    }
-  }
+	const target = children[targetIndex];
+	if (!STYLE_TARGET_TAGS.has(target.tagName)) return;
+	const rangeStamps = [];
+	const targetStamps = [];
+	for (const [key, value] of pairs) {
+		if (!accepts(name, key, value)) continue;
+		const rangeProperty = RANGE_PROPERTIES.get(key);
+		if (rangeProperty !== void 0) {
+			rangeStamps.push([rangeProperty, value]);
+			continue;
+		}
+		const pointProperty = POINT_PROPERTIES.get(key);
+		if (pointProperty !== void 0) targetStamps.push([pointProperty, value]);
+	}
+	const collapses = collapsesSection(name, pairs, target);
+	if (rangeStamps.length === 0 && targetStamps.length === 0 && !collapses) return;
+	const range = styleRange(children, targetIndex, name);
+	const group = collapses && range.length > 1 ? String(state.nextGroup++) : void 0;
+	for (let i = 0; i < range.length; i++) {
+		const element = children[range[i]];
+		for (const [property, value] of rangeStamps) setProperty(element, property, value);
+		if (i === 0) for (const [property, value] of targetStamps) setProperty(element, property, value);
+		if (rangeStamps.length > 0) setProperty(element, RUN_PROPERTY, runValue(i, range.length));
+		if (group === void 0) continue;
+		if (i === 0) setProperty(element, COLLAPSE_TOGGLE_PROPERTY, group);
+		else {
+			setProperty(element, COLLAPSED_PROPERTY, "true");
+			setProperty(element, COLLAPSE_GROUP_PROPERTY, group);
+		}
+	}
 }
 function stampOq(target, pairs) {
-  setProperty(target, OQ_PROPERTY, "true");
-  const leaning = pairs.get("leaning");
-  if (leaning === void 0) return;
-  const text = leaning.replace(/\s+/g, " ").trim().slice(0, MAX_LEANING);
-  if (text !== "") setProperty(target, LEANING_PROPERTY, text);
+	setProperty(target, OQ_PROPERTY, "true");
+	const leaning = pairs.get("leaning");
+	if (leaning === void 0) return;
+	const text = leaning.replace(/\s+/g, " ").trim().slice(0, MAX_LEANING);
+	if (text !== "") setProperty(target, LEANING_PROPERTY, text);
 }
+/**
+* Merge one run of directives onto one target, then stamp.
+*
+* Merging is defined on the tree, not on the source: every directive comment up
+* to the target merges, last-key-wins, whether or not blank lines separate
+* them. Measured — adjacent comments and comments separated by a blank line
+* produce byte-identical trees, so a rule that told them apart would have to
+* re-read line numbers to do it.
+*/
 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 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);
 }
+/** A directive comment, or `undefined` for anything else — malformed included. */
 function directiveOf(node) {
-  if (node.type !== "comment") return void 0;
-  const parsed = parseVantageDirective(node.value);
-  return parsed !== null && parsed.kind === "directive" ? parsed : void 0;
+	if (node.type !== "comment") return void 0;
+	const parsed = parseVantageDirective(node.value);
+	return parsed !== null && parsed.kind === "directive" ? parsed : void 0;
 }
+/**
+* One left-to-right pass over a parent's children, recursing into elements.
+*
+* 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
+* root-only walk finds none of them.
+*
+* Pass order is also what resolves a nested section: an inner heading's
+* directive necessarily sits at a higher child index than the outer directive
+* that ranged over it, so each property is simply last-write-wins.
+*/
 function processChildren(parent, state) {
-  const children = parent.children;
-  let i = 0;
-  while (i < children.length) {
-    const node = children[i];
-    if (node.type === "element") {
-      processChildren(node, state);
-      i++;
-      continue;
-    }
-    const first = directiveOf(node);
-    if (first === void 0) {
-      i++;
-      continue;
-    }
-    const run = [first];
-    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;
-      const directive = directiveOf(next);
-      if (directive !== void 0) run.push(directive);
-    }
-    if (targetIndex >= 0) stampRun(children, targetIndex, run, state);
-    i = j;
-  }
+	const children = parent.children;
+	let i = 0;
+	while (i < children.length) {
+		const node = children[i];
+		if (node.type === "element") {
+			processChildren(node, state);
+			i++;
+			continue;
+		}
+		const first = directiveOf(node);
+		if (first === void 0) {
+			i++;
+			continue;
+		}
+		const run = [first];
+		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;
+			const directive = directiveOf(next);
+			if (directive !== void 0) run.push(directive);
+		}
+		if (targetIndex >= 0) stampRun(children, targetIndex, run, state);
+		i = j;
+	}
 }
-var rehypeVantageDirectives = () => {
-  return (tree) => {
-    processChildren(tree, { nextGroup: 1 });
-  };
+const rehypeVantageDirectives = () => {
+	return (tree) => {
+		processChildren(tree, { nextGroup: 1 });
+	};
 };
-var rehypeVantageDirectives_default = rehypeVantageDirectives;
-
-// src/rehypeVantageMathStamps.ts
-var CARRIED_KEY = "vantageDisplayMathStamps";
+//#endregion
+//#region src/rehypeVantageMathStamps.ts
+/**
+* Where the snapshot lives between the two halves.
+*
+* `file.data` rather than a closure or a module-level map: `buildPipeline` is
+* allowed to be built once and run over many documents, and per-file state is
+* the only kind that cannot leak from one of those to the next.
+*/
+const CARRIED_KEY = "vantageDisplayMathStamps";
 function classNames(node) {
-  const value = node.properties?.className;
-  return Array.isArray(value) ? value.map(String) : [];
+	const value = node.properties?.className;
+	return Array.isArray(value) ? value.map(String) : [];
 }
+/**
+* A `<pre>` `rehype-katex` will replace — its own condition, restated.
+*
+* `language-math` is the only class to test: `rehype-katex` keys the
+* pre-as-scope branch on it, and the sanitiser strips the `math-display` that
+* `remark-math` also emits (measured — a stamped fence arrives here with
+* `className: ["language-math"]` alone).
+*/
 function isDisplayMath(node) {
-  if (node.type !== "element" || node.tagName !== "pre") return false;
-  return node.children.some(
-    (child) => child.type === "element" && child.tagName === "code" && classNames(child).includes("language-math")
-  );
+	if (node.type !== "element" || node.tagName !== "pre") return false;
+	return node.children.some((child) => child.type === "element" && child.tagName === "code" && classNames(child).includes("language-math"));
 }
+/**
+* What is worth carrying: everything this pipeline stamped itself.
+*
+* Deliberately not the whole property bag. `className`, `style` and `id` belong
+* to the element KaTeX is about to build, and copying a `<pre>`'s onto a
+* `<span class="katex-display">` would fight it.
+*/
 function carriedProperties(properties) {
-  const carried = {};
-  for (const [key, value] of Object.entries(properties ?? {})) {
-    if (key === "dataSourceLine" || key.startsWith("dataVantage")) {
-      carried[key] = value;
-    }
-  }
-  return carried;
+	const carried = {};
+	for (const [key, value] of Object.entries(properties ?? {})) if (key === "dataSourceLine" || key.startsWith("dataVantage")) carried[key] = value;
+	return carried;
 }
 function collect(parent, out) {
-  const children = parent.children;
-  for (let i = 0; i < children.length; i++) {
-    const node = children[i];
-    if (node.type !== "element") continue;
-    if (isDisplayMath(node)) {
-      const properties = carriedProperties(node.properties);
-      if (Object.keys(properties).length > 0) {
-        out.push({
-          parent,
-          anchor: i === 0 ? void 0 : children[i - 1],
-          properties
-        });
-      }
-      continue;
-    }
-    collect(node, out);
-  }
+	const children = parent.children;
+	for (let i = 0; i < children.length; i++) {
+		const node = children[i];
+		if (node.type !== "element") continue;
+		if (isDisplayMath(node)) {
+			const properties = carriedProperties(node.properties);
+			if (Object.keys(properties).length > 0) out.push({
+				parent,
+				anchor: i === 0 ? void 0 : children[i - 1],
+				properties
+			});
+			continue;
+		}
+		collect(node, out);
+	}
 }
 function reapply(carried) {
-  for (const { parent, anchor, properties } of carried) {
-    const siblings = parent.children;
-    let index = 0;
-    if (anchor !== void 0) {
-      const at = siblings.indexOf(anchor);
-      if (at === -1) continue;
-      index = at + 1;
-    }
-    const replacement = siblings[index];
-    if (replacement === void 0 || replacement.type !== "element") continue;
-    if (!classNames(replacement).some((name) => name.startsWith("katex"))) {
-      continue;
-    }
-    replacement.properties ??= {};
-    for (const [key, value] of Object.entries(properties)) {
-      replacement.properties[key] ??= value;
-    }
-  }
+	for (const { parent, anchor, properties } of carried) {
+		const siblings = parent.children;
+		let index = 0;
+		if (anchor !== void 0) {
+			const at = siblings.indexOf(anchor);
+			if (at === -1) continue;
+			index = at + 1;
+		}
+		const replacement = siblings[index];
+		if (replacement === void 0 || replacement.type !== "element") continue;
+		if (!classNames(replacement).some((name) => name.startsWith("katex"))) continue;
+		replacement.properties ??= {};
+		for (const [key, value] of Object.entries(properties)) replacement.properties[key] ??= value;
+	}
 }
-var rehypeCaptureMathStamps = () => {
-  return (tree, file) => {
-    const carried = [];
-    collect(tree, carried);
-    file.data[CARRIED_KEY] = carried;
-  };
+/** Snapshot every stamped display-math block. Register before `rehypeKatex`. */
+const rehypeCaptureMathStamps = () => {
+	return (tree, file) => {
+		const carried = [];
+		collect(tree, carried);
+		file.data[CARRIED_KEY] = carried;
+	};
 };
-var rehypeRestoreMathStamps = () => {
-  return (_tree, file) => {
-    const carried = file.data[CARRIED_KEY];
-    delete file.data[CARRIED_KEY];
-    if (Array.isArray(carried)) reapply(carried);
-  };
+/** Re-apply the snapshot. Register immediately after `rehypeKatex`. */
+const rehypeRestoreMathStamps = () => {
+	return (_tree, file) => {
+		const carried = file.data[CARRIED_KEY];
+		delete file.data[CARRIED_KEY];
+		if (Array.isArray(carried)) reapply(carried);
+	};
 };
-var SAFE_STYLE_PROPERTIES = [
-  // Box metrics. `top`/`right`/`bottom`/`left` are inert now that `position` is
-  // banned, and they stay only because dropping them would fail the whole
-  // attribute for a document that writes one — the all-or-nothing rule below
-  // makes every removal a behaviour change. They buy an attacker nothing that
-  // negative `margin` does not already buy.
-  "height",
-  "min-height",
-  "max-height",
-  "width",
-  "min-width",
-  "max-width",
-  "top",
-  "bottom",
-  "left",
-  "right",
-  "margin",
-  "margin-top",
-  "margin-right",
-  "margin-bottom",
-  "margin-left",
-  "padding",
-  "padding-top",
-  "padding-right",
-  "padding-bottom",
-  "padding-left",
-  // Rules and boxes.
-  "border",
-  "border-style",
-  "border-color",
-  "border-width",
-  "border-top-width",
-  "border-right-width",
-  "border-bottom-width",
-  "border-left-width",
-  "border-top-style",
-  "border-right-style",
-  "border-bottom-style",
-  "border-left-style",
-  "border-top-color",
-  "border-right-color",
-  "border-bottom-color",
-  "border-left-color",
-  "border-radius",
-  // Typography.
-  "color",
-  "background-color",
-  "font",
-  "font-size",
-  "font-style",
-  "font-weight",
-  "font-family",
-  "font-variant",
-  "line-height",
-  "letter-spacing",
-  "word-spacing",
-  "text-align",
-  "text-decoration",
-  "text-indent",
-  "white-space",
-  "vertical-align",
-  "list-style-type",
-  // Flow.
-  "display",
-  "float",
-  "clear",
-  "opacity",
-  "overflow"
-];
-var VALUE = `[^;:()"'\\\\]*`;
-var DECLARATION = `(?:(?:${SAFE_STYLE_PROPERTIES.join("|")})\\s*:${VALUE})`;
-var SAFE_STYLE = new RegExp(
-  `^\\s*(?:${DECLARATION};\\s*)*${DECLARATION}?$`,
-  "i"
-);
-var COLLAPSE_GROUP_ID = /^[0-9]+$/;
-var sanitizeSchema = {
-  ...defaultSchema,
-  tagNames: [
-    ...defaultSchema.tagNames || [],
-    // KaTeX MathML elements
-    "math",
-    "semantics",
-    "mrow",
-    "mi",
-    "mo",
-    "mn",
-    "msup",
-    "msub",
-    "mfrac",
-    "mover",
-    "munder",
-    "msqrt",
-    "mroot",
-    "mtable",
-    "mtr",
-    "mtd",
-    "mtext",
-    "mspace",
-    "annotation",
-    // Other
-    "figure",
-    "figcaption",
-    "summary",
-    "details"
-  ],
-  attributes: {
-    ...defaultSchema.attributes,
-    "*": [
-      ...defaultSchema.attributes?.["*"] || [],
-      "className",
-      ["style", SAFE_STYLE],
-      "dataSourceLine",
-      // What `rehypeVantageDirectives` compiles a `<!-- vantage: … -->` comment
-      // into, named individually — never by a `data-vantage-*` wildcard, which
-      // would readmit whatever a future bug emits and whatever a document
-      // hand-writes as raw HTML.
-      //
-      // The value lists are the belt to the plugin's braces: the vocabulary is
-      // closed in the plugin *and* here, imported from the one module that
-      // defines it, so even if a refactor let an unvalidated value reach the
-      // tree the sanitiser still refuses it.
-      ["dataVantageTone", ...VANTAGE_TONES],
-      ["dataVantageEmphasis", ...VANTAGE_EMPHASIS],
-      ["dataVantageBadge", ...VANTAGE_BADGES],
-      ["dataVantageCollapsed", ...VANTAGE_COLLAPSED],
-      // The other half of `collapsed`: which group a hidden block belongs to,
-      // and which group a heading toggles. Both are plugin-minted counters with
-      // no vocabulary to allowlist, so they take a pattern instead —
-      // `hast-util-sanitize` accepts a `RegExp` in place of a literal value.
-      // A pattern rather than a bare name because the JS interpolates the value
-      // into a selector: anything but digits has no business reaching it.
-      ["dataVantageCollapseGroup", COLLAPSE_GROUP_ID],
-      ["dataVantageCollapseToggle", COLLAPSE_GROUP_ID],
-      ["dataVantageRun", ...VANTAGE_RUNS],
-      ["dataVantageOq", "true"],
-      // The design's one genuinely free-text value: the body of a review
-      // comment, so it cannot be value-allowlisted and this entry is name-only.
-      // Two defences remain rather than three — `hast` escapes the value on
-      // serialisation and React sets it through the DOM property path, so it
-      // cannot break out of the attribute — and the honest record of that is in
-      // the design doc rather than a third layer implied here.
-      "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"],
-    math: ["xmlns"],
-    annotation: ["encoding"],
-    img: [...defaultSchema.attributes?.img || [], "loading"],
-    td: [...defaultSchema.attributes?.td || [], ["style", SAFE_STYLE]],
-    th: [...defaultSchema.attributes?.th || [], ["style", SAFE_STYLE]]
-  }
+//#endregion
+//#region src/sanitize.ts
+/**
+* Sanitization schema for the rendering pipeline.
+* Allows GFM, KaTeX MathML, syntax highlighting classes, and
+* data-source-line attributes while blocking XSS vectors.
+*/
+const DECLARATION = `(?:(?:${[
+	"height",
+	"min-height",
+	"max-height",
+	"width",
+	"min-width",
+	"max-width",
+	"top",
+	"bottom",
+	"left",
+	"right",
+	"margin",
+	"margin-top",
+	"margin-right",
+	"margin-bottom",
+	"margin-left",
+	"padding",
+	"padding-top",
+	"padding-right",
+	"padding-bottom",
+	"padding-left",
+	"border",
+	"border-style",
+	"border-color",
+	"border-width",
+	"border-top-width",
+	"border-right-width",
+	"border-bottom-width",
+	"border-left-width",
+	"border-top-style",
+	"border-right-style",
+	"border-bottom-style",
+	"border-left-style",
+	"border-top-color",
+	"border-right-color",
+	"border-bottom-color",
+	"border-left-color",
+	"border-radius",
+	"color",
+	"background-color",
+	"font",
+	"font-size",
+	"font-style",
+	"font-weight",
+	"font-family",
+	"font-variant",
+	"line-height",
+	"letter-spacing",
+	"word-spacing",
+	"text-align",
+	"text-decoration",
+	"text-indent",
+	"white-space",
+	"vertical-align",
+	"list-style-type",
+	"display",
+	"float",
+	"clear",
+	"opacity",
+	"overflow"
+].join("|")})\\s*:[^;:()"'\\\\]*)`;
+const SAFE_STYLE = new RegExp(`^\\s*(?:${DECLARATION};\\s*)*${DECLARATION}?$`, "i");
+/**
+* A collapse group id: one or more digits, anchored.
+*
+* The plugin mints these as a per-document counter, so there is no vocabulary to
+* list. Keeping the shape narrow matters anyway — the toggle JS builds a
+* `[data-vantage-collapse-group="…"]` selector out of the value, and a document
+* that hand-wrote raw HTML is the only way a non-numeric one could ever appear.
+*/
+const COLLAPSE_GROUP_ID = /^[0-9]+$/;
+/**
+* Never set `allowComments` here.
+*
+* `hast-util-sanitize` drops comment nodes because that boolean defaults to
+* `false` — comments are not elements, so `tagNames` has nothing to do with it.
+* `rehypeVantageDirectives` relies on that deletion: it consumes a
+* `<!-- vantage: … -->` comment into attributes and deliberately leaves the node
+* for the sanitiser. Turning the switch on readmits every directive comment —
+* valid and malformed alike — into the rendered HTML, which breaks the carrier's
+* whole premise. `vantageDirectives.test.ts` ("leaves no comment in the rendered
+* markup") is the guard.
+*/
+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: {
+		...defaultSchema.attributes,
+		"*": [
+			...defaultSchema.attributes?.["*"] || [],
+			"className",
+			["style", SAFE_STYLE],
+			"dataSourceLine",
+			["dataVantageTone", ...VANTAGE_TONES],
+			["dataVantageEmphasis", ...VANTAGE_EMPHASIS],
+			["dataVantageBadge", ...VANTAGE_BADGES],
+			["dataVantageCollapsed", ...VANTAGE_COLLAPSED],
+			["dataVantageCollapseGroup", COLLAPSE_GROUP_ID],
+			["dataVantageCollapseToggle", COLLAPSE_GROUP_ID],
+			["dataVantageRun", ...VANTAGE_RUNS],
+			["dataVantageOq", "true"],
+			["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"
+		],
+		math: ["xmlns"],
+		annotation: ["encoding"],
+		img: [...defaultSchema.attributes?.img || [], "loading"],
+		td: [...defaultSchema.attributes?.td || [], ["style", SAFE_STYLE]],
+		th: [...defaultSchema.attributes?.th || [], ["style", SAFE_STYLE]]
+	}
 };
-
-// src/pipeline.ts
+//#endregion
+//#region src/pipeline.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
+* rehype (`packages/vantage-check/src/core/document.ts`), and it has to parse
+* them exactly the way the viewer does.
+*/
 function buildRemarkPlugins(options = {}) {
-  const { gfm = true, math = true } = options;
-  const plugins = [];
-  if (gfm) plugins.push([remarkGfm, { singleTilde: false }]);
-  if (math) plugins.push([remarkMath, { singleDollarTextMath: false }]);
-  return plugins;
+	const { gfm = true, math = true } = options;
+	const plugins = [];
+	if (gfm) plugins.push([remarkGfm, { singleTilde: false }]);
+	if (math) plugins.push([remarkMath, { singleDollarTextMath: false }]);
+	return plugins;
 }
+/** The hast half. Deliberately not exported: see `buildPipeline`. */
 function buildRehypePlugins(options = {}) {
-  const {
-    math = true,
-    highlight = true,
-    sourceLines = true,
-    sanitize = true,
-    bodyLineOffset = 0
-  } = options;
-  const plugins = [rehypeRaw];
-  if (sourceLines) {
-    plugins.push([rehypeSourceLines_default, { offset: bodyLineOffset }]);
-  }
-  plugins.push(rehypeVantageDirectives_default);
-  if (sanitize) plugins.push([rehypeSanitize, sanitizeSchema]);
-  plugins.push(rehypeSlug);
-  if (highlight) plugins.push(rehypeHighlight);
-  if (math) {
-    plugins.push(rehypeCaptureMathStamps, rehypeKatex, rehypeRestoreMathStamps);
-  }
-  return plugins;
+	const { math = true, highlight = true, sourceLines = true, sanitize = true, bodyLineOffset = 0 } = options;
+	const plugins = [rehypeRaw];
+	if (sourceLines) plugins.push([rehypeSourceLines, { offset: bodyLineOffset }]);
+	plugins.push(rehypeVantageAlerts);
+	plugins.push(rehypeVantageDirectives);
+	if (sanitize) plugins.push([rehypeSanitize, sanitizeSchema]);
+	plugins.push(rehypeSlug);
+	if (highlight) plugins.push(rehypeHighlight);
+	if (math) plugins.push(rehypeCaptureMathStamps, rehypeKatex, rehypeRestoreMathStamps);
+	return plugins;
 }
+/**
+* Both halves from one options object.
+*
+* This is what every renderer calls. It takes one object rather than exposing
+* the two builders because `math` spans both halves — `remark-math` parses the
+* delimiters, `rehype-katex` renders the result — and two calls are two places
+* to forget the second one.
+*
+* Returns fresh arrays on every call and reads no module-level state; keep it
+* that way, so a plugin in the chain cannot become a function of how many times
+* the chain has been built.
+*/
 function buildPipeline(options = {}) {
-  return {
-    remarkPlugins: buildRemarkPlugins(options),
-    rehypePlugins: buildRehypePlugins(options)
-  };
+	return {
+		remarkPlugins: buildRemarkPlugins(options),
+		rehypePlugins: buildRehypePlugins(options)
+	};
 }
+//#endregion
+//#region src/frontmatter.ts
+/**
+* Frontmatter parser for YAML (---) and TOML (+++) delimited content.
+* Works in both browser and server environments.
+*/
+/**
+* Parse frontmatter from markdown content.
+* Supports YAML (delimited by ---) and TOML (delimited by +++).
+*/
 function parseFrontmatter(content) {
-  if (content.startsWith("+++")) {
-    return parseFrontmatterWithDelimiter(content, "+++", "toml");
-  }
-  if (content.startsWith("---")) {
-    return parseFrontmatterWithDelimiter(content, "---", "yaml");
-  }
-  return withOffset(content, {
-    frontmatter: {},
-    body: content,
-    format: "none"
-  });
+	if (content.startsWith("+++")) return parseFrontmatterWithDelimiter(content, "+++", "toml");
+	if (content.startsWith("---")) return parseFrontmatterWithDelimiter(content, "---", "yaml");
+	return withOffset(content, {
+		frontmatter: {},
+		body: content,
+		format: "none"
+	});
 }
+/**
+* Fill in `bodyLineOffset`. `body` is always a suffix of `content`, so the
+* newlines in the prefix that was stripped are exactly the shift — which also
+* accounts for the blank line consumed after the closing delimiter.
+*/
 function withOffset(content, parsed) {
-  const stripped = content.slice(0, content.length - parsed.body.length);
-  let bodyLineOffset = 0;
-  for (const ch of stripped) {
-    if (ch === "\n") bodyLineOffset++;
-  }
-  return { ...parsed, bodyLineOffset };
+	const stripped = content.slice(0, content.length - parsed.body.length);
+	let bodyLineOffset = 0;
+	for (const ch of stripped) if (ch === "\n") bodyLineOffset++;
+	return {
+		...parsed,
+		bodyLineOffset
+	};
 }
 function parseFrontmatterWithDelimiter(content, delimiter, format) {
-  const searchStart = delimiter.length;
-  const endIndex = content.indexOf(`
-${delimiter}`, searchStart);
-  if (endIndex === -1) {
-    return withOffset(content, {
-      frontmatter: {},
-      body: content,
-      format: "none",
-      problem: { kind: "unterminated", delimiter }
-    });
-  }
-  const raw = content.slice(searchStart + 1, endIndex).trim();
-  const bodyStart = endIndex + 1 + delimiter.length;
-  const body = content.slice(bodyStart).replace(/^\n/, "");
-  try {
-    const parsed = format === "toml" ? parse(raw) : YAML.parse(raw);
-    return withOffset(content, {
-      frontmatter: parsed || {},
-      body,
-      format,
-      ...isMapping(parsed) ? {} : { problem: { kind: "not-a-mapping", delimiter } }
-    });
-  } catch (error) {
-    return withOffset(content, {
-      frontmatter: {},
-      body: content,
-      format: "none",
-      problem: { kind: "invalid", delimiter, ...errorPosition(error) }
-    });
-  }
+	const searchStart = delimiter.length;
+	const endIndex = content.indexOf(`\n${delimiter}`, searchStart);
+	if (endIndex === -1) return withOffset(content, {
+		frontmatter: {},
+		body: content,
+		format: "none",
+		problem: {
+			kind: "unterminated",
+			delimiter
+		}
+	});
+	const raw = content.slice(searchStart + 1, endIndex).trim();
+	const bodyStart = endIndex + 1 + delimiter.length;
+	const body = content.slice(bodyStart).replace(/^\n/, "");
+	try {
+		const parsed = format === "toml" ? parse(raw) : YAML.parse(raw);
+		return withOffset(content, {
+			frontmatter: parsed || {},
+			body,
+			format,
+			...isMapping(parsed) ? {} : { problem: {
+				kind: "not-a-mapping",
+				delimiter
+			} }
+		});
+	} catch (error) {
+		return withOffset(content, {
+			frontmatter: {},
+			body: content,
+			format: "none",
+			problem: {
+				kind: "invalid",
+				delimiter,
+				...errorPosition(error)
+			}
+		});
+	}
 }
+/** Empty frontmatter is fine; a scalar or a list where a table belongs is not. */
 function isMapping(value) {
-  return value === null || value === void 0 || typeof value === "object" && !Array.isArray(value);
+	return value === null || value === void 0 || typeof value === "object" && !Array.isArray(value);
 }
+/**
+* Pull the parser's message and, where it gave one, the position inside the
+* frontmatter block. `yaml` reports `linePos`; `smol-toml` reports `line` and
+* `column`. Both are optional and both are read defensively — a missing
+* position costs a less precise report, a wrong assumption costs a crash.
+*/
 function errorPosition(error) {
-  const message = error instanceof Error ? error.message : String(error);
-  const source = error;
-  const yamlPosition = source?.linePos?.[0];
-  if (typeof yamlPosition?.line === "number") {
-    return {
-      message,
-      line: yamlPosition.line,
-      ...typeof yamlPosition.col === "number" ? { column: yamlPosition.col } : {}
-    };
-  }
-  if (typeof source?.line === "number") {
-    return {
-      message,
-      line: source.line,
-      ...typeof source.column === "number" ? { column: source.column } : {}
-    };
-  }
-  return { message };
+	const message = error instanceof Error ? error.message : String(error);
+	const source = error;
+	const yamlPosition = source?.linePos?.[0];
+	if (typeof yamlPosition?.line === "number") return {
+		message,
+		line: yamlPosition.line,
+		...typeof yamlPosition.col === "number" ? { column: yamlPosition.col } : {}
+	};
+	if (typeof source?.line === "number") return {
+		message,
+		line: source.line,
+		...typeof source.column === "number" ? { column: source.column } : {}
+	};
+	return { message };
 }
-
-// src/renderMarkdown.ts
+//#endregion
+//#region src/renderMarkdown.ts
+/**
+* Framework-agnostic markdown -> HTML rendering pipeline.
+* Uses the same remark/rehype chain as the Vantage viewer.
+*/
+/**
+* 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
-  } = 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 = await processor.process(parsed.body);
-  return {
-    html: String(result),
-    frontmatter: parsed.frontmatter,
-    body: parsed.body
-  };
+	const { gfm = true, math = true, highlight = true, sourceLines = true, sanitize = true, frontmatter: parseFm = true } = 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 result = await unified().use(remarkParse).use(remarkPlugins).use(remarkRehype, { allowDangerousHtml: true }).use(rehypePlugins).use(rehypeStringify).process(parsed.body);
+	return {
+		html: String(result),
+		frontmatter: parsed.frontmatter,
+		body: parsed.body
+	};
 }
-
-// src/lineAnchor.ts
+//#endregion
+//#region src/lineAnchor.ts
+/**
+* Parsing for GitHub-style line anchors, with no DOM in sight.
+*
+* Split out from scrollToLineAnchor.ts so that non-browser consumers — the
+* `vantage-check` CLI, which validates `#L42` links against the file on disk —
+* can share the *same* syntax the viewer honours instead of reimplementing it
+* and drifting.
+*/
+/**
+* Parse a GitHub-style line anchor hash.
+* Supports: #L42, #L42-L50, #L42-50
+* Returns null if the hash is not a line anchor.
+*/
 function parseLineAnchor(hash) {
-  if (!hash) return null;
-  const frag = hash.startsWith("#") ? hash.slice(1) : hash;
-  const match = frag.match(/^L(\d+)(?:-L?(\d+))?$/);
-  if (!match) return null;
-  const start = parseInt(match[1], 10);
-  const end = match[2] ? parseInt(match[2], 10) : start;
-  return { start: Math.min(start, end), end: Math.max(start, end) };
+	if (!hash) return null;
+	const match = (hash.startsWith("#") ? hash.slice(1) : hash).match(/^L(\d+)(?:-L?(\d+))?$/);
+	if (!match) return null;
+	const start = parseInt(match[1], 10);
+	const end = match[2] ? parseInt(match[2], 10) : start;
+	return {
+		start: Math.min(start, end),
+		end: Math.max(start, end)
+	};
 }
-
-// src/scrollToLineAnchor.ts
-var HIGHLIGHT_CLASS = "line-anchor-highlight";
+//#endregion
+//#region src/scrollToLineAnchor.ts
+/**
+* Framework-agnostic line anchor utilities.
+* Scroll to and highlight the elements a GitHub-style line anchor
+* (#L42, #L42-L50) names. The parsing half lives in lineAnchor.ts, which has
+* no DOM dependency.
+*/
+const HIGHLIGHT_CLASS = "line-anchor-highlight";
+/**
+* Clear all line anchor highlights from a container.
+*/
 function clearLineAnchorHighlights(container) {
-  container.querySelectorAll(`.${HIGHLIGHT_CLASS}`).forEach((node) => {
-    node.classList.remove(HIGHLIGHT_CLASS);
-  });
+	container.querySelectorAll(`.${HIGHLIGHT_CLASS}`).forEach((node) => {
+		node.classList.remove(HIGHLIGHT_CLASS);
+	});
 }
+/**
+* Scroll to and highlight line-anchored elements in a container.
+*
+* @param container - The DOM element containing rendered markdown
+* @param hash - The URL hash (e.g. "#L42" or "#L42-L50")
+* @returns A cleanup function that removes the highlights
+*/
 function scrollToLineAnchor(container, hash) {
-  clearLineAnchorHighlights(container);
-  const range = parseLineAnchor(hash);
-  if (!range) return null;
-  const blocks = container.querySelectorAll("[data-source-line]");
-  let firstMatch = null;
-  for (const block of blocks) {
-    const line = parseInt(block.dataset.sourceLine || "0", 10);
-    if (line >= range.start && line <= range.end) {
-      block.classList.add(HIGHLIGHT_CLASS);
-      if (!firstMatch) firstMatch = block;
-    }
-  }
-  if (!firstMatch) {
-    let closest = null;
-    let closestLine = 0;
-    for (const block of blocks) {
-      const line = parseInt(
-        block.dataset.sourceLine || "0",
-        10
-      );
-      if (line <= range.start && line > closestLine) {
-        closestLine = line;
-        closest = block;
-      }
-    }
-    if (closest) {
-      closest.classList.add(HIGHLIGHT_CLASS);
-      firstMatch = closest;
-    }
-  }
-  if (firstMatch) {
-    requestAnimationFrame(() => {
-      const scrollParent = findScrollParent(container);
-      if (scrollParent) {
-        const offset = firstMatch.getBoundingClientRect().top - scrollParent.getBoundingClientRect().top + scrollParent.scrollTop;
-        scrollParent.scrollTo({ top: offset - 32, behavior: "smooth" });
-      } else {
-        firstMatch.scrollIntoView({ behavior: "smooth", block: "start" });
-      }
-    });
-  }
-  return () => clearLineAnchorHighlights(container);
+	clearLineAnchorHighlights(container);
+	const range = parseLineAnchor(hash);
+	if (!range) return null;
+	const blocks = container.querySelectorAll("[data-source-line]");
+	let firstMatch = null;
+	for (const block of blocks) {
+		const line = parseInt(block.dataset.sourceLine || "0", 10);
+		if (line >= range.start && line <= range.end) {
+			block.classList.add(HIGHLIGHT_CLASS);
+			if (!firstMatch) firstMatch = block;
+		}
+	}
+	if (!firstMatch) {
+		let closest = null;
+		let closestLine = 0;
+		for (const block of blocks) {
+			const line = parseInt(block.dataset.sourceLine || "0", 10);
+			if (line <= range.start && line > closestLine) {
+				closestLine = line;
+				closest = block;
+			}
+		}
+		if (closest) {
+			closest.classList.add(HIGHLIGHT_CLASS);
+			firstMatch = closest;
+		}
+	}
+	if (firstMatch) requestAnimationFrame(() => {
+		const scrollParent = findScrollParent(container);
+		if (scrollParent) {
+			const offset = firstMatch.getBoundingClientRect().top - scrollParent.getBoundingClientRect().top + scrollParent.scrollTop;
+			scrollParent.scrollTo({
+				top: offset - 32,
+				behavior: "smooth"
+			});
+		} else firstMatch.scrollIntoView({
+			behavior: "smooth",
+			block: "start"
+		});
+	});
+	return () => clearLineAnchorHighlights(container);
 }
 function findScrollParent(el) {
-  let node = el;
-  while (node) {
-    const overflow = getComputedStyle(node).overflowY;
-    if (overflow === "auto" || overflow === "scroll") return node;
-    node = node.parentElement;
-  }
-  return null;
+	let node = el;
+	while (node) {
+		const overflow = getComputedStyle(node).overflowY;
+		if (overflow === "auto" || overflow === "scroll") return node;
+		node = node.parentElement;
+	}
+	return null;
 }
-
-// src/vantageFrontmatter.ts
-var DOC_STATUSES = [
-  "draft",
-  "in-review",
-  "accepted",
-  "deprecated"
+//#endregion
+//#region src/vantageFrontmatter.ts
+/**
+* The document lifecycle vocabulary. Closed; extending it is a code change.
+*
+* This is the repo's own existing set, not a new one — `styleGuide.ts` tells
+* every agent to write `status: in-review # draft | in-review | accepted |
+* deprecated`, and every document under `docs/` follows it. It is deliberately
+* *not* the `badge` set (`draft stale blocked done wip`): `badge` is
+* section-scoped workflow state, `status` is document lifecycle state, and
+* `in-review` — the value the design doc's own only example renders — is not a
+* badge word at all. Only `draft` is a member of both, and a token set is per key.
+*/
+const DOC_STATUSES = [
+	"draft",
+	"in-review",
+	"accepted",
+	"deprecated"
 ];
-var VANTAGE_FRONTMATTER_KEYS = ["status-chip"];
-var DOC_STATUS_TONES = {
-  draft: "muted",
-  "in-review": "warning",
-  accepted: "tip",
-  deprecated: "caution"
+/** Every key this build knows under `vantage:`. Closed. */
+const VANTAGE_FRONTMATTER_KEYS = ["status-chip"];
+/**
+* Which tone each status borrows its colours from.
+*
+* The chip has no palette of its own: it reuses the tone chips
+* (`.vantage-chip--<tone>` in `styles/directives.css`), which is also what makes
+* a `draft` chip and a `badge=draft` chip the same visual object. A map rather
+* than a computed class name, so the whole status→tone relation is one readable
+* table and a test can assert it covers the vocabulary.
+*/
+const DOC_STATUS_TONES = {
+	draft: "muted",
+	"in-review": "warning",
+	accepted: "tip",
+	deprecated: "caution"
 };
-var STATUS_CHIP_VALUES = [
-  ...DOC_STATUSES,
-  "true",
-  "false"
+/** The legal `status-chip` values, in the order a message should list them. */
+const STATUS_CHIP_VALUES = [
+	...DOC_STATUSES,
+	"true",
+	"false"
 ];
+/** Narrowing helper the chip and the checker both use. */
 function isDocStatus(value) {
-  return typeof value === "string" && DOC_STATUSES.includes(value);
+	return typeof value === "string" && DOC_STATUSES.includes(value);
 }
 function isTable(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
+	return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
 }
+/**
+* Read the `vantage:` key out of parsed frontmatter.
+*
+* Pure: no module state, no mutation of the input, no logging. The same object
+* in twice gives equal results out.
+*/
 function readVantageFrontmatter(frontmatter) {
-  const issues = [];
-  if (!Object.hasOwn(frontmatter, "vantage")) return { issues };
-  const value = frontmatter["vantage"];
-  if (!isTable(value)) {
-    issues.push({ kind: "not-a-table", value });
-    return { issues };
-  }
-  let statusChip;
-  for (const key of Object.keys(value)) {
-    if (!VANTAGE_FRONTMATTER_KEYS.includes(key)) {
-      issues.push({ kind: "unknown-key", key });
-      continue;
-    }
-    if (key === "status-chip") {
-      statusChip = readStatusChip(frontmatter, value[key], issues);
-    }
-  }
-  return { ...statusChip === void 0 ? {} : { statusChip }, issues };
+	const issues = [];
+	if (!Object.hasOwn(frontmatter, "vantage")) return { issues };
+	const value = frontmatter["vantage"];
+	if (!isTable(value)) {
+		issues.push({
+			kind: "not-a-table",
+			value
+		});
+		return { issues };
+	}
+	let statusChip;
+	for (const key of Object.keys(value)) {
+		if (!VANTAGE_FRONTMATTER_KEYS.includes(key)) {
+			issues.push({
+				kind: "unknown-key",
+				key
+			});
+			continue;
+		}
+		if (key === "status-chip") statusChip = readStatusChip(frontmatter, value[key], issues);
+	}
+	return {
+		...statusChip === void 0 ? {} : { statusChip },
+		issues
+	};
 }
+/**
+* `status-chip` takes two shapes, and the boolean one is the recommended shape.
+*
+* `true` **inherits** the document's own top-level `status:`, so the chip cannot
+* disagree with it — which is the entire point of §5.3 ("makes `status: draft`
+* visible rather than only buried in a metadata card"; the row stays, the chip
+* promotes the value rather than moving it). A literal token is kept
+* because the design doc's first draft of that example used one, and the
+* disagreement it makes possible is turned into a checker finding rather than
+* banned.
+*
+* Discrimination is on `typeof`, never truthiness: `true` is a YAML boolean and
+* `2026-08-31` is a `Date`, and both would sail through a truthy test.
+*/
 function readStatusChip(frontmatter, raw, issues) {
-  const status = frontmatter["status"];
-  if (raw === false) return void 0;
-  if (raw === true) {
-    if (isDocStatus(status)) return status;
-    issues.push({ kind: "status-chip-orphan", status });
-    return void 0;
-  }
-  if (isDocStatus(raw)) {
-    if (isDocStatus(status) && status !== raw) {
-      issues.push({ kind: "status-chip-disagrees", chip: raw, status });
-    }
-    return raw;
-  }
-  issues.push({
-    kind: "bad-value",
-    key: "status-chip",
-    value: raw,
-    legal: STATUS_CHIP_VALUES
-  });
-  return void 0;
+	const status = frontmatter["status"];
+	if (raw === false) return void 0;
+	if (raw === true) {
+		if (isDocStatus(status)) return status;
+		issues.push({
+			kind: "status-chip-orphan",
+			status
+		});
+		return;
+	}
+	if (isDocStatus(raw)) {
+		if (isDocStatus(status) && status !== raw) issues.push({
+			kind: "status-chip-disagrees",
+			chip: raw,
+			status
+		});
+		return raw;
+	}
+	issues.push({
+		kind: "bad-value",
+		key: "status-chip",
+		value: raw,
+		legal: STATUS_CHIP_VALUES
+	});
 }
-
-// src/mermaidCache.ts
-var svgCache = /* @__PURE__ */ new Map();
-
-// src/mermaidLoader.ts
-var mermaidInstance = null;
-var mermaidLoading = null;
-var isDark = () => typeof document !== "undefined" && document.documentElement.classList.contains("dark");
+//#endregion
+//#region src/mermaidCache.ts
+const svgCache = /* @__PURE__ */ new Map();
+//#endregion
+//#region src/mermaidLoader.ts
+let mermaidInstance = null;
+let mermaidLoading = null;
+const isDark = () => typeof document !== "undefined" && document.documentElement.classList.contains("dark");
 async function getMermaid() {
-  if (mermaidInstance) return mermaidInstance;
-  if (!mermaidLoading) {
-    mermaidLoading = import('mermaid').then((mod) => {
-      const m = mod.default;
-      m.initialize({
-        startOnLoad: false,
-        theme: isDark() ? "dark" : "default",
-        securityLevel: "strict",
-        suppressErrorRendering: true
-      });
-      mermaidInstance = m;
-      return m;
-    });
-  }
-  return mermaidLoading;
+	if (mermaidInstance) return mermaidInstance;
+	if (!mermaidLoading) mermaidLoading = import("mermaid").then((mod) => {
+		const m = mod.default;
+		m.initialize({
+			startOnLoad: false,
+			theme: isDark() ? "dark" : "default",
+			securityLevel: "strict",
+			suppressErrorRendering: true
+		});
+		mermaidInstance = m;
+		return m;
+	});
+	return mermaidLoading;
 }
-
-// src/renderMermaidBlocks.ts
+//#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.
+*
+* @param container - DOM element containing rendered markdown HTML
+* @param options - Optional configuration
+* @returns Promise that resolves when all diagrams are rendered
+*
+* @example
+* ```ts
+* import { renderMarkdown, renderMermaidBlocks } from "vantage-md";
+*
+* const { html } = await renderMarkdown(content);
+* container.innerHTML = html;
+* await renderMermaidBlocks(container);
+* ```
+*/
 async function renderMermaidBlocks(container, options = {}) {
-  const { className = "mermaid", onError } = options;
-  const codeBlocks = container.querySelectorAll(
-    'pre > code.language-mermaid, pre > code[class*="language-mermaid"]'
-  );
-  if (codeBlocks.length === 0) return;
-  const mermaid = await getMermaid();
-  const renderPromises = Array.from(codeBlocks).map(async (codeEl) => {
-    const preEl = codeEl.parentElement;
-    if (!preEl) return;
-    const code = codeEl.textContent || "";
-    if (!code.trim()) return;
-    const cached = svgCache.get(code);
-    if (cached) {
-      replaceWithSvg(preEl, cached, className);
-      return;
-    }
-    try {
-      let hash = 0;
-      for (let i = 0; i < code.length; i++) {
-        hash = (hash << 5) - hash + code.charCodeAt(i);
-        hash = hash & hash;
-      }
-      const id = `mermaid-${Math.abs(hash).toString(36)}-${Date.now()}`;
-      const { svg } = await mermaid.render(id, code);
-      svgCache.set(code, svg);
-      replaceWithSvg(preEl, svg, className);
-    } catch (err) {
-      if (onError) {
-        onError(code, err instanceof Error ? err : new Error(String(err)));
-      }
-    }
-  });
-  await Promise.all(renderPromises);
+	const { className = "mermaid", onError } = options;
+	const codeBlocks = container.querySelectorAll("pre > code.language-mermaid, pre > code[class*=\"language-mermaid\"]");
+	if (codeBlocks.length === 0) return;
+	const mermaid = await getMermaid();
+	const renderPromises = Array.from(codeBlocks).map(async (codeEl) => {
+		const preEl = codeEl.parentElement;
+		if (!preEl) return;
+		const code = codeEl.textContent || "";
+		if (!code.trim()) return;
+		const cached = svgCache.get(code);
+		if (cached) {
+			replaceWithSvg(preEl, cached, className);
+			return;
+		}
+		try {
+			let hash = 0;
+			for (let i = 0; i < code.length; i++) {
+				hash = (hash << 5) - hash + code.charCodeAt(i);
+				hash = hash & hash;
+			}
+			const id = `mermaid-${Math.abs(hash).toString(36)}-${Date.now()}`;
+			const { svg } = await mermaid.render(id, code);
+			svgCache.set(code, svg);
+			replaceWithSvg(preEl, svg, className);
+		} catch (err) {
+			if (onError) onError(code, err instanceof Error ? err : new Error(String(err)));
+		}
+	});
+	await Promise.all(renderPromises);
 }
 function replaceWithSvg(preEl, svg, className) {
-  const wrapper = document.createElement("div");
-  wrapper.className = className;
-  wrapper.innerHTML = svg;
-  preEl.replaceWith(wrapper);
+	const wrapper = document.createElement("div");
+	wrapper.className = className;
+	wrapper.innerHTML = svg;
+	preEl.replaceWith(wrapper);
 }
-
-// src/resolveLinks.ts
+//#endregion
+//#region src/resolveLinks.ts
+/**
+* Rewrite relative links in rendered HTML.
+*
+* Processes all `href="..."` attributes, skipping:
+* - Absolute URLs (http://, https://, mailto:, etc.)
+* - Anchor-only links (#section)
+* - Already-absolute paths (/path/to/file)
+*
+* @example
+* ```ts
+* import { renderMarkdown, resolveLinks } from "vantage-md";
+*
+* const { html } = await renderMarkdown(content);
+*
+* // Simple: prepend a base path
+* const resolved = resolveLinks(html, { basePath: "/docs/", currentPath: "guides/setup.md" });
+*
+* // Custom: full control over link rewriting
+* const resolved = resolveLinks(html, {
+*   currentPath: "guides/setup.md",
+*   rewriter: (href, currentPath) => `/kb/${currentPath}/../${href}`,
+* });
+* ```
+*/
 function resolveLinks(html, options = {}) {
-  const { basePath = "/", rewriter, currentPath = "" } = options;
-  const parts = currentPath.split("/");
-  parts.pop();
-  const currentDir = parts.join("/");
-  return html.replace(
-    /href="([^"]*?)"/g,
-    (_match, href) => {
-      if (href.startsWith("http://") || href.startsWith("https://") || href.startsWith("mailto:") || href.startsWith("data:") || href.startsWith("#") || href.startsWith("/")) {
-        return `href="${href}"`;
-      }
-      if (rewriter) {
-        const result = rewriter(href, currentPath);
-        if (result !== null) {
-          return `href="${result}"`;
-        }
-        return `href="${href}"`;
-      }
-      const [pathPart, hashPart] = href.split("#");
-      const cleanHref = pathPart.replace(/^\.\//, "");
-      const resolvedPath = currentDir ? `${currentDir}/${cleanHref}` : cleanHref;
-      const base = basePath.endsWith("/") ? basePath : `${basePath}/`;
-      const finalHref = `${base}${resolvedPath}${hashPart ? `#${hashPart}` : ""}`;
-      return `href="${finalHref}"`;
-    }
-  );
+	const { basePath = "/", rewriter, currentPath = "" } = options;
+	const parts = currentPath.split("/");
+	parts.pop();
+	const currentDir = parts.join("/");
+	return html.replace(/href="([^"]*?)"/g, (_match, href) => {
+		if (href.startsWith("http://") || href.startsWith("https://") || href.startsWith("mailto:") || href.startsWith("data:") || href.startsWith("#") || href.startsWith("/")) return `href="${href}"`;
+		if (rewriter) {
+			const result = rewriter(href, currentPath);
+			if (result !== null) return `href="${result}"`;
+			return `href="${href}"`;
+		}
+		const [pathPart, hashPart] = href.split("#");
+		const cleanHref = pathPart.replace(/^\.\//, "");
+		const resolvedPath = currentDir ? `${currentDir}/${cleanHref}` : cleanHref;
+		return `href="${`${basePath.endsWith("/") ? basePath : `${basePath}/`}${resolvedPath}${hashPart ? `#${hashPart}` : ""}`}"`;
+	});
 }
-
-// src/styleGuide.ts
-var STYLE_GUIDE = `## Markdown style guide (for Vantage viewer)
+//#endregion
+//#region src/styleGuide.ts
+/**
+* The canonical Vantage Markdown style guide.
+*
+* This string is the single source of truth for the conventions Vantage's
+* renderer expects. Two consumers read it:
+*
+* - the in-app "Style Guide for Agents" modal, which shows it with a copy
+*   button, and
+* - the `vantage-check style-guide` command, which prints it so an agent can
+*   fetch it without a human in the loop.
+*
+* Every rule stated here should be one a checker can enforce or a renderer
+* actually cares about — if a line is neither, it does not belong.
+*/
+const STYLE_GUIDE = `## Markdown style guide (for Vantage viewer)
 
 When writing or updating markdown documents that will be viewed in Vantage, follow these conventions:
 
 ### Structure
-- Use headings (## and ###) to organize content \u2014 they become navigable outline anchors.
+- Use headings (## and ###) to organize content — they become navigable outline anchors.
 - Keep paragraphs focused and concise. Break up dense text with subheadings, lists, or tables.
 
 ### Links and cross-references
@@ -1028,11 +1585,11 @@ When writing or updating markdown documents that will be viewed in Vantage, foll
   - Subdirectory: \`[Design Doc](./design/auth.md)\`
   - Parent / sibling folder: \`[Overview](../overview.md)\` or \`[Spec](../specs/api.md)\`
 - **Never use leading slashes**:
-  - \u274C \`[Doc](/docs/guide.md)\` (breaks web routing and multi-repo scoping)
-  - \u2705 \`[Doc](../docs/guide.md)\` or \`[Doc](./guide.md)\`
+  - ❌ \`[Doc](/docs/guide.md)\` (breaks web routing and multi-repo scoping)
+  - ✅ \`[Doc](../docs/guide.md)\` or \`[Doc](./guide.md)\`
 - **Never use absolute filesystem paths or URI schemes**:
-  - \u274C \`file:///workspace/docs/guide.md\`, \`/workspace/docs/guide.md\`, \`C:\\...\`
-  - \u2705 \`[Doc](./guide.md)\` or \`[Doc](../guide.md)\`
+  - ❌ \`file:///workspace/docs/guide.md\`, \`/workspace/docs/guide.md\`, \`C:\\...\`
+  - ✅ \`[Doc](./guide.md)\` or \`[Doc](../guide.md)\`
 - **Always include the file extension**: Use \`.md\`, \`.ts\`, \`.go\`, etc. (e.g. \`[Model](model.go)\`).
 - **Line anchors and ranges**:
   - Link to specific lines: \`[Handler](../server/api.go#L42)\` or \`[Range](../server/api.go#L42-L58)\`
@@ -1043,8 +1600,8 @@ When writing or updating markdown documents that will be viewed in Vantage, foll
   - Cross-doc: \`[Architecture](../overview.md#system-architecture)\`
   - Anchor slugs are lowercase, hyphenated, and punctuation-stripped.
 - **Backticks in links**: Place backticks inside the link label, not around the markdown link syntax:
-  - \u2705 \`[\`config.json\`](./config.json)\` or \`[config.json](./config.json)\`
-  - \u274C \`\`[config.json](./config.json)\`\`
+  - ✅ \`[\`config.json\`](./config.json)\` or \`[config.json](./config.json)\`
+  - ❌ \`\`[config.json](./config.json)\`\`
 
 ### Frontmatter (Metadata)
 - Include structured metadata at the very top of docs delimited by \`---\` (YAML) or \`+++\` (TOML). Vantage renders this as a metadata card:
@@ -1060,9 +1617,9 @@ vantage:
   status-chip: true # show \`status\` as a chip above the metadata card
 ---
 \`\`\`
-- **Nothing may sit above the opening delimiter** \u2014 not a blank line, not an editorial comment, not a \`<!-- vantage: \u2026 -->\` directive. Frontmatter is recognised only at the very first byte of the file (in Vantage, on GitHub, and in every other reader), so one line above it turns the whole block into body text: a horizontal rule followed by a heading made of the raw keys, with every field lost. \`vantage-check\` reports it as \`frontmatter/not-at-top\`.
+- **Nothing may sit above the opening delimiter** — not a blank line, not an editorial comment, not a \`<!-- vantage: … -->\` directive. Frontmatter is recognised only at the very first byte of the file (in Vantage, on GitHub, and in every other reader), so one line above it turns the whole block into body text: a horizontal rule followed by a heading made of the raw keys, with every field lost. \`vantage-check\` reports it as \`frontmatter/not-at-top\`.
 - **\`vantage:\` is Vantage's own reserved key.** It holds chrome that belongs to the file rather than to a section, it never shows up in the metadata card, and every other renderer ignores it. One key today: \`status-chip\`.
-- **Prefer \`status-chip: true\`**, which shows the document's own \`status:\` and therefore cannot disagree with it. A literal \`status-chip: accepted\` is accepted too, but it is a second value that goes stale on its own \u2014 \`vantage-check\` reports the disagreement.
+- **Prefer \`status-chip: true\`**, which shows the document's own \`status:\` and therefore cannot disagree with it. A literal \`status-chip: accepted\` is accepted too, but it is a second value that goes stale on its own — \`vantage-check\` reports the disagreement.
 - The chip's vocabulary is \`status\`'s, exactly: \`draft | in-review | accepted | deprecated\`, lowercase. \`Draft\` renders no chip at all, silently.
 
 ### Mermaid diagrams
@@ -1101,7 +1658,7 @@ flowchart TD
 
 ### Vantage directives (optional, and Vantage-only)
 
-Vantage reads a few styling hints from ordinary HTML comments. Every other renderer \u2014 GitHub included \u2014 drops them, so a document has to read exactly the same without them: directives decorate, they never carry meaning. One goes on a line of its own, with a blank line after it, and applies to the block that follows:
+Vantage reads a few styling hints from ordinary HTML comments. Every other renderer — GitHub included — drops them, so a document has to read exactly the same without them: directives decorate, they never carry meaning. One goes on a line of its own, with a blank line after it, and applies to the block that follows:
 
 \`\`\`markdown
 <!-- vantage: section tone=warning badge=stale -->
@@ -1112,17 +1669,18 @@ The steps below predate the rewrite.
 \`\`\`
 
 - **Three names**: \`section\` (the heading and everything under it), \`block\` (the one block after it), \`oq\` (one answerable Open Question).
-- **The keys and values are a closed set**: \`tone\` = \`note | tip | important | warning | caution | muted\`; \`emphasis\` = \`strong | normal | quiet\`; \`badge\` = \`draft | stale | blocked | done | wip\`; \`collapsed\` = \`true | false\`. Name a *tone*, never a colour \u2014 the theme decides what a warning looks like, in light mode, in dark mode, and in print.
+- **The keys and values are a closed set**: \`tone\` = \`note | tip | important | warning | caution | muted\`; \`emphasis\` = \`strong | normal | quiet\`; \`badge\` = \`draft | stale | blocked | done | wip\`; \`collapsed\` = \`true | false\`. Name a *tone*, never a colour — the theme decides what a warning looks like, in light mode, in dark mode, and in print.
 - **Use them sparingly.** One or two per document, on the sections that genuinely differ. A document where everything is toned says nothing, and a rainbow one is harder to read than a plain one.
-- **Anything outside those sets is silently ignored** \u2014 nothing breaks, and nothing styles either. Run \`vantage-check\` on the document: the \`vantage/*\` rules are the only thing that will ever tell you a directive did nothing.
-- **Always close the comment with \`-->\`.** Never \`--!>\`, and never leave it open: Markdown reads every line below an unclosed \`<!--\` as part of the comment, and the whole rest of the document vanishes from the page. For the same reason \`-->\` cannot appear *inside* a value \u2014 it ends the comment early and spills the remainder into the page as literal text.
-- **In a list, indent the directive inside the item**, with blank lines around it (below). At the start of a line between two items it ends the list and starts a second one, which changes the numbering and the spacing in every renderer \u2014 the one thing a directive must never do.
-- **A \`leaning\` restates the leaning; it is never "yes".** The one-click button in review mode files that text as a review comment, and the comment is all the agent reading it has \u2014 nobody remembers which button was clicked. \`leaning="Yes"\` beside a two-branch question is a support ticket.
+- **Anything outside those sets is silently ignored** — nothing breaks, and nothing styles either. Run \`vantage-check\` on the document: the \`vantage/*\` rules are the only thing that will ever tell you a directive did nothing.
+- **Always close the comment with \`-->\`.** Never \`--!>\`, and never leave it open: Markdown reads every line below an unclosed \`<!--\` as part of the comment, and the whole rest of the document vanishes from the page. For the same reason \`-->\` cannot appear *inside* a value — it ends the comment early and spills the remainder into the page as literal text.
+- **In a list, indent the directive inside the item**, with blank lines around it (below). At the start of a line between two items it ends the list and starts a second one, which changes the numbering and the spacing in every renderer — the one thing a directive must never do.
+- **Every open question (\u{1F4AC}) with a stated leaning gets an \`oq\` directive.** The convention's prose — the emoji, the \`OQ-N\` id, the \`_Leaning:_\` line, the fill-in \`**Answer:**\` — produces no button on its own. Writing the convention and stopping there is the most common way this feature goes missing: the questions look complete, review mode is on, and there is nothing to click. **\`vantage-check\` reports it as an error** (\`vantage/oq-missing\`), because a question awaiting a ruling that the reviewer cannot file is not a style preference. Mark it \u{1F512} if it is blocked on something upstream and cannot be answered yet, or \u2705 once it is decided; either state needs no directive.
+- **A \`leaning\` restates the leaning; it is never "yes".** The one-click button in review mode files that text as a review comment, and the comment is all the agent reading it has — nobody remembers which button was clicked. \`leaning="Yes"\` beside a two-branch question is a support ticket.
 
 \`\`\`markdown
 1. **OQ-9: Queue position on re-entry.**
 
-   <!-- vantage: oq id=OQ-9 leaning="Back of the queue \u2014 the fix might interact with what merged while it was out." -->
+   <!-- vantage: oq id=OQ-9 leaning="Back of the queue — the fix might interact with what merged while it was out." -->
 
    _Leaning:_ Back of the queue.
 \`\`\`
@@ -1130,10 +1688,10 @@ The steps below predate the rewrite.
 ### Tables, task lists, and math
 - **Tables**: Use standard markdown tables for structured comparisons and schemas.
 - **Task lists**: Use \`- [ ]\` and \`- [x]\` for actionable checklists and status tracking.
-- **LaTeX Math**: Use \`$$...$$\` for *all* KaTeX math \u2014 display blocks (\`$$\` alone on its own lines) and inline alike (\`$$E = mc^2$$\` mid-sentence).
+- **LaTeX Math**: Use \`$$...$$\` for *all* KaTeX math — display blocks (\`$$\` alone on its own lines) and inline alike (\`$$E = mc^2$$\` mid-sentence).
   - Single dollars are **not** math delimiters: \`$HOME\` and \`$100\` stay literal, so prose and shell snippets are safe to write as-is.
 `;
+//#endregion
+export { ALERT_TITLES, DIRECTIVE_NAMES, DIRECTIVE_VOCABULARY, DOC_STATUSES, DOC_STATUS_TONES, SAFE_STYLE, STYLE_GUIDE, VANTAGE_ALERTS, VANTAGE_BADGES, VANTAGE_COLLAPSED, VANTAGE_EMPHASIS, VANTAGE_FRONTMATTER_KEYS, VANTAGE_OQ_HOST_TARGETS, VANTAGE_RUNS, VANTAGE_SENTINEL, VANTAGE_TONES, buildPipeline, buildRemarkPlugins, clearLineAnchorHighlights, hasVantageSentinel, isDocStatus, parseFrontmatter, parseLineAnchor, parseVantageDirective, readVantageFrontmatter, rehypeSourceLines, rehypeVantageAlerts, rehypeVantageDirectives, renderMarkdown, renderMermaidBlocks, resolveLinks, sanitizeSchema, scrollToLineAnchor };
 
-export { DIRECTIVE_NAMES, DIRECTIVE_VOCABULARY, DOC_STATUSES, DOC_STATUS_TONES, SAFE_STYLE, STYLE_GUIDE, VANTAGE_BADGES, VANTAGE_COLLAPSED, VANTAGE_EMPHASIS, VANTAGE_FRONTMATTER_KEYS, VANTAGE_OQ_HOST_TARGETS, VANTAGE_RUNS, VANTAGE_SENTINEL, VANTAGE_TONES, buildPipeline, buildRemarkPlugins, clearLineAnchorHighlights, hasVantageSentinel, isDocStatus, parseFrontmatter, parseLineAnchor, parseVantageDirective, readVantageFrontmatter, rehypeSourceLines_default as rehypeSourceLines, rehypeVantageDirectives_default as rehypeVantageDirectives, renderMarkdown, renderMermaidBlocks, resolveLinks, sanitizeSchema, scrollToLineAnchor };
-//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map