@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/types/modules/archive/fs/archive-file.d.ts

@@ -234,15 +234,18 @@ export declare class ArchiveFile<F extends ArchiveFormat = "zip"> {
      * archive.addFile("large-file.bin");
      * archive.addDirectory("./data");
      *
-     * // Stream to a file
+     * // Recommended: pipeTo() handles backpressure end-to-end.
+     * await archive.pipeTo(createWriteStream("output.zip"));
+     *
+     * // Or stream manually — REMEMBER to honor backpressure on the sink:
+     * import { once } from "node:events";
      * const writeStream = createWriteStream("output.zip");
      * for await (const chunk of archive.stream()) {
-     *   writeStream.write(chunk);
+     *   if (!writeStream.write(chunk)) {
+     *     await once(writeStream, "drain");
+     *   }
      * }
      * writeStream.end();
-     *
-     * // Or use pipeTo() for simpler file output
-     * await archive.pipeTo(createWriteStream("output.zip"));
      * ```
      */
     stream(options?: ArchiveStreamOptions): AsyncIterable<Uint8Array>;

package/dist/types/modules/excel/chart/chart-ex-types.d.ts

@@ -89,18 +89,6 @@ export interface ChartExSpace {
     extLst?: string;
 }
 export interface ChartExData {
-    /**
-     * @deprecated Moved to {@link ChartExSpace.externalData} to match
-     * the Chart2014 schema (`cx:externalData` is a child of
-     * `cx:chartSpace`, not `cx:chartData`). The parser migrates legacy
-     * on-disk placements into `ChartExSpace.externalData`; this field
-     * remains on the type only to avoid breaking callers that read it
-     * directly. Write-side code no longer consults this slot.
-     */
-    externalData?: Array<{
-        id: string;
-        autoUpdate?: boolean;
-    }>;
     /** Chart data (numeric/string arrays referenced by series) */
     data: ChartExDataEntry[];
 }

package/dist/types/modules/excel/chart/chart.d.ts

@@ -129,7 +129,7 @@ interface ChartAnchorRange {
  *   `toPNG`, `unknownElements`) work uniformly. ChartTypeGroup-level
  *   APIs (`chartTypes`, `axes`, `plotArea`, `getAxis`, `categoryAxis`,
  *   `valueAxis`, `addSeries`, `removeSeries`, `getSeries`,
- *   `updateSeries`, `addSeriesFromOptions`, `seriesCount`, `mutate`,
+ *   `updateSeries`, `addSeriesFromOptions`, `getSeriesCount`, `mutate`,
  *   `setStyle`) are classic-only — ChartEx has its own topology that
  *   doesn't map cleanly onto the classic group/series abstraction;
  *   use {@link Chart.mutateChartEx} for ChartEx mutations.
@@ -393,10 +393,6 @@ declare class Chart {
      * @param groupIndex - 0-based index of the chart type group (defaults to 0).
      */
     getSeriesCount(groupIndex?: number): number;
-    /**
-     * @deprecated Use `getSeriesCount()` instead. Returns the count of series in the first chart type group.
-     */
-    get seriesCount(): number;
     /**
      * Create a deep copy of this chart and add it to a target worksheet.
      * The new chart receives a fresh chartNumber; the original is untouched.

package/dist/types/modules/excel/chart/types.d.ts

@@ -1501,12 +1501,6 @@ export interface PivotFormat {
      * label styling without dropping into raw XML.
      */
     dLbl?: DataLabelEntry;
-    /**
-     * @deprecated Use {@link dLbl} for structured access. Retained so
-     * files parsed before the structured slot landed continue to
-     * round-trip. Writers prefer `dLbl` when both are present.
-     */
-    rawDLbl?: string;
     /** Extension list (raw XML for round-trip). */
     extLst?: string;
 }

package/dist/types/modules/excel/stream/workbook-writer.browser.d.ts

@@ -67,6 +67,7 @@ interface OutputStreamLike {
     end(): void;
     once(eventName: string | symbol, listener: (...args: any[]) => void): this;
     removeListener(eventName: string | symbol, listener: (...args: any[]) => void): this;
+    on?(eventName: string | symbol, listener: (...args: any[]) => void): this;
 }
 export interface WorksheetWriterLike {
     id: number;
@@ -130,11 +131,50 @@ export declare abstract class WorkbookWriterBase<TWorksheetWriter extends Worksh
     promise: Promise<void[] | void>;
     protected _trueStreaming: boolean;
     protected WorksheetWriterClass: WorksheetWriterConstructor<TWorksheetWriter>;
+    private _needsDrain;
+    private _drainResolvers;
+    private _drainListenerAttached;
+    private _sinkError;
     constructor(options: WorkbookWriterOptions, WorksheetWriterClass: WorksheetWriterConstructor<TWorksheetWriter>);
     /**
      * Create output stream - can be overridden by Node.js to support filename
      */
     protected _createOutputStream(options: WorkbookWriterOptions): OutputStreamLike;
+    /**
+     * Internal: record whether the sink accepted the last write. The
+     * `OutputStreamLike.write` type advertises `boolean | Promise<boolean>`
+     * for forward compatibility, but in practice every concrete sink we
+     * accept (Node `Writable`, browser `Writable` from `@stream`, internal
+     * `StreamBuf`, fs.WriteStream, etc) returns a sync `boolean`. We
+     * defensively handle the Promise shape but it's never exercised.
+     */
+    private _trackBackpressure;
+    private _ensureDrainListener;
+    /**
+     * Attach error/close listeners on the user sink so any parked backpressure
+     * waiters are released the moment the sink fails. Without this, a
+     * `commit()` parked on `_waitForUserSinkDrain()` would hang forever if
+     * the sink errored before emitting 'drain'. Idempotent and a no-op for
+     * sinks that don't expose `.on` (e.g. internal `StreamBuf`).
+     *
+     * Uses a non-consuming listener: if the user has their own 'error' handler
+     * it still fires (EventEmitter broadcasts to all listeners). The error is
+     * also captured into `_sinkError` so `_finalize()` can replay it — `_finalize`
+     * registers its own listener with `once()`, which would miss errors that
+     * arrived earlier in the commit pipeline.
+     */
+    private _lifecycleListenersAttached;
+    private _attachSinkLifecycleListeners;
+    private _wakeAllBackpressureWaiters;
+    /**
+     * Park here until any async writes have settled and the user sink has
+     * drained below its high-water mark. Resolves immediately when no
+     * backpressure is in flight.
+     *
+     * Called at async boundaries inside `commit()` so a slow sink throttles
+     * the producer instead of letting bytes accumulate unboundedly.
+     */
+    private _waitForUserSinkDrain;
     get definedNames(): DefinedNames;
     /**
      * The default font for the workbook (fontId=0 / "Normal" style).

package/dist/types/modules/excel/utils/string-buf.d.ts

@@ -1,29 +1,8 @@
 /**
- * StringBuf - Cross-Platform String Buffer
+ * Re-export of the shared {@link StringBuf} from `@utils/string-buf`.
  *
- * A way to keep string memory operations to a minimum while building XML strings.
- * Uses TextEncoder and Uint8Array for cross-platform compatibility (Node.js + Browser).
+ * Kept as a thin alias so existing imports (`@excel/utils/string-buf`)
+ * continue to work without churn.
  */
-interface StringBufOptions {
-    size?: number;
-    encoding?: string;
-}
-/**
- * StringBuf - efficient string builder using Uint8Array
- * Works identically in Node.js and Browser environments.
- */
-declare class StringBuf {
-    private _buf;
-    private _inPos;
-    private _buffer;
-    constructor(options?: StringBufOptions);
-    get length(): number;
-    get capacity(): number;
-    get buffer(): Uint8Array;
-    toBuffer(): Uint8Array;
-    reset(position?: number): void;
-    private _grow;
-    addText(text: string): void;
-    addStringBuf(inBuf: StringBuf): void;
-}
-export { StringBuf };
+export { StringBuf } from "../../../utils/string-buf.js";
+export type { StringBufOptions } from "../../../utils/string-buf.js";

package/dist/types/modules/excel/xlsx/xlsx.browser.d.ts

@@ -200,9 +200,19 @@ interface ZipEntryLike {
 /**
  * XLSX class - handles Excel file operations
  * Works in both Node.js and Browser environments
+ *
+ * Generic over the concrete `Workbook` type so a Node subclass that extends
+ * `XLSX<NodeWorkbook>` automatically narrows `load()` / `read()` /
+ * `loadFromFiles()` / etc. to return the Node `Workbook` (which exposes
+ * `xlsx.readFile` / `xlsx.writeFile`). Without this, those methods are
+ * inherited unchanged and surface the browser `Workbook` type to Node
+ * consumers — see issue #160.
+ *
+ * The default type parameter keeps the public XLSX surface unchanged for
+ * external callers (`new XLSX(workbook)` is still typed as `XLSX<Workbook>`).
  */
-declare class XLSX {
-    workbook: Workbook;
+declare class XLSX<TWorkbook extends Workbook = Workbook> {
+    workbook: TWorkbook;
     static RelType: {
         OfficeDocument: string;
         Worksheet: string;
@@ -239,7 +249,7 @@ declare class XLSX {
         Timeline: string;
         TimelineCache: string;
     };
-    constructor(workbook: Workbook);
+    constructor(workbook: TWorkbook);
     /**
      * Create a stream from binary data (for media/themes)
      */
@@ -285,11 +295,11 @@ declare class XLSX {
     /**
      * Read workbook from a stream
      */
-    read(stream: IParseStream, options?: XlsxReadOptions): Promise<Workbook>;
+    read(stream: IParseStream, options?: XlsxReadOptions): Promise<TWorkbook>;
     /**
      * Write workbook to a stream
      */
-    write(stream: IWritableStream, options?: XlsxWriteOptions): Promise<XLSX>;
+    write(stream: IWritableStream, options?: XlsxWriteOptions): Promise<this>;
     /**
      * Load a workbook from binary data.
      *
@@ -302,11 +312,11 @@ declare class XLSX {
      *    raw binary cannot be round-tripped through a JS string and is rejected
      *    to prevent silent corruption.
      */
-    load(data: Uint8Array | ArrayBuffer | ArrayBufferView | string, options?: XlsxReadOptions): Promise<Workbook>;
+    load(data: Uint8Array | ArrayBuffer | ArrayBufferView | string, options?: XlsxReadOptions): Promise<TWorkbook>;
     /**
      * Internal: Load from Uint8Array buffer
      */
-    protected loadBuffer(buffer: Uint8Array, options?: XlsxReadOptions): Promise<Workbook>;
+    protected loadBuffer(buffer: Uint8Array, options?: XlsxReadOptions): Promise<TWorkbook>;
     /**
      * Internal: Load workbook from an async stream of ZIP entries.
      *
@@ -328,7 +338,7 @@ declare class XLSX {
      * Returns true if handled, false if should be passed to _processDefaultEntry
      */
     protected _processKnownEntry(stream: IParseStream, model: any, entryName: string, options?: XlsxOptions): Promise<boolean>;
-    protected loadFromZipEntries(entries: AsyncIterable<ZipEntryLike>, options?: XlsxOptions): Promise<any>;
+    protected loadFromZipEntries(entries: AsyncIterable<ZipEntryLike>, options?: XlsxOptions): Promise<TWorkbook>;
     /**
      * Write workbook to buffer
      */
@@ -470,7 +480,7 @@ declare class XLSX {
     _processChartRelsEntry(stream: IParseStream, model: any, chartNumber: number): Promise<void>;
     _processChartStyleEntry(stream: IParseStream, model: any, styleNumber: number): Promise<void>;
     _processChartColorsEntry(stream: IParseStream, model: any, colorsNumber: number): Promise<void>;
-    loadFromFiles(zipData: Record<string, Uint8Array>, options?: XlsxReadOptions): Promise<Workbook>;
+    loadFromFiles(zipData: Record<string, Uint8Array>, options?: XlsxReadOptions): Promise<TWorkbook>;
     /**
      * Process default entries (drawings, comments, tables, etc.)
      * @param rawData Optional raw entry data for passthrough preservation (used by loadFromFiles)

package/dist/types/modules/excel/xlsx/xlsx.d.ts

@@ -6,18 +6,26 @@
  * - writeFile: Write to file path
  * - Constructor injects readFileAsync for filename-based media loading
  *
- * Inherited from XLSX:
+ * Inherited from XLSX (and narrowed to the Node `Workbook` type via the
+ * `XLSXBase<Workbook>` generic):
  * - read: Read from stream
  * - write: Write to stream
  * - load: Load from buffer
  * - writeBuffer: Write to buffer (Uint8Array)
  * - addMedia: Supports buffer, base64, and filename (via readFileAsync)
+ *
+ * The `<Workbook>` type argument is what makes `wb.xlsx.load(buf)` /
+ * `wb.xlsx.read(stream)` return the *Node* Workbook (which exposes
+ * `xlsx.readFile` / `xlsx.writeFile`) instead of the browser base class.
+ * Without the generic, the inherited methods would be typed against the
+ * browser `Workbook` and Node consumers chaining off the returned value
+ * would lose access to the Node-only file APIs — issue #160.
  */
 import type { Workbook } from "../workbook.js";
 import type { XlsxReadOptions, XlsxWriteOptions } from "./xlsx.browser.js";
 import { XLSX as XLSXBase } from "./xlsx.browser.js";
 import type { ReadableLike } from "../../stream/types.js";
-declare class XLSX extends XLSXBase {
+declare class XLSX extends XLSXBase<Workbook> {
     constructor(workbook: Workbook);
     private static iterateZipEntries;
     read(stream: ReadableLike, options?: XlsxReadOptions): Promise<Workbook>;

package/dist/types/modules/pdf/excel-bridge.d.ts

@@ -3,6 +3,7 @@
  *
  * Converts Excel Workbook data into the PDF module's independent data model.
  * This is the ONLY file in the PDF module that imports from @excel.
+ * It also imports from @word/bridge/excel-bridge for Word chart → ChartModel mapping.
  *
  * @example
  * ```typescript
@@ -15,7 +16,9 @@
  * ```
  */
 import type { Chart, RegionMapDataOptions } from "../excel/chart/index.js";
-import type { Workbook } from "../excel/workbook.js";
+import type { Workbook } from "../excel/workbook.browser.js";
+import type { Chart as WordChart } from "../word/types.js";
+import { type PdfPageBuilder } from "./builder/document-builder.js";
 import { type PdfExportOptions } from "./types.js";
 /**
  * Export an Excel Workbook directly to PDF.
@@ -97,3 +100,29 @@ export interface ChartToPdfOptions {
  * `@cj-tech-master/excelts/pdf` alongside `excelToPdf`.
  */
 export declare function chartToPdf(chart: Chart, options?: ChartToPdfOptions): Promise<Uint8Array>;
+/**
+ * Create a chart renderer callback for use with `docxToPdf`.
+ *
+ * This factory returns a function that converts Word Chart definitions
+ * into Excel's internal ChartModel and renders them using the full
+ * Excel chart rendering engine (8000+ lines of vector drawing logic).
+ *
+ * Requires `installChartSupport()` to have been called.
+ *
+ * @example
+ * ```typescript
+ * import { installChartSupport } from "excelts/chart";
+ * import { docxToPdf, createWordChartPdfRenderer } from "excelts/pdf";
+ *
+ * installChartSupport();
+ * const pdfBytes = await docxToPdf(doc, {
+ *   chartRenderer: createWordChartPdfRenderer()
+ * });
+ * ```
+ */
+export declare function createWordChartPdfRenderer(): (chart: WordChart, page: PdfPageBuilder, rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}) => void;

package/dist/types/modules/pdf/font/metrics.d.ts

@@ -1,59 +1,10 @@
 /**
  * Character width metrics for the 14 PDF standard Type 1 fonts.
  *
- * These metrics are specified in 1/1000 of a text unit. To get the actual width
- * of a character at a given font size:
- *   width_in_points = (charWidth / 1000) * fontSize
- *
- * The 14 standard fonts are guaranteed to be available in every PDF viewer:
- * - Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique
- * - Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic
- * - Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique
- * - Symbol, ZapfDingbats
- *
- * We provide metrics for the most commonly needed: Helvetica and Times families,
- * plus Courier (fixed-width). For other fonts, we fall back to Helvetica metrics.
- *
- * Character widths are for the Latin-1 (ISO 8859-1) encoding.
+ * This module re-exports from the shared @utils/font-metrics to avoid
+ * data duplication while maintaining backward compatibility.
  *
  * @see PDF Reference 1.7, Appendix D - Standard Type 1 Fonts
  * @see Adobe Font Metrics files (AFM) for canonical widths
  */
-/**
- * Get the width of a character in a given font.
- * @param charCode - Unicode code point (or char code)
- * @param fontName - PDF standard font name
- * @returns Width in thousandths of a unit
- */
-export declare function getCharWidth(charCode: number, fontName: string): number;
-/**
- * Measure the width of a text string in the given font and size.
- * @param text - The string to measure
- * @param fontName - PDF standard font name
- * @param fontSize - Font size in points
- * @returns Width in points
- */
-export declare function measureText(text: string, fontName: string, fontSize: number): number;
-/**
- * Get the font ascent for a given font and size.
- * @returns Ascent in points (positive, distance above baseline)
- */
-export declare function getFontAscent(fontName: string, fontSize: number): number;
-/**
- * Get the font descent for a given font and size.
- * @returns Descent in points (negative, distance below baseline)
- */
-export declare function getFontDescent(fontName: string, fontSize: number): number;
-/**
- * Get the total line height (ascent - descent) for a font.
- * @returns Line height in points
- */
-export declare function getLineHeight(fontName: string, fontSize: number): number;
-/**
- * Check if a font name is a known standard PDF font.
- */
-export declare function isStandardFont(fontName: string): boolean;
-/**
- * Get all supported standard font names.
- */
-export declare function getStandardFontNames(): string[];
+export { measureTextWidth as measureText, getCharWidth, getFontAscent, getFontDescent, getLineHeight, isStandardFont, getStandardFontNames } from "../../../utils/font-metrics.js";

package/dist/types/modules/pdf/index.d.ts

@@ -43,7 +43,7 @@
 /** Standalone PDF generation — accepts plain arrays, sheet objects, or workbooks. */
 export { pdf } from "./pdf.js";
 /** Excel-to-PDF conversion — accepts an Excel Workbook instance. */
-export { excelToPdf, chartToPdf, type ChartToPdfOptions } from "./excel-bridge.js";
+export { excelToPdf, chartToPdf, createWordChartPdfRenderer, type ChartToPdfOptions } from "./excel-bridge.js";
 /** Word-to-PDF conversion — accepts a DocxDocument. */
 export { docxToPdf } from "./word-bridge.js";
 export type { DocxToPdfOptions } from "./word-bridge.js";

package/dist/types/modules/pdf/render-layout-to-pdf.d.ts

@@ -0,0 +1,66 @@
+/**
+ * LayoutDocument → PDF translation layer.
+ *
+ * Consumes the fully-positioned `LayoutDocument` produced by
+ * `@word/layout/layout-full` and emits PDF operators via
+ * `PdfDocumentBuilder`. Coordinate translation is the only logic
+ * here — every flow decision (line wrapping, page breaks, table cell
+ * sizing, float positioning, footnote placement) has already been
+ * resolved by the layout engine.
+ *
+ * The Word layout coordinate system uses points with origin at the
+ * top-left of the **content area** of each page (not the page itself),
+ * with Y increasing downwards. The PDF coordinate system uses points
+ * with origin at the bottom-left of the page and Y increasing upwards.
+ * `pdfY = pageHeight - (geometry.marginTop + layoutY) - lineHeight`,
+ * with the per-element `lineHeight` baked into rect.height for non-
+ * paragraph variants and per-line for paragraphs.
+ */
+import type { LayoutChart, LayoutDocument } from "../word/layout/layout-model.js";
+import { PdfDocumentBuilder, type PdfPageBuilder } from "./builder/document-builder.js";
+/** Options for rendering a LayoutDocument into a PdfDocumentBuilder. */
+export interface RenderLayoutOptions {
+    /** Document title (sets PDF metadata). */
+    readonly title?: string;
+    /** Document author (sets PDF metadata). */
+    readonly author?: string;
+    /** Document subject. */
+    readonly subject?: string;
+    /** Document creator (defaults to "excelts"). */
+    readonly creator?: string;
+    /** Default font family used when a paragraph run has no explicit font. */
+    readonly defaultFont?: string;
+    /** Default font size in points. */
+    readonly defaultFontSize?: number;
+    /**
+     * Optional pluggable chart renderer. Receives the bounding rect
+     * (already translated into PDF coordinates) and the layout chart
+     * info; the implementation paints onto `page` directly.
+     *
+     * Return value semantics:
+     * - `true` (or `void`) — the renderer handled this chart; no further
+     *   fallback drawing happens.
+     * - `false` — the renderer declined this chart (e.g. it only knows
+     *   how to draw a specific chart family); the translator falls back
+     *   to its built-in path (inline `LayoutChart.svg` if present,
+     *   otherwise a placeholder box with the chart title).
+     *
+     * The boolean variant lets a chart-aware host plug in a renderer
+     * that handles classic `<c:chart>` while still letting `chartEx`
+     * variants fall through to the simple placeholder.
+     */
+    readonly chartRenderer?: (chart: LayoutChart, page: PdfPageBuilder, rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }) => boolean | void;
+}
+/**
+ * Render a `LayoutDocument` into a freshly-constructed
+ * `PdfDocumentBuilder`. Call `.build()` on the returned builder to get
+ * the final PDF bytes; alternatively use {@link layoutToPdfBytes}.
+ */
+export declare function renderLayoutDocumentToPdf(layout: LayoutDocument, options?: RenderLayoutOptions): PdfDocumentBuilder;
+/** Convenience: render and immediately serialise to PDF bytes. */
+export declare function layoutToPdfBytes(layout: LayoutDocument, options?: RenderLayoutOptions): Promise<Uint8Array>;

package/dist/types/modules/pdf/word-bridge.d.ts

@@ -1,9 +1,27 @@
 /**
  * Word-to-PDF Bridge
  *
- * Converts a Word document (DocxDocument) to PDF.
- * Like excel-bridge.ts, this is the ONLY file in the PDF module that imports
- * from @word.
+ * Converts a Word document (`DocxDocument`) to PDF.
+ *
+ * The bridge is a thin translation layer:
+ *
+ *   DocxDocument
+ *      │
+ *      │  layoutDocumentFull()  ← @word/layout
+ *      ▼
+ *   LayoutDocument (positioned PageContent variants)
+ *      │
+ *      │  renderLayoutDocumentToPdf()  ← ./render-layout-to-pdf
+ *      ▼
+ *   PdfDocumentBuilder → bytes
+ *
+ * Every flow decision (line wrapping, page breaks, table sizing,
+ * float positioning) lives in `@word/layout`. This file only handles
+ * option mapping, optional chart-renderer auto-detection, and the
+ * final `builder.build()` serialization.
+ *
+ * Like `excel-bridge.ts`, this is the ONLY file in the PDF module that
+ * imports from `@word`.
  *
  * @example
  * ```typescript
@@ -13,11 +31,9 @@
  * const doc = await readDocx(docxBytes);
  * const pdfBytes = await docxToPdf(doc);
  * ```
- *
- * Note: This is a simple flow-based renderer. For high-fidelity output,
- * consider using Microsoft Word or LibreOffice.
  */
-import type { DocxDocument } from "../word/types.js";
+import type { Chart, DocxDocument } from "../word/types.js";
+import type { PdfPageBuilder } from "./builder/document-builder.js";
 /** Options for DOCX → PDF conversion. */
 export interface DocxToPdfOptions {
     /** Page width in points (default: from document sectPr or 612 US Letter). */
@@ -32,16 +48,68 @@ export interface DocxToPdfOptions {
     readonly marginLeft?: number;
     /** Right margin in points (default: from sectPr or 72). */
     readonly marginRight?: number;
-    /** Default font family (default: "Times-Roman"). */
+    /** Default font family (default: "Helvetica"). */
     readonly defaultFont?: string;
     /** Default font size in points (default: 11). */
     readonly defaultFontSize?: number;
+    /**
+     * Header margin from top edge in points (default: 36).
+     *
+     * @deprecated Currently has no effect on the layout-driven render
+     * path: header paragraphs are rendered into the page's `marginTop`
+     * strip starting at y=0 without an additional offset. Influence
+     * header placement by widening `marginTop` instead.
+     */
+    readonly headerMargin?: number;
+    /**
+     * Footer margin from bottom edge in points (default: 36).
+     *
+     * @deprecated See {@link DocxToPdfOptions.headerMargin}. Footer
+     * paragraphs are rendered starting at `pageHeight - marginBottom`.
+     */
+    readonly footerMargin?: number;
+    /**
+     * Optional high-quality chart renderer callback.
+     *
+     * When provided, Word charts are rendered using the injected renderer
+     * instead of the built-in simplified renderer. This allows consumers
+     * to plug in the Excel chart renderer for publication-quality output:
+     *
+     * ```typescript
+     * import { installChartSupport } from "excelts/chart";
+     * import { createWordChartPdfRenderer } from "excelts/pdf";
+     * installChartSupport();
+     * const pdfBytes = await docxToPdf(doc, {
+     *   chartRenderer: createWordChartPdfRenderer()
+     * });
+     * ```
+     *
+     * The callback receives the original Word `Chart` definition (taken
+     * from the source `ChartContent`), a `PdfPageBuilder`, and the
+     * destination rectangle in PDF coordinates. The implementation
+     * should draw the chart into the rectangle.
+     *
+     * Return `false` to decline a chart (the translator then falls back
+     * to its built-in placeholder rendering: an outlined rectangle with
+     * the chart title centred). Return `void` or `true` to indicate the
+     * chart was handled.
+     *
+     * Note: `chartEx` charts never reach this callback because there is
+     * no `Chart` instance to pass; they always render through the
+     * translator's built-in path.
+     */
+    readonly chartRenderer?: (chart: Chart, page: PdfPageBuilder, rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }) => boolean | void;
 }
 /**
- * Convert a DocxDocument to PDF bytes.
+ * Convert a `DocxDocument` to PDF bytes.
  *
- * @param doc - The DOCX document model (from readDocx or DocumentBuilder.build()).
- * @param options - PDF rendering options.
- * @returns Promise of PDF bytes.
+ * @param doc - The DOCX document model (from `readDocx` or `Document.build()`).
+ * @param options - Page geometry, fonts, optional chart renderer, …
+ * @returns PDF bytes ready to write to disk or stream over HTTP.
  */
 export declare function docxToPdf(doc: DocxDocument, options?: DocxToPdfOptions): Promise<Uint8Array>;

package/dist/types/modules/stream/index.base.d.ts

@@ -14,4 +14,6 @@ export { StreamStateError, StreamTypeError, UnsupportedStreamTypeError } from ".
 export { isReadableStream, isWritableStream, isAsyncIterable, isTransformStream } from "./internal/type-guards.js";
 export { onceEvent } from "./internal/event-utils.js";
 export { eventedReadableToAsyncIterableNoDestroy, type EventedReadableLike } from "./internal/evented-readable-to-async-iterable.js";
+export { SinkAdapter } from "./internal/sink-adapter.js";
+export type { AnySink, NodeWritableLike, DuckSinkLike } from "./internal/sink-adapter.js";
 export type { EventEmitterLike } from "./types.js";

package/dist/types/modules/stream/internal/sink-adapter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * SinkAdapter — unified writable-sink view.
+ *
+ * Producers (zip writers, docx streamers, etc.) generate `Uint8Array`
+ * chunks and want to push them through a user-supplied destination
+ * without caring whether that destination is a Web `WritableStream`,
+ * a Node `Writable`, or some duck-typed object.
+ *
+ * `SinkAdapter` collapses all three into one promise-based API:
+ *   - `write(chunk)` resolves once the chunk has been accepted by the
+ *     sink (after awaiting `drain` for Node-style sinks under
+ *     backpressure, or `writer.ready` for Web streams).
+ *   - `end()` finalises the sink and resolves on close.
+ *   - The first sink error is captured and re-thrown from the next
+ *     `write` / `end` so callers can't lose it.
+ *
+ * Producers are expected to either:
+ *   - drive `await sink.write(chunk)` directly (preferred — gives
+ *     true end-to-end backpressure), or
+ *   - chain writes onto a single shared promise so a synchronous
+ *     emit callback can still feed the adapter without blocking.
+ */
+import type { EventEmitterLike } from "../types.js";
+/**
+ * Loose Node `Writable`-like contract. Matches `stream.Writable` but only
+ * the subset SinkAdapter touches; intentionally avoids depending on
+ * `node:stream` so the adapter compiles in browsers.
+ */
+export interface NodeWritableLike extends EventEmitterLike {
+    write(chunk: Uint8Array, cb?: (err?: Error | null) => void): boolean;
+    end(cb?: () => void): unknown;
+    destroyed?: boolean;
+}
+/**
+ * Object that implements just enough of a writable to be useful: a
+ * `write` returning sync bool / Promise, plus `end`. Used as a fallback
+ * for legacy producers that don't fit either Node or Web streams.
+ */
+export interface DuckSinkLike extends EventEmitterLike {
+    write(chunk: Uint8Array): boolean | Promise<boolean>;
+    end(): unknown;
+}
+/** Anything SinkAdapter knows how to drive. */
+export type AnySink = WritableStream<Uint8Array> | NodeWritableLike | DuckSinkLike;
+/** Unified sink view with awaited write + error capture. */
+export declare class SinkAdapter {
+    private readonly _kind;
+    private readonly _webWriter?;
+    private readonly _nodeSink?;
+    private readonly _duckSink?;
+    private _error;
+    private _ended;
+    constructor(sink: AnySink);
+    /**
+     * The first error reported by the sink (or `null`). Producers that
+     * cannot await `write()` (synchronous emit callbacks) should poll
+     * this between operations.
+     */
+    get error(): Error | null;
+    write(chunk: Uint8Array): Promise<void>;
+    end(): Promise<void>;
+    private _captureError;
+    private _throwIfErrored;
+    private _attachErrorListener;
+}