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

package/docs/api/README.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 **@laminapdf/sdk**
@@ -12,6 +12,7 @@ version: "0.2.0-alpha.3"
 
 - [Builder](classes/Builder.md)
 - [Document](classes/Document.md)
+- [ExtractJob](classes/ExtractJob.md)
 - [Font](classes/Font.md)
 - [Image](classes/Image.md)
 - [LaminaPdfError](classes/LaminaPdfError.md)
@@ -33,10 +34,16 @@ version: "0.2.0-alpha.3"
 - [ExtractOptions](interfaces/ExtractOptions.md)
 - [ExtractResult](interfaces/ExtractResult.md)
 - [FontInfo](interfaces/FontInfo.md)
+- [HostModels](interfaces/HostModels.md)
 - [HttpRangeOptions](interfaces/HttpRangeOptions.md)
 - [InitOptions](interfaces/InitOptions.md)
+- [LayoutRegion](interfaces/LayoutRegion.md)
 - [Leak](interfaces/Leak.md)
 - [Location](interfaces/Location.md)
+- [ModelInfo](interfaces/ModelInfo.md)
+- [ModelRequest](interfaces/ModelRequest.md)
+- [Models](interfaces/Models.md)
+- [OcrWord](interfaces/OcrWord.md)
 - [OpenOptions](interfaces/OpenOptions.md)
 - [OpLog](interfaces/OpLog.md)
 - [PageTextOptions](interfaces/PageTextOptions.md)
@@ -76,6 +83,8 @@ version: "0.2.0-alpha.3"
 - [ExtractedSource](type-aliases/ExtractedSource.md)
 - [ExtractFormat](type-aliases/ExtractFormat.md)
 - [Extraction](type-aliases/Extraction.md)
+- [ExtractJobOptions](type-aliases/ExtractJobOptions.md)
+- [ExtractStep](type-aliases/ExtractStep.md)
 - [FillRule](type-aliases/FillRule.md)
 - [Fit](type-aliases/Fit.md)
 - [Flags](type-aliases/Flags.md)
@@ -90,8 +99,10 @@ version: "0.2.0-alpha.3"
 - [LineJoin](type-aliases/LineJoin.md)
 - [LinkTarget](type-aliases/LinkTarget.md)
 - [Metadata](type-aliases/Metadata.md)
+- [ModelResult](type-aliases/ModelResult.md)
 - [Op](type-aliases/Op.md)
 - [OutlineEntry](type-aliases/OutlineEntry.md)
+- [OutlineNode](type-aliases/OutlineNode.md)
 - [Overflow](type-aliases/Overflow.md)
 - [PageInfo](type-aliases/PageInfo.md)
 - [PageLabel](type-aliases/PageLabel.md)
@@ -102,6 +113,7 @@ version: "0.2.0-alpha.3"
 - [ReadingOrder](type-aliases/ReadingOrder.md)
 - [Rect](type-aliases/Rect.md)
 - [Region](type-aliases/Region.md)
+- [RegionLabel](type-aliases/RegionLabel.md)
 - [RenderMode](type-aliases/RenderMode.md)
 - [Rotation](type-aliases/Rotation.md)
 - [SaveOptions](type-aliases/SaveOptions.md)
@@ -111,11 +123,17 @@ version: "0.2.0-alpha.3"
 - [Standard14](type-aliases/Standard14.md)
 - [StructRef](type-aliases/StructRef.md)
 - [StructSource](type-aliases/StructSource.md)
+- [StructureKid](type-aliases/StructureKid.md)
+- [StructureNode](type-aliases/StructureNode.md)
 - [TableDetector](type-aliases/TableDetector.md)
 - [TableMode](type-aliases/TableMode.md)
 - [TableScope](type-aliases/TableScope.md)
 - [Tag](type-aliases/Tag.md)
 - [TagName](type-aliases/TagName.md)
+- [Target](type-aliases/Target.md)
+- [TargetView](type-aliases/TargetView.md)
+- [TextLayer](type-aliases/TextLayer.md)
+- [TextLayerStatus](type-aliases/TextLayerStatus.md)
 - [TextLayout](type-aliases/TextLayout.md)
 - [TextRange](type-aliases/TextRange.md)
 - [TextRunInfo](type-aliases/TextRunInfo.md)
@@ -134,6 +152,7 @@ version: "0.2.0-alpha.3"
 ## Functions
 
 - [callbackSource](functions/callbackSource.md)
+- [extractWithModels](functions/extractWithModels.md)
 - [httpRangeSource](functions/httpRangeSource.md)
 - [init](functions/init.md)
 - [isExtractLoaded](functions/isExtractLoaded.md)

package/docs/api/classes/Builder.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/Document.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)
@@ -112,6 +112,25 @@ Whether `free()` ran on this handle or its parent.
 
 ***
 
+### isTagged
+
+#### Get Signature
+
+> **get** **isTagged**(): `boolean`
+
+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
+
+[LaminaPdfError](LaminaPdfError.md) `extract-module-not-loaded`; reading errors.
+
+##### Returns
+
+`boolean`
+
+***
+
 ### owned
 
 #### Get Signature
@@ -386,6 +405,37 @@ const chunks = doc.extract({ format: "chunks", chunk: { maxTokens: 400 } });
 
 ***
 
+### extractJob()
+
+> **extractJob**\<`F`\>(`options`): [`ExtractJob`](ExtractJob.md)\<`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
+[ExtractJob.provide](ExtractJob.md#provide). [extractWithModels](../functions/extractWithModels.md) loops one for async models. Needs a
+document opened while the extract or text module was loaded.
+
+#### Type Parameters
+
+##### F
+
+`F` *extends* [`ExtractFormat`](../type-aliases/ExtractFormat.md)
+
+#### Parameters
+
+##### options
+
+[`ExtractJobOptions`](../type-aliases/ExtractJobOptions.md)\<`F`\>
+
+#### Returns
+
+[`ExtractJob`](ExtractJob.md)\<`F`\>
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) as [Document.extract](#extract).
+
+***
+
 ### free()
 
 > **free**(): `void`
@@ -404,6 +454,49 @@ calls this at the end of the block.
 
 ***
 
+### namedDestination()
+
+> **namedDestination**(`name`): `TargetJs` \| `undefined`
+
+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.
+
+#### Parameters
+
+##### name
+
+`string`
+
+#### Returns
+
+`TargetJs` \| `undefined`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) as [Document.outline](#outline).
+
+***
+
+### outline()
+
+> **outline**(): `OutlineNodeJs`[]
+
+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.
+
+#### Returns
+
+`OutlineNodeJs`[]
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `extract-module-not-loaded` for a document opened in the base
+  module; reading errors (`data-pending` for a range document: use `ensure`).
+
+***
+
 ### page()
 
 > **page**(`index`): [`PageRef`](PageRef.md)
@@ -604,6 +697,25 @@ As [Document.save](#save), with the save's report (mode used, bytes written, ren
 
 ***
 
+### structureTree()
+
+> **structureTree**(): `StructureNodeJs`[] \| `undefined`
+
+The structure tree's top-level elements in reading order, or `undefined` for a document
+without one. A text run's `mcid` (on [PageTextRun](PageTextRun.md)) links it to the element whose
+`{ type: "content", page, mcid }` kid names it. Needs the extract or text module, as
+`page.text()` does.
+
+#### Returns
+
+`StructureNodeJs`[] \| `undefined`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `extract-module-not-loaded`; reading errors.
+
+***
+
 ### transact()
 
 > **transact**\<`T`\>(`edit`): `T`

package/docs/api/classes/ExtractJob.md

@@ -0,0 +1,236 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / ExtractJob
+
+# Class: ExtractJob\<F\>
+
+An extraction in progress, from [Document.extractJob](Document.md#extractjob). It holds WebAssembly memory and is
+freed with its document, or earlier with `free()` or `using`.
+
+## Extends
+
+- `Handle`\<`BaseGlue`\>
+
+## Type Parameters
+
+### F
+
+`F` *extends* [`ExtractFormat`](../type-aliases/ExtractFormat.md) = [`ExtractFormat`](../type-aliases/ExtractFormat.md)
+
+## Accessors
+
+### instance
+
+#### Get Signature
+
+> **get** `protected` **instance**(): `Instance`\<`G`\>
+
+The instance this handle lives in (for the handles it makes).
+
+##### Returns
+
+`Instance`\<`G`\>
+
+#### Inherited from
+
+`Handle.instance`
+
+***
+
+### isFreed
+
+#### Get Signature
+
+> **get** `protected` **isFreed**(): `boolean`
+
+Whether `free()` ran on this handle or its parent.
+
+##### Returns
+
+`boolean`
+
+#### Inherited from
+
+`Handle.isFreed`
+
+***
+
+### owned
+
+#### Get Signature
+
+> **get** `protected` **owned**(): `boolean`
+
+Whether the handle's raw objects can be freed: its instance is current and hasn't trapped.
+
+##### Returns
+
+`boolean`
+
+#### Inherited from
+
+`Handle.owned`
+
+## Methods
+
+### \[dispose\]()
+
+> **\[dispose\]**(): `void`
+
+Frees the handle at the end of a `using` block (an alias of `free()`).
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+`Handle.[dispose]`
+
+***
+
+### assertLive()
+
+> `protected` **assertLive**(): `void`
+
+#### Returns
+
+`void`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `disposed` after `free()` (here or on the parent);
+  `instance-reset` when the instance was replaced (a trapped one is replaced first).
+
+#### Inherited from
+
+`Handle.assertLive`
+
+***
+
+### call()
+
+> `protected` **call**\<`T`\>(`f`): `T`
+
+Runs `f` (calls into the glue) on this live handle; see Instance.call.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### f
+
+(`glue`) => `T`
+
+#### Returns
+
+`T`
+
+#### Inherited from
+
+`Handle.call`
+
+***
+
+### cancel()
+
+> **cancel**(): `void`
+
+Stops the job: its next step fails with `cancelled`.
+
+#### Returns
+
+`void`
+
+***
+
+### free()
+
+> **free**(): `void`
+
+Frees the handle's memory now; without it, the garbage collector frees it later. A second
+call does nothing, and any other call afterwards throws `disposed`. Prefer `using`, which
+calls this at the end of the block.
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+`Handle.free`
+
+***
+
+### provide()
+
+> **provide**(`result`): `void`
+
+Hands the job the result of its open request.
+
+#### Parameters
+
+##### result
+
+[`ModelResult`](../type-aliases/ModelResult.md)
+
+#### Returns
+
+`void`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `model-result-unexpected` when nothing was asked for or `result`
+  is the other model's; `invalid-argument` / `unknown-option` for a malformed result.
+
+***
+
+### release()
+
+> `protected` **release**(): `void`
+
+Frees the WebAssembly side; called at most once, and only while [owned](#owned).
+
+#### Returns
+
+`void`
+
+#### Overrides
+
+`Handle.release`
+
+***
+
+### step()
+
+> **step**(`budget?`): [`ExtractStep`](../type-aliases/ExtractStep.md)\<`F`\>
+
+Extracts up to `budget` pages. While a model's result is awaited, the step returns
+`{ state: "progress", phase: "model", request }` and does nothing more until
+[provide](#provide) answers it.
+
+#### Parameters
+
+##### budget?
+
+`number` = `1`
+
+#### Returns
+
+[`ExtractStep`](../type-aliases/ExtractStep.md)\<`F`\>
+
+progress, or `{ state: "done", output }` with the output in the job's format.
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `cancelled`, `document-changed`, `job-finished`, the reading errors.

package/docs/api/classes/Font.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/Image.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/LaminaPdfError.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/Page.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/PageRef.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/PageText.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/PageTextRun.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/PendingPath.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/SaveJob.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/Surface.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)
@@ -20,13 +20,15 @@ geometry is reported by [Page.finish](Page.md#finish) (`invalid-geometry`).
 > **artifact**(`kind`, `draw`): `this`
 
 Draws what `draw` draws as an artifact: decoration, running heads and footers, backgrounds;
-content outside the structure tree.
+content outside the structure tree. `"header"`, `"footer"` and `"watermark"` are pagination
+artifacts that also say which (`/Subtype`), a header attached to the page's top edge and a
+footer to its bottom (`/Attached`).
 
 #### Parameters
 
 ##### kind
 
-`"layout"` \| `"page"` \| `"pagination"` \| `"background"`
+`"layout"` \| `"page"` \| `"pagination"` \| `"background"` \| `"header"` \| `"footer"` \| `"watermark"`
 
 ##### draw
 
@@ -273,7 +275,8 @@ Draws `text`: shaped, bidi-resolved, one line per line break (needs the text mod
 
 `TextRunJs`
 
-what the run measures.
+what the run measures, with `bottom`: where the next element can start (the next text box's top), the
+  descent below the last line that draws something, before the surface's transform; left out when nothing is.
 
 #### Throws
 
@@ -301,7 +304,9 @@ Lays `text` out in `options.box`, breaking lines at Unicode line-break opportuni
 
 `TextLayoutJs`
 
-the lines drawn and where the overflow starts (UTF-16 offsets).
+the lines drawn, where the overflow starts (UTF-16 offsets; test it with `!== undefined`, as `0` means no
+  line fitted) and `bottom`: the last line that draws something, before the surface's transform; left out when none
+  does.
 
 #### Throws
 

package/docs/api/classes/Transaction.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/functions/callbackSource.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/functions/extractWithModels.md

@@ -0,0 +1,70 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / extractWithModels
+
+# Function: extractWithModels()
+
+> **extractWithModels**\<`F`\>(`doc`, `options`, `models`, `__namedParameters?`): `Promise`\<[`ExtractResult`](../interfaces/ExtractResult.md)\[`F`\]\>
+
+Runs an extraction whose models the host runs asynchronously: steps a job, and for each
+request awaits the matching function of `models`, then hands its result back.
+
+## Type Parameters
+
+### F
+
+`F` *extends* [`ExtractFormat`](../type-aliases/ExtractFormat.md)
+
+## Parameters
+
+### doc
+
+[`Document`](../classes/Document.md)
+
+### options
+
+[`ExtractJobOptions`](../type-aliases/ExtractJobOptions.md)\<`F`\>
+
+### models
+
+[`HostModels`](../interfaces/HostModels.md)
+
+### \_\_namedParameters?
+
+#### budget?
+
+`number` = `16`
+
+#### signal?
+
+`AbortSignal`
+
+## Returns
+
+`Promise`\<[`ExtractResult`](../interfaces/ExtractResult.md)\[`F`\]\>
+
+## Example
+
+```ts
+const json = await extractWithModels(
+  doc,
+  { format: "json", models: { layout: { name: "my-layout", version: "1", sha256, licence: "Apache-2.0" } } },
+  { layout: async ({ page, dpi }) => myModel.detect(await render(page, dpi)) },
+);
+```
+On a document opened with `Document.openRange`, a step that needs bytes not yet fetched ends
+the job with `data-pending`, as every error ends a job; fetch the file first (`await
+doc.ensure(() => doc.pages)` reads only the page tree, so read the whole file for a long
+extraction), or wrap the call in `doc.ensure`, which runs it again, models included.
+
+## Throws
+
+[LaminaPdfError](../classes/LaminaPdfError.md) as [ExtractJob.step](../classes/ExtractJob.md#step); `invalid-argument` when
+  `options.models` names a model `models` has no function for; `cancelled` once `signal`
+  aborts, also when the model rejects because of it (the model's error is the `cause`).

package/docs/api/functions/httpRangeSource.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)
@@ -19,7 +19,7 @@ its `Last-Modified`); a response whose `ETag`, `Last-Modified` or total size dif
 with `source-changed`. A server that ignores
 `Range` (it answers `200`) is read with that one full download.
 
-The server must allow `Range` (across origins: `Access-Control-Allow-Headers: Range` and
+The server must allow `Range` (across origins: `Access-Control-Allow-Headers: Range, If-Range` and
 `Access-Control-Expose-Headers: Content-Range, Content-Length, ETag`) and must not compress
 the response.
 

package/docs/api/functions/init.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.4"
 ---
 
 [**@laminapdf/sdk**](../README.md)