@vtex/faststore 0.0.4 → 0.0.6

package/dist/docs/place-order.md

@@ -0,0 +1,157 @@
+# PlaceOrder
+
+**Category:** commerce
+**Purpose:** The checkout's place-order CTA. Runs the three-call payment sequence (start transaction, the holder's direct-to-gateway submission, gateway callback), blocks interaction while it runs, and renders one inline outcome — an error message or a success confirmation — once it settles.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A PlaceOrder block is present when you see:
+
+- A **primary CTA button** at the bottom of a payment/checkout section with a label like "Place order", "Finalizar compra", "Pay now", or similar.
+- The button may appear **greyed out with a spinner or busy indicator** and a label like "Placing order…" — that is still the same `PlaceOrder`, mid-sequence.
+- A **confirmation line or banner below the button** reading something like "Order placed successfully" once the button has been pressed and the order succeeded — this is `PlaceOrder`'s own inline success state, not a separate order-confirmation page.
+- An **inline error line below the button** (e.g. "Enter your payment details before placing the order.") is also part of this same block, not a separate error component.
+
+The image is the source of truth for layout.
+
+---
+
+## When to use
+
+- The final CTA in a credit-card checkout/payment section, once a method (and, for a new card, its fields) has been entered.
+
+## When NOT to use
+
+- Product-page purchase CTA (add to cart) — use [[buy-button]] instead. `PlaceOrder` is checkout-only and drives the payment sequence, not a cart write.
+- Do **not** nest it inside the card-entry form. It must be a **sibling** of card entry and saved cards under the same payment root — nesting it inside the card form would need a second CTA for the saved-card path, which is exactly the mistake this component's placement avoids.
+
+---
+
+## Composition
+
+`PlaceOrder` is a single, self-contained component — no Root/leaf split. It must be placed as a child of `PaymentSectionRoot` or `PaymentSectionController`, as a **sibling** of `CardEntry` / `SavedCards`, never nested inside either:
+
+```
+PaymentSectionRoot (or PaymentSectionController)
+├── PaymentMethodList
+├── CardEntry            (new-card path)
+├── SavedCards            (saved-card path)
+└── PlaceOrder             ← sibling, not a child of CardEntry/SavedCards
+```
+
+Child order reflects visual order. `PlaceOrder` composes under **either** payment root with no change — both provide the same `payment` context and the same submission channel (ADR-0009).
+
+`PlaceOrder` never reads or holds a card field. It calls `usePlaceOrder`, the T13 orchestration hook, which resolves a continuation that `CardEntry`/`SavedCards` registered on a submission channel by the shopper's entry path — this component only knows there is a hook to call, a loading state to block on, and an outcome to render. It also reads `usePayment().draft.billingAddressDifferent` (T11) and forwards it into `usePlaceOrder`, so the gateway descriptor carries whether the shopper picked a different billing address — the one other fact this component touches, and still not a card field.
+
+---
+
+## Components
+
+### PlaceOrder
+
+No sub-components. Renders a button and, once the sequence has settled, one inline outcome region (error or success).
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `"Place order"` | Button label while idle. |
+| `placingLabel` | string | `"Placing order..."` | Button label while the sequence is in flight. |
+| `resumeLabel` | string | `"Complete your order"` | Button label while a surviving attempt offers a resume — the card already left the browser (or its fate is unknown) and the next click finalizes it instead of running the full sequence again. |
+| `successMessage` | string | `"Order placed successfully."` | Shown once the sequence settles with no errors. |
+| `missingSubmissionMessage` | string | `"Enter your payment details before placing the order."` | Shown when `placeOrder()` is invoked with no registered submission for the current path (e.g. the shopper never finished entering a card). |
+| `missingMethodMessage` | string | `"Choose a payment method before placing the order."` | Shown when no payment method is selected yet. |
+| `invalidTransactionMessage` | string | `"Unable to start the payment. Please try again."` | Shown when `startTransaction` resolves incomplete transaction data. |
+| `networkErrorMessage` | string | `"Unable to complete the request. Please try again."` | Shown for an infrastructure-level failure reaching the payment gateway action. |
+| `missingDocumentMessage` | string | `"Enter your document before placing the order."` | Shown when the selected method requires a cardholder document and none is set. |
+| `invalidDocumentMessage` | string | `"Enter a valid document before placing the order."` | Shown when the typed cardholder document fails validation. |
+| `unavailableMethodMessage` | string | `"Choose another payment method before placing the order."` | Shown instead of the two document messages above when the selected method calls for a cardholder document the page is not showing — a method the card form cannot pay with, or one outside the payment root's `group` — so the shopper has to choose another payment method. |
+| `unsavedBillingAddressMessage` | string | `"Save your billing address before placing the order."` | Shown when the shopper declined "same as delivery" but never saved a custom billing address. |
+| `invalidCardDataMessage` | string | `"Enter valid card details before placing the order."` | Shown when the new-card draft itself fails validation before ever reaching the gateway. |
+| `invalidSecurityCodeMessage` | string | `"Enter a valid security code before placing the order."` | Shown when a saved-card submission is refused for a missing or invalid CVV. |
+| `gatewayErrorMessage` | string | `"Unable to complete the payment. Please try again."` | Shown when the payment gateway itself refuses the submitted card. |
+| `inFlightMessage` | string | `"This order is already being placed. Please wait."` | Shown when a click lands on an order-placement attempt whose own sequence is still running — a transaction this instance did not open, and which nothing here may finalize or re-run. |
+| `unconfirmedMessage` | string | `"We could not confirm your order yet. Your payment may still be processing, so please do not pay again."` | Shown when the payment was handed to the gateway but the order could not be confirmed, so it may still be processing. Renders in its own `role="status"` node, never in the error alert. |
+| `successHref` | string | *(none)* | Route **template** navigated to after a successful placement. The literal `{orderGroup}` is replaced with the placed order's group, percent-encoded. **Opt-in and success-gated**: no default is provided on purpose, so an absent prop keeps today's behavior byte-for-byte, and the navigation is requested only once an attempt settles with no errors and a non-null order group — never on a refusal. |
+
+Every message prop above is resolved by the `code` of the client-synthesized `PaymentUserError` this CTA renders — in its alert, or in its status node for `unconfirmedMessage` — never by which component produced the error. A `PaymentUserError` whose code this component does not author (a server-returned code) renders that error's own `message` unchanged.
+
+**Data:** declares its own thin `fragment PlaceOrderData on Query` selecting `payment.selectedMethodId`, `payment.selectedInstallment`, and `payment.methods { id groupName }` — the exact slice the orchestration hook needs, no more. **Actions:** declares `actions: { payment: ['startTransaction', 'gatewayCallback'], analytics: ['track'] }`. Must be inside a payment root (`requiresContext: 'payment'`).
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "children": ["payment-method-list", "card-entry", "place-order"]
+  },
+  "payment-method-list": { "type": "PaymentMethodList" },
+  "card-entry": { "type": "CardEntry" },
+  "place-order": {
+    "type": "PlaceOrder",
+    "props": {
+      "label": "Place order",
+      "placingLabel": "Placing order...",
+      "successMessage": "Order placed successfully.",
+      "successHref": "/checkout/order-placed/{orderGroup}"
+    }
+  }
+}
+```
+
+`successHref` is shown here for reference only — it is opt-in (see the props table above), and no store composes it today. It must be a path on the store's own origin (root-relative, like the example above, or an absolute URL on the same origin) — an absolute URL on a different origin, a protocol-relative URL, or a non-http(s) scheme is refused rather than navigated to.
+
+---
+
+## Common mistakes
+
+- **Nesting `PlaceOrder` inside `CardEntry` or `SavedCards`.** It must be a sibling of both under the same payment root, so one CTA serves both the new-card and saved-card paths.
+- **Placing `PlaceOrder` outside any `PaymentSectionRoot`/`PaymentSectionController`.** It throws at render — there is no payment context or submission channel to resolve.
+- **Confusing it with `BuyButtonButton`.** `BuyButtonButton` adds a product to the cart on a PDP; `PlaceOrder` runs the payment sequence in checkout. They are never composed together.
+- **Expecting a redirect or a 3D Secure challenge.** v1 is the direct-API mode only — the shopper stays on the page and the outcome renders inline. The redirect mode is phase 2.
+
+---
+
+## Known limitations
+
+- **A remount reads the surviving attempt instead of losing it — but the attempt itself does not survive a page reload.** T29 (`specs/make-an-order-attempt-survive-a.md`) gave the place-order sequence an identity-and-phase record on the payment context, above this component's own mount, alongside `placing`. Closing and reopening a `Dialog`/`Drawer` popup with no `keepMounted` no longer resets it: a settled attempt renders disabled with no further calls (`succeeded` is derived from the record, not only from this instance's own `attempted`/`userErrors`), and an attempt whose card already reached the gateway before the remount offers a resume (`resumeLabel`) that finalizes the same transaction — never a fresh `startTransaction` or a second card submission. This closes the case this bullet used to attribute to "a settled-order read model that outlives the overlay (T16/T17)": both are merged, and the limitation still stood, because neither one ever touched this component's own mount-scoped guard, which is what actually caused the duplicate-order risk. What is still not covered: a full page reload loses the attempt (no `sessionStorage` or equivalent persists it today — T29's own OQ-3), and the direct-to-gateway POST's abort budget (30s, `sdk/payment/gateway.ts`) is an unconfirmed placeholder pending a number from payments (OQ-7).
+- **Sibling placement (never nested inside `CardEntry`/`SavedCards`) is a convention, not something the compiler enforces.** `requiresContext: 'payment'` only fails a build with no payment-providing ancestor at any depth; it cannot detect that this component was nested one level too deep. Getting this wrong compiles clean and still leaves the other entry path with no CTA at all (see `specs/place-order.md`'s Open items).
+- **`successHref` navigates with `router.replace`, not `router.push`.** The payment step is removed from the history stack, so the Back button from the confirmation page returns to whatever preceded payment, not to the payment step itself — deliberate (placing an order is terminal, and a live place-order CTA one Back press away risks a duplicate transaction), but a divergence from this package's other redirect-on-success component, `CartRedirectOnAdd`, which uses `push`.
+- **A `successHref` authored without the literal `{orderGroup}` placeholder fails closed.** The component refuses to navigate rather than sending every shopper to the same unresolvable URL, and logs a `console.warn` outside production. This is a store-authoring mistake to fix in the template, not a runtime condition to handle.
+- **A `successHref` that resolves off the store's own origin also fails closed.** An absolute URL on a different origin, a protocol-relative URL (`//host/...`), or a non-http(s) scheme is refused rather than navigated to, with the same dev-only `console.warn`. This keeps a store schema from turning the CTA into a redirect off the storefront right after a real purchase.
+- **`successHref` is inert until a store authors it.** As of this writing no store composes it — see `specs/navigate-the-shopper-to-the-order.md` for the follow-up that wires Reserva's payment page to it, gated on the confirmation page's read path being fixed first.
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `PlaceOrder` (root `div`) | Layout wrapper stacking the button and the outcome region | `flex flex-col gap-[8px] items-start` |
+| Button (`data-fs-place-order-button`) | The CTA itself — full-width pill, disabled/busy states | `inline-flex items-center justify-center w-full h-[44px] px-[20px] bg-[#C8102E] text-white rounded-[4px] text-[14px] font-bold uppercase cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed` |
+| Error (`data-fs-place-order-error`) | Inline error line, `role="alert"` | `text-[13px] text-[#C0392B]` |
+| Unconfirmed (`data-fs-place-order-unconfirmed`) | Inline notice that the order could not be confirmed yet, `role="status"` | `text-[13px] text-[#8A6D3B]` |
+| Success (`data-fs-place-order-success`) | Inline success line, `role="status"` | `text-[13px] text-[#1E8E3E]` |
+| Success order id (`data-fs-place-order-success-order-id`) | The placed order's id, inside the success line | `font-mono text-[12px] text-[#666666]` |
+
+Always include `disabled:` styling on the button — it disables automatically while the sequence runs and again once it succeeds.
+
+Styled example:
+
+```json
+{
+  "place-order": {
+    "type": "PlaceOrder",
+    "style": ["flex", "flex-col", "gap-[8px]", "items-start"],
+    "props": { "label": "Place order" }
+  }
+}
+```
+
+---
+
+## Related
+
+- [[payment]] — `PaymentSectionRoot` / `PaymentSectionController`, the roots `PlaceOrder` must compose under.
+- [[buy-button]] — the PDP purchase CTA and this component's named precedent for the blocking loading-state pattern (disabled + `aria-busy` + a `-pending` hook).

package/dist/docs/save-card.md

@@ -0,0 +1,186 @@
+# SaveCard
+
+**Category:** commerce
+**Purpose:** Opt-in control for authenticated shoppers to save the card they are currently entering for a future purchase, with a custom nickname. Off by default. Checking it also grants the account's data-storage consent; unchecking it never revokes that consent.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Use these signals to detect that a SaveCard block is present. Position on the page is irrelevant for
+detection — it can appear anywhere inside a payment section. The image is the source of truth for
+layout.
+
+A SaveCard block contains any combination of:
+
+- A single **checkbox with a label reading something like "Save this card for next time"**, sitting
+  inside (or directly beside) a credit-card entry form.
+- Immediately below or beside the checkbox, **small, secondary-styled helper text** mentioning storing
+  or saving personal data — present only when the account has not already granted that consent.
+- When the checkbox is shown checked in the image, a **second text input labeled something like "Card
+  nickname" / "Name this card"** appears directly below it.
+- This block always sits **inside a checkout payment section**, near card-number fields or a saved-cards
+  list — never on a product page, cart page, or as a standalone marketing checkbox.
+
+If the image shows a single opt-in checkbox near card-entry fields, with an optional name/nickname text
+field conditionally shown, use `SaveCard`. If the checkbox instead controls a newsletter or general
+data-sharing preference with no relation to a card, that is `NewsletterOptInControl` /
+`SavePersonalDataOptInControl` (`ClientPreferencesRoot`'s Controls), not this component.
+
+---
+
+## When to use
+
+- Inside a checkout's payment section, as a sibling of the card-entry fields (and/or the saved-cards
+  list), so a logged-in shopper can opt in to saving the card they are currently using.
+
+## When NOT to use
+
+- A general "share my data with this store" consent, unrelated to a specific card → use
+  `SavePersonalDataOptInControl` (under `ClientPreferencesRoot`) instead. Different data ownership,
+  different section, and — critically — that surface's own `$data` read has a live defect (always reads
+  as unset); do not use it as a reference implementation for a new read.
+- A newsletter opt-in → use `NewsletterOptInControl` instead.
+- The list of already-saved cards → use `SavedCards` / `SavedCardOption` instead. `SaveCard` only offers
+  to save the card currently being entered; it never lists or selects an existing saved card.
+- Outside a payment section, or outside an identity/session context → `SaveCard` requires **both** a
+  `PaymentSectionRoot`/`PaymentSectionController` ancestor and a `SessionRoot` ancestor. Placing it
+  without either is a build/runtime error, not a silent no-op.
+- For a guest checkout flow with no login step at all → `SaveCard` self-gates to render nothing for
+  anyone who is not logged in; do not wrap it in an extra visibility condition in the schema.
+
+---
+
+## Composition
+
+`SaveCard` is a single leaf — no root, no required children, no sub-components:
+
+```
+PaymentSectionRoot (or PaymentSectionController)
+├── CardEntry            (sibling — new-card fields)
+├── SavedCards            (sibling — saved-card picker)
+├── Installments           (sibling — installment selector)
+└── SaveCard                (sibling — this component)
+```
+
+`SaveCard` must be a descendant of `PaymentSectionRoot` or `PaymentSectionController` (it reads and
+writes the shopper's in-progress card draft) **and** must also have a `SessionRoot` ancestor somewhere
+in the same composed page/layout tree (it reads the identity session state to self-gate). Place it as a
+**sibling** of `CardEntry` and `SavedCards`, never nested inside either — one `SaveCard` instance covers
+whichever entry path the shopper is on, the same way `Installments` does.
+
+It self-gates to render nothing while the session is loading, for a guest, or for an
+identified-but-not-logged-in shopper — safe to include speculatively inside any payment section, but for
+image-to-schema work only include it when the image actually shows the checkbox described above.
+
+It also renders nothing while the card payment is collapsed — the persisted selection is a method that
+is not a card, or one the section does not serve, and a composed `PaymentMethodList` can bring the card
+form back (see [[payment]]). The save-card flag and nickname stay on the draft, so the control comes back
+as the shopper left it.
+
+---
+
+## Components
+
+### SaveCard
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `"Save this card for next time"` | The toggle's own label text. |
+| `nicknameLabel` | string | `"Card nickname"` | Label for the nickname field; rendered only while checked. |
+| `nicknamePlaceholder` | string | — | Optional placeholder for the nickname field. |
+| `consentNoticeLabel` | string | `"Checking this also lets us store your personal data for future purchases."` | Shown beside the toggle while the account has not already granted the data-storage consent. |
+| `disabled` | boolean | `false` | Disables both the toggle and the nickname field. |
+
+**Data:** declares its own `fragment SaveCardData on Query` (selects `Query.clientPreferences.savePersonalData`
+only — a single boolean, not a card field) — a small, thin fragment the compiler merges into the page
+query alongside `PaymentSectionRoot`'s own selection; no explicit `dataSources` entry needed.
+`fetchStrategy: 'reactive'` — the consent notice updates live from the cache, no refetch.
+
+**The toggle never seeds from the standing consent.** It always starts unchecked, even when the account
+has already granted `savePersonalData` elsewhere — saving *this* card is always a fresh, per-transaction
+choice.
+
+**Checking the toggle** records the shopper's intent for this card *and* grants the account's
+data-storage consent in the same action; the nickname field appears immediately below. **Unchecking**
+withdraws only this transaction's intent — it never revokes a consent an unrelated control may have
+granted. On a rejected consent write, the first error message renders inline.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "children": ["card-entry", "saved-cards", "installments", "save-card"]
+  },
+  "save-card": {
+    "type": "SaveCard",
+    "props": { "label": "Save this card for next time" },
+    "style": ["flex", "flex-col", "gap-2"]
+  }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Inventing `SaveCardControl` or `SaveCardToggle`.** The component is `SaveCard`.
+- **Nesting `SaveCard` inside `CardEntry` or `SavedCards`.** It must be a sibling of both under the
+  same `PaymentSectionRoot`, exactly like `Installments`.
+- **Placing `SaveCard` without a `SessionRoot` ancestor somewhere in the page.** It requires session
+  context to self-gate and throws without one.
+- **Expecting the checkbox to start checked because the shopper already granted data-storage consent
+  elsewhere.** It always starts unchecked — the standing consent and the per-transaction save intent
+  are independent by design.
+- **Expecting unchecking to revoke a previously granted consent.** It deliberately does not; see
+  `specs/save-card-control.md` Decision 1 for the full rationale.
+- **Using `SaveCard` to render a general privacy/data-sharing consent form.** It is scoped to a single
+  boolean and a nickname for the card currently being entered — use `ClientPreferencesRoot`'s Controls
+  for anything broader.
+- **Expecting a full card number or CVV field.** The fragment structurally selects neither, and no prop
+  accepts one — this component never touches sensitive card data.
+
+---
+
+## Styling
+
+Single DOM root wrapping the toggle field, an optional nickname field, and an optional inline error.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `SaveCard` (root `div`) | Stacks the toggle field, nickname field, and error | `flex flex-col gap-[8px]` |
+| Consent notice (`data-fs-save-card-consent-notice`) | De-emphasized helper text | `text-[12px] text-[#666666]` |
+| Nickname field wrapper (`data-fs-save-card-nickname-field`) | Spacing above the field | `mt-[8px]` |
+| Inline error (`data-fs-save-card-error`) | Warning-toned alert text | `text-[12px] font-medium text-[#B00020]` |
+| Placing (`data-fs-save-card-placing`) | Present while an order-placement sequence is in flight (T28) — distinct from `data-fs-save-card-pending`, which this component already emits for its own local consent dispatch; the root is also `inert` and `aria-disabled` while placing | `opacity-60 cursor-not-allowed` |
+
+Styled example:
+
+```json
+{
+  "save-card": {
+    "type": "SaveCard",
+    "style": ["flex", "flex-col", "gap-2"]
+  }
+}
+```
+
+There is no per-field styling hook beyond the particles' own `data-fs-checkbox-*` / `data-fs-field-*`
+attributes (`Checkbox.Root`/`Checkbox.Indicator`, `Field.Root`/`Field.Label`/`Field.Control`) — style
+the checked state via Base UI's own `data-checked` on `Checkbox.Root`, per the `style-components` skill.
+
+---
+
+## Related
+
+- [[saved-cards]] — the list of already-saved cards, and the CVV re-entry for one; `SaveCard` only
+  offers to save the card currently being entered, never lists an existing one.
+- [[installments]] — the closest structural sibling: a single leaf requiring `PaymentSectionRoot`, no
+  Root/leaf split, sibling placement under the same section.
+- [[client-preferences]] — owns the broader `savePersonalData` / `optinNewsLetter` consent surface;
+  `SaveCard` reads the same underlying field but through its own fragment, never by composing under
+  `ClientPreferencesRoot` (whose own read of that field has a live, unrelated defect).

package/dist/docs/saved-cards.md

@@ -0,0 +1,218 @@
+# SavedCards
+
+**Category:** commerce
+**Purpose:** Renders the checkout payment step's saved-card picker — a radio list of a shopper's stored cards (network, last four digits, label), with expired cards shown but disabled, and a CVV field that appears once a card is selected.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Use these signals to detect that a SavedCards block is present. Position on the page is irrelevant for detection — it can appear anywhere in a payment/checkout step. The image is the source of truth for layout.
+
+A SavedCards block contains any combination of:
+
+- A **list of radio rows**, each showing a **card network name or logo** (Visa, Mastercard, …) plus a **masked number** like `•••• 4242` or `**** 4242`.
+- A **custom label** next to a row, e.g. *"Meu cartão"* / *"Personal card"* — shopper-assigned, not always present.
+- A row rendered **visually muted or with a "expired" tag**, still present in the list but not clickable.
+- A **short numeric input appearing next to or below the selected row**, typically labeled *"CVV"* / *"Security code"* / *"CVC"* — this appears only once a row is checked. Its digits render **obscured** (dots), same visual family as a password field, even though it is not one under the hood (see Components below, `SavedCardCvvField`, for why).
+- A **"pay with a new card" link or button** rendered as a sibling entry, not a row inside this list — that sibling is a different component (`CardEntry`), not part of this block.
+
+If the image shows a **radio list of masked card numbers with network names**, use `SavedCards`. Do not use it for a single card-entry form (no radio choice) — that is `CardEntry`.
+
+---
+
+## When to use
+
+- The checkout/payment step, for an authenticated shopper with one or more stored cards.
+- Anywhere a shopper picks among previously saved payment methods before completing a purchase.
+
+## When NOT to use
+
+- A blank new-card entry form (number, expiry, holder name fields) → use `CardEntry` instead; `SavedCards` never renders those fields.
+- A payment-method picker across networks/methods (Visa vs. Pix vs. Cash) → use `PaymentMethodList`, the sibling method-level picker under the same `PaymentSectionRoot`. `SavedCards` only distinguishes stored *cards*, not payment *methods*.
+- An address book / saved shipping addresses list → use the equivalent shipping-address components; visually similar (a radio list of saved records) but a different domain.
+
+---
+
+## Composition
+
+`SavedCards` is the list root and must be a descendant of `PaymentSectionRoot` or `PaymentSectionController`. `SavedCardOption` is the per-card row template placed directly inside it. `SavedCardCvvField` is placed inside `SavedCardOption` so the CVV appears once that row is selected.
+
+```
+PaymentSectionRoot (or PaymentSectionController)
+├── PaymentMethodList                (sibling — network/method picker)
+├── SavedCards
+│   └── SavedCardOption              (per-card template, repeated once per stored card)
+│       └── SavedCardCvvField        (appears only for the selected, CVV-required row)
+└── CardEntry                        (sibling — "use a new card", not a child of SavedCards)
+```
+
+Child order reflects visual order. `SavedCardOption` and `SavedCardCvvField` are the only two valid parent/child pairs this block defines; everything else (`PaymentMethodList`, `CardEntry`) is a sibling under the same `PaymentSectionRoot`, never nested inside `SavedCards`.
+
+**Composition rules:**
+
+- `SavedCards` must be inside `PaymentSectionRoot` or `PaymentSectionController`. Outside either, it throws.
+- `SavedCardOption` must be a direct child of `SavedCards`. It renders `null` when its row's data has not resolved.
+- `SavedCardCvvField` must be inside `SavedCardOption`. Outside it, it throws. Omitting it means a shopper can select that card but never submit a payment with it — always include it.
+- `CardEntry` ("use a new card") is a **sibling** of `SavedCards`, never a child or a row inside it — there is no "toggle" prop that switches this list into new-card mode.
+
+---
+
+## Components
+
+### SavedCards
+
+List root. Renders a radio group of the shopper's saved cards. Renders its container even when the list is empty or still loading (a hooked, not zero-height, region). It renders nothing at all while the card payment is collapsed — the persisted selection is a method that is not a card, or one the section does not serve, and a composed `PaymentMethodList` can bring the card form back (see [[payment]]). Its rows' CVV fields unmount with it, which clears any code typed there. To reach a saved card from a method that is not a card, the shopper chooses the card option first, which brings the list back.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `legend` | string | `"Saved cards"` | The radio group's accessible name, rendered as a visible fieldset legend above the rows (T38). An authored empty or whitespace-only string falls back to this default rather than rendering a nameless group. |
+
+Which cards exist is always real data (`Query.payment.savedCards`) — never author them as props.
+
+**Data:** declares `fragment SavedCardsListData on Query`. The compiler merges it into the page query — no explicit `dataSources` entry needed.
+
+### SavedCardOption
+
+One saved card as a radio row: network name, masked last four (`•••• 4242`), and the shopper's own label when set. Disabled (not selectable) when the card is expired — the row still renders so the shopper knows the card exists.
+
+No props beyond standard container attributes (`className`, `children`). Must be a direct child of `SavedCards`.
+
+**Data:** declares `fragment SavedCardOptionData on Query`, independently resolved per row (a write to one saved card only re-renders that row, not the whole list).
+
+### SavedCardCvvField
+
+The CVV re-entry field for its row. Renders nothing until that specific row is selected and the card requires a CVV; then renders a numeric input (digits only, capped at 4 characters) whose digits render **obscured** (dots) via an inline `-webkit-text-security: disc` style once the code is fully typed, with a helper line underneath it (`securityCodeDescription`, defaulting to "The 3-4 digit number on your card"; an empty string renders nothing). Wires the direct-to-gateway payment submission for the saved-card path the moment it is composed — the CVV is never sent to the storefront's own backend. A blank or under-three-digit code refuses before the place-order sequence opens a transaction, moving focus back to this input; the message reaches the shopper through the place-order CTA's own alert, not an inline field error here.
+
+The mask engages on the third digit and stays on for a fourth. Three, because a saved card carries no per-network security-code length — the row's data has a display network name, not a `cvvMask` — so there is no signal here that tells a 3-digit network apart from Amex's 4, and the field's own accept-either floor is the only length available. Masking at the floor never leaves a complete code legible on either kind of card; a 4-digit code is simply already masked when its last digit arrives. Below three digits the code renders in the clear, so a shopper can read back what they just typed, and backspacing below three reveals what is left. Same rule and same shared predicate as `CardEntry`'s CVV field, which resolves its length from the detected method instead.
+
+`type="password"` was tried first and reverted: a real Chrome browser offered to save the security code to its password manager (synced to the signed-in account) the instant the field carried that type, which PCI-DSS forbids for a value that must not be retained past authorization. The input stays `type="text"`, and no caller-passed `type` can override that. The CSS property above obscures the digits without tripping that heuristic, since it never touches `type`; a caller-passed `style` cannot remove it either — once the code is complete the mask always merges in last, so no caller can hold it off past that point. Supported in Chromium and WebKit (and, per T70's spec, Firefox 114+ — unverified on this branch); an engine without it renders the digits in the clear, same as before this mechanism existed — not a regression. The declaration is an inline style, which outranks a class-based rule from a compound swatch at normal importance — but not one that reaches for Tailwind's `!` important modifier: swatch tokens reach `className` verbatim with no validation, so a store that authors an arbitrary-property utility ending in `!` can still unmask the field. Nothing in this package closes that hole; it is accepted rather than fixed (masking spec, OQ-1).
+
+No props beyond standard input attributes (`className`), `securityCodeLabel` (accessible name), and `securityCodeDescription` (helper text). Must be inside `SavedCardOption`.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "saved-cards": {
+    "type": "SavedCards",
+    "children": ["saved-card-option"]
+  },
+  "saved-card-option": {
+    "type": "SavedCardOption",
+    "children": ["saved-card-cvv"]
+  },
+  "saved-card-cvv": { "type": "SavedCardCvvField" }
+}
+```
+
+### In context (inside a payment section, alongside the method picker and "use a new card")
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "children": ["payment-method-list", "saved-cards", "card-entry"]
+  },
+  "payment-method-list": { "type": "PaymentMethodList" },
+  "saved-cards": {
+    "type": "SavedCards",
+    "children": ["saved-card-option"]
+  },
+  "saved-card-option": {
+    "type": "SavedCardOption",
+    "children": ["saved-card-cvv"]
+  },
+  "saved-card-cvv": { "type": "SavedCardCvvField" },
+  "card-entry": { "type": "CardEntry" }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Nesting `CardEntry` ("use a new card") inside `SavedCards`.** It is a sibling under the same `PaymentSectionRoot`, never a row or a child of this list.
+- **Inventing a `mode` or `showNewCard` prop on `SavedCards` to switch to new-card entry.** There is no such prop — "use a new card" is a separate component composed alongside this one, not a display mode of it.
+- **Omitting `SavedCardCvvField` inside `SavedCardOption`.** Without it, a shopper can select a saved card but the place-order flow has nothing to submit with — always include it.
+- **Placing `SavedCardOption` or `SavedCardCvvField` outside their required ancestor.** `SavedCardOption` must be inside `SavedCards`; `SavedCardCvvField` must be inside `SavedCardOption`. Only `SavedCardCvvField` throws when misplaced. A misplaced `SavedCardOption` does **not** throw — it silently renders `null` (no ancestry check of its own; it just has no resolved row data to show), so a page can ship with a silently empty saved-cards list. This is an authoring convention, not a compiler or runtime guarantee: `requiresContext` is satisfied by *any* ancestor providing that context at *any* depth, not specifically a direct parent, and there is no mechanism that forbids a given ancestor either.
+- **Passing a `savedCards` prop, a card list, or a `cvv` value as an authored prop.** Every field here is real data from `Query.payment.savedCards` or shopper-typed local state — never a schema-bindable prop. Neither component in this block declares a `cvv`, `cardNumber`, or `bin` prop of any kind.
+- **Using `SavedCards` for the network/method picker.** That is `PaymentMethodList` — a sibling under the same root, distinguishing payment *methods* (Visa vs. Pix), not stored *cards*.
+- **Wrapping `SavedCards` in a page with no `PaymentSectionRoot` ancestor.** It requires the payment context; use only inside a composed payment section.
+
+---
+
+## Known limitations
+
+- **A saved card with `cvvRequired: false` can be selected but never paid with — open item, not fixed in this pass.** `SavedCardCvvField` renders nothing when `cvvRequired` is `false`, and it is the only component that registers the `'saved-card'` submission continuation. For such a card, today: the row renders selected (`data-fs-saved-card-option-selected` present, `aria-checked="true"`), but `usePaymentSubmission().resolve('saved-card')` returns `null`, so `usePlaceOrder` resolves `MISSING_PAYMENT_SUBMISSION` and Place Order fails — with no CVV field ever offered and no way for the shopper to proceed. This is data-driven (`SavedCard.cvvRequired` passes through the account's own `useCvvForAuthorization`), not an authoring mistake, and it is deliberately left open rather than guessed at: the fix depends on whether the payment gateway's direct-to-gateway POST accepts `fields.validationCode: ''` for a `useCvvForAuthorization: false` account, or whether that account type needs the legacy's separate no-CVV mutation instead — a payments question this repository cannot answer on its own. See `specs/saved-cards.md`'s Open Questions and Assumptions for the full record.
+
+---
+
+## Styling
+
+Style `SavedCards` as a vertical stack of rows, each row as a horizontal line (radio indicator, network, last four, label), and the CVV field as a small, short numeric input that appears inline with the selected row.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `SavedCards` | Stacks the rows | `flex flex-col gap-[8px] w-full` |
+| Fieldset (`data-fs-saved-cards-fieldset`, native `<fieldset>`) | Wraps the legend and the radio rows (T38) — gives the group its visible, accessible name | usually left unstyled; a merchant border/padding choice |
+| Legend (`data-fs-fieldset-legend`, native `<legend>`) | The group's visible name, from `legend` | `text-[14px] font-medium text-[#1A1A1A]` |
+| `SavedCardOption` | One row — indicator, network, last four, label in a line; muted/dashed when expired | `flex items-center gap-[8px] p-[12px] border border-[#E0E0E0] rounded-[8px] data-[fs-saved-card-option-expired]:opacity-50 data-[fs-saved-card-option-selected]:border-[#000000]` |
+| `SavedCardCvvField` | The short CVV input | `w-[64px] text-[14px] px-[8px] py-[6px] border border-[#CCCCCC] rounded-[4px]` |
+| CVV helper text (`data-fs-saved-card-cvv-description`) | Small muted line next to/under the CVV input | `text-[12px] text-[#666666]` |
+| Placing (`data-fs-saved-cards-placing`) | Present on `SavedCards`' own root while an order-placement sequence is in flight (T28); the whole list — including every `SavedCardOption` row and its `SavedCardCvvField` — is `inert` and `aria-disabled` at that point, transitively, with no attribute of their own | `opacity-60 cursor-not-allowed` |
+
+Styled example:
+
+```json
+{
+  "saved-cards": {
+    "type": "SavedCards",
+    "children": ["saved-card-option"],
+    "style": ["flex", "flex-col", "gap-[8px]", "w-full"]
+  },
+  "saved-card-option": {
+    "type": "SavedCardOption",
+    "children": ["saved-card-cvv"],
+    "style": [
+      "flex", "items-center", "gap-[8px]", "p-[12px]",
+      "border", "border-[#E0E0E0]", "rounded-[8px]",
+      "data-[fs-saved-card-option-expired]:opacity-50",
+      "data-[fs-saved-card-option-selected]:border-[#000000]"
+    ]
+  },
+  "saved-card-cvv": {
+    "type": "SavedCardCvvField",
+    "style": ["w-[64px]", "text-[14px]", "px-[8px]", "py-[6px]", "border", "border-[#CCCCCC]", "rounded-[4px]"]
+  }
+}
+```
+
+---
+
+## Accessibility Contract
+
+**What the platform promises:** `SavedCards`' radio group carries a visible, programmatic accessible
+name (`legend`, default `"Saved cards"`) — a screen-reader user hears these rows are a choice between
+stored cards, not payment methods. An authored empty or whitespace-only `legend` falls back to the
+default rather than shipping a nameless group. Each row keeps its own accessible name from its network
+and masked last four; the CVV re-entry field carries its own `securityCodeLabel` as an `aria-label`
+and, when `securityCodeDescription` is set, an `aria-describedby` association to the helper text. The
+group is a native `<fieldset>`/`<legend>` pair, not only `aria-label`. Keyboard: the group is one Tab
+stop — Tab lands on the checked row, and the arrow keys move the checked row and change the selection.
+A default `:focus-visible` outline is painted from the platform's own stylesheet.
+
+**What the platform does not promise:** colour contrast. `SavedCards` (and every other payment
+component) exposes `data-fs-*` hooks so a merchant can author contrast-compliant swatches, but no
+component in this package measures or guarantees any contrast ratio — that is the merchant's theme, not
+this platform.
+
+---
+
+## Related
+
+- [[payment]] — `PaymentSectionRoot` / `PaymentMethodList`: the required ancestor and the sibling network/method picker. `SavedCards` cannot render outside a `PaymentSectionRoot` (or `PaymentSectionController`).
+- `CardEntry` — the "use a new card" entry point (new-card capture, a different task's deliverable). Always a sibling of `SavedCards`, never nested inside it.
+- [[shipping-address]] — its saved-address list is the closest visual precedent (a radio list of stored records with an expired/non-selectable-style state), from a different domain (addresses, not cards).