vantage-md 0.5.8 → 0.5.9

package/dist/index.cjs

@@ -46,6 +46,21 @@ let unist_util_visit = require("unist-util-visit");
 let yaml = require("yaml");
 yaml = __toESM(yaml, 1);
 let smol_toml = require("smol-toml");
+//#region src/rehypeVantageAnchors.ts
+/** What `rehypeVantageDirectives` stamps, in hast property form. */
+const OQ_ID_PROPERTY$1 = "dataVantageOqId";
+function rehypeVantageAnchors() {
+	return (tree) => {
+		(0, unist_util_visit.visit)(tree, "element", (node) => {
+			const carried = node.properties?.[OQ_ID_PROPERTY$1];
+			if (typeof carried !== "string" || carried === "") return;
+			delete node.properties[OQ_ID_PROPERTY$1];
+			if (typeof node.properties.id === "string" && node.properties.id !== "") return;
+			node.properties.id = carried;
+		});
+	};
+}
+//#endregion
 //#region src/rehypeSourceLines.ts
 /**
 * Tags that get a `data-source-line`.
@@ -317,12 +332,17 @@ const VANTAGE_RUNS = [
 	"only"
 ];
 /**
-* The tags a `section`/`block` directive may stamp.
+* The tags a `section`/`block` directive may **target**.
+*
+* Deliberately `rehypeSourceLines`'s `BLOCK_TAGS`: a directive's target 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.
 *
-* 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 does **not** bound a `section`'s range. Every element in the span is
+* stamped, on the tag list or not, because a member only has to be a box in the
+* flow for the section's vertical rule to cross it — see `styleRange` in
+* `rehypeVantageDirectives.ts` for the hole that restricting the range left.
 *
 * 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
@@ -389,6 +409,23 @@ const VANTAGE_ANCHOR_TARGETS = [
 * 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");
+/**
+* The shape of an `oq` directive's `id`: `OQ-` then an optional short uppercase
+* prefix then digits. `OQ-9`, `OQ-TP6` and `OQ-A03` are ids; `OQ-foo`, `OQ-tp6`
+* and a bare `OQ6` are not.
+*
+* The prefix is what keeps ids distinct once one document references another's
+* questions — `trust-paths.md`'s `OQ-4` and a design sketch's `OQ-4` are
+* different questions, and a bare number cannot say which one a cross-document
+* reference means. It is optional because most documents never leave their own
+* file, and requiring it everywhere would fire on every single-doc sketch.
+*
+* Three consumers read it from here and none of them may re-spell it: the
+* plugin that stamps the anchor, the sanitiser that allowlists the value, and
+* the checker's `vantage/oq-id-format`. A fourth copy is how the checker starts
+* calling a working anchor malformed.
+*/
+const VANTAGE_OQ_ID = /^OQ-(?:[A-Z][A-Z0-9]{0,5})?[0-9]+$/;
 const STYLE_KEYS = {
 	tone: VANTAGE_TONES,
 	emphasis: VANTAGE_EMPHASIS,
@@ -531,11 +568,13 @@ function parseVantageDirective(comment) {
 //#endregion
 //#region src/rehypeVantageDirectives.ts
 /**
-* What a `section`/`block` and an `oq` directive may stamp.
+* What a `section`/`block` and an `oq` directive may **target**.
 *
 * Both lists live in `vantageDirectives.ts`, with the reasoning for each tag,
 * because the CLI checker resolves the same question over mdast and must reach
 * the same answer (D5).
+*
+* Neither list bounds a `section`'s range: see `styleRange`.
 */
 const STYLE_TARGET_TAGS = new Set(VANTAGE_STYLE_TARGETS);
 const ANCHOR_TARGET_TAGS = new Set(VANTAGE_ANCHOR_TARGETS);
@@ -582,6 +621,18 @@ const RUN_PROPERTY = "dataVantageRun";
 const OQ_PROPERTY = "dataVantageOq";
 const LEANING_PROPERTY = "dataVantageLeaning";
 /**
+* The id, carried as a `data-` attribute rather than written straight to `id`.
+*
+* This plugin runs *before* `rehypeSanitize` — it has to, it reads comments and
+* the sanitiser deletes them — and the sanitiser's default schema clobbers `id`
+* with the prefix `user-content-`. A bare `id` set here would reach the page as
+* `user-content-OQ-4`, every `#OQ-4` link in every document would land nowhere,
+* and nothing would error. `rehypeVantageAnchors` promotes this to a real `id`
+* on the other side of the sanitiser, which is the same reason `rehypeSlug` is
+* registered there (`pipeline.ts`).
+*/
+const OQ_ID_PROPERTY = "dataVantageOqId";
+/**
 * The three properties `collapsed=true` stamps across a section.
 *
 * The heading takes a *different* attribute from the blocks it hides, and that
@@ -654,6 +705,22 @@ function accepts(name, key, value) {
 * `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.
+*
+* **Every element in the span, not only a `VANTAGE_STYLE_TARGETS` one.** That
+* list gates the *target* and nothing else. Restricting the range to it as well
+* used to leave a raw-HTML `<figure>`, `<dl>` or `<details>` unstamped between
+* two stamped paragraphs — and the section's one continuous vertical rule is
+* drawn per member, so an unstamped member is a hole the height of the block
+* plus its margins. Measured over the real stylesheet: 44px for a one-line
+* `<figure>`, against the 40px a neighbour can bleed upward, and arbitrarily
+* large for anything taller. `collapsed=true` had the same shape of bug the
+* other way round — it hid the paragraphs and left the figure on the page.
+*
+* The two lists answering different questions is the point, not an oversight:
+* a *target* must be a block a review anchor can name, because a directive
+* pointing at something unanchorable is a directive with no addressable effect.
+* A *member* only has to be a box in the flow, because all it does is carry the
+* run's tone across itself.
 */
 function styleRange(children, targetIndex, name) {
 	const range = [targetIndex];
@@ -663,7 +730,7 @@ function styleRange(children, targetIndex, name) {
 		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);
+		if (node.type === "element") range.push(i);
 	}
 	return range;
 }
@@ -722,6 +789,8 @@ function stampStyle(children, targetIndex, name, pairs, state) {
 }
 function stampOq(target, pairs) {
 	setProperty(target, OQ_PROPERTY, "true");
+	const id = pairs.get("id");
+	if (id !== void 0 && id !== "") setProperty(target, OQ_ID_PROPERTY, id);
 	const leaning = pairs.get("leaning");
 	if (leaning === void 0) return;
 	const text = leaning.replace(/\s+/g, " ").trim().slice(0, MAX_LEANING);
@@ -1027,6 +1096,7 @@ const sanitizeSchema = {
 			["dataVantageCollapseToggle", COLLAPSE_GROUP_ID],
 			["dataVantageRun", ...VANTAGE_RUNS],
 			["dataVantageOq", "true"],
+			["dataVantageOqId", VANTAGE_OQ_ID],
 			["dataVantageAlert", ...VANTAGE_ALERTS],
 			"dataVantageLeaning"
 		],
@@ -1076,6 +1146,7 @@ function buildRehypePlugins(options = {}) {
 	plugins.push(rehypeVantageAlerts);
 	plugins.push(rehypeVantageDirectives);
 	if (sanitize) plugins.push([rehype_sanitize.default, sanitizeSchema]);
+	plugins.push(rehypeVantageAnchors);
 	plugins.push(rehype_slug.default);
 	if (highlight) plugins.push(rehype_highlight.default);
 	if (math) plugins.push(rehypeCaptureMathStamps, rehype_katex.default, rehypeRestoreMathStamps);
@@ -1469,27 +1540,92 @@ function readStatusChip(frontmatter, raw, issues) {
 	});
 }
 //#endregion
+//#region src/mermaidTheme.ts
+/** Whether the document is asking for the dark palette right now. */
+function currentMermaidTheme() {
+	return typeof document !== "undefined" && document.documentElement.classList.contains("dark") ? "dark" : "default";
+}
+/**
+* Theme variables per theme. Mermaid derives most of its palette from these, so
+* the set is deliberately small: the surfaces, the ink, and the lines.
+*/
+const THEME_VARIABLES = {
+	dark: {
+		background: "#1d293d",
+		mainBkg: "#314158",
+		nodeBorder: "#90a1b9",
+		nodeTextColor: "#f1f5f9",
+		lineColor: "#90a1b9",
+		textColor: "#e2e8f0",
+		edgeLabelBackground: "#1d293d"
+	},
+	default: {
+		background: "#f8fafc",
+		mainBkg: "#f1f5f9",
+		nodeBorder: "#62748e",
+		nodeTextColor: "#0f172b",
+		lineColor: "#62748e",
+		textColor: "#1d293d",
+		edgeLabelBackground: "#f8fafc"
+	}
+};
+function mermaidThemeVariables(theme) {
+	return THEME_VARIABLES[theme];
+}
+//#endregion
 //#region src/mermaidCache.ts
 const svgCache = /* @__PURE__ */ new Map();
+const cacheKey = (code, theme) => `${theme}${code}`;
+/** The SVG for this fence in the theme the page is currently asking for. */
+function getCachedSvg(code, theme = currentMermaidTheme()) {
+	return svgCache.get(cacheKey(code, theme));
+}
+function setCachedSvg(code, svg, theme = currentMermaidTheme()) {
+	svgCache.set(cacheKey(code, theme), svg);
+}
 //#endregion
 //#region src/mermaidLoader.ts
 let mermaidInstance = null;
 let mermaidLoading = null;
-const isDark = () => typeof document !== "undefined" && document.documentElement.classList.contains("dark");
+/** The theme the loaded instance was last configured for, `null` until loaded. */
+let configuredTheme = null;
+function configure(m, theme) {
+	m.initialize({
+		startOnLoad: false,
+		theme,
+		themeVariables: mermaidThemeVariables(theme),
+		securityLevel: "strict",
+		suppressErrorRendering: true
+	});
+	configuredTheme = theme;
+}
+/**
+* The mermaid module, configured for the theme the page is asking for *now*.
+*
+* Re-configuring on a theme change is the point. `initialize` used to run once,
+* on first import, so every diagram rendered after a light/dark switch still
+* came out in the palette the session started in — a white slab of a flowchart
+* on the dark page, or a black one on the light page. `initialize` merges into
+* mermaid's global config, so calling it again is how the next `render` picks
+* the new palette up; the cache is keyed by theme so the old SVGs are not
+* served instead (`mermaidCache.ts`).
+*/
 async function getMermaid() {
-	if (mermaidInstance) return mermaidInstance;
+	const theme = currentMermaidTheme();
+	if (mermaidInstance) {
+		if (configuredTheme !== theme) configure(mermaidInstance, theme);
+		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
-		});
+		configure(m, currentMermaidTheme());
 		mermaidInstance = m;
 		return m;
 	});
-	return mermaidLoading;
+	const loaded = await mermaidLoading;
+	const wanted = currentMermaidTheme();
+	if (configuredTheme !== wanted) configure(loaded, wanted);
+	return loaded;
 }
 //#endregion
 //#region src/renderMermaidBlocks.ts
@@ -1523,18 +1659,20 @@ 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();
+	let loading;
+	const mermaidOnce = () => loading ??= 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);
+		const cached = getCachedSvg(code);
 		if (cached) {
 			replaceWithSvg(preEl, cached, className);
 			return;
 		}
 		try {
+			const mermaid = await mermaidOnce();
 			let hash = 0;
 			for (let i = 0; i < code.length; i++) {
 				hash = (hash << 5) - hash + code.charCodeAt(i);
@@ -1542,7 +1680,7 @@ async function renderMermaidBlocks(container, options = {}) {
 			}
 			const id = `mermaid-${Math.abs(hash).toString(36)}-${Date.now()}`;
 			const { svg } = await mermaid.render(id, code);
-			svgCache.set(code, svg);
+			setCachedSvg(code, svg);
 			replaceWithSvg(preEl, svg, className);
 		} catch (err) {
 			if (onError) onError(code, err instanceof Error ? err : new Error(String(err)));
@@ -1550,9 +1688,34 @@ async function renderMermaidBlocks(container, options = {}) {
 	});
 	await Promise.all(renderPromises);
 }
+/**
+* Attributes the wrapper inherits from the `<pre>` it replaces.
+*
+* The splice is the same shape of problem `rehypeVantageMathStamps` solves for
+* KaTeX: the pipeline stamped the fence, and swapping the element out throws
+* the stamps away. A mermaid diagram inside a toned section then drew no slice
+* of the section's vertical rule, leaving a hole as tall as the diagram; a
+* collapsed section left the diagram visible under a closed heading; and a
+* `#L` anchor pointing at the fence resolved to nothing.
+*
+* Named individually rather than copied wholesale: `class` is the caller's
+* (`className`), and `id` would be duplicated onto a second element.
+*/
+const CARRIED_ATTRIBUTES = [
+	"data-source-line",
+	"data-vantage-tone",
+	"data-vantage-emphasis",
+	"data-vantage-run",
+	"data-vantage-collapsed",
+	"data-vantage-collapse-group"
+];
 function replaceWithSvg(preEl, svg, className) {
 	const wrapper = document.createElement("div");
 	wrapper.className = className;
+	for (const name of CARRIED_ATTRIBUTES) {
+		const value = preEl.getAttribute(name);
+		if (value !== null) wrapper.setAttribute(name, value);
+	}
 	wrapper.innerHTML = svg;
 	preEl.replaceWith(wrapper);
 }
@@ -1719,6 +1882,8 @@ The steps below predate the rewrite.
 - **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.
+- **An open question's id is \`OQ-\` then an optional short uppercase prefix then digits** — \`OQ-9\`, \`OQ-TP6\`, \`OQ-A03\`. The prefix is what keeps ids distinct once one document references another's questions, so use one in both whenever they cross-reference. \`vantage-check\` reports anything outside that shape as \`vantage/oq-id-format\`, and the same id twice in one document as \`vantage/oq-id-duplicate\` — both are silent otherwise, because the id becomes the block's anchor and a refused or duplicated one simply goes nowhere.
+- **A reference is a link, or it is a lie.** An \`OQ-\` id, a \`\u00a7N\` section number and a filename all read like pointers, and written as bare prose none of them can be followed or checked — which is exactly why a stale one is never caught. Link the question to its anchor (\`[OQ-4](#OQ-4)\`, or the Decision Ledger once it is compacted), the section to its heading, the filename to the file. \`vantage-check\` reports all three (\`ref/*\`) as errors, and checks that the link points at the thing the reference names rather than merely at something. Writing a specimen rather than a reference? Put it in a fenced block, which the rules never read.
 - **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.
 
@@ -1764,6 +1929,7 @@ exports.parseVantageDirective = parseVantageDirective;
 exports.readVantageFrontmatter = readVantageFrontmatter;
 exports.rehypeSourceLines = rehypeSourceLines;
 exports.rehypeVantageAlerts = rehypeVantageAlerts;
+exports.rehypeVantageAnchors = rehypeVantageAnchors;
 exports.rehypeVantageDirectives = rehypeVantageDirectives;
 exports.renderMarkdown = renderMarkdown;
 exports.renderMermaidBlocks = renderMermaidBlocks;