pdf-oxide 0.3.37 → 0.3.39

package/lib/builders/document-builder.js

@@ -0,0 +1,724 @@
+/**
+ * Fluent document builder — the programmatic multi-page construction API
+ * exposed through the C FFI.
+ *
+ * Mirrors the Python / WASM / C# / Go equivalents. The same handle-lifetime
+ * contract applies: terminal methods (`build`, `save`, `saveEncrypted`,
+ * `toBytesEncrypted`) CONSUME the builder, and only one `PageBuilder` may
+ * be open at a time.
+ *
+ * @example
+ * ```typescript
+ * import { DocumentBuilder, EmbeddedFont } from 'pdf-oxide';
+ *
+ * const font = EmbeddedFont.fromFile('DejaVuSans.ttf');
+ * const builder = DocumentBuilder.create()
+ *   .title('Hello')
+ *   .registerEmbeddedFont('DejaVu', font);   // consumes `font`
+ * builder.a4Page()
+ *   .font('DejaVu', 12)
+ *   .at(72, 720).text('Привет, мир!')
+ *   .at(72, 700).text('Καλημέρα κόσμε')
+ *   .done();
+ * const bytes = builder.build();            // consumes the builder
+ * ```
+ */
+// Load the addon via the shared prebuild-aware loader — resolves
+// against `prebuilds/<triple>/pdf_oxide.node` in the published
+// package and the in-tree `build/Release/` output in dev mode.
+import { loadNative } from '../native.js';
+import { Align, } from '../types/common.js';
+import { StreamingTable } from './streaming-table.js';
+const native = loadNative();
+/**
+ * TTF/OTF font handle registerable with {@link DocumentBuilder}. Single-use:
+ * after `registerEmbeddedFont` the native handle is moved into the builder
+ * and this object becomes disposed.
+ */
+export class EmbeddedFont {
+    constructor(handle) {
+        this._consumed = false;
+        this._handle = handle;
+    }
+    /** Load a TTF / OTF font from disk. */
+    static fromFile(path) {
+        return new EmbeddedFont(native.embeddedFontFromFile(path));
+    }
+    /** Load a font from a byte buffer; pass `name` to override the PostScript name. */
+    static fromBytes(data, name) {
+        return new EmbeddedFont(native.embeddedFontFromBytes(data, name));
+    }
+    /** @internal — used by {@link DocumentBuilder.registerEmbeddedFont} */
+    get handle() {
+        if (this._consumed) {
+            throw new Error('EmbeddedFont already consumed');
+        }
+        return this._handle;
+    }
+    /** @internal — called by the builder after the FFI transfers ownership. */
+    markConsumed() {
+        this._consumed = true;
+        this._handle = null;
+    }
+    /** Release the native font handle if it hasn't been consumed. */
+    close() {
+        if (!this._consumed && this._handle != null) {
+            native.embeddedFontFree(this._handle);
+            this._consumed = true;
+            this._handle = null;
+        }
+    }
+    /** Symbol.dispose support for `using` declarations. */
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+/**
+ * Fluent top-level API for multi-page PDF construction.
+ * Use {@link DocumentBuilder.create} to start a new builder.
+ */
+export class DocumentBuilder {
+    constructor(handle) {
+        this._consumed = false;
+        this._openPage = null;
+        this._handle = handle;
+    }
+    /** Create a fresh empty builder. */
+    static create() {
+        return new DocumentBuilder(native.documentBuilderCreate());
+    }
+    /** @internal — used by PageBuilder.done */
+    clearOpenPage() {
+        this._openPage = null;
+    }
+    checkUsable() {
+        if (this._consumed || this._handle == null) {
+            throw new Error('DocumentBuilder has been consumed');
+        }
+        if (this._openPage != null) {
+            throw new Error('A PageBuilder is already open; call done() first.');
+        }
+        return this._handle;
+    }
+    /** Set the document title. */
+    title(title) {
+        native.documentBuilderSetTitle(this.checkUsable(), title);
+        return this;
+    }
+    /** Set the document author. */
+    author(author) {
+        native.documentBuilderSetAuthor(this.checkUsable(), author);
+        return this;
+    }
+    /** Set the document subject. */
+    subject(subject) {
+        native.documentBuilderSetSubject(this.checkUsable(), subject);
+        return this;
+    }
+    /** Set the document keywords (comma-separated per PDF convention). */
+    keywords(keywords) {
+        native.documentBuilderSetKeywords(this.checkUsable(), keywords);
+        return this;
+    }
+    /** Set the creator application name. */
+    creator(creator) {
+        native.documentBuilderSetCreator(this.checkUsable(), creator);
+        return this;
+    }
+    /** Run a JavaScript script when the document is opened (/OpenAction). */
+    onOpen(script) {
+        native.documentBuilderOnOpen(this.checkUsable(), script);
+        return this;
+    }
+    /**
+     * Enable PDF/UA-1 tagged PDF mode.
+     *
+     * When enabled, `build()` emits `/MarkInfo`, `/StructTreeRoot`, `/Lang`, and
+     * `/ViewerPreferences` in the catalog. Opt-in — no effect unless called.
+     * Bundle F-1/F-2.
+     */
+    taggedPdfUa1() {
+        native.documentBuilderTaggedPdfUa1(this.checkUsable());
+        return this;
+    }
+    /**
+     * Set the document's natural language tag, e.g. `"en-US"`.
+     *
+     * Emitted as `/Lang` in the catalog when `taggedPdfUa1()` is set. Bundle F-2.
+     */
+    language(lang) {
+        native.documentBuilderLanguage(this.checkUsable(), lang);
+        return this;
+    }
+    /**
+     * Add a role-map entry: custom structure type → standard PDF structure type.
+     *
+     * Emitted in `/RoleMap` inside the StructTreeRoot when `taggedPdfUa1()` is
+     * set. Multiple calls accumulate entries. Bundle F-4.
+     */
+    roleMap(custom, standard) {
+        native.documentBuilderRoleMap(this.checkUsable(), custom, standard);
+        return this;
+    }
+    /**
+     * Register a TTF / OTF font under `name`. CONSUMES `font` on success —
+     * do not call `close()` on the font afterwards.
+     */
+    registerEmbeddedFont(name, font) {
+        const builderHandle = this.checkUsable();
+        // font.handle getter throws if already consumed, so validation is done.
+        native.documentBuilderRegisterEmbeddedFont(builderHandle, name, font.handle);
+        font.markConsumed();
+        return this;
+    }
+    /** Start a new A4 page. Only one page may be outstanding per builder. */
+    a4Page() {
+        const h = this.checkUsable();
+        const pageHandle = native.documentBuilderA4Page(h);
+        this._openPage = new PageBuilder(this, pageHandle);
+        return this._openPage;
+    }
+    /** Start a new US Letter page. */
+    letterPage() {
+        const h = this.checkUsable();
+        const pageHandle = native.documentBuilderLetterPage(h);
+        this._openPage = new PageBuilder(this, pageHandle);
+        return this._openPage;
+    }
+    /** Start a page with custom dimensions in PDF points (72 pt = 1 inch). */
+    page(width, height) {
+        const h = this.checkUsable();
+        const pageHandle = native.documentBuilderPage(h, width, height);
+        this._openPage = new PageBuilder(this, pageHandle);
+        return this._openPage;
+    }
+    consumeHandle() {
+        const h = this.checkUsable();
+        this._consumed = true;
+        this._handle = null;
+        return h;
+    }
+    /** Build the PDF and return the bytes. CONSUMES the builder. */
+    build() {
+        const h = this.consumeHandle();
+        try {
+            return native.documentBuilderBuild(h);
+        }
+        finally {
+            native.documentBuilderFree(h);
+        }
+    }
+    /** Save the PDF to a file. CONSUMES the builder. */
+    save(path) {
+        const h = this.consumeHandle();
+        try {
+            native.documentBuilderSave(h, path);
+        }
+        finally {
+            native.documentBuilderFree(h);
+        }
+    }
+    /** Save the PDF with AES-256 encryption. CONSUMES the builder. */
+    saveEncrypted(path, userPassword, ownerPassword) {
+        const h = this.consumeHandle();
+        try {
+            native.documentBuilderSaveEncrypted(h, path, userPassword, ownerPassword);
+        }
+        finally {
+            native.documentBuilderFree(h);
+        }
+    }
+    /** Return the PDF as encrypted bytes (AES-256). CONSUMES the builder. */
+    toBytesEncrypted(userPassword, ownerPassword) {
+        const h = this.consumeHandle();
+        try {
+            return native.documentBuilderToBytesEncrypted(h, userPassword, ownerPassword);
+        }
+        finally {
+            native.documentBuilderFree(h);
+        }
+    }
+    /** Release native resources if the builder wasn't consumed. */
+    close() {
+        if (!this._consumed && this._handle != null) {
+            native.documentBuilderFree(this._handle);
+            this._consumed = true;
+            this._handle = null;
+        }
+    }
+    /** Symbol.dispose support for `using` declarations. */
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+/**
+ * Fluent per-page builder returned by `DocumentBuilder.a4Page` etc.
+ * Single-use — `done()` commits the page and invalidates this builder.
+ */
+export class PageBuilder {
+    /** @internal — constructed by DocumentBuilder */
+    constructor(parent, handle) {
+        this._done = false;
+        this._parent = parent;
+        this._handle = handle;
+    }
+    h() {
+        if (this._done || this._handle == null) {
+            throw new Error('PageBuilder already committed');
+        }
+        return this._handle;
+    }
+    // --- content --------------------------------------------------------
+    /** Set font + size for subsequent text. */
+    font(name, size) {
+        native.pageBuilderFont(this.h(), name, size);
+        this._lastFontSize = size;
+        return this;
+    }
+    /** Move the cursor to absolute coordinates. */
+    at(x, y) {
+        native.pageBuilderAt(this.h(), x, y);
+        return this;
+    }
+    /** Emit a line of text at the current cursor position. */
+    text(text) {
+        native.pageBuilderText(this.h(), text);
+        return this;
+    }
+    /** Emit a heading (level 1-6). */
+    heading(level, text) {
+        native.pageBuilderHeading(this.h(), level, text);
+        return this;
+    }
+    /** Emit a paragraph with automatic line wrapping. */
+    paragraph(text) {
+        native.pageBuilderParagraph(this.h(), text);
+        return this;
+    }
+    /** Advance the cursor by the given number of points. */
+    space(points) {
+        native.pageBuilderSpace(this.h(), points);
+        return this;
+    }
+    /** Draw a horizontal rule across the page. */
+    horizontalRule() {
+        native.pageBuilderHorizontalRule(this.h());
+        return this;
+    }
+    // --- annotations (Phase 3) -----------------------------------------
+    /** Attach a URL link to the previous text element. */
+    linkUrl(url) {
+        native.pageBuilderLinkUrl(this.h(), url);
+        return this;
+    }
+    /** Link the previous text to an internal page (0-based). */
+    linkPage(pageIndex) {
+        native.pageBuilderLinkPage(this.h(), pageIndex);
+        return this;
+    }
+    /** Link the previous text to a named destination. */
+    linkNamed(destination) {
+        native.pageBuilderLinkNamed(this.h(), destination);
+        return this;
+    }
+    /** Link the previous text to a JavaScript action. */
+    linkJavascript(script) {
+        native.pageBuilderLinkJavascript(this.h(), script);
+        return this;
+    }
+    /** Run JavaScript when this page is opened (/AA /O). */
+    onOpen(script) {
+        native.pageBuilderOnOpen(this.h(), script);
+        return this;
+    }
+    /** Run JavaScript when this page is closed (/AA /C). */
+    onClose(script) {
+        native.pageBuilderOnClose(this.h(), script);
+        return this;
+    }
+    /** Set a keystroke JS action (/AA /K) on the last form field. */
+    fieldKeystroke(script) {
+        native.pageBuilderFieldKeystroke(this.h(), script);
+        return this;
+    }
+    /** Set a format JS action (/AA /F) on the last form field. */
+    fieldFormat(script) {
+        native.pageBuilderFieldFormat(this.h(), script);
+        return this;
+    }
+    /** Set a validate JS action (/AA /V) on the last form field. */
+    fieldValidate(script) {
+        native.pageBuilderFieldValidate(this.h(), script);
+        return this;
+    }
+    /** Set a calculate JS action (/AA /C) on the last form field. */
+    fieldCalculate(script) {
+        native.pageBuilderFieldCalculate(this.h(), script);
+        return this;
+    }
+    /** Highlight the previous text with an RGB colour (channels 0-1). */
+    highlight(r, g, b) {
+        native.pageBuilderHighlight(this.h(), r, g, b);
+        return this;
+    }
+    /** Underline the previous text. */
+    underline(r, g, b) {
+        native.pageBuilderUnderline(this.h(), r, g, b);
+        return this;
+    }
+    /** Strike through the previous text. */
+    strikeout(r, g, b) {
+        native.pageBuilderStrikeout(this.h(), r, g, b);
+        return this;
+    }
+    /** Squiggly-underline the previous text. */
+    squiggly(r, g, b) {
+        native.pageBuilderSquiggly(this.h(), r, g, b);
+        return this;
+    }
+    /** Attach a sticky-note annotation to the previous text. */
+    stickyNote(text) {
+        native.pageBuilderStickyNote(this.h(), text);
+        return this;
+    }
+    /** Place a sticky-note at an absolute position. */
+    stickyNoteAt(x, y, text) {
+        native.pageBuilderStickyNoteAt(this.h(), x, y, text);
+        return this;
+    }
+    /** Apply a text watermark to the page. */
+    watermark(text) {
+        native.pageBuilderWatermark(this.h(), text);
+        return this;
+    }
+    /** Apply the standard "CONFIDENTIAL" diagonal watermark. */
+    watermarkConfidential() {
+        native.pageBuilderWatermarkConfidential(this.h());
+        return this;
+    }
+    /** Apply the standard "DRAFT" diagonal watermark. */
+    watermarkDraft() {
+        native.pageBuilderWatermarkDraft(this.h());
+        return this;
+    }
+    /**
+     * Attach a standard stamp annotation at the cursor (150×50 default).
+     * `typeName` matches the PDF spec's standard stamps (Approved,
+     * NotApproved, Draft, Confidential, Final, Experimental, Expired,
+     * ForPublicRelease, NotForPublicRelease, AsIs, Sold, Departmental,
+     * ForComment, TopSecret) — any other name becomes a custom stamp.
+     */
+    stamp(typeName) {
+        native.pageBuilderStamp(this.h(), typeName);
+        return this;
+    }
+    /** Place a free-flowing text annotation inside the rectangle (x, y, w, h). */
+    freeText(x, y, w, h, text) {
+        native.pageBuilderFreetext(this.h(), x, y, w, h, text);
+        return this;
+    }
+    // --- Form-field widgets --------------------------------------------
+    /**
+     * Add a single-line text form field at the rectangle (x, y, w, h).
+     * `name` is the unique field identifier used for form submission;
+     * `defaultValue` is the initial text (pass undefined for blank).
+     */
+    textField(name, x, y, w, h, defaultValue) {
+        native.pageBuilderTextField(this.h(), name, x, y, w, h, defaultValue);
+        return this;
+    }
+    /**
+     * Add a checkbox form field at the rectangle (x, y, w, h).
+     * `checked` sets the initial state.
+     */
+    checkbox(name, x, y, w, h, checked = false) {
+        native.pageBuilderCheckbox(this.h(), name, x, y, w, h, checked);
+        return this;
+    }
+    /**
+     * Add a dropdown combo-box form field. `options` are the user-
+     * visible choices; `selected` picks the initial value.
+     */
+    comboBox(name, x, y, w, h, options, selected) {
+        native.pageBuilderComboBox(this.h(), name, x, y, w, h, options, selected);
+        return this;
+    }
+    /**
+     * Add a radio-button group. `buttons` is an array of
+     * `[exportValue, x, y, w, h]` tuples — one per option. `selected`
+     * picks the initial value by export value.
+     */
+    radioGroup(name, buttons, selected) {
+        native.pageBuilderRadioGroup(this.h(), name, buttons, selected);
+        return this;
+    }
+    /** Add a clickable push button with a visible caption. */
+    pushButton(name, x, y, w, h, caption) {
+        native.pageBuilderPushButton(this.h(), name, x, y, w, h, caption);
+        return this;
+    }
+    /** Add an unsigned signature placeholder field (/FT /Sig) at the given bounds. */
+    signatureField(name, x, y, w, h) {
+        native.pageBuilderSignatureField(this.h(), name, x, y, w, h);
+        return this;
+    }
+    /**
+     * Add a footnote: inline `refMark` emitted at the cursor position, and
+     * `noteText` placed near the page bottom with a separator artifact line.
+     */
+    footnote(refMark, noteText) {
+        native.pageBuilderFootnote(this.h(), refMark, noteText);
+        return this;
+    }
+    /**
+     * Lay out `text` as balanced multi-column flow.
+     * `columnCount` columns separated by `gapPt` points.
+     * Paragraphs in `text` are delimited by `"\n\n"`.
+     */
+    columns(columnCount, gapPt, text) {
+        native.pageBuilderColumns(this.h(), columnCount, gapPt, text);
+        return this;
+    }
+    /**
+     * Emit `text` inline at the current cursor position without advancing
+     * to a new line. The cursor advances horizontally so the next `inline`
+     * call follows on the same line.
+     */
+    inline(text) {
+        native.pageBuilderInline(this.h(), text);
+        return this;
+    }
+    /** Emit `text` inline in bold weight. */
+    inlineBold(text) {
+        native.pageBuilderInlineBold(this.h(), text);
+        return this;
+    }
+    /** Emit `text` inline in italic style. */
+    inlineItalic(text) {
+        native.pageBuilderInlineItalic(this.h(), text);
+        return this;
+    }
+    /** Emit `text` inline in an RGB colour (channels 0–1). */
+    inlineColor(r, g, b, text) {
+        native.pageBuilderInlineColor(this.h(), r, g, b, text);
+        return this;
+    }
+    /** Advance the cursor to the start of the next line. */
+    newline() {
+        native.pageBuilderNewline(this.h());
+        return this;
+    }
+    // --- Barcode / QR-code placement ------------------------------------
+    /**
+     * Place a 1-D barcode image on the page at `(x, y, w, h)`.
+     * `barcodeType`: 0=Code128 1=Code39 2=EAN13 3=EAN8 4=UPCA 5=ITF
+     * 6=Code93 7=Codabar.
+     */
+    barcode1d(barcodeType, data, x, y, w, h) {
+        native.pageBuilderBarcode1d(this.h(), barcodeType, data, x, y, w, h);
+        return this;
+    }
+    /** Place a QR-code image on the page (square: `size × size` pt). */
+    barcodeQr(data, x, y, size) {
+        native.pageBuilderBarcodeQr(this.h(), data, x, y, size);
+        return this;
+    }
+    /**
+     * Embed an image with an accessibility alt text (PDF/UA-1 §Figure).
+     * `bytes` must contain raw JPEG/PNG/WebP image data.
+     */
+    imageWithAlt(bytes, x, y, w, h, altText) {
+        native.pageBuilderImageWithAlt(this.h(), bytes, x, y, w, h, altText);
+        return this;
+    }
+    /**
+     * Embed a decorative image as an /Artifact (no alt text, PDF/UA-1 §Artifact).
+     * `bytes` must contain raw JPEG/PNG/WebP image data.
+     */
+    imageArtifact(bytes, x, y, w, h) {
+        native.pageBuilderImageArtifact(this.h(), bytes, x, y, w, h);
+        return this;
+    }
+    // --- Low-level graphics primitives ---------------------------------
+    /** Draw a stroked rectangle outline (1pt black). */
+    rect(x, y, w, h) {
+        native.pageBuilderRect(this.h(), x, y, w, h);
+        return this;
+    }
+    /** Draw a filled rectangle in RGB colour (channels 0–1). */
+    filledRect(x, y, w, h, r, g, b) {
+        native.pageBuilderFilledRect(this.h(), x, y, w, h, r, g, b);
+        return this;
+    }
+    /** Draw a line from `(x1, y1)` to `(x2, y2)` with 1pt black stroke. */
+    line(x1, y1, x2, y2) {
+        native.pageBuilderLine(this.h(), x1, y1, x2, y2);
+        return this;
+    }
+    // --- v0.3.39 primitives (#393) -------------------------------------
+    /**
+     * Draw a stroked rectangle outline with caller-supplied width + RGB
+     * colour (channels 0–1). Underlies the Table surface.
+     */
+    strokeRect(x, y, w, h, style) {
+        const width = style?.width ?? 1;
+        const [r, g, b] = style?.color ?? [0, 0, 0];
+        native.pageBuilderStrokeRect(this.h(), x, y, w, h, width, r, g, b);
+        return this;
+    }
+    /**
+     * Draw a straight line with caller-supplied width + RGB colour.
+     */
+    strokeLine(x1, y1, x2, y2, style) {
+        const width = style?.width ?? 1;
+        const [r, g, b] = style?.color ?? [0, 0, 0];
+        native.pageBuilderStrokeLine(this.h(), x1, y1, x2, y2, width, r, g, b);
+        return this;
+    }
+    /**
+     * Place wrapped text inside the rectangle (x, y, w, h) with the
+     * given horizontal alignment. Uses the current font + size. Text
+     * that does not fit is clipped to the rectangle height.
+     */
+    textInRect(x, y, w, h, text, align = Align.Left) {
+        native.pageBuilderTextInRect(this.h(), x, y, w, h, text, align);
+        return this;
+    }
+    /**
+     * Start a new page with the *same* dimensions as the current one.
+     * Text config (font + size) carries over; the cursor resets to the
+     * top-left margin. Callers wanting header-repeat-on-break must
+     * re-emit the header explicitly.
+     */
+    newPageSameSize() {
+        native.pageBuilderNewPageSameSize(this.h());
+        return this;
+    }
+    /**
+     * Measure the width of `text` in the current font and size.
+     *
+     * Note: v0.3.39 ships a JS-side approximation (0.55em per glyph for
+     * ASCII / typical Latin-1 characters). A true per-glyph measurement
+     * FFI is pending. The result is in PDF points.
+     */
+    measure(text) {
+        // Retrieve current font size if the user tracked it via `font(...)`.
+        // We have no FFI query for the size; fall back to the 10pt default.
+        const size = this._lastFontSize ?? 10;
+        // ~0.55 em is a reasonable average for proportional fonts.
+        return text.length * size * 0.55;
+    }
+    /**
+     * Estimate the remaining vertical space on the page at the current
+     * cursor position. v0.3.39 returns `null` when the native cursor is
+     * unknown — callers should treat `null` as "unknown; assume fresh
+     * page". A real FFI hook is pending in a follow-up release.
+     */
+    remainingSpace() {
+        return null;
+    }
+    /**
+     * Emit a buffered table at the current cursor. All rows are
+     * marshalled into a single FFI call — memory scales with the row
+     * count. For million-row streams use {@link streamingTable}.
+     */
+    table(spec) {
+        const columns = spec.columns;
+        if (!columns || columns.length === 0) {
+            throw new Error('table spec must contain at least one column');
+        }
+        const widths = columns.map((c) => c.width);
+        const aligns = columns.map((c) => (c.align ?? Align.Left));
+        const hasHeader = spec.hasHeader !== false;
+        const rows = spec.rows ?? [];
+        const cells = [];
+        if (hasHeader) {
+            for (const c of columns)
+                cells.push(c.header);
+        }
+        const bodyRowCount = rows.length;
+        for (const row of rows) {
+            if (row.length !== columns.length) {
+                throw new Error(`row width ${row.length} does not match column count ${columns.length}`);
+            }
+            for (const cell of row)
+                cells.push(cell ?? null);
+        }
+        const totalRows = (hasHeader ? 1 : 0) + bodyRowCount;
+        native.pageBuilderTable(this.h(), widths, aligns, totalRows, cells, hasHeader);
+        return this;
+    }
+    /**
+     * Begin a streaming table. Uses the native row-at-a-time FFI
+     * (`pdf_page_builder_streaming_table_begin_v2`). Pass a `mode` in
+     * `config` to control column-sizing strategy (default: fixed widths).
+     */
+    streamingTable(config) {
+        return new StreamingTable(this, config);
+    }
+    /** @internal — open streaming table FFI handle on this page. */
+    _streamingTableBeginV2(headers, widths, aligns, repeatHeader, mode, maxRowspan) {
+        let modeInt = 0;
+        let sampleRows = 20;
+        let minW = 0;
+        let maxW = 9999;
+        if (mode?.kind === 'sample') {
+            modeInt = 1;
+            if (mode.sampleRows != null)
+                sampleRows = mode.sampleRows;
+            if (mode.minColWidthPt != null)
+                minW = mode.minColWidthPt;
+            if (mode.maxColWidthPt != null)
+                maxW = mode.maxColWidthPt;
+        }
+        native.pageBuilderStreamingTableBeginV2(this.h(), headers, widths, aligns, repeatHeader, modeInt, sampleRows, minW, maxW, maxRowspan);
+    }
+    /** @internal — push one row into the open streaming table (all rowspan=1). */
+    _streamingTablePushRow(cells) {
+        native.pageBuilderStreamingTablePushRow(this.h(), cells);
+    }
+    /** @internal — push one row with per-cell rowspan values. */
+    _streamingTablePushRowV2(cells) {
+        native.pageBuilderStreamingTablePushRowV2(this.h(), cells);
+    }
+    /** @internal — close the open streaming table. */
+    _streamingTableFinish() {
+        native.pageBuilderStreamingTableFinish(this.h());
+    }
+    /**
+     * Commit the page's buffered operations to the parent builder and
+     * return the parent for chaining. After `done()` this PageBuilder is
+     * invalid.
+     */
+    done() {
+        if (this._done) {
+            throw new Error('PageBuilder already committed');
+        }
+        native.pageBuilderDone(this._handle);
+        this._done = true;
+        this._handle = null;
+        this._parent.clearOpenPage();
+        return this._parent;
+    }
+    /**
+     * Drop an uncommitted page. Use only for error recovery — the parent's
+     * open-page slot is released so the next `a4Page()` etc. succeeds.
+     */
+    close() {
+        if (!this._done && this._handle != null) {
+            native.pageBuilderFree(this._handle);
+            this._parent.clearOpenPage();
+            this._done = true;
+            this._handle = null;
+        }
+    }
+    /** Symbol.dispose support for `using`. */
+    [Symbol.dispose]() {
+        this.close();
+    }
+}
+export { StreamingTable } from './streaming-table.js';
+// Re-export the v0.3.39 table surface so users can `import { Align,
+// StreamingTable } from 'pdf-oxide'` without reaching into ./types or
+// ./builders/streaming-table.
+export { Align, };