@laminapdf/sdk 0.2.0-alpha.2 → 0.2.0-alpha.4

package/dist/document.d.ts

@@ -1,14 +1,22 @@
 import type { WasmDocument, WasmPage, WasmSaveJob } from "@laminapdf/wasm/base";
 import { type LaminaPdfWarning } from "./errors.js";
+import { type ExtractFormat, type ExtractOptions, type ExtractResult } from "./extract.js";
+import { ExtractJob, type ExtractJobOptions } from "./extract-job.js";
+import { type BaseGlue } from "./init.js";
+import { Handle } from "./internal/handle.js";
+import type { Instance } from "./internal/instance.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 {
+import type { DocumentInfo, Edited, Op, OpenOptions, OpLog, OutlineNode, PageInfo, Progress, SaveOptions, SaveReport, StructureNode, Target, UndoOutcome } from "./types.js";
+/**
+ * A page of a {@link Document}, held by its ID: moving pages doesn't retarget it (ADR 0028 F2).
+ * Freed with its document; every call after that throws `disposed`.
+ */
+export declare class PageRef extends Handle<BaseGlue> {
     #private;
     /** @internal */
-    constructor(page: WasmPage);
+    constructor(page: WasmPage, doc: Document, instance: Instance<BaseGlue>);
     /** 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. */
@@ -30,12 +38,16 @@ export declare class PageRef {
      *   module; `unknown-page`; reading errors (`data-pending` for a range document: use `ensure`).
      */
     text(options?: TextOptions): PageText;
+    protected release(): void;
 }
-/** A save in progress, stepped by the caller with a budget of work units (ADR 0028 §3). */
-export declare class SaveJob {
+/**
+ * A save in progress, stepped by the caller with a budget of work units (ADR 0028 §3). Freed with
+ * its document; every call after that throws `disposed`.
+ */
+export declare class SaveJob extends Handle<BaseGlue> {
     #private;
     /** @internal */
-    constructor(job: WasmSaveJob);
+    constructor(job: WasmSaveJob, doc: Document, instance: Instance<BaseGlue>);
     /**
      * Runs at most `budget` work units.
      *
@@ -51,25 +63,26 @@ export declare class SaveJob {
     };
     /** 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;
+    protected release(): void;
 }
 /**
- * An open PDF: read it, edit it with ops (atomic transactions with undo), save it.
+ * An open PDF: read it, edit it with ops (atomic transactions with undo), save it. It holds
+ * WebAssembly memory: free it with `using` or {@link Document.free} (an alias).
  *
  * @example
  * ```ts
  * await init();
- * const doc = Document.open(bytes);
+ * using doc = Document.open(bytes);
  * doc.transact((tx) => tx.setInfo({ title: "Final" }));
  * const updated = doc.save({ mode: "incremental" });
- * doc.free();
  * ```
  */
-export declare class Document {
+export declare class Document extends Handle<BaseGlue> {
     #private;
-    /** @internal Wraps a raw document (from `open`, `openRange` or `Builder.finish`). */
-    constructor(doc: WasmDocument, range?: RangeState);
+    /**
+     * @internal Wraps a raw document (from `open`, `openRange` or `Builder.finish`) of `instance`.
+     */
+    constructor(doc: WasmDocument, instance: Instance<BaseGlue>, 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,
@@ -147,8 +160,68 @@ export declare class Document {
      * @throws {@link LaminaPdfError} `invalid-argument`, `unknown-page`.
      */
     pageById(id: string): PageRef;
+    /**
+     * The outline (bookmarks): its top-level items in order, each with its children, and where
+     * each goes as a page and a view in page space; empty without one. Needs a document opened
+     * while the extract or text module was loaded.
+     *
+     * @throws {@link LaminaPdfError} `extract-module-not-loaded` for a document opened in the base
+     *   module; reading errors (`data-pending` for a range document: use `ensure`).
+     */
+    outline(): OutlineNode[];
+    /**
+     * Where the named destination `name` goes (the names a link or a `#nameddest=` address uses),
+     * or `undefined` when the document has none by that name. Needs a document opened while the
+     * extract or text module was loaded.
+     *
+     * @throws {@link LaminaPdfError} as {@link Document.outline}.
+     */
+    namedDestination(name: string): Target | undefined;
+    /**
+     * The document's text for retrieval and LLMs: Markdown or plain text in reading order, the
+     * `laminapdf.extract/1` JSON with a box for every block, or chunks sized for retrieval. Tables
+     * drawn with lines come out as tables, and text a reader can't see is left out. Needs a
+     * document opened while the extract or text module was loaded.
+     *
+     * @example
+     * ```ts
+     * await init({ extract: true });
+     * const doc = Document.open(bytes);
+     * const markdown = doc.extract({ format: "markdown" });
+     * const chunks = doc.extract({ format: "chunks", chunk: { maxTokens: 400 } });
+     * ```
+     * @returns a string for `"markdown"` and `"text"`, an {@link Extraction} for `"json"`,
+     *   {@link Chunk}s for `"chunks"`.
+     * @throws {@link LaminaPdfError} `extract-module-not-loaded` for a document opened in the base
+     *   module; `page-index-out-of-range`; `unknown-option` (with `didYouMean`) / `invalid-argument`
+     *   for bad options; reading errors (`data-pending` for a range document: use `ensure`).
+     */
+    extract<F extends ExtractFormat>(options: ExtractOptions<F>): ExtractResult[F];
+    /**
+     * An extraction stepped a page at a time, for models the host runs: each step that needs a
+     * model's result stops with a `request` (the page and resolution to render), answered with
+     * {@link ExtractJob.provide}. {@link extractWithModels} loops one for async models. Needs a
+     * document opened while the extract or text module was loaded.
+     *
+     * @throws {@link LaminaPdfError} as {@link Document.extract}.
+     */
+    extractJob<F extends ExtractFormat>(options: ExtractJobOptions<F>): ExtractJob<F>;
     /** The Info dictionary's text entries (document text). @throws {@link LaminaPdfError} reading errors. */
     get info(): DocumentInfo;
+    /**
+     * Whether the document says it is tagged (`/MarkInfo /Marked true`); it doesn't check the tree.
+     * Needs a document opened while the extract or text module was loaded, as `page.text()` does.
+     * @throws {@link LaminaPdfError} `extract-module-not-loaded`; reading errors.
+     */
+    get isTagged(): boolean;
+    /**
+     * The structure tree's top-level elements in reading order, or `undefined` for a document
+     * without one. A text run's `mcid` (on {@link PageTextRun}) links it to the element whose
+     * `{ type: "content", page, mcid }` kid names it. Needs the extract or text module, as
+     * `page.text()` does.
+     * @throws {@link LaminaPdfError} `extract-module-not-loaded`; reading errors.
+     */
+    structureTree(): StructureNode[] | undefined;
     /** 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. */
@@ -230,12 +303,6 @@ export declare class Document {
      * @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;
+    protected release(): void;
 }
 //# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEhF,OAAO,EAA2B,KAAK,gBAAgB,EAAgB,MAAM,aAAa,CAAC;AAE3F,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAsB,MAAM,mBAAmB,CAAC;AAC7G,OAAO,EAAE,QAAQ,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EACV,YAAY,EACZ,MAAM,EACN,EAAE,EACF,WAAW,EACX,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,UAAU,EACV,WAAW,EACZ,MAAM,YAAY,CAAC;AAoCpB,oGAAoG;AACpG,qBAAa,OAAO;;IAGlB,gBAAgB;IAChB,YAAY,IAAI,EAAE,QAAQ,EAEzB;IAED,sCAAsC;IACtC,IAAI,EAAE,IAAI,MAAM,CAEf;IAED,uGAAuG;IACvG,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,2FAA2F;IAC3F,IAAI,IAAI,IAAI,QAAQ,CAEnB;IAED;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,CAUpC;CACF;AAED,2FAA2F;AAC3F,qBAAa,OAAO;;IAGlB,gBAAgB;IAChB,YAAY,GAAG,EAAE,WAAW,EAE3B;IAED;;;;;OAKG;IACH,IAAI,CACF,MAAM,EAAE,MAAM,GAEZ,CAAC;QAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;KAAE,GAAG,QAAQ,CAAC,GAC3C;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;KAAE,CAEnG;IAED,2DAA2D;IAC3D,MAAM,IAAI,IAAI,CAEb;IAED,2EAA2E;IAC3E,IAAI,IAAI,IAAI,CAEX;CACF;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,QAAQ;;IAQnB,qFAAqF;IACrF,YAAY,GAAG,EAAE,YAAY,EAAE,KAAK,CAAC,EAAE,UAAU,EAGhD;IAED;;;;;;;;;;;;OAYG;IACH,OAAa,SAAS,CACpB,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,EAC1C,OAAO,GAAE,WAAW,GAAG,YAAiB,GACvC,OAAO,CAAC,QAAQ,CAAC,CAuCnB;IAED;;;;;;;;;;;;;;;;OAgBG;IACG,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAEpG;IAED;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,QAAQ,CAW5E;IAED;;;;OAIG;IACH,IAAI,cAAc,IAAI,OAAO,CAE5B;IAED,0EAA0E;IAC1E,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,wGAAwG;IACxG,IAAI,KAAK,IAAI,SAAS,QAAQ,EAAE,CAE/B;IAED;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAEhC;IAED;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE3B;IAED;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE5B;IAED,yGAAyG;IACzG,IAAI,IAAI,IAAI,YAAY,CAEvB;IAED,gFAAgF;IAChF,IAAI,QAAQ,IAAI,SAAS,gBAAgB,EAAE,CAY1C;IAED,yDAAyD;IACzD,IAAI,iBAAiB,IAAI,OAAO,CAE/B;IAED;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,GAAG,MAAM,CAGhC;IAED;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAIpC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,CAAC,GAAG,CAAC,CAmB3C;IASD;;;;;OAKG;IACH,IAAI,IAAI,WAAW,GAAG,SAAS,CAG9B;IAED;;;;;OAKG;IACH,IAAI,IAAI,WAAW,GAAG,SAAS,CAG9B;IAED;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC,CAEnD;IAED;;;;OAIG;IACH,cAAc,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG;QAAE,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;KAAE,CAG9G;IAED;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAGtC;IAED;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAG9B;IAED;;;OAGG;IACH,IAAI,IAAI,IAAI,CAMX;IAED,wDAAwD;IACxD,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,CAEvB;CACF"}
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"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"}

package/dist/document.js

@@ -1,5 +1,8 @@
-import { guard, isLaminaPdfError, packageError } from "./errors.js";
+import { isLaminaPdfError, packageError } from "./errors.js";
+import { parseExtract } from "./extract.js";
+import { ExtractJob } from "./extract-job.js";
 import { extractsText, readingModule } from "./init.js";
+import { Handle, watch } from "./internal/handle.js";
 import { settle, wholeBytes } from "./source/range.js";
 import { PageText } from "./text.js";
 import { Transaction } from "./transaction.js";
@@ -30,24 +33,28 @@ function passwordAttempts(options) {
 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 {
+/**
+ * A page of a {@link Document}, held by its ID: moving pages doesn't retarget it (ADR 0028 F2).
+ * Freed with its document; every call after that throws `disposed`.
+ */
+export class PageRef extends Handle {
     #page;
     /** @internal */
-    constructor(page) {
+    constructor(page, doc, instance) {
+        super("PageRef", instance, doc);
         this.#page = page;
     }
     /** The page's stable ID (`p12.0`). */
     get id() {
-        return this.#page.id;
+        return this.call(() => 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());
+        return this.call(() => this.#page.index());
     }
     /** The page's facts now. @throws {@link LaminaPdfError} `unknown-page` when it is gone. */
     get info() {
-        return guard(() => this.#page.info());
+        return this.call(() => this.#page.info());
     }
     /**
      * The page's text: lines in reading order, runs, and every glyph's quad in page space.
@@ -64,19 +71,27 @@ export class PageRef {
      *   module; `unknown-page`; reading errors (`data-pending` for a range document: use `ensure`).
      */
     text(options) {
+        this.assertLive();
         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)));
+        return new PageText(this.call(() => extract(options)));
+    }
+    release() {
+        this.#page.free();
     }
 }
-/** A save in progress, stepped by the caller with a budget of work units (ADR 0028 §3). */
-export class SaveJob {
+/**
+ * A save in progress, stepped by the caller with a budget of work units (ADR 0028 §3). Freed with
+ * its document; every call after that throws `disposed`.
+ */
+export class SaveJob extends Handle {
     #job;
     /** @internal */
-    constructor(job) {
+    constructor(job, doc, instance) {
+        super("SaveJob", instance, doc);
         this.#job = job;
     }
     /**
@@ -86,40 +101,42 @@ export class SaveJob {
      * @throws {@link LaminaPdfError} `cancelled`, `document-changed`, `job-finished`, or the save's errors.
      */
     step(budget) {
-        return guard(() => this.#job.step(budget));
+        return this.call(() => this.#job.step(budget));
     }
     /** Stops the job: its next step fails with `cancelled`. */
     cancel() {
-        this.#job.cancel();
+        this.call(() => this.#job.cancel());
     }
-    /** Frees the job's memory now (otherwise when it is garbage-collected). */
-    free() {
+    release() {
         this.#job.free();
     }
 }
 /**
- * An open PDF: read it, edit it with ops (atomic transactions with undo), save it.
+ * An open PDF: read it, edit it with ops (atomic transactions with undo), save it. It holds
+ * WebAssembly memory: free it with `using` or {@link Document.free} (an alias).
  *
  * @example
  * ```ts
  * await init();
- * const doc = Document.open(bytes);
+ * using doc = Document.open(bytes);
  * doc.transact((tx) => tx.setInfo({ title: "Final" }));
  * const updated = doc.save({ mode: "incremental" });
- * doc.free();
  * ```
  */
-export class Document {
+export class Document extends Handle {
     #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) {
+    /**
+     * @internal Wraps a raw document (from `open`, `openRange` or `Builder.finish`) of `instance`.
+     */
+    constructor(doc, instance, range) {
+        super("Document", instance);
         this.#doc = doc;
         this.#range = range;
+        watch(this, "Document");
     }
     /**
      * Opens a document whose bytes are fetched range by range ({@link httpRangeSource},
@@ -143,9 +160,11 @@ export class Document {
         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 instance = readingModule();
+        const sparse = instance.call((wasm) => new wasm.WasmSparseSource(src.size, budget));
         const state = {
+            instance,
+            generation: instance.generation,
             sparse,
             source: src,
             blockSize: blockSize ?? src.blockSize ?? 4096,
@@ -156,7 +175,10 @@ export class Document {
         try {
             for (let i = 0;; i++) {
                 try {
-                    return await settle(state, () => new Document(guard(() => wasm.WasmDocument.openSource(sparse, attempts[i])), state), signal);
+                    return await settle(state, () => new Document(instance.call((wasm) => {
+                        instance.check(state.generation, "Document");
+                        return wasm.WasmDocument.openSource(sparse, attempts[i]);
+                    }), instance, state), signal);
                 }
                 catch (e) {
                     if (!tryNext(e, i, attempts.length))
@@ -165,8 +187,10 @@ export class Document {
             }
         }
         catch (e) {
-            // Nothing holds the fetched bytes now: free them at once rather than at collection.
-            sparse.free();
+            // Nothing holds the fetched bytes now: free them at once rather than at collection, unless
+            // their instance was replaced (a trap, or reset() during a fetch).
+            if (instance.owns(state.generation))
+                sparse.free();
             throw e;
         }
     }
@@ -188,6 +212,7 @@ export class Document {
      * @throws what `f` throws, and as {@link Document.openRange}.
      */
     async ensure(f, options = {}) {
+        this.assertLive();
         return this.#range === undefined ? f() : settle(this.#range, f, options.signal);
     }
     /**
@@ -205,12 +230,12 @@ export class Document {
      *   `strict`, …; `unknown-option` / `invalid-argument` for bad options; `not-initialized`.
      */
     static open(bytes, options) {
-        const wasm = readingModule();
+        const instance = 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])));
+                return new Document(instance.call((wasm) => wasm.WasmDocument.openBytes(data, attempts[i])), instance);
             }
             catch (e) {
                 if (!tryNext(e, i, attempts.length))
@@ -224,15 +249,16 @@ export class Document {
      * module; save and reopen it to move it.
      */
     get canExtractText() {
+        this.assertLive();
         return extractsText(this.#doc);
     }
     /** The number of pages. @throws {@link LaminaPdfError} reading errors. */
     get pageCount() {
-        return guard(() => this.#doc.pageCount());
+        return this.call(() => 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());
+        return this.call(() => this.#doc.pageInfos());
     }
     /**
      * Page `index`'s facts.
@@ -240,7 +266,7 @@ export class Document {
      * @throws {@link LaminaPdfError} `page-index-out-of-range`.
      */
     pageInfo(index) {
-        return guard(() => this.#doc.pageInfo(index));
+        return this.call(() => this.#doc.pageInfo(index));
     }
     /**
      * A handle on page `index` that follows the page by its ID.
@@ -248,7 +274,7 @@ export class Document {
      * @throws {@link LaminaPdfError} `page-index-out-of-range`.
      */
     page(index) {
-        return new PageRef(guard(() => this.#doc.page(index)));
+        return new PageRef(this.call(() => this.#doc.page(index)), this, this.instance);
     }
     /**
      * A handle on the page with `id` (`p12.0`).
@@ -256,31 +282,125 @@ export class Document {
      * @throws {@link LaminaPdfError} `invalid-argument`, `unknown-page`.
      */
     pageById(id) {
-        return new PageRef(guard(() => this.#doc.pageById(id)));
+        return new PageRef(this.call(() => this.#doc.pageById(id)), this, this.instance);
+    }
+    /**
+     * The outline (bookmarks): its top-level items in order, each with its children, and where
+     * each goes as a page and a view in page space; empty without one. Needs a document opened
+     * while the extract or text module was loaded.
+     *
+     * @throws {@link LaminaPdfError} `extract-module-not-loaded` for a document opened in the base
+     *   module; reading errors (`data-pending` for a range document: use `ensure`).
+     */
+    outline() {
+        return this.call(() => this.#extracting("doc.outline()").outline());
+    }
+    /**
+     * Where the named destination `name` goes (the names a link or a `#nameddest=` address uses),
+     * or `undefined` when the document has none by that name. Needs a document opened while the
+     * extract or text module was loaded.
+     *
+     * @throws {@link LaminaPdfError} as {@link Document.outline}.
+     */
+    namedDestination(name) {
+        return this.call(() => this.#extracting("doc.namedDestination()").namedDestination(name));
+    }
+    /**
+     * The document's text for retrieval and LLMs: Markdown or plain text in reading order, the
+     * `laminapdf.extract/1` JSON with a box for every block, or chunks sized for retrieval. Tables
+     * drawn with lines come out as tables, and text a reader can't see is left out. Needs a
+     * document opened while the extract or text module was loaded.
+     *
+     * @example
+     * ```ts
+     * await init({ extract: true });
+     * const doc = Document.open(bytes);
+     * const markdown = doc.extract({ format: "markdown" });
+     * const chunks = doc.extract({ format: "chunks", chunk: { maxTokens: 400 } });
+     * ```
+     * @returns a string for `"markdown"` and `"text"`, an {@link Extraction} for `"json"`,
+     *   {@link Chunk}s for `"chunks"`.
+     * @throws {@link LaminaPdfError} `extract-module-not-loaded` for a document opened in the base
+     *   module; `page-index-out-of-range`; `unknown-option` (with `didYouMean`) / `invalid-argument`
+     *   for bad options; reading errors (`data-pending` for a range document: use `ensure`).
+     */
+    extract(options) {
+        this.assertLive();
+        const doc = this.#doc;
+        if (typeof doc.extract !== "function") {
+            throw packageError("extract-module-not-loaded", "doc.extract() needs a document opened while the extract or text module was loaded");
+        }
+        const extract = doc.extract.bind(doc);
+        return parseExtract(options.format, this.call(() => extract(options)));
+    }
+    /**
+     * An extraction stepped a page at a time, for models the host runs: each step that needs a
+     * model's result stops with a `request` (the page and resolution to render), answered with
+     * {@link ExtractJob.provide}. {@link extractWithModels} loops one for async models. Needs a
+     * document opened while the extract or text module was loaded.
+     *
+     * @throws {@link LaminaPdfError} as {@link Document.extract}.
+     */
+    extractJob(options) {
+        this.assertLive();
+        const doc = this.#doc;
+        if (typeof doc.extractJob !== "function") {
+            throw packageError("extract-module-not-loaded", "doc.extractJob() needs a document opened while the extract or text module was loaded");
+        }
+        const extractJob = doc.extractJob.bind(doc);
+        return new ExtractJob(this.call(() => extractJob(options)), options.format, this, this.instance);
     }
     /** The Info dictionary's text entries (document text). @throws {@link LaminaPdfError} reading errors. */
     get info() {
-        return guard(() => this.#doc.info());
+        return this.call(() => this.#doc.info());
+    }
+    /**
+     * Whether the document says it is tagged (`/MarkInfo /Marked true`); it doesn't check the tree.
+     * Needs a document opened while the extract or text module was loaded, as `page.text()` does.
+     * @throws {@link LaminaPdfError} `extract-module-not-loaded`; reading errors.
+     */
+    get isTagged() {
+        return this.call(() => this.#extracting("doc.isTagged").isTagged());
+    }
+    /**
+     * The structure tree's top-level elements in reading order, or `undefined` for a document
+     * without one. A text run's `mcid` (on {@link PageTextRun}) links it to the element whose
+     * `{ type: "content", page, mcid }` kid names it. Needs the extract or text module, as
+     * `page.text()` does.
+     * @throws {@link LaminaPdfError} `extract-module-not-loaded`; reading errors.
+     */
+    structureTree() {
+        return this.call(() => this.#extracting("doc.structureTree()").structureTree());
+    }
+    /** The document as the extract module made it, or `extract-module-not-loaded` naming `what`. */
+    #extracting(what) {
+        const doc = this.#doc;
+        if (typeof doc.structureTree !== "function" || typeof doc.isTagged !== "function") {
+            throw packageError("extract-module-not-loaded", `${what} needs a document opened while the extract or text module was loaded`);
+        }
+        return doc;
     }
     /** 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);
+        return this.call(() => {
+            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();
-        }
+            finally {
+                cursor.free();
+            }
+        });
     }
     /** Whether there are changes no save has written yet. */
     get hasUnsavedChanges() {
-        return this.#doc.hasUnsavedChanges();
+        return this.call(() => this.#doc.hasUnsavedChanges());
     }
     /**
      * Applies `ops` in order as one transaction: all of them, or none.
@@ -291,7 +411,7 @@ export class Document {
      */
     apply(ops) {
         this.#notInTransaction("apply");
-        return guard(() => this.#doc.apply(ops));
+        return this.call(() => this.#doc.apply(ops));
     }
     /**
      * Applies an op log (`{ v: 1, ops }`, as JSON text or an object) as one transaction.
@@ -301,7 +421,7 @@ export class Document {
     applyLog(log) {
         this.#notInTransaction("applyLog");
         const json = typeof log === "string" ? log : JSON.stringify(log);
-        return guard(() => this.#doc.applyLog(json));
+        return this.call(() => this.#doc.applyLog(json));
     }
     /**
      * Runs `edit` with a transaction handle and applies what it collected as one transaction
@@ -323,6 +443,7 @@ export class Document {
      * ```
      */
     transact(edit) {
+        this.assertLive();
         this.#notInTransaction("transact");
         this.#transacting = true;
         const tx = new Transaction();
@@ -358,7 +479,7 @@ export class Document {
      */
     undo() {
         this.#notInTransaction("undo");
-        return guard(() => this.#doc.undo());
+        return this.call(() => this.#doc.undo());
     }
     /**
      * Redoes the newest undone transaction.
@@ -368,7 +489,7 @@ export class Document {
      */
     redo() {
         this.#notInTransaction("redo");
-        return guard(() => this.#doc.redo());
+        return this.call(() => this.#doc.redo());
     }
     /**
      * Saves and rebases onto the output (later edits and saves build on it).
@@ -387,7 +508,7 @@ export class Document {
      */
     saveWithReport(options) {
         this.#notInTransaction("save");
-        return guard(() => this.#doc.save(options));
+        return this.call(() => this.#doc.save(options));
     }
     /**
      * A save as a job stepped by the caller (to keep a UI responsive).
@@ -396,7 +517,7 @@ export class Document {
      */
     saveJob(options) {
         this.#notInTransaction("saveJob");
-        return new SaveJob(guard(() => this.#doc.saveJob(options)));
+        return new SaveJob(this.call(() => this.#doc.saveJob(options)), this, this.instance);
     }
     /**
      * Rebases onto `bytes`, the output of a save whose rebase failed (`not-rebased`).
@@ -405,23 +526,12 @@ export class Document {
      */
     rebase(bytes) {
         this.#notInTransaction("rebase");
-        guard(() => this.#doc.rebase(bytes));
+        this.call(() => 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;
+    release() {
         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