@vtex/faststore 0.0.8 → 0.0.11

package/dist/docs/access-code-sign-in.md

@@ -1,14 +1,16 @@
-# AccessCodeSignIn (Root + Email + Request + Validate)
+# AccessCodeSignIn (Root + Request + SentNotice + Validate + Resend + CorrectEmail)
 
 **Category:** identity
-**Purpose:** A self-gating, cart-independent passwordless sign-in flow, available from the `anonymous` state onward. `AccessCodeSignInRoot` owns a locally-typed draft email (never written to the cart) and reads the account's provider config (`sessionAuthProviders.accessKeyAuthentication`); it renders nothing once the shopper is already `loggedIn` or the account disables the method. `AccessCodeEmailControl` collects the draft email; `AccessCodeRequestControl` sends the code; `AccessCodeValidateControl` collects and validates it. A successful validate flips `useSession()` to `loggedIn` (and the server persists the validated email onto the cart's profile as a side effect), which makes the whole Root disappear on its own.
+**Purpose:** The access-code (passwordless) method of the sign-in surface. It sits under `SignInRoot`, which reads the account's enabled methods once and owns the one email draft every method shares; `SignInEmailControl` is the email field. `AccessCodeSignInRoot` owns only the request/validate stepper, the `authenticationToken`, the address the code was requested for and the resend deadline. It renders nothing until the account configuration has arrived, when the account disables the access code, while another sign-in method is the active one, and once the shopper is `loggedIn`. `AccessCodeRequestControl` sends the code to the shared draft; `AccessCodeValidateControl` collects the code and validates it against the address it was requested for. While the shopper waits, `AccessCodeSentNotice` names that address, `AccessCodeResendControl` asks for another code once a visible interval has passed and `AccessCodeCorrectEmailControl` takes the shopper back to correct a mistyped address. A successful validate flips `useSession()` to `loggedIn` (and the server persists the validated email onto the cart's profile as a side effect), which makes the whole Root disappear on its own.
 
 ---
 
 ## Visual cues (how to identify in an image)
 
-- An **email input + "send a sign-in code" button**, usable with no prior identification step — this is `AccessCodeEmailControl` + `AccessCodeRequestControl`.
+- An **email input + "send a sign-in code" button**, usable with no prior identification step — this is `SignInEmailControl` (the shared email field) over `AccessCodeRequestControl`.
 - A **one-time-code input + submit button** shown right after activating the send-code button — this is `AccessCodeValidateControl` composing `AccessCodeField`.
+- A **line naming the e-mail address the code went to** above or beside the code input — `AccessCodeSentNotice`.
+- Below the code input, a secondary **"resend" button that is inert and counts down in its own label** ("send again in 42s") until it releases, and a second secondary **"use a different e-mail" button** — `AccessCodeResendControl` and `AccessCodeCorrectEmailControl`. Neither is a primary action.
 - Lives inside the checkout User Identity step as an optional method — never a step the shopper must complete to continue as a guest.
 - No third "blocked" or "rate limited" full-screen error state: those outcomes appear as small inline text under the button/field instead.
 
@@ -19,13 +21,14 @@ Use `AccessCodeSignIn.*` whenever the image shows a passwordless "email me a cod
 ## When to use
 
 - The access-code (passwordless) sign-in method in the checkout User Identity step, for a shopper at any session state short of `loggedIn` — including fully `anonymous`, with no prior email identification.
-- Alongside the password `SignInForm` (FSPG-865), as one of possibly several sign-in methods a page composes — this family never assumes it's the only one.
+- Alongside the password `SignInForm`, as one of the sign-in methods composed under the same `SignInRoot`: both share one email field, and this family shows only while the access code is the method showing.
 
 ## When NOT to use
 
-- A blocking, must-complete-to-continue login gate → this flow is always optional; it self-gates to hidden and never blocks guest checkout.
-- Persisting the draft email as profile data on its own → `AccessCodeEmailControl` never writes to the cart; only a successful `validateAccessCode` does, server-side, as a side effect of authentication. Don't pair it with `EmailIdentificationControl` for the same field — that control's blur-triggered `clientProfileUpdate` is a different, cart-writing identification path.
-- Composing "sign in with a password instead" or "use another email" switch affordances → those are the hosting component's job (FSPG-865), not this family's.
+- A blocking, must-complete-to-continue login gate → this flow is always optional; it hides itself when the account disables the method and never blocks guest checkout.
+- Persisting the draft email as profile data on its own → `SignInEmailControl` never writes to the cart; only a successful `validateAccessCode` does, server-side, as a side effect of authentication. Don't pair it with `EmailIdentificationControl` for the same field — that control's blur-triggered `clientProfileUpdate` is a different, cart-writing identification path.
+- Composing "sign in with a password instead" switch affordances → those are `SignInMethodSwitch` and `SignInMethodOption`, which live in the `sign-in` family, not this one.
+- Rendering outside a `SignInRoot` → every part of this family throws; there is no standalone use.
 
 ---
 
@@ -33,18 +36,24 @@ Use `AccessCodeSignIn.*` whenever the image shows a passwordless "email me a cod
 
 ```
 SessionRoot                              (provides the session tri-state; required ancestor)
-└── AccessCodeSignInRoot                 (data-fs-access-code-sign-in-root; self-gates; owns draft email + step + authenticationToken)
-    ├── AccessCodeEmailControl           (visible only in step 'request'; local draft email, never persisted)
-    ├── AccessCodeRequestControl         (visible only in step 'request')
-    │   └── (button)                     (dispatches $actions.session.requestAccessCode with the draft email)
-    └── AccessCodeValidateControl        (visible only in step 'validate')
-        ├── AccessCodeField              (the code input; value/invalid/errorMessage bound)
-        └── (submit button)              (dispatches $actions.session.validateAccessCode)
+└── SignInRoot                           (reads the account once; owns the shared email draft and the active method; required ancestor)
+    ├── SignInEmailControl               (the one email field, for every method)
+    └── AccessCodeSignInRoot             (data-fs-access-code-sign-in-root; renders while the access code is the active method; owns step + authenticationToken + requested address)
+        ├── AccessCodeRequestControl     (visible only in step 'request')
+        │   └── (button)                 (dispatches $actions.session.requestAccessCode with the shared draft)
+        ├── AccessCodeSentNotice         (visible only in step 'validate'; role="status"; names the pinned address)
+        ├── AccessCodeValidateControl    (visible only in step 'validate')
+        │   ├── AccessCodeField          (the code input; value/invalid/errorMessage bound)
+        │   └── (submit button)          (dispatches $actions.session.validateAccessCode)
+        ├── AccessCodeResendControl      (visible only in step 'validate'; paced by the Root's deadline)
+        │   └── (button)                 (dispatches $actions.session.requestAccessCode with the pinned address)
+        └── AccessCodeCorrectEmailControl (visible only in step 'validate')
+            └── (button)                 (calls the Root's resetToRequest())
 ```
 
-`AccessCodeSignInRoot` **must** have a `SessionRoot` ancestor — `useSession()` throws otherwise. `AccessCodeEmailControl`, `AccessCodeRequestControl`, and `AccessCodeValidateControl` **must** be descendants of `AccessCodeSignInRoot` — all three throw a descriptive error otherwise (runtime-only guard, not compiler-checked).
+Every part of this family **must** be a descendant of `SignInRoot`, which itself needs a `SessionRoot` ancestor — each throws `useSignIn() must be used inside a <SignInRoot> subtree.` otherwise. The five children also **must** be descendants of `AccessCodeSignInRoot` and throw a descriptive error otherwise (runtime-only guards, not compiler-checked; the compiler checks the `sign-in` ancestry of the Root).
 
-`AccessCodeEmailControl` is optional: an identified shopper's `clientProfile.email` pre-fills the Root's draft even without it composed, so a page that only wants the identified-shopper case (skipping straight to `AccessCodeRequestControl`) may omit it — but then an anonymous shopper has no way to type an email, so the request control stays disabled (empty draft never passes its valid-email gate).
+`SignInEmailControl` sits **above** `AccessCodeSignInRoot`, as its sibling, so the email stays anchored while the method below it swaps. It is not required by the compiler, but a page that omits it has no email input anywhere and the request control stays disabled (an empty draft never passes its valid-email gate), except for an identified shopper whose `clientProfile.email` seeds the draft. The other methods compose beside this Root under the same `SignInRoot`; see [[sign-in]].
 
 ---
 
@@ -52,37 +61,79 @@ SessionRoot                              (provides the session tri-state; requir
 
 ### `AccessCodeSignInRoot`
 
+Takes the props of a `div` and no others. It declares no fragment, no `fetchStrategy` and no `$data`; `requiresContext` is `'sign-in'`.
+
+**Gate:** renders its children whenever **all** hold: `useSession().state !== 'loggedIn'`, and, from `useSignIn()`, `resolved`, `accessCodeEnabled` and `method === 'accessCode'`. The three `sign-in` reads are the account's own configuration, so this family never reads `sessionAuthProviders` itself. Until the configuration has arrived, with the access code disabled, while another method is active, and once `loggedIn`, it renders nothing — it returns `null` rather than unmounting, so the stepper survives all of those.
+
+### `AccessCodeRequestControl`
+
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `$data` | `{ clientProfile: { email } \| null, sessionAuthProviders: { accessKeyAuthentication } \| null } \| null` | injected | Colocated `on Query` fragment slice. An unresolved (`null`) read is treated the same as "provider disabled" — the flow stays hidden rather than flashing. |
+| `label` | string | — | Send-code button label. |
+| `pendingLabel` | string | — | Label while the request is in flight; a blank one falls back to `label`. |
+| `onRequested` | `(authenticationToken: string) => void` | — | Fires after a successful request, alongside the Root's own step advance. |
+| `$content` | `ContentValue<typeof AccessCodeRequestControlContent>` | — | The inline message for each refusal of the send. |
+| `$actions` | injected | — | Carries `session.requestAccessCode` (compiler-injected, narrowed to that one method). |
 
-**Data:** declares `fragment AccessCodeSignInData on Query { clientProfile { email } sessionAuthProviders { accessKeyAuthentication } }` with `fetchStrategy: 'reactive'` and `requiresContext: 'session'`.
+Content type `access-code-request-control`, keyed on the refusal's `code`:
 
-**Gate:** renders its children whenever **both** hold: `useSession().state !== 'loggedIn'` and `sessionAuthProviders.accessKeyAuthentication === true`. Available from `anonymous` through `identified`; hides once `loggedIn` or when the account disables the method or the fragment hasn't resolved yet.
+| Content field | Codes | Source (en) |
+|---|---|---|
+| sendLimitMessage | `ACCESS_CODE_SEND_LIMIT` | Too many codes requested. Try again later. |
+| blockedMessage | `BLOCKED` (names no duration: the account service returns none) | This account is blocked. Contact support. |
+| networkErrorMessage | `NETWORK_ERROR`, `MISSING_AUTH_CONTEXT`, and the codes the send never returns (`INVALID_CREDENTIALS`, `INVALID_ACCESS_CODE`) | Something went wrong. Please try again. |
 
-### `AccessCodeEmailControl`
+A code none of these fields words (one a newer server added) shows `networkErrorMessage` and logs `message.unknown-code`. A blank field renders an empty alert and logs `message.missing`, never the server's text.
+
+The button is disabled until the shared draft email (`SignInRoot`'s, typed into `SignInEmailControl`) is a valid, non-empty address (checked with the same rule `EmailIdentificationControl` uses) — never a blocking error state, just an inert affordance.
+
+### `AccessCodeSentNotice`
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | — | Passed to `EmailField`. |
-| `placeholder` | string | — | Passed to `EmailField`. |
-| `invalidEmailMessage` | string | — | `EmailField`'s inline error text; format validation itself is `EmailField`'s own blur-triggered check, never per-keystroke. |
+| `$content` | `ContentValue<typeof AccessCodeSentNoticeContent>` | — | Its `template` message is the confirmation sentence. |
 
-Renders only at the request step. Declares no actions — it never dispatches a mutation, it only writes the Root's local draft state.
+Content type `access-code-sent-notice`:
 
-### `AccessCodeRequestControl`
+| Content field | Arguments | Source (en) |
+|---|---|---|
+| template | `email` (string): the address the code was sent to | We sent an access code to {email}. |
+
+An unauthored `template` renders empty and logs `message.missing`.
+
+Renders only at the validate step, as `<div role="status">`, so the confirmation is announced once. It names the Root's **pinned** address, not the live draft: editing the shared email field afterwards does not change it. Takes the props of a `div` as well.
+
+### `AccessCodeResendControl`
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | — | Send-code button label. |
-| `pendingLabel` | string | — | Label while the request is in flight. |
-| `sendLimitMessage` | string | — | Inline message for `ACCESS_CODE_SEND_LIMIT`. |
-| `blockedMessage` | string | — | Inline message for `BLOCKED`. |
-| `networkErrorMessage` | string | — | Inline message for the synthetic `NETWORK_ERROR`. |
-| `onRequested` | `(authenticationToken: string) => void` | — | Fires after a successful request, alongside the Root's own step advance. |
+| `label` | string | — | Button label once the pace has elapsed. |
+| `pendingLabel` | string | — | Label while the resend is in flight; falls back to `label`. |
+| `onResent` | `(authenticationToken: string) => void` | — | Fires after a successful resend, alongside the Root's own token replacement. |
+| `$content` | `ContentValue<typeof AccessCodeResendContent>` | — | Its `countdownTemplate` message is the button label while the pace has not elapsed; the other fields word each refusal of the send. |
 | `$actions` | injected | — | Carries `session.requestAccessCode` (compiler-injected, narrowed to that one method). |
 
-The button is disabled until the Root's draft email is a valid, non-empty address (checked with the same rule `EmailIdentificationControl` uses) — never a blocking error state, just an inert affordance.
+Content type `access-code-resend`:
+
+| Content field | Arguments | Source (en) |
+|---|---|---|
+| countdownTemplate | `seconds` (integer): the whole seconds left | Resend code in {seconds}s |
+| sendLimitMessage | — | Too many codes requested. Try again later. |
+| blockedMessage | — | This account is blocked. Contact support. |
+| networkErrorMessage | — | Something went wrong. Please try again. |
+
+The three error fields word the same codes as `AccessCodeRequestControl`'s, with the same unknown-code and blank-field behavior. An unauthored `countdownTemplate` renders an empty label and logs `message.missing`.
+
+Renders only at the validate step. There is no interval prop: the pace is the module constant `ACCESS_CODE_RESEND_INTERVAL_SECONDS` (60), because a CMS edit could set it to zero. Takes the props of a `div` as well.
+
+### `AccessCodeCorrectEmailControl`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | Button label. |
+| `onCorrected` | `() => void` | — | Fires after the earlier request has been discarded. |
+
+Renders only at the validate step. Takes the props of a `div` as well.
 
 ### `AccessCodeValidateControl`
 
@@ -92,24 +143,38 @@ The button is disabled until the Root's draft email is a valid, non-empty addres
 | `placeholder` | string | — | Passed to `AccessCodeField`. |
 | `submitLabel` | string | — | Submit button label. |
 | `codeLength` | number | `6` | Disables submit below this length and caps the field maxLength — a UX gate, never a validity claim. |
-| `invalidCodeMessage` | string | — | Inline message for `INVALID_ACCESS_CODE`. |
-| `blockedMessage` | string | — | Inline message for `BLOCKED`. |
-| `missingAuthContextMessage` | string | — | Inline message for `MISSING_AUTH_CONTEXT` (should not occur on a correct flow). |
-| `networkErrorMessage` | string | — | Inline message for the synthetic `NETWORK_ERROR`. |
 | `onValidated` | `() => void` | — | Fires after a successful validate. No local "success" UI is needed — the session flip hides the Root. |
+| `$content` | `ContentValue<typeof AccessCodeValidateControlContent>` | — | The field's message for each refusal of the code. |
 | `$actions` | injected | — | Carries `session.validateAccessCode` (compiler-injected, narrowed to that one method). |
 
+Content type `access-code-validate-control`, keyed on the refusal's `code`:
+
+| Content field | Codes | Source (en) |
+|---|---|---|
+| invalidCodeMessage | `INVALID_ACCESS_CODE` | That code is incorrect or expired. |
+| blockedMessage | `BLOCKED` | This account is blocked. Contact support. |
+| missingAuthContextMessage | `MISSING_AUTH_CONTEXT` (should not occur on a correct flow) | Something went wrong. Please try again. |
+| networkErrorMessage | `NETWORK_ERROR`, and the codes the validate never returns (`INVALID_CREDENTIALS`, `ACCESS_CODE_SEND_LIMIT`) | Something went wrong. Please try again. |
+
+An unknown code shows `networkErrorMessage` and logs `message.unknown-code`; a blank field leaves the field invalid with an empty message and logs `message.missing`.
+
 ---
 
 ## Behavior
 
-- **Draft email ownership:** the Root owns a local `email` string (`useState`), never the cart. It pre-fills from `clientProfile.email` when known (a convenience for an already-identified shopper) — untouched-field re-seed, mirroring `ClientProfileRoot`'s draft/dirty tracking: the re-seed only runs while the flow is still at the `request` step and the draft is untouched, so once the shopper edits the draft or the flow advances past `request`, further profile-email updates never clobber it (and the email can't diverge between `requestAccessCode` and `validateAccessCode`). Editing it dispatches nothing; it is purely the argument `requestAccessCode`/`validateAccessCode` are called with.
+- **The email draft is not this family's:** `SignInRoot` owns it, seeded from `clientProfile.email` until the shopper edits it, and it survives a method change. Editing it dispatches nothing; this family only reads it, at the moment the shopper requests a code.
+- **The requested address is pinned:** `AccessCodeRequestControl` reads the draft into a local before it dispatches, and hands that exact address to the Root together with the token, in one `startValidation(token, requestedEmail)` call. `AccessCodeValidateControl` dispatches with that pinned address and never reads the live draft, because the server rejects a `validateAccessCode` whose email differs from the `requestAccessCode` that issued the token. A shopper edit of the shared field, a profile re-seed of it or a method switch after the request therefore cannot change which address is validated. With a token but no pinned address the submit stays disabled.
+- **The resend pace is armed by a code actually sent:** a successful request and a successful resend each arm a deadline `ACCESS_CODE_RESEND_INTERVAL_SECONDS` (60) seconds away; `AccessCodeResendControl` is disabled until it passes and shows the whole seconds left in its own label. The deadline lives on the Root, not on the control, because the Root returns `null` on a method switch and a control-local countdown would reset with it. The rendered seconds are derived from the deadline, so a throttled background tab cannot make them drift, and the 1-second timer that re-renders them exists only while a deadline is pending. No `aria-live` wraps the countdown: sixty announcements are worse than none. The pace is a courtesy, not a rate limit — the server's `ACCESS_CODE_SEND_LIMIT` is the enforcement, and it renders inline like any other failure. A failed resend sent no code, so it arms nothing.
+- **Resend goes to the pinned address:** `AccessCodeResendControl` dispatches `requestAccessCode` with the Root's `requestedEmail`, never the live draft, and replaces the token through the same `startValidation(token, requestedEmail)`, so the notice, the pin and the new code agree. A resend that resolves after the shopper has gone back (or the session changed) is dropped, not written, so a token is never re-paired with the address that was left. **The same guard has a cost, and it is deliberate:** the resend control compares the token the Root holds against the one it was pressed under, and the control's cleanup clears it when it unmounts. A method switch mid-flight unmounts it, so a resend that was already sent is dropped too: the server has issued and emailed the second token (invalidating the first) while the Root still holds the first. On switching back, a correct code from the second email is dispatched under the first token and rejected as incorrect. It is recoverable (send again once the pace releases) but silent. The guard stays because the alternative re-pins an address the shopper abandoned, which breaks the invariant that a `validateAccessCode` never carries an address other than the one its token was issued for; a refactor that removes the cost must not reintroduce that. The test `drops a resend result when the shopper switches method mid-flight` pins the behaviour.
+- **A request is dropped when the session changed under it:** `AccessCodeRequestControl` does the same for a send still in flight when `useSession().state` changes. The Root has just cleared the stepper for that change, and writing the late result would bind the next shopper on a shared terminal to the address and live token of the one who pressed send. No `onRequested`, no error, no stepper write. A method switch is not a session change, so a request in flight across one still lands, and the shopper finds the code step when they return.
+- **Going back discards four things together:** `AccessCodeCorrectEmailControl` calls the Root's `resetToRequest()`, which resets the step, the `authenticationToken`, the pinned `requestedEmail` and the resend deadline in one transition. A corrected address is therefore a genuinely new request with its own token, and the earlier token can never be submitted against it. The deadline is cleared too, so a shopper who mistyped is not made to wait to send to the address they meant.
 - **Profile persistence happens server-side, on success:** a successful `validateAccessCode` sets the cart's `clientProfileData.email` to the validated email as a side effect of authentication (see the auth module's `completeLoginWithEmail`) — this family itself never calls `clientProfileUpdate`.
 - **No account-existence pre-check:** `AccessCodeRequestControl` dispatches unconditionally once the draft email is valid — no separate lookup call.
-- **Stepper:** the Root owns `step: 'request' | 'validate'` and `authenticationToken: string | null` as local state — the session-action namespace itself holds none of this (a deliberate choice in the FSPG-880 session-actions design).
-- **Every failure is inline:** `ACCESS_CODE_SEND_LIMIT` / `BLOCKED` / `NETWORK_ERROR` surface at the request control; `INVALID_ACCESS_CODE` / `BLOCKED` / `MISSING_AUTH_CONTEXT` / `NETWORK_ERROR` surface on the `AccessCodeField` inside the validate control. The step never changes on error — the shopper can retry or abandon the method and continue as a guest.
-- **Success is entirely reactive:** on a successful validate, the mutation's normalized cache write flips `useSession().state` to `loggedIn` with no refetch and no imperative cache write; the Root's own `useSession()` read reacts and self-gates back to hidden.
-- **Pending states:** both controls expose `data-fs-access-code-request-pending` / `data-fs-access-code-validate-pending` while their dispatch is in flight, disabling their interactive elements — mirrors `CartCouponForm`'s `data-fs-cart-coupon-pending`.
+- **Stepper:** the Root owns `step: 'request' | 'validate'`, `authenticationToken: string | null` and `requestedEmail: string | null` as local state — the session-action namespace itself holds none of this (a deliberate choice in the FSPG-880 session-actions design). The stepper survives a method round-trip: switching to the password and back returns to the code step the shopper left, not to the request. It clears on **any change** of `useSession().state` (`anonymous`, `identified`, `loggedIn`), through the same `resetToRequest()`, so the next shopper on a shared terminal never sees a code step, an address or a token that are not theirs. The trigger is a transition: a shopper who is already `identified` when they request a code keeps their own token. The session resolving is not a change: while it loads, `state` reads `anonymous` as a default, so the transition out of loading clears nothing, and a code sent in that window survives the arrival of the session it belongs to.
+- **The validate control keeps nothing across the back path:** it stays mounted while the stepper is at the request step, so it drops its typed code and its error message on that transition. A re-request therefore opens an empty field with the submit disabled and no message about the earlier request, and a stale code cannot be spent against the lock-out counter with a single click.
+- **Every failure is inline:** `ACCESS_CODE_SEND_LIMIT` / `BLOCKED` / `NETWORK_ERROR` surface at the request control and, for a resend, at the resend control; `INVALID_ACCESS_CODE` / `BLOCKED` / `MISSING_AUTH_CONTEXT` / `NETWORK_ERROR` surface on the `AccessCodeField` inside the validate control. The step never changes on error — the shopper can retry or abandon the method and continue as a guest.
+- **Success is entirely reactive:** on a successful validate, the mutation's normalized cache write flips `useSession().state` to `loggedIn` with no refetch and no imperative cache write; the Root's own `useSession()` read reacts and hides it.
+- **Pending states:** the request, validate and resend controls expose `data-fs-access-code-request-pending` / `data-fs-access-code-validate-pending` / `data-fs-access-code-resend-pending` while their dispatch is in flight, disabling their interactive elements — mirrors `CartCouponForm`'s `data-fs-cart-coupon-pending`.
 
 ---
 
@@ -118,40 +183,19 @@ The button is disabled until the Root's draft email is a valid, non-empty addres
 ```json
 {
   "type": "SessionRoot",
-  "children": [
-    {
-      "type": "AccessCodeSignInRoot",
-      "children": [
-        {
-          "type": "AccessCodeEmailControl",
-          "props": {
-            "label": "Email",
-            "placeholder": "you@example.com",
-            "invalidEmailMessage": "Enter a valid email address."
-          }
-        },
-        {
-          "type": "AccessCodeRequestControl",
-          "props": {
-            "label": "Send a sign-in code",
-            "sendLimitMessage": "Too many codes requested. Try again later.",
-            "blockedMessage": "This account is blocked. Contact support.",
-            "networkErrorMessage": "Something went wrong. Please try again."
-          }
-        },
-        {
-          "type": "AccessCodeValidateControl",
-          "props": {
-            "label": "Enter the code we sent you",
-            "placeholder": "000000",
-            "submitLabel": "Sign in",
-            "invalidCodeMessage": "That code is incorrect or expired.",
-            "networkErrorMessage": "Something went wrong. Please try again."
-          }
-        }
-      ]
-    }
-  ]
+  "children": [{
+    "type": "SignInRoot",
+    "children": [
+      { "type": "SignInEmailControl", "props": { "label": "Email", "placeholder": "you@example.com" } },
+      { "type": "AccessCodeSignInRoot", "children": [
+        { "type": "AccessCodeRequestControl", "props": { "label": "Send a sign-in code" } },
+        { "type": "AccessCodeSentNotice", "props": { "template": "We sent a code to {email}" } },
+        { "type": "AccessCodeValidateControl", "props": { "label": "Enter the code we sent you", "submitLabel": "Sign in" } },
+        { "type": "AccessCodeResendControl", "props": { "label": "Send another code", "countdownTemplate": "Send another code in {seconds}s" } },
+        { "type": "AccessCodeCorrectEmailControl", "props": { "label": "Use a different e-mail" } }
+      ]}
+    ]
+  }]
 }
 ```
 
@@ -159,10 +203,14 @@ The button is disabled until the Root's draft email is a valid, non-empty addres
 
 ## Common mistakes
 
-- **Rendering the controls outside `AccessCodeSignInRoot`.** All three throw a descriptive error immediately.
-- **Persisting the draft email yourself, or pairing this with `EmailIdentificationControl` for the same field.** `AccessCodeEmailControl` never writes to the cart; the server sets the profile email on a successful validate, not before.
+- **Rendering the controls outside `AccessCodeSignInRoot`, or any part outside `SignInRoot`.** Each throws a descriptive error immediately.
+- **Persisting the draft email yourself, or pairing this with `EmailIdentificationControl` for the same field.** `SignInEmailControl` never writes to the cart; the server sets the profile email on a successful validate, not before.
+- **Composing a second email field for this method.** The one `SignInEmailControl` serves every method; this family has no email control of its own.
 - **Adding a blocking error screen for send-limit/blocked outcomes.** Every failure is inline at the control that produced it — there is no third "error" step.
 - **Manually unmounting or resetting the flow after login.** The Root's own `useSession()` read is what hides it; no explicit call is needed.
+- **Pacing the first send.** The pace starts once a code has been sent and never holds the request control, so a shopper who mistyped is not stuck waiting. Do not add a delay to `AccessCodeRequestControl` or to the back path.
+- **Authoring the interval, or promising a time.** The interval is not a prop, and the `blockedMessage` message must not state when access returns: the account service reports a blocked account with no duration.
+- **Reading the live draft for the confirmation or the resend.** Both use the pinned address; the draft can move after the request.
 - **Persisting or logging the `authenticationToken` or the entered code.** Both flow through mutation variables only.
 
 ---
@@ -170,5 +218,6 @@ The button is disabled until the Root's draft email is a valid, non-empty addres
 ## Related
 
 - [[access-code-field]] — the presentational one-time-code particle this family composes.
+- [[sign-in]] — the required `SignInRoot` ancestor: the one account-configuration read, the shared email draft and the active method this family gates on.
 - [[session]] — provides the identification tri-state and the required `SessionRoot` ancestor; also what makes the Root disappear post-login.
 - [[email-identification]] — a separate, cart-writing identification path (blur-triggered `clientProfileUpdate`); do not compose it for the same email field as this family.