@docx-editor.dev/docx-to-pdf 0.0.1 → 2.23.0

package/docs/api.md

@@ -0,0 +1,127 @@
+# PDF export API
+
+Import conversion functions, error classes, font helpers, and result types from `@docx-editor.dev/docx-to-pdf`.
+
+## Convert a document
+
+`exportPdf(source, options?)` returns `Promise<PdfExportResult>`. Pass DOCX bytes as a `Uint8Array` or Node.js `Buffer`. Read files before conversion; the function does not accept paths, URLs, streams, or live editor views. The function preserves the source and releases its document session after success or failure.
+
+Use Node.js 20.16.0 or later in the 20.x release line, or Node.js 22.3.0 or later. The converter needs WebAssembly and access to its packaged font files. Browser and Edge runtimes are not supported.
+
+## Reusable sessions
+
+`openDocumentForExport(source, options?)` returns `Promise<OpenPdfDocumentForExportResult>`. It accepts immutable DOCX bytes and font/layout options. Its result has the same success/refusal shape as Markdown's open function. On success, `result.session` provides the font-backed capabilities required by PDF output. On refusal, inspect `reason` and optional `detail`. Font policy and resource failures still throw typed errors.
+
+`exportPdfFrom(session, options?)` returns `Promise<PdfExportResult>` without reopening the document. It accepts `PdfProjectionOptions`: `comments`, `fidelityPolicy`, `displayMode`, `timeoutMs`, `maxPages`, `maxOutputBytes`, and `signal`. Omit `displayMode` to use the session's default projection. An explicit mode uses the session's cached `layoutFor(mode)` projection. Result `timings.openMs` is `0` because this call does not open the document.
+
+Use `OpenPdfDocumentForExportOptions` for font and layout settings when opening. Use `PdfExportSession` when you need to name the session type. An ordinary Core session with approximate measurement cannot produce PDF output. `exportPdfFrom` rejects a session that lacks admitted fonts and glyph capabilities.
+
+The caller owns the session and must call `dispose()` in `finally`. An export failure, projection cancellation, or projection deadline does not dispose a caller-owned session. The signal supplied when opening controls shared resource work and the session lifetime. A signal supplied to `exportPdfFrom` stops only that export's wait and encoding work. Shared resource work can continue until settlement, its resource deadline, or session disposal. After disposal, later exports reject with `ExportResourceError` and `code: 'disposed'`.
+
+For both formats from one layout, see [Compare PDF and Markdown conversion](markdown-contract.md#reuse-one-session).
+
+## Options
+
+| Option | Default | Behavior |
+| --- | --- | --- |
+| `fidelityPolicy` | `'strict'` | Reject unsupported or approximate PDF content. `'best-effort'` returns available output with diagnostics. |
+| `displayMode` | `'proposed'` | Choose `'proposed'`, `'original'`, or `'all-markup'` for tracked changes. |
+| `comments` | `true` | Include native PDF annotations. |
+| `useSystemFonts` | `true` | Search supported installed font files. Disable for consistent font selection across hosts. |
+| `fonts` | — | Resolve these font sources before installed and packaged sources. |
+| `fallbackFonts` | — | Resolve missing faces after packaged substitutes. |
+| `lastResortFonts` | — | Resolve missing faces after embedded fonts and before generic substitutes. |
+| `fontPolicy` | `'best-effort'` | `'strict'` rejects failed sources or incomplete face coverage. Substitutes can satisfy coverage. |
+| `onFontResolution` | — | Receive font evidence before a strict font refusal. Callback promises do not delay export. |
+| `glyphFallbacks` | Packaged fallback list | Ordered faces for missing glyphs; at most 16 entries. |
+| `documentLigatures` | `true` | Apply optional document ligatures during measurement and PDF output. |
+| `timeoutMs` | `60000` | Cooperative conversion deadline. Integer from `1` to `2147483647`. |
+| `fontResolutionTimeoutMs` | `resourceTimeoutMs`, then `60000` | Font resolution deadline in milliseconds. |
+| `resourceTimeoutMs` | `60000` | Resource and layout deadline in milliseconds. |
+| `signal` | — | Cancel through an `AbortSignal`. |
+| `maxPages` | `10000` | Maximum pages; integer from `1` to `10000`. Checked after layout, before PDF painting. |
+| `maxOutputBytes` | `67108864` | Maximum encoded bytes; integer from `1` to `67108864`. Checked after encoding. |
+| `imageDecodePort` | Bounded built-in decoder | Supply image metadata through Core's decoder interface. |
+| `convertPreservedImage` | — | Convert a preserved image format through Core's converter interface. |
+
+Resource and font deadlines must be positive, finite numbers no greater than `2147483647`. The conversion deadline also applies during those phases. `measurer`, `producer`, and `reuseAcrossRevisions` are unsupported and cause `TypeError`. PDF conversion requires the fonts used during layout to encode the positioned glyphs.
+
+See [Configure PDF fonts](fonts.md) for font sources and policy details.
+
+## Result
+
+| Field | Meaning |
+| --- | --- |
+| `bytes` | PDF bytes owned by this result. Save them or send them with `Content-Type: application/pdf`. |
+| `pageCount` | Number of physical PDF pages. |
+| `layoutRevision` | Revision of this conversion's layout. This value is not a document identifier. |
+| `displayMode` | Applied revision display mode. |
+| `fontResolution` | Requested families, resolved faces, substitutions, and source failures. |
+| `diagnostics` | Immutable list of output limitations and informational notices. |
+| `timings` | `openMs`, `layoutMs`, `paintMs`, and `saveMs`, measured in milliseconds. |
+
+The result object and timing fields are immutable. The byte array remains mutable; changing it does not change later exports. Store the input hash, package versions, font configuration, and display mode when you need reproducible exports.
+
+## Diagnostics
+
+Each `PdfDiagnostic` includes `code`, `message`, and `severity`. Page diagnostics include zero-based `pageIndex` and one-based `pageNumber`. Use `pageNumber` for display, as with Markdown warnings. An absent page field means the diagnostic applies to the document or has no specific page.
+
+| Severity        | Strict output | Meaning                                                       |
+| --------------- | ------------- | ------------------------------------------------------------- |
+| `information`   | Allowed       | Inspect the report; this notice alone does not reject output. |
+| `approximation` | Rejected      | Output changes the requested presentation.                    |
+| `unsupported`   | Rejected      | The writer cannot reproduce the content.                      |
+
+Each `font-origin-failed` diagnostic identifies one failed source through `originIndex`, optional `originName`, and a guarded cause message. It appears even when another source supplies the font. `incomplete-font` identifies incomplete coverage or substituted face variants within a family. It has `information` severity; `fontPolicy: 'strict'` independently rejects the font failure. `font-substitution` reports generic substitutes that can change pagination. Other codes identify limitations such as `equation-fallback`, `image-clip`, or `core-*` source omissions. Handle unknown diagnostic codes by severity; the set can grow. Use messages for display, not program control.
+
+## Errors
+
+| Error | Stable `code` | Useful fields |
+| --- | --- | --- |
+| `PdfDocumentOpenError` | `documentOpenFailed` | Typed `reason` and optional `detail`. |
+| `PdfFidelityError` | `fidelityUnsupported` | `diagnostics` for the refused output. |
+| `PdfPageLimitError` | `pageLimitExceeded` | `limit` and `actual` page counts. Extends `RangeError`. |
+| `PdfOutputLimitError` | `outputTooLarge` | `limit` and `actual` byte counts. Extends `PdfEncodingError`. |
+| `PdfWorkLimitError` | `workLimitExceeded` | Content, operation, or diagnostic budget exceeded. |
+| `PdfEncodingError` | `encodingFailed` | Optional underlying `cause`. |
+| `ExportResourceError` | Core resource code | Optional underlying `cause`. |
+| `TypeError`, `RangeError` | — | Invalid arguments or other internal size limits. |
+
+PDF failure codes use Core's camelCase convention. Content diagnostic codes use kebab-case, as Markdown warnings do. Limit errors retain their previous base classes so existing `RangeError` and `PdfEncodingError` handlers still catch them.
+
+Core resource codes include `aborted`, `timedOut`, `nonConvergent`, `disposed`, `layoutInvariant`, and `layoutFailed`. A strict font refusal uses `ExportResourceError` with `code: 'layoutFailed'`. Use `onFontResolution` to retain its font evidence.
+
+Handle expected refusals and rethrow unexpected failures:
+
+```ts
+import {
+  exportPdf,
+  PdfDocumentOpenError,
+  PdfFidelityError,
+  PdfOutputLimitError,
+  PdfPageLimitError,
+} from '@docx-editor.dev/docx-to-pdf';
+
+try {
+  const result = await exportPdf(docxBytes, { maxPages: 100 });
+  await savePdf(result.bytes);
+} catch (error) {
+  if (error instanceof PdfFidelityError) {
+    console.table(error.diagnostics);
+  } else if (error instanceof PdfDocumentOpenError) {
+    console.error(error.code, error.reason);
+  } else if (error instanceof PdfPageLimitError || error instanceof PdfOutputLimitError) {
+    console.error(error.code, error.actual, error.limit);
+  } else {
+    throw error;
+  }
+}
+```
+
+Here, `docxBytes` contains the input and `savePdf` is your storage function. Choose best-effort output explicitly after reviewing your application's fidelity requirements. Do not automatically retry a strict refusal with weaker settings.
+
+## Resource boundaries
+
+The writer limits operations to `2000000`, diagnostics to `10000`, and uncompressed content to `67108864` bytes. Core also bounds DOCX parsing, fonts, images, and layout. `maxPages` and `maxOutputBytes` do not impose a process memory limit. They check completed layout and completed encoding, respectively.
+
+Cancellation checks occur between batches. Synchronous parsing, font work, and image work cannot stop during a call. For hard deadlines, terminate a worker after your deadline. For memory isolation, configure the worker's `resourceLimits.maxOldGenerationSizeMb`. Bound concurrent conversions; each active document retains layout and font data.

package/docs/fonts.md

@@ -0,0 +1,151 @@
+# Configure PDF fonts
+
+Fonts determine line breaks, page counts, and the glyphs embedded in PDF output. The converter uses installed fonts and packaged substitutes by default.
+
+## Choose a source
+
+| Need | Configuration |
+| --- | --- |
+| Use default font sources | Omit font options. |
+| Keep font selection consistent across hosts | Set `useSystemFonts: false` and pin package versions. |
+| Override an installed or packaged face | Supply `fonts`. |
+| Supply faces absent from packaged sources | Supply `fallbackFonts`. |
+| Keep embedded faces before your final fallback | Supply `lastResortFonts`. |
+
+Sources resolve in this order:
+
+1. Your `fonts` sources.
+2. Installed fonts, unless `useSystemFonts` is `false`.
+3. Packaged substitutes.
+4. Your `fallbackFonts` sources.
+5. Supplemental packaged faces, including `@docx-editor.dev/fonts-cjk` when it is installed.
+6. Document-embedded fonts.
+7. Your `lastResortFonts` sources.
+8. Generic substitutes for unresolved families.
+
+Earlier sources take priority. Each option accepts one source or an ordered array of sources. Use `defineFontResolver` for a resolver that reads the document's requested families. The `PdfFontOrigin` and `PdfFontsSource` types describe these inputs.
+
+The default sources need no network access. A resolver that you supply can make network requests.
+
+## Add Chinese, Japanese, and Korean text
+
+The converter package does not include a Chinese, Japanese, or Korean (CJK) font. If your server has no suitable font, install the optional package:
+
+```sh
+npm install @docx-editor.dev/fonts-cjk
+```
+
+The converter declares this package as an optional peer dependency. Install a version that satisfies its peer dependency range. The converter finds the package at runtime and needs no configuration. Its Noto Sans CJK JP font supplies CJK characters that earlier sources do not cover. It also substitutes for unavailable families such as SimSun, MS Mincho, and Malgun Gothic.
+
+If you previously relied on bundled CJK coverage, add this package to your production dependencies. Keep the package external to your server bundle. Retain its `dist/` and `assets/` directories in their package locations. Include its license files when distributing the package.
+
+You can omit the package when installed fonts or your supplied fonts cover every required character. An installed package with missing or unreadable assets reports `font-origin-failed`. Inspect `result.fontResolution.originFailures` for the cause.
+
+When `useSystemFonts` is `true`, suitable installed fonts take priority. Setting `useSystemFonts: false` still permits the optional package and fonts that you supply.
+
+If no source covers a CJK character, export reports `missing-glyph`, and strict export fails. When the optional package is absent, the diagnostic names it. An unavailable CJK family uses a generic substitute and reports `font-substitution`.
+
+### CJK package API
+
+`@docx-editor.dev/fonts-cjk` runs on Node.js `^20.16.0 || >=22.3.0`. It exports the font family and its local file URL:
+
+| Export | Type | Value |
+| --- | --- | --- |
+| `NOTO_SANS_CJK_JP_FAMILY` | String literal | `'Noto Sans CJK JP'` |
+| `NOTO_SANS_CJK_JP_URL` | `URL` | A `file:` URL for `assets/NotoSansCJKjp-Regular.otf`. |
+
+Use the URL to read the font directly:
+
+```ts
+import { readFile } from 'node:fs/promises';
+import {
+  NOTO_SANS_CJK_JP_FAMILY,
+  NOTO_SANS_CJK_JP_URL,
+} from '@docx-editor.dev/fonts-cjk';
+
+const fontBytes = new Uint8Array(await readFile(NOTO_SANS_CJK_JP_URL));
+console.log(NOTO_SANS_CJK_JP_FAMILY, fontBytes.byteLength);
+```
+
+Automatic PDF fallback needs no direct import. If you supply `glyphFallbacks`, your list replaces the defaults. For this fallback, add an entry with `family: NOTO_SANS_CJK_JP_FAMILY`, `weight: 400`, and `style: 'normal'`.
+
+### CJK font coverage and licensing
+
+The package supplies Noto Sans CJK JP Regular as an OpenType font with CFF outlines. It contains one weight (`400`) and one style (`'normal'`). PDF export can synthesize bold and italic from the regular face.
+
+The package contains the Japanese regional face, without separate Chinese or Korean regional faces. Substitution can change glyph forms, line breaks, and page counts. Supply your own font through `fonts` when you need a specific regional face or designed style.
+
+The package reads its font from disk without network access. It does not bundle the font into JavaScript or install a browser font.
+
+The package code uses the Apache License 2.0. The font uses the SIL Open Font License, Version 1.1. The PDF converter uses the separate EigenPal Pro License.
+
+## Export Arabic and Hebrew text
+
+Default fallback fonts cover Arabic and Hebrew. Arabic fallback selection requires a font with Arabic shaping support. Arabic joining continues across formatting runs, including changes in text color. The PDF text layer preserves logical word order for Arabic, Persian, and Hebrew text extraction.
+
+When a selected face lacks bold or italic variants, the writer can draw synthetic styles. It preserves text extraction and glyph positions. To use your own designed variants, supply separate regular, bold, italic, and bold-italic font files.
+
+## Supply a font file
+
+Use `createFontSource` from the converter package to validate your font bytes. This example expects your licensed regular font file and a document that requests `Application Sans`:
+
+```ts
+import { readFile, writeFile } from 'node:fs/promises';
+import { createFontSource, exportPdf } from '@docx-editor.dev/docx-to-pdf';
+
+const fontBytes = new Uint8Array(await readFile('ApplicationSans.ttf'));
+const admitted = createFontSource(fontBytes, {
+  family: 'Application Sans',
+  weight: 400,
+  style: 'normal',
+});
+if ('failure' in admitted) {
+  throw new Error(admitted.failure.diagnostic ?? admitted.failure.reason);
+}
+
+const source = await readFile('document.docx');
+const result = await exportPdf(source, {
+  useSystemFonts: false,
+  fonts: { sources: [admitted.source] },
+});
+await writeFile('document.pdf', result.bytes);
+```
+
+Register bold, italic, and bold-italic files separately when the document needs those faces. Use weights `400` and `700`, with styles `'normal'` and `'italic'`. Check your font license before embedding its bytes. The writer rejects prohibited embedding, prohibited subsetting, variable fonts, and unsupported font containers.
+
+## Separate font policy from PDF policy
+
+`fontPolicy: 'strict'` rejects failed sources and incomplete face coverage. It can reject an export when another source recovers from a source failure. Complete coverage can include substitutions; it does not prove original font selection.
+
+`fidelityPolicy: 'strict'` rejects unsupported or approximate PDF output. It permits the packaged metric substitutes but rejects generic substitutions that can change page breaks. It does not automatically enable strict font policy.
+
+To require both checks, set both policies:
+
+```ts
+const result = await exportPdf(source, {
+  fontPolicy: 'strict',
+  fidelityPolicy: 'strict',
+  useSystemFonts: false,
+  onFontResolution(report) {
+    console.table(report.families);
+  },
+});
+```
+
+The callback runs before a strict font refusal. Returned callback promises do not delay conversion.
+
+## Inspect font evidence
+
+`result.fontResolution.families` records each family's coverage and selected faces. Inspect each face's `sourceFamily`, `via`, and `substitution` fields. `originFailures` retains source failures and their causes. `droppedEmbeddedFonts` identifies embedded faces rejected during font admission.
+
+Each `font-origin-failed` diagnostic provides the source index, optional source name, and a guarded cause message. The `incomplete-font` diagnostic reports partial coverage and substituted variants within a family. It remains informational when `fontPolicy` permits recovery.
+
+| Symptom | Action |
+| --- | --- |
+| Pages differ across hosts | Disable system fonts and use identical font bytes and package versions. |
+| `font-substitution` diagnostic | Supply the requested family through `fonts` or review best-effort output. |
+| Strict font policy rejects conversion | Inspect the callback report for failed sources and missing face variants. |
+| Missing font assets after bundling | Keep converter packages external and copy their assets with deployment output. |
+| Missing glyphs | Supply a face that contains the requested characters. For CJK text, install `@docx-editor.dev/fonts-cjk`. |
+
+For server setup, see [Integrate PDF conversion](integrations.md).

package/docs/integrations.md

@@ -0,0 +1,107 @@
+# Integrate PDF conversion
+
+The converter runs on Node.js and returns PDF bytes. Keep conversion on the server for browser applications. The package uses the EigenPal Pro License. Install the converter and its engine peer before using these examples:
+
+```sh
+npm install @docx-editor.dev/docx-to-pdf @docx-editor.dev/core
+```
+
+## Return a PDF response
+
+A Node.js route can return the bytes in a web `Response`. This handler accepts raw DOCX bytes, not multipart form data:
+
+```ts
+import {
+  exportPdf,
+  ExportResourceError,
+  PdfDocumentOpenError,
+  PdfFidelityError,
+  PdfOutputLimitError,
+  PdfPageLimitError,
+} from '@docx-editor.dev/docx-to-pdf';
+
+export async function POST(request: Request): Promise<Response> {
+  try {
+    const source = new Uint8Array(await request.arrayBuffer());
+    const result = await exportPdf(source, {
+      signal: request.signal,
+      timeoutMs: 30_000,
+      maxPages: 100,
+      maxOutputBytes: 16 * 1024 * 1024,
+      useSystemFonts: false,
+    });
+    return new Response(new Uint8Array(result.bytes), {
+      headers: {
+        'Content-Type': 'application/pdf',
+        'Content-Disposition': 'attachment; filename="document.pdf"',
+        'Cache-Control': 'no-store',
+      },
+    });
+  } catch (error) {
+    if (error instanceof PdfDocumentOpenError) {
+      return Response.json({ error: error.code }, { status: 422 });
+    }
+    if (error instanceof PdfFidelityError) {
+      return Response.json({ error: error.code }, { status: 422 });
+    }
+    if (error instanceof PdfPageLimitError || error instanceof PdfOutputLimitError) {
+      return Response.json({ error: error.code }, { status: 413 });
+    }
+    if (error instanceof ExportResourceError && error.code === 'timedOut') {
+      return Response.json({ error: error.code }, { status: 504 });
+    }
+    throw error;
+  }
+}
+```
+
+Configure your server's request size limit before `request.arrayBuffer()` reads the body. The output byte limit does not limit uploaded bytes. Set a concurrency limit appropriate for your available memory.
+
+## Next.js
+
+Use `export const runtime = 'nodejs'` in the route file. Place the handler in `app/api/convert/route.ts`.
+
+Keep packages external so Node.js resolves their font and WebAssembly assets:
+
+```js
+// next.config.mjs
+export default {
+  serverExternalPackages: [
+    '@docx-editor.dev/docx-to-pdf',
+    '@docx-editor.dev/core',
+    '@docx-editor.dev/fonts',
+    '@docx-editor.dev/fonts-cjk',
+  ],
+};
+```
+
+For a standalone deployment, include the `assets/` directories from the converter and `@docx-editor.dev/fonts`. If you install `@docx-editor.dev/fonts-cjk`, include its `assets/` directory too. Keep the package directory structure intact. Test the deployment artifact with a real conversion before release.
+
+## Convert a batch
+
+Process a batch sequentially when memory use matters more than throughput:
+
+```ts
+import { readFile, writeFile } from 'node:fs/promises';
+import { exportPdf } from '@docx-editor.dev/docx-to-pdf';
+
+for (const name of ['first', 'second']) {
+  const source = await readFile(`${name}.docx`);
+  const result = await exportPdf(source, { useSystemFonts: false });
+  await writeFile(`${name}.pdf`, result.bytes);
+}
+```
+
+The exporter disposes its document session after each call, including failed calls. For repeated exports or both formats from one layout, use [a reusable PDF session](markdown-contract.md#reuse-one-session).
+
+## Runtime checks
+
+From this repository, validate packed Node.js consumers with:
+
+```sh
+bun run build:pdf
+bun run --filter '@docx-editor.dev/docx-to-markdown' build
+bun run --filter '@docx-editor.dev/docx-to-pdf' check:consumer
+```
+
+The check installs local tarballs in a temporary directory outside the workspace. It compiles TypeScript consumers and runs conversion through the built package. This check needs registry access for external dependencies.

package/docs/markdown-contract.md

@@ -0,0 +1,111 @@
+# Compare PDF and Markdown conversion
+
+Use `exportPdf(source, options)` and `exportMarkdown(source, options)` for one-shot conversion. Both functions accept DOCX bytes, preserve the source, and dispose their document session after success or failure. PDF and Markdown share font-source types, font helpers, font reports, and resource-error codes.
+
+## Share conversion settings
+
+Set `displayMode` explicitly when your application produces both formats. Markdown defaults to `'all-markup'`; PDF defaults to `'proposed'`. Without an explicit setting, the outputs can contain different text.
+
+Share your font sources and disable PDF system-font discovery for consistent font selection across hosts. Use `documentLigatures: false` on PDF to align with Markdown's default shaping policy. PDF otherwise honors optional document ligatures by default.
+
+This function uses the same input and common settings for both formats:
+
+```ts
+import { exportMarkdown, type MarkdownExportOptions } from '@docx-editor.dev/docx-to-markdown';
+import {
+  exportPdf,
+  type PdfExportOptions,
+  type PdfFontsSource,
+} from '@docx-editor.dev/docx-to-pdf';
+
+export async function convertBoth(source: Uint8Array, fonts: PdfFontsSource, signal?: AbortSignal) {
+  const common = {
+    displayMode: 'proposed',
+    fonts,
+    fontPolicy: 'best-effort',
+    resourceTimeoutMs: 15_000,
+    signal,
+  } satisfies MarkdownExportOptions & PdfExportOptions;
+
+  const markdown = await exportMarkdown(source, common);
+  const pdf = await exportPdf(source, {
+    ...common,
+    useSystemFonts: false,
+    documentLigatures: false,
+  });
+  return { markdown, pdf };
+}
+```
+
+Both packages export the same `createFontSource` and `defineFontResolver` helpers. For font registration, see [Configure PDF fonts](fonts.md). These settings align common controls; they do not guarantee identical pagination for every document. Missing glyphs, fallback faces, and unsupported features can still affect output.
+
+## Shared controls
+
+| Member | Shared meaning |
+| --- | --- |
+| `fonts` | Caller sources take priority over packaged substitutes. |
+| `fallbackFonts` | Supply faces absent from earlier sources. |
+| `fontPolicy` | Strict mode rejects failed origins and incomplete face coverage. |
+| `onFontResolution` | Receive font evidence before a strict font refusal. |
+| `displayMode` | Select proposed content, original content, or all markup. |
+| `signal` | Cancel resource waits and subsequent work. |
+| `resourceTimeoutMs` | Bound resource and layout work. |
+| `fontResolution` | Inspect requested families, selected faces, substitutions, and failed sources. |
+| `ExportResourceError` | Handle shared codes such as `aborted` and `timedOut`. |
+
+Strict font policy checks coverage and source failures. It does not prove that the selected faces are the document author's fonts.
+
+## Intentional differences
+
+| Area | Markdown | PDF |
+| --- | --- | --- |
+| Source | DOCX bytes or supported live views | DOCX bytes only |
+| Primary output | `result.markdown` | `result.bytes` |
+| Page data | `result.pages` | `result.pageCount` |
+| Page metadata | `result.pagination.layoutRevision` and `.displayMode` | `result.layoutRevision` and `.displayMode` |
+| Content notices | `result.warnings` | `result.diagnostics`, including severity |
+| Notice page location | Optional one-based `pageNumber` | Optional one-based `pageNumber`, plus zero-based `pageIndex` |
+| Open refusal | `DocumentOpenError` | `PdfDocumentOpenError` |
+| Default revisions | `'all-markup'` | `'proposed'` |
+| Default font discovery | Packaged and embedded sources | Installed, packaged, and embedded sources |
+| Optional ligatures | Disabled | Enabled unless `documentLigatures` is `false` |
+| Unsupported content | Warnings for omissions | Strict refusal by default; optional best-effort output |
+| Comments | Structured review data | Native PDF annotations, unless `comments` is `false` |
+| Reuse | Public export sessions and detached layouts | Public font-backed export sessions |
+| Result delivery | Markdown text, JSON projection, or media bundles | PDF bytes for storage or an HTTP response |
+
+PDF also exposes encoding limits, `fidelityPolicy`, and a whole-conversion `timeoutMs`. It needs the admitted font bytes that produced the layout to encode searchable text. It accepts font-backed sessions and rejects arbitrary sessions or detached layouts.
+
+Handle notices using each format's public fields. Do not treat a PDF `pageIndex` as a Markdown `pageNumber` without adding one. Store the input version with page references; layout revisions are not persistent document identifiers.
+
+## Reuse one session
+
+Open through PDF when you need both formats from one font-backed layout. Markdown-opened sessions use different font and ligature settings. PDF accepts these sessions, but strict conversion can refuse missing font identities or unshaped text.
+
+This example uses the PDF opener for both outputs:
+
+```ts
+import { readFile } from 'node:fs/promises';
+import { openDocumentForExport, exportPdfFrom } from '@docx-editor.dev/docx-to-pdf';
+import { exportMarkdownFrom } from '@docx-editor.dev/docx-to-markdown';
+
+const opened = await openDocumentForExport(await readFile('document.docx'), {
+  displayMode: 'proposed',
+  useSystemFonts: false,
+});
+if (!opened.ok) throw new Error(opened.reason);
+
+try {
+  const markdown = await exportMarkdownFrom(opened.session);
+  const pdf = await exportPdfFrom(opened.session);
+  console.log(markdown.pages.length, pdf.pageCount);
+} finally {
+  opened.session.dispose();
+}
+```
+
+Both exporters consume the same cached layout and font evidence. `exportPdfFrom` also accepts `displayMode` to encode another cached revision projection. The default session mode does not change when you request another projection. This workflow retains PDF's font and shaping policy for both outputs.
+
+## Contract verification
+
+`test/markdown-contract.test.ts` converts a synthetic revision document through both exporters. It checks visible text, selected font identity, page metadata, and cancellation with common options. The PDF consumer check compiles packed ESM and CommonJS consumers outside the workspace.

package/licenses/NotoEmoji-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2013 Google LLC
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.