@sekyro/web 0.1.0-rc.7 → 0.1.0-rc.8

package/dist/create-verification-C0AVIcVW.d.ts

@@ -0,0 +1,2787 @@
+import { b as Detector } from './detect-worker-DclNxkZT.js';
+import { i as CaptureState$1, f as CaptureSessionV3Events, g as CaptureSessionV3Options, c as CaptureErrorKind$1, p as DeviceClass, b as CaptureArtifacts, H as V3GateQuality, N as V3TelemetryEvent } from './capture-session-v3-CQK-G-qX.js';
+import { A as AcceptedDocumentType, a5 as StepSection, i as HostedBranding, c as ContactChannel, C as CheckReason, P as IdentityMethod, E as EidAfterPass, Q as IdentitySummarySource, p as HostedIcaoPolicy, V as NationalEidOption, N as IcaoReportEntry, I as IcaoCaptureTuning, w as HostedSessionView, x as HostedStepView, L as IcaoGateSummary, M as IcaoGateUpdate, a2 as SessionFailureReason, U as MethodChoiceView, z as HostedVoiceView, ao as Point, aK as PersonMask, a8 as Box, ag as IcaoFrameObservation, aL as HostedClient, aM as AttestationInput, a6 as SessionView, b as CheckType, a0 as PortraitIcaoInput, ah as IcaoGate } from './icao-gate-D8qm1O2t.js';
+
+declare const ISSUER_CODES: readonly string[];
+
+/** Accepted document types per issuer (the view's `acceptedDocuments`): `byIssuer[iso2] ?? default`; `"*"` = every type. */
+interface AcceptedDocumentsLike {
+    default: "*" | readonly AcceptedDocumentType[];
+    byIssuer?: Readonly<Record<string, readonly AcceptedDocumentType[]>>;
+}
+/** Picker order: identity card, passport, residence permit. */
+declare const DOCUMENT_TYPE_ORDER: readonly AcceptedDocumentType[];
+/** Types accepted for documents of `issuer` (ISO 3166-1 alpha-2), in picker order. */
+declare const acceptedTypesFor: (accepted: AcceptedDocumentsLike, issuer: string) => AcceptedDocumentType[];
+/** Issuers with at least one accepted type, sorted by code (name them with `Intl.DisplayNames`). */
+declare const acceptedIssuers: (accepted: AcceptedDocumentsLike, codes?: readonly string[]) => string[];
+/** `acceptedDocuments`, or — from a server that predates it — MR with the legacy `acceptedDocumentTypes`. */
+declare const resolveAcceptedDocuments: (view: {
+    acceptedDocuments?: AcceptedDocumentsLike | undefined;
+    acceptedDocumentTypes?: readonly AcceptedDocumentType[] | undefined;
+}) => AcceptedDocumentsLike;
+/** Flag emoji of an alpha-2 code (regional indicator symbols); `""` otherwise. */
+declare const flagOf: (iso2: string) => string;
+
+declare const WEB_IDENTITY_METHODS: readonly IdentityMethod[];
+/** Plan 4's web stop for `nfc.mode = mandatory` (view-only `failureReason`) and the skip reason in `preferred`. */
+declare const PLATFORM_UNSUPPORTED = "platform_unsupported";
+/** A step's section: the view's value (kept even when unknown), else the check type's. */
+declare function sectionOf(step: Pick<HostedStepView, "checkType" | "section">): StepSection | null;
+type DocumentSide = "recto" | "verso" | "single";
+interface DeriveStepEnv {
+    /** A phone / tablet browser; `false` routes a `requiresMobile` biometric step to `mobile_required`. */
+    isMobile?: boolean;
+}
+interface StepContext {
+    sessionId: string;
+    orgName: string;
+    returning: boolean;
+    consentRecorded: boolean;
+    expiresAt: string;
+    branding?: HostedBranding;
+    /**
+     * The sections of this session in flow order (flow model 2026-10-23), one
+     * progress segment each; a section with no steps is left out.
+     */
+    sections: StepSection[];
+}
+interface StepAttempts {
+    reason?: CheckReason;
+    attemptsRemaining: number;
+    attemptsExhausted: boolean;
+}
+type OtpNumberSource = "prefilled" | "user_entered" | "prefilled_or_entered";
+/** Where an email_otp address comes from (same vocabulary as the phone number). */
+type EmailSource = OtpNumberSource;
+/** A phone OTP delivery channel the person can choose. */
+type OtpChannel = "whatsapp" | "sms";
+interface PhoneOtpSnapshot extends StepAttempts {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "phone_otp";
+    key: string;
+    context: StepContext;
+    phase: "send" | "verify";
+    numberSource: OtpNumberSource;
+    needsPhone: boolean;
+    /**
+     * The channels the person chooses from, in the server's display order
+     * (WhatsApp first). `[]` for a session created before channel choice: send
+     * without a channel (SMS). With more than one, `send` needs the person's choice.
+     */
+    channels: OtpChannel[];
+    sentToMasked?: string;
+    channel?: "sms" | "whatsapp";
+    codeExpiresAt?: string;
+    /** ISO time from which a resend is allowed (the server's cooldown, else 30 s after this page's last send). */
+    resendAvailableAt?: string;
+    /** A `one_of` session where no contact step passed yet: the person may switch to {@link switchChannel}. */
+    canSwitch: boolean;
+    /** The other contact option (with `canSwitch`). */
+    switchChannel?: ContactChannel;
+}
+/** Email OTP (profile v2 §4.6.5): send a code to an address, then verify it. */
+interface EmailOtpSnapshot extends StepAttempts {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "email_otp";
+    key: string;
+    context: StepContext;
+    phase: "send" | "verify";
+    emailSource: EmailSource;
+    /** The person types the address (every source but `prefilled`). */
+    needsEmail: boolean;
+    /** Masked address of the last send (e.g. `a•••@e•••.com`). */
+    sentToMasked?: string;
+    codeExpiresAt?: string;
+    /** ISO time from which a resend is allowed (the server's cooldown, else 30 s after this page's last send). */
+    resendAvailableAt?: string;
+    /** See {@link PhoneOtpSnapshot.canSwitch}. */
+    canSwitch: boolean;
+    switchChannel?: ContactChannel;
+}
+/**
+ * Step 1 contact choice (flow model 2026-10-23): a `one_of` session before the
+ * person chose phone or email.
+ */
+interface ContactChoiceSnapshot {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "contact_choice";
+    key: string;
+    context: StepContext;
+    options: ContactChannel[];
+    selected: ContactChannel | null;
+    locked: boolean;
+}
+/**
+ * Step 2b summary and confirm (flow model 2026-10-23): the identity data read so
+ * far, to confirm before the live photo. Masks keep the last 4 characters. PII:
+ * never log these values or send them to analytics.
+ */
+interface IdentitySummarySnapshot {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "identity_summary";
+    key: string;
+    context: StepContext;
+    /** `full` (document / chip, with the photo) or `partial` (registry from a typed NNI: short name, birth year, no photo). */
+    summaryKind: "full" | "partial" | (string & {});
+    source: IdentitySummarySource | (string & {});
+    /** The full name, or the short form "Mohamed S." on a `partial` summary. */
+    fullName?: string;
+    birthDate?: string;
+    /** `partial` summaries carry the birth year only. */
+    birthYear?: string;
+    nationality?: string;
+    documentType?: string;
+    documentNumberMasked?: string;
+    nniMasked?: string;
+    expiryDate?: string;
+    /** The portrait can be fetched (`portrait()` on the handle). */
+    portraitAvailable: boolean;
+    retakeAvailable: boolean;
+    retakeTarget?: "document" | "national_number" | (string & {});
+}
+interface MethodSnapshot {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "method";
+    key: string;
+    context: StepContext;
+    options: IdentityMethod[];
+    /** The provider behind `national_eid` ("Verify with Houwiyeti"); absent when it is not offered. */
+    nationalEid?: NationalEidOption;
+}
+/**
+ * The national eID sign-in (SDK spec §3.2; Houwiyeti in MR). Two phases:
+ * - `identifier` — the person types their national number (the NNI in MR)
+ *   unless `identifierBound`, then the SDK asks the provider for a code;
+ * - `code` — the person opens the provider's app and types the code shown.
+ * A passed eID ends the session (no document, liveness or face match). With
+ * `canUseCamera` (`eid_not_enrolled`, `eid_unavailable`, `eid_locked` on a
+ * session that offers the camera path) the person may switch to `cameraMethod`.
+ */
+interface EidSnapshot extends StepAttempts {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "eid";
+    key: string;
+    context: StepContext;
+    /** `{ISO2}.{provider}`, e.g. `MR.houwiyeti`. */
+    provider: string;
+    /** Display name, e.g. "Houwiyeti" (for "Verify with Houwiyeti"). */
+    providerName: string;
+    country: string;
+    challenge: "app_code";
+    phase: "identifier" | "code";
+    identifierBound: boolean;
+    codeExpiresAt?: string;
+    resendAvailableAt?: string;
+    resendsRemaining?: number;
+    codeAttemptsRemaining?: number;
+    canUseCamera: boolean;
+    /** The camera-path method `useCamera()` selects (present with `canUseCamera`). */
+    cameraMethod?: IdentityMethod;
+    /** What follows a pass (flow model 2026-10-23): `continue` = a live photo follows ("then a quick selfie"). */
+    afterPass: EidAfterPass;
+}
+type RegistrySource = "bound" | "document" | "typed";
+interface RegistrySnapshot extends StepAttempts {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "registry";
+    key: string;
+    context: StepContext;
+    state: "pending" | "input_required";
+    source: RegistrySource;
+    recheck: boolean;
+    canUseDocument: boolean;
+}
+interface DocumentSnapshot extends StepAttempts {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "document";
+    key: string;
+    context: StepContext;
+    side: "recto" | "verso";
+    acceptedSides: ("recto" | "verso")[];
+    documents: AcceptedDocumentsLike;
+}
+interface LivenessSnapshot extends StepAttempts {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "liveness";
+    key: string;
+    context: StepContext;
+    mode: "liveness" | "selfie";
+    requiresMobile: boolean;
+    /**
+     * Step 3 instructions (flow model 2026-10-23): `icao` on a session whose
+     * selfie is ICAO-checked (`icao` below) — the ICAO tips variant.
+     */
+    instructions: "standard" | "icao";
+    /** The session's selfie ICAO policy (`icaoPolicyOf`), `null` when ICAO is off (absent on older SDKs). */
+    icao?: HostedIcaoPolicy | null;
+    /**
+     * Step 3 one capture: the capture also takes a full-resolution still. `icao`
+     * = the ICAO portrait is due from this capture (`portrait_icao` pending): the
+     * gate also requires the ICAO conditions and the still rides the liveness
+     * submission as `input.portraitIcao`. `null` on an older API.
+     */
+    livePhoto: LivePhotoPlan | null;
+}
+/** How one live-photo capture is taken (flow model 2026-10-23, Step 3). */
+interface LivePhotoPlan {
+    icao: boolean;
+    still: {
+        minLongSidePx: number;
+        jpegQuality: number;
+    };
+}
+/**
+ * The ICAO portrait step of an ID-document session (SDK spec §4.9, §5.4):
+ * - `capture` — `portrait_icao` is the frontier: run the strict gate, take the
+ *   portrait (a retry carries the server's `report` to coach from);
+ * - `match` — the portrait was accepted (`passed`, or `review` after the
+ *   attempt cap: `review: true`, "We'll review your photo") and `face_match`
+ *   is due: the SDK submits it with the portrait as the probe — no new capture.
+ */
+interface PortraitSnapshot extends StepAttempts {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "portrait";
+    key: string;
+    context: StepContext;
+    phase: "capture" | "match";
+    /** The server's per-criterion report of the last attempt (`null` before one). */
+    report: IcaoReportEntry[] | null;
+    /** The portrait goes to a reviewer (attempt cap reached in decision mode `review`). */
+    review: boolean;
+    /** `capture.icao` (coaching limits) and `capture.tuningVersion` of the view. */
+    tuning: IcaoCaptureTuning | null;
+    tuningVersion: string | null;
+    /** The session's ICAO policy and profile (`icaoPolicyOf`; absent on older SDKs). */
+    icao?: HostedIcaoPolicy | null;
+    /**
+     * Step 3 (flow model 2026-10-23): the live check of this session passed and
+     * only the ICAO portrait needs another still — a portrait-only retake, no new clip.
+     */
+    retakeOnly: boolean;
+}
+interface MobileRequiredSnapshot {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "mobile_required";
+    key: string;
+    context: StepContext;
+    checkType: "liveness" | "face_match";
+}
+interface ProcessingSnapshot {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "processing";
+    key: string;
+    context: StepContext;
+    stalled: boolean;
+}
+type UnsupportedReason = "platform_unsupported" | "update_required";
+interface UnsupportedSnapshot {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "unsupported";
+    key: string;
+    context: StepContext;
+    checkType: string;
+    reason: UnsupportedReason;
+}
+type ResultDisplay = "approved" | "review" | "rejected" | "expired" | "policy_stop" | "cooldown" | "platform_unsupported" | "attempts_exhausted";
+interface ResultSnapshot {
+    /**
+     * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
+     * `live_photo`; an unknown value from a newer server is kept), `null` when the
+     * step has none (an idle processing step, the result).
+     */
+    section: StepSection | null;
+    kind: "result";
+    key: string;
+    context: StepContext;
+    display: ResultDisplay;
+    result: VerificationResult;
+    failureReason?: string;
+    retryAfter?: string;
+}
+type StepSnapshot = PhoneOtpSnapshot | EmailOtpSnapshot | ContactChoiceSnapshot | IdentitySummarySnapshot | MethodSnapshot | EidSnapshot | RegistrySnapshot | DocumentSnapshot | LivenessSnapshot | PortraitSnapshot | MobileRequiredSnapshot | ProcessingSnapshot | UnsupportedSnapshot | ResultSnapshot;
+/**
+ * ID mode: `face_match` is due right after an ACCEPTED portrait (passed, or
+ * review after the cap) that it has not been tried with yet — the portrait is
+ * the probe (the server picks it), so no selfie is taken. A face_match that
+ * already carries a reason was tried: the regular selfie path applies.
+ */
+declare function portraitMatchStep(view: HostedSessionView, frontier: HostedStepView): HostedStepView | null;
+/** The step the view asks for right now. */
+declare function deriveStep(view: HostedSessionView, env?: DeriveStepEnv): StepSnapshot;
+
+type DocumentCaptureState = "idle" | "starting" | "scanning" | "captured" | "uploading" | "checking" | "done" | "error";
+/** Aggregated coaching (copy keys `dcv2.<key>`). */
+type DocumentFeedbackKey = "sensing" | "too_far" | "too_close" | "edge_clipped" | "wrong_shape" | "tilted" | "too_dark" | "too_bright" | "blurry" | "glare" | "hold_still" | "processing" | "side_captured" | "captured" | "focus_far";
+type DocumentReticle = "searching" | "coaching" | "locking" | "processing" | "flip" | "done";
+interface DocumentFeedback {
+    key: DocumentFeedbackKey;
+    reticle: DocumentReticle;
+}
+interface DocumentPoint {
+    x: number;
+    y: number;
+}
+interface DocumentQuad {
+    topLeft: DocumentPoint;
+    topRight: DocumentPoint;
+    bottomRight: DocumentPoint;
+    bottomLeft: DocumentPoint;
+}
+/** The card the guide-region lock measures inside the on-screen guide (ID-1 cards; absent for passport pages). */
+interface DocumentGuideMeasure {
+    /** A card is measured in the guide on this tick. */
+    detected: boolean;
+    /** Card width / guide width (1 = fitted). */
+    fill: number;
+    /** Card centre offset in guide widths / heights (+ = right / down). */
+    offsetX: number;
+    offsetY: number;
+}
+/** Gate ring + overlay; quad coordinates live in `frameWidth × frameHeight` (the detect frame). */
+interface DocumentGateUpdate {
+    progress: number;
+    quad: DocumentQuad | null;
+    frameWidth: number;
+    frameHeight: number;
+    /** The card measured in the guide (lets a UI frame the card it sees); absent when the guide lock is off. */
+    guide?: DocumentGuideMeasure;
+}
+/**
+ * The on-screen guide the card is framed in: `rect` normalized (0..1) in the video element of aspect `viewAspect`
+ * (width / height) that shows the camera with `object-fit: cover`.
+ */
+interface DocumentGuide {
+    viewAspect: number;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+type DocumentScanPhase = "framing" | "locking" | "capturing" | "flipCue" | "reaskRecto" | "reading" | "result";
+interface DocumentScanUpdate {
+    phase: DocumentScanPhase;
+    captured: DocumentSide[];
+    expected: DocumentSide | null;
+    /** Coaching left by the last capture or read (`blurry`: the blur gate refused the photo, retake at once). */
+    notice: "same_face" | "reread" | "technical" | "blurry" | null;
+    lastShot: DocumentSide | null;
+    manualShutter: boolean;
+    torchAvailable: boolean;
+    torch: boolean;
+}
+interface CapturedDocument {
+    /** Upload-ready JPEG (adaptive encode applied). Live camera only — there is no file input. */
+    image: Blob;
+    /** The face this photo shows (classified on device for cards; the server confirms). */
+    side: DocumentSide;
+    documentType: AcceptedDocumentType;
+    issuer?: string;
+    width: number;
+    height: number;
+    previewDataUrl: string;
+}
+/**
+ * Web live MRZ (spec 2026-10-21 D5): the on-device reader's state on a face with an MRZ (passport page, card back).
+ * Never carries text or a digest. `mismatch`: a valid read whose format contradicts the picked document (the photo is
+ * still taken; the server decides). `fallback`: the reader stepped aside (today's capture continues).
+ */
+interface DocumentMrzUpdate {
+    state: "searching" | "reading" | "valid" | "mismatch" | "fallback";
+    format?: "TD1" | "TD2" | "TD3";
+    coach?: "moveCloser" | "turnSideways" | "glare" | "holdStill";
+    reason?: "timeout" | "slow" | "unsupported" | "download" | "integrity" | "error" | "off";
+}
+/** Web live MRZ options (spec D7/D9): `mode: "off"` opts out; `auto` (default) obeys the session's server tuning. */
+interface DocumentLiveMrzOptions {
+    mode?: "auto" | "off";
+    /** Where the OCR assets are served (default the Sekyro AI assets CDN). Self-host: the `<fp12>/` directory goes under it. */
+    assetBaseUrl?: string;
+    /** Where your bundler serves `@sekyro/web/core/ocr/worker` (or the self-contained `worker.bundle.js`). Without it the reader stays off. */
+    workerUrl?: string | URL;
+}
+interface DocumentCaptureEvents {
+    state: DocumentCaptureState;
+    /** Web live MRZ reader state (MRZ faces only; text-free). */
+    mrz: DocumentMrzUpdate;
+    feedback: DocumentFeedback;
+    gate: DocumentGateUpdate;
+    scan: DocumentScanUpdate;
+    captured: CapturedDocument;
+    error: CaptureError;
+}
+interface DocumentCaptureOptions {
+    /** Host-owned `<video playsInline muted>`; the rear camera is opened. */
+    video: HTMLVideoElement;
+    documentType: AcceptedDocumentType;
+    /** Expected face; omit for a card's first face (either face). Passports are always `"single"`. */
+    side?: DocumentSide;
+    /** Display/telemetry only; capture is identical for every issuer. */
+    issuer?: string;
+    /** Default `true` (best-effort Screen Wake Lock while the camera is live). */
+    keepScreenAwake?: boolean;
+    /** `navigator.vibrate` on capture where available. Default `true`. */
+    haptics?: boolean;
+    /** Web live MRZ (on-device MRZ read that decides the shot on MRZ faces); server-controlled, additive. */
+    liveMrz?: DocumentLiveMrzOptions;
+}
+interface DocumentCaptureHandle {
+    readonly state: DocumentCaptureState;
+    on<K extends keyof DocumentCaptureEvents>(event: K, handler: (payload: DocumentCaptureEvents[K]) => void): () => void;
+    start(): Promise<void>;
+    /** Start over (both faces), or restart the camera after an error. */
+    retry(): void;
+    /** Ask for this face next (after the server accepted the other one). */
+    setSide(side: DocumentSide): void;
+    /** Take the photo now (meaningful while `scan.manualShutter`). */
+    shutter(): void;
+    /** Manual torch; no-op where the camera has none. Never turned on by the SDK. */
+    setTorch(on: boolean): void;
+    /**
+     * Tap-to-focus at a normalized point of the video frame (0..1, e.g. from a tap
+     * on the preview). No-op where the camera has no single-shot focus (iOS Safari).
+     */
+    focusAt(x: number, y: number): void;
+    /**
+     * Where the on-screen guide is (call again when the view resizes); `undefined` = the default guide, centred and
+     * 86 % of the frame wide. The lock measures the card inside it, so a guide drawn elsewhere must be declared.
+     */
+    setGuide(guide: DocumentGuide | undefined): void;
+    destroy(): void;
+}
+
+/**
+ * - `starting` — camera and landmark model loading;
+ * - `gating` — the strict ICAO gate is coaching (`gate` events);
+ * - `captured` — the portrait frame was taken (`captured` fired);
+ * - `uploading` / `checking` / `done` — driven by the verification when the
+ *   handle belongs to a plan-runner step;
+ * - `error` — camera or model failure (`error` fired).
+ */
+type PortraitCaptureState = "idle" | "starting" | "gating" | "captured" | "uploading" | "checking" | "done" | "error";
+/** One gate evaluation: per-criterion state, the one coaching message, readiness. */
+type PortraitGateUpdate = IcaoGateUpdate;
+interface CapturedPortrait {
+    /**
+     * Upload-ready JPEG: a 3:4 portrait region of the full-resolution frame
+     * around the face (not mirrored), at least 480×640. The server cuts the
+     * normalised ICAO crop from it.
+     */
+    image: Blob;
+    width: number;
+    height: number;
+    /** The on-device gate result and the eye-openness baseline (`gate` of the submission). */
+    gate: IcaoGateSummary;
+    /** `capture.tuningVersion` the gate ran with, when the server sent one. */
+    tuningVersion?: string;
+}
+interface PortraitCaptureEvents {
+    state: PortraitCaptureState;
+    gate: PortraitGateUpdate;
+    captured: CapturedPortrait;
+    error: CaptureError;
+}
+interface PortraitCaptureOptions {
+    /** Host-owned `<video playsInline muted>`; the front camera is opened. Mirror it with CSS. */
+    video: HTMLVideoElement;
+    /** `HostedSessionView.capture.icao`; missing fields use the bundled fallbacks. */
+    tuning?: IcaoCaptureTuning | null;
+    /** `HostedSessionView.capture.tuningVersion`, echoed on submit. */
+    tuningVersion?: string | null;
+    /**
+     * The session's ICAO policy (`icaoPolicyOf(view).policy`). `alert` coaches but
+     * never blocks: the photo is taken `capture.icao.alertGraceMs` after the face is
+     * accepted at the latest. Default `reject`.
+     */
+    policy?: "reject" | "alert";
+    /** Self-hosted MediaPipe assets (wasm fileset + `face_landmarker.task`); default `/models-v3`. */
+    assetBaseUrl?: string;
+    /** Default `true` (best-effort Screen Wake Lock while the camera is live). */
+    keepScreenAwake?: boolean;
+}
+interface PortraitCaptureHandle {
+    readonly state: PortraitCaptureState;
+    on<K extends keyof PortraitCaptureEvents>(event: K, handler: (payload: PortraitCaptureEvents[K]) => void): () => void;
+    /** Open the camera, load the model and start the gate. */
+    start(): Promise<void>;
+    /** Take the photo again (gate only — the camera stays open), or restart after an error. */
+    retry(): void;
+    destroy(): void;
+}
+
+/** Gate guidance code. `'hold'` is emitted while the clip records. */
+type GateHint = "center" | "closer" | "farther" | "light" | "still" | "hold";
+/**
+ * Capture + verification state, as seen by the partner:
+ *  - `idle → starting → gating → recording → captured` is the engine's run;
+ *  - `uploading → checking → done` follows ONLY when the handle was obtained via
+ *    {@link Verification.liveness} (the SDK uploads and submits after `captured`);
+ *  - `error` on a camera / engine failure (see {@link CaptureError}).
+ */
+type CaptureState = "idle" | "starting" | "gating" | "recording" | "captured" | "uploading" | "checking" | "done" | "error";
+/** Declared capture channel — the liveness band is mobile-calibrated. */
+type CaptureChannel = "mobile" | "desktop";
+/** Gate ring update: integrator progress 0..1 and the current guidance code. */
+interface GateUpdate {
+    /** Gate integrator 0..1 — drive the ring off this directly. */
+    progress: number;
+    /** Current guidance code, `null` when no hint applies. */
+    hint: GateHint | null;
+    /**
+     * The detector currently sees a face (a non-zero engine presence factor). `false`
+     * with `hint: 'center'` means "no face in frame" rather than "off-center" —
+     * hosts use it to tell seeking from aligning, and for the no-face copy.
+     */
+    faceDetected: boolean;
+}
+/**
+ * What the engine captured. Fires BEFORE any upload. `clip` is absent only in
+ * the `degraded: 'NO_RECORDER'` case (no MediaRecorder on this browser).
+ */
+interface CapturedArtifacts {
+    /** Mirrored JPEG keyframe (the face_match probe). */
+    keyframe: Blob;
+    /** The 2.5 s liveness clip (MP4-first mime ladder). */
+    clip?: Blob;
+    /** Container mime the clip finalized with — may carry codec params. */
+    clipMime?: string;
+    /** Intrinsic video width at capture time. */
+    width: number;
+    /** Intrinsic video height at capture time. */
+    height: number;
+    /** Recording-start → recording-stop, when known. */
+    clipMs?: number;
+    /** `'mobile'` on phones/tablets (the calibrated channel), else `'desktop'`. */
+    captureChannel: CaptureChannel;
+    /** Set when the browser has no MediaRecorder: a keyframe-only capture. */
+    degraded?: "NO_RECORDER";
+    /** The capture engine that produced the artifacts (`'v3'` for this SDK). Always set by the SDK; optional in the type so host-built fixtures stay valid. */
+    engine?: CaptureEngineId;
+    /**
+     * Camera request (`getUserMedia`) → the preview is live, in whole
+     * milliseconds measured with `performance.now()`. Part of the face-capture
+     * timing the SDK forwards to the backend as `input.capture` on the liveness
+     * submission; absent when the phase was not observed.
+     */
+    cameraReadyMs?: number;
+    /**
+     * Camera ready → the first face ACCEPTED by the gate (present and with
+     * size, centering and quality good enough to make progress — not merely
+     * detected), whole ms. Absent when no face was ever accepted.
+     */
+    faceAcquireMs?: number;
+    /**
+     * Face-capture duration: FIRST accepted face → gate progress 100 % (capture
+     * complete, before the clip window and any upload), whole ms. A face lost
+     * and re-acquired keeps the first acceptance as its start.
+     */
+    captureMs?: number;
+}
+/** Capture engine identifier carried on {@link CapturedArtifacts.engine}. */
+type CaptureEngineId = "v1" | "v3";
+/** Camera / engine failure kinds — collapsed to the public six. */
+type CaptureErrorKind = "permission" | "notfound" | "inuse" | "insecure" | "unsupported" | "generic";
+/** Camera / engine failure payload (`on('error')`). */
+interface CaptureError {
+    kind: CaptureErrorKind;
+    /**
+     * A fresh attempt (`retry()`) can succeed — false for `insecure` (needs
+     * HTTPS) and `unsupported` (the browser cannot capture at all).
+     */
+    retryable: boolean;
+}
+/** Event map of a {@link LivenessCaptureHandle}. */
+interface LivenessCaptureEvents {
+    /** Every state transition. */
+    state: CaptureState;
+    /** Gate ring updates while gating/recording. */
+    gate: GateUpdate;
+    /** The capture result — fires BEFORE any upload. */
+    captured: CapturedArtifacts;
+    /** Camera / engine failure. */
+    error: CaptureError;
+    /**
+     * Clip mode only: the recording window just ended and the keyframe is already
+     * available, BEFORE the clip finalizes (iOS can lag ~1.5 s). Hosts freeze the
+     * display on `previewDataUrl` (a mirrored JPEG data URL) instead of leaving
+     * the live feed running; `captured` follows once the clip lands.
+     */
+    frozen: {
+        previewDataUrl: string;
+    };
+    /**
+     * Device-profile hint, emitted when it changes: `'reduced'` asks the host to
+     * drop decorative animations (a LOW device class needs the frames for
+     * detection). Chrome only — never gate input.
+     */
+    profile: {
+        animations: "full" | "reduced";
+    };
+}
+/** Which camera to open: the selfie camera (`'user'`) or the rear one (`'environment'`). */
+type CameraFacing = "user" | "environment";
+/** Options of {@link LivenessCaptureHandle.start}. */
+interface LivenessStartOptions {
+    /**
+     * Camera for this attempt and its retries; default: the current one
+     * ({@link LivenessCaptureOptions.facing}, else `'user'`). Use `switchCamera()`
+     * to change camera mid-capture.
+     */
+    facing?: CameraFacing;
+}
+/** Live capture handle returned by {@link createLivenessCapture} / {@link Verification.liveness}. */
+interface LivenessCaptureHandle {
+    /** Current {@link CaptureState}. */
+    readonly state: CaptureState;
+    /** Subscribe; returns the unsubscribe function. */
+    on<K extends keyof LivenessCaptureEvents>(event: K, handler: (payload: LivenessCaptureEvents[K]) => void): () => void;
+    /**
+     * Ask for the camera and start gating. Resolves once the attempt is running or failed.
+     * `options.facing` picks the camera for this attempt and later retries.
+     */
+    start(options?: LivenessStartOptions): Promise<void>;
+    /** Fresh attempt: resets the engine and restarts the camera. */
+    retry(): void;
+    /** Toggle user/environment camera (gate restarts from zero). */
+    switchCamera(): void;
+    /** Stop the camera, release the detector, drop all listeners. */
+    destroy(): void;
+}
+/** Options of {@link createLivenessCapture} / {@link Verification.liveness}. */
+interface LivenessCaptureOptions {
+    /** Host-owned `<video playsInline muted>` element. */
+    video: HTMLVideoElement;
+    /** Initial camera; default `'user'`. `start({ facing })` overrides it. */
+    facing?: CameraFacing;
+    /** Base URL of the detector assets (tasks-vision wasm + tflite); default `/models-v3`. */
+    assetBaseUrl?: string;
+    /**
+     * Hold a Screen Wake Lock while the camera is live (`starting` / `gating` /
+     * `recording`) so the phone does not dim or lock mid-capture; re-taken when
+     * the page becomes visible again. Best-effort: unsupported browsers or a
+     * refused request (e.g. an iframe without `allow="screen-wake-lock"`) never
+     * affect the capture. Default `true`; `false` never requests the lock.
+     */
+    keepScreenAwake?: boolean;
+}
+/**
+ * SDK-side failure reasons (status `'unavailable'`):
+ *  - `no_recorder` — no MediaRecorder / unsupported clip container;
+ *  - `attestation` — Turnstile failed client-side or `attestation_invalid` after one retry;
+ *  - `network` — transport / API failure after the bounded replays;
+ *  - `nni_unbound` — `population_registry` is the frontier but the session was
+ *    minted WITHOUT a server-bound NNI (`POST /sessions` `input.nni`), so the
+ *    SDK cannot submit it. Mint the session with the NNI (or complete the
+ *    population step yourself) before starting the capture;
+ *  - `method_required` — the session waits on the identity-method choice
+ *    (profile v2 step 3; `on('method')` fired). Ask the person, call
+ *    {@link Verification.selectMethod}, then capture again;
+ *  - `inference_unavailable` — the model service stayed busy through the
+ *    automatic retries (profile v2 step 4; `on('busy')` fired for each). No
+ *    attempt was used and nothing was billed: let the person try again in a
+ *    moment;
+ *  - `portrait_required` — ID mode (SDK spec §4.9): liveness is done and the
+ *    session continues with the ICAO portrait step — not a failure. The plan
+ *    runner (`run()`) moves on by itself; a liveness-only integration hands
+ *    over to {@link createPortraitCapture} (or the hosted page).
+ *
+ * A liveness step that needs a phone (`HostedStepView.requiresMobile`) on a
+ * desktop browser ends with the reason `mobile_required` (status
+ * `unavailable`): send the person to their phone. The SDK stops before any
+ * upload when the view says so; otherwise the backend answers the submit with
+ * a request-level `409 mobile_required` (no attempt used, nothing billed).
+ */
+type SdkFailureReason = "no_recorder" | "attestation" | "network" | "nni_unbound" | "method_required" | "inference_unavailable" | "portrait_required";
+/** Backend reason taxonomy ∪ the SDK-side failure reasons. */
+type ReasonCode = CheckReason | SessionFailureReason | SdkFailureReason;
+/**
+ * - `approved` / `rejected` / `review` — the session's verdict;
+ * - `retry` — a retryable reason with attempts remaining (`autoRetry` on); the
+ *   capture re-arms by itself;
+ * - `unavailable` — v2 could not run this capture (no MediaRecorder,
+ *   attestation failed, network/API failure). Treat as "not completed".
+ */
+type VerificationStatus = "approved" | "rejected" | "review" | "retry" | "unavailable";
+/** The verdict for this session / capture (`on('result')`). */
+interface VerificationResult {
+    sessionId: string;
+    status: VerificationStatus;
+    /** Backend check or session-policy reason, or SDK-side reason for `unavailable`. */
+    reason?: ReasonCode;
+    /**
+     * `retry` (and a `rejected` on a still-parked step): submissions left for
+     * the parked check after this one, for the host's coaching copy.
+     */
+    attemptsRemaining?: number;
+    /**
+     * ISO-8601 time from which this device may verify again — set on a
+     * `rejected` result with reason `device_cooldown` (profile v2 step 4).
+     */
+    retryAfter?: string;
+}
+/**
+ * `on('busy')` payload: the model service answered
+ * `503 inference_unavailable` and the SDK waits `retryAfterSeconds` before
+ * retry number `attempt` (1-based, at most 3). Show "busy, trying again" copy.
+ */
+interface VerificationBusy {
+    attempt: number;
+    retryAfterSeconds: number;
+}
+/** Consent locale picklist (mirrors the backend HostedConsentSchema). */
+type VerificationLocale = "ar" | "fr" | "en";
+/** Options of {@link createVerification}. */
+interface VerificationOptions {
+    /** The session's client token (from `POST /api/v2/sessions` → `client_token`). */
+    clientToken: string;
+    /** API origin; default `https://api.sekyro.ai`. */
+    apiOrigin?: string;
+    /** Consent locale (echoed into the auditable consent record). */
+    locale: VerificationLocale;
+    /** Re-arm the capture on retryable reasons while attempts remain. Default `true`. */
+    autoRetry?: boolean;
+    /**
+     * How a `retry` verdict re-arms the capture (`autoRetry` on):
+     *  - `'auto'` (default) — the camera restarts immediately;
+     *  - `'manual'` — the handle settles at `done`; the host shows its coaching
+     *    and calls `retry()` on the handle when the user is ready.
+     */
+    rearm?: "auto" | "manual";
+    /** Injection seam for `fetch` (tests / non-window contexts). */
+    fetch?: typeof globalThis.fetch;
+}
+/** Event map of a {@link Verification}. */
+interface VerificationEvents {
+    /** Verdict per capture (and once when the registry settles the session early). */
+    result: VerificationResult;
+    /** Every hosted-view update the SDK observes (bootstrap, consent, submits). */
+    view: HostedSessionView;
+    /**
+     * The session waits on the identity-method choice (profile v2 step 3) and
+     * the SDK stopped before submitting anything: show the options and call
+     * {@link Verification.selectMethod}.
+     */
+    method: MethodChoiceView;
+    /**
+     * The model service is briefly unavailable and the SDK retries by itself
+     * (profile v2 step 4). A `result` follows: the verdict, or
+     * `unavailable / inference_unavailable` once the retries are spent.
+     */
+    busy: VerificationBusy;
+    /** The plan runner's current step — only after {@link Verification.run}. */
+    step: VerificationStep;
+}
+/** One session's verification, from {@link createVerification}. */
+interface Verification {
+    /** Record consent once (no-op when the session already has it). */
+    consent(): Promise<void>;
+    /**
+     * Submit `population_registry` early with an empty input when it is the
+     * pending frontier and the backend holds the NNI: the SERVER-bound one, or
+     * the one the document step read (`nniFromDocument`). Retries once on
+     * `registry_unavailable`. Never rejects — failures surface through
+     * `result`. Idempotent.
+     */
+    startRegistry(): Promise<void>;
+    /**
+     * The identity-method choice the session waits on (profile v2 step 3),
+     * bootstrapping the hosted view when needed; `null` when there is no
+     * pending choice, the bootstrap fails, or the verification was destroyed.
+     * Never rejects.
+     */
+    methodChoice(): Promise<MethodChoiceView | null>;
+    /**
+     * Send the person's identity method (`POST /hosted/method`) and continue
+     * from the returned view. Rejects with the typed `HostedApiError` (e.g.
+     * 409 `method_locked`).
+     */
+    selectMethod(method: IdentityMethod): Promise<void>;
+    /**
+     * The session's pending liveness step must be captured on a phone
+     * (`HostedStepView.requiresMobile`, profile v2 step 4 automatic decisions)
+     * and this browser is not one: show "continue on your phone" instead of
+     * starting the camera. Bootstraps the hosted view when needed; `false` when
+     * the bootstrap fails or the verification was destroyed. Never rejects.
+     * Optional so custom / older `Verification` implementations stay valid —
+     * treat an absent member as "no phone requirement".
+     */
+    mobileRequired?(): Promise<boolean>;
+    /**
+     * The session is a returning-user session (`HostedSessionView.returning`,
+     * profile v2 step 5): the person verified before and only confirms it is
+     * still them (liveness + face match against their stored photo) — show
+     * "Confirm it's you". Bootstraps the hosted view when needed; `false` when
+     * the bootstrap fails or the verification was destroyed. Never rejects.
+     * Optional so custom / older `Verification` implementations stay valid —
+     * treat an absent member as `false`.
+     */
+    returning?(): Promise<boolean>;
+    /**
+     * Start the plan runner (M5a): bootstraps the hosted view and resolves the
+     * step it waits on; every later step arrives through `on('step')`. Idempotent.
+     * Optional so custom / older `Verification` implementations stay valid —
+     * objects from `createVerification` ≥ 0.2 always have it.
+     */
+    run?(): Promise<VerificationStep>;
+    /** The step last delivered by the runner; `null` before {@link Verification.run}. */
+    currentStep?(): VerificationStep | null;
+    /** Start a liveness capture bound to this verification; the SDK uploads + submits on `captured`. */
+    liveness(options: LivenessCaptureOptions): LivenessCaptureHandle;
+    /**
+     * The session's Sekyro AI-hosted voice clips (`view.voice`), bootstrapping the
+     * hosted view when it has not been fetched yet. Resolves `null` when the
+     * session has no active clip set, the API predates the field, the bootstrap
+     * fails, or the verification was destroyed. Never rejects.
+     */
+    voiceClips(): Promise<HostedVoiceView | null>;
+    /** Subscribe; returns the unsubscribe function. */
+    on<K extends keyof VerificationEvents>(event: K, handler: (payload: VerificationEvents[K]) => void): () => void;
+    /** Destroy the active capture and drop all listeners. */
+    destroy(): void;
+}
+/** Phone OTP (profile v2 §4.1): send, then verify the 6-digit code. */
+interface PhoneOtpStepHandle extends PhoneOtpSnapshot {
+    /** ISO time from which a resend is allowed (the server's cooldown, else 30 s after this page's last send). */
+    resendAvailableAt?: string;
+    /**
+     * Send or resend. `phone` (E.164) is required unless `numberSource` is
+     * `prefilled`; a resend reuses the last one. `channel` is the person's
+     * choice: required when `channels` lists more than one (never picked for
+     * them), optional with one, and must be one of `channels` — else it rejects
+     * with `OtpInputError` (`channel`, `required` / `unavailable`).
+     */
+    send(input?: {
+        phone?: string;
+        channel?: "sms" | "whatsapp";
+    }): Promise<void>;
+    /** Check the 6-digit code; anything else rejects with `InvalidInputError` before any call. */
+    verify(code: string): Promise<void>;
+    /** With `canSwitch` (a `one_of` session): confirm the other contact instead. Rejects with `RangeError` otherwise. */
+    switchTo(): Promise<void>;
+}
+/** Email OTP (profile v2 §4.6.5): send a code to the address, then verify it. */
+interface EmailOtpStepHandle extends EmailOtpSnapshot {
+    /** Send or resend. `email` is required when `needsEmail` (checked locally: `OtpInputError("email", "format")`); a resend reuses the last one. */
+    send(input?: {
+        email?: string;
+    }): Promise<void>;
+    /** Check the 6-digit code; anything else rejects with `InvalidInputError` before any call. */
+    verify(code: string): Promise<void>;
+    /** See {@link PhoneOtpStepHandle.switchTo}. */
+    switchTo(): Promise<void>;
+}
+/** Step 1 contact choice (flow model 2026-10-23): phone or email. */
+interface ContactChoiceStepHandle extends ContactChoiceSnapshot {
+    /** Rejects with `RangeError` for a channel not in `options`. */
+    select(channel: ContactChannel): Promise<void>;
+}
+/**
+ * Step 2b summary and confirm (flow model 2026-10-23). PII: show the values,
+ * never log them or pass them to analytics.
+ */
+interface IdentitySummaryStepHandle extends IdentitySummarySnapshot {
+    /**
+     * The portrait on record as a JPEG `Blob` (fetched with the session token;
+     * show it with `URL.createObjectURL` and revoke it when done). `null` when
+     * none is available or it cannot be loaded.
+     */
+    portrait(): Promise<Blob | null>;
+    /** The details are right: the live photo comes next. */
+    confirm(): Promise<void>;
+    /** The details are wrong: the identity step opens again. Rejects with `RangeError` when `retakeAvailable` is false. */
+    retake(): Promise<void>;
+}
+/** "How do you want to verify?" (profile v2 §4.4). */
+interface MethodStepHandle extends MethodSnapshot {
+    /** Rejects with `RangeError` for a method not in `options`. */
+    select(method: IdentityMethod): Promise<void>;
+}
+/**
+ * The national eID sign-in (SDK spec §3.2; Houwiyeti in MR). Every action
+ * submits `eid_auth` and re-reads the view; a passed eID ends the session.
+ */
+interface EidStepHandle extends EidSnapshot {
+    /**
+     * `identifier` phase: ask the provider for a code. `identifier` (the NNI in
+     * MR, checked locally: 10 digits and the check digit — else
+     * `InvalidInputError("nni", …)`) is required unless
+     * `identifierBound`; on a bound session it is never sent.
+     */
+    start(identifier?: string): Promise<void>;
+    /** `code` phase: check the 6-digit code from the provider's app; anything else rejects with `InvalidInputError("code", "format")`. */
+    verify(code: string): Promise<void>;
+    /** Ask for a new code (the server spaces them out — `resendAvailableAt`). Rejects with `RangeError` when `resendsRemaining` is 0. */
+    resend(): Promise<void>;
+    /** With `canUseCamera`: switch to `cameraMethod`. Rejects with `RangeError` otherwise. */
+    useCamera(): Promise<void>;
+}
+/** The registry step (SDK spec §5.5). */
+interface RegistryStepHandle extends RegistrySnapshot {
+    /** Typed source only: checks the NNI locally (format, mod-97) before submitting. */
+    submitNni(nni: string): Promise<void>;
+    /** Bound or document source: submit with an empty input (the server holds the NNI). */
+    confirm(): Promise<void>;
+    /** After `nni_not_found` (`canUseDocument`): switch to the document photo. */
+    useDocument(): Promise<void>;
+}
+/** The document step — any issuing country (profile v2 §5.3a). */
+interface DocumentStepHandle extends DocumentSnapshot {
+    /** The picked issuer (`null` until picked; a verso keeps the recto's pick). */
+    issuer: string | null;
+    /** The picked type (`null` until picked). */
+    documentType: AcceptedDocumentType | null;
+    /** `"single"` for a passport, else the snapshot's side; `null` until a type is picked. */
+    captureSide: DocumentSide | null;
+    /** Pick (or re-pick after `document_type_not_accepted`). Throws `RangeError` when the profile does not accept `type` for `issuer`. */
+    selectDocument(issuer: string, type: AcceptedDocumentType): void;
+    /**
+     * The step's camera (rear). The SDK uploads and submits `doc_ocr` for every
+     * capture and re-arms the same stream for the other face. One handle per
+     * step: calling again with the same video returns the same handle until it
+     * is destroyed. Throws when no document was picked yet.
+     */
+    capture(options: {
+        video: HTMLVideoElement;
+        keepScreenAwake?: boolean;
+        /** Web live MRZ (on-device MRZ read on MRZ faces; obeys the session's server tuning). */
+        liveMrz?: DocumentLiveMrzOptions;
+    }): DocumentCaptureHandle;
+}
+/** The liveness / selfie step. */
+interface LivenessStepHandle extends LivenessSnapshot {
+    /** Same as {@link Verification.liveness}: the SDK uploads + submits on `captured`. */
+    capture(options: LivenessCaptureOptions): LivenessCaptureHandle;
+    /**
+     * Step 3 with `livePhoto.icao`: the ICAO coaching of the running capture
+     * (the gate fills only while `holding`; show `portrait.coach.<update.coach>`
+     * otherwise). Returns the unsubscribe; never fires without `livePhoto.icao`.
+     */
+    onLivePhoto(handler: (gate: LivePhotoGateUpdate) => void): () => void;
+}
+/** The ICAO coaching of a one-capture live photo (`LivenessStepHandle.onLivePhoto`). */
+interface LivePhotoGateUpdate {
+    /** The ICAO conditions hold: the liveness gate may fill. */
+    holding: boolean;
+    /** The last ICAO gate frame (`null` before the first). */
+    update: PortraitGateUpdate | null;
+}
+/** The ICAO portrait step (SDK spec §4.9, §5.4; ID-document sessions). */
+interface PortraitStepHandle extends PortraitSnapshot {
+    /**
+     * The last submission failed on the network (nothing was decided): in the
+     * `capture` phase offer a new take (`retry()` on the capture handle), in the
+     * `match` phase offer {@link PortraitStepHandle.resubmit}.
+     */
+    uploadFailed: boolean;
+    /** `match` phase: submit `face_match` again after `uploadFailed` (no-op otherwise). */
+    resubmit(): Promise<void>;
+    /**
+     * The step's camera (front), `capture` phase only. The SDK uploads the
+     * portrait and submits `portrait_icao` (then `face_match` with the portrait
+     * as the probe). Every attempt is billed, so after a server verdict the
+     * handle settles at `done` and the host calls `retry()` when the person is
+     * ready. One handle per step: the same video returns the same handle.
+     */
+    capture(options: {
+        video: HTMLVideoElement;
+        keepScreenAwake?: boolean;
+        assetBaseUrl?: string;
+    }): PortraitCaptureHandle;
+}
+/** The biometric step needs a phone (desktop browser). */
+interface MobileRequiredStepHandle extends MobileRequiredSnapshot {
+    /** Re-read the session (e.g. after the person finished on their phone). */
+    refresh(): Promise<void>;
+}
+/** The server is still deciding. */
+interface ProcessingStepHandle extends ProcessingSnapshot {
+    /** Re-read the session now (also after `stalled`). */
+    refresh(): Promise<void>;
+}
+/** A step this SDK cannot run (`platform_unsupported` / `update_required`). */
+type UnsupportedStepHandle = UnsupportedSnapshot;
+/** The session's outcome — display only (the SDK never decides it). */
+type ResultStepHandle = ResultSnapshot;
+/** What `on('step')` delivers: the step's data plus its actions. */
+type VerificationStep = PhoneOtpStepHandle | EmailOtpStepHandle | ContactChoiceStepHandle | IdentitySummaryStepHandle | MethodStepHandle | EidStepHandle | RegistryStepHandle | DocumentStepHandle | LivenessStepHandle | PortraitStepHandle | MobileRequiredStepHandle | ProcessingStepHandle | UnsupportedStepHandle | ResultStepHandle;
+
+/** The engine surface the handle binds — CaptureSessionV3 or a test double. */
+interface CaptureEngine {
+    readonly state: CaptureState$1;
+    on<K extends keyof CaptureSessionV3Events>(event: K, handler: (payload: CaptureSessionV3Events[K]) => void): () => void;
+    /** `facingMode` sets the camera for this attempt and later retries. */
+    start(options?: {
+        facingMode?: "user" | "environment";
+    }): Promise<void>;
+    retry(): void;
+    switchCamera(): void;
+    destroy(): void;
+    /** Device-profile chrome hint (LOW class → `'reduced'`); absent on doubles. */
+    readonly animations?: "full" | "reduced";
+}
+/** Internal construction seams (tests; Sekyro AI's own hosted page). */
+interface LivenessCaptureInternals {
+    /** Replace the engine constructor (default: `new CaptureSessionV3(options)`). */
+    createEngine?: (options: CaptureSessionV3Options) => CaptureEngine;
+    /** Extra engine options merged in (worker offload, warmed detector, telemetry). */
+    engineOptions?: Partial<Pick<CaptureSessionV3Options, "createDetector" | "createWorker" | "telemetry" | "deviceClass" | "rankKeyframes" | "measureQuality">>;
+    /** Clock (default `performance.now`). */
+    now?: () => number;
+}
+/** fcv3.* guidance key → public gate hint code. */
+declare function mapGuidanceHint(key: string): GateHint | null;
+/** Engine state → public state (`preflight|acquiring → starting`, `positioning → gating`). */
+declare function mapEngineState(state: CaptureState$1): CaptureState;
+/** Engine error kinds → the public six (`models|cliptoolarge|recorder|overconstrained → generic`). */
+declare function mapErrorKind(kind: CaptureErrorKind$1): CaptureErrorKind;
+/** Handle + the hooks the verification layer uses to drive the flow states. */
+interface LivenessCaptureInternalHandle {
+    handle: LivenessCaptureHandle;
+    /** Push a post-capture state (`uploading | checking | done`). */
+    setFlowState(state: Extract<CaptureState, "uploading" | "checking" | "done">): void;
+}
+declare function createLivenessCaptureInternal(options: LivenessCaptureOptions, internals?: LivenessCaptureInternals, 
+/** Keyframe ranking switch (SDK spec §4.8a) — createVerification reads the server tuning. */
+rankKeyframes?: () => boolean): LivenessCaptureInternalHandle;
+/**
+ * Create a standalone liveness capture (no upload — pair it with your own
+ * submission, or use {@link Verification.liveness} for the full flow).
+ */
+declare function createLivenessCapture(options: LivenessCaptureOptions): LivenessCaptureHandle;
+
+/** Preload state per asset base URL. */
+type LivenessAssetsStatus = "idle" | "loading" | "ready" | "failed";
+/** Options of {@link preloadLivenessAssets}. */
+interface PreloadLivenessAssetsOptions {
+    /** Same value as the capture's `assetBaseUrl`; default `/models-v3`. */
+    assetBaseUrl?: string;
+    /** Defer the load to browser idle time (`requestIdleCallback`, 1.2 s timeout fallback). Default `false`. */
+    idle?: boolean;
+    /** Skip when the browser asks to save data (`navigator.connection.saveData`). Default `false`. */
+    respectSaveData?: boolean;
+}
+/** Blaze init deadline for the preload — generous: a slow ~11 MB wasm download must finish. */
+declare const PRELOAD_BLAZE_INIT_TIMEOUT_MS = 120000;
+/** Outer budget reclaiming only a genuinely hung load (≥ the init deadline + slack). */
+declare const PRELOAD_BUDGET_MS = 130000;
+type Loader = (base: string) => Promise<Detector>;
+/** @internal Test seam: replace the detector loader (null restores the real one). */
+declare function setPreloadLoaderForTests(next: Loader | null): void;
+/** @internal Test seam: drop every entry (destroying warmed detectors). */
+declare function resetLivenessAssetsForTests(): void;
+/**
+ * Warm the face detector for `assetBaseUrl` so the capture starts instantly.
+ * Idempotent per base URL and never rejects: resolves the settled status.
+ * `'idle'` means nothing was preloaded here (SSR, no camera API, Data-Saver
+ * skip) — start normally. Calling again after `'failed'` retries the load.
+ * With `idle: true` the load is deferred (status stays `'idle'` until it
+ * starts); a later non-idle call — or a capture mounting meanwhile — starts it
+ * at once, and {@link releaseLivenessAssets} cancels it.
+ */
+declare function preloadLivenessAssets(options?: PreloadLivenessAssetsOptions): Promise<LivenessAssetsStatus>;
+/** Current preload status for `assetBaseUrl` (default `/models-v3`). */
+declare function getLivenessAssetsStatus(assetBaseUrl?: string): LivenessAssetsStatus;
+/**
+ * Subscribe to status changes for `assetBaseUrl`; returns the unsubscribe
+ * function. Does NOT emit the current status on subscribe (read it with
+ * {@link getLivenessAssetsStatus}) — the
+ * `useSyncExternalStore(subscribe, getSnapshot)` contract, so it plugs into
+ * that hook directly.
+ */
+declare function subscribeLivenessAssets(listener: (status: LivenessAssetsStatus) => void, assetBaseUrl?: string): () => void;
+/** Free the warmed detector (an SPA leaving the flow). Never call while a capture is mounted. */
+declare function releaseLivenessAssets(assetBaseUrl?: string): void;
+/**
+ * @internal The capture engine's detector source when a preload exists for
+ * `assetBaseUrl`: a non-owning view of the warm instance (waiting for an
+ * in-flight load), or — once that load failed — a cold detector OWNED by the
+ * session (default ladder + deadline). `undefined` when nothing was preloaded.
+ * Invoking it on an idle-scheduled preload starts that load now and joins it.
+ */
+declare function preloadedDetectorFactory(assetBaseUrl?: string): (() => Promise<Detector>) | undefined;
+
+/**
+ * Physical geometry the scanner frames (ISO/IEC 7810 / ICAO 9303). `"card"` is
+ * any identity card or residence permit of ANY issuer: ID-1 (TD1) or ID-2 (TD2)
+ * — the issuer decides the size, so the gate accepts either aspect.
+ */
+type DocFormat = "ID-1" | "ID-2" | "ID-3" | "card";
+type PhysicalFormat = Exclude<DocFormat, "card">;
+type DocSide = "recto" | "verso" | "single";
+interface DocCatalogEntry {
+    /** kyc-docs-v2 `document_type`, verbatim. */
+    docType: "carte_identite" | "passport" | "residence_permit";
+    format: DocFormat;
+    /** Capture sequence the hosted doc step walks, in order. */
+    sides: readonly DocSide[];
+    /** MRZ geometry: td1 = 3×30 (ID-1 verso), td3 = 2×44 (passport data page). */
+    mrz: "none" | "td1" | "td3";
+    /** Which side carries the holder photo (drives portrait expectations). */
+    portraitSide: DocSide;
+    /** Physical width/height ratio of the framed page. */
+    aspectRatio: number;
+    /** Where the subject identifier (NNI) is parsed from, when the doc carries one. */
+    identifierSource?: "mrz";
+}
+/**
+ * Plausibility aspect bands per physical format (Task 34 gate input): ID-1
+ * cards are 85.6×53.98mm → 1.586; ID-2 105×74mm → 1.419; an ID-3 passport DATA
+ * PAGE frames at ≈125×88mm → 1.42 (wider tolerance — page curl and hinge
+ * shadow skew the detected quad).
+ */
+declare const ASPECT_BANDS: Record<PhysicalFormat, {
+    center: number;
+    tolerance: number;
+}>;
+/** Aspect band for a format (`"card"` → the ID-1 band; use {@link aspectFits} for plausibility). */
+declare function aspectBand(format: DocFormat): {
+    center: number;
+    tolerance: number;
+};
+/** The quad aspect is plausible for the format (any of its physical bands). */
+declare function aspectFits(format: DocFormat, aspect: number): boolean;
+/** The MR docTypes facet (findings §4). Order = the hosted picker's display order. */
+declare const MR_DOC_CATALOG: readonly DocCatalogEntry[];
+/** Every document type (profile v2 §5.3a), picker order: identity card, passport, residence permit. */
+declare const DOC_CATALOG: readonly DocCatalogEntry[];
+/**
+ * Scanner format per document type for ANY issuer (profile v2 §5.3a): identity
+ * cards and residence permits are ID-1 or ID-2 (the issuer decides), passports
+ * are framed by their MRZ band (ID-3). Reads DOC_CATALOG; its entries (and
+ * MR_DOC_CATALOG, which the hosted page reads) keep `"ID-1"`.
+ */
+declare function scannerFormatFor(docType: DocCatalogEntry["docType"]): DocFormat;
+
+/** Detect-frame width the session downscales to (findings §1: 25ms median).
+ *  Lives HERE (not detector-scanic.ts) so the session can import it without
+ *  statically pulling the scanic chunk into host bundles. */
+declare const DOC_DETECT_WIDTH = 480;
+interface DocQuadPoint {
+    x: number;
+    y: number;
+}
+/** Detected document quad, image-space pixels (scanic CornerPoints shape). */
+interface DocQuad {
+    topLeft: DocQuadPoint;
+    topRight: DocQuadPoint;
+    bottomRight: DocQuadPoint;
+    bottomLeft: DocQuadPoint;
+}
+interface DocGateThresholds {
+    /** Quad area / frame area below which the doc is too far. */
+    MIN_AREA_FRAC: number;
+    /** A corner this close to (or past) a frame edge counts as clipped. */
+    EDGE_CLIP_MARGIN_PX: number;
+    /** Consecutive stable plausible+quality ticks required to fire. */
+    STABLE_TICKS: number;
+    /** Quad-bbox IoU with the previous tick at/above which the streak holds. */
+    IOU_STABLE_MIN: number;
+    /** Integrator slopes, per second — mirrors FaceGateV3's gentle drain. */
+    RISE_PER_S: number;
+    FALL_PER_S: number;
+    /** Quality guidance trigger levels (same semantics as the face gate). */
+    GUIDE_EXPOSURE: number;
+    GUIDE_SHARPNESS: number;
+    /** ID-3 (MRZ-band mode): band width / frame width floor. */
+    ID3_BAND_MIN_WIDTH_FRAC: number;
+    /** ID-3 (MRZ-band mode): band aspect (w/h) sanity bounds. */
+    ID3_BAND_ASPECT_MIN: number;
+    ID3_BAND_ASPECT_MAX: number;
+}
+/** Frozen defaults (plan Task 34 — do not retune without a golden update). */
+declare const DOC_GATE_V1_DEFAULTS: Readonly<DocGateThresholds>;
+interface DocGateQuality {
+    /** frame-quality.sharpness on the quad crop. */
+    sharpness: number;
+    /** frame-quality.exposure on the quad crop. */
+    exposure: number;
+    /** Mean crop luma — picks more_light vs too_bright. */
+    meanLuma: number;
+}
+interface DocGateTickInput {
+    timestampMs: number;
+    quad: DocQuad | null;
+    quality: DocGateQuality;
+    frameWidth: number;
+    frameHeight: number;
+}
+/** Per-tick output — the scanner chrome contract. */
+interface DocGateTick {
+    at: number;
+    quad: DocQuad | null;
+    /** Geometry passed: present × big enough × in frame × right shape. */
+    plausible: boolean;
+    /** Integrated progress 0..1 (the overlay ring). */
+    p: number;
+    /** dcv1.* message key (host translates; never prose). */
+    guidanceKey: string;
+    /** Fire signal: plausible × quality × STABLE_TICKS consecutive high-IoU ticks. */
+    ready: boolean;
+    /** Current stability streak length (diagnostics/telemetry). */
+    stableTicks: number;
+}
+/** Shoelace area of the quad as a fraction of the frame area. */
+declare function quadAreaFrac(quad: DocQuad, frameWidth: number, frameHeight: number): number;
+/** IoU of the two quads' axis-aligned bounding boxes (stability metric). */
+declare function quadIou(a: DocQuad, b: DocQuad): number;
+/** Axis-aligned bounds (width/height) of a quad — the ID-3 band-mode geometry. */
+declare function quadBounds(quad: DocQuad): {
+    width: number;
+    height: number;
+};
+declare class DocGateV1 {
+    private readonly t;
+    private readonly format;
+    private p;
+    private lastTickAt;
+    private lastQuad;
+    private streak;
+    constructor(format: DocFormat, overrides?: Partial<DocGateThresholds>);
+    reset(): void;
+    tick(input: DocGateTickInput): DocGateTick;
+    private edgeClipped;
+}
+
+type FramingStatus = "no_document" | "too_far" | "too_close" | "edge_clipped" | "wrong_shape" | "tilted" | "ok";
+type LightingStatus = "too_dark" | "too_bright" | "ok";
+type BlurStatus = "blurry" | "ok";
+type GlareStatus = "glare" | "ok";
+/** The per-frame analysis vector (every axis judged independently). */
+interface DocFrameAnalysis {
+    framing: FramingStatus;
+    lighting: LightingStatus;
+    blur: BlurStatus;
+    glare: GlareStatus;
+    /** All-clear: every axis ok — the gate's integrator/stability input. */
+    acceptable: boolean;
+}
+interface DocFrameMeasures {
+    /** frame-quality sharpness on the doc-region crop (0..1). */
+    sharpness: number;
+    /** frame-quality exposure on the doc-region crop (0..1). */
+    exposure: number;
+    /** Mean crop luma (0..255) — picks too_dark vs too_bright. */
+    meanLuma: number;
+    /** Fraction of crop pixels at/above the specular ceiling (0..1). */
+    specularFraction: number;
+}
+/** Analysis thresholds beyond the gate's — frozen defaults (round 4). */
+declare const DOC_ANALYSIS_DEFAULTS: Readonly<{
+    /** Doc area fraction above which the camera is too close (capture would crop). */
+    MAX_AREA_FRAC: 0.92;
+    /** Opposite-side length ratio beyond which the view is too oblique. */
+    TILT_MAX_SIDE_RATIO: 1.3;
+    /** Specular-pixel fraction at/above which the frame reads as glare. */
+    GLARE_MAX_SPECULAR_FRAC: 0.025;
+}>;
+/** Fraction of crop pixels with luma ≥ 252 — cheap specular-highlight measure. */
+declare function specularFraction(crop: ImageData): number;
+/** Opposite-side length ratio of the quad (1 = fronto-parallel). */
+declare function quadTiltRatio(quad: DocQuad): number;
+/**
+ * Judge one frame. `detectionMode` mirrors the gate: ID-1 quads carry
+ * area/aspect/tilt semantics; ID-3 MRZ bands carry width-fraction semantics
+ * (band rects are axis-aligned, so tilt/aspect checks are band-specific).
+ */
+declare function analyzeDocFrame(input: {
+    format: DocFormat;
+    quad: DocQuad | null;
+    frameWidth: number;
+    frameHeight: number;
+    measures: DocFrameMeasures;
+    thresholds?: Partial<DocGateThresholds>;
+}): DocFrameAnalysis;
+
+/** Feedback vocabulary (dcv2.* message keys on the hosted side). */
+type DocFeedbackKey = "sensing" | "too_far" | "too_close" | "edge_clipped" | "wrong_shape" | "tilted" | "too_dark" | "too_bright" | "blurry" | "focus_far" | "glare" | "hold_still" | "processing" | "side_captured" | "captured";
+/** Reticle rendering mode per feedback state (the stage maps to visuals). */
+type ReticleType = "searching" | "coaching" | "locking" | "processing" | "flip" | "done";
+interface DocFeedbackState {
+    key: DocFeedbackKey;
+    reticle: ReticleType;
+    /** The state holds the UI at least this long (ms) before a switch. */
+    minDurationMs: number;
+}
+declare const DOC_FEEDBACK_STATES: Readonly<Record<DocFeedbackKey, DocFeedbackState>>;
+/** Frame analysis → the feedback vote it casts (worst axis speaks). */
+declare function feedbackVoteOf(analysis: DocFrameAnalysis): DocFeedbackKey;
+/** Sliding vote window + exponential decay + per-state minimum hold. */
+declare class DocFeedbackAggregator {
+    private readonly windowMs;
+    /** Per-second decay factor — recent frames outvote stale ones. */
+    private readonly decayPerSecond;
+    private votes;
+    private current;
+    private currentSinceMs;
+    constructor(windowMs?: number, 
+    /** Per-second decay factor — recent frames outvote stale ones. */
+    decayPerSecond?: number);
+    reset(): void;
+    /** Force a terminal/choreography state (capture fired, side flip, upload). */
+    force(key: Extract<DocFeedbackKey, "processing" | "side_captured" | "captured" | "focus_far">, nowMs: number): DocFeedbackState;
+    /** Cast this frame's vote and return the (possibly held) winning state. */
+    tick(vote: DocFeedbackKey, nowMs: number): DocFeedbackState;
+}
+
+/** A rectangle in some image's pixels. */
+interface PixelRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+/** What a document still capture returns (`docRegion` in the still's pixels; null = unknown). */
+interface DocStill {
+    blob: Blob;
+    previewDataUrl: string;
+    docRegion?: PixelRect | null;
+    /** Which source produced it (telemetry / tests). */
+    source?: "photo" | "video";
+    width?: number;
+    height?: number;
+    /** Blur-gate sharpness of the document region (blur-gate.ts scale; -1 unknown). */
+    sharpness?: number;
+}
+
+/**
+ * Server-tunable document camera values (`capture.document.camera`, mirrored by
+ * identity-backend hosted-capture.ts). Coaching / capture behaviour only — the
+ * server re-checks every upload.
+ */
+interface DocCameraTuning {
+    /** Upgrade ask on the opened track (px; landscape terms). */
+    width: number;
+    height: number;
+    /** Rank back cameras and open the main wide lens by deviceId. */
+    lensSelection: boolean;
+    /** Apply `focusMode: continuous` where offered. */
+    continuousFocus: boolean;
+    /** Settle time after a single-shot refocus before the photo (ms; 0 = no refocus). */
+    refocusBeforePhotoMs: number;
+    /** Zoom never exceeds this. */
+    zoomMax: number;
+    /** Zoom when the camera reports no focus range (iOS Safari), on a large enough track. */
+    zoomNoFocusInfo: number;
+    /** Short side (px) the track needs before {@link zoomNoFocusInfo} applies. */
+    zoomMinSourcePx: number;
+    /** Distance (m) at which the document fills the guide at 1× (main wide lens). */
+    fillDistanceM: {
+        id1: number;
+        id3: number;
+    };
+    /** Extra margin over the minimum focus distance. */
+    focusMarginFrac: number;
+    /** Auto-captured still refused when its document sharpness is under this (blur-gate scale). */
+    stillSharpnessMin: number;
+    /** After this many refusals in a row the next still is kept (the server decides). */
+    stillRefusalsMax: number;
+    /** A blurry, large document (fill ≥ this of the frame) is coached "move farther". */
+    focusFarFillFrac: number;
+    /**
+     * Zoomed in (> 1×) and no document seen for this long (ms): coach "move a
+     * little farther" — a card held at the usual 1× distance overfills a 2×
+     * frame and reads as nothing (iPhone 2026-10-22: 72/74 empty frames). 0 = off.
+     */
+    noDocFarHintMs: number;
+    /** Still nothing seen for this long (ms) while zoomed: drop the zoom to 1×. 0 = never. */
+    zoomFallbackMs: number;
+}
+declare const DOC_CAMERA_TUNING_DEFAULTS: Readonly<DocCameraTuning>;
+/** Field-by-field merge of a server `capture.document.camera` block over the defaults (bad fields ignored). */
+declare function resolveDocCameraTuning(raw: unknown): DocCameraTuning;
+type LensKind = "main" | "virtual" | "ultra" | "tele" | "depth" | "front" | "unknown";
+/** What a camera label says about its lens (labels are English on Android Chrome / iOS Safari). */
+declare function lensKindOf(label: string): LensKind;
+/**
+ * Back cameras best-first: main wide lenses (lowest Android index first), then
+ * iOS virtual multi-lens devices; ultra-wide, telephoto, depth and front lenses
+ * are dropped. Empty when nothing is identifiable (keep the browser's pick).
+ */
+declare function rankBackCameras(devices: ReadonlyArray<{
+    deviceId: string;
+    label: string;
+    kind?: string;
+}>): string[];
+declare const LENS_STORAGE_KEY = "sekyro.doc.camera";
+/** The remembered document camera (per browser), or null (storage blocked / empty). */
+declare function readStoredLens(): string | null;
+declare function writeStoredLens(deviceId: string | null): void;
+interface FocusCaps {
+    focusMode?: readonly string[];
+    focusDistance?: {
+        min?: number;
+        max?: number;
+    };
+    zoom?: {
+        min?: number;
+        max?: number;
+        step?: number;
+    };
+    pointsOfInterest?: unknown;
+}
+declare const supportsFocusMode: (caps: FocusCaps | null | undefined, mode: string) => boolean;
+/**
+ * Single-shot refocus at a normalized point (0..1 of the video frame), when
+ * the camera offers single-shot focus. Chrome accepts `pointsOfInterest`
+ * without advertising it on every device, so it rides along whenever
+ * single-shot exists.
+ */
+declare function singleShotFocusAt(caps: FocusCaps | null | undefined, x: number, y: number): MediaTrackConstraintSet | null;
+/** Map a tap on an `object-fit: cover` video element to normalized video-frame coordinates. */
+declare function coverPointToVideo(clientX: number, clientY: number, rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, video: {
+    width: number;
+    height: number;
+}): {
+    x: number;
+    y: number;
+} | null;
+/**
+ * The zoom that keeps the document inside the focus range, or 1 (no change).
+ *  - focus range reported (Chrome Android, `focusDistance.min` in metres): zoom
+ *    so the fill distance clears min-focus × (1 + margin);
+ *  - no focus range (iOS Safari): {@link DocCameraTuning.zoomNoFocusInfo} on a
+ *    track whose short side is ≥ zoomMinSourcePx (pixel headroom), else 1.
+ * Always within the camera's zoom range and the tuning's zoomMax; 1 without a
+ * zoom capability.
+ */
+declare function docZoomFor(caps: FocusCaps | null | undefined, track: {
+    width: number;
+    height: number;
+}, format: DocFormat, tuning?: DocCameraTuning): number;
+interface OpenDocCameraDeps {
+    getUserMedia: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    /** (navigator.mediaDevices.enumerateDevices) — absent: keep the browser's pick. */
+    enumerateDevices?: () => Promise<ReadonlyArray<{
+        deviceId: string;
+        label: string;
+        kind?: string;
+    }>>;
+    lensSelection: boolean;
+    /** First ask (resolution). */
+    base: {
+        width: number;
+        height: number;
+    };
+}
+type LensSource = "stored" | "selected" | "default";
+/** Focus is fine when the camera offers continuous AF, or reports no focus modes at all (Safari / Firefox). */
+declare function focusOk(stream: MediaStream): boolean;
+/** At most this many ranked lenses are tried (each costs a camera reopen). */
+declare const LENS_TRY_MAX = 3;
+/**
+ * Open the back camera: the remembered lens first, else `facingMode:
+ * environment` (the permission prompt; labels appear after it), then the
+ * best-ranked main wide lens with continuous AF by deviceId. Any failure along
+ * the way keeps — or reopens — the browser's pick; only the very first
+ * getUserMedia error (permission, no camera) propagates.
+ */
+declare function openDocCamera(deps: OpenDocCameraDeps): Promise<{
+    stream: MediaStream;
+    lens: LensSource;
+}>;
+
+/** Normalized rect (0..1) of the upright frame. */
+interface GuideRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface GuideMetrics {
+    /** Mean luma inside the guide (0..255). */
+    brightness: number;
+    /** Fraction of guide samples at/above the glare luma (native measure: guide region incl. background). */
+    glare: number;
+    /**
+     * Fraction of samples at/above the glare luma INSIDE the measured card (inset
+     * 6 %) — what the web lock gates on: a bright table or floor around the card
+     * is not glare on the document. Equals {@link glare} when no card box is measured.
+     */
+    cardGlare: number;
+    /** Laplacian variance over the sampled guide grid (native scale). */
+    sharpness: number;
+    /** Detected card width / guide width (1 = fitted). */
+    fill: number;
+    /**
+     * The measured box's shape over the guide's (box w/h ÷ guide w/h; 1 = the
+     * format's aspect). A floor tile or a book in the guide reads far from 1.
+     */
+    shape: number;
+    /**
+     * Printed content inside the measured box: the fraction of interior samples
+     * on a strong luma step (≥ 24 levels to a 2-sample neighbour). A card's text,
+     * photo and guilloche read ~0.08+; an empty tile, table or hand ~0.01.
+     */
+    content: number;
+    /** Card centre offset in guide widths / heights (+ = right / down). */
+    offsetX: number;
+    offsetY: number;
+    /** Weakest side's edge strength over the mean gradient (≥ ~1.6 = a card is there). */
+    edgeConfidence: number;
+    /** The card's sides in frame pixels (for the still crop), null when unmeasured. */
+    box: {
+        left: number;
+        top: number;
+        right: number;
+        bottom: number;
+    } | null;
+}
+declare const EMPTY_GUIDE_METRICS: Readonly<GuideMetrics>;
+/**
+ * The on-screen guide in normalized coordinates of the upright frame, grown by
+ * `margin` of the guide on each side (GuideRegion.inFrame). `view` is the
+ * element showing the frame with `object-fit: cover`; `guide` is in view units.
+ */
+declare function guideRegionInFrame(view: {
+    width: number;
+    height: number;
+}, guide: GuideRect, frameAspect: number, margin?: number): GuideRect;
+/**
+ * Measure the card inside `region` of one RGBA frame (DocumentQuality.analyze,
+ * rotation 0: browser frames are already upright).
+ */
+declare function analyzeGuide(frame: ImageData, region: GuideRect, opts?: {
+    edgePeakFrac?: number;
+}): GuideMetrics;
+/** The measured card as a quad in frame pixels (axis-aligned), or null. */
+declare function guideQuad(m: GuideMetrics): DocQuad | null;
+/**
+ * Web guide-lock thresholds — server `capture.document.guide` (identity-backend
+ * hosted-capture.ts). Starts from the native `capture.document.scan` values
+ * (Mattel production) with the web calibration of 2026-10-22: the guide is the
+ * drawn card slot (no margin), so `fillMin` 0.82; glare is measured on the card
+ * only and gated at 0.025 (the web quad gate's specular ceiling) — the native
+ * 0.012 over the whole guide blocked a card back on a bright floor; steady
+ * deltas scale with the 3–6 Hz tick; the edge pick prefers the guide's side;
+ * and a card must be card-shaped and carry print (`shapeTolerance`, `contentMin`)
+ * — the nearer-edge pick otherwise reads a floor tile in the guide as a card.
+ */
+interface GuideLockTuning {
+    fillMin: number;
+    fillMax: number;
+    offsetMax: number;
+    glareMax: number;
+    /** Native-scale Laplacian variance floor (see {@link GuideMetrics.sharpness}). */
+    sharpnessMin: number;
+    edgeConfidenceMin: number;
+    darkBrightness: number;
+    lockMs: number;
+    steadyMs: number;
+    steadyFillMin: number;
+    steadyFillMax: number;
+    steadyFillDelta: number;
+    steadyOffsetDelta: number;
+    /**
+     * Report interval the steady deltas are defined for (native: 100 ms at 10 Hz).
+     * Web ticks at 3–6 Hz: the allowed deltas scale with the real interval
+     * (× dt / steadyRefMs, capped at 3×). 0 = no scaling.
+     */
+    steadyRefMs: number;
+    /**
+     * Edge pick: 0 = the band's strongest edge (native); in (0, 1) = of the peaks at
+     * least this fraction of the strongest, the one nearest the guide's side.
+     */
+    edgePeakFrac: number;
+    /** Max relative deviation of {@link GuideMetrics.shape} from 1 (0 = no check; native has none). */
+    shapeTolerance: number;
+    /** Min {@link GuideMetrics.content} for a card (0 = no check; native has none). */
+    contentMin: number;
+}
+declare const GUIDE_LOCK_DEFAULTS: Readonly<GuideLockTuning>;
+/** Field-by-field merge of a server `capture.document.scan` block over the defaults (bad fields ignored). */
+declare function resolveGuideLockTuning(raw: unknown): GuideLockTuning;
+/** Why the guide lock is not firing on this frame (telemetry + coaching). */
+type GuideBlocker = "no_card" | "too_small" | "too_big" | "off_center" | "glare" | "blurry" | "steadying" | "locking";
+interface GuideLockTick {
+    /** A card is measured in the guide (edge confidence over the floor). */
+    detected: boolean;
+    /** Fire: good for lockMs, or steady for steadyMs. */
+    ready: boolean;
+    /** "good" (fill/centre/glare/sharp) or "steady" (held still, looser fill). */
+    via: "good" | "steady" | null;
+    blocker: GuideBlocker;
+}
+/** The capture subset of the native ScanMachine (no flip / reads / torch hints). */
+declare class GuideLock {
+    private readonly t;
+    private goodSince;
+    private steadySince;
+    private last;
+    constructor(t?: GuideLockTuning);
+    reset(): void;
+    tick(m: GuideMetrics, at: number): GuideLockTick;
+}
+
+type MrzFormat = "TD1" | "TD2" | "TD3";
+type LoadFailure = "unsupported" | "download" | "integrity" | "error" | "timeout";
+/** One band read's outcome. `lineBoxes` are [x, y, w, h] normalized to the posted bitmap (the band; the whole still
+ * for a `still` read with a region). */
+interface BandResult {
+    kind: "band";
+    ms: number;
+    lineBoxes: [number, number, number, number][];
+    /** Lines the MRZ picker kept (2 or 3), 0 when none fit. */
+    lineCount: number;
+    format?: MrzFormat;
+    /** ICAO document code of a parsed MRZ (P, I, ID, IR, AC…): a fixed document-type code, not personal data. */
+    documentCode?: string;
+    /** Every HARD check digit valid. */
+    valid: boolean;
+    /** sha256("sekyro-mrz-1\0" + salt + "\0" + lines.join("\n")), 64 hex, only when valid. */
+    digest?: string;
+    /** The picked MRZ lines' box [x, y, w, h] normalized to the posted bitmap (geometry only). */
+    mrzBox?: [number, number, number, number];
+}
+/** The front-lock layout read (detector only, no recognizer): the text-line boxes of the card crop, [x, y, w, h]
+ * normalized to the posted bitmap, top to bottom. Geometry only. */
+interface LayoutResult {
+    kind: "layout";
+    ms: number;
+    lineBoxes: [number, number, number, number][];
+}
+interface ReadyInfo {
+    warmupMs: number;
+    downloadMs: number;
+    cached: boolean;
+}
+
+interface FrontLockTuning {
+    /** Lines the detector must find in the card crop to call it a card face (a printed front has 6–12). */
+    minLines: number;
+    /** Horizontal extent of the text block / crop width: below = "move closer", above = "move back". */
+    fillMin: number;
+    fillMax: number;
+    /** |text-block center − crop center| per axis, as a fraction of the crop. */
+    offsetMax: number;
+    /** Lumière steadiness deltas against the previous report. */
+    steadyFillDelta: number;
+    steadyOffsetDelta: number;
+    /** Mean shift of matched line centers between reports (fraction of the crop), and the allowed line-count change. */
+    layoutShiftMax: number;
+    lineCountDelta: number;
+    /** Lumière lockMs / steadyMs, plus a minimum number of consecutive layout reads (the sampler sets the cadence). */
+    lockMs: number;
+    steadyMs: number;
+    minFrames: number;
+}
+type FrontLockHint = "closer" | "farther" | "center" | "glare" | "blurry";
+
+/** The engine surface the assist needs (OcrEngineClient, once `ready`). */
+interface DocAssistEngine {
+    readonly busy: boolean;
+    bandRead(bitmap: ImageBitmap, detectorLimit?: number): Promise<BandResult>;
+    layoutRead(bitmap: ImageBitmap, detectorLimit: number): Promise<LayoutResult>;
+}
+/** `capture.document.frontLock` (server-delivered; the FrontLockTuning fields + the sampler's). */
+interface TextLockTuning extends FrontLockTuning {
+    minIntervalMs: number;
+    maxWidthPx: number;
+    detectorLimit: number;
+    /** Layout reads stop after this long with a card in view and no lock (the quality locks keep going). */
+    searchTimeoutMs: number;
+}
+/** `capture.document.liveMrz` — the sampler / gate subset (spec §9). */
+interface LiveMrzTuning {
+    detectorLimit: number;
+    bandMaxWidthPx: number;
+    minBandWidthPx: number;
+    bandTop: number;
+    minIntervalMs: number;
+    stableReads: number;
+    profileReads: number;
+    maxReadMs: number;
+    searchTimeoutMs: number;
+}
+declare const TEXT_LOCK_DEFAULTS: Readonly<TextLockTuning>;
+declare const LIVE_MRZ_DEFAULTS: Readonly<LiveMrzTuning>;
+/** A rect in VIDEO pixels. */
+interface VideoRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+type LiveMrzCoach = "moveCloser" | "turnSideways" | "glare" | "holdStill";
+/** `unsupported`: the camera can never show the band wide enough to read (e.g. a 720 px portrait stream). */
+type LiveMrzFallback = "timeout" | "slow" | "error" | "unsupported";
+type LiveMrzState = {
+    state: "searching";
+} | {
+    state: "reading";
+    coach?: LiveMrzCoach;
+    format?: MrzFormat;
+} | {
+    state: "valid";
+    format: MrzFormat;
+} | {
+    state: "fallback";
+    reason: LiveMrzFallback;
+};
+/** What a live-MRZ capture carries to the still confirmation and the `deviceRead` hint (text-free). */
+interface LiveMrzCapture {
+    format: MrzFormat;
+    documentCode?: string;
+    /** The salted digest of the two agreeing reads (64 hex). */
+    digest: string;
+    lineCount: number;
+    framesToValid: number;
+    msToValid: number;
+}
+interface DocAssistTickInput {
+    atMs: number;
+    video: HTMLVideoElement;
+    /** This face carries an MRZ (passport page, card back): live MRZ when enabled, else the text lock. */
+    mrzFace: boolean;
+    /** A card / page is in view this tick (a plausible quad, or the guide lock measuring one). */
+    present: boolean;
+    /** The card region (the guide slot or the card box) for the text lock. */
+    card: VideoRect | null;
+    /** The MRZ band for live MRZ. */
+    band: VideoRect | null;
+    portrait: boolean;
+    glareOk: boolean;
+    sharpOk: boolean;
+}
+interface DocAssistTick {
+    /** Capture now (the OCR path fired). */
+    ready: boolean;
+    via?: "text_lock" | "live_mrz";
+    /** Live MRZ decides this face: the host suspends its quality auto-capture. */
+    suspendQuality: boolean;
+    mode: "off" | "text_lock" | "live_mrz";
+    mrz?: LiveMrzState;
+    lock?: {
+        state: "searching" | "locking" | "locked";
+        hint?: FrontLockHint;
+    };
+}
+/** PII-free per-face report (the `live_mrz` capture report, spec §10 + D5b). */
+interface DocAssistReport {
+    capture: "recto" | "verso" | "single";
+    mode: "text_lock" | "live_mrz";
+    outcome: "valid" | "locked" | "timeout" | "slow" | "error" | "unsupported" | "off";
+    reads: number;
+    format?: MrzFormat;
+    framesToValid?: number;
+    msToValid?: number;
+    framesToLock?: number;
+    msToLock?: number;
+    readP50Ms?: number;
+    readP90Ms?: number;
+    deviceClass?: "fast" | "mid" | "slow";
+    typeMismatch?: boolean;
+}
+interface DocAssistOptions {
+    textLock: TextLockTuning | null;
+    liveMrz: LiveMrzTuning | null;
+    /** Video crop → bitmap (default createImageBitmap with resizeWidth). */
+    crop?: (video: HTMLVideoElement, r: VideoRect, resizeWidth: number) => Promise<ImageBitmap>;
+}
+declare class DocAssist {
+    private readonly o;
+    private engine;
+    private readonly crop;
+    private gen;
+    private inFlight;
+    private lastReadAt;
+    private firstSeen;
+    private reads;
+    private times;
+    private mrzGate;
+    private lockGate;
+    private mrzState;
+    private lockState;
+    private fallback;
+    private lockOff;
+    private lockError;
+    private fired;
+    private valid;
+    private faceMode;
+    private disabled;
+    constructor(o: DocAssistOptions);
+    /** The engine joins when ready (the camera never waits for it). */
+    setEngine(engine: DocAssistEngine | null): void;
+    /** The fallback card band's top (fraction of the guide), `liveMrz.bandTop`. */
+    get bandTop(): number;
+    get hasEngine(): boolean;
+    /** New face / retake / restart: every gate, clock and fallback starts over; in-flight results are dropped. */
+    reset(): void;
+    /**
+     * The OCR-fired still was refused (focus gate) or failed: read again on the next frames, but keep what this face
+     * already learnt — a fallback, the text-lock timeout, the search clock and the read profile stay.
+     */
+    rearmFace(): void;
+    /** The live-MRZ read that fired this face's capture (null for any other path). */
+    liveCapture(): LiveMrzCapture | null;
+    private modeFor;
+    tick(i: DocAssistTickInput): DocAssistTick;
+    private states;
+    private canRead;
+    private fall;
+    private liveTick;
+    private lockTick;
+    /** Stop using the engine for the session (it died, or was disposed). */
+    disable(): void;
+    /** The face's PII-free report (null when no OCR mode ran on it). */
+    report(capture: DocAssistReport["capture"], capturedVia: string | undefined, atMs: number): DocAssistReport | null;
+}
+
+/**
+ * Pre-fetch + cache the scanic chunk (call when the scan surface MOUNTS, before
+ * the camera is even granted) so the first detect tick pays no chunk-fetch
+ * latency. Fire-and-forget; failures fall back to the lazy path.
+ */
+declare function warmDocDetector(): void;
+/** Doc detect cadence per device class — scanic @480px is ~3–8× a face tick,
+ *  so the doc loop paces slower than the face profiles (findings §1: 2–5 Hz). */
+declare const DOC_CADENCE_HZ: Readonly<Record<DeviceClass, number>>;
+interface DocChecksPayload {
+    engine: "docv1";
+    /** Gate integrator 0..1 — the overlay ring. */
+    p: number;
+    plausible: boolean;
+    stableTicks: number;
+    quad: DocQuad | null;
+    /** Detect-frame size the quad coordinates live in (overlay scaling). */
+    frameWidth: number;
+    frameHeight: number;
+    /** Capture-v2 per-frame status vector (framing/lighting/blur/glare). */
+    analysis: DocFrameAnalysis;
+    /**
+     * The gate's fire signal on this tick (framed, steady, good quality); always
+     * set by this engine, optional so host-built payloads stay valid. With
+     * `autoCapture: false` the host takes the still itself ({@link CaptureSessionDoc.captureNow}).
+     */
+    ready?: boolean;
+    /** Guide-region lock on this tick — optional so host-built payloads stay valid. */
+    guide?: {
+        detected: boolean;
+        blocker: GuideBlocker;
+        fill: number;
+        shape?: number;
+        content?: number;
+        offsetX?: number;
+        offsetY?: number;
+    };
+    /** On-device OCR assist on this tick (text lock / live MRZ; enums only) — absent without an engine. */
+    ocr?: Pick<DocAssistTick, "mode" | "mrz" | "lock">;
+}
+/**
+ * How the still was taken: the guide-region lock (good card held `lockMs`, or a
+ * steady card `steadyMs`), the quad gate, or the user's manual shutter.
+ */
+type DocCaptureVia = "guide_good" | "guide_steady" | "quad" | "manual" | "text_lock" | "live_mrz";
+/** Why the manual shutter was offered. */
+type DocShutterReason = "timeout" | "detected_no_lock";
+/**
+ * Manual-shutter safety net (server `capture.document.scan`, the native scan
+ * machines' block): offered after `manualShutterMs` without a capture, or once
+ * a document has been detected (a quad, or a card in the guide) for
+ * `detectedNoLockMs` without any lock — long enough for the guide lock's
+ * steady path to win first, so it stays hidden on a normal scan.
+ */
+interface DocShutterTuning {
+    manualShutterMs: number;
+    detectedNoLockMs: number;
+}
+declare const DOC_SHUTTER_DEFAULTS: Readonly<DocShutterTuning>;
+/**
+ * Resolve the shutter tuning from a server `capture.document.scan` block:
+ * `manualShutterMs` as is; `detectedNoLockMs` = `steadyMs` + `lockMs` (a lock
+ * gets its full chance first). Bad / missing fields keep the defaults.
+ */
+declare function resolveDocShutterTuning(scan: unknown): DocShutterTuning;
+/**
+ * PII-free per-side capture report (telemetry): timings, which path took the
+ * still, and per-tick lock-failure reasons. No pixels, no text.
+ */
+interface DocCaptureReport {
+    side?: DocSide;
+    format: DocFormat;
+    deviceClass: DeviceClass;
+    /** Delivered video size (px). */
+    video: {
+        width: number;
+        height: number;
+    };
+    /** Zoom applied (1 = none). */
+    zoom: number;
+    /** ms from positioning until the zoom was dropped to 1× (nothing seen while zoomed); absent: never. */
+    zoomFallbackAtMs?: number;
+    /** ms from positioning to the still (absent: no still yet). */
+    msToCapture?: number;
+    via?: DocCaptureVia;
+    /** ms from positioning until the manual shutter was offered (absent: never). */
+    shutterAtMs?: number;
+    shutterReason?: DocShutterReason;
+    /** Detect ticks run while positioning this side. */
+    ticks: number;
+    /** Per tick: the gate's framing verdict ("ok" when framed; edge_clipped, too_far, no_document, …). */
+    quadFraming: Record<string, number>;
+    /** Per tick on framed ticks that did not lock: the quality reason (blurry, too_dark, glare, …). */
+    qualityBlockers: Record<string, number>;
+    /** Per tick: the guide lock's state (no_card, too_small, too_big, off_center, glare, blurry, steadying, locking). */
+    guideBlockers: Record<string, number>;
+    /** Focus-gate refusals of auto stills. */
+    stillRefusals: number;
+    /** The on-device OCR assist's per-face report (text lock / live MRZ), when it ran. */
+    ocr?: DocAssistReport;
+}
+/**
+ * Artifacts: `keyframe` = the full-res still of the framed side (JPEG, cropped
+ * to the document). `docRegion` = the document's bbox in the keyframe's pixels
+ * (`null`: unknown, measure the whole still; absent: a host seam that did not say).
+ */
+type DocArtifacts = CaptureArtifacts & {
+    side?: DocSide;
+    docRegion?: PixelRect | null;
+    /** The live-MRZ read that took this still (text-free: format, code, salted digest, counts) — the deviceRead hint's input. */
+    liveMrz?: LiveMrzCapture;
+};
+interface CaptureSessionDocEvents {
+    statechange: {
+        state: CaptureState$1;
+    };
+    checks: DocChecksPayload;
+    /** dcv1.* message KEY — hosts translate; never prose. Deduped. */
+    guidance: {
+        key: string;
+    };
+    /** Capture-v2 AGGREGATED feedback (time-decay voted, min-duration held) —
+     *  the stage's message + reticle channel. Deduped on state key. */
+    feedback: DocFeedbackState;
+    artifacts: DocArtifacts;
+    error: {
+        kind: CaptureErrorKind$1;
+        retryable: boolean;
+    };
+    /**
+     * Offer the manual shutter ({@link CaptureSessionDoc.captureNow}) — the safety
+     * net when the gate does not lock. `available: false` on re-arm / capture.
+     */
+    shutter: {
+        available: boolean;
+        reason?: DocShutterReason;
+    };
+}
+interface CaptureSessionDocOptions {
+    /** Host-owned <video playsInline muted>. */
+    video: HTMLVideoElement;
+    format?: DocFormat;
+    /** Side label stamped on the artifacts event (recto→verso sequencing). */
+    side?: DocSide;
+    thresholds?: Partial<DocGateThresholds>;
+    deviceClass?: DeviceClass;
+    /**
+     * Take the still when the gate is ready (default `true` — the hosted page's
+     * behaviour). `false`: `ready` is only reported on the checks payload and the
+     * host calls {@link CaptureSessionDoc.captureNow} (the Lumière scan flow).
+     */
+    autoCapture?: boolean;
+    /** (navigator.mediaDevices.getUserMedia — environment camera) */
+    getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    /** (vendored scanic detectQuad) */
+    detect?: (image: ImageData) => Promise<DocQuad | null>;
+    /** (canvas downscale of the live video to the 480px detect frame) */
+    grabDetectFrame?: (video: HTMLVideoElement, targetWidth: number) => ImageData | null;
+    /** (full-res still cropped to the quad's document → JPEG blob + preview: still-capture.ts) */
+    captureStill?: (video: HTMLVideoElement, quad: DocQuad, detectSize: {
+        width: number;
+        height: number;
+    }) => Promise<DocStill>;
+    /**
+     * Take the ImageCapture photo when the browser has one (default `true`; never
+     * on LOW devices or with the torch on). `false`: always the video frame.
+     */
+    photoCapture?: boolean;
+    /** Ask the opened track for up to 4K (default `true`; never on LOW devices). */
+    upgradeResolution?: boolean;
+    /**
+     * Server camera tuning (`capture.document.camera`, resolved with
+     * resolveDocCameraTuning): lens selection, focus, zoom and the still focus gate.
+     */
+    camera?: DocCameraTuning;
+    /**
+     * Guide-region lock thresholds (resolveGuideLockTuning over `capture.document.guide`).
+     */
+    guideLock?: GuideLockTuning;
+    /**
+     * The on-screen guide: `rect` normalized in a view of aspect `viewAspect`
+     * (width / height) showing the video with `object-fit: cover`. Default: a
+     * centered guide of the format's aspect spanning 86 % of the frame width.
+     */
+    guide?: {
+        viewAspect: number;
+        rect: GuideRect;
+    };
+    /** Manual-shutter safety net (resolveDocShutterTuning over `capture.document.scan`). */
+    shutter?: DocShutterTuning;
+    /**
+     * On-device OCR assist (web live MRZ, plan Tasks 6b + 6): the text lock on card faces and live MRZ on MRZ faces,
+     * driven by the wasm engine worker. Absent = today's flow. The host owns the engine (`ocr.setEngine` when ready).
+     */
+    ocr?: DocAssist;
+    /** (navigator.mediaDevices.enumerateDevices) — lens selection; absent in tests unless injected. */
+    enumerateDevices?: () => Promise<ReadonlyArray<{
+        deviceId: string;
+        label: string;
+        kind?: string;
+    }>>;
+    /** (performance.now) */
+    now?: () => number;
+    /** (setTimeout/clearTimeout) — the cadence pacer. */
+    setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimer?: (id: ReturnType<typeof setTimeout>) => void;
+}
+type Handler<K extends keyof CaptureSessionDocEvents> = (payload: CaptureSessionDocEvents[K]) => void;
+declare class CaptureSessionDoc {
+    private readonly opts;
+    private readonly gate;
+    private readonly cadenceMs;
+    private readonly deviceClass;
+    private torchOn;
+    private readonly camera;
+    /** Auto-capture stills refused in a row by the focus gate. */
+    private stillRefusals;
+    /** Zoom applied to the track (1 = none) — telemetry / tests. */
+    zoom: number;
+    private readonly shutterTuning;
+    /** Positioning clock for this side (tick time). */
+    private positioningSince;
+    private detectedSince;
+    /** Last tick a document was seen (a quad, or a card in the guide) — gates the manual shutter. */
+    private lastSeenAt;
+    private readonly guideLock;
+    private readonly guideTuning;
+    private lastGuideQuad;
+    /** The OCR assist fired on the last tick: its crop quad (detect frame) and path, for a host-timed captureNow. */
+    private lastOcrReady;
+    private shutterOffered;
+    private stats;
+    private readonly handlers;
+    private stream;
+    private timer;
+    private state;
+    private lastGuidance;
+    private attempt;
+    private capturing;
+    private readonly feedback;
+    private lastFeedbackKey;
+    /** Last detected quad + detect size (for a host-timed {@link captureNow}). */
+    private lastQuad;
+    private lastDetect;
+    constructor(opts: CaptureSessionDocOptions);
+    on<K extends keyof CaptureSessionDocEvents>(event: K, handler: Handler<K>): () => void;
+    private emit;
+    start(): Promise<void>;
+    /** Restart the gate for another side / a retake (same stream). */
+    rearm(side?: DocSide): void;
+    /**
+     * Take the full-resolution still now (the same best-frame window the gate
+     * uses), emitting `statechange: captured` + `artifacts`. Ignored unless the
+     * session is `positioning` and not already capturing. Without a detected
+     * card the still is still taken (manual shutter).
+     */
+    captureNow(): Promise<void>;
+    /** PII-free report of the side being (or last) positioned — telemetry. */
+    captureReport(): DocCaptureReport;
+    private ocrReport;
+    private static freshStats;
+    /** The on-screen guide moved (orientation change) — the guide lock measures the new region. */
+    setGuide(guide: {
+        viewAspect: number;
+        rect: GuideRect;
+    } | undefined): void;
+    /** The guide region in this frame (normalized), from the host's view geometry or the default. */
+    private guideRegion;
+    /** New side / retake / restart: the shutter clocks and the per-side report start over. */
+    private resetSide;
+    /** Withdraw the shutter (nothing card-like in view any more). */
+    private withdrawShutter;
+    /**
+     * Drop a zoom > 1× back to 1× (nothing seen for zoomFallbackMs while zoomed).
+     * Best-effort; the guide / quad gates re-measure at the new scale.
+     */
+    private zoomFallback;
+    private offerShutter;
+    /** The live camera exposes a torch (`MediaTrackCapabilities.torch`). */
+    torchAvailable(): boolean;
+    /** Switch the torch (manual only; errors swallowed — unsupported cameras ignore it). */
+    setTorch(on: boolean): Promise<void>;
+    destroy(): void;
+    /**
+     * Raise the opened track towards DOC_CAMERA_UPGRADE (still-geometry.ts) on the SAME
+     * camera (no lens re-pick). Best-effort: unsupported / refused constraints
+     * keep the 1080p track the stream opened with.
+     */
+    private upgradeResolution;
+    private focusCaps;
+    /** Continuous AF where offered, then the distance-strategy zoom. Each step is best-effort. */
+    private applyFocusAndZoom;
+    /**
+     * Tap-to-focus at a normalized point of the video frame (0..1). Single-shot
+     * AF there, back to continuous after ~1.5 s. No-op where the camera has no
+     * single-shot focus (iOS Safari keeps its own AF).
+     */
+    focusAt(x: number, y: number): Promise<void>;
+    private restoreContinuous;
+    /** Single-shot refocus on the document right before the photo (Chrome Android); no-op elsewhere. */
+    private refocusOn;
+    /** The live video track (null in tests / after destroy). */
+    private videoTrack;
+    /**
+     * One still: the ImageCapture photo where usable (first candidate only),
+     * else the native video frame — both cropped to the document.
+     */
+    private takeStill;
+    private detector;
+    private setState;
+    private scheduleTick;
+    private tick;
+    /**
+     * BEST-FRAME capture window (capture-v2): the first ready tick captures a
+     * candidate immediately, then up to CAPTURE_EXTRA_CANDIDATES more stills are
+     * taken at CAPTURE_CANDIDATE_SPACING_MS while the user holds — each scored
+     * by the live detect-tick sharpness at its capture moment — and the SHARPEST
+     * wins. Beats first-acceptable-frame capture without decoding stills.
+     */
+    private fire;
+    /**
+     * One OCR-assist tick (plan Tasks 6b + 6): the card region (the drawn guide slot) and the MRZ band (the passport band
+     * quad, else the guide from `bandTop`) in VIDEO pixels; glare / sharpness from this tick's guide measure (cards) or
+     * frame analysis (passports). Sets {@link lastOcrReady} when the assist fires.
+     */
+    private ocrTick;
+}
+/**
+ * The passport MRZ band to read, in video pixels, from the detect-frame stroke band (mrz-band.ts): 3 % wider and at
+ * least a fifth of its width tall, centred on it (a TD3 MRZ with margins is ≈ width / 6).
+ */
+declare function passportBandOf(b: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, sx: number, sy: number, vw: number, vh: number): VideoRect;
+/** Best-frame window: 2 extra candidates, 260ms apart, ≥8% sharper to replace. */
+declare const CAPTURE_EXTRA_CANDIDATES = 2;
+declare const CAPTURE_CANDIDATE_SPACING_MS = 260;
+
+interface EncodedDocument {
+    blob: Blob;
+    width: number;
+    height: number;
+}
+declare function encodeDocumentImage(still: Blob): Promise<EncodedDocument>;
+
+type ScanLayout = "twoSided" | "singlePage";
+type ScanSide = "recto" | "verso";
+type ScanPhase = "framing" | "locking" | "capturing" | "flipCue" | "reaskRecto" | "reading" | "result";
+/** `blurry`: the photo was refused before any upload (blur gate). */
+type ScanNotice = "same_face" | "reread" | "technical" | "blurry";
+interface ScanReport {
+    /** A plausible card / passport band is in view. */
+    present: boolean;
+    /** The gate's fire signal (quality + stability). */
+    ready: boolean;
+    /** Gate progress is high: show "hold still". */
+    locking: boolean;
+    /** Card area / detect-frame area. */
+    areaFrac: number;
+}
+interface ScanState {
+    layout: ScanLayout;
+    phase: ScanPhase;
+    captured: {
+        recto?: string;
+        verso?: string;
+    };
+    pending: string[];
+    lastShot?: string;
+    current?: ScanSide;
+    goodSince?: number;
+    lastCaptureAt: number;
+    lastReportAt: number;
+    manualShutter: boolean;
+    notice?: ScanNotice;
+    restPhase: "framing" | "flipCue" | "reaskRecto";
+    readSides: ScanSide[];
+    needFlip: boolean;
+    flipped: boolean;
+    flipTimeoutSpent: boolean;
+    timeoutCapture: boolean;
+    lastShotByTimeout: boolean;
+    awaySince?: number;
+    /** Area of the card when the last photo was taken (flip = shrinks below FLIP_FILL_MIN of it). */
+    captureArea?: number;
+    lastArea?: number;
+}
+type ScanEvent = {
+    type: "report";
+    report: ScanReport;
+    at: number;
+} | {
+    type: "tick";
+    at: number;
+} | {
+    type: "captured";
+    id: string;
+    at: number;
+} | {
+    type: "captureFailed";
+    at: number;
+} | {
+    type: "classified";
+    id: string;
+    side: ScanSide;
+} | {
+    type: "duplicate";
+    id: string;
+    side: ScanSide;
+} | {
+    type: "readOk";
+    side: ScanSide;
+} | {
+    type: "readFailed";
+    side: ScanSide;
+    id?: string;
+    issue: ScanNotice;
+} | {
+    type: "retake";
+} | {
+    type: "clockRestart";
+};
+/** Lumière values (tuned on the Mattel reference device; retune with the cores). */
+declare const FLIP_GAP_MS = 250;
+declare const FLIP_FILL_MIN = 0.6;
+declare const FLIP_TIMEOUT_MS = 1800;
+declare const MANUAL_SHUTTER_MS = 6000;
+declare const NO_REPORT_MS = 2000;
+/**
+ * Blur gate (Mattel 8f13198; server name `capture.document.scan.blurRefuseSharpnessMax`):
+ * a photo measuring under this inverse-edge-width sharpness is retaken at once.
+ * Real card photos measure ~0.42, dim/rough captures that still read 0.29 and up.
+ */
+declare const BLUR_REFUSE_SHARPNESS_MAX = 0.16;
+declare function initialScanState(layout: ScanLayout, at: number): ScanState;
+declare function nextScanState(state: ScanState, event: ScanEvent): ScanState;
+
+interface DeviceReadHint {
+    engine: string;
+    source: "live_mrz";
+    format: "TD1" | "TD2" | "TD3";
+    lineCount: number;
+    checkDigitsValid: true;
+    stillConfirmed?: boolean;
+    /** The MRZ band [x, y, w, h] normalized to the UPLOADED image (the still as encoded: same frame, any scale). */
+    band: [number, number, number, number];
+    digest: string;
+    framesToValid: number;
+    msToValid: number;
+}
+interface StillReader {
+    stillRead(bitmap: ImageBitmap, region: [number, number, number, number], detectorLimit?: number): Promise<BandResult>;
+}
+/**
+ * Read the still (the keyframe that is uploaded) and build the hint. `null` when the still read finds no MRZ band (the
+ * band is the hint's only use to the server) or fails. `region` = the part of the still to read (default: the whole).
+ */
+declare function buildDeviceReadHint(reader: StillReader, still: Blob, live: LiveMrzCapture, o: {
+    engine: string;
+    detectorLimit?: number;
+    decode?: (b: Blob) => Promise<ImageBitmap>;
+    retryMs?: number;
+    region?: [number, number, number, number];
+}): Promise<DeviceReadHint | null>;
+/** A hint promise read at POST time: the value if it already settled, else nothing (the POST never waits). */
+declare function settledHint(p: Promise<DeviceReadHint | null> | null): () => DeviceReadHint | null;
+
+interface OcrWorkerLike {
+    postMessage(data: unknown, transfer?: Transferable[]): void;
+    addEventListener(type: "message" | "error" | "messageerror", listener: (event: {
+        data?: unknown;
+    }) => void): void;
+    terminate(): void;
+}
+interface OcrEngineOptions {
+    baseUrl: string;
+    salt: string;
+    /** `readTimeoutMs` (default 10 s): a read with no answer means the worker died; the engine is disposed. */
+    tuning: {
+        detectorLimit: number;
+        maxDownloadMs: number;
+        loadTimeoutMs: number;
+        readTimeoutMs?: number;
+    };
+    /**
+     * Where the `@sekyro/web/core/ocr/worker` dist entry is served. Required (or `createWorker`): the host resolves it
+     * the way its bundler emits workers, as for the v3 detect worker; without either, `ready` is `unsupported`.
+     */
+    workerUrl?: string | URL;
+    /** Host- or test-built worker (e.g. `() => new Worker(new URL("@sekyro/web/core/ocr/worker", import.meta.url), { type: "module" })`). */
+    createWorker?: () => OcrWorkerLike;
+    /** Window to listen for `pagehide` on (default globalThis when it has addEventListener). */
+    page?: {
+        addEventListener(type: "pagehide", l: () => void, o?: {
+            once: boolean;
+        }): void;
+    } | null;
+}
+interface OcrEngineClient {
+    /** Resolves with the warm-up info, or a LoadFailure (never rejects). */
+    readonly ready: Promise<ReadyInfo | LoadFailure>;
+    bandRead(bitmap: ImageBitmap, detectorLimit?: number): Promise<BandResult>;
+    stillRead(bitmap: ImageBitmap, region: [number, number, number, number], detectorLimit?: number): Promise<BandResult>;
+    /** Front lock: the detector alone on a card crop (no recognizer); line boxes only. */
+    layoutRead(bitmap: ImageBitmap, detectorLimit: number): Promise<LayoutResult>;
+    readonly busy: boolean;
+    dispose(): void;
+}
+
+/** The engine surface the flow drives (CaptureSessionDoc in production). */
+type DocEngineLike = Pick<CaptureSessionDoc, "on" | "start" | "rearm" | "destroy" | "captureNow" | "setTorch" | "torchAvailable"> & Partial<Pick<CaptureSessionDoc, "focusAt" | "captureReport" | "setGuide">>;
+/**
+ * Web live MRZ for a session-bound capture (the step runner): the view's `capture.document` (the server-resolved
+ * `liveMrz` / `frontLock` blocks), the digest salt (the session id), the asset base, the report sink. Absent = off.
+ */
+interface DocumentWebOcr {
+    captureDocument: unknown;
+    salt: string;
+    baseUrl: string;
+    /** Fire-and-forget `live_mrz` reports (`POST /hosted/capture-reports`). */
+    reports?: (reports: readonly object[]) => void;
+    /** Test seam / host-built worker. */
+    createWorker?: () => OcrWorkerLike;
+}
+/** Seams (tests, the e2e harness, the step runner, Sekyro AI's hosted page) — `@sekyro/web/internal`. */
+interface DocumentCaptureInternals {
+    createEngine?: (options: CaptureSessionDocOptions) => DocEngineLike | Promise<DocEngineLike>;
+    engineOptions?: Partial<Omit<CaptureSessionDocOptions, "video" | "format" | "side" | "autoCapture">>;
+    encode?: (still: Blob) => Promise<EncodedDocument>;
+    /** Face of a card still (default: MRZ band on a 480 px copy). */
+    classify?: (still: Blob) => Promise<ScanSide>;
+    /**
+     * Photo sharpness for the blur gate (default: blur-gate.ts on the card region
+     * of the decoded still — the last gate quad, padded — at ≤ 1000 px; `-1` =
+     * unknown, never refused). `gate` is the last `checks` geometry.
+     */
+    measureSharpness?: (still: Blob, gate: LastGate | null) => Promise<number>;
+    /** Decode a still once per shot (default `createImageBitmap`). */
+    decode?: (still: Blob) => Promise<ImageBitmap>;
+    /** Blur-gate threshold (server name `capture.document.scan.blurRefuseSharpnessMax`); `0` disables it. Default 0.16. */
+    blurRefuseSharpnessMax?: number;
+    /** The step runner settles each face from the server verdict (`settle`); standalone captures settle at once. */
+    deferRead?: boolean;
+    now?: () => number;
+    /** Manual-shutter tick period (default 500 ms; 0 = no timer, tests). */
+    tickMs?: number;
+    /** Web live MRZ (plan Task 6): session-bound OCR (the step runner passes the view). */
+    webOcr?: DocumentWebOcr;
+    /**
+     * One engine report per document face, whether or not web OCR is on: `captured` when the face is
+     * delivered, `abandoned` when the capture is destroyed mid-face after the engine ticked. A throwing
+     * callback never reaches the capture.
+     */
+    onFaceReport?: (report: DocCaptureReport, outcome: "captured" | "abandoned") => void;
+}
+/** What {@link createDocumentCaptureInternal} returns: the public handle plus the runner's hooks. */
+interface DocumentCaptureController {
+    handle: DocumentCaptureHandle;
+    /** Upload / check progress of the current face (the step runner). */
+    setFlowState(state: "uploading" | "checking" | "done"): void;
+    /** Server verdict for a face (deferred reads only). */
+    settle(side: DocumentSide, verdict: {
+        ok: true;
+    } | {
+        ok: false;
+        issue: ScanNotice;
+    }): void;
+    /**
+     * The last live-MRZ capture's `deviceRead` hint if it is ready NOW (the doc_ocr POST never waits); null otherwise.
+     * Take it once per submission so a same-key replay sends the identical body.
+     */
+    takeDeviceRead(doc: CapturedDocument): DeviceReadHint | null;
+}
+/** After this many same-face drops in a row, the photo is kept (labelled as expected) and the server decides. */
+declare const SAME_FACE_MAX_DROPS = 2;
+/** The last gate geometry: the quad in detect-frame coordinates and that frame's size. */
+interface LastGate {
+    quad: DocumentQuad;
+    frameWidth: number;
+    frameHeight: number;
+    /** The quad is the engine's `docRegion`, already in the (cropped) still's pixels. */
+    inStill?: boolean;
+}
+/** {@link createDocumentCapture} with seams and the step runner's hooks. */
+declare function createDocumentCaptureInternal(options: DocumentCaptureOptions, internals: DocumentCaptureInternals): DocumentCaptureController;
+
+declare const LANDMARKER_MODEL = "face_landmarker.task";
+interface LandmarkedFace {
+    /** 478 normalised (0..1) landmarks. */
+    landmarks: Point[];
+    blendshapes: Record<string, number> | null;
+    /** 4×4 facial transformation matrix, column-major. */
+    matrix: number[] | null;
+}
+interface LandmarkerLike {
+    /** Detect on a frame; `timestampMs` must increase. Never throws (returns no face). */
+    detect(source: CanvasImageSource, timestampMs: number): LandmarkedFace[];
+    close(): void;
+}
+interface TasksVisionResult {
+    faceLandmarks?: Array<Array<{
+        x: number;
+        y: number;
+    }>>;
+    faceBlendshapes?: Array<{
+        categories: Array<{
+            categoryName: string;
+            score: number;
+        }>;
+    }>;
+    facialTransformationMatrixes?: Array<{
+        data: number[];
+    }>;
+}
+/** Map a tasks-vision result to plain faces (exported for tests). */
+declare function facesOf(result: TasksVisionResult): LandmarkedFace[];
+declare function createFaceLandmarker(assetBaseUrl: string): Promise<LandmarkerLike>;
+
+interface SegmenterLike {
+    /** Person confidence of a frame; `timestampMs` must increase. Never throws (`null` = no mask). */
+    segment(source: CanvasImageSource, timestampMs: number): PersonMask | null;
+    close(): void;
+}
+
+/** Long edge of the analysis frame the landmarker and the pixel heuristics run on. */
+declare const ANALYSIS_LONG_EDGE = 640;
+declare const PORTRAIT_JPEG_QUALITY = 0.92;
+/** A drawn frame: the pixels the gate measures and a source the landmarker reads. */
+interface GrabbedFrame {
+    source: CanvasImageSource;
+    width: number;
+    height: number;
+    /** RGBA pixels (`null` when the canvas cannot be read — heuristics are skipped). */
+    pixels: {
+        data: Uint8ClampedArray;
+        width: number;
+        height: number;
+    } | null;
+}
+/** Construction seams (tests / Sekyro AI's hosted page). */
+interface PortraitCaptureInternals {
+    createLandmarker?: (assetBaseUrl: string) => Promise<LandmarkerLike>;
+    /** The background-uniformity check's selfie segmenter (default: MediaPipe, lazy). */
+    createSegmenter?: (assetBaseUrl: string) => Promise<SegmenterLike>;
+    getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    /** Draw the video scaled to `longEdge` (analysis) or at full size (`null`). */
+    grabFrame?: (video: HTMLVideoElement, longEdge: number | null) => GrabbedFrame | null;
+    /** Cut `region` out of a full-size frame, scale to `outHeight`, encode JPEG. */
+    encodeRegion?: (frame: GrabbedFrame, region: Box, outHeight: number, quality: number) => Promise<Blob>;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (id: unknown) => void;
+}
+/** Handle + the hooks the plan runner uses to drive the post-capture states. */
+interface PortraitCaptureController {
+    handle: PortraitCaptureHandle;
+    setFlowState(state: Extract<PortraitCaptureState, "uploading" | "checking" | "done">): void;
+}
+/** The observation of one landmarked frame. `scale` maps analysis px → source px. */
+declare function observe(faces: readonly LandmarkedFace[], frame: GrabbedFrame, sourceWidth: number, sourceHeight: number): IcaoFrameObservation;
+declare function createPortraitCaptureInternal(options: PortraitCaptureOptions, internals?: PortraitCaptureInternals): PortraitCaptureController;
+
+/**
+ * The client surface the flow needs — `HostedClient` or a test fake. D8: the
+ * live-camera capture proof methods are optional (a fake / an older bridge
+ * without them presigns without a proof).
+ */
+type HostedClientLike = Pick<HostedClient, "getSession" | "recordConsent" | "selectMethod" | "presign" | "uploadToSpaces" | "completeMedia" | "submitCheck"> & Partial<Pick<HostedClient, "presignCapture" | "armCapture">> & Partial<Pick<HostedClient, "selectContact" | "confirmIdentity" | "identityPortrait">>;
+/** The presign policy allowlist for `kind: 'clip'` (media.policy.ts mirror). */
+declare const CLIP_MIME_ALLOWLIST: readonly string[];
+/** Same-key transport replays AFTER the first try, and the pause between them. */
+declare const TRANSPORT_REPLAY_ATTEMPTS = 2;
+declare const TRANSPORT_REPLAY_DELAY_MS = 1000;
+/**
+ * `503 inference_unavailable` (profile v2 step 4 — request-level: no state
+ * change, no attempt used, not billed): retries after `retryAfterSeconds`
+ * (default {@link INFERENCE_RETRY_DEFAULT_S}, capped at 30 s), at most
+ * {@link INFERENCE_RETRY_ATTEMPTS} times, each under a FRESH key (each retry
+ * is its own logical attempt; the backend never caches a 5xx envelope).
+ */
+declare const INFERENCE_RETRY_ATTEMPTS = 3;
+declare const INFERENCE_RETRY_DEFAULT_S = 10;
+/** A Turnstile challenge failed client-side (load / render / error-callback / timeout). */
+declare class AttestationError extends Error {
+    constructor(message: string);
+}
+/** One logical submission: receives the client and ITS idempotency key. */
+type SubmitExecutor = (client: HostedClientLike, idempotencyKey: string) => Promise<SessionView>;
+interface SubmitRuntime {
+    client: HostedClientLike;
+    /** Force-record consent (the server just said it is missing). */
+    ensureConsent(opts: {
+        force: true;
+    }): Promise<void>;
+    sleep(ms: number): Promise<void>;
+    uuid(): string;
+    /** An `inference_unavailable` retry is about to wait (the `busy` event). */
+    onBusy?(info: VerificationBusy): void;
+}
+/**
+ * Run one logical submission (ported use-submit semantics):
+ *  - a fresh `crypto.randomUUID()` key per logical submission;
+ *  - a transport-class failure replays the SAME executor under the SAME key
+ *    (bounded) — the backend's IdempotencyInterceptor returns the first
+ *    response instead of burning another attempt;
+ *  - ONE `consent_required` recovery: force-record consent and re-run under a
+ *    FRESH key (the 409 envelope is idempotency-cached under the old one);
+ *  - ONE attestation retry (client-side Turnstile failure or a server
+ *    `attestation_invalid`): `onAttestationInvalid` drops the cached token and
+ *    the executor re-runs under a fresh key;
+ *  - up to {@link INFERENCE_RETRY_ATTEMPTS} `inference_unavailable` retries
+ *    after `retryAfterSeconds`, each under a FRESH key and with a fresh
+ *    attestation (`onAttestationInvalid` — the Turnstile token was spent).
+ * Throws the final error otherwise.
+ */
+declare function runSubmission(rt: SubmitRuntime, executor: SubmitExecutor, hooks?: {
+    onAttestationInvalid?: () => void;
+}): Promise<SessionView>;
+interface LivenessFlowDeps extends SubmitRuntime {
+    artifacts: CapturedArtifacts;
+    /** Fresh attestation per call (Turnstile execute, or `{sandbox: true}`). */
+    getAttestation(): Promise<AttestationInput>;
+    /** Latest hosted view (frontier decisions). */
+    getView(): HostedSessionView;
+    /** Re-GET the view from the server (after a RESYNC code) and fold it in. */
+    refreshView(): Promise<HostedSessionView>;
+    /** Fold a submit response into the view. */
+    applySubmit(view: SessionView, submitted: CheckType): void;
+    /** Flow-state hook for the capture handle. */
+    onPhase(phase: "uploading" | "checking"): void;
+    /** The verification was destroyed (the only thing that cancels a chain). */
+    isCancelled(): boolean;
+    /**
+     * The keyframe (face_match probe) was promoted — the plan runner keeps the
+     * key for the profile v2 §4.4 wrong-number re-entry (face_match resubmitted
+     * with the same image). Optional; observation only.
+     */
+    onKeyframePromoted?(key: string): void;
+}
+type LivenessFlowOutcome = {
+    kind: "settled";
+} | {
+    kind: "resync";
+} | {
+    kind: "unavailable";
+    reason: SdkFailureReason | "mobile_required";
+} | {
+    kind: "cancelled";
+};
+/**
+ * Run the biometric submissions the CURRENT frontier allows, re-evaluating
+ * after every submit and after every RESYNC re-GET:
+ *  - frontier `liveness` → clip upload + attestation + `liveness` (once per capture);
+ *  - frontier `face_match` → keyframe upload + `face_match` (once per capture),
+ *    allowed when liveness was NOT part of this capture (it had already
+ *    settled — any state, incl. `failed`: the selfie-fallback case, where this
+ *    capture only feeds face_match) or settled chainable from this capture
+ *    (passed / review / processing / skipped — or absent);
+ *  - anything else (terminal view, a non-biometric frontier, a check this
+ *    capture already submitted) → `settled` for the caller to map the view.
+ * A RESYNC code re-GETs the view and re-enters (at most {@link RESYNC_REENTRY_MAX}
+ * times); the final RESYNC surfaces as `resync` for the caller to map.
+ */
+declare function runLivenessFlow(deps: LivenessFlowDeps): Promise<LivenessFlowOutcome>;
+
+/** The monitor never runs the landmarker faster than this (it shares the main thread with the liveness detector). */
+declare const LIVE_PHOTO_MAX_HZ = 6;
+/** No liveness gate tick for this long → the attempt ended: the monitor sleeps. */
+declare const LIVE_PHOTO_IDLE_MS = 1500;
+/** The still of one live-photo capture. */
+interface LivePhotoStill {
+    image: Blob;
+    width: number;
+    height: number;
+    /** The ICAO gate at the moment the capture fired (the `gate` block of portrait_icao). */
+    gate: ReturnType<IcaoGate["summary"]>;
+}
+interface LivePhotoKitOptions {
+    /** The capture's video (default: the one the liveness engine measures). */
+    video?: HTMLVideoElement;
+    /** `capture.icao` of the view (coaching limits), and `capture.tuningVersion`. */
+    tuning: IcaoCaptureTuning | null;
+    tuningVersion: string | null;
+    /** The session's ICAO policy (`icaoPolicyOf(view).policy`): `alert` never holds the clip past `alertGraceMs`. Default `reject`. */
+    policy?: "reject" | "alert";
+    still: {
+        minLongSidePx: number;
+        jpegQuality: number;
+    };
+    /** Detector assets base (the landmarker sits next to the liveness wasm); default `/models-v3`. */
+    assetBaseUrl?: string;
+}
+/** Test seams. */
+interface LivePhotoKitInternals {
+    createLandmarker?: (assetBaseUrl: string) => Promise<LandmarkerLike>;
+    /** The background-uniformity check's segmenter (default: MediaPipe selfie segmenter, lazy). */
+    createSegmenter?: (assetBaseUrl: string) => Promise<SegmenterLike>;
+    grabFrame?: (video: HTMLVideoElement, longEdge: number | null) => GrabbedFrame | null;
+    /** Encode the full frame as JPEG (unmirrored). */
+    encode?: (frame: GrabbedFrame, quality: number) => Promise<Blob>;
+    /** The engine's default face-crop quality (canvas). */
+    quality?: (video: HTMLVideoElement, box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }) => V3GateQuality;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (id: unknown) => void;
+}
+/** ICAO coaching while the liveness gate waits (the `portrait.coach.<coach>` copy). */
+interface LivePhotoGate {
+    /** The ICAO conditions hold: the liveness gate may fill. */
+    holding: boolean;
+    update: IcaoGateUpdate | null;
+}
+interface LivePhotoKit {
+    /** Seams for the liveness engine (`LivenessCaptureInternals.engineOptions`). */
+    engineOptions: {
+        measureQuality: (video: HTMLVideoElement, box: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        }) => V3GateQuality;
+        telemetry: (event: V3TelemetryEvent) => void;
+    };
+    /** The client with `input.portraitIcao` added to the liveness submission. */
+    decorate<C extends HostedClientLike>(client: C): C;
+    /** ICAO coaching updates (while the liveness gate is live). */
+    onGate(handler: (gate: LivePhotoGate) => void): () => void;
+    /** The portrait_icao body of the last liveness submission (outage fallback: submit it directly). */
+    lastPortraitInput(): PortraitIcaoInput | null;
+    destroy(): void;
+}
+declare function createLivePhotoKit(options: LivePhotoKitOptions, internals?: LivePhotoKitInternals): LivePhotoKit;
+
+/** Production API origin — the `apiOrigin` default. */
+declare const DEFAULT_API_ORIGIN = "https://api.sekyro.ai";
+/** Pause before the single `registry_unavailable` re-submit. */
+declare const REGISTRY_RETRY_DELAY_MS = 5000;
+/** Bounded poll while a biometric verdict is still `processing` after the submits. */
+declare const PROCESSING_POLL_DELAY_MS = 1500;
+declare const PROCESSING_POLL_MAX = 10;
+/**
+ * Construction seams — tests and Sekyro AI's own hosted page (`@sekyro/web/internal`).
+ * Not part of the partner contract.
+ */
+interface VerificationInternals {
+    /** Replace the HTTP client (default: `new HostedClient({...})`). */
+    client?: HostedClientLike;
+    /**
+     * Replace the Turnstile challenge (default: `executeTurnstile`, loaded on first use). The
+     * `signal` aborts when the verification is destroyed (M1).
+     */
+    getTurnstileToken?: (siteKey: string, opts: {
+        signal: AbortSignal;
+    }) => Promise<string>;
+    /** Capture-engine seams forwarded to {@link createLivenessCaptureInternal}. */
+    capture?: LivenessCaptureInternals;
+    sleep?: (ms: number) => Promise<void>;
+    uuid?: () => string;
+    /** Wall clock for the plan runner (OTP resend time); default `Date.now`. */
+    now?: () => number;
+    /** DocumentCapture seams for the runner's document step (engine, encode, classify, blur gate). */
+    document?: DocumentCaptureInternals;
+    /** PortraitCapture seams for the runner's ICAO portrait step (landmarker, camera, encode). */
+    portrait?: PortraitCaptureInternals;
+    /** Live-photo kit seams for the runner's one-capture Step 3 (landmarker, frames, encode). */
+    livePhoto?: LivePhotoKitInternals;
+}
+/** `crypto.randomUUID()` with a v4 fallback for hosts that lack it. */
+declare function randomUuid(): string;
+/**
+ * Create a verification bound to one session (spec §3.1):
+ * `consent()` → `startRegistry()` → `liveness({video})` → `on('result')`.
+ */
+declare function createVerification(options: VerificationOptions): Verification;
+/** {@link createVerification} with construction seams (tests / Sekyro AI-internal hosts). */
+declare function createVerificationInternal(options: VerificationOptions, internals: VerificationInternals): Verification;
+
+export { type LivenessStartOptions as $, type AcceptedDocumentsLike as A, type DocumentReticle as B, type CameraFacing as C, type DocumentCaptureOptions as D, type DocumentScanPhase as E, type DocumentScanUpdate as F, type DocumentSide as G, type DocumentSnapshot as H, type DocumentStepHandle as I, type EidSnapshot as J, type EidStepHandle as K, type EmailOtpSnapshot as L, type EmailOtpStepHandle as M, type EmailSource as N, type GateHint as O, type PortraitCaptureOptions as P, type GateUpdate as Q, ISSUER_CODES as R, type IdentitySummarySnapshot as S, type IdentitySummaryStepHandle as T, type LivePhotoGateUpdate as U, type LivePhotoPlan as V, type LivenessAssetsStatus as W, type LivenessCaptureEvents as X, type LivenessCaptureHandle as Y, type LivenessCaptureOptions as Z, type LivenessSnapshot as _, type DocumentCaptureHandle as a, ANALYSIS_LONG_EDGE as a$, type LivenessStepHandle as a0, type MethodSnapshot as a1, type MethodStepHandle as a2, type MobileRequiredSnapshot as a3, type MobileRequiredStepHandle as a4, type OtpChannel as a5, type OtpNumberSource as a6, PLATFORM_UNSUPPORTED as a7, type PhoneOtpSnapshot as a8, type PhoneOtpStepHandle as a9, type VerificationOptions as aA, type VerificationResult as aB, type VerificationStatus as aC, type VerificationStep as aD, WEB_IDENTITY_METHODS as aE, acceptedIssuers as aF, acceptedTypesFor as aG, createLivenessCapture as aH, createVerification as aI, deriveStep as aJ, flagOf as aK, getLivenessAssetsStatus as aL, preloadLivenessAssets as aM, releaseLivenessAssets as aN, resolveAcceptedDocuments as aO, sectionOf as aP, subscribeLivenessAssets as aQ, type DocCatalogEntry as aR, type LiveMrzTuning as aS, type TextLockTuning as aT, type OcrEngineClient as aU, type DocAssistReport as aV, type ReadyInfo as aW, type LoadFailure as aX, type OcrEngineOptions as aY, type SubmitRuntime as aZ, type HostedClientLike as a_, type PortraitCaptureEvents as aa, type PortraitCaptureState as ab, type PortraitGateUpdate as ac, type PortraitSnapshot as ad, type PortraitStepHandle as ae, type PreloadLivenessAssetsOptions as af, type ProcessingSnapshot as ag, type ProcessingStepHandle as ah, type ReasonCode as ai, type RegistrySnapshot as aj, type RegistrySource as ak, type RegistryStepHandle as al, type ResultDisplay as am, type ResultSnapshot as an, type ResultStepHandle as ao, type SdkFailureReason as ap, type StepAttempts as aq, type StepContext as ar, type StepSnapshot as as, type UnsupportedReason as at, type UnsupportedSnapshot as au, type UnsupportedStepHandle as av, type Verification as aw, type VerificationBusy as ax, type VerificationEvents as ay, type VerificationLocale as az, type PortraitCaptureHandle as b, INFERENCE_RETRY_ATTEMPTS as b$, ASPECT_BANDS as b0, AttestationError as b1, BLUR_REFUSE_SHARPNESS_MAX as b2, type BlurStatus as b3, CAPTURE_CANDIDATE_SPACING_MS as b4, CAPTURE_EXTRA_CANDIDATES as b5, CLIP_MIME_ALLOWLIST as b6, type CaptureEngine as b7, CaptureSessionDoc as b8, type CaptureSessionDocEvents as b9, type DocGateThresholds as bA, type DocGateTick as bB, type DocGateTickInput as bC, DocGateV1 as bD, type DocQuad as bE, type DocQuadPoint as bF, type DocShutterReason as bG, type DocShutterTuning as bH, type DocSide as bI, type DocumentCaptureController as bJ, type DocumentCaptureInternals as bK, EMPTY_GUIDE_METRICS as bL, type EncodedDocument as bM, FLIP_FILL_MIN as bN, FLIP_GAP_MS as bO, FLIP_TIMEOUT_MS as bP, type FocusCaps as bQ, type FramingStatus as bR, GUIDE_LOCK_DEFAULTS as bS, type GlareStatus as bT, type GrabbedFrame as bU, type GuideBlocker as bV, GuideLock as bW, type GuideLockTick as bX, type GuideLockTuning as bY, type GuideMetrics as bZ, type GuideRect as b_, type CaptureSessionDocOptions as ba, DOC_ANALYSIS_DEFAULTS as bb, DOC_CADENCE_HZ as bc, DOC_CAMERA_TUNING_DEFAULTS as bd, DOC_CATALOG as be, DOC_DETECT_WIDTH as bf, DOC_FEEDBACK_STATES as bg, DOC_GATE_V1_DEFAULTS as bh, DOC_SHUTTER_DEFAULTS as bi, type DeviceReadHint as bj, type DocArtifacts as bk, DocAssist as bl, type DocAssistEngine as bm, type DocAssistTick as bn, type DocCameraTuning as bo, type DocCaptureReport as bp, type DocCaptureVia as bq, type DocChecksPayload as br, type DocEngineLike as bs, DocFeedbackAggregator as bt, type DocFeedbackKey as bu, type DocFeedbackState as bv, type DocFormat as bw, type DocFrameAnalysis as bx, type DocFrameMeasures as by, type DocGateQuality as bz, type CaptureChannel as c, facesOf as c$, INFERENCE_RETRY_DEFAULT_S as c0, LANDMARKER_MODEL as c1, LENS_STORAGE_KEY as c2, LENS_TRY_MAX as c3, LIVE_MRZ_DEFAULTS as c4, LIVE_PHOTO_IDLE_MS as c5, LIVE_PHOTO_MAX_HZ as c6, type LandmarkedFace as c7, type LandmarkerLike as c8, type LensKind as c9, SAME_FACE_MAX_DROPS as cA, type ScanEvent as cB, type ScanLayout as cC, type ScanNotice as cD, type ScanPhase as cE, type ScanReport as cF, type ScanSide as cG, type ScanState as cH, type SubmitExecutor as cI, TEXT_LOCK_DEFAULTS as cJ, TRANSPORT_REPLAY_ATTEMPTS as cK, TRANSPORT_REPLAY_DELAY_MS as cL, type VerificationInternals as cM, analyzeDocFrame as cN, analyzeGuide as cO, aspectBand as cP, aspectFits as cQ, buildDeviceReadHint as cR, coverPointToVideo as cS, createDocumentCaptureInternal as cT, createFaceLandmarker as cU, createLivePhotoKit as cV, createLivenessCaptureInternal as cW, createPortraitCaptureInternal as cX, createVerificationInternal as cY, docZoomFor as cZ, encodeDocumentImage as c_, type LensSource as ca, type LightingStatus as cb, type LiveMrzCapture as cc, type LiveMrzState as cd, type LivePhotoGate as ce, type LivePhotoKit as cf, type LivePhotoKitInternals as cg, type LivePhotoKitOptions as ch, type LivePhotoStill as ci, type LivenessCaptureInternalHandle as cj, type LivenessCaptureInternals as ck, type LivenessFlowDeps as cl, type LivenessFlowOutcome as cm, MANUAL_SHUTTER_MS as cn, MR_DOC_CATALOG as co, NO_REPORT_MS as cp, type OpenDocCameraDeps as cq, PORTRAIT_JPEG_QUALITY as cr, PRELOAD_BLAZE_INIT_TIMEOUT_MS as cs, PRELOAD_BUDGET_MS as ct, PROCESSING_POLL_DELAY_MS as cu, PROCESSING_POLL_MAX as cv, type PortraitCaptureController as cw, type PortraitCaptureInternals as cx, REGISTRY_RETRY_DELAY_MS as cy, type ReticleType as cz, type CaptureEngineId as d, feedbackVoteOf as d0, focusOk as d1, guideQuad as d2, guideRegionInFrame as d3, initialScanState as d4, lensKindOf as d5, mapEngineState as d6, mapErrorKind as d7, mapGuidanceHint as d8, nextScanState as d9, writeStoredLens as dA, observe as da, openDocCamera as db, passportBandOf as dc, portraitMatchStep as dd, preloadedDetectorFactory as de, quadAreaFrac as df, quadBounds as dg, quadIou as dh, quadTiltRatio as di, randomUuid as dj, rankBackCameras as dk, readStoredLens as dl, resetLivenessAssetsForTests as dm, resolveDocCameraTuning as dn, resolveDocShutterTuning as dp, resolveGuideLockTuning as dq, runLivenessFlow as dr, runSubmission as ds, scannerFormatFor as dt, setPreloadLoaderForTests as du, settledHint as dv, singleShotFocusAt as dw, specularFraction as dx, supportsFocusMode as dy, warmDocDetector as dz, type CaptureError as e, type CaptureErrorKind as f, type CaptureState as g, type CapturedArtifacts as h, type CapturedDocument as i, type CapturedPortrait as j, type ContactChoiceSnapshot as k, type ContactChoiceStepHandle as l, DEFAULT_API_ORIGIN as m, DOCUMENT_TYPE_ORDER as n, type DeriveStepEnv as o, type DocumentCaptureEvents as p, type DocumentCaptureState as q, type DocumentFeedback as r, type DocumentFeedbackKey as s, type DocumentGateUpdate as t, type DocumentGuide as u, type DocumentGuideMeasure as v, type DocumentLiveMrzOptions as w, type DocumentMrzUpdate as x, type DocumentPoint as y, type DocumentQuad as z };