@incodetech/prizma-core-screens 0.2.4 → 0.2.12

package/dist/VideoSelfieSelfieCaptureScreen.d.ts

@@ -1,52 +1,69 @@
 import React, { type ReactNode } from 'react';
-import { type PrizmaCaptureScreenProps } from './CaptureScreen';
+import { type PrizmaScreenShellProps } from './ScreenShell';
 import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
-import type { VideoSelfieFeedbackKind, VideoSelfieStrings } from './VideoSelfieStrings';
+import type { VideoSelfieDocumentType, VideoSelfieFeedbackKind, VideoSelfieStrings } from './VideoSelfieStrings';
 import './ScreenLayout.css';
+import './ViewfinderScreen.css';
+import './VideoSelfieLayout.css';
 /** Which purple liveness section to render (group 8). */
 export type VideoSelfieSelfieState = 'start' | 'processing' | 'success' | 'failed';
-export interface VideoSelfieSelfieCaptureScreenProps extends Omit<PrizmaCaptureScreenProps, 'state' | 'feedbackText' | 'statusLabels' | 'verifiedLabel' | 'navLabel'> {
+export interface VideoSelfieSelfieCaptureScreenProps extends Omit<PrizmaScreenShellProps, 'dark' | 'title' | 'children'> {
     /** Module copy — this screen reads the `selfieCapture` slice. */
     strings: VideoSelfieStrings;
     /** Which purple section of group 8 to render. Default `start`. */
     state?: VideoSelfieSelfieState;
     /**
-     * Which of group 9's ELEVEN live-feedback lines to show under the ring.
-     * Only meaningful while the ring is live (`state="start"`): the sections of
+     * Which of group 9's live-feedback lines to show under the ring. Only
+     * meaningful while the ring is live (`state="start"`): the sections of
      * group 9 are that same frame with a different instruction. Omit for `8.0`,
      * which shows the plain "Look at your front camera" line.
      */
     feedback?: VideoSelfieFeedbackKind;
-    /** Live camera feed (<video>) or sample still (<img>). */
+    /** Which document the journey collects — the Stepper's own `documentType`. */
+    documentType?: VideoSelfieDocumentType;
+    /** Live camera feed (<video>) or sample still (<img>), full-bleed behind the
+     *  ring — NOT inside it. The overlay recipe makes the ring a window. */
     camera?: ReactNode;
     screenId?: string;
     overrides?: PrizmaScreenOverrides;
     onAction?: PrizmaScreenActionHandler;
 }
 /**
- * Video Selfie — the liveness ring (Archetype B, GUIDELINES.md §6-B).
- * ONE screen for FIFTEEN purple sections: `selfie capture 8.0–8.3` and every
- * `selfie capture feedback 9.1–9.11` message. They are `state` × `feedbackText`
- * variants of Core's `PrizmaSelfieCapture`, which owns the ring, the
- * silhouette, the ring offset (40), the instruction gap (32), the instruction
- * typography and every verdict treatment. None of it is re-implemented (§7),
- * and this file declares no layout at all.
+ * Video Selfie — the liveness ring (Archetype D, GUIDELINES.md §6-D; always
+ * dark). ONE screen for every purple section of groups 8 and 9: `selfie
+ * capture 8.0–8.3` and every `selfie capture feedback 9.x` message. They are
+ * `state` × `feedbackText` variants of Core's `PrizmaSelfieCapture`, which is
+ * exactly how the component is axed.
  *
- * **Figma vs Core — Core wins, reported.** These sections draw the camera
- * FULL-BLEED behind a scrimmed ring, on a black surface. Core's
- * `PrizmaSelfieCapture` puts the feed inside the ring's circular window on a
- * light surface, and pins light while the feed is open on purpose — "the
- * capture screen stays WHITE in both modes, light is needed for the shot"
- * (owner decision 2026-07-14, DEVIATIONS #F-27). Reshaping it here would mean
- * re-implementing a Core primitive with a second full-bleed recipe, so the
- * screen ships Core's treatment and the divergence is logged, exactly as the
- * Face Capture pilot settled it.
+ * **Rebuilt 2026-09-30 to follow the frames.** The first pass shipped Core's
+ * INLINE recipe — the feed inside a circular window on a WHITE surface, the
+ * verdicts dissolving the ring into a centred mark — and logged the gap. On
+ * the module page that read as a different product from the rest of the flow:
+ * a small ring on white between two full-bleed dark camera screens, with the
+ * ring vanishing on the very beats Figma keeps it (owner, 2026-09-30: "they
+ * are looking very broken… a broken experience"). Rather than hand-roll the
+ * full-bleed composition here, Core's `PrizmaSelfieCapture` grew the
+ * `mode="overlay"` + `scrim` axis `PrizmaIdCapture` already carries — it is
+ * the Figma library's own `Capture / Selfie overlay` component — and this
+ * screen composes it. Nothing about the ring, the scrim, the glow sweeps, the
+ * verdict marks or the instruction typography is re-implemented (§7).
+ * DEVIATIONS #VS-22.
  *
- * Figma also draws the journey stepper at the top of all fifteen sections.
- * Archetype B has no slot for it and this module does not hand-roll one —
- * reported. Nothing collapses without it: the four states and the eleven
- * messages already render distinctly through Core's own ring treatments and
- * instruction copy.
+ * The composition, measured off `8.0` (390×844):
+ *
+ * - the camera runs FULL-BLEED on `.prizma-viewfinder__surface` (`selfie bg
+ *   image`, 390×844 — it passes under the browser chrome too);
+ * - the journey stepper sits in the band the logo nav normally occupies
+ *   (`top content` y=56, the Stepper 342 wide at x=24), the module-wide
+ *   treatment `VideoSelfieLayout.css` owns;
+ * - the ring is 335 centred in the remaining air (Figma 27,188 → 362,523
+ *   against a 708-high content area), with the instruction stacked under it.
+ *   Core's own Spacing/32 gap replaces Figma's 25.5 (the token wins, §4).
+ *
+ * NO verified tag: `8.x` and `9.x` draw nothing between the instruction and
+ * the bottom of the screen (GUIDELINES §1 — follow the module's section, not
+ * the default). The document stage keeps its tag because its own sections
+ * draw one (#VS-3).
  */
 export declare const VideoSelfieSelfieCaptureScreen: React.ForwardRefExoticComponent<VideoSelfieSelfieCaptureScreenProps & React.RefAttributes<HTMLDivElement>>;
 export default VideoSelfieSelfieCaptureScreen;

package/dist/VideoSelfieSelfieCaptureScreen.js

@@ -1,58 +1,84 @@
 'use client';
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef } from 'react';
-import { PrizmaCaptureScreen } from './CaptureScreen';
+import { PrizmaSelfieCapture, } from '@incodetech/prizma-core-web/selfie-capture';
+import { PrizmaStepper } from '@incodetech/prizma-core-web/stepper';
+import { PrizmaScreenShell } from './ScreenShell';
 import './ScreenLayout.css';
-/** Purple state → Core `PrizmaSelfieCapture` state. Core models the in-flight
- *  and verdict beats as capture STATES — the ring dissolves into the spinner or
- *  the status mark in its own slot (DEVIATIONS #11) — so all four are one
- *  archetype call, not a separate processing screen. */
+import './ViewfinderScreen.css';
+import './VideoSelfieLayout.css';
+/**
+ * Purple state → Core `PrizmaSelfieCapture` state, in the OVERLAY recipe.
+ *
+ * `start` is `filled`, not `empty`: `empty` is Core's *searching* beat and
+ * draws the dashed silhouette guide, which `8.0` and every `9.x` message
+ * deliberately hide (`silhouette hidden=true` on the frames — the guide
+ * belongs to the head-turn steps, which do draw it). `filled` is Core's
+ * "window open, neutral ring, no guide" beat, and in overlay mode there is no
+ * still to fill it with: the host's feed shows straight through the ring.
+ */
 const CAPTURE_STATE = {
-    start: 'ready',
+    start: 'filled',
     processing: 'uploading',
     success: 'success',
     failed: 'error',
 };
+/** Which beat of the seven-step journey the liveness ring occupies — the
+ *  microphone grant is 1, the two document sides 2 and 3. */
+const STEP = 4;
 /**
- * Video Selfie — the liveness ring (Archetype B, GUIDELINES.md §6-B).
- * ONE screen for FIFTEEN purple sections: `selfie capture 8.0–8.3` and every
- * `selfie capture feedback 9.1–9.11` message. They are `state` × `feedbackText`
- * variants of Core's `PrizmaSelfieCapture`, which owns the ring, the
- * silhouette, the ring offset (40), the instruction gap (32), the instruction
- * typography and every verdict treatment. None of it is re-implemented (§7),
- * and this file declares no layout at all.
+ * Video Selfie — the liveness ring (Archetype D, GUIDELINES.md §6-D; always
+ * dark). ONE screen for every purple section of groups 8 and 9: `selfie
+ * capture 8.0–8.3` and every `selfie capture feedback 9.x` message. They are
+ * `state` × `feedbackText` variants of Core's `PrizmaSelfieCapture`, which is
+ * exactly how the component is axed.
+ *
+ * **Rebuilt 2026-09-30 to follow the frames.** The first pass shipped Core's
+ * INLINE recipe — the feed inside a circular window on a WHITE surface, the
+ * verdicts dissolving the ring into a centred mark — and logged the gap. On
+ * the module page that read as a different product from the rest of the flow:
+ * a small ring on white between two full-bleed dark camera screens, with the
+ * ring vanishing on the very beats Figma keeps it (owner, 2026-09-30: "they
+ * are looking very broken… a broken experience"). Rather than hand-roll the
+ * full-bleed composition here, Core's `PrizmaSelfieCapture` grew the
+ * `mode="overlay"` + `scrim` axis `PrizmaIdCapture` already carries — it is
+ * the Figma library's own `Capture / Selfie overlay` component — and this
+ * screen composes it. Nothing about the ring, the scrim, the glow sweeps, the
+ * verdict marks or the instruction typography is re-implemented (§7).
+ * DEVIATIONS #VS-22.
+ *
+ * The composition, measured off `8.0` (390×844):
  *
- * **Figma vs Core — Core wins, reported.** These sections draw the camera
- * FULL-BLEED behind a scrimmed ring, on a black surface. Core's
- * `PrizmaSelfieCapture` puts the feed inside the ring's circular window on a
- * light surface, and pins light while the feed is open on purpose — "the
- * capture screen stays WHITE in both modes, light is needed for the shot"
- * (owner decision 2026-07-14, DEVIATIONS #F-27). Reshaping it here would mean
- * re-implementing a Core primitive with a second full-bleed recipe, so the
- * screen ships Core's treatment and the divergence is logged, exactly as the
- * Face Capture pilot settled it.
+ * - the camera runs FULL-BLEED on `.prizma-viewfinder__surface` (`selfie bg
+ *   image`, 390×844 — it passes under the browser chrome too);
+ * - the journey stepper sits in the band the logo nav normally occupies
+ *   (`top content` y=56, the Stepper 342 wide at x=24), the module-wide
+ *   treatment `VideoSelfieLayout.css` owns;
+ * - the ring is 335 centred in the remaining air (Figma 27,188 → 362,523
+ *   against a 708-high content area), with the instruction stacked under it.
+ *   Core's own Spacing/32 gap replaces Figma's 25.5 (the token wins, §4).
  *
- * Figma also draws the journey stepper at the top of all fifteen sections.
- * Archetype B has no slot for it and this module does not hand-roll one —
- * reported. Nothing collapses without it: the four states and the eleven
- * messages already render distinctly through Core's own ring treatments and
- * instruction copy.
+ * NO verified tag: `8.x` and `9.x` draw nothing between the instruction and
+ * the bottom of the screen (GUIDELINES §1 — follow the module's section, not
+ * the default). The document stage keeps its tag because its own sections
+ * draw one (#VS-3).
  */
-export const VideoSelfieSelfieCaptureScreen = forwardRef(({ strings, state = 'start', feedback, camera, screenId = `video-selfie-selfie-capture-${feedback ?? state}`, overrides, onAction, ...shell }, ref) => {
+export const VideoSelfieSelfieCaptureScreen = forwardRef(({ strings, state = 'start', feedback, documentType = 'id', camera, screenId = `video-selfie-selfie-capture-${feedback ?? state}`, overrides, onAction, className, ...shell }, ref) => {
     const slice = strings.selfieCapture;
     /* The live ring carries an instruction; the in-flight and verdict beats
        carry Core's own status copy instead (its `statusLabels` slot), which is
        why the feedback line is scoped to the live state. */
-    const feedbackText = CAPTURE_STATE[state] === 'ready'
-        ? feedback
-            ? slice.feedback[feedback]
-            : slice.startLabel
-        : undefined;
-    return (_jsx(PrizmaCaptureScreen, { ref: ref, state: CAPTURE_STATE[state], cameraOpen: state === 'start', camera: camera, feedbackText: feedbackText, statusLabels: {
-            uploading: slice.processingLabel,
-            success: slice.successLabel,
-            error: slice.failedLabel,
-        }, verifiedLabel: strings.verifiedLabel, navLabel: strings.navLabel, screenId: screenId, overrides: overrides, onAction: onAction, ...shell }));
+    const feedbackText = state === 'start' ? (feedback ? slice.feedback[feedback] : slice.startLabel) : undefined;
+    return (_jsxs(PrizmaScreenShell, { ref: ref, dark: true, "data-pcs-overlay": "window", className: className, ...shell, children: [_jsx("div", { className: "prizma-viewfinder__surface", children: camera }), _jsx("div", { className: "video-selfie-stepper", children: _jsx(PrizmaStepper, { steps: 7, currentState: STEP, documentType: documentType, completedValueText: strings.stepperCompletedLabel }) }), _jsx("div", { className: [
+                    'prizma-viewfinder__content',
+                    overrides?.align === 'left' ? 'prizma-viewfinder__content--left' : '',
+                ]
+                    .filter(Boolean)
+                    .join(' '), children: _jsx("div", { className: "video-selfie-band video-selfie-band--ring", children: _jsx(PrizmaSelfieCapture, { mode: "overlay", scrim: true, state: CAPTURE_STATE[state], feedbackText: feedbackText, statusLabels: {
+                            uploading: slice.processingLabel,
+                            success: slice.successLabel,
+                            error: slice.failedLabel,
+                        } }) }) })] }));
 });
 VideoSelfieSelfieCaptureScreen.displayName = 'VideoSelfieSelfieCaptureScreen';
 export default VideoSelfieSelfieCaptureScreen;

package/dist/VideoSelfieSpeakScreen.js

@@ -59,7 +59,21 @@ export const VideoSelfieSpeakScreen = forwardRef(({ strings, family = 'voiceCons
             onPrimaryClick: () => onAction?.({ type: 'cta', screenId }),
             secondaryLabel: slice.confirm.retryLabel,
             onSecondaryClick: () => onAction?.({ type: 'secondary', screenId }),
-        } })) : stage === 'processing' ? (_jsx(PrizmaModalContent, { title: slice.processingLabel, showButtonGroup: false, closeLabel: slice.closeLabel, onClose: () => onAction?.({ type: 'tertiary', screenId }), body: _jsx(PrizmaLoadingSpinner, { loadingLabel: slice.processingLabel }) })) : stage === 'success' ? (_jsx(PrizmaModalContent, { title: slice.successLabel, showButtonGroup: false, closeLabel: slice.closeLabel, onClose: () => onAction?.({ type: 'tertiary', screenId }), body: _jsx("span", { className: "video-selfie-sheet-status", children: _jsx(IconStatusPositive, { size: "xl" }) }) })) : (_jsx(PrizmaModalContent, { title: prompt, subtitle: slice.eyebrow, 
+        } })) : stage === 'processing' || stage === 'success' ? (
+    /* The two verdict cards. They carry no buttons, so left alone they came
+       out shorter than the prompt they replace and the sheet jumped between
+       steps; and Core's Modal renders `body` AFTER the heading, which put
+       the spinner and the check UNDER their own label. Both are fixed in
+       the module: `--status` gives the card the prompt's measure and centres
+       its content, and the mark is passed as the LEADING slot so it stacks
+       above the copy the way `10.2` / `10.3` draw it.
+
+       No ✕ either. Figma draws one, but it is the same call #VS-5 already
+       made on the prompt: closing mid-step strands the user with no way
+       back, and a dismiss that appears on two of five cards and not the
+       other three is the inconsistency, not the fix (owner, 2026-09-30).
+       DEVIATIONS #VS-25. */
+    _jsx(PrizmaModalContent, { title: stage === 'processing' ? slice.processingLabel : slice.successLabel, showCloseIcon: false, showButtonGroup: false, leading: _jsx("span", { className: "video-selfie-sheet-status", children: stage === 'processing' ? (_jsx(PrizmaLoadingSpinner, { loadingLabel: slice.processingLabel })) : (_jsx(IconStatusPositive, { size: "xl" })) }) })) : (_jsx(PrizmaModalContent, { title: prompt, subtitle: slice.eyebrow, 
         /* No dismiss ✕ on the record step: the sheet IS the step, and closing it
            would strand the user mid-recording with no way back into the flow
            (owner-reported 2026-08-19). The confirm sheet already suppressed it;
@@ -79,7 +93,7 @@ export const VideoSelfieSpeakScreen = forwardRef(({ strings, family = 'voiceCons
                 secondaryLabel: slice.idleCtaLabel,
                 onSecondaryClick: () => onAction?.({ type: 'cta', screenId }),
             } }));
-    return (_jsxs(PrizmaScreenShell, { ref: ref, dark: true, className: className, ...shell, children: [_jsx("div", { className: "prizma-viewfinder__surface", children: camera }), _jsx("div", { className: "video-selfie-stepper", children: _jsx(PrizmaStepper, { steps: 7, currentState: STEP[family], documentType: documentType, completedValueText: strings.stepperCompletedLabel }) }), _jsx("div", { className: [
+    return (_jsxs(PrizmaScreenShell, { ref: ref, dark: true, "data-pcs-overlay": "window", className: className, ...shell, children: [_jsx("div", { className: "prizma-viewfinder__surface", children: camera }), _jsx("div", { className: "video-selfie-stepper", children: _jsx(PrizmaStepper, { steps: 7, currentState: STEP[family], documentType: documentType, completedValueText: strings.stepperCompletedLabel }) }), _jsx("div", { className: [
                     'prizma-viewfinder__content',
                     overrides?.align === 'left' ? 'prizma-viewfinder__content--left' : '',
                 ]
@@ -87,6 +101,9 @@ export const VideoSelfieSpeakScreen = forwardRef(({ strings, family = 'voiceCons
                     .join(' '), children: _jsx("div", { className: "video-selfie-band", children: stage === 'recording' ? (_jsxs("span", { className: "video-selfie-recording", children: [_jsx(IconSoundWave, { size: "xl" }), _jsx("span", { className: "prizma-viewfinder__title", children: slice.recordingLabel })] })) : null }) }), isConfirm ? (_jsx("div", { className: "video-selfie-sheet-scrim", "aria-hidden": "true" })) : null, _jsx("div", { "data-prizma-theme": "light", className: [
                     'video-selfie-sheet-panel',
                     isConfirm ? 'video-selfie-sheet-panel--centered' : '',
+                    stage === 'processing' || stage === 'success'
+                        ? 'video-selfie-sheet-panel--status'
+                        : '',
                 ]
                     .filter(Boolean)
                     .join(' '), children: card })] }));

package/dist/VideoSelfieStrings.d.ts

@@ -13,18 +13,58 @@ export interface VideoSelfieTutorialRow {
  * (its icon set is documented as "the Video Selfie sequence").
  */
 export type VideoSelfieTutorialRowKind = 'recording' | 'idFront' | 'idBack' | 'passport' | 'frontCamera' | 'waveHand' | 'questions' | 'speak';
-/** The eleven live-feedback messages of group 9, in Figma order. */
-export type VideoSelfieFeedbackKind = 'dark' | 'blurry' | 'maskDetected' | 'glassesDetected' | 'headTilted' | 'lookAtCamera' | 'turnRight' | 'turnLeft' | 'alignFace' | 'moveCloser' | 'moveAway';
+/** The live-feedback messages of group 9, in Figma order. Fourteen since
+ *  2026-09-30: `9.12`–`9.14` (head cover · closed eyes · face occlusion) were
+ *  added to the frames after the module's first build and are on the Web, iOS
+ *  and Android full-flow maps. */
+export type VideoSelfieFeedbackKind = 'dark' | 'blurry' | 'maskDetected' | 'glassesDetected' | 'headTilted' | 'lookAtCamera' | 'turnRight' | 'turnLeft' | 'alignFace' | 'moveCloser' | 'moveAway' | 'headCover' | 'closedEyes' | 'faceOcclusion';
+/** Which head-turn the liveness step is asking for (the `🙂‍↔️ Turn Head` band
+ *  of the full-flow frames: Left · Right · Upward · Downward, each drawn as a
+ *  guide beat and a captured beat). */
+export type VideoSelfieTurnDirection = 'left' | 'right' | 'up' | 'down';
 /** Which face of the document the ID stage is on (groups 3 and 5). */
 export type VideoSelfieIdSide = 'front' | 'back';
-/** Why an ID read was rejected (group 6, the `.1`–`.4` variants). */
 /**
- * REMOVED (2026-08-19). A rejection-REASON axis (`scanFailed | name | photo |
- * typeMismatch`) was invented: group 6 draws exactly FOUR sections —
- * `6.1.1`/`6.2.1` (front try-again / failed) and `6.3.1`/`6.4.1` (back) — with
- * no reason axis at all, so the four kinds multiplied the gallery to 16 error
- * cards where the spec has 4. Severity is the only real axis. DEVIATIONS #VS-1.
+ * Why an ID read was rejected — the `.1`–`.4` suffix of every group 6 section.
+ *
+ * RESTORED 2026-09-30. It was removed on 2026-08-19 on the reading that "group
+ * 6 draws exactly four sections", because the `📐 Screens specs & behavior`
+ * page documents ONE representative per group (`6.1.1`, `6.2.1`, `6.3.1`,
+ * `6.4.1`) and the rest are component variants inside it. The `🔸 Full flow
+ * map` draws them all, and they carry DIFFERENT copy, not a translation of
+ * one line: `6.2.2 - name failed` reads "Name verification failed",
+ * `6.2.3 - photo failed` reads "ID photo verification failed",
+ * `6.1.4 - type mismatch try again` reads "ID type mismatch, show the same ID".
+ * Collapsing them to one line lost three rejections a user can actually hit.
+ * DEVIATIONS #VS-1.
  */
+export type VideoSelfieIdErrorReason = 'scan' | 'name' | 'photo' | 'typeMismatch';
+/**
+ * A live CONDITION the document stage can coach the user out of, as opposed
+ * to a rejection it has to report.
+ *
+ * BOTH legs run five of these before the identity checks — the frames draw
+ * them on the back only, and the owner extended them to the front on
+ * 2026-09-30 ("I think it would be nice to add them for the front as well").
+ * Each one draws its OWN screen: the frame in its
+ * matching red treatment with a `Capture feedback` bubble above it saying
+ * what to do. They were all wired to the single "ID scan failed, try again"
+ * card until 2026-09-30 — the five screens are `frame` nodes rather than
+ * component instances in the flow map, so the first trace walked straight
+ * past them (owner: "we do have those states in figma").
+ *
+ * All five map 1:1 onto states Core already ships: four onto
+ * `PrizmaIdCapture`'s own `error-*` treatments, and `blurry` onto the plain
+ * error border plus the bubble, which is the recipe the owner set for
+ * detection results on 2026-07-28 (the border is the state, the message is
+ * the bubble).
+ */
+/** One coaching bubble's copy: what is wrong, and what to do about it. */
+export interface VideoSelfieConditionCopy {
+    title: string;
+    subtitle: string;
+}
+export type VideoSelfieIdCondition = 'wrongSide' | 'notAligned' | 'blurry' | 'glare' | 'tooDark';
 /** Whether the rejection invites a retry (`6.1` / `6.3`) or is terminal
  *  (`6.2` / `6.4`). */
 export type VideoSelfieIdErrorSeverity = 'tryAgain' | 'failed';
@@ -125,9 +165,26 @@ export interface VideoSelfieStrings {
         processingLabel: string;
         /** Accepted label (`3.3` / `5.3`). */
         successLabel: string;
-        /** Rejection copy, keyed reason → severity (group 6). */
-        /** Rejection copy per severity (group 6: try-again vs failed). */
-        errors: Record<VideoSelfieIdErrorSeverity, string>;
+        /** Rejection copy, keyed reason → severity (group 6). The two axes are
+         *  independent: `6.1.x` / `6.3.x` are the try-again lines, `6.2.x` /
+         *  `6.4.x` the terminal ones, and the `.1`–`.4` suffix is the reason. The
+         *  two sides share the copy — only the stepper beat differs. */
+        errors: Record<VideoSelfieIdErrorReason, Record<VideoSelfieIdErrorSeverity, string>>;
+        /**
+         * The five coaching bubbles — title + what to do about it.
+         *
+         * Only `wrongSide` is keyed by side, because it is the only one that
+         * NAMES the face the user should be showing; the other four describe the
+         * shot, which is the same problem whichever face is up. Keying all five by
+         * side would duplicate four strings per language for nothing.
+         */
+        conditions: {
+            wrongSide: Record<VideoSelfieIdSide, VideoSelfieConditionCopy>;
+            notAligned: VideoSelfieConditionCopy;
+            blurry: VideoSelfieConditionCopy;
+            glare: VideoSelfieConditionCopy;
+            tooDark: VideoSelfieConditionCopy;
+        };
     };
     /** Group 4 — the flip interstitial. */
     flipId: {
@@ -147,8 +204,17 @@ export interface VideoSelfieStrings {
         successLabel: string;
         /** `8.3` rejected. */
         failedLabel: string;
-        /** Group 9 — the eleven live-feedback lines. */
+        /** Group 9 — the fourteen live-feedback lines. */
         feedback: Record<VideoSelfieFeedbackKind, string>;
+        /** The head-turn step's own instruction, one per direction (the
+         *  `🙂‍↔️ Turn Head` band of the full-flow frames). */
+        turn: Record<VideoSelfieTurnDirection, string>;
+        /** The wave step's instruction and its three checkpoints (`👋 Wave`). */
+        wave: {
+            instruction: string;
+            steps: string[];
+            doneLabel: string;
+        };
     };
     /** Groups 10 · 11 — the spoken steps. */
     speak: Record<VideoSelfieSpeakFamily, VideoSelfieSpeakStrings>;
@@ -186,9 +252,12 @@ export interface VideoSelfieStrings {
             ctaLabel: string;
             quitLabel: string;
         };
-        /** `14.4` — connectivity. */
+        /** `14.4` — connectivity. The supporting line is the generic family's
+         *  (`ErrorScreensStrings.noConnection.subtitle`), so this screen reads
+         *  like every other module's connectivity screen (#F-34, #PI-8). */
         noConnection: {
             title: string;
+            subtitle?: string;
             ctaLabel: string;
             quitLabel: string;
         };

package/dist/VideoSelfieTurnHeadScreen.d.ts

@@ -0,0 +1,51 @@
+import React, { type ReactNode } from 'react';
+import { type PrizmaScreenShellProps } from './ScreenShell';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { VideoSelfieDocumentType, VideoSelfieStrings, VideoSelfieTurnDirection } from './VideoSelfieStrings';
+import './ScreenLayout.css';
+import './ViewfinderScreen.css';
+import './VideoSelfieLayout.css';
+/** The two beats each direction is drawn in: the stage ASKING (dashed guide
+ *  ring) and the stage having SEEN it (the positive ring). */
+export type VideoSelfieTurnStage = 'ask' | 'done';
+export interface VideoSelfieTurnHeadScreenProps extends Omit<PrizmaScreenShellProps, 'dark' | 'title' | 'children'> {
+    /** Module copy — this screen reads `selfieCapture.turn`. */
+    strings: VideoSelfieStrings;
+    /** Which way the user is asked to turn. Default `left`. */
+    direction?: VideoSelfieTurnDirection;
+    /** Asking, or seen. Default `ask`. */
+    stage?: VideoSelfieTurnStage;
+    /** Which document the journey collects — the Stepper's own `documentType`. */
+    documentType?: VideoSelfieDocumentType;
+    /** Live camera feed (<video>) or sample still (<img>), full-bleed behind
+     *  the ring. */
+    camera?: ReactNode;
+    screenId?: string;
+    overrides?: PrizmaScreenOverrides;
+    onAction?: PrizmaScreenActionHandler;
+}
+/**
+ * Video Selfie — the head-turn beats of the liveness sequence (Archetype D,
+ * GUIDELINES.md §6-D; always dark). NEW 2026-09-30: the `🙂‍↔️ Turn Head` band
+ * of the Web / iOS / Android full-flow frames draws four directions, each in
+ * two beats, and none of them existed in the screens package — the module
+ * jumped straight from the liveness ring to the spoken steps.
+ *
+ * The frames are the liveness stage with three changes, and nothing else:
+ *
+ * - the ring is Core's GUIDE stroke (`ring="dashed"`) while the stage waits
+ *   for the turn, and the positive ring once it has seen it;
+ * - the silhouette guide is ON (Core's `empty`), because the user is being
+ *   asked to move their face rather than hold it still;
+ * - a small arrow chip sits between the ring and the instruction, saying
+ *   which way.
+ *
+ * The mark under the ring is a canonical bank glyph at 2xl — the disc is part
+ * of the drawing, not something this screen paints. `PrizmaTitle.icon` takes
+ * `status | spinner | none` only (DEVIATIONS #10), so the block below the ring
+ * is composed here; it declares a gap and nothing else. CORE REQUEST stands: a
+ * `glyph` slot on the capture stage, so this and Face Capture's future hint
+ * marks share one component. DEVIATIONS #VS-20.
+ */
+export declare const VideoSelfieTurnHeadScreen: React.ForwardRefExoticComponent<VideoSelfieTurnHeadScreenProps & React.RefAttributes<HTMLDivElement>>;
+export default VideoSelfieTurnHeadScreen;

package/dist/VideoSelfieTurnHeadScreen.js

@@ -0,0 +1,66 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { IconChevronDown, IconChevronLeft, IconChevronRight, IconChevronUp, } from '@incodetech/prizma-core-icons';
+import { PrizmaSelfieCapture } from '@incodetech/prizma-core-web/selfie-capture';
+import { PrizmaStepper } from '@incodetech/prizma-core-web/stepper';
+import { PrizmaScreenShell } from './ScreenShell';
+import './ScreenLayout.css';
+import './ViewfinderScreen.css';
+import './VideoSelfieLayout.css';
+/**
+ * Direction → the mark under the ring, from the canonical bank at 2xl (48) —
+ * the size the frames draw it (`element container` 342×48, the glyph centred).
+ *
+ * Since the Core and Enterprise icon unification (Sofia, 2026-10-06) the
+ * mark is the library chevron at 2xl: the four solid circle arrows left the
+ * bank (their old names now alias the chevrons). Nothing is drawn here (§10).
+ *
+ * The mark never mirrors in RTL (Sofia, 2026-10-07): a head turn is a
+ * physical direction, so the chevrons keep their LTR orientation in Hebrew.
+ * The opt-out is one scoped rule in `VideoSelfieLayout.css`; the chevrons
+ * still mirror everywhere else.
+ */
+const TURN_ICON = {
+    left: _jsx(IconChevronLeft, { size: "2xl" }),
+    right: _jsx(IconChevronRight, { size: "2xl" }),
+    up: _jsx(IconChevronUp, { size: "2xl" }),
+    down: _jsx(IconChevronDown, { size: "2xl" }),
+};
+/**
+ * Video Selfie — the head-turn beats of the liveness sequence (Archetype D,
+ * GUIDELINES.md §6-D; always dark). NEW 2026-09-30: the `🙂‍↔️ Turn Head` band
+ * of the Web / iOS / Android full-flow frames draws four directions, each in
+ * two beats, and none of them existed in the screens package — the module
+ * jumped straight from the liveness ring to the spoken steps.
+ *
+ * The frames are the liveness stage with three changes, and nothing else:
+ *
+ * - the ring is Core's GUIDE stroke (`ring="dashed"`) while the stage waits
+ *   for the turn, and the positive ring once it has seen it;
+ * - the silhouette guide is ON (Core's `empty`), because the user is being
+ *   asked to move their face rather than hold it still;
+ * - a small arrow chip sits between the ring and the instruction, saying
+ *   which way.
+ *
+ * The mark under the ring is a canonical bank glyph at 2xl — the disc is part
+ * of the drawing, not something this screen paints. `PrizmaTitle.icon` takes
+ * `status | spinner | none` only (DEVIATIONS #10), so the block below the ring
+ * is composed here; it declares a gap and nothing else. CORE REQUEST stands: a
+ * `glyph` slot on the capture stage, so this and Face Capture's future hint
+ * marks share one component. DEVIATIONS #VS-20.
+ */
+export const VideoSelfieTurnHeadScreen = forwardRef(({ strings, direction = 'left', stage = 'ask', documentType = 'id', camera, screenId = `video-selfie-turn-${direction}-${stage}`, overrides, onAction, className, ...shell }, ref) => (_jsxs(PrizmaScreenShell, { ref: ref, dark: true, "data-pcs-overlay": "window", className: className, ...shell, children: [_jsx("div", { className: "prizma-viewfinder__surface", children: camera }), _jsx("div", { className: "video-selfie-stepper", children: _jsx(PrizmaStepper, { steps: 7, currentState: 4, documentType: documentType, completedValueText: strings.stepperCompletedLabel }) }), _jsx("div", { className: [
+                'prizma-viewfinder__content',
+                overrides?.align === 'left' ? 'prizma-viewfinder__content--left' : '',
+            ]
+                .filter(Boolean)
+                .join(' '), children: _jsxs("div", { className: "video-selfie-band video-selfie-band--ring", children: [_jsx(PrizmaSelfieCapture, { mode: "overlay", scrim: true, 
+                        /* The ring says WHICH WAY: the half on the side being asked for
+                           is dashed while the stage waits and positive once it has seen
+                           the turn, and the other half stays the neutral track. The state
+                           is `filled` on both beats — the verdict lives in the arc, not in
+                           the whole ring, so nothing else about the stage changes. */
+                        guide: { side: direction, state: stage === 'ask' ? 'waiting' : 'seen' }, state: "filled", showFeedback: false }), _jsxs("div", { className: "video-selfie-turn", children: [_jsx("span", { className: "video-selfie-turn__mark", children: TURN_ICON[direction] }), _jsx("p", { className: "prizma-viewfinder__title", children: strings.selfieCapture.turn[direction] })] })] }) })] })));
+VideoSelfieTurnHeadScreen.displayName = 'VideoSelfieTurnHeadScreen';
+export default VideoSelfieTurnHeadScreen;

package/dist/VideoSelfieTutorialScreen.d.ts

@@ -3,6 +3,7 @@ import { type PrizmaListScreenProps } from './ListScreen';
 import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
 import type { VideoSelfieDocumentType, VideoSelfieStrings } from './VideoSelfieStrings';
 import './ScreenLayout.css';
+import './VideoSelfieLayout.css';
 export interface VideoSelfieTutorialScreenProps extends Omit<PrizmaListScreenProps, 'status' | 'title' | 'subtitle' | 'children' | 'ctaLabel' | 'secondaryCtaLabel' | 'linkLabel' | 'verifiedLabel' | 'navLabel'> {
     /** Module copy — this screen reads the `tutorial` slice. */
     strings: VideoSelfieStrings;
@@ -28,6 +29,14 @@ export interface VideoSelfieTutorialScreenProps extends Omit<PrizmaListScreenPro
  * NOT archetype A: A centres one illustration in the flexible middle; here the
  * middle is a seven-row list that must span the column and start at the top —
  * the distinction `ScreenLayout.css` draws between `__flex` and `__list`.
+ *
+ * The one class it carries, `video-selfie-tutorial`, exists so the module's
+ * stylesheet can reach this screen on a SHORT panel: seven rows fit the 844
+ * reference to the pixel (measured 497 of 497), and on a 640 or 693 one they
+ * paint straight through the CTA. `VideoSelfieLayout.css` lets them pan there,
+ * the same concession the Android settings walk-through already makes with
+ * `scrollList` — and `scrollList` itself is not used here because its
+ * Spacing/16 margin would take the reference below the 497 the rows need.
  */
 export declare const VideoSelfieTutorialScreen: React.ForwardRefExoticComponent<VideoSelfieTutorialScreenProps & React.RefAttributes<HTMLDivElement>>;
 export default VideoSelfieTutorialScreen;

package/dist/VideoSelfieTutorialScreen.js

@@ -1,10 +1,11 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from 'react';
-import { IconBankCard, IconIdFront, IconMessages, IconMicrophone, IconNumberedList, IconPassport, IconUser, IconWavingHand, } from '@incodetech/prizma-core-icons';
-import { PrizmaListItem } from '@incodetech/prizma-core-web/list';
+import { IconBankCard, IconMessages, IconMicrophone, IconNumberedList, IconPassportCapture, IconUser, IconUserInformation, IconWavingHand, } from '@incodetech/prizma-core-icons';
+import { PrizmaList } from '@incodetech/prizma-core-web/list';
 import { PrizmaListScreen } from './ListScreen';
 import './ScreenLayout.css';
+import './VideoSelfieLayout.css';
 /**
  * Journey beat → canonical bank glyph. ONE map, in one place — the same seven
  * glyphs Core's `PrizmaStepper` carries (its icon set is documented as "the
@@ -13,9 +14,13 @@ import './ScreenLayout.css';
  */
 const ROW_ICONS = {
     recording: _jsx(IconMicrophone, { size: "m" }),
-    idFront: _jsx(IconIdFront, { size: "m" }),
+    // `user-information` and `passport-capture`, NOT `id-front` and `passport`:
+    // the tutorial promises the steps the Stepper then counts off, and the
+    // Stepper's own sequence uses these two. Corrected 2026-09-30 — the tutorial
+    // was drawing a different ID glyph from the one the journey shows.
+    idFront: _jsx(IconUserInformation, { size: "m" }),
     idBack: _jsx(IconBankCard, { size: "m" }),
-    passport: _jsx(IconPassport, { size: "m" }),
+    passport: _jsx(IconPassportCapture, { size: "m" }),
     frontCamera: _jsx(IconUser, { size: "m" }),
     waveHand: _jsx(IconWavingHand, { size: "m" }),
     questions: _jsx(IconNumberedList, { size: "m" }),
@@ -35,7 +40,19 @@ const ROW_ICONS = {
  * NOT archetype A: A centres one illustration in the flexible middle; here the
  * middle is a seven-row list that must span the column and start at the top —
  * the distinction `ScreenLayout.css` draws between `__flex` and `__list`.
+ *
+ * The one class it carries, `video-selfie-tutorial`, exists so the module's
+ * stylesheet can reach this screen on a SHORT panel: seven rows fit the 844
+ * reference to the pixel (measured 497 of 497), and on a 640 or 693 one they
+ * paint straight through the CTA. `VideoSelfieLayout.css` lets them pan there,
+ * the same concession the Android settings walk-through already makes with
+ * `scrollList` — and `scrollList` itself is not used here because its
+ * Spacing/16 margin would take the reference below the 497 the rows need.
  */
-export const VideoSelfieTutorialScreen = forwardRef(({ strings, documentType = 'id', screenId = `video-selfie-tutorial-${documentType}`, overrides, onAction, ...shell }, ref) => (_jsx(PrizmaListScreen, { ref: ref, title: strings.tutorial.title, subtitle: strings.tutorial.subtitle, ctaLabel: strings.tutorial.ctaLabel, verifiedLabel: strings.verifiedLabel, navLabel: strings.navLabel, screenId: screenId, overrides: overrides, onAction: onAction, ...shell, children: _jsx("ul", { className: "video-selfie-tutorial-list", children: strings.tutorial.rows[documentType].map((row) => (_jsx("li", { children: _jsx(PrizmaListItem, { variant: "icon-m", label: row.label, icon: ROW_ICONS[row.kind] }) }, row.kind))) }) })));
+export const VideoSelfieTutorialScreen = forwardRef(({ strings, documentType = 'id', screenId = `video-selfie-tutorial-${documentType}`, overrides, onAction, className, ...shell }, ref) => (_jsx(PrizmaListScreen, { ref: ref, className: ['video-selfie-tutorial', className].filter(Boolean).join(' '), title: strings.tutorial.title, subtitle: strings.tutorial.subtitle, ctaLabel: strings.tutorial.ctaLabel, verifiedLabel: strings.verifiedLabel, navLabel: strings.navLabel, screenId: screenId, overrides: overrides, onAction: onAction, ...shell, children: _jsx(PrizmaList, { variant: "icons-chain", showItem3: true, showItem4: true, showItem5: true, showItem6: true, showItem7: true, items: strings.tutorial.rows[documentType].map((row) => ({
+            variant: 'icon-connector',
+            label: row.label,
+            icon: ROW_ICONS[row.kind],
+        })) }) })));
 VideoSelfieTutorialScreen.displayName = 'VideoSelfieTutorialScreen';
 export default VideoSelfieTutorialScreen;