@sekyro/web 0.0.0-stage → 0.1.0-rc.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/CHANGELOG.md +220 -0
  2. package/LICENSE +29 -0
  3. package/README.md +136 -2
  4. package/THIRD-PARTY-NOTICES.txt +154 -0
  5. package/dist/background-monitor-A7FKJOAG.js +1 -0
  6. package/dist/capture-constraints-B5omafmk.d.cts +44 -0
  7. package/dist/capture-constraints-B5omafmk.d.ts +44 -0
  8. package/dist/capture-session-doc-GK6G7JOI.js +1 -0
  9. package/dist/capture-session-v3-CmJw_bK0.d.cts +585 -0
  10. package/dist/capture-session-v3-DGG2stO6.d.ts +585 -0
  11. package/dist/chunk-3MSUJYBO.js +1 -0
  12. package/dist/chunk-7ZCZY3ZP.js +1 -0
  13. package/dist/chunk-A3FUGHAH.js +2 -0
  14. package/dist/chunk-BAGSM67V.js +1 -0
  15. package/dist/chunk-BPE5NSQ2.js +1 -0
  16. package/dist/chunk-CJHMFPL6.js +1 -0
  17. package/dist/chunk-DFTCAWMP.js +1 -0
  18. package/dist/chunk-DK5YPBDQ.js +1 -0
  19. package/dist/chunk-ETY6SAAZ.js +1 -0
  20. package/dist/chunk-FFDB6LQN.js +1 -0
  21. package/dist/chunk-FHJ7HO3M.js +1 -0
  22. package/dist/chunk-FPXL63KZ.js +1 -0
  23. package/dist/chunk-FUHDOEBP.js +1 -0
  24. package/dist/chunk-G6LKLN4U.js +1 -0
  25. package/dist/chunk-GI3UFGRQ.js +1 -0
  26. package/dist/chunk-HAO6EQTH.js +1 -0
  27. package/dist/chunk-HWAXEQD5.js +1 -0
  28. package/dist/chunk-MXWLCDFX.js +1 -0
  29. package/dist/chunk-O5WKNZ2C.js +1 -0
  30. package/dist/chunk-OKWG3PVH.js +1 -0
  31. package/dist/chunk-POIQGEZM.js +1 -0
  32. package/dist/chunk-RI3E7GBN.js +1 -0
  33. package/dist/chunk-SEC64KZ3.js +1 -0
  34. package/dist/chunk-SMKCBUJL.js +1 -0
  35. package/dist/chunk-SXZCL5NO.js +1 -0
  36. package/dist/chunk-SZ7YGNUZ.js +1 -0
  37. package/dist/chunk-TDLIXFDT.js +1 -0
  38. package/dist/chunk-UGMHAFEY.js +1 -0
  39. package/dist/chunk-WKJJEPWA.js +1 -0
  40. package/dist/chunk-XR64UFLK.js +1 -0
  41. package/dist/client/index.cjs +1 -0
  42. package/dist/client/index.d.cts +71 -0
  43. package/dist/client/index.d.ts +71 -0
  44. package/dist/client/index.js +1 -0
  45. package/dist/core/index.cjs +1 -0
  46. package/dist/core/index.d.cts +87 -0
  47. package/dist/core/index.d.ts +87 -0
  48. package/dist/core/index.js +1 -0
  49. package/dist/core/ocr/worker.bundle.js +42 -0
  50. package/dist/core/ocr/worker.cjs +42 -0
  51. package/dist/core/ocr/worker.d.cts +84 -0
  52. package/dist/core/ocr/worker.d.ts +84 -0
  53. package/dist/core/ocr/worker.js +41 -0
  54. package/dist/core/v3/detect-worker.cjs +1 -0
  55. package/dist/core/v3/detect-worker.d.cts +1 -0
  56. package/dist/core/v3/detect-worker.d.ts +1 -0
  57. package/dist/core/v3/detect-worker.js +1 -0
  58. package/dist/create-document-capture-IGUQP2NS.js +1 -0
  59. package/dist/create-portrait-capture-RJSFY37D.js +1 -0
  60. package/dist/create-verification-Bb20j6zk.d.ts +2968 -0
  61. package/dist/create-verification-CtqF4A9W.d.cts +2968 -0
  62. package/dist/detect-worker-DclNxkZT.d.cts +111 -0
  63. package/dist/detect-worker-DclNxkZT.d.ts +111 -0
  64. package/dist/detector-scanic-YCDNLCGV.js +1 -0
  65. package/dist/icao-gate-PWBMKRGC.js +1 -0
  66. package/dist/icao-gate-terzKYD7.d.cts +1770 -0
  67. package/dist/icao-gate-terzKYD7.d.ts +1770 -0
  68. package/dist/icao-tuning-4GGVX6B4.js +1 -0
  69. package/dist/index.cjs +1 -0
  70. package/dist/index.d.cts +74 -0
  71. package/dist/index.d.ts +74 -0
  72. package/dist/index.js +1 -0
  73. package/dist/internal/index.cjs +1 -0
  74. package/dist/internal/index.d.cts +462 -0
  75. package/dist/internal/index.d.ts +462 -0
  76. package/dist/internal/index.js +1 -0
  77. package/dist/keyframe-rank-YAJLYJYF.js +1 -0
  78. package/dist/landmarker-KB7LVXAU.js +1 -0
  79. package/dist/mrz-band-VYHOTDHY.js +1 -0
  80. package/dist/plan-runner-QCK2SOGS.js +1 -0
  81. package/dist/popup/index.cjs +1 -0
  82. package/dist/popup/index.d.cts +66 -0
  83. package/dist/popup/index.d.ts +66 -0
  84. package/dist/popup/index.js +1 -0
  85. package/dist/scanic-ml-stub-KW7IZHUT.js +1 -0
  86. package/dist/segmenter-USLNBX65.js +1 -0
  87. package/dist/turnstile-FATNZ4AG.js +1 -0
  88. package/package.json +133 -4
  89. package/sbom.cdx.json +195 -0
@@ -0,0 +1,585 @@
1
+ import { F as FaceObservation, b as Detector, W as WorkerLike } from './detect-worker-DclNxkZT.cjs';
2
+
3
+ /** MP4-first ladder: one container (H.264 MP4) covers iOS/macOS Safari + Chrome 130+.
4
+ * WebM/VP9→VP8 only as the Firefox/older-Chromium fallback. */
5
+ declare const MIME_CANDIDATES: readonly ["video/mp4;codecs=avc1.42E01E,mp4a.40.2", "video/mp4;codecs=avc1.42E01E", "video/mp4", "video/webm;codecs=vp9,opus", "video/webm;codecs=vp9", "video/webm;codecs=vp8,opus", "video/webm;codecs=vp8", "video/webm"];
6
+ type CameraErrorKind = "permission" | "notfound" | "inuse" | "overconstrained" | "insecure" | "unsupported" | "generic";
7
+ /** First supported candidate, or "" to let the browser pick its own default. */
8
+ declare function pickMimeType(): string;
9
+ /** Default clip container when pickMimeType() === "" — NEVER .bin/octet-stream (REVIEW FIX 5).
10
+ * Prefer the first webm in the ladder the browser most likely defaults to. */
11
+ declare const DEFAULT_CLIP_MIME = "video/webm";
12
+ /** Branch on err.name (never the message). TypeError ⇒ navigator.mediaDevices was undefined
13
+ * (insecure/unsupported context) — surfaced as "insecure". */
14
+ declare function mapGetUserMediaError(err: unknown): CameraErrorKind;
15
+ declare function cameraPreflight(): "INSECURE_CONTEXT" | "UNSUPPORTED" | "OK";
16
+ /** iOS Safari (and any browser) may lack MediaRecorder entirely — detect BEFORE prompting
17
+ * for the camera so we can fall back to the v1 single-photo path (REVIEW FIX 1). */
18
+ declare function isMediaRecorderSupported(): boolean;
19
+ declare const MAX_CLIP_BYTES: number;
20
+ declare function isClipTooLarge(blob: Blob): boolean;
21
+ declare function extForMime(mime: string): string;
22
+ /** Build the exact multipart body /api/liveness/v2 expects: fields `token`, files `clip` + `keyframe`.
23
+ * Caller must NOT set Content-Type — the browser adds the boundary. */
24
+ declare function buildLivenessV2FormData(args: {
25
+ token: string;
26
+ clip: Blob;
27
+ keyframe: Blob;
28
+ ts?: number;
29
+ }): FormData;
30
+
31
+ declare const CLIP_MS = 2500;
32
+ declare const TIMESLICE_MS = 1000;
33
+ declare const STOP_GRACE_MS = 1500;
34
+ declare const VIDEO_BPS = 2500000;
35
+ type ClipErrorKind = CameraErrorKind | "cliptoolarge";
36
+ declare class ClipError extends Error {
37
+ kind: ClipErrorKind;
38
+ constructor(kind: ClipErrorKind, msg?: string);
39
+ }
40
+ interface ClipResult {
41
+ blob: Blob;
42
+ /** Container mime the clip was finalized with (recorder.mimeType || picked || DEFAULT_CLIP_MIME). */
43
+ mimeType: string;
44
+ }
45
+ declare class ClipRecorder {
46
+ private recorder;
47
+ private stream;
48
+ private chunks;
49
+ private bytes;
50
+ private hardStopTimer;
51
+ private graceTimer;
52
+ private settled;
53
+ private clearTimers;
54
+ /** Records CLIP_MS of the stream. Resolves with the clip blob + its container mime;
55
+ * rejects with ClipError. Behavior contract is the v1 hook's `start`, verbatim
56
+ * (iOS workarounds included).
57
+ *
58
+ * ONE RECORDING AT A TIME: chunk/byte/timer state is shared per instance, so a
59
+ * second record() while one is in flight rejects ClipError("generic") instead of
60
+ * corrupting the in-flight clip. (v2 guard — v1's hook was gated by its owning
61
+ * component; a class API invites reuse. Zero impact on clip bytes.)
62
+ *
63
+ * `onStopped` (optional) fires ONCE the moment the CLIP_MS recording window
64
+ * elapses (the hard-stop), BEFORE finalize — which on iOS can lag up to
65
+ * STOP_GRACE_MS while onstop flushes the last chunk. It lets the host freeze
66
+ * the display on the already-captured keyframe the instant recording ends,
67
+ * instead of waiting for the blob. PURE NOTIFICATION — it does not touch
68
+ * timers, chunks, or the finalize path, so it is calibration-neutral (no
69
+ * effect on clip bytes). Never fires on a rejected capture (error /
70
+ * cliptoolarge settle before the hard-stop and clear the timer). */
71
+ record(stream: MediaStream, onStopped?: () => void): Promise<ClipResult>;
72
+ /** Idempotent teardown: stop recorder + ALL tracks (v1 `stopAndCleanup` + the unmount
73
+ * effect). Optional `stream` override mirrors v1's `stopAndCleanup(stream?)`.
74
+ *
75
+ * MID-RECORDING SEMANTICS (verbatim v1): calling stop() while a record() is in
76
+ * flight may LATER resolve the pending promise with a TRUNCATED clip (recorder.stop()
77
+ * fires onstop → finalize from whatever chunks arrived so far), or — because this
78
+ * method clears the hard-stop/grace timers — never settle it at all if onstop never
79
+ * fires (the iOS grace path has been torn down). Callers MUST NOT treat a resolution
80
+ * arriving after stop() as a full CLIP_MS clip, and must not await a record()
81
+ * promise past stop() without their own timeout. (Task 4's CaptureSession owns
82
+ * sequencing on top of this contract.) */
83
+ stop(stream?: MediaStream | null): void;
84
+ }
85
+
86
+ /** CaptureSession state machine (transition map in capture-session.ts):
87
+ * idle → preflight → acquiring → positioning → recording → captured
88
+ * (photo mode skips `recording`: positioning → captured); any → error. */
89
+ type CaptureState = "idle" | "preflight" | "acquiring" | "positioning" | "recording" | "captured" | "error";
90
+ /** Camera kinds (ported media.ts) + engine kinds:
91
+ * - 'models' detector init failed (the v3 native→blaze ladder was
92
+ * exhausted — e.g. BlazeFace wasm never initialized). Fail
93
+ * loud; there is no degraded mode (a mock capture-anyway mode
94
+ * is a liveness hole, and the face-api floor was dropped).
95
+ * - 'cliptoolarge' the 8 MB clip cap (shared with the liveness API contract)
96
+ * - 'recorder' MediaRecorder failed mid-clip. ClipRecorder's v1-verbatim kind for
97
+ * this is 'generic'; CaptureSession REMAPS it to 'recorder' so hosts
98
+ * can distinguish recorder failure from camera 'generic'. */
99
+ type CaptureErrorKind = CameraErrorKind | "models" | "cliptoolarge" | "recorder";
100
+ /** The five v1 gate checks (hysteresis-smoothed statuses). */
101
+ interface GateChecks {
102
+ faceDetected: boolean;
103
+ inCircle: boolean;
104
+ centered: boolean;
105
+ goodQuality: boolean;
106
+ stable: boolean;
107
+ }
108
+ /**
109
+ * Client-side capture timing (face-capture duration, 2026-10-17), measured
110
+ * by the engine with its monotonic clock (`performance.now()` by default) and
111
+ * rounded to whole milliseconds. All fields are optional: a phase that never
112
+ * happened (e.g. no face ever detected before a retry) is simply absent.
113
+ */
114
+ interface CaptureTiming {
115
+ /** `getUserMedia` call → stream attached and the preview playing. */
116
+ cameraReadyMs?: number;
117
+ /** Camera ready → the first tick on which the GATE accepted the face
118
+ * (present + size / centering / quality good enough to make progress —
119
+ * not merely detected). */
120
+ faceAcquireMs?: number;
121
+ /** FIRST accepted face → gate progress 100 % (capture complete, BEFORE the
122
+ * clip window / upload). A face lost and re-acquired keeps the first start. */
123
+ captureMs?: number;
124
+ }
125
+ /** Capture output. Upload is NOT the engine's job — hosts submit these themselves. */
126
+ interface CaptureArtifacts {
127
+ /** Absent in photo mode. */
128
+ clip?: Blob;
129
+ /** Container mime the clip finalized with. Absent in photo mode. */
130
+ clipMimeType?: string;
131
+ /** JPEG keyframe (captureMirroredKeyframe): mirrored on the front camera, as the sensor sees it on the back one. */
132
+ keyframe: Blob;
133
+ /** JPEG data URL of the keyframe canvas (v1 preview, quality 0.92). */
134
+ previewDataUrl: string;
135
+ /** Capture-phase timing of the attempt that produced these artifacts. */
136
+ timing?: CaptureTiming;
137
+ }
138
+ interface CaptureSessionEvents {
139
+ statechange: {
140
+ state: CaptureState;
141
+ };
142
+ checks: GateChecks & {
143
+ counters: Record<keyof GateChecks, number>;
144
+ };
145
+ /** fcv2.* message KEY (messages.ts / guidanceCopy) — hosts translate; never prose. */
146
+ guidance: {
147
+ key: string;
148
+ };
149
+ artifacts: CaptureArtifacts;
150
+ error: {
151
+ kind: CaptureErrorKind;
152
+ retryable: boolean;
153
+ };
154
+ }
155
+
156
+ interface V3GateThresholds {
157
+ /** q at/above which progress rises; below it progress falls. */
158
+ Q_GOOD: number;
159
+ /** Integrator slopes, per second. */
160
+ RISE_PER_S: number;
161
+ FALL_PER_S: number;
162
+ /** Centering falloff radius = this × IOD (scale-invariant). The plan's
163
+ * formula is 0.45 × IOD × 3 — the 0.45 echoes v1's CIRCLE_RADIUS_FACTOR
164
+ * heritage — folded here to 1.35 × IOD. */
165
+ CENTER_FALLOFF_IOD_MULTIPLE: number;
166
+ /** Box-only tiers: gate point = bbox center shifted UP by this × height
167
+ * (the documented bbox-vs-eyes offset heuristic). */
168
+ BOX_EYE_OFFSET_FACTOR: number;
169
+ /** Box-only IOD proxy = this × box width. */
170
+ IOD_BOX_PROXY_FACTOR: number;
171
+ /** IOD / frame short side: ideal band + hard limits. */
172
+ SIZE_IDEAL_MIN: number;
173
+ SIZE_IDEAL_MAX: number;
174
+ SIZE_HARD_MIN: number;
175
+ SIZE_HARD_MAX: number;
176
+ /** Eye-line roll (deg) that zeroes the pose factor. */
177
+ ROLL_MAX_DEG: number;
178
+ /** Center velocity that zeroes the motion factor, in IOD-per-second. */
179
+ MOTION_VELOCITY_IOD_PER_S: number;
180
+ /** Velocity-EMA time constant (seconds) — the EMA weight is derived per
181
+ * tick as 1−exp(−dt/τ), so the smoothing HORIZON is cadence-invariant:
182
+ * a LOW device detecting at 5 Hz gets the same effective smoothing as a
183
+ * HIGH device at 10 Hz (a fixed per-sample alpha under-smoothed exactly
184
+ * the jittery low-cadence ticks that needed it most). */
185
+ MOTION_TAU_S: number;
186
+ /** Velocities at/below this (IOD/s) count as stillness — absorbs detector
187
+ * box jitter (largest on LOW's 128px input) before it reaches the EMA. */
188
+ MOTION_DEADBAND_IOD_PER_S: number;
189
+ /** ready = p ≥ 1 AND no bad tick (q < Q_GOOD) left in this window after
190
+ * TRIMMING: with ≥3 samples the single worst is dropped, so one flaky tick
191
+ * (5 Hz LOW cadence = only 2–3 samples per window) cannot veto an
192
+ * otherwise-ready user, while a SECOND bad tick (a real sustained wobble)
193
+ * still blocks. The readiness bar is Q_GOOD itself — the level the
194
+ * integrator rises on — so any input that fills the ring also fires it. */
195
+ READY_WINDOW_MS: number;
196
+ /** Per-factor guidance trigger levels (lowest failing factor speaks). */
197
+ GUIDE_SIZE: number;
198
+ GUIDE_CENTERING: number;
199
+ GUIDE_POSE: number;
200
+ GUIDE_EXPOSURE: number;
201
+ GUIDE_SHARPNESS: number;
202
+ GUIDE_MOTION: number;
203
+ }
204
+ /** Defaults — retuned 2026-07-12 (operator ruling superseding the 2026-07
205
+ * freeze; the capture Task-15 refit set must be split at this boundary):
206
+ * Q_GOOD 0.55→0.6 so it aligns with the 0.6 guidance thresholds under
207
+ * min-q ("no complaint" ⇔ "progress rises"); SIZE_IDEAL_MIN 0.16→0.12 —
208
+ * wide-FOV front cameras (common low-end) put an arm's-length face below
209
+ * 0.16, silently forcing lean-in; the 720p clip floor keeps a 0.12-IOD
210
+ * face fully resolvable server-side. */
211
+ declare const V3_GATE_DEFAULTS: Readonly<V3GateThresholds>;
212
+ interface V3GateQuality {
213
+ /** From frame-quality.sharpness on the face crop. */
214
+ sharpness: number;
215
+ /** From frame-quality.exposure on the face crop. */
216
+ exposure: number;
217
+ /** Mean crop luma — picks more_light vs too_bright guidance. */
218
+ meanLuma: number;
219
+ }
220
+ interface V3GateTickInput {
221
+ timestampMs: number;
222
+ observation: FaceObservation | null;
223
+ quality: V3GateQuality;
224
+ frameWidth: number;
225
+ frameHeight: number;
226
+ }
227
+ type V3GateFactor = "presence" | "centering" | "size" | "pose" | "sharpness" | "exposure" | "motion";
228
+ /** Per-tick output — the telemetry + chrome contract. */
229
+ interface V3GateTick {
230
+ at: number;
231
+ /** Instantaneous quality 0..1 (MIN over the factors — the worst factor). */
232
+ q: number;
233
+ /** Integrated progress 0..1. */
234
+ p: number;
235
+ factors: Record<V3GateFactor, number>;
236
+ /** fcv3.* message key for the lowest failing factor (host translates). */
237
+ guidanceKey: string;
238
+ /** Fire signal: p ≥ 1 AND no second bad tick (q < Q_GOOD) in READY_WINDOW_MS. */
239
+ ready: boolean;
240
+ /** The face on THIS tick is ACCEPTED by the gate — present and every factor
241
+ * (size, centering, pose, sharpness, exposure, motion) good enough that the
242
+ * integrator RISES (q ≥ Q_GOOD). The engine's "first accepted face" mark. */
243
+ accepted: boolean;
244
+ }
245
+ declare class FaceGateV3 {
246
+ private readonly t;
247
+ private p;
248
+ private lastTickAt;
249
+ private lastCenter;
250
+ private velocityEma;
251
+ private qWindow;
252
+ constructor(overrides?: Partial<V3GateThresholds>);
253
+ reset(): void;
254
+ tick(input: V3GateTickInput): V3GateTick;
255
+ private geometryOf;
256
+ private motionOf;
257
+ /** Lowest failing factor speaks — fixed priority (diagnostic, incl. light):
258
+ * presence → size → centering → pose → exposure → sharpness → hold.
259
+ *
260
+ * HONESTY FALLBACK (operator ruling 2026-07-12): when every factor clears
261
+ * its guide threshold but q (= min factor) is still below Q_GOOD — i.e.
262
+ * progress is DRAINING — "hold still" would be a lie ("Perfect" while
263
+ * nothing advances; the field symptom was users discovering by accident
264
+ * that only leaning in fires the gate). In that state the WORST factor
265
+ * speaks even though it passed its guide level, so the user always hears
266
+ * the change that actually unblocks recording. */
267
+ private guidanceOf;
268
+ /** Direction from the size band set THIS tick (never inverted at the hard
269
+ * limits: past SIZE_HARD_MAX the direction is 'close' → move_back). */
270
+ private sizeGuidance;
271
+ /** Band midpoint — direction only (tracks EXPOSURE_BAND automatically). */
272
+ private exposureGuidance;
273
+ /** Which side of the ideal band the last size measurement fell on. */
274
+ private lastSizeDirection;
275
+ }
276
+
277
+ type DeviceClass = "LOW" | "MID" | "HIGH";
278
+ interface DeviceProfile {
279
+ /** Detection cadence — the scheduler's pace. */
280
+ cadenceHz: number;
281
+ /** Downscaled snapshot width handed to the detector. */
282
+ inputWidth: number;
283
+ /** Chrome hint: 'reduced' tones down ticks/breathe on LOW even without
284
+ * prefers-reduced-motion. */
285
+ animations: "full" | "reduced";
286
+ }
287
+ declare const DEVICE_PROFILES: Readonly<Record<DeviceClass, Readonly<DeviceProfile>>>;
288
+ interface DeviceProbe {
289
+ cores: number;
290
+ /** null where the UA hides it — iOS Safari NEVER exposes deviceMemory
291
+ * (field lesson: a 2GB default classified every iPhone LOW). Unknown is
292
+ * treated as NEUTRAL (4GB): never demotes to LOW on its own, never
293
+ * promotes to HIGH; the dynamic profiler corrects truly slow devices. */
294
+ memGB: number | null;
295
+ /** WebAssembly SIMD available (informs wasm-tier expectations/telemetry). */
296
+ simd: boolean;
297
+ }
298
+ declare function probeDevice(): DeviceProbe;
299
+ /** Static class: LOW (<4 cores or <3GB), HIGH (≥8 cores AND ≥6GB), else MID.
300
+ * Unknown memory counts as a neutral 4GB (see DeviceProbe.memGB). */
301
+ declare function classifyDevice(probe: DeviceProbe): DeviceClass;
302
+ /** Dynamic refinement: after the FIRST 10 measured detect ticks, a mean over
303
+ * 70ms demotes straight to LOW; under 25ms promotes ONE class — at most one
304
+ * adjustment ever (no oscillation). */
305
+ declare class DeviceProfiler {
306
+ private current;
307
+ private readonly samples;
308
+ private adjusted;
309
+ constructor(initial: DeviceClass);
310
+ get deviceClass(): DeviceClass;
311
+ get profile(): DeviceProfile;
312
+ record(detectMs: number): DeviceClass;
313
+ }
314
+
315
+ /** Why a gate tick did not advance: no face, or the weakest gate check. */
316
+ type GateBlockReason = "no_face" | Exclude<V3GateFactor, "presence">;
317
+ interface GateBlockEntry {
318
+ /** Ticks blocked by this reason. */
319
+ count: number;
320
+ /** Wall time (whole ms) those ticks covered. */
321
+ ms: number;
322
+ }
323
+ interface GateBlockSummary {
324
+ /** Only the reasons that blocked at least once. */
325
+ blocked: Partial<Record<GateBlockReason, GateBlockEntry>>;
326
+ /** Wall time (whole ms) of ticks the gate accepted (progress rising). */
327
+ acceptedMs: number;
328
+ /** Total ticks seen. */
329
+ ticks: number;
330
+ }
331
+ /** The reason one tick was held back, or null when the gate accepted it. */
332
+ declare function blockReasonOf(tick: Pick<V3GateTick, "accepted" | "factors">): GateBlockReason | null;
333
+ declare class GateBlockStats {
334
+ private blocked;
335
+ private acceptedMs;
336
+ private ticks;
337
+ private lastAt;
338
+ /** Record one gate tick; the time since the previous tick is charged to THIS tick's state. */
339
+ record(tick: Pick<V3GateTick, "at" | "accepted" | "factors">): void;
340
+ summary(): GateBlockSummary;
341
+ }
342
+
343
+ /** A non-final `gate` telemetry snapshot at most this often while positioning
344
+ * (so an abandoned attempt still reports where its time went). */
345
+ declare const GATE_SNAPSHOT_MS = 1000;
346
+ /** Guidance key while a phone shows a landscape camera frame (the upright guard). */
347
+ declare const HOLD_UPRIGHT_KEY = "fcv3.hold_upright";
348
+ /** How often the upright guard re-reads the frame size while the clip records (plus every `resize` event). */
349
+ declare const UPRIGHT_WATCH_MS = 200;
350
+ /** Best-of-N keyframe window: up to 4 candidates over the first 600ms. */
351
+ declare const KEYFRAME_CANDIDATES = 4;
352
+ declare const KEYFRAME_WINDOW_MS = 600;
353
+ interface V3ChecksPayload {
354
+ engine: "v3";
355
+ /** Gate integrator 0..1 — the ring drives off this directly. */
356
+ progress: number;
357
+ /** Instantaneous quality 0..1. */
358
+ q: number;
359
+ factors: Record<V3GateFactor, number>;
360
+ /** Attempt ordinal (bumps on retry/switchCamera). */
361
+ attempt: number;
362
+ }
363
+ interface CaptureSessionV3Events {
364
+ statechange: {
365
+ state: CaptureState;
366
+ };
367
+ checks: V3ChecksPayload;
368
+ /** fcv3.* message KEY — hosts translate; never prose. Deduped. */
369
+ guidance: {
370
+ key: string;
371
+ };
372
+ artifacts: CaptureArtifacts;
373
+ error: {
374
+ kind: CaptureErrorKind;
375
+ retryable: boolean;
376
+ };
377
+ /** v3-only, CHROME-only (no data flows here): fires the instant the clip
378
+ * recording window ends — BEFORE the blob finalizes (iOS onstop can lag up
379
+ * to STOP_GRACE_MS). Carries the already-captured keyframe's JPEG data URL so
380
+ * the host can freeze the display on the still immediately instead of leaving
381
+ * the live feed running while the clip flushes. Clip mode only (photo mode
382
+ * goes straight to `artifacts`). A host that ignores it is unaffected. */
383
+ frozen: {
384
+ previewDataUrl: string;
385
+ };
386
+ }
387
+ type V3TelemetryEvent = {
388
+ type: "detector";
389
+ tier: Detector["tier"];
390
+ fallbackReason?: string;
391
+ } | {
392
+ type: "profile";
393
+ staticClass: DeviceClass;
394
+ activeClass: DeviceClass;
395
+ simd: boolean;
396
+ } | {
397
+ type: "fired";
398
+ timeToGateMs: number;
399
+ degradeCount: number;
400
+ meanDetectMs: number;
401
+ }
402
+ /** Where the attempt's gate time went (see gate-blocking.ts): per-reason
403
+ * blocked tick counts + ms, accepted ms, and the ACTIVE device class /
404
+ * cadence after any dynamic profile adjustment. `final` on the attempt's
405
+ * end (fired / error / retry / destroy); throttled snapshots before it. */
406
+ | ({
407
+ type: "gate";
408
+ final: boolean;
409
+ activeClass: DeviceClass;
410
+ cadenceHz: number;
411
+ } & GateBlockSummary) | {
412
+ type: "error";
413
+ kind: CaptureErrorKind;
414
+ fallbackReason?: string;
415
+ }
416
+ /** Keyframe ranking (SDK spec §4.8a; only when `rankKeyframes` is on): the
417
+ * rank numbers of every candidate (never an image), the chosen index, the
418
+ * index sharpness alone would have chosen, and the extra detector time. */
419
+ | {
420
+ type: "keyframe";
421
+ tier: Detector["tier"] | null;
422
+ chosen: number;
423
+ sharpest: number;
424
+ detectMs: number;
425
+ candidates: Array<{
426
+ face: boolean;
427
+ frontal: number;
428
+ yaw?: number;
429
+ roll?: number;
430
+ eyes?: number;
431
+ score: number;
432
+ sharpness: number;
433
+ }>;
434
+ };
435
+ interface KeyframeCandidate {
436
+ blob: Blob;
437
+ previewDataUrl: string;
438
+ sharpness: number;
439
+ }
440
+ /** Challenge-clip artifact for the Phase 3 escalation path. */
441
+ interface EscalationClipArtifact {
442
+ clip: Blob;
443
+ clipMimeType: string;
444
+ }
445
+ /** INERT Phase 3 seam (docs/superpowers/specs/2026-07-07-active-liveness-
446
+ * escalation-spec.md): when the server settles a liveness verdict in the
447
+ * REVIEW band it may mint ONE gesture challenge; the host then asks the
448
+ * engine for a challenge clip through this hook. Typed and documented NOW so
449
+ * capture-v3+ starts from a design — NEVER invoked anywhere in the current
450
+ * flow (pinned by a test). */
451
+ interface EscalationHook {
452
+ onBorderline(challenge: "blink" | "turn"): Promise<EscalationClipArtifact>;
453
+ }
454
+ interface CaptureSessionV3Options {
455
+ /** Host-owned <video playsInline muted> — same iOS contract as v1. */
456
+ video: HTMLVideoElement;
457
+ /** v3 assets base (tasks-vision wasm + tflite); default /models-v3. */
458
+ v3AssetBaseUrl?: string;
459
+ mode?: "clip" | "photo";
460
+ /** FaceGateV3 threshold overrides (Phase 2 tuning). */
461
+ thresholds?: Partial<V3GateThresholds>;
462
+ telemetry?: (event: V3TelemetryEvent) => void;
463
+ facingMode?: "user" | "environment";
464
+ /** Static class override (tests / host pinning); default = boot probe. */
465
+ deviceClass?: DeviceClass;
466
+ /** (detector ladder) */
467
+ createDetector?: () => Promise<Detector>;
468
+ /** (fresh ClipRecorder per attempt) */
469
+ createRecorder?: () => Pick<ClipRecorder, "record" | "stop">;
470
+ /** (navigator.mediaDevices.getUserMedia) */
471
+ getUserMedia?: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
472
+ /** (canvas keyframe, mirrored on the front camera only, + downscaled Laplacian sharpness) */
473
+ captureKeyframe?: (video: HTMLVideoElement) => Promise<KeyframeCandidate>;
474
+ /** (downscaled face-crop sharpness/exposure via canvas) */
475
+ measureQuality?: (video: HTMLVideoElement, box: {
476
+ x: number;
477
+ y: number;
478
+ width: number;
479
+ height: number;
480
+ }) => V3GateQuality;
481
+ /** (reused canvas at profile.inputWidth; falls back to the raw video where
482
+ * canvas is unavailable) */
483
+ makeSnapshot?: (video: HTMLVideoElement, targetWidth: number) => CanvasImageSource;
484
+ /** Worker offload opt-in (Task 9): when provided AND the platform supports
485
+ * it (OffscreenCanvas + createImageBitmap + Worker), detection runs
486
+ * worker-side through WorkerDetectorProxy. Hosts own Worker construction
487
+ * (bundler-specific `new Worker(new URL(...))`). */
488
+ createWorker?: () => WorkerLike;
489
+ /** Keyframe ranking switch (SDK spec §4.8a; server tuning
490
+ * `capture.liveness.keyframe.rank`, default off): read when positioning
491
+ * starts (prefetches the lazy ranker) and again when the capture fires.
492
+ * Off → today's sharpest-of-N, byte for byte. */
493
+ rankKeyframes?: () => boolean;
494
+ /** INERT (Phase 3 escalation seam — see EscalationHook). Accepted and
495
+ * retained, never called in Phases 1–2. */
496
+ escalation?: EscalationHook;
497
+ /** Upright guard (spec 2026-10-28 §4.2): the device is a phone, so a landscape frame (videoWidth > videoHeight)
498
+ * holds the gate and drops a clip being recorded (or the keyframes of a photo-mode capture). Read at each attempt
499
+ * start. (detectFormFactor() === 'phone' — desktop webcams are landscape by nature, and a tablet may stand in
500
+ * landscape on a stand: neither is ever guarded) */
501
+ isPhone?: () => boolean;
502
+ /** (performance.now) */
503
+ now?: () => number;
504
+ }
505
+ type Handler<K extends keyof CaptureSessionV3Events> = (payload: CaptureSessionV3Events[K]) => void;
506
+ /** Per-start options (the public handle's `start({ facing })`). */
507
+ interface CaptureSessionV3StartOptions {
508
+ /** Camera for this attempt AND later retries; absent → keep the current one. */
509
+ facingMode?: "user" | "environment";
510
+ }
511
+ declare class CaptureSessionV3 {
512
+ private readonly options;
513
+ private readonly handlers;
514
+ private stateValue;
515
+ private attempt;
516
+ private facing;
517
+ private stream;
518
+ private detector;
519
+ private scheduler;
520
+ private gate;
521
+ private profiler;
522
+ private lastGuidanceKey;
523
+ private positioningStartedAt;
524
+ private cameraRequestedAt;
525
+ private cameraReadyAt;
526
+ private faceAcquiredAt;
527
+ private captureCompleteAt;
528
+ private fired;
529
+ private carriedDegrade;
530
+ private carriedMeans;
531
+ private blockStats;
532
+ private lastGateSnapshotAt;
533
+ /** The upright guard applies to this attempt (a phone). */
534
+ private uprightGuard;
535
+ constructor(options: CaptureSessionV3Options);
536
+ get state(): CaptureState;
537
+ on<K extends keyof CaptureSessionV3Events>(event: K, handler: Handler<K>): () => void;
538
+ private emit;
539
+ start(options?: CaptureSessionV3StartOptions): Promise<void>;
540
+ /** The camera of the current attempt: the one its track reports once the stream is live, else the requested one
541
+ * (start option, switchCamera toggles). */
542
+ get facingMode(): "user" | "environment";
543
+ /** Full reset + camera restart — the documented recovery path (v1 parity). */
544
+ retry(): void;
545
+ switchCamera(): void;
546
+ destroy(): void;
547
+ private run;
548
+ /** Chrome hint (Task 11): 'reduced' on LOW even without the media query. */
549
+ get animations(): "full" | "reduced";
550
+ private startScheduler;
551
+ private detectTick;
552
+ private fire;
553
+ /** A phone showing a landscape frame: the guard holds the gate. */
554
+ private isLandscape;
555
+ /** Positioning on a sideways phone: no detection, the gate restarts from zero and the coaching says why. */
556
+ private holdUpright;
557
+ /** While the clip records (or, `recorder` null, the photo-mode keyframes are taken): a rotation to landscape aborts
558
+ * it. Returns the unwatch function. */
559
+ private watchRotation;
560
+ /** Drop the clip being recorded (or the photo-mode keyframes being taken; same stream, same detector) and go back to
561
+ * positioning with the upright coaching. */
562
+ private abortRecording;
563
+ /** Up to KEYFRAME_CANDIDATES frames (mirrored on the front camera) over KEYFRAME_WINDOW_MS —
564
+ * sharpest wins (reuses frame-quality.sharpness via the capture seam). */
565
+ private collectKeyframes;
566
+ private finishCapture;
567
+ /** The attempt's capture-phase timing (whole ms, ≥ 0); undefined when no mark landed. */
568
+ private captureTiming;
569
+ private defaultKeyframe;
570
+ /** Reused downscale canvas — falls back to the raw video where canvas 2D
571
+ * is unavailable (jsdom) so tests and exotic hosts keep detecting. */
572
+ private snapshotCanvas;
573
+ private defaultSnapshot;
574
+ private defaultQuality;
575
+ private centerSharpness;
576
+ private teardownAttempt;
577
+ /** Emit the attempt's gate breakdown; a final report closes it (exactly once). */
578
+ private reportGate;
579
+ private stopTracks;
580
+ private fail;
581
+ private setState;
582
+ private now;
583
+ }
584
+
585
+ export { isMediaRecorderSupported as $, MIME_CANDIDATES as A, type V3GateFactor as B, type CameraErrorKind as C, DEFAULT_CLIP_MIME as D, type EscalationClipArtifact as E, FaceGateV3 as F, GATE_SNAPSHOT_MS as G, HOLD_UPRIGHT_KEY as H, type V3GateQuality as I, type V3GateThresholds as J, KEYFRAME_CANDIDATES as K, type V3GateTick as L, MAX_CLIP_BYTES as M, type V3GateTickInput as N, type V3TelemetryEvent as O, V3_GATE_DEFAULTS as P, VIDEO_BPS as Q, blockReasonOf as R, STOP_GRACE_MS as S, TIMESLICE_MS as T, UPRIGHT_WATCH_MS as U, type V3ChecksPayload as V, buildLivenessV2FormData as W, cameraPreflight as X, classifyDevice as Y, extForMime as Z, isClipTooLarge as _, CLIP_MS as a, mapGetUserMediaError as a0, pickMimeType as a1, probeDevice as a2, type CaptureArtifacts as b, type CaptureErrorKind as c, type CaptureSessionEvents as d, CaptureSessionV3 as e, type CaptureSessionV3Events as f, type CaptureSessionV3Options as g, type CaptureSessionV3StartOptions as h, type CaptureState as i, type CaptureTiming as j, ClipError as k, type ClipErrorKind as l, ClipRecorder as m, type ClipResult as n, DEVICE_PROFILES as o, type DeviceClass as p, type DeviceProbe as q, type DeviceProfile as r, DeviceProfiler as s, type EscalationHook as t, type GateBlockEntry as u, type GateBlockReason as v, GateBlockStats as w, type GateBlockSummary as x, type GateChecks as y, KEYFRAME_WINDOW_MS as z };