@illusions-lab/mdi 2.0.18 → 2.0.20

package/README.md

@@ -79,6 +79,46 @@ Applications should treat the IR version as a wire-protocol version. They
 must not infer grammar rules from object shapes or silently accept an
 unsupported version.
 
+## Searchable text blocks
+
+`getMdiTextBlocks(source)` returns Rust-projected heading, paragraph, list,
+blockquote, code, table, footnote, and HTML text in source order. Positions
+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, 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`,
+`formatMdiTextPosition`, and `formatMdiTextRange` provide stateless coordinate
+helpers.
+
 ## Rendering
 
 Rendering starts from the same Rust IR. Canonical MDI, plain text, HTML, EPUB,

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

@@ -2,6 +2,8 @@
 import * as mdiCore from "@illusions-lab/mdi-core";
 import { parse as parseYaml } from "yaml";
 var {
+  getMdiTextBlocksJson,
+  resolveMdiSourceSpansJson,
   parseMdiSyntaxJson,
   renderHtml: renderHtmlFromRust,
   renderEpub: renderEpubFromRust,
@@ -24,6 +26,7 @@ function requireLayoutSystem(profile) {
 }
 var MDI_SPEC_VERSION = "2.0";
 var MDI_IR_VERSION = "1.0";
+var MDI_TEXT_PROJECTION_VERSION = "1.0";
 function parse(source) {
   if (typeof source !== "string") throw new TypeError("source must be a string");
   const result = JSON.parse(parseMdiSyntaxJson(source));
@@ -32,6 +35,144 @@ function parse(source) {
   }
   return result;
 }
+function getMdiTextBlocks(source) {
+  if (typeof source !== "string") throw new TypeError("source must be a string");
+  const result = JSON.parse(getMdiTextBlocksJson(source));
+  if (result.projectionVersion !== MDI_TEXT_PROJECTION_VERSION) {
+    throw new Error(`Unsupported MDI text projection version: ${String(result.projectionVersion)}`);
+  }
+  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);
+  if (!match) throw new RangeError(`Invalid MDI text position: ${position}`);
+  const block = Number(match[1]);
+  const character = Number(match[2]);
+  if (!Number.isSafeInteger(block) || !Number.isSafeInteger(character)) {
+    throw new RangeError(`Invalid MDI text position: ${position}`);
+  }
+  return { block, character };
+}
+function formatMdiTextPosition(position) {
+  if (!position || typeof position !== "object") {
+    throw new TypeError("position must be an object");
+  }
+  if (!isPositiveSafeInteger(position.block) || !isPositiveSafeInteger(position.character)) {
+    throw new RangeError("position.block and position.character must be positive safe integers");
+  }
+  return `${position.block}:${position.character}`;
+}
+function formatMdiTextRange(range) {
+  if (!range || typeof range !== "object") throw new TypeError("range must be an object");
+  const start = parseMdiTextPosition(range.start);
+  const end = parseMdiTextPosition(range.end);
+  if (start.block !== end.block || end.character < start.character) {
+    throw new RangeError("range must be ordered within one text block");
+  }
+  return `${range.start}-${range.end}`;
+}
+function sourceSpansForTextRange(block, range) {
+  if (!block || typeof block !== "object") throw new TypeError("block must be an object");
+  const start = parseMdiTextPosition(range.start);
+  const end = parseMdiTextPosition(range.end);
+  if (start.block !== block.index || end.block !== block.index) {
+    throw new RangeError("range must belong to the supplied text block");
+  }
+  const blockEnd = parseMdiTextPosition(block.range.end).character;
+  if (end.character < start.character || start.character < 1 || end.character > blockEnd) {
+    throw new RangeError("range falls outside the supplied text block");
+  }
+  const spans = [];
+  let previousRunEnd = 1;
+  for (const run of block.sourceMap.runs) {
+    const runStartPosition = parseMdiTextPosition(run.range.start);
+    const runEndPosition = parseMdiTextPosition(run.range.end);
+    const runStart = runStartPosition.character;
+    const runEnd = runEndPosition.character;
+    const invalidRange = runStartPosition.block !== block.index || runEndPosition.block !== block.index || runEnd < runStart || runStart < previousRunEnd || runEnd > blockEnd;
+    const invalidBoundaries = run.sourceBoundaries.length !== runEnd - runStart + 1 || run.sourceBoundaries.some((boundary) => !Number.isSafeInteger(boundary) || boundary < 0) || run.sourceBoundaries.some((boundary, index) => index > 0 && boundary < run.sourceBoundaries[index - 1]) || block.span !== void 0 && run.sourceBoundaries.some(
+      (boundary) => boundary < block.span.startByte || boundary > block.span.endByte
+    );
+    if (invalidRange || invalidBoundaries) {
+      throw new Error("Invalid MDI text source run");
+    }
+    previousRunEnd = runEnd;
+    const overlapStart = Math.max(start.character, runStart);
+    const overlapEnd = Math.min(end.character, runEnd);
+    for (let character = overlapStart; character < overlapEnd; character += 1) {
+      const offset = character - runStart;
+      appendMergedSourceSpan(spans, {
+        startByte: run.sourceBoundaries[offset],
+        endByte: run.sourceBoundaries[offset + 1]
+      });
+    }
+  }
+  return spans;
+}
+function appendMergedSourceSpan(spans, next) {
+  const previous = spans.at(-1);
+  if (previous?.endByte === next.startByte) {
+    previous.endByte = next.endByte;
+  } else {
+    spans.push(next);
+  }
+}
+function isPositiveSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+}
 function renderHtml(source, options) {
   assertSource(source);
   assertHtmlOptions(options);
@@ -366,7 +507,15 @@ export {
   initializeMdi,
   MDI_SPEC_VERSION,
   MDI_IR_VERSION,
+  MDI_TEXT_PROJECTION_VERSION,
   parse,
+  getMdiTextBlocks,
+  resolveMdiSourceSpan,
+  resolveMdiSourceSpans,
+  parseMdiTextPosition,
+  formatMdiTextPosition,
+  formatMdiTextRange,
+  sourceSpansForTextRange,
   renderHtml,
   renderHtmlWithDiagnostics,
   prepareRender,

package/dist/index.cjs

@@ -32,9 +32,14 @@ var index_exports = {};
 __export(index_exports, {
   MDI_IR_VERSION: () => MDI_IR_VERSION,
   MDI_SPEC_VERSION: () => MDI_SPEC_VERSION,
+  MDI_TEXT_PROJECTION_VERSION: () => MDI_TEXT_PROJECTION_VERSION,
+  formatMdiTextPosition: () => formatMdiTextPosition,
+  formatMdiTextRange: () => formatMdiTextRange,
+  getMdiTextBlocks: () => getMdiTextBlocks,
   initializeMdi: () => initializeMdi,
   parse: () => parse,
   parseMdiSyntax: () => parseMdiSyntax,
+  parseMdiTextPosition: () => parseMdiTextPosition,
   prepareRender: () => prepareRender,
   renderDocx: () => renderDocx,
   renderDocxWithDiagnostics: () => renderDocxWithDiagnostics,
@@ -48,13 +53,18 @@ __export(index_exports, {
   renderTextFormat: () => renderTextFormat,
   renderTextFormatWithDiagnostics: () => renderTextFormatWithDiagnostics,
   renderTextWithDiagnostics: () => renderTextWithDiagnostics,
+  resolveMdiSourceSpan: () => resolveMdiSourceSpan,
+  resolveMdiSourceSpans: () => resolveMdiSourceSpans,
   serializeMdi: () => serializeMdi,
+  sourceSpansForTextRange: () => sourceSpansForTextRange,
   toPublicationMdast: () => toPublicationMdast
 });
 module.exports = __toCommonJS(index_exports);
 var mdiCore = __toESM(require("@illusions-lab/mdi-core"), 1);
 var import_yaml = require("yaml");
 var {
+  getMdiTextBlocksJson,
+  resolveMdiSourceSpansJson,
   parseMdiSyntaxJson,
   renderHtml: renderHtmlFromRust,
   renderEpub: renderEpubFromRust,
@@ -77,6 +87,7 @@ function requireLayoutSystem(profile) {
 }
 var MDI_SPEC_VERSION = "2.0";
 var MDI_IR_VERSION = "1.0";
+var MDI_TEXT_PROJECTION_VERSION = "1.0";
 function parse(source) {
   if (typeof source !== "string") throw new TypeError("source must be a string");
   const result = JSON.parse(parseMdiSyntaxJson(source));
@@ -85,6 +96,144 @@ function parse(source) {
   }
   return result;
 }
+function getMdiTextBlocks(source) {
+  if (typeof source !== "string") throw new TypeError("source must be a string");
+  const result = JSON.parse(getMdiTextBlocksJson(source));
+  if (result.projectionVersion !== MDI_TEXT_PROJECTION_VERSION) {
+    throw new Error(`Unsupported MDI text projection version: ${String(result.projectionVersion)}`);
+  }
+  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);
+  if (!match) throw new RangeError(`Invalid MDI text position: ${position}`);
+  const block = Number(match[1]);
+  const character = Number(match[2]);
+  if (!Number.isSafeInteger(block) || !Number.isSafeInteger(character)) {
+    throw new RangeError(`Invalid MDI text position: ${position}`);
+  }
+  return { block, character };
+}
+function formatMdiTextPosition(position) {
+  if (!position || typeof position !== "object") {
+    throw new TypeError("position must be an object");
+  }
+  if (!isPositiveSafeInteger(position.block) || !isPositiveSafeInteger(position.character)) {
+    throw new RangeError("position.block and position.character must be positive safe integers");
+  }
+  return `${position.block}:${position.character}`;
+}
+function formatMdiTextRange(range) {
+  if (!range || typeof range !== "object") throw new TypeError("range must be an object");
+  const start = parseMdiTextPosition(range.start);
+  const end = parseMdiTextPosition(range.end);
+  if (start.block !== end.block || end.character < start.character) {
+    throw new RangeError("range must be ordered within one text block");
+  }
+  return `${range.start}-${range.end}`;
+}
+function sourceSpansForTextRange(block, range) {
+  if (!block || typeof block !== "object") throw new TypeError("block must be an object");
+  const start = parseMdiTextPosition(range.start);
+  const end = parseMdiTextPosition(range.end);
+  if (start.block !== block.index || end.block !== block.index) {
+    throw new RangeError("range must belong to the supplied text block");
+  }
+  const blockEnd = parseMdiTextPosition(block.range.end).character;
+  if (end.character < start.character || start.character < 1 || end.character > blockEnd) {
+    throw new RangeError("range falls outside the supplied text block");
+  }
+  const spans = [];
+  let previousRunEnd = 1;
+  for (const run of block.sourceMap.runs) {
+    const runStartPosition = parseMdiTextPosition(run.range.start);
+    const runEndPosition = parseMdiTextPosition(run.range.end);
+    const runStart = runStartPosition.character;
+    const runEnd = runEndPosition.character;
+    const invalidRange = runStartPosition.block !== block.index || runEndPosition.block !== block.index || runEnd < runStart || runStart < previousRunEnd || runEnd > blockEnd;
+    const invalidBoundaries = run.sourceBoundaries.length !== runEnd - runStart + 1 || run.sourceBoundaries.some((boundary) => !Number.isSafeInteger(boundary) || boundary < 0) || run.sourceBoundaries.some((boundary, index) => index > 0 && boundary < run.sourceBoundaries[index - 1]) || block.span !== void 0 && run.sourceBoundaries.some(
+      (boundary) => boundary < block.span.startByte || boundary > block.span.endByte
+    );
+    if (invalidRange || invalidBoundaries) {
+      throw new Error("Invalid MDI text source run");
+    }
+    previousRunEnd = runEnd;
+    const overlapStart = Math.max(start.character, runStart);
+    const overlapEnd = Math.min(end.character, runEnd);
+    for (let character = overlapStart; character < overlapEnd; character += 1) {
+      const offset = character - runStart;
+      appendMergedSourceSpan(spans, {
+        startByte: run.sourceBoundaries[offset],
+        endByte: run.sourceBoundaries[offset + 1]
+      });
+    }
+  }
+  return spans;
+}
+function appendMergedSourceSpan(spans, next) {
+  const previous = spans.at(-1);
+  if (previous?.endByte === next.startByte) {
+    previous.endByte = next.endByte;
+  } else {
+    spans.push(next);
+  }
+}
+function isPositiveSafeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+}
 function renderHtml(source, options) {
   assertSource(source);
   assertHtmlOptions(options);
@@ -418,9 +567,14 @@ var parseMdiSyntax = parse;
 0 && (module.exports = {
   MDI_IR_VERSION,
   MDI_SPEC_VERSION,
+  MDI_TEXT_PROJECTION_VERSION,
+  formatMdiTextPosition,
+  formatMdiTextRange,
+  getMdiTextBlocks,
   initializeMdi,
   parse,
   parseMdiSyntax,
+  parseMdiTextPosition,
   prepareRender,
   renderDocx,
   renderDocxWithDiagnostics,
@@ -434,6 +588,9 @@ var parseMdiSyntax = parse;
   renderTextFormat,
   renderTextFormatWithDiagnostics,
   renderTextWithDiagnostics,
+  resolveMdiSourceSpan,
+  resolveMdiSourceSpans,
   serializeMdi,
+  sourceSpansForTextRange,
   toPublicationMdast
 });

package/dist/index.d.cts

@@ -76,6 +76,8 @@ type MdiDocxExportProfile = ExportProfile & {
 declare const MDI_SPEC_VERSION: "2.0";
 /** Version of the complete Rust-owned document IR. */
 declare const MDI_IR_VERSION: "1.0";
+/** Version of the Rust-owned searchable text projection. */
+declare const MDI_TEXT_PROJECTION_VERSION: "1.0";
 interface MdiParserCapabilities {
     mdi: boolean;
     commonMark: boolean;
@@ -89,6 +91,80 @@ interface MdiSourceSpan {
     /** Exclusive UTF-8 byte offset. */
     endByte: number;
 }
+/** A canonical one-based `block:grapheme` text position. */
+type MdiTextPosition = `${number}:${number}`;
+interface MdiTextPositionValue {
+    block: number;
+    character: number;
+}
+interface MdiTextRange {
+    /** Inclusive. */
+    start: MdiTextPosition;
+    /** Exclusive. */
+    end: MdiTextPosition;
+}
+interface MdiTextSourceRun {
+    range: MdiTextRange;
+    /** One UTF-8 source boundary per grapheme, plus the final boundary. */
+    sourceBoundaries: number[];
+}
+interface MdiTextSourceMap {
+    runs: MdiTextSourceRun[];
+    synthetic: MdiTextRange[];
+    unmapped: MdiTextRange[];
+}
+type MdiAnnotationSourceMap = MdiTextSourceMap;
+interface MdiTextAnnotation {
+    kind: "rubyReading";
+    text: string;
+    anchor: MdiTextRange;
+    span?: MdiSourceSpan;
+    sourceMap: MdiAnnotationSourceMap;
+}
+interface MdiTextBlock {
+    /** One-based source-order block number. */
+    index: number;
+    kind: "heading" | "paragraph" | "listItem" | "blockquote" | "code" | "table" | "footnote" | "html" | "other";
+    text: string;
+    range: MdiTextRange;
+    span?: MdiSourceSpan;
+    sourceMap: MdiTextSourceMap;
+    annotations: MdiTextAnnotation[];
+    node: MdiNode;
+}
+interface MdiTextBlocksResult {
+    projectionVersion: "1.0";
+    positionEncoding: "unicode-grapheme-cluster-1-based";
+    irVersion: typeof MDI_IR_VERSION;
+    syntaxVersion: typeof MDI_SPEC_VERSION;
+    capabilities: MdiParserCapabilities;
+    blocks: MdiTextBlock[];
+    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;
@@ -178,6 +254,32 @@ type MdiSyntaxDocument = MdiDocument;
  * language-neutral document IR. JavaScript performs no grammar work.
  */
 declare function parse(source: string): MdiSyntaxParseResult;
+/**
+ * Parse once in Rust and return source-order plaintext blocks, annotations,
+ * 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. */
+declare function formatMdiTextPosition(position: MdiTextPositionValue): MdiTextPosition;
+/** Format a canonical full `start-end` range such as `3:18-3:24`. */
+declare function formatMdiTextRange(range: MdiTextRange): string;
+/**
+ * Resolve a text range to its source-derived UTF-8 spans. Synthetic table or
+ * paragraph separators are deliberately omitted.
+ */
+declare function sourceSpansForTextRange(block: MdiTextBlock, range: MdiTextRange): MdiSourceSpan[];
 /** Render complete `.mdi` source to standalone semantic HTML in Rust. */
 declare function renderHtml(source: string, options?: MdiHtmlRenderOptions): string;
 /**
@@ -248,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, 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 MdiTextFormat, initializeMdi, parse, parseMdiSyntax, prepareRender, renderDocx, renderDocxWithDiagnostics, renderDocxWithProfile, renderEpub, renderEpubWithDiagnostics, renderEpubWithProfile, renderHtml, renderHtmlWithDiagnostics, renderText, renderTextFormat, renderTextFormatWithDiagnostics, renderTextWithDiagnostics, serializeMdi, 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

@@ -76,6 +76,8 @@ type MdiDocxExportProfile = ExportProfile & {
 declare const MDI_SPEC_VERSION: "2.0";
 /** Version of the complete Rust-owned document IR. */
 declare const MDI_IR_VERSION: "1.0";
+/** Version of the Rust-owned searchable text projection. */
+declare const MDI_TEXT_PROJECTION_VERSION: "1.0";
 interface MdiParserCapabilities {
     mdi: boolean;
     commonMark: boolean;
@@ -89,6 +91,80 @@ interface MdiSourceSpan {
     /** Exclusive UTF-8 byte offset. */
     endByte: number;
 }
+/** A canonical one-based `block:grapheme` text position. */
+type MdiTextPosition = `${number}:${number}`;
+interface MdiTextPositionValue {
+    block: number;
+    character: number;
+}
+interface MdiTextRange {
+    /** Inclusive. */
+    start: MdiTextPosition;
+    /** Exclusive. */
+    end: MdiTextPosition;
+}
+interface MdiTextSourceRun {
+    range: MdiTextRange;
+    /** One UTF-8 source boundary per grapheme, plus the final boundary. */
+    sourceBoundaries: number[];
+}
+interface MdiTextSourceMap {
+    runs: MdiTextSourceRun[];
+    synthetic: MdiTextRange[];
+    unmapped: MdiTextRange[];
+}
+type MdiAnnotationSourceMap = MdiTextSourceMap;
+interface MdiTextAnnotation {
+    kind: "rubyReading";
+    text: string;
+    anchor: MdiTextRange;
+    span?: MdiSourceSpan;
+    sourceMap: MdiAnnotationSourceMap;
+}
+interface MdiTextBlock {
+    /** One-based source-order block number. */
+    index: number;
+    kind: "heading" | "paragraph" | "listItem" | "blockquote" | "code" | "table" | "footnote" | "html" | "other";
+    text: string;
+    range: MdiTextRange;
+    span?: MdiSourceSpan;
+    sourceMap: MdiTextSourceMap;
+    annotations: MdiTextAnnotation[];
+    node: MdiNode;
+}
+interface MdiTextBlocksResult {
+    projectionVersion: "1.0";
+    positionEncoding: "unicode-grapheme-cluster-1-based";
+    irVersion: typeof MDI_IR_VERSION;
+    syntaxVersion: typeof MDI_SPEC_VERSION;
+    capabilities: MdiParserCapabilities;
+    blocks: MdiTextBlock[];
+    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;
@@ -178,6 +254,32 @@ type MdiSyntaxDocument = MdiDocument;
  * language-neutral document IR. JavaScript performs no grammar work.
  */
 declare function parse(source: string): MdiSyntaxParseResult;
+/**
+ * Parse once in Rust and return source-order plaintext blocks, annotations,
+ * 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. */
+declare function formatMdiTextPosition(position: MdiTextPositionValue): MdiTextPosition;
+/** Format a canonical full `start-end` range such as `3:18-3:24`. */
+declare function formatMdiTextRange(range: MdiTextRange): string;
+/**
+ * Resolve a text range to its source-derived UTF-8 spans. Synthetic table or
+ * paragraph separators are deliberately omitted.
+ */
+declare function sourceSpansForTextRange(block: MdiTextBlock, range: MdiTextRange): MdiSourceSpan[];
 /** Render complete `.mdi` source to standalone semantic HTML in Rust. */
 declare function renderHtml(source: string, options?: MdiHtmlRenderOptions): string;
 /**
@@ -248,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, 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 MdiTextFormat, initializeMdi, parse, parseMdiSyntax, prepareRender, renderDocx, renderDocxWithDiagnostics, renderDocxWithProfile, renderEpub, renderEpubWithDiagnostics, renderEpubWithProfile, renderHtml, renderHtmlWithDiagnostics, renderText, renderTextFormat, renderTextFormatWithDiagnostics, renderTextWithDiagnostics, serializeMdi, 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

@@ -1,9 +1,14 @@
 import {
   MDI_IR_VERSION,
   MDI_SPEC_VERSION,
+  MDI_TEXT_PROJECTION_VERSION,
+  formatMdiTextPosition,
+  formatMdiTextRange,
+  getMdiTextBlocks,
   initializeMdi,
   parse,
   parseMdiSyntax,
+  parseMdiTextPosition,
   prepareRender,
   renderDocx,
   renderDocxWithDiagnostics,
@@ -17,15 +22,23 @@ import {
   renderTextFormat,
   renderTextFormatWithDiagnostics,
   renderTextWithDiagnostics,
+  resolveMdiSourceSpan,
+  resolveMdiSourceSpans,
   serializeMdi,
+  sourceSpansForTextRange,
   toPublicationMdast
-} from "./chunk-WEJ62HS6.js";
+} from "./chunk-GMS5SFZO.js";
 export {
   MDI_IR_VERSION,
   MDI_SPEC_VERSION,
+  MDI_TEXT_PROJECTION_VERSION,
+  formatMdiTextPosition,
+  formatMdiTextRange,
+  getMdiTextBlocks,
   initializeMdi,
   parse,
   parseMdiSyntax,
+  parseMdiTextPosition,
   prepareRender,
   renderDocx,
   renderDocxWithDiagnostics,
@@ -39,6 +52,9 @@ export {
   renderTextFormat,
   renderTextFormatWithDiagnostics,
   renderTextWithDiagnostics,
+  resolveMdiSourceSpan,
+  resolveMdiSourceSpans,
   serializeMdi,
+  sourceSpansForTextRange,
   toPublicationMdast
 };

package/dist/node.cjs

@@ -41,6 +41,8 @@ module.exports = __toCommonJS(node_exports);
 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-WEJ62HS6.js";
+} from "./chunk-GMS5SFZO.js";
 
 // src/node.ts
 import {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illusions-lab/mdi",
-  "version": "2.0.18",
+  "version": "2.0.20",
   "description": "Thin JavaScript binding for the Rust-authoritative MDI parser",
   "license": "MIT",
   "repository": {
@@ -32,9 +32,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@illusions-lab/mdi-core": "^2.0.18",
-    "@illusions-lab/mdi-export-profile": "^2.0.23",
-    "@illusions-lab/mdi-to-epub": "^2.0.33",
+    "@illusions-lab/mdi-core": "^2.0.20",
+    "@illusions-lab/mdi-export-profile": "^2.0.25",
+    "@illusions-lab/mdi-to-epub": "^2.0.35",
     "@types/mdast": "^4.0.0",
     "yaml": "^2.0.0"
   },