@openuji/speculator 0.2.0 → 0.3.1

package/dist/node.cjs

@@ -32,20 +32,25 @@ var node_exports = {};
 __export(node_exports, {
   DOMHtmlRenderer: () => DOMHtmlRenderer,
   FormatProcessor: () => FormatProcessor,
+  FormatRegistry: () => FormatRegistry,
   IncludeProcessor: () => IncludeProcessor,
   LinkedomHtmlRenderer: () => LinkedomHtmlRenderer,
+  RespecXrefResolver: () => RespecXrefResolver,
   Speculator: () => Speculator2,
   SpeculatorError: () => SpeculatorError,
+  StatsTracker: () => StatsTracker,
   browserFileLoader: () => browserFileLoader,
   createFallbackFileLoader: () => createFallbackFileLoader,
   createMarkdownRenderer: () => createMarkdownRenderer,
+  fromRespecConfig: () => fromRespecConfig,
+  getChangedOutputAreas: () => getChangedOutputAreas,
   getDefaultFileLoader: () => getDefaultFileLoader,
   nodeFileLoader: () => nodeFileLoader,
   parseMarkdown: () => parseMarkdown
 });
 module.exports = __toCommonJS(node_exports);
 
-// src/utils/file-loader.ts
+// src/utils/file-loader/node.ts
 var nodeFileLoader = async (path) => {
   const fs = await import("fs/promises");
   const { fileURLToPath } = await import("url");
@@ -56,6 +61,8 @@ var nodeFileLoader = async (path) => {
     throw new Error(`Failed to load file: ${path}. ${error instanceof Error ? error.message : "Unknown error"}`);
   }
 };
+
+// src/utils/file-loader/browser.ts
 var browserFileLoader = async (path) => {
   try {
     const response = await fetch(path);
@@ -67,6 +74,8 @@ var browserFileLoader = async (path) => {
     throw new Error(`Failed to fetch file: ${path}. ${error instanceof Error ? error.message : "Network error"}`);
   }
 };
+
+// src/utils/file-loader/index.ts
 function createFallbackFileLoader(loaders) {
   return async (path) => {
     let lastError;
@@ -100,58 +109,245 @@ var SpeculatorError = class extends Error {
     this.name = "SpeculatorError";
   }
 };
+function fromRespecConfig(respec) {
+  return { ...respec };
+}
 
-// src/pipeline/postprocess.ts
-async function postprocess(root, passes, options = {}) {
-  const warnings = [];
-  for (const pass of passes) {
-    const result = await pass.run(root, options);
-    if (result && result.length) {
-      warnings.push(...result);
+// src/utils/stats-tracker.ts
+var StatsTracker = class {
+  constructor() {
+    this._stats = {
+      elementsProcessed: 0,
+      filesIncluded: 0,
+      markdownBlocks: 0,
+      processingTime: 0
+    };
+    this.startTime = null;
+  }
+  start() {
+    this.startTime = performance.now();
+  }
+  stop() {
+    if (this.startTime !== null) {
+      this._stats.processingTime += performance.now() - this.startTime;
+      this.startTime = null;
     }
   }
-  return { warnings };
+  incrementElements(count = 1) {
+    this._stats.elementsProcessed += count;
+  }
+  incrementFiles(count = 1) {
+    this._stats.filesIncluded += count;
+  }
+  incrementMarkdownBlocks(count = 1) {
+    this._stats.markdownBlocks += count;
+  }
+  toJSON() {
+    return { ...this._stats };
+  }
+};
+
+// src/renderers/sections-renderer.ts
+var SectionsRenderer = class {
+  constructor(speculator) {
+    this.speculator = speculator;
+  }
+  async render(sections = [], tracker = new StatsTracker()) {
+    const warnings = [];
+    const processed = [];
+    for (const section of sections) {
+      try {
+        if (section.hasAttribute("data-include") || section.hasAttribute("data-format") || section.querySelector("[data-include],[data-format]")) {
+          const res = await this.speculator.processElement(section, tracker);
+          processed.push(res.element);
+          warnings.push(...res.warnings);
+        } else {
+          processed.push(section);
+        }
+      } catch (e) {
+        warnings.push(
+          `Failed to process element: ${e instanceof Error ? e.message : "Unknown error"}`
+        );
+        processed.push(section);
+      }
+    }
+    return { sections: processed, warnings, stats: tracker.toJSON() };
+  }
+};
+
+// src/renderers/header-renderer.ts
+var HeaderRenderer = class {
+  render(header) {
+    const result = {};
+    if (header) result.header = header;
+    return result;
+  }
+};
+
+// src/renderers/sotd-renderer.ts
+var SotdRenderer = class {
+  render(sotd) {
+    const result = {};
+    if (sotd) result.sotd = sotd;
+    return result;
+  }
+};
+
+// src/document-builder.ts
+var DocumentBuilder = class {
+  constructor(speculator, htmlRenderer) {
+    this.htmlRenderer = htmlRenderer;
+    this.headerRenderer = new HeaderRenderer();
+    this.sotdRenderer = new SotdRenderer();
+    this.sectionsRenderer = new SectionsRenderer(speculator);
+  }
+  async build(config) {
+    const tracker = new StatsTracker();
+    const sections = config.sections || [];
+    const header = config.header;
+    const sotd = config.sotd;
+    const baseDoc = (header || sotd || sections[0])?.ownerDocument;
+    const preContainer = baseDoc ? baseDoc.createElement("div") : this.htmlRenderer.parse("");
+    if (header) preContainer.appendChild(header);
+    if (sotd) preContainer.appendChild(sotd);
+    for (const section of sections) preContainer.appendChild(section);
+    const hooks = config.preProcess;
+    if (hooks) {
+      for (const hook of hooks) {
+        await hook(preContainer);
+      }
+    }
+    const children = Array.from(preContainer.children);
+    const updatedSections = [];
+    for (const child of children) {
+      if (child === header || child === sotd) continue;
+      updatedSections.push(child);
+    }
+    const { sections: processedSections, warnings, stats } = await this.sectionsRenderer.render(updatedSections, tracker);
+    const { header: renderedHeader } = this.headerRenderer.render(
+      header?.cloneNode(true)
+    );
+    const { sotd: renderedSotd } = this.sotdRenderer.render(
+      sotd?.cloneNode(true)
+    );
+    const finalBaseDoc = (renderedHeader || renderedSotd || processedSections[0])?.ownerDocument;
+    const container = finalBaseDoc ? finalBaseDoc.createElement("div") : this.htmlRenderer.parse("");
+    if (renderedHeader) container.appendChild(renderedHeader);
+    if (renderedSotd) container.appendChild(renderedSotd);
+    for (const section of processedSections) container.appendChild(section);
+    const result = { container, stats, warnings };
+    if (renderedHeader) result.header = renderedHeader;
+    if (renderedSotd) result.sotd = renderedSotd;
+    return result;
+  }
+};
+
+// src/pipeline/postprocess.ts
+var Postprocessor = class {
+  constructor(passes) {
+    this.passes = passes;
+  }
+  /**
+   * Run the configured passes.
+   * @param areas Optional list of output areas to run. If omitted, all passes
+   *              are executed.
+   * @param options Configuration options for the passes.
+   */
+  async run(config, areas) {
+    const ctx = { outputs: {}, warnings: [], config };
+    const active = areas ? this.passes.filter((p) => areas.includes(p.area)) : this.passes;
+    const composed = compose(active);
+    await composed(ctx);
+    return { outputs: ctx.outputs, warnings: ctx.warnings };
+  }
+};
+function compose(passes) {
+  return function run(ctx) {
+    let index = -1;
+    async function dispatch(i) {
+      if (i <= index) return;
+      index = i;
+      const pass = passes[i];
+      if (!pass) return;
+      await pass.run(ctx, () => dispatch(i + 1));
+    }
+    return dispatch(0);
+  };
 }
 
+// src/pipeline/pipeline-runner.ts
+var PipelineRunner = class {
+  constructor(passFactory) {
+    this.passFactory = passFactory;
+  }
+  run(container, config, areas) {
+    const passes = this.passFactory(container);
+    const processor = new Postprocessor(passes);
+    return processor.run(config, areas);
+  }
+};
+
+// src/utils/logger.ts
+var logger = {
+  debug: (...args) => {
+    if (process.env.NODE_ENV !== "production") {
+      console.debug(...args);
+    }
+  }
+};
+
 // src/processors/include-processor.ts
 var IncludeProcessor = class {
-  constructor(baseUrl, fileLoader, formatProcessor) {
+  constructor(baseUrl, fileLoader, formatRegistry) {
     this.baseUrl = baseUrl;
     this.fileLoader = fileLoader;
-    this.formatProcessor = formatProcessor;
+    this.formatRegistry = formatRegistry;
+  }
+  matches(element) {
+    return element.hasAttribute("data-include");
   }
-  async process(element, stats, warnings) {
+  async process(element, tracker, warnings) {
     const includePath = element.getAttribute("data-include");
     const includeFormat = element.getAttribute("data-include-format") || "text";
     if (!includePath) {
       warnings.push("data-include attribute is empty");
-      return;
+      element.removeAttribute("data-include");
+      element.removeAttribute("data-include-format");
+      return { content: null };
     }
     try {
       const fullPath = this.resolveFilePath(includePath);
       const content = await this.fileLoader(fullPath);
-      const processedContent = this.formatProcessor.processContent(content, includeFormat);
-      element.innerHTML = processedContent;
-      stats.filesIncluded++;
+      const processedContent = this.formatRegistry.processContent(content, includeFormat);
+      tracker.incrementFiles();
       if (includeFormat === "markdown") {
-        stats.markdownBlocks++;
+        tracker.incrementMarkdownBlocks();
       }
+      element.removeAttribute("data-include");
+      element.removeAttribute("data-include-format");
+      return { content: processedContent };
     } catch (error) {
       const errorMsg = `Failed to load: ${includePath}`;
-      warnings.push(errorMsg);
-      element.innerHTML = `<p class="error">${errorMsg}</p>`;
-      throw new SpeculatorError(errorMsg, element, includePath);
+      element.removeAttribute("data-include");
+      element.removeAttribute("data-include-format");
+      return { content: null, error: errorMsg };
     }
-    element.removeAttribute("data-include");
-    element.removeAttribute("data-include-format");
   }
   resolveFilePath(path) {
     const filePath = new URL(path, this.baseUrl || "file:///").toString();
-    console.log(`Resolved file path: ${filePath}`);
+    logger.debug(`Resolved file path: ${filePath}`);
     return filePath;
   }
 };
 
+// src/utils/strip-ident.ts
+function stripIndent(content) {
+  const lines = content.replace(/\r\n?/g, "\n").split("\n");
+  const indents = lines.filter((line) => line.trim().length > 0).map((line) => line.match(/^\s*/)?.[0].length || 0);
+  const minIndent = indents.length > 0 ? Math.min(...indents) : 0;
+  return lines.map((line) => line.slice(minIndent)).join("\n");
+}
+
 // src/markdown/index.ts
 var import_markdown_it = __toESM(require("markdown-it"), 1);
 
@@ -232,6 +428,72 @@ function respecCitePlugin(md) {
   md.inline.ruler.before("link", NAME, tokenize);
 }
 
+// src/markdown/plugins/mermaid.ts
+function ensureDom() {
+  if (typeof window !== "undefined" && typeof document !== "undefined") {
+    return;
+  }
+  if (typeof require !== "function") {
+    return;
+  }
+  const { DOMParser: DOMParser3 } = require("linkedom");
+  const { document: doc } = new DOMParser3().parseFromString("<html></html>", "text/html");
+  globalThis.window = doc.defaultView;
+  globalThis.document = doc;
+}
+function getMermaidAPI() {
+  const globalMermaid = globalThis.mermaid;
+  if (globalMermaid?.mermaidAPI) {
+    return globalMermaid.mermaidAPI;
+  }
+  if (globalThis.mermaidAPI) {
+    return globalThis.mermaidAPI;
+  }
+  if (typeof require === "function") {
+    try {
+      return require("mermaid").mermaidAPI;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+function respecMermaidPlugin(md, config = {}) {
+  const defaultFence = md.renderer.rules.fence ?? ((tokens, idx) => `<pre><code>${md.utils.escapeHtml(tokens[idx].content)}</code></pre>
+`);
+  md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+    const token = tokens[idx];
+    if (token.info.trim() !== "mermaid") {
+      return defaultFence(tokens, idx, options, env, self);
+    }
+    const mermaidAPI = getMermaidAPI();
+    if (!mermaidAPI) {
+      const code = md.utils.escapeHtml(token.content);
+      return `<pre><code>${code}</code></pre>
+`;
+    }
+    try {
+      ensureDom();
+      mermaidAPI.initialize(config);
+      const id = `mermaid-${idx}`;
+      const svg = mermaidAPI.render(id, token.content);
+      return `<div class="mermaid">${svg}</div>`;
+    } catch {
+      const code = md.utils.escapeHtml(token.content);
+      return `<pre><code>${code}</code></pre>
+`;
+    }
+  };
+}
+
+// src/utils/render.ts
+function insertContent(element, content) {
+  element.innerHTML = content;
+}
+function renderError(message) {
+  return `<p class="error">${message}</p>`;
+}
+
 // src/markdown/index.ts
 function createMarkdownRenderer(options = {}) {
   const md = new import_markdown_it.default({
@@ -269,6 +531,10 @@ function createMarkdownRenderer(options = {}) {
   md.use(respecConceptPlugin);
   md.use(respecIdlPlugin);
   md.use(respecCitePlugin);
+  if (options.mermaid) {
+    const config = options.mermaid === true ? {} : options.mermaid;
+    md.use(respecMermaidPlugin, config);
+  }
   for (const extension of options.extensions ?? []) {
     if (Array.isArray(extension)) {
       const [plugin, pluginOptions] = extension;
@@ -285,56 +551,88 @@ function parseMarkdown(markdown, options = {}, env) {
     return md.render(markdown, env);
   } catch (error) {
     console.error("Markdown parsing error:", error);
-    return `<p class="error">Error parsing markdown: ${error instanceof Error ? error.message : "Unknown error"}</p>`;
+    return renderError(
+      `Error parsing markdown: ${error instanceof Error ? error.message : "Unknown error"}`
+    );
   }
 }
 function slugify(content) {
   return content.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-");
 }
 
-// src/utils/strip-ident.ts
-function stripIndent(content) {
-  const lines = content.replace(/\r\n?/g, "\n").split("\n");
-  const indents = lines.filter((line) => line.trim().length > 0).map((line) => line.match(/^\s*/)?.[0].length || 0);
-  const minIndent = indents.length > 0 ? Math.min(...indents) : 0;
-  return lines.map((line) => line.slice(minIndent)).join("\n");
-}
-
-// src/processors/format-processor.ts
-var FormatProcessor = class {
-  constructor(markdownOptions = {}) {
-    this.markdownOptions = markdownOptions;
+// src/format-registry.ts
+var MarkdownStrategy = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  convert(content) {
+    return parseMarkdown(content, this.options);
+  }
+};
+var PassthroughStrategy = class {
+  convert(content) {
+    return content;
+  }
+};
+var FormatRegistry = class {
+  constructor(markdownOptions = {}, customStrategies = {}) {
+    const markdown = new MarkdownStrategy(markdownOptions);
+    const passthrough = new PassthroughStrategy();
+    this.strategies = /* @__PURE__ */ new Map([
+      ["markdown", markdown],
+      ["text", passthrough],
+      ["html", passthrough]
+    ]);
+    for (const [format, strategy] of Object.entries(customStrategies)) {
+      this.strategies.set(format, strategy);
+    }
+  }
+  /**
+   * Register a new strategy for a given format.
+   */
+  register(format, strategy) {
+    this.strategies.set(format, strategy);
   }
   /**
    * Convert content based on the specified format.
    */
   processContent(content, format) {
-    switch (format) {
-      case "markdown":
-        return parseMarkdown(content, this.markdownOptions);
-      case "text":
-      case "html":
-      default:
-        return content;
+    const strategy = this.strategies.get(format);
+    if (!strategy) {
+      throw new Error(`Unsupported format: ${format}`);
     }
+    return strategy.convert(content);
   }
-  /**
-   * Process an element with a data-format attribute.
-   */
-  process(element, stats, warnings) {
+};
+
+// src/processors/format-processor.ts
+var FormatProcessor = class {
+  constructor(registry = new FormatRegistry()) {
+    this.registry = registry;
+  }
+  matches(element) {
+    return element.hasAttribute("data-format");
+  }
+  process(element, tracker, _warnings) {
     const format = element.getAttribute("data-format");
+    let result = {};
     if (format === "markdown" && element.innerHTML.trim()) {
       try {
         const markdownContent = stripIndent(element.innerHTML).trim();
-        element.innerHTML = this.processContent(markdownContent, format);
-        stats.markdownBlocks++;
+        result.content = this.registry.processContent(markdownContent, format);
+        tracker.incrementMarkdownBlocks();
       } catch (error) {
-        const errorMsg = `Failed to process markdown: ${error instanceof Error ? error.message : "Unknown error"}`;
-        warnings.push(errorMsg);
-        element.innerHTML = `<p class="error">${errorMsg}</p>`;
+        result.error = `Failed to process markdown: ${error instanceof Error ? error.message : "Unknown error"}`;
+      }
+    } else {
+      try {
+        result.content = this.registry.processContent(element.innerHTML, format);
+      } catch (error) {
+        result.error = error instanceof Error ? error.message : String(error);
       }
     }
     element.removeAttribute("data-format");
+    return result;
   }
 };
 
@@ -478,17 +776,27 @@ function resolveIdlLinks(root, index, warnings, suppressClass) {
     }
   });
 }
-var idlPass = {
-  async run(root, options) {
+var IdlPass = class {
+  constructor(root) {
+    this.root = root;
+    this.area = "idl";
+  }
+  async execute(_data, config) {
     const warnings = [];
-    const suppressClass = options.diagnostics?.suppressClass ?? "no-link-warnings";
-    const index = buildIdlIndex(root, warnings);
-    resolveIdlLinks(root, index, warnings, suppressClass);
-    return warnings;
+    const suppressClass = config.postprocess?.diagnostics?.suppressClass ?? "no-link-warnings";
+    const index = buildIdlIndex(this.root, warnings);
+    resolveIdlLinks(this.root, index, warnings, suppressClass);
+    return { warnings };
+  }
+  async run(ctx, next) {
+    const current = ctx.outputs[this.area];
+    const { warnings } = await this.execute(current, ctx.config);
+    if (warnings && warnings.length) ctx.warnings.push(...warnings);
+    await next();
   }
 };
 
-// src/pipeline/passes/xref.ts
+// src/xref/local-map.ts
 function uniqueId2(doc, base) {
   let id = base;
   let i = 2;
@@ -501,9 +809,6 @@ function norm2(term) {
 function slugify2(text) {
   return text.trim().toLowerCase().replace(/[^\w]+/g, "-").replace(/^-+|-+$/g, "");
 }
-function isSuppressed(node, suppressClass) {
-  return !!node.closest(`.${suppressClass}`);
-}
 function buildLocalMap(root) {
   const map = /* @__PURE__ */ new Map();
   const doc = root.ownerDocument;
@@ -548,72 +853,159 @@ function buildLocalMap(root) {
   });
   return map;
 }
-var xrefPass = {
-  async run(root, options) {
-    const suppressClass = options.diagnostics?.suppressClass ?? "no-link-warnings";
-    const warnings = [];
-    const localMap = buildLocalMap(root);
-    const xrefAnchors = Array.from(root.querySelectorAll("a[data-xref]"));
-    const unresolved = /* @__PURE__ */ new Map();
-    for (const a of xrefAnchors) {
-      if (isSuppressed(a, suppressClass)) continue;
-      const term = a.getAttribute("data-xref") || "";
-      const key = norm2(term);
-      const hit = localMap.get(key);
-      if (hit) {
-        a.setAttribute("href", hit.href);
+
+// src/xref/resolve.ts
+async function resolveQueries(resolverConfigs, unresolved) {
+  const warnings = [];
+  for (const cfg of resolverConfigs) {
+    const queries = [];
+    const idMap = /* @__PURE__ */ new Map();
+    for (const [key, entry] of unresolved.entries()) {
+      let specs;
+      if (entry.specsOverride) {
+        const allowed = cfg.specs ? entry.specsOverride.filter((s) => cfg.specs.includes(s)) : entry.specsOverride;
+        specs = allowed;
       } else {
-        const bucket = unresolved.get(key) || [];
-        bucket.push(a);
-        unresolved.set(key, bucket);
+        specs = cfg.specs;
       }
+      if (specs && specs.length === 0) continue;
+      const id = `${key}|${queries.length}`;
+      const q = { id, term: entry.term };
+      if (specs && specs.length) q.specs = specs;
+      queries.push(q);
+      idMap.set(id, entry);
     }
-    const resolver = options.xref?.resolver;
-    if (resolver && unresolved.size) {
-      const queries = Array.from(unresolved.keys()).map((term) => ({ term }));
-      resolver.resolveBatch(queries, options.xref?.specs).then((results) => {
-        for (const [key, anchors] of unresolved.entries()) {
-          const res = results.get(key);
-          if (!res) continue;
-          for (const a of anchors) {
-            a.setAttribute("href", res.href);
-            if (res.cite) a.setAttribute("data-cite", res.cite);
-          }
-          unresolved.delete(key);
-        }
-      }).catch((err) => {
-        warnings.push(`Xref resolver failed: ${err instanceof Error ? err.message : String(err)}`);
-      });
+    if (!queries.length) continue;
+    try {
+      const resMap = await cfg.resolver.resolveBatch(queries);
+      for (const [id, hits] of resMap.entries()) {
+        const entry = idMap.get(id);
+        if (entry) entry.results.push(...hits);
+      }
+    } catch (err) {
+      warnings.push(
+        `Xref resolver failed: ${err instanceof Error ? err.message : String(err)}`
+      );
     }
-    for (const [key, anchors] of unresolved.entries()) {
-      const original = anchors[0].getAttribute("data-xref") || key;
-      warnings.push(`Unresolved xref: "${original}"`);
+  }
+  return { unresolved, warnings };
+}
+
+// src/pipeline/passes/xref.ts
+function isSuppressed(node, suppressClass) {
+  return !!node.closest(`.${suppressClass}`);
+}
+function getCiteSpecs(node) {
+  let el = node;
+  while (el) {
+    const cite = el.getAttribute("data-cite");
+    if (cite) {
+      return cite.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean);
     }
-    return warnings;
+    el = el.parentElement;
+  }
+  return void 0;
+}
+var XrefPass = class {
+  constructor(root) {
+    this.root = root;
+    this.area = "xref";
+  }
+  async execute(_data, config) {
+    const suppressClass = config.postprocess?.diagnostics?.suppressClass ?? "no-link-warnings";
+    const localMap = buildLocalMap(this.root);
+    const xrefAnchors = Array.from(this.root.querySelectorAll("a[data-xref]"));
+    const resolverConfigs = Array.isArray(config.postprocess?.xref) ? config.postprocess.xref : config.postprocess?.xref ? [config.postprocess.xref] : [];
+    const unresolved = collectUnresolvedAnchors(xrefAnchors, localMap, suppressClass);
+    const { unresolved: resolvedEntries, warnings: resolveWarnings } = await resolveQueries(
+      resolverConfigs,
+      unresolved
+    );
+    const defaultPriority = resolverConfigs.flatMap((cfg) => cfg.specs || []);
+    const applyWarnings = applyXrefResults(resolvedEntries, defaultPriority);
+    return { warnings: [...resolveWarnings, ...applyWarnings] };
+  }
+  async run(ctx, next) {
+    const current = ctx.outputs[this.area];
+    const { warnings } = await this.execute(current, ctx.config);
+    if (warnings && warnings.length) ctx.warnings.push(...warnings);
+    await next();
   }
 };
-
-// src/pipeline/passes/references.ts
-function ensureSection(root, id, title) {
-  let section = root.querySelector(`#${id}`);
-  if (!section) {
-    section = root.ownerDocument.createElement("section");
-    section.id = id;
-    section.innerHTML = `<h2>${title}</h2>`;
-    root.appendChild(section);
-  }
-  return section;
-}
-function ensureSubsection(parent, id, title) {
-  let sec = parent.querySelector(`#${id}`);
-  if (!sec) {
-    sec = parent.ownerDocument.createElement("section");
-    sec.id = id;
-    sec.innerHTML = `<h3>${title}</h3><ul></ul>`;
-    parent.appendChild(sec);
+function collectUnresolvedAnchors(anchors, localMap, suppressClass) {
+  const unresolved = /* @__PURE__ */ new Map();
+  for (const a of anchors) {
+    if (isSuppressed(a, suppressClass)) continue;
+    const term = a.getAttribute("data-xref") || "";
+    const key = norm2(term);
+    const hit = localMap.get(key);
+    if (hit) {
+      a.setAttribute("href", hit.href);
+      continue;
+    }
+    const specsOverride = getCiteSpecs(a);
+    const mapKey = `${key}|${(specsOverride || []).join(",")}`;
+    let entry = unresolved.get(mapKey);
+    if (!entry) {
+      entry = { term, anchors: [], results: [] };
+      if (specsOverride) entry.specsOverride = specsOverride;
+      unresolved.set(mapKey, entry);
+    }
+    entry.anchors.push(a);
   }
-  return sec;
+  return unresolved;
+}
+function applyXrefResults(unresolved, defaultPriority) {
+  const warnings = [];
+  for (const entry of unresolved.values()) {
+    const hits = entry.results;
+    let chosen;
+    let ambiguous = false;
+    const preferred = entry.specsOverride && entry.specsOverride.length ? entry.specsOverride : defaultPriority;
+    if (hits.length > 0) {
+      if (preferred && preferred.length) {
+        const remaining = new Set(hits);
+        for (const spec of preferred) {
+          const matches = hits.filter((h) => h.cite === spec);
+          matches.forEach((m) => remaining.delete(m));
+          if (matches.length === 1) {
+            chosen = matches[0];
+            break;
+          }
+          if (matches.length > 1) {
+            ambiguous = true;
+            break;
+          }
+        }
+        if (!chosen && !ambiguous) {
+          const leftovers = Array.from(remaining);
+          if (leftovers.length === 1) {
+            chosen = leftovers[0];
+          } else if (leftovers.length > 1) {
+            ambiguous = true;
+          }
+        }
+      } else if (hits.length === 1) {
+        chosen = hits[0];
+      } else {
+        ambiguous = true;
+      }
+    }
+    if (chosen) {
+      for (const a of entry.anchors) {
+        a.setAttribute("href", chosen.href);
+        if (chosen.cite) a.setAttribute("data-cite", chosen.cite);
+      }
+    } else if (ambiguous) {
+      warnings.push(`Ambiguous xref: "${entry.term}"`);
+    } else {
+      warnings.push(`No matching xref: "${entry.term}"`);
+    }
+  }
+  return warnings;
 }
+
+// src/renderers/references-renderer.ts
 function formatEntry(id, e) {
   const parts = [];
   parts.push(`<span class="ref-id">[${id}]</span>`);
@@ -629,86 +1021,111 @@ function formatEntry(id, e) {
 function idForRef(id) {
   return `bib-${id.toLowerCase()}`;
 }
-var referencesPass = {
-  async run(root, options) {
-    const warnings = [];
-    const biblio = options.biblio?.entries ?? {};
-    const cites = Array.from(root.querySelectorAll("a[data-spec]"));
-    if (!cites.length) return warnings;
-    const normative = /* @__PURE__ */ new Set();
-    const informative = /* @__PURE__ */ new Set();
-    for (const a of cites) {
-      const id = (a.getAttribute("data-spec") || "").trim();
-      const norm3 = (a.getAttribute("data-normative") || "false") === "true";
-      (norm3 ? normative : informative).add(id);
-    }
-    for (const id of normative) informative.delete(id);
-    const refs = ensureSection(root, "references", "References");
-    const normSec = ensureSubsection(refs, "normative-references", "Normative references");
-    const infoSec = ensureSubsection(refs, "informative-references", "Informative references");
-    const renderList = (sec, ids) => {
+var ReferencesRenderer = class {
+  constructor(doc) {
+    this.doc = doc;
+  }
+  render(data) {
+    const section = this.doc.createElement("section");
+    section.id = "references";
+    const normSec = this.doc.createElement("section");
+    normSec.id = "normative-references";
+    normSec.innerHTML = "<h3>Normative references</h3><ul></ul>";
+    const infoSec = this.doc.createElement("section");
+    infoSec.id = "informative-references";
+    infoSec.innerHTML = "<h3>Informative references</h3><ul></ul>";
+    section.innerHTML = "<h2>References</h2>";
+    section.appendChild(normSec);
+    section.appendChild(infoSec);
+    const renderList = (sec, items) => {
       const ul = sec.querySelector("ul");
       ul.innerHTML = "";
-      Array.from(ids).sort((a, b) => a.localeCompare(b)).forEach((id) => {
-        const li = root.ownerDocument.createElement("li");
+      items.sort((a, b) => a.id.localeCompare(b.id)).forEach(({ id, entry }) => {
+        const li = this.doc.createElement("li");
         li.id = idForRef(id);
-        const entry = biblio[id];
         if (entry) {
           li.innerHTML = formatEntry(id, entry);
         } else {
           li.setAttribute("data-spec", id);
           li.innerHTML = `<span class="ref-id">[${id}]</span> <span class="ref-missing">\u2014 unresolved reference</span>`;
-          warnings.push(`Unresolved reference: "${id}"`);
         }
         ul.appendChild(li);
       });
     };
-    renderList(normSec, normative);
-    renderList(infoSec, informative);
+    renderList(normSec, data.normative);
+    renderList(infoSec, data.informative);
+    return section.outerHTML;
+  }
+};
+
+// src/pipeline/passes/references.ts
+var ReferencesPass = class {
+  constructor(root) {
+    this.root = root;
+    this.area = "references";
+  }
+  async execute(_data, config) {
+    const warnings = [];
+    const biblio = config.postprocess?.biblio?.entries ?? {};
+    const cites = Array.from(this.root.querySelectorAll("a[data-spec]"));
+    if (!cites.length) return { data: { html: "", citeUpdates: [] }, warnings };
+    const normativeIds = /* @__PURE__ */ new Set();
+    const informativeIds = /* @__PURE__ */ new Set();
+    for (const a of cites) {
+      const id = (a.getAttribute("data-spec") || "").trim();
+      const norm3 = (a.getAttribute("data-normative") || "false") === "true";
+      (norm3 ? normativeIds : informativeIds).add(id);
+    }
+    for (const id of normativeIds) informativeIds.delete(id);
+    const normative = [];
+    const informative = [];
+    Array.from(normativeIds).sort((a, b) => a.localeCompare(b)).forEach((id) => {
+      const entry = biblio[id];
+      if (!entry) warnings.push(`Unresolved reference: "${id}"`);
+      normative.push({ id, entry });
+    });
+    Array.from(informativeIds).sort((a, b) => a.localeCompare(b)).forEach((id) => {
+      const entry = biblio[id];
+      if (!entry) warnings.push(`Unresolved reference: "${id}"`);
+      informative.push({ id, entry });
+    });
+    const renderer = new ReferencesRenderer(this.root.ownerDocument);
+    const html = renderer.render({ normative, informative });
+    const citeUpdates = [];
     for (const a of cites) {
       const id = (a.getAttribute("data-spec") || "").trim();
       const targetId = idForRef(id);
-      a.setAttribute("href", `#${targetId}`);
-      a.setAttribute("data-cite-ref", targetId);
+      citeUpdates.push({ element: a, href: `#${targetId}` });
     }
-    return warnings;
+    return { data: { html, citeUpdates }, warnings };
+  }
+  async run(ctx, next) {
+    const current = ctx.outputs[this.area];
+    const { data, warnings } = await this.execute(current, ctx.config);
+    if (data !== void 0) ctx.outputs[this.area] = data;
+    if (warnings && warnings.length) ctx.warnings.push(...warnings);
+    await next();
   }
 };
 
 // src/pipeline/passes/boilerplate.ts
-function createSection(doc, id, title, content) {
-  const sec = doc.createElement("section");
-  sec.id = id;
-  const h2 = doc.createElement("h2");
-  h2.textContent = title;
-  sec.appendChild(h2);
-  if (content) {
-    const p = doc.createElement("p");
-    p.textContent = content;
-    sec.appendChild(p);
+var BoilerplatePass = class {
+  constructor(root) {
+    this.root = root;
+    this.area = "boilerplate";
   }
-  return sec;
-}
-var boilerplatePass = {
-  async run(root, options) {
-    const bp = options.boilerplate;
-    if (!bp) return [];
-    const doc = root.ownerDocument;
+  async execute(_data, config) {
+    const bp = config.postprocess?.boilerplate;
+    if (!bp) return { data: { sections: [], ref: null }, warnings: [] };
     const mountMode = bp.mount || "end";
     let ref = null;
     if (mountMode === "before-references") {
-      ref = root.querySelector("#references");
+      ref = this.root.querySelector("#references");
     } else if (mountMode === "after-toc") {
-      const toc = root.querySelector("#toc");
+      const toc = this.root.querySelector("#toc");
       ref = toc ? toc.nextSibling : null;
     }
-    const insert = (section) => {
-      if (ref) {
-        root.insertBefore(section, ref);
-      } else {
-        root.appendChild(section);
-      }
-    };
+    const sections = [];
     const defs = [
       { key: "conformance", title: "Conformance" },
       { key: "security", title: "Security" },
@@ -719,52 +1136,138 @@ var boilerplatePass = {
       if (!opt) continue;
       const cfg = typeof opt === "object" ? opt : {};
       const id = cfg.id || key;
-      if (root.querySelector(`#${id}`)) continue;
+      if (this.root.querySelector(`#${id}`)) continue;
       const title = cfg.title || defaultTitle;
       const content = cfg.content;
-      const sec = createSection(doc, id, title, content);
-      insert(sec);
+      const descriptor = { id, title };
+      if (content !== void 0) descriptor.content = content;
+      sections.push(descriptor);
+    }
+    return { data: { sections, ref }, warnings: [] };
+  }
+  async run(ctx, next) {
+    const current = ctx.outputs[this.area];
+    const { data, warnings } = await this.execute(current, ctx.config);
+    if (data !== void 0) ctx.outputs[this.area] = data;
+    if (warnings && warnings.length) ctx.warnings.push(...warnings);
+    await next();
+  }
+};
+
+// src/renderers/boilerplate-renderer.ts
+function createSection(doc, id, title, content) {
+  const sec = doc.createElement("section");
+  sec.id = id;
+  const h2 = doc.createElement("h2");
+  h2.textContent = title;
+  sec.appendChild(h2);
+  if (content) {
+    const p = doc.createElement("p");
+    p.textContent = content;
+    sec.appendChild(p);
+  }
+  return sec;
+}
+var BoilerplateRenderer = class {
+  constructor(doc) {
+    this.doc = doc;
+  }
+  render(descriptors) {
+    return descriptors.map((d) => createSection(this.doc, d.id, d.title, d.content));
+  }
+};
+
+// src/renderers/toc-renderer.ts
+var TocRenderer = class {
+  constructor(doc) {
+    this.doc = doc;
+  }
+  render(items = []) {
+    if (!items.length) return { toc: "" };
+    const minDepth = Math.min(...items.map((i) => i.depth));
+    const rootOl = this.doc.createElement("ol");
+    rootOl.setAttribute("role", "list");
+    const olStack = [rootOl];
+    let currentDepth = 1;
+    for (const item of items) {
+      const targetDepth = item.depth - minDepth + 1;
+      while (targetDepth > currentDepth) {
+        const newOl = this.doc.createElement("ol");
+        newOl.setAttribute("role", "list");
+        const parentOl = olStack[olStack.length - 1];
+        let parentLi = parentOl.lastElementChild;
+        if (!parentLi) {
+          parentLi = this.doc.createElement("li");
+          parentOl.appendChild(parentLi);
+        }
+        parentLi.appendChild(newOl);
+        olStack.push(newOl);
+        currentDepth++;
+      }
+      while (targetDepth < currentDepth) {
+        olStack.pop();
+        currentDepth--;
+      }
+      const currentOl = olStack[olStack.length - 1];
+      const li = this.doc.createElement("li");
+      li.setAttribute("data-depth", String(item.depth));
+      const a = this.doc.createElement("a");
+      a.href = `#${item.id}`;
+      a.textContent = item.text;
+      li.appendChild(a);
+      currentOl.appendChild(li);
     }
-    return [];
+    return { toc: rootOl.outerHTML };
   }
 };
 
 // src/pipeline/passes/toc.ts
-var tocPass = {
-  async run(root, options) {
-    const { toc } = options;
-    if (toc?.enabled === false) return [];
-    const selector = toc?.selector ?? "#toc";
-    const mount = root.querySelector(selector);
-    if (!mount) return [];
-    const headings = Array.from(root.querySelectorAll("h2, h3"));
-    if (!headings.length) return [];
-    const doc = root.ownerDocument;
-    const ol = doc.createElement("ol");
-    ol.setAttribute("role", "list");
-    for (const h of headings) {
-      if (!h.id) continue;
-      const li = doc.createElement("li");
-      const depth = h.tagName.toLowerCase() === "h3" ? 2 : 1;
-      li.setAttribute("data-depth", String(depth));
-      li.innerHTML = `<a href="#${h.id}">${h.textContent || ""}</a>`;
-      ol.appendChild(li);
-    }
-    mount.innerHTML = "";
-    mount.appendChild(ol);
-    return [];
+function collectTocItems(root) {
+  const headings = Array.from(root.querySelectorAll("h2, h3, h4"));
+  const items = [];
+  for (const h of headings) {
+    if (!h.id) continue;
+    const depth = h.tagName.toLowerCase() === "h3" ? 2 : h.tagName.toLowerCase() === "h4" ? 3 : 1;
+    items.push({ id: h.id, text: h.textContent || "", depth });
+  }
+  return items;
+}
+var TocPass = class {
+  constructor(root) {
+    this.root = root;
+    this.area = "toc";
+  }
+  async execute(_data, config) {
+    const { toc } = config.postprocess || {};
+    if (toc?.enabled === false) return { data: "", warnings: [] };
+    const items = collectTocItems(this.root);
+    if (!items.length) return { data: "", warnings: [] };
+    const renderer = new TocRenderer(this.root.ownerDocument);
+    const { toc: tocHtml } = renderer.render(items);
+    return { data: tocHtml, warnings: [] };
+  }
+  async run(ctx, next) {
+    const current = ctx.outputs[this.area];
+    const { data, warnings } = await this.execute(current, ctx.config);
+    if (data !== void 0) ctx.outputs[this.area] = data;
+    if (warnings && warnings.length) ctx.warnings.push(...warnings);
+    await next();
   }
 };
 
 // src/pipeline/passes/diagnostics.ts
-var diagnosticsPass = {
-  async run(root, options) {
+var DiagnosticsPass = class {
+  constructor(root) {
+    this.root = root;
+    this.area = "diagnostics";
+  }
+  async execute(_data, config) {
     const warnings = [];
-    const suppressClass = options.diagnostics?.suppressClass ?? "no-link-warnings";
-    const idsAndLinks = options.diagnostics?.idsAndLinks ?? true;
+    const suppressClass = config.postprocess?.diagnostics?.suppressClass ?? "no-link-warnings";
+    const idsAndLinks = config.postprocess?.diagnostics?.idsAndLinks ?? true;
     if (idsAndLinks) {
       const seen = /* @__PURE__ */ new Map();
-      root.querySelectorAll("[id]").forEach((el) => {
+      this.root.querySelectorAll("[id]").forEach((el) => {
         const id = el.id;
         if (!id) return;
         if (seen.has(id)) {
@@ -775,7 +1278,7 @@ var diagnosticsPass = {
           seen.set(id, el);
         }
       });
-      const anchors = root.querySelectorAll("a");
+      const anchors = this.root.querySelectorAll("a");
       anchors.forEach((a) => {
         if (a.closest(`.${suppressClass}`)) return;
         const hasHref = a.hasAttribute("href") && a.getAttribute("href") !== "";
@@ -786,44 +1289,206 @@ var diagnosticsPass = {
         }
       });
     }
-    return warnings;
+    return { warnings };
+  }
+  async run(ctx, next) {
+    const current = ctx.outputs[this.area];
+    const { warnings } = await this.execute(current, ctx.config);
+    if (warnings && warnings.length) ctx.warnings.push(...warnings);
+    await next();
+  }
+};
+
+// src/pipeline/passes/assertions.ts
+function getSpecAndVersionFromBaseUrl(baseUrl) {
+  if (!baseUrl) return {};
+  try {
+    const url = new URL(baseUrl);
+    const parts = url.pathname.replace(/\/+$/, "").split("/").filter(Boolean);
+    const n = parts.length;
+    if (n >= 2) {
+      const version = parts[n - 1];
+      const spec = parts[n - 2];
+      return { spec, version };
+    }
+  } catch {
+  }
+  return {};
+}
+function toStandardId(prefix, major, seq) {
+  const n = String(seq).padStart(3, "0");
+  return `${prefix}-${major}-${n}`;
+}
+function closestBlock(el) {
+  return el.closest("p, li, dd, dt, td, th, blockquote") || null;
+}
+function normText(el) {
+  const text = (el.textContent || "").replace(/\s+/g, " ").trim();
+  return text.length > 200 ? `${text.slice(0, 197)}...` : text;
+}
+function ensureUniqueId(root, desired) {
+  let id = desired;
+  let i = 1;
+  const doc = root.ownerDocument;
+  while (doc && typeof doc.getElementById === "function" && doc.getElementById(id)) {
+    id = `${desired}-${i++}`;
+  }
+  return id;
+}
+var AssertionsPass = class {
+  constructor(root) {
+    this.root = root;
+    this.area = "assertions";
+  }
+  async execute(_data, config) {
+    const warnings = [];
+    const { spec: specOpt, version: versionOpt } = config.postprocess?.assertions || {};
+    const { spec: specFromPath, version: versionFromPath } = getSpecAndVersionFromBaseUrl(config.baseUrl);
+    const spec = (specOpt || specFromPath || "SPEC").toUpperCase();
+    const version = (versionOpt || versionFromPath || "0").toString();
+    const majorMatch = version.match(/^(\d+)/);
+    const major = majorMatch ? majorMatch[1] : "0";
+    const map = /* @__PURE__ */ new Map();
+    const markers = Array.from(this.root.querySelectorAll("em.rfc2119"));
+    for (const em of markers) {
+      const block = closestBlock(em);
+      if (!block) continue;
+      const text = (em.textContent || "").trim().toUpperCase();
+      let type = void 0;
+      if (text === "MUST NOT") type = "MUST NOT";
+      else if (text === "MUST") type = "MUST";
+      else if (text === "SHOULD") type = "SHOULD";
+      else if (text === "MAY") type = "MAY";
+      if (!type) continue;
+      const entry = map.get(block) || { keywords: [], markers: [] };
+      entry.keywords.push(type);
+      entry.markers.push(em);
+      map.set(block, entry);
+    }
+    if (!map.size) return { data: [], warnings };
+    const selectors = "p, li, dd, dt, td, th, blockquote";
+    const blocksInOrder = Array.from(this.root.querySelectorAll(selectors)).filter((el) => map.has(el));
+    const items = [];
+    let seq = 1;
+    for (const block of blocksInOrder) {
+      const { keywords } = map.get(block);
+      if (keywords.length > 1) {
+        warnings.push(
+          `Multiple normative keywords (${keywords.join(", ")}) in block: "${normText(block)}"`
+        );
+      }
+      const type = keywords[0];
+      const standardId = toStandardId(spec, major, seq++);
+      let anchorId = block.id;
+      if (!anchorId) {
+        anchorId = ensureUniqueId(this.root, standardId);
+        block.id = anchorId;
+      }
+      block.setAttribute("data-assertion-id", standardId);
+      items.push({ id: standardId, anchorId, type, snippet: normText(block) });
+    }
+    return { data: items, warnings };
+  }
+  async run(ctx, next) {
+    const current = ctx.outputs[this.area];
+    const { data, warnings } = await this.execute(current, ctx.config);
+    if (data !== void 0) ctx.outputs[this.area] = data;
+    if (warnings && warnings.length) ctx.warnings.push(...warnings);
+    await next();
   }
 };
 
+// src/utils/output-areas.ts
+var CONFIG_TO_OUTPUT_MAP = [
+  {
+    fields: ["sections"],
+    outputs: ["idl", "xref", "references", "boilerplate", "toc", "diagnostics", "assertions"]
+  },
+  {
+    fields: ["header", "sotd", "pubrules", "legal"],
+    outputs: ["boilerplate"]
+  },
+  {
+    fields: ["lint"],
+    outputs: ["diagnostics"]
+  },
+  {
+    fields: ["xref", "mdn"],
+    outputs: ["xref"]
+  }
+];
+function fieldChanged(oldVal, newVal) {
+  if (Array.isArray(oldVal) && Array.isArray(newVal)) {
+    if (oldVal === newVal) return false;
+    if (oldVal.length !== newVal.length) return true;
+    for (let i = 0; i < oldVal.length; i++) {
+      if (oldVal[i] !== newVal[i]) return true;
+    }
+    return false;
+  }
+  return oldVal !== newVal;
+}
+function getChangedOutputAreas(oldConfig, newConfig) {
+  if (!oldConfig) {
+    const all = /* @__PURE__ */ new Set();
+    for (const mapping of CONFIG_TO_OUTPUT_MAP) {
+      for (const out of mapping.outputs) all.add(out);
+    }
+    return Array.from(all);
+  }
+  const areas = /* @__PURE__ */ new Set();
+  for (const { fields, outputs } of CONFIG_TO_OUTPUT_MAP) {
+    if (fields.some((f) => fieldChanged(oldConfig[f], newConfig[f]))) {
+      outputs.forEach((o) => areas.add(o));
+    }
+  }
+  return Array.from(areas);
+}
+
 // src/speculator.ts
 var Speculator = class {
   constructor(options = {}) {
     const baseUrl = options.baseUrl;
     const fileLoader = options.fileLoader || getDefaultFileLoader();
     const markdownOptions = options.markdownOptions || {};
-    this.postprocessOptions = options.postprocess || {};
-    this.formatProcessor = options.formatProcessor || new FormatProcessor(markdownOptions);
-    this.includeProcessor = options.includeProcessor || new IncludeProcessor(baseUrl, fileLoader, this.formatProcessor);
+    this.baseConfig = { postprocess: options.postprocess || {} };
+    this.formatRegistry = options.formatRegistry || new FormatRegistry(markdownOptions);
+    this.formatProcessor = options.formatProcessor || new FormatProcessor(this.formatRegistry);
+    this.includeProcessor = options.includeProcessor || new IncludeProcessor(baseUrl, fileLoader, this.formatRegistry);
     this.htmlRenderer = options.htmlRenderer || new DOMHtmlRenderer();
+    this.documentBuilder = new DocumentBuilder(this, this.htmlRenderer);
+    this.processors = [this.includeProcessor, this.formatProcessor];
+    const passes = options.passes;
+    if (Array.isArray(passes)) {
+      this.passFactory = () => passes;
+    } else if (typeof passes === "function") {
+      this.passFactory = passes;
+    } else {
+      this.passFactory = (container) => {
+        return [
+          new IdlPass(container),
+          new XrefPass(container),
+          new ReferencesPass(container),
+          new BoilerplatePass(container),
+          new TocPass(container),
+          new AssertionsPass(container),
+          new DiagnosticsPass(container)
+        ];
+      };
+    }
+    this.pipelineRunner = new PipelineRunner(this.passFactory);
   }
   /**
    * Process a single DOM element
    */
-  async processElement(element) {
-    const startTime = performance.now();
-    const stats = {
-      elementsProcessed: 0,
-      filesIncluded: 0,
-      markdownBlocks: 0,
-      processingTime: 0
-    };
+  async processElement(element, tracker = new StatsTracker()) {
+    tracker.start();
     const warnings = [];
     const clonedElement = element.cloneNode(true);
     try {
-      if (clonedElement.hasAttribute("data-include")) {
-        await this.includeProcessor.process(clonedElement, stats, warnings);
-      }
-      if (clonedElement.hasAttribute("data-format")) {
-        this.formatProcessor.process(clonedElement, stats, warnings);
-      }
-      stats.elementsProcessed = 1;
-      stats.processingTime = performance.now() - startTime;
-      return { element: clonedElement, warnings, stats };
+      await this.processNode(clonedElement, tracker, warnings);
+      tracker.stop();
+      return { element: clonedElement, warnings, stats: tracker.toJSON() };
     } catch (error) {
       throw new SpeculatorError(
         `Failed to process element: ${error instanceof Error ? error.message : "Unknown error"}`,
@@ -831,66 +1496,126 @@ var Speculator = class {
       );
     }
   }
+  async processNode(node, tracker, warnings) {
+    let matched = false;
+    for (const processor of this.processors) {
+      if (!processor.matches(node)) continue;
+      matched = true;
+      const { content, error } = await processor.process(node, tracker, warnings);
+      if (error) {
+        warnings.push(error);
+        insertContent(node, renderError(error));
+        continue;
+      }
+      if (content !== void 0 && content !== null) {
+        let renderedContent = content;
+        if (processor instanceof FormatProcessor) {
+          const rendered = this.htmlRenderer.parse(content);
+          renderedContent = this.htmlRenderer.serialize(rendered);
+        }
+        insertContent(node, renderedContent);
+      }
+    }
+    if (matched) tracker.incrementElements();
+    const children = Array.from(node.children);
+    for (const child of children) {
+      await this.processNode(child, tracker, warnings);
+    }
+  }
   /**
-   * Process an entire document
+   * Process an entire document described by a SpeculatorConfig
    */
-  async renderDocument(container) {
+  async renderDocument(spec, configOrOutputs = {}) {
     const startTime = performance.now();
-    const sections = container.querySelectorAll(
-      "section[data-include], section[data-format], *[data-include], *[data-format]"
-    );
-    const allStats = {
-      elementsProcessed: 0,
-      filesIncluded: 0,
-      markdownBlocks: 0,
-      processingTime: 0
+    const config = {
+      ...this.baseConfig,
+      ...spec,
+      postprocess: { ...this.baseConfig.postprocess || {}, ...spec.postprocess || {} }
     };
-    const allWarnings = [];
-    const processedElements = [];
-    for (const section of Array.from(sections)) {
-      try {
-        const result = await this.processElement(section);
-        processedElements.push(result.element);
-        allStats.elementsProcessed += result.stats.elementsProcessed;
-        allStats.filesIncluded += result.stats.filesIncluded;
-        allStats.markdownBlocks += result.stats.markdownBlocks;
+    const { container, header, sotd, stats, warnings: sectionWarnings } = await this.documentBuilder.build(config);
+    const allWarnings = [...sectionWarnings];
+    let areas = getChangedOutputAreas(this.prevConfig, config);
+    this.prevConfig = config;
+    if (Array.isArray(configOrOutputs)) {
+      areas = areas.filter((a) => configOrOutputs.includes(a));
+    }
+    let toc;
+    let boilerplate;
+    let references;
+    let pipelineOutputs = {};
+    try {
+      if (areas.length) {
+        const result = await this.pipelineRunner.run(container, config, areas);
+        pipelineOutputs = result.outputs;
         allWarnings.push(...result.warnings);
-      } catch (error) {
-        allWarnings.push(
-          `Failed to process element: ${error instanceof Error ? error.message : "Unknown error"}`
-        );
-        processedElements.push(section);
+        if (result.outputs.toc) {
+          toc = result.outputs.toc;
+        }
+        const bpOut = result.outputs.boilerplate;
+        if (bpOut && bpOut.sections.length) {
+          const renderer = new BoilerplateRenderer(container.ownerDocument);
+          const nodes = renderer.render(bpOut.sections);
+          boilerplate = nodes.map((el) => el.outerHTML);
+        }
+        const refOut = result.outputs.references;
+        if (refOut && refOut.html) {
+          refOut.citeUpdates.forEach(
+            ({ element, href }) => element.setAttribute("href", href)
+          );
+          references = refOut.html;
+        }
       }
-    }
-    sections.forEach((section, index) => {
-      if (processedElements[index] && section.parentNode) {
-        section.parentNode.replaceChild(processedElements[index], section);
+      const hooks = config.postProcess ? Array.isArray(config.postProcess) ? config.postProcess : [config.postProcess] : [];
+      for (const hook of hooks) {
+        await hook(container, pipelineOutputs);
       }
-    });
-    const passes = [
-      idlPass,
-      xrefPass,
-      referencesPass,
-      boilerplatePass,
-      tocPass,
-      diagnosticsPass
-    ];
-    try {
-      const { warnings } = await postprocess(container, passes, this.postprocessOptions || {});
-      allWarnings.push(...warnings);
     } catch (e) {
-      allWarnings.push(`Postprocess failed: ${e instanceof Error ? e.message : "Unknown error"}`);
+      allWarnings.push(
+        `Postprocess failed: ${e instanceof Error ? e.message : "Unknown error"}`
+      );
     }
-    allStats.processingTime = performance.now() - startTime;
-    return { element: container, warnings: allWarnings, stats: allStats };
+    stats.processingTime = performance.now() - startTime;
+    const finalSections = Array.from(container.children).filter(
+      (el) => el !== header && el !== sotd
+    );
+    return {
+      sections: finalSections,
+      warnings: allWarnings,
+      toc,
+      stats,
+      ...header ? { header } : {},
+      ...sotd ? { sotd } : {},
+      ...boilerplate ? { boilerplate } : {},
+      ...references ? { references } : {}
+    };
+  }
+  async renderSections(inputHtml) {
+    const container = this.htmlRenderer.parse(inputHtml);
+    const sections = Array.from(container.children);
+    return this.renderDocument({ sections });
   }
   /**
    * Process HTML string and return processed HTML
    */
-  async renderHTML(html) {
-    const container = this.htmlRenderer.parse(html);
-    await this.renderDocument(container);
-    return this.htmlRenderer.serialize(container);
+  async renderHTML(inputHtml) {
+    const result = await this.renderSections(inputHtml);
+    const container = this.htmlRenderer.parse("<div></div>");
+    const doc = container.ownerDocument;
+    const root = doc.createElement("div");
+    for (const section of result.sections) {
+      root.appendChild(section);
+    }
+    const htmlSections = this.htmlRenderer.serialize(root);
+    return {
+      sections: htmlSections,
+      toc: result.toc,
+      warnings: result.warnings,
+      stats: result.stats,
+      ...result.header ? { header: this.htmlRenderer.serialize(result.header) } : {},
+      ...result.sotd ? { sotd: this.htmlRenderer.serialize(result.sotd) } : {},
+      ...result.boilerplate ? { boilerplate: result.boilerplate } : {},
+      ...result.references ? { references: result.references } : {}
+    };
   }
 };
 
@@ -907,6 +1632,58 @@ var LinkedomHtmlRenderer = class {
   }
 };
 
+// src/utils/respec-xref-resolver.ts
+function groupQueriesBySpec(queries) {
+  const bySpec = /* @__PURE__ */ new Map();
+  for (const q of queries) {
+    const key = (q.specs || []).slice().sort().join(",");
+    const arr = bySpec.get(key) || [];
+    arr.push(q);
+    bySpec.set(key, arr);
+  }
+  return bySpec;
+}
+function buildXrefURL(endpoint, specKey, qs) {
+  const params = new URLSearchParams();
+  for (const q of qs) {
+    params.append("terms", q.term);
+  }
+  if (specKey) params.set("cite", specKey);
+  return `${endpoint}?${params.toString()}`;
+}
+function mapXrefResults(data, q) {
+  const list = data[q.term.toLowerCase()] || [];
+  return list.map((item) => ({
+    href: item.uri || item.url || item.href,
+    text: item.title || item.term || item.text,
+    cite: item.spec || item.shortname
+  })).filter((r) => !!r.href);
+}
+var RespecXrefResolver = class {
+  constructor(fetchFn = fetch, endpoint = "https://respec.org/xref") {
+    this.fetchFn = fetchFn;
+    this.endpoint = endpoint;
+  }
+  async resolveBatch(queries) {
+    const results = /* @__PURE__ */ new Map();
+    for (const [specKey, qs] of groupQueriesBySpec(queries)) {
+      const url = buildXrefURL(this.endpoint, specKey, qs);
+      try {
+        const resp = await this.fetchFn(url);
+        const data = await resp.json();
+        for (const q of qs) {
+          results.set(q.id || q.term, mapXrefResults(data, q));
+        }
+      } catch {
+        for (const q of qs) {
+          results.set(q.id || q.term, []);
+        }
+      }
+    }
+    return results;
+  }
+};
+
 // src/node.ts
 var Speculator2 = class extends Speculator {
   constructor(options = {}) {
@@ -917,13 +1694,18 @@ var Speculator2 = class extends Speculator {
 0 && (module.exports = {
   DOMHtmlRenderer,
   FormatProcessor,
+  FormatRegistry,
   IncludeProcessor,
   LinkedomHtmlRenderer,
+  RespecXrefResolver,
   Speculator,
   SpeculatorError,
+  StatsTracker,
   browserFileLoader,
   createFallbackFileLoader,
   createMarkdownRenderer,
+  fromRespecConfig,
+  getChangedOutputAreas,
   getDefaultFileLoader,
   nodeFileLoader,
   parseMarkdown