vantage-md 0.1.3 → 0.5.4

package/dist/index.cjs

@@ -2,30 +2,30 @@
 
 var unified = require('unified');
 var remarkParse = require('remark-parse');
+var remarkRehype = require('remark-rehype');
+var rehypeStringify = require('rehype-stringify');
 var remarkGfm = require('remark-gfm');
 var remarkMath = require('remark-math');
-var remarkRehype = require('remark-rehype');
 var rehypeRaw = require('rehype-raw');
 var rehypeSanitize = require('rehype-sanitize');
 var rehypeHighlight = require('rehype-highlight');
 var rehypeKatex = require('rehype-katex');
 var rehypeSlug = require('rehype-slug');
-var rehypeStringify = require('rehype-stringify');
 var YAML = require('yaml');
 var smolToml = require('smol-toml');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var remarkParse__default = /*#__PURE__*/_interopDefault(remarkParse);
+var remarkRehype__default = /*#__PURE__*/_interopDefault(remarkRehype);
+var rehypeStringify__default = /*#__PURE__*/_interopDefault(rehypeStringify);
 var remarkGfm__default = /*#__PURE__*/_interopDefault(remarkGfm);
 var remarkMath__default = /*#__PURE__*/_interopDefault(remarkMath);
-var remarkRehype__default = /*#__PURE__*/_interopDefault(remarkRehype);
 var rehypeRaw__default = /*#__PURE__*/_interopDefault(rehypeRaw);
 var rehypeSanitize__default = /*#__PURE__*/_interopDefault(rehypeSanitize);
 var rehypeHighlight__default = /*#__PURE__*/_interopDefault(rehypeHighlight);
 var rehypeKatex__default = /*#__PURE__*/_interopDefault(rehypeKatex);
 var rehypeSlug__default = /*#__PURE__*/_interopDefault(rehypeSlug);
-var rehypeStringify__default = /*#__PURE__*/_interopDefault(rehypeStringify);
 var YAML__default = /*#__PURE__*/_interopDefault(YAML);
 
 // src/renderMarkdown.ts
@@ -49,25 +49,511 @@ var BLOCK_TAGS = /* @__PURE__ */ new Set([
   "hr",
   "div"
 ]);
-function visit(node) {
+function visit(node, offset) {
   if ("children" in node) {
     for (const child of node.children) {
       if (child.type === "element") {
         if (BLOCK_TAGS.has(child.tagName) && child.position?.start?.line) {
           child.properties = child.properties || {};
-          child.properties["dataSourceLine"] = child.position.start.line;
+          child.properties["dataSourceLine"] = child.position.start.line + offset;
         }
-        visit(child);
+        visit(child, offset);
       }
     }
   }
 }
-var rehypeSourceLines = () => {
+var rehypeSourceLines = (options) => {
+  const offset = options?.offset ?? 0;
   return (tree) => {
-    visit(tree);
+    visit(tree, offset);
   };
 };
 var rehypeSourceLines_default = rehypeSourceLines;
+
+// src/vantageDirectives.ts
+var VANTAGE_SENTINEL = "vantage:";
+var DIRECTIVE_NAMES = ["section", "block", "oq"];
+var VANTAGE_TONES = [
+  "note",
+  "tip",
+  "important",
+  "warning",
+  "caution",
+  "muted"
+];
+var VANTAGE_EMPHASIS = ["strong", "normal", "quiet"];
+var VANTAGE_BADGES = [
+  "draft",
+  "stale",
+  "blocked",
+  "done",
+  "wip"
+];
+var VANTAGE_COLLAPSED = ["true", "false"];
+var VANTAGE_RUNS = ["start", "middle", "end", "only"];
+var VANTAGE_STYLE_TARGETS = [
+  "p",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "li",
+  "blockquote",
+  "pre",
+  "table",
+  "tr",
+  "ul",
+  "ol",
+  "hr",
+  "div"
+];
+var VANTAGE_ANCHOR_TARGETS = [
+  "p",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "li",
+  "blockquote",
+  "pre",
+  "table"
+];
+var VANTAGE_OQ_HOST_TARGETS = VANTAGE_ANCHOR_TARGETS.filter(
+  (tag) => tag !== "pre" && tag !== "table"
+);
+var STYLE_KEYS = {
+  tone: VANTAGE_TONES,
+  emphasis: VANTAGE_EMPHASIS,
+  badge: VANTAGE_BADGES,
+  collapsed: VANTAGE_COLLAPSED
+};
+var DIRECTIVE_VOCABULARY = {
+  section: STYLE_KEYS,
+  block: STYLE_KEYS,
+  oq: { id: null, leaning: null }
+};
+var WS = /[ \t\r\n]*/y;
+var SENTINEL_PREFIX = /^[ \t\r\n]*vantage:/;
+var NAME = /[a-z][a-z0-9-]*/y;
+var UNQUOTED = /[A-Za-z0-9_.:#-]+/y;
+var QUOTED = /"[^"]*"/y;
+function hasVantageSentinel(comment) {
+  return SENTINEL_PREFIX.test(comment);
+}
+function token(comment, offset) {
+  const rest = comment.slice(offset);
+  const end = rest.search(/[ \t\r\n]/);
+  const word = end === -1 ? rest : rest.slice(0, end);
+  return word.length > 24 ? `${word.slice(0, 24)}\u2026` : word;
+}
+function matchAt(pattern, comment, offset) {
+  pattern.lastIndex = offset;
+  const match = pattern.exec(comment);
+  return match === null ? null : match[0];
+}
+function skipWhitespace(comment, offset) {
+  return matchAt(WS, comment, offset)?.length ?? 0;
+}
+function malformed(reason, offset) {
+  return { kind: "malformed", reason, offset };
+}
+function parseVantageDirective(comment) {
+  const sentinel = SENTINEL_PREFIX.exec(comment);
+  if (sentinel === null) return null;
+  let at = sentinel[0].length;
+  at += skipWhitespace(comment, at);
+  const nameOffset = at;
+  const name = matchAt(NAME, comment, at);
+  if (name === null) {
+    return malformed("no directive name after `vantage:`", at);
+  }
+  at += name.length;
+  const pairs = [];
+  while (at < comment.length) {
+    const gap = skipWhitespace(comment, at);
+    at += gap;
+    if (at >= comment.length) break;
+    if (gap === 0) {
+      return malformed(`\`${token(comment, at)}\` needs a space before it`, at);
+    }
+    const keyOffset = at;
+    const key = matchAt(NAME, comment, at);
+    if (key === null) {
+      return malformed(
+        `\`${token(comment, at)}\` is not a \`key=value\` pair`,
+        at
+      );
+    }
+    at += key.length;
+    if (comment[at] !== "=") {
+      return malformed(`\`${key}\` is not followed by \`=value\``, at);
+    }
+    at += 1;
+    const valueOffset = at;
+    const quoted = matchAt(QUOTED, comment, at);
+    if (quoted !== null) {
+      at += quoted.length;
+      pairs.push({
+        key,
+        value: quoted.slice(1, -1),
+        keyOffset,
+        valueOffset,
+        quoted: true
+      });
+      continue;
+    }
+    const unquoted = matchAt(UNQUOTED, comment, at);
+    if (unquoted === null) {
+      const found = token(comment, at);
+      return malformed(
+        found === "" ? `\`${key}=\` has no value` : `\`${found}\` is not a valid value for \`${key}\``,
+        at
+      );
+    }
+    at += unquoted.length;
+    pairs.push({ key, value: unquoted, keyOffset, valueOffset, quoted: false });
+  }
+  return { kind: "directive", name, nameOffset, pairs };
+}
+
+// src/rehypeVantageDirectives.ts
+var STYLE_TARGET_TAGS = new Set(VANTAGE_STYLE_TARGETS);
+var ANCHOR_TARGET_TAGS = new Set(VANTAGE_ANCHOR_TARGETS);
+var HEADING_DEPTHS = /* @__PURE__ */ new Map([
+  ["h1", 1],
+  ["h2", 2],
+  ["h3", 3],
+  ["h4", 4],
+  ["h5", 5],
+  ["h6", 6]
+]);
+var RANGE_PROPERTIES = /* @__PURE__ */ new Map([
+  ["tone", "dataVantageTone"],
+  ["emphasis", "dataVantageEmphasis"]
+]);
+var POINT_PROPERTIES = /* @__PURE__ */ new Map([["badge", "dataVantageBadge"]]);
+var RUN_PROPERTY = "dataVantageRun";
+var OQ_PROPERTY = "dataVantageOq";
+var LEANING_PROPERTY = "dataVantageLeaning";
+var COLLAPSED_PROPERTY = "dataVantageCollapsed";
+var COLLAPSE_GROUP_PROPERTY = "dataVantageCollapseGroup";
+var COLLAPSE_TOGGLE_PROPERTY = "dataVantageCollapseToggle";
+var MAX_LEANING = 500;
+function isSkippable(node) {
+  if (node.type === "comment" || node.type === "doctype") return true;
+  if (node.type === "text") return node.value.trim() === "";
+  return false;
+}
+function headingDepth(node) {
+  if (node.type !== "element") return void 0;
+  return HEADING_DEPTHS.get(node.tagName);
+}
+function setProperty(element, property, value) {
+  element.properties = element.properties ?? {};
+  element.properties[property] = value;
+}
+function runValue(index, length) {
+  if (length === 1) return "only";
+  if (index === 0) return "start";
+  return index === length - 1 ? "end" : "middle";
+}
+function vocabularyOf(name, key) {
+  return DIRECTIVE_VOCABULARY[name]?.[key];
+}
+function accepts(name, key, value) {
+  const values = vocabularyOf(name, key);
+  if (values === void 0) return false;
+  return values === null || values.includes(value);
+}
+function styleRange(children, targetIndex, name) {
+  const range = [targetIndex];
+  const depth = name === "section" ? headingDepth(children[targetIndex]) : void 0;
+  if (depth === void 0) return range;
+  for (let i = targetIndex + 1; i < children.length; i++) {
+    const node = children[i];
+    const nodeDepth = headingDepth(node);
+    if (nodeDepth !== void 0 && nodeDepth <= depth) break;
+    if (node.type === "element" && STYLE_TARGET_TAGS.has(node.tagName)) {
+      range.push(i);
+    }
+  }
+  return range;
+}
+function collapsesSection(name, pairs, target) {
+  if (name !== "section") return false;
+  if (pairs.get("collapsed") !== "true") return false;
+  return headingDepth(target) !== void 0;
+}
+function stampStyle(children, targetIndex, name, pairs, state) {
+  const target = children[targetIndex];
+  if (!STYLE_TARGET_TAGS.has(target.tagName)) return;
+  const rangeStamps = [];
+  const targetStamps = [];
+  for (const [key, value] of pairs) {
+    if (!accepts(name, key, value)) continue;
+    const rangeProperty = RANGE_PROPERTIES.get(key);
+    if (rangeProperty !== void 0) {
+      rangeStamps.push([rangeProperty, value]);
+      continue;
+    }
+    const pointProperty = POINT_PROPERTIES.get(key);
+    if (pointProperty !== void 0) targetStamps.push([pointProperty, value]);
+  }
+  const collapses = collapsesSection(name, pairs, target);
+  if (rangeStamps.length === 0 && targetStamps.length === 0 && !collapses) {
+    return;
+  }
+  const range = styleRange(children, targetIndex, name);
+  const group = collapses && range.length > 1 ? String(state.nextGroup++) : void 0;
+  for (let i = 0; i < range.length; i++) {
+    const element = children[range[i]];
+    for (const [property, value] of rangeStamps) {
+      setProperty(element, property, value);
+    }
+    if (i === 0) {
+      for (const [property, value] of targetStamps) {
+        setProperty(element, property, value);
+      }
+    }
+    if (rangeStamps.length > 0) {
+      setProperty(element, RUN_PROPERTY, runValue(i, range.length));
+    }
+    if (group === void 0) continue;
+    if (i === 0) {
+      setProperty(element, COLLAPSE_TOGGLE_PROPERTY, group);
+    } else {
+      setProperty(element, COLLAPSED_PROPERTY, "true");
+      setProperty(element, COLLAPSE_GROUP_PROPERTY, group);
+    }
+  }
+}
+function stampOq(target, pairs) {
+  setProperty(target, OQ_PROPERTY, "true");
+  const leaning = pairs.get("leaning");
+  if (leaning === void 0) return;
+  const text = leaning.replace(/\s+/g, " ").trim().slice(0, MAX_LEANING);
+  if (text !== "") setProperty(target, LEANING_PROPERTY, text);
+}
+function stampRun(children, targetIndex, run, state) {
+  const target = children[targetIndex];
+  const style = /* @__PURE__ */ new Map();
+  const oq = /* @__PURE__ */ new Map();
+  let styleName;
+  let hasOq = false;
+  for (const directive of run) {
+    if (directive.name === "section" || directive.name === "block") {
+      styleName = directive.name;
+      for (const pair of directive.pairs) style.set(pair.key, pair.value);
+    } else if (directive.name === "oq") {
+      hasOq = true;
+      for (const pair of directive.pairs) oq.set(pair.key, pair.value);
+    }
+  }
+  if (styleName !== void 0) {
+    stampStyle(children, targetIndex, styleName, style, state);
+  }
+  if (hasOq && ANCHOR_TARGET_TAGS.has(target.tagName)) {
+    stampOq(target, oq);
+  }
+}
+function directiveOf(node) {
+  if (node.type !== "comment") return void 0;
+  const parsed = parseVantageDirective(node.value);
+  return parsed !== null && parsed.kind === "directive" ? parsed : void 0;
+}
+function processChildren(parent, state) {
+  const children = parent.children;
+  let i = 0;
+  while (i < children.length) {
+    const node = children[i];
+    if (node.type === "element") {
+      processChildren(node, state);
+      i++;
+      continue;
+    }
+    const first = directiveOf(node);
+    if (first === void 0) {
+      i++;
+      continue;
+    }
+    const run = [first];
+    let j = i + 1;
+    let targetIndex = -1;
+    for (; j < children.length; j++) {
+      const next = children[j];
+      if (next.type === "element") {
+        targetIndex = j;
+        break;
+      }
+      if (!isSkippable(next)) break;
+      const directive = directiveOf(next);
+      if (directive !== void 0) run.push(directive);
+    }
+    if (targetIndex >= 0) stampRun(children, targetIndex, run, state);
+    i = j;
+  }
+}
+var rehypeVantageDirectives = () => {
+  return (tree) => {
+    processChildren(tree, { nextGroup: 1 });
+  };
+};
+var rehypeVantageDirectives_default = rehypeVantageDirectives;
+
+// src/rehypeVantageMathStamps.ts
+var CARRIED_KEY = "vantageDisplayMathStamps";
+function classNames(node) {
+  const value = node.properties?.className;
+  return Array.isArray(value) ? value.map(String) : [];
+}
+function isDisplayMath(node) {
+  if (node.type !== "element" || node.tagName !== "pre") return false;
+  return node.children.some(
+    (child) => child.type === "element" && child.tagName === "code" && classNames(child).includes("language-math")
+  );
+}
+function carriedProperties(properties) {
+  const carried = {};
+  for (const [key, value] of Object.entries(properties ?? {})) {
+    if (key === "dataSourceLine" || key.startsWith("dataVantage")) {
+      carried[key] = value;
+    }
+  }
+  return carried;
+}
+function collect(parent, out) {
+  const children = parent.children;
+  for (let i = 0; i < children.length; i++) {
+    const node = children[i];
+    if (node.type !== "element") continue;
+    if (isDisplayMath(node)) {
+      const properties = carriedProperties(node.properties);
+      if (Object.keys(properties).length > 0) {
+        out.push({
+          parent,
+          anchor: i === 0 ? void 0 : children[i - 1],
+          properties
+        });
+      }
+      continue;
+    }
+    collect(node, out);
+  }
+}
+function reapply(carried) {
+  for (const { parent, anchor, properties } of carried) {
+    const siblings = parent.children;
+    let index = 0;
+    if (anchor !== void 0) {
+      const at = siblings.indexOf(anchor);
+      if (at === -1) continue;
+      index = at + 1;
+    }
+    const replacement = siblings[index];
+    if (replacement === void 0 || replacement.type !== "element") continue;
+    if (!classNames(replacement).some((name) => name.startsWith("katex"))) {
+      continue;
+    }
+    replacement.properties ??= {};
+    for (const [key, value] of Object.entries(properties)) {
+      replacement.properties[key] ??= value;
+    }
+  }
+}
+var rehypeCaptureMathStamps = () => {
+  return (tree, file) => {
+    const carried = [];
+    collect(tree, carried);
+    file.data[CARRIED_KEY] = carried;
+  };
+};
+var rehypeRestoreMathStamps = () => {
+  return (_tree, file) => {
+    const carried = file.data[CARRIED_KEY];
+    delete file.data[CARRIED_KEY];
+    if (Array.isArray(carried)) reapply(carried);
+  };
+};
+var SAFE_STYLE_PROPERTIES = [
+  // Box metrics. `top`/`right`/`bottom`/`left` are inert now that `position` is
+  // banned, and they stay only because dropping them would fail the whole
+  // attribute for a document that writes one — the all-or-nothing rule below
+  // makes every removal a behaviour change. They buy an attacker nothing that
+  // negative `margin` does not already buy.
+  "height",
+  "min-height",
+  "max-height",
+  "width",
+  "min-width",
+  "max-width",
+  "top",
+  "bottom",
+  "left",
+  "right",
+  "margin",
+  "margin-top",
+  "margin-right",
+  "margin-bottom",
+  "margin-left",
+  "padding",
+  "padding-top",
+  "padding-right",
+  "padding-bottom",
+  "padding-left",
+  // Rules and boxes.
+  "border",
+  "border-style",
+  "border-color",
+  "border-width",
+  "border-top-width",
+  "border-right-width",
+  "border-bottom-width",
+  "border-left-width",
+  "border-top-style",
+  "border-right-style",
+  "border-bottom-style",
+  "border-left-style",
+  "border-top-color",
+  "border-right-color",
+  "border-bottom-color",
+  "border-left-color",
+  "border-radius",
+  // Typography.
+  "color",
+  "background-color",
+  "font",
+  "font-size",
+  "font-style",
+  "font-weight",
+  "font-family",
+  "font-variant",
+  "line-height",
+  "letter-spacing",
+  "word-spacing",
+  "text-align",
+  "text-decoration",
+  "text-indent",
+  "white-space",
+  "vertical-align",
+  "list-style-type",
+  // Flow.
+  "display",
+  "float",
+  "clear",
+  "opacity",
+  "overflow"
+];
+var VALUE = `[^;:()"'\\\\]*`;
+var DECLARATION = `(?:(?:${SAFE_STYLE_PROPERTIES.join("|")})\\s*:${VALUE})`;
+var SAFE_STYLE = new RegExp(
+  `^\\s*(?:${DECLARATION};\\s*)*${DECLARATION}?$`,
+  "i"
+);
+var COLLAPSE_GROUP_ID = /^[0-9]+$/;
 var sanitizeSchema = {
   ...rehypeSanitize.defaultSchema,
   tagNames: [
@@ -103,20 +589,94 @@ var sanitizeSchema = {
     "*": [
       ...rehypeSanitize.defaultSchema.attributes?.["*"] || [],
       "className",
-      "style",
-      "dataSourceLine"
+      ["style", SAFE_STYLE],
+      "dataSourceLine",
+      // What `rehypeVantageDirectives` compiles a `<!-- vantage: … -->` comment
+      // into, named individually — never by a `data-vantage-*` wildcard, which
+      // would readmit whatever a future bug emits and whatever a document
+      // hand-writes as raw HTML.
+      //
+      // The value lists are the belt to the plugin's braces: the vocabulary is
+      // closed in the plugin *and* here, imported from the one module that
+      // defines it, so even if a refactor let an unvalidated value reach the
+      // tree the sanitiser still refuses it.
+      ["dataVantageTone", ...VANTAGE_TONES],
+      ["dataVantageEmphasis", ...VANTAGE_EMPHASIS],
+      ["dataVantageBadge", ...VANTAGE_BADGES],
+      ["dataVantageCollapsed", ...VANTAGE_COLLAPSED],
+      // The other half of `collapsed`: which group a hidden block belongs to,
+      // and which group a heading toggles. Both are plugin-minted counters with
+      // no vocabulary to allowlist, so they take a pattern instead —
+      // `hast-util-sanitize` accepts a `RegExp` in place of a literal value.
+      // A pattern rather than a bare name because the JS interpolates the value
+      // into a selector: anything but digits has no business reaching it.
+      ["dataVantageCollapseGroup", COLLAPSE_GROUP_ID],
+      ["dataVantageCollapseToggle", COLLAPSE_GROUP_ID],
+      ["dataVantageRun", ...VANTAGE_RUNS],
+      ["dataVantageOq", "true"],
+      // The design's one genuinely free-text value: the body of a review
+      // comment, so it cannot be value-allowlisted and this entry is name-only.
+      // Two defences remain rather than three — `hast` escapes the value on
+      // serialisation and React sets it through the DOM property path, so it
+      // cannot break out of the attribute — and the honest record of that is in
+      // the design doc rather than a third layer implied here.
+      "dataVantageLeaning"
     ],
     code: [...rehypeSanitize.defaultSchema.attributes?.code || [], "className"],
-    span: [...rehypeSanitize.defaultSchema.attributes?.span || [], "className", "style"],
-    div: [...rehypeSanitize.defaultSchema.attributes?.div || [], "className", "style"],
+    span: [
+      ...rehypeSanitize.defaultSchema.attributes?.span || [],
+      "className",
+      ["style", SAFE_STYLE]
+    ],
+    div: [
+      ...rehypeSanitize.defaultSchema.attributes?.div || [],
+      "className",
+      ["style", SAFE_STYLE]
+    ],
     a: [...rehypeSanitize.defaultSchema.attributes?.a || [], "id", "className"],
     math: ["xmlns"],
     annotation: ["encoding"],
     img: [...rehypeSanitize.defaultSchema.attributes?.img || [], "loading"],
-    td: [...rehypeSanitize.defaultSchema.attributes?.td || [], "style"],
-    th: [...rehypeSanitize.defaultSchema.attributes?.th || [], "style"]
+    td: [...rehypeSanitize.defaultSchema.attributes?.td || [], ["style", SAFE_STYLE]],
+    th: [...rehypeSanitize.defaultSchema.attributes?.th || [], ["style", SAFE_STYLE]]
   }
 };
+
+// src/pipeline.ts
+function buildRemarkPlugins(options = {}) {
+  const { gfm = true, math = true } = options;
+  const plugins = [];
+  if (gfm) plugins.push([remarkGfm__default.default, { singleTilde: false }]);
+  if (math) plugins.push([remarkMath__default.default, { singleDollarTextMath: false }]);
+  return plugins;
+}
+function buildRehypePlugins(options = {}) {
+  const {
+    math = true,
+    highlight = true,
+    sourceLines = true,
+    sanitize = true,
+    bodyLineOffset = 0
+  } = options;
+  const plugins = [rehypeRaw__default.default];
+  if (sourceLines) {
+    plugins.push([rehypeSourceLines_default, { offset: bodyLineOffset }]);
+  }
+  plugins.push(rehypeVantageDirectives_default);
+  if (sanitize) plugins.push([rehypeSanitize__default.default, sanitizeSchema]);
+  plugins.push(rehypeSlug__default.default);
+  if (highlight) plugins.push(rehypeHighlight__default.default);
+  if (math) {
+    plugins.push(rehypeCaptureMathStamps, rehypeKatex__default.default, rehypeRestoreMathStamps);
+  }
+  return plugins;
+}
+function buildPipeline(options = {}) {
+  return {
+    remarkPlugins: buildRemarkPlugins(options),
+    rehypePlugins: buildRehypePlugins(options)
+  };
+}
 function parseFrontmatter(content) {
   if (content.startsWith("+++")) {
     return parseFrontmatterWithDelimiter(content, "+++", "toml");
@@ -124,25 +684,75 @@ function parseFrontmatter(content) {
   if (content.startsWith("---")) {
     return parseFrontmatterWithDelimiter(content, "---", "yaml");
   }
-  return { frontmatter: {}, body: content, format: "none" };
+  return withOffset(content, {
+    frontmatter: {},
+    body: content,
+    format: "none"
+  });
+}
+function withOffset(content, parsed) {
+  const stripped = content.slice(0, content.length - parsed.body.length);
+  let bodyLineOffset = 0;
+  for (const ch of stripped) {
+    if (ch === "\n") bodyLineOffset++;
+  }
+  return { ...parsed, bodyLineOffset };
 }
 function parseFrontmatterWithDelimiter(content, delimiter, format) {
   const searchStart = delimiter.length;
   const endIndex = content.indexOf(`
 ${delimiter}`, searchStart);
   if (endIndex === -1) {
-    return { frontmatter: {}, body: content, format: "none" };
+    return withOffset(content, {
+      frontmatter: {},
+      body: content,
+      format: "none",
+      problem: { kind: "unterminated", delimiter }
+    });
   }
   const raw = content.slice(searchStart + 1, endIndex).trim();
   const bodyStart = endIndex + 1 + delimiter.length;
   const body = content.slice(bodyStart).replace(/^\n/, "");
   try {
-    const frontmatter = format === "toml" ? smolToml.parse(raw) : YAML__default.default.parse(raw);
-    return { frontmatter: frontmatter || {}, body, format };
-  } catch {
-    return { frontmatter: {}, body: content, format: "none" };
+    const parsed = format === "toml" ? smolToml.parse(raw) : YAML__default.default.parse(raw);
+    return withOffset(content, {
+      frontmatter: parsed || {},
+      body,
+      format,
+      ...isMapping(parsed) ? {} : { problem: { kind: "not-a-mapping", delimiter } }
+    });
+  } catch (error) {
+    return withOffset(content, {
+      frontmatter: {},
+      body: content,
+      format: "none",
+      problem: { kind: "invalid", delimiter, ...errorPosition(error) }
+    });
   }
 }
+function isMapping(value) {
+  return value === null || value === void 0 || typeof value === "object" && !Array.isArray(value);
+}
+function errorPosition(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const source = error;
+  const yamlPosition = source?.linePos?.[0];
+  if (typeof yamlPosition?.line === "number") {
+    return {
+      message,
+      line: yamlPosition.line,
+      ...typeof yamlPosition.col === "number" ? { column: yamlPosition.col } : {}
+    };
+  }
+  if (typeof source?.line === "number") {
+    return {
+      message,
+      line: source.line,
+      ...typeof source.column === "number" ? { column: source.column } : {}
+    };
+  }
+  return { message };
+}
 
 // src/renderMarkdown.ts
 async function renderMarkdown(content, options = {}) {
@@ -158,27 +768,22 @@ async function renderMarkdown(content, options = {}) {
   if (parseFm) {
     parsed = parseFrontmatter(content);
   } else {
-    parsed = { frontmatter: {}, body: content, format: "none" };
-  }
-  const remarkPlugins = [];
-  const rehypePlugins = [];
-  if (gfm) remarkPlugins.push([remarkGfm__default.default, { singleTilde: false }]);
-  if (math) remarkPlugins.push([remarkMath__default.default, { singleDollarTextMath: false }]);
-  rehypePlugins.push([rehypeRaw__default.default]);
-  if (sourceLines) rehypePlugins.push([rehypeSourceLines_default]);
-  if (sanitize) rehypePlugins.push([rehypeSanitize__default.default, sanitizeSchema]);
-  rehypePlugins.push([rehypeSlug__default.default]);
-  if (highlight) rehypePlugins.push([rehypeHighlight__default.default]);
-  if (math) rehypePlugins.push([rehypeKatex__default.default]);
-  let processor = unified.unified().use(remarkParse__default.default);
-  for (const [plugin, ...args] of remarkPlugins) {
-    processor = processor.use(plugin, ...args);
-  }
-  processor = processor.use(remarkRehype__default.default, { allowDangerousHtml: true });
-  for (const [plugin, ...args] of rehypePlugins) {
-    processor = processor.use(plugin, ...args);
-  }
-  processor = processor.use(rehypeStringify__default.default);
+    parsed = {
+      frontmatter: {},
+      body: content,
+      format: "none",
+      bodyLineOffset: 0
+    };
+  }
+  const { remarkPlugins, rehypePlugins } = buildPipeline({
+    gfm,
+    math,
+    highlight,
+    sourceLines,
+    sanitize,
+    bodyLineOffset: parsed.bodyLineOffset
+  });
+  const processor = unified.unified().use(remarkParse__default.default).use(remarkPlugins).use(remarkRehype__default.default, { allowDangerousHtml: true }).use(rehypePlugins).use(rehypeStringify__default.default);
   const result = await processor.process(parsed.body);
   return {
     html: String(result),
@@ -187,8 +792,7 @@ async function renderMarkdown(content, options = {}) {
   };
 }
 
-// src/scrollToLineAnchor.ts
-var HIGHLIGHT_CLASS = "line-anchor-highlight";
+// src/lineAnchor.ts
 function parseLineAnchor(hash) {
   if (!hash) return null;
   const frag = hash.startsWith("#") ? hash.slice(1) : hash;
@@ -198,6 +802,9 @@ function parseLineAnchor(hash) {
   const end = match[2] ? parseInt(match[2], 10) : start;
   return { start: Math.min(start, end), end: Math.max(start, end) };
 }
+
+// src/scrollToLineAnchor.ts
+var HIGHLIGHT_CLASS = "line-anchor-highlight";
 function clearLineAnchorHighlights(container) {
   container.querySelectorAll(`.${HIGHLIGHT_CLASS}`).forEach((node) => {
     node.classList.remove(HIGHLIGHT_CLASS);
@@ -210,10 +817,7 @@ function scrollToLineAnchor(container, hash) {
   const blocks = container.querySelectorAll("[data-source-line]");
   let firstMatch = null;
   for (const block of blocks) {
-    const line = parseInt(
-      block.dataset.sourceLine || "0",
-      10
-    );
+    const line = parseInt(block.dataset.sourceLine || "0", 10);
     if (line >= range.start && line <= range.end) {
       block.classList.add(HIGHLIGHT_CLASS);
       if (!firstMatch) firstMatch = block;
@@ -260,6 +864,74 @@ function findScrollParent(el) {
   return null;
 }
 
+// src/vantageFrontmatter.ts
+var DOC_STATUSES = [
+  "draft",
+  "in-review",
+  "accepted",
+  "deprecated"
+];
+var VANTAGE_FRONTMATTER_KEYS = ["status-chip"];
+var DOC_STATUS_TONES = {
+  draft: "muted",
+  "in-review": "warning",
+  accepted: "tip",
+  deprecated: "caution"
+};
+var STATUS_CHIP_VALUES = [
+  ...DOC_STATUSES,
+  "true",
+  "false"
+];
+function isDocStatus(value) {
+  return typeof value === "string" && DOC_STATUSES.includes(value);
+}
+function isTable(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Date);
+}
+function readVantageFrontmatter(frontmatter) {
+  const issues = [];
+  if (!Object.hasOwn(frontmatter, "vantage")) return { issues };
+  const value = frontmatter["vantage"];
+  if (!isTable(value)) {
+    issues.push({ kind: "not-a-table", value });
+    return { issues };
+  }
+  let statusChip;
+  for (const key of Object.keys(value)) {
+    if (!VANTAGE_FRONTMATTER_KEYS.includes(key)) {
+      issues.push({ kind: "unknown-key", key });
+      continue;
+    }
+    if (key === "status-chip") {
+      statusChip = readStatusChip(frontmatter, value[key], issues);
+    }
+  }
+  return { ...statusChip === void 0 ? {} : { statusChip }, issues };
+}
+function readStatusChip(frontmatter, raw, issues) {
+  const status = frontmatter["status"];
+  if (raw === false) return void 0;
+  if (raw === true) {
+    if (isDocStatus(status)) return status;
+    issues.push({ kind: "status-chip-orphan", status });
+    return void 0;
+  }
+  if (isDocStatus(raw)) {
+    if (isDocStatus(status) && status !== raw) {
+      issues.push({ kind: "status-chip-disagrees", chip: raw, status });
+    }
+    return raw;
+  }
+  issues.push({
+    kind: "bad-value",
+    key: "status-chip",
+    value: raw,
+    legal: STATUS_CHIP_VALUES
+  });
+  return void 0;
+}
+
 // src/mermaidCache.ts
 var svgCache = /* @__PURE__ */ new Map();
 
@@ -357,10 +1029,152 @@ function resolveLinks(html, options = {}) {
   );
 }
 
+// src/styleGuide.ts
+var STYLE_GUIDE = `## Markdown style guide (for Vantage viewer)
+
+When writing or updating markdown documents that will be viewed in Vantage, follow these conventions:
+
+### Structure
+- Use headings (## and ###) to organize content \u2014 they become navigable outline anchors.
+- Keep paragraphs focused and concise. Break up dense text with subheadings, lists, or tables.
+
+### Links and cross-references
+- **Relative paths only**: Always link relative to the *current file's directory*:
+  - Sibling in same folder: \`[Other Doc](./other-doc.md)\` or \`[Other Doc](other-doc.md)\`
+  - Subdirectory: \`[Design Doc](./design/auth.md)\`
+  - Parent / sibling folder: \`[Overview](../overview.md)\` or \`[Spec](../specs/api.md)\`
+- **Never use leading slashes**:
+  - \u274C \`[Doc](/docs/guide.md)\` (breaks web routing and multi-repo scoping)
+  - \u2705 \`[Doc](../docs/guide.md)\` or \`[Doc](./guide.md)\`
+- **Never use absolute filesystem paths or URI schemes**:
+  - \u274C \`file:///workspace/docs/guide.md\`, \`/workspace/docs/guide.md\`, \`C:\\...\`
+  - \u2705 \`[Doc](./guide.md)\` or \`[Doc](../guide.md)\`
+- **Always include the file extension**: Use \`.md\`, \`.ts\`, \`.go\`, etc. (e.g. \`[Model](model.go)\`).
+- **Line anchors and ranges**:
+  - Link to specific lines: \`[Handler](../server/api.go#L42)\` or \`[Range](../server/api.go#L42-L58)\`
+  - Same-file line anchor: \`[See lines](#L10-L25)\`
+  - Vantage scrolls to and highlights the target lines.
+- **Section anchors**:
+  - Same doc: \`[Usage](#usage)\`
+  - Cross-doc: \`[Architecture](../overview.md#system-architecture)\`
+  - Anchor slugs are lowercase, hyphenated, and punctuation-stripped.
+- **Backticks in links**: Place backticks inside the link label, not around the markdown link syntax:
+  - \u2705 \`[\`config.json\`](./config.json)\` or \`[config.json](./config.json)\`
+  - \u274C \`\`[config.json](./config.json)\`\`
+
+### Frontmatter (Metadata)
+- Include structured metadata at the very top of docs delimited by \`---\` (YAML) or \`+++\` (TOML). Vantage renders this as a metadata card:
+\`\`\`yaml
+---
+title: "Feature Specification"
+author: "Agent"
+date: 2026-08-15
+status: in-review # draft | in-review | accepted | deprecated
+tags: [architecture, backend, api]
+summary: "Brief description of the document purpose."
+vantage:
+  status-chip: true # show \`status\` as a chip above the metadata card
+---
+\`\`\`
+- **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\`.
+- **\`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 \u2014 \`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.
+
+### Mermaid diagrams
+- Use \`\`\`mermaid code blocks for flowcharts, sequence diagrams, and architecture diagrams. Vantage provides interactive zoom, pan, dark/light theme adaptation, and SVG export.
+- **Quote labels with special characters**: Always quote node labels containing parentheses, brackets, or colons to prevent syntax errors:
+\`\`\`mermaid
+flowchart TD
+    client["Client (React SPA)"] -->|WebSocket| srv["Vantage Server (Go)"]
+    srv --> git["Git CLI (git diff)"]
+\`\`\`
+
+### Code blocks and diffs
+- Always tag fenced code blocks with language identifiers (\`ts\`, \`go\`, \`python\`, \`bash\`, \`json\`, \`yaml\`, \`diff\`, \`sql\`, etc.) for syntax highlighting.
+- For proposed code modifications, use \`\`\`diff blocks with \`+\` and \`-\` prefixes:
+\`\`\`diff
+-const oldUrl = "/api/v1";
++const newUrl = "/api/v2";
+\`\`\`
+
+### Callouts and alerts
+- Use GitHub-style blockquote callouts for notes, tips, and warnings:
+> [!NOTE]
+> Background context or helpful explanation.
+
+> [!TIP]
+> Best practice advice or optimization suggestions.
+
+> [!IMPORTANT]
+> Key requirements or crucial information.
+
+> [!WARNING]
+> Urgent caution, breaking changes, or potential pitfalls.
+
+> [!CAUTION]
+> High-risk actions that could cause data loss or security issues.
+
+### Vantage directives (optional, and Vantage-only)
+
+Vantage 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:
+
+\`\`\`markdown
+<!-- vantage: section tone=warning badge=stale -->
+
+## Migration path
+
+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 \u2014 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** \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.
+- **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.
+- **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.
+- **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.
+
+\`\`\`markdown
+1. **OQ-9: Queue position on re-entry.**
+
+   <!-- vantage: oq id=OQ-9 leaning="Back of the queue \u2014 the fix might interact with what merged while it was out." -->
+
+   _Leaning:_ Back of the queue.
+\`\`\`
+
+### Tables, task lists, and math
+- **Tables**: Use standard markdown tables for structured comparisons and schemas.
+- **Task lists**: Use \`- [ ]\` and \`- [x]\` for actionable checklists and status tracking.
+- **LaTeX Math**: Use \`$$...$$\` for *all* KaTeX math \u2014 display blocks (\`$$\` alone on its own lines) and inline alike (\`$$E = mc^2$$\` mid-sentence).
+  - Single dollars are **not** math delimiters: \`$HOME\` and \`$100\` stay literal, so prose and shell snippets are safe to write as-is.
+`;
+
+exports.DIRECTIVE_NAMES = DIRECTIVE_NAMES;
+exports.DIRECTIVE_VOCABULARY = DIRECTIVE_VOCABULARY;
+exports.DOC_STATUSES = DOC_STATUSES;
+exports.DOC_STATUS_TONES = DOC_STATUS_TONES;
+exports.SAFE_STYLE = SAFE_STYLE;
+exports.STYLE_GUIDE = STYLE_GUIDE;
+exports.VANTAGE_BADGES = VANTAGE_BADGES;
+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_RUNS = VANTAGE_RUNS;
+exports.VANTAGE_SENTINEL = VANTAGE_SENTINEL;
+exports.VANTAGE_TONES = VANTAGE_TONES;
+exports.buildPipeline = buildPipeline;
+exports.buildRemarkPlugins = buildRemarkPlugins;
 exports.clearLineAnchorHighlights = clearLineAnchorHighlights;
+exports.hasVantageSentinel = hasVantageSentinel;
+exports.isDocStatus = isDocStatus;
 exports.parseFrontmatter = parseFrontmatter;
 exports.parseLineAnchor = parseLineAnchor;
+exports.parseVantageDirective = parseVantageDirective;
+exports.readVantageFrontmatter = readVantageFrontmatter;
 exports.rehypeSourceLines = rehypeSourceLines_default;
+exports.rehypeVantageDirectives = rehypeVantageDirectives_default;
 exports.renderMarkdown = renderMarkdown;
 exports.renderMermaidBlocks = renderMermaidBlocks;
 exports.resolveLinks = resolveLinks;