@dylanl1/dsh-plugin-pdf 0.1.2 → 0.1.3

package/dist/types/modules/retrieval/cache.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import type { RetrievalCache } from './types.js';
-export declare const RETRIEVAL_EXTRACTION_VERSION = "joined-page-text-v1";
+export declare const RETRIEVAL_EXTRACTION_VERSION = "page-content-v3-representations";
 export declare const digest: (value: string) => string;
 export declare const retrievalCacheKey: (...values: unknown[]) => string;
 declare const pageSchema: z.ZodObject<{
@@ -12,12 +12,54 @@ declare const pageSchema: z.ZodObject<{
     }>;
     warnings: z.ZodOptional<z.ZodArray<z.ZodString>>;
     paragraphBreaks: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    units: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        blockId: z.ZodString;
+        kind: z.ZodEnum<{
+            "ocr-text": "ocr-text";
+            "image-description": "image-description";
+            "native-text": "native-text";
+        }>;
+        text: z.ZodString;
+        digest: z.ZodString;
+        paragraphBreaks: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        nativeRange: z.ZodOptional<z.ZodObject<{
+            startUtf16: z.ZodNumber;
+            endUtf16: z.ZodNumber;
+        }, z.core.$strict>>;
+        rectPdf: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
+        spans: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            startUtf16: z.ZodNumber;
+            endUtf16: z.ZodNumber;
+            rectPdf: z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber, z.ZodNumber], null>;
+        }, z.core.$strict>>>;
+        producer: z.ZodOptional<z.ZodObject<{
+            id: z.ZodString;
+            version: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            configurationIdentity: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        inputDigest: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    contentIdentity: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type CachedRetrievalPage = z.infer<typeof pageSchema>;
-export declare function pageCacheKey(path: string, sourceDigest: string, page: number): string;
+/** The empty legacy identity intentionally preserves the unextended key shape. */
+export declare function pageCacheKey(path: string, sourceDigest: string, page: number, extractionIdentity?: string): string;
+export declare function validateRetrievalPage(value: unknown): CachedRetrievalPage | undefined;
 export declare function readCachedPage(cache: RetrievalCache | undefined, key: string): Promise<CachedRetrievalPage | undefined>;
 /** Derived caches are disposable; an unavailable cache must not break reading. */
 export declare function cacheDerived(cache: RetrievalCache | undefined, key: string, value: unknown): Promise<void>;
 export declare function validVector(value: unknown, dimensions: number): value is number[];
+interface CachedRetrievalVector {
+    version: 1;
+    encoding: 'float32-le-base64';
+    dimensions: number;
+    data: string;
+    sha256: string;
+}
+/** Persist the same normalized Float32 precision used by cosine search. Explicit
+ * byte order also makes caches reusable between CPU architectures. */
+export declare function encodeCachedVector(input: ArrayLike<number>): CachedRetrievalVector;
 export declare function readCachedVector(cache: RetrievalCache | undefined, key: string, dimensions: number): Promise<number[] | undefined>;
 export {};

package/dist/types/modules/retrieval/document-policy.d.ts

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+import { type PdfDocumentIndexPolicy, type PdfDocumentIndexSettings } from '../../contracts/indexing.js';
+import { type EngineJson } from '../engines/index.js';
+import { type PdfSettings } from '../../shared/contracts.js';
+export declare const resolvedIndexPlanSchema: z.ZodObject<{
+    policy: z.ZodObject<{
+        indexScanPages: z.ZodBoolean;
+        indexImageDescriptions: z.ZodBoolean;
+        embeddingEngine: z.ZodString;
+        ocrEngine: z.ZodString;
+        imageEngine: z.ZodString;
+    }, z.core.$strict>;
+    configurations: z.ZodObject<{
+        ocr: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<EngineJson, unknown, z.core.$ZodTypeInternals<EngineJson, unknown>>>>>;
+        image: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<EngineJson, unknown, z.core.$ZodTypeInternals<EngineJson, unknown>>>>>;
+        translation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<EngineJson, unknown, z.core.$ZodTypeInternals<EngineJson, unknown>>>>>;
+        embedding: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<EngineJson, unknown, z.core.$ZodTypeInternals<EngineJson, unknown>>>>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ResolvedIndexPlan = z.infer<typeof resolvedIndexPlanSchema>;
+export declare const documentIndexRecordSchema: z.ZodObject<{
+    version: z.ZodOptional<z.ZodLiteral<2>>;
+    revision: z.ZodNumber;
+    desired: z.ZodUnion<readonly [z.ZodObject<{
+        indexScanPages: z.ZodBoolean;
+        indexImageDescriptions: z.ZodBoolean;
+    }, z.core.$strict>, z.ZodPipe<z.ZodObject<{
+        indexScanPages: z.ZodBoolean;
+        indexImageDescriptions: z.ZodBoolean;
+        embeddingEngine: z.ZodString;
+        ocrEngine: z.ZodString;
+        imageEngine: z.ZodString;
+    }, z.core.$strict>, z.ZodTransform<{
+        indexScanPages: boolean;
+        indexImageDescriptions: boolean;
+    }, {
+        indexScanPages: boolean;
+        indexImageDescriptions: boolean;
+        embeddingEngine: string;
+        ocrEngine: string;
+        imageEngine: string;
+    }>>]>;
+    active: z.ZodObject<{
+        policy: z.ZodObject<{
+            indexScanPages: z.ZodBoolean;
+            indexImageDescriptions: z.ZodBoolean;
+            embeddingEngine: z.ZodString;
+            ocrEngine: z.ZodString;
+            imageEngine: z.ZodString;
+        }, z.core.$strict>;
+        configurations: z.ZodObject<{
+            ocr: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<EngineJson, unknown, z.core.$ZodTypeInternals<EngineJson, unknown>>>>>;
+            image: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<EngineJson, unknown, z.core.$ZodTypeInternals<EngineJson, unknown>>>>>;
+            translation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<EngineJson, unknown, z.core.$ZodTypeInternals<EngineJson, unknown>>>>>;
+            embedding: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<EngineJson, unknown, z.core.$ZodTypeInternals<EngineJson, unknown>>>>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+type Record = z.infer<typeof documentIndexRecordSchema>;
+interface Store {
+    key(path: string): string;
+    get(key: string): unknown;
+    put(key: string, value: Record): Promise<unknown>;
+}
+export declare function indexPolicy(settings: Pick<PdfSettings, 'indexScanPages' | 'indexImageDescriptions'>): PdfDocumentIndexPolicy;
+/** Freeze only the selected bindings; edits to unrelated engines do not invalidate this document. */
+export declare function resolveIndexPlan(policy: PdfDocumentIndexPolicy, settings: PdfSettings): ResolvedIndexPlan;
+export declare function settingsForIndexPlan(plan: ResolvedIndexPlan, defaults?: PdfSettings): PdfSettings;
+/** Host/profile-owned preferences. The path key survives saves; source digests belong to derived indexes. */
+export declare function createDocumentIndexPolicies(store: Store, defaults: () => PdfSettings): {
+    enabled: () => boolean;
+    active(path: string): ResolvedIndexPlan;
+    desired: (path: string) => ResolvedIndexPlan;
+    settled(path: string): Promise<void>;
+    snapshot(path: string, documentId: string): PdfDocumentIndexSettings;
+    configure(path: string, revision: number, policy: PdfDocumentIndexPolicy): Promise<void>;
+    defaults(path: string, revision: number): Promise<void>;
+    activate(path: string, plan: ResolvedIndexPlan): Promise<void>;
+    subscribe(listener: () => void): () => void;
+    releaseUnused(paths: ReadonlySet<string>): void;
+    dispose(): Promise<void>;
+};
+export {};

package/dist/types/modules/retrieval/index.d.ts

@@ -1,6 +1,9 @@
 export * from './types.js';
 export * from './service.js';
-export { chunkPage, tokenizeRetrievalText, RETRIEVAL_TEXT_VERSION } from './text.js';
+export { createDocumentIndexPolicies, documentIndexRecordSchema, indexPolicy, resolveIndexPlan, settingsForIndexPlan } from './document-policy.js';
+export type { ResolvedIndexPlan } from './document-policy.js';
+export { chunkPage, chunkRetrievalPage, tokenizeRetrievalText, RETRIEVAL_TEXT_VERSION } from './text.js';
 export { retrievalPageText } from './paragraphs.js';
 export type { RetrievalChunk } from './text.js';
 export { createBm25Index, searchBm25, rankVectors, reciprocalRankFusion, hybridCandidates } from './ranking.js';
+export { projectPageContent } from './page-content.js';

package/dist/types/modules/retrieval/page-content.d.ts

@@ -0,0 +1,4 @@
+import { type PageContent } from '../document/index.js';
+import type { RetrievalPage } from './types.js';
+/** Indexing is a projection of representations, not a second editable document. */
+export declare function projectPageContent(content: PageContent): RetrievalPage;

package/dist/types/modules/retrieval/paragraphs.d.ts

@@ -1,12 +1 @@
-import type { NativeTextContent } from '../../shared/native.js';
-type TextItem = NativeTextContent['items'][number];
-/**
- * Preserve native extraction order and exact joined-text offsets. Only obvious
- * layout gaps/font changes add boundaries; ordinary wrapped lines remain one
- * paragraph. These are retrieval units, never certified reading-order geometry.
- */
-export declare function retrievalPageText(items: readonly TextItem[]): {
-    text: string;
-    paragraphBreaks: number[];
-};
-export {};
+export { nativePageContentText as retrievalPageText } from '../document/index.js';

package/dist/types/modules/retrieval/shared-source.d.ts

@@ -0,0 +1,25 @@
+import type { RetrievalDocument, RetrievalEmbedding, RetrievalPorts } from './types.js';
+/** Authority belongs to a caller, never to the content-addressed index. */
+export interface RetrievalBinding {
+    sessionId: string;
+    document: RetrievalDocument;
+    provider?: RetrievalEmbedding;
+    selectionIdentity: string;
+    extractionIdentity: string;
+    lifetime: {
+        valid: boolean;
+        id: string;
+    };
+    signal: AbortSignal;
+}
+/** A shared step owns its lease. A departing caller does not cancel another
+ * caller's work; a changed/revoked source is replaced before derived data commits. */
+export declare function createSharedRetrievalSource(ports: RetrievalPorts, bindings: ReadonlySet<RetrievalBinding>, signal: AbortSignal, checkIndex: () => void, checkBinding: (binding: RetrievalBinding) => void, checkOrigin: (binding: RetrievalBinding) => void): {
+    current: (excluded?: ReadonlySet<RetrievalBinding>) => RetrievalBinding;
+    check: () => void;
+    read: (page: number) => Promise<import("./types.js").RetrievalPage>;
+    embed: (texts: string[]) => Promise<number[][]>;
+    signal: AbortSignal;
+    dispose: () => void;
+};
+export type SharedRetrievalSource = ReturnType<typeof createSharedRetrievalSource>;

package/dist/types/modules/retrieval/text.d.ts

@@ -1,14 +1,29 @@
+import type { RetrievalPage, RetrievalPageUnitKind, RetrievalPageUnitProducer, RetrievalPageUnitSpan } from './types.js';
 /** Changing boundaries or tokenization invalidates the derived lexical index. */
 export declare const RETRIEVAL_TEXT_VERSION = "page-text-v2-paragraphs";
 export declare const MAX_RETRIEVAL_PARAGRAPH_BREAKS = 10000;
 export interface RetrievalChunk {
     id: string;
     page: number;
+    /** Joined native-page offsets for pdf-text; representation-local offsets for generated content. */
     startUtf16: number;
     endUtf16: number;
     text: string;
+    /** Native joined-page digest, or exact OCR/description unit text digest (unprefixed SHA-256). */
     pageTextDigest: string;
-    source: 'pdf-text' | 'ocr';
+    source: 'pdf-text' | 'ocr' | 'image-description';
+    representation?: {
+        id: string;
+        blockId: string;
+        kind: RetrievalPageUnitKind;
+        unitDigest: string;
+        unitStartUtf16: number;
+        unitEndUtf16: number;
+        rectPdf?: [number, number, number, number];
+        spans?: RetrievalPageUnitSpan[];
+        producer?: RetrievalPageUnitProducer;
+        inputDigest?: string;
+    };
 }
 export interface ChunkPageOptions {
     maxCharacters?: number;
@@ -21,3 +36,6 @@ export declare function tokenizeRetrievalText(text: string): string[];
 export declare function validParagraphBreaks(text: string, breaks: unknown): breaks is number[] | undefined;
 /** Page-local exact substrings. UTF-16 offsets refer to the unmodified joined page text. */
 export declare function chunkPage(page: number, text: string, source?: RetrievalChunk['source'], options?: ChunkPageOptions): RetrievalChunk[];
+/** Chunk the projected representations without losing their evidence coordinate
+ * system. Native ranges refer to joined page text; generated ranges are local. */
+export declare function chunkRetrievalPage(page: number, content: RetrievalPage, options?: Pick<ChunkPageOptions, 'maxCharacters' | 'overlapCharacters'>): RetrievalChunk[];

package/dist/types/modules/retrieval/types.d.ts

@@ -10,8 +10,13 @@ export interface RetrievalDocument {
 export interface RetrievalEmbedding {
     /** Includes provider, model revision, dimensions and query/document encoding configuration. */
     fingerprint: string;
+    /** Provider-attested document encoding identity. When absent the complete
+     * fingerprint/binding pair remains the conservative persistent vector key. */
+    documentFingerprint?: string;
     /** Registration lifetime, separate from the reusable model/config fingerprint. */
     generation?: string;
+    /** Exact engine binding identity; third-party fingerprints may omit configuration. */
+    configurationIdentity?: string;
     dimensions: number;
     maxBatchSize: number;
     maxInputCharacters?: number;
@@ -21,6 +26,55 @@ export interface RetrievalEmbedding {
 export interface RetrievalCache {
     get(key: string): Promise<unknown>;
     set(key: string, value: unknown): Promise<void>;
+    /** Remove all derived records. Required when this cache supports explicit rebuilds. */
+    clear?(): Promise<void>;
+}
+export type RetrievalPageUnitKind = 'native-text' | 'ocr-text' | 'image-description';
+export interface RetrievalPageUnitProducer {
+    id: string;
+    version?: string;
+    model?: string;
+    configurationIdentity?: string;
+}
+export interface RetrievalPageUnitSpan {
+    startUtf16: number;
+    endUtf16: number;
+    rectPdf: [number, number, number, number];
+}
+/** One exact representation of a logical content block. Generated offsets stay
+ * local to this unit and must never be interpreted as native PDF text offsets. */
+export interface RetrievalPageUnit {
+    id: string;
+    blockId: string;
+    kind: RetrievalPageUnitKind;
+    text: string;
+    /** SHA-256 of the exact representation text, prefixed with sha256:. */
+    digest: string;
+    paragraphBreaks?: number[];
+    nativeRange?: {
+        startUtf16: number;
+        endUtf16: number;
+    };
+    rectPdf?: [number, number, number, number];
+    spans?: RetrievalPageUnitSpan[];
+    producer?: RetrievalPageUnitProducer;
+    inputDigest?: string;
+}
+export interface RetrievalPageFailure {
+    code: string;
+}
+export interface RetrievalPage {
+    /** Joined native text; legacy OCR-only ports may keep their existing format. */
+    text: string;
+    source: 'pdf-text' | 'ocr';
+    warnings?: string[];
+    paragraphBreaks?: number[];
+    /** When supplied, these are the complete searchable units for this page. */
+    units?: RetrievalPageUnit[];
+    contentIdentity?: string;
+    /** Available representations are usable, but optional extraction was incomplete.
+     * Such pages are never persisted and retry only through an explicit rebuild. */
+    failure?: RetrievalPageFailure;
 }
 export interface RetrievalPorts {
     documents: {
@@ -29,13 +83,9 @@ export interface RetrievalPorts {
         retain?(sessionId: string, documentId: string, signal: AbortSignal): Promise<() => void>;
     };
     pages: {
-        read(sessionId: string, documentId: string, page: number, signal: AbortSignal): Promise<{
-            text: string;
-            source: 'pdf-text' | 'ocr';
-            warnings?: string[];
-            /** Source UTF-16 offsets of conservatively identified paragraph starts. */
-            paragraphBreaks?: number[];
-        }>;
+        /** Synchronous extraction/pipeline identity, independent of embedding selection. */
+        identity?(sessionId: string): string;
+        read(sessionId: string, documentId: string, page: number, signal: AbortSignal): Promise<RetrievalPage>;
     };
     cache?: RetrievalCache;
     embedding?: {
@@ -62,6 +112,22 @@ export interface RetrievalInput {
     maxPages?: number;
     cursor?: string;
 }
+/** Query-free preparation shares the same scoped index as later searches. */
+export type RetrievalPrepareInput = Pick<RetrievalInput, 'documentId' | 'fromPage' | 'maxPages'> & {
+    /** Re-extract and re-embed this source with the selected engine, preserving unrelated indexes. */
+    rebuild?: boolean;
+};
+/** Observable work counts, separate from task completion and document authority. */
+export interface RetrievalProgress {
+    indexedPages: number;
+    totalPages: number;
+    embeddedChunks: number;
+    totalChunks: number;
+    /** Current work, distinct from counters that also advance on cache hits. */
+    phase?: 'restoring' | 'extracting' | 'embedding' | 'ready';
+    reusedChunks?: number;
+    computedChunks?: number;
+}
 export interface RetrievalResult {
     status: 'building' | 'complete' | 'incomplete';
     requestedMode: RetrievalMode;
@@ -76,8 +142,10 @@ export interface RetrievalResult {
     coverage: {
         indexedPages: number;
         totalPages: number;
+        /** No native or OCR text; a generated image description does not imply page transcription. */
         noTextPages: number[];
         ocrPages: number[];
+        imageDescriptionPages: number[];
         failedPages: {
             page: number;
             attempts: number;
@@ -89,18 +157,24 @@ export interface RetrievalResult {
         }[];
         embeddedChunks: number;
         totalChunks: number;
-        visual: 'not-indexed';
+        visual: 'not-indexed' | 'image-descriptions';
     };
-    /** Original text ranges. The caller mints exact evidence refs only for returned hits. */
+    /** Native offsets support exact evidence; generated units require their own
+     * representation provenance and approximate PDF region evidence. */
     chunks: (RetrievalChunk & {
         score: number;
     })[];
     nextCursor?: string;
 }
 export interface RetrievalService {
+    /** Operational state only; never a document access or engine capability grant. */
+    state(): 'ready' | 'rebuilding' | 'failed' | 'disposed';
+    prepare(sessionId: string, input: RetrievalPrepareInput, signal?: AbortSignal, onProgress?: (progress: RetrievalProgress) => void): Promise<void>;
     search(sessionId: string, input: RetrievalInput, signal?: AbortSignal): Promise<RetrievalResult>;
     /** Revalidate after adapter awaits, including reference issuance; never an authorization grant. */
     validate(sessionId: string, result: RetrievalResult): void;
     cancelSession(sessionId: string): void;
+    /** Invalidate active searches and derived caches; later searches rebuild on demand. */
+    rebuild(): Promise<void>;
     dispose(): Promise<void>;
 }

package/dist/types/modules/retrieval/vector.d.ts

@@ -0,0 +1,3 @@
+/** Cosine search is scale-invariant. Normalize in Float64 before compact storage
+ * so finite provider values never overflow or all underflow during conversion. */
+export declare function compactRetrievalVector(input: ArrayLike<number>): Float32Array;

package/dist/types/modules/working-copy/index.d.ts

@@ -1,4 +1,4 @@
-export type { HostWorkspaceSnapshot, WorkingCopyReadPort, DocumentResidency, DocumentReleaseStatus } from './ports.js';
+export type { HostWorkspaceSnapshot, WorkingCopyReadPort, DocumentResidency, DocumentReleaseStatus, OpenWorkingCopyDocument } from './ports.js';
 export { createWorkingCopyService } from './service.js';
 export type { PdfDocumentPort, V1DraftPort, WorkingCopyDraftPort, WorkingCopyAgent, WorkingCopyFilePort, WorkingCopyFileRead, } from './ports.js';
 export type { DraftRecord, WorkspaceRecord } from './schema.js';

package/dist/types/modules/working-copy/ports.d.ts

@@ -18,6 +18,17 @@ export interface DocumentResidency {
     modelReferenceId?: string;
     pins: number;
 }
+/** Open ownership and source identity only; operation pins never constitute an open document. */
+export interface OpenWorkingCopyDocument {
+    sessionId: string;
+    id: string;
+    /** Canonical resource identity remains available after idle working-set eviction. */
+    path?: string;
+    contentVersion: string;
+    sourceDigest: string;
+    conflict: boolean;
+    title?: string;
+}
 /** Minimum authority needed by read-only features after session authorization. */
 export interface WorkingCopyReadPort {
     readSnapshot(sessionId: string, documentId: string): HostWorkspaceSnapshot;

package/dist/types/modules/working-copy/service.d.ts

@@ -1,4 +1,5 @@
-import type { HostWorkspaceSnapshot, PdfDocumentPort, WorkingCopyDraftPort, WorkingCopyAgent, WorkingCopyFilePort, DocumentReleaseStatus, DocumentResidency } from './ports.js';
+import type { PdfDocumentInfo } from '../../core/pdf-types.js';
+import type { HostWorkspaceSnapshot, PdfDocumentPort, WorkingCopyDraftPort, WorkingCopyAgent, WorkingCopyFilePort, DocumentReleaseStatus, DocumentResidency, OpenWorkingCopyDocument } from './ports.js';
 export type { HostWorkspaceSnapshot } from './ports.js';
 /** Authoritative working copies, serialized per session. A draft is durable before the UI accepts it. */
 export declare function createWorkingCopyService(files: WorkingCopyFilePort, drafts: WorkingCopyDraftPort, pdf: PdfDocumentPort): {
@@ -30,10 +31,21 @@ export declare function createWorkingCopyService(files: WorkingCopyFilePort, dra
         id?: undefined;
         status?: undefined;
     }>;
+    /** Inspect source bytes without acquiring an owner or creating a durable draft. */
+    inspectFile(sessionId: string, path: string, agent: WorkingCopyAgent, signal: AbortSignal): Promise<{
+        path: string;
+        size: number;
+        sourceVersion: string;
+        sourceDigest: string;
+        document: PdfDocumentInfo;
+    }>;
     /** Pin the whole operation, including image decoding or save approval waits. */
     acquire(sessionId: string, id: string, agent: WorkingCopyAgent, signal: AbortSignal): Promise<() => void>;
     touch(sessionId: string, id: string): void;
     onIdle(listener: (sessionId: string, id: string) => void): () => void;
+    listOpenDocuments: () => OpenWorkingCopyDocument[];
+    /** Passive ownership/source notifications; subscribers schedule their own asynchronous work. */
+    onDocumentsChanged(listener: () => void): () => void;
     listDocuments(): DocumentResidency[];
     waitForRevision(sessionId: string, id: string, knownRevision: number, signal: AbortSignal): Promise<number>;
     isUiOwned(sessionId: string, id: string): boolean;

package/dist/types/ocr/types.d.ts

@@ -59,7 +59,8 @@ export interface OcrEngineDescriptor {
     id: string;
     name: string;
     version: string;
-    execution: 'disabled' | 'local' | 'remote';
+    execution: import('../modules/engines/types.js').EngineDescriptor['execution'];
+    capabilities?: import('../modules/engines/types.js').EngineCapability[];
     languages?: readonly string[];
     geometry: readonly ('block' | 'line' | 'word')[];
     confidence: boolean;

package/dist/types/shared/contracts.d.ts

@@ -21,6 +21,10 @@ export interface PdfSettings {
     ocrEngine?: string;
     imageEngine?: string;
     embeddingEngine?: string;
+    /** Recognize scanned or damaged pages with the selected OCR engine while indexing. */
+    indexScanPages?: boolean;
+    /** Optional generated whole-page visual descriptions, independently of OCR. */
+    indexImageDescriptions?: boolean;
     engineConfigurations?: import('../modules/engines/types.js').EngineConfigurations;
     ocrTimeoutMs: number;
     translationEngine: string;

package/dist/types/shared/geometry/native-viewport.d.ts

@@ -1,31 +1,13 @@
 import type { PdfPageInfo } from '../../core/pdf-types.js';
 /** PDF user space to CSS pixels; crop, UserUnit, rotation and Y inversion occur once. */
 export declare class NativeViewport {
-    readonly geometry: PdfPageInfo;
     readonly scale: number;
     readonly rotation: number;
-    readonly offsetX: number;
-    readonly offsetY: number;
-    readonly dontFlip: boolean;
-    readonly viewBox: number[];
     readonly userUnit: number;
     readonly width: number;
     readonly height: number;
     readonly transform: number[];
-    readonly rawDims: {
-        pageWidth: number;
-        pageHeight: number;
-        pageX: number;
-        pageY: number;
-    };
     constructor(geometry: PdfPageInfo, scale: number, rotation?: number, offsetX?: number, offsetY?: number, dontFlip?: boolean);
-    clone(options?: {
-        scale?: number;
-        rotation?: number;
-        offsetX?: number;
-        offsetY?: number;
-        dontFlip?: boolean;
-    }): NativeViewport;
     convertToViewportPoint(x: number, y: number): [number, number];
     convertToPdfPoint(x: number, y: number): [number, number];
     convertToViewportRectangle(rect: number[]): number[];

package/dist/types/shared/geometry/text-target.d.ts

@@ -1,17 +1,13 @@
 import type { PdfRect } from '../../core/pdf-types.js';
 import type { NativeTextContent } from '../native.js';
-export interface TextTargetGeometry {
+export interface TextTargetRange {
     rect: PdfRect;
     quadPoints: number[];
-}
-export interface TextTargetRange extends TextTargetGeometry {
     startUtf16: number;
     endUtf16: number;
     text: string;
 }
-/** Resolve bounded start/end anchors against the same joined text exposed by pdf_read_page. */
+/** Resolve bounded start/end anchors against the same joined text exposed by pdf_page_read. */
 export declare function locateTextRange(content: NativeTextContent, startQuote?: string, endQuote?: string, requireReadingOrder?: boolean): TextTargetRange;
 /** Resolve an attested UTF-16 range, including repeated quotes, against native glyphs only. */
 export declare function locateTextOffsetRange(content: NativeTextContent, start: number, end: number, requireReadingOrder?: boolean): TextTargetRange;
-/** Resolve an exact, unique quote to PDF-space glyph geometry, never to a guessed page rectangle. */
-export declare function locateTextTarget(content: NativeTextContent, quote: string): TextTargetGeometry;

package/dist/types/shared/native.d.ts

@@ -29,7 +29,8 @@ export interface NativeTextContent {
         dir: string;
         fontName: string;
         hasEOL: boolean;
-        /** PDF-space origin and advance for each Unicode scalar; omitted for oversized pages. */
+        /** One PDF-space origin/advance per Unicode scalar, including single-scalar runs.
+         * Omitted only when native positioning is unavailable or the page exceeds the frame budget. */
         glyphs?: [x: number, y: number, advance: number][];
     }[];
     styles: Record<string, {

package/dist/types/shared/passive-poll.d.ts

@@ -0,0 +1,4 @@
+/** Compatibility with official Desktop builds whose update admission check expires in 10 seconds.
+ * Read-only subscriptions yield with 5 seconds of headroom; events still wake them immediately.
+ * This budget never bounds writes or active tool work. */
+export declare const PASSIVE_POLL_TIMEOUT_MS = 5000;

package/dist/types/translation/locales.d.ts

@@ -11,7 +11,10 @@ export declare const translationEn: {
     'translation.retry': string;
     'translation.cancel': string;
     'translation.original': string;
-    'translation.reselect': string;
+    'translation.interpretationCorrection': string;
+    'translation.interpretationCompletion': string;
+    'translation.interpretationPossibleCorrection': string;
+    'translation.interpretationPossibleCompletion': string;
     'translation.loading': string;
     'translation.cancelled': string;
     'translation.result': string;
@@ -48,7 +51,5 @@ export declare const translationEn: {
     'translation.errorInvalidModelOutput': string;
     'translation.errorIncompleteModelOutput': string;
     'translation.errorEmptyModelOutput': string;
-    'translation.errorIncompleteSelection': string;
-    'translation.errorUnrecognizedSelection': string;
 };
 export declare const translationZh: Record<keyof typeof translationEn, string>;

package/dist/types/translation/schema.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+/** Shared by model parsing, engine validation and the authenticated Client wire. */
+export declare const interpretationSchema: z.ZodObject<{
+    text: z.ZodString;
+    kind: z.ZodEnum<{
+        correction: "correction";
+        completion: "completion";
+    }>;
+    certainty: z.ZodEnum<{
+        confident: "confident";
+        tentative: "tentative";
+    }>;
+    explanation: z.ZodString;
+}, z.core.$strict>;

package/dist/types/translation/types.d.ts

@@ -2,7 +2,7 @@ export type TranslationJson = null | boolean | number | string | TranslationJson
     [key: string]: TranslationJson;
 };
 export type TranslationConfiguration = Readonly<Record<string, TranslationJson>>;
-export type TranslationErrorCode = 'disabled' | 'not-configured' | 'engine-unavailable' | 'authentication-failed' | 'invalid-request' | 'limit-exceeded' | 'timeout' | 'cancelled' | 'stale-result' | 'translation-failed' | 'invalid-model-output' | 'incomplete-model-output' | 'empty-model-output' | 'incomplete-selection' | 'unrecognized-selection';
+export type TranslationErrorCode = 'disabled' | 'not-configured' | 'engine-unavailable' | 'authentication-failed' | 'invalid-request' | 'limit-exceeded' | 'timeout' | 'cancelled' | 'stale-result' | 'translation-failed' | 'invalid-model-output' | 'incomplete-model-output' | 'empty-model-output';
 export declare class TranslationError extends Error {
     readonly code: TranslationErrorCode;
     constructor(code: TranslationErrorCode, message: string, options?: ErrorOptions);
@@ -39,12 +39,22 @@ export interface TranslationEngineRequest extends Omit<TranslationRequest, 'sign
     timeoutMs: number;
     maxOutputCharacters: number;
 }
+/** The source used for this result, distinct from the user's unchanged selection.
+ * Certainty is the engine's assessment, not proof that a completion is original. */
+export interface TranslationInterpretation {
+    text: string;
+    kind: 'correction' | 'completion';
+    certainty: 'confident' | 'tentative';
+    explanation: string;
+}
 export interface TranslationOutput {
     text: string;
     status: 'complete' | 'partial';
     /** Stable warning identifiers suitable for localization by the consuming UI. */
     warnings: string[];
     detectedSourceLanguage?: string;
+    /** Omit when translating the selection as-is. Never write this back to the PDF. */
+    interpretation?: TranslationInterpretation;
     /** Lexical detail is present only when an engine can validate it. */
     detail?: {
         kind: 'word' | 'phrase';
@@ -63,7 +73,7 @@ export interface TranslationEngineDescriptor {
     id: string;
     name: string;
     version: string;
-    execution: 'disabled' | 'local' | 'remote';
+    execution: import('../modules/engines/types.js').EngineDescriptor['execution'];
     maxInputCharacters?: number;
     configurationFields?: import('../modules/engines/types.js').EngineConfigurationField[];
 }