vantage-md 0.1.7 → 0.5.4

package/dist/react.d.cts

@@ -1,6 +1,6 @@
 import React, { RefObject } from 'react';
 import { Root } from 'hast';
-import { Plugin } from 'unified';
+import { Plugin, PluggableList } from 'unified';
 import { defaultSchema } from 'rehype-sanitize';
 
 /**
@@ -56,6 +56,107 @@ interface FrontmatterDisplayProps {
 }
 declare const FrontmatterDisplay: React.NamedExoticComponent<FrontmatterDisplayProps>;
 
+/**
+ * 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"];
+
+/**
+ * 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;
+
+declare const DocumentStatusChip: React.NamedExoticComponent<{
+    status: DocStatus;
+}>;
+
 /**
  * Framework-agnostic markdown -> HTML rendering pipeline.
  * Uses the same remark/rehype chain as the Vantage viewer.
@@ -87,7 +188,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
@@ -108,22 +209,98 @@ 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.
+ * 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;
 /**
- * Parse a GitHub-style line anchor hash.
- * Supports: #L42, #L42-L50, #L42-50
- * Returns null if the hash is not a line anchor.
+ * 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.
  */
@@ -137,15 +314,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.
@@ -160,6 +394,18 @@ declare function parseFrontmatter(content: string): ParsedFrontmatter;
  */
 
 type Schema = typeof defaultSchema;
+/**
+ * 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;
 
 /**
@@ -241,4 +487,4 @@ interface ResolveLinkOptions {
  */
 declare function resolveLinks(html: string, options?: ResolveLinkOptions): string;
 
-export { FrontmatterDisplay, type FrontmatterFormat, MarkdownViewer, type MarkdownViewerProps, MermaidDiagram, type ParsedFrontmatter, type RenderMermaidOptions, type RenderOptions, type RenderResult, type ResolveLinkOptions, clearLineAnchorHighlights, parseFrontmatter, parseLineAnchor, rehypeSourceLines, renderMarkdown, renderMermaidBlocks, resolveLinks, sanitizeSchema, scrollToLineAnchor, useLineAnchor };
+export { DOC_STATUSES, DOC_STATUS_TONES, type DocStatus, DocumentStatusChip, FrontmatterDisplay, type FrontmatterFormat, MarkdownViewer, type MarkdownViewerProps, MermaidDiagram, type ParsedFrontmatter, type Pipeline, type PipelineOptions, type RenderMermaidOptions, type RenderOptions, type RenderResult, type ResolveLinkOptions, VANTAGE_FRONTMATTER_KEYS, type VantageFrontmatter, type VantageFrontmatterIssue, buildPipeline, buildRemarkPlugins, clearLineAnchorHighlights, isDocStatus, parseFrontmatter, parseLineAnchor, readVantageFrontmatter, rehypeSourceLines, renderMarkdown, renderMermaidBlocks, resolveLinks, sanitizeSchema, scrollToLineAnchor, useLineAnchor };

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import React, { RefObject } from 'react';
 import { Root } from 'hast';
-import { Plugin } from 'unified';
+import { Plugin, PluggableList } from 'unified';
 import { defaultSchema } from 'rehype-sanitize';
 
 /**
@@ -56,6 +56,107 @@ interface FrontmatterDisplayProps {
 }
 declare const FrontmatterDisplay: React.NamedExoticComponent<FrontmatterDisplayProps>;
 
+/**
+ * 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"];
+
+/**
+ * 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;
+
+declare const DocumentStatusChip: React.NamedExoticComponent<{
+    status: DocStatus;
+}>;
+
 /**
  * Framework-agnostic markdown -> HTML rendering pipeline.
  * Uses the same remark/rehype chain as the Vantage viewer.
@@ -87,7 +188,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
@@ -108,22 +209,98 @@ 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.
+ * 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;
 /**
- * Parse a GitHub-style line anchor hash.
- * Supports: #L42, #L42-L50, #L42-50
- * Returns null if the hash is not a line anchor.
+ * 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.
  */
@@ -137,15 +314,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.
@@ -160,6 +394,18 @@ declare function parseFrontmatter(content: string): ParsedFrontmatter;
  */
 
 type Schema = typeof defaultSchema;
+/**
+ * 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;
 
 /**
@@ -241,4 +487,4 @@ interface ResolveLinkOptions {
  */
 declare function resolveLinks(html: string, options?: ResolveLinkOptions): string;
 
-export { FrontmatterDisplay, type FrontmatterFormat, MarkdownViewer, type MarkdownViewerProps, MermaidDiagram, type ParsedFrontmatter, type RenderMermaidOptions, type RenderOptions, type RenderResult, type ResolveLinkOptions, clearLineAnchorHighlights, parseFrontmatter, parseLineAnchor, rehypeSourceLines, renderMarkdown, renderMermaidBlocks, resolveLinks, sanitizeSchema, scrollToLineAnchor, useLineAnchor };
+export { DOC_STATUSES, DOC_STATUS_TONES, type DocStatus, DocumentStatusChip, FrontmatterDisplay, type FrontmatterFormat, MarkdownViewer, type MarkdownViewerProps, MermaidDiagram, type ParsedFrontmatter, type Pipeline, type PipelineOptions, type RenderMermaidOptions, type RenderOptions, type RenderResult, type ResolveLinkOptions, VANTAGE_FRONTMATTER_KEYS, type VantageFrontmatter, type VantageFrontmatterIssue, buildPipeline, buildRemarkPlugins, clearLineAnchorHighlights, isDocStatus, parseFrontmatter, parseLineAnchor, readVantageFrontmatter, rehypeSourceLines, renderMarkdown, renderMermaidBlocks, resolveLinks, sanitizeSchema, scrollToLineAnchor, useLineAnchor };