@incodetech/prizma-core-screens 0.2.4 → 0.2.12

package/src/EkycCountryCatalog.ts

@@ -20,7 +20,10 @@
 // Verification", and no variant draws a close in the nav; steps after the
 // first get the archetype's Back button instead of a back arrow (#EKC-2).
 
-export type EkycFieldKind = 'text' | 'date' | 'phone' | 'dropdown' | 'radio';
+/** `password`: Core's `PrizmaPassword`, the field with the eye that hides the
+ *  typed value. For the identifiers a stranger must not read over a shoulder:
+ *  the SSN / ITIN fields (Elena, 2026-09-28). No requirement checklist. */
+export type EkycFieldKind = 'text' | 'date' | 'phone' | 'dropdown' | 'radio' | 'password';
 
 export type EkycFieldKey =
   | 'firstName' | 'middleName' | 'middleNameOptional' | 'lastName' | 'surname' | 'maternalSurname'
@@ -75,6 +78,8 @@ export interface EkycCountryVariant {
 }
 
 const t = (key: EkycFieldKey, extra: Partial<EkycField> = {}): EkycField => ({ key, kind: 'text', ...extra });
+/** A hidden-by-default identifier, with the eye to reveal it. */
+const secret = (key: EkycFieldKey, extra: Partial<EkycField> = {}): EkycField => ({ key, kind: 'password', ...extra });
 const date = (key: EkycFieldKey = 'dateOfBirth', extra: Partial<EkycField> = {}): EkycField => ({ key, kind: 'date', ...extra });
 // Required fields carry Core's asterisk (`required` + `requiredHint`), the
 // owner's rule (Elena, 2026-09-24, DEVIATIONS #EKC-6): first name, last name or
@@ -112,7 +117,7 @@ export const EKYC_COUNTRY_CATALOG: EkycCountryVariant[] = [
   {
     id: 'us-telco-1', country: 'US', label: 'United States', provider: 'Telco 1', stepper: 3,
     steps: [
-      { node: '2098:9575', fields: [...NAME_PAIR(), email(), ...DOB_PHONE('US'), t('ssnLast4')] },
+      { node: '2098:9575', fields: [...NAME_PAIR(), email(), ...DOB_PHONE('US'), secret('ssnLast4')] },
       { node: '5854:76222', section: 'license', fields: [t('licenseNumber'), { key: 'licenseState', kind: 'dropdown', placeholder: 'selectState' }] },
       { node: '5854:76221', section: 'address', fields: US_ADDRESS },
     ],
@@ -129,7 +134,7 @@ export const EKYC_COUNTRY_CATALOG: EkycCountryVariant[] = [
     steps: [
       /* Same First | Last pair as the licence variant; Middle name (Optional)
          follows it and spans (#EKC-5). */
-      { node: '2098:9577', fields: [...NAME_PAIR(), t('middleNameOptional'), ...DOB_PHONE('US'), email(), t('ssnOrItin')] },
+      { node: '2098:9577', fields: [...NAME_PAIR(), t('middleNameOptional'), ...DOB_PHONE('US'), email(), secret('ssnOrItin')] },
       { node: '5857:34094', section: 'address', fields: US_ADDRESS },
     ],
   },
@@ -148,7 +153,7 @@ export const EKYC_COUNTRY_CATALOG: EkycCountryVariant[] = [
   {
     id: 'ca-res-credit', country: 'CA', label: 'Canada', provider: 'Residential credit', stepper: 2,
     steps: [
-      { node: '2098:9570', fields: [...NAME_PAIR(), email(), ...DOB_PHONE('CA'), t('ssnOrItin')] },
+      { node: '2098:9570', fields: [...NAME_PAIR(), email(), ...DOB_PHONE('CA'), secret('ssnOrItin')] },
       { node: '5857:36450', section: 'address', fields: CODE_ADDRESS('stateCodeCa') },
     ],
   },

package/src/EkycCountryFormScreen.tsx

@@ -1,5 +1,6 @@
 import React, { forwardRef } from 'react';
 import { PrizmaTextField } from '@incodetech/prizma-core-web/text-field';
+import { PrizmaPassword } from '@incodetech/prizma-core-web/password';
 import { PrizmaDateField } from '@incodetech/prizma-core-web/date-field';
 import { PrizmaDropdown } from '@incodetech/prizma-core-web/dropdown';
 import { PrizmaCombined, type PrizmaCountry } from '@incodetech/prizma-core-web/combined';
@@ -28,11 +29,20 @@ export interface EkycCountryFormScreenProps
   values?: EkycCountryValues;
   /**
    * The state after Continue was pressed with fields still empty: every empty
-   * field shows Core's error state and `country.requiredError` under it.
-   * Continue itself is ALWAYS enabled (Elena, 2026-09-24): validation happens
-   * on press, not by greying the button.
+   * REQUIRED field shows Core's error state and `country.requiredError` under
+   * it, and Continue is disabled (GUIDELINES §6-E empty-submit rule, Elena
+   * 2026-09-30). Without it Continue stays enabled: validation happens on
+   * press, the resting page never greys the button.
    */
   showErrors?: boolean;
+  /**
+   * Field keys whose typed value failed the format check on Continue (an
+   * invalid CPF, say). Each keeps its value, shows Core's error state and
+   * `country.invalidErrors[key]` under it; Continue stays enabled so the user
+   * corrects it and presses again, the CURP precedent (`CurpEnterScreen`'s
+   * `invalid`). A key with no message in `invalidErrors` shows no error.
+   */
+  invalidFields?: string[];
   /** Dial codes the phone field offers. Runtime data, never copy. */
   phoneCountries?: PrizmaCountry[];
   /** Options for the dropdown fields, keyed by field key. Runtime data. */
@@ -52,10 +62,13 @@ export interface EkycCountryFormScreenProps
  * dropdown, radio pair — so a new country is a catalogue entry, never a file.
  *
  * Deliberate, per frame and per owner:
- * - Continue is ALWAYS enabled (Elena, 2026-09-24, overriding the grey button
- *   most frames draw): pressing it with empty fields is the `showErrors` state,
- *   Core's error ring and message under each empty field. The radio pair has
- *   no error state in Core, so an empty gender shows none (DEVIATIONS #EKC-4).
+ * - Continue is enabled on the resting page (Elena, 2026-09-24, overriding the
+ *   grey button most frames draw): pressing it with empty fields is the
+ *   `showErrors` state, Core's error ring and message under each empty
+ *   required field, and THEN Continue is disabled. The "always enabled" half
+ *   of DEVIATIONS #EKC-4 is superseded by the 2026-09-30 empty-submit rule
+ *   (GUIDELINES §6-E). The radio pair has no error state in Core, so an empty
+ *   gender still shows none.
  * - ONE title per step (Elena, 2026-09-24): the personal-data step is "Enter
  *   your details" with its subtitle; a licence step is titled "Driver's
  *   License details" and an address step "Address details", with nothing
@@ -82,7 +95,7 @@ const groupRows = (fields: EkycField[]): EkycField[][] => {
   return groups;
 };
 export const EkycCountryFormScreen = forwardRef<HTMLDivElement, EkycCountryFormScreenProps>(
-  ({ strings, variant, step = 1, values, showErrors = false, phoneCountries, options, screenId, overrides, onAction, ...shell }, ref) => {
+  ({ strings, variant, step = 1, values, showErrors = false, invalidFields, phoneCountries, options, screenId, overrides, onAction, ...shell }, ref) => {
     const v = typeof variant === 'string' ? ekycCountryVariant(variant) : variant;
     if (!v) return null;
     const s = v.steps[Math.min(Math.max(step, 1), v.steps.length) - 1];
@@ -90,15 +103,23 @@ export const EkycCountryFormScreen = forwardRef<HTMLDivElement, EkycCountryFormS
     const stepperState: PrizmaStepperState = step <= 1 ? 'Start' : (Math.min(step, 6) as PrizmaStepperState);
 
     const label = (f: EkycField) => c.fields[f.key] ?? f.key;
-    const placeholder = (f: EkycField) => (f.placeholder ? c.placeholders[f.placeholder] : c.placeholders[f.key]);
+    // A lone field in its empty-submit error drops its placeholder, as the
+    // single-input screens do (Phone, Email and CURP's `emptyError`).
+    const lone = s.fields.length === 1;
+    const placeholder = (f: EkycField) =>
+      lone && showErrors && !values?.[f.key] ? undefined : f.placeholder ? c.placeholders[f.placeholder] : c.placeholders[f.key];
 
     const renderField = (f: EkycField) => {
       // Only a REQUIRED empty field is an error on press (Elena, 2026-09-24,
-      // DEVIATIONS #EKC-6): an optional field left blank shows nothing.
-      const missing = showErrors && Boolean(f.required) && !values?.[f.key];
+      // DEVIATIONS #EKC-6): an optional field left blank shows nothing. A
+      // step's lone field is required by definition, asterisk or not (the
+      // single-input rule, as Phone and Email Input: Elena, 2026-10-02).
+      const required = Boolean(f.required) || lone;
+      const missing = showErrors && required && !values?.[f.key];
+      const invalidText = invalidFields?.includes(f.key) ? c.invalidErrors?.[f.key] : undefined;
       const common = {
         key: f.key, label: label(f), required: f.required, requiredHint: strings.details.requiredHint,
-        error: missing || undefined, errorText: missing ? c.requiredError : undefined,
+        error: missing || Boolean(invalidText) || undefined, errorText: missing ? c.requiredError : invalidText,
       } as const;
       switch (f.kind) {
         case 'date':
@@ -126,6 +147,22 @@ export const EkycCountryFormScreen = forwardRef<HTMLDivElement, EkycCountryFormS
               defaultValue={values?.[f.key] ?? null}
             />
           );
+        case 'password':
+          /* The SSN / ITIN fields: Core's Password field, hidden by default, the
+             eye reveals it. No requirement checklist — this is an identifier,
+             not a password to compose (Elena, 2026-09-28). */
+          return (
+            <PrizmaPassword
+              {...common}
+              placeholder={placeholder(f)}
+              autoComplete="off"
+              defaultValue={values?.[f.key] ?? ''}
+              showPasswordLabel={c.showValueLabel}
+              hidePasswordLabel={c.hideValueLabel}
+              showHelper={false}
+              showRequirements={false}
+            />
+          );
         case 'radio':
           return (
             <PrizmaRadioGroup key={f.key} name={f.key} legend={label(f)} defaultValue={values?.[f.key]} className="ekyc-country__radios">
@@ -158,6 +195,8 @@ export const EkycCountryFormScreen = forwardRef<HTMLDivElement, EkycCountryFormS
           ) : undefined
         }
         ctaLabel={c.ctaLabel}
+        /* Greyed only after the empty submit (2026-09-30 empty-submit rule). */
+        ctaDisabled={showErrors}
         verifiedLabel={strings.verifiedLabel}
         navLabel={strings.navLabel}
         screenId={screenId}

package/src/EkycDetailsScreen.tsx

@@ -71,6 +71,13 @@ export interface EkycDetailsScreenProps
  * the label row Figma draws as "First name *" — so Middle name, the one
  * optional field, correctly renders none.
  *
+ * `emptyError` is the state after Continue was pressed with the fields still
+ * empty (Elena, 2026-09-30, GUIDELINES §6-E empty-submit rule; drawn precedent
+ * `FormsFieldScreen`'s `emptyError`): every field renders empty, the three
+ * REQUIRED ones carry Core's `error` + `country.requiredError`, Middle name
+ * stays unflagged (DEVIATIONS #EKC-6), and Continue is disabled. The resting
+ * `default` keeps Continue enabled so the press can happen at all.
+ *
  * Figma draws a two-segment journey bar between the nav and the title on every
  * page-1 frame, and it is the only chrome that separates page 1 from page 2.
  * Archetype E had no slot above the title; the gap is now CLOSED in the
@@ -85,8 +92,9 @@ export const EkycDetailsScreen = forwardRef<HTMLDivElement, EkycDetailsScreenPro
     {
       strings,
       state = 'default',
-      values,
+      values: valuesProp,
       screenId = `ekyc-details-${state}`,
+      ctaDisabled,
       className,
       overrides,
       onAction,
@@ -98,6 +106,13 @@ export const EkycDetailsScreen = forwardRef<HTMLDivElement, EkycDetailsScreenPro
     // rings First name blue and shows its clear ✕; the other two draw every
     // field resting.
     const focused = state === 'focused';
+    // The empty-submit state: every field empty, required ones in error.
+    const emptyError = state === 'emptyError';
+    const values = emptyError ? undefined : valuesProp;
+    // Core's own error treatment, spread onto the REQUIRED fields only.
+    const missing = emptyError
+      ? { error: true, errorText: strings.country.requiredError }
+      : {};
 
     return (
       <PrizmaFormScreen
@@ -122,6 +137,9 @@ export const EkycDetailsScreen = forwardRef<HTMLDivElement, EkycDetailsScreenPro
         title={strings.details.title}
         subtitle={strings.details.subtitle}
         ctaLabel={strings.details.ctaLabel}
+        /* Disabled only after the empty submit; the resting page keeps it
+           enabled so the press can happen. */
+        ctaDisabled={emptyError || ctaDisabled}
         verifiedLabel={strings.verifiedLabel}
         navLabel={strings.navLabel}
         screenId={screenId}
@@ -146,6 +164,7 @@ export const EkycDetailsScreen = forwardRef<HTMLDivElement, EkycDetailsScreenPro
             label={strings.details.firstNameLabel}
             required
             requiredHint={strings.details.requiredHint}
+            {...missing}
             defaultValue={values?.firstName ?? ''}
             autoComplete="off"
             /* Only 2101:8159 draws the ✕, and only in this field. */
@@ -156,6 +175,7 @@ export const EkycDetailsScreen = forwardRef<HTMLDivElement, EkycDetailsScreenPro
             label={strings.details.lastNameLabel}
             required
             requiredHint={strings.details.requiredHint}
+            {...missing}
             defaultValue={values?.lastName ?? ''}
             autoComplete="off"
             clearable={false}
@@ -171,6 +191,7 @@ export const EkycDetailsScreen = forwardRef<HTMLDivElement, EkycDetailsScreenPro
           label={strings.details.dateOfBirthLabel}
           required
           requiredHint={strings.details.requiredHint}
+          {...missing}
           defaultValue={values?.dateOfBirth ?? ''}
           autoComplete="off"
           /* No `onCalendarClick`: a screen is a static spec state with no

package/src/EkycStrings.ts

@@ -43,8 +43,12 @@
  *               the clear ✕ (2101:8159 draws the OS keyboard over the CTA; the
  *               keyboard is OS chrome, never a screen element)
  * - `filled`  — all four fields resting with their values
+ * - `emptyError` — Continue was pressed with the fields empty (GUIDELINES §6-E
+ *               empty-submit rule, Elena 2026-09-30): the three REQUIRED fields
+ *               in Core's error state with `country.requiredError`, Middle name
+ *               (optional) unflagged, and Continue disabled. Not a Figma frame.
  */
-export type EkycDetailsState = 'default' | 'focused' | 'filled';
+export type EkycDetailsState = 'default' | 'focused' | 'filled' | 'emptyError';
 
 /**
  * The page-2 sections (`eKYC.default` / `eKYC.filled` / `eKYC.loading`), same
@@ -153,6 +157,10 @@ export interface EkycStrings {
     licenseSection: string;
     /** Accessible name of the phone field's dial-code list. */
     countryListLabel: string;
+    /** Accessible names for the eye on a `password` field (the SSN / ITIN
+     *  fields): while the value is hidden, and while it is shown. */
+    showValueLabel: string;
+    hideValueLabel: string;
     /** The gender radio pair, Argentina. */
     genderOptions: { value: string; label: string }[];
     fields: Record<string, string>;
@@ -160,8 +168,12 @@ export interface EkycStrings {
     ctaLabel: string;
     /** The secondary button on a step after the first. */
     backLabel: string;
-    /** Under every empty field once Continue was pressed (`showErrors`). */
+    /** Under every empty REQUIRED field once Continue was pressed: the
+     *  by-country `showErrors` state and page 1's `emptyError` both read it. */
     requiredError: string;
+    /** Under a field whose value failed the format check on Continue, by
+     *  field key (`invalidFields`). `cpf` is SDK key `dynamicForms.invalidCpf`. */
+    invalidErrors?: Record<string, string>;
   };
 
   /** `eKYC.processing` — spinner over the status line, no button. */

package/src/ElectronicSignatureLayout.css

@@ -47,6 +47,12 @@
   border: var(--prizma-border-width-regular) solid var(--prizma-border-neutral-100);
   border-radius: var(--prizma-border-radius-small);
   text-align: start;
+  /* Air between the frame and the CTA band. Archetype G's list middle carries
+     no bottom gap (its content normally ends well above the band), so a frame
+     that fills the middle sat flush against Continue (owner-reported
+     2026-09-29). Spacing/16 is the archetype's own scrolling-middle → band gap
+     (`.prizma-screen-layout__list--scroll`, ScreenLayout.css). */
+  margin-bottom: var(--prizma-spacing-16);
 }
 
 /* The agreement's own typography — Body/M Regular on Text/Body/500, the pair

package/src/EmailInputStrings.ts

@@ -27,13 +27,18 @@
  * - `filled`  — focused field with a complete address
  * - `error`   — negative field + clear ✕ + the invalid-format row
  * - `loading` — field greyed while the code is requested, spinner in the CTA
+ * - `emptyError` — "Continue" pressed with the field still empty: the field
+ *   stays empty (no placeholder) in Core's error state with `requiredError`,
+ *   and the CTA is disabled. GUIDELINES §6-E empty-submit rule (Elena,
+ *   2026-09-30).
  */
 export type EmailInputVerifyState =
   | 'default'
   | 'typing'
   | 'filled'
   | 'error'
-  | 'loading';
+  | 'loading'
+  | 'emptyError';
 
 /**
  * The `email.OTP.*` sections — same layout, different code-field state:
@@ -58,6 +63,12 @@ export interface EmailInputStrings {
   verifiedLabel: string;
   /** Accessible name for the logo nav row. */
   navLabel?: string;
+  /**
+   * Error row under the required field when the primary CTA is pressed with it
+   * still empty (the verify screen's `emptyError` state): "This field is
+   * required". SDK key `dynamicForms.fieldRequired`.
+   */
+  requiredError: string;
 
   /** email.verifyEmail.* */
   verify: {

package/src/EmailInputVerifyScreen.tsx

@@ -48,6 +48,13 @@ export interface EmailInputVerifyScreenProps
  * paints the DISABLED surface (owner definition 2026-07-12), which would grey
  * the four resting states Figma draws white. The field is uncontrolled instead
  * (DEVIATIONS #PI-6).
+ *
+ * `emptyError` is the empty-submit state (rule from Elena, 2026-09-30,
+ * GUIDELINES §6-E empty-submit rule): "Continue" was pressed with nothing
+ * typed. The field renders empty with no placeholder, in Core's error state
+ * with `requiredError`, and the primary CTA is disabled, following the drawn
+ * precedent in `FormsFieldScreen`. The resting `default` keeps the CTA enabled
+ * so the user can reach this state.
  */
 export const EmailInputVerifyScreen = forwardRef<HTMLDivElement, EmailInputVerifyScreenProps>(
   (
@@ -64,6 +71,9 @@ export const EmailInputVerifyScreen = forwardRef<HTMLDivElement, EmailInputVerif
   ) => {
     const busy = state === 'loading';
     const invalid = state === 'error';
+    // Empty submit: the field drops its placeholder and takes Core's error
+    // state with the shared "required" row; the CTA greys.
+    const emptyError = state === 'emptyError';
     const focused = state === 'typing' || state === 'filled';
 
     return (
@@ -74,6 +84,7 @@ export const EmailInputVerifyScreen = forwardRef<HTMLDivElement, EmailInputVerif
         ctaLabel={strings.verify.ctaLabel}
         /* Figma's `loading` section swaps the CTA label for Core's spinner. */
         ctaLoading={busy}
+        ctaDisabled={emptyError}
         ctaLoadingLabel={strings.verify.ctaLoadingLabel}
         verifiedLabel={strings.verifiedLabel}
         navLabel={strings.navLabel}
@@ -97,13 +108,19 @@ export const EmailInputVerifyScreen = forwardRef<HTMLDivElement, EmailInputVerif
           /* Figma's field has no visible label row — the placeholder carries
              the meaning — so the copy rides `aria-label` (DEVIATIONS #PI-4). */
           aria-label={strings.verify.fieldLabel}
-          placeholder={strings.verify.placeholder}
+          placeholder={emptyError ? undefined : strings.verify.placeholder}
           /* Uncontrolled: a screen is one static spec state, so no `onChange`
              is needed and no warning is raised. */
-          defaultValue={value ?? ''}
+          defaultValue={emptyError ? '' : value ?? ''}
           disabled={busy}
-          error={invalid}
-          errorText={invalid ? strings.verify.errorText : undefined}
+          error={invalid || emptyError}
+          errorText={
+            invalid
+              ? strings.verify.errorText
+              : emptyError
+                ? strings.requiredError
+                : undefined
+          }
           /* The clear ✕ is drawn on the `error` section only. */
           clearable={invalid}
           clearLabel={strings.verify.clearLabel}

package/src/ErrorScreensScreen.tsx

@@ -38,7 +38,7 @@ export interface ErrorScreensScreenProps
  * Error screens — the session-level failures, built on the Result archetype
  * (GUIDELINES.md §6-F, `PrizmaResultScreen`).
  *
- * ONE screen for all three generic sections. They draw the identical skeleton —
+ * ONE screen for all four generic sections. They draw the identical skeleton —
  * a centred mark + title + supporting line over a CTA band — and differ only in
  * copy, in which mark leads, and in what the band carries:
  *
@@ -46,8 +46,11 @@ export interface ErrorScreensScreenProps
  * - `noConnection`       — Wi-Fi glyph, "Refresh"
  * - `unsupportedBrowser` — canonical negative mark, the session URL above
  *                          "Copy link", with "Continue anyways" under it
+ * - `somethingWentWrong` — canonical negative mark, "Try again" when the copy
+ *                          carries a CTA, "Quit process" under it when it
+ *                          carries a quit label; a dead end when it has neither
  *
- * Chrome is CONSTANT. All three frames are drawn without the logo header and
+ * Chrome is CONSTANT. All the frames are drawn without the logo header and
  * without the verified tag; both are kept here, because the owner rule of
  * 2026-08-18 (#F-30, #F-34) makes the chrome the same on every screen so
  * nothing shifts between states, and every module's connectivity screen must
@@ -91,11 +94,19 @@ export const ErrorScreensScreen = forwardRef<HTMLDivElement, ErrorScreensScreenP
   ) => {
     const unsupported = variant === 'unsupportedBrowser';
     const noConnection = variant === 'noConnection';
+    const generic = variant === 'somethingWentWrong';
     const copy = unsupported
       ? strings.unsupportedBrowser
       : noConnection
         ? strings.noConnection
-        : strings.sessionExpired;
+        : generic
+          ? strings.somethingWentWrong
+          : strings.sessionExpired;
+    const linkLabel = unsupported
+      ? strings.unsupportedBrowser.continueLabel
+      : generic
+        ? strings.somethingWentWrong.quitLabel
+        : undefined;
 
     return (
       <PrizmaResultScreen
@@ -133,7 +144,7 @@ export const ErrorScreensScreen = forwardRef<HTMLDivElement, ErrorScreensScreenP
             : undefined
         }
         ctaLabel={copy.ctaLabel}
-        linkLabel={unsupported ? strings.unsupportedBrowser.continueLabel : undefined}
+        linkLabel={linkLabel}
         verifiedLabel={strings.verifiedLabel}
         navLabel={strings.navLabel}
         screenId={screenId}

package/src/ErrorScreensStrings.ts

@@ -6,19 +6,27 @@
 //   214:3357 Geolocation.error.noNetwork      → `noConnection`
 //   240:154  Error screen - Unsupported browser → `unsupportedBrowser`
 //
-// The three failures that belong to the SESSION rather than to any module: the
-// link has expired, the network went away, the browser cannot run the SDK.
-// Every module can hit all three, which is why they are drawn once in the
-// generic file — a user who sees three different "no internet" screens in one
-// journey reads them as three different products.
+// plus the one failure every module draws for itself and the file never did:
+//
+//   —        <module>.error "Something went wrong" → `somethingWentWrong`
+//
+// The failures that belong to the SESSION rather than to any module: the link
+// has expired, the network went away, the browser cannot run the SDK, the
+// server said no for a reason the user cannot act on. Every module can hit all
+// four, which is why they are recorded once in the generic family — a user who
+// sees three different "no internet" screens in one journey reads them as three
+// different products.
 //
 // `noConnection` is deliberately the same screen every module already ships
 // (`FaceCaptureNoConnectionScreen`, `IdCaptureNoConnectionScreen`,
-// `DocumentCaptureNoConnectionScreen`, `GeolocationErrorScreen`'s `noNetwork`).
-// The generic entry is where the shape is DOCUMENTED; the module copies stay
-// put until someone retires them deliberately, because deleting four exported
-// components to save one screen is a breaking change for every host that
-// imports them. Flagged for the owner.
+// `DocumentCaptureNoConnectionScreen`, `GeolocationErrorScreen`'s `noNetwork`,
+// Phone Input's and Video Selfie's `noConnection`). `somethingWentWrong` is the
+// same screen eKYC, eKYB, Forms, Email Input, Phone Input, Certificate
+// Issuance, both signatures and Video Selfie already ship. The generic entry is
+// where the shape and the copy are DOCUMENTED; the module copies stay put until
+// someone retires them deliberately, because deleting exported components to
+// save one screen is a breaking change for every host that imports them.
+// Flagged for the owner (DEVIATIONS #GEN-7, #GEN-18).
 //
 // The family has no flow of its own: each of these is entered from wherever the
 // session broke and exits to a retry or to nothing. Core Lab lists it as a
@@ -27,15 +35,17 @@
 // No hardcoded English anywhere in a screen: every visible string arrives here.
 
 /**
- * The three sections.
+ * The four sections.
  * - `sessionExpired`     — the link is dead; the user must go back to the provider
  * - `noConnection`       — the network went away; retry when it returns
  * - `unsupportedBrowser` — the SDK cannot run here; copy the link and move
+ * - `somethingWentWrong` — the generic failure; try again, or nothing, or quit
  */
 export type ErrorScreensVariant =
   | 'sessionExpired'
   | 'noConnection'
-  | 'unsupportedBrowser';
+  | 'unsupportedBrowser'
+  | 'somethingWentWrong';
 
 export interface ErrorScreensCopy {
   title: string;
@@ -63,4 +73,19 @@ export interface ErrorScreensStrings {
     /** Snackbar copy after the link is copied — the frame's second state. */
     copiedLabel: string;
   };
+
+  /**
+   * The generic failure. Three ways the modules fill it, all the same screen:
+   * `ctaLabel` "Try again" (eKYC, eKYB, Forms, Email Input);
+   * no `ctaLabel`, a dead end (Certificate Issuance, Qualified Signature);
+   * `ctaLabel` plus `quitLabel`, the way out under the retry (Video Selfie).
+   * Phone Input's `unknown` fills it with "Continue" instead, because a retry
+   * may not be possible there (owner, 2026-10-09) — the CTA is the module's
+   * call; the shape and the title are what the family fixes.
+   * The title never carries an ellipsis — a failure is not in progress.
+   */
+  somethingWentWrong: ErrorScreensCopy & {
+    /** Tertiary link under the CTA — "Quit process". Omit for no way out. */
+    quitLabel?: string;
+  };
 }

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';