@exige/web-scanner-sdk 0.2.0

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,76 @@
+/**
+ * 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;
+    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` 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, redaction,
+ * and vehicle entry points. Throws before those APIs do any work.
+ */
+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/ocr.d.ts

@@ -0,0 +1,75 @@
+import { type CastShadowAnalysis } from './lighting';
+import type { ImageSource, OcrBox, OcrResult } from './types';
+export interface OcrOptions {
+    language?: string;
+    /**
+     * Minimum normalized confidence accepted for OCR tokens, from 0 to 1.
+     * Defaults to 0.5. Words and characters are filtered independently.
+     */
+    minConfidence?: number;
+    /**
+     * Re-reads one low-yield phone/hand cast-shadow tile after local
+     * illumination normalization. Defaults to true.
+     */
+    shadowPass?: boolean;
+    includeWords?: boolean;
+    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;
+export declare function recognizeText(source: ImageSource, options?: OcrOptions): Promise<OcrResult>;
+export {};

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

@@ -0,0 +1,102 @@
+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';
+export interface SemanticRedactionRule {
+    id: string;
+    strategy: 'semantic';
+    field: SemanticField;
+}
+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[];
+    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 {
+    ocr?: OcrResult;
+    style?: RedactOptions;
+    requireAll?: boolean;
+    models?: {
+        fields?: string;
+        fieldClasses?: SemanticField[];
+        confidence?: number;
+        allowHeuristicFallback?: boolean;
+    };
+}
+export interface ProgrammaticRedactionResult extends RedactionMatchResult {
+    status: 'success' | 'partial' | 'unmatched';
+    ocr?: OcrResult;
+    canvas?: HTMLCanvasElement;
+    blob?: Blob;
+    modelStatus: 'not-requested' | 'loaded' | 'fallback' | 'failed';
+    modelError?: string;
+}
+export declare function matchRedactionRules(ocr: OcrResult | undefined, options: MatchRedactionOptions): RedactionMatchResult;
+export declare function redactionStatus(summary: RedactionMatchResult, requireAll?: boolean): ProgrammaticRedactionResult['status'];
+export declare function redactProgrammatically(image: ImageSource, options: ProgrammaticRedactionOptions): Promise<ProgrammaticRedactionResult>;

package/dist/sdk/redact.d.ts

@@ -0,0 +1,12 @@
+import type { ImageSource, RedactionRegion, RedactOptions } from './types';
+export interface RedactResult {
+    canvas: HTMLCanvasElement;
+    blob: Blob;
+}
+/**
+ * Applies redaction regions to a copy of an image and encodes the result.
+ *
+ * The source is not mutated. Regions use source-image pixel coordinates and
+ * are clipped to the image bounds.
+ */
+export declare function applyRedactions(source: ImageSource, regions: RedactionRegion[], options?: RedactOptions): Promise<RedactResult>;

package/dist/sdk/scan.d.ts

@@ -0,0 +1,32 @@
+import type { DocumentCorners, DocumentDetectionResult, DocumentDetectorMode, ImageSource, ScanResult } from './types';
+export interface ScanOptions {
+    minDimension?: number;
+    edgeThreshold?: number;
+    minConfidence?: number;
+    maxAnalysisDimension?: number;
+    maxOutputDimension?: number;
+    useWorker?: boolean;
+    /** OR the current edge map with recent frames; useful for live finder input. */
+    temporalEdgeWindow?: number;
+    /** Enables experimental Hough line assembly when no connected contour survives. */
+    lineFallback?: boolean;
+    /** Selects zero-download classical detection, strict ML, or ML with classical fallback. */
+    detector?: DocumentDetectorMode;
+    /** URL of a DocAligner-compatible [1,3,256,256] ONNX heatmap model. */
+    modelUrl?: string;
+    /** Heatmap threshold used before largest-component corner centroids. */
+    heatmapThreshold?: number;
+    /** Reuse model bytes through the browser HTTP cache. */
+    cacheModel?: boolean;
+    /** Base URL for ONNX Runtime WASM files when WebGPU is unavailable. */
+    ortWasmPaths?: string;
+}
+export declare const DEFAULT_DOCUMENT_MODEL_URL = "https://exige-scanner-sdk.vercel.app/models/docaligner-lcnet100-f4117b78.onnx";
+export declare function resolveDocumentModelUrl(detector?: DocumentDetectorMode, modelUrl?: string): string | undefined;
+export declare function perspectiveOutputSize(corners: DocumentCorners, maxDimension: number): {
+    width: number;
+    height: number;
+};
+export declare function detectDocument(source: ImageSource, options?: ScanOptions): Promise<DocumentDetectionResult>;
+export declare function cropDocument(source: ImageSource, corners: DocumentCorners, options?: Pick<ScanOptions, 'maxOutputDimension'>): Promise<ScanResult>;
+export declare function scanDocument(source: ImageSource, options?: ScanOptions): Promise<ScanResult>;

package/dist/sdk/types.d.ts

@@ -0,0 +1,92 @@
+export type ImageSource = Blob | HTMLImageElement | HTMLCanvasElement | ImageBitmap;
+export interface Point {
+    x: number;
+    y: number;
+}
+export interface Box {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface DocumentCorners {
+    topLeft: Point;
+    topRight: Point;
+    bottomRight: Point;
+    bottomLeft: Point;
+}
+export interface DocumentEdge {
+    start: Point;
+    end: Point;
+}
+export interface DocumentQuad extends DocumentCorners {
+    edges: {
+        top: DocumentEdge;
+        right: DocumentEdge;
+        bottom: DocumentEdge;
+        left: DocumentEdge;
+    };
+}
+export type DocumentDetectionStatus = 'success' | 'no-document' | 'low-confidence' | 'low-quality';
+export type DocumentDetectorMode = 'classical' | 'ml' | 'auto';
+export type DocumentModelStatus = 'not-requested' | 'loading' | 'ready' | 'fallback' | 'failed';
+export interface DocumentDetectionResult {
+    status: DocumentDetectionStatus;
+    quad?: DocumentQuad;
+    corners?: DocumentCorners;
+    confidence: number;
+    message: string;
+    sourceWidth: number;
+    sourceHeight: number;
+    detector?: 'classical' | 'ml';
+    modelStatus?: DocumentModelStatus;
+    modelProvider?: 'webgpu' | 'wasm';
+    modelError?: string;
+    inferenceMs?: number;
+}
+export interface ScanResult extends DocumentDetectionResult {
+    canvas?: HTMLCanvasElement;
+}
+export interface OcrResult {
+    /** Text rebuilt from words that meet OcrOptions.minConfidence. */
+    text: string;
+    /** Arithmetic mean of retained word confidence, normalized 0–1; 0 when empty. */
+    confidence: number;
+    language: string;
+    imageWidth: number;
+    imageHeight: number;
+    diagnostics?: OcrDiagnostics;
+    words?: OcrBox[];
+    characters?: OcrBox[];
+}
+export interface OcrDiagnostics {
+    shadowPassUsed: boolean;
+    castShadowStrength: number;
+    shadowRegion?: Box;
+}
+export interface OcrBox {
+    text: string;
+    /** Token confidence normalized to 0–1. */
+    confidence: number;
+    bbox: Box;
+}
+export interface Detection extends Box {
+    id: string;
+    label: string;
+    confidence: number;
+    source: 'model' | 'heuristic';
+}
+export interface DetectOptions {
+    modelUrl?: string;
+    confidence?: number;
+    allowFallback?: boolean;
+}
+export interface RedactionRegion extends Box {
+    mode?: 'blackout' | 'blur';
+}
+export interface RedactOptions {
+    mode?: 'blackout' | 'blur';
+    blurRadius?: number;
+    mimeType?: 'image/png' | 'image/jpeg' | 'image/webp';
+    quality?: number;
+}

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@exige/web-scanner-sdk",
+  "version": "0.2.0",
+  "description": "Client-side document scanning, OCR, YOLO inference, and visual redaction for web apps.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/scanner-sdk.js",
+  "module": "./dist/scanner-sdk.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/scanner-sdk.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./camera-overlay.css": "./dist/components/scanner-camera-overlay.css"
+  },
+  "scripts": {
+    "dev": "vite --config vite.config.app.ts",
+    "build": "npm run build:lib && npm run build:demo",
+    "build:lib": "tsc -b && vite build && tsc -p tsconfig.lib.json",
+    "build:demo": "tsc -b && vite build --config vite.config.app.ts",
+    "vercel-build": "npm run build:demo",
+    "typecheck": "tsc -b",
+    "test": "vitest run",
+    "lint": "oxlint",
+    "preview": "vite preview --config vite.config.app.ts",
+    "docs:api": "typedoc",
+    "docs:dev": "npm run docs:api && vitepress dev site --host 0.0.0.0 --port 43261",
+    "docs:build": "npm run docs:api && vitepress build site",
+    "docs:preview": "vitepress preview site --host 0.0.0.0 --port 43261",
+    "dev:portal": "npm --prefix license-portal run dev",
+    "test:portal": "npm --prefix license-portal test"
+  },
+  "dependencies": {
+    "onnxruntime-web": "^1.30.0",
+    "tesseract.js": "^7.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.7",
+    "@vitejs/plugin-react": "^6.1.1",
+    "oxlint": "^1.81.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.13.1",
+    "typescript": "~6.0.2",
+    "vite": "^8.3.0",
+    "vitepress": "^1.6.4",
+    "vitest": "^5.0.1"
+  }
+}