@sekyro/web 0.1.0-rc.3 → 0.1.0-rc.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/CHANGELOG.md +427 -0
  2. package/LICENSE +25 -16
  3. package/README.md +150 -62
  4. package/THIRD-PARTY-NOTICES.txt +154 -0
  5. package/dist/background-monitor-A7FKJOAG.js +1 -0
  6. package/dist/barcode-detect-C5IOXMKI.js +1 -0
  7. package/dist/camera-trait-V4UAOPIQ.js +1 -0
  8. package/dist/capture-constraints-CVqpMNGA.d.cts +48 -0
  9. package/dist/capture-constraints-CVqpMNGA.d.ts +48 -0
  10. package/dist/capture-session-doc-ESEZJBQM.js +1 -0
  11. package/dist/{capture-session-v3-CvIfcwST.d.ts → capture-session-v3-CTQL6eFd.d.cts} +259 -13
  12. package/dist/{capture-session-v3-COIO_F2w.d.cts → capture-session-v3-DHlOE6cS.d.ts} +259 -13
  13. package/dist/challenge-frame-YAQJ5YMB.js +1 -0
  14. package/dist/chunk-2LDOXGY3.js +1 -0
  15. package/dist/chunk-33KKMPJ5.js +1 -0
  16. package/dist/chunk-3LMJ4335.js +1 -0
  17. package/dist/chunk-53POX7U4.js +1 -0
  18. package/dist/chunk-7252SFZ6.js +1 -0
  19. package/dist/chunk-7QZWBDI5.js +1 -0
  20. package/dist/chunk-A7QFTU6M.js +1 -0
  21. package/dist/chunk-CJHMFPL6.js +1 -0
  22. package/dist/chunk-CMXN4SOZ.js +1 -0
  23. package/dist/chunk-CPUECYAJ.js +1 -0
  24. package/dist/chunk-DFTCAWMP.js +1 -0
  25. package/dist/chunk-DK5YPBDQ.js +1 -0
  26. package/dist/chunk-FPXL63KZ.js +1 -0
  27. package/dist/chunk-FSSMUAKC.js +1 -0
  28. package/dist/chunk-G6LKLN4U.js +1 -0
  29. package/dist/chunk-GFJATPUR.js +1 -0
  30. package/dist/chunk-GI3UFGRQ.js +1 -0
  31. package/dist/chunk-JLVZ35QK.js +2 -0
  32. package/dist/chunk-KA43AAM7.js +1 -0
  33. package/dist/chunk-KXFHVAYQ.js +1 -0
  34. package/dist/chunk-ODI4A5K4.js +1 -0
  35. package/dist/chunk-OEQJ62CC.js +3 -0
  36. package/dist/chunk-POIQGEZM.js +1 -0
  37. package/dist/chunk-RI3E7GBN.js +1 -0
  38. package/dist/chunk-S5BUCUZ4.js +1 -0
  39. package/dist/chunk-SLKRT74K.js +1 -0
  40. package/dist/chunk-SMKCBUJL.js +1 -0
  41. package/dist/chunk-SX7TUC3V.js +1 -0
  42. package/dist/chunk-TSA6GHUG.js +1 -0
  43. package/dist/chunk-UTPUHE4J.js +1 -0
  44. package/dist/chunk-VVUQ4PFU.js +1 -0
  45. package/dist/chunk-VWGKUQ3C.js +1 -0
  46. package/dist/chunk-ZKF2XMNX.js +1 -0
  47. package/dist/client/index.cjs +1 -357
  48. package/dist/client/index.d.cts +6 -37
  49. package/dist/client/index.d.ts +6 -37
  50. package/dist/client/index.js +1 -15
  51. package/dist/clip-inspect-DLJXVKV6.js +1 -0
  52. package/dist/core/index.cjs +1 -1606
  53. package/dist/core/index.d.cts +5 -4
  54. package/dist/core/index.d.ts +5 -4
  55. package/dist/core/index.js +1 -139
  56. package/dist/core/ocr/worker.bundle.js +42 -0
  57. package/dist/core/ocr/worker.cjs +42 -0
  58. package/dist/core/ocr/worker.d.cts +84 -0
  59. package/dist/core/ocr/worker.d.ts +84 -0
  60. package/dist/core/ocr/worker.js +41 -0
  61. package/dist/core/v3/detect-worker.cjs +1 -392
  62. package/dist/core/v3/detect-worker.d.cts +1 -1
  63. package/dist/core/v3/detect-worker.d.ts +1 -1
  64. package/dist/core/v3/detect-worker.js +1 -13
  65. package/dist/create-document-capture-V7XCRRDV.js +1 -0
  66. package/dist/create-portrait-capture-5VGYZUOK.js +1 -0
  67. package/dist/create-verification-CGBe2yLE.d.cts +3719 -0
  68. package/dist/create-verification-aoY2QoRx.d.ts +3719 -0
  69. package/dist/{detect-worker-CKXHlXx9.d.ts → detect-worker-CHqsPJoM.d.cts} +25 -2
  70. package/dist/{detect-worker-CKXHlXx9.d.cts → detect-worker-CHqsPJoM.d.ts} +25 -2
  71. package/dist/detector-scanic-SE3CL55N.js +1 -0
  72. package/dist/icao-gate-DveU9Cr8.d.ts +573 -0
  73. package/dist/icao-gate-T3BTOKFJ.js +1 -0
  74. package/dist/icao-gate-xyWB7dz2.d.cts +573 -0
  75. package/dist/icao-policy-BWu1JLgi.d.cts +80 -0
  76. package/dist/icao-policy-OOEQDG9_.d.ts +80 -0
  77. package/dist/icao-tuning-4ETMF53W.js +1 -0
  78. package/dist/index.cjs +3 -2649
  79. package/dist/index.d.cts +138 -5
  80. package/dist/index.d.ts +138 -5
  81. package/dist/index.js +1 -28
  82. package/dist/internal/index.cjs +3 -4179
  83. package/dist/internal/index.d.cts +390 -371
  84. package/dist/internal/index.d.ts +390 -371
  85. package/dist/internal/index.js +1 -647
  86. package/dist/keyframe-rank-YAJLYJYF.js +1 -0
  87. package/dist/landmarker-KB7LVXAU.js +1 -0
  88. package/dist/mrz-band-VYHOTDHY.js +1 -0
  89. package/dist/plan-runner-IXCKR4DB.js +1 -0
  90. package/dist/popup/index.cjs +1 -76
  91. package/dist/popup/index.d.cts +9 -3
  92. package/dist/popup/index.d.ts +9 -3
  93. package/dist/popup/index.js +1 -11
  94. package/dist/print-SEWS3VHQ.js +1 -0
  95. package/dist/scanic-ml-stub-KW7IZHUT.js +1 -0
  96. package/dist/segmenter-USLNBX65.js +1 -0
  97. package/dist/types-CezFEXzl.d.cts +2103 -0
  98. package/dist/types-CezFEXzl.d.ts +2103 -0
  99. package/dist/upload-file-EGXXM6TQ.js +1 -0
  100. package/package.json +30 -11
  101. package/sbom.cdx.json +349 -0
  102. package/dist/capture-constraints-BujkZcfb.d.cts +0 -21
  103. package/dist/capture-constraints-BujkZcfb.d.ts +0 -21
  104. package/dist/chunk-7TC6TOZ4.js +0 -1095
  105. package/dist/chunk-7TC6TOZ4.js.map +0 -1
  106. package/dist/chunk-FIXX2AXC.js +0 -864
  107. package/dist/chunk-FIXX2AXC.js.map +0 -1
  108. package/dist/chunk-MWNFSNMP.js +0 -52
  109. package/dist/chunk-MWNFSNMP.js.map +0 -1
  110. package/dist/chunk-NILNKLK6.js +0 -50
  111. package/dist/chunk-NILNKLK6.js.map +0 -1
  112. package/dist/chunk-NWF46H7K.js +0 -359
  113. package/dist/chunk-NWF46H7K.js.map +0 -1
  114. package/dist/chunk-WY6U7AIK.js +0 -193
  115. package/dist/chunk-WY6U7AIK.js.map +0 -1
  116. package/dist/chunk-YVFF4Q4G.js +0 -327
  117. package/dist/chunk-YVFF4Q4G.js.map +0 -1
  118. package/dist/client/index.cjs.map +0 -1
  119. package/dist/client/index.js.map +0 -1
  120. package/dist/core/index.cjs.map +0 -1
  121. package/dist/core/index.js.map +0 -1
  122. package/dist/core/v3/detect-worker.cjs.map +0 -1
  123. package/dist/core/v3/detect-worker.js.map +0 -1
  124. package/dist/create-verification-CP18eq1Q.d.cts +0 -348
  125. package/dist/create-verification-CswF2As-.d.ts +0 -348
  126. package/dist/detector-scanic-4C6IEW2K.js +0 -787
  127. package/dist/detector-scanic-4C6IEW2K.js.map +0 -1
  128. package/dist/hosted-client-BpvBqu9f.d.cts +0 -408
  129. package/dist/hosted-client-BpvBqu9f.d.ts +0 -408
  130. package/dist/index.cjs.map +0 -1
  131. package/dist/index.js.map +0 -1
  132. package/dist/internal/index.cjs.map +0 -1
  133. package/dist/internal/index.js.map +0 -1
  134. package/dist/popup/index.cjs.map +0 -1
  135. package/dist/popup/index.js.map +0 -1
  136. package/dist/scanic-ml-stub-S2OZ6HEF.js +0 -10
  137. package/dist/scanic-ml-stub-S2OZ6HEF.js.map +0 -1
@@ -0,0 +1,3719 @@
1
+ import { b as Detector } from './detect-worker-CHqsPJoM.cjs';
2
+ import { A as AcceptedDocumentType, ar as NationalEidOption, b8 as StepSection, bj as HostedBranding, aF as PlanSectionView, aC as PlanChoiceKind, aa as HostedSimulationView, l as ContactChannel, f as CheckReason, bn as RetakeHint, az as PhotoSource, aA as PhotoSourcePick, ai as IdentityMethod, E as EidAfterPass, X as HostedFormView, aj as IdentitySummarySource, Y as HostedIcaoPolicy, $ as HostedNativeAppView, av as PhoneCountryRule, ag as IcaoReportEntry, bm as IcaoCaptureTuning, a6 as HostedPortraitPendingFix, b as CaptureMode, a5 as HostedPoaRuleView, aL as PoaNameMatchMode, b2 as SessionReason, b0 as SessionDecidingStep, a9 as HostedSessionView, ab as HostedStepView, aG as PlanStepView, aZ as ResolvedCaptureMode, I as FormIssueCode, br as ScreenRampReport, bi as CaptureProvenance, H as FormInput, bp as ScreenRampPaint, b1 as SessionFailureReason, bf as AgeEstimationReason, bd as VerificationLevel, bc as VerificationAssurance, a$ as SandboxSimulation, aq as MethodChoiceView, bg as CameraUnavailableCause, bh as CaptureIssueReport, ae as HostedVoiceView, bo as ScreenRampChallenge, a as AttestationInput, h as CheckType, bw as PersonMask, aT as PortraitIcaoInput, P as HostedChallengeView } from './types-CezFEXzl.cjs';
3
+ import { i as CaptureState$1, f as CaptureSessionV3Events, g as CaptureSessionV3Options, c as CaptureErrorKind$1, q as DeviceClass, b as CaptureArtifacts, ad as EngineErrorDetail, W as V3GateQuality, _ as V3TelemetryEvent } from './capture-session-v3-CTQL6eFd.cjs';
4
+ import { f as IcaoGateSummary, g as IcaoGateUpdate, H as HostedClient, P as Point, p as IcaoGateScores, h as Box, m as IcaoFrameObservation, n as IcaoGate } from './icao-gate-xyWB7dz2.cjs';
5
+
6
+ /** Why a challenge produced no token (spec §4.5). */
7
+ type ChallengeErrorCode = "challenge_frame_blocked" | "challenge_script_blocked" | "site_key_rejected" | "challenge_failed" | "timeout" | "embedder_opaque" | "aborted";
8
+ /**
9
+ * A challenge that produced no token. `detail` is Cloudflare's numeric error code when there is one; `readyMs` is
10
+ * how long the last frame took to answer `ready` (absent when it never did), for the capture issue (incident 2026-11-13).
11
+ */
12
+ declare class ChallengeError extends Error {
13
+ readonly code: ChallengeErrorCode;
14
+ readonly detail?: string;
15
+ readyMs?: number;
16
+ constructor(code: ChallengeErrorCode, detail?: string);
17
+ }
18
+ /**
19
+ * Bound on the frame's `ready` message after it is inserted (a blocked frame never sends it). On slow mobile
20
+ * networks the frame document and its script alone can take more than 10 s (incident 2026-11-15:
21
+ * `challenge_frame_blocked` on pages whose CSP allowed the frame), so the bound is 30 s.
22
+ */
23
+ declare const CHALLENGE_READY_TIMEOUT_MS = 30000;
24
+ /**
25
+ * Bound on one challenge after the request is posted. A healthy invisible challenge settles in a few seconds, but on
26
+ * entry-level Android phones on mobile networks it often takes far longer: with a 30 s bound, the waits that did end
27
+ * in a token were spread evenly from 5 s up to the bound (incident 2026-11-15), so the bound cut off challenges that
28
+ * were still working. Kept equal to `EXECUTE_TIMEOUT_MS` in the hosted frame (`public/challenge/frame.js`).
29
+ */
30
+ declare const CHALLENGE_EXECUTE_TIMEOUT_MS = 120000;
31
+ /** What the token is for: the liveness submission, or the try-link start. */
32
+ type ChallengeAction = "liveness" | "try_link";
33
+ /** Options of {@link executeChallenge}. */
34
+ interface ExecuteChallengeOptions {
35
+ /** The frame URL (`HostedSessionView.challenge.url`). */
36
+ frameUrl: string;
37
+ /** The site key the frame renders (`HostedSessionView.challenge.siteKey`). */
38
+ siteKey: string;
39
+ action: ChallengeAction;
40
+ /** The session id (`ses_...`) for `liveness`; the hex sha256 of the try token for `try_link`. */
41
+ subject: string;
42
+ /** Aborts the challenge: the promise rejects with `aborted` and the frame is removed. */
43
+ signal?: AbortSignal;
44
+ /** Bound on the challenge once requested; default {@link CHALLENGE_EXECUTE_TIMEOUT_MS}. */
45
+ timeoutMs?: number;
46
+ /** Bound on the frame's `ready`; default {@link CHALLENGE_READY_TIMEOUT_MS}. */
47
+ readyTimeoutMs?: number;
48
+ }
49
+ /** Test-only: drop the kept frame and the queue between cases. */
50
+ declare function resetChallengeFrameForTests(): void;
51
+ /**
52
+ * Obtain one token from the challenge frame. Challenges run in order on one
53
+ * kept frame; a failed challenge runs once more on a fresh frame before the
54
+ * promise rejects with a {@link ChallengeError} (a timed-out one rejects at once).
55
+ */
56
+ declare function executeChallenge(opts: ExecuteChallengeOptions): Promise<string>;
57
+
58
+ declare const ISSUER_CODES: readonly string[];
59
+
60
+ /** Accepted document types per issuer (the view's `acceptedDocuments`): `byIssuer[iso2] ?? default`; `"*"` = every type. */
61
+ interface AcceptedDocumentsLike {
62
+ default: "*" | readonly AcceptedDocumentType[];
63
+ byIssuer?: Readonly<Record<string, readonly AcceptedDocumentType[]>>;
64
+ }
65
+ /** Picker order: identity card, passport, residence permit. */
66
+ declare const DOCUMENT_TYPE_ORDER: readonly AcceptedDocumentType[];
67
+ /** Types accepted for documents of `issuer` (ISO 3166-1 alpha-2), in picker order. */
68
+ declare const acceptedTypesFor: (accepted: AcceptedDocumentsLike, issuer: string) => AcceptedDocumentType[];
69
+ /** Issuers with at least one accepted type, sorted by code (name them with `Intl.DisplayNames`). */
70
+ declare const acceptedIssuers: (accepted: AcceptedDocumentsLike, codes?: readonly string[]) => string[];
71
+ /** `acceptedDocuments`, or — from a server that predates it — MR with the legacy `acceptedDocumentTypes`. */
72
+ declare const resolveAcceptedDocuments: (view: {
73
+ acceptedDocuments?: AcceptedDocumentsLike | undefined;
74
+ acceptedDocumentTypes?: readonly AcceptedDocumentType[] | undefined;
75
+ }) => AcceptedDocumentsLike;
76
+ /** Flag emoji of an alpha-2 code (regional indicator symbols); `""` otherwise. */
77
+ declare const flagOf: (iso2: string) => string;
78
+
79
+ declare const WEB_IDENTITY_METHODS: readonly IdentityMethod[];
80
+ /** Plan 4's web stop for `nfc.mode = mandatory` (view-only `reasonCode`) and the skip reason in `preferred`. */
81
+ declare const PLATFORM_UNSUPPORTED = "platform_unsupported";
82
+ /** A step's section: the view's value (kept even when unknown), else the check type's. */
83
+ declare function sectionOf(step: Pick<HostedStepView, "checkType" | "section">): StepSection | null;
84
+ declare function sectionOf(step: Pick<PlanStepView, "checkType" | "section">): StepSection | null;
85
+ /**
86
+ * The in-lane switch of a step screen (C4 client rule §5 item 6): the session's choice is still open (present,
87
+ * unlocked) while a step of one of its lanes is current. `options` are the choice's options this SDK renders, in
88
+ * the server's order; `current` is the lane taken. With exactly one other option a screen offers a direct switch
89
+ * labelled by it; with two or more, « Use another option » re-opens the choice locally.
90
+ */
91
+ interface InLaneSwitch {
92
+ nodeId: string;
93
+ kind: PlanChoiceKind;
94
+ current: string | null;
95
+ options: ChoiceOptionSnapshot[];
96
+ }
97
+ /** The open choice of the view as an in-lane switch, `null` without one (locked, absent, or the choice itself current). */
98
+ declare function laneOf(view: HostedSessionView): InLaneSwitch | null;
99
+ /** The other options of an in-lane switch. */
100
+ declare function otherOptions(lane: InLaneSwitch | null | undefined): ChoiceOptionSnapshot[];
101
+ type DocumentSide = "recto" | "verso" | "single";
102
+ interface DeriveStepEnv {
103
+ /**
104
+ * A phone / tablet browser. `false` (a desktop) routes a `requiresMobile` camera step to `mobile_required`, and a
105
+ * `choice` photo step to its upload with the camera on a phone (`photo.cameraOnPhone`). Absent: neither.
106
+ */
107
+ isMobile?: boolean;
108
+ }
109
+ interface StepContext {
110
+ /** The session id as partners read it (`ses_...`): the reference shown on the result screen. */
111
+ sessionId: string;
112
+ orgName: string;
113
+ /**
114
+ * A Sandbox (test) session (`view.sandbox`): show the "Test session" badge. `false` in Live and on an older backend.
115
+ * The flow is the same in both environments; only the badge, and on a simulated session `simulation`, differ.
116
+ */
117
+ sandbox: boolean;
118
+ returning: boolean;
119
+ consentRecorded: boolean;
120
+ expiresAt: string;
121
+ branding?: HostedBranding;
122
+ /**
123
+ * The sections of this session in flow order (`plan.sections`), one
124
+ * progress segment each: the sections still possible on any remaining path.
125
+ */
126
+ sections: StepSection[];
127
+ /** `plan.sections` with their states (`done | current | upcoming`): draw the progress from these. */
128
+ progress: PlanSectionView[];
129
+ /** The step's in-lane switch (C4 client rule §5 item 6); absent without an open choice. */
130
+ switchable?: InLaneSwitch;
131
+ /** Spec 2026-10-29 §6.7: the session's copy set (`view.purpose`; `identity` from an older backend). */
132
+ purpose: "human" | "identity";
133
+ /**
134
+ * Spec 2026-10-29 §3.4: a flow fallback takes over a missing camera at the live step (`view.cameraUnavailableHandled`).
135
+ * Absent otherwise: then only a `human` session offers "continue without a camera".
136
+ */
137
+ cameraUnavailableHandled?: true;
138
+ /**
139
+ * Sandbox DX spec 2026-11-06 §8: a simulated session (`view.simulation`). Say that nothing is sent, show `otpCode` on
140
+ * the code screens, and with `skipCapture` offer the step's `skipCapture()`. Absent on every other session.
141
+ */
142
+ simulation?: HostedSimulationView;
143
+ /**
144
+ * Spec 2026-11-09 §3.3: offer "Run real checks as a tester" (`view.testerGate`): a simulated Sandbox session before
145
+ * its first capture. Run it with `Verification.testerGate()`. Absent on every other session.
146
+ */
147
+ testerGate?: {
148
+ attemptsLeft: number;
149
+ };
150
+ }
151
+ interface StepAttempts {
152
+ reason?: CheckReason;
153
+ /** Liveness v7 §5.2: what to change for the next capture, when the API reports it (prefer `hints.*` copy). */
154
+ retakeHint?: RetakeHint;
155
+ attemptsRemaining: number;
156
+ /** Every counted attempt is used (`attempts.used >= attempts.max`): no try is left. */
157
+ attemptsExhausted: boolean;
158
+ }
159
+ type OtpNumberSource = "prefilled" | "user_entered" | "prefilled_or_entered";
160
+ /** Where an email_otp address comes from (same vocabulary as the phone number). */
161
+ type EmailSource = OtpNumberSource;
162
+ /** A phone OTP delivery channel the person can choose. */
163
+ type OtpChannel = "whatsapp" | "sms";
164
+ interface PhoneOtpSnapshot extends StepAttempts {
165
+ /**
166
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
167
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
168
+ * step has none (an idle processing step, the result).
169
+ */
170
+ section: StepSection | null;
171
+ kind: "phone_otp";
172
+ key: string;
173
+ context: StepContext;
174
+ phase: "send" | "verify";
175
+ numberSource: OtpNumberSource;
176
+ /**
177
+ * The person types the number: not with a `prefilled` source, nor when the partner supplied the number of a
178
+ * `prefilled_or_entered` session (`prefilled`; the server would send to the partner's number anyway).
179
+ */
180
+ needsPhone: boolean;
181
+ /** UX refresh 2026-11-05: the partner supplied the number (the server's `otp.prefilled`); the screen says so. */
182
+ prefilled?: true;
183
+ /**
184
+ * The channels the person chooses from, in the server's display order
185
+ * (WhatsApp first). `[]` for a session created before channel choice: send
186
+ * without a channel (SMS). With more than one, `send` needs the person's choice.
187
+ */
188
+ channels: OtpChannel[];
189
+ /**
190
+ * The countries the number may be from (ISO alpha-2, the first the default of the
191
+ * country picker; person data spec Q16). Absent from a server before person data
192
+ * Task A9: `@sekyro/react` then falls back to its legacy `MR` field. An empty list means the
193
+ * free international field.
194
+ */
195
+ phoneCountries?: string[];
196
+ /**
197
+ * The numbering plan of the `phoneCountries` (phone rules spec 2026-11-02 §2.1), malformed rules and rules
198
+ * of other countries left out. Absent from an older server: nothing is blocked or grouped.
199
+ */
200
+ phoneRules?: PhoneCountryRule[];
201
+ /** Numbers from other countries are accepted, through a free international field (spec §4.1 item 7). */
202
+ phoneInternational?: true;
203
+ sentToMasked?: string;
204
+ channel?: "sms" | "whatsapp";
205
+ codeExpiresAt?: string;
206
+ /** ISO time from which a resend is allowed (the server's cooldown, else 30 s after this page's last send). */
207
+ resendAvailableAt?: string;
208
+ /** A `one_of` session where no contact step passed yet: the person may switch to {@link switchChannel}. */
209
+ canSwitch: boolean;
210
+ /** The other contact option (with `canSwitch`). */
211
+ switchChannel?: ContactChannel;
212
+ }
213
+ /** Email OTP (profile v2 §4.6.5): send a code to an address, then verify it. */
214
+ interface EmailOtpSnapshot extends StepAttempts {
215
+ /**
216
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
217
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
218
+ * step has none (an idle processing step, the result).
219
+ */
220
+ section: StepSection | null;
221
+ kind: "email_otp";
222
+ key: string;
223
+ context: StepContext;
224
+ phase: "send" | "verify";
225
+ emailSource: EmailSource;
226
+ /** The person types the address (every source but `prefilled`, and not over a partner's address). */
227
+ needsEmail: boolean;
228
+ /** UX refresh 2026-11-05: the partner supplied the address (the server's `emailOtp.prefilled`). */
229
+ prefilled?: true;
230
+ /** Masked address of the last send (e.g. `a•••@e•••.com`). */
231
+ sentToMasked?: string;
232
+ codeExpiresAt?: string;
233
+ /** ISO time from which a resend is allowed (the server's cooldown, else 30 s after this page's last send). */
234
+ resendAvailableAt?: string;
235
+ /** See {@link PhoneOtpSnapshot.canSwitch}. */
236
+ canSwitch: boolean;
237
+ switchChannel?: ContactChannel;
238
+ }
239
+ /**
240
+ * Step 1 contact choice (flow model 2026-10-23): a `one_of` session before the
241
+ * person chose phone or email.
242
+ */
243
+ /** One option of a choice screen (server order; only services this SDK renders). */
244
+ interface ChoiceOptionSnapshot {
245
+ /** The option id {@link ChoiceStepHandle.choose} sends. */
246
+ id: string;
247
+ /** The lane's service: label it (`document`, `population_registry`, `national_eid`, `phone_otp`, `email_otp`). */
248
+ service: string;
249
+ /** `national_eid`: the provider ("Verify with Houwiyeti"); absent = the generic eID copy. */
250
+ nationalEid?: NationalEidOption;
251
+ /**
252
+ * `phone_otp` (flow UX refresh 2026-11-05): the channels in display order, so a contact choice offers WhatsApp / SMS
253
+ * directly next to Email (choose the option, then send with that channel). Absent on an older API.
254
+ */
255
+ channels?: OtpChannel[];
256
+ }
257
+ /** `plan.choice` as a choice screen shows it. */
258
+ interface PlanChoiceSnapshot {
259
+ nodeId: string;
260
+ /** `identity_method` (method.* copy), `contact` (contact.* copy) or `generic` (choice.* copy). */
261
+ kind: PlanChoiceKind;
262
+ selected: string | null;
263
+ options: ChoiceOptionSnapshot[];
264
+ }
265
+ /**
266
+ * A choice screen of another kind (Sekyro flows `generic`): the person picks
267
+ * one option; its `kind` decides the copy (`choice.*`).
268
+ */
269
+ interface ChoiceSnapshot {
270
+ section: StepSection | null;
271
+ kind: "choice";
272
+ key: string;
273
+ context: StepContext;
274
+ choice: PlanChoiceSnapshot;
275
+ }
276
+ interface ContactChoiceSnapshot {
277
+ /**
278
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
279
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
280
+ * step has none (an idle processing step, the result).
281
+ */
282
+ section: StepSection | null;
283
+ kind: "contact_choice";
284
+ key: string;
285
+ context: StepContext;
286
+ options: ContactChannel[];
287
+ selected: ContactChannel | null;
288
+ locked: boolean;
289
+ /** The choice behind this screen (`plan.choice`, kind `contact`). */
290
+ choice: PlanChoiceSnapshot;
291
+ }
292
+ /**
293
+ * Step 2b summary and confirm (flow model 2026-10-23): the identity data read so
294
+ * far, to confirm before the live photo. Masks keep the last 4 characters. PII:
295
+ * never log these values or send them to analytics.
296
+ */
297
+ interface IdentitySummarySnapshot {
298
+ /**
299
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
300
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
301
+ * step has none (an idle processing step, the result).
302
+ */
303
+ section: StepSection | null;
304
+ kind: "identity_summary";
305
+ key: string;
306
+ context: StepContext;
307
+ /** `full` (document / chip, with the photo) or `partial` (registry from a typed NNI: short name, birth year, no photo). */
308
+ summaryKind: "full" | "partial" | (string & {});
309
+ source: IdentitySummarySource | (string & {});
310
+ /** The full name, or the short form "Mohamed S." on a `partial` summary. */
311
+ fullName?: string;
312
+ birthDate?: string;
313
+ /** `partial` summaries carry the birth year only. */
314
+ birthYear?: string;
315
+ nationality?: string;
316
+ documentType?: string;
317
+ documentNumberMasked?: string;
318
+ /** The bound ID number, masked (last 4), from either view name. */
319
+ idNumberMasked?: string;
320
+ /** @deprecated Read `idNumberMasked` (the same value). */
321
+ nniMasked?: string;
322
+ expiryDate?: string;
323
+ /** The portrait can be fetched (`portrait()` on the handle). */
324
+ portraitAvailable: boolean;
325
+ retakeAvailable: boolean;
326
+ retakeTarget?: "document" | "national_number" | (string & {});
327
+ }
328
+ interface MethodSnapshot {
329
+ /**
330
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
331
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
332
+ * step has none (an idle processing step, the result).
333
+ */
334
+ section: StepSection | null;
335
+ kind: "method";
336
+ key: string;
337
+ context: StepContext;
338
+ options: IdentityMethod[];
339
+ /** The provider behind `national_eid` ("Verify with Houwiyeti"); absent when it is not offered. */
340
+ nationalEid?: NationalEidOption;
341
+ /** The choice behind this screen (`plan.choice`, kind `identity_method`). */
342
+ choice: PlanChoiceSnapshot;
343
+ }
344
+ /**
345
+ * The national eID sign-in (SDK spec §3.2; Houwiyeti in MR). Two phases:
346
+ * - `identifier` — the person types their national number (the NNI in MR)
347
+ * unless `identifierBound`, then the SDK asks the provider for a code;
348
+ * - `code` — the person opens the provider's app and types the code shown.
349
+ * A passed eID ends the session (no document, liveness or face match). With
350
+ * `canUseCamera` (`eid_not_enrolled`, `eid_unavailable`, `eid_locked` on a
351
+ * session that offers the camera path) the person may switch to `cameraMethod`.
352
+ */
353
+ interface EidSnapshot extends StepAttempts {
354
+ /**
355
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
356
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
357
+ * step has none (an idle processing step, the result).
358
+ */
359
+ section: StepSection | null;
360
+ kind: "eid";
361
+ key: string;
362
+ context: StepContext;
363
+ /** `{ISO2}.{provider}`, e.g. `MR.houwiyeti`. */
364
+ provider: string;
365
+ /** Display name, e.g. "Houwiyeti" (for "Verify with Houwiyeti"). */
366
+ providerName: string;
367
+ country: string;
368
+ challenge: "app_code";
369
+ phase: "identifier" | "code";
370
+ identifierBound: boolean;
371
+ codeExpiresAt?: string;
372
+ resendAvailableAt?: string;
373
+ resendsRemaining?: number;
374
+ codeAttemptsRemaining?: number;
375
+ canUseCamera: boolean;
376
+ /** The camera-path method `useCamera()` selects (present with `canUseCamera`). */
377
+ cameraMethod?: IdentityMethod;
378
+ /** What follows a pass (flow model 2026-10-23): `continue` = a live photo follows ("then a quick selfie"). */
379
+ afterPass: EidAfterPass;
380
+ }
381
+ type RegistrySource = "bound" | "document" | "typed";
382
+ interface RegistrySnapshot extends StepAttempts {
383
+ /**
384
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
385
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
386
+ * step has none (an idle processing step, the result).
387
+ */
388
+ section: StepSection | null;
389
+ kind: "registry";
390
+ key: string;
391
+ context: StepContext;
392
+ state: "pending" | "input_required";
393
+ source: RegistrySource;
394
+ recheck: boolean;
395
+ canUseDocument: boolean;
396
+ }
397
+ interface DocumentSnapshot extends StepAttempts {
398
+ /**
399
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
400
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
401
+ * step has none (an idle processing step, the result).
402
+ */
403
+ section: StepSection | null;
404
+ kind: "document";
405
+ key: string;
406
+ context: StepContext;
407
+ side: "recto" | "verso";
408
+ acceptedSides: ("recto" | "verso")[];
409
+ documents: AcceptedDocumentsLike;
410
+ /**
411
+ * The person's country as detected from their IP address (ISO 3166-1 alpha-2, the view's
412
+ * `detectedCountry`): list it first among the issuers when `documents` accepts it. Absent when unknown.
413
+ */
414
+ detectedCountry?: string;
415
+ /**
416
+ * Age check (selfie): `true` when the session reached this document because the selfie could not settle the
417
+ * person's age (`age_estimation` failed with `age_uncertain` or `age_unavailable`); show the step-up line
418
+ * (`doc.ageStepUp`). Absent otherwise.
419
+ */
420
+ ageStepUp?: true;
421
+ /** 2026-11-05: where the document photo comes from (the view's `documents`; camera only when absent). */
422
+ photo: PhotoSourceState;
423
+ }
424
+ /**
425
+ * Where the photo of the ID document step or the portrait step comes from (2026-11-05), from the hosted view:
426
+ * - `source` `camera`: the camera screen only (no upload, even when the camera cannot open);
427
+ * - `source` `upload`: the upload screen at once (no camera screen);
428
+ * - `source` `choice`: ask "Take a photo" or "Upload a photo", unless `pick` holds the person's earlier pick for this
429
+ * step (a retry, the back side): then go straight to that source.
430
+ */
431
+ interface PhotoSourceState {
432
+ /** The step's setting. */
433
+ source: PhotoSource;
434
+ /** The person's pick under `choice` (recorded by the server from their first photo of the step); `null` before one. */
435
+ pick: PhotoSourcePick | null;
436
+ /** An upload is accepted now (`uploadDocument` / `uploadPortrait`). */
437
+ uploadOffered: boolean;
438
+ /**
439
+ * Spec 2026-11-06 §3.1, a `choice` step on a desktop: the camera runs on a phone only. Offer the upload and
440
+ * "Continue on my phone" (the hand-over), never the webcam. Absent otherwise.
441
+ */
442
+ cameraOnPhone?: true;
443
+ }
444
+ /**
445
+ * The proof of address step (spec 2026-11-10 §5, §7.4): a recent document in the person's name at their address, as
446
+ * 1 to 3 page photos or one PDF. `phase: "holder_letter"` once the bill was read under `third_party_letter` (the
447
+ * holder's signed letter is asked for). Show `rule` as the accepted list for `rule.country` (the global list when
448
+ * `rule.country` is `null`), one row per kind with that kind's `maxAgeDays`; after
449
+ * `document_kind_not_accepted` or `document_too_old` it is the rule of the failed document's country.
450
+ */
451
+ interface ProofOfAddressSnapshot extends StepAttempts {
452
+ section: StepSection | null;
453
+ kind: "proof_of_address";
454
+ key: string;
455
+ context: StepContext;
456
+ phase: "document" | "holder_letter";
457
+ /** The accepted kinds, resolved by the server (an empty global rule from a server without the block). */
458
+ rule: HostedPoaRuleView;
459
+ nameMatch: PoaNameMatchMode;
460
+ /** Where the pages come from (the view's `proofOfAddress.source`; the camera when absent). */
461
+ photo: PhotoSourceState;
462
+ /** Pages per document, at most. */
463
+ maxPages: 3;
464
+ /** A PDF upload's limits. */
465
+ pdf: {
466
+ maxBytes: number;
467
+ maxPages: 3;
468
+ };
469
+ /**
470
+ * Spec 2026-11-10 §5.3: the step accepts the address of the driving licence read earlier, so the person may continue
471
+ * without a document ({@link ProofOfAddressStepHandle.useLicenceAddress}). Always `false` in the `holder_letter` phase.
472
+ */
473
+ licenceAddressAccepted: boolean;
474
+ }
475
+ /**
476
+ * The Form step (spec 2026-11-14 §14): one screen, the questions in the client's order, then the consents, one
477
+ * "Continue". `form` holds the client's text in `form.locale` (render it with that `lang` and `dir`, whatever the page
478
+ * language); ready-made field labels, buttons and errors are the SDK's own copy. Prefilled answers are editable.
479
+ */
480
+ interface FormSnapshot extends StepAttempts {
481
+ section: StepSection | null;
482
+ kind: "form";
483
+ key: string;
484
+ context: StepContext;
485
+ form: HostedFormView;
486
+ /** The direction of `form.locale` (`rtl` for Arabic). */
487
+ dir: "rtl" | "ltr";
488
+ }
489
+ interface LivenessSnapshot extends StepAttempts {
490
+ /**
491
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
492
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
493
+ * step has none (an idle processing step, the result).
494
+ */
495
+ section: StepSection | null;
496
+ kind: "liveness";
497
+ key: string;
498
+ context: StepContext;
499
+ mode: "liveness" | "selfie";
500
+ requiresMobile: boolean;
501
+ /**
502
+ * Step 3 instructions (flow model 2026-10-23): `icao` on a session whose
503
+ * selfie is ICAO-checked (`icao` below) — the ICAO tips variant.
504
+ */
505
+ instructions: "standard" | "icao";
506
+ /** The session's selfie ICAO policy (`icaoPolicyOf`), `null` when ICAO is off (absent on older SDKs). */
507
+ icao?: HostedIcaoPolicy | null;
508
+ /**
509
+ * Step 3 one capture: the capture also takes a full-resolution still. `icao`
510
+ * = the ICAO portrait is due from this capture (`portrait_icao` pending): the
511
+ * gate also requires the ICAO conditions and the still rides the liveness
512
+ * submission as `input.portraitIcao`. `null` on an older API.
513
+ */
514
+ livePhoto: LivePhotoPlan | null;
515
+ }
516
+ /** How one live-photo capture is taken (flow model 2026-10-23, Step 3). */
517
+ interface LivePhotoPlan {
518
+ icao: boolean;
519
+ still: {
520
+ minLongSidePx: number;
521
+ jpegQuality: number;
522
+ };
523
+ }
524
+ /**
525
+ * The ICAO portrait step of an ID-document session (SDK spec §4.9, §5.4):
526
+ * - `capture` — `portrait_icao` is the frontier: run the strict gate, take the
527
+ * portrait (a retry carries the server's `report` to coach from), or upload
528
+ * a photo when `photo.uploadOffered` (design 2026-11-04 §6.2);
529
+ * - `review` — the server adjusted the photo and waits for the person to accept
530
+ * it (`pendingFix`, design 2026-11-04 §6.4 step 4): show both photos and call
531
+ * `confirmFix(true | false)`;
532
+ * - `match` — the portrait was accepted (`passed`, or `review` after the
533
+ * attempt cap: `review: true`, "We'll review your photo") and `face_match`
534
+ * is due: the SDK submits it with the portrait as the probe — no new capture.
535
+ */
536
+ interface PortraitSnapshot extends StepAttempts {
537
+ /**
538
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
539
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
540
+ * step has none (an idle processing step, the result).
541
+ */
542
+ section: StepSection | null;
543
+ kind: "portrait";
544
+ key: string;
545
+ context: StepContext;
546
+ phase: "capture" | "review" | "match";
547
+ /** The server's per-criterion report of the last attempt (`null` before one). */
548
+ report: IcaoReportEntry[] | null;
549
+ /** The portrait goes to a reviewer (attempt cap reached in decision mode `review`). */
550
+ review: boolean;
551
+ /** `capture.icao` (coaching limits) and `capture.tuningVersion` of the view. */
552
+ tuning: IcaoCaptureTuning | null;
553
+ tuningVersion: string | null;
554
+ /** The session's ICAO policy and profile (`icaoPolicyOf`; absent on older SDKs). */
555
+ icao?: HostedIcaoPolicy | null;
556
+ /**
557
+ * Step 3 (flow model 2026-10-23): the live check of this session passed and
558
+ * only the ICAO portrait needs another still — a portrait-only retake, no new clip.
559
+ */
560
+ retakeOnly: boolean;
561
+ /**
562
+ * 2026-11-05: where the photo comes from (the view's `portrait.source`; `camera` on older servers). `uploadOffered`
563
+ * is `false` outside the `capture` phase.
564
+ */
565
+ photo: PhotoSourceState;
566
+ /** `review` phase: the original and the adjusted photo, and what was changed. `null` otherwise. */
567
+ pendingFix: HostedPortraitPendingFix | null;
568
+ /**
569
+ * Design 2026-11-04 §4, §6.3 (`portrait.captureMode`): who takes the photo on the step's own camera screen (`self`,
570
+ * `assisted`, or `choice`: ask who takes the photo unless the person already picked for the session). Absent when
571
+ * the still rides the liveness capture (one capture) or on an older server.
572
+ */
573
+ captureMode?: CaptureMode;
574
+ /**
575
+ * Design 2026-11-04 §6.6: a returning person's earlier photo is being bound to today's liveness (the SDK submits it
576
+ * by itself: nothing for the person to do). Absent on older servers.
577
+ */
578
+ reuse?: boolean;
579
+ }
580
+ interface MobileRequiredSnapshot {
581
+ /**
582
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
583
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
584
+ * step has none (an idle processing step, the result).
585
+ */
586
+ section: StepSection | null;
587
+ kind: "mobile_required";
588
+ key: string;
589
+ context: StepContext;
590
+ /** The camera step to continue on a phone (spec 2026-11-06 §3.1: every live camera capture, in every decision mode). */
591
+ checkType: "liveness" | "face_match" | "doc_ocr" | "portrait_icao" | "poa";
592
+ }
593
+ /**
594
+ * Native-only capture (spec 2026-11-15): the flow takes this camera step in a native app only (`requiresNativeApp`),
595
+ * so a browser, phone or desktop alike, shows the way to the partner's app or the Sekyro AI app instead of the camera.
596
+ */
597
+ interface NativeAppRequiredSnapshot {
598
+ /** The section of the flow (see {@link MobileRequiredSnapshot.section}). */
599
+ section: StepSection | null;
600
+ kind: "native_app_required";
601
+ key: string;
602
+ context: StepContext;
603
+ /** The camera step to continue in the app. */
604
+ checkType: string;
605
+ /** Where to continue (`view.nativeApp`); `{ sekyroApp: false }` when the server sent none. */
606
+ nativeApp: HostedNativeAppView;
607
+ }
608
+ interface ProcessingSnapshot {
609
+ /**
610
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
611
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
612
+ * step has none (an idle processing step, the result).
613
+ */
614
+ section: StepSection | null;
615
+ kind: "processing";
616
+ key: string;
617
+ context: StepContext;
618
+ stalled: boolean;
619
+ /**
620
+ * The service of the step the server is running (`age_estimation`, `face_dedup`, …), when one is known: a screen
621
+ * may say what is being checked. Absent when nothing names the step.
622
+ */
623
+ service?: string;
624
+ }
625
+ type UnsupportedReason = "platform_unsupported" | "update_required";
626
+ interface UnsupportedSnapshot {
627
+ /**
628
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
629
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
630
+ * step has none (an idle processing step, the result).
631
+ */
632
+ section: StepSection | null;
633
+ kind: "unsupported";
634
+ key: string;
635
+ context: StepContext;
636
+ checkType: string;
637
+ reason: UnsupportedReason;
638
+ }
639
+ /**
640
+ * The result screen to show (session outcome model §5.1): `verified`; `review`; `rejected` (a
641
+ * verdict against the person); `inconclusive` (no verdict could be reached); `unavailable` (the
642
+ * check could not run); `expired` (the person left, nobody opened the link, the organization
643
+ * cancelled it or a newer session took it over: this link is over); `policy` (a flow rule
644
+ * stopped it); `cooldown` (this device may try again later); `platform_unsupported` (this
645
+ * client cannot run a required step).
646
+ */
647
+ type ResultDisplay = "verified" | "review" | "rejected" | "inconclusive" | "unavailable" | "expired" | "policy" | "cooldown" | "platform_unsupported";
648
+ interface ResultSnapshot {
649
+ /**
650
+ * Flow model 2026-10-23: the section of the flow (`contact`, `identity`,
651
+ * `live_photo`; an unknown value from a newer server is kept), `null` when the
652
+ * step has none (an idle processing step, the result).
653
+ */
654
+ section: StepSection | null;
655
+ kind: "result";
656
+ key: string;
657
+ context: StepContext;
658
+ display: ResultDisplay;
659
+ result: VerificationResult;
660
+ /** `not_verified` only: why ({@link SessionReason}). */
661
+ reason?: SessionReason;
662
+ /** The detailed code behind the result (`spoof_detected`, `device_cooldown`, `platform_unsupported`, ...). */
663
+ reasonCode?: string;
664
+ /** `not_verified` only: the step that decided it, when one did. */
665
+ step?: SessionDecidingStep;
666
+ retryAfter?: string;
667
+ }
668
+ type StepSnapshot = PhoneOtpSnapshot | EmailOtpSnapshot | ContactChoiceSnapshot | IdentitySummarySnapshot | MethodSnapshot | ChoiceSnapshot | EidSnapshot | RegistrySnapshot | DocumentSnapshot | LivenessSnapshot | PortraitSnapshot | ProofOfAddressSnapshot | FormSnapshot | MobileRequiredSnapshot | NativeAppRequiredSnapshot | ProcessingSnapshot | UnsupportedSnapshot | ResultSnapshot;
669
+ /**
670
+ * ID mode: `face_match` is due right after an ACCEPTED portrait (passed, or
671
+ * review after the cap) that it has not been tried with yet — the server picks
672
+ * the probe, so no selfie is taken. A face_match that
673
+ * already carries a reason was tried: the regular selfie path applies.
674
+ */
675
+ declare function portraitMatchStep(view: HostedSessionView, frontier: PlanStepView): PlanStepView | null;
676
+ /** The step the view asks for right now (the C4 client rule, Sekyro flows §8.3). */
677
+ declare function deriveStep(view: HostedSessionView, env?: DeriveStepEnv): StepSnapshot;
678
+
679
+ type DocumentCaptureState = "idle" | "starting" | "scanning" | "captured" | "uploading" | "checking" | "done" | "error";
680
+ /** Aggregated coaching (copy keys `dcv2.<key>`). */
681
+ 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";
682
+ type DocumentReticle = "searching" | "coaching" | "locking" | "processing" | "flip" | "done";
683
+ interface DocumentFeedback {
684
+ key: DocumentFeedbackKey;
685
+ reticle: DocumentReticle;
686
+ }
687
+ interface DocumentPoint {
688
+ x: number;
689
+ y: number;
690
+ }
691
+ interface DocumentQuad {
692
+ topLeft: DocumentPoint;
693
+ topRight: DocumentPoint;
694
+ bottomRight: DocumentPoint;
695
+ bottomLeft: DocumentPoint;
696
+ }
697
+ /** The card the guide-region lock measures inside the on-screen guide (ID-1 cards; absent for passport pages). */
698
+ interface DocumentGuideMeasure {
699
+ /** A card is measured in the guide on this tick. */
700
+ detected: boolean;
701
+ /** Card width / guide width (1 = fitted). */
702
+ fill: number;
703
+ /** Card centre offset in guide widths / heights (+ = right / down). */
704
+ offsetX: number;
705
+ offsetY: number;
706
+ }
707
+ /** Gate ring + overlay; quad coordinates live in `frameWidth × frameHeight` (the detect frame). */
708
+ interface DocumentGateUpdate {
709
+ progress: number;
710
+ quad: DocumentQuad | null;
711
+ frameWidth: number;
712
+ frameHeight: number;
713
+ /** The card measured in the guide (lets a UI frame the card it sees); absent when the guide lock is off. */
714
+ guide?: DocumentGuideMeasure;
715
+ }
716
+ /**
717
+ * The on-screen guide the card is framed in: `rect` normalized (0..1) in the video element of aspect `viewAspect`
718
+ * (width / height) that shows the camera with `object-fit: cover`.
719
+ */
720
+ interface DocumentGuide {
721
+ viewAspect: number;
722
+ rect: {
723
+ x: number;
724
+ y: number;
725
+ width: number;
726
+ height: number;
727
+ };
728
+ }
729
+ type DocumentScanPhase = "framing" | "locking" | "capturing" | "flipCue" | "reaskRecto" | "reading" | "result";
730
+ interface DocumentScanUpdate {
731
+ phase: DocumentScanPhase;
732
+ captured: DocumentSide[];
733
+ expected: DocumentSide | null;
734
+ /** Coaching left by the last capture or read (`blurry`: the blur gate refused the photo, retake at once). */
735
+ notice: "same_face" | "reread" | "technical" | "blurry" | null;
736
+ lastShot: DocumentSide | null;
737
+ manualShutter: boolean;
738
+ torchAvailable: boolean;
739
+ torch: boolean;
740
+ }
741
+ interface CapturedDocument {
742
+ /** Upload-ready JPEG (adaptive encode applied). Live camera only — there is no file input. */
743
+ image: Blob;
744
+ /** The face this photo shows (classified on device for cards; the server confirms). */
745
+ side: DocumentSide;
746
+ documentType: AcceptedDocumentType;
747
+ issuer?: string;
748
+ width: number;
749
+ height: number;
750
+ previewDataUrl: string;
751
+ }
752
+ /**
753
+ * Web live MRZ (spec 2026-10-21 D5): the on-device reader's state on a face with an MRZ (passport page, card back).
754
+ * Never carries text or a digest. `mismatch`: a valid read whose format contradicts the picked document (the photo is
755
+ * still taken; the server decides). `fallback`: the reader stepped aside (today's capture continues).
756
+ */
757
+ interface DocumentMrzUpdate {
758
+ state: "searching" | "reading" | "valid" | "mismatch" | "fallback";
759
+ format?: "TD1" | "TD2" | "TD3";
760
+ coach?: "moveCloser" | "turnSideways" | "glare" | "holdStill";
761
+ reason?: "timeout" | "slow" | "unsupported" | "download" | "integrity" | "error" | "off";
762
+ }
763
+ /** Web live MRZ options (spec D7/D9): `mode: "off"` opts out; `auto` (default) obeys the session's server tuning. */
764
+ interface DocumentLiveMrzOptions {
765
+ mode?: "auto" | "off";
766
+ /** Where the OCR assets are served (default the Sekyro AI assets CDN). Self-host: the `<fp12>/` directory goes under it. */
767
+ assetBaseUrl?: string;
768
+ /** Where your bundler serves `@sekyro/web/core/ocr/worker` (or the self-contained `worker.bundle.js`). Without it the reader stays off. */
769
+ workerUrl?: string | URL;
770
+ }
771
+ interface DocumentCaptureEvents {
772
+ state: DocumentCaptureState;
773
+ /** Web live MRZ reader state (MRZ faces only; text-free). */
774
+ mrz: DocumentMrzUpdate;
775
+ feedback: DocumentFeedback;
776
+ gate: DocumentGateUpdate;
777
+ scan: DocumentScanUpdate;
778
+ captured: CapturedDocument;
779
+ error: CaptureError;
780
+ }
781
+ interface DocumentCaptureOptions {
782
+ /** Host-owned `<video playsInline muted>`; the rear camera is opened. */
783
+ video: HTMLVideoElement;
784
+ documentType: AcceptedDocumentType;
785
+ /** Expected face; omit for a card's first face (either face). Passports are always `"single"`. */
786
+ side?: DocumentSide;
787
+ /**
788
+ * The issuing country (ISO alpha-2). A standalone capture is identical for every issuer; in a verification's document
789
+ * step the session may have capture follow the document catalog's series for this country (sides, shape, MRZ).
790
+ */
791
+ issuer?: string;
792
+ /** Default `true` (best-effort Screen Wake Lock while the camera is live). */
793
+ keepScreenAwake?: boolean;
794
+ /** `navigator.vibrate` on capture where available. Default `true`. */
795
+ haptics?: boolean;
796
+ /** Web live MRZ (on-device MRZ read that decides the shot on MRZ faces); server-controlled, additive. */
797
+ liveMrz?: DocumentLiveMrzOptions;
798
+ /**
799
+ * Where the barcode decoder binary is served, for a document whose faces are told apart by a
800
+ * barcode. Self-host `zxing_reader.wasm` of the `zxing-wasm` version this SDK pins as
801
+ * `<base>/<sha12>/zxing_reader.wasm` (`<sha12>`: the first 12 hex characters of its sha256); the
802
+ * SDK checks the bytes before it runs them. Absent in a standalone capture: the order of capture
803
+ * decides the face.
804
+ */
805
+ barcodeAssetBaseUrl?: string;
806
+ }
807
+ interface DocumentCaptureHandle {
808
+ readonly state: DocumentCaptureState;
809
+ on<K extends keyof DocumentCaptureEvents>(event: K, handler: (payload: DocumentCaptureEvents[K]) => void): () => void;
810
+ start(): Promise<void>;
811
+ /** Start over (both faces), or restart the camera after an error. */
812
+ retry(): void;
813
+ /** Ask for this face next (after the server accepted the other one). */
814
+ setSide(side: DocumentSide): void;
815
+ /** Take the photo now (meaningful while `scan.manualShutter`). */
816
+ shutter(): void;
817
+ /** Manual torch; no-op where the camera has none. Never turned on by the SDK. */
818
+ setTorch(on: boolean): void;
819
+ /**
820
+ * Tap-to-focus at a normalized point of the video frame (0..1, e.g. from a tap
821
+ * on the preview). No-op where the camera has no single-shot focus (iOS Safari).
822
+ */
823
+ focusAt(x: number, y: number): void;
824
+ /**
825
+ * Where the on-screen guide is (call again when the view resizes); `undefined` = the default guide, centred and
826
+ * 86 % of the frame wide. The lock measures the card inside it, so a guide drawn elsewhere must be declared.
827
+ */
828
+ setGuide(guide: DocumentGuide | undefined): void;
829
+ destroy(): void;
830
+ }
831
+
832
+ /**
833
+ * - `starting` — camera and landmark model loading;
834
+ * - `gating` — the strict ICAO gate is coaching (`gate` events);
835
+ * - `captured` — the portrait frame was taken (`captured` fired);
836
+ * - `uploading` / `checking` / `done` — driven by the verification when the
837
+ * handle belongs to a plan-runner step;
838
+ * - `error` — camera or model failure (`error` fired).
839
+ */
840
+ type PortraitCaptureState = "idle" | "starting" | "gating" | "captured" | "uploading" | "checking" | "done" | "error" | "mode_switch";
841
+ /** One gate evaluation: per-criterion state, the one coaching message, readiness. */
842
+ type PortraitGateUpdate = IcaoGateUpdate;
843
+ interface CapturedPortrait {
844
+ /**
845
+ * Upload-ready JPEG: a 3:4 portrait region of the full-resolution frame
846
+ * around the face (not mirrored), at least 480×640. The server cuts the
847
+ * normalised ICAO crop from it.
848
+ */
849
+ image: Blob;
850
+ width: number;
851
+ height: number;
852
+ /** The on-device gate result and the eye-openness baseline (`gate` of the submission). */
853
+ gate: IcaoGateSummary;
854
+ /** `capture.tuningVersion` the gate ran with, when the server sent one. */
855
+ tuningVersion?: string;
856
+ /** The camera the photo was taken with (as the live track reports it, else as requested). */
857
+ facingMode: CameraFacing;
858
+ }
859
+ interface PortraitCaptureEvents {
860
+ state: PortraitCaptureState;
861
+ gate: PortraitGateUpdate;
862
+ captured: CapturedPortrait;
863
+ error: CaptureError;
864
+ }
865
+ interface PortraitCaptureOptions {
866
+ /**
867
+ * Host-owned `<video playsInline muted>`. A self capture opens the front camera; mirror the preview with CSS while
868
+ * {@link PortraitCaptureHandle.facingMode} is `'user'` (an assisted capture's back camera is not mirrored).
869
+ */
870
+ video: HTMLVideoElement;
871
+ /**
872
+ * Ignored: the capture mode sets the camera. A `self` capture (every standalone {@link createPortraitCapture}) opens
873
+ * the front camera and an `assisted` capture the back camera; the other camera is ignored with a console warning.
874
+ */
875
+ facing?: CameraFacing;
876
+ /** `HostedSessionView.capture.icao`; missing fields use the bundled fallbacks. */
877
+ tuning?: IcaoCaptureTuning | null;
878
+ /** `HostedSessionView.capture.tuningVersion`, echoed on submit. */
879
+ tuningVersion?: string | null;
880
+ /**
881
+ * The session's ICAO policy (`icaoPolicyOf(view).policy`). `alert` coaches but
882
+ * never blocks: the photo is taken `capture.icao.alertGraceMs` after the face is
883
+ * accepted at the latest. Default `reject`.
884
+ */
885
+ policy?: "reject" | "alert";
886
+ /** Self-hosted MediaPipe assets (wasm fileset + `face_landmarker.task`); default `/models-v3`. */
887
+ assetBaseUrl?: string;
888
+ /** Default `true` (best-effort Screen Wake Lock while the camera is live). */
889
+ keepScreenAwake?: boolean;
890
+ }
891
+ interface PortraitCaptureHandle {
892
+ readonly state: PortraitCaptureState;
893
+ on<K extends keyof PortraitCaptureEvents>(event: K, handler: (payload: PortraitCaptureEvents[K]) => void): () => void;
894
+ /**
895
+ * Who films the face: a portrait step's handle follows the session (`HostedSessionView.capture.mode`); a standalone
896
+ * {@link createPortraitCapture} is always `self` (the front camera, no switch). Never `choice`.
897
+ */
898
+ readonly captureMode: CaptureMode;
899
+ /** The camera of the live stream (as its track reports it, else as requested); `'user'` before the first start. */
900
+ readonly facingMode: CameraFacing;
901
+ /** Open the capture mode's camera, load the model and start the gate. */
902
+ start(options?: PortraitStartOptions): Promise<void>;
903
+ /** Take the photo again (gate only — the camera stays open), or restart after an error. */
904
+ retry(): void;
905
+ /**
906
+ * Does nothing and returns `false` (with a console warning): the capture mode sets the camera, the front one in
907
+ * `self` and the back one in `assisted`. Under `choice` the person switches the mode
908
+ * ({@link PortraitCaptureHandle.setCaptureMode}).
909
+ */
910
+ switchCamera(): boolean;
911
+ /**
912
+ * Spec 2026-11-06 §3.3, a portrait step whose capture mode is `choice`: whether the person can switch between `self`
913
+ * and `assisted` on the camera view (a device with a front/back choice). `false` otherwise and on a standalone
914
+ * capture. Never rejects.
915
+ */
916
+ canSwitchCaptureMode(): Promise<boolean>;
917
+ /**
918
+ * Spec 2026-11-06 §3.3: switch the capture mode under `choice` ({@link PortraitCaptureHandle.canSwitchCaptureMode}).
919
+ * The pick is recorded for the session (`Verification.chooseCaptureMode`), and the camera reopens in the new mode
920
+ * (`self`: the front one, `assisted`: the back one) with the gate from zero, through the `mode_switch` state.
921
+ * Before the first start it only records the pick. Resolves `false` and changes nothing when the switch is not
922
+ * offered, the mode is already in force, or the photo was taken.
923
+ */
924
+ setCaptureMode(mode: ResolvedCaptureMode): Promise<boolean>;
925
+ destroy(): void;
926
+ }
927
+ /** Options of {@link PortraitCaptureHandle.start}. */
928
+ interface PortraitStartOptions {
929
+ /** Ignored: the capture mode sets the camera (`self` the front one, `assisted` the back one), with a console warning. */
930
+ facing?: CameraFacing;
931
+ }
932
+
933
+ /** One refused answer: the question (or consent) id, why, and the values its message names. */
934
+ interface FormIssue {
935
+ id: string;
936
+ code: FormIssueCode | (string & {});
937
+ /** `too_long` / `too_short`: `max` / `min` characters; `number_too_*`: `min` / `max`; `date_too_*`: `date`. */
938
+ params?: {
939
+ min?: number | string;
940
+ max?: number | string;
941
+ date?: string;
942
+ };
943
+ }
944
+ /** The code of the 422 a refused Form submit answers (spec 2026-11-14 §14). */
945
+ declare const FORM_ANSWERS_INVALID = "form_answers_invalid";
946
+ /**
947
+ * A Form submit was refused: before any network call (the client's own check) or by the server (422
948
+ * `form_answers_invalid`). Nothing was stored and no attempt was used; show each issue under its question.
949
+ */
950
+ declare class FormAnswersError extends Error {
951
+ readonly issues: FormIssue[];
952
+ /** `client`: refused before sending; `server`: the server's 422. */
953
+ readonly source: "client" | "server";
954
+ constructor(issues: FormIssue[], source: "client" | "server");
955
+ }
956
+
957
+ /**
958
+ * Gate guidance code. `'hold'` is emitted while the clip records. `'upright'`:
959
+ * the phone is held sideways (a landscape camera frame on a phone); the gate
960
+ * waits, and a clip being recorded is dropped, until it is upright again.
961
+ * `'one_face'`: the camera sees a second person of meaningful size; the gate
962
+ * waits until only one face is in the frame.
963
+ */
964
+ type GateHint = "center" | "closer" | "farther" | "light" | "still" | "hold" | "upright" | "one_face";
965
+ /**
966
+ * Capture + verification state, as seen by the partner:
967
+ * - `idle → starting → gating → recording → captured` is the engine's run;
968
+ * - `uploading → checking → done` follows ONLY when the handle was obtained via
969
+ * {@link Verification.liveness} (the SDK uploads and submits after `captured`);
970
+ * - `error` on a camera / engine failure (see {@link CaptureError}).
971
+ */
972
+ type CaptureState = "idle" | "starting" | "gating" | "recording" | "captured" | "uploading" | "checking" | "done" | "error" | "mode_switch";
973
+ /** Declared capture channel — the liveness band is mobile-calibrated. */
974
+ type CaptureChannel = "mobile" | "desktop";
975
+ /** Gate ring update: integrator progress 0..1 and the current guidance code. */
976
+ interface GateUpdate {
977
+ /** Gate integrator 0..1 — drive the ring off this directly. */
978
+ progress: number;
979
+ /** Current guidance code, `null` when no hint applies. */
980
+ hint: GateHint | null;
981
+ /**
982
+ * The detector currently sees a face (a non-zero engine presence factor). `false`
983
+ * with `hint: 'center'` means "no face in frame" rather than "off-center" —
984
+ * hosts use it to tell seeking from aligning, and for the no-face copy.
985
+ */
986
+ faceDetected: boolean;
987
+ }
988
+ /**
989
+ * What the engine captured. Fires BEFORE any upload. `clip` is absent only in
990
+ * the `degraded: 'NO_RECORDER'` case (no MediaRecorder on this browser).
991
+ */
992
+ interface CapturedArtifacts {
993
+ /** JPEG keyframe (the face_match probe): mirrored on the front camera, not on the back one (`facingMode`). */
994
+ keyframe: Blob;
995
+ /** The 2.5 s liveness clip (MP4-first mime ladder). */
996
+ clip?: Blob;
997
+ /** Container mime the clip finalized with — may carry codec params. */
998
+ clipMime?: string;
999
+ /** Intrinsic video width at capture time. */
1000
+ width: number;
1001
+ /** Intrinsic video height at capture time. */
1002
+ height: number;
1003
+ /** The clip's duration (ms) read from its container; recording start → stop when the container was not read. */
1004
+ clipMs?: number;
1005
+ /** Video frames in the clip (read from its container). */
1006
+ clipFrames?: number;
1007
+ /** The clip's frame rate: frames over its duration. */
1008
+ fps?: number;
1009
+ /** Silent re-recordings (0 or 1): the first take was short, unreadable or errored. */
1010
+ clipRetakes?: number;
1011
+ /** The clip's codec (`avc1.42E01E`, `h264`, `vp8`, …), from the recorder's type. */
1012
+ codec?: string;
1013
+ /** `'mobile'` on phones/tablets (the calibrated channel), else `'desktop'`. */
1014
+ captureChannel: CaptureChannel;
1015
+ /** Set when the browser has no MediaRecorder: a keyframe-only capture. */
1016
+ degraded?: "NO_RECORDER";
1017
+ /** 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. */
1018
+ engine?: CaptureEngineId;
1019
+ /**
1020
+ * Camera request (`getUserMedia`) → the preview is live, in whole
1021
+ * milliseconds measured with `performance.now()`. Part of the face-capture
1022
+ * timing the SDK forwards to the backend as `input.capture` on the liveness
1023
+ * submission; absent when the phase was not observed.
1024
+ */
1025
+ cameraReadyMs?: number;
1026
+ /**
1027
+ * Camera ready → the first face ACCEPTED by the gate (present and with
1028
+ * size, centering and quality good enough to make progress — not merely
1029
+ * detected), whole ms. Absent when no face was ever accepted.
1030
+ */
1031
+ faceAcquireMs?: number;
1032
+ /**
1033
+ * Face-capture duration: FIRST accepted face → gate progress 100 % (capture
1034
+ * complete, before the clip window and any upload), whole ms. A face lost
1035
+ * and re-acquired keeps the first acceptance as its start.
1036
+ */
1037
+ captureMs?: number;
1038
+ /**
1039
+ * The camera the capture was filmed with (`'environment'` = the back camera): the facing the video track reports,
1040
+ * else the requested one; undefined when the engine does not say.
1041
+ */
1042
+ facingMode?: CameraFacing | undefined;
1043
+ /**
1044
+ * The device: `'phone'`, `'tablet'` or `'desktop'` (user agent, touch and screen size; never the window width).
1045
+ * The upright requirement applies to phones only. Always set by the SDK.
1046
+ */
1047
+ formFactor?: "phone" | "tablet" | "desktop";
1048
+ /**
1049
+ * The capture mode the attempt ran in ({@link LivenessCaptureHandle.captureMode}): `self` or `assisted`, never
1050
+ * `choice`. Always set by the SDK.
1051
+ */
1052
+ mode?: CaptureMode;
1053
+ /**
1054
+ * Liveness v7 §4.4: the screen ramp rendered against the session's issued challenge, stamped on the clip's own
1055
+ * timeline. Present only when a challenge was issued, the capture is `self` and clip mode, and a host painted the
1056
+ * `ramp` event. Forwarded as `input.capture.screenRamp`.
1057
+ */
1058
+ screenRamp?: ScreenRampReport;
1059
+ /** Liveness v7 §4.5 item 2: how the capture was made (track settings, label class, frame statistics, prototype check). */
1060
+ provenance?: CaptureProvenance;
1061
+ }
1062
+ /** Capture engine identifier carried on {@link CapturedArtifacts.engine}. */
1063
+ type CaptureEngineId = "v1" | "v3";
1064
+ /** Camera / engine failure kinds — collapsed to the public six. */
1065
+ type CaptureErrorKind = "permission" | "notfound" | "inuse" | "insecure" | "unsupported" | "generic";
1066
+ /** The capture step that was running when a capture failed. */
1067
+ type CaptureErrorPhase = "preflight" | "acquiring" | "models" | "recording" | "keyframes" | "upload";
1068
+ /**
1069
+ * What the public {@link CaptureErrorKind} leaves out, for diagnostics. Never personal data: `name` is the thrown
1070
+ * error's `name` only (a class or DOMException name such as `NotReadableError`, never its message), letters only and
1071
+ * at most 40 characters.
1072
+ */
1073
+ interface CaptureErrorDetail {
1074
+ /** The thrown error's `name`, when the failure threw one. */
1075
+ name?: string;
1076
+ phase: CaptureErrorPhase;
1077
+ /**
1078
+ * The engine's own kind before the public collapse (`models`, `recorder`, `cliptoolarge`, `overconstrained`,
1079
+ * `generic`, or a public kind unchanged).
1080
+ */
1081
+ engineKind?: string;
1082
+ }
1083
+ /** Camera / engine failure payload (`on('error')`). */
1084
+ interface CaptureError {
1085
+ kind: CaptureErrorKind;
1086
+ /**
1087
+ * A fresh attempt (`retry()`) can succeed — false for `insecure` (needs
1088
+ * HTTPS) and `unsupported` (the browser cannot capture at all).
1089
+ */
1090
+ retryable: boolean;
1091
+ /** Where and how the capture failed, when the engine knows. */
1092
+ detail?: CaptureErrorDetail;
1093
+ }
1094
+
1095
+ /**
1096
+ * The cause a camera failure reports (2026-10-30): `permission` is `denied`; `notfound`, `insecure` and `unsupported`
1097
+ * are `no_camera`; any other kind (`inuse`, `generic`) is not a missing camera and maps to nothing.
1098
+ */
1099
+ declare function cameraUnavailableCauseOf(kind: CaptureErrorKind): CameraUnavailableCause | undefined;
1100
+ /** Event map of a {@link LivenessCaptureHandle}. */
1101
+ interface LivenessCaptureEvents {
1102
+ /** Every state transition. */
1103
+ state: CaptureState;
1104
+ /** Gate ring updates while gating/recording. */
1105
+ gate: GateUpdate;
1106
+ /** The capture result — fires BEFORE any upload. */
1107
+ captured: CapturedArtifacts;
1108
+ /** Camera / engine failure. */
1109
+ error: CaptureError;
1110
+ /**
1111
+ * Clip mode only: the recording window just ended and the keyframe is already
1112
+ * available, BEFORE the clip finalizes (iOS can lag ~1.5 s). Hosts freeze the
1113
+ * display on `previewDataUrl` (the keyframe's JPEG data URL) instead of leaving
1114
+ * the live feed running; `captured` follows once the clip lands.
1115
+ */
1116
+ frozen: {
1117
+ previewDataUrl: string;
1118
+ };
1119
+ /**
1120
+ * Device-profile hint, emitted when it changes: `'reduced'` asks the host to
1121
+ * drop decorative animations (a LOW device class needs the frames for
1122
+ * detection). Chrome only — never gate input.
1123
+ */
1124
+ profile: {
1125
+ animations: "full" | "reduced";
1126
+ };
1127
+ /**
1128
+ * Ramp v2: paint a full-screen layer this colour (`screenRampColourValue(colour)`), black (`"dark"`, the dark-gap
1129
+ * arm; `screenRampColourValue("dark")`) or clear it (`null`). Fires while the clip records, at the times the
1130
+ * session's challenge issued. Subscribing is the acknowledgement: the engine runs the ramp only when a listener is bound when the
1131
+ * recording starts, and the stamps it reports describe exactly these calls. `@sekyro/react` paints it; a host on
1132
+ * `@sekyro/web` alone paints it itself (a `position: fixed; inset: 0` element behind its chrome) or leaves the
1133
+ * event unbound. Never fires in an assisted capture or a keyframe-only capture.
1134
+ */
1135
+ ramp: {
1136
+ colour: ScreenRampPaint;
1137
+ };
1138
+ }
1139
+ /** Which camera to open: the selfie camera (`'user'`) or the rear one (`'environment'`). */
1140
+ type CameraFacing = "user" | "environment";
1141
+ /** Options of {@link LivenessCaptureHandle.start}. */
1142
+ interface LivenessStartOptions {
1143
+ /**
1144
+ * Ignored: the capture mode sets the camera. A `self` capture opens the front camera and an `assisted` capture the
1145
+ * back camera; the other camera is ignored with a console warning.
1146
+ */
1147
+ facing?: CameraFacing;
1148
+ }
1149
+ /** Live capture handle returned by {@link createLivenessCapture} / {@link Verification.liveness}. */
1150
+ interface LivenessCaptureHandle {
1151
+ /** Current {@link CaptureState}. */
1152
+ readonly state: CaptureState;
1153
+ /**
1154
+ * Who films the face. A handle from {@link Verification.liveness} follows the
1155
+ * session (`HostedSessionView.capture.mode`, set in the flow; `self` until
1156
+ * the view is known; under `choice` the person's pick, `self` until
1157
+ * {@link Verification.chooseCaptureMode}); a standalone {@link createLivenessCapture} is always
1158
+ * `self`. The mode sets the camera: `self` the front one, `assisted` the back one
1159
+ * ({@link LivenessCaptureHandle.switchCamera} does nothing). Never `choice`.
1160
+ */
1161
+ readonly captureMode: CaptureMode;
1162
+ /**
1163
+ * The camera of the current attempt: the facing its video track reports once the stream is live (a laptop webcam
1164
+ * answers an `environment` request with itself), else the requested one; `'user'` before the first start. Mirror
1165
+ * the preview while it is `'user'`.
1166
+ */
1167
+ readonly facingMode: CameraFacing;
1168
+ /** Subscribe; returns the unsubscribe function. */
1169
+ on<K extends keyof LivenessCaptureEvents>(event: K, handler: (payload: LivenessCaptureEvents[K]) => void): () => void;
1170
+ /**
1171
+ * Ask for the capture mode's camera and start gating. Resolves once the attempt is running or failed.
1172
+ */
1173
+ start(options?: LivenessStartOptions): Promise<void>;
1174
+ /** Fresh attempt: resets the engine and restarts the camera. */
1175
+ retry(): void;
1176
+ /**
1177
+ * Does nothing and returns `false` (with a console warning): the capture mode sets the camera, the front one in
1178
+ * `self` and the back one in `assisted`. Under `choice` the person switches the mode
1179
+ * ({@link LivenessCaptureHandle.setCaptureMode}).
1180
+ */
1181
+ switchCamera(): boolean;
1182
+ /**
1183
+ * Spec 2026-11-06 §3.3, a session whose capture mode is `choice`: whether the person can switch between `self`
1184
+ * and `assisted` on the camera view (a device with a front/back choice). `false` on a `self` or `assisted`
1185
+ * session, on a one-camera device (the person captures in `self`) and on a standalone capture. Never rejects.
1186
+ */
1187
+ canSwitchCaptureMode(): Promise<boolean>;
1188
+ /**
1189
+ * Spec 2026-11-06 §3.3: switch the capture mode under `choice` ({@link LivenessCaptureHandle.canSwitchCaptureMode}).
1190
+ * The pick is recorded for the session (`Verification.chooseCaptureMode`, so `captureMode` follows it), and a
1191
+ * running take restarts in the new mode: a recording is discarded (never submitted, no attempt used), the state
1192
+ * passes through `mode_switch`, and the camera reopens (`self`: the front one, `assisted`: the back one). Before
1193
+ * the first start it only records the pick. Resolves `false` and changes nothing when the switch is not offered,
1194
+ * the mode is already in force, or a take is being submitted (`captured`, `uploading`, `checking`).
1195
+ */
1196
+ setCaptureMode(mode: ResolvedCaptureMode): Promise<boolean>;
1197
+ /** Stop the camera, release the detector, drop all listeners. */
1198
+ destroy(): void;
1199
+ }
1200
+ /** Options of {@link createLivenessCapture} / {@link Verification.liveness}. */
1201
+ interface LivenessCaptureOptions {
1202
+ /** Host-owned `<video playsInline muted>` element. */
1203
+ video: HTMLVideoElement;
1204
+ /**
1205
+ * Ignored: the capture mode sets the camera. A `self` capture (every standalone capture, and sessions whose flow
1206
+ * films the person themselves) uses `'user'` and an `assisted` capture `'environment'`; the other camera is ignored
1207
+ * with a console warning.
1208
+ */
1209
+ facing?: CameraFacing;
1210
+ /** Base URL of the detector assets (tasks-vision wasm + tflite); default `/models-v3`. */
1211
+ assetBaseUrl?: string;
1212
+ /**
1213
+ * Hold a Screen Wake Lock while the camera is live (`starting` / `gating` /
1214
+ * `recording`) so the phone does not dim or lock mid-capture; re-taken when
1215
+ * the page becomes visible again. Best-effort: unsupported browsers or a
1216
+ * refused request (e.g. an iframe without `allow="screen-wake-lock"`) never
1217
+ * affect the capture. Default `true`; `false` never requests the lock.
1218
+ */
1219
+ keepScreenAwake?: boolean;
1220
+ }
1221
+ /**
1222
+ * SDK-side failure reasons (status `'unavailable'`):
1223
+ * - `no_recorder` — no MediaRecorder / unsupported clip container;
1224
+ * - `attestation` — the challenge frame produced no token and the server refused the submission without one, or
1225
+ * `attestation_invalid` after one retry ({@link VerificationResult.attestationError} says why the frame failed);
1226
+ * - `network` — transport / API failure after the bounded replays;
1227
+ * - `nni_unbound` — `population_registry` is the frontier but the session was
1228
+ * minted WITHOUT a bound ID number (`POST /sessions` `subject.idNumber`), so
1229
+ * the SDK cannot submit it. Mint the session with the number (or complete the
1230
+ * population step yourself) before starting the capture. `id_number_unbound`
1231
+ * is its generic name (person data spec Appendix A.2): this SDK still reports
1232
+ * `nni_unbound`; handle both;
1233
+ * - `method_required` — the session waits on the identity-method choice
1234
+ * (profile v2 step 3; `on('method')` fired). Ask the person, call
1235
+ * {@link Verification.selectMethod}, then capture again;
1236
+ * - `inference_unavailable` — the model service stayed busy through the
1237
+ * automatic retries (profile v2 step 4; `on('busy')` fired for each). No
1238
+ * attempt was used and nothing was billed: let the person try again in a
1239
+ * moment;
1240
+ * - `portrait_required` — ID mode (SDK spec §4.9): liveness is done and the
1241
+ * session continues with the ICAO portrait step — not a failure. The plan
1242
+ * runner (`run()`) moves on by itself; a liveness-only integration hands
1243
+ * over to {@link createPortraitCapture} (or the hosted page).
1244
+ *
1245
+ * A liveness step that needs a phone (`HostedStepView.requiresMobile`) on a
1246
+ * desktop browser ends with the reason `mobile_required` (status
1247
+ * `unavailable`): send the person to their phone. The SDK stops before any
1248
+ * upload when the view says so; otherwise the backend answers the submit with
1249
+ * a request-level `409 mobile_required` (no attempt used, nothing billed).
1250
+ */
1251
+ type SdkFailureReason = "no_recorder" | "attestation" | "network" | "nni_unbound" | "id_number_unbound" | "method_required" | "inference_unavailable" | "portrait_required";
1252
+ /** Backend reason taxonomy ∪ the SDK-side failure reasons. */
1253
+ type ReasonCode = CheckReason | SessionFailureReason | SdkFailureReason | AgeEstimationReason;
1254
+ /**
1255
+ * - `verified` / `not_verified` / `review`: the session's end state (a `not_verified`
1256
+ * result says why in {@link VerificationResult.reason});
1257
+ * - `retry`: the capture was not conclusive and attempts remain (`autoRetry` on);
1258
+ * the capture re-arms by itself;
1259
+ * - `unavailable`: the check could not run (the service was unavailable, no
1260
+ * MediaRecorder, attestation failed, network or API failure, or a step only a
1261
+ * phone can capture). Treat as "not finished".
1262
+ */
1263
+ type VerificationStatus = "verified" | "not_verified" | "review" | "retry" | "unavailable";
1264
+ /** The verdict for this session / capture (`on('result')`). */
1265
+ interface VerificationResult {
1266
+ /**
1267
+ * The session id in the form `sessions.create` returns and webhooks name
1268
+ * (`ses_...`), so your server can match the result to its session.
1269
+ */
1270
+ sessionId: string;
1271
+ status: VerificationStatus;
1272
+ /**
1273
+ * `not_verified` only: why ({@link SessionReason}). On a capture refused while the session
1274
+ * is still open (`autoRetry` off, or no attempt left), the reason the step's result gives
1275
+ * (`rejected`, `inconclusive`, `unavailable`).
1276
+ */
1277
+ reason?: SessionReason;
1278
+ /**
1279
+ * The detailed code: the backend check or session-policy reason (`spoof_detected`,
1280
+ * `match_inconclusive`, `device_cooldown`, ...), or the SDK-side reason of an
1281
+ * `unavailable` result.
1282
+ */
1283
+ reasonCode?: ReasonCode;
1284
+ /**
1285
+ * `retry` (and a `not_verified` on a still-parked step): submissions left for
1286
+ * the parked check after this one, for the host's coaching copy.
1287
+ */
1288
+ attemptsRemaining?: number;
1289
+ /**
1290
+ * `retry` on a liveness step (liveness v7 §5.2): what to change for the next
1291
+ * capture, when the API reports it. Show `hints.<retakeHint>` copy instead of
1292
+ * the reason's generic text; absent on older APIs and on decisive results.
1293
+ */
1294
+ retakeHint?: RetakeHint;
1295
+ /**
1296
+ * ISO-8601 time from which this device may verify again, set on a
1297
+ * `not_verified` result with reason code `device_cooldown` (profile v2 step 4).
1298
+ */
1299
+ retryAfter?: string;
1300
+ /**
1301
+ * What the session proved (`verified`, `not_verified`, `review`), when the API
1302
+ * reports it: `1` Contact, `2` Human, `3` Identity, `0` nothing proven. A
1303
+ * display hint: confirm on your server with the result token.
1304
+ */
1305
+ level?: VerificationLevel;
1306
+ /** How the level was proved, when the API reports it. */
1307
+ assurance?: VerificationAssurance;
1308
+ /**
1309
+ * `unavailable` with reason code `attestation` only: why the security check frame produced no token, when it
1310
+ * failed on this page. `challenge_frame_blocked` means the page's Content-Security-Policy (or an extension) blocked
1311
+ * the frame: allow `frame-src` for the Sekyro verification host. Absent when the server refused a token.
1312
+ */
1313
+ attestationError?: ChallengeErrorCode;
1314
+ /**
1315
+ * Sandbox only: the session ran on simulated test data because no enrolled Sandbox tester ran it, and why. The same
1316
+ * object as on `GET /sessions/{id}` and the session webhooks. Absent in Live and on a session a tester ran.
1317
+ */
1318
+ sandbox?: SandboxSimulation;
1319
+ }
1320
+ /**
1321
+ * `on('busy')` payload: the model service answered
1322
+ * `503 inference_unavailable` and the SDK waits `retryAfterSeconds` before
1323
+ * retry number `attempt` (1-based, at most 3). The wait is the service's
1324
+ * `Retry-After` (10 s without one) capped at 20 s and spread by ±25 %, so it
1325
+ * may have a fraction. Show "busy, trying again" copy.
1326
+ */
1327
+ interface VerificationBusy {
1328
+ attempt: number;
1329
+ retryAfterSeconds: number;
1330
+ }
1331
+ /**
1332
+ * Consent locale picklist (mirrors the backend HostedConsentSchema): the six end-user locales (spec 2026-10-29 §9).
1333
+ * A backend older than Plan C accepts ar/fr/en only.
1334
+ */
1335
+ type VerificationLocale = "ar" | "fr" | "en" | "es" | "pt" | "de";
1336
+ /** Options of {@link createVerification}. */
1337
+ interface VerificationOptions {
1338
+ /** The session's client token (from `POST /api/v2/sessions` → `clientToken`). */
1339
+ clientToken: string;
1340
+ /** API origin; default `https://api.sekyro.ai`. */
1341
+ apiOrigin?: string;
1342
+ /** Consent locale (echoed into the auditable consent record). */
1343
+ locale: VerificationLocale;
1344
+ /** Re-arm the capture on retryable reasons while attempts remain. Default `true`. */
1345
+ autoRetry?: boolean;
1346
+ /**
1347
+ * How a `retry` verdict re-arms the capture (`autoRetry` on):
1348
+ * - `'auto'` (default) — the camera restarts immediately;
1349
+ * - `'manual'` — the handle settles at `done`; the host shows its coaching
1350
+ * and calls `retry()` on the handle when the user is ready.
1351
+ */
1352
+ rearm?: "auto" | "manual";
1353
+ /** Injection seam for `fetch` (tests / non-window contexts). */
1354
+ fetch?: typeof globalThis.fetch;
1355
+ }
1356
+ /** Event map of a {@link Verification}. */
1357
+ interface VerificationEvents {
1358
+ /** Verdict per capture (and once when the registry settles the session early). */
1359
+ result: VerificationResult;
1360
+ /** Every hosted-view update the SDK observes (bootstrap, consent, submits). */
1361
+ view: HostedSessionView;
1362
+ /**
1363
+ * The session waits on the identity-method choice (profile v2 step 3) and
1364
+ * the SDK stopped before submitting anything: show the options and call
1365
+ * {@link Verification.selectMethod}.
1366
+ */
1367
+ method: MethodChoiceView;
1368
+ /**
1369
+ * The model service is briefly unavailable and the SDK retries by itself
1370
+ * (profile v2 step 4). A `result` follows: the verdict, or
1371
+ * `unavailable / inference_unavailable` once the retries are spent.
1372
+ */
1373
+ busy: VerificationBusy;
1374
+ /** The plan runner's current step — only after {@link Verification.run}. */
1375
+ step: VerificationStep;
1376
+ }
1377
+ /** One session's verification, from {@link createVerification}. */
1378
+ interface Verification {
1379
+ /** Record consent once (no-op when the session already has it). */
1380
+ consent(): Promise<void>;
1381
+ /**
1382
+ * Submit `population_registry` early with an empty input when it is the
1383
+ * pending frontier and the backend holds the number: the SERVER-bound one, or
1384
+ * the one the document step read (`idNumberFromDocument`). Retries once on
1385
+ * `registry_unavailable`. Never rejects — failures surface through
1386
+ * `result`. Idempotent.
1387
+ */
1388
+ startRegistry(): Promise<void>;
1389
+ /**
1390
+ * The identity-method choice the session waits on (profile v2 step 3),
1391
+ * bootstrapping the hosted view when needed; `null` when there is no
1392
+ * pending choice, the bootstrap fails, or the verification was destroyed.
1393
+ * Never rejects.
1394
+ */
1395
+ methodChoice(): Promise<MethodChoiceView | null>;
1396
+ /**
1397
+ * Send the person's identity method: the identity choice's option of that
1398
+ * method (`POST /hosted/choice`), then continue from the returned view.
1399
+ * Rejects with the typed `HostedApiError` (e.g. 409 `choice_locked`), or a
1400
+ * `RangeError` when the session offers no such option.
1401
+ */
1402
+ selectMethod(method: IdentityMethod): Promise<void>;
1403
+ /**
1404
+ * Spec 2026-10-29 §3.4: the device has no usable camera (denied or absent) and the person ends the live step
1405
+ * without a capture. Records consent when needed, then `POST /hosted/camera-unavailable`: the server fails the
1406
+ * liveness step with `camera_unavailable` (no attempt, nothing billed) and the runner shows what the flow chose (a
1407
+ * fallback step, else the result at level 0). A 409 `check_out_of_order` (the live step is no longer the current one)
1408
+ * re-reads the view and resolves; other failures reject with the typed `HostedApiError`. Optional so custom / older
1409
+ * `Verification` implementations stay valid:
1410
+ * without it, offer no "continue without a camera" action.
1411
+ * `cause` (2026-10-30) says why: `denied` when the permission was refused, `no_camera` otherwise; the server
1412
+ * records it under the same reason. Omit it when unknown.
1413
+ */
1414
+ reportCameraUnavailable?(cause?: CameraUnavailableCause): Promise<void>;
1415
+ /**
1416
+ * Spec 2026-11-09 §3.3: "Run real checks as a tester", offered while `context.testerGate` is set (a simulated
1417
+ * Sandbox session before its first capture). Pass the artifacts of a liveness capture (`createLivenessCapture`,
1418
+ * capture-only): the SDK uploads the clip with its capture proof, attests like the liveness step and asks the server
1419
+ * whether the face is one of the organization's enrolled testers. `bound: true`: the session now runs real checks;
1420
+ * `bound: false`: it stays simulated (the face is not kept). The new view is applied either way (the step updates).
1421
+ * Rejects with the typed `HostedApiError` (`409 gate_attempts_exhausted`, `409 tester_gate_closed`,
1422
+ * `429 tester_limit_reached`, ...). Optional so custom `Verification` implementations stay valid.
1423
+ */
1424
+ testerGate?(artifacts: CapturedArtifacts): Promise<{
1425
+ bound: boolean;
1426
+ }>;
1427
+ /**
1428
+ * 2026-11-04: record a capture failure the page showed on the session (`POST /hosted/capture-issue`), for
1429
+ * diagnosis. Fire-and-forget: never throws, never changes the session, never bills, never counts as an attempt.
1430
+ * Sends at most one report per distinct (check, attempt, kind, name, phase); `formFactor` is filled in when absent.
1431
+ * Optional so custom / older `Verification` implementations stay valid.
1432
+ */
1433
+ reportCaptureIssue?(issue: CaptureIssueReport): void;
1434
+ /**
1435
+ * The session's current camera step (liveness, a selfie face match, a
1436
+ * camera document or portrait photo; spec 2026-11-06 §3.1, every decision
1437
+ * mode), or its pending liveness step, must be captured on a phone
1438
+ * (`HostedStepView.requiresMobile`) and this browser is not one: show
1439
+ * "continue on your phone" instead of starting the camera. A `choice` photo
1440
+ * step is not: its upload stays on the desktop. Bootstraps the hosted view when needed; `false` when
1441
+ * the bootstrap fails or the verification was destroyed. Never rejects.
1442
+ * Optional so custom / older `Verification` implementations stay valid —
1443
+ * treat an absent member as "no phone requirement".
1444
+ */
1445
+ mobileRequired?(): Promise<boolean>;
1446
+ /**
1447
+ * Who films the face in this session (`HostedSessionView.capture.mode`, a
1448
+ * flow setting): `self` (the person, front camera), `assisted` (an agent,
1449
+ * back camera) or `choice` (the camera opens in `self` and the person
1450
+ * switches on the camera view: {@link LivenessCaptureHandle.setCaptureMode}).
1451
+ * Once picked (on this page, or the session's latest pick `capture.pick`),
1452
+ * resolves to the pick. Bootstraps the hosted
1453
+ * view when needed; `self` when the bootstrap fails or the verification was
1454
+ * destroyed. Never rejects.
1455
+ * Optional so custom / older `Verification` implementations stay valid:
1456
+ * treat an absent member as `self`.
1457
+ */
1458
+ captureMode?(): Promise<CaptureMode>;
1459
+ /**
1460
+ * Under `choice`: record the person's pick. It holds for the whole session (in
1461
+ * memory, for this `Verification`), so the portrait camera does not ask again;
1462
+ * the liveness and portrait cameras run in it and `input.capture.mode` sends it.
1463
+ * Ignored when the session's mode is not `choice`.
1464
+ * Optional so custom / older `Verification` implementations stay valid.
1465
+ */
1466
+ chooseCaptureMode?(mode: ResolvedCaptureMode): void;
1467
+ /**
1468
+ * Under `choice`: the pick made with {@link Verification.chooseCaptureMode}, else the session's latest
1469
+ * (`HostedSessionView.capture.pick`, once the view is known); `null` before either.
1470
+ */
1471
+ readonly captureChoice?: ResolvedCaptureMode | null;
1472
+ /**
1473
+ * The session is a returning-user session (`HostedSessionView.returning`,
1474
+ * profile v2 step 5): the person verified before and only confirms it is
1475
+ * still them (liveness + face match against their stored photo) — show
1476
+ * "Confirm it's you". Bootstraps the hosted view when needed; `false` when
1477
+ * the bootstrap fails or the verification was destroyed. Never rejects.
1478
+ * Optional so custom / older `Verification` implementations stay valid —
1479
+ * treat an absent member as `false`.
1480
+ */
1481
+ returning?(): Promise<boolean>;
1482
+ /**
1483
+ * Start the plan runner (M5a): bootstraps the hosted view and resolves the
1484
+ * step it waits on; every later step arrives through `on('step')`. Idempotent.
1485
+ * Optional so custom / older `Verification` implementations stay valid —
1486
+ * objects from `createVerification` ≥ 0.2 always have it.
1487
+ */
1488
+ run?(): Promise<VerificationStep>;
1489
+ /** The step last delivered by the runner; `null` before {@link Verification.run}. */
1490
+ currentStep?(): VerificationStep | null;
1491
+ /** Start a liveness capture bound to this verification; the SDK uploads + submits on `captured`. */
1492
+ liveness(options: LivenessCaptureOptions): LivenessCaptureHandle;
1493
+ /**
1494
+ * The session's Sekyro AI-hosted voice clips (`view.voice`), bootstrapping the
1495
+ * hosted view when it has not been fetched yet. Resolves `null` when the
1496
+ * session has no active clip set, the API predates the field, the bootstrap
1497
+ * fails, or the verification was destroyed. Never rejects.
1498
+ */
1499
+ voiceClips(): Promise<HostedVoiceView | null>;
1500
+ /** Subscribe; returns the unsubscribe function. */
1501
+ on<K extends keyof VerificationEvents>(event: K, handler: (payload: VerificationEvents[K]) => void): () => void;
1502
+ /** Destroy the active capture and drop all listeners. */
1503
+ destroy(): void;
1504
+ }
1505
+ /** Phone OTP (profile v2 §4.1): send, then verify the 6-digit code. */
1506
+ interface PhoneOtpStepHandle extends PhoneOtpSnapshot {
1507
+ /** Switch to another option of the open choice (`context.switchable`; `POST /hosted/choice`). Present only with it. */
1508
+ chooseOption?(option: string): Promise<void>;
1509
+ /** ISO time from which a resend is allowed (the server's cooldown, else 30 s after this page's last send). */
1510
+ resendAvailableAt?: string;
1511
+ /**
1512
+ * Send or resend. `phone` (E.164) is required unless `numberSource` is
1513
+ * `prefilled`; a resend reuses the last one. `channel` is the person's
1514
+ * choice: required when `channels` lists more than one (never picked for
1515
+ * them), optional with one, and must be one of `channels` — else it rejects
1516
+ * with `OtpInputError` (`channel`, `required` / `unavailable`).
1517
+ */
1518
+ send(input?: {
1519
+ phone?: string;
1520
+ channel?: "sms" | "whatsapp";
1521
+ }): Promise<void>;
1522
+ /** Check the 6-digit code; anything else rejects with `InvalidInputError` before any call. */
1523
+ verify(code: string): Promise<void>;
1524
+ /** With `canSwitch` (a `one_of` session): confirm the other contact instead. Rejects with `RangeError` otherwise. */
1525
+ switchTo(): Promise<void>;
1526
+ }
1527
+ /** Email OTP (profile v2 §4.6.5): send a code to the address, then verify it. */
1528
+ interface EmailOtpStepHandle extends EmailOtpSnapshot {
1529
+ /** Switch to another option of the open choice (`context.switchable`; `POST /hosted/choice`). Present only with it. */
1530
+ chooseOption?(option: string): Promise<void>;
1531
+ /** Send or resend. `email` is required when `needsEmail` (checked locally: `OtpInputError("email", "format")`); a resend reuses the last one. */
1532
+ send(input?: {
1533
+ email?: string;
1534
+ }): Promise<void>;
1535
+ /** Check the 6-digit code; anything else rejects with `InvalidInputError` before any call. */
1536
+ verify(code: string): Promise<void>;
1537
+ /** See {@link PhoneOtpStepHandle.switchTo}. */
1538
+ switchTo(): Promise<void>;
1539
+ }
1540
+ /** Step 1 contact choice (flow model 2026-10-23): phone or email. */
1541
+ interface ContactChoiceStepHandle extends ContactChoiceSnapshot {
1542
+ /** Rejects with `RangeError` for a channel not in `options`. */
1543
+ select(channel: ContactChannel): Promise<void>;
1544
+ /** Pick by option id (`choice.options[].id`). */
1545
+ choose(option: string): Promise<void>;
1546
+ }
1547
+ /**
1548
+ * Step 2b summary and confirm (flow model 2026-10-23). PII: show the values,
1549
+ * never log them or pass them to analytics.
1550
+ */
1551
+ interface IdentitySummaryStepHandle extends IdentitySummarySnapshot {
1552
+ /** Switch to another option of the open choice (`context.switchable`; `POST /hosted/choice`). Present only with it. */
1553
+ chooseOption?(option: string): Promise<void>;
1554
+ /**
1555
+ * The portrait on record as a JPEG `Blob` (fetched with the session token;
1556
+ * show it with `URL.createObjectURL` and revoke it when done). `null` when
1557
+ * none is available or it cannot be loaded.
1558
+ */
1559
+ portrait(): Promise<Blob | null>;
1560
+ /** The details are right: the live photo comes next. */
1561
+ confirm(): Promise<void>;
1562
+ /** The details are wrong: the identity step opens again. Rejects with `RangeError` when `retakeAvailable` is false. */
1563
+ retake(): Promise<void>;
1564
+ }
1565
+ /** "How do you want to verify?" (profile v2 §4.4). */
1566
+ interface MethodStepHandle extends MethodSnapshot {
1567
+ /** Rejects with `RangeError` for a method not in `options`. */
1568
+ select(method: IdentityMethod): Promise<void>;
1569
+ /** Pick by option id (`choice.options[].id`): the same answer as {@link MethodStepHandle.select}. */
1570
+ choose(option: string): Promise<void>;
1571
+ }
1572
+ /**
1573
+ * The national eID sign-in (SDK spec §3.2; Houwiyeti in MR). Every action
1574
+ * submits `eid_auth` and re-reads the view; a passed eID ends the session.
1575
+ */
1576
+ /**
1577
+ * A choice of another kind (Sekyro flows `generic`, copy `choice.*`): pick one
1578
+ * of `choice.options` (`POST /hosted/choice`); the next step follows.
1579
+ */
1580
+ interface ChoiceStepHandle extends ChoiceSnapshot {
1581
+ choose(option: string): Promise<void>;
1582
+ }
1583
+ interface EidStepHandle extends EidSnapshot {
1584
+ /** Switch to another option of the open choice (`context.switchable`; `POST /hosted/choice`). Present only with it. */
1585
+ chooseOption?(option: string): Promise<void>;
1586
+ /**
1587
+ * `identifier` phase: ask the provider for a code. `identifier` (the NNI in
1588
+ * MR, checked locally: 10 digits and the check digit — else
1589
+ * `InvalidInputError("nni", …)`) is required unless
1590
+ * `identifierBound`; on a bound session it is never sent.
1591
+ */
1592
+ start(identifier?: string): Promise<void>;
1593
+ /** `code` phase: check the 6-digit code from the provider's app; anything else rejects with `InvalidInputError("code", "format")`. */
1594
+ verify(code: string): Promise<void>;
1595
+ /** Ask for a new code (the server spaces them out — `resendAvailableAt`). Rejects with `RangeError` when `resendsRemaining` is 0. */
1596
+ resend(): Promise<void>;
1597
+ /** With `canUseCamera`: switch to `cameraMethod`. Rejects with `RangeError` otherwise. */
1598
+ useCamera(): Promise<void>;
1599
+ }
1600
+ /** The registry step (SDK spec §5.5). */
1601
+ interface RegistryStepHandle extends RegistrySnapshot {
1602
+ /** Switch to another option of the open choice (`context.switchable`; `POST /hosted/choice`). Present only with it. */
1603
+ chooseOption?(option: string): Promise<void>;
1604
+ /**
1605
+ * Typed source only: checks the national number locally (the registry country's
1606
+ * rule: 10 digits and the check digit) before submitting it (`{ idNumber, nni }`, the
1607
+ * former name too until it is removed). A refused
1608
+ * number rejects with `InvalidInputError("idNumber", "format" | "check_digit")`.
1609
+ */
1610
+ submitIdNumber(idNumber: string): Promise<void>;
1611
+ /**
1612
+ * @deprecated Use {@link RegistryStepHandle.submitIdNumber} (the same request).
1613
+ * Rejects with `InvalidInputError("nni", …)`.
1614
+ */
1615
+ submitNni(nni: string): Promise<void>;
1616
+ /** Bound or document source: submit with an empty input (the server holds the number). */
1617
+ confirm(): Promise<void>;
1618
+ /** After `registry_record_not_found` (formerly `nni_not_found`; `canUseDocument`): switch to the document photo. */
1619
+ useDocument(): Promise<void>;
1620
+ }
1621
+ /** The document step — any issuing country (profile v2 §5.3a). */
1622
+ interface DocumentStepHandle extends DocumentSnapshot {
1623
+ /** Switch to another option of the open choice (`context.switchable`; `POST /hosted/choice`). Present only with it. */
1624
+ chooseOption?(option: string): Promise<void>;
1625
+ /**
1626
+ * Spec 2026-11-06 §3.1, present only with `photo.cameraOnPhone` (a `choice` step on a desktop): re-read the session,
1627
+ * so the page follows the person who continued on their phone (the hand-over polls it).
1628
+ */
1629
+ refresh?(): Promise<void>;
1630
+ /** The picked issuer (`null` until picked; a verso keeps the recto's pick). */
1631
+ issuer: string | null;
1632
+ /** The picked type (`null` until picked). */
1633
+ documentType: AcceptedDocumentType | null;
1634
+ /** `"single"` for a passport, else the snapshot's side; `null` until a type is picked. */
1635
+ captureSide: DocumentSide | null;
1636
+ /** Pick (or re-pick after `document_type_not_accepted`). Throws `RangeError` when the profile does not accept `type` for `issuer`. */
1637
+ selectDocument(issuer: string, type: AcceptedDocumentType): void;
1638
+ /**
1639
+ * The step's camera (rear). The SDK uploads and submits `doc_ocr` for every
1640
+ * capture and re-arms the same stream for the other face. One handle per
1641
+ * step: calling again with the same video returns the same handle until it
1642
+ * is destroyed. Throws when no document was picked yet.
1643
+ */
1644
+ capture(options: {
1645
+ video: HTMLVideoElement;
1646
+ keepScreenAwake?: boolean;
1647
+ /** Web live MRZ (on-device MRZ read on MRZ faces; obeys the session's server tuning). */
1648
+ liveMrz?: DocumentLiveMrzOptions;
1649
+ /** Where the barcode decoder binary is served (default: Sekyro AI's asset host). */
1650
+ barcodeAssetBaseUrl?: string;
1651
+ }): DocumentCaptureHandle;
1652
+ /**
1653
+ * Design 2026-11-04 §5.2: submit a photo of the document picked from the device, for the face the step asks for
1654
+ * (`captureSide`, else `side`). Only while `photo.uploadOffered`, else rejects with `RangeError("upload_not_offered")`.
1655
+ * JPEG and PNG are sent as JPEG; HEIC is converted to JPEG on the device where the browser can decode it. A file
1656
+ * that is not an image of these types, or cannot be decoded, rejects with `TypeError("unsupported_file")` (nothing
1657
+ * is sent). The SDK scales the photo down (long side at most 2560 px), uploads it without a capture proof and submits
1658
+ * `doc_ocr` with `source: "upload"`; the step then moves on as after a camera photo (the next face, a retry with its
1659
+ * `reason`, or the next step). Other failures reject with the typed `HostedApiError`.
1660
+ */
1661
+ uploadDocument(file: Blob): Promise<void>;
1662
+ /**
1663
+ * Sandbox DX spec 2026-11-06 §8: present only when `context.simulation.skipCapture` is set. Stops the camera and
1664
+ * submits the check with `{ simulatedCapture: true }` and no media; the step then moves on as after a capture.
1665
+ * Repeating it while it is on its way reuses the same submission. Rejects with the typed `HostedApiError`.
1666
+ */
1667
+ skipCapture?(): Promise<void>;
1668
+ }
1669
+ /** The liveness / selfie step. */
1670
+ interface LivenessStepHandle extends LivenessSnapshot {
1671
+ /** Switch to another option of the open choice (`context.switchable`; `POST /hosted/choice`). Present only with it. */
1672
+ chooseOption?(option: string): Promise<void>;
1673
+ /** Same as {@link Verification.liveness}: the SDK uploads + submits on `captured`. */
1674
+ capture(options: LivenessCaptureOptions): LivenessCaptureHandle;
1675
+ /**
1676
+ * Step 3 with `livePhoto.icao`: the ICAO coaching of the running capture
1677
+ * (the gate fills only while `holding`; show `portrait.coach.<update.coach>`
1678
+ * otherwise). Returns the unsubscribe; never fires without `livePhoto.icao`.
1679
+ */
1680
+ onLivePhoto(handler: (gate: LivePhotoGateUpdate) => void): () => void;
1681
+ /**
1682
+ * Sandbox DX spec 2026-11-06 §8: present only when `context.simulation.skipCapture` is set. Stops the camera and
1683
+ * submits the check with `{ simulatedCapture: true }` and no media; the step then moves on as after a capture.
1684
+ * Repeating it while it is on its way reuses the same submission. Rejects with the typed `HostedApiError`.
1685
+ */
1686
+ skipCapture?(): Promise<void>;
1687
+ }
1688
+ /** The ICAO coaching of a one-capture live photo (`LivenessStepHandle.onLivePhoto`). */
1689
+ interface LivePhotoGateUpdate {
1690
+ /** The ICAO conditions hold: the liveness gate may fill. */
1691
+ holding: boolean;
1692
+ /** The last ICAO gate frame (`null` before the first). */
1693
+ update: PortraitGateUpdate | null;
1694
+ }
1695
+ /** The ICAO portrait step (SDK spec §4.9, §5.4; ID-document sessions). */
1696
+ interface PortraitStepHandle extends PortraitSnapshot {
1697
+ /** Switch to another option of the open choice (`context.switchable`; `POST /hosted/choice`). Present only with it. */
1698
+ chooseOption?(option: string): Promise<void>;
1699
+ /**
1700
+ * Spec 2026-11-06 §3.1, present only with `photo.cameraOnPhone` (a `choice` step on a desktop): re-read the session,
1701
+ * so the page follows the person who continued on their phone (the hand-over polls it).
1702
+ */
1703
+ refresh?(): Promise<void>;
1704
+ /**
1705
+ * The last submission failed on the network (nothing was decided): in the
1706
+ * `capture` phase offer a new take (`retry()` on the capture handle), in the
1707
+ * `match` phase offer {@link PortraitStepHandle.resubmit}.
1708
+ */
1709
+ uploadFailed: boolean;
1710
+ /** `match` phase: submit `face_match` again after `uploadFailed` (no-op otherwise). */
1711
+ resubmit(): Promise<void>;
1712
+ /**
1713
+ * The step's camera, `capture` phase only: the front camera for a self
1714
+ * capture; for an assisted capture the back camera when the device has a
1715
+ * choice (switchable), else the front one. The SDK uploads the
1716
+ * portrait and submits `portrait_icao` (then `face_match` with the portrait
1717
+ * as the probe). Every attempt is billed, so after a server verdict the
1718
+ * handle settles at `done` and the host calls `retry()` when the person is
1719
+ * ready. One handle per step: the same video returns the same handle.
1720
+ */
1721
+ capture(options: {
1722
+ video: HTMLVideoElement;
1723
+ keepScreenAwake?: boolean;
1724
+ assetBaseUrl?: string;
1725
+ }): PortraitCaptureHandle;
1726
+ /**
1727
+ * Design 2026-11-04 §6.2: submit a photo picked from the device as the portrait, `capture` phase only and only while
1728
+ * `photo.uploadOffered`, else rejects with `RangeError("upload_not_offered")`. JPEG and PNG are sent as picked (a large one
1729
+ * is scaled down and sent as JPEG); HEIC is converted to JPEG on the device where the browser can decode it. A file
1730
+ * that is not an image of these types, or cannot be decoded, rejects with `TypeError("unsupported_file")` (nothing is
1731
+ * sent). The SDK uploads it without a capture proof and submits `portrait_icao` with `source: "upload"`; the step then
1732
+ * moves on as after a camera photo (the `review` phase, a retry with its `reason`, or the next step). Other failures
1733
+ * reject with the typed `HostedApiError`.
1734
+ */
1735
+ uploadPortrait(file: Blob): Promise<void>;
1736
+ /**
1737
+ * Design 2026-11-04 §6.4 step 4, `review` phase only (else rejects with `RangeError("no_pending_fix")`): `true` uses
1738
+ * the adjusted photo, `false` declines it (the attempt ends, `portrait_declined_fix`, not billed) and the step returns
1739
+ * to the `capture` phase for another photo. Submits `portrait_icao` with `{ fixReview: { accept } }`.
1740
+ */
1741
+ confirmFix(accept: boolean): Promise<void>;
1742
+ /**
1743
+ * Sandbox DX spec 2026-11-06 §8: present only when `context.simulation.skipCapture` is set. Stops the camera and
1744
+ * submits the check with `{ simulatedCapture: true }` and no media; the step then moves on as after a capture.
1745
+ * Repeating it while it is on its way reuses the same submission. Rejects with the typed `HostedApiError`.
1746
+ */
1747
+ skipCapture?(): Promise<void>;
1748
+ }
1749
+ /**
1750
+ * The camera of the proof of address step ({@link ProofOfAddressStepHandle.capturePage}): the rear camera without a
1751
+ * card frame, one still per page, up to `maxPages`, then {@link PageCaptureHandle.submitPages}.
1752
+ */
1753
+ interface PageCaptureHandle {
1754
+ /** Open the rear camera on the step's video. Rejects with the camera error when it cannot open. */
1755
+ start(): Promise<void>;
1756
+ /** Take a JPEG still of the page in view. Rejects with `RangeError("too_many_pages")` once `maxPages` are taken. */
1757
+ takePage(): Promise<Blob>;
1758
+ /** The pages taken so far, in order (show them as thumbnails). */
1759
+ readonly pages: readonly Blob[];
1760
+ /** Drop a taken page (a retake). */
1761
+ removePage(index: number): void;
1762
+ /**
1763
+ * Upload the pages (each with the camera's capture proof) and submit `poa` with `source: "camera"`, as the document
1764
+ * or, in the `holder_letter` phase, as the holder's letter. Rejects with `RangeError("no_pages")` without a page.
1765
+ * The camera stops once the server took them; the step then moves on as after an upload.
1766
+ */
1767
+ submitPages(): Promise<void>;
1768
+ /** Stop the camera and forget the pages. */
1769
+ destroy(): void;
1770
+ }
1771
+ /** The proof of address step (spec 2026-11-10 §5, §7.4). */
1772
+ interface ProofOfAddressStepHandle extends ProofOfAddressSnapshot {
1773
+ /** Switch to another option of the open choice (`context.switchable`; `POST /hosted/choice`). Present only with it. */
1774
+ chooseOption?(option: string): Promise<void>;
1775
+ /**
1776
+ * Present only with `photo.cameraOnPhone` (a `choice` step on a desktop): re-read the session, so the page follows
1777
+ * the person who continued on their phone.
1778
+ */
1779
+ refresh?(): Promise<void>;
1780
+ /**
1781
+ * Submit the document picked from the device: 1 to `maxPages` JPEG, PNG or HEIC images (one per page, in order), or
1782
+ * exactly one PDF (at most `pdf.maxBytes`). Only while `photo.uploadOffered`, else rejects with
1783
+ * `RangeError("upload_not_offered")`. More pages, or a PDF with anything else, rejects with
1784
+ * `RangeError("too_many_pages")`; a PDF over the limit with `RangeError("file_too_large")`; a file of another type
1785
+ * (or one the server's sniffer refuses) with `TypeError("unsupported_file")`. Nothing is sent on a local refusal.
1786
+ * Images go up as `image` media, a PDF as `document_file`, then `poa` is submitted with `source: "upload"`; the step
1787
+ * then moves on (a retry with its `reason`, the `holder_letter` phase, or the next step). Other failures reject with
1788
+ * the typed `HostedApiError`.
1789
+ */
1790
+ uploadPages(files: Blob[]): Promise<void>;
1791
+ /**
1792
+ * The `holder_letter` phase only (else rejects with `RangeError("holder_letter_not_requested")`): the bill holder's
1793
+ * signed letter, with the same files and refusals as {@link ProofOfAddressStepHandle.uploadPages}.
1794
+ */
1795
+ uploadHolderLetter(files: Blob[]): Promise<void>;
1796
+ /**
1797
+ * The step's page camera (rear, no card frame), unless `photo.source` is `upload` (then it throws
1798
+ * `RangeError("camera_not_offered")`). One handle per step: the same video returns the same handle until it is
1799
+ * destroyed.
1800
+ */
1801
+ capturePage(options: {
1802
+ video: HTMLVideoElement;
1803
+ keepScreenAwake?: boolean;
1804
+ }): PageCaptureHandle;
1805
+ /**
1806
+ * Spec 2026-11-10 §5.3 licence shortcut: present only while `licenceAddressAccepted`. Submits `poa` with
1807
+ * `{ part: "document" }` and no media: the server decides from the driving licence read earlier in the session
1808
+ * (address matching still applies). The step then moves on as after an upload.
1809
+ */
1810
+ useLicenceAddress?(): Promise<void>;
1811
+ /**
1812
+ * Sandbox DX spec 2026-11-06 §8: present only when `context.simulation.skipCapture` is set. Submits the check with
1813
+ * `{ simulatedCapture: true }` and no media; the step then moves on as after an upload.
1814
+ */
1815
+ skipCapture?(): Promise<void>;
1816
+ }
1817
+ /** The Form step (spec 2026-11-14 §14). */
1818
+ interface FormStepHandle extends FormSnapshot {
1819
+ /** Switch to another option of the open choice (`context.switchable`; `POST /hosted/choice`). Present only with it. */
1820
+ chooseOption?(option: string): Promise<void>;
1821
+ /** The refused answers of `input` by this client's own check (empty: send it). Shows errors without a round trip. */
1822
+ validate(input: FormInput): FormIssue[];
1823
+ /**
1824
+ * Check `input`, then submit `form` with it. Rejects with {@link FormAnswersError} (each issue names its question
1825
+ * id) when the client's check or the server (422 `form_answers_invalid`, e.g. a card number typed into a text
1826
+ * answer) refuses it: nothing is stored and no attempt is used. Answers are final once accepted; the step then moves
1827
+ * on. Other failures reject with the typed `HostedApiError`.
1828
+ */
1829
+ submit(input: FormInput): Promise<void>;
1830
+ }
1831
+ /** The biometric step needs a phone (desktop browser). */
1832
+ interface MobileRequiredStepHandle extends MobileRequiredSnapshot {
1833
+ /** Switch to another option of the open choice (`context.switchable`; `POST /hosted/choice`). Present only with it. */
1834
+ chooseOption?(option: string): Promise<void>;
1835
+ /** Re-read the session (e.g. after the person finished on their phone). */
1836
+ refresh(): Promise<void>;
1837
+ /**
1838
+ * Sandbox DX spec 2026-11-06 §8: present only when `context.simulation.skipCapture` is set. Stops the camera and
1839
+ * submits the check with `{ simulatedCapture: true }` and no media; the step then moves on as after a capture.
1840
+ * Repeating it while it is on its way reuses the same submission. Rejects with the typed `HostedApiError`.
1841
+ */
1842
+ skipCapture?(): Promise<void>;
1843
+ }
1844
+ /** Spec 2026-11-15: the camera step runs in a native app only (the partner's app or the Sekyro AI app). */
1845
+ interface NativeAppRequiredStepHandle extends NativeAppRequiredSnapshot {
1846
+ /** Switch to another option of the open choice (`context.switchable`; `POST /hosted/choice`). Present only with it. */
1847
+ chooseOption?(option: string): Promise<void>;
1848
+ /** Re-read the session (the person continues in the app; the page follows). */
1849
+ refresh(): Promise<void>;
1850
+ /** Sandbox DX spec 2026-11-06 §8: see {@link MobileRequiredStepHandle.skipCapture}. */
1851
+ skipCapture?(): Promise<void>;
1852
+ }
1853
+ /** The server is still deciding. */
1854
+ interface ProcessingStepHandle extends ProcessingSnapshot {
1855
+ /** Switch to another option of the open choice (`context.switchable`; `POST /hosted/choice`). Present only with it. */
1856
+ chooseOption?(option: string): Promise<void>;
1857
+ /** Re-read the session now (also after `stalled`). */
1858
+ refresh(): Promise<void>;
1859
+ }
1860
+ /** A step this SDK cannot run (`platform_unsupported` / `update_required`). */
1861
+ type UnsupportedStepHandle = UnsupportedSnapshot & {
1862
+ /** The chip step of a simulated session (`checkType: "nfc_chip"`); see {@link DocumentStepHandle.skipCapture}. */
1863
+ skipCapture?(): Promise<void>;
1864
+ };
1865
+ /** The session's outcome — display only (the SDK never decides it). */
1866
+ type ResultStepHandle = ResultSnapshot;
1867
+ /** What `on('step')` delivers: the step's data plus its actions. */
1868
+ type VerificationStep = PhoneOtpStepHandle | EmailOtpStepHandle | ContactChoiceStepHandle | IdentitySummaryStepHandle | MethodStepHandle | ChoiceStepHandle | EidStepHandle | RegistryStepHandle | DocumentStepHandle | LivenessStepHandle | PortraitStepHandle | ProofOfAddressStepHandle | FormStepHandle | MobileRequiredStepHandle | NativeAppRequiredStepHandle | ProcessingStepHandle | UnsupportedStepHandle | ResultStepHandle;
1869
+
1870
+ /** The engine surface the handle binds — CaptureSessionV3 or a test double. */
1871
+ interface CaptureEngine {
1872
+ readonly state: CaptureState$1;
1873
+ on<K extends keyof CaptureSessionV3Events>(event: K, handler: (payload: CaptureSessionV3Events[K]) => void): () => void;
1874
+ /** `facingMode` sets the camera for this attempt and later retries. */
1875
+ start(options?: {
1876
+ facingMode?: "user" | "environment";
1877
+ }): Promise<void>;
1878
+ retry(): void;
1879
+ switchCamera(): void;
1880
+ /** Drop the running attempt (discarding a recording) and start again on `facingMode`. */
1881
+ restart(facingMode: "user" | "environment"): void;
1882
+ destroy(): void;
1883
+ /** Device-profile chrome hint (LOW class → `'reduced'`); absent on doubles. */
1884
+ readonly animations?: "full" | "reduced";
1885
+ /** The camera the engine opens (after any switch); absent on doubles. */
1886
+ readonly facingMode?: "user" | "environment";
1887
+ }
1888
+ /** Internal construction seams (tests; Sekyro AI's own hosted page). */
1889
+ interface LivenessCaptureInternals {
1890
+ /** Replace the engine constructor (default: `new CaptureSessionV3(options)`). */
1891
+ createEngine?: (options: CaptureSessionV3Options) => CaptureEngine;
1892
+ /** Extra engine options merged in (worker offload, warmed detector, telemetry). */
1893
+ engineOptions?: Partial<Pick<CaptureSessionV3Options, "createDetector" | "createWorker" | "telemetry" | "deviceClass" | "rankKeyframes" | "measureQuality">>;
1894
+ /** Clock (default `performance.now`). */
1895
+ now?: () => number;
1896
+ /** Whether a front/back choice exists (default {@link hasMultipleCameras}): an assisted capture opens the back
1897
+ * camera by default only then, else the front one (a laptop webcam). */
1898
+ canChooseFacing?: () => Promise<boolean>;
1899
+ }
1900
+ /** fcv3.* guidance key → public gate hint code. */
1901
+ declare function mapGuidanceHint(key: string): GateHint | null;
1902
+ /** Engine state → public state (`preflight|acquiring → starting`, `positioning → gating`). */
1903
+ declare function mapEngineState(state: CaptureState$1): CaptureState;
1904
+ /** Engine error kinds → the public six (`models|cliptoolarge|recorder|overconstrained → generic`, `backcamera → notfound`). */
1905
+ declare function mapErrorKind(kind: CaptureErrorKind$1): CaptureErrorKind;
1906
+ /**
1907
+ * Spec 2026-11-06 §3.3: the capture mode switch of a capture bound to a session. `session` is the session's own mode
1908
+ * (the switch exists under `choice` only); `onModeChange` records the person's pick (`Verification.chooseCaptureMode`)
1909
+ * so the `captureMode` getter of the handle follows it.
1910
+ */
1911
+ interface CaptureModeSwitch {
1912
+ session(): CaptureMode;
1913
+ onModeChange(mode: ResolvedCaptureMode): void;
1914
+ }
1915
+ /** Handle + the hooks the verification layer uses to drive the flow states. */
1916
+ interface LivenessCaptureInternalHandle {
1917
+ handle: LivenessCaptureHandle;
1918
+ /** Push a post-capture state (`uploading | checking | done`). */
1919
+ setFlowState(state: Extract<CaptureState, "uploading" | "checking" | "done">): void;
1920
+ }
1921
+ declare function createLivenessCaptureInternal(options: LivenessCaptureOptions, internals?: LivenessCaptureInternals,
1922
+ /** Keyframe ranking switch (SDK spec §4.8a) — createVerification reads the server tuning. */
1923
+ rankKeyframes?: () => boolean,
1924
+ /**
1925
+ * Who films the face (spec 2026-10-28 §4.3): createVerification reads the session's `capture.mode`, read at every
1926
+ * start and switch, resolved through the person's pick under `choice` (never `choice` itself). Absent (a capture
1927
+ * bound to no session) → `self`.
1928
+ */
1929
+ captureMode?: () => ResolvedCaptureMode,
1930
+ /**
1931
+ * Liveness v7 §4.4: the session's screen-ramp challenge (`capture.liveness.screenRamp`), read when the recording
1932
+ * starts. The engine gets it only for a `self` capture with a `ramp` listener bound (the host paints); absent (a
1933
+ * capture bound to no session, older backends) → no ramp.
1934
+ */
1935
+ screenRamp?: () => ScreenRampChallenge | undefined,
1936
+ /** Spec 2026-11-06 §3.3: the mode switch under `choice`; absent (a capture bound to no session) → none. */
1937
+ modeSwitch?: CaptureModeSwitch): LivenessCaptureInternalHandle;
1938
+ /**
1939
+ * Create a standalone liveness capture (no upload — pair it with your own
1940
+ * submission, or use {@link Verification.liveness} for the full flow).
1941
+ */
1942
+ declare function createLivenessCapture(options: LivenessCaptureOptions): LivenessCaptureHandle;
1943
+
1944
+ /** Preload state per asset base URL. */
1945
+ type LivenessAssetsStatus = "idle" | "loading" | "ready" | "failed";
1946
+ /** Options of {@link preloadLivenessAssets}. */
1947
+ interface PreloadLivenessAssetsOptions {
1948
+ /** Same value as the capture's `assetBaseUrl`; default `/models-v3`. */
1949
+ assetBaseUrl?: string;
1950
+ /** Defer the load to browser idle time (`requestIdleCallback`, 1.2 s timeout fallback). Default `false`. */
1951
+ idle?: boolean;
1952
+ /** Skip when the browser asks to save data (`navigator.connection.saveData`). Default `false`. */
1953
+ respectSaveData?: boolean;
1954
+ }
1955
+ /** Blaze init deadline for the preload — generous: a slow ~11 MB wasm download must finish. */
1956
+ declare const PRELOAD_BLAZE_INIT_TIMEOUT_MS = 120000;
1957
+ /** Outer budget reclaiming only a genuinely hung load (≥ the init deadline + slack). */
1958
+ declare const PRELOAD_BUDGET_MS = 130000;
1959
+ type Loader = (base: string) => Promise<Detector>;
1960
+ /** @internal Test seam: replace the detector loader (null restores the real one). */
1961
+ declare function setPreloadLoaderForTests(next: Loader | null): void;
1962
+ /** @internal Test seam: drop every entry (destroying warmed detectors). */
1963
+ declare function resetLivenessAssetsForTests(): void;
1964
+ /**
1965
+ * Warm the face detector for `assetBaseUrl` so the capture starts instantly.
1966
+ * Idempotent per base URL and never rejects: resolves the settled status.
1967
+ * `'idle'` means nothing was preloaded here (SSR, no camera API, Data-Saver
1968
+ * skip) — start normally. Calling again after `'failed'` retries the load.
1969
+ * With `idle: true` the load is deferred (status stays `'idle'` until it
1970
+ * starts); a later non-idle call — or a capture mounting meanwhile — starts it
1971
+ * at once, and {@link releaseLivenessAssets} cancels it.
1972
+ */
1973
+ declare function preloadLivenessAssets(options?: PreloadLivenessAssetsOptions): Promise<LivenessAssetsStatus>;
1974
+ /** Current preload status for `assetBaseUrl` (default `/models-v3`). */
1975
+ declare function getLivenessAssetsStatus(assetBaseUrl?: string): LivenessAssetsStatus;
1976
+ /**
1977
+ * Subscribe to status changes for `assetBaseUrl`; returns the unsubscribe
1978
+ * function. Does NOT emit the current status on subscribe (read it with
1979
+ * {@link getLivenessAssetsStatus}) — the
1980
+ * `useSyncExternalStore(subscribe, getSnapshot)` contract, so it plugs into
1981
+ * that hook directly.
1982
+ */
1983
+ declare function subscribeLivenessAssets(listener: (status: LivenessAssetsStatus) => void, assetBaseUrl?: string): () => void;
1984
+ /** Free the warmed detector (an SPA leaving the flow). Never call while a capture is mounted. */
1985
+ declare function releaseLivenessAssets(assetBaseUrl?: string): void;
1986
+ /**
1987
+ * @internal The capture engine's detector source when a preload exists for
1988
+ * `assetBaseUrl`: a non-owning view of the warm instance (waiting for an
1989
+ * in-flight load), or — once that load failed — a cold detector OWNED by the
1990
+ * session (default ladder + deadline). `undefined` when nothing was preloaded.
1991
+ * Invoking it on an idle-scheduled preload starts that load now and joins it.
1992
+ */
1993
+ declare function preloadedDetectorFactory(assetBaseUrl?: string): (() => Promise<Detector>) | undefined;
1994
+
1995
+ /** Seams for tests (jsdom has neither `createImageBitmap` nor a canvas encoder). */
1996
+ interface UploadFileInternals {
1997
+ decode?(blob: Blob): Promise<{
1998
+ width: number;
1999
+ height: number;
2000
+ draw(ctx: CanvasRenderingContext2D, w: number, h: number): void;
2001
+ close(): void;
2002
+ }>;
2003
+ encode?(source: {
2004
+ width: number;
2005
+ height: number;
2006
+ draw(ctx: CanvasRenderingContext2D, w: number, h: number): void;
2007
+ }, quality: number): Promise<Blob | null>;
2008
+ }
2009
+
2010
+ /**
2011
+ * The client surface the flow needs — `HostedClient` or a test fake. D8: the
2012
+ * live-camera capture proof methods are optional (a fake / an older bridge
2013
+ * without them presigns without a proof).
2014
+ */
2015
+ type HostedClientLike = Pick<HostedClient, "getSession" | "recordConsent" | "choose" | "presign" | "uploadToSpaces" | "completeMedia" | "submitCheck"> & Partial<Pick<HostedClient, "presignCapture" | "armCapture">> & Partial<Pick<HostedClient, "confirmIdentity" | "identityPortrait">> & Partial<Pick<HostedClient, "reportCameraUnavailable">> & Partial<Pick<HostedClient, "reportCaptureIssue">> & Partial<Pick<HostedClient, "testerGate">>;
2016
+ /** The presign policy allowlist for `kind: 'clip'` (media.policy.ts mirror). */
2017
+ declare const CLIP_MIME_ALLOWLIST: readonly string[];
2018
+ /** Same-key transport replays AFTER the first try, and the pause between them. */
2019
+ declare const TRANSPORT_REPLAY_ATTEMPTS = 2;
2020
+ declare const TRANSPORT_REPLAY_DELAY_MS = 1000;
2021
+ /**
2022
+ * `503 inference_unavailable` (profile v2 step 4 — request-level: no state
2023
+ * change, no attempt used, not billed): retries after `retryAfterSeconds`
2024
+ * (default {@link INFERENCE_RETRY_DEFAULT_S}, capped at 20 s, ±25 % jitter,
2025
+ * at least 0.5 s: `jitteredRetryWaitMs`), at most
2026
+ * {@link INFERENCE_RETRY_ATTEMPTS} times, each under a FRESH key (each retry
2027
+ * is its own logical attempt; the backend never caches a 5xx envelope).
2028
+ */
2029
+ declare const INFERENCE_RETRY_ATTEMPTS = 3;
2030
+ declare const INFERENCE_RETRY_DEFAULT_S = 10;
2031
+ /** `getAttestation` threw (a host's own seam): the submission is not sent; it is retried once. */
2032
+ declare class AttestationError extends Error {
2033
+ constructor(message: string);
2034
+ }
2035
+ /** One logical submission: receives the client and ITS idempotency key. */
2036
+ type SubmitExecutor = (client: HostedClientLike, idempotencyKey: string) => Promise<HostedSessionView>;
2037
+ interface SubmitRuntime {
2038
+ client: HostedClientLike;
2039
+ /** Force-record consent (the server just said it is missing). */
2040
+ ensureConsent(opts: {
2041
+ force: true;
2042
+ }): Promise<void>;
2043
+ sleep(ms: number): Promise<void>;
2044
+ uuid(): string;
2045
+ /** An `inference_unavailable` retry is about to wait (the `busy` event). */
2046
+ onBusy?(info: VerificationBusy): void;
2047
+ /** The retry jitter source, a value in [0, 1) (tests pin it). Defaults to `Math.random`. */
2048
+ random?(): number;
2049
+ }
2050
+ /**
2051
+ * Run one logical submission (ported use-submit semantics):
2052
+ * - a fresh `crypto.randomUUID()` key per logical submission;
2053
+ * - a transport-class failure replays the SAME executor under the SAME key
2054
+ * (bounded) — the backend's IdempotencyInterceptor returns the first
2055
+ * response instead of burning another attempt;
2056
+ * - ONE `consent_required` recovery: force-record consent and re-run under a
2057
+ * FRESH key (the 409 envelope is idempotency-cached under the old one);
2058
+ * - ONE attestation retry (a host seam's throw or a server
2059
+ * `attestation_invalid`): `onAttestationInvalid` drops the cached token and
2060
+ * the executor re-runs under a fresh key; an {@link AttestationUnavailableError}
2061
+ * (no token within the SDK's bound) is final;
2062
+ * - up to {@link INFERENCE_RETRY_ATTEMPTS} `inference_unavailable` retries
2063
+ * after `retryAfterSeconds`, each under a FRESH key and with a fresh
2064
+ * attestation (`onAttestationInvalid` — the Turnstile token was spent).
2065
+ * Throws the final error otherwise.
2066
+ */
2067
+ declare function runSubmission(rt: SubmitRuntime, executor: SubmitExecutor, hooks?: {
2068
+ onAttestationInvalid?: () => void;
2069
+ }): Promise<HostedSessionView>;
2070
+ interface LivenessFlowDeps extends SubmitRuntime {
2071
+ artifacts: CapturedArtifacts;
2072
+ /** Fresh attestation per call (the challenge frame's token; `{}` when the view has no challenge). */
2073
+ getAttestation(): Promise<AttestationInput>;
2074
+ /**
2075
+ * Why the challenge behind the attestation just returned produced no token (a `ChallengeErrorCode`), sent as
2076
+ * `input.capture.attestationError`; undefined when it did.
2077
+ */
2078
+ attestationError?(): string | undefined;
2079
+ /** Latest hosted view (frontier decisions). */
2080
+ getView(): HostedSessionView;
2081
+ /** Re-GET the view from the server (after a RESYNC code) and fold it in. */
2082
+ refreshView(): Promise<HostedSessionView>;
2083
+ /** Fold a submit response into the view (re-reading it when the response says nothing about the next step). */
2084
+ applySubmit(view: HostedSessionView, submitted: CheckType): void | Promise<void>;
2085
+ /** Flow-state hook for the capture handle. */
2086
+ onPhase(phase: "uploading" | "checking"): void;
2087
+ /** The verification was destroyed (the only thing that cancels a chain). */
2088
+ isCancelled(): boolean;
2089
+ /**
2090
+ * The keyframe (face_match probe) was promoted — the plan runner keeps the
2091
+ * key for the profile v2 §4.4 wrong-number re-entry (face_match resubmitted
2092
+ * with the same image). Optional; observation only.
2093
+ */
2094
+ onKeyframePromoted?(key: string): void;
2095
+ }
2096
+ type LivenessFlowOutcome = {
2097
+ kind: "settled";
2098
+ } | {
2099
+ kind: "resync";
2100
+ } | {
2101
+ kind: "unavailable";
2102
+ reason: SdkFailureReason | "mobile_required";
2103
+ } | {
2104
+ kind: "cancelled";
2105
+ };
2106
+ /**
2107
+ * Run the biometric submissions the CURRENT frontier allows, re-evaluating
2108
+ * after every submit and after every RESYNC re-GET:
2109
+ * - frontier `liveness` → clip upload + attestation + `liveness` (once per capture);
2110
+ * - frontier `face_match` → keyframe upload + `face_match` (once per match node, at most two per capture: a
2111
+ * step-up's bound match then its document match, same keyframe),
2112
+ * allowed when liveness was NOT part of this capture (it had already
2113
+ * settled — any state, incl. `failed`: the selfie-fallback case, where this
2114
+ * capture only feeds face_match) or settled chainable from this capture
2115
+ * (passed / review / processing / skipped — or absent);
2116
+ * - anything else (terminal view, a non-biometric frontier, a check this
2117
+ * capture already submitted) → `settled` for the caller to map the view.
2118
+ * A RESYNC code re-GETs the view and re-enters (at most {@link RESYNC_REENTRY_MAX}
2119
+ * times); the final RESYNC surfaces as `resync` for the caller to map.
2120
+ */
2121
+ declare function runLivenessFlow(deps: LivenessFlowDeps): Promise<LivenessFlowOutcome>;
2122
+
2123
+ /** Seams of the page camera (tests: jsdom has neither a camera nor a canvas encoder). */
2124
+ interface PageCameraInternals {
2125
+ /** Open the rear camera. */
2126
+ open?(): Promise<MediaStream>;
2127
+ /** A JPEG still of the video's current frame. */
2128
+ grab?(video: HTMLVideoElement): Promise<Blob>;
2129
+ /** Show the stream on the video. */
2130
+ attach?(video: HTMLVideoElement, stream: MediaStream): void;
2131
+ }
2132
+
2133
+ /**
2134
+ * Physical geometry the scanner frames (ISO/IEC 7810 / ICAO 9303). `"card"` is
2135
+ * any identity card or residence permit of ANY issuer: ID-1 (TD1) or ID-2 (TD2)
2136
+ * — the issuer decides the size, so the gate accepts either aspect.
2137
+ */
2138
+ type DocFormat = "ID-1" | "ID-2" | "ID-3" | "card";
2139
+ type PhysicalFormat = Exclude<DocFormat, "card">;
2140
+ type DocSide = "recto" | "verso" | "single";
2141
+ interface DocCatalogEntry {
2142
+ /** kyc-docs-v2 `document_type`, verbatim. */
2143
+ docType: "carte_identite" | "passport" | "residence_permit" | "drivers_license";
2144
+ format: DocFormat;
2145
+ /** Capture sequence the hosted doc step walks, in order. */
2146
+ sides: readonly DocSide[];
2147
+ /** MRZ geometry: td1 = 3×30 (ID-1 verso), td2 = 2×36 (ID-2), td3 = 2×44 (passport data page). */
2148
+ mrz: "none" | "td1" | "td2" | "td3";
2149
+ /** Which side carries the holder photo (drives portrait expectations). */
2150
+ portraitSide: DocSide;
2151
+ /** Physical width/height ratio of the framed page. */
2152
+ aspectRatio: number;
2153
+ /** Where the subject identifier (NNI) is parsed from, when the doc carries one. */
2154
+ identifierSource?: "mrz";
2155
+ }
2156
+ /**
2157
+ * Plausibility aspect bands per physical format (Task 34 gate input): ID-1
2158
+ * cards are 85.6×53.98mm → 1.586; ID-2 105×74mm → 1.419; an ID-3 passport DATA
2159
+ * PAGE frames at ≈125×88mm → 1.42 (wider tolerance — page curl and hinge
2160
+ * shadow skew the detected quad).
2161
+ */
2162
+ declare const ASPECT_BANDS: Record<PhysicalFormat, {
2163
+ center: number;
2164
+ tolerance: number;
2165
+ }>;
2166
+ /** Aspect band for a format (`"card"` → the ID-1 band; use {@link aspectFits} for plausibility). */
2167
+ declare function aspectBand(format: DocFormat): {
2168
+ center: number;
2169
+ tolerance: number;
2170
+ };
2171
+ /** The quad aspect is plausible for the format (any of its physical bands). */
2172
+ declare function aspectFits(format: DocFormat, aspect: number): boolean;
2173
+ /** Every document type (profile v2 §5.3a), picker order. */
2174
+ declare const DOC_CATALOG: readonly DocCatalogEntry[];
2175
+ /** The two types the legacy MR picker offers. Order = the hosted picker's display order. */
2176
+ declare const MR_DOC_CATALOG: readonly DocCatalogEntry[];
2177
+ /**
2178
+ * Scanner format per document type for ANY issuer (profile v2 §5.3a): identity
2179
+ * cards and residence permits are ID-1 or ID-2 (the issuer decides), passports
2180
+ * are framed by their MRZ band (ID-3). Reads DOC_CATALOG; its entries (and
2181
+ * MR_DOC_CATALOG, which the hosted page reads) keep `"ID-1"`.
2182
+ */
2183
+ declare function scannerFormatFor(docType: DocCatalogEntry["docType"]): DocFormat;
2184
+
2185
+ /** Detect-frame width the session downscales to (findings §1: 25ms median).
2186
+ * Lives HERE (not detector-scanic.ts) so the session can import it without
2187
+ * statically pulling the scanic chunk into host bundles. */
2188
+ declare const DOC_DETECT_WIDTH = 480;
2189
+ interface DocQuadPoint {
2190
+ x: number;
2191
+ y: number;
2192
+ }
2193
+ /** Detected document quad, image-space pixels (scanic CornerPoints shape). */
2194
+ interface DocQuad {
2195
+ topLeft: DocQuadPoint;
2196
+ topRight: DocQuadPoint;
2197
+ bottomRight: DocQuadPoint;
2198
+ bottomLeft: DocQuadPoint;
2199
+ }
2200
+ interface DocGateThresholds {
2201
+ /** Quad area / frame area below which the doc is too far. */
2202
+ MIN_AREA_FRAC: number;
2203
+ /** A corner this close to (or past) a frame edge counts as clipped. */
2204
+ EDGE_CLIP_MARGIN_PX: number;
2205
+ /** Consecutive stable plausible+quality ticks required to fire. */
2206
+ STABLE_TICKS: number;
2207
+ /** Quad-bbox IoU with the previous tick at/above which the streak holds. */
2208
+ IOU_STABLE_MIN: number;
2209
+ /** Integrator slopes, per second — mirrors FaceGateV3's gentle drain. */
2210
+ RISE_PER_S: number;
2211
+ FALL_PER_S: number;
2212
+ /** Quality guidance trigger levels (same semantics as the face gate). */
2213
+ GUIDE_EXPOSURE: number;
2214
+ GUIDE_SHARPNESS: number;
2215
+ /** ID-3 (MRZ-band mode): band width / frame width floor. */
2216
+ ID3_BAND_MIN_WIDTH_FRAC: number;
2217
+ /** ID-3 (MRZ-band mode): band aspect (w/h) sanity bounds. */
2218
+ ID3_BAND_ASPECT_MIN: number;
2219
+ ID3_BAND_ASPECT_MAX: number;
2220
+ }
2221
+ /** Frozen defaults (plan Task 34 — do not retune without a golden update). */
2222
+ declare const DOC_GATE_V1_DEFAULTS: Readonly<DocGateThresholds>;
2223
+ interface DocGateQuality {
2224
+ /** frame-quality.sharpness on the quad crop. */
2225
+ sharpness: number;
2226
+ /** frame-quality.exposure on the quad crop. */
2227
+ exposure: number;
2228
+ /** Mean crop luma — picks more_light vs too_bright. */
2229
+ meanLuma: number;
2230
+ }
2231
+ interface DocGateTickInput {
2232
+ timestampMs: number;
2233
+ quad: DocQuad | null;
2234
+ quality: DocGateQuality;
2235
+ frameWidth: number;
2236
+ frameHeight: number;
2237
+ }
2238
+ /** Per-tick output — the scanner chrome contract. */
2239
+ interface DocGateTick {
2240
+ at: number;
2241
+ quad: DocQuad | null;
2242
+ /** Geometry passed: present × big enough × in frame × right shape. */
2243
+ plausible: boolean;
2244
+ /** Integrated progress 0..1 (the overlay ring). */
2245
+ p: number;
2246
+ /** dcv1.* message key (host translates; never prose). */
2247
+ guidanceKey: string;
2248
+ /** Fire signal: plausible × quality × STABLE_TICKS consecutive high-IoU ticks. */
2249
+ ready: boolean;
2250
+ /** Current stability streak length (diagnostics/telemetry). */
2251
+ stableTicks: number;
2252
+ }
2253
+ /** Shoelace area of the quad as a fraction of the frame area. */
2254
+ declare function quadAreaFrac(quad: DocQuad, frameWidth: number, frameHeight: number): number;
2255
+ /** IoU of the two quads' axis-aligned bounding boxes (stability metric). */
2256
+ declare function quadIou(a: DocQuad, b: DocQuad): number;
2257
+ /** Axis-aligned bounds (width/height) of a quad — the ID-3 band-mode geometry. */
2258
+ declare function quadBounds(quad: DocQuad): {
2259
+ width: number;
2260
+ height: number;
2261
+ };
2262
+ declare class DocGateV1 {
2263
+ private readonly t;
2264
+ private readonly format;
2265
+ private p;
2266
+ private lastTickAt;
2267
+ private lastQuad;
2268
+ private streak;
2269
+ constructor(format: DocFormat, overrides?: Partial<DocGateThresholds>);
2270
+ reset(): void;
2271
+ tick(input: DocGateTickInput): DocGateTick;
2272
+ private edgeClipped;
2273
+ }
2274
+
2275
+ type FramingStatus = "no_document" | "too_far" | "too_close" | "edge_clipped" | "wrong_shape" | "tilted" | "ok";
2276
+ type LightingStatus = "too_dark" | "too_bright" | "ok";
2277
+ type BlurStatus = "blurry" | "ok";
2278
+ type GlareStatus = "glare" | "ok";
2279
+ /** The per-frame analysis vector (every axis judged independently). */
2280
+ interface DocFrameAnalysis {
2281
+ framing: FramingStatus;
2282
+ lighting: LightingStatus;
2283
+ blur: BlurStatus;
2284
+ glare: GlareStatus;
2285
+ /** All-clear: every axis ok — the gate's integrator/stability input. */
2286
+ acceptable: boolean;
2287
+ }
2288
+ interface DocFrameMeasures {
2289
+ /** frame-quality sharpness on the doc-region crop (0..1). */
2290
+ sharpness: number;
2291
+ /** frame-quality exposure on the doc-region crop (0..1). */
2292
+ exposure: number;
2293
+ /** Mean crop luma (0..255) — picks too_dark vs too_bright. */
2294
+ meanLuma: number;
2295
+ /** Fraction of crop pixels at/above the specular ceiling (0..1). */
2296
+ specularFraction: number;
2297
+ }
2298
+ /** Analysis thresholds beyond the gate's — frozen defaults (round 4). */
2299
+ declare const DOC_ANALYSIS_DEFAULTS: Readonly<{
2300
+ /** Doc area fraction above which the camera is too close (capture would crop). */
2301
+ MAX_AREA_FRAC: 0.92;
2302
+ /** Opposite-side length ratio beyond which the view is too oblique. */
2303
+ TILT_MAX_SIDE_RATIO: 1.3;
2304
+ /** Specular-pixel fraction at/above which the frame reads as glare. */
2305
+ GLARE_MAX_SPECULAR_FRAC: 0.025;
2306
+ }>;
2307
+ /** Fraction of crop pixels with luma ≥ 252 — cheap specular-highlight measure. */
2308
+ declare function specularFraction(crop: ImageData): number;
2309
+ /** Opposite-side length ratio of the quad (1 = fronto-parallel). */
2310
+ declare function quadTiltRatio(quad: DocQuad): number;
2311
+ /**
2312
+ * Judge one frame. `detectionMode` mirrors the gate: ID-1 quads carry
2313
+ * area/aspect/tilt semantics; ID-3 MRZ bands carry width-fraction semantics
2314
+ * (band rects are axis-aligned, so tilt/aspect checks are band-specific).
2315
+ */
2316
+ declare function analyzeDocFrame(input: {
2317
+ format: DocFormat;
2318
+ quad: DocQuad | null;
2319
+ frameWidth: number;
2320
+ frameHeight: number;
2321
+ measures: DocFrameMeasures;
2322
+ thresholds?: Partial<DocGateThresholds>;
2323
+ }): DocFrameAnalysis;
2324
+
2325
+ /** Feedback vocabulary (dcv2.* message keys on the hosted side). */
2326
+ 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";
2327
+ /** Reticle rendering mode per feedback state (the stage maps to visuals). */
2328
+ type ReticleType = "searching" | "coaching" | "locking" | "processing" | "flip" | "done";
2329
+ interface DocFeedbackState {
2330
+ key: DocFeedbackKey;
2331
+ reticle: ReticleType;
2332
+ /** The state holds the UI at least this long (ms) before a switch. */
2333
+ minDurationMs: number;
2334
+ }
2335
+ declare const DOC_FEEDBACK_STATES: Readonly<Record<DocFeedbackKey, DocFeedbackState>>;
2336
+ /** Frame analysis → the feedback vote it casts (worst axis speaks). */
2337
+ declare function feedbackVoteOf(analysis: DocFrameAnalysis): DocFeedbackKey;
2338
+ /** Sliding vote window + exponential decay + per-state minimum hold. */
2339
+ declare class DocFeedbackAggregator {
2340
+ private readonly windowMs;
2341
+ /** Per-second decay factor — recent frames outvote stale ones. */
2342
+ private readonly decayPerSecond;
2343
+ private votes;
2344
+ private current;
2345
+ private currentSinceMs;
2346
+ constructor(windowMs?: number,
2347
+ /** Per-second decay factor — recent frames outvote stale ones. */
2348
+ decayPerSecond?: number);
2349
+ reset(): void;
2350
+ /** Force a terminal/choreography state (capture fired, side flip, upload). */
2351
+ force(key: Extract<DocFeedbackKey, "processing" | "side_captured" | "captured" | "focus_far">, nowMs: number): DocFeedbackState;
2352
+ /** Cast this frame's vote and return the (possibly held) winning state. */
2353
+ tick(vote: DocFeedbackKey, nowMs: number): DocFeedbackState;
2354
+ }
2355
+
2356
+ /** A rectangle in some image's pixels. */
2357
+ interface PixelRect {
2358
+ x: number;
2359
+ y: number;
2360
+ width: number;
2361
+ height: number;
2362
+ }
2363
+
2364
+ /** What a document still capture returns (`docRegion` in the still's pixels; null = unknown). */
2365
+ interface DocStill {
2366
+ blob: Blob;
2367
+ previewDataUrl: string;
2368
+ docRegion?: PixelRect | null;
2369
+ /** Which source produced it (telemetry / tests). */
2370
+ source?: "photo" | "video";
2371
+ width?: number;
2372
+ height?: number;
2373
+ /** Blur-gate sharpness of the document region (blur-gate.ts scale; -1 unknown). */
2374
+ sharpness?: number;
2375
+ }
2376
+
2377
+ /**
2378
+ * Server-tunable document camera values (`capture.document.camera`, mirrored by
2379
+ * identity-backend hosted-capture.ts). Coaching / capture behaviour only — the
2380
+ * server re-checks every upload.
2381
+ */
2382
+ interface DocCameraTuning {
2383
+ /** Upgrade ask on the opened track (px; landscape terms). */
2384
+ width: number;
2385
+ height: number;
2386
+ /** Rank back cameras and open the main wide lens by deviceId. */
2387
+ lensSelection: boolean;
2388
+ /** Apply `focusMode: continuous` where offered. */
2389
+ continuousFocus: boolean;
2390
+ /** Settle time after a single-shot refocus before the photo (ms; 0 = no refocus). */
2391
+ refocusBeforePhotoMs: number;
2392
+ /** Zoom never exceeds this. */
2393
+ zoomMax: number;
2394
+ /** Zoom when the camera reports no focus range (iOS Safari), on a large enough track. */
2395
+ zoomNoFocusInfo: number;
2396
+ /** Short side (px) the track needs before {@link zoomNoFocusInfo} applies. */
2397
+ zoomMinSourcePx: number;
2398
+ /** Distance (m) at which the document fills the guide at 1× (main wide lens). */
2399
+ fillDistanceM: {
2400
+ id1: number;
2401
+ id3: number;
2402
+ };
2403
+ /** Extra margin over the minimum focus distance. */
2404
+ focusMarginFrac: number;
2405
+ /** Auto-captured still refused when its document sharpness is under this (blur-gate scale). */
2406
+ stillSharpnessMin: number;
2407
+ /** After this many refusals in a row the next still is kept (the server decides). */
2408
+ stillRefusalsMax: number;
2409
+ /** A blurry, large document (fill ≥ this of the frame) is coached "move farther". */
2410
+ focusFarFillFrac: number;
2411
+ /**
2412
+ * Zoomed in (> 1×) and no document seen for this long (ms): coach "move a
2413
+ * little farther" — a card held at the usual 1× distance overfills a 2×
2414
+ * frame and reads as nothing (iPhone 2026-10-22: 72/74 empty frames). 0 = off.
2415
+ */
2416
+ noDocFarHintMs: number;
2417
+ /** Still nothing seen for this long (ms) while zoomed: drop the zoom to 1×. 0 = never. */
2418
+ zoomFallbackMs: number;
2419
+ }
2420
+ declare const DOC_CAMERA_TUNING_DEFAULTS: Readonly<DocCameraTuning>;
2421
+ /** Field-by-field merge of a server `capture.document.camera` block over the defaults (bad fields ignored). */
2422
+ declare function resolveDocCameraTuning(raw: unknown): DocCameraTuning;
2423
+
2424
+ declare const LENS_STORAGE_KEY = "sekyro.doc.camera";
2425
+ /** The remembered document camera (per browser), or null (storage blocked / empty). */
2426
+ declare function readStoredLens(): string | null;
2427
+ declare function writeStoredLens(deviceId: string | null): void;
2428
+ interface FocusCaps {
2429
+ focusMode?: readonly string[];
2430
+ focusDistance?: {
2431
+ min?: number;
2432
+ max?: number;
2433
+ };
2434
+ zoom?: {
2435
+ min?: number;
2436
+ max?: number;
2437
+ step?: number;
2438
+ };
2439
+ pointsOfInterest?: unknown;
2440
+ }
2441
+ declare const supportsFocusMode: (caps: FocusCaps | null | undefined, mode: string) => boolean;
2442
+ /**
2443
+ * Single-shot refocus at a normalized point (0..1 of the video frame), when
2444
+ * the camera offers single-shot focus. Chrome accepts `pointsOfInterest`
2445
+ * without advertising it on every device, so it rides along whenever
2446
+ * single-shot exists.
2447
+ */
2448
+ declare function singleShotFocusAt(caps: FocusCaps | null | undefined, x: number, y: number): MediaTrackConstraintSet | null;
2449
+ /** Map a tap on an `object-fit: cover` video element to normalized video-frame coordinates. */
2450
+ declare function coverPointToVideo(clientX: number, clientY: number, rect: {
2451
+ left: number;
2452
+ top: number;
2453
+ width: number;
2454
+ height: number;
2455
+ }, video: {
2456
+ width: number;
2457
+ height: number;
2458
+ }): {
2459
+ x: number;
2460
+ y: number;
2461
+ } | null;
2462
+ /**
2463
+ * The zoom that keeps the document inside the focus range, or 1 (no change).
2464
+ * - focus range reported (Chrome Android, `focusDistance.min` in metres): zoom
2465
+ * so the fill distance clears min-focus × (1 + margin);
2466
+ * - no focus range (iOS Safari): {@link DocCameraTuning.zoomNoFocusInfo} on a
2467
+ * track whose short side is ≥ zoomMinSourcePx (pixel headroom), else 1.
2468
+ * Always within the camera's zoom range and the tuning's zoomMax; 1 without a
2469
+ * zoom capability.
2470
+ */
2471
+ declare function docZoomFor(caps: FocusCaps | null | undefined, track: {
2472
+ width: number;
2473
+ height: number;
2474
+ }, format: DocFormat, tuning?: DocCameraTuning): number;
2475
+ interface OpenDocCameraDeps {
2476
+ getUserMedia: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
2477
+ /** (navigator.mediaDevices.enumerateDevices) — absent: keep the browser's pick. */
2478
+ enumerateDevices?: () => Promise<ReadonlyArray<{
2479
+ deviceId: string;
2480
+ label: string;
2481
+ kind?: string;
2482
+ }>>;
2483
+ lensSelection: boolean;
2484
+ /** First ask (resolution). */
2485
+ base: {
2486
+ width: number;
2487
+ height: number;
2488
+ };
2489
+ }
2490
+ type LensSource = "stored" | "selected" | "default";
2491
+ /** Focus is fine when the camera offers continuous AF, or reports no focus modes at all (Safari / Firefox). */
2492
+ declare function focusOk(stream: MediaStream): boolean;
2493
+
2494
+ /**
2495
+ * Open the back camera: the remembered lens first, else `facingMode:
2496
+ * environment` (the permission prompt; labels appear after it), then the
2497
+ * best-ranked main wide lens with continuous AF by deviceId. Any failure along
2498
+ * the way keeps — or reopens — the browser's pick; only the very first
2499
+ * getUserMedia error (permission, no camera) propagates.
2500
+ */
2501
+ declare function openDocCamera(deps: OpenDocCameraDeps): Promise<{
2502
+ stream: MediaStream;
2503
+ lens: LensSource;
2504
+ }>;
2505
+
2506
+ /** Normalized rect (0..1) of the upright frame. */
2507
+ interface GuideRect {
2508
+ x: number;
2509
+ y: number;
2510
+ width: number;
2511
+ height: number;
2512
+ }
2513
+ interface GuideMetrics {
2514
+ /** Mean luma inside the guide (0..255). */
2515
+ brightness: number;
2516
+ /** Fraction of guide samples at/above the glare luma (native measure: guide region incl. background). */
2517
+ glare: number;
2518
+ /**
2519
+ * Fraction of samples at/above the glare luma INSIDE the measured card (inset
2520
+ * 6 %) — what the web lock gates on: a bright table or floor around the card
2521
+ * is not glare on the document. Equals {@link glare} when no card box is measured.
2522
+ */
2523
+ cardGlare: number;
2524
+ /** Laplacian variance over the sampled guide grid (native scale). */
2525
+ sharpness: number;
2526
+ /** Detected card width / guide width (1 = fitted). */
2527
+ fill: number;
2528
+ /**
2529
+ * The measured box's shape over the guide's (box w/h ÷ guide w/h; 1 = the
2530
+ * format's aspect). A floor tile or a book in the guide reads far from 1.
2531
+ */
2532
+ shape: number;
2533
+ /**
2534
+ * Printed content inside the measured box: the fraction of interior samples
2535
+ * on a strong luma step (≥ 24 levels to a 2-sample neighbour). A card's text,
2536
+ * photo and guilloche read ~0.08+; an empty tile, table or hand ~0.01.
2537
+ */
2538
+ content: number;
2539
+ /** Card centre offset in guide widths / heights (+ = right / down). */
2540
+ offsetX: number;
2541
+ offsetY: number;
2542
+ /** Weakest side's edge strength over the mean gradient (≥ ~1.6 = a card is there). */
2543
+ edgeConfidence: number;
2544
+ /** The card's sides in frame pixels (for the still crop), null when unmeasured. */
2545
+ box: {
2546
+ left: number;
2547
+ top: number;
2548
+ right: number;
2549
+ bottom: number;
2550
+ } | null;
2551
+ }
2552
+ declare const EMPTY_GUIDE_METRICS: Readonly<GuideMetrics>;
2553
+ /**
2554
+ * The on-screen guide in normalized coordinates of the upright frame, grown by
2555
+ * `margin` of the guide on each side (GuideRegion.inFrame). `view` is the
2556
+ * element showing the frame with `object-fit: cover`; `guide` is in view units.
2557
+ */
2558
+ declare function guideRegionInFrame(view: {
2559
+ width: number;
2560
+ height: number;
2561
+ }, guide: GuideRect, frameAspect: number, margin?: number): GuideRect;
2562
+ /**
2563
+ * Measure the card inside `region` of one RGBA frame (DocumentQuality.analyze,
2564
+ * rotation 0: browser frames are already upright).
2565
+ */
2566
+ declare function analyzeGuide(frame: ImageData, region: GuideRect, opts?: {
2567
+ edgePeakFrac?: number;
2568
+ }): GuideMetrics;
2569
+ /** The measured card as a quad in frame pixels (axis-aligned), or null. */
2570
+ declare function guideQuad(m: GuideMetrics): DocQuad | null;
2571
+ /**
2572
+ * Web guide-lock thresholds — server `capture.document.guide` (identity-backend
2573
+ * hosted-capture.ts). Starts from the native `capture.document.scan` values
2574
+ * (Mattel production) with the web calibration of 2026-10-22: the guide is the
2575
+ * drawn card slot (no margin), so `fillMin` 0.82; glare is measured on the card
2576
+ * only and gated at 0.025 (the web quad gate's specular ceiling) — the native
2577
+ * 0.012 over the whole guide blocked a card back on a bright floor; steady
2578
+ * deltas scale with the 3–6 Hz tick; the edge pick prefers the guide's side;
2579
+ * and a card must be card-shaped and carry print (`shapeTolerance`, `contentMin`)
2580
+ * — the nearer-edge pick otherwise reads a floor tile in the guide as a card.
2581
+ */
2582
+ interface GuideLockTuning {
2583
+ fillMin: number;
2584
+ fillMax: number;
2585
+ offsetMax: number;
2586
+ glareMax: number;
2587
+ /** Native-scale Laplacian variance floor (see {@link GuideMetrics.sharpness}). */
2588
+ sharpnessMin: number;
2589
+ edgeConfidenceMin: number;
2590
+ darkBrightness: number;
2591
+ lockMs: number;
2592
+ steadyMs: number;
2593
+ steadyFillMin: number;
2594
+ steadyFillMax: number;
2595
+ steadyFillDelta: number;
2596
+ steadyOffsetDelta: number;
2597
+ /**
2598
+ * Report interval the steady deltas are defined for (native: 100 ms at 10 Hz).
2599
+ * Web ticks at 3–6 Hz: the allowed deltas scale with the real interval
2600
+ * (× dt / steadyRefMs, capped at 3×). 0 = no scaling.
2601
+ */
2602
+ steadyRefMs: number;
2603
+ /**
2604
+ * Edge pick: 0 = the band's strongest edge (native); in (0, 1) = of the peaks at
2605
+ * least this fraction of the strongest, the one nearest the guide's side.
2606
+ */
2607
+ edgePeakFrac: number;
2608
+ /** Max relative deviation of {@link GuideMetrics.shape} from 1 (0 = no check; native has none). */
2609
+ shapeTolerance: number;
2610
+ /** Min {@link GuideMetrics.content} for a card (0 = no check; native has none). */
2611
+ contentMin: number;
2612
+ }
2613
+ declare const GUIDE_LOCK_DEFAULTS: Readonly<GuideLockTuning>;
2614
+ /** Field-by-field merge of a server `capture.document.scan` block over the defaults (bad fields ignored). */
2615
+ declare function resolveGuideLockTuning(raw: unknown): GuideLockTuning;
2616
+ /** Why the guide lock is not firing on this frame (telemetry + coaching). */
2617
+ type GuideBlocker = "no_card" | "too_small" | "too_big" | "off_center" | "glare" | "blurry" | "steadying" | "locking";
2618
+ interface GuideLockTick {
2619
+ /** A card is measured in the guide (edge confidence over the floor). */
2620
+ detected: boolean;
2621
+ /** Fire: good for lockMs, or steady for steadyMs. */
2622
+ ready: boolean;
2623
+ /** "good" (fill/centre/glare/sharp) or "steady" (held still, looser fill). */
2624
+ via: "good" | "steady" | null;
2625
+ blocker: GuideBlocker;
2626
+ }
2627
+ /** The capture subset of the native ScanMachine (no flip / reads / torch hints). */
2628
+ declare class GuideLock {
2629
+ private readonly t;
2630
+ private goodSince;
2631
+ private steadySince;
2632
+ private last;
2633
+ constructor(t?: GuideLockTuning);
2634
+ reset(): void;
2635
+ tick(m: GuideMetrics, at: number): GuideLockTick;
2636
+ }
2637
+
2638
+ type MrzFormat = "TD1" | "TD2" | "TD3";
2639
+ type LoadFailure = "unsupported" | "download" | "integrity" | "error" | "timeout";
2640
+ /** One band read's outcome. `lineBoxes` are [x, y, w, h] normalized to the posted bitmap (the band; the whole still
2641
+ * for a `still` read with a region). */
2642
+ interface BandResult {
2643
+ kind: "band";
2644
+ ms: number;
2645
+ lineBoxes: [number, number, number, number][];
2646
+ /** Lines the MRZ picker kept (2 or 3), 0 when none fit. */
2647
+ lineCount: number;
2648
+ format?: MrzFormat;
2649
+ /** ICAO document code of a parsed MRZ (P, I, ID, IR, AC…): a fixed document-type code, not personal data. */
2650
+ documentCode?: string;
2651
+ /** Every HARD check digit valid. */
2652
+ valid: boolean;
2653
+ /** sha256("sekyro-mrz-1\0" + salt + "\0" + lines.join("\n")), 64 hex, only when valid. */
2654
+ digest?: string;
2655
+ /** The picked MRZ lines' box [x, y, w, h] normalized to the posted bitmap (geometry only). */
2656
+ mrzBox?: [number, number, number, number];
2657
+ }
2658
+ /** The front-lock layout read (detector only, no recognizer): the text-line boxes of the card crop, [x, y, w, h]
2659
+ * normalized to the posted bitmap, top to bottom. Geometry only. */
2660
+ interface LayoutResult {
2661
+ kind: "layout";
2662
+ ms: number;
2663
+ lineBoxes: [number, number, number, number][];
2664
+ }
2665
+ interface ReadyInfo {
2666
+ warmupMs: number;
2667
+ downloadMs: number;
2668
+ cached: boolean;
2669
+ }
2670
+
2671
+ interface FrontLockTuning {
2672
+ /** Lines the detector must find in the card crop to call it a card face (a printed front has 6–12). */
2673
+ minLines: number;
2674
+ /** Horizontal extent of the text block / crop width: below = "move closer", above = "move back". */
2675
+ fillMin: number;
2676
+ fillMax: number;
2677
+ /** |text-block center − crop center| per axis, as a fraction of the crop. */
2678
+ offsetMax: number;
2679
+ /** Lumière steadiness deltas against the previous report. */
2680
+ steadyFillDelta: number;
2681
+ steadyOffsetDelta: number;
2682
+ /** Mean shift of matched line centers between reports (fraction of the crop), and the allowed line-count change. */
2683
+ layoutShiftMax: number;
2684
+ lineCountDelta: number;
2685
+ /** Lumière lockMs / steadyMs, plus a minimum number of consecutive layout reads (the sampler sets the cadence). */
2686
+ lockMs: number;
2687
+ steadyMs: number;
2688
+ minFrames: number;
2689
+ }
2690
+ type FrontLockHint = "closer" | "farther" | "center" | "glare" | "blurry";
2691
+
2692
+ /** The engine surface the assist needs (OcrEngineClient, once `ready`). */
2693
+ interface DocAssistEngine {
2694
+ readonly busy: boolean;
2695
+ bandRead(bitmap: ImageBitmap, detectorLimit?: number): Promise<BandResult>;
2696
+ layoutRead(bitmap: ImageBitmap, detectorLimit: number): Promise<LayoutResult>;
2697
+ }
2698
+ /** `capture.document.frontLock` (server-delivered; the FrontLockTuning fields + the sampler's). */
2699
+ interface TextLockTuning extends FrontLockTuning {
2700
+ minIntervalMs: number;
2701
+ maxWidthPx: number;
2702
+ detectorLimit: number;
2703
+ /** Layout reads stop after this long with a card in view and no lock (the quality locks keep going). */
2704
+ searchTimeoutMs: number;
2705
+ }
2706
+ /** `capture.document.liveMrz` — the sampler / gate subset (spec §9). */
2707
+ interface LiveMrzTuning {
2708
+ detectorLimit: number;
2709
+ bandMaxWidthPx: number;
2710
+ minBandWidthPx: number;
2711
+ bandTop: number;
2712
+ minIntervalMs: number;
2713
+ stableReads: number;
2714
+ profileReads: number;
2715
+ maxReadMs: number;
2716
+ searchTimeoutMs: number;
2717
+ }
2718
+ declare const TEXT_LOCK_DEFAULTS: Readonly<TextLockTuning>;
2719
+ declare const LIVE_MRZ_DEFAULTS: Readonly<LiveMrzTuning>;
2720
+ /** A rect in VIDEO pixels. */
2721
+ interface VideoRect {
2722
+ x: number;
2723
+ y: number;
2724
+ w: number;
2725
+ h: number;
2726
+ }
2727
+ type LiveMrzCoach = "moveCloser" | "turnSideways" | "glare" | "holdStill";
2728
+ /** `unsupported`: the camera can never show the band wide enough to read (e.g. a 720 px portrait stream). */
2729
+ type LiveMrzFallback = "timeout" | "slow" | "error" | "unsupported";
2730
+ type LiveMrzState = {
2731
+ state: "searching";
2732
+ } | {
2733
+ state: "reading";
2734
+ coach?: LiveMrzCoach;
2735
+ format?: MrzFormat;
2736
+ } | {
2737
+ state: "valid";
2738
+ format: MrzFormat;
2739
+ } | {
2740
+ state: "fallback";
2741
+ reason: LiveMrzFallback;
2742
+ };
2743
+ /** What a live-MRZ capture carries to the still confirmation and the `deviceRead` hint (text-free). */
2744
+ interface LiveMrzCapture {
2745
+ format: MrzFormat;
2746
+ documentCode?: string;
2747
+ /** The salted digest of the two agreeing reads (64 hex). */
2748
+ digest: string;
2749
+ lineCount: number;
2750
+ framesToValid: number;
2751
+ msToValid: number;
2752
+ }
2753
+ interface DocAssistTickInput {
2754
+ atMs: number;
2755
+ video: HTMLVideoElement;
2756
+ /** This face carries an MRZ (passport page, card back): live MRZ when enabled, else the text lock. */
2757
+ mrzFace: boolean;
2758
+ /** A card / page is in view this tick (a plausible quad, or the guide lock measuring one). */
2759
+ present: boolean;
2760
+ /** The card region (the guide slot or the card box) for the text lock. */
2761
+ card: VideoRect | null;
2762
+ /** The MRZ band for live MRZ. */
2763
+ band: VideoRect | null;
2764
+ portrait: boolean;
2765
+ glareOk: boolean;
2766
+ sharpOk: boolean;
2767
+ }
2768
+ interface DocAssistTick {
2769
+ /** Capture now (the OCR path fired). */
2770
+ ready: boolean;
2771
+ via?: "text_lock" | "live_mrz";
2772
+ /** Live MRZ decides this face: the host suspends its quality auto-capture. */
2773
+ suspendQuality: boolean;
2774
+ mode: "off" | "text_lock" | "live_mrz";
2775
+ mrz?: LiveMrzState;
2776
+ lock?: {
2777
+ state: "searching" | "locking" | "locked";
2778
+ hint?: FrontLockHint;
2779
+ };
2780
+ }
2781
+ /** PII-free per-face report (the `live_mrz` capture report, spec §10 + D5b). */
2782
+ interface DocAssistReport {
2783
+ capture: "recto" | "verso" | "single";
2784
+ mode: "text_lock" | "live_mrz";
2785
+ outcome: "valid" | "locked" | "timeout" | "slow" | "error" | "unsupported" | "off";
2786
+ reads: number;
2787
+ format?: MrzFormat;
2788
+ framesToValid?: number;
2789
+ msToValid?: number;
2790
+ framesToLock?: number;
2791
+ msToLock?: number;
2792
+ readP50Ms?: number;
2793
+ readP90Ms?: number;
2794
+ deviceClass?: "fast" | "mid" | "slow";
2795
+ typeMismatch?: boolean;
2796
+ }
2797
+ interface DocAssistOptions {
2798
+ textLock: TextLockTuning | null;
2799
+ liveMrz: LiveMrzTuning | null;
2800
+ /** Video crop → bitmap (default createImageBitmap with resizeWidth). */
2801
+ crop?: (video: HTMLVideoElement, r: VideoRect, resizeWidth: number) => Promise<ImageBitmap>;
2802
+ }
2803
+ declare class DocAssist {
2804
+ private readonly o;
2805
+ private engine;
2806
+ private readonly crop;
2807
+ private gen;
2808
+ private inFlight;
2809
+ private lastReadAt;
2810
+ private firstSeen;
2811
+ private reads;
2812
+ private times;
2813
+ private mrzGate;
2814
+ private lockGate;
2815
+ private mrzState;
2816
+ private lockState;
2817
+ private fallback;
2818
+ private lockOff;
2819
+ private lockError;
2820
+ private fired;
2821
+ private valid;
2822
+ private faceMode;
2823
+ private disabled;
2824
+ constructor(o: DocAssistOptions);
2825
+ /** The engine joins when ready (the camera never waits for it). */
2826
+ setEngine(engine: DocAssistEngine | null): void;
2827
+ /** The fallback card band's top (fraction of the guide), `liveMrz.bandTop`. */
2828
+ get bandTop(): number;
2829
+ get hasEngine(): boolean;
2830
+ /** New face / retake / restart: every gate, clock and fallback starts over; in-flight results are dropped. */
2831
+ reset(): void;
2832
+ /**
2833
+ * The OCR-fired still was refused (focus gate) or failed: read again on the next frames, but keep what this face
2834
+ * already learnt — a fallback, the text-lock timeout, the search clock and the read profile stay.
2835
+ */
2836
+ rearmFace(): void;
2837
+ /** The live-MRZ read that fired this face's capture (null for any other path). */
2838
+ liveCapture(): LiveMrzCapture | null;
2839
+ private modeFor;
2840
+ tick(i: DocAssistTickInput): DocAssistTick;
2841
+ private states;
2842
+ private canRead;
2843
+ private fall;
2844
+ private liveTick;
2845
+ private lockTick;
2846
+ /** Stop using the engine for the session (it died, or was disposed). */
2847
+ disable(): void;
2848
+ /** The face's PII-free report (null when no OCR mode ran on it). */
2849
+ report(capture: DocAssistReport["capture"], capturedVia: string | undefined, atMs: number): DocAssistReport | null;
2850
+ }
2851
+
2852
+ /**
2853
+ * Pre-fetch + cache the scanic chunk (call when the scan surface MOUNTS, before
2854
+ * the camera is even granted) so the first detect tick pays no chunk-fetch
2855
+ * latency. Fire-and-forget; failures fall back to the lazy path.
2856
+ */
2857
+ declare function warmDocDetector(): void;
2858
+ /**
2859
+ * The opened camera must show a live picture within this many ms: a camera that never plays, ends, or sends black
2860
+ * frames is reopened once, then reported as a retryable error, so the scan view never stays dark without a word
2861
+ * (staging 2026-11-01). 0 = no watch.
2862
+ */
2863
+ declare const DOC_FIRST_FRAME_MS = 4000;
2864
+ /** Ticks whose frame-wide mean luma stays at or under this read as a black (dead) camera picture. */
2865
+ declare const DOC_BLACK_FRAME_LUMA = 2;
2866
+ /** Black ticks in a row, with no lit frame since the camera opened, that count as a dead picture. */
2867
+ declare const DOC_BLACK_FRAME_TICKS = 3;
2868
+ /** Doc detect cadence per device class — scanic @480px is ~3–8× a face tick,
2869
+ * so the doc loop paces slower than the face profiles (findings §1: 2–5 Hz). */
2870
+ declare const DOC_CADENCE_HZ: Readonly<Record<DeviceClass, number>>;
2871
+ interface DocChecksPayload {
2872
+ engine: "docv1";
2873
+ /** Gate integrator 0..1 — the overlay ring. */
2874
+ p: number;
2875
+ plausible: boolean;
2876
+ stableTicks: number;
2877
+ quad: DocQuad | null;
2878
+ /** Detect-frame size the quad coordinates live in (overlay scaling). */
2879
+ frameWidth: number;
2880
+ frameHeight: number;
2881
+ /** Capture-v2 per-frame status vector (framing/lighting/blur/glare). */
2882
+ analysis: DocFrameAnalysis;
2883
+ /**
2884
+ * The gate's fire signal on this tick (framed, steady, good quality); always
2885
+ * set by this engine, optional so host-built payloads stay valid. With
2886
+ * `autoCapture: false` the host takes the still itself ({@link CaptureSessionDoc.captureNow}).
2887
+ */
2888
+ ready?: boolean;
2889
+ /** Guide-region lock on this tick — optional so host-built payloads stay valid. */
2890
+ guide?: {
2891
+ detected: boolean;
2892
+ blocker: GuideBlocker;
2893
+ fill: number;
2894
+ shape?: number;
2895
+ content?: number;
2896
+ offsetX?: number;
2897
+ offsetY?: number;
2898
+ };
2899
+ /** On-device OCR assist on this tick (text lock / live MRZ; enums only) — absent without an engine. */
2900
+ ocr?: Pick<DocAssistTick, "mode" | "mrz" | "lock">;
2901
+ }
2902
+ /**
2903
+ * How the still was taken: the guide-region lock (good card held `lockMs`, or a
2904
+ * steady card `steadyMs`), the quad gate, or the user's manual shutter.
2905
+ */
2906
+ type DocCaptureVia = "guide_good" | "guide_steady" | "quad" | "manual" | "text_lock" | "live_mrz";
2907
+ /** Why the manual shutter was offered. */
2908
+ type DocShutterReason = "timeout" | "detected_no_lock";
2909
+ /**
2910
+ * Manual-shutter safety net (server `capture.document.scan`, the native scan
2911
+ * machines' block): offered after `manualShutterMs` without a capture, or once
2912
+ * a document has been detected (a quad, or a card in the guide) for
2913
+ * `detectedNoLockMs` without any lock — long enough for the guide lock's
2914
+ * steady path to win first, so it stays hidden on a normal scan.
2915
+ */
2916
+ interface DocShutterTuning {
2917
+ manualShutterMs: number;
2918
+ detectedNoLockMs: number;
2919
+ }
2920
+ declare const DOC_SHUTTER_DEFAULTS: Readonly<DocShutterTuning>;
2921
+ /**
2922
+ * Resolve the shutter tuning from a server `capture.document.scan` block:
2923
+ * `manualShutterMs` as is; `detectedNoLockMs` = `steadyMs` + `lockMs` (a lock
2924
+ * gets its full chance first). Bad / missing fields keep the defaults.
2925
+ */
2926
+ declare function resolveDocShutterTuning(scan: unknown): DocShutterTuning;
2927
+ /**
2928
+ * PII-free per-side capture report (telemetry): timings, which path took the
2929
+ * still, and per-tick lock-failure reasons. No pixels, no text.
2930
+ */
2931
+ interface DocCaptureReport {
2932
+ side?: DocSide;
2933
+ format: DocFormat;
2934
+ deviceClass: DeviceClass;
2935
+ /** Delivered video size (px). */
2936
+ video: {
2937
+ width: number;
2938
+ height: number;
2939
+ };
2940
+ /** Zoom applied (1 = none). */
2941
+ zoom: number;
2942
+ /** ms from positioning until the zoom was dropped to 1× (nothing seen while zoomed); absent: never. */
2943
+ zoomFallbackAtMs?: number;
2944
+ /** ms from positioning to the still (absent: no still yet). */
2945
+ msToCapture?: number;
2946
+ via?: DocCaptureVia;
2947
+ /** ms from positioning until the manual shutter was offered (absent: never). */
2948
+ shutterAtMs?: number;
2949
+ shutterReason?: DocShutterReason;
2950
+ /** Detect ticks run while positioning this side. */
2951
+ ticks: number;
2952
+ /** Per tick: the gate's framing verdict ("ok" when framed; edge_clipped, too_far, no_document, …). */
2953
+ quadFraming: Record<string, number>;
2954
+ /** Per tick on framed ticks that did not lock: the quality reason (blurry, too_dark, glare, …). */
2955
+ qualityBlockers: Record<string, number>;
2956
+ /** Per tick: the guide lock's state (no_card, too_small, too_big, off_center, glare, blurry, steadying, locking). */
2957
+ guideBlockers: Record<string, number>;
2958
+ /** Focus-gate refusals of auto stills. */
2959
+ stillRefusals: number;
2960
+ /** The on-device OCR assist's per-face report (text lock / live MRZ), when it ran. */
2961
+ ocr?: DocAssistReport;
2962
+ }
2963
+ /**
2964
+ * Artifacts: `keyframe` = the full-res still of the framed side (JPEG, cropped
2965
+ * to the document). `docRegion` = the document's bbox in the keyframe's pixels
2966
+ * (`null`: unknown, measure the whole still; absent: a host seam that did not say).
2967
+ */
2968
+ type DocArtifacts = CaptureArtifacts & {
2969
+ side?: DocSide;
2970
+ docRegion?: PixelRect | null;
2971
+ /** The live-MRZ read that took this still (text-free: format, code, salted digest, counts) — the deviceRead hint's input. */
2972
+ liveMrz?: LiveMrzCapture;
2973
+ };
2974
+ interface CaptureSessionDocEvents {
2975
+ statechange: {
2976
+ state: CaptureState$1;
2977
+ };
2978
+ checks: DocChecksPayload;
2979
+ /** dcv1.* message KEY — hosts translate; never prose. Deduped. */
2980
+ guidance: {
2981
+ key: string;
2982
+ };
2983
+ /** Capture-v2 AGGREGATED feedback (time-decay voted, min-duration held) —
2984
+ * the stage's message + reticle channel. Deduped on state key. */
2985
+ feedback: DocFeedbackState;
2986
+ artifacts: DocArtifacts;
2987
+ /** `detail`: where the attempt failed and the thrown error's name (never its message). */
2988
+ error: {
2989
+ kind: CaptureErrorKind$1;
2990
+ retryable: boolean;
2991
+ detail?: EngineErrorDetail;
2992
+ };
2993
+ /**
2994
+ * Offer the manual shutter ({@link CaptureSessionDoc.captureNow}) — the safety
2995
+ * net when the gate does not lock. `available: false` on re-arm / capture.
2996
+ */
2997
+ shutter: {
2998
+ available: boolean;
2999
+ reason?: DocShutterReason;
3000
+ };
3001
+ }
3002
+ interface CaptureSessionDocOptions {
3003
+ /** Host-owned <video playsInline muted>. */
3004
+ video: HTMLVideoElement;
3005
+ format?: DocFormat;
3006
+ /** Side label stamped on the artifacts event (recto→verso sequencing). */
3007
+ side?: DocSide;
3008
+ thresholds?: Partial<DocGateThresholds>;
3009
+ deviceClass?: DeviceClass;
3010
+ /**
3011
+ * Take the still when the gate is ready (default `true` — the hosted page's
3012
+ * behaviour). `false`: `ready` is only reported on the checks payload and the
3013
+ * host calls {@link CaptureSessionDoc.captureNow} (the Lumière scan flow).
3014
+ */
3015
+ autoCapture?: boolean;
3016
+ /** (navigator.mediaDevices.getUserMedia — environment camera) */
3017
+ getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
3018
+ /** (vendored scanic detectQuad) */
3019
+ detect?: (image: ImageData) => Promise<DocQuad | null>;
3020
+ /** (canvas downscale of the live video to the 480px detect frame) */
3021
+ grabDetectFrame?: (video: HTMLVideoElement, targetWidth: number) => ImageData | null;
3022
+ /** (full-res still cropped to the quad's document → JPEG blob + preview: still-capture.ts) */
3023
+ captureStill?: (video: HTMLVideoElement, quad: DocQuad, detectSize: {
3024
+ width: number;
3025
+ height: number;
3026
+ }) => Promise<DocStill>;
3027
+ /**
3028
+ * Take the ImageCapture photo when the browser has one (default `true`; never
3029
+ * on LOW devices or with the torch on). `false`: always the video frame.
3030
+ */
3031
+ photoCapture?: boolean;
3032
+ /** Ask the opened track for up to 4K (default `true`; never on LOW devices). */
3033
+ upgradeResolution?: boolean;
3034
+ /**
3035
+ * Server camera tuning (`capture.document.camera`, resolved with
3036
+ * resolveDocCameraTuning): lens selection, focus, zoom and the still focus gate.
3037
+ */
3038
+ camera?: DocCameraTuning;
3039
+ /**
3040
+ * Guide-region lock thresholds (resolveGuideLockTuning over `capture.document.guide`).
3041
+ */
3042
+ guideLock?: GuideLockTuning;
3043
+ /**
3044
+ * The on-screen guide: `rect` normalized in a view of aspect `viewAspect`
3045
+ * (width / height) showing the video with `object-fit: cover`. Default: a
3046
+ * centered guide of the format's aspect spanning 86 % of the frame width.
3047
+ */
3048
+ guide?: {
3049
+ viewAspect: number;
3050
+ rect: GuideRect;
3051
+ };
3052
+ /** Manual-shutter safety net (resolveDocShutterTuning over `capture.document.scan`). */
3053
+ shutter?: DocShutterTuning;
3054
+ /**
3055
+ * On-device OCR assist (web live MRZ, plan Tasks 6b + 6): the text lock on card faces and live MRZ on MRZ faces,
3056
+ * driven by the wasm engine worker. Absent = today's flow. The host owns the engine (`ocr.setEngine` when ready).
3057
+ */
3058
+ ocr?: DocAssist;
3059
+ /** (navigator.mediaDevices.enumerateDevices) — lens selection; absent in tests unless injected. */
3060
+ enumerateDevices?: () => Promise<ReadonlyArray<{
3061
+ deviceId: string;
3062
+ label: string;
3063
+ kind?: string;
3064
+ }>>;
3065
+ /**
3066
+ * Ms the opened camera has to show a live picture (default {@link DOC_FIRST_FRAME_MS}; 0 = no watch): a stream that
3067
+ * never plays, ends, or shows only black frames is reopened once, then reported as a retryable `generic` error.
3068
+ */
3069
+ firstFrameMs?: number;
3070
+ /** (the video plays and has a decoded frame) — whether the camera shows a live picture. */
3071
+ hasFrames?: (video: HTMLVideoElement) => boolean;
3072
+ /** (performance.now) */
3073
+ now?: () => number;
3074
+ /** (setTimeout/clearTimeout) — the cadence pacer. */
3075
+ setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
3076
+ clearTimer?: (id: ReturnType<typeof setTimeout>) => void;
3077
+ }
3078
+ type Handler<K extends keyof CaptureSessionDocEvents> = (payload: CaptureSessionDocEvents[K]) => void;
3079
+ declare class CaptureSessionDoc {
3080
+ private readonly opts;
3081
+ private readonly gate;
3082
+ private readonly cadenceMs;
3083
+ private readonly deviceClass;
3084
+ private torchOn;
3085
+ private readonly camera;
3086
+ /** Auto-capture stills refused in a row by the focus gate. */
3087
+ private stillRefusals;
3088
+ /** Zoom applied to the track (1 = none) — telemetry / tests. */
3089
+ zoom: number;
3090
+ private readonly shutterTuning;
3091
+ /** Positioning clock for this side (tick time). */
3092
+ private positioningSince;
3093
+ private detectedSince;
3094
+ /** Last tick a document was seen (a quad, or a card in the guide) — gates the manual shutter. */
3095
+ private lastSeenAt;
3096
+ private readonly guideLock;
3097
+ private readonly guideTuning;
3098
+ private lastGuideQuad;
3099
+ /** The OCR assist fired on the last tick: its crop quad (detect frame) and path, for a host-timed captureNow. */
3100
+ private lastOcrReady;
3101
+ private shutterOffered;
3102
+ private stats;
3103
+ private readonly handlers;
3104
+ private stream;
3105
+ private timer;
3106
+ private state;
3107
+ private lastGuidance;
3108
+ private attempt;
3109
+ private capturing;
3110
+ private readonly feedback;
3111
+ private lastFeedbackKey;
3112
+ /** Last detected quad + detect size (for a host-timed {@link captureNow}). */
3113
+ private lastQuad;
3114
+ private lastDetect;
3115
+ /** The first-frame watch of the current camera ({@link DOC_FIRST_FRAME_MS}). */
3116
+ private frameWatch;
3117
+ /** The camera was reopened once by the watch since it last showed a picture. */
3118
+ private reopened;
3119
+ /** A tick saw a lit frame since the camera opened; black ticks in a row before that. */
3120
+ private lit;
3121
+ private blackTicks;
3122
+ /** Unsubscribes the opened track's `ended` listener. */
3123
+ private offEnded;
3124
+ constructor(opts: CaptureSessionDocOptions);
3125
+ on<K extends keyof CaptureSessionDocEvents>(event: K, handler: Handler<K>): () => void;
3126
+ private emit;
3127
+ start(): Promise<void>;
3128
+ /** play() on the kept stream when it is still live and attached (see start()); null when there is nothing to play. */
3129
+ private resumePlayback;
3130
+ /** Whether the video shows a live picture right now (playing, with a decoded frame). */
3131
+ private framesNow;
3132
+ /** Arm the first-frame watch for this camera. */
3133
+ private watchFrames;
3134
+ private clearFrameWatch;
3135
+ /** The opened track ended on its own (the camera was taken or interrupted): the same path as a dead picture. */
3136
+ private watchEnded;
3137
+ /**
3138
+ * The camera opened but shows no live picture: reopen it once (silently), then a retryable error. A live stream the
3139
+ * browser would not play is kept for the retry's tap to play it ({@link resumePlayback}).
3140
+ */
3141
+ private cameraDead;
3142
+ /** Stop and detach this engine's stream. */
3143
+ private releaseStream;
3144
+ /** Restart the gate for another side / a retake (same stream). */
3145
+ rearm(side?: DocSide): void;
3146
+ /**
3147
+ * Take the full-resolution still now (the same best-frame window the gate
3148
+ * uses), emitting `statechange: captured` + `artifacts`. Ignored unless the
3149
+ * session is `positioning` and not already capturing. Without a detected
3150
+ * card the still is still taken (manual shutter).
3151
+ */
3152
+ captureNow(): Promise<void>;
3153
+ /** PII-free report of the side being (or last) positioned — telemetry. */
3154
+ captureReport(): DocCaptureReport;
3155
+ private ocrReport;
3156
+ private static freshStats;
3157
+ /** The on-screen guide moved (orientation change) — the guide lock measures the new region. */
3158
+ setGuide(guide: {
3159
+ viewAspect: number;
3160
+ rect: GuideRect;
3161
+ } | undefined): void;
3162
+ /** The guide region in this frame (normalized), from the host's view geometry or the default. */
3163
+ private guideRegion;
3164
+ /** New side / retake / restart: the shutter clocks and the per-side report start over. */
3165
+ private resetSide;
3166
+ /** Withdraw the shutter (nothing card-like in view any more). */
3167
+ private withdrawShutter;
3168
+ /**
3169
+ * Drop a zoom > 1× back to 1× (nothing seen for zoomFallbackMs while zoomed).
3170
+ * Best-effort; the guide / quad gates re-measure at the new scale.
3171
+ */
3172
+ private zoomFallback;
3173
+ private offerShutter;
3174
+ /** The live camera exposes a torch (`MediaTrackCapabilities.torch`). */
3175
+ torchAvailable(): boolean;
3176
+ /** Switch the torch (manual only; errors swallowed — unsupported cameras ignore it). */
3177
+ setTorch(on: boolean): Promise<void>;
3178
+ destroy(): void;
3179
+ /**
3180
+ * Raise the opened track towards DOC_CAMERA_UPGRADE (still-geometry.ts) on the SAME
3181
+ * camera (no lens re-pick). Best-effort: unsupported / refused constraints
3182
+ * keep the 1080p track the stream opened with.
3183
+ */
3184
+ private upgradeResolution;
3185
+ private focusCaps;
3186
+ /** Continuous AF where offered, then the distance-strategy zoom. Each step is best-effort. */
3187
+ private applyFocusAndZoom;
3188
+ /**
3189
+ * Tap-to-focus at a normalized point of the video frame (0..1). Single-shot
3190
+ * AF there, back to continuous after ~1.5 s. No-op where the camera has no
3191
+ * single-shot focus (iOS Safari keeps its own AF).
3192
+ */
3193
+ focusAt(x: number, y: number): Promise<void>;
3194
+ private restoreContinuous;
3195
+ /** Single-shot refocus on the document right before the photo (Chrome Android); no-op elsewhere. */
3196
+ private refocusOn;
3197
+ /** The live video track (null in tests / after destroy). */
3198
+ private videoTrack;
3199
+ /**
3200
+ * One still: the ImageCapture photo where usable (first candidate only),
3201
+ * else the native video frame — both cropped to the document.
3202
+ */
3203
+ private takeStill;
3204
+ private detector;
3205
+ private setState;
3206
+ private scheduleTick;
3207
+ private tick;
3208
+ /**
3209
+ * BEST-FRAME capture window (capture-v2): the first ready tick captures a
3210
+ * candidate immediately, then up to CAPTURE_EXTRA_CANDIDATES more stills are
3211
+ * taken at CAPTURE_CANDIDATE_SPACING_MS while the user holds — each scored
3212
+ * by the live detect-tick sharpness at its capture moment — and the SHARPEST
3213
+ * wins. Beats first-acceptable-frame capture without decoding stills.
3214
+ */
3215
+ private fire;
3216
+ /**
3217
+ * One OCR-assist tick (plan Tasks 6b + 6): the card region (the drawn guide slot) and the MRZ band (the passport band
3218
+ * quad, else the guide from `bandTop`) in VIDEO pixels; glare / sharpness from this tick's guide measure (cards) or
3219
+ * frame analysis (passports). Sets {@link lastOcrReady} when the assist fires.
3220
+ */
3221
+ private ocrTick;
3222
+ }
3223
+ /**
3224
+ * The passport MRZ band to read, in video pixels, from the detect-frame stroke band (mrz-band.ts): 3 % wider and at
3225
+ * least a fifth of its width tall, centred on it (a TD3 MRZ with margins is ≈ width / 6).
3226
+ */
3227
+ declare function passportBandOf(b: {
3228
+ x: number;
3229
+ y: number;
3230
+ width: number;
3231
+ height: number;
3232
+ }, sx: number, sy: number, vw: number, vh: number): VideoRect;
3233
+ /** Best-frame window: 2 extra candidates, 260ms apart, ≥8% sharper to replace. */
3234
+ declare const CAPTURE_EXTRA_CANDIDATES = 2;
3235
+ declare const CAPTURE_CANDIDATE_SPACING_MS = 260;
3236
+
3237
+ interface EncodedDocument {
3238
+ blob: Blob;
3239
+ width: number;
3240
+ height: number;
3241
+ }
3242
+ declare function encodeDocumentImage(still: Blob): Promise<EncodedDocument>;
3243
+
3244
+ type ScanLayout = "twoSided" | "singlePage";
3245
+ type ScanSide = "recto" | "verso";
3246
+ type ScanPhase = "framing" | "locking" | "capturing" | "flipCue" | "reaskRecto" | "reading" | "result";
3247
+ /** `blurry`: the photo was refused before any upload (blur gate). */
3248
+ type ScanNotice = "same_face" | "reread" | "technical" | "blurry";
3249
+ interface ScanReport {
3250
+ /** A plausible card / passport band is in view. */
3251
+ present: boolean;
3252
+ /** The gate's fire signal (quality + stability). */
3253
+ ready: boolean;
3254
+ /** Gate progress is high: show "hold still". */
3255
+ locking: boolean;
3256
+ /** Card area / detect-frame area. */
3257
+ areaFrac: number;
3258
+ }
3259
+ interface ScanState {
3260
+ layout: ScanLayout;
3261
+ phase: ScanPhase;
3262
+ captured: {
3263
+ recto?: string;
3264
+ verso?: string;
3265
+ };
3266
+ pending: string[];
3267
+ lastShot?: string;
3268
+ current?: ScanSide;
3269
+ goodSince?: number;
3270
+ lastCaptureAt: number;
3271
+ lastReportAt: number;
3272
+ manualShutter: boolean;
3273
+ notice?: ScanNotice;
3274
+ restPhase: "framing" | "flipCue" | "reaskRecto";
3275
+ readSides: ScanSide[];
3276
+ needFlip: boolean;
3277
+ flipped: boolean;
3278
+ flipTimeoutSpent: boolean;
3279
+ timeoutCapture: boolean;
3280
+ lastShotByTimeout: boolean;
3281
+ awaySince?: number;
3282
+ /** Area of the card when the last photo was taken (flip = shrinks below FLIP_FILL_MIN of it). */
3283
+ captureArea?: number;
3284
+ lastArea?: number;
3285
+ }
3286
+ type ScanEvent = {
3287
+ type: "report";
3288
+ report: ScanReport;
3289
+ at: number;
3290
+ } | {
3291
+ type: "tick";
3292
+ at: number;
3293
+ } | {
3294
+ type: "captured";
3295
+ id: string;
3296
+ at: number;
3297
+ } | {
3298
+ type: "captureFailed";
3299
+ at: number;
3300
+ } | {
3301
+ type: "classified";
3302
+ id: string;
3303
+ side: ScanSide;
3304
+ } | {
3305
+ type: "duplicate";
3306
+ id: string;
3307
+ side: ScanSide;
3308
+ } | {
3309
+ type: "readOk";
3310
+ side: ScanSide;
3311
+ } | {
3312
+ type: "readFailed";
3313
+ side: ScanSide;
3314
+ id?: string;
3315
+ issue: ScanNotice;
3316
+ } | {
3317
+ type: "retake";
3318
+ } | {
3319
+ type: "clockRestart";
3320
+ };
3321
+ /** Lumière values (tuned on the Mattel reference device; retune with the cores). */
3322
+ declare const FLIP_GAP_MS = 250;
3323
+ declare const FLIP_FILL_MIN = 0.6;
3324
+ declare const FLIP_TIMEOUT_MS = 1800;
3325
+ declare const MANUAL_SHUTTER_MS = 6000;
3326
+ declare const NO_REPORT_MS = 2000;
3327
+ /**
3328
+ * Blur gate (Mattel 8f13198; server name `capture.document.scan.blurRefuseSharpnessMax`):
3329
+ * a photo measuring under this inverse-edge-width sharpness is retaken at once.
3330
+ * Real card photos measure ~0.42, dim/rough captures that still read 0.29 and up.
3331
+ */
3332
+ declare const BLUR_REFUSE_SHARPNESS_MAX = 0.16;
3333
+ declare function initialScanState(layout: ScanLayout, at: number): ScanState;
3334
+ declare function nextScanState(state: ScanState, event: ScanEvent): ScanState;
3335
+
3336
+ interface DeviceReadHint {
3337
+ engine: string;
3338
+ source: "live_mrz";
3339
+ format: "TD1" | "TD2" | "TD3";
3340
+ lineCount: number;
3341
+ checkDigitsValid: true;
3342
+ stillConfirmed?: boolean;
3343
+ /** The MRZ band [x, y, w, h] normalized to the UPLOADED image (the still as encoded: same frame, any scale). */
3344
+ band: [number, number, number, number];
3345
+ digest: string;
3346
+ framesToValid: number;
3347
+ msToValid: number;
3348
+ }
3349
+ interface StillReader {
3350
+ stillRead(bitmap: ImageBitmap, region: [number, number, number, number], detectorLimit?: number): Promise<BandResult>;
3351
+ }
3352
+ /**
3353
+ * Read the still (the keyframe that is uploaded) and build the hint. `null` when the still read finds no MRZ band (the
3354
+ * band is the hint's only use to the server) or fails. `region` = the part of the still to read (default: the whole).
3355
+ */
3356
+ declare function buildDeviceReadHint(reader: StillReader, still: Blob, live: LiveMrzCapture, o: {
3357
+ engine: string;
3358
+ detectorLimit?: number;
3359
+ decode?: (b: Blob) => Promise<ImageBitmap>;
3360
+ retryMs?: number;
3361
+ region?: [number, number, number, number];
3362
+ }): Promise<DeviceReadHint | null>;
3363
+ /** A hint promise read at POST time: the value if it already settled, else nothing (the POST never waits). */
3364
+ declare function settledHint(p: Promise<DeviceReadHint | null> | null): () => DeviceReadHint | null;
3365
+
3366
+ interface OcrWorkerLike {
3367
+ postMessage(data: unknown, transfer?: Transferable[]): void;
3368
+ addEventListener(type: "message" | "error" | "messageerror", listener: (event: {
3369
+ data?: unknown;
3370
+ }) => void): void;
3371
+ terminate(): void;
3372
+ }
3373
+ interface OcrEngineOptions {
3374
+ baseUrl: string;
3375
+ salt: string;
3376
+ /** `readTimeoutMs` (default 10 s): a read with no answer means the worker died; the engine is disposed. */
3377
+ tuning: {
3378
+ detectorLimit: number;
3379
+ maxDownloadMs: number;
3380
+ loadTimeoutMs: number;
3381
+ readTimeoutMs?: number;
3382
+ };
3383
+ /**
3384
+ * Where the `@sekyro/web/core/ocr/worker` dist entry is served. Required (or `createWorker`): the host resolves it
3385
+ * the way its bundler emits workers, as for the v3 detect worker; without either, `ready` is `unsupported`.
3386
+ */
3387
+ workerUrl?: string | URL;
3388
+ /** Host- or test-built worker (e.g. `() => new Worker(new URL("@sekyro/web/core/ocr/worker", import.meta.url), { type: "module" })`). */
3389
+ createWorker?: () => OcrWorkerLike;
3390
+ /** Window to listen for `pagehide` on (default globalThis when it has addEventListener). */
3391
+ page?: {
3392
+ addEventListener(type: "pagehide", l: () => void, o?: {
3393
+ once: boolean;
3394
+ }): void;
3395
+ } | null;
3396
+ }
3397
+ interface OcrEngineClient {
3398
+ /** Resolves with the warm-up info, or a LoadFailure (never rejects). */
3399
+ readonly ready: Promise<ReadyInfo | LoadFailure>;
3400
+ bandRead(bitmap: ImageBitmap, detectorLimit?: number): Promise<BandResult>;
3401
+ stillRead(bitmap: ImageBitmap, region: [number, number, number, number], detectorLimit?: number): Promise<BandResult>;
3402
+ /** Front lock: the detector alone on a card crop (no recognizer); line boxes only. */
3403
+ layoutRead(bitmap: ImageBitmap, detectorLimit: number): Promise<LayoutResult>;
3404
+ readonly busy: boolean;
3405
+ dispose(): void;
3406
+ }
3407
+
3408
+ /** The engine surface the flow drives (CaptureSessionDoc in production). */
3409
+ type DocEngineLike = Pick<CaptureSessionDoc, "on" | "start" | "rearm" | "destroy" | "captureNow" | "setTorch" | "torchAvailable"> & Partial<Pick<CaptureSessionDoc, "focusAt" | "captureReport" | "setGuide">>;
3410
+ /**
3411
+ * Web live MRZ for a session-bound capture (the step runner): the view's `capture.document` (the server-resolved
3412
+ * `liveMrz` / `frontLock` blocks), the digest salt (the session id), the asset base, the report sink. Absent = off.
3413
+ */
3414
+ interface DocumentWebOcr {
3415
+ captureDocument: unknown;
3416
+ salt: string;
3417
+ baseUrl: string;
3418
+ /** Fire-and-forget `live_mrz` reports (`POST /hosted/capture-reports`). */
3419
+ reports?: (reports: readonly object[]) => void;
3420
+ /** Test seam / host-built worker. */
3421
+ createWorker?: () => OcrWorkerLike;
3422
+ }
3423
+ /** Seams (tests, the e2e harness, the step runner, Sekyro AI's hosted page) — `@sekyro/web/internal`. */
3424
+ interface DocumentCaptureInternals {
3425
+ createEngine?: (options: CaptureSessionDocOptions) => DocEngineLike | Promise<DocEngineLike>;
3426
+ engineOptions?: Partial<Omit<CaptureSessionDocOptions, "video" | "format" | "side" | "autoCapture">>;
3427
+ encode?: (still: Blob) => Promise<EncodedDocument>;
3428
+ /** Face of a card still (default: MRZ band on a 480 px copy). */
3429
+ classify?: (still: Blob) => Promise<ScanSide>;
3430
+ /**
3431
+ * Spec 2026-11-11 D10, D12, seams: `side` overrides the capture plan's barcode face,
3432
+ * `assetBaseUrl` is the runner's default base of the decoder binary, `seen` replaces the decoder
3433
+ * (does this still show a barcode).
3434
+ */
3435
+ barcode?: {
3436
+ side?: ScanSide;
3437
+ assetBaseUrl?: string;
3438
+ seen?: (still: Blob) => Promise<boolean>;
3439
+ };
3440
+ /**
3441
+ * Photo sharpness for the blur gate (default: blur-gate.ts on the card region
3442
+ * of the decoded still — the last gate quad, padded — at ≤ 1000 px; `-1` =
3443
+ * unknown, never refused). `gate` is the last `checks` geometry.
3444
+ */
3445
+ measureSharpness?: (still: Blob, gate: LastGate | null) => Promise<number>;
3446
+ /** Decode a still once per shot (default `createImageBitmap`). */
3447
+ decode?: (still: Blob) => Promise<ImageBitmap>;
3448
+ /** Blur-gate threshold (server name `capture.document.scan.blurRefuseSharpnessMax`); `0` disables it. Default 0.16. */
3449
+ blurRefuseSharpnessMax?: number;
3450
+ /** The step runner settles each face from the server verdict (`settle`); standalone captures settle at once. */
3451
+ deferRead?: boolean;
3452
+ now?: () => number;
3453
+ /** Manual-shutter tick period (default 500 ms; 0 = no timer, tests). */
3454
+ tickMs?: number;
3455
+ /** Web live MRZ (plan Task 6): session-bound OCR (the step runner passes the view). */
3456
+ webOcr?: DocumentWebOcr;
3457
+ /**
3458
+ * Spec 2026-11-11 D12: sides, shape and the MRZ expectation come from the catalog's series for the picked country
3459
+ * (`issuer`). The step runner sets it from the session's `capture.document.catalog`; absent (a standalone capture, an
3460
+ * older backend, the catalog flag off) = the type's generic plan, today's capture.
3461
+ */
3462
+ catalogCapture?: boolean;
3463
+ /**
3464
+ * One engine report per document face, whether or not web OCR is on: `captured` when the face is
3465
+ * delivered, `abandoned` when the capture is destroyed mid-face after the engine ticked. A throwing
3466
+ * callback never reaches the capture.
3467
+ */
3468
+ onFaceReport?: (report: DocCaptureReport, outcome: "captured" | "abandoned") => void;
3469
+ }
3470
+ /** What {@link createDocumentCaptureInternal} returns: the public handle plus the runner's hooks. */
3471
+ interface DocumentCaptureController {
3472
+ handle: DocumentCaptureHandle;
3473
+ /** Upload / check progress of the current face (the step runner). */
3474
+ setFlowState(state: "uploading" | "checking" | "done"): void;
3475
+ /** Server verdict for a face (deferred reads only). */
3476
+ settle(side: DocumentSide, verdict: {
3477
+ ok: true;
3478
+ } | {
3479
+ ok: false;
3480
+ issue: ScanNotice;
3481
+ }): void;
3482
+ /**
3483
+ * The last live-MRZ capture's `deviceRead` hint if it is ready NOW (the doc_ocr POST never waits); null otherwise.
3484
+ * Take it once per submission so a same-key replay sends the identical body.
3485
+ */
3486
+ takeDeviceRead(doc: CapturedDocument): DeviceReadHint | null;
3487
+ }
3488
+ /** After this many same-face drops in a row, the photo is kept (labelled as expected) and the server decides. */
3489
+ declare const SAME_FACE_MAX_DROPS = 2;
3490
+ /** The last gate geometry: the quad in detect-frame coordinates and that frame's size. */
3491
+ interface LastGate {
3492
+ quad: DocumentQuad;
3493
+ frameWidth: number;
3494
+ frameHeight: number;
3495
+ /** The quad is the engine's `docRegion`, already in the (cropped) still's pixels. */
3496
+ inStill?: boolean;
3497
+ }
3498
+ /** {@link createDocumentCapture} with seams and the step runner's hooks. */
3499
+ declare function createDocumentCaptureInternal(options: DocumentCaptureOptions, internals: DocumentCaptureInternals): DocumentCaptureController;
3500
+
3501
+ declare const LANDMARKER_MODEL = "face_landmarker.task";
3502
+ interface LandmarkedFace {
3503
+ /** 478 normalised (0..1) landmarks. */
3504
+ landmarks: Point[];
3505
+ blendshapes: Record<string, number> | null;
3506
+ /** 4×4 facial transformation matrix, column-major. */
3507
+ matrix: number[] | null;
3508
+ }
3509
+ interface LandmarkerLike {
3510
+ /** Detect on a frame; `timestampMs` must increase. Never throws (returns no face). */
3511
+ detect(source: CanvasImageSource, timestampMs: number): LandmarkedFace[];
3512
+ close(): void;
3513
+ }
3514
+ interface TasksVisionResult {
3515
+ faceLandmarks?: Array<Array<{
3516
+ x: number;
3517
+ y: number;
3518
+ }>>;
3519
+ faceBlendshapes?: Array<{
3520
+ categories: Array<{
3521
+ categoryName: string;
3522
+ score: number;
3523
+ }>;
3524
+ }>;
3525
+ facialTransformationMatrixes?: Array<{
3526
+ data: number[];
3527
+ }>;
3528
+ }
3529
+ /** Map a tasks-vision result to plain faces (exported for tests). */
3530
+ declare function facesOf(result: TasksVisionResult): LandmarkedFace[];
3531
+ declare function createFaceLandmarker(assetBaseUrl: string): Promise<LandmarkerLike>;
3532
+
3533
+ interface SegmenterLike {
3534
+ /** Person confidence of a frame; `timestampMs` must increase. Never throws (`null` = no mask). */
3535
+ segment(source: CanvasImageSource, timestampMs: number): PersonMask | null;
3536
+ close(): void;
3537
+ }
3538
+
3539
+ /** Long edge of the analysis frame the landmarker and the pixel heuristics run on. */
3540
+ declare const ANALYSIS_LONG_EDGE = 640;
3541
+ declare const PORTRAIT_JPEG_QUALITY = 0.92;
3542
+ /** A drawn frame: the pixels the gate measures and a source the landmarker reads. */
3543
+ interface GrabbedFrame {
3544
+ source: CanvasImageSource;
3545
+ width: number;
3546
+ height: number;
3547
+ /** RGBA pixels (`null` when the canvas cannot be read — heuristics are skipped). */
3548
+ pixels: {
3549
+ data: Uint8ClampedArray;
3550
+ width: number;
3551
+ height: number;
3552
+ } | null;
3553
+ }
3554
+ /** Construction seams (tests / Sekyro AI's hosted page). */
3555
+ interface PortraitCaptureInternals {
3556
+ createLandmarker?: (assetBaseUrl: string) => Promise<LandmarkerLike>;
3557
+ /** The background-uniformity check's selfie segmenter (default: MediaPipe, lazy). */
3558
+ createSegmenter?: (assetBaseUrl: string) => Promise<SegmenterLike>;
3559
+ getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
3560
+ /** (navigator.mediaDevices.enumerateDevices, only without a `getUserMedia` double) — the back lenses by id. */
3561
+ enumerateDevices?: () => Promise<ReadonlyArray<{
3562
+ deviceId: string;
3563
+ label: string;
3564
+ kind?: string;
3565
+ }>>;
3566
+ /** Draw the video scaled to `longEdge` (analysis) or at full size (`null`). */
3567
+ grabFrame?: (video: HTMLVideoElement, longEdge: number | null) => GrabbedFrame | null;
3568
+ /** Cut `region` out of a full-size frame, scale to `outHeight`, encode JPEG. */
3569
+ encodeRegion?: (frame: GrabbedFrame, region: Box, outHeight: number, quality: number) => Promise<Blob>;
3570
+ /** Whether a front/back choice exists (default {@link hasMultipleCameras}): an assisted capture opens the back
3571
+ * camera by default only then. */
3572
+ canChooseFacing?: () => Promise<boolean>;
3573
+ now?: () => number;
3574
+ setTimer?: (fn: () => void, ms: number) => unknown;
3575
+ clearTimer?: (id: unknown) => void;
3576
+ }
3577
+ /** Handle + the hooks the plan runner uses to drive the post-capture states. */
3578
+ interface PortraitCaptureController {
3579
+ handle: PortraitCaptureHandle;
3580
+ setFlowState(state: Extract<PortraitCaptureState, "uploading" | "checking" | "done">): void;
3581
+ /** This gate run's mouth scores (staff diagnostics). */
3582
+ gateScores(): IcaoGateScores | null;
3583
+ }
3584
+ /** The observation of one landmarked frame. `scale` maps analysis px → source px. */
3585
+ declare function observe(faces: readonly LandmarkedFace[], frame: GrabbedFrame, sourceWidth: number, sourceHeight: number): IcaoFrameObservation;
3586
+ declare function createPortraitCaptureInternal(options: PortraitCaptureOptions, internals?: PortraitCaptureInternals,
3587
+ /**
3588
+ * Who films the face (spec 2026-10-28 §4.3): the portrait step reads the session's `capture.mode` at every start
3589
+ * and switch, as the liveness capture does. Absent (a standalone capture) → `self`: the front camera only.
3590
+ */
3591
+ captureMode?: () => ResolvedCaptureMode,
3592
+ /** Spec 2026-11-06 §3.3: the capture mode switch of a `choice` step; absent (a standalone capture) → none. */
3593
+ modeSwitch?: CaptureModeSwitch): PortraitCaptureController;
3594
+
3595
+ /** The monitor never runs the landmarker faster than this (it shares the main thread with the liveness detector). */
3596
+ declare const LIVE_PHOTO_MAX_HZ = 6;
3597
+ /** No liveness gate tick for this long → the attempt ended: the monitor sleeps. */
3598
+ declare const LIVE_PHOTO_IDLE_MS = 1500;
3599
+ /** The still of one live-photo capture. */
3600
+ interface LivePhotoStill {
3601
+ image: Blob;
3602
+ width: number;
3603
+ height: number;
3604
+ /** The ICAO gate at the moment the capture fired (the `gate` block of portrait_icao). */
3605
+ gate: ReturnType<IcaoGate["summary"]>;
3606
+ }
3607
+ interface LivePhotoKitOptions {
3608
+ /** The capture's video (default: the one the liveness engine measures). */
3609
+ video?: HTMLVideoElement;
3610
+ /** `capture.icao` of the view (coaching limits), and `capture.tuningVersion`. */
3611
+ tuning: IcaoCaptureTuning | null;
3612
+ tuningVersion: string | null;
3613
+ /** The session's ICAO policy (`icaoPolicyOf(view).policy`): `alert` never holds the clip past `alertGraceMs`. Default `reject`. */
3614
+ policy?: "reject" | "alert";
3615
+ still: {
3616
+ minLongSidePx: number;
3617
+ jpegQuality: number;
3618
+ };
3619
+ /** Detector assets base (the landmarker sits next to the liveness wasm); default `/models-v3`. */
3620
+ assetBaseUrl?: string;
3621
+ }
3622
+ /** Test seams. */
3623
+ interface LivePhotoKitInternals {
3624
+ createLandmarker?: (assetBaseUrl: string) => Promise<LandmarkerLike>;
3625
+ /** The background-uniformity check's segmenter (default: MediaPipe selfie segmenter, lazy). */
3626
+ createSegmenter?: (assetBaseUrl: string) => Promise<SegmenterLike>;
3627
+ grabFrame?: (video: HTMLVideoElement, longEdge: number | null) => GrabbedFrame | null;
3628
+ /** Encode the full frame as JPEG (unmirrored). */
3629
+ encode?: (frame: GrabbedFrame, quality: number) => Promise<Blob>;
3630
+ /** The engine's default face-crop quality (canvas). */
3631
+ quality?: (video: HTMLVideoElement, box: {
3632
+ x: number;
3633
+ y: number;
3634
+ width: number;
3635
+ height: number;
3636
+ }) => V3GateQuality;
3637
+ now?: () => number;
3638
+ setTimer?: (fn: () => void, ms: number) => unknown;
3639
+ clearTimer?: (id: unknown) => void;
3640
+ }
3641
+ /** ICAO coaching while the liveness gate waits (the `portrait.coach.<coach>` copy). */
3642
+ interface LivePhotoGate {
3643
+ /** The ICAO conditions hold: the liveness gate may fill. */
3644
+ holding: boolean;
3645
+ update: IcaoGateUpdate | null;
3646
+ }
3647
+ interface LivePhotoKit {
3648
+ /** Seams for the liveness engine (`LivenessCaptureInternals.engineOptions`). */
3649
+ engineOptions: {
3650
+ measureQuality: (video: HTMLVideoElement, box: {
3651
+ x: number;
3652
+ y: number;
3653
+ width: number;
3654
+ height: number;
3655
+ }) => V3GateQuality;
3656
+ telemetry: (event: V3TelemetryEvent) => void;
3657
+ };
3658
+ /** The client with `input.portraitIcao` added to the liveness submission. */
3659
+ decorate<C extends HostedClientLike>(client: C): C;
3660
+ /** ICAO coaching updates (while the liveness gate is live). */
3661
+ onGate(handler: (gate: LivePhotoGate) => void): () => void;
3662
+ /** The portrait_icao body of the last liveness submission (outage fallback: submit it directly). */
3663
+ lastPortraitInput(): PortraitIcaoInput | null;
3664
+ destroy(): void;
3665
+ }
3666
+ declare function createLivePhotoKit(options: LivePhotoKitOptions, internals?: LivePhotoKitInternals): LivePhotoKit;
3667
+
3668
+ /** Production API origin — the `apiOrigin` default. */
3669
+ declare const DEFAULT_API_ORIGIN = "https://api.sekyro.ai";
3670
+ /** Pause before the single `registry_unavailable` re-submit. */
3671
+ declare const REGISTRY_RETRY_DELAY_MS = 5000;
3672
+ /** Bounded poll while a biometric verdict is still `processing` after the submits. */
3673
+ declare const PROCESSING_POLL_DELAY_MS = 1500;
3674
+ declare const PROCESSING_POLL_MAX = 10;
3675
+ /**
3676
+ * Construction seams — tests and Sekyro AI's own hosted page (`@sekyro/web/internal`).
3677
+ * Not part of the partner contract.
3678
+ */
3679
+ interface VerificationInternals {
3680
+ /** Replace the HTTP client (default: `new HostedClient({...})`). */
3681
+ client?: HostedClientLike;
3682
+ /**
3683
+ * Replace the challenge (default: `executeChallenge` on the view's challenge frame, loaded on first use).
3684
+ * `subject` is the session id the token is bound to; the `signal` aborts when the verification is destroyed (M1).
3685
+ */
3686
+ getChallengeToken?: (challenge: HostedChallengeView, opts: {
3687
+ signal: AbortSignal;
3688
+ subject: string;
3689
+ }) => Promise<string>;
3690
+ /** Capture-engine seams forwarded to {@link createLivenessCaptureInternal}. */
3691
+ capture?: LivenessCaptureInternals;
3692
+ sleep?: (ms: number) => Promise<void>;
3693
+ uuid?: () => string;
3694
+ /** The `inference_unavailable` retry jitter source, a value in [0, 1); default `Math.random`. */
3695
+ random?: () => number;
3696
+ /** Wall clock for the plan runner (OTP resend time); default `Date.now`. */
3697
+ now?: () => number;
3698
+ /** DocumentCapture seams for the runner's document step (engine, encode, classify, blur gate). */
3699
+ document?: DocumentCaptureInternals;
3700
+ /** PortraitCapture seams for the runner's ICAO portrait step (landmarker, camera, encode). */
3701
+ portrait?: PortraitCaptureInternals;
3702
+ /** Live-photo kit seams for the runner's one-capture Step 3 (landmarker, frames, encode). */
3703
+ livePhoto?: LivePhotoKitInternals;
3704
+ /** Document upload seams for the runner's document step (image decode / encode). */
3705
+ upload?: UploadFileInternals;
3706
+ /** Page camera seams for the runner's proof of address step (camera open, still grab). */
3707
+ pageCamera?: PageCameraInternals;
3708
+ }
3709
+ /** `crypto.randomUUID()` with a v4 fallback for hosts that lack it. */
3710
+ declare function randomUuid(): string;
3711
+ /**
3712
+ * Create a verification bound to one session (spec §3.1):
3713
+ * `consent()` → `startRegistry()` → `liveness({video})` → `on('result')`.
3714
+ */
3715
+ declare function createVerification(options: VerificationOptions): Verification;
3716
+ /** {@link createVerification} with construction seams (tests / Sekyro AI-internal hosts). */
3717
+ declare function createVerificationInternal(options: VerificationOptions, internals: VerificationInternals): Verification;
3718
+
3719
+ export { type GateUpdate as $, type AcceptedDocumentsLike as A, type DocumentGuide as B, type CameraFacing as C, type DocumentCaptureOptions as D, type DocumentGuideMeasure as E, type FormIssue as F, type DocumentLiveMrzOptions as G, type DocumentMrzUpdate as H, type DocumentPoint as I, type DocumentQuad as J, type DocumentReticle as K, type DocumentScanPhase as L, type DocumentScanUpdate as M, type DocumentSide as N, type DocumentSnapshot as O, type PortraitCaptureOptions as P, type DocumentStepHandle as Q, type EidSnapshot as R, type EidStepHandle as S, type EmailOtpSnapshot as T, type EmailOtpStepHandle as U, type EmailSource as V, FORM_ANSWERS_INVALID as W, FormAnswersError as X, type FormSnapshot as Y, type FormStepHandle as Z, type GateHint as _, type DocumentCaptureHandle as a, cameraUnavailableCauseOf as a$, ISSUER_CODES as a0, type IdentitySummarySnapshot as a1, type IdentitySummaryStepHandle as a2, type InLaneSwitch as a3, type LivePhotoGateUpdate as a4, type LivePhotoPlan as a5, type LivenessAssetsStatus as a6, type LivenessCaptureEvents as a7, type LivenessCaptureHandle as a8, type LivenessCaptureOptions as a9, type ProofOfAddressSnapshot as aA, type ProofOfAddressStepHandle as aB, type ReasonCode as aC, type RegistrySnapshot as aD, type RegistrySource as aE, type RegistryStepHandle as aF, type ResultDisplay as aG, type ResultSnapshot as aH, type ResultStepHandle as aI, type SdkFailureReason as aJ, type StepAttempts as aK, type StepContext as aL, type StepSnapshot as aM, type UnsupportedReason as aN, type UnsupportedSnapshot as aO, type UnsupportedStepHandle as aP, type Verification as aQ, type VerificationBusy as aR, type VerificationEvents as aS, type VerificationLocale as aT, type VerificationOptions as aU, type VerificationResult as aV, type VerificationStatus as aW, type VerificationStep as aX, WEB_IDENTITY_METHODS as aY, acceptedIssuers as aZ, acceptedTypesFor as a_, type LivenessSnapshot as aa, type LivenessStartOptions as ab, type LivenessStepHandle as ac, type MethodSnapshot as ad, type MethodStepHandle as ae, type MobileRequiredSnapshot as af, type MobileRequiredStepHandle as ag, type NativeAppRequiredSnapshot as ah, type NativeAppRequiredStepHandle as ai, type OtpChannel as aj, type OtpNumberSource as ak, PLATFORM_UNSUPPORTED as al, type PageCaptureHandle as am, type PhoneOtpSnapshot as an, type PhoneOtpStepHandle as ao, type PhotoSourceState as ap, type PlanChoiceSnapshot as aq, type PortraitCaptureEvents as ar, type PortraitCaptureState as as, type PortraitGateUpdate as at, type PortraitSnapshot as au, type PortraitStartOptions as av, type PortraitStepHandle as aw, type PreloadLivenessAssetsOptions as ax, type ProcessingSnapshot as ay, type ProcessingStepHandle as az, type PortraitCaptureHandle as b, type DocFrameAnalysis as b$, createLivenessCapture as b0, createVerification as b1, deriveStep as b2, flagOf as b3, getLivenessAssetsStatus as b4, laneOf as b5, otherOptions as b6, preloadLivenessAssets as b7, releaseLivenessAssets as b8, resolveAcceptedDocuments as b9, type ChallengeAction as bA, ChallengeError as bB, DOC_ANALYSIS_DEFAULTS as bC, DOC_BLACK_FRAME_LUMA as bD, DOC_BLACK_FRAME_TICKS as bE, DOC_CADENCE_HZ as bF, DOC_CAMERA_TUNING_DEFAULTS as bG, DOC_CATALOG as bH, DOC_DETECT_WIDTH as bI, DOC_FEEDBACK_STATES as bJ, DOC_FIRST_FRAME_MS as bK, DOC_GATE_V1_DEFAULTS as bL, DOC_SHUTTER_DEFAULTS as bM, type DeviceReadHint as bN, type DocArtifacts as bO, DocAssist as bP, type DocAssistEngine as bQ, type DocAssistTick as bR, type DocCameraTuning as bS, type DocCaptureReport as bT, type DocCaptureVia as bU, type DocChecksPayload as bV, type DocEngineLike as bW, DocFeedbackAggregator as bX, type DocFeedbackKey as bY, type DocFeedbackState as bZ, type DocFormat as b_, sectionOf as ba, subscribeLivenessAssets as bb, type SubmitRuntime as bc, type HostedClientLike as bd, type DocCatalogEntry as be, type LiveMrzTuning as bf, type TextLockTuning as bg, type OcrEngineClient as bh, type DocAssistReport as bi, type ReadyInfo as bj, type LoadFailure as bk, type OcrEngineOptions as bl, ANALYSIS_LONG_EDGE as bm, ASPECT_BANDS as bn, AttestationError as bo, BLUR_REFUSE_SHARPNESS_MAX as bp, type BlurStatus as bq, CAPTURE_CANDIDATE_SPACING_MS as br, CAPTURE_EXTRA_CANDIDATES as bs, CHALLENGE_EXECUTE_TIMEOUT_MS as bt, CHALLENGE_READY_TIMEOUT_MS as bu, CLIP_MIME_ALLOWLIST as bv, type CaptureEngine as bw, CaptureSessionDoc as bx, type CaptureSessionDocEvents as by, type CaptureSessionDocOptions as bz, type CaptureChannel as c, REGISTRY_RETRY_DELAY_MS as c$, type DocFrameMeasures as c0, type DocGateQuality as c1, type DocGateThresholds as c2, type DocGateTick as c3, type DocGateTickInput as c4, DocGateV1 as c5, type DocQuad as c6, type DocQuadPoint as c7, type DocShutterReason as c8, type DocShutterTuning as c9, LIVE_PHOTO_MAX_HZ as cA, type LandmarkedFace as cB, type LandmarkerLike as cC, type LensSource as cD, type LightingStatus as cE, type LiveMrzCapture as cF, type LiveMrzState as cG, type LivePhotoGate as cH, type LivePhotoKit as cI, type LivePhotoKitInternals as cJ, type LivePhotoKitOptions as cK, type LivePhotoStill as cL, type LivenessCaptureInternalHandle as cM, type LivenessCaptureInternals as cN, type LivenessFlowDeps as cO, type LivenessFlowOutcome as cP, MANUAL_SHUTTER_MS as cQ, MR_DOC_CATALOG as cR, NO_REPORT_MS as cS, type OpenDocCameraDeps as cT, PORTRAIT_JPEG_QUALITY as cU, PRELOAD_BLAZE_INIT_TIMEOUT_MS as cV, PRELOAD_BUDGET_MS as cW, PROCESSING_POLL_DELAY_MS as cX, PROCESSING_POLL_MAX as cY, type PortraitCaptureController as cZ, type PortraitCaptureInternals as c_, type DocSide as ca, type DocumentCaptureController as cb, type DocumentCaptureInternals as cc, EMPTY_GUIDE_METRICS as cd, type EncodedDocument as ce, type ExecuteChallengeOptions as cf, FLIP_FILL_MIN as cg, FLIP_GAP_MS as ch, FLIP_TIMEOUT_MS as ci, type FocusCaps as cj, type FramingStatus as ck, GUIDE_LOCK_DEFAULTS as cl, type GlareStatus as cm, type GrabbedFrame as cn, type GuideBlocker as co, GuideLock as cp, type GuideLockTick as cq, type GuideLockTuning as cr, type GuideMetrics as cs, type GuideRect as ct, INFERENCE_RETRY_ATTEMPTS as cu, INFERENCE_RETRY_DEFAULT_S as cv, LANDMARKER_MODEL as cw, LENS_STORAGE_KEY as cx, LIVE_MRZ_DEFAULTS as cy, LIVE_PHOTO_IDLE_MS as cz, type CaptureEngineId as d, supportsFocusMode as d$, type ReticleType as d0, SAME_FACE_MAX_DROPS as d1, type ScanEvent as d2, type ScanLayout as d3, type ScanNotice as d4, type ScanPhase as d5, type ScanReport as d6, type ScanSide as d7, type ScanState as d8, type SubmitExecutor as d9, mapEngineState as dA, mapErrorKind as dB, mapGuidanceHint as dC, nextScanState as dD, observe as dE, openDocCamera as dF, passportBandOf as dG, portraitMatchStep as dH, preloadedDetectorFactory as dI, quadAreaFrac as dJ, quadBounds as dK, quadIou as dL, quadTiltRatio as dM, randomUuid as dN, readStoredLens as dO, resetChallengeFrameForTests as dP, resetLivenessAssetsForTests as dQ, resolveDocCameraTuning as dR, resolveDocShutterTuning as dS, resolveGuideLockTuning as dT, runLivenessFlow as dU, runSubmission as dV, scannerFormatFor as dW, setPreloadLoaderForTests as dX, settledHint as dY, singleShotFocusAt as dZ, specularFraction as d_, TEXT_LOCK_DEFAULTS as da, TRANSPORT_REPLAY_ATTEMPTS as db, TRANSPORT_REPLAY_DELAY_MS as dc, type VerificationInternals as dd, analyzeDocFrame as de, analyzeGuide as df, aspectBand as dg, aspectFits as dh, buildDeviceReadHint as di, coverPointToVideo as dj, createDocumentCaptureInternal as dk, createFaceLandmarker as dl, createLivePhotoKit as dm, createLivenessCaptureInternal as dn, createPortraitCaptureInternal as dp, createVerificationInternal as dq, docZoomFor as dr, encodeDocumentImage as ds, executeChallenge as dt, facesOf as du, feedbackVoteOf as dv, focusOk as dw, guideQuad as dx, guideRegionInFrame as dy, initialScanState as dz, type CaptureError as e, warmDocDetector as e0, writeStoredLens as e1, type CaptureErrorDetail as f, type CaptureErrorKind as g, type CaptureErrorPhase as h, type CaptureState as i, type CapturedArtifacts as j, type CapturedDocument as k, type CapturedPortrait as l, type ChallengeErrorCode as m, type ChoiceOptionSnapshot as n, type ChoiceSnapshot as o, type ChoiceStepHandle as p, type ContactChoiceSnapshot as q, type ContactChoiceStepHandle as r, DEFAULT_API_ORIGIN as s, DOCUMENT_TYPE_ORDER as t, type DeriveStepEnv as u, type DocumentCaptureEvents as v, type DocumentCaptureState as w, type DocumentFeedback as x, type DocumentFeedbackKey as y, type DocumentGateUpdate as z };