@laminapdf/sdk 0.0.0-stage → 0.2.0-alpha.2

package/dist/document.d.ts

@@ -0,0 +1,241 @@
+import type { WasmDocument, WasmPage, WasmSaveJob } from "@laminapdf/wasm/base";
+import { type LaminaPdfWarning } from "./errors.js";
+import { type RangeOptions, type RangeSource, type RangeState } from "./source/range.js";
+import { PageText, type TextOptions } from "./text.js";
+import { Transaction } from "./transaction.js";
+import type { DocumentInfo, Edited, Op, OpenOptions, OpLog, PageInfo, Progress, SaveOptions, SaveReport, UndoOutcome } from "./types.js";
+/** A page of a {@link Document}, held by its ID: moving pages doesn't retarget it (ADR 0028 F2). */
+export declare class PageRef {
+    #private;
+    /** @internal */
+    constructor(page: WasmPage);
+    /** The page's stable ID (`p12.0`). */
+    get id(): string;
+    /** The page's current 0-based index. @throws {@link LaminaPdfError} `unknown-page` when it is gone. */
+    get index(): number;
+    /** The page's facts now. @throws {@link LaminaPdfError} `unknown-page` when it is gone. */
+    get info(): PageInfo;
+    /**
+     * The page's text: lines in reading order, runs, and every glyph's quad in page space.
+     * Needs a document opened while the extract or text module was loaded.
+     *
+     * @example
+     * ```ts
+     * await init({ extract: true });
+     * const doc = Document.open(bytes);
+     * const text = doc.page(0).text().text();
+     * ```
+     * @param options - `skipInvisible` leaves out invisible text (OCR layers).
+     * @throws {@link LaminaPdfError} `extract-module-not-loaded` for a document opened in the base
+     *   module; `unknown-page`; reading errors (`data-pending` for a range document: use `ensure`).
+     */
+    text(options?: TextOptions): PageText;
+}
+/** A save in progress, stepped by the caller with a budget of work units (ADR 0028 §3). */
+export declare class SaveJob {
+    #private;
+    /** @internal */
+    constructor(job: WasmSaveJob);
+    /**
+     * Runs at most `budget` work units.
+     *
+     * @returns `{ state: "progress", … }`, or `{ state: "done", bytes, report }` at the end.
+     * @throws {@link LaminaPdfError} `cancelled`, `document-changed`, `job-finished`, or the save's errors.
+     */
+    step(budget: number): ({
+        readonly state: "progress";
+    } & Progress) | {
+        readonly state: "done";
+        readonly bytes: Uint8Array<ArrayBuffer>;
+        readonly report: SaveReport;
+    };
+    /** Stops the job: its next step fails with `cancelled`. */
+    cancel(): void;
+    /** Frees the job's memory now (otherwise when it is garbage-collected). */
+    free(): void;
+}
+/**
+ * An open PDF: read it, edit it with ops (atomic transactions with undo), save it.
+ *
+ * @example
+ * ```ts
+ * await init();
+ * const doc = Document.open(bytes);
+ * doc.transact((tx) => tx.setInfo({ title: "Final" }));
+ * const updated = doc.save({ mode: "incremental" });
+ * doc.free();
+ * ```
+ */
+export declare class Document {
+    #private;
+    /** @internal Wraps a raw document (from `open`, `openRange` or `Builder.finish`). */
+    constructor(doc: WasmDocument, range?: RangeState);
+    /**
+     * Opens a document whose bytes are fetched range by range ({@link httpRangeSource},
+     * {@link callbackSource}): only what the open needs is fetched (the end of the file, the xref,
+     * the catalog). Calls on the document stay synchronous; one that needs bytes not fetched yet
+     * throws `data-pending` with `ranges`, so wrap later reads in {@link Document.ensure}.
+     *
+     * @param source - the file (or a promise of it, as `httpRangeSource` returns).
+     * @param options - open options (password, strict, limits) and fetch options.
+     * @returns the document, once open has everything it needs.
+     * @throws {@link LaminaPdfError} as {@link Document.open}; `data-pending` when fetching made no
+     *   progress or `maxRounds` ran out; `source-budget-exceeded`; the source's own errors
+     *   (`fetch-failed`, `source-changed`); the signal's reason when aborted.
+     */
+    static openRange(source: RangeSource | Promise<RangeSource>, options?: OpenOptions & RangeOptions): Promise<Document>;
+    /**
+     * Runs a synchronous call on this document, fetching what it needs first: for a document
+     * from {@link Document.openRange}, a `data-pending` makes it fetch the ranges asked for and
+     * call `f` again. For other documents it just returns `f()`.
+     *
+     * @example
+     * ```ts
+     * const doc = await Document.openRange(httpRangeSource(url));
+     * const pages = await doc.ensure(() => doc.pages);
+     * ```
+     * @param f - the call (it may run several times; keep it free of side effects). An async
+     *   function works too: its `data-pending` rejections are caught the same way.
+     * @param options - `signal` aborts this call's fetches (the open's signal applies to the open
+     *   only).
+     * @returns what `f` returns.
+     * @throws what `f` throws, and as {@link Document.openRange}.
+     */
+    ensure<T>(f: () => T | Promise<T>, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<T>;
+    /**
+     * Opens a document from its bytes (the bytes are copied into the WASM memory).
+     *
+     * The password is tried as given. When that fails with `wrong-password` and its NFKC form
+     * differs, the NFKC form is tried too: R5/R6 passwords are prepared with SASLprep, whose
+     * normalisation the WASM modules leave out (ADR 0016 §7), while R2–R4 passwords must reach
+     * the core unchanged.
+     *
+     * @param bytes - the PDF file.
+     * @param options - password, strict mode, limits.
+     * @returns the document.
+     * @throws {@link LaminaPdfError} `not-pdf`, `password-required`, `wrong-password`, `limit-exceeded`,
+     *   `strict`, …; `unknown-option` / `invalid-argument` for bad options; `not-initialized`.
+     */
+    static open(bytes: Uint8Array | ArrayBuffer, options?: OpenOptions): Document;
+    /**
+     * Whether `page(i).text()` works on this document: it was opened or built while the extract or
+     * the text module was loaded. A document opened before the module loaded stays in the base
+     * module; save and reopen it to move it.
+     */
+    get canExtractText(): boolean;
+    /** The number of pages. @throws {@link LaminaPdfError} reading errors. */
+    get pageCount(): number;
+    /** Every page's facts, in order (one page-tree walk). @throws {@link LaminaPdfError} reading errors. */
+    get pages(): readonly PageInfo[];
+    /**
+     * Page `index`'s facts.
+     *
+     * @throws {@link LaminaPdfError} `page-index-out-of-range`.
+     */
+    pageInfo(index: number): PageInfo;
+    /**
+     * A handle on page `index` that follows the page by its ID.
+     *
+     * @throws {@link LaminaPdfError} `page-index-out-of-range`.
+     */
+    page(index: number): PageRef;
+    /**
+     * A handle on the page with `id` (`p12.0`).
+     *
+     * @throws {@link LaminaPdfError} `invalid-argument`, `unknown-page`.
+     */
+    pageById(id: string): PageRef;
+    /** The Info dictionary's text entries (document text). @throws {@link LaminaPdfError} reading errors. */
+    get info(): DocumentInfo;
+    /** Every warning so far (build warnings first), each the ADR 0026 §1 object. */
+    get warnings(): readonly LaminaPdfWarning[];
+    /** Whether there are changes no save has written yet. */
+    get hasUnsavedChanges(): boolean;
+    /**
+     * Applies `ops` in order as one transaction: all of them, or none.
+     *
+     * @returns the pages the edit touched.
+     * @throws {@link LaminaPdfError} `unknown-option` / `invalid-argument` for a value that isn't an op;
+     *   the first failing op's error (`unknown-page`, …), with nothing applied.
+     */
+    apply(ops: readonly Op[]): Edited;
+    /**
+     * Applies an op log (`{ v: 1, ops }`, as JSON text or an object) as one transaction.
+     *
+     * @throws {@link LaminaPdfError} `invalid-op-log`, `unsupported-version`; as {@link Document.apply}.
+     */
+    applyLog(log: string | OpLog): Edited;
+    /**
+     * Runs `edit` with a transaction handle and applies what it collected as one transaction
+     * (ADR 0006 §2). When `edit` throws, nothing is applied and the error propagates. The ops are
+     * applied when `edit` returns: reads inside `edit` see the document before the transaction.
+     *
+     * @param edit - collects ops on `tx`; synchronous only (a callback returning a promise is
+     *   refused with `invalid-argument` and nothing is applied).
+     * @returns what `edit` returned.
+     * @throws {@link LaminaPdfError} `nested-transaction` when called (or when `apply`, `undo`, `redo`,
+     *   `save`… are called) inside a `transact` of the same document; `invalid-argument` for an
+     *   async callback; as {@link Document.apply}.
+     * @example
+     * ```ts
+     * doc.transact((tx) => {
+     *   tx.setInfo({ title: "Report" });
+     *   tx.rotatePage(doc.page(0).id, 90);
+     * });
+     * ```
+     */
+    transact<T>(edit: (tx: Transaction) => T): T;
+    /**
+     * Undoes the newest transaction.
+     *
+     * @returns how it went, or `undefined` when there is nothing to undo.
+     * @throws {@link LaminaPdfError} `saved-not-rebased`; reading errors.
+     */
+    undo(): UndoOutcome | undefined;
+    /**
+     * Redoes the newest undone transaction.
+     *
+     * @returns how it went, or `undefined` when there is nothing to redo.
+     * @throws {@link LaminaPdfError} as {@link Document.undo}.
+     */
+    redo(): UndoOutcome | undefined;
+    /**
+     * Saves and rebases onto the output (later edits and saves build on it).
+     *
+     * @param options - `mode` (`auto`, `incremental`, `fullRewrite`), overrides, output form.
+     * @returns the file's bytes.
+     * @throws {@link LaminaPdfError} `would-invalidate-signatures`, `requires-rewrite`, `encrypted-base`, …
+     */
+    save(options?: SaveOptions): Uint8Array<ArrayBuffer>;
+    /**
+     * As {@link Document.save}, with the save's report (mode used, bytes written, renumbering, …).
+     *
+     * @throws {@link LaminaPdfError} as {@link Document.save}.
+     */
+    saveWithReport(options?: SaveOptions): {
+        readonly bytes: Uint8Array<ArrayBuffer>;
+        readonly report: SaveReport;
+    };
+    /**
+     * A save as a job stepped by the caller (to keep a UI responsive).
+     *
+     * @throws {@link LaminaPdfError} `unknown-option` / `invalid-argument` for bad options.
+     */
+    saveJob(options?: SaveOptions): SaveJob;
+    /**
+     * Rebases onto `bytes`, the output of a save whose rebase failed (`not-rebased`).
+     *
+     * @throws {@link LaminaPdfError} `no-pending-save`; reading errors in `bytes`.
+     */
+    rebase(bytes: Uint8Array): void;
+    /**
+     * Frees the document's WASM memory now; without it, it is freed when garbage-collected.
+     * Calling it twice is harmless; using the document afterwards is not (L2b adds `disposed`).
+     */
+    free(): void;
+    /** Frees the document at the end of a `using` block. */
+    [Symbol.dispose](): void;
+}
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"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"}

package/dist/document.js

@@ -0,0 +1,427 @@
+import { guard, isLaminaPdfError, packageError } from "./errors.js";
+import { extractsText, readingModule } from "./init.js";
+import { settle, wholeBytes } from "./source/range.js";
+import { PageText } from "./text.js";
+import { Transaction } from "./transaction.js";
+function isThenable(value) {
+    return ((typeof value === "object" || typeof value === "function") &&
+        value !== null &&
+        typeof value.then === "function");
+}
+/** How many warnings one cursor call fetches. */
+const WARNING_BATCH = 256;
+function bytesOf(input) {
+    return input instanceof Uint8Array ? input : new Uint8Array(input);
+}
+/**
+ * The open options to try, in order: as given, then, when the password's NFKC form differs, with
+ * that form (tried only after `wrong-password`). R5/R6 passwords are prepared with SASLprep,
+ * whose normalisation the WASM modules leave out (ADR 0016 §7), while R2–R4 passwords must reach
+ * the core unchanged.
+ */
+function passwordAttempts(options) {
+    const password = options.password;
+    const nfkc = password?.normalize("NFKC");
+    return password === undefined || nfkc === undefined || nfkc === password
+        ? [options]
+        : [options, { ...options, password: nfkc }];
+}
+/** Whether a failed attempt should be followed by the next one. */
+function tryNext(e, attempt, attempts) {
+    return attempt + 1 < attempts && isLaminaPdfError(e, "wrong-password");
+}
+/** A page of a {@link Document}, held by its ID: moving pages doesn't retarget it (ADR 0028 F2). */
+export class PageRef {
+    #page;
+    /** @internal */
+    constructor(page) {
+        this.#page = page;
+    }
+    /** The page's stable ID (`p12.0`). */
+    get id() {
+        return this.#page.id;
+    }
+    /** The page's current 0-based index. @throws {@link LaminaPdfError} `unknown-page` when it is gone. */
+    get index() {
+        return guard(() => this.#page.index());
+    }
+    /** The page's facts now. @throws {@link LaminaPdfError} `unknown-page` when it is gone. */
+    get info() {
+        return guard(() => this.#page.info());
+    }
+    /**
+     * The page's text: lines in reading order, runs, and every glyph's quad in page space.
+     * Needs a document opened while the extract or text module was loaded.
+     *
+     * @example
+     * ```ts
+     * await init({ extract: true });
+     * const doc = Document.open(bytes);
+     * const text = doc.page(0).text().text();
+     * ```
+     * @param options - `skipInvisible` leaves out invisible text (OCR layers).
+     * @throws {@link LaminaPdfError} `extract-module-not-loaded` for a document opened in the base
+     *   module; `unknown-page`; reading errors (`data-pending` for a range document: use `ensure`).
+     */
+    text(options) {
+        const page = this.#page;
+        if (typeof page.text !== "function") {
+            throw packageError("extract-module-not-loaded", "page.text() needs a document opened while the extract or text module was loaded");
+        }
+        const extract = page.text.bind(page);
+        return new PageText(guard(() => extract(options)));
+    }
+}
+/** A save in progress, stepped by the caller with a budget of work units (ADR 0028 §3). */
+export class SaveJob {
+    #job;
+    /** @internal */
+    constructor(job) {
+        this.#job = job;
+    }
+    /**
+     * Runs at most `budget` work units.
+     *
+     * @returns `{ state: "progress", … }`, or `{ state: "done", bytes, report }` at the end.
+     * @throws {@link LaminaPdfError} `cancelled`, `document-changed`, `job-finished`, or the save's errors.
+     */
+    step(budget) {
+        return guard(() => this.#job.step(budget));
+    }
+    /** Stops the job: its next step fails with `cancelled`. */
+    cancel() {
+        this.#job.cancel();
+    }
+    /** Frees the job's memory now (otherwise when it is garbage-collected). */
+    free() {
+        this.#job.free();
+    }
+}
+/**
+ * An open PDF: read it, edit it with ops (atomic transactions with undo), save it.
+ *
+ * @example
+ * ```ts
+ * await init();
+ * const doc = Document.open(bytes);
+ * doc.transact((tx) => tx.setInfo({ title: "Final" }));
+ * const updated = doc.save({ mode: "incremental" });
+ * doc.free();
+ * ```
+ */
+export class Document {
+    #doc;
+    /** Set for a document opened with {@link Document.openRange}: where more bytes come from. */
+    #range;
+    #freed = false;
+    /** Whether a `transact` callback of this document is running. */
+    #transacting = false;
+    /** @internal Wraps a raw document (from `open`, `openRange` or `Builder.finish`). */
+    constructor(doc, range) {
+        this.#doc = doc;
+        this.#range = range;
+    }
+    /**
+     * Opens a document whose bytes are fetched range by range ({@link httpRangeSource},
+     * {@link callbackSource}): only what the open needs is fetched (the end of the file, the xref,
+     * the catalog). Calls on the document stay synchronous; one that needs bytes not fetched yet
+     * throws `data-pending` with `ranges`, so wrap later reads in {@link Document.ensure}.
+     *
+     * @param source - the file (or a promise of it, as `httpRangeSource` returns).
+     * @param options - open options (password, strict, limits) and fetch options.
+     * @returns the document, once open has everything it needs.
+     * @throws {@link LaminaPdfError} as {@link Document.open}; `data-pending` when fetching made no
+     *   progress or `maxRounds` ran out; `source-budget-exceeded`; the source's own errors
+     *   (`fetch-failed`, `source-changed`); the signal's reason when aborted.
+     */
+    static async openRange(source, options = {}) {
+        // The source first: a rejected source promise must not go unhandled behind not-initialized.
+        const src = await source;
+        const { signal, blockSize, readahead, maxRounds, budget, ...open } = options;
+        // A server that ignored Range from the start sent the whole file: open those bytes as they
+        // are, rather than copying them into a sparse source as well.
+        const whole = wholeBytes(src);
+        if (whole !== undefined)
+            return Document.open(whole, open);
+        const wasm = readingModule();
+        const sparse = guard(() => new wasm.WasmSparseSource(src.size, budget));
+        const state = {
+            sparse,
+            source: src,
+            blockSize: blockSize ?? src.blockSize ?? 4096,
+            readahead: readahead ?? 0,
+            maxRounds: maxRounds ?? 1024,
+        };
+        const attempts = passwordAttempts(open);
+        try {
+            for (let i = 0;; i++) {
+                try {
+                    return await settle(state, () => new Document(guard(() => wasm.WasmDocument.openSource(sparse, attempts[i])), state), signal);
+                }
+                catch (e) {
+                    if (!tryNext(e, i, attempts.length))
+                        throw e;
+                }
+            }
+        }
+        catch (e) {
+            // Nothing holds the fetched bytes now: free them at once rather than at collection.
+            sparse.free();
+            throw e;
+        }
+    }
+    /**
+     * Runs a synchronous call on this document, fetching what it needs first: for a document
+     * from {@link Document.openRange}, a `data-pending` makes it fetch the ranges asked for and
+     * call `f` again. For other documents it just returns `f()`.
+     *
+     * @example
+     * ```ts
+     * const doc = await Document.openRange(httpRangeSource(url));
+     * const pages = await doc.ensure(() => doc.pages);
+     * ```
+     * @param f - the call (it may run several times; keep it free of side effects). An async
+     *   function works too: its `data-pending` rejections are caught the same way.
+     * @param options - `signal` aborts this call's fetches (the open's signal applies to the open
+     *   only).
+     * @returns what `f` returns.
+     * @throws what `f` throws, and as {@link Document.openRange}.
+     */
+    async ensure(f, options = {}) {
+        return this.#range === undefined ? f() : settle(this.#range, f, options.signal);
+    }
+    /**
+     * Opens a document from its bytes (the bytes are copied into the WASM memory).
+     *
+     * The password is tried as given. When that fails with `wrong-password` and its NFKC form
+     * differs, the NFKC form is tried too: R5/R6 passwords are prepared with SASLprep, whose
+     * normalisation the WASM modules leave out (ADR 0016 §7), while R2–R4 passwords must reach
+     * the core unchanged.
+     *
+     * @param bytes - the PDF file.
+     * @param options - password, strict mode, limits.
+     * @returns the document.
+     * @throws {@link LaminaPdfError} `not-pdf`, `password-required`, `wrong-password`, `limit-exceeded`,
+     *   `strict`, …; `unknown-option` / `invalid-argument` for bad options; `not-initialized`.
+     */
+    static open(bytes, options) {
+        const wasm = readingModule();
+        const data = bytesOf(bytes);
+        const attempts = passwordAttempts(options ?? {});
+        for (let i = 0;; i++) {
+            try {
+                return new Document(guard(() => wasm.WasmDocument.openBytes(data, attempts[i])));
+            }
+            catch (e) {
+                if (!tryNext(e, i, attempts.length))
+                    throw e;
+            }
+        }
+    }
+    /**
+     * Whether `page(i).text()` works on this document: it was opened or built while the extract or
+     * the text module was loaded. A document opened before the module loaded stays in the base
+     * module; save and reopen it to move it.
+     */
+    get canExtractText() {
+        return extractsText(this.#doc);
+    }
+    /** The number of pages. @throws {@link LaminaPdfError} reading errors. */
+    get pageCount() {
+        return guard(() => this.#doc.pageCount());
+    }
+    /** Every page's facts, in order (one page-tree walk). @throws {@link LaminaPdfError} reading errors. */
+    get pages() {
+        return guard(() => this.#doc.pageInfos());
+    }
+    /**
+     * Page `index`'s facts.
+     *
+     * @throws {@link LaminaPdfError} `page-index-out-of-range`.
+     */
+    pageInfo(index) {
+        return guard(() => this.#doc.pageInfo(index));
+    }
+    /**
+     * A handle on page `index` that follows the page by its ID.
+     *
+     * @throws {@link LaminaPdfError} `page-index-out-of-range`.
+     */
+    page(index) {
+        return new PageRef(guard(() => this.#doc.page(index)));
+    }
+    /**
+     * A handle on the page with `id` (`p12.0`).
+     *
+     * @throws {@link LaminaPdfError} `invalid-argument`, `unknown-page`.
+     */
+    pageById(id) {
+        return new PageRef(guard(() => this.#doc.pageById(id)));
+    }
+    /** The Info dictionary's text entries (document text). @throws {@link LaminaPdfError} reading errors. */
+    get info() {
+        return guard(() => this.#doc.info());
+    }
+    /** Every warning so far (build warnings first), each the ADR 0026 §1 object. */
+    get warnings() {
+        const cursor = this.#doc.warnings();
+        try {
+            const out = [];
+            for (;;) {
+                const batch = cursor.nextBatch(WARNING_BATCH);
+                if (batch.length === 0)
+                    return out;
+                out.push(...batch);
+            }
+        }
+        finally {
+            cursor.free();
+        }
+    }
+    /** Whether there are changes no save has written yet. */
+    get hasUnsavedChanges() {
+        return this.#doc.hasUnsavedChanges();
+    }
+    /**
+     * Applies `ops` in order as one transaction: all of them, or none.
+     *
+     * @returns the pages the edit touched.
+     * @throws {@link LaminaPdfError} `unknown-option` / `invalid-argument` for a value that isn't an op;
+     *   the first failing op's error (`unknown-page`, …), with nothing applied.
+     */
+    apply(ops) {
+        this.#notInTransaction("apply");
+        return guard(() => this.#doc.apply(ops));
+    }
+    /**
+     * Applies an op log (`{ v: 1, ops }`, as JSON text or an object) as one transaction.
+     *
+     * @throws {@link LaminaPdfError} `invalid-op-log`, `unsupported-version`; as {@link Document.apply}.
+     */
+    applyLog(log) {
+        this.#notInTransaction("applyLog");
+        const json = typeof log === "string" ? log : JSON.stringify(log);
+        return guard(() => this.#doc.applyLog(json));
+    }
+    /**
+     * Runs `edit` with a transaction handle and applies what it collected as one transaction
+     * (ADR 0006 §2). When `edit` throws, nothing is applied and the error propagates. The ops are
+     * applied when `edit` returns: reads inside `edit` see the document before the transaction.
+     *
+     * @param edit - collects ops on `tx`; synchronous only (a callback returning a promise is
+     *   refused with `invalid-argument` and nothing is applied).
+     * @returns what `edit` returned.
+     * @throws {@link LaminaPdfError} `nested-transaction` when called (or when `apply`, `undo`, `redo`,
+     *   `save`… are called) inside a `transact` of the same document; `invalid-argument` for an
+     *   async callback; as {@link Document.apply}.
+     * @example
+     * ```ts
+     * doc.transact((tx) => {
+     *   tx.setInfo({ title: "Report" });
+     *   tx.rotatePage(doc.page(0).id, 90);
+     * });
+     * ```
+     */
+    transact(edit) {
+        this.#notInTransaction("transact");
+        this.#transacting = true;
+        const tx = new Transaction();
+        let result;
+        try {
+            result = edit(tx);
+        }
+        finally {
+            this.#transacting = false;
+            tx.close();
+        }
+        if (isThenable(result)) {
+            // The ops of an async callback would be applied before its awaits finish: refuse it.
+            throw packageError("invalid-argument", "transact takes a synchronous callback; it returned a promise", {
+                data: { argument: "edit", detail: "the callback returned a promise; nothing was applied" },
+            });
+        }
+        if (tx.ops.length > 0)
+            this.apply(tx.ops);
+        return result;
+    }
+    /** Throws `nested-transaction` while a `transact` callback of this document runs. */
+    #notInTransaction(call) {
+        if (this.#transacting) {
+            throw packageError("nested-transaction", `${call} was called inside a transaction of the same document`);
+        }
+    }
+    /**
+     * Undoes the newest transaction.
+     *
+     * @returns how it went, or `undefined` when there is nothing to undo.
+     * @throws {@link LaminaPdfError} `saved-not-rebased`; reading errors.
+     */
+    undo() {
+        this.#notInTransaction("undo");
+        return guard(() => this.#doc.undo());
+    }
+    /**
+     * Redoes the newest undone transaction.
+     *
+     * @returns how it went, or `undefined` when there is nothing to redo.
+     * @throws {@link LaminaPdfError} as {@link Document.undo}.
+     */
+    redo() {
+        this.#notInTransaction("redo");
+        return guard(() => this.#doc.redo());
+    }
+    /**
+     * Saves and rebases onto the output (later edits and saves build on it).
+     *
+     * @param options - `mode` (`auto`, `incremental`, `fullRewrite`), overrides, output form.
+     * @returns the file's bytes.
+     * @throws {@link LaminaPdfError} `would-invalidate-signatures`, `requires-rewrite`, `encrypted-base`, …
+     */
+    save(options) {
+        return this.saveWithReport(options).bytes;
+    }
+    /**
+     * As {@link Document.save}, with the save's report (mode used, bytes written, renumbering, …).
+     *
+     * @throws {@link LaminaPdfError} as {@link Document.save}.
+     */
+    saveWithReport(options) {
+        this.#notInTransaction("save");
+        return guard(() => this.#doc.save(options));
+    }
+    /**
+     * A save as a job stepped by the caller (to keep a UI responsive).
+     *
+     * @throws {@link LaminaPdfError} `unknown-option` / `invalid-argument` for bad options.
+     */
+    saveJob(options) {
+        this.#notInTransaction("saveJob");
+        return new SaveJob(guard(() => this.#doc.saveJob(options)));
+    }
+    /**
+     * Rebases onto `bytes`, the output of a save whose rebase failed (`not-rebased`).
+     *
+     * @throws {@link LaminaPdfError} `no-pending-save`; reading errors in `bytes`.
+     */
+    rebase(bytes) {
+        this.#notInTransaction("rebase");
+        guard(() => this.#doc.rebase(bytes));
+    }
+    /**
+     * Frees the document's WASM memory now; without it, it is freed when garbage-collected.
+     * Calling it twice is harmless; using the document afterwards is not (L2b adds `disposed`).
+     */
+    free() {
+        if (this.#freed)
+            return;
+        this.#freed = true;
+        this.#doc.free();
+        // A range document's fetched bytes live in its sparse source.
+        this.#range?.sparse.free();
+    }
+    /** Frees the document at the end of a `using` block. */
+    [Symbol.dispose]() {
+        this.free();
+    }
+}
+//# sourceMappingURL=document.js.map