@incodetech/prizma-core-screens 0.2.7 → 0.2.12

package/src/FaceCaptureCapturingScreen.tsx

@@ -1,5 +1,6 @@
 import React, { forwardRef, type ReactNode } from 'react';
 import type { PrizmaSelfieCaptureState } from '@incodetech/prizma-core-web/selfie-capture';
+import { PrizmaSnackbar } from '@incodetech/prizma-core-web/snackbar';
 import { PrizmaCaptureScreen, type PrizmaCaptureScreenProps } from './CaptureScreen';
 import type {
   FaceCaptureCapturingState,
@@ -46,6 +47,19 @@ export interface FaceCaptureCapturingScreenProps
   state?: FaceCaptureCapturingState;
   /** Live camera feed (<video>) or sample still (<img>) for the ring window. */
   camera?: ReactNode;
+  /**
+   * Raise the "Need more time?" offer over the feed — the accessibility
+   * notification shown 20 s before auto capture falls back to manual.
+   *
+   * It is a MODIFIER of whatever capturing state is already on screen, not a
+   * sixteenth state: the timer runs underneath the guidance, so the user can be
+   * told to move closer and offered more time in the same frame. Needs
+   * `strings.extendTime`; without it the flag is a no-op, which is what a host
+   * that has not localized the copy should get rather than English.
+   */
+  extendTime?: boolean;
+  /** Tapping "Extend auto-capture". The host resets its own fallback timer. */
+  onExtendTime?: () => void;
 }
 
 /**
@@ -65,6 +79,56 @@ export interface FaceCaptureCapturingScreenProps
  *
  * The archetype adds no offsets of its own — the component owns that spacing
  * (same deviation row).
+ *
+ * ── The "Need more time?" offer (`extendTime`) ──────────────────────────────
+ *
+ * Auto capture gives up after a configured timeout and drops the user into
+ * manual capture. Someone who is struggling — a tremor, low vision, bad light,
+ * an unfamiliar phone — gets moved off the EASIER path precisely because they
+ * were slow, which is backwards. So 20 s before the switch, the screen offers
+ * to stay on auto. A client turns it on per flow from the dashboard; with it
+ * off, nothing about today's capture changes.
+ *
+ * NOT a nicety — it is the conformance route for WCAG 2.2.1 Timing Adjustable
+ * via the *Extend* clause (warn before the limit, ≥20 s to act, ≥10 extensions).
+ * Two things follow that the visuals cannot settle: the notice must be able to
+ * come back ten times, and it must be ANNOUNCED early enough to be acted on.
+ *
+ * ── Live-region politeness: `role="alert"`, not the default ────────────────
+ *
+ * SETTLED 2026-10-05 (Camila). The Snackbar computes `role="status"` (polite)
+ * for every state but error, and this instance overrides it to `alert`.
+ *
+ * A polite region is allowed to wait until the screen reader finishes whatever
+ * it is already saying — and on this screen it always IS saying something: the
+ * capture instruction under the ring changes as the face moves, so the queue
+ * is rarely empty. The offer has a 20 s life. Queued behind two or three
+ * guidance announcements it can be read out after it has already expired,
+ * which turns the one affordance a struggling user needs into an
+ * announcement that the limit has passed.
+ *
+ * That is not a polish issue, it is the conformance failing: WCAG 2.2.1's
+ * Extend clause requires the warning to be given in time to ACT on it. An
+ * announcement the user cannot act on does not satisfy it, however correct the
+ * visuals. `alert` is assertive, so it interrupts the guidance and is heard
+ * while the 20 s is still running.
+ *
+ * The usual objection to `alert` is that interrupting is rude. It applies to
+ * notices that can wait; this one cannot, and it is strictly better to
+ * interrupt "Move closer" than to let the window close in silence. It is also
+ * why the offer must not be re-raised on a timer — each new `alert` interrupts
+ * again. It appears once per countdown, and WCAG allows that up to ten times.
+ *
+ * ⚠ NEW, not yet authored in Core. Two parts of this notice have no Figma
+ * variant behind them and are drawn from the exploration, not from the SoT:
+ *   • the bold title line — the Snackbar has no `title` slot, so it rides
+ *     inside `children` as a <strong>. Core to decide whether to adopt a real
+ *     slot, at which point this moves onto it.
+ *   • the state — it is `neutral` (blue surface, ⓘ glyph), Camila's call
+ *     2026-10-05. `warning` would signal attention more sharply but turns the
+ *     surface amber, and the exploration's open question is whether amber
+ *     reads as "hurry up" to someone who was already struggling. The icon
+ *     cannot be chosen independently: `ICON_BY_STATE` binds it to `state`.
  */
 export const FaceCaptureCapturingScreen = forwardRef<
   HTMLDivElement,
@@ -75,24 +139,49 @@ export const FaceCaptureCapturingScreen = forwardRef<
       strings,
       state = 'initiating',
       camera,
+      extendTime,
+      onExtendTime,
       screenId = 'face-capture-capturing',
       className,
       ...rest
     },
     ref,
-  ) => (
-    <PrizmaCaptureScreen
-      ref={ref}
-      className={className}
-      state={SELFIE_STATE[state]}
-      camera={camera}
-      feedbackText={strings.capturing[state]}
-      verifiedLabel={strings.verifiedLabel}
-      navLabel={strings.navLabel}
-      screenId={screenId}
-      {...rest}
-    />
-  ),
+  ) => {
+    const offer = strings.extendTime;
+    // No copy, no notice: a host that has not localized this must not get
+    // English, and the flag alone is not permission to invent it.
+    const notice =
+      extendTime && offer ? (
+        <PrizmaSnackbar
+          state="neutral"
+          isMultiline
+          // Assertive on purpose — see the live-region note in this file's
+          // header. The component default here would be `status`.
+          role="alert"
+          linkLabel={offer.linkLabel}
+          onLinkClick={onExtendTime}
+        >
+          <strong>{offer.title}</strong>
+          <br />
+          {offer.description}
+        </PrizmaSnackbar>
+      ) : undefined;
+
+    return (
+      <PrizmaCaptureScreen
+        ref={ref}
+        className={className}
+        state={SELFIE_STATE[state]}
+        camera={camera}
+        feedbackText={strings.capturing[state]}
+        notice={notice}
+        verifiedLabel={strings.verifiedLabel}
+        navLabel={strings.navLabel}
+        screenId={screenId}
+        {...rest}
+      />
+    );
+  },
 );
 FaceCaptureCapturingScreen.displayName = 'FaceCaptureCapturingScreen';
 

package/src/FaceCaptureLayout.css

@@ -12,7 +12,72 @@
  * inherit all three as correct defaults.
  */
 
-/* Nothing module-specific is left: the non-status glyph slot this file used to
- * own (`.face-capture-glyph`) was the third byte-identical copy of one pattern,
- * so it moved to `ScreenLayout.css` as `__glyph` — DEVIATIONS #DC-29, closed.
- * The file is kept as the module's landing place for future additions. */
+/* The non-status glyph slot this file used to own (`.face-capture-glyph`) was
+ * the third byte-identical copy of one pattern, so it moved to
+ * `ScreenLayout.css` as `__glyph` — DEVIATIONS #DC-29, closed. */
+
+/* ── Short panels: the capture stack moves up, the ring never changes size ───
+ * `PrizmaSelfieCapture` is a fixed stack by design: Spacing/40, the 335 stage,
+ * Spacing/32, the instruction, and in manual mode another Spacing/32 and the 64
+ * shutter, then Spacing/40 — 583 tall on the manual screen, every number
+ * measured off the module Figma (DEVIATIONS #12). Under the nav and above the
+ * footer's reserve a closed iPhone Duo leaves 513 (678 − 103 − 62, measured
+ * 2026-10-14), so the manual stack ran 70 past its column and the shutter
+ * landed on the verified tag (shutter 582–646, tag 606–636). The auto-capture
+ * screens are 94 shorter and fit the Duo as authored.
+ *
+ * The RING is not what gives ground. Camila, 2026-10-14: the face frame is the
+ * same size on every screen, because the user has to see their face; if it
+ * ever had to shrink it would shrink on every capture screen together, and we
+ * avoid that. So the stack moves UP instead: the root's Spacing/40 above and
+ * below go (the ring sits flush under the nav row, 40 higher than on the
+ * reference) and the two Spacing/32 gaps become Spacing/16, which on the
+ * manual screen is 112 back — 103 + 334 + 16 + 41 + 16 + 64 = 574, 32 of air
+ * above the tag. Instruction and shutter keep their height, the ring its 334.
+ *
+ * EVERY capture screen takes it, not only the manual one that needed it
+ * (Camila, 2026-10-14: "put all face frames at the height that the manual
+ * capture one is, so we don't need a jump there"). The ring not moving between
+ * screens is the rule Video Selfie's #VS-24 was written for: a capture window
+ * that jumps as the step advances reads as a glitch. So on a short panel the
+ * whole module's ring is at 103, auto, manual, loading and verdict alike.
+ * Outside the query not one declaration exists, so the reference is
+ * byte-identical. DEVIATIONS #20. */
+@container pcs-screen (max-height: 720px) {
+  .prizma-screen-layout__content--capture > .prizma-selfie-capture {
+    padding-block: 0;
+    gap: var(--prizma-spacing-16);
+  }
+}
+
+/* ── Big panels: the ring grows to the column and the stack moves down ───────
+ * The mirror of the block above, and the capture counterpart of the tutorial's
+ * #F-36. On the 768 × 1024 iPad the column widens to 468 but the stack kept
+ * its 335 ring flush under the nav, so the ring read small (335 in a 420
+ * content column, 85px of air either side) and high (its centre at 30% of the
+ * panel, where the 390 phone has it at 37%), with 300px of empty column under
+ * the instruction (Camila, 2026-10-19: "the face frame too small and way up
+ * the screen", on the tablet flow, grid and screen view alike).
+ *
+ * Two owner decisions, 2026-10-20. The RING GROWS: the 2026-10-14 rule that
+ * the ring never changes size was written so it would not SHRINK on a short
+ * panel, and on a panel this big the person's face is still what the screen is
+ * about, so the stage takes the content column's full measure (420 inside the
+ * 468 wide column), the way #F-36 lets the tutorial art grow. Every state
+ * grows together (auto, manual, loading, verdict) so the ring still never
+ * jumps between steps. The STACK MOVES DOWN BY A FIXED OFFSET, not to the
+ * centre: the stack under the ring is a different height on every screen
+ * (the manual one carries the shutter), so centring THAT would move the ring
+ * between steps, the bug #VS-24 exists for; the same reason Video Selfie's
+ * #VS-32 took an offset. Spacing/40 + Spacing/32 above the ring puts its
+ * centre at 102 + 72 + 210 = 384, 37.5% of 1024, the reference's own
+ * proportion (measured 2026-10-20); the manual screen's shutter ends at 765
+ * with the verified tag at 978. Both axes gate it for #F-36's reasons: `min-height: 845px` keeps the
+ * 844 reference and every short panel byte-identical, `min-width: 468px` keeps
+ * it off phones and foldables where the column stays 390. DEVIATIONS #21. */
+@container pcs-screen ((min-height: 845px) and (min-width: 468px)) {
+  .prizma-screen-layout__content--capture > .prizma-selfie-capture {
+    max-width: 100%;
+    padding-top: calc(var(--prizma-spacing-40) + var(--prizma-spacing-32));
+  }
+}

package/src/FaceCaptureStrings.ts

@@ -56,6 +56,30 @@ export interface FaceCaptureStrings {
    *  `initiating` has no instruction in the design; omit it. */
   capturing: Partial<Record<FaceCaptureCapturingState, string>>;
 
+  /**
+   * faceCapture.capturing.extendTime — the accessibility offer that rides any
+   * capturing state 20 s before auto capture falls back to manual.
+   *
+   * It exists for WCAG 2.2.1 Timing Adjustable, satisfied through the *Extend*
+   * clause: warn before the limit expires, give the user at least 20 s to
+   * extend with a simple action, and let them extend at least ten times. The
+   * 20 s is that threshold, not a chosen duration — which is why `description`
+   * is a whole string and not a number the screen formats: ten locales write
+   * that sentence ten different ways, and the count has to live inside it.
+   *
+   * Shown only when accessibility mode is ON for the flow (a per-flow
+   * dashboard setting). With it off, nothing about today's capture changes.
+   * Optional for that reason: a host that never turns it on never writes it.
+   */
+  extendTime?: {
+    /** Bold first line — "Need more time?" */
+    title: string;
+    /** "Manual capture starts in 20 s" — carries the count, see above. */
+    description: string;
+    /** The action that keeps the user on auto — "Extend auto-capture". */
+    linkLabel: string;
+  };
+
   /** faceCapture.manualCapture.default */
   manualCapture: {
     /** "Align your face within the silhouette and press the button to capture" */

package/src/FormScreen.css

@@ -29,6 +29,20 @@
   padding-top: var(--pfs-fields-offset, var(--prizma-spacing-32));
 }
 
+/* ── Field stack pinned to the CTA band ──────────────────────────────────────
+ * `fieldsAlign="end"` on `PrizmaFormScreen`. The stack keeps its `flex: 1`
+ * column and simply packs its rows at the bottom, so the space between the
+ * title block and the first row is what is left over rather than a value
+ * anybody declares. The `margin-bottom` is the frame's own Spacing/16 between
+ * the card and the Button group (`biometricConsent.empty`, 2001:16361 — the
+ * CONTENT column's gap), the same value the scrolling stack uses for the same
+ * seam, so the two shapes agree on how far a row sits from Continue. Biometric
+ * Consent is the first consumer. DEVIATIONS #BC-1. */
+.prizma-form-screen__fields--end {
+  justify-content: flex-end;
+  margin-bottom: var(--prizma-spacing-16);
+}
+
 /* ── Scrolling field stack ───────────────────────────────────────────────────
  * Screens are authored at 390×844 and never reflow (DEVIATIONS #17), but some
  * Form sections draw a middle column taller than the frame and let it pan:

package/src/FormScreen.tsx

@@ -62,6 +62,13 @@ export interface PrizmaFormScreenProps
    * body text.
    */
   linkLabel?: string;
+  /**
+   * Renders `linkLabel` in Core's disabled treatment, for a link that exists
+   * but cannot be pressed yet — Phone Input's "Resend code in 30s" while the
+   * resend timer runs (Figma `phoneNumber.OTP.typing`, Tertiary / Link ·
+   * Disabled).
+   */
+  linkDisabled?: boolean;
   /**
    * A composed line below the primary: body copy with inline links, e.g. Phone
    * Input's "Didn't receive the code? **Resend code** or **Change phone
@@ -98,6 +105,27 @@ export interface PrizmaFormScreenProps
    * eKYB, Data Sharing Consent); it is the archetype's now. DEVIATIONS #DSC-2.
    */
   scrollFields?: boolean;
+  /**
+   * Where the field stack sits in the column when it is SHORTER than the
+   * space it has. `start` (the default) hangs it off the title block, which is
+   * every form so far. `end` pins it to the CTA band instead, leaving the space
+   * between the title and the stack empty — Biometric Consent's section draws
+   * exactly that: a `justify-between` middle with the Title at the top and the
+   * one consent card flush against Continue, Spacing/16 above it
+   * (`biometricConsent.empty`, 2001:16361). Selected here so the module
+   * declares no layout of its own; the rule lives once in `FormScreen.css`.
+   * DEVIATIONS #BC-1.
+   */
+  fieldsAlign?: 'start' | 'end';
+  /**
+   * A shell-level layer painted OVER the whole screen — the same slot archetype
+   * A carries for Document Capture's method sheet (#F-32, #DC-30): a scrim plus
+   * Core's `PrizmaBottomSheetContent` or `PrizmaModalContent`, presented on top
+   * of the dimmed form. It cannot ride in the content column: it is absolutely
+   * positioned against the shell. Biometric Consent's quit confirmation is the
+   * first Form consumer (DEVIATIONS #BC-8).
+   */
+  overlay?: ReactNode;
   /**
    * Let the field stack change SHAPE on a wide screen: `PrizmaFormRow` pairs
    * become two lanes and Continue + Back share a row, once the shell's own
@@ -140,12 +168,15 @@ export const PrizmaFormScreen = forwardRef<HTMLDivElement, PrizmaFormScreenProps
       ctaLoading = false,
       ctaLoadingLabel,
       linkLabel,
+      linkDisabled,
       linkContent,
       verifiedLabel,
       children,
       fieldsOffset,
       fieldsGap,
       scrollFields = false,
+      fieldsAlign = 'start',
+      overlay,
       responsive = false,
       navLabel,
       screenId,
@@ -179,6 +210,7 @@ export const PrizmaFormScreen = forwardRef<HTMLDivElement, PrizmaFormScreenProps
           className={[
             'prizma-form-screen__fields',
             scrollFields ? 'prizma-form-screen__fields--scroll' : null,
+            fieldsAlign === 'end' ? 'prizma-form-screen__fields--end' : null,
           ]
             .filter(Boolean)
             .join(' ')}
@@ -217,6 +249,7 @@ export const PrizmaFormScreen = forwardRef<HTMLDivElement, PrizmaFormScreenProps
               <PrizmaButton
                 variant="tertiary-link"
                 size="L"
+                disabled={linkDisabled}
                 onClick={() => onAction?.({ type: 'secondary', screenId })}
               >
                 {linkLabel}
@@ -231,6 +264,7 @@ export const PrizmaFormScreen = forwardRef<HTMLDivElement, PrizmaFormScreenProps
           </div>
         ) : null}
       </div>
+      {overlay}
     </PrizmaScreenShell>
   ),
 );

package/src/IdCaptureLayout.css

@@ -99,12 +99,89 @@
   flex-basis: calc((100cqw - 2 * var(--prizma-spacing-24)) * 420 / 306);
 }
 
+/* ── A notice on the stage: the horizontal frame may give up height too ──────
+ * The "Need more time?" offer (`.id-capture-stage__notice`, IDC-32) adds ~90px
+ * of content to the bottom band. On the 390 × 844 reference the band has the
+ * room and nothing moves. On a short panel it does not: measured 2026-10-15,
+ * the horizontal ID frame is aspect-locked and does not shrink, so the column
+ * overflowed and the notice ran 10px into the help strip at 320 × 693 and 36px
+ * at the closed iPhone Duo (466 × 678). The same recipe as the vertical rule
+ * above, applied to the horizontal frames ONLY while a notice is on the stage:
+ * the frame starts at its full-width height and gives up height when the
+ * column is short, the aspect ratio narrows it to match, the title band keeps
+ * its content height. Face Capture makes the identical trade at 320 (its
+ * selfie frame gives up Spacing/40 for the notice, ScreenLayout.css) and the
+ * owner's rule is explicit that the frame may get smaller (2026-08-18). A
+ * stage without a notice is untouched. */
+.prizma-viewfinder__content:has(> .id-capture-band > .id-capture-stage__notice) {
+  min-height: 0;
+}
+.prizma-viewfinder__content:has(> .id-capture-band > .id-capture-stage__notice) > .id-capture-band--top {
+  flex-shrink: 0;
+  min-height: min-content;
+}
+.prizma-viewfinder__content:has(> .id-capture-band > .id-capture-stage__notice) > .prizma-id-capture--horizontal:not(.prizma-id-capture--poa) {
+  flex: 0 1 auto;
+  min-height: 0;
+}
+.prizma-viewfinder__content:has(> .id-capture-band > .id-capture-stage__notice) > .prizma-id-capture--horizontal:not(.prizma-id-capture--poa) .prizma-id-capture__frame {
+  flex: 0 1 auto;
+  min-height: 0;
+  width: auto;
+  max-width: 100%;
+  flex-basis: calc((100cqw - 2 * var(--prizma-spacing-24)) * 220 / 350);
+}
+.prizma-viewfinder__content:has(> .id-capture-band > .id-capture-stage__notice) > .prizma-id-capture--passport.prizma-id-capture--horizontal .prizma-id-capture__frame {
+  flex-basis: calc((100cqw - 2 * var(--prizma-spacing-24)) * 254 / 350);
+}
+
+/* ── Short panels: the tutorial art is sized by its halo, not its canvas ─────
+ * `PrizmaIllustrationIdTutorial` is a 342 × 392 canvas with the halo centred
+ * at r130 (y 66–326) and the hand-and-document artwork inside it (y 100–313;
+ * the passport's hand fades out above). The 66 above and below the halo are
+ * air at rest; the bottom band is where the hand travels in from during the
+ * loop. The selfie illustration is a 296 canvas with the same r130 halo and 18
+ * of air: on the 844 reference both halos are 260 and the two tutorials match.
+ *
+ * On a short panel the tutorial middle is height-limited (ScreenLayout.css,
+ * #F-35) and the two canvases scale by height, so the ID halo comes out 18 %
+ * smaller than the selfie's (170 vs 209 on the closed iPhone Duo, measured
+ * 2026-10-14; Camila: "ID tutorials have illustration a bit too small, no?
+ * Compared to the size on the selfie tutorial one"). Fixed by cropping the
+ * canvas to the halo band plus Spacing/16 on each side — y 50 to 342, 292
+ * units, the same 89 % the selfie's halo takes of its own box — so the halo
+ * fills the slot the way the selfie's does. The wrapper takes the slot and
+ * clips; the svg is scaled so 292 of its 392 units fill the wrapper and
+ * centres, so the crop is symmetric around the halo and the halo's centre
+ * does not move. During the loop the entering hand is clipped 50 units
+ * earlier than the canvas clips it, which is invisible against the fade.
+ * Outside the query nothing exists: the reference renders the full canvas.
+ * DEVIATIONS #IDC-31. */
+@container pcs-screen (max-height: 720px) {
+  .prizma-screen-layout__flex > .prizma-illustration-tutorial {
+    flex: 1 1 0;
+    min-height: 0;
+    align-self: stretch;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    overflow: hidden;
+  }
+
+  .prizma-screen-layout__flex > .prizma-illustration-tutorial > svg {
+    flex: none;
+    height: calc(100% * 392 / 292);
+    width: auto;
+    max-width: none;
+  }
+}
+
 /* ── Camera stage (dark) ───────────────────────────────────────────────────── */
 
 /* The stage's nav row carries only the close X (no logo — the camera owns the
  * screen). The foundation `.prizma-screen-nav` supplies the status-bar reserve,
  * the 44px flow slot and the un-fixing of Core's PrizmaNavigation; the ink is
- * the only thing the camera stage changes: Core's nav icon is the THEMED
+ * the only thing the camera stage changes: Core's nav icon is the themed
  * `Icon/Neutral/500`, which disappears on the always-dark camera surface, so it
  * takes the camera's own Static ink — the same token PrizmaCaptureManual uses
  * for the shutter and the "?" help control. DEVIATIONS.md #IDC-21. */
@@ -118,6 +195,44 @@
   width: 100%;
 }
 
+/* ── The "Need more time?" notice ─────────────────────────────────────────────
+ * The Snackbar the stage raises 20 s before auto-capture falls back to the
+ * shutter (IdCaptureStageScreen `extendTime`, 2026-10-15). It takes the BOTTOM
+ * band — the air between the encrypted row and the strip's reserved space —
+ * because, unlike Face Capture, this stage's strip is never empty: the "?" help
+ * control rides it on every stage (IDC-29), so the shared rail the selfie notice
+ * uses (`.prizma-screen-layout__capture-notice`) would land on top of it.
+ *
+ * The band is `justify-content: flex-end`, so the notice sits just above the
+ * strip's Spacing/12 of breathing and the frame above does not move when the
+ * offer arrives. The band is also `flex: 1; min-height: 0`, which on a short
+ * panel would let it shrink to nothing and spill the notice upward over the
+ * encrypted row; with a notice in it the band keeps its content height and the
+ * shortfall goes where this stylesheet already sends it — the vertical frame
+ * (the short-panel rule above), which the owner has said may get smaller
+ * (2026-08-18). DEVIATIONS #IDC-32. */
+.id-capture-band:has(> .id-capture-stage__notice) {
+  flex-shrink: 0;
+  min-height: min-content;
+  padding-top: var(--prizma-spacing-16);
+}
+
+.id-capture-stage__notice {
+  display: flex;
+  /* The HUD column centres its copy; the Snackbar's own text is left-set. */
+  text-align: left;
+}
+
+/* On a 320 phone the notice drops its status glyph — the same call Face
+ * Capture made (Camila, 2026-10-05, ScreenLayout.css): 44 of the 272px column
+ * on a decorative mark pushed the body to four lines. The icon is
+ * `aria-hidden`; the copy carries the meaning without it. */
+@container pcs-screen (max-width: 340px) {
+  .id-capture-stage__notice .prizma-snackbar__icon {
+    display: none;
+  }
+}
+
 /* The feedback pill replaces the title block on the error stages (Figma
  * `1-5-5 … 1-5-9-id-errors`): same band, same Spacing/40 above the frame. */
 .id-capture-stage__feedback {
@@ -125,6 +240,54 @@
   justify-content: center;
 }
 
+/* ── Short or narrow panels: the live cue takes Template B ───────────────────
+ * `PrizmaCaptureFeedback` ships two templates on its `showAnimation` axis:
+ * A, the 120-ish pill with the illustration and a Headline/H3 title, and B, a
+ * 72 pill with no illustration and Headline/H5. The error stages draw A on the
+ * 390 × 844 reference. On a closed iPhone Duo (678) A still fits — measured
+ * 2026-10-14, the frame lands at 198–473 with the pill above it — but it is
+ * the tallest element on a stage that has just lost 166px, and on a 640 phone
+ * or a 320 column it does not fit at all. Video Selfie already made this call
+ * for its own cues (DEVIATIONS #VS-30, Camila 2026-10-07): under 340 wide or
+ * 720 tall the pill is B. The same line here, so the two camera modules agree
+ * on when a cue goes compact. Nothing is re-skinned: 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, taken from
+ * `CaptureFeedback.css`'s own `--compact` modifier.
+ *
+ * A container query, not the prop: the screen cannot know the panel's height,
+ * the shell's `pcs-screen` container can. ONE `or` condition, not two
+ * comma-separated queries (lightningcss rejects the latter; see
+ * VideoSelfieLayout.css). The 390 reference is unchanged. DEVIATIONS #IDC-30. */
+@container pcs-screen ((max-width: 340px) or (max-height: 720px)) {
+  .id-capture-stage__feedback .prizma-capture-feedback__illustration {
+    display: none;
+  }
+
+  /* Template B: body padding-bottom 12 → 16, itemSpacing 8 → 4. */
+  .id-capture-stage__feedback .prizma-capture-feedback__body {
+    padding: var(--prizma-spacing-16) 0;
+    gap: var(--prizma-spacing-4);
+  }
+
+  /* Title Headline/H3 → Headline/H5. */
+  .id-capture-stage__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. */
+  .id-capture-stage__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);
+  }
+}
+
 /* ── Removed: promoted into the foundation ───────────────────────────────────
  * `.id-capture-glyph*` (the non-status glyph slot) is now
  * `ScreenLayout.css`'s `__glyph` — DEVIATIONS #DC-29, closed.
@@ -142,7 +305,7 @@
  *
  * The plate needs no override — Core's own `mode="overlay"` already makes the
  * window transparent, which is what the light screens want. The ink does: the
- * row is re-inked with the THEMED body token so it also survives dark mode,
+ * row is re-inked with the themed body token so it also survives dark mode,
  * scoped to the light screens only (the camera stage keeps Core's Static white).
  * Core gap — PrizmaIdCapture has no surface-aware encrypted row. DEVIATIONS.md #IDC-28.
  */

package/src/IdCaptureStageScreen.tsx

@@ -6,6 +6,7 @@ import {
 } from '@incodetech/prizma-core-web/id-capture';
 import { PrizmaCaptureManual } from '@incodetech/prizma-core-web/capture-manual';
 import { PrizmaCaptureFeedback } from '@incodetech/prizma-core-web/capture-feedback';
+import { PrizmaSnackbar } from '@incodetech/prizma-core-web/snackbar';
 import { PrizmaTag } from '@incodetech/prizma-core-web/tag';
 import { PrizmaScreenShell, type PrizmaScreenShellProps } from './ScreenShell';
 import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
@@ -80,6 +81,28 @@ export interface IdCaptureStageScreenProps
   still?: ReactNode;
   /** Digit shown by the countdown Timer (`*-countdown` sections 1..3). */
   countdownValue?: 1 | 2 | 3;
+  /**
+   * Raise the "Need more time?" offer over the feed — the accessibility
+   * notification shown 20 s before auto-capture falls back to the shutter.
+   *
+   * A MODIFIER of whatever stage state is already showing, not a twelfth
+   * state: the 30 s fallback timer runs underneath the hint overlay, so the
+   * person can be shown the hand-and-document ghost and offered more time in
+   * the same frame. Needs `strings.stage.extendTime`; without it the flag is a
+   * no-op, which is what a host that has not localized the copy should get
+   * rather than English. Same contract as `FaceCaptureCapturingScreen`.
+   */
+  extendTime?: boolean;
+  /** Tapping "Extend auto-capture". The host resets its own fallback timer. */
+  onExtendTime?: () => void;
+  /**
+   * A notice band of the host's own, in the slot `extendTime` uses. Wins over
+   * `extendTime` when both are given. Exists for a host that needs the
+   * Snackbar to do something the static one cannot — Core Lab's prototype
+   * swaps in a copy whose count actually runs down — without reaching into
+   * the screen. The static `extendTime` notice stays the default.
+   */
+  notice?: ReactNode;
   screenId?: string;
   overrides?: PrizmaScreenOverrides;
   onAction?: PrizmaScreenActionHandler;
@@ -113,6 +136,31 @@ export interface IdCaptureStageScreenProps
  * to the column's bottom padding) — no offsets are invented here, and
  * PrizmaIdCapture's own frame→encrypted-row adjacency is left untouched
  * (DEVIATIONS.md #12's lesson: never stack an offset a Core component carries).
+ *
+ * ── The "Need more time?" offer (`extendTime`) ──────────────────────────────
+ *
+ * Auto-capture gives up after a configured timeout (30 s in the module's own
+ * flow frames) and drops the person onto the shutter. Someone who is
+ * struggling — a tremor, low vision, a dark room, a card that will not sit
+ * flat — gets moved off the EASIER path precisely because they were slow,
+ * which is backwards. So 20 s before the switch, the stage offers to stay on
+ * auto. A client turns it on per flow from the dashboard; with it off, nothing
+ * about today's capture changes. It is the conformance route for WCAG 2.2.1
+ * Timing Adjustable via the *Extend* clause (warn before the limit, ≥20 s to
+ * act, ≥10 extensions) — the reasoning, the `role="alert"` decision and the
+ * `neutral` state are all Face Capture's (2026-10-05) and are not re-argued
+ * here: `FaceCaptureCapturingScreen`'s header is the record. One feature, two
+ * modules, one Snackbar.
+ *
+ * WHERE IT SITS is the one thing this module decides differently. Face
+ * Capture anchors the notice on the shutter-strip rail because, there, notice
+ * and shutter are alternatives — a capturing screen either raises the offer or
+ * shows the button. ID Capture's strip is never free: the "?" help control
+ * rides it on every stage, auto or manual (IDC-29). So the notice takes the
+ * BOTTOM BAND instead — the flexible air between the encrypted row and the
+ * strip's reserved space — which is the one slot on this stage nothing else
+ * owns. It bottom-anchors there like the band's other content would, so the
+ * frame above does not move when the offer arrives. DEVIATIONS.md #IDC-32.
  */
 export const IdCaptureStageScreen = forwardRef<HTMLDivElement, IdCaptureStageScreenProps>(
   (
@@ -128,6 +176,9 @@ export const IdCaptureStageScreen = forwardRef<HTMLDivElement, IdCaptureStageScr
       camera,
       still,
       countdownValue = 3,
+      extendTime,
+      onExtendTime,
+      notice,
       screenId = `id-capture-${documentType}-${side}-${state}`,
       overrides,
       onAction,
@@ -146,6 +197,29 @@ export const IdCaptureStageScreen = forwardRef<HTMLDivElement, IdCaptureStageScr
     const pillKind = feedback === undefined ? STAGE_FEEDBACK[state] : feedback;
     const pillCopy = pillKind ? strings.feedback[pillKind] : undefined;
 
+    const offer = strings.stage.extendTime;
+    // No copy, no notice: a host that has not localized this must not get
+    // English, and the flag alone is not permission to invent it.
+    const band =
+      notice ??
+      (extendTime && offer ? (
+        <PrizmaSnackbar
+          state="neutral"
+          isMultiline
+          // Assertive on purpose — a polite region can queue behind the
+          // stage's own state announcements and be read out after the 20 s
+          // has already run out. FaceCaptureCapturingScreen's header has the
+          // full reasoning; this instance follows it.
+          role="alert"
+          linkLabel={offer.linkLabel}
+          onLinkClick={onExtendTime}
+        >
+          <strong>{offer.title}</strong>
+          <br />
+          {offer.description}
+        </PrizmaSnackbar>
+      ) : undefined);
+
     return (
       <PrizmaScreenShell
         ref={ref}
@@ -213,6 +287,7 @@ export const IdCaptureStageScreen = forwardRef<HTMLDivElement, IdCaptureStageScr
             still={still}
           />
           <div className="id-capture-band">
+            {band ? <div className="id-capture-stage__notice">{band}</div> : null}
           </div>
         </div>
         <div className="prizma-screen-layout__capture-strip">