dsh-ab-ocr 0.1.0

package/lib/render.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Model-facing text of one ocr call's result. Pure: it reads only the canonical
+ * value the call recorded, so a replayed session renders the same lines.
+ * @module @deepseek-ai/dsh-ab-ocr/render
+ */
+import type { OcrDocument, OcrResult } from './types.ts';
+/**
+ * Describe one recognized document.
+ * @param document - the document's canonical value.
+ * @returns the document's result lines.
+ */
+export declare function renderDocument(document: OcrDocument): string;
+/**
+ * Compose the model-facing text of one call's result.
+ * @param value - the canonical value the call recorded.
+ * @returns one block per document, then one per failure.
+ */
+export declare function renderOcr(value: OcrResult): string;
+//# sourceMappingURL=render.d.ts.map

package/lib/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAExD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAkB5D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAOlD"}

package/lib/render.js

@@ -0,0 +1,45 @@
+/**
+ * Model-facing text of one ocr call's result. Pure: it reads only the canonical
+ * value the call recorded, so a replayed session renders the same lines.
+ * @module @deepseek-ai/dsh-ab-ocr/render
+ */
+/**
+ * Describe one recognized document.
+ * @param document - the document's canonical value.
+ * @returns the document's result lines.
+ */
+export function renderDocument(document) {
+    const scope = document.pages === document.totalPages
+        ? String(document.pages)
+        : document.pages + ' of ' + document.totalPages;
+    const lines = [
+        document.corrections > 0
+            ? 'Corrected ' + document.corrections + ' heading level(s) in ' + document.input
+            : 'Recognized ' + document.input,
+        'Saved to ' + document.output,
+        'Pages: ' + scope + ' | lines: ' + document.lines + ' | headings: ' + document.headings
+            + ' | characters: ' + document.chars,
+        'Removed ' + document.droppedPageNumbers + ' page numbers and '
+            + document.droppedRunningHeads + ' running heads; joined '
+            + document.joinedAcrossPages + ' paragraph(s) across a page break',
+    ];
+    if (document.pageDir !== '')
+        lines.push('Per-page text: ' + document.pageDir);
+    lines.push('Outline: ' + document.outlinePath + (document.outlineTruncated ? ' (incomplete)' : ''));
+    return lines.join('\n');
+}
+/**
+ * Compose the model-facing text of one call's result.
+ * @param value - the canonical value the call recorded.
+ * @returns one block per document, then one per failure.
+ */
+export function renderOcr(value) {
+    const blocks = value.documents.map(renderDocument);
+    for (const failure of value.failures) {
+        blocks.push('Failed ' + failure.input + '\n' + failure.error);
+    }
+    if (blocks.length === 0)
+        return 'Nothing was recognized.';
+    return blocks.join('\n\n---\n\n');
+}
+//# sourceMappingURL=render.js.map

package/lib/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,QAAqB;IAClD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,KAAK,QAAQ,CAAC,UAAU;QAClD,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QACxB,CAAC,CAAC,QAAQ,CAAC,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC,UAAU,CAAA;IACjD,MAAM,KAAK,GAAG;QACZ,QAAQ,CAAC,WAAW,GAAG,CAAC;YACtB,CAAC,CAAC,YAAY,GAAG,QAAQ,CAAC,WAAW,GAAG,uBAAuB,GAAG,QAAQ,CAAC,KAAK;YAChF,CAAC,CAAC,aAAa,GAAG,QAAQ,CAAC,KAAK;QAClC,WAAW,GAAG,QAAQ,CAAC,MAAM;QAC7B,SAAS,GAAG,KAAK,GAAG,YAAY,GAAG,QAAQ,CAAC,KAAK,GAAG,eAAe,GAAG,QAAQ,CAAC,QAAQ;cACnF,iBAAiB,GAAG,QAAQ,CAAC,KAAK;QACtC,UAAU,GAAG,QAAQ,CAAC,kBAAkB,GAAG,oBAAoB;cAC3D,QAAQ,CAAC,mBAAmB,GAAG,yBAAyB;cACxD,QAAQ,CAAC,iBAAiB,GAAG,mCAAmC;KACrE,CAAA;IACD,IAAI,QAAQ,CAAC,OAAO,KAAK,EAAE;QAAE,KAAK,CAAC,IAAI,CAAC,iBAAiB,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAA;IAC7E,KAAK,CAAC,IAAI,CAAC,WAAW,GAAG,QAAQ,CAAC,WAAW,GAAG,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IACnG,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,KAAgB;IACxC,MAAM,MAAM,GAAG,KAAK,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;IAClD,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;QACrC,MAAM,CAAC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;IAC/D,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,yBAAyB,CAAA;IACzD,OAAO,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAA;AACnC,CAAC"}

package/lib/sandbox.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The per-call file fence this plugin writes under, and the one place a write
+ * is refused.
+ *
+ * `@deepseek-ai/dsh-fs-sandbox` fences each mutation by a per-call policy, and
+ * that policy is the only thing naming the workspace the CALLING SESSION runs
+ * in: omitted, the backend falls back to the deployment's root — the directory
+ * the server was launched from — and a session working anywhere else has every
+ * artifact refused. The tool layer therefore resolves one policy per call and
+ * stamps it onto every write.
+ *
+ * The policy service is read with `ctx.get('sandboxPolicy')` rather than
+ * declared in `inject`, for the same reason `ctx.fs` is: a declared injection
+ * makes the service a provider requirement of this row. A composition that
+ * mounts the confining filesystem WITHOUT the policy service therefore composes
+ * cleanly and is refused at the first call, which is the earliest point where
+ * its real shape is knowable — see {@link callFence}.
+ * @module @deepseek-ai/dsh-ab-ocr/sandbox
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type FileSystem from '@deepseek-ai/dsh-fs';
+import type { FsTarget } from '@deepseek-ai/dsh-fs';
+import { type SandboxExecutionPolicy } from '@deepseek-ai/dsh-sandbox';
+import type { SandboxPolicyService } from '@deepseek-ai/dsh-sandbox-policy';
+/**
+ * The part of a resolved policy a write is fenced by: the mode the backend
+ * judges and the workspace root a `workspace-write` mutation must land under.
+ * Every other field of a {@link SandboxExecutionPolicy} is about the session
+ * that asked, which no write here needs.
+ */
+export type CallFence = Pick<SandboxExecutionPolicy, 'mode' | 'workspaceRoot'>;
+/**
+ * Resolve the policy one call writes under, refusing a composition that could
+ * only ever write to the wrong place.
+ * @param ctx - the registrant context, carrying the filesystem and the policy service.
+ * @param request - the calling session whose cwd is the workspace root, or `undefined` for an agentless call.
+ * @returns the fence to stamp onto this call's writes, or undefined when the mounted backend does not confine.
+ * @throws Error when a confining backend is mounted but no policy service can name the calling session's workspace.
+ */
+export declare function callFence(ctx: Context, request: Parameters<SandboxPolicyService['resolve']>[0]): CallFence | undefined;
+/**
+ * Write one text artifact under the call's fence. Every text this plugin
+ * persists goes through here, so the fence is applied in one place and a
+ * refusal is restated with the path, the mode, and the workspace to move under
+ * — what the provider's own text leaves out and a caller needs.
+ * @param fs - the mounted filesystem capability every write goes through.
+ * @param target - the resolved target to write.
+ * @param content - the complete file content.
+ * @param fence - the per-call fence to stamp onto the write; absent on a bare backend.
+ * @param signal - caller cancellation, forwarded to the write.
+ * @throws Error as the backend raised it, or the same refusal restated with the remedy.
+ */
+export declare function saveText(fs: FileSystem, target: FsTarget, content: string, fence?: CallFence | undefined, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=sandbox.d.ts.map

package/lib/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,UAAU,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAuB,KAAK,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AAC3F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAA;AAE3E;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,eAAe,CAAC,CAAA;AAS9E;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,UAAU,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,GACtD,SAAS,GAAG,SAAS,CAevB;AAYD;;;;;;;;;;;GAWG;AACH,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,UAAU,EACd,MAAM,EAAE,QAAQ,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,SAAS,GAAG,SAAS,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAOf"}

package/lib/sandbox.js

@@ -0,0 +1,101 @@
+/**
+ * The per-call file fence this plugin writes under, and the one place a write
+ * is refused.
+ *
+ * `@deepseek-ai/dsh-fs-sandbox` fences each mutation by a per-call policy, and
+ * that policy is the only thing naming the workspace the CALLING SESSION runs
+ * in: omitted, the backend falls back to the deployment's root — the directory
+ * the server was launched from — and a session working anywhere else has every
+ * artifact refused. The tool layer therefore resolves one policy per call and
+ * stamps it onto every write.
+ *
+ * The policy service is read with `ctx.get('sandboxPolicy')` rather than
+ * declared in `inject`, for the same reason `ctx.fs` is: a declared injection
+ * makes the service a provider requirement of this row. A composition that
+ * mounts the confining filesystem WITHOUT the policy service therefore composes
+ * cleanly and is refused at the first call, which is the earliest point where
+ * its real shape is knowable — see {@link callFence}.
+ * @module @deepseek-ai/dsh-ab-ocr/sandbox
+ */
+import { sandboxDenialMarker } from '@deepseek-ai/dsh-sandbox';
+/**
+ * The structured code a confining filesystem reports a refused mutation with.
+ * Matched structurally rather than by importing the error class, so a backend
+ * that throws its own equivalent is still recognized as a denial.
+ */
+const SANDBOX_DENIED = 'FS_SANDBOX_DENIED';
+/**
+ * Resolve the policy one call writes under, refusing a composition that could
+ * only ever write to the wrong place.
+ * @param ctx - the registrant context, carrying the filesystem and the policy service.
+ * @param request - the calling session whose cwd is the workspace root, or `undefined` for an agentless call.
+ * @returns the fence to stamp onto this call's writes, or undefined when the mounted backend does not confine.
+ * @throws Error when a confining backend is mounted but no policy service can name the calling session's workspace.
+ */
+export function callFence(ctx, request) {
+    // A missing policy service is refused here rather than when the row loads,
+    // because it cannot be seen there: a confining backend declares
+    // `sandboxPolicy` as an injection, so in a composition that mounts one
+    // WITHOUT the service the backend is never constructed at all — `ctx.get('fs')`
+    // is undefined while this row applies, and the row mounts cleanly. The first
+    // call is the earliest point at which the composition's real shape is knowable.
+    const policy = ctx.get('sandboxPolicy');
+    const fs = ctx.get('fs');
+    if (fs?.sandboxMode === undefined)
+        return undefined;
+    if (policy === undefined) {
+        throw new Error('dsh-ab-ocr: the mounted filesystem confines but ctx.sandboxPolicy is missing'
+            + ', so no workspace root can be resolved for this session and none of its artifacts could be written');
+    }
+    return policy.resolve(request ?? {});
+}
+/**
+ * Whether one thrown error is the file sandbox refusing a mutation, judged by
+ * the structured code the capability publishes rather than by its message text.
+ * @param error - the error a write threw.
+ * @returns true when a confining filesystem denied the write.
+ */
+function isSandboxDenial(error) {
+    return typeof error === 'object' && error !== null && error.code === SANDBOX_DENIED;
+}
+/**
+ * Write one text artifact under the call's fence. Every text this plugin
+ * persists goes through here, so the fence is applied in one place and a
+ * refusal is restated with the path, the mode, and the workspace to move under
+ * — what the provider's own text leaves out and a caller needs.
+ * @param fs - the mounted filesystem capability every write goes through.
+ * @param target - the resolved target to write.
+ * @param content - the complete file content.
+ * @param fence - the per-call fence to stamp onto the write; absent on a bare backend.
+ * @param signal - caller cancellation, forwarded to the write.
+ * @throws Error as the backend raised it, or the same refusal restated with the remedy.
+ */
+export async function saveText(fs, target, content, fence, signal) {
+    try {
+        await fs.writeText(target, content, undefined, signal, fence);
+    }
+    catch (error) {
+        if (fence === undefined || !isSandboxDenial(error))
+            throw error;
+        throw restated(fence, fs.processPath(target), error);
+    }
+}
+/**
+ * Restate one refused write as the path, the mode, and the workspace it has to
+ * move under.
+ * @param fence - the fence the refused write was stamped with.
+ * @param path - the target's path in the backend's execution world.
+ * @param cause - the refusal the backend raised.
+ * @returns the error to throw in its place, keeping the denial code a consumer keys off.
+ */
+function restated(fence, path, cause) {
+    const error = new Error(sandboxDenialMarker(fence.mode)
+        + ': cannot write ' + path + '; this session\'s workspace is ' + fence.workspaceRoot
+        + '. Name an `outputDir` inside it, or a source file inside it.', { cause });
+    // The structured code travels with the restated message: a caller that keys a
+    // retry or an observer off FS_SANDBOX_DENIED still sees the same denial.
+    const stamped = error;
+    stamped.code = SANDBOX_DENIED;
+    return stamped;
+}
+//# sourceMappingURL=sandbox.js.map

package/lib/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,EAAE,mBAAmB,EAA+B,MAAM,0BAA0B,CAAA;AAW3F;;;;GAIG;AACH,MAAM,cAAc,GAAW,mBAAmB,CAAA;AAElD;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CACvB,GAAY,EACZ,OAAuD;IAEvD,2EAA2E;IAC3E,gEAAgE;IAChE,uEAAuE;IACvE,gFAAgF;IAChF,6EAA6E;IAC7E,gFAAgF;IAChF,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,eAAe,CAAqC,CAAA;IAC3E,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAA2B,CAAA;IAClD,IAAI,EAAE,EAAE,WAAW,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACnD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,8EAA8E;cAC1F,oGAAoG,CAAC,CAAA;IAC3G,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAA;AACtC,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAA4B,CAAC,IAAI,KAAK,cAAc,CAAA;AAC7G,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,EAAc,EACd,MAAgB,EAChB,OAAe,EACf,KAA6B,EAC7B,MAAoB;IAEpB,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,CAAA;IAC/D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAA;QAC/D,MAAM,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,CAAA;IACtD,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,QAAQ,CAAC,KAAgB,EAAE,IAAY,EAAE,KAAc;IAC9D,MAAM,KAAK,GAAG,IAAI,KAAK,CACrB,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC;UAC7B,iBAAiB,GAAG,IAAI,GAAG,iCAAiC,GAAG,KAAK,CAAC,aAAa;UAClF,8DAA8D,EAChE,EAAE,KAAK,EAAE,CACV,CAAA;IACD,8EAA8E;IAC9E,yEAAyE;IACzE,MAAM,OAAO,GAAG,KAAkC,CAAA;IAClD,OAAO,CAAC,IAAI,GAAG,cAAc,CAAA;IAC7B,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/lib/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Values the ocr tool accepts and returns. Kept out of the entry module so a
+ * browser consumer can share one declaration.
+ * @module @deepseek-ai/dsh-ab-ocr/types
+ */
+/** One recognized line, with the geometry the merge pass reads. */
+export interface OcrGeometryLine {
+    /** The line's text. */
+    text: string;
+    /** Left edge of the line's box, in page units. */
+    x0: number;
+    /** Top edge of the line's box, in page units. */
+    y0: number;
+    /** Right edge of the line's box, in page units. */
+    x1: number;
+    /** Bottom edge of the line's box, in page units. */
+    y1: number;
+    /** Glyph height the line was set in. */
+    height: number;
+}
+/** One recognized page's geometry. */
+export interface OcrPageGeometry {
+    /** The page's one-based number. */
+    index: number;
+    /** Page width in render units. */
+    width: number;
+    /** Page height in render units. */
+    height: number;
+    /** The page's lines, in reading order. */
+    lines: OcrGeometryLine[];
+}
+/** Every recognized page's geometry, in page order. */
+export interface OcrGeometry {
+    /** The document's pages. */
+    pages: OcrPageGeometry[];
+}
+/** One heading candidate of the outline a recognition inferred. */
+export interface OcrOutlineEntry {
+    /** Candidate id: `h1`, `h2`, … in document order. */
+    id: string;
+    /** The page the heading sits on. */
+    page: number;
+    /** The heading's text. */
+    text: string;
+    /** The level the merge inferred, or null when it inferred none. */
+    level: number | null;
+    /** Glyph height over the document's body height. */
+    ratio: number;
+    /** The section number the heading carries, or null. */
+    numbered: string | null;
+    /** The level the merge inferred for this line, before any correction was applied. */
+    inferred: number | null;
+}
+/**
+ * Merge switches and thresholds one call sends, in the names the worker reads
+ * them under. They are part of the recognition's identity: two calls that
+ * differ here produce different Markdown from the same source.
+ */
+export interface MergeOptions {
+    /** Whether folios are removed from the merged document. */
+    removePageNumbers: boolean;
+    /** Whether lines that repeat in the edge bands of most pages are removed. */
+    removeRunningHeads: boolean;
+    /** Fraction of pages a repeated edge line must appear on to count as a running head. */
+    runningHeadRatio: number;
+    /** Fewest pages such a line must appear on, whatever the ratio. */
+    runningHeadMinPages: number;
+    /** Whether headings are inferred at all. */
+    detectHeadings: boolean;
+    /** How much taller than body text a line must be to be read as a heading by size. */
+    headingMinRatio: number;
+    /** Left-edge offset, in body glyph heights, that marks an indented first line. */
+    indentRatio: number;
+    /** Vertical gap, in body glyph heights, that separates two paragraphs. */
+    paragraphGapRatio: number;
+    /** Glyph height over body height above which a line becomes an outline candidate. */
+    outlineCandidateRatio: number;
+    /** Most outline candidates one document may offer. */
+    maxOutlineCandidates: number;
+    /** Candidate id to heading level corrections, applied over the inferred levels. */
+    levelOverrides?: Record<string, number>;
+}
+/** One recognized document in the tool's result. */
+export interface OcrDocument {
+    /** The path the model asked to recognize, as it supplied it. */
+    input: string;
+    /** Absolute path of the Markdown file that was written. */
+    output: string;
+    /** Pages recognized in this call. */
+    pages: number;
+    /** Pages the source carries, which exceeds pages when a selection was given. */
+    totalPages: number;
+    /** Lines kept after page furniture was removed. */
+    lines: number;
+    /** Headings found in the outline. */
+    headings: number;
+    /** Characters the Markdown body carries. */
+    chars: number;
+    /** Folios removed. */
+    droppedPageNumbers: number;
+    /** Running heads and feet removed. */
+    droppedRunningHeads: number;
+    /** Paragraphs continued across a page break. */
+    joinedAcrossPages: number;
+    /** Directory holding the per-page text, or an empty string when they were removed. */
+    pageDir: string;
+    /** Wall-clock seconds the document took. */
+    seconds: number;
+    /** Content digest of this recognition, 12 hex characters. */
+    digest: string;
+    /** The explicit ascending pages this document's text came from. */
+    selection: number[];
+    /** Absolute path of the outline file, which names every heading candidate. */
+    outlinePath: string;
+    /** Whether the heading candidate ceiling cut the outline short. */
+    outlineTruncated: boolean;
+    /** Heading-level corrections this call applied; 0 for a recognition. */
+    corrections: number;
+}
+/** One document the call could not finish. */
+export interface OcrFailure {
+    /** The path that failed. */
+    input: string;
+    /** What went wrong, in the terms the caller can act on. */
+    error: string;
+}
+/** The canonical value one call records. */
+export interface OcrResult {
+    /** Documents recognized in this call, in request order. */
+    documents: OcrDocument[];
+    /** Documents that failed; the others are still saved. */
+    failures: OcrFailure[];
+}
+/** Arguments the model supplies to one call. */
+export interface OcrArgs {
+    /** One document to recognize. */
+    path?: string;
+    /** Several documents to recognize in one call. */
+    paths?: string[];
+    /** Pages to recognize, counted from one, as single pages and inclusive ranges. */
+    pages?: string;
+    /** Directory for the Markdown files; relative values resolve against the working directory. */
+    outputDir?: string;
+    /** Heading-level corrections for a document an earlier call recognized, such as "h12=2,h15=1". */
+    levels?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAA;IACV,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAA;IACV,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAA;IACV,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAA;IACV,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAA;CACf;AAED,sCAAsC;AACtC,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,0CAA0C;IAC1C,KAAK,EAAE,eAAe,EAAE,CAAA;CACzB;AAED,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,4BAA4B;IAC5B,KAAK,EAAE,eAAe,EAAE,CAAA;CACzB;AAED,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,EAAE,EAAE,MAAM,CAAA;IACV,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAA;IACZ,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,mEAAmE;IACnE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,qFAAqF;IACrF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,iBAAiB,EAAE,OAAO,CAAA;IAC1B,6EAA6E;IAC7E,kBAAkB,EAAE,OAAO,CAAA;IAC3B,wFAAwF;IACxF,gBAAgB,EAAE,MAAM,CAAA;IACxB,mEAAmE;IACnE,mBAAmB,EAAE,MAAM,CAAA;IAC3B,4CAA4C;IAC5C,cAAc,EAAE,OAAO,CAAA;IACvB,qFAAqF;IACrF,eAAe,EAAE,MAAM,CAAA;IACvB,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAA;IACnB,0EAA0E;IAC1E,iBAAiB,EAAE,MAAM,CAAA;IACzB,qFAAqF;IACrF,qBAAqB,EAAE,MAAM,CAAA;IAC7B,sDAAsD;IACtD,oBAAoB,EAAE,MAAM,CAAA;IAC5B,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC;AAED,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAA;IACd,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAA;IACb,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAA;IACb,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAA;IACb,sBAAsB;IACtB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,sCAAsC;IACtC,mBAAmB,EAAE,MAAM,CAAA;IAC3B,gDAAgD;IAChD,iBAAiB,EAAE,MAAM,CAAA;IACzB,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAA;IACf,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAA;IACf,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,8EAA8E;IAC9E,WAAW,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,gBAAgB,EAAE,OAAO,CAAA;IACzB,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;CACd;AAED,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,SAAS,EAAE,WAAW,EAAE,CAAA;IACxB,yDAAyD;IACzD,QAAQ,EAAE,UAAU,EAAE,CAAA;CACvB;AAED,gDAAgD;AAChD,MAAM,WAAW,OAAO;IACtB,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+FAA+F;IAC/F,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,kGAAkG;IAClG,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB"}

package/lib/types.js

@@ -0,0 +1,7 @@
+/**
+ * Values the ocr tool accepts and returns. Kept out of the entry module so a
+ * browser consumer can share one declaration.
+ * @module @deepseek-ai/dsh-ab-ocr/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/lib/worker.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Transport to the OCR worker process. The worker speaks newline-delimited
+ * JSON: one event per line on stdout, diagnostics on stderr. This module owns
+ * the process lifetime, the spec handoff, the timeout, and the cancellation, so
+ * the tool's entry module only has to interpret events.
+ * @module @deepseek-ai/dsh-ab-ocr/worker
+ */
+import type { MergeOptions, OcrGeometry } from './types.ts';
+/** One event line the worker wrote, already parsed. */
+export interface WorkerEvent {
+    /** Event name: start, page, released, done, error, fatal, or end. */
+    event: string;
+    /** Event payload, whose fields depend on the name. */
+    [key: string]: unknown;
+}
+/** Where the worker executable and its script live, and how long a run may take. */
+export interface WorkerInvocation {
+    /** Python executable that carries the OCR dependencies. */
+    python: string;
+    /** Absolute path of the worker script. */
+    script: string;
+    /** Milliseconds one call may take; 0 disables the ceiling. */
+    timeoutMs: number;
+}
+/** One job in the spec the worker reads from stdin. */
+export interface WorkerJob {
+    /** Whether the worker recognizes the document or assembles a stored record. */
+    mode: 'recognize' | 'assemble';
+    /** Caller-chosen identifier echoed on every event. */
+    id: string;
+    /** Absolute path of the document to recognize, in the worker's own execution world. */
+    input: string;
+    /** Pages to recognize in the caller's notation, or null for the whole document. */
+    pages?: string | null;
+    /** The merge switches and thresholds; an assembly job adds its level corrections here. */
+    merge: MergeOptions;
+    /** The stored page geometry an assembly job merges; absent from a recognition job. */
+    record?: OcrGeometry;
+    /** Everything else the worker needs: the render bounds and the recognition switches. */
+    [key: string]: unknown;
+}
+/** The spec one worker process reads from stdin. */
+export interface WorkerSpec {
+    /** Whether the engine is rebuilt per document or shared across the batch. */
+    engineLifetime: 'perDocument' | 'shared';
+    /** Documents to process, in order. */
+    jobs: WorkerJob[];
+}
+/** Everything one worker process produced. */
+export interface WorkerRun {
+    /** Events the worker wrote, in order. */
+    events: WorkerEvent[];
+    /** Tail of the worker's diagnostics. */
+    stderr: string;
+    /** Process exit code, or null when a signal ended it. */
+    exitCode: number | null;
+    /** Whether the run hit its time ceiling. */
+    timedOut: boolean;
+    /** Whether the run was cancelled. */
+    aborted: boolean;
+}
+/** What one environment check produced. */
+export interface SelfTest {
+    /** The worker's report, or undefined when it never produced one. */
+    report: Record<string, unknown> | undefined;
+    /** Tail of the worker's diagnostics. */
+    stderr: string;
+    /** Process exit code, or null when a signal or a failed start ended it. */
+    exitCode: number | null;
+}
+/**
+ * Split a run of text into whole lines, returning what is left of a partial one.
+ * @param buffered - text received so far, including any partial final line.
+ * @param chunk - newly received text.
+ * @returns the complete lines and the remaining partial line.
+ */
+export declare function splitLines(buffered: string, chunk: string): {
+    lines: string[];
+    rest: string;
+};
+/**
+ * Parse one event line, ignoring a line that is not a JSON object.
+ * @param line - one complete stdout line.
+ * @returns the parsed event, or undefined for a line that is not one.
+ */
+export declare function parseEvent(line: string): WorkerEvent | undefined;
+/**
+ * Ask the worker to report its environment.
+ * @param invocation - executable, script, and the ceiling this check may take.
+ * @param signal - caller cancellation.
+ * @returns the report and the diagnostics, whether or not the worker started.
+ */
+export declare function runSelfTest(invocation: WorkerInvocation, signal?: AbortSignal): Promise<SelfTest>;
+/**
+ * Run one batch of documents through the worker.
+ *
+ * The event callback sees each event as it is parsed, which is what lets the
+ * caller persist a finished page before the next one is recognized instead of
+ * holding the whole document until the process exits.
+ * @param invocation - executable, script, and time ceiling.
+ * @param spec - the documents and options to process.
+ * @param onEvent - called with each parsed event as it arrives.
+ * @param signal - caller cancellation.
+ * @returns the events, diagnostics, and exit state.
+ */
+export declare function runSpec(invocation: WorkerInvocation, spec: WorkerSpec, onEvent: (event: WorkerEvent) => void, signal?: AbortSignal): Promise<WorkerRun>;
+//# sourceMappingURL=worker.d.ts.map

package/lib/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE3D,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAA;IACd,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAA;IACd,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,uDAAuD;AACvD,MAAM,WAAW,SAAS;IACxB,+EAA+E;IAC/E,IAAI,EAAE,WAAW,GAAG,UAAU,CAAA;IAC9B,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAA;IACV,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAA;IACb,mFAAmF;IACnF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,0FAA0F;IAC1F,KAAK,EAAE,YAAY,CAAA;IACnB,sFAAsF;IACtF,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,wFAAwF;IACxF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,cAAc,EAAE,aAAa,GAAG,QAAQ,CAAA;IACxC,sCAAsC;IACtC,IAAI,EAAE,SAAS,EAAE,CAAA;CAClB;AAED,8CAA8C;AAC9C,MAAM,WAAW,SAAS;IACxB,yCAAyC;IACzC,MAAM,EAAE,WAAW,EAAE,CAAA;IACrB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,yDAAyD;IACzD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,4CAA4C;IAC5C,QAAQ,EAAE,OAAO,CAAA;IACjB,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,2CAA2C;AAC3C,MAAM,WAAW,QAAQ;IACvB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IAC3C,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAKD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAK7F;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAchE;AA6ED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,gBAAgB,EAC5B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,QAAQ,CAAC,CAOnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CACrB,UAAU,EAAE,gBAAgB,EAC5B,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,EACrC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,SAAS,CAAC,CAEpB"}