@exige/web-scanner-sdk 0.2.9

package/dist/sdk/finder.d.ts

@@ -0,0 +1,174 @@
+import { type ScanOptions } from './scan';
+import type { DocumentDetectionResult, DocumentModelStatus, DocumentQuad } from './types';
+export type AutoCaptureMode = 'defaultOn' | 'defaultOff' | 'alwaysOn' | 'alwaysOff' | 'only';
+export type FinderSource = HTMLVideoElement | MediaStream | HTMLCanvasElement;
+export type FinderState = 'seeking' | 'detecting' | 'unstable' | 'ready' | 'captured';
+export type FinderGuidanceReason = 'place-document' | 'move-closer' | 'move-farther-away' | 'straighten-camera' | 'hold-still' | 'ready';
+export interface QuadFill {
+    /** Raw quad bounds width divided by the analysis frame width. */
+    widthFill: number;
+    /** Raw quad bounds height divided by the analysis frame height. */
+    heightFill: number;
+    /** Fill on the limiting axis: `max(widthFill, heightFill)`. */
+    limitingFill: number;
+    /** Shoelace polygon area divided by the analysis frame area. Diagnostic only. */
+    areaFill: number;
+    /** Long side divided by short side of the raw quad. */
+    aspectRatio: number;
+}
+export interface FinderGuidance {
+    hint: string;
+    reason: FinderGuidanceReason;
+    /**
+     * Fill on the limiting axis of the raw quad: the larger of its width and
+     * height fill. A tall receipt that fills the frame height is fully framed
+     * even though its bounding box covers little frame area.
+     */
+    fillRatio: number;
+    /** Component fills, polygon area fill, and aspect ratio behind `fillRatio`. */
+    fill: QuadFill;
+    readyForAutoCapture: boolean;
+}
+export interface FinderLighting {
+    castShadow: boolean;
+    strength: number;
+    hint?: string;
+}
+export declare function selectFinderHint(guidance: FinderGuidance, lighting: FinderLighting): string;
+export interface AutoCaptureControl {
+    visible: boolean;
+    checked: boolean;
+    mutable: boolean;
+}
+export interface FinderStatus {
+    state: FinderState;
+    confidence: number;
+    quad?: DocumentQuad;
+    guidance: FinderGuidance;
+    lighting: FinderLighting;
+    stableFrames: number;
+    requiredStableFrames: number;
+    autoCapture: AutoCaptureControl;
+    sourceWidth?: number;
+    sourceHeight?: number;
+    detector?: DocumentDetectionResult['detector'];
+    modelStatus?: DocumentModelStatus;
+    modelProvider?: DocumentDetectionResult['modelProvider'];
+    modelError?: string;
+    inferenceMs?: number;
+}
+export interface FinderCapture {
+    frame: HTMLCanvasElement;
+    detection?: DocumentDetectionResult;
+    reason: 'auto' | 'manual';
+}
+export interface FinderOptions {
+    source: FinderSource;
+    autoCapture: AutoCaptureMode;
+    /** Supplies the final full-resolution frame while finder analysis stays bounded. */
+    captureFrame?: () => HTMLCanvasElement | Promise<HTMLCanvasElement>;
+    onStatus?: (status: FinderStatus) => void;
+    onCapture?: (capture: FinderCapture) => void | Promise<void>;
+    /** Reports capture failures, including automatic captures, instead of swallowing them. */
+    onCaptureError?: (error: Error) => void;
+    /** Consecutive stable raw detections required. Defaults to 4. */
+    stableFrames?: number;
+    /** Minimum detector confidence on the normalized 0–1 scale. Defaults to 0.72. */
+    confidenceThreshold?: number;
+    /** Maximum normalized corner movement while entering ready. Defaults to 0.024. */
+    cornerTolerance?: number;
+    /** Movement allowed after ready before dropping out. Defaults to 0.036. */
+    exitCornerTolerance?: number;
+    intervalMs?: number;
+    maxFrameDimension?: number;
+    guidance?: FinderGuidanceOptions;
+    detection?: ScanOptions;
+    playShutterSound?: boolean;
+}
+export interface FinderSession {
+    stop: () => void;
+    capture: () => Promise<FinderCapture>;
+    setAutoCapture: (enabled: boolean) => boolean;
+    getStatus: () => FinderStatus;
+}
+export declare function snapshotBeforeCaptureFeedback<T>(snapshot: () => T | Promise<T>, feedback: () => void): Promise<T>;
+export declare function autoCaptureControl(mode: AutoCaptureMode): AutoCaptureControl;
+export interface StabilityOptions {
+    stableFrames: number;
+    confidenceThreshold: number;
+    cornerTolerance: number;
+    exitCornerTolerance?: number;
+}
+export interface FinderGuidanceOptions {
+    confidenceThreshold?: number;
+    /** Limiting-axis fill required to enter ready. Defaults to 0.72. */
+    minFillRatio?: number;
+    /** Limiting-axis fill allowed after ready before exiting. Defaults to 0.64. */
+    exitFillRatio?: number;
+    /** Long-to-short side ratio that makes a document high-aspect. Defaults to 2.2. */
+    highAspectRatio?: number;
+    /** Long-side fill required to enter ready on a high-aspect document. Defaults to 0.8. */
+    highAspectFillRatio?: number;
+    /** Long-side fill allowed after ready on a high-aspect document. Defaults to 0.72. */
+    highAspectExitFillRatio?: number;
+    /** Edge clearance required to enter ready. Defaults to 0.015. */
+    edgeMarginRatio?: number;
+    /** Edge clearance allowed after ready. Defaults to 0.005. */
+    exitEdgeMarginRatio?: number;
+    /** Opposite-edge ratio required to enter ready. Defaults to 0.48. */
+    minPerspectiveRatio?: number;
+    /** Opposite-edge ratio allowed after ready. Defaults to 0.4. */
+    exitMinPerspectiveRatio?: number;
+}
+export declare const DEFAULT_FINDER_STABLE_FRAMES = 4;
+export declare const DEFAULT_FINDER_CONFIDENCE_THRESHOLD = 0.72;
+export declare const DEFAULT_FINDER_CORNER_TOLERANCE = 0.024;
+export declare const DEFAULT_FINDER_EXIT_CORNER_TOLERANCE = 0.036;
+export declare const DEFAULT_FINDER_MIN_FILL_RATIO = 0.72;
+export declare const DEFAULT_FINDER_EXIT_FILL_RATIO = 0.64;
+export declare const DEFAULT_FINDER_HIGH_ASPECT_RATIO = 2.2;
+/** Extra long-side fill asked of a high-aspect document, above the base target. */
+export declare const DEFAULT_FINDER_HIGH_ASPECT_FILL_MARGIN = 0.08;
+export declare const DEFAULT_FINDER_EDGE_MARGIN_RATIO = 0.015;
+export declare const DEFAULT_FINDER_EXIT_EDGE_MARGIN_RATIO = 0.005;
+export declare const DEFAULT_FINDER_MIN_PERSPECTIVE_RATIO = 0.48;
+export declare const DEFAULT_FINDER_EXIT_MIN_PERSPECTIVE_RATIO = 0.4;
+/**
+ * Measures how much of each frame axis the raw quad occupies. A document can
+ * only grow until its limiting axis reaches a frame edge, so the larger of the
+ * two axis fills — not the bounding-box area — describes how well it is framed.
+ */
+export declare function measureQuadFill(quad: DocumentQuad, frameWidth: number, frameHeight: number): QuadFill;
+/**
+ * Fill the limiting axis must reach. High-aspect documents are asked for a
+ * little more of the long side, because their short side can never fill and
+ * the long side is the only axis carrying resolution. The target never exceeds
+ * what the edge margin physically allows.
+ */
+export declare function limitingFillTarget(fill: QuadFill, previouslyReady: boolean, edgeMarginRatio: number, options?: FinderGuidanceOptions): number;
+export declare function selectFinderGuidance(detection: DocumentDetectionResult, stability: {
+    ready: boolean;
+    previouslyReady?: boolean;
+}, options?: FinderGuidanceOptions): FinderGuidance;
+export declare class QuadStabilityTracker {
+    private previous?;
+    private count;
+    private ready;
+    private readonly options;
+    constructor(options: StabilityOptions);
+    reset(): void;
+    update(detection: DocumentDetectionResult): {
+        stableFrames: number;
+        ready: boolean;
+        movement: number;
+    };
+}
+/**
+ * Watches a camera or canvas for a stable document.
+ * Detection quality is reported on `FinderStatus`, not thrown.
+ * Worker startup and DocAligner HTTP failures are caught on each tick and
+ * reported as `modelStatus: 'failed'` with `modelError`. The camera stays up.
+ *
+ * @throws {LicenseError} LicenseError when the scan feature is not licensed. The finder does not start.
+ */
+export declare function startFinder(options: FinderOptions): Promise<FinderSession>;

package/dist/sdk/frame-geometry.d.ts

@@ -0,0 +1,6 @@
+import type { DocumentCorners } from './types';
+export interface FrameSize {
+    width: number;
+    height: number;
+}
+export declare function mapDocumentCornersToFrame(corners: DocumentCorners, source: FrameSize, target: FrameSize): DocumentCorners;

package/dist/sdk/image.d.ts

@@ -0,0 +1,18 @@
+import type { ImageSource } from './types';
+export interface CanvasSourceOptions {
+    cloneCanvas?: boolean;
+    maxDimension?: number;
+}
+export declare function sourceToCanvas(source: ImageSource, options?: CanvasSourceOptions): Promise<HTMLCanvasElement>;
+export declare function canvasToBlob(canvas: HTMLCanvasElement, type?: string, quality?: number): Promise<Blob>;
+export declare function clampBox(box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, width: number, height: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};

package/dist/sdk/license-codec.d.ts

@@ -0,0 +1,2 @@
+export declare function bytesToBase64Url(bytes: Uint8Array): string;
+export declare function base64UrlToBytes(value: string): Uint8Array;

package/dist/sdk/license-public-key.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Raw Ed25519 public key: 32 bytes, base64url, no padding.
+ *
+ * The license portal signs with `LICENSE_SIGNING_PRIVATE_KEY`.
+ * Generate a pair with `npm run generate-keypair --prefix license-portal`,
+ * then replace this constant with the printed public key and rebuild the
+ * library. Never commit the private key.
+ */
+export declare const LICENSE_PUBLIC_KEY_BASE64 = "uFpA_UXGk-1AjjG31cFP6cqXOQX0w2TnuR7Bl-msZ6I";

package/dist/sdk/license-runtime.d.ts

@@ -0,0 +1,2 @@
+/** Public key embedded in the published package. Tests replace this module. */
+export declare function embeddedLicensePublicKey(): Uint8Array;

package/dist/sdk/license.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Hosts that may use the SDK before a paid license exists.
+ * Add a production hostname here when it should run without a signed key.
+ *
+ * An entry is either an exact hostname or a single `*.suffix` pattern.
+ * `*.exige.io` matches `exige.io` and any host that ends with `.exige.io`.
+ * It does not match `exige.io.evil.com`. Other entries are exact:
+ * `exige-park-app.ngrok.io` does not allow the rest of ngrok, and nothing
+ * here allows `*.vercel.app`. Paid license `domains` stay exact hostnames.
+ */
+export declare const DEV_LICENSE_HOSTS: readonly ["localhost", "127.0.0.1", "exige-scanner-sdk.vercel.app", "exige-park-app.ngrok.io", "*.exige.io"];
+export declare const LICENSE_FEATURES: readonly ["scan", "ocr", "redaction", "vehicles", "torch"];
+export type LicenseFeature = (typeof LICENSE_FEATURES)[number];
+export type LicenseErrorCode = 'missing' | 'malformed' | 'invalid-signature' | 'expired' | 'domain' | 'feature';
+export interface LicenseFeatures {
+    scan: boolean;
+    ocr: boolean;
+    redaction: boolean;
+    /**
+     * Kept so existing signed keys still verify.
+     * No camera, finder, scan, OCR, or redaction entry point asserts this flag.
+     */
+    vehicles: boolean;
+    torch: boolean;
+}
+export interface LicenseClaims {
+    customerId: string;
+    /** Exact hostnames. `localhost` and `127.0.0.1` are included only when listed. */
+    domains: string[];
+    /** Unix expiry in seconds. The key is valid while `now < exp`. */
+    exp: number;
+    features: LicenseFeatures;
+}
+/**
+ * Compact signed payload: `base64url(json).base64url(ed25519 signature)`.
+ * The signature covers the raw JSON bytes. Public APIs do not accept a
+ * caller-supplied public key or hostname.
+ */
+export interface LicenseVerification {
+    publicKey: Uint8Array;
+    /** Injected only for Node tests. Browsers use `location.hostname`. */
+    hostname: string;
+    /** Unix time in seconds. */
+    now: number;
+}
+export declare class LicenseError extends Error {
+    readonly code: LicenseErrorCode;
+    constructor(code: LicenseErrorCode, message: string);
+}
+export declare function normalizeHostname(value: string): string;
+/**
+ * Canonical JSON signed by the license portal. Key order is part of the
+ * signature bytes. Keep this in lockstep with `license-portal/lib/license-token.ts`.
+ */
+export declare function canonicalLicensePayload(claims: LicenseClaims): string;
+/**
+ * Verifies a compact license. Hostname and public key are explicit so Node
+ * tests can inject them. Published entry points call `assertLicense`, which
+ * always uses the embedded public key and `location.hostname`.
+ */
+export declare function verifyLicenseToken(licenseKey: string, verification: LicenseVerification): Promise<LicenseClaims>;
+/**
+ * Verifies `licenseKey` for the current page and keeps it for later calls.
+ *
+ * @throws {LicenseError} LicenseError when the key is missing, malformed, badly signed,
+ * expired, or not issued for `location.hostname`.
+ */
+export declare function setLicenseKey(licenseKey: string): Promise<LicenseClaims>;
+/**
+ * Feature flags from the key most recently accepted by `setLicenseKey`.
+ * Returns null when no key is loaded, the key is expired, or this hostname
+ * is not on the key. Enforcement still re-checks the signature in `assertLicense`.
+ */
+export declare function getLicense(): LicenseClaims | null;
+/**
+ * Fail-closed gate used by the public camera, finder, scan, OCR, and
+ * redaction entry points.
+ *
+ * @throws {LicenseError} LicenseError before those APIs do any work, when the key is
+ * missing, invalid, or missing `feature`.
+ */
+export declare function assertLicense(feature: LicenseFeature): Promise<LicenseClaims>;
+/** Drops the in-memory key. Not part of the published package entry. */
+export declare function clearLicenseForTests(): void;

package/dist/sdk/lighting.d.ts

@@ -0,0 +1,22 @@
+import type { DocumentQuad } from './types';
+export interface CastShadowRegion {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface CastShadowAnalysis {
+    strong: boolean;
+    strength: number;
+    darkness: number;
+    areaRatio: number;
+    region?: CastShadowRegion;
+}
+/**
+ * Finds a connected, page-sized dark blob in any direction. A component must
+ * cover meaningful area and contain local contrast, distinguishing cast
+ * shadows over printed paper from a dark border or isolated illustration.
+ */
+export declare function analyzeCastShadowLuminance(luminance: Uint8Array, width: number, height: number, gridSize?: number): CastShadowAnalysis;
+export declare function flattenIlluminationLuminance(luminance: Uint8Array, width: number, height: number, radius?: number): Uint8Array<ArrayBuffer>;
+export declare function analyzeCanvasCastShadow(canvas: HTMLCanvasElement, quad: DocumentQuad): CastShadowAnalysis;

package/dist/sdk/model-download.d.ts

@@ -0,0 +1,25 @@
+export interface ModelDownloadProgress {
+    loaded: number;
+    /** Byte length from Content-Length. Null when that header is absent. */
+    total: number | null;
+    done?: boolean;
+}
+export interface ModelDownloadSnapshot {
+    downloading: boolean;
+    loaded: number;
+    /** Sum of Content-Length values when every active transfer has one. */
+    total: number | null;
+}
+export declare function modelDownloadSnapshot(): ModelDownloadSnapshot;
+/** Subscribing does not fetch. Downloads start only from `downloadModelBytes`. */
+export declare function subscribeModelDownloads(listener: (snapshot: ModelDownloadSnapshot) => void): () => void;
+/** Progress reported from another realm, such as the document worker. */
+export declare function reportModelDownload(url: string, progress: ModelDownloadProgress): void;
+export declare function readResponseBytes(response: Response, onProgress?: (progress: ModelDownloadProgress) => void): Promise<ArrayBuffer>;
+/**
+ * Fetch a model file and report loaded/total while the body transfers.
+ * A second call for the same URL reuses the cached bytes and does not fetch.
+ */
+export declare function downloadModelBytes(url: string, init?: {
+    cache?: RequestCache;
+}): Promise<ArrayBuffer>;

package/dist/sdk/ocr-runtime.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Browser files copied from tesseract.js 7, tesseract.js-core 7.0.0 LSTM builds,
+ * and @tesseract.js-data/eng 4.0.0_best_int. Literal `new URL` keeps them visible
+ * to Webpack and Turbopack.
+ */
+export declare const tesseractWorkerUrl: URL;
+export declare const tesseractCoreLstmUrl: URL;
+export declare const tesseractCoreSimdLstmUrl: URL;
+export declare const tesseractCoreRelaxedSimdLstmUrl: URL;
+export declare const bundledEnglishTraineddataUrl: URL;
+export interface LstmCoreSupport {
+    relaxedSimd: boolean;
+    simd: boolean;
+}
+/** Same relaxed-SIMD then SIMD order as tesseract.js `getCore` for an LSTM core. */
+export declare function detectLstmCoreSupport(): LstmCoreSupport;
+export declare function selectLstmCoreUrl(support: LstmCoreSupport): URL;
+export type OcrLanguagePlan = {
+    kind: 'bundled-eng';
+    language: 'eng';
+} | {
+    kind: 'lang-path';
+    language: string;
+    langPath: string;
+};
+export declare function resolveOcrLanguage(language?: string, langPath?: string): OcrLanguagePlan;
+export declare function loadBundledEnglishTraineddata(): Promise<Uint8Array<ArrayBuffer>>;

package/dist/sdk/ocr.d.ts

@@ -0,0 +1,104 @@
+import { type CastShadowAnalysis } from './lighting';
+import type { ImageSource, OcrBox, OcrResult } from './types';
+export interface OcrOptions {
+    /**
+     * Tesseract language code. Defaults to `eng`, which loads the packaged
+     * English LSTM traineddata. Any other code needs `langPath`.
+     */
+    language?: string;
+    /**
+     * Directory URL that contains `${language}.traineddata.gz`.
+     * Required when `language` is not `eng`. For `eng`, set this only to
+     * replace the packaged English model.
+     */
+    langPath?: string;
+    /**
+     * Minimum normalized confidence accepted for OCR tokens, from 0 to 1.
+     * Defaults to 0.5. Words and characters are filtered independently.
+     * A value outside 0–1 throws `RangeError`.
+     */
+    minConfidence?: number;
+    /**
+     * Re-reads one low-yield phone/hand cast-shadow tile after local
+     * illumination normalization. Defaults to true.
+     */
+    shadowPass?: boolean;
+    /**
+     * Include word boxes on the result. Defaults to false.
+     * Redaction that matches words needs `true`.
+     */
+    includeWords?: boolean;
+    /**
+     * Include character boxes on the result. Defaults to false.
+     */
+    includeCharacters?: boolean;
+    onProgress?: (progress: number, status: string) => void;
+}
+interface TesseractBbox {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+interface TesseractSymbol {
+    text: string;
+    confidence: number;
+    bbox: TesseractBbox;
+}
+interface TesseractWord {
+    text: string;
+    confidence: number;
+    bbox: TesseractBbox;
+    symbols: TesseractSymbol[];
+}
+interface TesseractBlock {
+    paragraphs: Array<{
+        lines: Array<{
+            words: TesseractWord[];
+        }>;
+    }>;
+}
+export interface OcrPass {
+    blocks: TesseractBlock[] | null;
+    /** Maps pass coordinates back into the original input image. */
+    scaleX?: number;
+    scaleY?: number;
+    offsetX?: number;
+    offsetY?: number;
+}
+export declare function mergeOcrPasses(passes: OcrPass[], options: Pick<OcrOptions, 'minConfidence' | 'includeWords' | 'includeCharacters'>, imageSize?: {
+    width: number;
+    height: number;
+}, inkDensity?: (box: OcrBox['bbox']) => number): {
+    text: string;
+    confidence: number;
+    words: OcrBox[];
+    characters: OcrBox[];
+};
+export declare function extractOcrLayout(blocks: TesseractBlock[] | null, options: Pick<OcrOptions, 'minConfidence' | 'includeWords' | 'includeCharacters'>): {
+    text: string;
+    confidence: number;
+    words: OcrBox[];
+    characters: OcrBox[];
+};
+export declare function extractOcrBoxes(blocks: TesseractBlock[] | null, options: Pick<OcrOptions, 'minConfidence' | 'includeWords' | 'includeCharacters'>): {
+    words: OcrBox[];
+    characters: OcrBox[];
+};
+export declare function shadowRegionNeedsOcr(analysis: CastShadowAnalysis, words: OcrBox[], imageSize: {
+    width: number;
+    height: number;
+}): boolean;
+/**
+ * Reads text from a browser image. English uses the packaged traineddata.
+ * `includeWords` and `includeCharacters` default to false.
+ * `minConfidence` defaults to 0.5.
+ *
+ * @throws {LicenseError} LicenseError when the OCR feature is not licensed. Recognition does not start.
+ * @throws {RangeError} RangeError when `minConfidence` is outside 0–1.
+ * @throws {ScannerError} ScannerError `language` when `language` is not `eng` and `langPath` is omitted.
+ * `canvas` when canvas 2D is unavailable.
+ * `model-http` when the packaged English traineddata request fails.
+ */
+export declare function recognizeText(source: ImageSource, options?: OcrOptions): Promise<OcrResult>;
+export {};

package/dist/sdk/ort-runtime.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ONNX Runtime Web 1.30 extern-wasm JSEP build (WebGPU, then WASM).
+ * Literal `new URL` calls are what Webpack and Turbopack copy.
+ */
+export declare const packagedOrtWasmFile: URL;
+export declare const packagedOrtWasmGlue: URL;
+export interface PackagedOrtWasmPaths {
+    wasm: string;
+    mjs: string;
+}
+/**
+ * Override for the packaged ONNX Runtime files.
+ * A string is a directory that contains `ort-wasm-simd-threaded.jsep.wasm`
+ * and `ort-wasm-simd-threaded.jsep.mjs`. An object sets each file URL.
+ * Omit the option to use the copies shipped with the SDK.
+ */
+export type OrtWasmPaths = string | {
+    wasm: string;
+    mjs: string;
+};
+export declare function packagedOrtWasmPaths(): PackagedOrtWasmPaths;
+/** Uses the packaged wasm pair when the override is missing or blank. */
+export declare function resolveOrtWasmPaths(value?: OrtWasmPaths): OrtWasmPaths;

package/dist/sdk/programmatic-redaction.d.ts

@@ -0,0 +1,151 @@
+import { type FaceDetection } from './face-model';
+import { type FieldLayout } from './field-model';
+import type { Box, ImageSource, OcrResult, RedactOptions } from './types';
+export type StringMatchMode = 'exact' | 'case-insensitive' | 'regex';
+export type LabelDirection = 'above' | 'below' | 'left' | 'right' | 'any';
+export interface StringRedactionRule {
+    id: string;
+    strategy: 'string';
+    mode: StringMatchMode;
+    values?: string[];
+    pattern?: string;
+    flags?: string;
+    scope?: 'word' | 'line';
+}
+export interface LabelRedactionRule {
+    id: string;
+    strategy: 'label';
+    label: string;
+    direction: LabelDirection;
+    labelMode?: 'exact' | 'case-insensitive';
+    valuePattern?: string;
+    patternFlags?: string;
+    window?: {
+        distance?: number;
+        crossAxis?: number;
+    };
+    redactLabel?: boolean;
+}
+export type SemanticField = 'person_name' | 'date_of_birth' | 'address' | 'document_number' | 'expiration_date' | 'postal_code' | 'state';
+/** `logical` uses aliases, MRZ, and layout. `model` uses a field ONNX. */
+export type SemanticFieldDetector = 'logical' | 'model';
+export interface SemanticRedactionRule {
+    id: string;
+    strategy: 'semantic';
+    field: SemanticField;
+    /**
+     * Defaults to `logical`. A loaded field model does not replace logical rules.
+     * Set `model` on a separate rule to redact from `models.fields` or `semanticDetections`.
+     */
+    detector?: SemanticFieldDetector;
+}
+export interface SemanticModelDetection {
+    field: SemanticField;
+    bbox: Box;
+    confidence: number;
+}
+export type ProgrammaticRedactionRule = StringRedactionRule | LabelRedactionRule | SemanticRedactionRule;
+export interface NormalizedRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface TemplateRectField {
+    id: string;
+    strategy: 'rect';
+    rect: NormalizedRect;
+}
+export interface TemplateAnchorField extends Omit<LabelRedactionRule, 'id' | 'strategy'> {
+    id: string;
+    strategy: 'anchor';
+}
+export type RedactionTemplateField = TemplateRectField | TemplateAnchorField;
+export interface RedactionTemplate {
+    id: string;
+    fields: RedactionTemplateField[];
+}
+export interface MatchRedactionOptions {
+    rules: ProgrammaticRedactionRule[];
+    template?: RedactionTemplate;
+    imageWidth?: number;
+    imageHeight?: number;
+    semanticDetections?: SemanticModelDetection[];
+    /**
+     * When true, rules with `detector: 'model'` use `semanticDetections`.
+     * Logical rules ignore this flag.
+     */
+    modelRequested?: boolean;
+}
+export interface RedactionMatch {
+    ruleId: string;
+    strategy: 'string' | 'label' | 'template-rect' | 'template-anchor' | 'semantic';
+    source?: 'string' | 'label' | 'template' | 'alias' | 'mrz' | 'layout' | 'model';
+    bbox: Box;
+    text?: string;
+    confidence: number;
+}
+export interface RedactionMatchResult {
+    matches: RedactionMatch[];
+    unmatchedRuleIds: string[];
+    complete: boolean;
+    confidence: number;
+}
+export interface ProgrammaticRedactionOptions extends MatchRedactionOptions {
+    /**
+     * Prior OCR. Omit it to run OCR with word boxes.
+     * An object without `words` is used as-is. OCR does not re-run, and
+     * word, label, and semantic rules then match nothing.
+     */
+    ocr?: OcrResult;
+    style?: RedactOptions;
+    requireAll?: boolean;
+    models?: {
+        fields?: string;
+        fieldClasses?: SemanticField[];
+        /**
+         * ONNX output layout. Defaults to `yolov8` (`[1, classes+4, anchors]`).
+         * `yolox` is decoded YOLOX-Nano `[1, anchors, 5+classes]`
+         * (`cx, cy, w, h, objectness`, then class scores). A tensor of that shape
+         * is read as YOLOX even when this is omitted.
+         */
+        fieldLayout?: FieldLayout;
+        confidence?: number;
+        /**
+         * When the field model fails to load, model-detector rules use logical finding.
+         * Defaults to true. Logical rules are unchanged either way.
+         */
+        allowHeuristicFallback?: boolean;
+        /**
+         * One-class YOLOX-Nano face ONNX. Boxes are painted on the image.
+         * They do not select OCR words. Omitted means no face model is fetched.
+         */
+        face?: string;
+        faceConfidence?: number;
+    };
+}
+export interface ProgrammaticRedactionResult extends RedactionMatchResult {
+    status: 'success' | 'partial' | 'unmatched';
+    ocr?: OcrResult;
+    canvas?: HTMLCanvasElement;
+    blob?: Blob;
+    modelStatus: 'not-requested' | 'loaded' | 'fallback' | 'failed';
+    modelError?: string;
+    faces: FaceDetection[];
+    faceStatus: 'not-requested' | 'loaded' | 'failed';
+    faceError?: string;
+}
+export declare function matchRedactionRules(ocr: OcrResult | undefined, options: MatchRedactionOptions): RedactionMatchResult;
+export declare function redactionStatus(summary: RedactionMatchResult, requireAll?: boolean): ProgrammaticRedactionResult['status'];
+/**
+ * Matches rules and paints a new canvas.
+ * Returns `success`, `partial`, or `unmatched`. An unmatched rule does not throw.
+ *
+ * Omit `ocr` to run OCR with `includeWords: true`. An `ocr` object without
+ * `words` is used as-is, and OCR does not re-run.
+ * Face blackout is `models.face` on this call.
+ *
+ * @throws {LicenseError} LicenseError when the redaction feature is not licensed. Matching does not start.
+ * @throws {ScannerError} ScannerError `canvas` when canvas 2D is unavailable.
+ */
+export declare function redactProgrammatically(image: ImageSource, options: ProgrammaticRedactionOptions): Promise<ProgrammaticRedactionResult>;

package/dist/sdk/redact.d.ts

@@ -0,0 +1,17 @@
+import type { ImageSource, RedactionRegion, RedactOptions } from './types';
+export interface RedactResult {
+    canvas: HTMLCanvasElement;
+    blob: Blob;
+}
+/**
+ * Paints trusted redaction regions onto a copy of an image and encodes it.
+ * Use this when the rectangles are already known. `redactProgrammatically`
+ * calls it after matching rules.
+ *
+ * The source is not mutated. Regions use source-image pixel coordinates and
+ * are clipped to the image bounds.
+ *
+ * @throws {LicenseError} LicenseError when the redaction feature is not licensed.
+ * @throws {ScannerError} ScannerError `canvas` when canvas 2D is unavailable.
+ */
+export declare function applyRedactions(source: ImageSource, regions: RedactionRegion[], options?: RedactOptions): Promise<RedactResult>;