@sekyro/web 0.0.0-stage → 0.1.0-rc.2

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @sekyro/web
+
+## 0.1.0-rc.2
+
+### Patch Changes
+
+- ca2cd0e: Verification flow: a capture's submission chain now survives a `<LivenessCapture>` remount, and the flow resumes from the server's frontier after a `409`.
+  
+  - Submission chains are **serialized per verification**: creating a new capture handle via `verification.liveness()` (a React remount, a partner re-rendering the stage) no longer cancels the previous capture's in-flight liveness → face_match chain. The new capture's artifacts queue behind it and are then evaluated against the current hosted view. Only `verification.destroy()` cancels. Post-capture states (`uploading` / `checking` / `done`) and the auto re-arm reach a handle only while it is alive and still on the attempt that produced the artifacts.
+  - The flow is **frontier-driven**: when `liveness` is the frontier it uploads the clip and submits liveness, then face_match from the same keyframe; when liveness already settled and `face_match` is the frontier it submits the keyframe only; a frontier the SDK cannot drive finishes with the mapped result. After a RESYNC code (`check_already_finalized`, `check_out_of_order`, `session_not_active`, `check_not_found`) the view is re-fetched and the frontier logic re-entered (bounded, `RESYNC_REENTRY_MAX`) instead of finishing on a stale view — a liveness that passed under an earlier run still gets its face_match.
+  - Idempotency / same-key replay semantics are unchanged; `result` is still emitted once per terminal verdict (and once per non-terminal finish of a run).
+
+## 0.1.0-rc.1
+
+### Minor Changes
+
+- 466d3e1: Initial release line of the Sekyro SDKs: `@sekyro/web` (browser liveness capture, hosted-verification client and popup embed), `@sekyro/react` (the themeable, accessible `<LivenessCapture />` component over `@sekyro/web`, ar/fr/en, RTL-safe) and `@sekyro/node` (server-side sessions client and signed-webhook verification, zero runtime dependencies). Pre-releases ship as `0.1.0-rc.N` under the `next` dist-tag from `develop`; the first stable `0.1.0` ships from `main`. All three packages are proprietary (`UNLICENSED` — see each package's LICENSE).

package/LICENSE

@@ -0,0 +1,20 @@
+Sekyro SDK — Proprietary License
+
+Copyright (c) 2026 Ibtikar Technologies. All rights reserved.
+
+This software (the "SDK") is proprietary to Ibtikar Technologies. Use is
+permitted only under a Sekyro customer agreement with Ibtikar Technologies, and
+only to integrate the customer's own applications with the Sekyro
+identity-verification service. For that purpose you may install the SDK
+from the public npm registry and run it unmodified.
+
+No other right or license, express or implied, is granted. You may not
+modify, reverse-engineer, redistribute, sublicense, resell or create
+derivative works of the SDK, nor remove or alter this notice. The source
+code is published for transparency (build provenance, security review); its
+publication grants no additional rights.
+
+THE SDK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. TO THE EXTENT PERMITTED BY LAW, IBTIKAR TECHNOLOGIES SHALL NOT BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM THE USE OF THE
+SDK, EXCEPT AS PROVIDED IN THE APPLICABLE CUSTOMER AGREEMENT.

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# @sekyro/web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browser SDK for [Sekyro](https://sekyro.ai) identity verification: liveness capture
+(v3 engine), the typed hosted-verification client, and the partner popup embed.
+Framework-free; pair it with `@sekyro/react` for a ready-made `<LivenessCapture>`.
+
+```ts
+import { createVerification } from "@sekyro/web";
+
+const v = createVerification({ clientToken, locale: "ar" }); // token from your server (@sekyro/node)
+v.on("result", ({ status, reason }) => {
+  // approved | rejected | review | retry | unavailable — for display;
+  // the verdict that counts is read server-side (sessions.get + webhooks).
+});
+const cap = v.liveness({ video }); // your <video playsinline muted>
+cap.on("gate", ({ progress, hint }) => {/* ring 0..1, hint code */});
+await v.consent();
+void v.startRegistry();
+await cap.start();
+```
+
+**Read the [Web SDK guide](../../docs/partner/web-sdk.md)** for the full integration:
+server-bound NNI, results, webhooks, registered origins, CSP, model assets
+(`assetBaseUrl`), reason codes, billing. Hosted-flow embed only? The
+[quickstart](../../docs/partner/quickstart.md) covers `openHosted`.
+
+Requirements: a secure context (HTTPS or `localhost`), self-hosted detector assets
+under `/models-v3` (or `assetBaseUrl`), and your page origin registered with Sekyro.
+
+> Status: `0.1.0-rc.0`, still `private` — the public npm release is wired in a later
+> task (Changesets + Trusted Publishing). Sekyro's own hosted page consumes it via a
+> `file:` link today. Formerly `@ibtikar/identity-web-sdk` (internal).
+
+## Entry points
+
+| Export | Contents | Public API |
+|---|---|---|
+| `@sekyro/web` | **The partner API** (spec §3.1): `createVerification` (consent → early registry → liveness capture → upload → Turnstile attestation → `liveness` + `face_match` → `result`), `createLivenessCapture` (standalone capture handle), `openHosted` (popup/redirect embed) + the contract types. Surface pinned by `etc/sekyro-web.api.md` (api-extractor) | Yes |
+| `@sekyro/web/core` | Framework-free capture: `CaptureSessionV3`, `createDetector`, `FaceGateV3`, frame quality, device profile, `media`/`keyframe`/`messages`/`ClipRecorder` (calibration-pinned v1 port), camera constraints | Yes |
+| `@sekyro/web/core/v3/detect-worker` | Standalone detection-worker entry — construct with `new Worker(new URL('@sekyro/web/core/v3/detect-worker', import.meta.url))` so its worker-scope auto-install never rides a main-thread bundle | Yes |
+| `@sekyro/web/client` | Typed client for the hosted session API: `HostedClient`, error codes, check input/view types | Yes |
+| `@sekyro/web/popup` | Partner-facing popup/redirect embed (`open`, `SekyroEvent`) | Yes |
+| `@sekyro/web/internal` | **Not public.** Document scanner (doc catalog, `DocGateV1`, MRZ band, frame analysis, feedback aggregator, `CaptureSessionDoc`) + gate-debug geometry constants + the verification internals (`createVerificationInternal` / `createLivenessCaptureInternal` seams, `runLivenessFlow`, `runSubmission`, result mapping, Turnstile loader), consumed by Sekyro's hosted page / `@sekyro/react` only. No semver guarantees; may change in any release | No |
+
+Every entry ships ESM + CJS + `.d.ts` (`tsup`). `./core` deliberately does **not**
+re-export the document scanner (that lives only under `./internal`) nor the worker
+entry.
+
+## Calibration pin — do not "improve" `src/core/`
+
+`src/core/media.ts`, `keyframe.ts`, and `messages.ts` are **byte-identical ports** of
+v1's `kyc-ibtikar/lib/faceCaptureV2/*`. The only allowed delta is the 3-line port
+header block (two comment lines + one blank separator line) prepended to each file.
+`src/core/clip-recorder.ts` is the de-hooked `useClipRecorder` with identical
+constants and behavior (`CLIP_MS=2500`, `TIMESLICE_MS=1000`, `STOP_GRACE_MS=1500`,
+`VIDEO_BPS=2_500_000`, `MAX_CLIP_BYTES=8MiB`, mime ladder, guarded double construction,
+incremental cap enforcement, stop-grace finalize, single-settle, stop-all-tracks).
+
+The FAS-CLIP liveness model was calibrated on clips produced by exactly this v1
+pipeline (spec §6 / risk 1). Any drift silently invalidates the calibration.
+`test/port-parity.test.ts` enforces this in two layers: a sha256 checksum pin against
+the committed `test/port-manifest.json` that runs **everywhere, CI included**, and a
+byte-level comparison against the real v1 sources that runs on every dev machine with
+the `kyc-ibtikar/` checkout alongside (that layer self-skips in CI, where the
+gitignored v1 checkout is absent — and it also verifies the manifest itself matches
+header + v1 bytes, so the manifest cannot drift). Do NOT edit `src/core/` without a
+calibration re-validation; if a re-validated change ever lands, regenerate the
+manifest hashes alongside it.
+
+The parity test resolves the v1 checkout as `../../kyc-ibtikar/lib/faceCaptureV2`
+from the package root, so this package must stay **two levels below the repo root**
+(`packages/sekyro-web`).
+
+Note: v1's `upload.ts` is intentionally NOT ported — uploading is the typed client's
+job in v2 (`HostedClient.uploadAndSubmit`).
+
+## Develop
+
+```bash
+npm ci
+npm run build      # tsup → dist/ (ESM + CJS + d.ts per entry)
+npm test           # vitest (jsdom)
+npm run typecheck  # tsc --noEmit
+npm run api:check  # api-extractor: fails when the ROOT public surface drifts from etc/sekyro-web.api.md
+npm run api:report # regenerate etc/sekyro-web.api.md after an intentional, reviewed API change
+```
+
+The api-extractor report covers the root `.` entry only (the partner contract); the
+subpath entries (`./core`, `./client`, `./popup`) are not reported. `npm run build` must
+precede `api:check` (it reads `dist/index.d.ts`).
+
+Standalone package: own lockfile, no workspace wiring. `identity-hosted` consumes it
+via `"@sekyro/web": "file:../packages/sekyro-web"` and needs `dist/` built first.

package/dist/capture-constraints-BujkZcfb.d.cts

@@ -0,0 +1,21 @@
+/** getUserMedia constraint tier — 720p-class on every device since 2026-07-06.
+ *  The v2 FAS-CLIP liveness head loses its texture cues below ~720p: the SAME
+ *  genuine clip scores heads 0.0001 at 720x1280 vs 0.355 at the old 480x360
+ *  mobile tier, which pushed real users into review (first observed live on
+ *  staging 2026-07-06; falsified on corpus clips the same day). Dimensions are
+ *  sensor-relative (landscape); mobile browsers deliver portrait via rotation
+ *  metadata, which the liveness service's decoder applies (cv2
+ *  ORIENTATION_AUTO). `isMobile` is kept for call-site compat and future
+ *  divergence — both tiers are 720p today. Bitrate pairs with VIDEO_BPS in
+ *  clip-recorder.ts (2.5 Mbps). */
+declare function buildCaptureConstraints(isMobile: boolean, facingMode: "user" | "environment"): MediaStreamConstraints;
+/** v1 mobile heuristic (FaceCaptureV2.tsx L216-224). */
+declare function detectIsMobile(): boolean;
+/** Gate radius as a fraction of the guidance circle (v1 L501: circleSize × 0.45). */
+declare const CIRCLE_RADIUS_FACTOR = 0.45;
+/** `inCircle` tolerance as a fraction of the gate radius (v1 L508: r × 0.9). */
+declare const IN_CIRCLE_FACTOR = 0.9;
+/** `centered` tolerance as a fraction of the gate radius (v1 L509: r × 0.4). */
+declare const CENTERED_FACTOR = 0.4;
+
+export { CENTERED_FACTOR as C, IN_CIRCLE_FACTOR as I, CIRCLE_RADIUS_FACTOR as a, buildCaptureConstraints as b, detectIsMobile as d };

package/dist/capture-constraints-BujkZcfb.d.ts

@@ -0,0 +1,21 @@
+/** getUserMedia constraint tier — 720p-class on every device since 2026-07-06.
+ *  The v2 FAS-CLIP liveness head loses its texture cues below ~720p: the SAME
+ *  genuine clip scores heads 0.0001 at 720x1280 vs 0.355 at the old 480x360
+ *  mobile tier, which pushed real users into review (first observed live on
+ *  staging 2026-07-06; falsified on corpus clips the same day). Dimensions are
+ *  sensor-relative (landscape); mobile browsers deliver portrait via rotation
+ *  metadata, which the liveness service's decoder applies (cv2
+ *  ORIENTATION_AUTO). `isMobile` is kept for call-site compat and future
+ *  divergence — both tiers are 720p today. Bitrate pairs with VIDEO_BPS in
+ *  clip-recorder.ts (2.5 Mbps). */
+declare function buildCaptureConstraints(isMobile: boolean, facingMode: "user" | "environment"): MediaStreamConstraints;
+/** v1 mobile heuristic (FaceCaptureV2.tsx L216-224). */
+declare function detectIsMobile(): boolean;
+/** Gate radius as a fraction of the guidance circle (v1 L501: circleSize × 0.45). */
+declare const CIRCLE_RADIUS_FACTOR = 0.45;
+/** `inCircle` tolerance as a fraction of the gate radius (v1 L508: r × 0.9). */
+declare const IN_CIRCLE_FACTOR = 0.9;
+/** `centered` tolerance as a fraction of the gate radius (v1 L509: r × 0.4). */
+declare const CENTERED_FACTOR = 0.4;
+
+export { CENTERED_FACTOR as C, IN_CIRCLE_FACTOR as I, CIRCLE_RADIUS_FACTOR as a, buildCaptureConstraints as b, detectIsMobile as d };

package/dist/capture-session-v3-BJ8ciaWl.d.ts

@@ -0,0 +1,457 @@
+import { F as FaceObservation, b as Detector, W as WorkerLike } from './detect-worker-CKXHlXx9.js';
+
+/** MP4-first ladder: one container (H.264 MP4) covers iOS/macOS Safari + Chrome 130+.
+ *  WebM/VP9→VP8 only as the Firefox/older-Chromium fallback. */
+declare const MIME_CANDIDATES: readonly ["video/mp4;codecs=avc1.42E01E,mp4a.40.2", "video/mp4;codecs=avc1.42E01E", "video/mp4", "video/webm;codecs=vp9,opus", "video/webm;codecs=vp9", "video/webm;codecs=vp8,opus", "video/webm;codecs=vp8", "video/webm"];
+type CameraErrorKind = "permission" | "notfound" | "inuse" | "overconstrained" | "insecure" | "unsupported" | "generic";
+/** First supported candidate, or "" to let the browser pick its own default. */
+declare function pickMimeType(): string;
+/** Default clip container when pickMimeType() === "" — NEVER .bin/octet-stream (REVIEW FIX 5).
+ *  Prefer the first webm in the ladder the browser most likely defaults to. */
+declare const DEFAULT_CLIP_MIME = "video/webm";
+/** Branch on err.name (never the message). TypeError ⇒ navigator.mediaDevices was undefined
+ *  (insecure/unsupported context) — surfaced as "insecure". */
+declare function mapGetUserMediaError(err: unknown): CameraErrorKind;
+declare function cameraPreflight(): "INSECURE_CONTEXT" | "UNSUPPORTED" | "OK";
+/** iOS Safari (and any browser) may lack MediaRecorder entirely — detect BEFORE prompting
+ *  for the camera so we can fall back to the v1 single-photo path (REVIEW FIX 1). */
+declare function isMediaRecorderSupported(): boolean;
+declare const MAX_CLIP_BYTES: number;
+declare function isClipTooLarge(blob: Blob): boolean;
+declare function extForMime(mime: string): string;
+/** Build the exact multipart body /api/liveness/v2 expects: fields `token`, files `clip` + `keyframe`.
+ *  Caller must NOT set Content-Type — the browser adds the boundary. */
+declare function buildLivenessV2FormData(args: {
+    token: string;
+    clip: Blob;
+    keyframe: Blob;
+    ts?: number;
+}): FormData;
+
+declare const CLIP_MS = 2500;
+declare const TIMESLICE_MS = 1000;
+declare const STOP_GRACE_MS = 1500;
+declare const VIDEO_BPS = 2500000;
+type ClipErrorKind = CameraErrorKind | "cliptoolarge";
+declare class ClipError extends Error {
+    kind: ClipErrorKind;
+    constructor(kind: ClipErrorKind, msg?: string);
+}
+interface ClipResult {
+    blob: Blob;
+    /** Container mime the clip was finalized with (recorder.mimeType || picked || DEFAULT_CLIP_MIME). */
+    mimeType: string;
+}
+declare class ClipRecorder {
+    private recorder;
+    private stream;
+    private chunks;
+    private bytes;
+    private hardStopTimer;
+    private graceTimer;
+    private settled;
+    private clearTimers;
+    /** Records CLIP_MS of the stream. Resolves with the clip blob + its container mime;
+     *  rejects with ClipError. Behavior contract is the v1 hook's `start`, verbatim
+     *  (iOS workarounds included).
+     *
+     *  ONE RECORDING AT A TIME: chunk/byte/timer state is shared per instance, so a
+     *  second record() while one is in flight rejects ClipError("generic") instead of
+     *  corrupting the in-flight clip. (v2 guard — v1's hook was gated by its owning
+     *  component; a class API invites reuse. Zero impact on clip bytes.)
+     *
+     *  `onStopped` (optional) fires ONCE the moment the CLIP_MS recording window
+     *  elapses (the hard-stop), BEFORE finalize — which on iOS can lag up to
+     *  STOP_GRACE_MS while onstop flushes the last chunk. It lets the host freeze
+     *  the display on the already-captured keyframe the instant recording ends,
+     *  instead of waiting for the blob. PURE NOTIFICATION — it does not touch
+     *  timers, chunks, or the finalize path, so it is calibration-neutral (no
+     *  effect on clip bytes). Never fires on a rejected capture (error /
+     *  cliptoolarge settle before the hard-stop and clear the timer). */
+    record(stream: MediaStream, onStopped?: () => void): Promise<ClipResult>;
+    /** Idempotent teardown: stop recorder + ALL tracks (v1 `stopAndCleanup` + the unmount
+     *  effect). Optional `stream` override mirrors v1's `stopAndCleanup(stream?)`.
+     *
+     *  MID-RECORDING SEMANTICS (verbatim v1): calling stop() while a record() is in
+     *  flight may LATER resolve the pending promise with a TRUNCATED clip (recorder.stop()
+     *  fires onstop → finalize from whatever chunks arrived so far), or — because this
+     *  method clears the hard-stop/grace timers — never settle it at all if onstop never
+     *  fires (the iOS grace path has been torn down). Callers MUST NOT treat a resolution
+     *  arriving after stop() as a full CLIP_MS clip, and must not await a record()
+     *  promise past stop() without their own timeout. (Task 4's CaptureSession owns
+     *  sequencing on top of this contract.) */
+    stop(stream?: MediaStream | null): void;
+}
+
+/** CaptureSession state machine (transition map in capture-session.ts):
+ *  idle → preflight → acquiring → positioning → recording → captured
+ *  (photo mode skips `recording`: positioning → captured); any → error. */
+type CaptureState = "idle" | "preflight" | "acquiring" | "positioning" | "recording" | "captured" | "error";
+/** Camera kinds (ported media.ts) + engine kinds:
+ *  - 'models'       detector init failed (the v3 native→blaze ladder was
+ *                   exhausted — e.g. BlazeFace wasm never initialized). Fail
+ *                   loud; there is no degraded mode (a mock capture-anyway mode
+ *                   is a liveness hole, and the face-api floor was dropped).
+ *  - 'cliptoolarge' the 8 MB clip cap (shared with the liveness API contract)
+ *  - 'recorder'     MediaRecorder failed mid-clip. ClipRecorder's v1-verbatim kind for
+ *                   this is 'generic'; CaptureSession REMAPS it to 'recorder' so hosts
+ *                   can distinguish recorder failure from camera 'generic'. */
+type CaptureErrorKind = CameraErrorKind | "models" | "cliptoolarge" | "recorder";
+/** The five v1 gate checks (hysteresis-smoothed statuses). */
+interface GateChecks {
+    faceDetected: boolean;
+    inCircle: boolean;
+    centered: boolean;
+    goodQuality: boolean;
+    stable: boolean;
+}
+/** Capture output. Upload is NOT the engine's job — hosts submit these themselves. */
+interface CaptureArtifacts {
+    /** Absent in photo mode. */
+    clip?: Blob;
+    /** Container mime the clip finalized with. Absent in photo mode. */
+    clipMimeType?: string;
+    /** Mirrored JPEG keyframe (captureMirroredKeyframe). */
+    keyframe: Blob;
+    /** JPEG data URL of the keyframe canvas (v1 preview, quality 0.92). */
+    previewDataUrl: string;
+}
+interface CaptureSessionEvents {
+    statechange: {
+        state: CaptureState;
+    };
+    checks: GateChecks & {
+        counters: Record<keyof GateChecks, number>;
+    };
+    /** fcv2.* message KEY (messages.ts / guidanceCopy) — hosts translate; never prose. */
+    guidance: {
+        key: string;
+    };
+    artifacts: CaptureArtifacts;
+    error: {
+        kind: CaptureErrorKind;
+        retryable: boolean;
+    };
+}
+
+interface V3GateThresholds {
+    /** q at/above which progress rises; below it progress falls. */
+    Q_GOOD: number;
+    /** Integrator slopes, per second. */
+    RISE_PER_S: number;
+    FALL_PER_S: number;
+    /** Centering falloff radius = this × IOD (scale-invariant). The plan's
+     *  formula is 0.45 × IOD × 3 — the 0.45 echoes v1's CIRCLE_RADIUS_FACTOR
+     *  heritage — folded here to 1.35 × IOD. */
+    CENTER_FALLOFF_IOD_MULTIPLE: number;
+    /** Box-only tiers: gate point = bbox center shifted UP by this × height
+     *  (the documented bbox-vs-eyes offset heuristic). */
+    BOX_EYE_OFFSET_FACTOR: number;
+    /** Box-only IOD proxy = this × box width. */
+    IOD_BOX_PROXY_FACTOR: number;
+    /** IOD / frame short side: ideal band + hard limits. */
+    SIZE_IDEAL_MIN: number;
+    SIZE_IDEAL_MAX: number;
+    SIZE_HARD_MIN: number;
+    SIZE_HARD_MAX: number;
+    /** Eye-line roll (deg) that zeroes the pose factor. */
+    ROLL_MAX_DEG: number;
+    /** Center velocity that zeroes the motion factor, in IOD-per-second. */
+    MOTION_VELOCITY_IOD_PER_S: number;
+    /** Velocity-EMA time constant (seconds) — the EMA weight is derived per
+     *  tick as 1−exp(−dt/τ), so the smoothing HORIZON is cadence-invariant:
+     *  a LOW device detecting at 5 Hz gets the same effective smoothing as a
+     *  HIGH device at 10 Hz (a fixed per-sample alpha under-smoothed exactly
+     *  the jittery low-cadence ticks that needed it most). */
+    MOTION_TAU_S: number;
+    /** Velocities at/below this (IOD/s) count as stillness — absorbs detector
+     *  box jitter (largest on LOW's 128px input) before it reaches the EMA. */
+    MOTION_DEADBAND_IOD_PER_S: number;
+    /** ready = p ≥ 1 AND mean q over this window ≥ READY_MEAN_Q. The mean is
+     *  TRIMMED: with ≥3 samples in the window the single worst is dropped, so
+     *  one flaky tick (5 Hz LOW cadence = only 2–3 samples per window) cannot
+     *  veto an otherwise-ready user. */
+    READY_WINDOW_MS: number;
+    READY_MEAN_Q: number;
+    /** Per-factor guidance trigger levels (lowest failing factor speaks). */
+    GUIDE_SIZE: number;
+    GUIDE_CENTERING: number;
+    GUIDE_POSE: number;
+    GUIDE_EXPOSURE: number;
+    GUIDE_SHARPNESS: number;
+    GUIDE_MOTION: number;
+}
+/** Defaults — retuned 2026-07-12 (operator ruling superseding the 2026-07
+ *  freeze; the capture Task-15 refit set must be split at this boundary):
+ *  Q_GOOD 0.55→0.6 so it aligns with the 0.6 guidance thresholds under
+ *  min-q ("no complaint" ⇔ "progress rises"); SIZE_IDEAL_MIN 0.16→0.12 —
+ *  wide-FOV front cameras (common low-end) put an arm's-length face below
+ *  0.16, silently forcing lean-in; the 720p clip floor keeps a 0.12-IOD
+ *  face fully resolvable server-side. */
+declare const V3_GATE_DEFAULTS: Readonly<V3GateThresholds>;
+interface V3GateQuality {
+    /** From frame-quality.sharpness on the face crop. */
+    sharpness: number;
+    /** From frame-quality.exposure on the face crop. */
+    exposure: number;
+    /** Mean crop luma — picks more_light vs too_bright guidance. */
+    meanLuma: number;
+}
+interface V3GateTickInput {
+    timestampMs: number;
+    observation: FaceObservation | null;
+    quality: V3GateQuality;
+    frameWidth: number;
+    frameHeight: number;
+}
+type V3GateFactor = "presence" | "centering" | "size" | "pose" | "sharpness" | "exposure" | "motion";
+/** Per-tick output — the telemetry + chrome contract. */
+interface V3GateTick {
+    at: number;
+    /** Instantaneous quality 0..1 (MIN over the factors — the worst factor). */
+    q: number;
+    /** Integrated progress 0..1. */
+    p: number;
+    factors: Record<V3GateFactor, number>;
+    /** fcv3.* message key for the lowest failing factor (host translates). */
+    guidanceKey: string;
+    /** Fire signal: p ≥ 1 AND the READY_WINDOW mean q ≥ READY_MEAN_Q. */
+    ready: boolean;
+}
+declare class FaceGateV3 {
+    private readonly t;
+    private p;
+    private lastTickAt;
+    private lastCenter;
+    private velocityEma;
+    private qWindow;
+    constructor(overrides?: Partial<V3GateThresholds>);
+    reset(): void;
+    tick(input: V3GateTickInput): V3GateTick;
+    private geometryOf;
+    private motionOf;
+    /** Lowest failing factor speaks — fixed priority (diagnostic, incl. light):
+     *  presence → size → centering → pose → exposure → sharpness → hold.
+     *
+     *  HONESTY FALLBACK (operator ruling 2026-07-12): when every factor clears
+     *  its guide threshold but q (= min factor) is still below Q_GOOD — i.e.
+     *  progress is DRAINING — "hold still" would be a lie ("Perfect" while
+     *  nothing advances; the field symptom was users discovering by accident
+     *  that only leaning in fires the gate). In that state the WORST factor
+     *  speaks even though it passed its guide level, so the user always hears
+     *  the change that actually unblocks recording. */
+    private guidanceOf;
+    /** Direction from the size band set THIS tick (never inverted at the hard
+     *  limits: past SIZE_HARD_MAX the direction is 'close' → move_back). */
+    private sizeGuidance;
+    /** Band midpoint — direction only (tracks EXPOSURE_BAND automatically). */
+    private exposureGuidance;
+    /** Which side of the ideal band the last size measurement fell on. */
+    private lastSizeDirection;
+}
+
+type DeviceClass = "LOW" | "MID" | "HIGH";
+interface DeviceProfile {
+    /** Detection cadence — the scheduler's pace. */
+    cadenceHz: number;
+    /** Downscaled snapshot width handed to the detector. */
+    inputWidth: number;
+    /** Chrome hint: 'reduced' tones down ticks/breathe on LOW even without
+     *  prefers-reduced-motion. */
+    animations: "full" | "reduced";
+}
+declare const DEVICE_PROFILES: Readonly<Record<DeviceClass, Readonly<DeviceProfile>>>;
+interface DeviceProbe {
+    cores: number;
+    /** null where the UA hides it — iOS Safari NEVER exposes deviceMemory
+     *  (field lesson: a 2GB default classified every iPhone LOW). Unknown is
+     *  treated as NEUTRAL (4GB): never demotes to LOW on its own, never
+     *  promotes to HIGH; the dynamic profiler corrects truly slow devices. */
+    memGB: number | null;
+    /** WebAssembly SIMD available (informs wasm-tier expectations/telemetry). */
+    simd: boolean;
+}
+declare function probeDevice(): DeviceProbe;
+/** Static class: LOW (<4 cores or <3GB), HIGH (≥8 cores AND ≥6GB), else MID.
+ *  Unknown memory counts as a neutral 4GB (see DeviceProbe.memGB). */
+declare function classifyDevice(probe: DeviceProbe): DeviceClass;
+/** Dynamic refinement: after the FIRST 10 measured detect ticks, a mean over
+ *  70ms demotes straight to LOW; under 25ms promotes ONE class — at most one
+ *  adjustment ever (no oscillation). */
+declare class DeviceProfiler {
+    private current;
+    private readonly samples;
+    private adjusted;
+    constructor(initial: DeviceClass);
+    get deviceClass(): DeviceClass;
+    get profile(): DeviceProfile;
+    record(detectMs: number): DeviceClass;
+}
+
+/** Best-of-N keyframe window: up to 4 candidates over the first 600ms. */
+declare const KEYFRAME_CANDIDATES = 4;
+declare const KEYFRAME_WINDOW_MS = 600;
+interface V3ChecksPayload {
+    engine: "v3";
+    /** Gate integrator 0..1 — the ring drives off this directly. */
+    progress: number;
+    /** Instantaneous quality 0..1. */
+    q: number;
+    factors: Record<V3GateFactor, number>;
+    /** Attempt ordinal (bumps on retry/switchCamera). */
+    attempt: number;
+}
+interface CaptureSessionV3Events {
+    statechange: {
+        state: CaptureState;
+    };
+    checks: V3ChecksPayload;
+    /** fcv3.* message KEY — hosts translate; never prose. Deduped. */
+    guidance: {
+        key: string;
+    };
+    artifacts: CaptureArtifacts;
+    error: {
+        kind: CaptureErrorKind;
+        retryable: boolean;
+    };
+    /** v3-only, CHROME-only (no data flows here): fires the instant the clip
+     *  recording window ends — BEFORE the blob finalizes (iOS onstop can lag up
+     *  to STOP_GRACE_MS). Carries the already-captured keyframe's JPEG data URL so
+     *  the host can freeze the display on the still immediately instead of leaving
+     *  the live feed running while the clip flushes. Clip mode only (photo mode
+     *  goes straight to `artifacts`). A host that ignores it is unaffected. */
+    frozen: {
+        previewDataUrl: string;
+    };
+}
+type V3TelemetryEvent = {
+    type: "detector";
+    tier: Detector["tier"];
+    fallbackReason?: string;
+} | {
+    type: "profile";
+    staticClass: DeviceClass;
+    activeClass: DeviceClass;
+    simd: boolean;
+} | {
+    type: "fired";
+    timeToGateMs: number;
+    degradeCount: number;
+    meanDetectMs: number;
+} | {
+    type: "error";
+    kind: CaptureErrorKind;
+    fallbackReason?: string;
+};
+interface KeyframeCandidate {
+    blob: Blob;
+    previewDataUrl: string;
+    sharpness: number;
+}
+/** Challenge-clip artifact for the Phase 3 escalation path. */
+interface EscalationClipArtifact {
+    clip: Blob;
+    clipMimeType: string;
+}
+/** INERT Phase 3 seam (docs/superpowers/specs/2026-07-07-active-liveness-
+ *  escalation-spec.md): when the server settles a liveness verdict in the
+ *  REVIEW band it may mint ONE gesture challenge; the host then asks the
+ *  engine for a challenge clip through this hook. Typed and documented NOW so
+ *  capture-v3+ starts from a design — NEVER invoked anywhere in the current
+ *  flow (pinned by a test). */
+interface EscalationHook {
+    onBorderline(challenge: "blink" | "turn"): Promise<EscalationClipArtifact>;
+}
+interface CaptureSessionV3Options {
+    /** Host-owned <video playsInline muted> — same iOS contract as v1. */
+    video: HTMLVideoElement;
+    /** v3 assets base (tasks-vision wasm + tflite); default /models-v3. */
+    v3AssetBaseUrl?: string;
+    mode?: "clip" | "photo";
+    /** FaceGateV3 threshold overrides (Phase 2 tuning). */
+    thresholds?: Partial<V3GateThresholds>;
+    telemetry?: (event: V3TelemetryEvent) => void;
+    facingMode?: "user" | "environment";
+    /** Static class override (tests / host pinning); default = boot probe. */
+    deviceClass?: DeviceClass;
+    /** (detector ladder) */
+    createDetector?: () => Promise<Detector>;
+    /** (fresh ClipRecorder per attempt) */
+    createRecorder?: () => Pick<ClipRecorder, "record" | "stop">;
+    /** (navigator.mediaDevices.getUserMedia) */
+    getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    /** (mirrored canvas keyframe + downscaled Laplacian sharpness) */
+    captureKeyframe?: (video: HTMLVideoElement) => Promise<KeyframeCandidate>;
+    /** (downscaled face-crop sharpness/exposure via canvas) */
+    measureQuality?: (video: HTMLVideoElement, box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }) => V3GateQuality;
+    /** (reused canvas at profile.inputWidth; falls back to the raw video where
+     *  canvas is unavailable) */
+    makeSnapshot?: (video: HTMLVideoElement, targetWidth: number) => CanvasImageSource;
+    /** Worker offload opt-in (Task 9): when provided AND the platform supports
+     *  it (OffscreenCanvas + createImageBitmap + Worker), detection runs
+     *  worker-side through WorkerDetectorProxy. Hosts own Worker construction
+     *  (bundler-specific `new Worker(new URL(...))`). */
+    createWorker?: () => WorkerLike;
+    /** INERT (Phase 3 escalation seam — see EscalationHook). Accepted and
+     *  retained, never called in Phases 1–2. */
+    escalation?: EscalationHook;
+    /** (performance.now) */
+    now?: () => number;
+}
+type Handler<K extends keyof CaptureSessionV3Events> = (payload: CaptureSessionV3Events[K]) => void;
+declare class CaptureSessionV3 {
+    private readonly options;
+    private readonly handlers;
+    private stateValue;
+    private attempt;
+    private facing;
+    private stream;
+    private detector;
+    private scheduler;
+    private gate;
+    private profiler;
+    private lastGuidanceKey;
+    private positioningStartedAt;
+    private fired;
+    private carriedDegrade;
+    private carriedMeans;
+    constructor(options: CaptureSessionV3Options);
+    get state(): CaptureState;
+    on<K extends keyof CaptureSessionV3Events>(event: K, handler: Handler<K>): () => void;
+    private emit;
+    start(): Promise<void>;
+    /** Full reset + camera restart — the documented recovery path (v1 parity). */
+    retry(): void;
+    switchCamera(): void;
+    destroy(): void;
+    private run;
+    /** Chrome hint (Task 11): 'reduced' on LOW even without the media query. */
+    get animations(): "full" | "reduced";
+    private startScheduler;
+    private detectTick;
+    private fire;
+    /** Up to KEYFRAME_CANDIDATES mirrored frames over KEYFRAME_WINDOW_MS —
+     *  sharpest wins (reuses frame-quality.sharpness via the capture seam). */
+    private collectKeyframes;
+    private finishCapture;
+    private defaultKeyframe;
+    /** Reused downscale canvas — falls back to the raw video where canvas 2D
+     *  is unavailable (jsdom) so tests and exotic hosts keep detecting. */
+    private snapshotCanvas;
+    private defaultSnapshot;
+    private defaultQuality;
+    private centerSharpness;
+    private teardownAttempt;
+    private stopTracks;
+    private fail;
+    private setState;
+    private now;
+}
+
+export { V3_GATE_DEFAULTS as A, VIDEO_BPS as B, type CameraErrorKind as C, DEFAULT_CLIP_MIME as D, type EscalationClipArtifact as E, FaceGateV3 as F, type GateChecks as G, buildLivenessV2FormData as H, cameraPreflight as I, classifyDevice as J, KEYFRAME_CANDIDATES as K, extForMime as L, MAX_CLIP_BYTES as M, isClipTooLarge as N, isMediaRecorderSupported as O, mapGetUserMediaError as P, pickMimeType as Q, probeDevice as R, STOP_GRACE_MS as S, TIMESLICE_MS as T, type V3ChecksPayload as V, CLIP_MS as a, type CaptureArtifacts as b, type CaptureErrorKind as c, type CaptureSessionEvents as d, CaptureSessionV3 as e, type CaptureSessionV3Events as f, type CaptureSessionV3Options as g, type CaptureState as h, ClipError as i, type ClipErrorKind as j, ClipRecorder as k, type ClipResult as l, DEVICE_PROFILES as m, type DeviceClass as n, type DeviceProbe as o, type DeviceProfile as p, DeviceProfiler as q, type EscalationHook as r, KEYFRAME_WINDOW_MS as s, MIME_CANDIDATES as t, type V3GateFactor as u, type V3GateQuality as v, type V3GateThresholds as w, type V3GateTick as x, type V3GateTickInput as y, type V3TelemetryEvent as z };