scanic 1.1.1 → 1.3.0

package/src/scanic.d.ts

@@ -22,12 +22,64 @@ export interface CornerEditorMagnifierOptions {
 }
 
 export interface CornerEditorNudgesOptions {
+  /** Show the on-screen nudge pad. Default false. */
   enabled?: boolean;
+  /** Step sizes (px) to render as nudge buttons. Default [1, 10]. */
   steps?: number[];
 }
 
+export interface CornerEditorToolbarOptions {
+  /** Show the floating toolbar. Default true. */
+  enabled?: boolean;
+  /** Include the Reset button. Default true. */
+  reset?: boolean;
+  /** Include the Cancel button. Default true. */
+  cancel?: boolean;
+  /** Include the Apply button. Default true. */
+  apply?: boolean;
+  /** Override the button labels. */
+  labels?: { reset?: string; cancel?: string; apply?: string };
+}
+
+/**
+ * Programmatic theme overrides. Each maps to a CSS custom property on the host
+ * (e.g. `accent` → `--scanic-accent`). You can also set these variables directly
+ * in your own CSS, or override the `.scanic-*` classes entirely.
+ */
+export interface CornerEditorTheme {
+  /** Primary colour for edges, rings and active handles. */
+  accent?: string;
+  /** Fill colour outside the document quad. */
+  mask?: string;
+  /** Quad outline colour. Defaults to `accent`. */
+  edgeColor?: string;
+  /** Quad outline width (unitless number). */
+  edgeWidth?: number | string;
+  /** Handle diameter. Number is treated as px. */
+  handleSize?: number | string;
+  /** Pointer/touch hit-target size. Number is treated as px. */
+  handleHit?: number | string;
+  /** Handle fill colour (idle). */
+  handleColor?: string;
+  /** Handle ring colour (idle). */
+  handleRingColor?: string;
+  /** Background of the toolbar / nudge pad. */
+  surface?: string;
+  /** Foreground (text) colour of the toolbar / nudge pad. */
+  surfaceColor?: string;
+  /** Corner radius of the toolbar / nudge pad. */
+  radius?: string;
+}
+
+export interface CornerEditorClassNames {
+  root?: string;
+  handle?: string;
+  toolbar?: string;
+  nudges?: string;
+}
+
 export interface CornerEditorOptions {
-  /** Host element the editor canvas is mounted into. */
+  /** Host element the editor is mounted into. */
   container: HTMLElement;
   /** Source image to adjust corners against. */
   image: HTMLImageElement | HTMLCanvasElement | ImageData;
@@ -35,19 +87,26 @@ export interface CornerEditorOptions {
   corners?: CornerPoints;
   magnifier?: CornerEditorMagnifierOptions;
   nudges?: CornerEditorNudgesOptions;
-  /** Touch/click target radius (px) around each handle. Default 48. */
+  /** Floating Reset/Cancel/Apply toolbar. Shown by default. */
+  toolbar?: CornerEditorToolbarOptions;
+  /** Programmatic theme overrides (CSS variables). */
+  theme?: CornerEditorTheme;
+  /** Extra class names applied to editor parts. */
+  classNames?: CornerEditorClassNames;
+  /** Inject the default stylesheet once per document. Default true. */
+  injectStyles?: boolean;
+  /** Pointer/touch target size (px) around each handle. Default 44. */
   handleHitArea?: number;
   /**
-   * Enable keyboard control of the focused canvas (default true):
-   * arrow keys nudge the active corner (Shift = coarse step),
-   * Enter confirms, Escape cancels.
+   * Enable keyboard control (default true): focus a handle, then arrow keys
+   * nudge it (Shift = coarse step), Enter confirms, Escape cancels.
    */
   keyboard?: boolean;
   /** Fired on every corner change (drag, nudge, keyboard). */
   onChange?: (corners: CornerPoints) => void;
-  /** Fired by confirm()/Enter with the final corners. */
+  /** Fired by confirm()/Enter/Apply with the final corners. */
   onConfirm?: (corners: CornerPoints) => void;
-  /** Fired by cancel()/Escape. */
+  /** Fired by cancel()/Escape/Cancel. */
   onCancel?: () => void;
 }
 
@@ -56,14 +115,44 @@ export interface CornerEditor {
   setCorners(corners: CornerPoints): boolean;
   reset(): void;
   nudge(cornerKey: keyof CornerPoints, dx: number, dy: number, step?: number): boolean;
+  /** Re-read CSS variables into the canvas layer after a runtime theme change. */
+  refreshTheme(theme?: CornerEditorTheme): void;
   confirm(): CornerPoints;
   cancel(): void;
   destroy(): void;
 }
 
+/**
+ * Options for the optional ML detector (`detector: 'ml'`). Assets are lazy-loaded
+ * from the companion `scanic-ml` package on a CDN by default; `onnxruntime-web`
+ * (v1.23.x, matching the bundled wasm) must be installed as a peer dependency.
+ */
+export interface MlDetectorOptions {
+  /** Base URL for the wasm + `.ort` model. Default: scanic-ml on jsDelivr. */
+  assetBaseUrl?: string;
+  /** Explicit model URL (overrides `assetBaseUrl` for the model). */
+  modelUrl?: string;
+  /** Explicit wasm directory (overrides `assetBaseUrl` for the runtime wasm). */
+  wasmPaths?: string;
+  /** Pre-fetched `.ort` model bytes (skips the network fetch). */
+  modelBytes?: Uint8Array;
+  /** ORT thread count. Default 1; values >1 require COOP/COEP headers on the host. */
+  numThreads?: number;
+  /** Minimum P(document) to report success. Default 0.5. */
+  minScore?: number;
+}
+
 export interface DetectionOptions {
   mode?: 'detect' | 'extract';
   output?: 'canvas' | 'imagedata' | 'dataurl';
+  /**
+   * Detection backend. `'classical'` (default) is the pure-JS/WASM Canny
+   * pipeline. `'ml'` uses the optional DocCornerNet SimCC model via
+   * onnxruntime-web — more robust on cluttered/low-contrast photos.
+   */
+  detector?: 'classical' | 'ml';
+  /** Options forwarded to the ML detector when `detector: 'ml'`. */
+  ml?: MlDetectorOptions;
   debug?: boolean;
   maxProcessingDimension?: number;
   lowThreshold?: number;
@@ -98,6 +187,8 @@ export interface ScannerResult {
   success: boolean;
   message: string;
   confidence?: number | null;
+  /** P(document present) from the ML detector (`detector: 'ml'`); null otherwise. */
+  score?: number | null;
   output: HTMLCanvasElement | ImageData | string | null;
   corners: CornerPoints | null;
   contour: Point[] | null;