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

package/docs/fonts.md

@@ -0,0 +1,172 @@
+# Configure fonts for Markdown layout
+
+Use fonts that match the source document when you need accurate page references. The converter measures text to calculate line wrapping, table row heights, and page boundaries before generating Markdown. Markdown does not preserve the DOCX font family; your renderer controls the displayed font.
+
+Before you begin, [install the converter](../README.md#install-the-package). The examples use Node.js and DOCX bytes. Save each complete example as `convert.mjs`, place `document.docx` beside it, and run `node convert.mjs`.
+
+## Choose a font source
+
+| Your task                                          | Configuration                                                                              |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Convert documents that use common Word fonts       | Start with the bundled defaults; no font option is required.                               |
+| Load missing faces from Google Fonts               | Set `fallbackFonts: googleFonts()`. Network access is required.                            |
+| Use your own fonts or replace a bundled substitute | Supply font bytes through `fonts`.                                                         |
+| Convert without network access                     | Use bundled fonts, document-embedded fonts, and local custom fonts. Omit remote resolvers. |
+
+Fonts resolve in this order:
+
+1. Your `fonts` configuration or resolvers, with earlier entries taking priority.
+2. Bundled substitutes.
+3. Optional `fallbackFonts`.
+4. Document-embedded fonts for faces that earlier sources did not resolve.
+
+A fallback supplies missing faces. It does not replace a face that an earlier source has already resolved. To override a bundled substitute, use `fonts`.
+
+## Start with bundled fonts
+
+The converter includes substitutes for common Word fonts:
+
+| Word font       | Bundled substitute |
+| --------------- | ------------------ |
+| Calibri         | Carlito            |
+| Cambria         | Caladea            |
+| Times New Roman | Liberation Serif   |
+| Arial           | Liberation Sans    |
+| Courier New     | Liberation Mono    |
+
+These substitutes target matching character widths for the glyphs they cover. Differences in glyphs and kerning can still change line and page breaks. For matching page references, compare representative exports with Word using the same revision visibility.
+
+If a font remains unresolved, the default `fontPolicy: 'best-effort'` allows approximate measurement. Check the resolution report before relying on page citations.
+
+## Add Google Fonts fallback
+
+Install the fonts package as a direct dependency of your application:
+
+```sh
+npm install @docx-editor.dev/fonts
+```
+
+This example keeps the bundled substitutes and requests missing faces from the Google Fonts catalog:
+
+```js
+import { readFile } from 'node:fs/promises';
+import { exportMarkdown } from '@docx-editor.dev/docx-to-markdown';
+import { googleFonts } from '@docx-editor.dev/fonts/google';
+
+const docxBytes = await readFile('document.docx');
+const result = await exportMarkdown(docxBytes, {
+  fallbackFonts: googleFonts(),
+});
+
+console.log(result.markdown);
+console.dir(result.fontResolution, { depth: null });
+console.log(result.warnings);
+```
+
+The resolver fetches matching faces from a pinned catalog with verified content hashes. Requests disclose requested font families to the CDN. It cannot supply fonts outside the catalog or guarantee the same pagination as Word.
+
+For offline conversion, omit `fallbackFonts` and ensure that any custom resolvers use local data.
+
+## Supply your own fonts
+
+Use `fonts` when you have licensed font files that match the document, or when you need to override a bundled substitute. Register each face under the family name requested by the DOCX.
+
+This example expects a document that uses Aptos and four licensed files in a `fonts/` directory beside `convert.mjs`: `Aptos.ttf`, `Aptos-Bold.ttf`, `Aptos-Italic.ttf`, and `Aptos-BoldItalic.ttf`. Replace the family name and filenames with your document's fonts. The converter does not include these files.
+
+```js
+import { readFile } from 'node:fs/promises';
+import { createFontSource, exportMarkdown } from '@docx-editor.dev/docx-to-markdown';
+
+const faces = [
+  { file: 'Aptos.ttf', weight: 400, style: 'normal' },
+  { file: 'Aptos-Bold.ttf', weight: 700, style: 'normal' },
+  { file: 'Aptos-Italic.ttf', weight: 400, style: 'italic' },
+  { file: 'Aptos-BoldItalic.ttf', weight: 700, style: 'italic' },
+];
+
+const sources = [];
+for (const { file, weight, style } of faces) {
+  const bytes = new Uint8Array(await readFile(`fonts/${file}`));
+  const admitted = createFontSource(bytes, { family: 'Aptos', weight, style });
+  if ('failure' in admitted) {
+    throw new Error(admitted.failure.diagnostic ?? admitted.failure.reason);
+  }
+  sources.push(admitted.source);
+}
+
+const docxBytes = await readFile('document.docx');
+const result = await exportMarkdown(docxBytes, { fonts: { sources } });
+
+console.log(result.markdown);
+console.dir(result.fontResolution, { depth: null });
+```
+
+Repeat registration for other document families. You can combine `fonts` with `fallbackFonts` to resolve faces your local sources do not provide.
+
+## Read the font report
+
+`result.fontResolution.families` reports the faces available for each checked family. For example, a family with only its regular face can produce an entry like this; optional identity fields are omitted:
+
+```json
+{
+  "family": "Acme Sans",
+  "coverage": "partial",
+  "faces": [
+    {
+      "weight": 400,
+      "style": "normal",
+      "sourceFamily": "Acme Sans",
+      "via": "direct"
+    }
+  ]
+}
+```
+
+This entry means that the bold, italic, and bold-italic faces are missing. Supply those files through `fonts`, or use a fallback that provides them.
+
+- `coverage: 'complete'` means all four static faces resolved. It does not certify glyph coverage for every script or that the original Word fonts were used.
+- `coverage: 'partial'` means some faces resolved. `coverage: 'none'` means no faces resolved.
+- `via: 'substitution'` identifies a substituted face. Inspect `sourceFamily` and the face's `substitution` details to understand the choice.
+- `originFailures` records font-source failures, even when another source supplies the missing faces.
+
+For a compact view, add this code after either conversion example:
+
+```js
+console.table(
+  result.fontResolution?.families.map(({ family, coverage, faces }) => ({
+    family,
+    coverage,
+    faces: faces.map(({ weight, style, via }) => `${weight} ${style} (${via})`).join(', '),
+  })) ?? []
+);
+```
+
+Document-aware byte exports return a report. Detached layouts and custom measurers can return `fontResolution: null`; that means evidence is unavailable, not that no fonts were needed.
+
+## Require complete font resolution
+
+Add `fontPolicy: 'strict'` to the options in either conversion example to reject font-source failures or missing regular, bold, italic, or bold-italic faces among the checked families. Strict mode can reject an export even if the document only uses regular text or another source recovered from a font-source failure.
+
+Strict mode checks font resolution. It does not guarantee the same page breaks as Word, and complete coverage can include substitutes. The resolver checks at most 64 candidate families, prioritizing the body, then headers and footers, then notes. Additional families do not cause strict mode to fail.
+
+Save `result.fontResolution`, your package versions, font configuration, document version, and revision mode with exports that require reproducible page citations. Use `toMarkdownJSON(result)` when storing the result as JSON so font failure causes become diagnostic strings.
+
+## Troubleshoot fonts and pagination
+
+| Symptom                                        | What to check                                         | What to do                                                                                                                                                |
+| ---------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Page breaks differ from Word                   | Substituted or incomplete families, and `displayMode` | Supply the source document's fonts through `fonts`, match revision visibility, and compare representative documents. Other layout differences can remain. |
+| `incomplete-font` warning                      | The family's `coverage` and `faces`                   | Supply the missing regular, bold, italic, or bold-italic files. Use Google Fonts fallback only if it contains that family and those faces.                |
+| `font-origin-failed` warning                   | `fontResolution.originFailures`                       | Correct the failing resolver or file path. For remote sources, check network access and the reported failure.                                             |
+| Google Fonts does not change the selected font | Whether an earlier source already resolved the face   | Put your replacement font in `fonts`; `fallbackFonts` does not override bundled substitutes.                                                              |
+| Strict export fails with `layoutFailed`        | The error message and font-source diagnostics         | Supply missing faces or fix the failing source. Use best effort only if approximate measurement is acceptable.                                            |
+| Font policy throws `TypeError`                 | Input type and custom `measurer`                      | Pass immutable DOCX bytes with the default measurer, or omit `fontPolicy` and `onFontResolution` for a live view or custom measurer.                      |
+| Deployed export cannot load bundled fonts      | Whether deployment retained package assets            | Follow the Node.js and Next.js deployment configuration in the integration guide.                                                                         |
+
+For strict failures, use `onFontResolution: (report) => console.dir(report, { depth: null })` to inspect the report before rejection. The exporter does not await callback promises. See the [font resource limits](api.md#font-limits) for file size and memory constraints.
+
+## Next steps
+
+- [Deploy the converter](integrations.md#nextjs).
+- [Read page and warning fields](api.md).
+- [Include and deliver images](images.md).

package/docs/images.md

@@ -0,0 +1,223 @@
+# Include images in Markdown exports
+
+Before you begin, [install the converter](../README.md#install-the-package).
+Set `images: true` to include image links and extracted bytes. For this Node.js example, save the code as `convert.mjs`, place `document.docx` beside it, and run `node convert.mjs`:
+
+```ts
+import { readFile } from 'node:fs/promises';
+import { exportMarkdown } from '@docx-editor.dev/docx-to-markdown';
+
+const docxBytes = await readFile('document.docx');
+const result = await exportMarkdown(docxBytes, { images: true });
+console.log(result.markdown); // ![Description](media/<digest>.png)
+console.log(result.media); // Unique bytes, paths, URLs, dimensions, and occurrences.
+```
+
+`images: true` and `images: {}` use relative URLs. If you omit `images`, the result contains no image links and returns `media: []`.
+
+Each image contains its ID, path, URL, MIME type, bytes, intrinsic dimensions, and occurrences.
+The ID is a hexadecimal SHA-256 digest without the `sha256:` prefix. MIME types and extensions describe the exported bytes, including converted images.
+
+Each occurrence records its page, story, source position, displayed dimensions, drawing kind, and alternative text.
+Repeated uses of identical bytes share one asset with separate occurrences. Source offsets use UTF-16 code units.
+Keep the document version with stored citations: occurrence and page identifiers belong to that export snapshot.
+See the [image types](https://github.com/eigenpal/docx-editor/blob/main/packages/docx-to-markdown/src/media-types.ts) for all returned fields.
+
+## Preserve displayed image sizes
+
+An image file's `pixelWidth` and `pixelHeight` describe its intrinsic pixels. Word can display the same file at different sizes.
+Use each occurrence's `displayWidthPx` and `displayHeightPx` for the document's displayed size, in CSS pixels at 96 pixels per inch.
+These values retain fractional pixels. `kind` distinguishes inline and anchored drawings.
+
+Standard Markdown image syntax has no width or height attributes. To carry each occurrence's size into your Markdown renderer, replace the conversion call in the first example with:
+
+```ts
+const result = await exportMarkdown(docxBytes, {
+  images: { syntax: 'html' },
+});
+// <img src="media/<digest>.png" alt="Banner" width="300" height="80">
+```
+
+The converter escapes HTML attributes and rounds the display dimensions to whole CSS pixels. Extents smaller than half a pixel round to zero.
+This option works with local folders, ZIP downloads, and `resolveUrl` for server storage.
+The default `syntax: 'markdown'` keeps standard image links without dimensions.
+Both options return full occurrence metadata.
+
+Configure your renderer to parse HTML, sanitize it, and retain `img` attributes `src`, `alt`, `width`, and `height`.
+For example, [`react-markdown`](https://github.com/remarkjs/react-markdown#appendix-a-html-in-markdown) supports `rehype-raw` followed by [`rehype-sanitize`](https://github.com/rehypejs/rehype-sanitize); the default sanitizer retains these attributes.
+If your renderer disables HTML or removes size attributes, use the metadata in a custom preview.
+
+For a custom React preview, pass the selected occurrence and its asset's trusted preview URL:
+
+```tsx
+import type { MarkdownImageOccurrence } from '@docx-editor.dev/docx-to-markdown';
+
+function ImagePreview({
+  imageUrl,
+  occurrence,
+}: {
+  imageUrl: string;
+  occurrence: MarkdownImageOccurrence;
+}) {
+  const { displayWidthPx: width, displayHeightPx: height, alt } = occurrence;
+  return (
+    <img
+      src={imageUrl}
+      alt={alt}
+      width={Math.round(width)}
+      height={Math.round(height)}
+      style={{
+        display: 'inline',
+        width,
+        maxWidth: '100%',
+        height: width === 0 || height === 0 ? height : 'auto',
+        ...(width > 0 && height > 0 ? { aspectRatio: `${width} / ${height}` } : {}),
+      }}
+    />
+  );
+}
+```
+
+The explicit aspect ratio preserves Word's displayed proportions when the image shrinks, even if they differ from its intrinsic proportions.
+Use the same styles in a custom Markdown image component, with `width` and `height` from the generated HTML.
+Resolve `src` through your known asset URLs, as shown in the browser example.
+
+Do not use an asset's first occurrence to size every image with the same URL.
+Occurrences describe physical layout and include repeated headers; their order is not a Markdown image index.
+Use HTML syntax to attach the correct dimensions directly to each rendered image.
+For a preview built from occurrence metadata, identify the occurrence by its page, story, part, and drawing node.
+
+Displayed dimensions describe the drawing's extent before crop and rotation. They do not reproduce cropping, rotation, effects, alignment, or floating text wrapping.
+Anchored images appear at their source paragraph positions in Markdown.
+
+## Save a local folder
+
+Use `writeMarkdownBundle()` to save Markdown, JSON metadata, and image files:
+
+```ts
+import { readFile } from 'node:fs/promises';
+import { exportMarkdown } from '@docx-editor.dev/docx-to-markdown';
+import { writeMarkdownBundle } from '@docx-editor.dev/docx-to-markdown/node';
+
+const result = await exportMarkdown(await readFile('input.docx'), { images: true });
+await writeMarkdownBundle(result, { directory: './output' });
+```
+
+The helper writes `document.md`, `document.json`, and `media/`.
+The parent directory must exist, and the output directory must be new or empty. Existing files are not overwritten.
+Files use `0o600` permissions where supported. JSON includes page, review, and image metadata without image bytes.
+
+## Save a ZIP file
+
+This complete Node.js example writes a portable archive:
+
+```js
+import { readFile, writeFile } from 'node:fs/promises';
+import { createMarkdownZip, exportMarkdown } from '@docx-editor.dev/docx-to-markdown';
+
+const result = await exportMarkdown(await readFile('document.docx'), { images: true });
+await writeFile('document.zip', await createMarkdownZip(result));
+```
+
+The ZIP includes `document.md`, `document.json`, and `media/`. Keep generated relative image URLs for ZIP and folder output; exports with hosted URLs cannot be saved as portable bundles.
+
+## Convert and download in the browser
+
+Configure your bundler to serve the package's font and WebAssembly assets.
+For a working configuration, see the [browser demo](https://github.com/eigenpal/docx-editor/tree/main/examples/docx-to-markdown).
+Image extraction runs in the browser without a server or storage service.
+
+```ts
+import { exportMarkdown, createMarkdownZip } from '@docx-editor.dev/docx-to-markdown';
+
+async function download(file: File) {
+  const bytes = new Uint8Array(await file.arrayBuffer());
+  const result = await exportMarkdown(bytes, { images: true });
+  const zip = await createMarkdownZip(result);
+  const url = URL.createObjectURL(new Blob([zip.slice().buffer], { type: 'application/zip' }));
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = file.name.replace(/\.docx$/i, '') + '.zip';
+  link.click();
+  setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+```
+
+ZIP and folder output contain the same files. ZIP entry ordering and timestamps are deterministic. ZIP compression yields between bounded chunks; it needs no workers or worker CSP permissions. Both helpers require portable URLs (`image.url === image.path`). For a local bundle, export with `images: true` without `resolveUrl`; hosted-URL results produce `MarkdownBundleError` with `non-portable-image-url`.
+
+For an on-screen preview, use your completed browser export as `result` and map paths to object URLs without rewriting Markdown:
+
+```ts
+const imageUrls = new Map(
+  result.media.map((image) => [
+    image.path,
+    URL.createObjectURL(new Blob([image.bytes.slice().buffer], { type: image.mimeType })),
+  ])
+);
+
+// Give your Markdown renderer a custom image component that looks up only known paths.
+// Continue sanitizing Markdown and HTML. Render SVG through <img>, never inline SVG.
+// On result replacement, unmount, or a discarded async result:
+for (const url of imageUrls.values()) URL.revokeObjectURL(url);
+```
+
+Create URLs outside rendering. Keep them alive while the corresponding preview remains visible. Do not persist or transmit object URLs; they belong to the current browser context. See [MDN object URL lifecycle](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL_static).
+
+## Return server URLs to a client
+
+The application supplies storage and returns its image URLs. The converter does not create a backend or upload files automatically.
+
+```ts
+import { exportMarkdown, toMarkdownJSON } from '@docx-editor.dev/docx-to-markdown';
+
+// storage and documentId belong to your application.
+const result = await exportMarkdown(docxBytes, {
+  signal: request.signal,
+  images: {
+    resolveUrl: (image, { signal }) =>
+      storage.upload(`documents/${documentId}/${image.path}`, image.bytes, {
+        contentType: image.mimeType,
+        signal,
+      }),
+  },
+});
+return Response.json(toMarkdownJSON(result));
+```
+
+`toMarkdownJSON` omits image bytes and converts arbitrary font-origin failure causes to diagnostic strings. It preserves the remaining export fields. Send binary image responses separately. Do not JSON-serialize `Uint8Array` values directly. Metadata stores raw URLs; Markdown destinations are escaped separately. Resolvers may return relative paths or absolute HTTP(S) URLs. Relative paths require application routing or accompanying files.
+
+The resolver runs once per unique image, sequentially, after all extraction and budget checks succeed. This makes callback ordering predictable; many remote uploads incur cumulative latency. There are no automatic retries. URLs are finalized before translation, preserving correct review offsets. Applications own completed uploads, cleanup after failure, access control, and signed-URL expiry.
+
+Serve untrusted media from an isolated origin without application cookies, or through a controlled response route. Set the actual `Content-Type` and `X-Content-Type-Options: nosniff`. For SVG, use a restrictive response CSP such as `sandbox; default-src 'none'`. Core's image validation is not SVG sanitization. Direct navigation to SVG has different restrictions from SVG displayed in `<img>`; never inline extracted SVG in trusted application markup. See [MDN SVG image restrictions](https://developer.mozilla.org/en-US/docs/Web/SVG/Guides/SVG_as_an_image).
+
+## Sessions, limits, and failure handling
+
+For an existing export session, pass image options to `exportMarkdownFrom()`:
+
+```ts
+const result = await exportMarkdownFrom(session, {
+  images: { maxTotalBytes: 128 * 1024 * 1024 },
+  signal,
+});
+```
+
+`exportMarkdownFrom` leaves the caller's session open. Returned bytes survive disposal. `exportMarkdownLayout` remains synchronous and text-only because detached layouts do not own image bytes.
+
+The default limit is 64 MiB of unique extracted bytes, including assets from omitted text-box stories. It is not a total parsing, layout, or transient-memory limit. `maxTotalBytes` must be a positive safe integer. A limit failure rejects the export before any resolver runs. It does not return partial Markdown. Raise the limit or use `images: false`.
+
+`MarkdownMediaError.code` is `media-limit`, `url-resolution-failed`, `invalid-image-url`, or `image-bytes-unavailable`. Limit errors include `limitBytes` and `actualBytes`, the total observed when the limit was exceeded. Resolver failures retain `cause` and the asset ID. Cancellation uses the existing `ExportResourceError` with code `aborted`; a resolver receives the signal and pending callback waits end promptly. Cancellation cannot interrupt synchronous parsing/layout or undo completed uploads.
+
+The resolver gets a separate byte copy. Mutations cannot corrupt returned assets. Result byte arrays are caller-owned; treat them as read-only to preserve their IDs. Metadata objects and collections are frozen.
+
+`MarkdownBundleError.code` is `invalid-media-path`, `duplicate-output-path`, `non-portable-image-url`, `output-not-empty`, `write-failed`, or `archive-failed`. Filesystem failures preserve the cause and relevant path. Helpers remove only files they created during a failed write.
+
+## Output limits
+
+Extraction covers validated ready images published by layout, including the body, headers, footers, tables, notes, separators, and nested text boxes. Hidden and revision-suppressed images are not published and are not extracted. Unsupported images, missing resources, external links, and shapes remain omitted with warnings; extraction never fetches document-linked external images. Existing conversion hooks can supply raster replacements for preserved TIFF, EMF, and WMF files.
+
+Inline and anchored images appear at their source paragraph positions, including table cells. Anchors within projected field results follow the field; display text cannot provide an exact source position. Decorative images have empty alternative text. Text-box content and note separators remain outside Markdown, although their image bytes and occurrences remain available. Unplaced anchors use an explicit `image-placement-fallback` warning. The logical document and affected page emit separate fallback warnings; page warnings include `pageNumber`. Cropping, rotation, and drawing effects are not reproduced.
+
+## Next steps
+
+- [Review export options and warnings](api.md).
+- [Configure your application runtime](integrations.md).

package/docs/integrations.md

@@ -0,0 +1,112 @@
+# Integrate DOCX to Markdown
+
+Before you begin, [install the converter and check the runtime requirements](../README.md#before-you-begin).
+Use `result.markdown` for text and `result.pages` for page citations. See [image delivery](images.md) for browser ZIP downloads, local folders, and server URLs with JSON metadata.
+
+## LangChain
+
+Install the packages, then create one LangChain document for each exported page:
+
+```sh
+npm install @docx-editor.dev/docx-to-markdown @docx-editor.dev/core @langchain/core
+```
+
+```ts
+import { readFile } from 'node:fs/promises';
+import { Document } from '@langchain/core/documents';
+import { exportMarkdown } from '@docx-editor.dev/docx-to-markdown';
+
+const filename = 'contract.docx';
+const docxBytes = await readFile(filename);
+const result = await exportMarkdown(docxBytes, { displayMode: 'proposed' });
+const documents = result.pages.map(
+  (page) =>
+    new Document({
+      pageContent: page.markdown,
+      metadata: { source: filename, page: page.number },
+    })
+);
+```
+
+Pass `documents` to your splitter or vector store. Preserve page metadata when splitting, and add a document version or content hash before storing citations. Review `result.warnings` for omitted content or incomplete fonts.
+
+## Other ingestion pipelines
+
+Use this converter for DOCX files in a MarkItDown, Docling, or Unstructured pipeline. Map each page to a text record with source and page metadata.
+
+```ts
+const records = result.pages.map((page) => ({
+  text: page.markdown,
+  metadata: { source: filename, page: page.number },
+}));
+```
+
+Map these fields to your pipeline's document schema. For Python applications, expose the Node.js converter through a service that returns JSON.
+
+## Next.js
+
+Keep the packages external so Node.js can load their bundled font and WebAssembly files. This configuration works with both Webpack and Turbopack.
+
+```js
+// next.config.mjs
+export default {
+  serverExternalPackages: [
+    '@docx-editor.dev/docx-to-markdown',
+    '@docx-editor.dev/core',
+    '@docx-editor.dev/fonts',
+  ],
+};
+```
+
+```ts
+// app/api/convert/route.ts
+import {
+  DocumentOpenError,
+  exportMarkdown,
+  toMarkdownJSON,
+} from '@docx-editor.dev/docx-to-markdown';
+
+export const runtime = 'nodejs';
+
+export async function POST(request: Request) {
+  try {
+    const result = await exportMarkdown(new Uint8Array(await request.arrayBuffer()), {
+      displayMode: 'proposed',
+      signal: request.signal,
+      resourceTimeoutMs: 15_000,
+    });
+    return Response.json(toMarkdownJSON(result));
+  } catch (error) {
+    if (error instanceof DocumentOpenError) {
+      return Response.json({ error: 'Document could not be opened' }, { status: 422 });
+    }
+    throw error;
+  }
+}
+```
+
+The example buffers the request. Apply authentication and upload limits before reading the body, and handle resource failures through your application's error handling. `toMarkdownJSON` excludes binary image bytes; if you enable images, deliver their assets separately or use a ZIP.
+
+With your development server running, send a local DOCX file and save the response:
+
+```sh
+curl --fail-with-body http://localhost:3000/api/convert \
+  -H 'Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document' \
+  --data-binary @contract.docx \
+  --output contract.json
+```
+
+For self-hosted standalone output, add `output: 'standalone'` to your Next.js configuration and retain the traced package assets. See [Next.js serverExternalPackages](https://nextjs.org/docs/app/api-reference/config/next-config-js/serverExternalPackages).
+
+## Serverless functions and worker threads
+
+Use a Node.js runtime that allows WebAssembly and includes the packages' font and WASM assets. The converter uses bundled fonts by default. See [font setup](fonts.md) to configure remote fallback or local custom fonts.
+
+`resourceTimeoutMs` limits resource waits, including font provisioning. It is not a deadline for the whole conversion. Parsing and layout run synchronously; `AbortSignal` cannot interrupt JavaScript that is already running. For a hard deadline, run conversion in a worker thread and terminate the worker on timeout. Limit upload size and concurrent conversions to fit your deployment's memory budget.
+
+Next.js Edge is unsupported. Validate the production bundle, font coverage, and page counts on your target platform before deployment.
+
+## Next steps
+
+- [Deliver image files and JSON metadata](images.md).
+- [Configure export options and handle errors](api.md).

package/package.json

@@ -1,24 +1,74 @@
 {
   "name": "@docx-editor.dev/docx-to-markdown",
-  "version": "0.0.1",
-  "description": "Convert DOCX to Markdown with layout-derived pages, headers, footers, comments, and tracked changes.",
-  "license": "Apache-2.0",
+  "version": "2.19.0",
+  "private": false,
   "publishConfig": {
     "access": "public"
   },
+  "description": "Convert DOCX to Markdown with layout-derived pages, headers, footers, comments, and tracked changes.",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": "^20.16.0 || >=22.3.0"
+  },
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./types/index.d.cts",
+        "default": "./dist/index.cjs"
+      },
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json",
+    "./node": {
+      "require": {
+        "types": "./types/node.d.cts",
+        "default": "./dist/node.cjs"
+      },
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js"
+    }
+  },
   "files": [
-    "README.md"
+    "dist",
+    "types",
+    "!dist/metafile-*.json",
+    "README.md",
+    "docs",
+    "THIRD_PARTY_NOTICES.md"
   ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "api:extract": "node ../../scripts/api-extractor.mjs --package @docx-editor.dev/docx-to-markdown --local",
+    "api:check": "node ../../scripts/api-extractor.mjs --package @docx-editor.dev/docx-to-markdown",
+    "check:consumer": "node ../../scripts/check-markdown-media-consumer.mjs"
+  },
+  "peerDependencies": {
+    "@docx-editor.dev/core": "~2.19.0"
+  },
+  "dependencies": {
+    "@docx-editor.dev/fonts": "~2.19.0",
+    "fflate": "^0.8.2"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.8.3",
+    "@docx-editor.dev/core": "workspace:*",
+    "micromark": "^4.0.2",
+    "micromark-extension-gfm": "^3.0.0",
+    "typescript": "^5.3.3"
+  },
   "keywords": [
     "docx",
     "markdown",
     "converter",
     "headless"
   ],
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/eigenpal/docx-editor.git",
     "directory": "packages/docx-to-markdown"
-  },
-  "homepage": "https://www.docx-editor.dev/docs/2.x/export/markdown"
+  }
 }

package/types/index.d.cts

@@ -0,0 +1,26 @@
+// CommonJS uses the same contracts as ESM. Explicit type-only import resolution
+// supports TypeScript's Node16 module mode with Core's shared ESM declarations.
+import type * as API from '../dist/index.js' with { 'resolution-mode': 'import' };
+export type * from '../dist/index.js' with { 'resolution-mode': 'import' };
+
+export declare const exportMarkdown: typeof API.exportMarkdown;
+export declare const exportMarkdownFrom: typeof API.exportMarkdownFrom;
+export declare const exportMarkdownLayout: typeof API.exportMarkdownLayout;
+export declare const openDocumentForExport: typeof API.openDocumentForExport;
+export declare const createFontSource: typeof API.createFontSource;
+export declare const defineFontResolver: typeof API.defineFontResolver;
+export declare const forEachSemanticDrawing: typeof API.forEachSemanticDrawing;
+export declare const HARD_MAX_AGGREGATE_FONT_BYTES: typeof API.HARD_MAX_AGGREGATE_FONT_BYTES;
+export declare const HARD_MAX_FONT_BYTES: typeof API.HARD_MAX_FONT_BYTES;
+export declare const HARD_MAX_FONT_SOURCES: typeof API.HARD_MAX_FONT_SOURCES;
+export declare const DocumentOpenError: typeof API.DocumentOpenError;
+export type DocumentOpenError = API.DocumentOpenError;
+export declare const ExportResourceError: typeof API.ExportResourceError;
+export type ExportResourceError = API.ExportResourceError;
+
+export declare const createMarkdownZip: typeof API.createMarkdownZip;
+export declare const toMarkdownJSON: typeof API.toMarkdownJSON;
+export declare const MarkdownMediaError: typeof API.MarkdownMediaError;
+export type MarkdownMediaError = API.MarkdownMediaError;
+export declare const MarkdownBundleError: typeof API.MarkdownBundleError;
+export type MarkdownBundleError = API.MarkdownBundleError;

package/types/node.d.cts

@@ -0,0 +1,3 @@
+import type * as API from '../dist/node.js' with { 'resolution-mode': 'import' };
+export type * from '../dist/node.js' with { 'resolution-mode': 'import' };
+export declare const writeMarkdownBundle: typeof API.writeMarkdownBundle;