@vtex/faststore 0.0.7 → 0.0.10

package/dist/docs/card-entry.md

@@ -70,7 +70,9 @@ While collapsed, `CardEntry` still answers a place-order attempt: it keeps its s
 
 Collapsing clears the security code field, and only the security code. The card number, holder name, and expiration survive, so a shopper who switches method and switches back finds what they typed — no credit-card component in this package retains a security code across a visibility change.
 
-The authored `disabled` prop is independent of this: a store that freezes the form with `disabled` sees no change, and a collapsed form may also be `disabled` — neither implies the other.
+The authored `disabled` prop is independent of the collapse: a store that freezes the form with `disabled` sees no change, and a collapsed form may also be `disabled` — neither implies the other.
+
+In the checkout, the card number, holder name, expiration, and security code are cleared after every outcome in which the card target ran: the card POST resolved clean, resolved with errors or threw, or the target refused before any request. They are kept when the submission was refused before the target ran (the form's own check, a refused or untrusted transaction, the submit gate, no method selected) so the shopper can fix them.
 
 ---
 
@@ -78,23 +80,23 @@ The authored `disabled` prop is independent of this: a store that freezes the fo
 
 `CardEntry` renders the detected card network's icon at runtime, once the typed number matches a configured payment method's `validator.numberRegex` — the icon name is computed in component code, not read from a schema prop, so the compiler's prop-type-driven icon collection never sees it.
 
-**Any store composing `CardEntry` (or `SavedCards` / `SavedCardOption`) must declare the five network icon names in `global.icons.include`:**
+**Any store composing `CardEntry` (or `SavedCards` / `SavedCardOption`) must declare the six network icon names in `global.icons.include`:**
 
 ```json
 {
   "icons": {
-    "include": ["amex", "diners", "elo-card", "mastercard", "visa"]
+    "include": ["amex", "diners", "discover", "elo-card", "mastercard", "visa"]
   }
 }
 ```
 
-**If the store's `global.json` already has an `icons` object, extend it — do not replace it.** A store that already sets `"collection"` (or `"aliases"` / `"collections"`) must keep that key alongside the new `include`:
+**If the store's `foundation.json` already has an `icons` object, extend it — do not replace it.** A store that already sets `"collection"` (or `"aliases"` / `"collections"`) must keep that key alongside the new `include`:
 
 ```json
 {
   "icons": {
     "collection": "ph",
-    "include": ["amex", "diners", "elo-card", "mastercard", "visa"]
+    "include": ["amex", "diners", "discover", "elo-card", "mastercard", "visa"]
   }
 }
 ```
@@ -103,6 +105,34 @@ Copying the first snippet verbatim over an existing `icons` object silently drop
 
 Omitting `include` entirely is silent too. The network icon renders as an empty 24×24 box instead of the card mark.
 
+## Store setup: response headers
+
+The card number and security code are typed into `CardEntry`'s raw fields and POSTed from the browser straight to the VTEX payment gateway, so the page that composes it needs a policy that names the vault host the card is POSTed to, forbids framing the page, and narrows what the page may load and call. The generator ships no default: the store declares it in `foundation.json` under `responseHeaders`, scoped by `routes` to the page that composes `CardEntry`.
+
+```json
+{
+  "responseHeaders": [
+    {
+      "routes": ["/checkout"],
+      "headers": {
+        "Content-Security-Policy": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' https://acme.vtexvault.com; frame-ancestors 'none'; base-uri 'self'; object-src 'none'",
+        "Referrer-Policy": "strict-origin-when-cross-origin"
+      }
+    }
+  ]
+}
+```
+
+- **The vault host in `connect-src` is `https://{account}.vtexvault.com`, for the account the store serves.** That is the `NEXT_PUBLIC_ACCOUNT` the store is built with, which is not always `store.account` in `foundation.json`. Write the served account, with no wildcard: `https://*.vtexvault.com` would let a compromised script send the card to any tenant's vault.
+- **A policy that names the legacy payments host (`vtexpayments.com.br`) makes the browser block the card POST.** The order cannot be placed and nothing else on the page reports why. The generated app calls its own GraphQL at the relative `/api/graphql`, so `'self'` covers it; a store built with an absolute `NEXT_PUBLIC_STOREFRONT_API_URL` must add that origin.
+- **A rule's `routes` must name the page that composes `CardEntry`**, as the page's `route` spells it (`/checkout`, `/reserva/checkout/payment`). Renaming that page fails the compile instead of dropping the policy. A page added later that composes `CardEntry` carries nothing until its route is added to the rule.
+- **`script-src 'unsafe-inline'` is a known limit, and the policy does not stop injected script from sending the card off the page.** A static header cannot carry a nonce, so the inline scripts Next.js emits need it, and script injected into the page runs with the same rights. `connect-src` closes only `fetch`, XHR, beacons and WebSocket. The policy still leaves three channels open to any https host: an image request (`img-src https:`, which the page needs for catalog images), a form submission (no `form-action`) and a navigation (CSP cannot restrict one). What today's ruled policy does give is the vault origin pinned, no `'unsafe-eval'`, a page no other site can frame (`frame-ancestors 'none'`) and no `http:` or wildcard source. It does not replace keeping untrusted script off the payment page.
+- **`frame-ancestors 'none'`** blanks the page inside any iframe, including an editor preview.
+- **reCAPTCHA needs the anti-bot origins, and the ruled policy above does not declare them yet.** The challenge frame and script come from `https://www.google.com` and `https://www.gstatic.com`, the origins `sdk/anti-bot` declares. The frame is blocked by `default-src 'self'` (no `frame-src`) and the script by `script-src 'self' 'unsafe-inline'`, so both need the anti-bot origins. The stores add them together with whoever wires `getAntiBotToken`; the header check accepts a `frame-src` that names only those two origins and rejects any other.
+- **Under `next dev` the served `script-src` also carries `'unsafe-eval'`; production does not.** React Refresh evaluates code in the browser, so the generated `next.config.ts` adds `'unsafe-eval'` to the `script-src` of every Content-Security-Policy it serves only when `NODE_ENV` is `development` (what `next dev` sets), which is what `pnpm dev:example` runs. Any build whose `NODE_ENV` is not `development` (the default for `next build` and `next start`) serves the declared policy byte for byte, so the live header check still runs against them: a dev response shows a `script-src` the store never declared, which `scripts/assert-payment-page-headers.mjs` rejects by design, so run that script against `next start`.
+
+To check a served page, run `node scripts/assert-payment-page-headers.mjs --url <page url> --vault-host https://<account>.vtexvault.com`.
+
 ---
 
 ## Components
@@ -124,7 +154,8 @@ The only component. No internal sub-parts are separately schema-addressable.
 | `cvvPlaceholder` | string | — | CVV field placeholder. |
 | `cvvDescription` | string | `"The 3-4 digit number on your card"` | Helper text under the CVV field. Empty string renders nothing. |
 | `numberRequiredMessage` | string | `"Card number is required"` | Shown when the card-number field is left blank. |
-| `numberInvalidMessage` | string | `"Enter a valid card number"` | Shown for a Luhn-invalid number, or one that matches no configured method — the same string covers both. |
+| `numberInvalidMessage` | string | `"Enter a valid card number"` | Shown for a Luhn-invalid number, or one a configured network claims only as a prefix (the wrong length, or two networks at once). |
+| `networkNotAcceptedMessage` | string | `"This card is not from a network the store accepts"` | Shown for a Luhn-valid number that no configured network claims at all. |
 | `holderNameRequiredMessage` | string | `"Cardholder name is required"` | Shown when the holder-name field is left blank and the detected method requires it. |
 | `expirationRequiredMessage` | string | `"Expiration date is required"` | Shown when the expiration field is left blank and the detected method requires it. |
 | `expirationInvalidMessage` | string | `"Enter a valid expiration date"` | Shown for a structurally malformed `MM/YY`. |
@@ -208,7 +239,7 @@ Style `CardEntry`'s root as a vertical stack of fields, matching a typical card
 | Field inputs (`data-fs-field-control`) | The bordered text input | `border border-[#CCCCCC] rounded-[6px] px-[12px] py-[10px] text-[15px] w-full` |
 | Field errors (`data-fs-field-error`) | Inline validation message, small and red | `text-[12px] text-[#C8102E] mt-[4px] block` |
 | CVV helper text (`data-fs-card-entry-cvv-description`) | Small muted line under the CVV field | `text-[12px] text-[#666666] mt-[4px] block` |
-| Placing (`data-fs-card-entry-placing`) | Present while an order-placement sequence is in flight (T28); the whole root is also `inert` and `aria-disabled` at that point, so style this hook rather than relying on pointer events alone | `opacity-60 cursor-not-allowed` |
+| Placing (`data-fs-card-entry-placing`) | Present while an order-placement sequence is in flight (T28), and while the order attempt is resume-only (its card may already have been sent, so the fields do not accept input) until the attempt is freed; the whole root is also `inert` and `aria-disabled` at that point, so style this hook rather than relying on pointer events alone | `opacity-60 cursor-not-allowed` |
 | Collapsed (`data-fs-card-entry-collapsed`) | Present on the styled root while the card payment is collapsed — the persisted selection is a method this section does not serve or one that is not a card, and a picker is composed to un-hide it (see Reveal and collapse); the root is also `inert`. **No transition or animation can run on it**: the actual hide is a `hidden` attribute one level up, on an unstyled wrapper this node cannot reach with any class, and an ancestor's `display:none` removes the whole subtree from rendering the instant it applies, before any transition on a descendant could ever paint. Use this hook only for one-shot conditional styling of the (already-unrendered) subtree, never for an entrance/exit animation | `opacity-60` |
 
 Styled minimal example:

package/dist/docs/card-summary.md

@@ -0,0 +1,175 @@
+# Card Summary
+
+**Category:** content
+**Purpose:** A saved card's identity: its network's mark, its label or else its network name, a mask, and its last four digits, as parts the schema arranges.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A card-network logo (Visa, Mastercard, American Express, Diners, Elo) beside a short text.
+- A name such as `Visa` or a shopper's own label such as `Company card`.
+- A masking symbol (`••••`, `****`) followed by four digits: `•••• 1234`.
+- Usually one line per card, repeated in a list or inside a selectable row.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- Describing one saved card wherever it appears: the account's saved-cards list, a removal confirmation, the checkout's saved-card row.
+
+## When NOT to use
+
+- The store's accepted payment methods as a strip of logos → [[payment-methods]].
+- Typing a new card → the checkout's card entry; this particle never takes a full number or a security code.
+- A card's expiry or usability state → the row that owns the card renders it beside this particle.
+
+---
+
+## Composition
+
+```
+<row that provides 'card-summary'>   ← e.g. AccountSavedCardItem
+└── CardSummary
+    ├── CardSummaryMark      (default)
+    ├── CardSummaryName      (default)
+    ├── CardSummaryMask      (default)
+    └── CardSummaryDigits    (default)
+```
+
+`CardSummary` with no children renders the four parts in that order. Composing children replaces the default: any order, any subset. Child order is the visual order and the screen-reader order. The parts can also sit directly in the providing row, without the `CardSummary` wrapper.
+
+Every part requires the `card-summary` context, and only a matter row that owns card data provides it in a schema. The row wraps its children in `CardSummaryRoot` in code and declares `'card-summary'` in its own `providesContext`, so the schema composes the parts directly in the row. Context matching is by contract, not by component name. Stories, tests, and hand-written JSX render `CardSummaryRoot` themselves.
+
+A part outside any provider fails the build with a `ContextConstraintError`, and throws at runtime outside the compiler.
+
+---
+
+## Components
+
+### CardSummaryRoot
+
+Code only: it has no catalog entry and is never placed in a schema, because a schema cannot supply the card. Renders no element. Publishes the card to the parts. Keeps only the trailing four digit characters of `lastDigits`; the raw value never reaches a part.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `network` | string | — | The network's display name from the platform, e.g. `Visa`. Data, not a schema prop. |
+| `lastDigits` | string | — | The card's last digits. Only four ever render. Data, not a schema prop. |
+| `label` | string \| null | — | The shopper's own name for the card. Shown in place of the network name when non-blank. Data, not a schema prop. |
+
+### CardSummary
+
+The wrapper, `<span data-fs-card-summary>`. Carries `data-fs-card-summary-network="<icon>"` when the network has a mark and `data-fs-card-summary-labeled` when a label is present. No props.
+
+### CardSummaryMark
+
+The network's mark. No props. Decided by the data, never by which other parts are composed:
+
+| Card | Renders |
+|---|---|
+| Mapped network, no label | The glyph, decorative (the name says the network). |
+| Mapped network, labelled | The glyph plus the network name as screen-reader text. |
+| Unmapped network, no label | Nothing. |
+| Unmapped network, labelled | The network name as visible text (`data-fs-card-summary-network-name`), never another network's glyph. |
+
+So a labelled card still tells a sighted shopper and a screen reader its network, even when the schema drops `CardSummaryName`. An unlabelled card does not: its glyph is decorative and `CardSummaryName` is what announces the network, so the network is announced exactly once in the default composition.
+
+### CardSummaryName
+
+The label, or else the network name. Nothing when both are blank. Read-only. No props.
+
+### CardSummaryMask
+
+Decoration for the hidden digits, always `aria-hidden`. Nothing when empty or when the card has no digits.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `mask` | string | `••••` | The masking symbol. An empty string renders nothing. |
+
+`children` replace `mask`, e.g. an `Icon`. Keep them inline: the particle sits inside labels and paragraphs.
+
+### CardSummaryDigits
+
+The last four digits. Screen readers hear "ending in 1234" (message id `fs/card.ending-in`, in en-US, es-ES, and pt-BR); the visible digits are hidden from them. Nothing when the card has no digits. No props.
+
+---
+
+## Networks and the `icons.include` obligation
+
+The mark comes from `CARD_NETWORK_ICON_BY_KEY` in `card-network.ts`, the one map every card surface shares. A network name matches after lowercasing and removing every character outside `a-z`: `Visa`, `Mastercard`, `Amex`, `American Express`, `Diners`, `Diners Club`, and `Elo` have marks. Matching is exact, so `Visa Electron` or `Elo Debit` render by name, without a mark. `cardNetworkIcon(name)` returns the icon name or `null`.
+
+**Every mapped name must be registered.** The network comes from data, so the compiler cannot see which glyphs a route needs. A store that renders `CardSummaryMark` lists the names under `icons.include` in its `foundation.json`; it is JSON, so it cannot import `CARD_NETWORK_ICON_NAMES`, and the names are written out:
+
+```json
+{ "icons": { "include": ["visa", "mastercard", "amex", "diners", "elo-card"] } }
+```
+
+A name the store never registered renders an empty `<svg>`: no build error and no runtime error, just a missing mark. All five are base-dialect names, so they resolve in any store whatever its icon collection.
+
+---
+
+## Canonical schema example
+
+The account's row provides the context; the schema arranges the parts:
+
+```json
+{
+  "saved-card-item": { "type": "AccountSavedCardItem", "children": ["card-summary"] },
+  "card-summary": { "type": "CardSummary", "style": ["inline-flex", "items-center", "gap-[8px]"] }
+}
+```
+
+Digits first, with another mask:
+
+```json
+{
+  "saved-card-item": { "type": "AccountSavedCardItem", "children": ["card-digits", "card-mask", "card-mark", "card-name"] },
+  "card-digits": { "type": "CardSummaryDigits" },
+  "card-mask": { "type": "CardSummaryMask", "props": { "mask": "****" } },
+  "card-mark": { "type": "CardSummaryMark" },
+  "card-name": { "type": "CardSummaryName" }
+}
+```
+
+## Common mistakes
+
+- **`CardSummaryNumber`, `CardSummaryLastFour`.** The correct name is `CardSummaryDigits`.
+- **`CardSummaryBrand`, `CardSummaryFlag`, `CardSummaryIcon`.** The correct name is `CardSummaryMark`.
+- **`CardSummaryLabel`.** The correct name is `CardSummaryName`; it shows the label or else the network name.
+- **Writing the bullets inside `CardSummaryDigits`.** The mask is its own part, `CardSummaryMask`.
+- **Placing `CardSummaryRoot` in a schema, or passing `network`, `lastDigits`, or `label` as schema props.** The card is data from the row that provides `card-summary`; the Root is not in the catalog.
+- **Composing a part outside a row that provides `card-summary`.** It fails the build.
+- **Dropping `CardSummaryMark` or `CardSummaryDigits` from a custom composition.** The PRD requires both beside a card; only the default composition guarantees them.
+- **Composing `CardSummaryMark` without `CardSummaryName`.** On an unlabelled card the glyph is decorative and the name is what announces the network, so a screen reader hears only "ending in 1234". Keep `CardSummaryName` whenever `CardSummaryMark` is composed.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `CardSummary` | Lines the parts up | `inline-flex items-center gap-[8px]` |
+| `CardSummaryMark` | Mark box; size the glyph through it | `inline-flex items-center [&_svg]:h-[24px] [&_svg]:w-[32px]` |
+| `CardSummaryName` | Name typography | `text-[14px] font-medium text-[#1F1F1F]` |
+| `CardSummaryMask` | Mask color and spacing | `text-[14px] tracking-[2px] text-[#6B6B6B]` |
+| `CardSummaryDigits` | Digit typography | `text-[14px] tabular-nums text-[#1F1F1F]` |
+
+`CardSummaryRoot` renders no element and is not styled.
+
+```json
+{
+  "card-summary": { "type": "CardSummary", "style": ["inline-flex", "items-center", "gap-[8px]"], "children": ["card-mark", "card-name", "card-mask", "card-digits"] },
+  "card-mark": { "type": "CardSummaryMark", "style": ["inline-flex", "items-center", "[&_svg]:h-[24px]", "[&_svg]:w-[32px]"] },
+  "card-name": { "type": "CardSummaryName", "style": ["text-[14px]", "font-medium", "text-[#1F1F1F]"] },
+  "card-mask": { "type": "CardSummaryMask", "style": ["text-[14px]", "tracking-[2px]", "text-[#6B6B6B]"] },
+  "card-digits": { "type": "CardSummaryDigits", "style": ["text-[14px]", "tabular-nums", "text-[#1F1F1F]"] }
+}
+```
+
+---
+
+## Related
+
+- [[payment-methods]]: the store's accepted payment methods as a strip of logos; not a saved card.
+- [[address-summary]]: the same Root-plus-parts shape, for a postal address.
+- [[icon]]: renders the mark from the base icon dialect.

package/dist/docs/cardholder-document.md

@@ -1,7 +1,7 @@
 # CardholderDocument
 
 **Category:** commerce
-**Purpose:** A single tax-document input (CPF) for the checkout payment step, shown or hidden and marked required by the currently selected payment method's server-driven configuration.
+**Purpose:** A single tax-document input for the checkout payment step. The store's country picks the document (SSN for the United States, CPF for Brazil, SIN for Canada, RFC for Mexico); the currently selected payment method's server-driven configuration shows or hides it and marks it required.
 
 ---
 
@@ -11,12 +11,12 @@ Use these signals to detect that a CardholderDocument block is present. Position
 
 A CardholderDocument block is:
 
-- A **single labeled text input**, formatted with dots and a dash like `123.456.789-01` (the CPF mask).
-- Labeled **"CPF"** or a similar tax-document label — never "Card number", "Expiration", or "CVV".
+- A **single labeled text input**, formatted like `123.456.789-01` (CPF), `123-45-6789` (SSN), `046-454-286` (SIN) or `ABCD010101AB1` (RFC).
+- Labeled **"CPF"**, **"SSN"**, **"SIN"**, **"RFC"** or a similar tax-document label — never "Card number", "Expiration", or "CVV".
 - Not accompanied by a network icon, a "•••• 1234" masked number, or any card-brand logo — those belong to `CardEntry` or `SavedCards`, not this block.
 - Sometimes marked with a required indicator (an asterisk or similar) next to its label; sometimes not — both are valid, since requiredness is server-driven per payment method.
 
-If the image shows a **card-entry form with one extra plain text field formatted like a Brazilian tax ID**, use `CardholderDocument`. Do not use it for the shopper's account/profile document field — that is a different, identity-step component this block never composes with or reads from.
+If the image shows a **card-entry form with one extra plain text field formatted like a tax ID (CPF, SSN, SIN or RFC)**, use `CardholderDocument`. Do not use it for the shopper's account/profile document field — that is a different, identity-step component this block never composes with or reads from.
 
 ---
 
@@ -28,7 +28,7 @@ If the image shows a **card-entry form with one extra plain text field formatted
 
 - The shopper's saved profile/identity document (a client-identity or user-profile field) → use the identity-step document component instead. `CardholderDocument` is a payment-time value, deliberately separate — it never reads or writes the stored profile document, because the epic's RFC records that the two may differ.
 - A generic, data-agnostic tax-document input with no server-driven presence/requiredness → use the `DocumentField` particle directly instead; `CardholderDocument` exists specifically to wire that particle to the selected payment method's validator.
-- More than one document type or country → out of scope today. Only CPF renders; see this component's own spec for the recorded deferral.
+- A business document (CNPJ, EIN, BN, the corporate RFC) → not offered; only the four person documents render.
 
 ---
 
@@ -50,7 +50,7 @@ Child order reflects visual order. There is no parent/child relationship for thi
 **Composition rules:**
 
 - Must be inside `PaymentSectionRoot` or `PaymentSectionController`. Outside either, it throws.
-- Renders `null` (no DOM at all) when the selected payment method's validator does not mark a document displayable, or when no method is selected yet. This is normal, not an error — most methods most of the time render nothing here.
+- Renders `null` (no DOM at all) when the selected payment method's validator does not mark a document displayable, when no method is selected yet, or when the store's country has no document type (an unlisted country, or no country data). This is normal, not an error — most methods most of the time render nothing here.
 - Also renders `null` 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]]) — whatever that method's own validator says. When the card comes back, the field re-seeds from the value already typed.
 - Takes no children; passing any is a no-op.
 
@@ -60,18 +60,20 @@ Child order reflects visual order. There is no parent/child relationship for thi
 
 ### CardholderDocument
 
-The field itself. Renders the `DocumentField` particle for CPF, with presence and requiredness resolved from `usePayment().selectedMethod.validator` (`documentDisplayable` / `documentRequired`) rather than from any prop.
+The field itself. Renders the `DocumentField` particle for the type `usePayment().countryDocumentType` resolves (`USA` SSN, `BRA` CPF, `CAN` SIN, `MEX` RFC), with presence and requiredness resolved from `usePayment().selectedMethod.validator` (`documentDisplayable` / `documentRequired`) rather than from any prop.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | `string` | `'CPF'` | The field's visible label. |
-| `placeholder` | `string` | `'000.000.000-00'` | Shown in the empty input as a format hint. |
-| `errorMessage` | `string` | `'Invalid CPF'` | Shown inline when the typed value fails CPF check-digit validation on blur. |
+| `label` | `string` | the type's name (`SSN`, `CPF`, `SIN`, `RFC`) | The field's visible label. |
+| `placeholder` | `string` | the type's own (`000-00-0000`, `000.000.000-00`, `000-000-000`, `AAAA000000AAA`) | Shown in the empty input as a format hint. |
+| `errorMessage` | `string` | `'Invalid '` + the type's name | Shown inline when the typed value fails the type's validation on blur. |
 | `disabled` | `boolean` | `false` | Disables the input without hiding it — independent of the data-driven presence gate. |
 
-No `documentType` prop — this build supports CPF only. No `required` prop — requiredness is always read from the selected method's validator, never authored.
+No `documentType` prop — the store's country decides it. No `required` prop — requiredness is always read from the selected method's validator, never authored.
 
-**Data:** declares no `fragment` of its own. It reads `selectedMethod`, `draft`, and `setDraftDocument` off the ambient `payment` context that `PaymentSectionRoot` / `PaymentSectionController` already fetches for.
+**Data:** declares no `fragment` of its own. It reads `selectedMethod`, `countryDocumentType`, `draft`, and `setDraftDocument` off the ambient `payment` context that `PaymentSectionRoot` / `PaymentSectionController` already fetches for.
+
+**Focus on refusal:** while the field is on screen and not `disabled`, it registers itself so that when `PlaceOrder` refuses an order because the document is missing or malformed, keyboard focus moves to the `<input>`. The reason stays in `PlaceOrder`'s existing alert. Focus moves only on the refused click, and never for a refusal the gateway returned. With the field absent or `disabled`, nothing moves.
 
 ---
 
@@ -98,7 +100,7 @@ No `documentType` prop — this build supports CPF only. No `required` prop —
 ## Common mistakes
 
 - **Nesting `CardholderDocument` inside `CardEntry`.** It is a sibling under the same `PaymentSectionRoot`, never a child — `CardEntry` does not accept children.
-- **Passing a `documentType`, `required`, `countryCode`, or `document` prop.** None exist. Document type is fixed to CPF; requiredness and presence are always read from the selected method's validator, never authored; the typed value is not a prop at all — it flows into the shared payment draft internally.
+- **Passing a `documentType`, `required`, `countryCode`, or `document` prop.** None exist. The document type follows the store's country; requiredness and presence are always read from the selected method's validator, never authored; the typed value is not a prop at all — it flows into the shared payment draft internally.
 - **Using this component for the shopper's saved profile document.** That is a different, identity-step field this component never reads from or writes to — the two are intentionally separate, even for the same shopper.
 - **Expecting it to render outside a `PaymentSectionRoot` / `PaymentSectionController`.** It throws — the same requirement every other payment leaf (`CardEntry`, `Installments`, `SavedCards`, …) has.
 - **Treating a blank render as broken.** Most of the time, for most payment methods, this component correctly renders nothing — that is the "not displayable" state, not a bug.
@@ -107,7 +109,7 @@ No `documentType` prop — this build supports CPF only. No `required` prop —
 
 ## Known limitations
 
-- **CPF only.** The underlying read model carries no document-type or country signal (see this component's own spec for the full, measured deferral) — a store outside Brazil cannot get a different document type from this component today.
+- **Four person documents, by store country.** The country comes from `Payment.storeCountryCode` and `Payment.countries`. A store whose country resolves to no document type shows no field, refuses nothing and sends no document. A document typed while the field was shown is posted only while the selected method still asks for one and the country still resolves a type; the draft itself is not cleared. `label`, `placeholder` and `errorMessage` have no catalog default (the right copy depends on the country), so leave them unset unless the store serves one country.
 - **Server-driven requiredness renders the field correctly and is also enforced at submit time — but not by this component or by `CardEntry`.** This component marks the field required when the validator says so; a required-but-blank or malformed value (whether or not required) blocks Place Order client-side, before any transaction opens, **while the selected method's validator also says the document is displayable**. That gate lives in `matter/payment/use-payment-submit-gate.ts` (T24) and is consumed by `PlaceOrder`, not by this component or by `CardEntry`'s own `validateDraft` — this component's only job stays publishing `draft.document` via `setDraftDocument`. When the *currently* selected method's validator says `documentDisplayable: false`, the gate treats `draft.document` as inert either way (fix pass, findings R1/S4/S5): there is no field on screen for the shopper to read a leftover value from or correct it in, whether that value is left over from a previously selected, displayable method or simply blank. See `specs/cardholder-document-submit-gate.md` for the gate's full contract.
 
 ---

package/dist/docs/cart-destination.md

@@ -0,0 +1,238 @@
+# CartDestination
+
+**Category:** content
+**Purpose:** The Cart page's delivery location. `CartDestinationRoot` reads where the cart is delivered and writes a new destination from a postal code alone, so the free-shipping bar beside it follows. It has two modes: read ("Entregando em 01310-100 · São Paulo, SP" plus a change link) and edit (a postal code field with "Atualizar" and "Cancelar").
+
+---
+
+## Visual cues (how to identify in an image)
+
+Look in the **top of the cart page's main column**, above the free-shipping bar and the line items:
+
+- A single line reading **"Entregando em"** (or "Delivering to") followed by a **postal code and city, state**, beside a link such as **"Trocar localização?"**.
+- With no destination yet, the line reads a prompt such as **"Informe seu CEP"** beside the same link.
+- Pressing the link swaps the line for **one masked postal code field**, an **"Atualizar"** button, a **"Cancelar"** button and a short help line.
+
+The image is the source of truth for layout.
+
+A postal code control in the **site header** is not this component: that is `RegionRoot`.
+
+---
+
+## When to use
+
+- On the **Cart page**, once, where the design shows where the cart is delivered and lets the shopper change it.
+
+## When NOT to use
+
+- **In the header** — that is `Region`, which only sets a cookie and never touches the cart.
+- **For the full delivery address on checkout** — that is `ShippingAddressFieldset`.
+- **For a shipping-cost quote on a product page or in the cart drawer** — that is `ShippingSimulator`; it quotes and writes nothing.
+- More than once per page: two roots mean two drafts over the same destination.
+
+---
+
+## Composition
+
+`CartDestinationRoot` provides the `'cartDestination'` context; every other part declares `requiresContext: 'cartDestination'`.
+
+```
+CartDestinationRoot                      (provides 'cartDestination'; starts in read mode)
+├── CartDestinationRead                  (read mode only)
+│   ├── CartDestinationValue             (the destination, once set)
+│   ├── CartDestinationUnset             (the store's invitation, while none is set)
+│   │   └── Text                         ("Informe seu CEP")
+│   └── CartDestinationChange            (opens edit mode)
+└── CartDestinationForm                  (edit mode only)
+    ├── CartDestinationPostalCodeControl
+    ├── CartDestinationSubmit
+    ├── CartDestinationCancel
+    ├── Text                             (the help line, placed by the store)
+    └── CartDestinationError
+```
+
+Child order reflects visual order. The store cannot open edit mode from outside: the mode is local to the root, and the destination shown always comes from the cart, never from what was typed.
+
+---
+
+## Components
+
+### CartDestinationRoot
+
+Reads the cart destination reactively and broadcasts it, the edit-mode flag, the draft and the write state. Starts in read mode, also with no destination.
+
+**Data:** declares `fragment CartDestinationData on Query` (`shipping { id address { postalCode country city state } }`) with `fetchStrategy: 'reactive'`. It selects no name and no street.
+
+**Write:** declares `actions: { shipping: ['setAddress'] }`. A submit sends `{ postalCode, country }` and nothing else; the cart keeps its recipient name. The response updates the destination and the free-shipping bar through the cache.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `defaultCountry` | string | `"BRA"` | Used while the cart has no address; the address country wins |
+
+### CartDestinationRead
+
+Renders its children only in read mode. No props.
+
+### CartDestinationValue
+
+The destination as prefix, postal code, city and state, each in its own element. Renders nothing while loading or when none is set.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `prefix` | string | — | For example `"Entregando em"`; authored content wins |
+
+**Content model** (`cart-destination-value`): `prefix`.
+
+### CartDestinationUnset
+
+Renders its children only once the destination resolved and none is set. Place the invitation inside it, within `CartDestinationRead`. No props.
+
+### CartDestinationChange
+
+Button that opens edit mode, with `aria-expanded` tied to the mode. Styled as a link by the store.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | For example `"Trocar localização?"`; authored content wins |
+
+**Content model** (`cart-destination-change`): `label`.
+
+### CartDestinationForm
+
+Renders only in edit mode. Enter in the field runs the submit, which flags an incomplete or unchanged draft instead of sending it. Opening it focuses the field; leaving it focuses `CartDestinationChange`.
+
+### CartDestinationPostalCodeControl
+
+A `PostalCodeField` bound to the draft, empty every time edit mode opens.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `mask` | string | the country's mask | `99999-999` for BRA; also the mask Submit checks the draft against, and the typed value must still match the country's pattern, so a mask the pattern rejects (9 digits in BRA, for example) keeps Submit disabled |
+| `label` | string | — | Field label |
+| `placeholder` | string | — | Field placeholder |
+| `invalidMessage` | string | — | Shown for a draft that is incomplete or fails the country's pattern |
+
+### CartDestinationSubmit
+
+Writes the typed postal code. Disabled until the draft is complete for the field's mask (the control's `mask`, else the country's), matches its pattern and differs from the current postal code, and while a write is pending (`aria-busy`). A pending write also waits for any cart line write in flight.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | For example `"Atualizar"` |
+| `pendingLabel` | string | — | Shown while the write is in flight |
+
+**Content model** (`cart-destination-submit`): `label`, `pendingLabel`.
+
+### CartDestinationCancel
+
+Closes edit mode, discards the draft and any error, and writes nothing. Disabled while a write is pending.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | For example `"Cancelar"` |
+
+**Content model** (`cart-destination-cancel`): `label`.
+
+### CartDestinationError
+
+An alert announcing a failed write; renders nothing otherwise. A refused postal code and a network failure reach the client as the same error, so author one message that covers both.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `genericMessage` | string | — | Authored message; the server's own is the fallback |
+
+**Content model** (`cart-destination-error`): `genericMessage`.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "cart-destination": {
+    "type": "CartDestinationRoot",
+    "style": ["flex", "flex-col", "gap-2", "text-sm"],
+    "children": ["cart-destination-read", "cart-destination-form"]
+  },
+  "cart-destination-read": {
+    "type": "CartDestinationRead",
+    "style": ["flex", "items-center", "gap-2"],
+    "children": ["cart-destination-value", "cart-destination-unset", "cart-destination-change"]
+  },
+  "cart-destination-value": { "type": "CartDestinationValue", "props": { "prefix": "Entregando em" }, "style": ["flex", "gap-1"] },
+  "cart-destination-unset": { "type": "CartDestinationUnset", "children": ["cart-destination-invitation"] },
+  "cart-destination-invitation": { "type": "Text", "props": { "as": "span", "children": "Informe seu CEP" } },
+  "cart-destination-change": {
+    "type": "CartDestinationChange",
+    "props": { "label": "Trocar localização?" },
+    "style": ["text-[#2563eb]", "font-medium", "cursor-pointer"]
+  },
+  "cart-destination-form": {
+    "type": "CartDestinationForm",
+    "style": ["flex", "flex-col", "gap-2"],
+    "children": [
+      "cart-destination-control",
+      "cart-destination-submit",
+      "cart-destination-cancel",
+      "cart-destination-help",
+      "cart-destination-error"
+    ]
+  },
+  "cart-destination-control": { "type": "CartDestinationPostalCodeControl", "props": { "label": "CEP" } },
+  "cart-destination-submit": { "type": "CartDestinationSubmit", "props": { "label": "Atualizar", "pendingLabel": "Atualizando…" } },
+  "cart-destination-cancel": { "type": "CartDestinationCancel", "props": { "label": "Cancelar" } },
+  "cart-destination-help": {
+    "type": "Text",
+    "props": { "as": "span", "children": "Após confirmar, a barra volta ao modo leitura com o novo CEP e cidade." }
+  },
+  "cart-destination-error": {
+    "type": "CartDestinationError",
+    "props": { "genericMessage": "Não foi possível usar esse CEP. Confira o número e tente de novo." },
+    "style": ["text-sm", "text-red-700"]
+  }
+}
+```
+
+---
+
+## Styling hooks
+
+| Attribute | On | Present when |
+|---|---|---|
+| `data-fs-cart-destination` | `CartDestinationRoot` | Always |
+| `data-fs-cart-destination-editing` | `CartDestinationRoot` | Edit mode is open |
+| `data-fs-cart-destination-pending` | `CartDestinationRoot` | A write is in flight |
+| `data-fs-cart-destination-read` | `CartDestinationRead` | Read mode |
+| `data-fs-cart-destination-value` | `CartDestinationValue` | A destination is set |
+| `data-fs-cart-destination-value-prefix`, `-postal-code`, `-city`, `-state` | The piece's element | The piece exists |
+| `data-fs-cart-destination-unset` | `CartDestinationUnset` | No destination is set |
+| `data-fs-cart-destination-change` | `CartDestinationChange` | Always |
+| `data-fs-cart-destination-form` | `CartDestinationForm` | Edit mode |
+| `data-fs-cart-destination-postal-code-control` | `CartDestinationPostalCodeControl` | Always |
+| `data-fs-cart-destination-submit`, `-submit-pending` | `CartDestinationSubmit` | Always, and while a write is in flight |
+| `data-fs-cart-destination-cancel` | `CartDestinationCancel` | Always |
+| `data-fs-cart-destination-error` | `CartDestinationError` | The latest write failed |
+
+No part ships CSS of its own. Spacing, the link look of the change control and the two modes' boxes are swatch decisions; use `data-fs-cart-destination-editing` to style them apart.
+
+---
+
+## Common mistakes
+
+- **Inventing `CartDestination` (without `Root`).** The provider is `CartDestinationRoot`.
+- **Using `RegionRoot` on the cart page.** `Region` only sets the header cookie; it never changes the cart destination, so the free-shipping bar never moves.
+- **Placing `CartDestinationValue` or `CartDestinationChange` outside `CartDestinationRead`.** They stay on screen while the form is open.
+- **Placing the postal code control, `CartDestinationSubmit` or `CartDestinationCancel` outside `CartDestinationForm`.** Only the form is bound to edit mode: outside it they render in read mode too, and Enter in the field no longer reaches the submit.
+- **Looking for an `open` prop or a controller.** The root owns edit mode; nothing outside it can open it.
+- **Omitting `CartDestinationUnset`.** With no destination the page then shows only the change link and no invitation.
+- **Expecting the Value to show what the shopper just typed.** It shows what the cart confirms.
+- **Authoring a "CEP não encontrado" message.** A refused code and a network failure are the same error today: author one message in `CartDestinationError`.
+
+---
+
+## Related
+
+- [[../free-shipping-progress/free-shipping-progress]] — the bar beside this component; it follows the destination write through the cache with no wiring.
+- [[../region/region]] — the header's region control; same postal code field, but a cookie and no cart write.
+- [[../shipping-address/shipping-address]] — the full delivery address on checkout, which this component's write shares with.
+- [[../../particles/postal-code-field/postal-code-field]] — the masked input this component composes.