vantage-md 0.6.1 → 0.7.0

package/dist/prose.css

@@ -141,7 +141,7 @@
    `directives.css` draws a toned section's vertical rule, and clipping it breaks
    the rule for the height of every code fence. See the note there beside
    `[data-vantage-tone]:is(pre, hr)`. Keeping this unconditional rather than
-   scoping it to toned fences means one behaviour for every fence, and no
+   scoping it to toned fences means one behavior for every fence, and no
    specificity tie between the two stylesheets. */
 .vantage-prose pre code {
   background: none;

package/dist/react.cjs

@@ -121,14 +121,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
@@ -142,7 +142,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.
@@ -364,7 +364,7 @@ VANTAGE_ANCHOR_TARGETS.filter((tag) => tag !== "pre" && tag !== "table");
 * 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.
 */
@@ -522,7 +522,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
@@ -557,11 +557,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";
@@ -593,7 +593,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) {
@@ -645,7 +645,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.
 *
@@ -827,7 +827,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).
 */
@@ -981,7 +981,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.
@@ -1208,6 +1208,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.
 */
@@ -1231,27 +1274,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,
@@ -1259,7 +1383,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*.
@@ -1273,19 +1397,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;
 }
@@ -1588,7 +1712,7 @@ function DiagramModal({ isOpen, onClose, children }) {
 }
 /**
 * The palette the page is asking for, re-read whenever `<html>`'s class list
-* changes.
+* or its color-theme attribute changes.
 *
 * A diagram is an SVG baked at render time, so unlike everything else on the
 * page it does not restyle when the theme flips — it has to be drawn again. The
@@ -1605,14 +1729,19 @@ function subscribeToTheme(onChange) {
 	const observer = new MutationObserver(onChange);
 	observer.observe(document.documentElement, {
 		attributes: true,
-		attributeFilter: ["class"]
+		attributeFilter: [
+			"class",
+			COLOR_THEME_ATTRIBUTE,
+			COLOR_THEME_SOURCE_ATTRIBUTE
+		]
 	});
 	return () => observer.disconnect();
 }
 /** Server render has no `<html>` to read, and no diagram to draw either. */
 const serverTheme = () => "default";
+/** The palette key the page is asking for (see `currentMermaidPalette`). */
 function useMermaidTheme() {
-	return (0, react.useSyncExternalStore)(subscribeToTheme, currentMermaidTheme, serverTheme);
+	return (0, react.useSyncExternalStore)(subscribeToTheme, currentMermaidPalette, serverTheme);
 }
 const MermaidDiagramInner = ({ code }) => {
 	const theme = useMermaidTheme();
@@ -1754,7 +1883,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
@@ -1873,7 +2002,7 @@ function readStatusChip(frontmatter, raw, issues) {
 *
 * Styling comes entirely from `styles/directives.css` — `.vantage-chip` for the
 * geometry, shared by selector list with the `badge=` pseudo-element, and
-* `.vantage-chip--<tone>` for the colours. No Tailwind utility appears here, so
+* `.vantage-chip--<tone>` for the colors. No Tailwind utility appears here, so
 * the chip survives in a consumer that does not run Tailwind and no class name
 * has to be discovered by a content scan.
 */
@@ -1988,7 +2117,7 @@ const FrontmatterDisplay = (0, react.memo)(FrontmatterDisplayInner);
 *
 * 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.
 */
 /**
@@ -2305,10 +2434,6 @@ const MarkdownViewer = (0, react.memo)(MarkdownViewerInner, (prevProps, nextProp
 //#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):
@@ -2325,7 +2450,7 @@ const MarkdownViewer = (0, react.memo)(MarkdownViewerInner, (prevProps, nextProp
 * 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;
+	const { gfm = true, math = true, highlight = true, sourceLines = true, sanitize = true, frontmatter: parseFm = true, tree } = options;
 	let parsed;
 	if (parseFm) parsed = parseFrontmatter(content);
 	else parsed = {
@@ -2342,7 +2467,8 @@ async function renderMarkdown(content, options = {}) {
 		sanitize,
 		bodyLineOffset: parsed.bodyLineOffset
 	});
-	const result = await (0, unified.unified)().use(remark_parse.default).use(remarkPlugins).use(remark_rehype.default, { allowDangerousHtml: true }).use(rehypePlugins).use(rehype_stringify.default).process(parsed.body);
+	const processor = (0, unified.unified)().use(remark_parse.default).use(remarkPlugins).use(remark_rehype.default, { allowDangerousHtml: true }).use(rehypePlugins).use(rehype_stringify.default);
+	const result = tree === void 0 ? String(await processor.process(parsed.body)) : processor.stringify(await processor.run(tree, parsed.body), parsed.body);
 	return {
 		html: String(result),
 		frontmatter: parsed.frontmatter,