@sekyro/react 0.1.0-rc.1 → 0.1.0-rc.3

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,40 @@
1
1
  # @sekyro/react
2
2
 
3
+ ## 0.1.0-rc.3
4
+
5
+ ### Minor Changes
6
+
7
+ - 1ab07df: `<LivenessCapture>` now ships a built-in "get ready" screen and speaks the capture guidance.
8
+
9
+ - **Pre-capture screen (default intro).** Tips, a camera-permission row, a front/back camera choice (on devices with both), a voice switch, the security note and one Start control that waits for the detector preload (`preloadLivenessAssets`, started on mount): busy while the models download, ready to start, or a Retry if the download failed.
10
+ - **New props:** `notice` (a node or `{ tone, text }` above the screen, pre-capture only), `startDisabled` / `startLabel` (e.g. a cooldown; gates only the built-in Start, not the error Retry / "record again" / retake), `tips` (`false`, or built-in ids / your own `IntroTip`s; `DEFAULT_TIPS`), `defaultFacing`, `voice` (`false` or `VoiceOptions`), `onGuidance(key)` (once per displayed `fcv3.*` key change).
11
+ - **`autoStart: "when-permitted"`** starts only when the camera permission is already granted (until the permission probe answers, the screen shows its loader). **Behaviour change:** `autoStart` (both forms) now waits for the detector preload to be ready before starting; meanwhile the screen shows its loader (or the retry on failure).
12
+ - **Voice guidance, on by default.** Bundled clips (`assets/audio/v1`, served at `${assetBaseUrl ?? "/models-v3"}/audio/v1`) with a device-voice (speechSynthesis) fallback; a stage chip and the intro switch toggle it; the choice persists in `localStorage`. `VoiceOptions.clips` takes a `VoiceClipSource`: a resolver `(key, locale) => url | null` or a `{ [locale]: { [voiceKey]: url } }` map (e.g. from your backend); `createManifestResolver(manifest, baseUrl)` resolves over a clip-set manifest. CSP: `media-src 'self' blob:` is enough. On iOS audio unlocks in the Start tap; with `autoStart` it unlocks on the first activating touch (`touchend`), click or key press (not Escape) inside the component. Clips are prefetched in that same gesture, and only while voice is on.
13
+ - **Slots:** `slots.intro(start, context)` gets an `IntroContext` (preload gate + retry, permission, facing + setter, voice), and `start` opens the chosen camera. `slots.voicePrompt(hint, text, key, voice)` replaces the built-in chip and gets the `VoiceControl` (`{ supported, enabled, setEnabled, toggle }`) as a 4th argument.
14
+ - **Migration — partners who speak from `voicePrompt`:** the component now speaks the guidance itself; pass `voice={false}` or the person hears it twice. A development build warns once (`console.warn`) when `slots.voicePrompt` is set and `voice` is left undefined; pass `voice={false}` (your slot speaks) or `voice={{}}` (keep the built-in voice) to silence it.
15
+ - **Migration — hosts with their own intro + `autoStart`:** if you render your own "get ready" screen outside the component and mount it with `autoStart`, the built-in pre-capture screen now appears (with its loader) while the detector preload loads, instead of the camera starting at once. Pass `slots.intro` to keep your own look during that wait (e.g. `(start, context) => context.assets === "failed" ? <YourRetry onClick={context.retryAssets} /> : <YourLoader />`), or move your intro into `slots.intro` and drop `autoStart`.
16
+ - New exports: `LivenessNotice`, `IntroContext`, `IntroTip`, `BuiltInTipId`, `DEFAULT_TIPS`, `VoiceOptions`, `VoiceControl`, `VoiceKey`, `VOICE_KEYS`, `VoiceClipSource`, `VoiceClipMap`, `VoiceClipResolver`, `VoiceClipManifest`, `createManifestResolver`.
17
+ - The bundle is now built with whitespace/syntax minification (identifiers, function names and sourcemaps kept). `process.env.NODE_ENV` stays a live expression in the published bundle, so the dev-only warnings follow your build mode.
18
+ - Peer dependency: `@sekyro/web` `^0.1.0-rc.5` (the pre-capture building blocks).
19
+
20
+ ### Patch Changes
21
+
22
+ - Updated dependencies [a14ac15]
23
+ - Updated dependencies [66522c3]
24
+ - @sekyro/web@0.1.0-rc.5
25
+
26
+ ## 0.1.0-rc.2
27
+
28
+ ### Patch Changes
29
+
30
+ - 9991ea5: Face-capture timing on `captured` and on the liveness submission (session insights).
31
+
32
+ - `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`.
33
+ - `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.
34
+ - `@sekyro/react`: `<LivenessCapture onCaptured>` receives the new fields unchanged (no code change — the dependency bump only).
35
+ - Updated dependencies [9991ea5]
36
+ - @sekyro/web@0.1.0-rc.4
37
+
3
38
  ## 0.1.0-rc.1
4
39
 
5
40
  ### Minor Changes
package/README.md CHANGED
@@ -59,14 +59,88 @@ const verification = createVerification({ clientToken, locale: "ar" });
59
59
  | `locale` | `"ar" \| "fr" \| "en"` | Built-in dictionary. |
60
60
  | `dir?` | `"ltr" \| "rtl"` | Defaults to `rtl` for `ar`. |
61
61
  | `strings?` | `Partial<Strings>` | Per-key overrides on top of the built-ins. |
62
- | `slots?` | `{ header, footer, intro(start), stageOverlay(videoRef), voicePrompt(hint, text, key), errorPanel(err, retry) }` | `intro` replaces the built-in intro (permission rows, loaders, settings); `stageOverlay` renders inside the stage box above the ring (overlays, debug HUDs); `voicePrompt` renders in the stage's start corner (audio / TTS — `key` selects the clip); `errorPanel` replaces the camera-error notice. |
63
- | `autoStart?` | `boolean` | Start the camera instead of showing the intro — once, the first time it is `true` while idle (flip it when your own preconditions are met). |
62
+ | `slots?` | `{ header, footer, intro(start, context), stageOverlay(videoRef), voicePrompt(hint, text, key, voice), errorPanel(err, retry) }` | `intro` replaces the built-in pre-capture screen (see below); `stageOverlay` renders inside the stage box above the ring (overlays, debug HUDs); `voicePrompt` replaces the built-in voice chip in the stage's start corner; `errorPanel` replaces the camera-error notice. |
63
+ | `autoStart?` | `boolean \| "when-permitted"` | Skip the pre-capture screen and start once the detector preload is ready — at most once per mount. `true` arms it (flip it when your own preconditions are met); `"when-permitted"` arms it only when the camera permission is already `granted` (until the permission probe answers, the screen shows its loader). |
64
+ | `notice?` | `ReactNode \| { tone, text }` | Host message above the pre-capture screen (busy service, previous failure). Pre-capture only. |
65
+ | `startDisabled?` / `startLabel?` | `boolean` / `ReactNode` | Disable the built-in Start and relabel it (e.g. a cooldown: "Retry in 12 s"). It gates only the pre-capture Start — not the error Retry, "record again" or the retake button. |
66
+ | `tips?` | `false \| (BuiltInTipId \| IntroTip)[]` | Tips card; default `DEFAULT_TIPS`; `false` hides it. |
67
+ | `defaultFacing?` | `"user" \| "environment"` | Camera the attempt opens with (default front). |
68
+ | `voice?` | `false \| VoiceOptions` | Voice guidance; on by default. `false` = no speech, no switch, no chip. |
69
+ | `onGuidance?` | `(key) => void` | Telemetry: once per change of the displayed `fcv3.*` guidance key. |
64
70
  | `onStateChange?` | `(state) => void` | Every capture-state transition, for host chrome (hide a description while the stage is live, telemetry). |
65
71
  | `onCaptured?` | `(artifacts) => void` | Fires before any upload. |
66
72
  | `onResult?` | `(result) => void` | Verification mode only. |
67
73
  | `onError?` | `(error) => void` | Camera / engine failure (`permission \| notfound \| inuse \| insecure \| unsupported \| generic`). |
68
74
  | `assetBaseUrl?` | `string` | Detector assets base (default `/models-v3`). |
69
75
 
76
+ ### Pre-capture screen
77
+
78
+ While the capture is idle the component renders a built-in "get ready" screen:
79
+ a tips card, the camera-permission row (`granted` / `prompt` / `denied` with the
80
+ fix / `unknown`), a front/back choice on devices with both cameras, the voice
81
+ switch, the security note and **one** Start control gated on the detector preload
82
+ (`preloadLivenessAssets` from `@sekyro/web`, kicked on mount): a busy Start while
83
+ the models download, Start when ready, a danger notice + Retry if the download
84
+ failed. Without a camera API (SSR, old browsers) the preload is skipped and Start
85
+ is ready at once.
86
+
87
+ `slots.intro(start, context)` replaces the whole screen. `context` is
88
+ `{ assets: "loading" | "ready" | "failed", retryAssets, permission, facing,
89
+ setFacing, canChooseFacing, voice }`; call `start` from your click handler — it
90
+ opens `context.facing` and unlocks audio inside the gesture (iOS). The `notice`
91
+ still renders above your intro.
92
+
93
+ ```tsx
94
+ <LivenessCapture
95
+ verification={verification}
96
+ locale="fr"
97
+ notice={busy ? { tone: "warning", text: t("serviceBusy") } : undefined}
98
+ startDisabled={cooldown > 0}
99
+ startLabel={cooldown > 0 ? t("retryIn", { s: cooldown }) : undefined}
100
+ tips={["light", "uncover", { id: "id-card", text: t("haveIdReady") }]}
101
+ />
102
+ ```
103
+
104
+ ### Voice guidance
105
+
106
+ During capture the component speaks the displayed (debounced) guidance — the
107
+ `fcv3.*` gate hints — through one `<audio>` element, falling back to the
108
+ device voice (`speechSynthesis`). A stage chip (`aria-pressed`) and the intro
109
+ switch toggle it; the viewer's choice persists in `localStorage`.
110
+
111
+ | `VoiceOptions` | Default | Notes |
112
+ |---|---|---|
113
+ | `defaultEnabled?` | `true` | Used when the viewer has no stored preference. |
114
+ | `clips?` | bundled set | `VoiceClipSource`: a resolver `(key, locale) => url \| null` **or** a map `{ [locale]: { [voiceKey]: url } }` (e.g. delivered by your backend — pass a new object to change it). A missing URL or a throwing resolver = no clip → device voice. `createManifestResolver(manifest, baseUrl)` resolves over a `manifest.json` of the bundled shape. |
115
+ | `clipBaseUrl?` | `${assetBaseUrl ?? "/models-v3"}/audio/v1` | Where the bundled clip set is served. |
116
+ | `speechFallback?` | `true` | `false`, or the locales where the device voice may speak. A device with no voice for the language stays silent rather than read Arabic in a French voice. |
117
+ | `storageKey?` | `"sekyro.voiceGuidance"` | `null` = do not persist. |
118
+
119
+ **Clip layout.** The package ships its set under `@sekyro/react/assets/audio/v1/`
120
+ (`manifest.json`, `ar/<name>.mp3`, `fr/<name>.mp3`, `<name>` = the key's last
121
+ segment, e.g. `center_face`). Copy the directory next to your vendored models
122
+ (`<assetBaseUrl>/audio/v1`) or host it elsewhere and pass `clipBaseUrl` / `clips`.
123
+ `VOICE_KEYS` lists the nine keys. English always uses the device voice.
124
+
125
+ **iOS.** Audio unlocks inside a user gesture: the Start tap, or the voice
126
+ switch/chip turned on. With `autoStart` there is no Start tap, so audio stays
127
+ locked until the person's first activating touch, click or key press anywhere
128
+ inside the component (`touchend` / `click` / `keydown` other than Escape, or a
129
+ mouse/pen `pointerup`; a touch `pointerdown` is not a user activation on WebKit).
130
+ It unlocks once; an event without activation leaves the listener armed. The
131
+ clips are prefetched in that same gesture, and only while voice is on. Guidance
132
+ due before the unlock stays silent on iOS.
133
+
134
+ **`voicePrompt` slot.** It replaces the chip and receives the shared
135
+ `VoiceControl` (`{ supported, enabled, setEnabled, toggle }`) as its fourth
136
+ argument; the component keeps speaking. If your slot plays audio itself, pass
137
+ `voice={false}` or the person hears it twice. A development build warns once
138
+ when `slots.voicePrompt` is set and `voice` is undefined (pass `voice={{}}` to keep
139
+ the built-in voice and silence it).
140
+
141
+ **CSP.** Clips and the unlock use `media-src 'self' blob:` (the silent unlock WAV
142
+ is a `blob:` URL — no `data:` needed); add your clip host if `clips` points off-origin.
143
+
70
144
  ### Theme
71
145
 
72
146
  `SekyroThemeProvider` writes CSS variables on a `.sekyro-root` wrapper:
@@ -0,0 +1,60 @@
1
+ # Voice-guidance clips — set `v1`
2
+
3
+ Pre-recorded neural-voice MP3s that `@sekyro/react` plays for the gate guidance
4
+ (`fcv3.*` hints) during a liveness capture. A key without a clip falls back to
5
+ the browser's speechSynthesis (when the voice options allow it for the locale).
6
+
7
+ ## Layout
8
+
9
+ ```
10
+ assets/audio/v1/
11
+ manifest.json { "set": "v1", "clips": { "<loc>": { "<name>": { "sha256", "text", "bytes" } } } }
12
+ ar/<name>.mp3 <name> = last segment of the fcv3.* key, e.g. center_face.mp3
13
+ fr/<name>.mp3
14
+ ```
15
+
16
+ The 9 keys: `no_face`, `come_closer`, `move_back`, `center_face`, `straighten`,
17
+ `more_light`, `too_bright`, `hold_still`, `steady_camera`. English never ships
18
+ clips (it always uses speechSynthesis).
19
+
20
+ `src/voice/clip-manifest.ts` is generated alongside: the same manifest shape,
21
+ trimmed to the clip names (`BUNDLED_CLIP_MANIFEST`). The default clip source is
22
+ `createManifestResolver(BUNDLED_CLIP_MANIFEST, clipBaseUrl)`, so a key without a
23
+ shipped clip goes straight to the fallback with no 404 round-trip. An empty
24
+ manifest (`"clips": { "ar": {}, "fr": {} }`) means the package ships TTS-only.
25
+
26
+ Clips hosted elsewhere (CDN / object storage) plug in through `voice.clips` —
27
+ either a `(key, locale) → url | null` resolver or a `{ [locale]: { [voiceKey]: url } }`
28
+ map (e.g. delivered by the backend), or `createManifestResolver(manifest, baseUrl)`
29
+ over a manifest of this shape served next to the clips.
30
+
31
+ Hosts serve this directory at `<clipBaseUrl>` — by default
32
+ `${assetBaseUrl ?? "/models-v3"}/audio/v1` — next to the vendored models.
33
+
34
+ ## Voice
35
+
36
+ - Provider: Azure Speech neural TTS (REST), output `audio-24khz-48kbitrate-mono-mp3`
37
+ - Arabic: `ar-SA-ZariyahNeural` (MSA) · French: `fr-FR-DeniseNeural`
38
+ - SSML `<prosody rate="-5%">`
39
+ - Spoken text: verbatim from `src/strings/{ar,fr}.ts`
40
+
41
+ ## Regenerating
42
+
43
+ The credential lives only in your shell env — never in a file, commit or log.
44
+
45
+ ```sh
46
+ cd packages/sekyro-react
47
+ export AZURE_SPEECH_KEY=… # from the vault
48
+ export AZURE_SPEECH_REGION=westeurope
49
+ npm run voice:generate -- --dry-run # print the plan (no network)
50
+ npm run voice:generate # write the MP3s + both manifests
51
+ ```
52
+
53
+ Swapping providers means replacing the single `synthesize(text, locale)`
54
+ function in `scripts/generate-voice-clips.mts`.
55
+
56
+ ## Cache-busting rule
57
+
58
+ Clips are served with immutable caching. **A new voice or any new text means a
59
+ new set directory** (`assets/audio/v2/`) and a bump of the `SET` constant in the
60
+ generator (it becomes `BUNDLED_CLIP_MANIFEST.set`). Never overwrite the MP3s of a published set.
@@ -0,0 +1,7 @@
1
+ {
2
+ "set": "v1",
3
+ "clips": {
4
+ "ar": {},
5
+ "fr": {}
6
+ }
7
+ }