@sekyro/web 0.1.0-rc.1 → 0.1.0-rc.10

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