@illusions-lab/mdi 2.0.19 → 2.0.21

package/README.md

@@ -87,15 +87,32 @@ such as `3:18` count one-based Unicode grapheme clusters; ruby readings are a
 separate annotation channel anchored to the base-text range.
 
 ```ts
-import { getMdiTextBlocks, sourceSpansForTextRange } from "@illusions-lab/mdi";
+import { getMdiTextBlocks, resolveMdiSourceSpan, resolveMdiSourceSpans, sourceSpansForTextRange } from "@illusions-lab/mdi";
 
 const result = getMdiTextBlocks("{東京|とうきょう}");
 const block = result.blocks[0];
 console.log(block.text); // 東京
 console.log(block.annotations[0].anchor); // { start: "1:1", end: "1:3" }
 console.log(sourceSpansForTextRange(block, { start: "1:1", end: "1:3" }));
+console.log(resolveMdiSourceSpan("{東京|とうきょう}", { startByte: 1, endByte: 7 }));
+console.log(resolveMdiSourceSpans("same same", [{ startByte: 0, endByte: 4 }, { startByte: 5, endByte: 9 }]));
 ```
 
+`resolveMdiSourceSpan` accepts half-open UTF-8 byte offsets and returns ordered
+`blockText` and `annotation` matches in canonical grapheme coordinates.
+`coverage` is `complete`, `partial`, or `none`; each match is `exact` only when
+its complete forward source coverage equals the requested span. Ruby base text
+and readings are separate channels, and annotation indexes are zero-based.
+Zero-width spans are valid and return no matches. Pure Markdown/MDI delimiters,
+synthetic separators, and unmapped text do not acquire invented ranges, though
+a delimiter token already owned by one projected grapheme (such as an explicit
+break) can match. Reverse and forward mapping are therefore not generally
+bijective, especially for annotations, multi-byte token mappings, partial
+graphemes, discontinuous runs, and synthetic or unmapped text.
+For multiple lookups against one document, use `resolveMdiSourceSpans`. It
+validates the full array, performs one Rust parse/projection, and preserves
+input order; repeated calls to the singular convenience API each parse anew.
+
 Each source-derived grapheme is represented by a `sourceMap.runs` boundary;
 table tabs/newlines and multi-paragraph joiners appear in `synthetic` and do
 not receive invented source spans. `parseMdiTextPosition`,

package/dist/{chunk-JTDOLXFG.js → chunk-GMS5SFZO.js}

@@ -3,6 +3,7 @@ import * as mdiCore from "@illusions-lab/mdi-core";
 import { parse as parseYaml } from "yaml";
 var {
   getMdiTextBlocksJson,
+  resolveMdiSourceSpansJson,
   parseMdiSyntaxJson,
   renderHtml: renderHtmlFromRust,
   renderEpub: renderEpubFromRust,
@@ -42,6 +43,58 @@ function getMdiTextBlocks(source) {
   }
   return result;
 }
+function resolveMdiSourceSpan(source, span) {
+  return resolveMdiSourceSpans(source, [span])[0];
+}
+function resolveMdiSourceSpans(source, spans) {
+  if (typeof source !== "string") throw new TypeError("source must be a string");
+  if (!Array.isArray(spans)) throw new TypeError("spans must be an array");
+  if (spans.length === 0) return [];
+  const utf8 = utf8SourceBoundaries(source);
+  for (const [index, span] of spans.entries()) {
+    assertSourceSpanInput(span, `spans[${index}]`);
+    if (span.startByte > span.endByte) {
+      throw new RangeError(`spans[${index}].startByte must not exceed endByte`);
+    }
+    if (span.endByte > utf8.length) {
+      throw new RangeError(`spans[${index}] falls outside the UTF-8 source length`);
+    }
+    if (!utf8.boundaries.has(span.startByte) || !utf8.boundaries.has(span.endByte)) {
+      throw new RangeError(`spans[${index}] endpoints must be UTF-8 code-point boundaries`);
+    }
+  }
+  const results = JSON.parse(
+    resolveMdiSourceSpansJson(source, JSON.stringify(spans))
+  );
+  for (const result of results) {
+    if (result.projectionVersion !== MDI_TEXT_PROJECTION_VERSION) {
+      throw new Error(`Unsupported MDI text projection version: ${String(result.projectionVersion)}`);
+    }
+  }
+  return results;
+}
+function assertSourceSpanInput(span, name = "span") {
+  if (!span || typeof span !== "object" || Array.isArray(span)) {
+    throw new TypeError(`${name} must be an object`);
+  }
+  if (typeof span.startByte !== "number" || typeof span.endByte !== "number") {
+    throw new TypeError(`${name}.startByte and ${name}.endByte must be numbers`);
+  }
+  const isUint32 = (value) => Number.isInteger(value) && value >= 0 && value <= 4294967295;
+  if (!isUint32(span.startByte) || !isUint32(span.endByte)) {
+    throw new RangeError(`${name}.startByte and ${name}.endByte must be uint32 values`);
+  }
+}
+function utf8SourceBoundaries(source) {
+  let length = 0;
+  const boundaries = /* @__PURE__ */ new Set([0]);
+  for (const character of source) {
+    const codePoint = character.codePointAt(0);
+    length += codePoint <= 127 ? 1 : codePoint <= 2047 ? 2 : codePoint <= 65535 ? 3 : 4;
+    boundaries.add(length);
+  }
+  return { length, boundaries };
+}
 function parseMdiTextPosition(position) {
   if (typeof position !== "string") throw new TypeError("position must be a string");
   const match = /^([1-9]\d*):([1-9]\d*)$/.exec(position);
@@ -457,6 +510,8 @@ export {
   MDI_TEXT_PROJECTION_VERSION,
   parse,
   getMdiTextBlocks,
+  resolveMdiSourceSpan,
+  resolveMdiSourceSpans,
   parseMdiTextPosition,
   formatMdiTextPosition,
   formatMdiTextRange,

package/dist/index.cjs

@@ -53,6 +53,8 @@ __export(index_exports, {
   renderTextFormat: () => renderTextFormat,
   renderTextFormatWithDiagnostics: () => renderTextFormatWithDiagnostics,
   renderTextWithDiagnostics: () => renderTextWithDiagnostics,
+  resolveMdiSourceSpan: () => resolveMdiSourceSpan,
+  resolveMdiSourceSpans: () => resolveMdiSourceSpans,
   serializeMdi: () => serializeMdi,
   sourceSpansForTextRange: () => sourceSpansForTextRange,
   toPublicationMdast: () => toPublicationMdast
@@ -62,6 +64,7 @@ var mdiCore = __toESM(require("@illusions-lab/mdi-core"), 1);
 var import_yaml = require("yaml");
 var {
   getMdiTextBlocksJson,
+  resolveMdiSourceSpansJson,
   parseMdiSyntaxJson,
   renderHtml: renderHtmlFromRust,
   renderEpub: renderEpubFromRust,
@@ -101,6 +104,58 @@ function getMdiTextBlocks(source) {
   }
   return result;
 }
+function resolveMdiSourceSpan(source, span) {
+  return resolveMdiSourceSpans(source, [span])[0];
+}
+function resolveMdiSourceSpans(source, spans) {
+  if (typeof source !== "string") throw new TypeError("source must be a string");
+  if (!Array.isArray(spans)) throw new TypeError("spans must be an array");
+  if (spans.length === 0) return [];
+  const utf8 = utf8SourceBoundaries(source);
+  for (const [index, span] of spans.entries()) {
+    assertSourceSpanInput(span, `spans[${index}]`);
+    if (span.startByte > span.endByte) {
+      throw new RangeError(`spans[${index}].startByte must not exceed endByte`);
+    }
+    if (span.endByte > utf8.length) {
+      throw new RangeError(`spans[${index}] falls outside the UTF-8 source length`);
+    }
+    if (!utf8.boundaries.has(span.startByte) || !utf8.boundaries.has(span.endByte)) {
+      throw new RangeError(`spans[${index}] endpoints must be UTF-8 code-point boundaries`);
+    }
+  }
+  const results = JSON.parse(
+    resolveMdiSourceSpansJson(source, JSON.stringify(spans))
+  );
+  for (const result of results) {
+    if (result.projectionVersion !== MDI_TEXT_PROJECTION_VERSION) {
+      throw new Error(`Unsupported MDI text projection version: ${String(result.projectionVersion)}`);
+    }
+  }
+  return results;
+}
+function assertSourceSpanInput(span, name = "span") {
+  if (!span || typeof span !== "object" || Array.isArray(span)) {
+    throw new TypeError(`${name} must be an object`);
+  }
+  if (typeof span.startByte !== "number" || typeof span.endByte !== "number") {
+    throw new TypeError(`${name}.startByte and ${name}.endByte must be numbers`);
+  }
+  const isUint32 = (value) => Number.isInteger(value) && value >= 0 && value <= 4294967295;
+  if (!isUint32(span.startByte) || !isUint32(span.endByte)) {
+    throw new RangeError(`${name}.startByte and ${name}.endByte must be uint32 values`);
+  }
+}
+function utf8SourceBoundaries(source) {
+  let length = 0;
+  const boundaries = /* @__PURE__ */ new Set([0]);
+  for (const character of source) {
+    const codePoint = character.codePointAt(0);
+    length += codePoint <= 127 ? 1 : codePoint <= 2047 ? 2 : codePoint <= 65535 ? 3 : 4;
+    boundaries.add(length);
+  }
+  return { length, boundaries };
+}
 function parseMdiTextPosition(position) {
   if (typeof position !== "string") throw new TypeError("position must be a string");
   const match = /^([1-9]\d*):([1-9]\d*)$/.exec(position);
@@ -533,6 +588,8 @@ var parseMdiSyntax = parse;
   renderTextFormat,
   renderTextFormatWithDiagnostics,
   renderTextWithDiagnostics,
+  resolveMdiSourceSpan,
+  resolveMdiSourceSpans,
   serializeMdi,
   sourceSpansForTextRange,
   toPublicationMdast

package/dist/index.d.cts

@@ -142,6 +142,29 @@ interface MdiTextBlocksResult {
     document: MdiDocument;
     diagnostics: MdiDiagnostic[];
 }
+type MdiSourceSpanCoverage = "complete" | "partial" | "none";
+type MdiSourceSpanRelation = "exact" | "overlap";
+interface MdiSourceSpanBlockTextMatch {
+    kind: "blockText";
+    blockIndex: number;
+    range: MdiTextRange;
+    relation: MdiSourceSpanRelation;
+}
+interface MdiSourceSpanAnnotationMatch {
+    kind: "annotation";
+    blockIndex: number;
+    /** Zero-based index in the containing block's annotations array. */
+    annotationIndex: number;
+    range: MdiTextRange;
+    relation: MdiSourceSpanRelation;
+}
+type MdiSourceSpanTextMatch = MdiSourceSpanBlockTextMatch | MdiSourceSpanAnnotationMatch;
+interface MdiSourceSpanTextResolution {
+    projectionVersion: "1.0";
+    sourceSpan: MdiSourceSpan;
+    coverage: MdiSourceSpanCoverage;
+    matches: MdiSourceSpanTextMatch[];
+}
 interface MdiDiagnostic {
     severity: "warning" | "error";
     code: string;
@@ -236,6 +259,16 @@ declare function parse(source: string): MdiSyntaxParseResult;
  * and grapheme-precise UTF-8 source maps alongside the complete document IR.
  */
 declare function getMdiTextBlocks(source: string): MdiTextBlocksResult;
+/**
+ * Resolve a half-open UTF-8 source span to all mapped canonical block and
+ * annotation ranges. Mapping semantics are implemented exclusively in Rust.
+ */
+declare function resolveMdiSourceSpan(source: string, span: MdiSourceSpan): MdiSourceSpanTextResolution;
+/**
+ * Resolve many half-open UTF-8 source spans with one Rust parse/projection.
+ * The returned resolutions preserve input order.
+ */
+declare function resolveMdiSourceSpans(source: string, spans: readonly MdiSourceSpan[]): MdiSourceSpanTextResolution[];
 /** Parse and validate a canonical one-based `block:character` position. */
 declare function parseMdiTextPosition(position: string): MdiTextPositionValue;
 /** Format a validated one-based text position. */
@@ -317,4 +350,4 @@ declare function renderTextFormatWithDiagnostics(source: string, format: MdiText
 /** @deprecated Use {@link parse}; it now parses the complete document. */
 declare const parseMdiSyntax: typeof parse;
 
-export { MDI_IR_VERSION, MDI_SPEC_VERSION, MDI_TEXT_PROJECTION_VERSION, type MdiAnnotationSourceMap, type MdiDiagnostic, type MdiDocument, type MdiDocxExportProfile, type MdiEpubExportOptions, type MdiFrontmatter, type MdiHeading, type MdiHtmlRenderOptions, type MdiNode, type MdiParserCapabilities, type MdiPublicationFrontmatter, type MdiPublicationRoot, type MdiRenderResult, type MdiRubyReading, type MdiSourceSpan, type MdiSyntaxDocument, type MdiSyntaxParseResult, type MdiTextAnnotation, type MdiTextBlock, type MdiTextBlocksResult, type MdiTextFormat, type MdiTextPosition, type MdiTextPositionValue, type MdiTextRange, type MdiTextSourceMap, type MdiTextSourceRun, formatMdiTextPosition, formatMdiTextRange, getMdiTextBlocks, initializeMdi, parse, parseMdiSyntax, parseMdiTextPosition, prepareRender, renderDocx, renderDocxWithDiagnostics, renderDocxWithProfile, renderEpub, renderEpubWithDiagnostics, renderEpubWithProfile, renderHtml, renderHtmlWithDiagnostics, renderText, renderTextFormat, renderTextFormatWithDiagnostics, renderTextWithDiagnostics, serializeMdi, sourceSpansForTextRange, toPublicationMdast };
+export { MDI_IR_VERSION, MDI_SPEC_VERSION, MDI_TEXT_PROJECTION_VERSION, type MdiAnnotationSourceMap, type MdiDiagnostic, type MdiDocument, type MdiDocxExportProfile, type MdiEpubExportOptions, type MdiFrontmatter, type MdiHeading, type MdiHtmlRenderOptions, type MdiNode, type MdiParserCapabilities, type MdiPublicationFrontmatter, type MdiPublicationRoot, type MdiRenderResult, type MdiRubyReading, type MdiSourceSpan, type MdiSourceSpanAnnotationMatch, type MdiSourceSpanBlockTextMatch, type MdiSourceSpanCoverage, type MdiSourceSpanRelation, type MdiSourceSpanTextMatch, type MdiSourceSpanTextResolution, type MdiSyntaxDocument, type MdiSyntaxParseResult, type MdiTextAnnotation, type MdiTextBlock, type MdiTextBlocksResult, type MdiTextFormat, type MdiTextPosition, type MdiTextPositionValue, type MdiTextRange, type MdiTextSourceMap, type MdiTextSourceRun, formatMdiTextPosition, formatMdiTextRange, getMdiTextBlocks, initializeMdi, parse, parseMdiSyntax, parseMdiTextPosition, prepareRender, renderDocx, renderDocxWithDiagnostics, renderDocxWithProfile, renderEpub, renderEpubWithDiagnostics, renderEpubWithProfile, renderHtml, renderHtmlWithDiagnostics, renderText, renderTextFormat, renderTextFormatWithDiagnostics, renderTextWithDiagnostics, resolveMdiSourceSpan, resolveMdiSourceSpans, serializeMdi, sourceSpansForTextRange, toPublicationMdast };

package/dist/index.d.ts

@@ -142,6 +142,29 @@ interface MdiTextBlocksResult {
     document: MdiDocument;
     diagnostics: MdiDiagnostic[];
 }
+type MdiSourceSpanCoverage = "complete" | "partial" | "none";
+type MdiSourceSpanRelation = "exact" | "overlap";
+interface MdiSourceSpanBlockTextMatch {
+    kind: "blockText";
+    blockIndex: number;
+    range: MdiTextRange;
+    relation: MdiSourceSpanRelation;
+}
+interface MdiSourceSpanAnnotationMatch {
+    kind: "annotation";
+    blockIndex: number;
+    /** Zero-based index in the containing block's annotations array. */
+    annotationIndex: number;
+    range: MdiTextRange;
+    relation: MdiSourceSpanRelation;
+}
+type MdiSourceSpanTextMatch = MdiSourceSpanBlockTextMatch | MdiSourceSpanAnnotationMatch;
+interface MdiSourceSpanTextResolution {
+    projectionVersion: "1.0";
+    sourceSpan: MdiSourceSpan;
+    coverage: MdiSourceSpanCoverage;
+    matches: MdiSourceSpanTextMatch[];
+}
 interface MdiDiagnostic {
     severity: "warning" | "error";
     code: string;
@@ -236,6 +259,16 @@ declare function parse(source: string): MdiSyntaxParseResult;
  * and grapheme-precise UTF-8 source maps alongside the complete document IR.
  */
 declare function getMdiTextBlocks(source: string): MdiTextBlocksResult;
+/**
+ * Resolve a half-open UTF-8 source span to all mapped canonical block and
+ * annotation ranges. Mapping semantics are implemented exclusively in Rust.
+ */
+declare function resolveMdiSourceSpan(source: string, span: MdiSourceSpan): MdiSourceSpanTextResolution;
+/**
+ * Resolve many half-open UTF-8 source spans with one Rust parse/projection.
+ * The returned resolutions preserve input order.
+ */
+declare function resolveMdiSourceSpans(source: string, spans: readonly MdiSourceSpan[]): MdiSourceSpanTextResolution[];
 /** Parse and validate a canonical one-based `block:character` position. */
 declare function parseMdiTextPosition(position: string): MdiTextPositionValue;
 /** Format a validated one-based text position. */
@@ -317,4 +350,4 @@ declare function renderTextFormatWithDiagnostics(source: string, format: MdiText
 /** @deprecated Use {@link parse}; it now parses the complete document. */
 declare const parseMdiSyntax: typeof parse;
 
-export { MDI_IR_VERSION, MDI_SPEC_VERSION, MDI_TEXT_PROJECTION_VERSION, type MdiAnnotationSourceMap, type MdiDiagnostic, type MdiDocument, type MdiDocxExportProfile, type MdiEpubExportOptions, type MdiFrontmatter, type MdiHeading, type MdiHtmlRenderOptions, type MdiNode, type MdiParserCapabilities, type MdiPublicationFrontmatter, type MdiPublicationRoot, type MdiRenderResult, type MdiRubyReading, type MdiSourceSpan, type MdiSyntaxDocument, type MdiSyntaxParseResult, type MdiTextAnnotation, type MdiTextBlock, type MdiTextBlocksResult, type MdiTextFormat, type MdiTextPosition, type MdiTextPositionValue, type MdiTextRange, type MdiTextSourceMap, type MdiTextSourceRun, formatMdiTextPosition, formatMdiTextRange, getMdiTextBlocks, initializeMdi, parse, parseMdiSyntax, parseMdiTextPosition, prepareRender, renderDocx, renderDocxWithDiagnostics, renderDocxWithProfile, renderEpub, renderEpubWithDiagnostics, renderEpubWithProfile, renderHtml, renderHtmlWithDiagnostics, renderText, renderTextFormat, renderTextFormatWithDiagnostics, renderTextWithDiagnostics, serializeMdi, sourceSpansForTextRange, toPublicationMdast };
+export { MDI_IR_VERSION, MDI_SPEC_VERSION, MDI_TEXT_PROJECTION_VERSION, type MdiAnnotationSourceMap, type MdiDiagnostic, type MdiDocument, type MdiDocxExportProfile, type MdiEpubExportOptions, type MdiFrontmatter, type MdiHeading, type MdiHtmlRenderOptions, type MdiNode, type MdiParserCapabilities, type MdiPublicationFrontmatter, type MdiPublicationRoot, type MdiRenderResult, type MdiRubyReading, type MdiSourceSpan, type MdiSourceSpanAnnotationMatch, type MdiSourceSpanBlockTextMatch, type MdiSourceSpanCoverage, type MdiSourceSpanRelation, type MdiSourceSpanTextMatch, type MdiSourceSpanTextResolution, type MdiSyntaxDocument, type MdiSyntaxParseResult, type MdiTextAnnotation, type MdiTextBlock, type MdiTextBlocksResult, type MdiTextFormat, type MdiTextPosition, type MdiTextPositionValue, type MdiTextRange, type MdiTextSourceMap, type MdiTextSourceRun, formatMdiTextPosition, formatMdiTextRange, getMdiTextBlocks, initializeMdi, parse, parseMdiSyntax, parseMdiTextPosition, prepareRender, renderDocx, renderDocxWithDiagnostics, renderDocxWithProfile, renderEpub, renderEpubWithDiagnostics, renderEpubWithProfile, renderHtml, renderHtmlWithDiagnostics, renderText, renderTextFormat, renderTextFormatWithDiagnostics, renderTextWithDiagnostics, resolveMdiSourceSpan, resolveMdiSourceSpans, serializeMdi, sourceSpansForTextRange, toPublicationMdast };

package/dist/index.js

@@ -22,10 +22,12 @@ import {
   renderTextFormat,
   renderTextFormatWithDiagnostics,
   renderTextWithDiagnostics,
+  resolveMdiSourceSpan,
+  resolveMdiSourceSpans,
   serializeMdi,
   sourceSpansForTextRange,
   toPublicationMdast
-} from "./chunk-JTDOLXFG.js";
+} from "./chunk-GMS5SFZO.js";
 export {
   MDI_IR_VERSION,
   MDI_SPEC_VERSION,
@@ -50,6 +52,8 @@ export {
   renderTextFormat,
   renderTextFormatWithDiagnostics,
   renderTextWithDiagnostics,
+  resolveMdiSourceSpan,
+  resolveMdiSourceSpans,
   serializeMdi,
   sourceSpansForTextRange,
   toPublicationMdast

package/dist/internal/mdast.cjs

@@ -0,0 +1,72 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/internal/mdast.ts
+var mdast_exports = {};
+__export(mdast_exports, {
+  MDI_MDAST_PROVENANCE_VERSION: () => MDI_MDAST_PROVENANCE_VERSION,
+  parseForMdast: () => parseForMdast
+});
+module.exports = __toCommonJS(mdast_exports);
+var import_mdi_core = require("@illusions-lab/mdi-core");
+
+// src/index.ts
+var mdiCore = __toESM(require("@illusions-lab/mdi-core"), 1);
+var import_yaml = require("yaml");
+var {
+  getMdiTextBlocksJson,
+  resolveMdiSourceSpansJson,
+  parseMdiSyntaxJson,
+  renderHtml: renderHtmlFromRust,
+  renderEpub: renderEpubFromRust,
+  renderEpubWithProfile: renderEpubWithProfileFromRust,
+  renderDocx: renderDocxFromRust,
+  renderDocxWithProfile: renderDocxWithProfileFromRust,
+  renderText: renderTextFromRust,
+  renderTextFormat: renderTextFormatFromRust,
+  resolveExportProfileJson: resolveExportProfileJsonFromRust,
+  serializeMdi: serializeMdiFromRust
+} = mdiCore;
+var MDI_IR_VERSION = "1.0";
+
+// src/internal/mdast.ts
+var MDI_MDAST_PROVENANCE_VERSION = "1.0";
+function parseForMdast(source) {
+  if (typeof source !== "string") throw new TypeError("source must be a string");
+  const result = JSON.parse((0, import_mdi_core.parseMdiMdastJson)(source));
+  if (result.irVersion !== MDI_IR_VERSION) {
+    throw new Error(`Unsupported MDI IR version: ${String(result.irVersion)}`);
+  }
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MDI_MDAST_PROVENANCE_VERSION,
+  parseForMdast
+});

package/dist/internal/mdast.d.cts

@@ -0,0 +1,56 @@
+import { MdiDocument, MdiFrontmatter, MdiSourceSpan, MdiTextRange, MdiNode, MDI_IR_VERSION, MDI_SPEC_VERSION, MdiParserCapabilities, MdiDiagnostic } from '../index.cjs';
+import '@illusions-lab/mdi-to-epub';
+import '@illusions-lab/mdi-export-profile';
+import 'mdast';
+
+/** Version of Rust-owned transient mdast provenance records. */
+declare const MDI_MDAST_PROVENANCE_VERSION: "1.0";
+/** A projection target assigned by Rust to a source-backed IR construct. */
+type MdiMdastProvenanceTarget = {
+    blockIndex: number;
+    channel: "blockText";
+    range: MdiTextRange;
+} | {
+    blockIndex: number;
+    channel: "annotation";
+    annotationIndex: number;
+    range: MdiTextRange;
+};
+/**
+ * Transient identity and projection metadata emitted by Rust for mdast
+ * adapters. `construct.path` is valid only for this parse result; it is not a
+ * persisted document ID and must not be inferred from text or order.
+ */
+interface MdiMdastProvenance {
+    version: typeof MDI_MDAST_PROVENANCE_VERSION;
+    construct: {
+        path: string;
+        type: string;
+    };
+    span: MdiSourceSpan | null;
+    role: "container" | "textBearing";
+    status: "sourceBacked" | "synthetic" | "unmapped";
+    targets: MdiMdastProvenanceTarget[];
+}
+type MdiMdastNode = Omit<MdiNode, "children"> & {
+    mdiProvenance?: MdiMdastProvenance;
+    children?: MdiMdastNode[];
+};
+type MdiMdastFrontmatter = MdiFrontmatter & {
+    mdiProvenance: MdiMdastProvenance;
+};
+type MdiMdastDocument = Omit<MdiDocument, "frontmatter" | "children"> & {
+    frontmatter?: MdiMdastFrontmatter;
+    children: MdiMdastNode[];
+};
+interface MdiMdastParseResult {
+    irVersion: typeof MDI_IR_VERSION;
+    syntaxVersion: typeof MDI_SPEC_VERSION;
+    capabilities: MdiParserCapabilities;
+    document: MdiMdastDocument;
+    diagnostics: MdiDiagnostic[];
+}
+/** Rust-backed transport exclusively for mdast adapters. */
+declare function parseForMdast(source: string): MdiMdastParseResult;
+
+export { MDI_MDAST_PROVENANCE_VERSION, type MdiMdastDocument, type MdiMdastFrontmatter, type MdiMdastNode, type MdiMdastParseResult, type MdiMdastProvenance, type MdiMdastProvenanceTarget, parseForMdast };

package/dist/internal/mdast.d.ts

@@ -0,0 +1,56 @@
+import { MdiDocument, MdiFrontmatter, MdiSourceSpan, MdiTextRange, MdiNode, MDI_IR_VERSION, MDI_SPEC_VERSION, MdiParserCapabilities, MdiDiagnostic } from '../index.js';
+import '@illusions-lab/mdi-to-epub';
+import '@illusions-lab/mdi-export-profile';
+import 'mdast';
+
+/** Version of Rust-owned transient mdast provenance records. */
+declare const MDI_MDAST_PROVENANCE_VERSION: "1.0";
+/** A projection target assigned by Rust to a source-backed IR construct. */
+type MdiMdastProvenanceTarget = {
+    blockIndex: number;
+    channel: "blockText";
+    range: MdiTextRange;
+} | {
+    blockIndex: number;
+    channel: "annotation";
+    annotationIndex: number;
+    range: MdiTextRange;
+};
+/**
+ * Transient identity and projection metadata emitted by Rust for mdast
+ * adapters. `construct.path` is valid only for this parse result; it is not a
+ * persisted document ID and must not be inferred from text or order.
+ */
+interface MdiMdastProvenance {
+    version: typeof MDI_MDAST_PROVENANCE_VERSION;
+    construct: {
+        path: string;
+        type: string;
+    };
+    span: MdiSourceSpan | null;
+    role: "container" | "textBearing";
+    status: "sourceBacked" | "synthetic" | "unmapped";
+    targets: MdiMdastProvenanceTarget[];
+}
+type MdiMdastNode = Omit<MdiNode, "children"> & {
+    mdiProvenance?: MdiMdastProvenance;
+    children?: MdiMdastNode[];
+};
+type MdiMdastFrontmatter = MdiFrontmatter & {
+    mdiProvenance: MdiMdastProvenance;
+};
+type MdiMdastDocument = Omit<MdiDocument, "frontmatter" | "children"> & {
+    frontmatter?: MdiMdastFrontmatter;
+    children: MdiMdastNode[];
+};
+interface MdiMdastParseResult {
+    irVersion: typeof MDI_IR_VERSION;
+    syntaxVersion: typeof MDI_SPEC_VERSION;
+    capabilities: MdiParserCapabilities;
+    document: MdiMdastDocument;
+    diagnostics: MdiDiagnostic[];
+}
+/** Rust-backed transport exclusively for mdast adapters. */
+declare function parseForMdast(source: string): MdiMdastParseResult;
+
+export { MDI_MDAST_PROVENANCE_VERSION, type MdiMdastDocument, type MdiMdastFrontmatter, type MdiMdastNode, type MdiMdastParseResult, type MdiMdastProvenance, type MdiMdastProvenanceTarget, parseForMdast };

package/dist/internal/mdast.js

@@ -0,0 +1,19 @@
+import {
+  MDI_IR_VERSION
+} from "../chunk-GMS5SFZO.js";
+
+// src/internal/mdast.ts
+import { parseMdiMdastJson } from "@illusions-lab/mdi-core";
+var MDI_MDAST_PROVENANCE_VERSION = "1.0";
+function parseForMdast(source) {
+  if (typeof source !== "string") throw new TypeError("source must be a string");
+  const result = JSON.parse(parseMdiMdastJson(source));
+  if (result.irVersion !== MDI_IR_VERSION) {
+    throw new Error(`Unsupported MDI IR version: ${String(result.irVersion)}`);
+  }
+  return result;
+}
+export {
+  MDI_MDAST_PROVENANCE_VERSION,
+  parseForMdast
+};

package/dist/node.cjs

@@ -42,6 +42,7 @@ var mdiCore = __toESM(require("@illusions-lab/mdi-core"), 1);
 var import_yaml = require("yaml");
 var {
   getMdiTextBlocksJson,
+  resolveMdiSourceSpansJson,
   parseMdiSyntaxJson,
   renderHtml: renderHtmlFromRust,
   renderEpub: renderEpubFromRust,

package/dist/node.js

@@ -1,7 +1,7 @@
 import {
   parse,
   renderHtml
-} from "./chunk-JTDOLXFG.js";
+} from "./chunk-GMS5SFZO.js";
 
 // src/node.ts
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illusions-lab/mdi",
-  "version": "2.0.19",
+  "version": "2.0.21",
   "description": "Thin JavaScript binding for the Rust-authoritative MDI parser",
   "license": "MIT",
   "repository": {
@@ -21,20 +21,24 @@
     "./node": {
       "types": "./dist/node.d.ts",
       "default": "./dist/node.js"
+    },
+    "./internal/mdast": {
+      "types": "./dist/internal/mdast.d.ts",
+      "default": "./dist/internal/mdast.js"
     }
   },
   "files": [
     "dist"
   ],
   "scripts": {
-    "build": "tsup src/index.ts src/node.ts --format esm,cjs --dts",
+    "build": "tsup src/index.ts src/node.ts src/internal/mdast.ts --format esm,cjs --dts",
     "test": "vitest run --passWithNoTests",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@illusions-lab/mdi-core": "^2.0.19",
-    "@illusions-lab/mdi-export-profile": "^2.0.24",
-    "@illusions-lab/mdi-to-epub": "^2.0.34",
+    "@illusions-lab/mdi-core": "^2.0.21",
+    "@illusions-lab/mdi-export-profile": "^2.0.26",
+    "@illusions-lab/mdi-to-epub": "^2.0.36",
     "@types/mdast": "^4.0.0",
     "yaml": "^2.0.0"
   },