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

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