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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/CHANGELOG.md +433 -0
  2. package/LICENSE +25 -16
  3. package/README.md +157 -62
  4. package/THIRD-PARTY-NOTICES.txt +154 -0
  5. package/dist/background-monitor-A7FKJOAG.js +1 -0
  6. package/dist/barcode-detect-C5IOXMKI.js +1 -0
  7. package/dist/camera-trait-V4UAOPIQ.js +1 -0
  8. package/dist/capture-constraints-CVqpMNGA.d.cts +48 -0
  9. package/dist/capture-constraints-CVqpMNGA.d.ts +48 -0
  10. package/dist/capture-session-doc-2LIRRKFX.js +1 -0
  11. package/dist/{capture-session-v3-COIO_F2w.d.cts → capture-session-v3-Fbj-X2Ij.d.ts} +259 -13
  12. package/dist/{capture-session-v3-CvIfcwST.d.ts → capture-session-v3-XtBrXpoW.d.cts} +259 -13
  13. package/dist/challenge-frame-YAQJ5YMB.js +1 -0
  14. package/dist/chunk-2LDOXGY3.js +1 -0
  15. package/dist/chunk-2MX4J26D.js +3 -0
  16. package/dist/chunk-33KKMPJ5.js +1 -0
  17. package/dist/chunk-3K3A7O7J.js +1 -0
  18. package/dist/chunk-53POX7U4.js +1 -0
  19. package/dist/chunk-6ERQTXMY.js +1 -0
  20. package/dist/chunk-6Z4MIKGF.js +1 -0
  21. package/dist/chunk-7QZWBDI5.js +1 -0
  22. package/dist/chunk-CJHMFPL6.js +1 -0
  23. package/dist/chunk-CMXN4SOZ.js +1 -0
  24. package/dist/chunk-CPUECYAJ.js +1 -0
  25. package/dist/chunk-DFTCAWMP.js +1 -0
  26. package/dist/chunk-DK5YPBDQ.js +1 -0
  27. package/dist/chunk-FPXL63KZ.js +1 -0
  28. package/dist/chunk-FSSMUAKC.js +1 -0
  29. package/dist/chunk-G6LKLN4U.js +1 -0
  30. package/dist/chunk-GFJATPUR.js +1 -0
  31. package/dist/chunk-GI3UFGRQ.js +1 -0
  32. package/dist/chunk-GXL6ZD4I.js +1 -0
  33. package/dist/chunk-JLVZ35QK.js +2 -0
  34. package/dist/chunk-MD4YXLPK.js +1 -0
  35. package/dist/chunk-OUC57KMS.js +1 -0
  36. package/dist/chunk-POIQGEZM.js +1 -0
  37. package/dist/chunk-R3JMNYW5.js +1 -0
  38. package/dist/chunk-RI3E7GBN.js +1 -0
  39. package/dist/chunk-SMKCBUJL.js +1 -0
  40. package/dist/chunk-SUANHBF4.js +1 -0
  41. package/dist/chunk-SX7TUC3V.js +1 -0
  42. package/dist/chunk-TN4JWBFJ.js +1 -0
  43. package/dist/chunk-TSA6GHUG.js +1 -0
  44. package/dist/chunk-VWGKUQ3C.js +1 -0
  45. package/dist/chunk-XFDWFJLY.js +1 -0
  46. package/dist/chunk-ZKF2XMNX.js +1 -0
  47. package/dist/client/index.cjs +1 -357
  48. package/dist/client/index.d.cts +6 -37
  49. package/dist/client/index.d.ts +6 -37
  50. package/dist/client/index.js +1 -15
  51. package/dist/clip-inspect-DLJXVKV6.js +1 -0
  52. package/dist/core/index.cjs +1 -1606
  53. package/dist/core/index.d.cts +5 -4
  54. package/dist/core/index.d.ts +5 -4
  55. package/dist/core/index.js +1 -139
  56. package/dist/core/ocr/worker.bundle.js +42 -0
  57. package/dist/core/ocr/worker.cjs +42 -0
  58. package/dist/core/ocr/worker.d.cts +84 -0
  59. package/dist/core/ocr/worker.d.ts +84 -0
  60. package/dist/core/ocr/worker.js +41 -0
  61. package/dist/core/v3/detect-worker.cjs +1 -392
  62. package/dist/core/v3/detect-worker.d.cts +1 -1
  63. package/dist/core/v3/detect-worker.d.ts +1 -1
  64. package/dist/core/v3/detect-worker.js +1 -13
  65. package/dist/create-document-capture-X35M4UAK.js +1 -0
  66. package/dist/create-portrait-capture-5VGYZUOK.js +1 -0
  67. package/dist/create-verification-RdG6qv51.d.ts +3732 -0
  68. package/dist/create-verification-lXGU3ac4.d.cts +3732 -0
  69. package/dist/{detect-worker-CKXHlXx9.d.ts → detect-worker-CHqsPJoM.d.cts} +25 -2
  70. package/dist/{detect-worker-CKXHlXx9.d.cts → detect-worker-CHqsPJoM.d.ts} +25 -2
  71. package/dist/detector-scanic-KMAVOHGF.js +1 -0
  72. package/dist/icao-gate-Cp1C4IEZ.d.ts +578 -0
  73. package/dist/icao-gate-DVNkPclI.d.cts +578 -0
  74. package/dist/icao-gate-T3BTOKFJ.js +1 -0
  75. package/dist/icao-policy-CcrwfsVr.d.ts +80 -0
  76. package/dist/icao-policy-c2Ykm9r2.d.cts +80 -0
  77. package/dist/icao-tuning-4ETMF53W.js +1 -0
  78. package/dist/index.cjs +3 -2649
  79. package/dist/index.d.cts +138 -5
  80. package/dist/index.d.ts +138 -5
  81. package/dist/index.js +1 -28
  82. package/dist/internal/index.cjs +3 -4179
  83. package/dist/internal/index.d.cts +390 -371
  84. package/dist/internal/index.d.ts +390 -371
  85. package/dist/internal/index.js +1 -647
  86. package/dist/keyframe-rank-YAJLYJYF.js +1 -0
  87. package/dist/landmarker-KB7LVXAU.js +1 -0
  88. package/dist/mrz-band-VYHOTDHY.js +1 -0
  89. package/dist/plan-runner-T2ZTSBI4.js +1 -0
  90. package/dist/popup/index.cjs +1 -76
  91. package/dist/popup/index.d.cts +9 -3
  92. package/dist/popup/index.d.ts +9 -3
  93. package/dist/popup/index.js +1 -11
  94. package/dist/print-SEWS3VHQ.js +1 -0
  95. package/dist/scanic-ml-stub-KW7IZHUT.js +1 -0
  96. package/dist/segmenter-USLNBX65.js +1 -0
  97. package/dist/types-B47mZ5TT.d.cts +2107 -0
  98. package/dist/types-B47mZ5TT.d.ts +2107 -0
  99. package/dist/upload-file-EGXXM6TQ.js +1 -0
  100. package/package.json +30 -11
  101. package/sbom.cdx.json +349 -0
  102. package/dist/capture-constraints-BujkZcfb.d.cts +0 -21
  103. package/dist/capture-constraints-BujkZcfb.d.ts +0 -21
  104. package/dist/chunk-7TC6TOZ4.js +0 -1095
  105. package/dist/chunk-7TC6TOZ4.js.map +0 -1
  106. package/dist/chunk-FIXX2AXC.js +0 -864
  107. package/dist/chunk-FIXX2AXC.js.map +0 -1
  108. package/dist/chunk-MWNFSNMP.js +0 -52
  109. package/dist/chunk-MWNFSNMP.js.map +0 -1
  110. package/dist/chunk-NILNKLK6.js +0 -50
  111. package/dist/chunk-NILNKLK6.js.map +0 -1
  112. package/dist/chunk-NWF46H7K.js +0 -359
  113. package/dist/chunk-NWF46H7K.js.map +0 -1
  114. package/dist/chunk-WY6U7AIK.js +0 -193
  115. package/dist/chunk-WY6U7AIK.js.map +0 -1
  116. package/dist/chunk-YVFF4Q4G.js +0 -327
  117. package/dist/chunk-YVFF4Q4G.js.map +0 -1
  118. package/dist/client/index.cjs.map +0 -1
  119. package/dist/client/index.js.map +0 -1
  120. package/dist/core/index.cjs.map +0 -1
  121. package/dist/core/index.js.map +0 -1
  122. package/dist/core/v3/detect-worker.cjs.map +0 -1
  123. package/dist/core/v3/detect-worker.js.map +0 -1
  124. package/dist/create-verification-CP18eq1Q.d.cts +0 -348
  125. package/dist/create-verification-CswF2As-.d.ts +0 -348
  126. package/dist/detector-scanic-4C6IEW2K.js +0 -787
  127. package/dist/detector-scanic-4C6IEW2K.js.map +0 -1
  128. package/dist/hosted-client-BpvBqu9f.d.cts +0 -408
  129. package/dist/hosted-client-BpvBqu9f.d.ts +0 -408
  130. package/dist/index.cjs.map +0 -1
  131. package/dist/index.js.map +0 -1
  132. package/dist/internal/index.cjs.map +0 -1
  133. package/dist/internal/index.js.map +0 -1
  134. package/dist/popup/index.cjs.map +0 -1
  135. package/dist/popup/index.js.map +0 -1
  136. package/dist/scanic-ml-stub-S2OZ6HEF.js +0 -10
  137. package/dist/scanic-ml-stub-S2OZ6HEF.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,438 @@
1
1
  # @sekyro/web
2
2
 
3
+ ## 0.1.0-rc.31
4
+
5
+ ### Patch Changes
6
+
7
+ - a649247: The browser check runs once per session instead of on every selfie video. It starts as soon as the session loads, the session's first submission carries its token, and the server then holds a proof for 30 minutes on this page and device, so later steps (document sides, the selfie video, retakes) send no token. Every code send by SMS, WhatsApp or email still carries a fresh token, and the SDK keeps a check running while a code step is ahead. The device header declares the new `session_proof` capability (requires a Sekyro AI backend from 2026-11-15). A submission waits up to 90 s for a token (was 120 s): the check started at page load, so it rarely waits at all. When the selfie video could not get a token, `retry()` on the capture handle submits the same video again with a fresh check, and the person does not film again. The capture metadata now reports how many checks ran (`attestationChecks`) and how long the submitted token's check took (`attestationChallengeMs`).
8
+
9
+ ## 0.1.0-rc.30
10
+
11
+ ### Patch Changes
12
+
13
+ - e70fdcd: The security check gets the time slow phones need. On entry-level Android phones on mobile networks the check often takes longer than 30 s, and the old 30 s bound failed it, then started it again from zero on a fresh frame. A check now gets up to 120 s, and only a check that failed is retried on a fresh frame, not a slow one. The check frame gets 30 s instead of 10 s to load. When the check started at consent has failed, the camera start begins a fresh one, so it runs while the person films and not after the uploads. A token counts as fresh from when it arrived, not from when its check started.
14
+
15
+ ## 0.1.0-rc.29
16
+
17
+ ### Minor Changes
18
+
19
+ - 1e6001c: Two new document reasons. `document_sides_mismatch` (`DocReason`): the front and the back of the card are from two different cards. It is retryable and not billed. When the front was read first the server keeps it (`acceptedSides: ["recto"]`) and the camera asks for the back only; when the back was read first both faces are dropped and the camera starts the card again. `@sekyro/react` shows `doc.reason_document_sides_mismatch` (six languages) without the photo tips. `document_photo_mismatch` (`DocReason` and `NfcChipReason`): the portrait on the document, or in its chip, is a different person from the registry's photo for its identity number. It is final: the session ends rejected.
20
+ - 06d8764: New document step reason `document_type_not_supported`: the document type chosen cannot be used in this flow (it has no machine-readable zone the flow accepts, or the session does not offer it). It is retryable and not billed. The step comes back with `documentType: null`, so the picker reopens, and the refused type is no longer in `step.documents`; when no other type is left, the step fails with this reason. `@sekyro/react` shows `doc.reason_document_type_not_supported` (six languages) without the photo tips. `identity.document.evidence` says what the identity was read from (`mrz`, `barcode`, `visual` or `chip`).
21
+ - 1c7c752: The Form step's contract (planned: no flow can contain it yet). `CheckType` gains `form` and `StepSection` gains `form`; an open Form step carries `form` on its plan step (`HostedFormView`: the client's text in one `locale`, the questions, the consents and the prefill), and `CheckInputByType.form` is the submission (`FormInput`: answers by question id, consents by id). New types: `HostedFormView`, `FormQuestionView`, `FormFieldQuestionView`, `FormCustomQuestionView`, `FormChoiceView`, `FormQuestionOptions`, `FormConsentView`, `FormAddressValue`, `FormAnswerValue`, `FormInput`, `FormIssueCode`, `FormLocale`, `FormFieldName`, `FormQuestionType`. Until the step is rendered, a Form step still shows "update required".
22
+ - 030c9dc: The Form step (planned: no flow can contain it yet). A plan step of the `form` service is the new `form` step (`FormStepHandle`): `form` holds the partner's questions and consents in one language (`dir` says its direction) and the prefill. `validate(input)` lists the refused answers by question id (`FormIssue`), and `submit(input)` checks them, then submits `form`; a refusal, by this client or by the server (422 `form_answers_invalid`, such as a card number typed into a text answer), rejects with `FormAnswersError` and uses no attempt. A question type or field this version does not know is still "update required". New exports: `FormStepHandle`, `FormSnapshot`, `FormIssue`, `FormAnswersError`, `formIssues`, `containsCardNumber`, `directionOf`, `isFormDate`, `isFormNumber`, `todayIso`, `FORM_ANSWER_LIMITS`, `FORM_ANSWERS_INVALID`.
23
+ - 4581cc5: `HostedSessionView.demo`: present (`true`) on a Sekyro AI website demo session that shows the visitor's own name as `orgName`. The hosted verification page uses it to show "Demo by Sekyro AI" in its header; SDK hosts never run the website demo app and can ignore it.
24
+ - 1b8395d: Flows that take their photos in a native app only. When a flow's Device & Network step is set to capture on "Native app or SDK only", its camera steps carry `requiresNativeApp` and the view carries `nativeApp` (`HostedNativeAppView`: whether the Sekyro AI app is allowed, the session link and the Sekyro AI app link). In a browser such a step is the new `native_app_required` step (`NativeAppRequiredStepHandle`, with `refresh`) instead of the camera. A submission from a browser answers `409 native_app_required` (new in `KNOWN_CODES`); the SDK re-reads the session and shows that step. `@sekyro/react` renders it: the partner's app and, when allowed, the Sekyro AI app (open link on a phone, store links, the session QR on a desktop), in six languages (`needsApp.capture.*`).
25
+ - 43ae1ec: Document capture labels the faces of a document without an MRZ from its barcode. When the session's capture plan says which face carries a barcode (PDF417, QR, Data Matrix or Aztec), the capture decodes it on the device to tell the front from the back; only that yes or no is used, and the server's read still decides. The decoder (`zxing-wasm`) loads by `import()` on such a document only, and its binary is fetched from Sekyro AI's asset host and checked against the sha256 built into the SDK before it runs. New option `barcodeAssetBaseUrl` on `createDocumentCapture` and on the document step's `capture()` to self-host that binary (`<base>/<sha12>/zxing_reader.wasm`, where `<sha12>` is the first 12 hex characters of the file's sha256). When the binary cannot be fetched or checked, capture works as before.
26
+ - 80fbf3d: The document step now tells the server which document type and issuing country the person picked, on every side (camera and upload). A document that is not the one picked is refused with `document_type_mismatch`.
27
+
28
+ ### Patch Changes
29
+
30
+ - a63d45e: In a verification's document step, the camera capture can follow the document catalog for the picked country: the sides to capture, the frame's shape, and whether the document has a machine-readable zone. A document without one is captured like a driving licence (both faces, no live MRZ reader). It applies only when the session asks for it; otherwise capture is unchanged.
31
+ - 98f6752: The document catalog and the identity number rules now come from the shared document catalog. No behaviour change.
32
+ - 567f41a: A refused Form submit now shows which questions to change. The client reads the server's `details.errors` (one `{ id, code }` per refused question) and turns each server code into its own `FormIssue` code, with the limit its message names, so every error appears under its question; a card number keeps its own message. `HostedErrorDetails` gains the optional `errors` list. With no details, the client's own check runs again on what was sent. When a refusal names no question of the form, the Form screen says the answers could not be sent instead of staying silent.
33
+ - a75a33e: The liveness submission is never sent without a security check token. The server refuses every hosted web liveness without one, so a slow or failed check used to cost a certain `attestation_invalid` and the capture's only attestation retry. The SDK now waits for the running check after the uploads and, when a check fails, starts a fresh one after a short pause (at most 3, all within 2 minutes). Only then does the capture end `unavailable` with `reasonCode: "attestation"` and the check's `attestationError`, with nothing submitted. A check still running then serves the next capture. A token the server refuses still gets its one retry with a fresh token. The `attestation` capture issue now also carries Cloudflare's numeric error code (`detail`), the check's duration (`challengeMs`), how long the check frame took to load (`readyMs`) and whether the page runs in an app's WebView (`inApp`). It is also sent once for each failed check.
34
+
35
+ ## 0.1.0-rc.28
36
+
37
+ ### Minor Changes
38
+
39
+ - 14faf9e: The result says when a Sandbox session ran on simulated test data. `VerificationResult.sandbox` is `{ simulated: true, reason }`, the same object as on `GET /sessions/{id}` and the session webhooks. `reason` is `no_testers` (your organization has no active Sandbox tester), `tester_gate_not_used` (nobody ran the tester check at the start of the session) or `tester_gate_missed` (the tester check ran and recognized nobody). No real check ran on such a session. The field is absent in Live and on a Sandbox session an enrolled tester ran. The hosted view's `simulation` block carries the same `reason`, so a step's `context.simulation.reason` is there for your own result screen. The new types `SandboxSimulation` and `SandboxSimulatedReason` are exported.
40
+
41
+ ### Patch Changes
42
+
43
+ - 94565f2: `provenance.rampPainter` is now `true` only when the screen ramp challenge is one this client can render. Before, any challenge handed to the engine set it, so a challenge of another version's shape painted nothing and still reported a painter; the backend then recorded the capture as a ramp that went missing instead of a client that cannot paint it. No API change.
44
+
45
+ ## 0.1.0-rc.27
46
+
47
+ ### Minor Changes
48
+
49
+ - 707ccc7: Levels are renumbered: `1` Contact, `2` Human, `3` Identity, `0` when nothing was proven. `VerificationAssurance` gains the Contact values `device_only`, `contact_email`, `contact_phone` and `unbound_identity`. A result's `level` stays a display hint: a check for a real person is now `level >= 2` and a check for identity `level >= 3`. To require a particular proof, compare `assurance` with a list of accepted values on your server, for example `["registry_biometric"]`.
50
+
51
+ ## 0.1.0-rc.26
52
+
53
+ ### Minor Changes
54
+
55
+ - 246b0f3: Proof of address and the driver's license. A `poa` step in the flow is the new `proof_of_address` step (`ProofOfAddressStepHandle`): it shows the accepted documents the server resolved for the person's country (`rule`: each kind with its own `maxAgeDays` and `earliestIssueDate`), the name rule and the phase (`document`, or `holder_letter` when the bill is in another person's name). `uploadPages(files)` sends 1 to 3 images or one PDF (the new `document_file` media kind, `application/pdf`), `uploadHolderLetter(files)` sends the holder's letter, and `capturePage({ video })` takes one photo per page on the rear camera. On a desktop an upload step stays on the desktop; a camera step continues on a phone. `drivers_license` joins the accepted document types: two faces on the card frame, no live MRZ reading, offered only when the flow lists it. New types: `PoaKind`, `PoaReason`, `PoaNameMatchMode`, `PoaRuleSource`, `HostedProofOfAddressView`, `HostedPoaRuleView`, `HostedPoaRuleKindView`, `PoaInput`, `ProofOfAddressSnapshot`, `ProofOfAddressStepHandle`, `PageCaptureHandle`; `CheckType` gains `poa`, `MediaKind` gains `document_file`, `IdNumberType` gains `drivers_license` (Mauritania: the 8-digit number; elsewhere 4 to 20 letters or digits). A document photo of a driver's license sends `documentType: "drivers_license"` in the `doc_ocr` input (`DocOcrInput.documentType`), so the server reads it with its document reader. When the view says `proofOfAddress.licenceAddressAccepted`, `useLicenceAddress()` passes the step with the address the driver's license gave (`PoaLicenceInput`, no media).
56
+
57
+ ### Patch Changes
58
+
59
+ - cc7eedb: The challenge frame binds its token to the public session id (`ses_<hex>`), the subject the server checks, instead of the bare id from the session view.
60
+
61
+ ## 0.1.0-rc.25
62
+
63
+ ### Minor Changes
64
+
65
+ - 0d23a56: The liveness attestation now runs in the Sekyro security check frame. `createVerification` asks a hidden frame served from `https://verify.sekyro.ai/challenge` for the token instead of loading Cloudflare Turnstile in your page, and the token is bound to the session and to your page's origin. If your page has a Content-Security-Policy, allow `frame-src https://verify.sekyro.ai`; the `challenges.cloudflare.com` entries in `script-src`, `frame-src` and `connect-src` are no longer needed.
66
+
67
+ - `HostedSessionView.challenge: { url, siteKey } | null` (`HostedChallengeView`) replaces `turnstileSiteKey`.
68
+ - The liveness `attestation` body no longer carries `siteKey`: it is `{ channel: 'hosted_web', turnstileToken }`, or `{ channel: 'hosted_web' }` when no token was obtained.
69
+ - When the frame produces no token, the submission records `input.capture.attestationError`, the SDK reports one `attestation` capture issue, and a result with `reasonCode: 'attestation'` carries `attestationError` (`ChallengeErrorCode`): `challenge_frame_blocked`, `challenge_script_blocked`, `site_key_rejected`, `challenge_failed`, `timeout`, `embedder_opaque` or `aborted`. A blocked frame also prints one console line naming the `frame-src` to allow.
70
+ - Timing is unchanged: the token is fetched when the camera starts, a failed challenge runs once more on a fresh frame, the submission waits at most 30 s for it and is sent without one as the last resort.
71
+ - A challenge that failed earlier (for example the prefetch at camera start on a blocked frame) still sets `input.capture.attestationError` and the result's `attestationError` when the submission's own challenge does not finish within the 30 s wait.
72
+
73
+ ## 0.1.0-rc.24
74
+
75
+ ### Patch Changes
76
+
77
+ - 6dfd321: Fixes liveness submissions failing on slow phones because the Turnstile challenge did not finish in time. A challenge now times out after 30 s again (10 s since rc.22). When a challenge fails or times out, the SDK removes the widget and runs the challenge once more on a new one. The submission waits at most 30 s for the token after the uploads finish. If there is still no token, it is sent without one and the server's attestation rules decide; the challenge keeps running, so a retry can use its token.
78
+
79
+ ## 0.1.0-rc.23
80
+
81
+ ### Minor Changes
82
+
83
+ - f7b755c: `StepContext.sandbox`: `true` on a Sandbox session (`view.sandbox`), `false` in Live. The flow is the same in both environments; a UI shows the "Test session" badge from it.
84
+ - 3eafb6e: The tester gate (Sandbox): `HostedSessionView.testerGate` and `StepContext.testerGate` offer "Run real checks as a tester" on a simulated Sandbox session before its first capture, and `verification.testerGate(artifacts)` sends one liveness capture to `POST /hosted/tester-gate`. `bound: true` means the session now runs real checks; `bound: false` keeps it simulated. `HostedClient.testerGate` and the types `HostedTesterGateView`, `TesterGateInput`, `TesterGateResponse`.
85
+ - d25960c: Turnstile runs in both environments: a Sandbox session's view carries Cloudflare's test site key, so the liveness submission sends the same `{ channel: "hosted_web", siteKey, turnstileToken }` as in Live. The `{ sandbox: true }` attestation is gone (the API refuses it in both environments).
86
+
87
+ ## 0.1.0-rc.22
88
+
89
+ ### Minor Changes
90
+
91
+ - ad0d148: Assisted capture uses the back camera only, on the liveness and the portrait cameras, as self capture uses the front camera only. `switchCamera()` on `LivenessCaptureHandle` and `PortraitCaptureHandle` does nothing and returns `false`, and a `facing` option or `start({ facing })` asking for the other camera is ignored; both log one console warning per handle. Under capture mode `choice` the person still switches the mode (`setCaptureMode`), and the camera follows it. `CapturedPortrait.facingMode` reports the camera the photo was taken with, and the portrait submission sends it as `input.capture.facingMode`. New reason `capture_front_camera` on `LivenessReason` and `PortraitIcaoReason`: an assisted capture reported on the front camera is refused before scoring, retryable, not billed and not counted as an attempt (in `RETRYABLE_REASONS`).
92
+
93
+ `@sekyro/react`: the front/back camera choice before an assisted capture and the flip button on the liveness and portrait cameras are gone. `IntroContext` no longer has `setFacing` or `canChooseFacing`; `IntroContext.facing` is the capture mode's camera. The new `reasons.capture_front_camera` string comes in every language.
94
+ - ad0d148: Under capture mode `choice` the person switches between filming themselves and being filmed on the camera view. `LivenessCaptureHandle.canSwitchCaptureMode()` says whether the switch is offered (a device with a front and a back camera), and `LivenessCaptureHandle.setCaptureMode(mode)` switches: the pick is recorded for the session (`Verification.chooseCaptureMode`), a running take restarts in the new mode (the recording is dropped, never submitted, and `CaptureState` passes through `mode_switch`), and the camera reopens on the front camera for `self` and the back one for `assisted`. The mode sets the camera.
95
+
96
+ `@sekyro/react`: `<LivenessCapture>` no longer asks who films before the liveness camera opens. Under `choice` the stage shows a chip in its end corner ("Someone is helping me", then "I film myself") that switches the mode and restarts the take with a "Camera switched" status line; a one-camera device does not show it. The new `capture.modeSwitch.*` strings come in every language. The portrait step keeps its who-takes-the-photo question.
97
+ - ad0d148: Every camera step hands off to a phone on a desktop browser, in every decision mode. `deriveStep` turns a `doc_ocr` or `portrait_icao` step that `requiresMobile` with the camera as its source into the `mobile_required` step (`MobileRequiredSnapshot.checkType` gains `doc_ocr` and `portrait_icao`); a `choice` photo step stays on the desktop with `photo.cameraOnPhone: true`, its upload offered and `refresh()` on the document and portrait handles. `Verification.mobileRequired()` covers every camera step. Under capture mode `choice`, `HostedCaptureTuning.pick` is the session's latest mode and the cameras open in it (`Verification.captureChoice` reports it). `detectFormFactor()` reads Windows and ChromeOS touch devices as desktops; iPadOS stays a tablet; a browser whose client hints (`navigator.userAgentData`) say `mobile` or an Android, iOS or iPadOS platform is never a desktop, so an Android phone in "desktop site" mode (a Windows user agent) is not handed off. The reason `uncalibrated_capture_channel` is gone from `LivenessReason`; `@sekyro/react` keeps its `reasons.uncalibrated_capture_channel` wording and `Strings` entry, frozen in the 0.1 dictionaries, though no reason resolves to it.
98
+
99
+ `@sekyro/react`: `<SekyroVerification>` shows the QR of `handoffUrl` at a camera document or portrait step, with a line that says what the phone is for; a `choice` photo step offers "Continue on my phone" and "Upload a photo", and never opens the webcam. Each of these hand-overs, and the liveness hand-over, uses the styled QR code with the Sekyro AI mark in the centre at error correction level H, like the QR codes in the dashboard. The code no longer shows your branding logo, with or without one in your session branding; the rest of the page keeps your branding. The code stays navy on a white tile, in dark mode and under your branding colours.
100
+ - 0804d05: Only one person may be in the liveness video. The capture gate reads the faces its detector already finds (no new model): while another face has at least a quarter of the person's face area, the gate waits (progress drains, the clip never starts) with the new hint `one_face` on `GateHint` and resumes once one face remains. Smaller faces further back never block. The native `FaceDetector` tier now asks for up to four faces and takes the largest as the person. New reason `multiple_faces` on `LivenessReason`: the server saw a second person in the clip and asks for a new one; retryable, not billed and not counted as an attempt for up to 5 retakes per step (in `RETRYABLE_REASONS`).
101
+
102
+ `@sekyro/react`: new strings `fcv3.one_face` (the guidance line, also spoken by the device voice) and `reasons.multiple_faces` (the retake line) in every language; `hintStringKey("one_face")` and `VOICE_KEYS` include it.
103
+ - ad0d148: The portrait step switches the capture mode on its camera too, under capture mode `choice`. `PortraitCaptureHandle.canSwitchCaptureMode()` and `PortraitCaptureHandle.setCaptureMode(mode)` work as on the liveness handle: the pick is recorded for the session, the camera reopens in the new mode (front for `self`, back for `assisted`) with the gate from zero, and `PortraitCaptureState` passes through `mode_switch`. Before the photo is taken only.
104
+
105
+ `@sekyro/react`: the portrait camera opens on the person's pick (`self` before one) with the switch chip in its end corner ("Someone is helping me", then "I take the photo myself") and a "Camera switched" line; a one-camera device does not show it. The who-takes-the-photo question is gone, and with it `CaptureModePicker` and the `capture.modePicker.*` strings; the new `capture.modeSwitch.*Photo` strings come in every language.
106
+ - f4840d7: `FaceMatchReason` no longer has `prior_review_rejected`: an earlier review is reused only when it approved the match, so a face match step never ends with that reason.
107
+ - 2beba0c: `PopulationReason` no longer has `result_from_cache`: a passed registry step carries no reason. `@sekyro/react` drops its wording (`reasons.result_from_cache`) in every language.
108
+
109
+ An object literal that overrides `reasons.result_from_cache` (for example the strings passed to `resolveStrings` or a custom dictionary typed with the package's strings type) must drop that key, or TypeScript reports an unknown property.
110
+ - 5329680: Screen ramp v2 (the liveness colour flash). The palette is four saturated colours, `magenta`, `yellow`, `green` and `blue` (`ScreenRampColour`); the six pastel names are gone. `ScreenRampChallenge` now carries `holdMs`, `endMs` and `clipMs`, and up to eight colours: the engine paints each colour at its onset, black after `holdMs` when the hold is shorter than the slot, and clears the layer at `endMs`. A capture that applies the ramp records the challenge's `clipMs` (3.0 s as issued, a 2.5 s clip otherwise) instead of 2.5 s. The `ramp` event's `colour` is a `ScreenRampPaint`: a colour, `"dark"` or `null`; `screenRampColourValue("dark")` is black. `SCREEN_RAMP_END_MS` and `SCREEN_RAMP_SEGMENT_MS` are removed (the challenge carries the timing). A challenge in the old shape is ignored: no ramp, the default clip.
111
+ - c5b46c4: A finished session is `verified` or `not_verified`. `SessionStatus` is `created | in_progress | review_pending | verified | not_verified`. A `not_verified` session says why in `reason` (`rejected`, `inconclusive`, `unavailable`, `abandoned`, `not_opened`, `policy`, `cancelled`, `superseded`), with the detailed code in `reasonCode`, who or what closed it in `closedBy` and the deciding step in `step`. Plan steps carry `result` (`passed`, `rejected`, `inconclusive`, `unreadable`, `unavailable`, `review`) next to `attempts { used, max }`.
112
+
113
+ `VerificationResult.status` is `verified | not_verified | review | retry | unavailable`. `reason` is the session reason and the check or SDK code is `reasonCode`. A capture refused while the session stays open (`autoRetry` off, or no try left) is `not_verified` with the reason its step result gives. A parked step with tries left is a `retry`, and a step the service could not run is `unavailable`.
114
+
115
+ The result step's `display` is `verified`, `review`, `rejected`, `inconclusive`, `unavailable`, `expired`, `policy`, `cooldown` or `platform_unsupported`. `ResultSnapshot` carries `reason`, `reasonCode` and `step`. The popup events are `session.verified`, `session.not_verified`, `session.review_pending` and `session.cancelled`.
116
+
117
+ Removed: `HostedSessionView.outcome` and `failureReason`, `SessionOutcome`, `PolicyFailureReason`, `HostedStepView.attemptsExhausted` (`attempts.used >= attempts.max` says it) and `ResultSnapshot.failureReason`. `CheckReason` gains `review_timeout` and `inference_unavailable`.
118
+
119
+ ### Patch Changes
120
+
121
+ - 37a6305: Assisted capture asks for the back camera exactly (`facingMode: { exact: "environment" }`), then a back lens by `deviceId`, then the browser's own pick, on the liveness and the portrait cameras. When only the front camera opens, nothing is recorded or uploaded: under capture mode `choice` the take continues as a self capture on the front camera (the pick is recorded and the stage shows the mode switch), otherwise the capture fails with `kind: "notfound"` and `detail.engineKind: "backcamera"`. Before this, a browser could answer the back-camera request with the front camera, and the server refused the uploaded clip with `capture_front_camera`.
122
+
123
+ `@sekyro/react`: the camera error notice shows the new `fcv2.err.backcamera` string for that failure, in every language.
124
+ - 960f295: Capture provenance reads the iPhone's camera names in the device language. `labelClass` was `unknown` for every iPhone set to Arabic, French, Spanish, Portuguese or German (`الكاميرا الأمامية`, `Caméra avant`, `Cámara frontal`, `Câmera frontal`, `Frontkamera` and their back-camera names). These now read as `platform`, like `Front Camera`. The label is still classified on the device and never sent. The field stays a recorded signal and decides nothing.
125
+ - ab329bc: The portrait and document steps no longer hand out a camera handle that was destroyed. A camera view that unmounts and mounts again on the same `<video>` (React StrictMode in development, or a remount) used to get the cached, destroyed handle back. Its `start()` did nothing, so the camera never appeared. It now gets a new handle.
126
+ - f8eae5a: The document step returns to the camera when the server asks for a retake of a passport page (`doc_ocr` `input_required` with `unreadable` or any other retryable reason). Before, the one-face read was settled as accepted and the camera stayed on the read screen with no way forward; a card whose two faces were both in but still asked for again did the same. Both now re-read the face that was sent. `@sekyro/react`: the retake line over the camera shows the server's reason, as the native SDKs do; a re-read the device asks for by itself keeps the re-read line.
127
+ - 704e58a: Liveness clips now cover their full window on Android browsers. The recording stops once the camera has presented `clipMs` of frames after the recorder started, plus 100 ms for the encoder to hand over the last frame (hard cap `clipMs` + 700 ms), instead of on a timer from `start()`. Browsers without an MP4 recorder (Chromium before 126) record H.264 in WebM on the hardware encoder before VP8 and VP9, and Chromium 126 skips its MP4 recorder. Every finished clip is measured from its container, a Chromium WebM gets the Duration its muxer leaves out, and a clip more than 100 ms short, unreadable or failed by the recorder is recorded once more, silently, then the better take is sent. `CapturedArtifacts` gains `clipFrames`, `fps`, `clipRetakes` and `codec`; `clipMs` is the measured clip length when the container was read. The liveness submission sends them in `input.capture`.
128
+ - 59b610b: A liveness capture made in a desktop browser is never uploaded or submitted, in every decision mode: the verification continues on a phone through the QR code. The device header now also reports the screen's touch points, so the server can tell a tablet that sends a desktop user agent (iPadOS Safari, Android "desktop site") from a desktop.
129
+ - 745caf9: Every hosted API call sends the browser's form factor in the `sekyro-client-form-factor` header (`desktop`, `phone` or `tablet`, from `detectFormFactor()`). The server reads it only to record where a session started and continued when its own request headers cannot tell (Safari or Firefox on a Mac, an iPad); it never decides whether a camera capture is accepted.
130
+ - 1d7ee00: The liveness submission waits less for its Turnstile token, and the consent is recorded when the person taps Continue. When the camera starts and the face capture is the next step, `createVerification` records the consent (the person's first action, spec §3.7) instead of just before the uploads; nothing else is submitted then, and a failed call is made again before the first submission. `createVerification` requests the token when the camera starts (and when consent is recorded), so the challenge runs while the person films, and submits it if it is less than 240 s old (Cloudflare accepts a token for 300 s); a token that is older, or a prefetch that failed, is replaced by a fresh one. One invisible widget per site key is rendered and kept: a later token is `reset()` and `execute()` on the same widget instead of a new widget each time. A challenge now times out after 10 s instead of 30 s; the submission still retries once. `input.capture.attestationMs` reports how long the token took once the uploads had settled.
131
+
132
+ ## 0.1.0-rc.21
133
+
134
+ ### Minor Changes
135
+
136
+ - f3f4313: `PortraitIcaoReason` no longer has `portrait_recaptured`: the server no longer checks a portrait photo for a photo of a screen or a print, so a portrait step never ends with that reason. `@sekyro/react` drops its wording (`reasons.portrait_recaptured`) in every language.
137
+
138
+ ### Patch Changes
139
+
140
+ - ff2011d: The document country picker lists the person's own country first, as detected from their network, when the session accepts a document from it. `HostedSessionView.detectedCountry` and the document step's `detectedCountry` carry it (ISO 3166-1 alpha-2), absent when unknown. The search still covers every accepted country.
141
+ - 5f9503f: Headless flows (`verification.run()`) now report the camera errors of the portrait step to the session, as `<SekyroVerification>` does, with no code change on your side. The reports and the `error` event of a portrait capture now carry `detail` (the failing phase and the thrown error's name), as liveness and document do. A flow that uses both sends one report. This is a diagnostic only: it does not change what the step offers.
142
+ - 74477bc: ID photo gate: a relaxed narrow mouth no longer fails "Neutral expression" (the pucker limit is 0.48 on the device), and each eye is now judged against its own usual openness, so one eye that is always less open passes while a blink or a closed eye still fails. The gate submits a baseline per eye (`gate.baselineEyeOpennessLeft` and `Right`) next to the existing one. The gate also reports its mouth scores (numbers only, no image) for Sekyro staff diagnostics. No code change on your side.
143
+ - bb79da6: Simulated Sandbox sessions now say so in the flow. `<SekyroVerification>` replaces "We sent a code" with a test-session message that shows the code to enter, and offers "Skip with test data" on the document, chip, live photo and portrait steps, before the camera opens and on the camera screen. Headless flows read `step.context.simulation` (`{ otpCode, skipCapture }`) and call `step.skipCapture()` on those steps. Nothing changes on a Live session or a session bound to a tester: the block and the action are absent.
144
+
145
+ ## 0.1.0-rc.20
146
+
147
+ ### Minor Changes
148
+
149
+ - 1005d9e: The document step can take a photo of the document picked from the device. Where the photo comes from is a setting of the step: the hosted session view gains `documents` (`HostedDocumentsView`: `source` `camera`, `upload` or `choice` (`PhotoSource`), `sourcePick` once the person chose under `choice` (`PhotoSourcePick`: `camera` or `upload`), and `uploadOffered`, true when an upload is accepted now). Absent means the camera with no upload offered. Under `camera` no upload is ever offered, even when the step's camera cannot open: the step's source is final. `DocumentSnapshot.photo` (`PhotoSourceState`: `source`, `pick` and `uploadOffered`) tells the UI what to show.
150
+
151
+ `DocumentStepHandle.uploadDocument(file)` sends the picked photo for the face the step asks for and submits `doc_ocr` with `source: "upload"` (new on `DocOcrInput`; a camera photo sends `source: "camera"` when the view has a `documents` block). A JPEG or PNG within 5 MB is sent as picked; a HEIC photo is converted to JPEG on the device where the browser can decode it, and a larger photo is scaled down. It rejects with `RangeError("upload_not_offered")` while `photo.uploadOffered` is false and with `TypeError("unsupported_file")` for any other file. The photo is presigned as a declared upload (`source: "upload"` on the media request, no capture proof). `HostedClient.presign` takes `{ source: "upload" }`, and a repeated `reportCaptureIssue` now resolves when the first send settles.
152
+
153
+ `@sekyro/react` follows the step's source: the camera screen (with "Upload a photo instead" only under `choice` while an upload is offered, never under `camera`), the upload screen at once, or a "Take a photo" / "Upload a photo" choice unless the person already chose for the step.
154
+ - c17645e: The portrait step: an ICAO photo of its own, from the camera or a photo picked from the device, which the server may adjust and the person accepts. The hosted session view's `portrait` gains `source` (`PhotoSource`: `camera`, `upload` or `choice`), `sourcePick` (`PhotoSourcePick`), `uploadOffered`, `fixes`, `fixReview`, `output` (`PortraitOutputFormat`) and `pendingFix` (`HostedPortraitPendingFix`: the original and adjusted photo URLs, the fixes applied and when the URLs expire). `PortraitSnapshot` gains `photo` (`PhotoSourceState`), `pendingFix` and the `review` phase. `CaptureIssueReport.check` gains `portrait`: `@sekyro/react` reports a portrait camera that cannot open as a diagnostic. A step under `camera` never offers an upload, even then.
155
+
156
+ `PortraitStepHandle.uploadPortrait(file)` sends a photo picked from the device (converted on the device like a document upload, presigned as a declared upload without a capture proof) and submits `portrait_icao` with `source: "upload"`; it rejects with `RangeError("upload_not_offered")` while `photo.uploadOffered` is false and with `TypeError("unsupported_file")` for any other file. `PortraitStepHandle.confirmFix(accept)` answers an adjusted photo in the `review` phase (`portrait_icao` with `{ fixReview: { accept } }`, `PortraitFixReviewInput`). A camera photo now sends `source: "camera"` and `capture: { mode }` (new on `PortraitIcaoInput`). `PortraitIcaoReason` gains `portrait_recaptured`, `portrait_morph_suspected`, `portrait_reference_mismatch`, `portrait_declined_fix` and `portrait_fix_review`, and `PortraitFix` names the fixes the server applies.
157
+
158
+ `@sekyro/react` asks "Take a photo" or "Upload a photo" under `choice` unless the person already chose (the upload screen at once under `upload`), shows the adjusted photo next to the original with the fixes in words, "Use this photo" and another photo, and words the new reasons in every language.
159
+
160
+ The face match after an accepted portrait sends no image key: the server compares the liveness capture with the reference, not the portrait.
161
+ - b7e6423: `VerificationResult` no longer carries `personId` or `subjectId` (and `HostedSessionView` no longer has `subjectId`): the hosted session view can be read by anyone holding the link, so it never names the person. Identify the person on your server with the result token's `sub` after you verify the token (the API's `personId` is `per_<sub>`), or with the webhook.
162
+
163
+ ### Patch Changes
164
+
165
+ - 6a53392: Headless flows (`verification.run()`, `verification.liveness()`) now report the capture errors they surface to the session, as `<LivenessCapture>` does, with no code change on your side. A capture bound to no session reports nothing.
166
+ - 1f93754: The device header says when the page runs inside an app's browser (`inApp`), so the dashboard can show how often that happens on an integration. `isInAppBrowser()` is also exported from `@sekyro/web/client`.
167
+ - 6c0141f: `SessionFailureReason` gains `blocked_by_org`: one of the organization's blocks stopped the session. The result screen shows one line asking the person to contact the organization, in every locale. Nothing returns it until blocks are available to the organization.
168
+ - 5994d5d: Retries the service paces are spread out and wait longer when asked. When the service is busy (503 `server_busy` or `request_timeout`), the hosted client waits the `Retry-After` the service sends (2 seconds without one) up to 20 seconds, previously 3, before its one retry. When the model service is unavailable (503 `inference_unavailable`), a submission waits the `Retry-After` (10 seconds without one) up to 20 seconds, previously 30, before each of its three retries. Every such wait is spread by ±25 % (at least 0.5 seconds) so clients do not all come back at the same moment, and the `busy` event's `retryAfterSeconds` is the wait actually taken, so it can have a fraction.
169
+ - 0b01cee: The web SDK sends a device fingerprint for fraud prevention: browser, hardware and camera traits from the ThumbmarkJS library, each hashed in the browser, and the phone model and operating system version on Chromium browsers. It adds the `@thumbmarkjs/thumbmarkjs` dependency, loaded on demand, with no network request of its own. Name device fingerprinting in your privacy notice; see "Device fingerprinting" in the web SDK guide.
170
+ - 5c5f7e3: A code send the server refused no longer moves the number or address a later `send()` without one goes to, nor the local resend cooldown. A resend after a page reload now names no target, so the server sends to the one it kept with the code, instead of failing with an input error.
171
+
172
+ ## 0.1.0-rc.19
173
+
174
+ ### Minor Changes
175
+
176
+ - 5c480f8: Age check (selfie) copy. A document step reached because the selfie could not settle the person's age carries `ageStepUp: true`, and `<SekyroVerification>` shows "We could not confirm your age from the selfie. Continue with an ID document." on the first document screen the person sees, in all six locales. A session stopped with `underage_estimated` ends on "This service is for people who have reached its minimum age." in all six locales, instead of the generic rejection. New string keys: `doc.ageStepUp` and `reasons.underage_estimated`.
177
+
178
+ ### Patch Changes
179
+
180
+ - 61f92b1: Capture failures leave a diagnostic trace. A capture error now carries an optional `detail`: the step that was running (`phase`), the thrown error's `name` (never its message) and the engine's own kind before the public collapse (`engineKind`). A camera that Android Chrome reports as `AbortError` (held by a call or another app) is now `inuse`, and a `SecurityError` is `permission`. `Verification.reportCaptureIssue()` records a shown capture failure on the session (`POST /hosted/capture-issue`); it never changes the session, never bills and never counts as an attempt. `<LivenessCapture>` and the document step of `<SekyroVerification>` report the errors they show.
181
+
182
+ The result screen explains an owner check refused because the same person already earned the starting credit (`failureReason: "starter_credit_claimed"`, hosted owner checks only), in every SDK language.
183
+ - 4555bac: A flow can let the person choose how the face video is filmed. When the session's capture mode is `choice`, the person picks once, before the first camera step, between filming themselves and having an agent film them; the pick holds for the whole session, including the portrait camera. `@sekyro/web`: `Verification.chooseCaptureMode(mode)` records the pick, `captureChoice` reads it, `captureMode()` returns `"choice"` until a pick and the pick after, and the pick is sent with the capture (`input.capture.mode`). `CaptureMode` gains `"choice"` and the new `ResolvedCaptureMode` is `"self" | "assisted"`. The portrait still is encoded at the camera's full size. `@sekyro/react`: `<LivenessCapture>` and `<PortraitCapture>` show the new `CaptureModePicker` when the session is `choice` and nobody has picked yet, in every SDK language.
184
+ - c8ec50f: The hosted client retries once when the API answers 503 `server_busy` or `request_timeout`: it waits the `Retry-After` delay (at most 3 s), then repeats the call. Only calls that are safe to repeat retry: `getSession`, `identityPortrait`, `recordConsent`, `choose`, and `submitCheck` with an idempotency key. A second busy answer reaches the page as before.
185
+
186
+ ## 0.1.0-rc.18
187
+
188
+ ### Minor Changes
189
+
190
+ - 75b8595: The verification result's `sessionId`, and the session reference on the step context (the reference shown on the result screen), now use the `ses_` form that `sessions.create` returns and webhooks name, so your server can match a result to its session without converting it. A bare id you stored earlier still names the same session on the API. The result also carries `personId`, the person in the `per_` form, next to the bare `subjectId`.
191
+
192
+ ## 0.1.0-rc.17
193
+
194
+ ### Patch Changes
195
+
196
+ - c40301a: Phone step: the step snapshot carries the server's phone rules (`phoneRules`, one per country: calling code, valid lengths, digit grouping) and `phoneInternational`, with malformed rules left out. Sends carry `phoneRules: 1`, so the server can answer with the two new reasons `otp_number_invalid` and `otp_number_not_mobile`. The local number check now matches the server's lower bound. Additive: nothing to change on an existing integration.
197
+
198
+ ## 0.1.0-rc.16
199
+
200
+ ### Minor Changes
201
+
202
+ - 0dd0208: Type the review outcome values the session view can carry: the `superseded` session outcome, the face match reasons `prior_review_approved` and `prior_review_rejected`, and the step reasons `superseded_by_retry` and `review_split`.
203
+
204
+ ## 0.1.0-rc.15
205
+
206
+ ### Patch Changes
207
+
208
+ - 7eddbf1: `HostedBranding.colors` no longer carries `danger`, `success` or `warning`. Status colours are standard on every partner page.
209
+ - ff5cc35: Doc comments: `subjectId` on session views and webhooks, and the result token `sub`, are present only once the subject has passed a verification (the API leaves them out before that).
210
+
211
+ ## 0.1.0-rc.14
212
+
213
+ ### Patch Changes
214
+
215
+ - 5fded53: The document camera never stays dark without a word. If the scanner fails to load (a flaky network, or a new deploy that replaced its files), the capture now emits a retryable `error` instead of rejecting `start()` silently. Before it opens the back camera, the capture releases any camera stream an earlier Sekyro capture in the page still holds. If the opened camera shows no picture within 4 seconds (it never plays, its track ends, or it sends only black frames), the capture reopens it once and then emits a retryable `generic` error. When the browser refuses to play a live stream, the retry plays it from the person's tap. `<DocumentCapture>` now gives the reason for a camera error: the permission hint when access was refused, and the camera error's own text otherwise.
216
+ - 37c823e: Add the `insufficient_balance` phone OTP reason: the organization's prepaid balance cannot cover the send, so nothing was sent. `PhoneOtpReason` gains it, and the phone step shows the same "This verification method is not available right now" notice as `spend_cap_reached` (`otp.reason_insufficient_balance`, ar/fr/en and the es/pt/de overlays).
217
+
218
+ ## 0.1.0-rc.13
219
+
220
+ ### Minor Changes
221
+
222
+ - ef0b9b2: Person data (spec 2026-10-31): generic ID number names with the former ones kept. New `isValidIdNumber({ type, issuingCountry, number })` (the per-country rules, mirrored from the server), `normalizeDigits()`, `RegistryStepHandle.submitIdNumber()` (posts `{ idNumber, nni }` with the same value until the former name is removed) and `InvalidInputError.field` value `"idNumber"`; `isValidNni`, `normalizeNni` and `submitNni` are deprecated aliases (`submitNni` posts the same body). Hosted views are read under both field names (`idNumberBound` / `nniBound`, `idNumberFromDocument`, `idNumberMasked`), so the SDK works with servers before and after the change; `PopulationInput.idNumber` is new. The phone step snapshot carries `phoneCountries`. Reason unions and `KNOWN_CODES` carry the new names (`registry_record_not_found`, `id_number_invalid`, `id_number_recheck`, `document_id_number_mismatch`, `id_number_locked`, `id_number_unbound`). Every hosted call, the live-MRZ capture reports included, sends `x-sekyro-sdk: @sekyro/web/<version>` (`SEKYRO_SDK_HEADER`, exported from `@sekyro/web/client`), and capture reports send `missing_id_number`.
223
+
224
+ ## 0.1.0-rc.12
225
+
226
+ ### Patch Changes
227
+
228
+ - 22acfcf: Adds the Age check (selfie) processing step and renders any future server step as processing. Deploy this version before turning on the age check for your organization. The processing snapshot names the running step (`service`), plan steps carry `interaction` (`person` or `server`) on newer servers, `AgeEstimationReason` lists the step's reasons (`age_uncertain`, `age_unavailable`, `underage_estimated`), `underage_estimated` joins the policy reasons, and a sandbox liveness submit accepts `forceOutcome` `age_over`, `age_uncertain`, `age_under` and `age_unavailable`.
229
+
230
+ ## 0.1.0-rc.11
231
+
232
+ ### Minor Changes
233
+
234
+ - a3247a3: Screen ramp and capture provenance (liveness v7). When the session's capture tuning carries `capture.liveness.screenRamp` (a server-issued challenge: three pastel colours and their onsets), `@sekyro/web` paints them through the new `ramp` event of the liveness capture handle while the clip records, stamps each change on the clip's own timeline (the recorder's start, corrected by the video element's frame clock when the browser reports one) and sends what it rendered as `input.capture.screenRamp: {nonce, rendered: [{tMs, colour}]}`. `@sekyro/react` paints the layer in both stages (the face camera of `SekyroVerification` and the 0.1 stage) and hands it to a custom stage renderer as `ramp` on the stage view; a host on `@sekyro/web` alone subscribes to `ramp` and paints a fixed full-viewport element with `screenRampColourValue(colour)`, or leaves the event unbound (then no ramp is reported). Hosts that want ramp verification bind the `ramp` event: `provenance.rampPainter` tells the backend whether a painter was bound, so an unbound host is a client without the ramp rather than one missing it. No ramp in an assisted capture or without a challenge. Every liveness submit now also carries `input.capture.provenance` (the video track's settings with the device id hashed, whether `getCapabilities` exists, the camera label's class against a small list of virtual-camera products, `requestVideoFrameCallback` statistics over the recording, and whether the capture prototypes are still native code): signals only, no media, no raw identifiers. New types: `ScreenRampChallenge`, `ScreenRampColour`, `ScreenRampReport`, `CaptureProvenance`, `HostedLivenessCaptureTuning`. The native SDKs decode the challenge in this release and render it in the following one.
235
+
236
+ ### Patch Changes
237
+
238
+ - 032585b: Liveness retakes: `VerificationResult.retakeHint` and `StepAttempts.retakeHint` (`appearance | motion | lighting | framing`) carry the backend's retake hint; `@sekyro/react` shows the matching `hints.*` copy in place of the reason's generic text. A parked step whose attempts did not grow (a voided capture) is always a `retry`, and `capture_back_camera` / `capture_not_upright` are retryable.
239
+ - f13b832: Adds the `sekyro_app_not_allowed` error code (400, not retryable): the native SDKs receive it when a verification runs in the Sekyro AI app on an application that does not allow it, with `details.continueUrl` to continue in the browser when the request carries a session token. The web SDK does not change its behaviour.
240
+ - 90dde69: Adds the `sekyro_app_unverified` error code (400, not retryable, `details.continueUrl`): the native SDKs receive it when the Sekyro AI app cannot prove itself on an application that has not registered that native platform, and offer to continue in the browser. The web SDK does not change its behaviour.
241
+
242
+ ## 0.1.0-rc.10
243
+
244
+ ### Minor Changes
245
+
246
+ - a3cd61c: Assisted capture follow-ups: the right camera on every device, the ICAO portrait included.
247
+
248
+ - The upright guard applies to phones only. A tablet (iPad, an Android tablet, a Windows or ChromeOS tablet) may stand in landscape and is no longer held. Tablets still count as mobile for `captureChannel`, `mobileRequired()` and the hand-over. `CapturedArtifacts.formFactor` (`"phone"`, `"tablet"` or `"desktop"`, from the user agent, touch and screen size, never the window width) is new and rides in `input.capture.formFactor`.
249
+ - The upright guard also runs while photo-mode keyframes are taken: turning the phone sideways drops them and goes back to positioning.
250
+ - Assisted liveness opens the back camera by default only on a device with a front/back choice; without one (a laptop webcam) it opens the front camera. `LivenessCaptureHandle.facingMode` (new) is the camera of the live stream as its video track reports it, else the requested one. The keyframe mirroring, `CapturedArtifacts.facingMode` and a later switch follow the actual camera, so a webcam that answers a back-camera request with itself is treated as the front camera.
251
+ - The ICAO portrait step follows the session's capture mode. A self capture keeps the front camera only. An assisted one opens the back camera by default on a device with a choice and can switch: `PortraitCaptureHandle` gains `captureMode`, `facingMode`, `start({ facing })` and `switchCamera()` (assisted only, until the photo is taken), and `PortraitCaptureOptions.facing` sets the first camera. A standalone `createPortraitCapture()` is a self capture.
252
+ - Fix: a portrait camera stream that a newer start superseded no longer overwrites the live one.
253
+ - 7ce5ab1: Breaking (pre-1.0): the session now decides which camera films the face. A flow's liveness step is either a **self** capture (the person films themselves, the default) or an **assisted** capture (an agent films the person), and a capture bound to a verification follows it (`HostedSessionView.capture.mode`, new; the deprecated `capture.cameraSwitch: true` is read as assisted on older backends).
254
+
255
+ - Self: the front camera only. `facing: "environment"` (option or `start({ facing })`) is ignored with a console warning, and `switchCamera()` does nothing and returns `false`. A standalone `createLivenessCapture()` (no session) is a self capture.
256
+ - Assisted: the back camera by default, `switchCamera()` switches and returns `true`.
257
+ - `switchCamera()` now returns a boolean; the handle exposes `captureMode` and `Verification.captureMode()` resolves the session's mode.
258
+ - On a phone the camera must be held upright: a landscape frame holds the gate with the new hint `upright` (guidance key `fcv3.hold_upright`), and turning the phone sideways while the clip records drops that clip and goes back to positioning.
259
+ - Phone detection uses the user agent and touch support, not the window width: a narrow desktop window is a desktop (`captureChannel: "desktop"`, `mobileRequired()`).
260
+ - `input.capture` carries `mode` next to `facingMode`. New liveness reasons `capture_back_camera` and `capture_not_upright` (retryable, not billed): a self session filmed on the back camera or on a phone held sideways.
261
+
262
+ ### Patch Changes
263
+
264
+ - b092ac3: The back camera is no longer mirrored. On the front camera (the default) the face preview and the keyframe stay mirrored like a selfie, exactly as before. When a capture runs on the back camera (`start({ facing: "environment" })` or the in-capture switch), the engine's keyframe and `previewDataUrl` are drawn as the camera sees them, and `<LivenessCapture>` / `<SekyroVerification>` show the back camera's preview unmirrored (an inline `transform: none` on the `<video>`). The liveness clip is unchanged: it was never mirrored.
265
+ - 857ec58: Sekyro flows: the result names the failure that decided the session. A failure a flow fallback took over (e.g. registry `nni_not_found` → document) no longer becomes the rejection `reason`, and its exhausted attempts no longer turn the result screen into « attempts exhausted ».
266
+
267
+ ## 0.1.0-rc.9
268
+
269
+ ### Minor Changes
270
+
271
+ - 8dbdcf3: Sekyro flows: the SDK renders the flow plan of the hosted view (`HostedSessionView.plan`, `flow`), never the flat step list.
272
+
273
+ - New types `HostedPlanView` (`current`, `choice`, `steps`, `sections`), `PlanChoiceView` / `PlanChoiceOption` (with the optional `nationalEid` provider), `PlanStepView` (node id, `service`, `attempts { used, max }` and today's per-type extras), `PlanSectionView`, `HostedFlowRef`; `NfcStepView.mrz`; `StepSection` gains `screening`.
274
+ - **Breaking:** `HostedSessionView.steps`, `methodChoice` and `otpChoice` are removed, and so are `HostedClient.selectMethod()` / `selectContact()` (`POST /hosted/method`, `/hosted/contact`). Use `HostedClient.choose(nodeId, option)` (`POST /hosted/choice`, returns the view). `OtpChoiceView` is deprecated.
275
+ - The step model follows `plan.current`: the choice screen when it is `plan.choice` (`method` for the identity method and `contact_choice` for the contact, as before, plus a new `choice` step for other kinds; every choice step carries `choice` and a `choose(optionId)` action), else the current step by its service (an unknown service, or an active session without a plan, is `unsupported` / `update_required`; server-run services show `processing`). Step ids are node ids (`n_live.icao` is the ICAO portrait). Attempts come from `attempts { used, max }`. The summary is the `summary_confirm` step. Progress: `StepContext.progress` (`plan.sections` with `done | current | upcoming`).
276
+ - In-lane switches follow the open choice (C4 rule §5 item 6): `StepContext.switchable` (`InLaneSwitch`: the choice's options, the lane taken) and `chooseOption(optionId)` on the step handles while it is open. With exactly one other option the screen's direct switch is set (`canSwitch` phone ⇄ email, `canUseDocument` registry → document, `canUseCamera` eID → camera path), at any time, no longer after a failure only; with two or more, offer « Use another option ».
277
+ - `HostedApiError.details` (`HostedErrorDetails`: `issues[]`, `fields`) carries the flow errors' machine-readable details.
278
+ - The liveness submission bundles the face-match keyframe only when no ICAO portrait follows (the ICAO still is then the probe). `409 choice_locked`, `choice_option_unavailable`, `choice_not_found` and `step_not_on_path` re-read the view.
279
+ - Every submission, `choose()`, identity confirm and consent answer is the hosted view (`submitCheck()` / `uploadAndSubmit()` now return `HostedSessionView`; `recordConsent()` returns `HostedConsentView` = the view + `alreadyRecorded`) and is rendered without a re-read.
280
+ - `verification.methodChoice()` / `selectMethod()` and the `method` event keep working over `plan.choice` (`document` → `document_photo`, `nfc` → `document_chip`, `population_registry` → `national_number`, `national_eid` → `national_eid`).
281
+
282
+ ## 0.1.0-rc.8
283
+
284
+ ### Minor Changes
285
+
286
+ - 6571361: Flow model 2026-10-23: `KNOWN_CODES` gains `contact_locked` (the phone-or-email contact choice can no longer change), `identity_confirm_required` (confirm the identity summary before the live photo) and `identity_confirm_locked` (no summary to confirm, or no retake left). All three are 409s from the new hosted routes (`POST /hosted/contact`, `POST /hosted/identity/confirm`) and the submit flow. Nothing changes at runtime until a profile turns on `contact.mode: 'one_of'` or `identity.confirmSummary` (the latter also behind the platform's `IDENTITY_SUMMARY_ENABLED`).
287
+
288
+ **Migration (TypeScript):** `KnownCode` gained three members; code that switches over it exhaustively must handle them.
289
+ - ff0dcc7: Flow model 2026-10-23 (web lane):
290
+
291
+ - Every step snapshot / handle carries `section` (`contact` / `identity` / `live_photo`, an unknown value is kept) and `context.sections` lists the session's sections in order.
292
+ - New steps: `contact_choice` (a `contact.mode: one_of` session: `select("phone" | "email")`; the OTP handles gain `canSwitch` / `switchChannel` / `switchTo()`) and `identity_summary` (the masked identity data to confirm before the live photo — `summaryKind` `full` / `partial`, `birthYear` on a partial one; `portrait()`, `confirm()`, `retake()`; a partial summary without a masked NNI shows the last 4 of the NNI typed on this page); it outranks the live-photo frontier.
293
+ - `eid.afterPass` / `nationalEid.afterPass` (`continue`: a live photo follows the national eID).
294
+ - Implicit consent: the runner records the consent right before the person's first action (method, contact choice and summary answers included); a `consent_required` reply records it and retries once. `contact_locked` / `identity_confirm_*` re-read the session.
295
+ - Step 3 one-capture live photo: `liveness.instructions` (`icao` on an ID-document session), `liveness.livePhoto` and `onLivePhoto()`. On an ICAO session the liveness gate also waits for the ICAO conditions (Face Landmarker, same gate as the portrait step) and, when it fires, a full-resolution unmirrored still (long side ≥ `capture.livePhoto.still.minLongSidePx`, JPEG `jpegQuality`) is sent with the liveness submission as `input.portraitIcao`; a still below the minimum is never sent. `portrait.retakeOnly` marks a portrait-only retake; when the server could not run the ICAO check the runner submits the same still directly. Old backends keep the sequential path.
296
+ - ICAO background-uniformity check (ID mode only, portrait step and one-capture live photo): the MediaPipe selfie segmenter (`selfie_segmenter.tflite`, lazy, self-hosted under `assetBaseUrl`) removes the person a few times per second; colour spread, edge density and brightness gradient around the head and shoulders hold the shot with the "plain, light wall" coaching for at most `timeoutMs` (then the shot proceeds; the server decides). Strip fallback beside the face when the segmenter is missing or slow. Thresholds: `capture.icao.backgroundCheck` (defaults in `BACKGROUND_CHECK_DEFAULTS`); the numbers ride `portrait_icao` `gate.backgroundCheck`.
297
+ - `HostedClient.selectContact(channel)`, `confirmIdentity(decision)`, `identityPortrait()` (session-token header, returns a `Blob`); view types `otpChoice`, `identitySummary`, `capture.livePhoto`, `docCapture`, `LivenessInput.portraitIcao`.
298
+ - The Turnstile loader now loads on first use (its own chunk, −459 B gzip on the liveness-only bundle), which pays for the new client calls: that bundle stays at ~18.6 KB (budget unchanged).
299
+
300
+ **Migration (TypeScript):** `VerificationStep` / `StepSnapshot` gained two members (`contact_choice`, `identity_summary`); exhaustive switches must handle them. Hand-built handles (test fakes) need the new required fields (`section`, `context.sections`, `canSwitch`, `switchTo`, `afterPass`, `instructions`, `livePhoto`, `onLivePhoto`, `retakeOnly`).
301
+ - 46905f2: National eID sign-in (SDK spec §3.2; Houwiyeti in Mauritania) in the headless web runner: the `eid_auth` check type, the `national_eid` identity method with `methodChoice.nationalEid`, the `HostedStepView.eid` view and the `eid_*` reasons, and an `eid` plan-runner step whose handle offers `start(identifier?)`, `verify(code)`, `resend()` and `useCamera()`. `@sekyro/react` has no eID screen yet: its method screen leaves `national_eid` out and `<SekyroVerification>` shows the "unsupported" notice when the eID is the only path.
302
+
303
+ **Migration (TypeScript):** these exported unions gained members — `CheckType` (`eid_auth`), `IdentityMethod` (`national_eid`), `CheckReason` (the `eid_*` reasons), `VerificationStep` (a new `kind: "eid"` step). Code that switches over them exhaustively must add an `eid` branch. An invalid eID number rejects with the existing `InvalidInputError("nni", …)`. Nothing changes at runtime until a profile turns the national eID on.
304
+ - 7a3f935: Phone OTP channel choice and the email OTP step.
305
+
306
+ - `@sekyro/web`: the phone OTP step lists the channels the person can choose from (`PhoneOtpSnapshot.channels`, WhatsApp first; `[]` on a session created before channel choice). With more than one, `send({ channel })` needs the person's choice — it is never picked for them — and a channel the step doesn't offer is refused locally with the new `OtpInputError` (`channel`, `required` / `unavailable`). `resendAvailableAt` now follows the server's resend time when the session reports one. New `email_otp` step (`EmailOtpStepHandle`: `send({ email })`, `verify(code)`; a malformed address rejects with `OtpInputError("email", "format")`), shown before the identity-method choice like the phone step. New types: `HostedEmailOtpView`, `EmailOtpInput`, `EmailOtpReason`, the `email_otp` check type and the reasons `otp_channel_unavailable`, `otp_destination_not_allowed`, `otp_destination_unknown`, `otp_rate_limited`, `email_invalid`, `email_disposable`.
307
+ - `@sekyro/react`: `PhoneOtpStep` shows one "Send code by …" button per offered channel (WhatsApp first) and a "Resend by …" button per channel after the server's resend time; sessions without channels keep the single "Send code" button. New `EmailOtpStep` (rendered by `SekyroVerification` for the `email_otp` step); its view and ar/fr/en copy load on demand, so apps without an email check don't download them. New copy keys `otp.chooseChannel`, `otp.sendBy`, `otp.resendBy`, the new `otp.reason_*` keys and `emailOtp.*` (overridable through `strings`).
308
+ - `@sekyro/node`: profile `phone.channels` / `phone.destinations`, `email` (`ProfileEmail`: `emailSource`, `disposable`), `attempts.email`, the `input.email` session anchor and the `email_otp` check type.
309
+ - c9edead: `<SekyroVerification>` takes the Sekyro identity the Android and iOS SDKs share: the partner's logo (or initials) and name
310
+ over "identity verification", the section progress (flow model v3) drawn as thin bars, the Sekyro brand as the default
311
+ theme (partner branding and the runtime theme still win), six-box one-time code fields, document cards with an icon
312
+ and a subtitle, the camera stages in the Sekyro navy, and a "Verified by Sekyro AI" footer (`slots.footer` replaces it,
313
+ `footer: null` hides it). New `colorScheme` prop: `light` (default), `dark` or `system`; in dark a partner's brand is
314
+ kept only while it stands out from the dark canvas.
315
+ The 0.1 surface (`DEFAULT_THEME`, `styles.css`, `<LivenessCapture>` and the other 0.1 components) is unchanged.
316
+
317
+ **Visible to existing `<SekyroVerification>` integrations.** Without a `theme` prop or session branding the flow now
318
+ draws in the Sekyro brand (it used `DEFAULT_THEME` before) and ends with a "Verified by Sekyro AI" line. To keep your
319
+ current look, pass your colours (`theme={{ colors: … }}`, or set them as the app's branding) and `slots={{ footer: null }}`.
320
+ `verification.css` now loads the SDK's fonts (`./fonts/*.woff2`): your bundler must emit them as assets (esbuild needs
321
+ `loader: { ".woff2": "file" }`; Vite, webpack 5 and Next.js do it by default) and your CSP `font-src` must allow them.
322
+ - 4e6bfb8: `createDocumentCapture({ video, documentType })` is now public: the guided rear-camera scanner for identity cards (ID-1 or ID-2), residence permits and passport data pages of any issuing country. Cards can be shown either face first; after the first photo the `scan` event asks to turn the card over and the other face is taken once the flip is seen (same flow as the Sekyro native SDKs). A blurred photo is refused before upload and retaken at once (`scan.notice: "blurry"`). Coaching (`feedback`), the gate ring (`gate`), a manual shutter fallback and the torch toggle are included; `captured` delivers an upload-ready JPEG per face. Live camera only. Its engine loads on first use, so the main bundle does not grow.
323
+ - 69638fa: The plan runner now drives the document step for any issuing country (`selectDocument(issuer, type)` then `capture({ video })`: the SDK uploads each side and follows recto → verso) and the liveness step (`capture({ video })`), and ends on a typed `result` step for every outcome: approved, review, rejected, expired, policy stops, device cooldown (with `retryAfter`), "needs a phone app" (`platform_unsupported`) and no attempts left. After a wrong national number (`nni_recheck`) the registry step comes back with `recheck: true`, and the face match is resubmitted with the photo already taken.
324
+ - fce1604: Web live MRZ (on-device, server-controlled, additive):
325
+
326
+ - `@sekyro/web`: `DocumentCaptureOptions.liveMrz` (`mode`, `assetBaseUrl`, `workerUrl`) and the text-free `mrz` event (`searching` / `reading` / `valid` / `mismatch` / `fallback`, with a format, a coaching hint or a reason — never MRZ text). On a face with an MRZ, the session's `capture.document.liveMrz` tuning lets the on-device reader (the OCR engine in a Web Worker, now with a 494 KB MRZ-only recognizer) take the photo once every hard check digit validates twice in a row; card fronts get a text-layout lock (`capture.document.frontLock`). Every failure is today's capture. `doc_ocr` submissions carry the optional, text-free `deviceRead` hint (`DocOcrInput.deviceRead`, `DocDeviceRead`) when the still confirmation is ready. New static file `core/ocr/worker.bundle.js` (a self-contained OCR worker for static hosting).
327
+ - `@sekyro/react`: `SekyroVerification`'s `documentLiveMrz` and `DocumentCapture`'s `liveMrz` pass the options through; the document view shows the reader's states (ar/fr/en), a band strip and the 2 s "this looks like a passport/card" line.
328
+ - 426e180: On-device OCR engine for the browser (web live MRZ, groundwork; nothing in the capture flow uses it yet): a new `@sekyro/web/core/ocr/worker` module-worker entry runs the shared Sekyro OCR engine compiled to WebAssembly (SIMD, single thread; built and locked in the private `packages/sekyro-ocr-wasm`). The worker downloads its wasm and models lazily, checks every byte against a sha256 manifest compiled into the SDK before compiling or loading anything, and answers MRZ band reads with geometry, the MRZ format, a check-digit validity flag and a session-salted digest — never the read text. No change to the root entry's bundle or public API.
329
+ - b4c8465: Profile v2 step model: `deriveStep(view)` tells you which step a hosted session waits on (phone OTP, method choice, registry, document, liveness, results, policy stops, cooldown), `isValidNni` / `normalizeNni` check an NNI before it is submitted, and `acceptedIssuers` / `acceptedTypesFor` read the per-country accepted documents (`HostedSessionView.acceptedDocuments`). Nothing existing changes.
330
+ - 225aeea: Plan runner: `await verification.run()` returns the step the session waits on and `verification.on('step', …)` delivers every next one with its actions — `send(phone?)` / `verify(code)` for the phone OTP, `select(method)` for the method choice, `submitNni(nni)` / `confirm()` / `useDocument()` for the registry, `capture({ video })` for liveness, `refresh()` while processing. Inputs are checked before anything is submitted (`InvalidInputError`). Without `run()` the SDK behaves exactly as before.
331
+
332
+ ### Patch Changes
333
+
334
+ - b81288e: Adds types for the native-only `capture.document.ocr` block (`HostedOcrTuning`) and `capture.document.scan.blurRefuseSharpnessMax` (`HostedDocumentScanTuning`, `HostedDocumentCaptureTuning`), reachable through `HostedNativeCaptureTuning` (narrow `HostedSessionView.capture` to it). `HostedCaptureTuning` is unchanged; the web SDK ignores both blocks.
335
+ - d0c4f27: Capture telemetry: the v3 engine's `telemetry` callback gains a `gate` event — for the attempt, every face-gate tick that did not let progress rise is charged to ONE reason (`no_face`, or the weakest check: `size`, `centering`, `pose`, `exposure`, `sharpness`, `motion`) with its tick count and the milliseconds it covered, plus the accepted time and the device class / detection cadence ACTIVE at the end (after any dynamic profile adjustment). Throttled snapshots (≤ 1 per second) while positioning, one `final: true` report at fire / error / retry / destroy. Read-only over the gate: no threshold, calibration or gate behaviour changes.
336
+ - 3438e10: Live-camera capture proof (D8): the SDK's own capture flows (liveness clip + keyframe, document sides, ICAO portrait) now presign through `HostedClient.presignCapture`. It attaches a single-use server capture nonce (prefetched by `armCapture` when a liveness flow starts, else fetched just in time) with the capture engine and duration. `presign` (no proof) is unchanged. When the backend has no nonce route, the presign goes out without a proof, as before.
337
+ - e82324a: Document capture: ID-1 cards (fronts and backs, any issuer) lock from the card measured inside the on-screen guide — the native Lumière measure (row/column gradient edges → fill, centring, edge strength; card-only glare; sharpness) with a lock on a good card held `lockMs` or a steady card held `steadyMs` — instead of depending on the detector's largest contour, which a hand or a patterned floor around the card turned into an edge-clipped quad forever. Web calibration: the guide is the card slot (no margin), card-only glare gated at 0.025, steady deltas scaled to the tick interval, the edge pick prefers the guide's side, and a card must be card-shaped and printed (no lock on a floor tile). Thresholds come from server `capture.document.guide` (`resolveGuideLockTuning`); hosts pass the drawn guide (`guide` option / `setGuide()`). The quad gate still fires where it frames; passports keep the MRZ-band lock. The manual-shutter safety net now waits for `steadyMs + lockMs` of an unlocked detection; `captureReport()` adds `guideBlockers`.
338
+ - c9edead: Document capture: `DocumentCaptureHandle.setGuide(guide)` declares where the on-screen guide is drawn (normalized rect in a `object-fit: cover` video of aspect `viewAspect`), so a full-screen camera with its guide above the middle locks on the card in that guide; the `gate` event carries `guide` — the card measured inside it (`detected`, `fill`, `offsetX`, `offsetY`) — so a UI can frame the card the camera sees.
339
+ - f0ba853: Document capture safety net: `CaptureSessionDoc` emits a `shutter` event offering the manual shutter (`captureNow()`) after `manualShutterMs` (6 s, server `capture.document.scan`) without a capture, or once a document has been detected for `steadyMs` (1.5 s) without the gate locking — e.g. a card held in a hand, where the detector's largest contour is edge-clipped on every frame. A manual still skips the engine's focus gate (the server decides). `captureReport()` returns a PII-free per-side report (capture path, timings, per-tick lock-failure reasons) for telemetry. Lock, zoom and focus behaviour are unchanged.
340
+ - 626104f: Document capture resolution: the scanner asks the opened back camera for up to 4K, takes the full-sensor `ImageCapture` photo where the browser has one (else the native video frame), crops the still to the document (card + 15 % margins, or the passport page estimated from the MRZ band) and encodes the crop at a 2560 / 2240 / 1920 px long edge (1.6 MB / 1.2 MB / 700 KB budgets). A passport MRZ goes from ~630 px to ≥ 1300 px wide where the camera delivers the pixels. `@sekyro/react`'s document stage switches to a 4:3 layout when the phone is held sideways.
341
+
342
+ Focus: the scanner ranks the back cameras after permission and opens the main wide lens (lowest-index Android back camera with continuous AF; iOS "Back Camera"), remembered per browser, falling back to `facingMode`. It applies continuous autofocus where offered, refocuses (single-shot at the document) before the photo, zooms in (≤ 2×) when the camera reports a minimum focus distance beyond the document's fill distance (1.5× on a ≥ 4K track with no focus info), refuses an out-of-focus auto-captured still (`focus_far` coaching, `dcv2.focus_far`), and adds `DocumentCaptureHandle.focusAt(x, y)` for tap-to-focus (wired into `@sekyro/react`'s stage). All feature-detected; no-ops where unsupported.
343
+ - 0f19e99: Document capture: the manual shutter is offered only while a document is in view (seen by the quad or the guide lock within the last 1.2 s) and is withdrawn otherwise — a tap can no longer upload a frame with no document in it. Zoomed in with nothing in view, the scanner coaches "move a little farther" after `camera.noDocFarHintMs` and drops the zoom to 1× after `camera.zoomFallbackMs` (server tuning; report field `zoomFallbackAtMs`).
344
+ - 76174c8: The document capture internals gain an `onFaceReport` seam: one engine report per document face (`captured`, or `abandoned` when destroyed mid-face after the engine ticked), so the hosted page can keep its scanner telemetry.
345
+ - 67a6be3: The document camera takes a steady card after 0.9 s instead of 1.5 s (`GUIDE_LOCK_DEFAULTS.steadyMs`, used when the session sends no capture tuning). The hosted backend serves the same value from capture tuning version `2026-10-23.2`.
346
+ - c9edead: Document capture no longer uses `ImageCapture.takePhoto()` on WebKit (Safari and every iOS browser). iOS 18 Safari ships ImageCapture, and its `takePhoto` aborts Safari's GPU process (`AVCapturePhotoOutput setMaxPhotoDimensions:` throws): the camera track goes muted, the page goes black and the scan never finishes. WebKit keeps the native video frame for the still, as before ImageCapture existed there; Chromium keeps the full-sensor photo.
347
+ - 650d70d: Treat an empty liveness recording as a recorder failure. iOS Safari can stop a `MediaRecorder` without delivering any data; the SDK used to upload the 0-byte clip, the API refused it (400) and the capture stalled. The capture now fails with the retryable recorder error so the person records again.
348
+ - 68b5df5: `HostedSessionView.acceptedDocuments` (optional): the document types accepted per issuing country, for an issuer-first document picker (profile v2 §5.3a).
349
+ - 4c1aa5b: International documents (profile v2 §5.3a): the document type `residence_permit` joins `AcceptedDocumentType` / `ProfileDocumentType`, and `carte_identite` now means a national identity card of any issuing country. `acceptedDocumentTypes` keeps listing only `carte_identite` and `passport`.
350
+ - 273d2ce: Live MRZ: the passport band read around the detected MRZ is at least a fifth of its width tall (a thin detect band cut the MRZ lines, so passports never read on device).
351
+ - 9db49b8: Adds the `nationality_unreadable` document reason: the MRZ nationality (no check digit covers it) could not be read as a country code, nor recovered from a re-read or the printed nationality — retryable with a clearer photo, not billed, and never replaced by the issuing state. `@sekyro/web`: in `DocReason` and the retryable set (the same document side is re-read). `@sekyro/react`: `reasons.nationality_unreadable` copy in ar/fr/en.
352
+ - 6420611: `HostedSessionView` now types the optional `capture` (server capture-coaching tuning) and `integrity` (native device attestation) blocks the hosted API returns. The web SDK does not change its behaviour. Adds the `device_integrity_failed` liveness reason and the `platform_unregistered` / `app_attest_invalid` / `too_many_challenges` error codes used by the native SDKs.
353
+ - 9acafe1: NFC chip check (M-nfc). New check type `nfc_chip` (read by the native SDKs only), its reasons (`NfcChipReason`: retryable `chip_read_failed`, `chip_access_denied`, `chip_parse_failed`; final `chip_not_present`, `nfc_unavailable`, `chip_document_mismatch`, `chip_integrity_failed`, `registry_mismatch`, `document_nni_mismatch`, `platform_unsupported`), the error codes `method_not_offered` and `nfc_outcome_not_accepted` (`KNOWN_CODES`), the identity method `document_chip`, the session failure reason `platform_unsupported` and the optional `HostedStepView.nfc` hints (`NfcStepView`). Web behaviour is unchanged: the server skips the chip for web clients or stops the session with `platform_unsupported`; `@sekyro/react`'s method screen never renders the `document_chip` option.
354
+ - 2055ae5: Adds the `nni_recheck` registry reason (profile v2 §4.4 wrong-number re-entry): after a face match fails against the registry record of a typed national number, the registry step is re-opened once (`input_required`, reason `nni_recheck`) so the person can re-enter the number. `@sekyro/web`: in `PopulationReason` and the retryable set.
355
+ - 9e27401: The OCR worker manifest pins the canonical CI rebuild of the wasm engine (`c15968a6…`, new asset directory `08390000c48a`). Behaviour is unchanged.
356
+ - 723039c: ICAO gate (ID mode): the pitch limit now applies around a 4° offset (`capture.icao.pitchOffsetDeg`, bundled fallback 4 — the same value kyc-portrait applies server-side), so faces people judge frontal are no longer coached to "look straight". `baselineEyeOpenness` is documented as 1 − the Landmarker blink blendshape (the server's unit) and is never sent when it rounds to 0.
357
+ - 4dd2b68: ICAO `id_document` portrait capture on the web (SDK spec §5.4, M1b): `createPortraitCapture` (strict ICAO gate on the MediaPipe Face Landmarker, lazy-loaded engine, server `capture.icao` tuning), a `portrait` plan-runner step that submits `portrait_icao` and then `face_match` with the portrait, the `portrait_required` hand-over reason, and `<PortraitCapture>` in `@sekyro/react/verification`.
358
+ - 471d833: ICAO `id_document` portrait mode (SDK spec §4.9), types and partner helper. New check type `portrait_icao` with its reasons (`PortraitIcaoReason`: `icao_pose`, `icao_eyes`, `icao_mouth`, `icao_occlusion`, `icao_lighting`, `icao_background`, `icao_resolution`, `portrait_not_from_liveness`, all retryable), the per-criterion report (`IcaoReportEntry` on `HostedStepView.icao` and `SessionStepView.report`), `HostedSessionView.portrait` and the `PortraitIcaoInput` submission shape. `@sekyro/node`: `sessions.portrait(id)` returns a 5-minute link to the 480×640 portrait (scope `portrait:read`), `Session.portraitAvailable` and the same flag on the terminal and `review_decided` webhook data. Web behaviour is unchanged: the browser ICAO gate ships later, so the web step model renders `portrait_icao` as "update required".
359
+ - 8425e95: Face-match probe binding (SDK spec §4.10): the server matches the face_match probe against face crops of the scored liveness clip. New retryable, billed `face_match` reason `probe_not_from_liveness` (the face image isn't the person in the liveness clip). `@sekyro/web`: in `FaceMatchReason` and the retryable set (the runner re-captures). `@sekyro/react`: ar/fr/en retry copy "Keep your face in the frame the whole time, then try again"; bundle budget 24 → 25 KiB. `@sekyro/node`: `ProbeBindingReason`. No capture or upload change on any platform.
360
+ - c9edead: `<SekyroVerification>` matches the native SDKs on the remaining screens. Consent stays flow model v3's one line (no consent screen). The face capture (liveness and the ICAO live photo, whose tips the Sekyro face intro lists) is the Lumière face camera, edge to edge: the oval cut from the ink, a ring of ticks that turns green with the capture while the aqua light runs round it, the instruction above the oval. New optional `onClose(event)` prop: when given, the header ends with a close button (`{ reason: "cancelled" }`) and the result page with "Back to {org}" (`{ reason: "finished", result }`); `VerificationResultScreen` takes an optional `onClose` for the same action. The SDK's fonts (Inter, Inter Display for titles, Cairo for Arabic) ship as woff2 assets beside `verification.css` (`font-display: swap`, `unicode-range`). Also: resending a code is a quiet text action with its countdown; the document intro offers "Change document" when the country has other documents and "Change country" only with several countries; the ID card's landscape glyph; white turn cue; one 2 px read line; the lock and the capture checks in the camera's own green; the reference is one tabular caption line with a copy glyph. In `@sekyro/web`, a card's face is classified on the card itself (an MRZ band in its lower half), so the photo side is no longer filed as the verso. The 0.1 surface (`DEFAULT_THEME`, `styles.css`) is unchanged.
361
+ - 8425e95: Returning-user sessions (profile v2 step 5): `HostedSessionView.returning` and the optional `Verification.returning()` tell the host the session only confirms a known person (liveness + face match against their stored photo); `<LivenessCapture>` opens with "Confirm it's you" (ar/fr/en) unless the host renders its own header.
362
+ - a3689e4: The step runner applies the session's `capture.document` camera, scan and guide tuning (and the `scan.blurRefuseSharpnessMax` blur gate) to the document camera, so the hosted page and partner integrations get the same server tuning. Explicit `documentInternals` seams still win.
363
+ - 45f639f: Licence: the SDKs are now under the Sekyro AI SDK License of Ibtikar Technologies, Inc. (https://sekyro.ai/en/legal/sdk-license, also in French and Arabic). `package.json#license` is `SEE LICENSE IN LICENSE`, and each package's `LICENSE` summarises the licence and links to it. `@sekyro/web` now also ships `THIRD-PARTY-NOTICES.txt` with the MIT notice of the bundled scanic document detector and the MIT/NCSA notice of the Emscripten glue in its OCR worker.
364
+ - bc29977: Selfie ICAO policy (spec 2026-10-24): `HostedSessionView.portrait` becomes `HostedPortraitView` (`purpose: "verification" | "id_document"`, optional `icao: { policy: "reject" | "alert"; profile: "id_document" | "selfie" }`). The new `icaoPolicyOf(view)` is the one activation rule: ICAO runs when `portrait.icao` is present or the purpose is `id_document` (an older server's `{ purpose: "id_document" }` alone reads as `reject` / `id_document`). The liveness and portrait snapshots carry it as `icao`; `PortraitCaptureOptions.policy` and the live-photo kit take the policy. With `alert` the gate coaches but never blocks: the capture goes `capture.icao.alertGraceMs` (default 3000) after the face was accepted at the latest. `capture.icao` gains `profile`, `alertGraceMs` and `background.required`; with `background.required: false` (the `selfie` profile) the background is not measured, coached or reported, and the web segmenter check never loads. The bundled fallbacks are now the generated device limits of the profile (a little stricter than the server, from packages/sekyro-contract/icao/profiles.json) instead of looser ones. The gate's per-criterion decision is the pure `judgeIcao`, checked against the shared conformance cases. `portraitIcao.gate.criteria` is now the device verdict as booleans under the server's criterion names (`IcaoGateSummary.verdict`; `framing` folds into `resolution`, unmeasured criteria are omitted). While the eye baseline is still being learned, the gate now says "hold" instead of coaching the eyes.
365
+ - 5eec558: Keyframe ranking (SDK spec §4.8a, M1a), off by default. When the server capture tuning sets `capture.liveness.keyframe.rank: true`, the liveness engine loads a small lazy chunk and picks the face_match keyframe among the same 4 best-of-N candidates (unchanged 600 ms window) by frontal pose (BlazeFace nose-to-eye-midpoint yaw proxy plus eye-line roll), then relative eye-openness (neutral on web: no landmarker in liveness), then detector confidence as an occlusion proxy, with today's sharpness as the tiebreaker. Ranking only, never a rejection. One extra detector pass per candidate. The v3 `telemetry` callback gains a `keyframe` event with the rank numbers (never an image). `FaceObservation` gains an optional `nose` (blaze keypoint 2). The default path and the createVerification-only bundle are unchanged in behaviour.
366
+ - bdcd56e: Internal groundwork for live MRZ scanning in the browser (not exported, not in any entry yet): TypeScript ports of the native on-device OCR read logic (CTC, the any-issuer ICAO 9303 MRZ parser with the OCR look-alike repair, MrzRead, the live MRZ stability gate, and the still-read layer: labels, printed NNI, Arabic/Latin cross-check, recto fields, recovery, profiles, side reads and device verdicts), conformance-tested against the shared Android/iOS vectors and replays. No public API or bundle change.
367
+ - 2f9e980: Step actions are now guarded per action, not per check: repeating the same action while it is in flight (a double tap on `send()`) still sends once, but a different action on the same check — `verify()` right after `send()`, `confirm()` after `submitNni()` — is no longer swallowed by the pending one. It runs as soon as the previous submission settles, including when you call it from inside the `on("step")` handler.
368
+
369
+ ## 0.1.0-rc.7
370
+
371
+ ### Minor Changes
372
+
373
+ - fa95c41: Bundled liveness + face_match submission (one round trip off the face step).
374
+
375
+ - `createVerification` now uploads the liveness clip and the selfie keyframe **in parallel** and submits `liveness` with `input.faceMatch: { imageKey }` (`LivenessInput.faceMatch`). A Sekyro backend with the bundle enabled runs face_match in the same submission; otherwise the SDK submits `face_match` itself with the **already-uploaded** keyframe (no second upload). A keyframe upload failure falls back to today's sequential path. The parallel keyframe upload (and `faceMatch`) only happens when `face_match` is the next executable step after `liveness`: liveness-only templates and skipped / absent face_match never upload a face image, and nothing is uploaded after `destroy()`.
376
+ - Idempotency: a same-key transport replay sends a byte-identical body (same clip key, same keyframe key).
377
+ - Capture states: the chained face_match no longer shows a second `uploading` phase when the key is reused.
378
+ - 06ea302: Org and app branding from the Sekyro AI dashboard.
379
+
380
+ - `@sekyro/web`: `HostedSessionView.branding` (`HostedBranding`: `logoUrl`, `colors`, `radius`, `fontFamily`, all optional) carries only the branding set in the dashboard, merged per field (app over org). Fields nobody set are absent (keep your defaults for them), and `branding` itself is absent when nothing is set or on older APIs.
381
+ - `@sekyro/react`: `brandingToTheme(view.branding)` maps it onto a `SekyroTheme`, and `mergeThemes(...)` combines themes left to right. Pass your own theme last so it still wins: `mergeThemes(brandingToTheme(view.branding), myTheme)`. Integrations that ignore it keep the default theme.
382
+
383
+ ### Patch Changes
384
+
385
+ - 4e7a4a3: Brand: the product is now **Sekyro AI** — package descriptions, READMEs, LICENSE text and the `@sekyro/node` configuration error messages say "Sekyro AI". No API change: package names, the `Sekyro` class, exports and header names are unchanged.
386
+ - d321707: Wait for a fresh capture when bundled face matching requires new input, and reflect its consumed attempt in view and retry events. Keep sequential fallback when the backend leaves matching pending, without double-counting same-key transport replays.
387
+ - c3699fd: Send the time zone and a device context header on hosted API calls (profile v2 §9–§10). No permission prompt; raw ids are hashed per org server-side.
388
+ - c3699fd: Add the `document_nni_mismatch` doc_ocr reason (document NNI differs from the session's bound NNI).
389
+ - 1b6bef2: Profile v2 policy reasons, round 2. New eligibility reason `age_unverifiable` (the app sets a minimum age but the birth date could not be read — `doc_ocr`: retryable with a clearer photo; `population_registry`: final). `failureReason` is widened to every policy reason a session can end on: the session-level reasons plus `nationality_not_allowed`, `underage`, `document_type_not_accepted`, `document_nni_mismatch` and `age_unverifiable`. `@sekyro/web`: `PolicyFailureReason` widened, `age_unverifiable` in `DocReason` / `PopulationReason` / `RETRYABLE_REASONS`. `@sekyro/react`: ar/fr/en copy for `age_unverifiable`. `@sekyro/node`: `EligibilityReason` gains `age_unverifiable`; new `PolicyFailureReason` type used by `Session.failureReason` and the `session.failed` webhook data.
390
+ - 1b6bef2: Profile v2 policy reasons. `@sekyro/web`: the eligibility check reasons `document_type_not_accepted` (retryable), `nationality_not_allowed` and `underage`; `SessionFailureReason` (`location_not_allowed`, `anonymizer_blocked`); `HostedSessionView.failureReason` and `acceptedDocumentTypes`. `@sekyro/react`: ar/fr/en copy for the five reasons. `@sekyro/node`: `SessionFailureReason`, `EligibilityReason`, and `failureReason` on `Session` and the `session.failed` webhook data.
391
+ - 13d512f: Profile v2 step 3: identity-method choice, document-NNI registry submit, matching reasons, `subject` input. `@sekyro/web`: `IdentityMethod`, `MethodChoiceView` and `HostedSessionView.methodChoice`; `HostedStepView.attemptsExhausted` / `nniFromDocument` (and `SessionStepView.attemptsExhausted`); `HostedClient.selectMethod()` (`POST /hosted/method`); error codes `method_required` / `method_locked` / `document_nni_mismatch` (409 when a typed NNI differs from the document's); matching reasons `name_mismatch`, `birth_date_mismatch`, `nationality_mismatch` (doc_ocr + population_registry) and `document_number_mismatch` (doc_ocr) as `MatchReason`. The headless runner stops on a pending choice (`unavailable` / `method_required`, `on('method')`), adds `verification.methodChoice()` / `selectMethod()`, and submits the registry with an empty input when the document gave the NNI. `@sekyro/react`: ar/fr/en copy for the four reasons and the method screen; `<LivenessCapture>` handles the method step while the session waits on the choice: it offers only the methods it can run (the national number — it has no document capture) and selects it without a screen when it is the only one left. `@sekyro/node`: `CreateSessionInput.subject` (`SessionSubjectInput`), `CreateSessionInput.identityMethod` and `sessions.selectMethod(id, method)` (`POST /sessions/:id/method`, `IdentityMethod`) so partners can choose the identity method of an optional-document session, `subjectId` / `externalRef` / `subjectConflict` on `Session` and session webhooks, `SessionStep.attemptsExhausted`, `MatchReason`, and the `subject.updated` webhook data (`{ subjectId, sessionId, status, outcome }`).
392
+ - acbf409: Profile v2 step 4: decision mode, desktop handoff, device stops, per-session profile overrides. `@sekyro/web`: decision-mode reasons `liveness_inconclusive`, `mobile_required`, `match_inconclusive`, `document_authenticity` (`DecisionReason`; the inconclusive three are retryable) and the registered `uncalibrated_capture_channel`; session failure reasons `capture_tampered`, `device_velocity_exceeded`, `device_cooldown`; `HostedStepView.requiresMobile` and `HostedSessionView.retryAfter`; the error code `inference_unavailable` (503, request-level, with `retryAfterSeconds` from `Retry-After` or the body). The headless runner retries `inference_unavailable` up to 3 times after `retryAfterSeconds` (default 10 s) under a fresh idempotency key and a fresh attestation, emitting `on('busy')` for each retry, then surfaces `unavailable / inference_unavailable`; it never captures a `requiresMobile` liveness step on desktop (`unavailable / mobile_required`, nothing uploaded) and adds `verification.mobileRequired()`; a `device_cooldown` result carries `retryAfter`. `@sekyro/react`: ar/fr/en coaching for the inconclusive reasons, "Continue on your phone" instead of the camera when liveness needs a phone, a "busy, trying again" notice, the device stop copy (the cooldown says when to try again — `retryAfterTime()`), no retry button for stops or `mobile_required`; bundle budget 23 → 24 KiB. `@sekyro/node`: `CreateSessionInput.profile` (`EkycProfileOverride`, a deep-partial of `EkycProfileSettings`; unknown keys are rejected server-side, widening answers `403 override_widens_profile` unless the app allows it), `Session.overriddenFields` / `riskSignals` / `retryAfter` (`overriddenFields` and `riskSignals` also on the session lifecycle webhooks), `DecisionReason`, the three device stops in `SessionFailureReason`, and the `subject.suspicious_activity` webhook data (`{ subjectId, sessionId, count }`).
393
+ - b230694: Preserve session policy failure reasons in verification results, including location and anonymizer blocks before capture or during submission. The public result reason type now includes session policy codes, so partner integrations and the React component can display the existing policy explanations.
394
+ - 58e220c: Published bundles are now minified and no longer include source maps. The public API and types are unchanged.
395
+
396
+ ## 0.1.0-rc.6
397
+
398
+ ### Minor Changes
399
+
400
+ - 54b153c: `HostedSessionView.voice` + `Verification.voiceClips()` — Sekyro-hosted voice clips of the session (used by `@sekyro/react` verification mode).
401
+
402
+ - **`HostedVoiceView` / `HostedVoiceLocale`** (new types): `{ setId, clips: { ar?, fr?, en? } }`, each locale mapping a voice key (`fcv3.*`) to an absolute clip URL on the Sekyro assets host (`assets.sekyro.ai`). A page with a Content-Security-Policy must allow that origin in `media-src`.
403
+ - **`HostedSessionView.voice?: HostedVoiceView | null`** — `null` when no clip set is active; absent on older APIs.
404
+ - **`verification.voiceClips()`** resolves the session's clips (fetching the hosted view if needed), or `null`. It never rejects: a failed bootstrap or a destroyed verification resolves `null`.
405
+
406
+ ## 0.1.0-rc.5
407
+
408
+ ### Minor Changes
409
+
410
+ - a14ac15: Pre-capture building blocks: choose the camera at start, warm the face detector ahead of time, and read the camera state for a "get ready" screen.
411
+
412
+ - **Camera at start.** `handle.start({ facing: "user" | "environment" })` (new `LivenessStartOptions`, `CameraFacing` types) picks the camera for this attempt; `retry()` keeps it and `switchCamera()` still flips it. `start()` with no options behaves as before, and `LivenessCaptureOptions.facing` remains the default. `verification.liveness()` handles pass the option through.
413
+ - **Detector preload.** `preloadLivenessAssets({ assetBaseUrl?, idle?, respectSaveData? })` downloads and initialises the face detector so the capture starts instantly instead of racing the cold-start deadline. It is idempotent per `assetBaseUrl`, never rejects, and resolves the settled status (`LivenessAssetsStatus`): `'ready'`; `'failed'` (call it again to retry); or `'idle'`, meaning nothing was preloaded (server-side rendering, no camera API, or Data-Saver with `respectSaveData: true`) — start normally. `idle: true` defers the load to browser idle time; a capture that needs the detector meanwhile starts it at once. The preload warms the blaze (MediaPipe) tier only, with a generous 120 s init deadline; captures without a preload keep the existing detector ladder and deadline, unchanged.
414
+ - **Used automatically.** Every `createLivenessCapture` / `verification.liveness()` capture with the same `assetBaseUrl` reuses the preloaded detector — no extra wiring — and destroying or retrying a capture never frees it. The preload is shared across duplicate copies of `@sekyro/web` on the page.
415
+ - **Status store.** `getLivenessAssetsStatus(assetBaseUrl?)` and `subscribeLivenessAssets(listener, assetBaseUrl?)` (the `useSyncExternalStore` contract: no emit on subscribe) drive a Start button's loading / retry state.
416
+ - **Release.** `releaseLivenessAssets(assetBaseUrl?)` frees the warmed detector (or cancels a pending idle load) when the user leaves the flow. Never call it while a capture is mounted.
417
+ - **Camera probes.** `queryCameraPermission()` and `subscribeCameraPermission(listener)` report `CameraPermissionState` (`'granted' | 'prompt' | 'denied' | 'unknown'`; the subscription emits the current state first, then every change). `hasMultipleCameras()` tells whether a front/back choice makes sense (phones and tablets always; desktops with two or more cameras). All are safe to call during server-side rendering and never throw.
418
+ - 66522c3: The liveness capture now keeps the screen awake while the camera is live.
419
+
420
+ - **Screen Wake Lock.** From `starting` through `gating` and `recording`, the capture holds a Screen Wake Lock so the phone does not dim or lock while the person positions their face. It is released on `captured`, `error` and `destroy()`, taken again on `retry()`, and re-taken automatically when the person returns to the page (browsers drop the lock when a page is hidden).
421
+ - **On by default, best-effort.** Browsers without the Screen Wake Lock API, or a refused request (page not visible, insecure context, blocked by Permissions-Policy), leave the capture exactly as before — nothing throws and no `error` is emitted.
422
+ - **Opt out:** `keepScreenAwake: false` on `createLivenessCapture({ … })` / `verification.liveness({ … })` never requests the lock.
423
+ - **Iframes:** if you embed the capture in an iframe, allow the permission alongside the camera — `<iframe allow="camera; screen-wake-lock">` — and do not send `Permissions-Policy: screen-wake-lock=()`. Without it the capture still works; the screen may just dim.
424
+ - `@sekyro/react`'s `<LivenessCapture>` gets this automatically once it runs on this `@sekyro/web` version.
425
+
426
+ ## 0.1.0-rc.4
427
+
428
+ ### Minor Changes
429
+
430
+ - 9991ea5: Face-capture timing on `captured` and on the liveness submission (session insights).
431
+
432
+ - `CapturedArtifacts` gains `engine` (`'v3'`) and three optional whole-millisecond durations measured by the capture engine with `performance.now()`: `cameraReadyMs` (camera request → preview live), `faceAcquireMs` (camera ready → first accepted face) and `captureMs` (first accepted face → gate progress 100 %, i.e. capture complete, before the clip window and any upload; a face lost and re-acquired keeps the first start). The core `CaptureArtifacts` carries the same marks as `timing`.
433
+ - `createVerification` forwards them, together with the already-known `width` / `height` / `clipMs` and the engine id, as `input.capture` on the `liveness` submission (`LivenessInput.capture`, `LivenessCaptureInput`) so the Sekyro dashboard can show how long the face capture, the upload and the processing of each check took. Nothing else changes on the wire; `face_match` is untouched.
434
+ - `@sekyro/react`: `<LivenessCapture onCaptured>` receives the new fields unchanged (no code change — the dependency bump only).
435
+
3
436
  ## 0.1.0-rc.3
4
437
 
5
438
  ### Patch Changes