@vtex/faststore 0.0.8 → 0.0.11

package/dist/docs/saved-cards.md

@@ -1,7 +1,7 @@
 # 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.
+**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 that needs a security code is selected. A card that needs none shows no field and is placed with one action.
 
 ---
 
@@ -11,7 +11,7 @@ Use these signals to detect that a SavedCards block is present. Position on the
 
 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 **list of radio rows**, each showing a **card network mark or name** (Visa, Mastercard, …) plus a **masked number** like `•••• 4242` or `**** 4242`, the facts separated by a dot.
 - 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).
@@ -36,24 +36,26 @@ If the image shows a **radio list of masked card numbers with network names**, u
 
 ## 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.
+`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, for a card that needs one. `SavedCardRemove` is placed inside `SavedCardOption` too, so an expired card can be removed from the list.
 
 ```
 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)
+│       ├── SavedCardCvvField        (appears only for the selected, non-expired row that needs a CVV)
+│       └── SavedCardRemove          (appears only for an expired row: removes the card)
 └── 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`.
+Child order reflects visual order. `SavedCardCvvField` and `SavedCardRemove` are the only two children this block defines for `SavedCardOption`; 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.
+- `SavedCardCvvField` must be inside `SavedCardOption`. Outside it, it throws. It is only needed for cards that need a security code: omitting it means a shopper can select such a card but never submit a payment with it, so include it. A card that needs no code is payable through `SavedCardOption` alone.
+- `SavedCardRemove` must be inside `SavedCardOption`. Outside it, it throws an error that names `SavedCardRemove`. It renders only for an expired row, so composing it in the one row template is safe for every card.
 - `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.
 
 ---
@@ -64,9 +66,7 @@ Child order reflects visual order. `SavedCardOption` and `SavedCardCvvField` are
 
 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. |
+No copy props. **Content model** (`saved-cards`): `legend`, the radio group's accessible name, rendered as a visible fieldset legend above the rows (T38); `savedCardUnavailableMessage`, the inline alert when the server no longer matches the picked card (`INVALID_SAVED_CARD_ACCOUNT_ID`, `MISMATCHED_BIN_FOR_SAVED_CARD`); and `genericErrorMessage`, the alert for every other selection code and `NETWORK_ERROR`. A code the package does not know (one a newer server added) also shows `genericErrorMessage` and logs `message.unknown-code`.
 
 Which cards exist is always real data (`Query.payment.savedCards`) — never author them as props.
 
@@ -74,7 +74,11 @@ Which cards exist is always real data (`Query.payment.savedCards`) — never aut
 
 ### 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.
+One saved card as a radio row: the network's mark (the card entry's icon for that network), the masked last four (`•••• 4242`), and the shopper's own label when set, separated by a dot (`data-fs-saved-card-option-separator`, hidden from assistive tech; none renders after the last fact). A network the icon table does not know shows its name as text instead. The mark keeps the network in the radio's accessible name (`role="img"`, `aria-label` set to the network).
+
+Disabled (not selectable) when the card is expired — the row still renders so the shopper knows the card exists. An expired card is never the selection, even when it is the persisted one: no row is checked or marked selected, the radio group has no value, no security-code field mounts and nothing is registered to submit.
+
+A card whose `cvvRequired` is a literal `false` needs no security code. Selected and not expired, it shows no field and `SavedCardOption` itself registers a `'saved-card'` submission that sends nothing: placing the order opens the transaction, skips Send Payments and the gateway callback, and takes the order group as the order id, and the client treats the attempt as terminal (ruled 2026-10-14). That is the client's state, not confirmed platform order creation: the live proof is pending (PEXP-2194, ADR-0023). Any other flag value (absent, `null`, non-boolean) keeps the field and the coded path: an unknown never becomes a silent skip.
 
 No props beyond standard container attributes (`className`, `children`). Must be a direct child of `SavedCards`.
 
@@ -82,13 +86,37 @@ No props beyond standard container attributes (`className`, `children`). Must be
 
 ### 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 typed code is cleared when the submission settles, by any route except that format refusal (which keeps it for the shopper to fix).
+The CVV re-entry field for its row. Renders nothing until that specific row is selected, is not expired and its card requires a CVV (only a literal `cvvRequired: false` skips it); then renders a numeric input (digits only, capped at 4 characters) whose digits render **obscured** (dots) via an inline `-webkit-text-security: disc` style whenever the field does not have focus, with a helper line underneath it (the `securityCodeDescription` message; a blank one 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 typed code is cleared when the submission settles, by any route except that format refusal (which keeps it for the shopper to fix).
+
+The code is readable while the field has focus and obscured when it does not, so a shopper can read back what they just typed and catch a typo, and nothing is left legible once they move on. No length is involved: a saved card carries no per-network security-code length (the row's data has a display network name, not a `cvvMask`), and a partial code is hidden on blur like a full one. Re-focusing a hidden code reveals it again, so a typo can be read and corrected. A disabled field counts as unfocused, because a browser fires no `blur` when a focused input becomes disabled, and the focus flag dies with the input when deselecting the row unmounts it. A caller's `onFocus` and `onBlur` still run: they are composed with the field's own. Same rule and same shared predicate (`isSecurityCodeMasked`) as `CardEntry`'s CVV field.
+
+`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 — whenever the code is hidden the mask merges in last, so a caller's style can hold it off only while the field has focus, never while the code is obscured. 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`). **Content model** (`saved-card-cvv-field`): `securityCodeLabel` (accessible name) and `securityCodeDescription` (helper text). Must be inside `SavedCardOption`.
+
+The input carries no `name` attribute, on purpose. Changing a field's signature without evidence was ruled out on 2026-08-14 (R1's T100 block, commit `d284f9736`) and no evidence has been produced since; a test pins the absence, so adding one later is a deliberate edit of that test.
+
+### SavedCardRemove
+
+A button that removes an expired saved card from the shopper's account and from the checkout list. It renders **only for an expired row**: a row whose card can still be used has no control, and a row whose data lacks the expired flag has none either. Its visible text is the `label` message; its accessible name starts with that text and adds the card (`Remove card Visa •••• 0002`), so several expired rows are not announced alike. The network and the digits drop out of the name when the row has none.
+
+**Content model** (`saved-card-remove`): `label`, the visible text of the button, and `failureMessage`, shown in the row when the removal did not complete.
+
+Activating it calls the `savedCard.remove` action once for that card and nothing else. When the action resolves with no errors the row leaves the list. When it resolves with errors, rejects, or is not wired, the row stays and a `role="alert"` paragraph (`data-fs-saved-card-remove-error`) shows the `failureMessage` message. The message is always the authored copy, never the server's text, and the next attempt clears it. While a removal is pending the button is `aria-busy` and `aria-disabled` (`data-fs-saved-card-remove-pending`), ignores further clicks and keeps focus: it is not `disabled`.
+
+The action is `savedCard.remove`, which calls the `customerSavedCardRemove` mutation (`sdk/saved-cards/use-saved-card-actions.ts`). That mutation takes the account-side card id, the opaque `CustomerSavedCard` id. The checkout row is a different entity, `SavedCard`, with its own opaque id, so passing the row's id would be answered with `CARD_NOT_FOUND`. Both ids wrap the same platform `accountId`, so the control derives the account-side id from the row's `accountId` (base64 of `CustomerSavedCard:<accountId>`, the encoding of the server's `encodeOpaqueId`) and sends nothing else. A change in that encoding makes the server refuse the removal, which lands on the failure path below instead of removing the wrong card (`saved-cards.test.tsx` pins the exact id for a fixed `accountId`, including a non-ASCII one).
 
-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.
+The action's own cache write updates the account's `CustomerSavedCards` entity, which the checkout list does not read, so a success changes nothing on screen by itself. The control therefore evicts the row's `SavedCard` entity from the Apollo cache and Apollo drops the dangling reference from `Payment.savedCards`: the row leaves every subscriber at once, with no refetch. Outside `SavedCards` there is no list-item ref to evict, so nothing leaves and no message shows. The eviction is local to the cache. If the platform still lists the card in the order form, a later response that returns the order form's saved cards writes the row again; whether the platform drops it was not measured against a live account.
 
-`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).
+The failure path is deliberately conservative. Only a resolution with an empty `userErrors` list counts as a removal; one or more errors, a rejection and a missing `savedCard.remove` action all leave the `SavedCard` entity untouched, so the card stays listed and the shopper never reads a failure as a success. The message is authored copy because a server message can carry text the store did not write. A caught rejection logs only the error's name, never the card or the thrown message. The pending button stays `aria-disabled` rather than `disabled` because a `disabled` button loses focus in browsers, which strands a keyboard user after a failed removal.
 
-No props beyond standard input attributes (`className`), `securityCodeLabel` (accessible name), and `securityCodeDescription` (helper text). Must be inside `SavedCardOption`.
+It never changes the selection: no payment method, no card and no draft is touched, whatever the outcome. There is no built-in confirmation step (a store adds one through `onClick`, below) and no success message, and the row's removal does not clear a persisted selection that names the card (an expired persisted selection already counts as no selection). Composing it in a store's page is a separate step: nothing shows it until the page adds it.
+
+No props beyond standard button attributes (`className`, `onClick`). Must be inside `SavedCardOption`.
+
+Every message of these components is read only from `$content`. A missing message renders empty and logs `message.missing`.
+
+A store's `onClick` runs before the removal and can cancel it: call `event.preventDefault()` in it (for example when the shopper answers Cancel in the store's own confirmation dialog) and nothing is removed, no message is shown and the button does not go busy. A click while a removal is already pending is ignored, and the store's `onClick` does not run for it.
 
 ---
 
@@ -102,9 +130,10 @@ No props beyond standard input attributes (`className`), `securityCodeLabel` (ac
   },
   "saved-card-option": {
     "type": "SavedCardOption",
-    "children": ["saved-card-cvv"]
+    "children": ["saved-card-cvv", "saved-card-remove"]
   },
-  "saved-card-cvv": { "type": "SavedCardCvvField" }
+  "saved-card-cvv": { "type": "SavedCardCvvField" },
+  "saved-card-remove": { "type": "SavedCardRemove" }
 }
 ```
 
@@ -136,20 +165,16 @@ No props beyond standard input attributes (`className`), `securityCodeLabel` (ac
 
 - **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.
+- **Omitting `SavedCardCvvField` inside `SavedCardOption`.** For a card that needs a security code, without it a shopper can select the card but the place-order flow has nothing to submit with — include it. A card that needs no code does not depend on it.
+- **Placing `SavedCardOption`, `SavedCardCvvField` or `SavedCardRemove` outside their required ancestor.** `SavedCardOption` must be inside `SavedCards`; `SavedCardCvvField` and `SavedCardRemove` must be inside `SavedCardOption`. Only those two throw 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.
+- **Reusing the account's `AccountSavedCardRemove` parts in the checkout list.** They need `AccountSavedCardsRoot` and the `CustomerSavedCard` entity, and a checkout row is neither. Compose `SavedCardRemove` there.
+- **Expecting `SavedCardRemove` on a card that can still be used, or to ask for confirmation.** It renders only for an expired row and removes on the first activation unless the store's `onClick` cancels it with `preventDefault()`; there is no built-in confirmation. There is no prop to widen it to other cards.
+- **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. No 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.
@@ -158,12 +183,16 @@ Style `SavedCards` as a vertical stack of rows, each row as a horizontal line (r
 |---|---|---|
 | `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]` |
+| Legend (`data-fs-fieldset-legend`, native `<legend>`) | The group's visible name, from `legend` | `text-[14px] font-medium text-[var(--color-ink)]` |
+| `SavedCardOption` | One row — indicator, network mark (`data-fs-saved-card-option-network-icon`), separators (`data-fs-saved-card-option-separator`), last four, label in a line; muted/dashed when expired | `flex items-center gap-[8px] p-[12px] border border-[color-mix(in_srgb,var(--color-ink)_20%,transparent)] rounded-[var(--radius-base)] data-[fs-saved-card-option-expired]:opacity-50 data-[fs-saved-card-option-selected]:border-[var(--color-primary)]` |
+| `SavedCardCvvField` | The short CVV input | `w-[64px] text-[14px] px-[8px] py-[6px] border border-[color-mix(in_srgb,var(--color-ink)_20%,transparent)] rounded-[var(--radius-base)]` |
+| CVV helper text (`data-fs-saved-card-cvv-description`) | Small muted line next to/under the CVV input | `text-[12px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]` |
+| `SavedCardRemove` (`data-fs-saved-card-remove`, native `<button>`) | The remove control in an expired row; pending state is `data-fs-saved-card-remove-pending` | `text-[12px] underline data-[fs-saved-card-remove-pending]:opacity-60` |
+| Remove failure (`data-fs-saved-card-remove-error`, `role="alert"`) | The message under a row whose removal did not complete | `text-[12px] font-medium` |
 | Placing (`data-fs-saved-cards-placing`) | Present on `SavedCards`' own root 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 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` |
 
+A status color is a `visualIdentity` feedback role of the foundation: when the store declares it, color the Remove failure row `text-[var(--color-feedback-danger)]`, never with a hex.
+
 Styled example:
 
 ```json
@@ -178,14 +207,14 @@ Styled example:
     "children": ["saved-card-cvv"],
     "style": [
       "flex", "items-center", "gap-[8px]", "p-[12px]",
-      "border", "border-[#E0E0E0]", "rounded-[8px]",
+      "border", "border-[color-mix(in_srgb,var(--color-ink)_20%,transparent)]", "rounded-[var(--radius-base)]",
       "data-[fs-saved-card-option-expired]:opacity-50",
-      "data-[fs-saved-card-option-selected]:border-[#000000]"
+      "data-[fs-saved-card-option-selected]:border-[var(--color-primary)]"
     ]
   },
   "saved-card-cvv": {
     "type": "SavedCardCvvField",
-    "style": ["w-[64px]", "text-[14px]", "px-[8px]", "py-[6px]", "border", "border-[#CCCCCC]", "rounded-[4px]"]
+    "style": ["w-[64px]", "text-[14px]", "px-[8px]", "py-[6px]", "border", "border-[color-mix(in_srgb,var(--color-ink)_20%,transparent)]", "rounded-[var(--radius-base)]"]
   }
 }
 ```
@@ -195,10 +224,10 @@ Styled example:
 ## 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`
+name (the `legend` message) — a screen-reader user hears these rows are a choice between stored
+cards, not payment methods. A store that leaves `legend` unauthored ships a nameless group, and the
+formatter logs `message.missing`. Each row keeps its own accessible name from its network
+(the mark carries it as an `aria-label`) and masked last four, with the separators hidden from assistive tech; 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.

package/dist/docs/select.md

@@ -26,10 +26,9 @@ Signals that distinguish it from other controls:
 - A **country/region selector** (ISO codes resolved to display names), a **sort-order dropdown**, or a
   **quantity/unit picker** are the most common PDP/checkout uses.
 
-This particle currently has no `store-editor` knowledge-base row: it is a leaf control with no
-distinct visual region of its own, and the bound `FieldSelect.*` parts cannot be generated from a
-screenshot without the bound Control that consumes them (`ShippingAddressCountryControl`). This section documents the
-visual pattern for a human reader; it is not wired into image→schema detection.
+This particle is a leaf control with no distinct visual region of its own, and the bound `FieldSelect.*`
+parts cannot be generated from a screenshot without the bound Control that consumes them
+(`ShippingAddressCountryControl`). This section documents the visual pattern for a human reader.
 
 ---
 

package/dist/docs/shipping-address.md

@@ -11,11 +11,11 @@ Use these signals to detect that a ShippingAddress block is present. Position on
 
 A ShippingAddress block contains any combination of:
 
-- A **country dropdown** listing country names (e.g. "Brazil", "United States").
+- A **country dropdown** listing country names (e.g. "Brazil", "United States", "Canada", "Mexico").
 - Labeled **input fields** for street, number, city, state, and postal code.
 - A **recipient name** field, often showing a pre-filled name as its value.
 - An optional **"Complement"** field (apartment, suite, unit).
-- A **"Neighborhood"** field — present only for Brazil-shaped forms, absent for US-shaped forms.
+- A **"Neighborhood"** field — present only for Brazil- and Mexico-shaped forms, absent for US- and Canada-shaped forms.
 - A **submit button** shared with the rest of the page's form, possibly showing a pending label while a write is in flight.
 - An **error banner** showing domain validation messages or a generic failure state.
 
@@ -50,7 +50,7 @@ FormRoot
 │   ├── StreetControl
 │   ├── NumberControl
 │   ├── ComplementControl
-│   ├── NeighborhoodControl             (renders only for countries whose descriptor includes it, e.g. Brazil)
+│   ├── NeighborhoodControl             (renders only for countries whose descriptor includes it, e.g. Brazil or Mexico)
 │   ├── CityControl
 │   └── StateControl / PostalCodeControl
 ├── FormError                            (sibling of the fieldset, not a child)
@@ -63,7 +63,7 @@ Child order reflects visual order — place Controls in the same sequence they a
 
 - Every Control must be a descendant of `ShippingAddressFieldset` — each throws if rendered outside it.
 - `ShippingAddressFieldset` must be a descendant of `FormRoot` — it throws its own named error otherwise.
-- `NeighborhoodControl` renders `null` when the active country's descriptor omits it (e.g. United States in v1) — safe to include speculatively, but only place it in the schema if the target country is expected to show it.
+- `NeighborhoodControl` renders `null` when the active country's descriptor omits it (e.g. United States or Canada) — safe to include speculatively, but only place it in the schema if the target country is expected to show it.
 - Only one `ShippingAddressFieldset` per `FormRoot`; a second one under the same `shippingAddress` namespace throws at mount.
 
 ---
@@ -78,9 +78,21 @@ Registers under the `shippingAddress` namespace with an ancestor `FormRoot`; ren
 |------|------|---------|-------|
 | `defaultCountry` | string | `"BRA"` | ISO alpha-3 country code used when no address exists yet |
 | `skeletonCount` | number | `9` | Placeholder rows drawn while the address resolves. Set it to the number of Controls composed. |
-| `loadingLabel` | string | `"Loading your delivery address"` | Announced politely while the address resolves. Blank means no announcement. |
-| `loadedLabel` | string | `"Your delivery address is ready"` | Announced politely once the Controls mount. Blank means no announcement. |
-| `groupLabel` | string | `"Your delivery address"` | Accessible name of the `<fieldset>` group. Blank means no name is exposed. |
+
+**Content (`shipping-address-fieldset`):** message fields the store authors in `$content`; a missing one renders empty and logs `message.missing`.
+
+| Field | Source (English) | Notes |
+|-------|------------------|-------|
+| `loadingLabel` | `Loading your delivery address` | Announced politely while the address resolves. Blank means no announcement. |
+| `loadedLabel` | `Your delivery address is ready` | Announced politely once the Controls mount. Blank means no announcement. |
+| `groupLabel` | `Your delivery address` | Accessible name of the `<fieldset>` group. Blank means no name is exposed. |
+| `requiredMessage` | `{label} is required` | Shown under a required field left blank. `label` is that field's own label message. |
+| `missingRecipientNameMessage` | `Enter the recipient's name.` | Shown by `FormError` for `MISSING_RECIPIENT_NAME`. |
+| `invalidPostalCodeMessage` | `Enter a valid postal code.` | Shown by `FormError` for `INVALID_POSTAL_CODE`. |
+| `invalidAddressMessage` | `Check the address and try again.` | Shown by `FormError` for `INVALID_ADDRESS`. |
+| `genericErrorMessage` | `Unable to save your delivery address. Please try again.` | Shown by `FormError` for a network failure and for the refusals the shopper cannot fix: `MISSING_CART_CONTEXT`, `CART_NOT_FOUND`, `INVALID_SAVED_ADDRESS_ID`, `INVALID_COUNTRY_CODE`. |
+
+A refused write reaches `FormError` worded from these fields, keyed on the error's `code`. The server's English `message` never shows: a code this fieldset has no field for, one a newer server added, shows `genericErrorMessage` and logs `message.unknown-code`.
 
 **Data:** declares `fragment ShippingAddressFieldsetData on Query` (`shipping { address }` + `clientProfile { id firstName lastName }`), `fetchStrategy: 'reactive'`. The compiler merges it into the page query — no explicit `dataSources` entry needed.
 
@@ -93,25 +105,25 @@ Registers under the `shippingAddress` namespace with an ancestor `FormRoot`; ren
 - Compose `FormSubmit` and `FormError` as siblings, not children — the fieldset renders no submit or error part.
 - Only one `ShippingAddressFieldset` per `FormRoot`; a second one under the same `shippingAddress` namespace throws at mount.
 
-**Overriding a control's text:** every field Control also takes optional `label` and `placeholder` props. Absence means the platform's value — the active country descriptor's label where one exists (e.g. "cidade" for `CityControl`), and for `CountryControl` the descriptor's `countryLabel` ("país" for Brazil, "country" for the United States). The required message follows the same rule: `<label> <requiredSuffix>` with the descriptor's suffix ("é obrigatório", "is required"), so an authored `label` renames the field in its message too. Neither has a schema default, so an author only sets one when the platform copy is wrong for their store.
+**A control's text:** every field Control has its own content type, `shipping-address-<field>` (`-recipient-name`, `-street`, `-number`, `-complement`, `-neighborhood`, `-city`, `-state`, `-postal-code`, `-country`), with one `label` message field; `placeholder` stays a plain prop with no default. The descriptors hold no copy, so the store's locale is the form's language whatever country is selected. Wording that differs by country takes a `country` select argument (the active country's ISO alpha-3 code, one of `BRA`, `USA`, `CAN`, `MEX`, with an `other` case): `shipping-address-state › label` (`{country, select, CAN {province} other {state}}`), and `shipping-address-postal-code › label` and `invalidMessage` (`{country, select, USA {zip code} other {postal code}}`, `{country, select, USA {invalid zip code} other {invalid postal code}}`). The required message names the field with its label message, so a store renames the field in its message too. Country names in the selector come from `Intl.DisplayNames` in the store locale ("Brazil" in `en-US`, "Brasil" in `pt-BR`).
 
 **Recomposing a control's anatomy:** every field Control declares `providesContext: 'field'` (RFC:503), so a `Field.*` part composed inside one is not a context-constraint-violation. Given children, a field Control renders them in place of its default `Field.Label` / `Field.Control` / `Field.Error` (or, for `CountryControl`, `Field.Label` / `FieldSelect.Root` / `Field.Error`) — useful to reorder the label against the input or insert an icon. The binding underneath is unchanged either way.
 
 ### RecipientNameControl
 
-The recipient-name input. The only required field: submit is blocked while it is blank. Defaults from `clientProfile.firstName`/`lastName` (joined) as a real, editable value — not a placeholder hint — whenever the stored address has no recipient name yet; degrades to an empty required field when the profile has neither part. No props beyond `className`, `label`, `placeholder`.
+The recipient-name input. The only required field: submit is blocked while it is blank. Defaults from `clientProfile.firstName`/`lastName` (joined) as a real, editable value — not a placeholder hint — whenever the stored address has no recipient name yet; degrades to an empty required field when the profile has neither part. No props beyond `className`, `placeholder`; its label is `shipping-address-recipient-name › label`.
 
 ### StreetControl / NumberControl / CityControl / StateControl / PostalCodeControl / ComplementControl
 
-Thin field Controls; each renders `null` when the active country's descriptor omits that field. `PostalCodeControl` is additionally client-validated against the active country's format (CEP for Brazil, ZIP/ZIP+4 for the United States) — a malformed value blocks submit even though the field is not required. No props beyond `className`, `label`, `placeholder`.
+Thin field Controls; each renders `null` when the active country's descriptor omits that field. `PostalCodeControl` is additionally client-validated against the active country's format (CEP for Brazil, ZIP/ZIP+4 for the United States, the library's own rule for Canada and Mexico) — a malformed value blocks submit even though the field is not required, and shows `shipping-address-postal-code › invalidMessage`. No props beyond `className`, `placeholder`.
 
 ### NeighborhoodControl
 
-Same shape as the other field Controls. Renders only for countries whose descriptor includes a neighborhood field (Brazil in v1); renders `null` for others (United States in v1). Its draft value is retained (not cleared) when hidden, so it reappears with the same value if the shopper switches back to a country that shows it.
+Same shape as the other field Controls. Renders only for countries whose descriptor includes a neighborhood field (Brazil and Mexico); renders `null` for others (United States and Canada). Its draft value is retained (not cleared) when hidden, so it reappears with the same value if the shopper switches back to a country that shows it.
 
 ### CountryControl
 
-Country selector. Lists only countries with an implemented descriptor (Brazil and United States in v1) — a descriptor-less country is unreachable. Switching country preserves the values of fields the two descriptors share (keyed by canonical field name) and only adds/removes country-specific fields. No props beyond `className`, `label`, `placeholder`.
+Country selector. Lists only countries with a descriptor — Brazil and the United States, written in the descriptor table, then Canada and Mexico once their rules have loaded from `@vtex/country-forms` — a descriptor-less country is unreachable. A stored or default `CAN` or `MEX` address keeps the fieldset in its skeleton until that country has loaded. Switching country preserves the values of fields the two descriptors share (keyed by canonical field name) and only adds/removes country-specific fields. No props beyond `className`, `placeholder` (absent, the trigger shows the active country's name).
 
 ---
 
@@ -127,6 +139,16 @@ The nine field Controls, batched behind a form-level submit:
   },
   "shipping-address-fieldset": {
     "type": "ShippingAddressFieldset",
+    "props": {
+      "loadingLabel": "Loading your delivery address",
+      "loadedLabel": "Your delivery address is ready",
+      "groupLabel": "Your delivery address",
+      "requiredMessage": "{label} is required",
+      "missingRecipientNameMessage": "Enter the recipient's name.",
+      "invalidPostalCodeMessage": "Enter a valid postal code.",
+      "invalidAddressMessage": "Check the address and try again.",
+      "genericErrorMessage": "Unable to save your delivery address. Please try again."
+    },
     "children": [
       "fieldset-country",
       "fieldset-recipient",
@@ -139,15 +161,27 @@ The nine field Controls, batched behind a form-level submit:
       "fieldset-postal-code"
     ]
   },
-  "fieldset-country": { "type": "ShippingAddressCountryControl" },
-  "fieldset-recipient": { "type": "ShippingAddressRecipientNameControl" },
-  "fieldset-street": { "type": "ShippingAddressStreetControl" },
-  "fieldset-number": { "type": "ShippingAddressNumberControl" },
-  "fieldset-complement": { "type": "ShippingAddressComplementControl" },
-  "fieldset-neighborhood": { "type": "ShippingAddressNeighborhoodControl" },
-  "fieldset-city": { "type": "ShippingAddressCityControl" },
-  "fieldset-state": { "type": "ShippingAddressStateControl" },
-  "fieldset-postal-code": { "type": "ShippingAddressPostalCodeControl" },
+  "fieldset-country": { "type": "ShippingAddressCountryControl", "props": { "label": "country" } },
+  "fieldset-recipient": { "type": "ShippingAddressRecipientNameControl", "props": { "label": "recipient name" } },
+  "fieldset-street": { "type": "ShippingAddressStreetControl", "props": { "label": "street" } },
+  "fieldset-number": { "type": "ShippingAddressNumberControl", "props": { "label": "number" } },
+  "fieldset-complement": {
+    "type": "ShippingAddressComplementControl",
+    "props": { "label": "apartment, suite, etc. (optional)" }
+  },
+  "fieldset-neighborhood": { "type": "ShippingAddressNeighborhoodControl", "props": { "label": "neighborhood" } },
+  "fieldset-city": { "type": "ShippingAddressCityControl", "props": { "label": "city" } },
+  "fieldset-state": {
+    "type": "ShippingAddressStateControl",
+    "props": { "label": "{country, select, CAN {province} other {state}}" }
+  },
+  "fieldset-postal-code": {
+    "type": "ShippingAddressPostalCodeControl",
+    "props": {
+      "label": "{country, select, USA {zip code} other {postal code}}",
+      "invalidMessage": "{country, select, USA {invalid zip code} other {invalid postal code}}"
+    }
+  },
   "form-error": { "type": "FormError" },
   "form-submit": { "type": "FormSubmit", "props": { "label": "Continue" } }
 }
@@ -155,6 +189,8 @@ The nine field Controls, batched behind a form-level submit:
 
 ### Minimal variant (manual entry only)
 
+The variants below leave out the message fields for brevity; author them on each element as the canonical example does.
+
 ```json
 {
   "checkout-form": {

package/dist/docs/shipping-simulator.md

@@ -45,9 +45,9 @@ The context distinguishes three states via `shippingOptions`:
 - **`[]`** — a simulation ran and returned an empty list. `Empty` renders its message; `Options` renders nothing.
 - **`[...]`** — options available. `Options` renders one `Option` per row; `Empty` renders nothing.
 
-`ShippingSimulatorError` shows the first `userError`'s message. A transport failure has no upstream message, so the component supplies `fs/shipping.calculation-failed` from the catalog — built in the `.catch()` handler, where only a string fits.
+`ShippingSimulatorError` words the first `userError` by its code from its own fields, never from the error's `message`: `INVALID_POSTAL_CODE` → `invalidPostalCode`, `UNKNOWN` → `genericErrorMessage`, `CALCULATION_FAILED` → `calculationFailed`. The default hooks keep `INVALID_POSTAL_CODE` and collapse every other server code and every transport failure into `UNKNOWN`. When `onSimulate` rejects, the Root records a client-side `CALCULATION_FAILED` error with an empty `message` (`onResult` receives it as is). A code outside the three (a store's own `onSimulate`) shows its `message`; composed `children` replace the message.
 
-`Empty` renders **only** for `[]` with no `userErrors` — so it never flashes on first paint, and an error path defers to `ShippingSimulatorError`. Its copy comes from the message catalog (`fs/shipping.no-options`), per locale, and `children` overrides it. It renders a polite live region (an `<output aria-live="polite">`, matching `Loading`), so it is announced when it appears.
+`Empty` renders **only** for `[]` with no `userErrors` — so it never flashes on first paint, and an error path defers to `ShippingSimulatorError`. Its copy is its `text` field, and `children` overrides it. It renders a polite live region (an `<output aria-live="polite">`, matching `Loading`), so it is announced when it appears.
 
 ---
 
@@ -58,14 +58,14 @@ CartShippingSimulatorRoot          ← whole-cart calculator (no fragment, no Ca
 ├── ShippingSimulatorForm          ← wraps input + submit
 │   ├── ShippingSimulatorInput       props: format (auto-hyphenate CEP)
 │   └── ShippingSimulatorSubmit      children: "Calcular"
-├── ShippingSimulatorLoading       ← shows while a simulation is pending (`fs/shipping.calculating`)
+├── ShippingSimulatorLoading       ← shows while a simulation is pending
 ├── ShippingSimulatorError         ← shows a validation/transport error
 ├── ShippingSimulatorOptions       ← renders one Option per available option
 │   │   props: sortBy ("price" | "estimate"), maxOptions
 │   └── ShippingSimulatorOption
 │       ├── ShippingSimulatorOptionName
-│       ├── ShippingSimulatorOptionEstimate   ← one whole sentence per unit, from the catalog
-│       └── ShippingSimulatorOptionPrice       ← "Grátis" from the catalog when the amount is 0
+│       ├── ShippingSimulatorOptionEstimate   ← one whole sentence per unit
+│       └── ShippingSimulatorOptionPrice       ← its `freeLabel` when the amount is 0
 └── ShippingSimulatorEmpty         ← shows only when a simulation returned []
 ```
 
@@ -77,11 +77,28 @@ The PDP composition is identical, with `ShippingSimulatorRoot` in place of `Cart
 |---|---|---|
 | `ShippingSimulatorRoot` | `country`, `quantity` | PDP Root; carries a product fragment + `fetchStrategy: 'reactive'`; needs a `$slug` page |
 | `CartShippingSimulatorRoot` | `country` | Cart Root; no fragment, no `fetchStrategy`, no `CartRoot` ancestor; submits `{ postalCode, country }` only |
-| `ShippingSimulatorInput` | `format` | `format` auto-hyphenates the CEP (01310-100). The placeholder and the default `aria-label` come from the message catalog (`fs/shipping.postal-code.*`); `aria-label` stays a DOM pass-through, so a store can still set its own |
+| `ShippingSimulatorInput` | `format` | `format` auto-hyphenates the CEP (01310-100). The `aria-label` and the placeholder are its `ariaLabel` and `placeholder` fields; neither is a prop |
 | `ShippingSimulatorOptions` | `sortBy`, `maxOptions` | Both optional; omitted = every option in API order. `sortBy="price"` orders cheapest first, `"estimate"` fastest first (business days weigh as calendar days); `maxOptions` caps the rendered rows — `sortBy="price"` + `maxOptions=1` shows only the cheapest option. Works identically under either Root |
-| `ShippingSimulatorOptionEstimate` | — | One whole sentence per unit (`fs/shipping.estimate.in-*`), so the plural agrees with the locale; a zero value reads `fs/shipping.estimate.today` |
-| `ShippingSimulatorOptionPrice` | — | Renders `fs/shipping.free-price` when the amount is 0; otherwise formats via `Intl` from the active storefront context |
-| `ShippingSimulatorEmpty` | — | Renders only for a simulated-empty result (`fs/shipping.no-options`); `children` overrides it |
+| `ShippingSimulatorOptionEstimate` | — | One whole sentence per unit (`inBusinessDays`, `inDays`, `inHours`, `inMinutes`), so the plural agrees with the locale; a zero value reads `today`. `children` overrides it |
+| `ShippingSimulatorOptionPrice` | — | Renders `freeLabel` when the amount is 0; otherwise formats via `Intl` from the active storefront context. `children` overrides it |
+| `ShippingSimulatorEmpty` | — | Renders only for a simulated-empty result; `children` overrides it |
+
+Each part with copy reads it only from its own `$content`, whose fields are ICU messages. A missing message renders empty and logs an error. `children` replaces the copy of `Loading`, `Error`, `OptionEstimate`, `OptionPrice`, `OptionFreeBadge` and `Empty`, and then no message is formatted.
+
+| Component | Content type | Content fields |
+|---|---|---|
+| `ShippingSimulatorInput` | `shipping-simulator-input` | ariaLabel, placeholder |
+| `ShippingSimulatorLoading` | `shipping-simulator-loading` | text |
+| `ShippingSimulatorError` | `shipping-simulator-error` | calculationFailed, invalidPostalCode, genericErrorMessage |
+| `ShippingSimulatorOptionEstimate` | `shipping-simulator-option-estimate` | today, inBusinessDays, inDays (plural on `days`), inHours (`hours`), inMinutes (`minutes`) |
+| `ShippingSimulatorOptionPrice` | `shipping-simulator-option-price` | freeLabel |
+| `ShippingSimulatorOptionFreeBadge` | `shipping-simulator-option-free-badge` | text |
+| `ShippingSimulatorEmpty` | `shipping-simulator-empty` | text |
+| `DeliveryOptionsRoot` / `DeliveryOptionsList` | `delivery-options-root` / `delivery-options-list` | optionUnavailableMessage (`OPTION_UNAVAILABLE`), missingAddressMessage (`MISSING_SHIPPING_ADDRESS`), genericErrorMessage (`NETWORK_ERROR`, `MISSING_CART_CONTEXT`, `CART_NOT_FOUND`): the inline selection error; an unknown code shows genericErrorMessage |
+| `DeliveryOptionsAccordion` | `delivery-options-accordion` | placeholder (the trigger while nothing is selected), freeLabel (the trigger echo of a free selected option), and the same three selection-error fields as `delivery-options-root` |
+| `DeliveryOptionsSummary` | `delivery-options-summary` | placeholder (the summary while nothing is selected), freeLabel (the summary echo of a free selected option) |
+
+The delivery-options echoes reuse `ShippingSimulatorOptionPrice` and word a free price with their own `freeLabel`, never with the price part's.
 
 Prices format from the **active storefront context's currency** (not the payload `currencyCode`); the binding's currency must match the payload currency.
 
@@ -112,11 +129,18 @@ Place the calculator inside `cart-filled` (an empty cart has nothing to ship), b
   },
   "cart-shipping-input": {
     "type": "ShippingSimulatorInput",
-    "props": { "format": true }
+    "props": { "format": true, "ariaLabel": "CEP", "placeholder": "Digite seu CEP" }
   },
   "cart-shipping-submit": { "type": "ShippingSimulatorSubmit", "props": { "children": "Calcular" } },
-  "cart-shipping-loading": { "type": "ShippingSimulatorLoading" },
-  "cart-shipping-error": { "type": "ShippingSimulatorError" },
+  "cart-shipping-loading": { "type": "ShippingSimulatorLoading", "props": { "text": "Calculando…" } },
+  "cart-shipping-error": {
+    "type": "ShippingSimulatorError",
+    "props": {
+      "calculationFailed": "Não foi possível calcular o frete. Tente novamente.",
+      "invalidPostalCode": "CEP inválido. Verifique e tente novamente.",
+      "genericErrorMessage": "Não foi possível calcular o frete. Tente novamente."
+    }
+  },
   "cart-shipping-options": {
     "type": "ShippingSimulatorOptions",
     "children": ["cart-shipping-option"]
@@ -126,12 +150,26 @@ Place the calculator inside `cart-filled` (an empty cart has nothing to ship), b
     "children": ["cart-shipping-option-name", "cart-shipping-option-estimate", "cart-shipping-option-price"]
   },
   "cart-shipping-option-name": { "type": "ShippingSimulatorOptionName" },
-  "cart-shipping-option-estimate": { "type": "ShippingSimulatorOptionEstimate" },
-  "cart-shipping-option-price": { "type": "ShippingSimulatorOptionPrice" },
-  "cart-shipping-empty": { "type": "ShippingSimulatorEmpty" }
+  "cart-shipping-option-estimate": {
+    "type": "ShippingSimulatorOptionEstimate",
+    "props": {
+      "today": "vai ser entregue hoje",
+      "inBusinessDays": "em {days, plural, one {# dia útil} other {# dias úteis}}",
+      "inDays": "em {days, plural, one {# dia} other {# dias}}",
+      "inHours": "em {hours, plural, one {# hora} other {# horas}}",
+      "inMinutes": "em {minutes, plural, one {# minuto} other {# minutos}}"
+    }
+  },
+  "cart-shipping-option-price": { "type": "ShippingSimulatorOptionPrice", "props": { "freeLabel": "Grátis" } },
+  "cart-shipping-empty": {
+    "type": "ShippingSimulatorEmpty",
+    "props": { "text": "Nenhuma opção de entrega disponível para este endereço." }
+  }
 }
 ```
 
+A store without CMS authors the message fields on the element, as above; a CMS-bound store keeps them in content.
+
 ### Product page preview (single product)
 
 Identical shape, with `ShippingSimulatorRoot` as the Root and `quantity` available as a prop. It lives on a PDP where a `$slug` variable resolves the product fragment.