smartcomply-web-sdk 1.0.80 → 1.0.82

package/dist/esm/utils/ImageQuality.js

@@ -163,6 +163,104 @@ export function assessQuality(imageData) {
         quality: metrics,
     };
 }
+/**
+ * Lightweight, dependency-free framing heuristic — NOT real document/edge
+ * detection (that needs actual computer vision, e.g. OpenCV.js). This is the
+ * same class of check as assessQuality above: cheap enough to run every
+ * ~300ms on a mid-range phone, good enough to catch the obvious failure
+ * (no document in frame, badly cropped, document far outside the guide box),
+ * not intended to catch subtle/partial cropping — that's still the backend
+ * OCR + registry check's job.
+ *
+ * Approach: a real physical document produces a sharp intensity edge at its
+ * own boundary. If the guide box is roughly aligned with a real document,
+ * that edge should sit close to the guide box's own border. Sample a thin
+ * ring around the guide box border and check edge strength there (Sobel-style
+ * gradient, cheaper than the full Laplacian pass in calculateSharpness), plus
+ * confirm the box interior isn't just blank/uniform background (a document
+ * held further back than the guide, or no document at all, leaves the
+ * interior looking like flat background/desk).
+ *
+ * guideBoxPct: the guide box's position as a fraction of imageData's full
+ * width/height (0-1) — callers pass the SAME percentages used to size the
+ * on-screen CSS guide box (see DocumentCapture's guideWrap), computed against
+ * the raw video frame's own pixel dimensions so no CSS/object-fit mapping is
+ * needed.
+ */
+export function assessFraming(imageData, guideBoxPct) {
+    const { width: W, height: H, data } = imageData;
+    const gray = new Uint8Array(W * H);
+    for (let i = 0; i < W * H; i++) {
+        const idx = i * 4;
+        gray[i] = Math.round(0.299 * data[idx] + 0.587 * data[idx + 1] + 0.114 * data[idx + 2]);
+    }
+    const gx0 = Math.round(guideBoxPct.x * W);
+    const gy0 = Math.round(guideBoxPct.y * H);
+    const gx1 = Math.round((guideBoxPct.x + guideBoxPct.width) * W);
+    const gy1 = Math.round((guideBoxPct.y + guideBoxPct.height) * H);
+    const edgeAt = (x, y) => {
+        if (x < 1 || y < 1 || x >= W - 1 || y >= H - 1)
+            return 0;
+        const gxVal = gray[y * W + x + 1] - gray[y * W + x - 1];
+        const gyVal = gray[(y + 1) * W + x] - gray[(y - 1) * W + x];
+        return Math.sqrt(gxVal * gxVal + gyVal * gyVal);
+    };
+    const EDGE_THRESHOLD = 40;
+    const BORDER_BAND = Math.max(4, Math.round(Math.min(W, H) * 0.015));
+    // Sample points along the guide box border ring (top/bottom edges, left/right edges).
+    let borderPoints = 0;
+    let borderHits = 0;
+    const SAMPLES_PER_SIDE = 24;
+    const sampleBand = (fixed, isX, start, end) => {
+        for (let s = 0; s < SAMPLES_PER_SIDE; s++) {
+            const t = start + ((end - start) * s) / (SAMPLES_PER_SIDE - 1);
+            let bestEdge = 0;
+            for (let b = -BORDER_BAND; b <= BORDER_BAND; b++) {
+                const x = isX ? fixed + b : Math.round(t);
+                const y = isX ? Math.round(t) : fixed + b;
+                bestEdge = Math.max(bestEdge, edgeAt(x, y));
+            }
+            borderPoints++;
+            if (bestEdge >= EDGE_THRESHOLD)
+                borderHits++;
+        }
+    };
+    sampleBand(gy0, false, gx0, gx1); // top
+    sampleBand(gy1, false, gx0, gx1); // bottom
+    sampleBand(gx0, true, gy0, gy1); // left
+    sampleBand(gx1, true, gy0, gy1); // right
+    const borderEdgeCoverage = borderPoints > 0 ? borderHits / borderPoints : 0;
+    // Interior variance — sample a coarse grid inside the box, well clear of
+    // the border band, and check the spread of gray values isn't flat.
+    let sum = 0, sumSq = 0, n = 0;
+    const GRID = 12;
+    const insetX = Math.round((gx1 - gx0) * 0.1);
+    const insetY = Math.round((gy1 - gy0) * 0.1);
+    for (let iy = 0; iy < GRID; iy++) {
+        for (let ix = 0; ix < GRID; ix++) {
+            const x = gx0 + insetX + Math.round(((gx1 - gx0 - 2 * insetX) * ix) / (GRID - 1));
+            const y = gy0 + insetY + Math.round(((gy1 - gy0 - 2 * insetY) * iy) / (GRID - 1));
+            if (x < 0 || y < 0 || x >= W || y >= H)
+                continue;
+            const v = gray[y * W + x];
+            sum += v;
+            sumSq += v * v;
+            n++;
+        }
+    }
+    const mean = n > 0 ? sum / n : 0;
+    const variance = n > 0 ? sumSq / n - mean * mean : 0;
+    // Normalize against a "reasonable document photo" ballpark std-dev (~35)
+    // so the 0-1 scale is comparable across lighting conditions.
+    const interiorVariance = Math.min(1, Math.sqrt(Math.max(0, variance)) / 35);
+    // Require a solid majority of the border ring to show an edge AND some
+    // real content inside — either alone can false-positive (a plain wall has
+    // no edges but so does a document photographed at very low contrast; a
+    // cluttered background has edges everywhere but nothing document-shaped
+    // where the guide box actually is).
+    const isFramed = borderEdgeCoverage >= 0.55 && interiorVariance >= 0.25;
+    return { isFramed, borderEdgeCoverage, interiorVariance };
+}
 /**
  * Get quality color for UI feedback
  */

package/dist/esm/utils/ImageQuality.js.map

@@ -1 +1 @@
-{"version":3,"file":"ImageQuality.js","sourceRoot":"","sources":["../../../src/utils/ImageQuality.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAkBH;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,SAAoB;IACrD,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC;IAE1C,uBAAuB;IACvB,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;IAC1F,CAAC;IAED,yBAAyB;IACzB,MAAM,SAAS,GAAG,IAAI,YAAY,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC;IACnD,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACnC,MAAM,GAAG,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC;YAE1B,mBAAmB;YACnB,MAAM,GAAG,GACP,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC;gBACtB,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;gBAClB,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC;gBACb,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC;gBAClB,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,GAAG,KAAK,CAAC,CAAC;YAEzB,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;YACrB,GAAG,IAAI,GAAG,CAAC;YACX,KAAK,IAAI,GAAG,GAAG,GAAG,CAAC;YACnB,KAAK,EAAE,CAAC;QACV,CAAC;IACH,CAAC;IAED,qBAAqB;IACrB,MAAM,IAAI,GAAG,GAAG,GAAG,KAAK,CAAC;IACzB,MAAM,QAAQ,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAEjD,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,SAAoB,EAAE,YAAoB,GAAG;IACvE,MAAM,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC;IAC3B,IAAI,WAAW,GAAG,CAAC,CAAC;IAEpB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,UAAU,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC7D,IAAI,UAAU,GAAG,SAAS,EAAE,CAAC;YAC3B,WAAW,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IAED,OAAO,WAAW,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAoB;IACpD,MAAM,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC;IAC3B,IAAI,GAAG,GAAG,CAAC,CAAC;IACZ,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;IAEnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QACzE,GAAG,IAAI,IAAI,CAAC;QACZ,KAAK,IAAI,IAAI,GAAG,IAAI,CAAC;IACvB,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,GAAG,UAAU,CAAC;IAC9B,MAAM,QAAQ,GAAG,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IAEtD,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAoB;IACtD,MAAM,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC;IAC3B,IAAI,GAAG,GAAG,CAAC,CAAC;IAEZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,SAAoB;IAChD,MAAM,SAAS,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAG,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAElD,MAAM,QAAQ,GAAG,SAAS,GAAG,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAG,KAAK,GAAG,IAAI,CAAC;IAC9B,MAAM,SAAS,GAAG,UAAU,GAAG,EAAE,CAAC;IAClC,MAAM,WAAW,GAAG,UAAU,GAAG,GAAG,CAAC;IACrC,MAAM,WAAW,GAAG,QAAQ,GAAG,EAAE,CAAC;IAElC,kCAAkC;IAClC,IAAI,KAAK,GAAG,GAAG,CAAC;IAChB,IAAI,QAAQ;QAAE,KAAK,IAAI,EAAE,CAAC;IAC1B,IAAI,QAAQ;QAAE,KAAK,IAAI,EAAE,CAAC;IAC1B,IAAI,SAAS;QAAE,KAAK,IAAI,EAAE,CAAC;IAC3B,IAAI,WAAW;QAAE,KAAK,IAAI,EAAE,CAAC;IAC7B,IAAI,WAAW;QAAE,KAAK,IAAI,EAAE,CAAC;IAE7B,MAAM,OAAO,GAAmB;QAC9B,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,EAAE,CAAC,GAAG,EAAE;QAC1C,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,EAAE,CAAC,GAAG,EAAE;QACxC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,UAAU,GAAG,EAAE,CAAC,GAAG,EAAE;QAC5C,QAAQ;QACR,QAAQ;QACR,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC;KACjC,CAAC;IAEF,oBAAoB;IACpB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,eAAe,GAAa,EAAE,CAAC;IAErC,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC1B,eAAe,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QAC3C,eAAe,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IAC/C,CAAC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC9B,eAAe,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;QACvD,eAAe,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;IACjD,CAAC;IAED,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACxB,eAAe,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QAC9C,eAAe,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;IAC9C,CAAC;IAED,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC1B,eAAe,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QACxC,eAAe,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACpD,CAAC;IAED,IAAI,WAAW,EAAE,CAAC;QAChB,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC5B,eAAe,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,IAAI,EAAE,CAAC;IAC5B,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC;QAC/B,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;QACnB,CAAC,CAAC,cAAc,CAAC;IAEnB,OAAO;QACL,OAAO;QACP,OAAO;QACP,eAAe,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,wBAAwB;QACtE,OAAO,EAAE,OAAO;KACjB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAI,KAAK,IAAI,EAAE;QAAE,OAAO,SAAS,CAAC,CAAC,QAAQ;IAC3C,IAAI,KAAK,IAAI,EAAE;QAAE,OAAO,SAAS,CAAC,CAAC,SAAS;IAC5C,OAAO,SAAS,CAAC,CAAC,MAAM;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,KAAK,IAAI,EAAE;QAAE,OAAO,8BAA8B,CAAC;IACvD,IAAI,KAAK,IAAI,EAAE;QAAE,OAAO,oBAAoB,CAAC;IAC7C,IAAI,KAAK,IAAI,EAAE;QAAE,OAAO,4BAA4B,CAAC;IACrD,OAAO,sBAAsB,CAAC;AAChC,CAAC"}
+{"version":3,"file":"ImageQuality.js","sourceRoot":"","sources":["../../../src/utils/ImageQuality.ts"],"names":[],"mappings":"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"}

package/dist/flow/DocumentCapture.d.ts

@@ -27,6 +27,9 @@ export declare class DocumentCapture {
     private backBlob;
     private currentSide;
     private requiresBackOverride;
+    private framingTimer;
+    private framingStableCount;
+    private framingAutoTriggered;
     /**
      * Mount the document capture UI and return a promise that resolves
      * with the captured document image(s).
@@ -58,15 +61,49 @@ export declare class DocumentCapture {
      */
     private _watchOrientation;
     private _unwatchOrientation;
+    /**
+     * Auto-capture-on-stability — the same pattern the liveness module already
+     * uses for face-lock (see liveness.ts's checkFace), applied to documents:
+     * poll the raw video frame on an interval, score it against the guide box
+     * with assessFraming() (see utils/ImageQuality.ts), and fire the shutter
+     * automatically once several consecutive samples score as "framed". This
+     * is industry-standard for document capture (Persona/Onfido/Jumio-style
+     * SDKs all auto-capture rather than trust a manual tap against a static
+     * guide overlay) — the guide box alone never blocked a badly cropped tap.
+     *
+     * The manual capture button still works throughout and always wins
+     * (framingAutoTriggered guards against a race between the two).
+     */
+    private _startFramingLoop;
+    private _stopFramingLoop;
     private openCamera;
     private captureFrame;
     private showPreview;
     /**
-     * Runs the shared client-side quality heuristic (blur/glare/contrast/
-     * brightness — see utils/ImageQuality.ts) against the just-captured photo
-     * and, if it scores poorly, shows a plain-language nudge on the preview
-     * screen. Fails silently on decode error — this is an advisory extra, not
-     * a required step, so a browser that can't run it must not block capture.
+     * Runs the shared client-side quality heuristics — blur/glare/contrast/
+     * brightness (assessQuality) and document framing/completeness
+     * (assessFraming) — against the just-captured or just-uploaded photo, and
+     * shows a plain-language nudge on the preview screen if either scores
+     * poorly. This is the one chokepoint both the camera and manual-upload
+     * paths funnel through (see showPreview), so it's the only place that
+     * reliably catches a badly cropped document regardless of how the photo
+     * arrived — the camera's own auto-capture framing loop only guards live
+     * capture, and does nothing for an uploaded file or a manual shutter tap
+     * fired before the loop ever samples.
+     *
+     * Framing here checks the WHOLE image (guideBoxPct = full frame), not a
+     * guide-box region — there's no guide overlay for an arbitrary uploaded
+     * photo, so "does the document fill most of the frame" is the correct
+     * question, matching the same border-edge + interior-variance heuristic
+     * the camera loop already uses.
+     *
+     * A framing failure disables useBtn — unlike the blur/glare nudge, this
+     * one blocks: a cropped ID reads as a confident, wrong identity downstream
+     * (partial OCR fields, a registry check against a truncated ID number)
+     * with no further chance to catch it, so the user must retake/re-upload
+     * rather than being trusted to notice an advisory nudge and act on it
+     * voluntarily. Fails open on decode error — this heuristic not running at
+     * all must not lock the user out of a photo it never actually scored.
      */
     private _checkPhotoQuality;
     /** Decodes to a canvas, optionally downscaled to maxDim on the long edge (never upscales). */

package/dist/flow/DocumentCapture.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocumentCapture.d.ts","sourceRoot":"","sources":["../../src/flow/DocumentCapture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAgB,MAAM,SAAS,CAAC;AACpD,OAAO,EAAuC,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAQ3F;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,IAAI,CAAC;IACZ,IAAI,CAAC,EAAE,IAAI,CAAC;IAKZ,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAA+B;IAC3C,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,cAAc,CAA0D;IAChF,OAAO,CAAC,aAAa,CAAuC;IAC5D,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,oBAAoB,CAAuC;IAEnE;;;OAGG;IACH,OAAO,CACL,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,MAAM,EACpB,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,qBAAqB,CAAC;IAiCjC,OAAO,IAAI,IAAI;IAuBf,OAAO,CAAC,eAAe;IAOvB,8EAA8E;IAC9E,OAAO,CAAC,qBAAqB;IAI7B,0EAA0E;IAC1E,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,kBAAkB;IA4L1B,wDAAwD;IACxD,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,gBAAgB;IAyHxB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,mBAAmB;YAQb,UAAU;IAsExB,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,WAAW;IA4JnB;;;;;;OAMG;YACW,kBAAkB;IA4BhC,8FAA8F;IAC9F,OAAO,CAAC,aAAa;IAqBrB;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IA2BpB,OAAO,CAAC,qBAAqB;IAyC7B,OAAO,CAAC,wBAAwB;IAShC,OAAO,CAAC,YAAY;IAsBpB;;;;;;;;OAQG;YACW,sBAAsB;IASpC,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,SAAS;IAoCjB,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,aAAa;IA4ErB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAuC5B,OAAO,CAAC,gBAAgB;CAazB"}
+{"version":3,"file":"DocumentCapture.d.ts","sourceRoot":"","sources":["../../src/flow/DocumentCapture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAgB,MAAM,SAAS,CAAC;AACpD,OAAO,EAAuC,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAQ3F;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,IAAI,CAAC;IACZ,IAAI,CAAC,EAAE,IAAI,CAAC;IAKZ,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,IAAI,CAA+B;IAC3C,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,cAAc,CAA0D;IAChF,OAAO,CAAC,aAAa,CAAuC;IAC5D,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAqB;IACtC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,oBAAoB,CAAuC;IACnE,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,oBAAoB,CAAS;IAErC;;;OAGG;IACH,OAAO,CACL,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,WAAW,EAClB,YAAY,EAAE,MAAM,EACpB,YAAY,CAAC,EAAE,YAAY,GAC1B,OAAO,CAAC,qBAAqB,CAAC;IAiCjC,OAAO,IAAI,IAAI;IAuBf,OAAO,CAAC,eAAe;IAOvB,8EAA8E;IAC9E,OAAO,CAAC,qBAAqB;IAI7B,0EAA0E;IAC1E,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,kBAAkB;IA4L1B,wDAAwD;IACxD,OAAO,CAAC,QAAQ;IAQhB,OAAO,CAAC,gBAAgB;IA0IxB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,mBAAmB;IAQ3B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,iBAAiB;IA2FzB,OAAO,CAAC,gBAAgB;YAOV,UAAU;IAsExB,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,WAAW;IA+JnB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;YACW,kBAAkB;IAsDhC,8FAA8F;IAC9F,OAAO,CAAC,aAAa;IAqBrB;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IA2BpB,OAAO,CAAC,qBAAqB;IAyC7B,OAAO,CAAC,wBAAwB;IAShC,OAAO,CAAC,YAAY;IAsBpB;;;;;;;;OAQG;YACW,sBAAsB;IASpC,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,SAAS;IAoCjB,OAAO,CAAC,YAAY;IA4BpB,OAAO,CAAC,aAAa;IA4ErB;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAuC5B,OAAO,CAAC,gBAAgB;CAazB"}

package/dist/flow/DocumentCapture.js

@@ -23,6 +23,9 @@ class DocumentCapture {
         this.backBlob = null;
         this.currentSide = 'front';
         this.requiresBackOverride = undefined;
+        this.framingTimer = null;
+        this.framingStableCount = 0;
+        this.framingAutoTriggered = false;
     }
     /**
      * Mount the document capture UI and return a promise that resolves
@@ -332,7 +335,7 @@ class DocumentCapture {
         svg.appendChild(bracketGroup);
         guideWrap.appendChild(svg);
         wrapper.appendChild(guideWrap);
-        // Header — gradient scrim + document label
+        // Header — gradient scrim + document label + live framing status
         const header = document.createElement("div");
         header.style.cssText = `
       position:absolute;top:0;left:0;right:0;
@@ -340,6 +343,13 @@ class DocumentCapture {
       padding:14px 16px 32px;text-align:center;
     `;
         header.innerHTML = `<div style="color:#fff;font-size:${theme_1.TYPE.sm}px;font-weight:600;">Align your ${this.getDocumentLabel(documentType)} within the frame</div>`;
+        const framingStatus = document.createElement("div");
+        framingStatus.style.cssText = `
+      margin-top:6px;font-size:${theme_1.TYPE.xs}px;font-weight:600;
+      color:rgba(255,255,255,0.7);transition:color 0.2s ease;
+    `;
+        framingStatus.textContent = "Fit the document inside the frame";
+        header.appendChild(framingStatus);
         wrapper.appendChild(header);
         // Footer — gradient scrim + tips
         const footer = document.createElement("div");
@@ -374,11 +384,17 @@ class DocumentCapture {
             inner.style.transform = "translate(-50%,-50%) scale(1)";
         });
         captureBtn.addEventListener("click", () => {
+            this.framingAutoTriggered = true; // manual tap always wins, skip any pending auto-trigger
             this.captureFrame(container, theme, documentType);
         });
         container.appendChild(captureBtn);
-        // Open camera
-        this.openCamera();
+        // Open camera, then start the auto-capture framing loop once the stream
+        // has real dimensions to sample against.
+        this.openCamera().then(() => {
+            if (this.videoEl) {
+                this.videoEl.addEventListener("loadedmetadata", () => this._startFramingLoop(container, theme, documentType, framingStatus), { once: true });
+            }
+        });
     }
     /**
      * Matches the video box's aspect-ratio CSS to the stream's actual
@@ -415,6 +431,103 @@ class DocumentCapture {
             this.orientationHandler = null;
         }
     }
+    /**
+     * Auto-capture-on-stability — the same pattern the liveness module already
+     * uses for face-lock (see liveness.ts's checkFace), applied to documents:
+     * poll the raw video frame on an interval, score it against the guide box
+     * with assessFraming() (see utils/ImageQuality.ts), and fire the shutter
+     * automatically once several consecutive samples score as "framed". This
+     * is industry-standard for document capture (Persona/Onfido/Jumio-style
+     * SDKs all auto-capture rather than trust a manual tap against a static
+     * guide overlay) — the guide box alone never blocked a badly cropped tap.
+     *
+     * The manual capture button still works throughout and always wins
+     * (framingAutoTriggered guards against a race between the two).
+     */
+    _startFramingLoop(container, theme, documentType, statusEl) {
+        if (!this.videoEl)
+            return;
+        this.framingStableCount = 0;
+        this.framingAutoTriggered = false;
+        const STABLE_REQUIRED = 3; // consecutive good samples before firing
+        const SAMPLE_INTERVAL_MS = 350; // cheap enough to run this often; not every animation frame
+        const MAX_WAIT_MS = 12000; // give up auto-capture, leave the manual button as the only path
+        const startTime = performance.now();
+        // Guide box in fractional coordinates, matching the on-screen CSS guide
+        // (width:84%, aspect-ratio:16/10, centered) — computed directly against
+        // the video's own pixel dimensions so no CSS/object-fit mapping is needed.
+        const boxWidthPct = 0.84;
+        const boxAspect = 16 / 10;
+        const tick = () => {
+            if (!this.videoEl || this.framingAutoTriggered)
+                return;
+            if (performance.now() - startTime >= MAX_WAIT_MS) {
+                statusEl.textContent = "Fit the document inside the frame";
+                return; // stop auto-detecting; manual capture button remains available
+            }
+            const w = this.videoEl.videoWidth;
+            const h = this.videoEl.videoHeight;
+            if (!w || !h || this.videoEl.readyState < 2) {
+                this.framingTimer = setTimeout(tick, SAMPLE_INTERVAL_MS);
+                return;
+            }
+            try {
+                const boxWidthPx = w * boxWidthPct;
+                const boxHeightPx = boxWidthPx / boxAspect;
+                const boxXPct = (1 - boxWidthPct) / 2;
+                const boxHeightPct = boxHeightPx / h;
+                const boxYPct = (1 - boxHeightPct) / 2;
+                const canvas = document.createElement("canvas");
+                // Downscaled sampling copy only — matches _checkPhotoQuality's own
+                // reasoning for why this must not run against the full-resolution
+                // frame on every tick.
+                const scale = Math.min(1, 480 / w);
+                canvas.width = Math.round(w * scale);
+                canvas.height = Math.round(h * scale);
+                const ctx = canvas.getContext("2d", { willReadFrequently: true });
+                if (!ctx) {
+                    this.framingTimer = setTimeout(tick, SAMPLE_INTERVAL_MS);
+                    return;
+                }
+                ctx.drawImage(this.videoEl, 0, 0, canvas.width, canvas.height);
+                const pixels = ctx.getImageData(0, 0, canvas.width, canvas.height);
+                const result = (0, ImageQuality_1.assessFraming)(pixels, {
+                    x: boxXPct, y: boxYPct, width: boxWidthPct, height: boxHeightPct,
+                });
+                if (result.isFramed) {
+                    this.framingStableCount++;
+                    statusEl.style.color = theme.primary;
+                    statusEl.textContent = this.framingStableCount >= STABLE_REQUIRED
+                        ? "Capturing…"
+                        : "Hold steady…";
+                }
+                else {
+                    this.framingStableCount = 0;
+                    statusEl.style.color = "rgba(255,255,255,0.7)";
+                    statusEl.textContent = result.interiorVariance < 0.25
+                        ? "Move closer — fill the frame with your document"
+                        : "Align all 4 corners within the guide";
+                }
+                if (this.framingStableCount >= STABLE_REQUIRED) {
+                    this.framingAutoTriggered = true;
+                    this.captureFrame(container, theme, documentType);
+                    return;
+                }
+            }
+            catch {
+                // Advisory/auto-capture only — a scoring failure just falls back to
+                // the manual capture button, never blocks the flow.
+            }
+            this.framingTimer = setTimeout(tick, SAMPLE_INTERVAL_MS);
+        };
+        this.framingTimer = setTimeout(tick, SAMPLE_INTERVAL_MS);
+    }
+    _stopFramingLoop() {
+        if (this.framingTimer !== null) {
+            clearTimeout(this.framingTimer);
+            this.framingTimer = null;
+        }
+    }
     async openCamera() {
         // Check browser compatibility
         if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
@@ -576,7 +689,7 @@ class DocumentCapture {
                 URL.revokeObjectURL(currentUrl);
                 currentUrl = URL.createObjectURL(rotated);
                 img.src = currentUrl;
-                this._checkPhotoQuality(currentBlob, qualityNotice, theme);
+                this._checkPhotoQuality(currentBlob, qualityNotice, theme, useBtn);
             }
             catch {
                 // Leave the current photo untouched — rotation is a convenience,
@@ -598,12 +711,14 @@ class DocumentCapture {
         sublabel.style.cssText = `color:${theme.textMuted};font-size:${theme_1.TYPE.xs}px;text-align:center;line-height:1.6;`;
         sublabel.textContent = "All text must be readable and all four corners must be visible. Sideways or upside-down? Use Rotate on the photo above.";
         this.root.appendChild(sublabel);
-        // Advisory-only quality nudge — catches an obviously blurry/dark/glare-
-        // heavy photo right here instead of only finding out several seconds
-        // later. Never blocks "Use Photo": this is a heuristic, not a hard
-        // rule, so a photo that's actually fine but scores oddly must still be
-        // usable — it just nudges the user toward retaking with a plain-
-        // language reason instead of silently letting a bad photo through.
+        // Quality/framing notice. Blur/glare/contrast issues (assessQuality) stay
+        // advisory-only — a heuristic that's off shouldn't block a photo that's
+        // actually fine. A framing failure (document not fully in frame —
+        // assessFraming) DOES block "Use Photo": a cropped ID reads as a
+        // confident, wrong identity downstream (partial OCR fields, a registry
+        // check against a truncated ID number) with no further chance to catch
+        // it, so this is the one signal worth hard-blocking on rather than
+        // trusting the user to notice and retake voluntarily.
         const qualityNotice = document.createElement("div");
         qualityNotice.style.cssText = `
       display:none;width:100%;padding:10px 14px;border-radius:${theme_1.RADIUS.md}px;
@@ -612,7 +727,6 @@ class DocumentCapture {
     `;
         qualityNotice.setAttribute("role", "status");
         this.root.appendChild(qualityNotice);
-        this._checkPhotoQuality(currentBlob, qualityNotice, theme);
         // Buttons
         const btnRow = document.createElement("div");
         btnRow.style.cssText = "display:flex;gap:12px;width:100%;";
@@ -638,15 +752,35 @@ class DocumentCapture {
         btnRow.appendChild(retakeBtn);
         btnRow.appendChild(useBtn);
         this.root.appendChild(btnRow);
+        this._checkPhotoQuality(currentBlob, qualityNotice, theme, useBtn);
     }
     /**
-     * Runs the shared client-side quality heuristic (blur/glare/contrast/
-     * brightness — see utils/ImageQuality.ts) against the just-captured photo
-     * and, if it scores poorly, shows a plain-language nudge on the preview
-     * screen. Fails silently on decode error — this is an advisory extra, not
-     * a required step, so a browser that can't run it must not block capture.
+     * Runs the shared client-side quality heuristics — blur/glare/contrast/
+     * brightness (assessQuality) and document framing/completeness
+     * (assessFraming) — against the just-captured or just-uploaded photo, and
+     * shows a plain-language nudge on the preview screen if either scores
+     * poorly. This is the one chokepoint both the camera and manual-upload
+     * paths funnel through (see showPreview), so it's the only place that
+     * reliably catches a badly cropped document regardless of how the photo
+     * arrived — the camera's own auto-capture framing loop only guards live
+     * capture, and does nothing for an uploaded file or a manual shutter tap
+     * fired before the loop ever samples.
+     *
+     * Framing here checks the WHOLE image (guideBoxPct = full frame), not a
+     * guide-box region — there's no guide overlay for an arbitrary uploaded
+     * photo, so "does the document fill most of the frame" is the correct
+     * question, matching the same border-edge + interior-variance heuristic
+     * the camera loop already uses.
+     *
+     * A framing failure disables useBtn — unlike the blur/glare nudge, this
+     * one blocks: a cropped ID reads as a confident, wrong identity downstream
+     * (partial OCR fields, a registry check against a truncated ID number)
+     * with no further chance to catch it, so the user must retake/re-upload
+     * rather than being trusted to notice an advisory nudge and act on it
+     * voluntarily. Fails open on decode error — this heuristic not running at
+     * all must not lock the user out of a photo it never actually scored.
      */
-    async _checkPhotoQuality(imageData, noticeEl, theme) {
+    async _checkPhotoQuality(imageData, noticeEl, theme, useBtn) {
         try {
             // Document photos are captured at up to DOC_CAMERA_IDEAL_WIDTH/HEIGHT
             // (2000x1500) — scoring every pixel across four full-image passes in
@@ -659,6 +793,28 @@ class DocumentCapture {
             if (!ctx)
                 return;
             const pixels = ctx.getImageData(0, 0, canvas.width, canvas.height);
+            const framing = (0, ImageQuality_1.assessFraming)(pixels, { x: 0, y: 0, width: 1, height: 1 });
+            if (!framing.isFramed) {
+                if (noticeEl.isConnected) {
+                    noticeEl.style.display = "block";
+                    noticeEl.textContent = framing.interiorVariance < 0.25
+                        ? "We couldn't detect a document in this photo — make sure the ID is clearly visible and try again."
+                        : "Part of the document looks cut off — make sure all four corners are visible and try again.";
+                }
+                if (useBtn.isConnected) {
+                    useBtn.disabled = true;
+                    useBtn.style.opacity = "0.5";
+                    useBtn.style.cursor = "not-allowed";
+                }
+                return; // framing issue is the more actionable/specific one — don't also show the quality nudge
+            }
+            // Framing passed — make sure a previous failed attempt (before Retake/
+            // Rotate) doesn't leave the button stuck disabled.
+            if (useBtn.isConnected) {
+                useBtn.disabled = false;
+                useBtn.style.opacity = "1";
+                useBtn.style.cursor = "pointer";
+            }
             const result = (0, ImageQuality_1.assessQuality)(pixels);
             if (noticeEl.isConnected && !result.isValid) {
                 noticeEl.style.display = "block";
@@ -668,7 +824,7 @@ class DocumentCapture {
             }
         }
         catch {
-            // Advisory only — no notice shown if scoring fails for any reason.
+            // Fails open — no notice, button stays enabled, if scoring fails for any reason.
         }
     }
     /** Decodes to a canvas, optionally downscaled to maxDim on the long edge (never upscales). */
@@ -805,6 +961,7 @@ class DocumentCapture {
             input.click();
     }
     stopCamera() {
+        this._stopFramingLoop();
         this._unwatchOrientation();
         this.cameraManager.stop();
         if (this.videoEl) {