vantage-md 0.6.2 → 0.7.1

package/dist/index.cjs

@@ -116,14 +116,14 @@ const rehypeSourceLines = (options) => {
 * `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
+* italicizes 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
+* an alert *is* the six-color 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
@@ -137,7 +137,7 @@ const rehypeSourceLines = (options) => {
 *
 * ## What it does not do
 *
-* It does not touch a blockquote that carries no marker, and an unrecognised
+* It does not touch a blockquote that carries no marker, and an unrecognized
 * 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.
@@ -421,11 +421,63 @@ const VANTAGE_OQ_HOST_TARGETS = VANTAGE_ANCHOR_TARGETS.filter((tag) => tag !== "
 * 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
+* plugin that stamps the anchor, the sanitizer that allowlists the value, and
 * the checker's `vantage/oq-id-format`. A fourth copy is how the checker starts
 * calling a working anchor malformed.
 */
 const VANTAGE_OQ_ID = /^OQ-(?:[A-Z][A-Z0-9]{0,5})?[0-9]+$/;
+/**
+* The status emoji the documentation convention marks an Open Question with, and
+* what each one means to a reader deciding whether the question wants them.
+*
+* These are *prose* — ordinary characters in the question's title, not part of
+* any directive — which is exactly why they need a home that both readers of
+* them can import. Two consumers ask what a marker means and they must not
+* answer differently: the checker's `vantage/oq-missing`, which demands a
+* directive on an open question and must never demand one on a blocked one, and
+* the viewer's contents column, which shows the marker and needs a word for it
+* that a screen reader can say. They were private constants in the checker until
+* the second consumer arrived.
+*
+* `open` is the only state that wants a one-click answer. `settled` and
+* `blocked` deliberately carry no directive at all — a control offering to
+* answer a question that is already decided, or that cannot be answered yet, is
+* a lie — so the checker keys on the distinction rather than on the word
+* "Leaning:" alone. Either non-open marker wins when both appear on one item.
+*/
+const VANTAGE_OQ_STATUS = {
+	/** 💬 — an active decision awaiting a ruling. */
+	open: "💬",
+	/** ✅ — decided, awaiting compaction into a Decision Ledger. */
+	settled: "✅",
+	/** 🔒 — blocked on an upstream decision or experiment. */
+	blocked: "🔒"
+};
+/**
+* What a marker says, in words, for somewhere an emoji cannot go.
+*
+* An accessible name is the reason this exists: a contents entry whose whole
+* status is one glyph says nothing to a screen reader, and "speech bubble" —
+* which is what it would otherwise read out — is worse than nothing.
+*/
+const VANTAGE_OQ_STATUS_LABEL = {
+	open: "Open question",
+	settled: "Answered question",
+	blocked: "Blocked question"
+};
+/**
+* The state `text` is marked with, or `null` when it carries no marker.
+*
+* Non-open wins over open, the resolution `vantage/oq-missing` has always made:
+* a question marked both 💬 and ✅ has been answered and the stale marker simply
+* has not been cleared yet, so treating it as open would re-open a ruling.
+*/
+function vantageOqStatus(text) {
+	if (text.includes(VANTAGE_OQ_STATUS.settled)) return "settled";
+	if (text.includes(VANTAGE_OQ_STATUS.blocked)) return "blocked";
+	if (text.includes(VANTAGE_OQ_STATUS.open)) return "open";
+	return null;
+}
 const STYLE_KEYS = {
 	tone: VANTAGE_TONES,
 	emphasis: VANTAGE_EMPHASIS,
@@ -589,7 +641,7 @@ const HEADING_DEPTHS = /* @__PURE__ */ new Map([
 /**
 * Key → hast property, for the keys that treat a whole run.
 *
-* A camelCase hast property serialises to the kebab-case attribute, so
+* A camelCase hast property serializes 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
@@ -624,11 +676,11 @@ 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`
+* the sanitizer deletes them — and the sanitizer'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
+* on the other side of the sanitizer, which is the same reason `rehypeSlug` is
 * registered there (`pipeline.ts`).
 */
 const OQ_ID_PROPERTY = "dataVantageOqId";
@@ -660,7 +712,7 @@ const MAX_LEANING = 500;
 * 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
+* sanitizer, so letting it change a directive's meaning would make behavior
 * depend on something no reader can see.
 */
 function isSkippable(node) {
@@ -712,7 +764,7 @@ function accepts(name, key, value) {
 * 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
+* `<figure>`, against the 40px a neighbor 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.
 *
@@ -894,7 +946,7 @@ function classNames(node) {
 * 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
+* pre-as-scope branch on it, and the sanitizer strips the `math-display` that
 * `remark-math` also emits (measured — a stamped fence arrives here with
 * `className: ["language-math"]` alone).
 */
@@ -1048,7 +1100,7 @@ const COLLAPSE_GROUP_ID = /^[0-9]+$/;
 * `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 —
+* for the sanitizer. 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.
@@ -1319,7 +1371,7 @@ async function renderMarkdown(content, options = {}) {
 *
 * 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
+* can share the *same* syntax the viewer honors instead of reimplementing it
 * and drifting.
 */
 /**
@@ -1436,7 +1488,7 @@ const DOC_STATUSES = [
 /** Every key this build knows under `vantage:`. Closed. */
 const VANTAGE_FRONTMATTER_KEYS = ["status-chip"];
 /**
-* Which tone each status borrows its colours from.
+* Which tone each status borrows its colors 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
@@ -1543,6 +1595,49 @@ function currentMermaidTheme() {
 	return typeof document !== "undefined" && document.documentElement.classList.contains("dark") ? "dark" : "default";
 }
 /**
+* The attribute on `<html>` naming the active color theme. Absent means the
+* built-in look. The app sets it only once the theme's stylesheet has loaded,
+* so a reader of this attribute can trust the theme's variables are in effect.
+*/
+const COLOR_THEME_ATTRIBUTE = "data-vantage-theme";
+/**
+* The attribute on `<html>` saying where the active theme came from: `"user"`
+* for a stylesheet in the reader's themes directory, `"built-in"` for one the
+* app ships. Set with {@link COLOR_THEME_ATTRIBUTE}, and absent with it.
+*
+* It exists because an id alone is not a palette. A user theme may share a
+* built-in's id — that is how a reader tweaks one — and the app applies the
+* stored built-in synchronously, then swaps in the same-id user file once
+* /api/themes answers. Keyed on the id, the diagrams drawn in between kept the
+* built-in's colors: the key did not change, so neither the cache nor
+* `useSyncExternalStore` saw a reason to redraw.
+*/
+const COLOR_THEME_SOURCE_ATTRIBUTE = "data-vantage-theme-source";
+/** The active color theme's id, or `""` for the built-in look. */
+function currentColorTheme() {
+	if (typeof document === "undefined") return "";
+	return document.documentElement.getAttribute("data-vantage-theme") ?? "";
+}
+/**
+* Everything a rendered diagram's colors depend on, as one string: the
+* light/dark mode, plus the color theme when one is active.
+*
+* A diagram is baked at render time, so anything that changes its colors has
+* to change this key — it is what the SVG cache and the loader's "configured
+* for" check compare. Under the built-in look it is exactly the mode name,
+* which is what both keyed on before color themes existed.
+*/
+function currentMermaidPalette() {
+	const theme = currentColorTheme();
+	if (!theme) return currentMermaidTheme();
+	const user = document.documentElement.getAttribute(COLOR_THEME_SOURCE_ATTRIBUTE) === "user";
+	return `${currentMermaidTheme()} ${theme}${user ? " user" : ""}`;
+}
+/** The mermaid theme name a palette key was built from. */
+function mermaidThemeOf(palette) {
+	return palette.startsWith("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.
 */
@@ -1566,27 +1661,108 @@ const THEME_VARIABLES = {
 		edgeLabelBackground: "#f8fafc"
 	}
 };
+/**
+* Where each variable comes from under a color theme: the palette step the
+* built-in value was chosen from. The hex above IS that step in Tailwind's own
+* palette, so reading the step back out of the page gives the same diagram
+* under the built-in look and the theme's colors under any other.
+*/
+const THEME_SOURCES = {
+	dark: {
+		background: "--color-slate-800",
+		mainBkg: "--color-slate-700",
+		nodeBorder: "--color-slate-400",
+		nodeTextColor: "--color-slate-100",
+		lineColor: "--color-slate-400",
+		textColor: "--color-slate-200",
+		edgeLabelBackground: "--color-slate-800"
+	},
+	default: {
+		background: "--color-slate-50",
+		mainBkg: "--color-slate-100",
+		nodeBorder: "--color-slate-500",
+		nodeTextColor: "--color-slate-900",
+		lineColor: "--color-slate-500",
+		textColor: "--color-slate-800",
+		edgeLabelBackground: "--color-slate-50"
+	}
+};
 function mermaidThemeVariables(theme) {
-	return THEME_VARIABLES[theme];
+	const fixed = THEME_VARIABLES[theme];
+	if (!currentColorTheme()) return fixed;
+	const out = {};
+	for (const [key, hex] of Object.entries(fixed)) out[key] = resolveCssColor(THEME_SOURCES[theme][key]) ?? hex;
+	return out;
+}
+/**
+* A custom property's color as `#rrggbb`, or `null` when it cannot be read.
+*
+* Mermaid wants hex at `initialize()` time, and a theme's value can be any CSS
+* color — `oklch()`, `color-mix()`, a `var()` of another variable. So the
+* browser does the work: a probe element resolves the property to a computed
+* color, and a 1×1 canvas turns that into sRGB bytes whatever syntax it came
+* back in. No canvas (jsdom, a locked-down embed) is `null`, and the caller
+* falls back to the built-in value.
+*
+* A property nobody declared is `null` too, and has to be checked for up
+* front: `color: var(--unset)` is invalid at computed-value time, so the probe
+* *inherits* its color instead — the page's text color, which the canvas
+* would dutifully turn into a plausible hex and mermaid would paint every node
+* box with.
+*/
+function resolveCssColor(property) {
+	if (typeof document === "undefined") return null;
+	if (!getComputedStyle(document.documentElement).getPropertyValue(property).trim()) return null;
+	const probe = document.createElement("span");
+	probe.style.display = "none";
+	probe.style.color = `var(${property})`;
+	document.documentElement.appendChild(probe);
+	const computed = getComputedStyle(probe).color;
+	probe.remove();
+	if (!computed) return null;
+	const ctx = pixelContext();
+	if (!ctx) return null;
+	ctx.fillStyle = computed;
+	ctx.fillRect(0, 0, 1, 1);
+	const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+	return `#${[
+		r,
+		g,
+		b
+	].map((v) => v.toString(16).padStart(2, "0")).join("")}`;
+}
+/** A 1×1 2D context to read a color back from, or `null` where there is none. */
+function pixelContext() {
+	try {
+		const canvas = document.createElement("canvas");
+		canvas.width = canvas.height = 1;
+		return canvas.getContext("2d", { willReadFrequently: true });
+	} catch {
+		return null;
+	}
 }
 //#endregion
 //#region src/mermaidCache.ts
 const svgCache = /* @__PURE__ */ new Map();
-const cacheKey = (code, theme) => `${theme}${code}`;
+const cacheKey = (code, theme) => `${theme}\u0000${code}`;
 /** The SVG for this fence in the theme the page is currently asking for. */
-function getCachedSvg(code, theme = currentMermaidTheme()) {
+function getCachedSvg(code, theme = currentMermaidPalette()) {
 	return svgCache.get(cacheKey(code, theme));
 }
-function setCachedSvg(code, svg, theme = currentMermaidTheme()) {
+function setCachedSvg(code, svg, theme = currentMermaidPalette()) {
 	svgCache.set(cacheKey(code, theme), svg);
 }
 //#endregion
 //#region src/mermaidLoader.ts
 let mermaidInstance = null;
 let mermaidLoading = null;
-/** The theme the loaded instance was last configured for, `null` until loaded. */
+/**
+* The palette key (`currentMermaidPalette`) the loaded instance was last
+* configured for, `null` until loaded.
+*/
 let configuredTheme = null;
-function configure(m, theme) {
+function configure(m, palette) {
+	const theme = mermaidThemeOf(palette);
 	m.initialize({
 		startOnLoad: false,
 		theme,
@@ -1594,7 +1770,7 @@ function configure(m, theme) {
 		securityLevel: "strict",
 		suppressErrorRendering: true
 	});
-	configuredTheme = theme;
+	configuredTheme = palette;
 }
 /**
 * The mermaid module, configured for the theme the page is asking for *now*.
@@ -1608,19 +1784,19 @@ function configure(m, theme) {
 * served instead (`mermaidCache.ts`).
 */
 async function getMermaid() {
-	const theme = currentMermaidTheme();
+	const theme = currentMermaidPalette();
 	if (mermaidInstance) {
 		if (configuredTheme !== theme) configure(mermaidInstance, theme);
 		return mermaidInstance;
 	}
 	if (!mermaidLoading) mermaidLoading = import("mermaid").then((mod) => {
 		const m = mod.default;
-		configure(m, currentMermaidTheme());
+		configure(m, currentMermaidPalette());
 		mermaidInstance = m;
 		return m;
 	});
 	const loaded = await mermaidLoading;
-	const wanted = currentMermaidTheme();
+	const wanted = currentMermaidPalette();
 	if (configuredTheme !== wanted) configure(loaded, wanted);
 	return loaded;
 }
@@ -1822,7 +1998,7 @@ vantage:
   status-chip: true # show \`status\` as a chip above the metadata card
 ---
 \`\`\`
-- **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\`.
+- **Nothing may sit above the opening delimiter** — not a blank line, not an editorial comment, not a \`<!-- vantage: … -->\` directive. Frontmatter is recognized 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 — \`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.
@@ -1874,7 +2050,7 @@ 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 — 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 color — 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** — 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.
@@ -1900,6 +2076,8 @@ The steps below predate the rewrite.
 `;
 //#endregion
 exports.ALERT_TITLES = ALERT_TITLES;
+exports.COLOR_THEME_ATTRIBUTE = COLOR_THEME_ATTRIBUTE;
+exports.COLOR_THEME_SOURCE_ATTRIBUTE = COLOR_THEME_SOURCE_ATTRIBUTE;
 exports.DIRECTIVE_NAMES = DIRECTIVE_NAMES;
 exports.DIRECTIVE_VOCABULARY = DIRECTIVE_VOCABULARY;
 exports.DOC_STATUSES = DOC_STATUSES;
@@ -1912,12 +2090,15 @@ exports.VANTAGE_COLLAPSED = VANTAGE_COLLAPSED;
 exports.VANTAGE_EMPHASIS = VANTAGE_EMPHASIS;
 exports.VANTAGE_FRONTMATTER_KEYS = VANTAGE_FRONTMATTER_KEYS;
 exports.VANTAGE_OQ_HOST_TARGETS = VANTAGE_OQ_HOST_TARGETS;
+exports.VANTAGE_OQ_STATUS = VANTAGE_OQ_STATUS;
+exports.VANTAGE_OQ_STATUS_LABEL = VANTAGE_OQ_STATUS_LABEL;
 exports.VANTAGE_RUNS = VANTAGE_RUNS;
 exports.VANTAGE_SENTINEL = VANTAGE_SENTINEL;
 exports.VANTAGE_TONES = VANTAGE_TONES;
 exports.buildPipeline = buildPipeline;
 exports.buildRemarkPlugins = buildRemarkPlugins;
 exports.clearLineAnchorHighlights = clearLineAnchorHighlights;
+exports.currentColorTheme = currentColorTheme;
 exports.hasVantageSentinel = hasVantageSentinel;
 exports.isDocStatus = isDocStatus;
 exports.parseFrontmatter = parseFrontmatter;
@@ -1933,5 +2114,6 @@ exports.renderMermaidBlocks = renderMermaidBlocks;
 exports.resolveLinks = resolveLinks;
 exports.sanitizeSchema = sanitizeSchema;
 exports.scrollToLineAnchor = scrollToLineAnchor;
+exports.vantageOqStatus = vantageOqStatus;
 
 //# sourceMappingURL=index.cjs.map