vantage-md 0.1.3 → 0.5.4

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { Root } from 'hast';
-import { Plugin } from 'unified';
+import { Plugin, PluggableList } from 'unified';
 import { defaultSchema } from 'rehype-sanitize';
 
 /**
@@ -33,7 +33,7 @@ interface RenderResult {
  *
  * Features (all enabled by default):
  * - GitHub Flavored Markdown (tables, strikethrough, task lists)
- * - KaTeX math rendering ($$...$$ blocks)
+ * - KaTeX math rendering, inline and block ($$...$$ only; single $ is not a delimiter)
  * - Syntax highlighting via highlight.js
  * - `data-source-line` attributes for line anchors
  * - XSS sanitization
@@ -54,22 +54,274 @@ declare function renderMarkdown(content: string, options?: RenderOptions): Promi
  * each rendered block a traceable line number from the source.
  */
 
-declare const rehypeSourceLines: Plugin<[], Root>;
+interface RehypeSourceLinesOptions {
+    /**
+     * Lines stripped off the front of the file before parsing — frontmatter,
+     * essentially. Added to every emitted line number so `data-source-line`
+     * names a line in the *file* rather than in the parsed body, which is what
+     * a `#L42` link written against the file means. Defaults to 0.
+     */
+    offset?: number;
+}
+declare const rehypeSourceLines: Plugin<[RehypeSourceLinesOptions?], Root>;
 
 /**
- * Framework-agnostic line anchor utilities.
- * Parse GitHub-style line anchors (#L42, #L42-L50) and scroll/highlight
- * matching elements in a container.
+ * Rehype plugin that compiles `<!-- vantage: … -->` directives into
+ * `data-vantage-*` attributes on the block that follows them.
+ *
+ * It has to run between `rehype-raw` — which turns the comment into a hast node
+ * — and `rehype-sanitize`, which deletes every comment node. That is the only
+ * window in which the information exists (`docs/reference/inline-markup.md`, "Where the plugin runs"),
+ * and `pipeline.ts` is where the slot is spelled out.
+ *
+ * The grammar and the vocabulary live in `./vantageDirectives.js`, which the
+ * CLI checker imports too: one parser, two callers, so a directive cannot mean
+ * one thing in the viewer and another in the tool that validates it (D5).
+ *
+ * Nothing here throws and nothing logs. An unknown name drops the whole
+ * directive, an unknown key or value drops that pair only, and a directive with
+ * no block after it does nothing at all (P3/D2/D6). The comment node is left
+ * where it is: the sanitiser removes it, which is why no Vantage-specific
+ * markup other than these attributes ever reaches the DOM.
  */
+
+declare const rehypeVantageDirectives: Plugin<[], Root>;
+
 /**
- * Parse a GitHub-style line anchor hash.
- * Supports: #L42, #L42-L50, #L42-50
- * Returns null if the hash is not a line anchor.
+ * The directive grammar and the closed vocabulary — one parser, no renderer.
+ *
+ * A Vantage directive is an ordinary HTML comment carrying a `vantage:`
+ * sentinel: `<!-- vantage: section tone=warning -->`. GitHub drops it, every
+ * other Markdown renderer drops it, and Vantage compiles it into
+ * `data-vantage-*` attributes on the block that follows
+ * (`rehypeVantageDirectives`). See `docs/reference/inline-markup.md`, "The carrier and the grammar".
+ *
+ * This module is deliberately **zero-dependency — not even a type import**, and
+ * it knows nothing about hast. Two callers need it and only one of them has a
+ * tree: the rehype plugin stamps attributes, and the `vantage-check` CLI
+ * validates directives with no rendering at all, importing this file by
+ * relative path. A checker with its own copy of the grammar is a checker that
+ * disagrees with the renderer, which is the failure D5 names.
+ *
+ * Everything here is a pure function of a string. Nothing throws, nothing logs
+ * (P3): a comment that is not a directive is `null`, and a comment that carries
+ * the sentinel but does not parse is `malformed` with a reason only the checker
+ * reads.
+ */
+/**
+ * The mandatory sentinel — the full word, never a terser `v:`.
+ *
+ * It is what keeps an ordinary `<!-- TODO: rewrite this -->` from being parsed
+ * as markup, and it makes the common case a prefix test rather than a grammar
+ * attempt (Ledger OQ-1).
+ */
+declare const VANTAGE_SENTINEL = "vantage:";
+/**
+ * The closed name set. An unknown name drops the **whole** directive: there is
+ * no target semantics without a name. An unknown key or value drops only that
+ * pair (D2 is per-key).
+ *
+ * Position picks the target; the name picks the extent. `section` before a
+ * heading reaches the heading's whole section, `block` reaches one block, and
+ * `oq` marks one answerable question. The name cannot disagree with position —
+ * it only says how far the stamp reaches — so §4.2's refusal of a `scope=` key
+ * stands.
+ */
+declare const DIRECTIVE_NAMES: readonly ["section", "block", "oq"];
+/**
+ * The `tone` vocabulary: GitHub's alert words plus `muted`.
+ *
+ * Semantic, never chromatic (P2, Ledger OQ-3). A document says what a section
+ * *is*; the theme decides what that looks like, which is what lets one document
+ * render correctly in light, in dark, and in themes that do not exist yet.
+ */
+declare const VANTAGE_TONES: readonly ["note", "tip", "important", "warning", "caution", "muted"];
+/** How much the block should pull the eye — separate from `tone` on purpose. */
+declare const VANTAGE_EMPHASIS: readonly ["strong", "normal", "quiet"];
+/** A small chip beside the heading. */
+declare const VANTAGE_BADGES: readonly ["draft", "stale", "blocked", "done", "wip"];
+/**
+ * `collapsed` is a token, not a flag: `false` is the default written down.
+ *
+ * It stamps nothing on its own. Its one real effect is overriding a
+ * `collapsed=true` earlier in the same merged directive run — last key wins — so
+ * it is in the vocabulary rather than being an unknown value that drops. It
+ * cannot cancel an *enclosing* collapsed section: a nested heading is a hidden
+ * member of the outer group by design (A3), and the outer run is stamped before
+ * any inner directive has been resolved.
+ */
+declare const VANTAGE_COLLAPSED: readonly ["true", "false"];
+/**
+ * Where a block sits in a stamped run, so section-wide CSS can join its members
+ * without an adjacent-sibling combinator.
+ *
+ * Not cosmetic. Review mode inserts comment cards as siblings *inside* a
+ * stamped run (`useReviewHighlights`), so `[tone] + [tone]` severs at every
+ * commented paragraph and bleeds across the boundary between two adjacent runs
+ * of different tone. An attribute survives both.
+ */
+declare const VANTAGE_RUNS: readonly ["start", "middle", "end", "only"];
+/**
+ * The tags a `<!-- vantage: oq … -->` directive actually yields a *button* on —
+ * `VANTAGE_ANCHOR_TARGETS` minus `pre` and `table`, written as an explicit
+ * subtraction so the narrowing stays visible.
+ *
+ * Anchorable and button-hosting are different questions, and this is the second
+ * one. A comment *can* be anchored on a `<pre>` or a `<table>` — both are in
+ * `ANCHOR_TAGS` — but neither can hold the affordance: inside a `<pre>` the
+ * button renders as part of the code, and a `<button>` child of `<table>` is not
+ * valid HTML at all, so the parser hoists it out.
+ *
+ * Both consumers read it from here: `OQ_HOST_TAGS` in the app's
+ * `useOpenQuestionButtons`, and the `oq` branch of the checker's
+ * `vantage/orphan`. They were two hand-written lists that disagreed — the
+ * checker called an `oq` above a fence fine while the app rendered no button
+ * and said nothing, which is the D5 break this module exists to prevent.
+ */
+declare const VANTAGE_OQ_HOST_TARGETS: ("p" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "li" | "blockquote")[];
+/** `null` for a key the grammar accepts but no closed set covers. */
+type KeyVocabulary = readonly string[] | null;
+/** The keys one directive name accepts. `undefined` for an unknown key. */
+type KeyTable = Readonly<Record<string, KeyVocabulary | undefined>>;
+/** The whole vocabulary. `undefined` for an unknown directive name. */
+type DirectiveVocabulary = Readonly<Record<string, KeyTable | undefined>>;
+/**
+ * Name → key → the closed value set for that key.
+ *
+ * `section` and `block` share their keys: they differ in *extent*, not in what
+ * they can say. `oq`'s two keys are the design's only values with no closed set
+ * — `id` is a token an author chose and `leaning` is a sentence (§8.3) — so
+ * neither can be value-allowlisted, which is recorded here as `null` rather
+ * than left to a caller to guess.
+ */
+declare const DIRECTIVE_VOCABULARY: DirectiveVocabulary;
+interface DirectivePair {
+    key: string;
+    /** The value with quotes stripped, if it was quoted. */
+    value: string;
+    /** Offset of `key` within the comment's inner text. */
+    keyOffset: number;
+    /** Offset of the value token — opening quote included — within it. */
+    valueOffset: number;
+    quoted: boolean;
+}
+interface ParsedDirective {
+    kind: "directive";
+    name: string;
+    /** Offset of `name` within the comment's inner text. */
+    nameOffset: number;
+    /** In written order, duplicates included: a checker reports them, the
+     * renderer resolves them last-one-wins. */
+    pairs: DirectivePair[];
+}
+/** Sentinel present, grammar not satisfied. The renderer ignores `reason`. */
+interface MalformedDirective {
+    kind: "malformed";
+    /** One clause a checker can quote verbatim, lowercase and unpunctuated. */
+    reason: string;
+    /** Offset of the first character the parse could not use. */
+    offset: number;
+}
+type DirectiveParse = ParsedDirective | MalformedDirective | null;
+/**
+ * The cheap prefix test. Runs first on every comment in every document, so an
+ * ordinary editorial comment never reaches the tokenizer.
+ *
+ * Note `<!--- vantage: x -->` is *not* a directive: its inner text begins with
+ * the extra `-`, and the sentinel must be the first thing in the comment.
+ */
+declare function hasVantageSentinel(comment: string): boolean;
+/**
+ * Parse one comment's **inner** text — the value of a hast `comment` node, with
+ * `<!--` and `-->` already stripped. `null` means "no sentinel, not ours".
+ *
+ * Hand-rolled rather than one regular expression, because a repeated capture
+ * group keeps only its last match and the checker needs an offset per token to
+ * point at the character that broke.
+ */
+declare function parseVantageDirective(comment: string): DirectiveParse;
+
+/**
+ * The one definition of the Vantage remark/rehype chain.
+ *
+ * Three call sites render Markdown — `renderMarkdown` (string in, HTML out,
+ * which is what the CLI checker runs), the app's `<MarkdownViewer>`, and this
+ * package's exported `<MarkdownViewer>` — and each one used to hand-write the
+ * same plugin list in the same order. Three copies kept in sync by hand is how
+ * a plugin lands in the viewer and not in the checker: a document that styles
+ * in the app and renders bare through the tool that is supposed to validate it,
+ * with no error anywhere.
+ *
+ * The order is load-bearing, not incidental:
+ *
+ * - `rehypeRaw` first: `remark-rehype` runs with `allowDangerousHtml: true`,
+ *   so raw HTML is still a string until this plugin parses it.
+ * - `rehypeSourceLines` before `rehypeSanitize`: `data-source-line` has to be
+ *   an allowlisted attribute on an element the sanitiser keeps.
+ * - `rehypeSlug`, `rehypeHighlight` and `rehypeKatex` after `rehypeSanitize`.
+ *   For `rehypeSlug` this is not a preference: the sanitiser's default schema
+ *   clobbers `id` with the prefix `user-content-`, so slugging before it turns
+ *   every `#heading` link in every document into a dead anchor. For the other
+ *   two it means their output is trusted rather than filtered — KaTeX emits
+ *   inline `style` on nearly every glyph.
+ *
+ * Anything that reads HTML comments must sit between `rehypeRaw` and
+ * `rehypeSanitize`: before `rehypeRaw` there are no comment nodes, and
+ * `rehypeSanitize` deletes them. `rehypeVantageDirectives` is what occupies
+ * that slot, and it is registered unconditionally — a renderer that skipped it
+ * would disagree with the others about what a document means.
+ */
+
+interface PipelineOptions {
+    /** GFM tables, strikethrough, task lists (default: true) */
+    gfm?: boolean;
+    /** KaTeX math, `$$…$$` only (default: true) */
+    math?: boolean;
+    /** Syntax highlighting via highlight.js (default: true) */
+    highlight?: boolean;
+    /** `data-source-line` attributes for line anchors (default: true) */
+    sourceLines?: boolean;
+    /** XSS sanitisation (default: true) */
+    sanitize?: boolean;
+    /**
+     * Lines the frontmatter consumed, added to every emitted line number so
+     * `data-source-line` names a line in the *file* rather than in the parsed
+     * body — which is what a `#L42` link written against the file means.
+     * Defaults to 0. Ignored when `sourceLines` is false.
+     */
+    bodyLineOffset?: number;
+}
+interface Pipeline {
+    remarkPlugins: PluggableList;
+    rehypePlugins: PluggableList;
+}
+/**
+ * The mdast half of the chain. Exported on its own because there is a real
+ * mdast-only consumer: the CLI checker parses documents without ever running
+ * rehype (`packages/vantage-check/src/core/document.ts`), and it has to parse
+ * them exactly the way the viewer does.
+ */
+declare function buildRemarkPlugins(options?: PipelineOptions): PluggableList;
+/**
+ * Both halves from one options object.
+ *
+ * This is what every renderer calls. It takes one object rather than exposing
+ * the two builders because `math` spans both halves — `remark-math` parses the
+ * delimiters, `rehype-katex` renders the result — and two calls are two places
+ * to forget the second one.
+ *
+ * Returns fresh arrays on every call and reads no module-level state; keep it
+ * that way, so a plugin in the chain cannot become a function of how many times
+ * the chain has been built.
+ */
+declare function buildPipeline(options?: PipelineOptions): Pipeline;
+
+/**
+ * Framework-agnostic line anchor utilities.
+ * Scroll to and highlight the elements a GitHub-style line anchor
+ * (#L42, #L42-L50) names. The parsing half lives in lineAnchor.ts, which has
+ * no DOM dependency.
  */
-declare function parseLineAnchor(hash: string): {
-    start: number;
-    end: number;
-} | null;
 /**
  * Clear all line anchor highlights from a container.
  */
@@ -83,15 +335,72 @@ declare function clearLineAnchorHighlights(container: HTMLElement): void;
  */
 declare function scrollToLineAnchor(container: HTMLElement, hash: string): (() => void) | null;
 
+/**
+ * Parsing for GitHub-style line anchors, with no DOM in sight.
+ *
+ * Split out from scrollToLineAnchor.ts so that non-browser consumers — the
+ * `vantage-check` CLI, which validates `#L42` links against the file on disk —
+ * can share the *same* syntax the viewer honours instead of reimplementing it
+ * and drifting.
+ */
+/**
+ * Parse a GitHub-style line anchor hash.
+ * Supports: #L42, #L42-L50, #L42-50
+ * Returns null if the hash is not a line anchor.
+ */
+declare function parseLineAnchor(hash: string): {
+    start: number;
+    end: number;
+} | null;
+
 /**
  * Frontmatter parser for YAML (---) and TOML (+++) delimited content.
  * Works in both browser and server environments.
  */
 type FrontmatterFormat = "yaml" | "toml" | "none";
+/**
+ * Why a document that *looks* like it has frontmatter ended up without any.
+ *
+ * The parser deliberately never throws: a document whose frontmatter is broken
+ * still renders, with the block treated as body text. That is the right
+ * behaviour for a viewer and the wrong one for an author, who gets no signal
+ * at all — so the reason is recorded here for anything that wants to report it
+ * (`vantage-check` does; see its frontmatter rules).
+ *
+ * - `unterminated` — an opening delimiter with no closing one.
+ * - `invalid` — the block did not parse; `message` is the parser's own words,
+ *   and `line`/`column` are 1-based *within the block* when it said.
+ * - `not-a-mapping` — it parsed, but to a string or a list rather than a table
+ *   of fields, which is not something a metadata card can render.
+ */
+interface FrontmatterProblem {
+    kind: "unterminated" | "invalid" | "not-a-mapping";
+    /** The delimiter the document opened with. */
+    delimiter: string;
+    message?: string;
+    line?: number;
+    column?: number;
+}
 interface ParsedFrontmatter {
     frontmatter: Record<string, unknown>;
     body: string;
     format: FrontmatterFormat;
+    /**
+     * How many source lines the frontmatter block consumed — the shift between a
+     * line number in `body` and the same line in the original file:
+     * `fileLine = bodyLine + bodyLineOffset`.
+     *
+     * Anything that renders `body` and reports line numbers (line anchors, review
+     * comment anchors) has to add this back, or every number it produces points
+     * `bodyLineOffset` lines short of the text it names.
+     */
+    bodyLineOffset: number;
+    /**
+     * Set when the document opens with a frontmatter delimiter that did not
+     * yield a metadata table. Everything else in this result is unchanged —
+     * this records *why*, it does not change what rendering does.
+     */
+    problem?: FrontmatterProblem;
 }
 /**
  * Parse frontmatter from markdown content.
@@ -99,6 +408,94 @@ interface ParsedFrontmatter {
  */
 declare function parseFrontmatter(content: string): ParsedFrontmatter;
 
+/**
+ * The `vantage:` frontmatter key — file-scoped chrome (`docs/reference/inline-markup.md`, "File-scoped chrome").
+ *
+ * One reserved key at the top level of a document's frontmatter, holding the
+ * chrome that belongs to the *file* rather than to a section. Today that is one
+ * thing: whether the document's lifecycle `status:` is shown as a chip above the
+ * metadata card, instead of being buried as one row inside it.
+ *
+ * Read only at the top level, and **inert on every failure** (P3): an unknown
+ * key, a value outside the closed set, or a `vantage:` that is not a table
+ * produces no chrome, no throw and no console output. The reasons are returned
+ * as data in `issues`, for anything that wants to report them — `vantage-check`
+ * does, and it is the only signal an author gets. That split is exactly the one
+ * `FrontmatterProblem` already uses in `frontmatter.ts`: the viewer reads the
+ * value, the checker reads the reasons.
+ *
+ * Like `vantageDirectives.ts`, this module is imported by the CLI checker **by
+ * relative path**, so it must stay a pure function of already-parsed data: no
+ * hast, no React, no filesystem.
+ */
+
+/**
+ * The document lifecycle vocabulary. Closed; extending it is a code change.
+ *
+ * This is the repo's own existing set, not a new one — `styleGuide.ts` tells
+ * every agent to write `status: in-review # draft | in-review | accepted |
+ * deprecated`, and every document under `docs/` follows it. It is deliberately
+ * *not* the `badge` set (`draft stale blocked done wip`): `badge` is
+ * section-scoped workflow state, `status` is document lifecycle state, and
+ * `in-review` — the value the design doc's own only example renders — is not a
+ * badge word at all. Only `draft` is a member of both, and a token set is per key.
+ */
+declare const DOC_STATUSES: readonly ["draft", "in-review", "accepted", "deprecated"];
+type DocStatus = (typeof DOC_STATUSES)[number];
+/** Every key this build knows under `vantage:`. Closed. */
+declare const VANTAGE_FRONTMATTER_KEYS: readonly ["status-chip"];
+/**
+ * Which tone each status borrows its colours from.
+ *
+ * The chip has no palette of its own: it reuses the tone chips
+ * (`.vantage-chip--<tone>` in `styles/directives.css`), which is also what makes
+ * a `draft` chip and a `badge=draft` chip the same visual object. A map rather
+ * than a computed class name, so the whole status→tone relation is one readable
+ * table and a test can assert it covers the vocabulary.
+ */
+declare const DOC_STATUS_TONES: Readonly<Record<DocStatus, (typeof VANTAGE_TONES)[number]>>;
+/**
+ * Why something under `vantage:` produced no chrome.
+ *
+ * `status-chip-orphan` and `status-chip-disagrees` are not vocabulary errors —
+ * both values are legal — but both are the markup rot R3 is about: a chip that
+ * says something the document's own `status:` does not.
+ */
+type VantageFrontmatterIssue = {
+    kind: "not-a-table";
+    value: unknown;
+} | {
+    kind: "unknown-key";
+    key: string;
+} | {
+    kind: "bad-value";
+    key: string;
+    value: unknown;
+    legal: readonly string[];
+} | {
+    kind: "status-chip-orphan";
+    status: unknown;
+} | {
+    kind: "status-chip-disagrees";
+    chip: DocStatus;
+    status: unknown;
+};
+interface VantageFrontmatter {
+    /** The chip's text, or `undefined` for no chip. */
+    statusChip?: DocStatus;
+    /** Why something was dropped. A viewer must never read this (P3). */
+    issues: VantageFrontmatterIssue[];
+}
+/** Narrowing helper the chip and the checker both use. */
+declare function isDocStatus(value: unknown): value is DocStatus;
+/**
+ * Read the `vantage:` key out of parsed frontmatter.
+ *
+ * Pure: no module state, no mutation of the input, no logging. The same object
+ * in twice gives equal results out.
+ */
+declare function readVantageFrontmatter(frontmatter: Record<string, unknown>): VantageFrontmatter;
+
 /**
  * Sanitization schema for the rendering pipeline.
  * Allows GFM, KaTeX MathML, syntax highlighting classes, and
@@ -106,6 +503,19 @@ declare function parseFrontmatter(content: string): ParsedFrontmatter;
  */
 
 type Schema = typeof defaultSchema;
+declare const SAFE_STYLE: RegExp;
+/**
+ * Never set `allowComments` here.
+ *
+ * `hast-util-sanitize` drops comment nodes because that boolean defaults to
+ * `false` — comments are not elements, so `tagNames` has nothing to do with it.
+ * `rehypeVantageDirectives` relies on that deletion: it consumes a
+ * `<!-- vantage: … -->` comment into attributes and deliberately leaves the node
+ * for the sanitiser. Turning the switch on readmits every directive comment —
+ * valid and malformed alike — into the rendered HTML, which breaks the carrier's
+ * whole premise. `vantageDirectives.test.ts` ("leaves no comment in the rendered
+ * markup") is the guard.
+ */
 declare const sanitizeSchema: Schema;
 
 /**
@@ -187,4 +597,20 @@ interface ResolveLinkOptions {
  */
 declare function resolveLinks(html: string, options?: ResolveLinkOptions): string;
 
-export { type FrontmatterFormat, type ParsedFrontmatter, type RenderMermaidOptions, type RenderOptions, type RenderResult, type ResolveLinkOptions, clearLineAnchorHighlights, parseFrontmatter, parseLineAnchor, rehypeSourceLines, renderMarkdown, renderMermaidBlocks, resolveLinks, sanitizeSchema, scrollToLineAnchor };
+/**
+ * The canonical Vantage Markdown style guide.
+ *
+ * This string is the single source of truth for the conventions Vantage's
+ * renderer expects. Two consumers read it:
+ *
+ * - the in-app "Style Guide for Agents" modal, which shows it with a copy
+ *   button, and
+ * - the `vantage-check style-guide` command, which prints it so an agent can
+ *   fetch it without a human in the loop.
+ *
+ * Every rule stated here should be one a checker can enforce or a renderer
+ * actually cares about — if a line is neither, it does not belong.
+ */
+declare const STYLE_GUIDE = "## Markdown style guide (for Vantage viewer)\n\nWhen writing or updating markdown documents that will be viewed in Vantage, follow these conventions:\n\n### Structure\n- Use headings (## and ###) to organize content \u2014 they become navigable outline anchors.\n- Keep paragraphs focused and concise. Break up dense text with subheadings, lists, or tables.\n\n### Links and cross-references\n- **Relative paths only**: Always link relative to the *current file's directory*:\n  - Sibling in same folder: `[Other Doc](./other-doc.md)` or `[Other Doc](other-doc.md)`\n  - Subdirectory: `[Design Doc](./design/auth.md)`\n  - Parent / sibling folder: `[Overview](../overview.md)` or `[Spec](../specs/api.md)`\n- **Never use leading slashes**:\n  - \u274C `[Doc](/docs/guide.md)` (breaks web routing and multi-repo scoping)\n  - \u2705 `[Doc](../docs/guide.md)` or `[Doc](./guide.md)`\n- **Never use absolute filesystem paths or URI schemes**:\n  - \u274C `file:///workspace/docs/guide.md`, `/workspace/docs/guide.md`, `C:\\...`\n  - \u2705 `[Doc](./guide.md)` or `[Doc](../guide.md)`\n- **Always include the file extension**: Use `.md`, `.ts`, `.go`, etc. (e.g. `[Model](model.go)`).\n- **Line anchors and ranges**:\n  - Link to specific lines: `[Handler](../server/api.go#L42)` or `[Range](../server/api.go#L42-L58)`\n  - Same-file line anchor: `[See lines](#L10-L25)`\n  - Vantage scrolls to and highlights the target lines.\n- **Section anchors**:\n  - Same doc: `[Usage](#usage)`\n  - Cross-doc: `[Architecture](../overview.md#system-architecture)`\n  - Anchor slugs are lowercase, hyphenated, and punctuation-stripped.\n- **Backticks in links**: Place backticks inside the link label, not around the markdown link syntax:\n  - \u2705 `[`config.json`](./config.json)` or `[config.json](./config.json)`\n  - \u274C ``[config.json](./config.json)``\n\n### Frontmatter (Metadata)\n- Include structured metadata at the very top of docs delimited by `---` (YAML) or `+++` (TOML). Vantage renders this as a metadata card:\n```yaml\n---\ntitle: \"Feature Specification\"\nauthor: \"Agent\"\ndate: 2026-08-15\nstatus: in-review # draft | in-review | accepted | deprecated\ntags: [architecture, backend, api]\nsummary: \"Brief description of the document purpose.\"\nvantage:\n  status-chip: true # show `status` as a chip above the metadata card\n---\n```\n- **Nothing may sit above the opening delimiter** \u2014 not a blank line, not an editorial comment, not a `<!-- vantage: \u2026 -->` directive. Frontmatter is recognised only at the very first byte of the file (in Vantage, on GitHub, and in every other reader), so one line above it turns the whole block into body text: a horizontal rule followed by a heading made of the raw keys, with every field lost. `vantage-check` reports it as `frontmatter/not-at-top`.\n- **`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`.\n- **Prefer `status-chip: true`**, which shows the document's own `status:` and therefore cannot disagree with it. A literal `status-chip: accepted` is accepted too, but it is a second value that goes stale on its own \u2014 `vantage-check` reports the disagreement.\n- The chip's vocabulary is `status`'s, exactly: `draft | in-review | accepted | deprecated`, lowercase. `Draft` renders no chip at all, silently.\n\n### Mermaid diagrams\n- Use ```mermaid code blocks for flowcharts, sequence diagrams, and architecture diagrams. Vantage provides interactive zoom, pan, dark/light theme adaptation, and SVG export.\n- **Quote labels with special characters**: Always quote node labels containing parentheses, brackets, or colons to prevent syntax errors:\n```mermaid\nflowchart TD\n    client[\"Client (React SPA)\"] -->|WebSocket| srv[\"Vantage Server (Go)\"]\n    srv --> git[\"Git CLI (git diff)\"]\n```\n\n### Code blocks and diffs\n- Always tag fenced code blocks with language identifiers (`ts`, `go`, `python`, `bash`, `json`, `yaml`, `diff`, `sql`, etc.) for syntax highlighting.\n- For proposed code modifications, use ```diff blocks with `+` and `-` prefixes:\n```diff\n-const oldUrl = \"/api/v1\";\n+const newUrl = \"/api/v2\";\n```\n\n### Callouts and alerts\n- Use GitHub-style blockquote callouts for notes, tips, and warnings:\n> [!NOTE]\n> Background context or helpful explanation.\n\n> [!TIP]\n> Best practice advice or optimization suggestions.\n\n> [!IMPORTANT]\n> Key requirements or crucial information.\n\n> [!WARNING]\n> Urgent caution, breaking changes, or potential pitfalls.\n\n> [!CAUTION]\n> High-risk actions that could cause data loss or security issues.\n\n### Vantage directives (optional, and Vantage-only)\n\nVantage reads a few styling hints from ordinary HTML comments. Every other renderer \u2014 GitHub included \u2014 drops them, so a document has to read exactly the same without them: directives decorate, they never carry meaning. One goes on a line of its own, with a blank line after it, and applies to the block that follows:\n\n```markdown\n<!-- vantage: section tone=warning badge=stale -->\n\n## Migration path\n\nThe steps below predate the rewrite.\n```\n\n- **Three names**: `section` (the heading and everything under it), `block` (the one block after it), `oq` (one answerable Open Question).\n- **The keys and values are a closed set**: `tone` = `note | tip | important | warning | caution | muted`; `emphasis` = `strong | normal | quiet`; `badge` = `draft | stale | blocked | done | wip`; `collapsed` = `true | false`. Name a *tone*, never a colour \u2014 the theme decides what a warning looks like, in light mode, in dark mode, and in print.\n- **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.\n- **Anything outside those sets is silently ignored** \u2014 nothing breaks, and nothing styles either. Run `vantage-check` on the document: the `vantage/*` rules are the only thing that will ever tell you a directive did nothing.\n- **Always close the comment with `-->`.** Never `--!>`, and never leave it open: Markdown reads every line below an unclosed `<!--` as part of the comment, and the whole rest of the document vanishes from the page. For the same reason `-->` cannot appear *inside* a value \u2014 it ends the comment early and spills the remainder into the page as literal text.\n- **In a list, indent the directive inside the item**, with blank lines around it (below). At the start of a line between two items it ends the list and starts a second one, which changes the numbering and the spacing in every renderer \u2014 the one thing a directive must never do.\n- **A `leaning` restates the leaning; it is never \"yes\".** The one-click button in review mode files that text as a review comment, and the comment is all the agent reading it has \u2014 nobody remembers which button was clicked. `leaning=\"Yes\"` beside a two-branch question is a support ticket.\n\n```markdown\n1. **OQ-9: Queue position on re-entry.**\n\n   <!-- vantage: oq id=OQ-9 leaning=\"Back of the queue \u2014 the fix might interact with what merged while it was out.\" -->\n\n   _Leaning:_ Back of the queue.\n```\n\n### Tables, task lists, and math\n- **Tables**: Use standard markdown tables for structured comparisons and schemas.\n- **Task lists**: Use `- [ ]` and `- [x]` for actionable checklists and status tracking.\n- **LaTeX Math**: Use `$$...$$` for *all* KaTeX math \u2014 display blocks (`$$` alone on its own lines) and inline alike (`$$E = mc^2$$` mid-sentence).\n  - Single dollars are **not** math delimiters: `$HOME` and `$100` stay literal, so prose and shell snippets are safe to write as-is.\n";
+
+export { DIRECTIVE_NAMES, DIRECTIVE_VOCABULARY, DOC_STATUSES, DOC_STATUS_TONES, type DirectivePair, type DirectiveParse, type DirectiveVocabulary, type DocStatus, type FrontmatterFormat, type FrontmatterProblem, type KeyTable, type KeyVocabulary, type MalformedDirective, type ParsedDirective, type ParsedFrontmatter, type Pipeline, type PipelineOptions, type RenderMermaidOptions, type RenderOptions, type RenderResult, type ResolveLinkOptions, SAFE_STYLE, STYLE_GUIDE, VANTAGE_BADGES, VANTAGE_COLLAPSED, VANTAGE_EMPHASIS, VANTAGE_FRONTMATTER_KEYS, VANTAGE_OQ_HOST_TARGETS, VANTAGE_RUNS, VANTAGE_SENTINEL, VANTAGE_TONES, type VantageFrontmatter, type VantageFrontmatterIssue, buildPipeline, buildRemarkPlugins, clearLineAnchorHighlights, hasVantageSentinel, isDocStatus, parseFrontmatter, parseLineAnchor, parseVantageDirective, readVantageFrontmatter, rehypeSourceLines, rehypeVantageDirectives, renderMarkdown, renderMermaidBlocks, resolveLinks, sanitizeSchema, scrollToLineAnchor };