vantage-md 0.6.2 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,211 @@
+# Changelog
+
+What changed in each release of Vantage, newest first.
+
+Releases before 0.7.0 are summarized one section per minor line — `0.6.x`,
+`0.5.x` — rather than one per patch release. The per-patch detail is in the
+commit log.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.7.0] - 2026-09-23
+
+Vantage now supports color themes and bookmarks, and reads per-project settings
+from `.vantage.toml`.
+
+### Added
+
+**Color themes.** Pick a palette under **Colors** in the settings menu. Six come
+with Vantage: Catppuccin, Gruvbox, Lila, Nord, Solarized, and Tokyo Night, each
+with its own light and dark variants, alongside the default look, now called
+Slate.
+
+To write your own, put a CSS file in `~/.config/vantage/themes/`. It shows up in
+the menu on the next page load, with no restart. Set `theme = "gruvbox"` in your
+config to start every browser in one. A project can suggest a theme in its
+`.vantage.toml`, and your own choice always wins. A theme with no dark colors is
+listed as "(light only)". Every built-in theme keeps its text at 3:1 contrast or
+better in both modes, checked in a real browser; your own themes aren't checked.
+Review mode's comment colors and printing still ignore the theme. See
+[Color Themes](userguide/guides/themes.md).
+
+**Bookmarks.** Click the star next to a document's name to bookmark it. Folders
+work too. Bookmarks appear in a **Starred** section above the file tree. They're
+stored in `~/.local/share/vantage/starred/` instead of in your browser, so they
+survive a restart and show up in every tab. If a bookmarked file disappears, the
+entry stays put and offers to remove itself when you open it.
+
+A project can also list the documents worth reading first in its `.vantage.toml`,
+and you can list files you always want starred in your own config. Those entries
+are marked with a pin and name the file that added them. See
+[Starred](userguide/features.md#starred).
+
+**Open questions in the contents panel.** A document's open questions now appear
+in the table of contents, under the heading they sit below, with a count next to
+**Contents**. `💬 3` means three are waiting on a decision; `💬 1 ✅ 2` means one
+is open and two are answered. Click one to jump to it. See
+[Table of Contents](userguide/features.md#table-of-contents).
+
+### Changed
+
+Settings now follow you between tabs. Before, a second tab read most settings
+once when it loaded and then drifted, so changing the theme in one tab left the
+other on the old one. `Shift+D` had the same problem inside a single tab: it
+changed the page without updating the settings menu. The sidebar and its width,
+the tree filters, the project sort order, light/dark, and the color theme all
+stay in sync now.
+
+Review mode is a deliberate exception. Two tabs are usually on different
+documents, and picking up a toggle from another tab would close the review pane
+while you're partway through a comment.
+
+### Fixed
+
+- The file pickers (`t`, `Shift+T`, `Shift+R`, `Shift+P`) reload their list every
+  time they open, and a picker that's already open keeps up with the filesystem.
+  Before, a file created after the page loaded was unfindable until you
+  reloaded.
+- A modified file's icon was too faint to read in the file tree in light mode.
+- A document that fails to load no longer moves you off the one you're reading,
+  and the error names the file you actually asked for.
+- A slow response for a document you've already navigated away from is thrown
+  away instead of replacing what you're reading.
+- `vantage-check check --config <a directory>` now says
+  `docs is a directory, not a config file` and exits 2, instead of printing a
+  stack trace.
+
+### Contributors
+
+Thanks to [@nichiflu](https://github.com/nichiflu) for the initial color-theme
+implementation.
+
+### Works well with
+
+[matt-craft](https://github.com/mschulkind-oss/matt-craft) is out — the skills I use to
+write the documents I then read in Vantage: design notes that carry their open
+questions, roadmaps, research rounds, user stories, and one for Vantage's own Markdown
+conventions. It is not part of Vantage and Vantage does not need it. If you write your
+own documents your own way, nothing here changes for you.
+
+## 0.6.x
+
+_0.6.0 – 0.6.2, September 2026._
+
+Long documents have a table of contents. The list button beside the breadcrumb
+shows the document's headings in the left margin, and the list stays put while
+you scroll. The button beside it lets the text fill the pane. The reading band
+moved to the left edge too, so the file list, the contents, and the text sit
+together.
+
+- Serving a git repository no longer makes the browser reload itself once a
+  second. Vantage's own `git status` calls rewrote `.git/index`, and the watcher
+  read that as your edit.
+- A repository cloned under one of your `source_dirs` shows up within thirty
+  seconds, with no restart. One whose directory goes away is dropped, then
+  picked back up when it returns. See
+  [Daemon Mode](userguide/guides/daemon-mode.md).
+- A port you name is bound exactly or startup fails. Only the default 8000 walks
+  to the next free port, and it tells you which one it took.
+- Images on adjacent lines render on one row, the way GitHub lays them out. A
+  README's badges used to stack into a column.
+- `vantage-check` splits a run across worker threads by default, and the report
+  reads the same either way.
+
+### Contributors
+
+Thanks to Eduardo Hidalgo ([@edus44](https://github.com/edus44)) for the table
+of contents, the Vantage favicon, and fixes to port selection and spurious
+browser reloads.
+
+## 0.5.x
+
+_0.5.0 – 0.5.10, May to September 2026._
+
+Vantage stopped being a Python server and became one Go binary. The viewer and
+the shortcuts are the same; installing it is not. You install it with `brew
+install`, `uvx vantage-md ~/notes`, or a platform archive from a release.
+`vantage serve` opens your browser, and `--no-open` stops it.
+
+- `vantage-check` is new. It runs your documents through the viewer's own
+  pipeline and reports dead links, dead anchors, broken mermaid diagrams, and
+  style problems. See [vantage-check](userguide/guides/vantage-check.md).
+- You can mark a document up with `<!-- vantage: … -->` comments that GitHub
+  ignores and Vantage reads: a status chip beside a heading, collapsible
+  sections, emphasis, and badges. GitHub's alert blocks render too.
+- Review mode was rebuilt. A comment anchors to a whole block, replies thread, a
+  rail shows where the comments are, and you can answer an open question in one
+  click. Agents reply through a `.vantage/` directory. See
+  [The `.vantage/` directory](userguide/guides/review-inbox.md).
+- The "What's New" popup, the changed-document highlight, and the jj history
+  viewer were removed.
+- `.vantageignore` and `~/.config/vantage/ignore` keep files out of the tree, and
+  the sidebar has a drag handle that remembers its width.
+
+## 0.4.x
+
+_0.4.0 – 0.4.2, April 2026._
+
+Installing Vantage got short. `uvx vantage-md ~/notes` started the server and
+opened your browser at the directory you named, and naming a file landed on that
+file with the sidebar already expanded. There was a Homebrew formula as well.
+macOS became a platform Vantage was tested on.
+
+- Review mode became per file. Turning it on for one document no longer followed
+  you to the next, and the toggle survived a reload even before you had written a
+  comment.
+- Hovering any paragraph in review mode put a button in the gutter, so you could
+  comment on a whole block without selecting text first.
+- You could edit a comment in place, from the document or from the sidebar.
+  Resolved comments collapsed into one indicator instead of asking to be
+  dismissed one at a time.
+- A comment you had just written was sometimes marked "Outdated" immediately.
+- `log_level` in the config, `VANTAGE_LOG_LEVEL` in the environment. The watcher
+  reported your inotify limits at startup and warned near the ceiling, which is
+  the usual reason live reload stops working.
+
+## 0.3.x
+
+_0.3.0 – 0.3.8, April 2026._
+
+This is the line that added review mode. You turned it on for a document,
+selected some text, and left a comment. The server stored the comments, so they
+survived a restart. When the text under a comment changed, the comment turned
+amber and said "Outdated". Every save while review mode was on snapshotted the
+previous version, so you could step back through revisions and see which
+paragraphs had changed. One button copied every comment as Markdown quotes, with
+line numbers and surrounding context, ready to paste to an agent.
+
+- Opening a project no longer waited for its file tree. The document rendered
+  first and the sidebar filled in behind it.
+- Headings got hover anchors, and `#L42` or `#L42-L50` in the URL scrolled to
+  those source lines and highlighted them.
+- You could collapse the sidebar to give the document the window, and reveal
+  hidden or gitignored files with new toggles.
+- TOML frontmatter between `+++` fences was parsed and shown, with taxonomies and
+  extra fields as tag pills.
+- A red banner with a timer appeared when the page lost its connection, so a
+  document that had stopped live-reloading said so.
+
+## 0.2.x and earlier
+
+_0.0.1 – 0.2.0, February to March 2026._
+
+Where Vantage started. It served the Markdown in your git repositories over a
+local port and reloaded the page when you saved: GitHub-flavored Markdown,
+syntax highlighting, KaTeX math, mermaid diagrams you could click to zoom,
+commit history and diffs, a fuzzy file picker on `t`, dark mode on `Shift+D`,
+vim-style scrolling, and a print stylesheet. It could also export a static site
+to host on Cloudflare Pages or S3. The server was written in Python then.
+
+- `Shift+T` searched files across every project, `P` switched projects, `r` and
+  `Shift+R` found recently modified files, and `y` copied the current file's
+  absolute path.
+- `source_dirs` in the config found every git repository under a directory, so
+  you did not have to list them one by one.
+- The project picker became a full page, with repository names, relative
+  timestamps, and a toggle between alphabetical and recent order.
+- A "What's New" popup showed the changelog the first time you opened a new
+  version. You could turn it off in settings. Vantage dropped it in 0.5.
+- A jj history and evolution viewer sat beside the git one, for Jujutsu
+  repositories. That went in 0.5 too.

package/README.md

@@ -76,7 +76,7 @@ The React component includes mermaid diagram rendering (lazy-loaded), frontmatte
 ### Your own processor, Vantage's chain
 
 `buildPipeline` returns the exact remark and rehype lists `renderMarkdown` and
-the React viewer use, in the exact order — including the sanitiser schema, and
+the React viewer use, in the exact order — including the sanitizer schema, and
 `rehypeSlug` after it, which is what keeps generated heading ids free of
 `rehype-sanitize`'s `user-content-` prefix. Use it rather than assembling the
 chain yourself; that is how a document ends up rendering differently in two
@@ -118,7 +118,7 @@ if all you want is `data-source-line`.
 
 | Entry point | Description |
 |-------------|-------------|
-| `vantage-md` | `renderMarkdown`, `buildPipeline`, `buildRemarkPlugins`, `rehypeSourceLines`, `scrollToLineAnchor`, `parseLineAnchor`, `parseFrontmatter`, `readVantageFrontmatter`, `sanitizeSchema` |
+| `vantage-md` | `renderMarkdown`, `buildPipeline`, `buildRemarkPlugins`, `rehypeSourceLines`, `scrollToLineAnchor`, `parseLineAnchor`, `parseFrontmatter`, `readVantageFrontmatter`, `sanitizeSchema`, `COLOR_THEME_ATTRIBUTE`, `COLOR_THEME_SOURCE_ATTRIBUTE`, `currentColorTheme` |
 | `vantage-md/react` | `MarkdownViewer`, `useLineAnchor`, `MermaidDiagram`, `FrontmatterDisplay`, `DocumentStatusChip` + all core exports |
 | `vantage-md/styles` | Line-anchor highlight CSS, plus the theme layer for the `data-vantage-*` directive attributes and the chrome chips (light + dark mode) |
 
@@ -132,6 +132,7 @@ if all you want is `data-source-line`.
 - **Frontmatter** — YAML (`---`) and TOML (`+++`) parsing. A reserved `vantage:` key carries file-scoped chrome: `status-chip: true` makes `FrontmatterDisplay` render the document's `status:` as a chip above the metadata card, and the reserved key itself is never shown as a metadata row
 - **Sanitization** — XSS-safe with allowlisted KaTeX/MathML elements
 - **Dark mode** — all styles support `.dark` class
+- **Color themes** — `MermaidDiagram` follows a host page's color theme. While `<html>` carries `data-vantage-theme` (`COLOR_THEME_ATTRIBUTE`), diagram colors are read from the page's `--color-slate-*` variables instead of the built-in hex, and diagrams redraw when it or `data-vantage-theme-source` (`COLOR_THEME_SOURCE_ATTRIBUTE`: `built-in` or `user`, which tells a user theme apart from the built-in it replaces under the same id) changes. `currentColorTheme()` reads the first. A page that sets neither renders exactly as before
 
 ## License
 

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