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

package/dist/lamina_pdf_extract.d.ts

@@ -1,7 +1,7 @@
 /* tslint:disable */
 /* eslint-disable */
 
-/** A page's text as `WasmPage.text` returns it (B9c). */
+/** A page's text as `WasmPage.text` returns it. */
 export interface PageTextJs {
     /** The text by line, in content order (runs on one baseline, joined; trimmed). */
     lines: string[];
@@ -50,11 +50,35 @@ export interface ProgressJs {
      */
     total?: number;
     /**
-     * The phase (`parse`, `layout`, `extract`, `render`, `write`, `sign`).
+     * The phase (`parse`, `layout`, `extract`, `render`, `write`, `sign`, `model`).
      */
     phase: string;
 }
 
+/**
+ * A kid of a structure element: an element, or marked content on a page.
+ */
+export type StructureKidJs = ({ type: "node" } & StructureNodeJs) | { type: "content"; page: number; mcid: number };
+
+/**
+ * A layout region, its box `[x, y, width, height]` in top-left points (ADR 0027), as the
+ * output's boxes are.
+ */
+export interface RegionInit {
+    /**
+     * What it is.
+     */
+    label: RegionLabelName;
+    /**
+     * `[x, y, width, height]`.
+     */
+    bbox: [number, number, number, number];
+    /**
+     * The model's confidence, 0 to 1.
+     */
+    score: number;
+}
+
 /**
  * A list of ops with its schema version ([ADR 0006] §6): `{ "v": 1, "ops": [ … ] }`, used
  * for saved op logs, batch processing and sync messages. Unknown fields are rejected, and so
@@ -76,11 +100,114 @@ export interface OpLog {
     ops: Op[];
 }
 
+/**
+ * A model result the job waits for.
+ */
+export interface ModelRequestJs {
+    /**
+     * `layout` (regions) or `ocr` (words).
+     */
+    kind: string;
+    /**
+     * The 0-based page to render.
+     */
+    page: number;
+    /**
+     * The resolution to render it at.
+     */
+    dpi: number;
+    /**
+     * OCR's languages (BCP 47); empty for the engine's default.
+     */
+    langs: string[];
+}
+
+/**
+ * A model the host runs, as the output's `generator.models` names it.
+ */
+export interface ModelInfoInit {
+    /**
+     * Its name.
+     */
+    name: string;
+    /**
+     * Its version or revision.
+     */
+    version: string;
+    /**
+     * Its weights' SHA-256, lowercase hex.
+     */
+    sha256: string;
+    /**
+     * Its weights' SPDX licence.
+     */
+    licence: string;
+}
+
+/**
+ * A page and how to show it.
+ */
+export interface TargetJs {
+    /**
+     * The page's 0-based index.
+     */
+    page: number;
+    /**
+     * How to show it, in page space.
+     */
+    view: TargetViewJs;
+}
+
 /**
  * A page-label numbering style.
  */
 export type LabelStyleInit = "decimal" | "upperRoman" | "lowerRoman" | "upperLetters" | "lowerLetters";
 
+/**
+ * A region's kind.
+ */
+export type RegionLabelName = "text" | "title" | "section-header" | "list-item" | "table" | "picture" | "caption" | "footnote" | "formula" | "page-header" | "page-footer" | "other";
+
+/**
+ * A step's progress, and the model result the job waits for, if any.
+ */
+export interface ExtractProgressJs {
+    /**
+     * Pages done.
+     */
+    done: number;
+    /**
+     * Pages asked for.
+     */
+    total?: number;
+    /**
+     * `extract`, or `model` while a request is open.
+     */
+    phase: string;
+    /**
+     * The result the job waits for: hand it to `provide`.
+     */
+    request?: ModelRequestJs;
+}
+
+/**
+ * An OCR word, its box as a region's.
+ */
+export interface WordInit {
+    /**
+     * Its text.
+     */
+    text: string;
+    /**
+     * `[x, y, width, height]`.
+     */
+    bbox: [number, number, number, number];
+    /**
+     * The engine's confidence, 0 to 1.
+     */
+    confidence: number;
+}
+
 /**
  * An attached file's options.
  */
@@ -181,6 +308,11 @@ export interface SetInfo {
  */
 export type FitInit = { type: "page" } | { type: "width"; top?: number } | { type: "height"; left?: number } | { type: "xyz"; left?: number; top?: number; zoom?: number } | { type: "rect"; x: number; y: number; width: number; height: number } | { type: "bounds" };
 
+/**
+ * How a target shows its page, in page space; an unset coordinate is left out.
+ */
+export type TargetViewJs = { kind: "at"; x?: number; y?: number; zoom?: number } | { kind: "fit" } | { kind: "fit-width"; y?: number } | { kind: "fit-height"; x?: number } | { kind: "fit-rect"; x0: number; y0: number; x1: number; y1: number };
+
 /**
  * How a viewer lays pages out.
  */
@@ -196,6 +328,24 @@ export type AfRelationshipInit = "source" | "data" | "alternative" | "supplement
  */
 export type UndoOutcomeJs = "applied" | "partial" | "skipped";
 
+/**
+ * How the Markdown is cut into chunks.
+ */
+export interface ChunkInit {
+    /**
+     * A chunk's budget in approximate tokens (characters / 4); 512 by default.
+     */
+    maxTokens?: number;
+    /**
+     * Approximate tokens of whole blocks repeated from the chunk before; 0 by default.
+     */
+    overlap?: number;
+    /**
+     * Where chunks may start; `"headings"` by default.
+     */
+    splitOn?: SplitOnName;
+}
+
 /**
  * How viewers present the document when it opens.
  */
@@ -219,6 +369,32 @@ export interface ViewerPreferencesInit {
  */
 export type RenumberJs = "keep" | "compact";
 
+/**
+ * One element of the structure tree (`laminapdf::StructureNode`; its strings are document text).
+ */
+export interface StructureNodeJs {
+    /**
+     * Its standard structure type (`H1`, `P`, `LI`, `Figure` …), through the `/RoleMap`.
+     */
+    kind: string;
+    /**
+     * `/Alt`: alternate text.
+     */
+    alt?: string;
+    /**
+     * `/Lang`: the language of its content.
+     */
+    lang?: string;
+    /**
+     * `/ActualText`: the text its content stands for.
+     */
+    actualText?: string;
+    /**
+     * Its kids, in reading order.
+     */
+    kids: StructureKidJs[];
+}
+
 /**
  * One outline item and its children.
  */
@@ -253,6 +429,28 @@ export interface OutlineEntryInit {
     italic?: boolean;
 }
 
+/**
+ * One outline item.
+ */
+export interface OutlineNodeJs {
+    /**
+     * Its title (document text).
+     */
+    title: string;
+    /**
+     * Whether it opens with its children shown.
+     */
+    open: boolean;
+    /**
+     * Where it goes, when its destination names a page of this document.
+     */
+    target?: TargetJs;
+    /**
+     * Its children, in order.
+     */
+    children: OutlineNodeJs[];
+}
+
 /**
  * One page's facts (`laminapdf::PageInfo`).
  */
@@ -306,7 +504,7 @@ export interface PageLabelInit {
 }
 
 /**
- * One text run (`laminapdf::extract::TextRun`): glyphs of one font, size, direction and marked
+ * One text run (`laminapdf::extract::PageTextRun`): glyphs of one font, size, direction and marked
  * content on one baseline, in logical order.
  */
 export interface TextRunJs {
@@ -348,6 +546,48 @@ export interface TextRunJs {
     glyphs: [number, number];
 }
 
+/**
+ * Options for `WasmDocument.extract`.
+ */
+export interface ExtractInit {
+    /**
+     * What to return.
+     */
+    format: ExtractFormat;
+    /**
+     * The 0-based page indices to extract, in this order; every page by default.
+     */
+    pages?: number[];
+    /**
+     * Where the reading order comes from; `"auto"` by default.
+     */
+    readingOrder?: ReadingOrderName;
+    /**
+     * What happens to hidden text.
+     */
+    drop?: DropInit;
+    /**
+     * Which table detectors run; `"lattice"` by default.
+     */
+    tables?: TableModeName;
+    /**
+     * Join words hyphenated across lines; on by default.
+     */
+    dehyphenate?: boolean;
+    /**
+     * Write `<!-- page N -->` before each page's first block (Markdown, chunks and JSON).
+     */
+    pageMarkers?: boolean;
+    /**
+     * How chunks are cut (`chunks`, and `json` to include them).
+     */
+    chunk?: ChunkInit;
+    /**
+     * Models the host runs (`extractJob` only): the job asks for their results.
+     */
+    models?: ModelsInit;
+}
+
 /**
  * Options for `WasmDocument.openBytes`.
  */
@@ -553,6 +793,28 @@ export interface MetadataInit {
  */
 export type ModificationClass = "metadata" | "formFill" | "annotation" | "signature" | "pageStructure" | "content" | "document";
 
+/**
+ * The models the host runs for an extraction job.
+ */
+export interface ModelsInit {
+    /**
+     * A layout model: every page's regions are asked for.
+     */
+    layout?: ModelInfoInit;
+    /**
+     * An OCR engine: pages with no visible text are asked for.
+     */
+    ocr?: ModelInfoInit;
+    /**
+     * The resolution pages are asked for at; 150 by default.
+     */
+    dpi?: number;
+    /**
+     * OCR's languages (BCP 47).
+     */
+    langs?: string[];
+}
+
 /**
  * The pages an edit touched.
  */
@@ -573,6 +835,16 @@ export type PageModeInit = "none" | "outlines" | "thumbnails" | "fullScreen" | "
  */
 export type SaveModeJs = "auto" | "incremental" | "fullRewrite";
 
+/**
+ * What `WasmDocument.extract` returns.
+ */
+export type ExtractFormat = "markdown" | "json" | "text" | "chunks";
+
+/**
+ * What `provide` takes.
+ */
+export type ModelResultInit = { kind: "layout"; regions: RegionInit[] } | { kind: "ocr"; words: WordInit[] };
+
 /**
  * What a save wrote (`laminapdf::SaveReport`).
  */
@@ -608,11 +880,41 @@ export interface SaveReportJs {
  */
 export type OutputJs = "whole" | "appendedOnly";
 
+/**
+ * What happens to hidden text and page furniture.
+ */
+export interface DropInit {
+    /**
+     * Keep each dropped run's text in its `dropped` entry (JSON only), for auditing a file.
+     */
+    keepSpans?: boolean;
+    /**
+     * Drop running headers, footers, page numbers and artifact-marked text too, listing them
+     * in `dropped`; on by default.
+     */
+    furniture?: boolean;
+}
+
 /**
  * Where a link or outline item goes.
  */
 export type LinkTargetInit = { type: "uri"; uri: string } | { type: "page"; index: number; fit?: FitInit } | { type: "named"; name: string };
 
+/**
+ * Where chunks may start.
+ */
+export type SplitOnName = "headings" | "blocks" | "pages";
+
+/**
+ * Where the reading order comes from.
+ */
+export type ReadingOrderName = "auto" | "tagged" | "layout" | "content-stream";
+
+/**
+ * Which table detectors run.
+ */
+export type TableModeName = "off" | "lattice" | "lattice-and-stream";
+
 /**
  * `Limits` with every field optional (ADR 0003 §3; names as in Rust, camelCase).
  */
@@ -782,6 +1084,25 @@ export class WasmDocument {
      * error (nothing is applied).
      */
     apply(ops: Op[]): EditedJs;
+    /**
+     * An extraction stepped a page at a time, whose models the host runs: each step returns
+     * its progress, with the result it waits for under `request` (render that page at `dpi`,
+     * run the model, hand the result to `provide`), and once every page is done, the output in
+     * `options.format` (the extract and text modules).
+     *
+     * # Errors
+     * As `extract`, for the options and the pages asked for.
+     */
+    extractJob(options: ExtractInit): WasmExtractJob;
+    /**
+     * The document's text for retrieval and LLMs, as one string: Markdown, plain text, the
+     * `laminapdf.extract/1` JSON, or the chunks as a JSON array (the extract and text modules).
+     *
+     * # Errors
+     * `page-index-out-of-range` for a page in `pages` past the end; `data-pending` and the
+     * reading errors; `unknown-option` / `invalid-argument` for bad options.
+     */
+    extract(options: ExtractInit): string;
     /**
      * Whether there are changes no save has written yet.
      */
@@ -793,6 +1114,21 @@ export class WasmDocument {
      * Reading errors.
      */
     info(): DocumentInfoJs;
+    /**
+     * Whether the document says it is tagged (`/MarkInfo /Marked true`; the extract and text modules).
+     *
+     * # Errors
+     * Reading errors.
+     */
+    isTagged(): boolean;
+    /**
+     * The named destination `name`, or `undefined` when the document has none by that name or
+     * it names no page here (the extract and text modules).
+     *
+     * # Errors
+     * `data-pending` and the reading errors.
+     */
+    namedDestination(name: string): TargetJs | undefined;
     /**
      * Opens a document from its bytes.
      *
@@ -810,6 +1146,14 @@ export class WasmDocument {
      * As `openBytes`, and `data-pending`.
      */
     static openSource(source: WasmSparseSource, options: OpenOptionsInit | undefined): WasmDocument;
+    /**
+     * The outline's top-level items, each with its children; empty without an outline (the
+     * extract and text modules).
+     *
+     * # Errors
+     * `data-pending` and the reading errors.
+     */
+    outline(): OutlineNodeJs[];
     /**
      * A handle on the page with `id` (`p12.0`).
      *
@@ -873,6 +1217,14 @@ export class WasmDocument {
      * The save's errors (`would-invalidate-signatures`, `requires-rewrite`, …).
      */
     save(options: SaveOptionsInit | undefined): { bytes: Uint8Array<ArrayBuffer>; report: SaveReportJs };
+    /**
+     * The structure tree's top-level elements in reading order, or `undefined` without one (the
+     * extract and text modules, beside `WasmPage.text`, whose runs it links by MCID).
+     *
+     * # Errors
+     * Reading errors.
+     */
+    structureTree(): StructureNodeJs[] | undefined;
     /**
      * Undoes the newest transaction; `undefined` when there is nothing to undo.
      *
@@ -886,6 +1238,38 @@ export class WasmDocument {
     warnings(): WasmWarningCursor;
 }
 
+/**
+ * An extraction in progress, from `WasmDocument.extractJob`; it holds its document weakly.
+ */
+export class WasmExtractJob {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Stops the job: its next step fails with `cancelled`.
+     */
+    cancel(): void;
+    /**
+     * Hands the job the result of its open request: `{ kind: "layout", regions }` or
+     * `{ kind: "ocr", words }`, boxes as `[x, y, width, height]` in top-left points.
+     *
+     * # Errors
+     * `model-result-unexpected` when nothing was asked for or `result` is the other kind;
+     * `invalid-argument` / `unknown-option` for a malformed result.
+     */
+    provide(result: ModelResultInit): void;
+    /**
+     * Extracts up to `budget` pages: `{ state: "progress", done, total, phase, request? }` or
+     * `{ state: "done", output }`, the output in the job's format. While `request` is set, a
+     * step does nothing until `provide` answers it.
+     *
+     * # Errors
+     * `cancelled`, `document-changed`, `job-finished`, `disposed` when the document is freed,
+     * and the reading errors.
+     */
+    step(budget: number): ({ state: "progress" } & ExtractProgressJs) | { state: "done"; output: string };
+}
+
 /**
  * An image to draw (decoded or passed through once, shared by every use).
  */
@@ -935,7 +1319,8 @@ export class WasmPage {
      * The page's current 0-based index.
      *
      * # Errors
-     * `unknown-page` when the page is gone; reading errors.
+     * `unknown-page` when the page is gone; `disposed` when its document is freed; reading
+     * errors.
      */
     index(): number;
     /**
@@ -946,12 +1331,12 @@ export class WasmPage {
      */
     info(): PageInfoJs;
     /**
-     * The page's text: lines, runs, glyph quads and glyph text (B9c; the extract and text
-     * modules).
+     * The page's text: lines, runs, glyph quads and glyph text (the extract and text modules).
      *
      * # Errors
-     * `unknown-page` when the page is gone; `data-pending` and the reading errors;
-     * `unknown-option` / `invalid-argument` for bad options.
+     * `unknown-page` when the page is gone; `disposed` when its document is freed;
+     * `data-pending` and the reading errors; `unknown-option` / `invalid-argument` for bad
+     * options.
      */
     text(options: TextOptionsInit | undefined): PageTextJs;
     /**
@@ -970,7 +1355,8 @@ export class WasmPageBuilder {
     [Symbol.dispose](): void;
     /**
      * Opens an artifact until the matching `endTag`: `kind` is `layout`, `page`, `pagination`
-     * or `background`.
+     * or `background`, or a pagination artifact that says what it is: `header` (attached to the
+     * top edge), `footer` (the bottom) or `watermark`.
      *
      * # Errors
      * `invalid-argument` for another kind.
@@ -1155,7 +1541,8 @@ export class WasmSaveJob {
      * `{ state: "done", bytes, report }`.
      *
      * # Errors
-     * `cancelled`, `document-changed`, `job-finished`, or the save's own errors.
+     * `cancelled`, `document-changed`, `job-finished`, `disposed` when the document is freed,
+     * or the save's own errors.
      */
     step(budget: number): ({ state: "progress" } & ProgressJs) | { state: "done"; bytes: Uint8Array<ArrayBuffer>; report: SaveReportJs };
 }
@@ -1214,6 +1601,14 @@ export class WasmWarningCursor {
     remaining(): number;
 }
 
+export function __wbg_reset_state(): void;
+
+/**
+ * Whether the most recent allocation failed: after a trap, `true` means the module ran out of
+ * memory.
+ */
+export function allocationFailed(): boolean;
+
 /**
  * Whether this module is the text module (fonts, `text`, `textBox`).
  */
@@ -1230,12 +1625,14 @@ export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_wasmbuilder_free: (a: number, b: number) => void;
     readonly __wbg_wasmdocument_free: (a: number, b: number) => void;
+    readonly __wbg_wasmextractjob_free: (a: number, b: number) => void;
     readonly __wbg_wasmimage_free: (a: number, b: number) => void;
     readonly __wbg_wasmpage_free: (a: number, b: number) => void;
     readonly __wbg_wasmpagebuilder_free: (a: number, b: number) => void;
     readonly __wbg_wasmsavejob_free: (a: number, b: number) => void;
     readonly __wbg_wasmsparsesource_free: (a: number, b: number) => void;
     readonly __wbg_wasmwarningcursor_free: (a: number, b: number) => void;
+    readonly allocationFailed: () => number;
     readonly hasText: () => number;
     readonly version: () => [number, number];
     readonly wasmbuilder_attach: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: any) => [number, number];
@@ -1250,10 +1647,15 @@ export interface InitOutput {
     readonly wasmbuilder_viewerPreferences: (a: number, b: any) => [number, number];
     readonly wasmdocument_apply: (a: number, b: any) => [number, number, number];
     readonly wasmdocument_applyLog: (a: number, b: number, c: number) => [number, number, number];
+    readonly wasmdocument_extract: (a: number, b: any) => [number, number, number, number];
+    readonly wasmdocument_extractJob: (a: number, b: any) => [number, number, number];
     readonly wasmdocument_hasUnsavedChanges: (a: number) => number;
     readonly wasmdocument_info: (a: number) => [number, number, number];
+    readonly wasmdocument_isTagged: (a: number) => [number, number, number];
+    readonly wasmdocument_namedDestination: (a: number, b: number, c: number) => [number, number, number];
     readonly wasmdocument_openBytes: (a: number, b: number, c: any) => [number, number, number];
     readonly wasmdocument_openSource: (a: number, b: any) => [number, number, number];
+    readonly wasmdocument_outline: (a: number) => [number, number, number];
     readonly wasmdocument_page: (a: number, b: number) => [number, number, number];
     readonly wasmdocument_pageById: (a: number, b: number, c: number) => [number, number, number];
     readonly wasmdocument_pageCount: (a: number) => [number, number, number];
@@ -1263,8 +1665,12 @@ export interface InitOutput {
     readonly wasmdocument_redo: (a: number) => [number, number, number];
     readonly wasmdocument_save: (a: number, b: any) => [number, number, number];
     readonly wasmdocument_saveJob: (a: number, b: any) => [number, number, number];
+    readonly wasmdocument_structureTree: (a: number) => [number, number, number];
     readonly wasmdocument_undo: (a: number) => [number, number, number];
     readonly wasmdocument_warnings: (a: number) => number;
+    readonly wasmextractjob_cancel: (a: number) => void;
+    readonly wasmextractjob_provide: (a: number, b: any) => [number, number];
+    readonly wasmextractjob_step: (a: number, b: number) => [number, number, number];
     readonly wasmimage_height: (a: number) => number;
     readonly wasmimage_jpeg: (a: number, b: number) => [number, number, number];
     readonly wasmimage_png: (a: number, b: number) => [number, number, number];