@incodetech/prizma-core-screens 0.2.7 → 0.2.12

package/src/VideoSelfieLayout.css

@@ -13,6 +13,14 @@
  * spoken step) carry the band here.
  */
 
+/* The air above the stepper band, named once because TWO rules depend on it:
+ * the band's own offset and the ring's, which counts down from Figma's y=188.
+ * Scoped to a shell that actually carries the band, so no other module's
+ * screen inherits a property it never reads. */
+.prizma-screen-shell:has(> .video-selfie-stepper) {
+  --vs-top-reserve: max(var(--pcs-status-bar, 47px), var(--prizma-spacing-24));
+}
+
 /* ── Journey stepper band ────────────────────────────────────────────────────
  * Figma draws the Stepper as the first thing under the OS status bar — no logo
  * row above it (`top content` frame, y=54, the Stepper 342 wide at x=24 on
@@ -42,7 +50,14 @@
    * ScreenLayout.css already reserves for the tag and shutter, which must sit
    * above the scrim for exactly the same reason. DEVIATIONS #VS-2. */
   z-index: 2;
-  margin-top: var(--pcs-status-bar, 47px);
+  /* Clear the OS status bar, and NEVER sit flush against the top edge. A host
+   * that draws no phone chrome sets `--pcs-status-bar: 0px` — Core Lab's
+   * desktop panel does — and the band then started at pixel zero, hard against
+   * the browser bar (Camila, 2026-10-09: "the stepper is way too high and
+   * touches the screen border"). The floor is the content column's own
+   * Spacing/24 gutter, the same air every other screen has above its first
+   * block; on a phone the 47 reserve is larger and nothing moves. */
+  margin-top: var(--vs-top-reserve, var(--pcs-status-bar, 47px));
   padding-inline: var(--prizma-spacing-24);
 }
 
@@ -63,6 +78,74 @@
   z-index: 1;
 }
 
+/* A band carrying the coaching bubble keeps the bubble's own height; the frame
+ * below is what gives ground on a short screen.
+ *
+ * `.video-selfie-band` is `flex: 1; min-height: 0`, so on a 360 × 640 panel the
+ * flex column took the whole shortfall out of THIS band: it collapsed to zero
+ * and the bubble — which is still painted — overflowed it in both directions,
+ * across the stepper above and the document frame below (Camila, 2026-10-07).
+ * `IdCaptureLayout.css` already names the rule for this exact column: the frame
+ * is the one part that shrinks, the band above it keeps its content height. Same
+ * rule, this module's class. */
+.video-selfie-band:has(> .video-selfie-feedback) {
+  flex: 0 0 auto;
+  min-height: min-content;
+}
+
+/* …and the band UNDER the document stage never gives up the footer's own
+ * footprint, so the frame stops above the verified tag instead of sliding under
+ * it. `ScreenLayout.css` reserves `--pcs-footer-space` on
+ * `.prizma-screen-layout__content`; these are camera surfaces with no content
+ * column, so the reserve has to be claimed here, and claiming it as the BAND's
+ * minimum rather than as padding on the viewfinder is what keeps the reference
+ * untouched: at 390 the band is already ~100 tall, so a 72 floor is a no-op and
+ * the frame stays exactly where Figma centres it (y 172–627 of a 91–708 content
+ * area). On a 640-tall panel the floor binds, and the frame — the one part of
+ * this column that may get smaller (owner, 2026-08-18) — gives the height back
+ * through Core's own `flex-basis`, its aspect narrowing it to match. */
+.video-selfie-stage + .video-selfie-band {
+  min-height: var(--pcs-footer-space);
+}
+
+/* ── The camera owns the window; only the HUD is a column ────────────────────
+ * The five camera screens carry `data-pcs-overlay="window"` on their shell.
+ * That attribute is the screens package's contract with a host that FRAMES a
+ * screen — Core Lab's desktop panel, which otherwise lays every screen inside
+ * the 800 x 840 white card Elena's eKYB frames draw. A form belongs in that
+ * card. A camera does not: boxed into it, the feed and its scrim were a narrow
+ * strip with white either side of them on a 1440 panel, the desktop version of
+ * the "phone pasted onto the tablet" her 2026-10-02 call already fixed for the
+ * tablet (Camila, 2026-10-08). `PermissionsAskScreen` set the same attribute
+ * first, for its dialog's dim.
+ *
+ * NOT fixed here: Face Capture's, ID Capture's and Document Capture's camera
+ * stages sit in the same card for the same reason. The rule reads as theirs
+ * too, but their screens have not been looked at on the panel — reported. */
+
+/* ── The HUD stays in a column when the panel is wider than the reference ─────
+ * On a panel wider than 390 the camera feed and its scrim are full-bleed — that
+ * is what a camera does on a real device, and what the Lab's laid-out
+ * breakpoints draw (`bleed`, convert.ts). The copy over the feed is NOT: left to
+ * `width: 100%` the stepper ran the full 720 of a tablet and the coaching bubble
+ * with it, which reads as a stretched phone rather than a tablet (Camila,
+ * 2026-10-07).
+ *
+ * `--pcs-column` is the host's own property for this — the same contract as
+ * `--pcs-status-bar` — and it is already what `ScreenLayout`'s content and band
+ * read on a device panel: 390 on a phone, 468 on a tablet or desktop one. Here
+ * the two Spacing/24 gutters come off it, because these bands sit INSIDE
+ * `.prizma-viewfinder__content`'s own padding, so the result is exactly the
+ * content width the reference has (342 at 390, 420 on a tablet). Unset — a plain
+ * 390 screen, any SDK host — the calc resolves to 342 and nothing moves. */
+.video-selfie-stepper > *,
+.video-selfie-feedback,
+.video-selfie-recording,
+.video-selfie-turn {
+  max-width: calc(var(--pcs-column, 390px) - 2 * var(--prizma-spacing-24));
+  margin-inline: auto;
+}
+
 /* ── The face ring sits in the SAME place on every screen ────────────────────
  * Figma puts `ring-uploading` at (27, 188) on every frame that draws it —
  * `8.x`, `9.x`, the four head turns and the wave — and never moves it. Left
@@ -81,7 +164,95 @@
  * DEVIATIONS #VS-24. */
 .video-selfie-band--ring {
   justify-content: flex-start;
-  padding-top: calc(188px - var(--pcs-status-bar, 47px) - 37px - var(--prizma-spacing-40));
+  /* 188 is Figma's, and on a panel SHORTER than the 844 the frames are drawn
+   * against it is read proportionally: 154 at 693, 143 at 640. The reference
+   * and anything taller keep the literal 188, which is what `min()` guarantees.
+   * Fixed, it was 29% of a 640 panel — the ring plus its status block ran up to
+   * 67px past the fold (Camila, 2026-10-07), and the air above a ring is the
+   * first thing that should give. */
+  padding-top: max(
+    0px,
+    calc(
+      min(188px, 100cqh * 188 / 844) - var(--vs-top-reserve, var(--pcs-status-bar, 47px)) -
+        37px - var(--prizma-spacing-40)
+    )
+  );
+}
+
+/* ── On a LANDSCAPE window the ring centres instead ──────────────────────────
+ * 188 is a portrait measurement: it is 22% down an 844 phone, and the capture
+ * block reads as sitting near the top with the instruction under it. Down a
+ * 1440 x 820 browser window the same offset leaves the whole bottom half empty
+ * and the composition reads as a phone screen pinned to the top of a desktop
+ * page (Camila, 2026-10-09).
+ *
+ * #VS-24's rule survives intact, and it is the reason this is an OFFSET and not
+ * `justify-content: center`. The rule is that the ring does not move BETWEEN
+ * screens — a capture window that jumps as the step advances reads as a glitch
+ * — and the stack under the ring is a different height on every one of them (an
+ * instruction here, a spinner and a label there, an arrow chip on the turns).
+ * Centring that stack would move the ring again, which is the exact bug #VS-24
+ * was written for. Centring the RING instead depends on two numbers only: the
+ * shell's height and Core's own 335 capture box. Every ring screen lands in the
+ * same place, and the copy flows below it as before. */
+@container pcs-screen (min-aspect-ratio: 1 / 1) {
+  .video-selfie-band--ring {
+    padding-top: max(
+      0px,
+      calc(
+        (100cqh - 335px) / 2 - var(--vs-top-reserve, var(--pcs-status-bar, 47px)) - 37px -
+          var(--prizma-spacing-40)
+      )
+    );
+  }
+}
+
+/* ── …and on a short panel the ring itself gives ground ──────────────────────
+ * Scaling the offset is not enough at 640: the stack below the ring is a title
+ * and a subtitle on the verdict beats ("Selfie not captured, try again") and an
+ * arrow plus an instruction on the turns, and all of it is content height the
+ * band cannot take back.
+ *
+ * So the RING shrinks, exactly the way `IdCaptureLayout.css` already lets the
+ * document frame shrink and for the same stated reason — the capture window may
+ * get smaller, that is not a constraint (owner, 2026-08-18). Core's stage is
+ * `width: 100%; aspect-ratio: 1`, so giving it a flex basis of its own width and
+ * letting the column take the shortfall out of its HEIGHT makes the aspect
+ * narrow it back: still a circle, still centred, just smaller. Everything inside
+ * it is already proportional (the ring is an SVG on a 335 viewBox, the
+ * silhouette is in %), so nothing else has to be told.
+ *
+ * 87.7cqw is Core's own capture width (`min(87.7cqw, 335px)` — 335 of the 390
+ * reference); it is named here only because a flex basis cannot read it off the
+ * element it is sizing. Outside the query not one of these declarations exists,
+ * so the reference stage is untouched. */
+@container pcs-screen (max-height: 720px) {
+  .prizma-viewfinder__content:has(> .video-selfie-band--ring) {
+    min-height: 0;
+  }
+
+  .video-selfie-band--ring {
+    min-height: 0;
+  }
+
+  .video-selfie-band--ring > .prizma-selfie-capture {
+    flex: 0 1 auto;
+    min-height: 0;
+  }
+
+  .video-selfie-band--ring .prizma-selfie-capture__stage {
+    flex: 0 1 auto;
+    min-height: 0;
+    width: auto;
+    max-width: 100%;
+    flex-basis: min(335px, 87.7cqw);
+  }
+
+  /* The copy under the ring keeps its own height — the ring is what shrinks. */
+  .video-selfie-band--ring > .prizma-selfie-capture > :not(.prizma-selfie-capture__stage),
+  .video-selfie-band--ring > .video-selfie-turn {
+    flex-shrink: 0;
+  }
 }
 
 /* ── Recording indicator (10.1 / 11.1 / 11.3 / 11.5) ─────────────────────────
@@ -117,6 +288,20 @@
   bottom: 0;
   z-index: 3;
   padding: var(--prizma-spacing-16);
+  /* The SCRIM is full-bleed; the card is not. On a panel wider than the
+   * reference the panel keeps the host's column (`--pcs-column`, see the HUD
+   * block above) and centres, so the card stays a card instead of a 720-wide
+   * strip. Its own Spacing/16 inset is untouched, which is what keeps the
+   * reference rendering byte-identical: at 390 the column IS the panel. */
+  max-width: var(--pcs-column, none);
+  margin-inline: auto;
+}
+
+/* Core's Modal caps itself too, so on a tablet's 468 column the card has room
+ * to spare inside the panel and was landing flush left. Centre it, same as the
+ * coaching bubble. */
+.video-selfie-sheet-panel > * {
+  margin-inline: auto;
 }
 
 /* The confirmation dialog (10.4) is a true centred modal over a dimmed screen,
@@ -173,6 +358,36 @@
   height: var(--prizma-title-icon-size);
 }
 
+/* ── The tutorial's seven rows on a short panel ──────────────────────────────
+ * The promise list fits the 844 reference to the pixel — measured 497 of the
+ * 497 the column leaves — so on a 693 or 640 panel the last two rows painted
+ * through the CTA and the verified tag (Camila, 2026-10-07).
+ *
+ * The concession is the one archetype G already ships and this module already
+ * uses on its Android settings walk-through: the ROWS pan, the title, the CTA
+ * band and the anchored tag hold still (`__list--scroll`, ScreenLayout.css).
+ * It is applied here, under a container query, rather than through the
+ * `scrollList` prop, because that variant also adds a Spacing/16 margin below
+ * the list — on the reference that is 16 of the 497 the rows need, so the prop
+ * would start clipping the very screen it is meant to leave alone.
+ *
+ * 720 is the same line the live cues use: the reference is 844, and anything
+ * at 640 or 693 is a short panel. */
+@container pcs-screen (max-height: 720px) {
+  .video-selfie-tutorial .prizma-screen-layout__list {
+    overflow-y: auto;
+    /* `__list--scroll`'s own Spacing/16, so the row the clip cuts through is not
+       flush against the CTA. Inside the query it costs the reference nothing. */
+    margin-bottom: var(--prizma-spacing-16);
+  }
+
+  /* Rows keep their intrinsic height instead of being squeezed — the reason
+     `__list--scroll` carries the same declaration. */
+  .video-selfie-tutorial .prizma-screen-layout__list > * {
+    flex-shrink: 0;
+  }
+}
+
 /* ── The OS settings walk-through (2.5) ──────────────────────────────────────
  * Two labelled sections inside archetype G's list slot: a numbered step list
  * and a plain note. CONTENT typography only — the offset above the block is
@@ -348,6 +563,82 @@
   margin-block: 0 auto;
 }
 
+/* Core caps the pill itself at 400 (CaptureFeedback.css, FLAG-DOUBLE-MAXWIDTH),
+ * which is narrower than a tablet's 420 column — so inside the wrapper it has
+ * 20px to spare and was landing flush left, off the frame's centre line. Same
+ * centring `.video-selfie-stage` needs, for the same reason. */
+.video-selfie-feedback > .prizma-capture-feedback {
+  margin-inline: auto;
+}
+
+/* ── The live cues go COMPACT on a small phone ───────────────────────────────
+ * `PrizmaCaptureFeedback` ships two templates on its own `Show Animation` axis:
+ * A, the 135px pill with the illustration beside the copy at Headline/H3, and
+ * B, a 72px pill with no illustration at Headline/H5 (CaptureFeedback.css,
+ * "Compact modifier"). The module's frames draw A, and A is what every screen
+ * with room keeps.
+ *
+ * It is the wrong template on a small phone. At 320 the pill's 70px
+ * illustration column plus its Spacing/16 gap take 86 of the 272 the content
+ * has — a third of the width spent on a decoration — so "Center your ID inside
+ * the frame" wrapped to three lines and the pill grew to 150; on the 640-tall
+ * panel the same pill is a quarter of the whole screen. Either way it ate the
+ * air the document frame needs, and the frame came down through it (Camila,
+ * 2026-10-07: "in smaller phones, the live cues should change to the compact
+ * version"). Template B says the same two lines in 72.
+ *
+ * A CONTAINER query, and in the SCREENS layer rather than CaptureFeedback.css,
+ * for the reason `ScreenLayout.css` gives on the capture notice: Core web
+ * components are width-agnostic by design, and the browser viewport is not the
+ * phone — in Core Lab a 320 shell sits inside a 1400px window, so `@media`
+ * would read the wrong number. `pcs-screen` is the shell's own container
+ * (ScreenShell.css).
+ *
+ * Two triggers, because two different things run out:
+ *   · 340 wide — the line above the narrowest phone we support and below the
+ *     next one, the same threshold the capture notice drops its glyph at: 320
+ *     goes compact, 360 and 390 keep the illustration.
+ *   · 720 tall — the reference is 844 and the frames are drawn against it. A
+ *     panel at 640 or 693 has no air to spend on a 135px pill, however wide it
+ *     is. 720 clears 844, 932 and the tablet's 1024.
+ *
+ * Nothing is re-skinned: the pill's fill, radius, stroke and shadow are Core's
+ * and identical between A and B (capture-feedback.md §4.4). What changes is
+ * exactly Template B's four switches. DEVIATIONS #VS-30. */
+/* ⚠ ONE `or` condition, not two comma-separated queries. A container query
+ * names its container ONCE and the conditions go in a single boolean group:
+ * `pcs-screen (a), pcs-screen (b)` parses in Chrome and is a hard error in
+ * lightningcss, so the hub's production build failed on it while the dev server
+ * was fine. Any future multi-condition query in this package wants this shape. */
+@container pcs-screen ((max-width: 340px) or (max-height: 720px)) {
+  .video-selfie-feedback .prizma-capture-feedback__illustration {
+    display: none;
+  }
+
+  /* Template B: body padding-bottom 12 → 16, itemSpacing 8 → 4. */
+  .video-selfie-feedback .prizma-capture-feedback__body {
+    padding: var(--prizma-spacing-16) 0;
+    gap: var(--prizma-spacing-4);
+  }
+
+  /* Title Headline/H3 → Headline/H5. */
+  .video-selfie-feedback .prizma-capture-feedback__title {
+    font-weight: var(--prizma-headline-h5-font-weight);
+    font-size: var(--prizma-headline-h5-font-size);
+    line-height: var(--prizma-headline-h5-line-height);
+    letter-spacing: var(--prizma-headline-h5-letter-spacing);
+  }
+
+  /* Subtitle Headline/H5 → Body/M Regular. */
+  .video-selfie-feedback .prizma-capture-feedback__subtitle {
+    font-family: var(--prizma-body-family);
+    font-weight: var(--prizma-body-m-regular-font-weight);
+    font-size: var(--prizma-body-m-regular-font-size);
+    line-height: var(--prizma-body-m-regular-line-height);
+    letter-spacing: var(--prizma-body-m-regular-letter-spacing);
+  }
+}
+
 /* ── The head-turn mark and its instruction ──────────────────────────────────
  * The `🙂‍↔️ Turn Head` band puts a 48 circled arrow between the ring and the
  * line that says which way to turn (`element container` 342×48, the glyph
@@ -375,6 +666,17 @@
   color: var(--prizma-icon-neutral-50-static);
 }
 
+/* The mark NEVER mirrors in a right-to-left locale (owner decision, Sofia
+ * 2026-10-07). A head turn is a physical direction, not a reading direction,
+ * so "left" stays left in Hebrew too. Core flips the horizontal chevrons in
+ * RTL through `[dir="rtl"] .prizma-icon--rtl-mirror` (Navigation.css); this
+ * rule, the same selector scoped to the mark, outranks it on this screen only
+ * and every other chevron keeps mirroring. The solid circle arrows the mark
+ * used to be never flipped, so this restores their behaviour. */
+[dir='rtl'] .video-selfie-turn__mark .prizma-icon--rtl-mirror {
+  transform: none;
+}
+
 /* Step rows — the <ol> `PrizmaList` would supply, composed here only because
  * the wrapper has no variant reaching Core's plain `number` squircle (#VS-16).
  * The gap is the icon family's own Spacing/12; nothing new is declared. */

package/src/VideoSelfieSelfieCaptureScreen.tsx

@@ -126,7 +126,15 @@ export const VideoSelfieSelfieCaptureScreen = forwardRef<
       state === 'start' ? (feedback ? slice.feedback[feedback] : slice.startLabel) : undefined;
 
     return (
-      <PrizmaScreenShell ref={ref} dark className={className} {...shell}>
+      <PrizmaScreenShell
+        ref={ref}
+        dark
+        /* The camera owns the whole window, never a column of it — see the
+           contract note in `VideoSelfieLayout.css`. */
+        data-pcs-overlay="window"
+        className={className}
+        {...shell}
+      >
         <div className="prizma-viewfinder__surface">{camera}</div>
         <div className="video-selfie-stepper">
           <PrizmaStepper

package/src/VideoSelfieSpeakScreen.tsx

@@ -178,7 +178,15 @@ export const VideoSelfieSpeakScreen = forwardRef<
     );
 
     return (
-      <PrizmaScreenShell ref={ref} dark className={className} {...shell}>
+      <PrizmaScreenShell
+        ref={ref}
+        dark
+        /* The camera owns the whole window, never a column of it — see the
+           contract note in `VideoSelfieLayout.css`. */
+        data-pcs-overlay="window"
+        className={className}
+        {...shell}
+      >
         <div className="prizma-viewfinder__surface">{camera}</div>
         <div className="video-selfie-stepper">
           <PrizmaStepper

package/src/VideoSelfieStrings.ts

@@ -289,7 +289,9 @@ export interface VideoSelfieStrings {
     stepError: { title: string; ctaLabel: string };
     /** `14.3` — the whole module blew up. */
     moduleError: { title: string; ctaLabel: string; quitLabel: string };
-    /** `14.4` — connectivity. */
-    noConnection: { title: string; ctaLabel: string; quitLabel: string };
+    /** `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/src/VideoSelfieTurnHeadScreen.tsx

@@ -1,9 +1,9 @@
 import React, { forwardRef, type ReactNode } from 'react';
 import {
-  IconArrowDownCircle,
-  IconArrowLeftCircle,
-  IconArrowRightCircle,
-  IconArrowUpCircle,
+  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';
@@ -26,17 +26,20 @@ export type VideoSelfieTurnStage = 'ask' | 'done';
  * 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).
  *
- * It is ONE glyph, a filled disc with the arrow knocked out of it, which is
- * what `Left Circle - Iconly Pro` is. The first pass paired a 24px bare arrow
- * with a hand-made disc behind it and read as a thin chevron floating on the
- * camera (owner, 2026-09-30). The four circle arrows were extracted into the
- * bank on the same day. Nothing is drawn here (§10).
+ * 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: Record<VideoSelfieTurnDirection, ReactNode> = {
-  left: <IconArrowLeftCircle size="2xl" />,
-  right: <IconArrowRightCircle size="2xl" />,
-  up: <IconArrowUpCircle size="2xl" />,
-  down: <IconArrowDownCircle size="2xl" />,
+  left: <IconChevronLeft size="2xl" />,
+  right: <IconChevronRight size="2xl" />,
+  up: <IconChevronUp size="2xl" />,
+  down: <IconChevronDown size="2xl" />,
 };
 
 export interface VideoSelfieTurnHeadScreenProps
@@ -99,7 +102,15 @@ export const VideoSelfieTurnHeadScreen = forwardRef<
     },
     ref,
   ) => (
-    <PrizmaScreenShell ref={ref} dark className={className} {...shell}>
+    <PrizmaScreenShell
+      ref={ref}
+      dark
+      /* The camera owns the whole window, never a column of it — see the
+         contract note in `VideoSelfieLayout.css`. */
+      data-pcs-overlay="window"
+      className={className}
+      {...shell}
+    >
       <div className="prizma-viewfinder__surface">{camera}</div>
       <div className="video-selfie-stepper">
         <PrizmaStepper

package/src/VideoSelfieTutorialScreen.tsx

@@ -18,6 +18,7 @@ import type {
   VideoSelfieTutorialRowKind,
 } from './VideoSelfieStrings';
 import './ScreenLayout.css';
+import './VideoSelfieLayout.css';
 
 /**
  * Journey beat → canonical bank glyph. ONE map, in one place — the same seven
@@ -78,6 +79,14 @@ export interface VideoSelfieTutorialScreenProps
  * 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<
   HTMLDivElement,
@@ -90,12 +99,14 @@ export const VideoSelfieTutorialScreen = forwardRef<
       screenId = `video-selfie-tutorial-${documentType}`,
       overrides,
       onAction,
+      className,
       ...shell
     },
     ref,
   ) => (
     <PrizmaListScreen
       ref={ref}
+      className={['video-selfie-tutorial', className].filter(Boolean).join(' ')}
       title={strings.tutorial.title}
       subtitle={strings.tutorial.subtitle}
       ctaLabel={strings.tutorial.ctaLabel}

package/src/VideoSelfieWaveScreen.tsx

@@ -75,7 +75,15 @@ export const VideoSelfieWaveScreen = forwardRef<HTMLDivElement, VideoSelfieWaveS
     const seen = stage === 'success';
 
     return (
-      <PrizmaScreenShell ref={ref} dark className={className} {...shell}>
+      <PrizmaScreenShell
+        ref={ref}
+        dark
+        /* The camera owns the whole window, never a column of it — see the
+           contract note in `VideoSelfieLayout.css`. */
+        data-pcs-overlay="window"
+        className={className}
+        {...shell}
+      >
         <div className="prizma-viewfinder__surface">{camera}</div>
         <div className="video-selfie-stepper">
           <PrizmaStepper

package/src/ViewfinderScreen.css

@@ -13,6 +13,42 @@
   object-fit: cover;
 }
 
+/* ── A feed has an ASPECT, and the plate has to match it ─────────────────────
+ * `object-fit: cover` is right for a live feed and wrong for a still: a phone
+ * plate is 390 x 844, and covering a 1440 x 820 browser window scales it 3.7x,
+ * so the subject fills the window and her face lands nowhere near the capture
+ * ring (Camila, 2026-10-09: "the image is now too zoomed in because full screen
+ * is not good for this image ratio"). A real desktop webcam does not hand the
+ * page a portrait frame; it hands it a landscape one.
+ *
+ * So the HOST may supply two plates and the viewfinder picks the one whose
+ * shape fits the shell it is actually being drawn at:
+ *
+ *   <div className="prizma-viewfinder__surface">
+ *     <img data-pcs-plate="tall" src={portrait} alt="" />
+ *     <img data-pcs-plate="wide" src={landscape} alt="" />
+ *   </div>
+ *
+ * Supply one and nothing changes — an untagged `<img>` or `<video>` is shown at
+ * every shape, which is every existing caller. A CONTAINER query, not a media
+ * one, for the reason `ScreenLayout.css` gives on the capture notice: the
+ * browser viewport is not the screen, and in Core Lab a 390 shell sits inside a
+ * 1400px window. The line is square: anything wider than it is tall takes the
+ * landscape plate. */
+.prizma-viewfinder__surface > [data-pcs-plate='wide'] {
+  display: none;
+}
+
+@container pcs-screen (min-aspect-ratio: 1 / 1) {
+  .prizma-viewfinder__surface > [data-pcs-plate='tall'] {
+    display: none;
+  }
+
+  .prizma-viewfinder__surface > [data-pcs-plate='wide'] {
+    display: block;
+  }
+}
+
 .prizma-viewfinder__content {
   position: relative;
   z-index: 1;

package/src/flows.ts

@@ -83,6 +83,10 @@ export interface FaceCaptureFlowVariant {
   ctaLoading?: boolean;
   /** FaceCaptureCapturingScreen — which of the 15 `capturing.*` sections. */
   state?: FaceCaptureCapturingState;
+  /** FaceCaptureCapturingScreen — raise the "Need more time?" offer over the
+   *  feed. A modifier of `state`, not one of the fifteen: the fallback timer
+   *  runs underneath whichever guidance is showing. */
+  extendTime?: boolean;
   /** FaceCaptureLoadingScreen — `loading.uploading` vs `loading.processing`. */
   stage?: 'uploading' | 'processing';
   /** FaceCaptureResultErrorScreen — the `*Exhausted` half of the error pairs. */
@@ -140,6 +144,14 @@ export const faceCaptureFlow: readonly FaceCaptureFlowStep[] = [
 /** The off-path screens: manual capture (offered when auto-capture is turned
  *  off or gives up), the two error verdicts, and the connectivity error. */
 export const faceCaptureBranches: readonly FaceCaptureFlowStep[] = [
+  {
+    // A branch, not a step: it only appears when accessibility mode is ON for
+    // the flow AND the fallback timer is 20 s from expiring. It returns to the
+    // capturing states it came from, so it never "follows" anything.
+    screenId: 'face-capture-capturing-extend-time',
+    component: FaceCaptureCapturingScreen,
+    variant: { state: 'alignFace', extendTime: true },
+  },
   {
     screenId: 'face-capture-manual-capture',
     component: FaceCaptureManualCaptureScreen,
@@ -479,6 +491,10 @@ export interface IdCaptureFlowVariant {
   vertical?: boolean;
   /** IdCaptureStageScreen — which stage section. */
   state?: IdCaptureStageState;
+  /** IdCaptureStageScreen — raise the "Need more time?" offer over the feed.
+   *  A modifier of `state`, not one of the eleven: the fallback timer runs
+   *  underneath whichever stage is showing. */
+  extendTime?: boolean;
   /** IdCaptureStageScreen — the `*-manual` sections. */
   manual?: boolean;
   /** IdCaptureResultScreen — which verdict section. */
@@ -633,6 +649,15 @@ export const idCaptureBranches: readonly IdCaptureFlowStep[] = [
     screenId: 'id-capture-age-verification',
     component: IdCaptureAgeVerificationScreen,
   },
+  {
+    // A branch, not a step: it only appears when accessibility mode is ON for
+    // the flow AND the 30 s fallback timer is 20 s from expiring. It returns
+    // to the hint stage it came from, so it never "follows" anything — the
+    // same shape as Face Capture's `capturing-extend-time`.
+    screenId: 'id-capture-front-extend-time',
+    component: IdCaptureStageScreen,
+    variant: { state: 'hint', extendTime: true },
+  },
   {
     screenId: 'id-capture-front-manual',
     component: IdCaptureStageScreen,