@docx-editor.dev/docx-to-markdown 0.0.1 → 2.19.0

package/dist/markdown-types-Cn-MizR0.d.ts

@@ -0,0 +1,251 @@
+/// <reference lib="dom" />
+import { SemanticDrawingVisit, SemanticCommentArtifactRecord, SemanticTrackedChangeArtifactRecord, SemanticReviewArtifactRecord, RevisionDisplayMode } from '@docx-editor.dev/core/layout';
+import { OpenDocumentForExportOptions, FontOrigin, ExportFontResolutionReport } from '@docx-editor.dev/core/export';
+
+/** One physical occurrence of an extracted image. @public */
+interface MarkdownImageOccurrence {
+    readonly pageNumber: number;
+    readonly story: SemanticDrawingVisit['story'];
+    readonly rootStory: SemanticDrawingVisit['rootStory'];
+    readonly partName: string;
+    readonly drawingNodeId: string;
+    readonly paragraphId: string;
+    /** Source offset within the paragraph, in UTF-16 code units. */
+    readonly start: number;
+    /** Word's extent width in CSS pixels (96 px per inch), before crop or rotation. */
+    readonly displayWidthPx: number;
+    /** Word's extent height in CSS pixels (96 px per inch), before crop or rotation. */
+    readonly displayHeightPx: number;
+    /** Anchored images render at their paragraph position; Markdown does not reproduce text wrapping. */
+    readonly kind: 'inline' | 'anchored';
+    readonly decorative: boolean;
+    readonly alt: string;
+}
+/** Image bytes and provenance supplied to a URL resolver. @public */
+interface MarkdownImageData {
+    /** Core's SHA-256 content identifier for the exported bytes. */
+    readonly id: string;
+    /** Portable relative filename, independent of the resolved URL. */
+    readonly path: string;
+    readonly mimeType: string;
+    /** Owned bytes. Treat as read-only to preserve the content identifier. */
+    readonly bytes: Uint8Array;
+    readonly byteLength: number;
+    /** Intrinsic pixel width of the exported bytes; use occurrence dimensions for display. */
+    readonly pixelWidth: number;
+    /** Intrinsic pixel height of the exported bytes; use occurrence dimensions for display. */
+    readonly pixelHeight: number;
+    readonly occurrences: readonly MarkdownImageOccurrence[];
+}
+/** One unique image returned by a Markdown export. @public */
+interface MarkdownImageAsset extends MarkdownImageData {
+    /** Raw URL; Markdown output escapes destination syntax separately. */
+    readonly url: string;
+}
+/** Portable image extraction and optional application-owned storage. @public */
+interface MarkdownImageOptions {
+    /**
+     * Default: `markdown` emits standard image links without dimensions.
+     * `html` emits an escaped `<img>` with each occurrence's display width and height,
+     * rounded to whole CSS pixels. Your renderer must allow HTML and these attributes.
+     * Neither syntax reproduces cropping, rotation, or floating text wrapping.
+     */
+    readonly syntax?: 'markdown' | 'html';
+    /**
+     * Called sequentially once per unique image, after all extraction succeeds. Receives a
+     * separate byte copy; mutations cannot change result bytes. Return a relative path or HTTP(S)
+     * URL. The application owns completed uploads, their cleanup, and signed-URL expiry.
+     */
+    readonly resolveUrl?: (image: MarkdownImageData, context: {
+        readonly signal?: AbortSignal;
+    }) => string | Promise<string>;
+    /** Unique extracted bytes; default 64 MiB. Not a total parsing/layout memory limit. */
+    readonly maxTotalBytes?: number;
+}
+/** Projection controls for an already-open export session. @public */
+interface MarkdownProjectionOptions {
+    /** `true` or `{}` extracts images with portable relative URLs. Default: false. */
+    readonly images?: boolean | MarkdownImageOptions;
+    /** Cancels export waits; cannot interrupt synchronous parsing or layout. */
+    readonly signal?: AbortSignal;
+}
+
+/** Page/story/source provenance for one exported review artifact. @public */
+type MarkdownReviewOccurrence = SemanticReviewArtifactRecord['occurrences'][number];
+/**
+ * Normalized DOCX comment, independent of editor UI state.
+ *
+ * Its ID is opaque and stable only within one {@link MarkdownExportResult}. Never persist the ID
+ * across exports; pair citations with the caller's own document version or content hash.
+ * @public
+ */
+type MarkdownComment = SemanticCommentArtifactRecord;
+/**
+ * Normalized DOCX tracked change, independent of editor UI state.
+ *
+ * Its ID is opaque and stable only within one {@link MarkdownExportResult}. Never persist the ID
+ * across exports; pair citations with the caller's own document version or content hash.
+ * @public
+ */
+type MarkdownTrackedChange = SemanticTrackedChangeArtifactRecord;
+/**
+ * Comment or tracked change returned by Markdown export. IDs are opaque and result-local.
+ * @public
+ */
+type MarkdownReviewArtifact = SemanticReviewArtifactRecord;
+/** A UTF-16 range suitable for slicing the named Markdown projection. @public */
+interface MarkdownReviewRange {
+    /** Inclusive start offset in the selected Markdown string. */
+    readonly start: number;
+    /** Exclusive end offset in the selected Markdown string. */
+    readonly end: number;
+    /** Offsets use JavaScript string indexing and can be passed directly to `String.slice()`. */
+    readonly unit: 'utf16-code-unit';
+    /** Whether this is an exact text mapping or the smallest generated construct containing it. */
+    readonly precision: MarkdownReviewRangePrecision;
+}
+/** Precision of a source-to-Markdown review range. @public */
+type MarkdownReviewRangePrecision = 'exact' | 'containing-construct';
+/** How much of one Core source occurrence is represented by the returned ranges. @public */
+type MarkdownReviewCoverage = 'complete' | 'partial' | 'none';
+/** Markdown string containing one review binding. @public */
+type MarkdownReviewProjection = {
+    /** Selects `MarkdownExportResult.markdown`. */
+    readonly kind: 'document';
+} | {
+    /** Selects one field on one entry in `MarkdownExportResult.pages`. */
+    readonly kind: 'page';
+    /** Zero-based index into `MarkdownExportResult.pages`. */
+    readonly pageIndex: number;
+    /** One-based page number, included for citation and validation. */
+    readonly pageNumber: number;
+    /** Markdown page field containing the bound ranges. */
+    readonly field: 'markdown' | 'headerMarkdown' | 'footerMarkdown';
+};
+/** Why a source occurrence has no range in a particular Markdown projection. @public */
+type MarkdownReviewUnmappedReason = 'not-represented-in-markdown' | 'non-linear-structural-change' | 'omitted-story-content';
+/** Honest snapshot-local mapping from a Core review occurrence to generated Markdown. @public */
+interface MarkdownReviewBinding {
+    /** ID of the corresponding artifact in this export result; do not join it across snapshots. */
+    readonly artifactId: string;
+    /** Discriminant of the corresponding review artifact. */
+    readonly artifactKind: MarkdownReviewArtifact['kind'];
+    /** Index into this snapshot's immutable artifact `occurrences` array. */
+    readonly occurrenceIndex: number;
+    /** Generated Markdown string containing this binding. */
+    readonly projection: MarkdownReviewProjection;
+    /** Ordered, non-overlapping ranges in the selected projection. */
+    readonly ranges: readonly MarkdownReviewRange[];
+    /** Whether the ranges represent all, some, or none of the source occurrence. */
+    readonly coverage: MarkdownReviewCoverage;
+    /** Present when the source occurrence has no honest linear range in this projection. */
+    readonly unmappedReason?: MarkdownReviewUnmappedReason;
+}
+
+/** Markdown emitted for one physical layout page. @public */
+interface MarkdownPage {
+    /** Identifier for this page within this export result. */
+    readonly id: string;
+    /** One-based physical page number. */
+    readonly number: number;
+    /** Body projection, plus local note definitions or labelled continuation blocks. */
+    readonly markdown: string;
+    /** Header story for this page, kept separate from logical document content. */
+    readonly headerMarkdown: string;
+    /** Footer story for this page, kept separate from logical document content. */
+    readonly footerMarkdown: string;
+    /**
+     * Membership view of comments occurring on this page. Each entry is the complete document-wide
+     * artifact and can contain occurrences from other pages. For page-local provenance, filter with
+     * `occurrence.pageIndex === page.number - 1`.
+     */
+    readonly comments: readonly MarkdownComment[];
+    /**
+     * Membership view of tracked changes occurring on this page. Each entry is the complete
+     * document-wide artifact and can contain occurrences from other pages. For page-local
+     * provenance, filter with `occurrence.pageIndex === page.number - 1`.
+     */
+    readonly trackedChanges: readonly MarkdownTrackedChange[];
+}
+/** Machine-readable scope of the page numbers returned by this export. @public */
+interface MarkdownPaginationInfo {
+    /** Pages come from the docx-editor semantic layout engine, not stale DOCX page-break hints. */
+    readonly source: 'layout-engine';
+    /** Page numbers describe this exact export result. */
+    readonly scope: 'export-snapshot';
+    /** Core store revision from which this layout snapshot was produced. */
+    readonly layoutRevision: number;
+    /** Tracked-change display mode used to paginate and translate this snapshot. */
+    readonly displayMode: RevisionDisplayMode;
+}
+/** Content or resources that could not be represented fully. @public */
+interface MarkdownWarning {
+    /** Stable code for filtering warnings without parsing messages. */
+    readonly code: 'omitted-drawing' | 'omitted-textbox' | 'font-origin-failed' | 'incomplete-font' | 'content-scan-limit' | 'image-placement-fallback';
+    /** Human-readable description of the limitation. */
+    readonly message: string;
+    /** One-based page number, when the warning concerns a drawing occurrence. */
+    readonly pageNumber?: number;
+    /** Package part when the warning comes from source inspection. */
+    readonly partName?: string;
+}
+/** Full logical document plus page-scoped projections. @public */
+interface MarkdownExportResult {
+    /** Unique extracted images; empty unless images are enabled. */
+    readonly media: readonly MarkdownImageAsset[];
+    /** Omitted content and font problems that may affect completeness or pagination. */
+    readonly warnings: readonly MarkdownWarning[];
+    /** Primary physical page projections, preserving Word layout boundaries and furniture. */
+    readonly pages: readonly MarkdownPage[];
+    /**
+     * Every normalized comment and tracked change, including artifacts without a page occurrence.
+     * Artifact IDs are opaque and stable only within this result.
+     */
+    readonly reviewArtifacts: readonly MarkdownReviewArtifact[];
+    /** Markdown offsets valid only within this immutable result, with explicit mapping fidelity. */
+    readonly reviewBindings: readonly MarkdownReviewBinding[];
+    /** Structured font-resolution evidence, or null when the layout's font origin is unavailable. */
+    readonly fontResolution: ExportFontResolutionReport | null;
+    /** How page numbers and tracked changes were projected for this result. */
+    readonly pagination: MarkdownPaginationInfo;
+    /** Convenience logical Markdown with split records joined and repeated furniture excluded. */
+    readonly markdown: string;
+}
+/** One caller-controlled font origin used for headless pagination. @public */
+type MarkdownFontOrigin = FontOrigin;
+/** One font origin, or an ordered first-wins list of origins. @public */
+type MarkdownFontsSource = MarkdownFontOrigin | readonly MarkdownFontOrigin[];
+/** Layout controls for a reusable Markdown export session. @public */
+interface OpenMarkdownDocumentForExportOptions extends OpenDocumentForExportOptions {
+    /**
+     * Retains incremental state for a live view or caller-measured session. Document-aware byte
+     * sessions are immutable and reject `true` instead of silently ignoring it.
+     */
+    readonly reuseAcrossRevisions?: boolean;
+    /**
+     * Caller-supplied font bytes or resolvers, in first-wins order. These take precedence over the
+     * package's bundled metric-compatible Word substitutes. A resolver is invoked after the DOCX is
+     * parsed with the bounded family list layout can render. Custom origins require immutable DOCX
+     * bytes; for a live view, supply a revision-stable `measurer` instead. An explicit measurer takes
+     * precedence and font origins are not invoked.
+     */
+    readonly fonts?: MarkdownFontsSource;
+    /**
+     * Opt-in origins consulted only after caller fonts and bundled substitutes. Put
+     * `googleFonts()` here to fetch catalogued families the local origins cannot paint. This has the
+     * same immutable-bytes restriction and explicit-measurer precedence as {@link fonts}.
+     */
+    readonly fallbackFonts?: MarkdownFontsSource;
+    /** `strict` refuses failed origins or any requested family missing one of four static faces. */
+    readonly fontPolicy?: 'best-effort' | 'strict';
+    /**
+     * Fire-and-forget evidence for the exact direct/substituted faces behind page breaks. Returned
+     * promises are observed for rejection but do not delay export.
+     */
+    readonly onFontResolution?: (report: ExportFontResolutionReport) => void;
+}
+/** Layout and resource controls for one-shot Markdown export. @public */
+interface MarkdownExportOptions extends OpenMarkdownDocumentForExportOptions, MarkdownProjectionOptions {
+}
+
+export type { MarkdownImageAsset as M, OpenMarkdownDocumentForExportOptions as O, MarkdownExportResult as a, MarkdownExportOptions as b, MarkdownProjectionOptions as c, MarkdownComment as d, MarkdownFontOrigin as e, MarkdownFontsSource as f, MarkdownImageData as g, MarkdownImageOccurrence as h, MarkdownImageOptions as i, MarkdownPage as j, MarkdownPaginationInfo as k, MarkdownReviewArtifact as l, MarkdownReviewBinding as m, MarkdownReviewCoverage as n, MarkdownReviewOccurrence as o, MarkdownReviewProjection as p, MarkdownReviewRange as q, MarkdownReviewRangePrecision as r, MarkdownReviewUnmappedReason as s, MarkdownTrackedChange as t, MarkdownWarning as u };

package/dist/node.cjs

@@ -0,0 +1 @@
+'use strict';var chunkNP5KYCWK_cjs=require('./chunk-NP5KYCWK.cjs'),promises=require('fs/promises'),path=require('path'),fs=require('fs');function C(e){return typeof e=="object"&&e!==null&&"code"in e&&e.code==="ENOENT"}async function f(e){let i=path.parse(e).root,n=i;for(let a of e.slice(i.length).split(path.sep).filter(Boolean)){n=path.join(n,a);let s=await promises.lstat(n);if(s.isSymbolicLink()||!s.isDirectory())throw new chunkNP5KYCWK_cjs.b("write-failed","Output directories must be real directories, not symbolic links.",{path:n})}}async function j(e,i){let n=chunkNP5KYCWK_cjs.d(e);if(typeof i?.directory!="string"||!i.directory.trim())throw new TypeError("directory must be a nonempty path");let a=path.resolve(i.directory),s=[],w=[];try{let r=await promises.realpath(path.dirname(a)),t=path.join(r,path.basename(a));await f(r);try{await promises.mkdir(t),w.push(t);}catch(o){if(!(typeof o=="object"&&o&&"code"in o&&o.code==="EEXIST"))throw o}if(await f(t),(await promises.readdir(t)).length)throw new chunkNP5KYCWK_cjs.b("output-not-empty","Choose a new or empty directory; existing files are never overwritten.",{path:t});if(e.media.length){let o=path.join(t,"media");await promises.mkdir(o),w.push(o);}for(let[o,k]of n){let p=path.join(t,o);await f(path.dirname(p));let m=await promises.open(p,fs.constants.O_WRONLY|fs.constants.O_CREAT|fs.constants.O_EXCL|fs.constants.O_NOFOLLOW,384);s.push(p);try{await m.writeFile(k);}finally{await m.close();}}}catch(r){for(let t of s.reverse())try{await promises.unlink(t);}catch{}for(let t of w.reverse())try{await promises.rmdir(t);}catch{}throw r instanceof chunkNP5KYCWK_cjs.b?r:new chunkNP5KYCWK_cjs.b("write-failed",C(r)?"The parent output directory must exist.":"Could not write the Markdown bundle.",{path:a,cause:r})}}exports.writeMarkdownBundle=j;

package/dist/node.d.cts

@@ -0,0 +1,14 @@
+/// <reference lib="dom" />
+import { a as MarkdownExportResult } from './markdown-types-Cn-MizR0.cjs';
+import '@docx-editor.dev/core/layout';
+import '@docx-editor.dev/core/export';
+
+/** Output folder for a portable bundle. @public */
+interface WriteMarkdownBundleOptions {
+    /** New or existing empty directory. Files are never overwritten. */
+    readonly directory: string;
+}
+/** Write document.md, document.json, and media/ into a new or empty directory. @public */
+declare function writeMarkdownBundle(result: MarkdownExportResult, options: WriteMarkdownBundleOptions): Promise<void>;
+
+export { type WriteMarkdownBundleOptions, writeMarkdownBundle };

package/dist/node.d.ts

@@ -0,0 +1,14 @@
+/// <reference lib="dom" />
+import { a as MarkdownExportResult } from './markdown-types-Cn-MizR0.js';
+import '@docx-editor.dev/core/layout';
+import '@docx-editor.dev/core/export';
+
+/** Output folder for a portable bundle. @public */
+interface WriteMarkdownBundleOptions {
+    /** New or existing empty directory. Files are never overwritten. */
+    readonly directory: string;
+}
+/** Write document.md, document.json, and media/ into a new or empty directory. @public */
+declare function writeMarkdownBundle(result: MarkdownExportResult, options: WriteMarkdownBundleOptions): Promise<void>;
+
+export { type WriteMarkdownBundleOptions, writeMarkdownBundle };

package/dist/node.js

@@ -0,0 +1 @@
+import {d,b}from'./chunk-CYF5JG4K.js';import {realpath,mkdir,readdir,open,unlink,rmdir,lstat}from'fs/promises';import {resolve,dirname,join,basename,parse,sep}from'path';import {constants}from'fs';function C(e){return typeof e=="object"&&e!==null&&"code"in e&&e.code==="ENOENT"}async function f(e){let i=parse(e).root,n=i;for(let a of e.slice(i.length).split(sep).filter(Boolean)){n=join(n,a);let s=await lstat(n);if(s.isSymbolicLink()||!s.isDirectory())throw new b("write-failed","Output directories must be real directories, not symbolic links.",{path:n})}}async function j(e,i){let n=d(e);if(typeof i?.directory!="string"||!i.directory.trim())throw new TypeError("directory must be a nonempty path");let a=resolve(i.directory),s=[],w=[];try{let r=await realpath(dirname(a)),t=join(r,basename(a));await f(r);try{await mkdir(t),w.push(t);}catch(o){if(!(typeof o=="object"&&o&&"code"in o&&o.code==="EEXIST"))throw o}if(await f(t),(await readdir(t)).length)throw new b("output-not-empty","Choose a new or empty directory; existing files are never overwritten.",{path:t});if(e.media.length){let o=join(t,"media");await mkdir(o),w.push(o);}for(let[o,k]of n){let p=join(t,o);await f(dirname(p));let m=await open(p,constants.O_WRONLY|constants.O_CREAT|constants.O_EXCL|constants.O_NOFOLLOW,384);s.push(p);try{await m.writeFile(k);}finally{await m.close();}}}catch(r){for(let t of s.reverse())try{await unlink(t);}catch{}for(let t of w.reverse())try{await rmdir(t);}catch{}throw r instanceof b?r:new b("write-failed",C(r)?"The parent output directory must exist.":"Could not write the Markdown bundle.",{path:a,cause:r})}}export{j as writeMarkdownBundle};

package/docs/api.md

@@ -0,0 +1,330 @@
+# DOCX to Markdown API reference
+
+Use this reference to choose an export function, configure conversion, and inspect the result.
+For installation and a first export, see the [package quickstart](../README.md).
+
+## Public interface
+
+```ts
+exportMarkdown(
+  source: Uint8Array | HeadlessDocumentView,
+  options?: MarkdownExportOptions
+): Promise<MarkdownExportResult>;
+
+openDocumentForExport(
+  source: Uint8Array | HeadlessDocumentView,
+  options?: OpenMarkdownDocumentForExportOptions
+): Promise<OpenMarkdownDocumentForExportResult>;
+
+exportMarkdownFrom(
+  session: ExportSession,
+  options?: MarkdownProjectionOptions
+): Promise<MarkdownExportResult>;
+
+exportMarkdownLayout(layout: ExportSemanticLayout): MarkdownExportResult;
+```
+
+Use `exportMarkdown` for a single export. To reuse or inspect a layout, use `openDocumentForExport` and `exportMarkdownFrom`. To convert a layout after disposing its session, use `exportMarkdownLayout`.
+
+### Result shape
+
+```ts
+interface MarkdownExportResult {
+  /** Unique extracted assets, or [] when images are disabled. */
+  readonly media: readonly MarkdownImageAsset[];
+  /** Omitted content and font problems. */
+  readonly warnings: readonly MarkdownWarning[];
+  /** Primary output: physical page projections with page furniture and provenance. */
+  readonly pages: readonly MarkdownPage[];
+  /** All comments and tracked changes, including artifacts without a page occurrence. */
+  readonly reviewArtifacts: readonly MarkdownReviewArtifact[];
+  /** Offsets and artifact IDs valid only within this immutable result. */
+  readonly reviewBindings: readonly MarkdownReviewBinding[];
+  /** Font families and faces used for pagination, or null when the layout's font origin is unavailable. */
+  readonly fontResolution: ExportFontResolutionReport | null;
+  /** How this result's pages and revision content were produced. */
+  readonly pagination: {
+    readonly source: 'layout-engine';
+    readonly scope: 'export-snapshot';
+    readonly layoutRevision: number;
+    readonly displayMode: 'all-markup' | 'proposed' | 'original';
+  };
+  /** Convenience logical, full-document Markdown. */
+  readonly markdown: string;
+}
+
+interface MarkdownPage {
+  /** Identifier for this page within this export result. */
+  readonly id: string;
+  /** One-based physical page number. */
+  readonly number: number;
+  /** Body content and page-local note definitions or continuations. */
+  readonly markdown: string;
+  /** Header and footer are separate from logical document content. */
+  readonly headerMarkdown: string;
+  readonly footerMarkdown: string;
+  /** Membership views: complete artifacts with at least one occurrence on this page. */
+  readonly comments: readonly MarkdownComment[];
+  readonly trackedChanges: readonly MarkdownTrackedChange[];
+}
+
+interface MarkdownReviewBinding {
+  readonly artifactId: string;
+  readonly artifactKind: 'comment' | 'tracked-change';
+  readonly occurrenceIndex: number;
+  readonly coverage: 'complete' | 'partial' | 'none';
+  readonly projection:
+    | { readonly kind: 'document' }
+    | {
+        readonly kind: 'page';
+        readonly pageIndex: number;
+        readonly pageNumber: number;
+        readonly field: 'markdown' | 'headerMarkdown' | 'footerMarkdown';
+      };
+  readonly ranges: readonly {
+    readonly start: number;
+    readonly end: number;
+    readonly unit: 'utf16-code-unit';
+    readonly precision: 'exact' | 'containing-construct';
+  }[];
+  readonly unmappedReason?:
+    | 'not-represented-in-markdown'
+    | 'non-linear-structural-change'
+    | 'omitted-story-content';
+}
+```
+
+`fontResolution` lists requested families, resolved and substituted faces, coverage (`complete`, `partial`, or `none`), and nonfatal `originFailures`. Document-aware byte sessions return this report. Reusable sessions also expose it as `session.fontResolution`. It is `null` for detached layouts, custom measurers, ordinary Core sessions, and live views using shared shaping. Fatal failures throw `DocumentOpenError` or `ExportResourceError`.
+
+`pages` contains the page output from the editor's layout engine. Page numbers and IDs apply only to this export. Different fonts or Microsoft Word versions can produce different page breaks.
+
+`pagination` records the layout source, export scope, Core revision, and tracked-change display mode.
+
+For citations that must survive storage or document updates, retain your own document version or content hash alongside the page number. For example:
+
+```ts
+const citation = {
+  documentVersion: contract.sha256,
+  engineVersion: applicationBuild.docxEditorVersion,
+  pageNumber: result.pages[11]!.number,
+  pageId: result.pages[11]!.id,
+  pagination: result.pagination,
+};
+```
+
+`result.markdown` contains the whole document. It joins content split across pages and excludes repeated headers and footers. Use `pages` when you need page citations.
+
+### Comments and tracked changes
+
+The exporter returns comments and revision metadata separately from Markdown. Review IDs are opaque and valid only within one export. For stored citations, include your own document version or content hash.
+
+`page.comments` and `page.trackedChanges` contain complete artifacts with occurrences on that page. Their `occurrences` can include other pages. Filter them to avoid double counting:
+
+```ts
+const localComments = page.comments.flatMap((artifact) =>
+  artifact.occurrences
+    .filter(({ physicalPageNumber }) => physicalPageNumber === page.number)
+    .map((occurrence) => ({ artifact, occurrence }))
+);
+```
+
+Page artifacts can occur in the body, headers, footers, footnotes, endnotes, or note separators. `result.reviewArtifacts` contains all artifacts, including those without a page occurrence.
+
+`result.reviewBindings` connects each occurrence to offsets in `result.markdown`, `page.markdown`, `page.headerMarkdown`, or `page.footerMarkdown`. Offsets use JavaScript UTF-16 string indexing and can be passed directly to `slice()`:
+
+```ts
+for (const binding of result.reviewBindings) {
+  const output =
+    binding.projection.kind === 'document'
+      ? result.markdown
+      : result.pages[binding.projection.pageIndex]![binding.projection.field];
+
+  for (const range of binding.ranges) {
+    console.log(output.slice(range.start, range.end));
+  }
+}
+```
+
+For source-aligned edits, require `coverage === 'complete'` and `precision === 'exact'`. For citations or display, you can use partial or `containing-construct` bindings if you retain that precision information. Existing bindings with no mapped ranges include an `unmappedReason`.
+
+Artifacts without occurrences have no bindings or `unmappedReason`. These include orphan comments and comments entirely hidden by the selected revision mode. Inspect `result.reviewArtifacts` as well as `result.reviewBindings` to retain them.
+
+Artifact IDs, occurrence indexes, page IDs, and offsets are valid only within this export.
+
+Tracked changes also participate in layout through `displayMode`: `all-markup` (default) keeps inserted and deleted text visible, `proposed` includes pending insertions and hides pending deletions, and `original` hides pending insertions and shows pending deletions. Revision mode applies to the whole document.
+
+## Images and portable delivery
+
+Enable `images: true` for relative image links and `result.media` bytes. Use `{ images: { resolveUrl, maxTotalBytes } }` for custom delivery. The default extracted-byte limit is 64 MiB; image extraction is opt-in. `exportMarkdownFrom(session, options)` accepts the same image options and an abort signal.
+
+Set `images: { syntax: 'html' }` to emit `<img>` tags with each occurrence's displayed width and height in whole CSS pixels.
+The default `syntax: 'markdown'` emits standard image links without size attributes.
+Your renderer must support sanitized HTML and retain `width` and `height`.
+Occurrences expose exact `displayWidthPx`, `displayHeightPx`, and `kind` (`inline` or `anchored`).
+Asset `pixelWidth` and `pixelHeight` describe the image bytes, not their displayed size.
+Crop, rotation, and floating text wrapping are not reproduced.
+
+`createMarkdownZip(result)` and `toMarkdownJSON(result)` are exported from the main package. `writeMarkdownBundle(result, { directory })` comes from `@docx-editor.dev/docx-to-markdown/node`. See [image APIs, errors, ownership, and runnable workflows](images.md).
+
+## Options
+
+`MarkdownExportOptions` contains layout and resource controls for the export snapshot.
+
+| Option                  | Meaning                                                                                       |
+| ----------------------- | --------------------------------------------------------------------------------------------- |
+| `displayMode`           | Tracked-change projection: `all-markup` (default), `proposed`, or `original`.                 |
+| `signal`                | Aborts resource waits and later layout work.                                                  |
+| `resourceTimeoutMs`     | Deadline applied separately to initial font provisioning and each layout resource wait.       |
+| `reuseAcrossRevisions`  | Retains state for live/caller-measured sessions; document-aware byte sessions reject `true`.  |
+| `fonts`                 | Font configuration or resolver. Earlier entries win. Requires immutable DOCX bytes.           |
+| `fallbackFonts`         | Fallback after bundled fonts. Requires DOCX bytes. Accepts `googleFonts()`.                   |
+| `fontPolicy`            | `best-effort` (default), or `strict` to require all four static faces and no origin failures. |
+| `onFontResolution`      | Receives the font-resolution report.                                                          |
+| `measurer`              | Custom text measurer. Overrides font resolution.                                              |
+| `producer`              | Stable identity for a host-owned measurer and its cache entries.                              |
+| `imageDecodePort`       | Custom image metadata decoder. Defaults to the Node.js decoder.                               |
+| `convertPreservedImage` | Converts preserved EMF, WMF, or TIFF bytes to a supported raster format.                      |
+
+`fontPolicy` and `onFontResolution` require immutable DOCX bytes with the default document-aware font resolution. Both options throw `TypeError` when used with a live `HeadlessDocumentView` or combined with a custom `measurer`, including an explicit `fontPolicy: 'best-effort'`.
+
+### Tracked changes
+
+To show the proposed text, set `displayMode` to `proposed`. This changes the export projection; it does not accept changes in the DOCX. Review artifacts remain available:
+
+```ts
+const proposed = await exportMarkdown(docxBytes, {
+  displayMode: 'proposed',
+});
+```
+
+## Reuse an export session
+
+```ts
+import { readFile } from 'node:fs/promises';
+import { exportMarkdownFrom, openDocumentForExport } from '@docx-editor.dev/docx-to-markdown';
+
+const docxBytes = await readFile('document.docx');
+const opened = await openDocumentForExport(docxBytes, {
+  displayMode: 'all-markup',
+});
+
+if (!opened.ok) {
+  throw new Error(
+    `DOCX was refused: ${opened.reason}${opened.detail ? ` (${opened.detail})` : ''}`
+  );
+}
+
+try {
+  // Resource settlement and layout are cached by the session.
+  const layout = await opened.session.layout();
+  console.log(`Pages: ${layout.pages.length}`);
+
+  const first = await exportMarkdownFrom(opened.session);
+  const second = await exportMarkdownFrom(opened.session);
+  console.log(first.pages.length === second.pages.length);
+} finally {
+  opened.session.dispose();
+}
+```
+
+Call `dispose()` on reusable sessions to release caches and pending resource work. Repeated calls are safe. Live views can retain state across revisions; byte sources use one-shot caching by default.
+
+For a single export, use `exportMarkdown(docxBytes)`. To keep a layout without retaining session resources, obtain it before disposal, then pass it to `exportMarkdownLayout`. Layouts remain valid after disposal.
+
+## Images
+
+Images affect page boundaries and are omitted from Markdown unless you enable `images`. If omitting an inline image would join words, the exporter inserts a space.
+
+## Errors and cancellation
+
+For malformed or unsupported DOCX input, `exportMarkdown` throws `DocumentOpenError`. `openDocumentForExport` returns `{ ok: false, reason, detail }` instead.
+
+Both workflows throw `TypeError` for unsupported combinations of [export options](#options), such as a custom `measurer` combined with `fontPolicy` or `onFontResolution`.
+
+Both workflows can throw `ExportResourceError` with one of these codes:
+
+- `aborted`, `timedOut`, `nonConvergent`, or `disposed`.
+- `layoutInvariant`: document geometry exceeds the engine's page model.
+- `layoutFailed`: another layout or host integration failure.
+
+The layout errors retain the original diagnostic as `cause`. Aborting a reusable session releases its resources and prevents reuse. Calling `dispose()` afterward is safe.
+
+```ts
+import {
+  DocumentOpenError,
+  ExportResourceError,
+  exportMarkdown,
+} from '@docx-editor.dev/docx-to-markdown';
+
+const controller = new AbortController();
+
+try {
+  const result = await exportMarkdown(docxBytes, {
+    signal: controller.signal,
+    resourceTimeoutMs: 30_000,
+  });
+  console.log(result.markdown);
+} catch (error) {
+  if (error instanceof DocumentOpenError) {
+    console.error(error.reason, error.detail);
+  } else if (error instanceof ExportResourceError) {
+    console.error(error.code, error.message);
+  } else {
+    throw error;
+  }
+}
+```
+
+## Layout and fonts
+
+Core resolves fonts, images, document geometry, and `displayMode` before pagination. Markdown uses that immutable layout. `signal` and `resourceTimeoutMs` cover resource processing.
+
+See [Configure fonts for Markdown layout](fonts.md) for resolution order, bundled substitutes, separate Google Fonts and custom-font examples, strict mode, and troubleshooting.
+
+Custom `fonts` and `fallbackFonts` require immutable DOCX bytes. For a live `HeadlessDocumentView`, use a host-owned, revision-stable `measurer` with a stable `producer`. A custom measurer takes precedence and bypasses both font options. Omit `fontPolicy` and `onFontResolution` when using a custom measurer or live view; these combinations throw `TypeError`.
+
+Use `onFontResolution` to observe resolved and substituted faces. The exporter does not await callback promises. Callback errors are logged without failing the export. To wait for report storage, save `result.fontResolution` after export and await that operation.
+
+Use `googleFonts({ onFailure })` to log fallback failures. Failed or aborted Google Fonts requests are not cached.
+
+### Font limits
+
+The package exports these limits:
+
+- `HARD_MAX_FONT_BYTES`: 64 MiB per face.
+- `HARD_MAX_FONT_SOURCES`: 256 sources per composition.
+- `HARD_MAX_AGGREGATE_FONT_BYTES`: 128 MiB per composition and across active document font leases.
+
+Invalid or oversized origins are reported and skipped. Exceeding the process-wide lease budget causes `layoutFailed`. Return only requested faces from resolvers, limit concurrent exports, and dispose reusable sessions promptly. Use the exported constants in your code.
+
+Document-embedded fonts are admitted after caller fonts, bundled substitutes, and optional fallback origins, using the same mapper as the browser editor. Regular, bold, italic, and bold-italic embedded faces must pass the shared font limits.
+
+## Warnings
+
+`result.warnings` contains `{ code, message, pageNumber?, partName? }` objects. Codes are stable; messages are for display. `pageNumber` is one-based when present.
+
+| Code                 | Meaning                                                              |
+| -------------------- | -------------------------------------------------------------------- |
+| `omitted-drawing`    | Images or shapes are omitted.                                        |
+| `omitted-textbox`    | Text box content is omitted.                                         |
+| `font-origin-failed` | A font source failed to load.                                        |
+| `content-scan-limit` | Source inspection reached its bound; additional omissions may exist. |
+| `incomplete-font`    | A requested family lacks one or more faces; pagination may differ.   |
+
+Drawing warnings are grouped by category and page, including headers, footers, and notes. Unsupported legacy images, shapes, and text boxes are reported from the source package with `partName`, without a page number. Each warning identifies omitted content.
+
+## Markdown limitations
+
+- Use `pages` for page output and `markdown` for the whole document.
+- Page headers and footers are returned separately per page.
+- Merged table cells are flattened.
+- Nested tables use inline HTML (`<table>`, `<tr>`, `<td>`, and `<th>`). Cells retain inline Markdown.
+- Images affect layout. They are omitted by default; `images: true` includes supported images and returns their bytes.
+- Anchored text-box text is omitted because it has no unambiguous linear position; comments and tracked changes inside it remain available as page artifacts with exact text-box provenance.
+- Office Math uses the core semantic equation fallback.
+- A note continued without its reference is emitted as a labeled continuation block in page Markdown.
+
+## See also
+
+- [Image extraction and delivery](images.md).
+- [Application integrations](integrations.md).