@incodetech/prizma-core-screens 0.2.3 → 0.2.7

package/src/VideoSelfieStrings.ts

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

package/src/VideoSelfieTurnHeadScreen.tsx

@@ -0,0 +1,151 @@
+import React, { forwardRef, type ReactNode } from 'react';
+import {
+  IconArrowDownCircle,
+  IconArrowLeftCircle,
+  IconArrowRightCircle,
+  IconArrowUpCircle,
+} from '@incodetech/prizma-core-icons';
+import { PrizmaSelfieCapture } from '@incodetech/prizma-core-web/selfie-capture';
+import { PrizmaStepper } from '@incodetech/prizma-core-web/stepper';
+import { PrizmaScreenShell, type PrizmaScreenShellProps } from './ScreenShell';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type {
+  VideoSelfieDocumentType,
+  VideoSelfieStrings,
+  VideoSelfieTurnDirection,
+} from './VideoSelfieStrings';
+import './ScreenLayout.css';
+import './ViewfinderScreen.css';
+import './VideoSelfieLayout.css';
+
+/** The two beats each direction is drawn in: the stage ASKING (dashed guide
+ *  ring) and the stage having SEEN it (the positive ring). */
+export type VideoSelfieTurnStage = 'ask' | 'done';
+
+/**
+ * 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).
+ */
+const TURN_ICON: Record<VideoSelfieTurnDirection, ReactNode> = {
+  left: <IconArrowLeftCircle size="2xl" />,
+  right: <IconArrowRightCircle size="2xl" />,
+  up: <IconArrowUpCircle size="2xl" />,
+  down: <IconArrowDownCircle size="2xl" />,
+};
+
+export interface VideoSelfieTurnHeadScreenProps
+  extends Omit<PrizmaScreenShellProps, 'dark' | 'title' | 'children'> {
+  /** Module copy — this screen reads `selfieCapture.turn`. */
+  strings: VideoSelfieStrings;
+  /** Which way the user is asked to turn. Default `left`. */
+  direction?: VideoSelfieTurnDirection;
+  /** Asking, or seen. Default `ask`. */
+  stage?: VideoSelfieTurnStage;
+  /** Which document the journey collects — the Stepper's own `documentType`. */
+  documentType?: VideoSelfieDocumentType;
+  /** Live camera feed (<video>) or sample still (<img>), full-bleed behind
+   *  the ring. */
+  camera?: ReactNode;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Video Selfie — the head-turn beats of the liveness sequence (Archetype D,
+ * GUIDELINES.md §6-D; always dark). NEW 2026-09-30: the `🙂‍↔️ Turn Head` band
+ * of the Web / iOS / Android full-flow frames draws four directions, each in
+ * two beats, and none of them existed in the screens package — the module
+ * jumped straight from the liveness ring to the spoken steps.
+ *
+ * The frames are the liveness stage with three changes, and nothing else:
+ *
+ * - the ring is Core's GUIDE stroke (`ring="dashed"`) while the stage waits
+ *   for the turn, and the positive ring once it has seen it;
+ * - the silhouette guide is ON (Core's `empty`), because the user is being
+ *   asked to move their face rather than hold it still;
+ * - a small arrow chip sits between the ring and the instruction, saying
+ *   which way.
+ *
+ * The mark under the ring is a canonical bank glyph at 2xl — the disc is part
+ * of the drawing, not something this screen paints. `PrizmaTitle.icon` takes
+ * `status | spinner | none` only (DEVIATIONS #10), so the block below the ring
+ * is composed here; it declares a gap and nothing else. CORE REQUEST stands: a
+ * `glyph` slot on the capture stage, so this and Face Capture's future hint
+ * marks share one component. DEVIATIONS #VS-20.
+ */
+export const VideoSelfieTurnHeadScreen = forwardRef<
+  HTMLDivElement,
+  VideoSelfieTurnHeadScreenProps
+>(
+  (
+    {
+      strings,
+      direction = 'left',
+      stage = 'ask',
+      documentType = 'id',
+      camera,
+      screenId = `video-selfie-turn-${direction}-${stage}`,
+      overrides,
+      onAction,
+      className,
+      ...shell
+    },
+    ref,
+  ) => (
+    <PrizmaScreenShell ref={ref} dark className={className} {...shell}>
+      <div className="prizma-viewfinder__surface">{camera}</div>
+      <div className="video-selfie-stepper">
+        <PrizmaStepper
+          steps={7}
+          currentState={4}
+          documentType={documentType}
+          completedValueText={strings.stepperCompletedLabel}
+        />
+      </div>
+      <div
+        className={[
+          'prizma-viewfinder__content',
+          overrides?.align === 'left' ? 'prizma-viewfinder__content--left' : '',
+        ]
+          .filter(Boolean)
+          .join(' ')}
+      >
+        <div className="video-selfie-band video-selfie-band--ring">
+          <PrizmaSelfieCapture
+            mode="overlay"
+            scrim
+            /* The ring says WHICH WAY: the half on the side being asked for
+               is dashed while the stage waits and positive once it has seen
+               the turn, and the other half stays the neutral track. The state
+               is `filled` on both beats — the verdict lives in the arc, not in
+               the whole ring, so nothing else about the stage changes. */
+            guide={{ side: direction, state: stage === 'ask' ? 'waiting' : 'seen' }}
+            state="filled"
+            showFeedback={false}
+          />
+          {/* Both beats carry the SAME chip and the same instruction — the
+              frames change only the ring. Nothing is announced on the turn
+              itself, which is why the stage is handed no `statusLabels`: in
+              overlay mode a verdict with no copy is a ring colour, not a
+              message. */}
+          <div className="video-selfie-turn">
+            <span className="video-selfie-turn__mark">{TURN_ICON[direction]}</span>
+            <p className="prizma-viewfinder__title">
+              {strings.selfieCapture.turn[direction]}
+            </p>
+          </div>
+        </div>
+      </div>
+    </PrizmaScreenShell>
+  ),
+);
+VideoSelfieTurnHeadScreen.displayName = 'VideoSelfieTurnHeadScreen';
+
+export default VideoSelfieTurnHeadScreen;

package/src/VideoSelfieTutorialScreen.tsx

@@ -1,15 +1,15 @@
 import React, { forwardRef, type ReactNode } from 'react';
 import {
   IconBankCard,
-  IconIdFront,
   IconMessages,
   IconMicrophone,
   IconNumberedList,
-  IconPassport,
+  IconPassportCapture,
   IconUser,
+  IconUserInformation,
   IconWavingHand,
 } from '@incodetech/prizma-core-icons';
-import { PrizmaListItem } from '@incodetech/prizma-core-web/list';
+import { PrizmaList } from '@incodetech/prizma-core-web/list';
 import { PrizmaListScreen, type PrizmaListScreenProps } from './ListScreen';
 import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
 import type {
@@ -27,9 +27,13 @@ import './ScreenLayout.css';
  */
 const ROW_ICONS: Record<VideoSelfieTutorialRowKind, ReactNode> = {
   recording: <IconMicrophone size="m" />,
-  idFront: <IconIdFront size="m" />,
+  // `user-information` and `passport-capture`, NOT `id-front` and `passport`:
+  // the tutorial promises the steps the Stepper then counts off, and the
+  // Stepper's own sequence uses these two. Corrected 2026-09-30 — the tutorial
+  // was drawing a different ID glyph from the one the journey shows.
+  idFront: <IconUserInformation size="m" />,
   idBack: <IconBankCard size="m" />,
-  passport: <IconPassport size="m" />,
+  passport: <IconPassportCapture size="m" />,
   frontCamera: <IconUser size="m" />,
   waveHand: <IconWavingHand size="m" />,
   questions: <IconNumberedList size="m" />,
@@ -102,25 +106,32 @@ export const VideoSelfieTutorialScreen = forwardRef<
       onAction={onAction}
       {...shell}
     >
-      {/* Core's LIST-WITH-ICON rows. `1.0`/`1.2` draw the steps as plain
-          icon + label rows with NO card surface behind them, so
-          `PrizmaCardListCommonIssues` was wrong — it gave every row a tinted
-          card the design does not have (owner-reported 2026-08-19).
+      {/* Core's `PrizmaList`, `icons-chain` — the stepper-style list: a 40
+          squircle per step with a 2×8 connector running down to the next one,
+          which is exactly what `1.0` and `1.2` draw (`List` → `List item` →
+          `Icon / List item` → `stepIcon` + `bottomConnector`).
 
-          The rows are Core's `PrizmaListItem` (`icon-m`), composed directly
-          rather than through `PrizmaList`: the wrapper's icon variants cap at
-          SIX slots and silently drop the rest, and this tutorial draws SEVEN
-          steps. The <ul> carries only the variant's own Spacing/12 rhythm —
-          no new value. CORE REQUEST: let `PrizmaList`'s icon variants take a
-          seventh row. DEVIATIONS #VS-8.
-       */}
-      <ul className="video-selfie-tutorial-list">
-        {strings.tutorial.rows[documentType].map((row) => (
-          <li key={row.kind}>
-            <PrizmaListItem variant="icon-m" label={row.label} icon={ROW_ICONS[row.kind]} />
-          </li>
-        ))}
-      </ul>
+          It used to be a hand-rolled <ul> of bare `PrizmaListItem`s, for two
+          reasons that are both gone: the icon LIST variants capped at six
+          slots and this tutorial draws seven, and no list variant paired with
+          the `icon-connector` ROW variant at all, so a stepper list could
+          only be numbered. `icons-chain` was added to Core on 2026-09-30 with
+          seven slots, and closes both (#VS-8, #VS-16). The list declares no
+          layout of its own here — the rhythm, the squircle and the connector
+          are the variant's. */}
+      <PrizmaList
+        variant="icons-chain"
+        showItem3
+        showItem4
+        showItem5
+        showItem6
+        showItem7
+        items={strings.tutorial.rows[documentType].map((row) => ({
+          variant: 'icon-connector' as const,
+          label: row.label,
+          icon: ROW_ICONS[row.kind],
+        }))}
+      />
     </PrizmaListScreen>
   ),
 );

package/src/VideoSelfieWaveScreen.tsx

@@ -0,0 +1,135 @@
+import React, { forwardRef, type ReactNode } from 'react';
+import { PrizmaModalContent } from '@incodetech/prizma-core-web/modal';
+import { PrizmaSelfieCapture } from '@incodetech/prizma-core-web/selfie-capture';
+import { PrizmaStepper } from '@incodetech/prizma-core-web/stepper';
+import { PrizmaScreenShell, type PrizmaScreenShellProps } from './ScreenShell';
+import type { PrizmaScreenActionHandler, PrizmaScreenOverrides } from './types';
+import type { VideoSelfieDocumentType, VideoSelfieStrings } from './VideoSelfieStrings';
+import './ScreenLayout.css';
+import './ViewfinderScreen.css';
+import './VideoSelfieLayout.css';
+
+/** The three beats the `👋 Wave` band draws. */
+export type VideoSelfieWaveStage = 'waiting' | 'ready' | 'success';
+
+export interface VideoSelfieWaveScreenProps
+  extends Omit<PrizmaScreenShellProps, 'dark' | 'title' | 'children'> {
+  /** Module copy — this screen reads `selfieCapture.wave`. */
+  strings: VideoSelfieStrings;
+  /** Which beat to render. Default `waiting`. */
+  stage?: VideoSelfieWaveStage;
+  /** Which document the journey collects — the Stepper's own `documentType`. */
+  documentType?: VideoSelfieDocumentType;
+  /** Live camera feed (<video>) or sample still (<img>), full-bleed behind
+   *  the ring. */
+  camera?: ReactNode;
+  screenId?: string;
+  overrides?: PrizmaScreenOverrides;
+  onAction?: PrizmaScreenActionHandler;
+}
+
+/**
+ * Video Selfie — the hand-wave beat of the liveness sequence (Archetype D,
+ * GUIDELINES.md §6-D; always dark). NEW 2026-09-30, from the `👋 Wave` band of
+ * the full-flow frames; like the head turns, it had no screen at all.
+ *
+ * The composition is the liveness ring with the spoken steps' card under it:
+ * the feed runs full-bleed, the ring frames the face, and Core's Modal asks
+ * for the gesture with a CTA that only lights up once the stage has seen it
+ * (the frames' "5 second delay" note between the two). The verdict beat is the
+ * ring's own positive treatment plus the module's "Looking good!" — the SAME
+ * copy and the same mark `8.2` uses, because it is the same answer.
+ *
+ * The scrim/panel positioning is the recipe Document Capture's method sheet
+ * established (DEVIATIONS #DC-30): Core's safe presenter portals to
+ * `document.body`, which would escape the 390×844 frame and the host's
+ * `transform: scale()`, so the screen owns the panel and Core owns the card.
+ * The card is pinned back to LIGHT inside the dark shell for the reason
+ * `VideoSelfieSpeakScreen` documents (#VS-10).
+ *
+ * The hand that sweeps across the face is Core's, not this screen's:
+ * `PrizmaSelfieCapture` grew a `hint="wave"` axis on 2026-09-30 (owner: "we
+ * need the hand wave"), the face counterpart of `PrizmaIdCapture`'s animated
+ * hand hint, so the art and the choreography live where every other capture
+ * gesture already lives. The screen only says WHEN: the hand runs while the
+ * stage is waiting and stops the moment the wave has landed, which is the
+ * frames' own "5 second delay · Remove animation (Accessibility)" note.
+ * DEVIATIONS #VS-21.
+ */
+export const VideoSelfieWaveScreen = forwardRef<HTMLDivElement, VideoSelfieWaveScreenProps>(
+  (
+    {
+      strings,
+      stage = 'waiting',
+      documentType = 'id',
+      camera,
+      screenId = `video-selfie-wave-${stage}`,
+      overrides,
+      onAction,
+      className,
+      ...shell
+    },
+    ref,
+  ) => {
+    const slice = strings.selfieCapture.wave;
+    const seen = stage === 'success';
+
+    return (
+      <PrizmaScreenShell ref={ref} dark className={className} {...shell}>
+        <div className="prizma-viewfinder__surface">{camera}</div>
+        <div className="video-selfie-stepper">
+          <PrizmaStepper
+            steps={7}
+            currentState={5}
+            documentType={documentType}
+            completedValueText={strings.stepperCompletedLabel}
+          />
+        </div>
+        <div
+          className={[
+            'prizma-viewfinder__content',
+            overrides?.align === 'left' ? 'prizma-viewfinder__content--left' : '',
+          ]
+            .filter(Boolean)
+            .join(' ')}
+        >
+          <div className="video-selfie-band video-selfie-band--ring">
+            <PrizmaSelfieCapture
+              mode="overlay"
+              scrim
+              state={seen ? 'success' : 'filled'}
+              /* The hand demonstrates the gesture only while the stage is
+                 still waiting for it. On `ready` the wave has landed and the
+                 CTA lights up instead — the frames drop the animation at
+                 exactly that beat. */
+              hint={stage === 'waiting' ? 'wave' : undefined}
+              showFeedback={false}
+              statusLabels={{ success: strings.selfieCapture.successLabel }}
+            />
+          </div>
+        </div>
+        {/* The card is gone on the verdict beat — the ring and the mark are the
+            whole answer there, exactly as the band's last frame draws it. */}
+        {seen ? null : (
+          <div data-prizma-theme="light" className="video-selfie-sheet-panel">
+            <PrizmaModalContent
+              title={slice.instruction}
+              showCloseIcon={false}
+              buttonGroupProps={{
+                orientation: 'vertical-v1',
+                showPrimary: true,
+                showSecondary: false,
+                primaryLabel: slice.doneLabel,
+                primaryDisabled: stage !== 'ready',
+                onPrimaryClick: () => onAction?.({ type: 'cta', screenId }),
+              }}
+            />
+          </div>
+        )}
+      </PrizmaScreenShell>
+    );
+  },
+);
+VideoSelfieWaveScreen.displayName = 'VideoSelfieWaveScreen';
+
+export default VideoSelfieWaveScreen;

package/src/WatchlistBusinessFormScreen.tsx

@@ -41,8 +41,9 @@ export interface WatchlistBusinessFormScreenProps
  * (GUIDELINES.md §6-E, `PrizmaFormScreen`).
  *
  * ONE screen for both purple form sections (`watchlist.default` and
- * `watchlist.filled`): measured against the 390 frames they share an identical
- * skeleton — nav → Title (H2, no subtitle) → Spacing/32 → Country dropdown,
+ * `watchlist.filled`), plus the `emptyError` state the GUIDELINES §6-E
+ * empty-submit rule adds (Elena 2026-09-30, see note 3): measured against the 390 frames they share an identical
+ * skeleton — nav → Title (H2 + the "fields marked with *" H5) → Spacing/32 → Country dropdown,
  * Business Name and Tax ID at Spacing/16 → primary CTA → tag — and differ ONLY
  * in field content and whether the CTA is live.
  *
@@ -57,11 +58,14 @@ export interface WatchlistBusinessFormScreenProps
  *    and Core's `readOnly`, the other way to make a field inert, paints the
  *    DISABLED grey surface on states Figma draws white (DEVIATIONS #PI-6).
  *    Neither section greys anything, so `disabled` is set nowhere.
- * 3. The CTA state comes from the SECTION, not from the values: Figma greys
- *    "Continue" on `default` and lights it on `filled` — and `filled` leaves Tax
- *    ID empty, which is how we know the tax identifier does not gate the lookup
- *    (DEVIATIONS #WB-2). Deriving `ctaDisabled` from the values would have
- *    disagreed with the design.
+ * 3. The CTA state comes from the SECTION, not from the values. Under the
+ *    GUIDELINES §6-E empty-submit rule (Elena 2026-09-30) "Continue" is live
+ *    on the resting `default` form, so the user can press it, and greys ONLY
+ *    on `emptyError`, the state that press leads to: Country and Business
+ *    Name render empty (no placeholder) in Core's error state with
+ *    `requiredError`. Tax ID never errors — `filled` leaves it empty with the
+ *    CTA live, which is how we know it does not gate the lookup (DEVIATIONS
+ *    #WB-2).
  * 4. The country flag is Core's canonical raster (24×18, radius 2) in the
  *    dropdown's LEADING slot — `PrizmaCountryFlag` composed into
  *    `PrizmaDropdown.renderLeading`, which exists for exactly this case and
@@ -95,9 +99,11 @@ export const WatchlistBusinessFormScreen = forwardRef<
     ref,
   ) => {
     const copy = strings.form;
-    // `default` draws the CTA greyed, `filled` draws it live. The section is the
-    // spec, not the field contents (see note 3 above).
-    const empty = state === 'default';
+    // The CTA greys only after an empty submit; the resting form keeps it live
+    // so that submit can happen. The section is the spec, not the field
+    // contents (see note 3 above).
+    const emptyError = state === 'emptyError';
+    const errorText = emptyError ? strings.requiredError : undefined;
 
     // The label is the country NAME only. The flag is not part of it — it rides
     // the dropdown's leading slot below, where Core paints the raster.
@@ -112,7 +118,7 @@ export const WatchlistBusinessFormScreen = forwardRef<
         title={copy.title}
         subtitle={copy.subtitle}
         ctaLabel={copy.ctaLabel}
-        ctaDisabled={empty}
+        ctaDisabled={emptyError}
         ctaLoadingLabel={copy.ctaLoadingLabel}
         /* Figma draws no verified tag on either form section, but GUIDELINES §1
            and the standing owner rule (#F-30, #PI-8) keep header AND footer on
@@ -127,9 +133,17 @@ export const WatchlistBusinessFormScreen = forwardRef<
       >
         <PrizmaDropdown
           label={copy.country.label}
-          placeholder={copy.country.placeholder}
+          /* Country and Business Name are required and marked (Elena,
+             2026-09-30); the H5 explains the asterisk. */
+          required
+          requiredHint={strings.requiredHint}
+          /* The empty-submit error draws the field with nothing in it, as the
+             `FormsFieldScreen` `emptyError` precedent does. */
+          placeholder={emptyError ? undefined : copy.country.placeholder}
           options={options}
-          defaultValue={values?.country ?? null}
+          defaultValue={emptyError ? null : (values?.country ?? null)}
+          error={emptyError}
+          errorText={errorText}
           /* A country catalogue is long enough that Core's own search bar is
              the right behaviour; no purple section draws the menu open, so
              nothing about its appearance is being invented here. */
@@ -155,9 +169,13 @@ export const WatchlistBusinessFormScreen = forwardRef<
         />
         <PrizmaTextField
           label={copy.businessName.label}
-          placeholder={copy.businessName.placeholder}
+          required
+          requiredHint={strings.requiredHint}
+          placeholder={emptyError ? undefined : copy.businessName.placeholder}
           autoComplete="organization"
-          defaultValue={values?.businessName ?? ''}
+          defaultValue={emptyError ? '' : (values?.businessName ?? '')}
+          error={emptyError}
+          errorText={errorText}
         />
         <PrizmaTextField
           label={copy.taxId.label}
@@ -165,7 +183,8 @@ export const WatchlistBusinessFormScreen = forwardRef<
           autoComplete="off"
           autoCapitalize="characters"
           spellCheck={false}
-          defaultValue={values?.taxId ?? ''}
+          /* Optional (#WB-2): an empty submit leaves it clean. */
+          defaultValue={emptyError ? '' : (values?.taxId ?? '')}
         />
       </PrizmaFormScreen>
     );

package/src/WatchlistBusinessStrings.ts

@@ -23,15 +23,18 @@
  * in field content and whether the CTA is live, which is exactly what
  * GUIDELINES §6-E means by "states are separate screens sharing the identical
  * layout":
- * - `default` — every field empty (the country dropdown on its placeholder),
- *   CTA greyed
- * - `filled`  — country selected and business name typed, CTA live
+ * - `default`    — every field empty (the country dropdown on its placeholder),
+ *   CTA live so the user can press it (GUIDELINES §6-E empty-submit rule)
+ * - `filled`     — country selected and business name typed, CTA live
+ * - `emptyError` — the user pressed the CTA with the form empty: Country and
+ *   Business Name render empty in Core's error state with `requiredError`,
+ *   Tax ID stays clean, CTA greyed (Elena 2026-09-30)
  *
  * Note what `filled` does NOT do: it leaves **Tax ID empty** and still enables
  * the CTA, so the tax identifier is optional and does not gate the lookup
- * (DEVIATIONS #WB-2).
+ * (DEVIATIONS #WB-2). That is also why `emptyError` leaves Tax ID alone.
  */
-export type WatchlistBusinessFormState = 'default' | 'filled';
+export type WatchlistBusinessFormState = 'default' | 'filled' | 'emptyError';
 
 /**
  * One selectable country of registration. Runtime data, never copy — the host
@@ -81,12 +84,23 @@ export interface WatchlistBusinessStrings {
   verifiedLabel: string;
   /** Accessible name for the logo nav row. */
   navLabel?: string;
+  /**
+   * The error row the REQUIRED fields (Country, Business Name) show on the
+   * `emptyError` form state ("This field is required"). Maps to the SDK's
+   * `dynamicForms.fieldRequired` key. GUIDELINES §6-E empty-submit rule.
+   */
+  requiredError: string;
+  /**
+   * Required-field marker ("*"), passed to Core's own `requiredHint` prop on
+   * Country and Business Name (Elena, 2026-09-30).
+   */
+  requiredHint?: string;
 
-  /** watchlist.{default,filled} */
+  /** watchlist.{default,filled,emptyError} */
   form: {
     /** H2 ("Watchlist for business"). */
     title: string;
-    /** H5 — the purple sections draw none, kept for hosts that want one. */
+    /** H5 ("All fields marked with * are required."), explains the asterisk. */
     subtitle?: string;
     country: WatchlistBusinessFieldStrings & {
       /** Search placeholder inside the open menu. */