@vtex/faststore 0.0.8 → 0.0.11

package/dist/docs/payment.md

@@ -80,8 +80,19 @@ Both providers declare `providesContext: ['payment', 'card-capture']`. Every lea
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `group` | string, or array of strings | `["creditCardPaymentGroup", "debitCardPaymentGroup"]` | Scopes the method list to a set of payment groups — a method renders when its `groupName` is a member. A single string still scopes to exactly that one group. Set to `""` (the empty **string**) to show every method the store offers. An empty **array** (`[]`) is not a second spelling of that opt-out — it matches no group, so every method is scoped out and the list renders empty. It only *filters* — it never supplies methods. |
+| `groupOrder` | string, or array of strings | none | The order of the rows in `PaymentMethodList`, as payment group names (`PaymentMethod.groupName`) — copy them from the store's own order-form data, because a name matches **exactly** (case-sensitive, nothing trimmed) and one the store does not use (`pixPaymentGroup` for `instantPaymentPaymentGroup`) is silently ignored. A method's row takes its group's position in the list; the one card option takes the position of the first of its groups (`creditCardPaymentGroup`, `debitCardPaymentGroup`) that the list names and the store offers. A group the list **leaves out** still shows, after the named ones, in the order form's order, with the card option first among them. It only orders: it never hides, adds or renames a method, never changes which method is preselected, and never changes which method a typed card number selects. Unset or `[]` keeps the order form's order, the card option first. A single string is a list of one. |
 
-**Data:** declares `fragment PaymentSectionData on Query`, which selects two root fields: `Query.payment` (the method list with its validator config, plus `selectedMethodId` / `selectedAccountId` / `selectedBin`) and `Query.cart.total`, for the `add_payment_info` event. The compiler merges it into the page query — no `dataSources` entry needed — and, because it has two root fields, delivers `$data` keyed as `{ payment, cart }` (ADR-0015). `fetchStrategy: 'reactive'` — picking a method re-renders the whole section from the cache, no refetch.
+To put Pix above the card option and keep Boleto last, with a store whose Pix group is `instantPaymentPaymentGroup`:
+
+```json
+{ "group": ["creditCardPaymentGroup", "instantPaymentPaymentGroup", "boletoPaymentGroup"], "groupOrder": ["instantPaymentPaymentGroup", "creditCardPaymentGroup"] }
+```
+
+The rows read `Pix`, `Pay with Credit / Debit Card`, `Boleto`: Pix and the card option are named, and Boleto, which the list leaves out, follows them.
+
+The order is display-only. `PaymentMethodList` sorts a copy of its own rows, and the `methods` and `allMethods` the other leaves read keep the order form's order (`orderMethodListRows` in `use-payment-method-selection.ts`; pinned in `use-payment-method-selection.test.tsx`). That separation matters for money: a typed card number resolves to the first method in `methods` order whose pattern matches, so sorting `methods` would let the merchant's order change which method an order is charged under. The same reason keeps `methods` the same array as `allMethods` under `group: ""`. The sorted card option takes the position of the first card group the list names that the store actually offers, so naming a debit group the store does not sell cannot pull the card option ahead of rows the merchant listed. The normalized list is published on the `payment` context as `groupOrder`, which keeps its identity while its content is equal. The badge strips (`PaymentMethodBadges`, `AcceptedPaymentMethodBadges`) do not follow it.
+
+**Data:** declares `fragment PaymentSectionData on Query`, which selects three root fields: `Query.payment` (the method list with its validator config, plus `selectedMethodId` / `selectedAccountId` / `selectedBin`), `Query.cart.total`, for the `add_payment_info` event, and `Query.clientProfile` (`firstName`, `lastName`, `phone`), for the place-order check. The compiler merges it into the page query — no `dataSources` entry needed — and, because it has three root fields, delivers `$data` keyed as `{ payment, cart, clientProfile }` (ADR-0015). The profile reaches the `payment` context as `clientProfile`: absent or `null` means it was not read and never refuses, an object means it was read, even with every field `null`. `fetchStrategy: 'reactive'` — picking a method re-renders the whole section from the cache, no refetch.
 
 **Writes:** `actions: { payment: ['setMethod', 'sendPayments'], analytics: ['track'] }`. Selecting a method dispatches `setMethod`. The root also provides `card-capture` to `CardEntry`: when the place-order sequence runs the `new-card` submission, `CardEntry` builds the card and the root folds in the draft's document, label, and save flag and sends it through `sendPayments`. Once a `CardEntry` is mounted and the cart total has resolved, the root fires `add_payment_info` once.
 
@@ -89,18 +100,24 @@ Renders one container `div` and its children. No heading, no copy, no layout —
 
 ### PaymentSectionController
 
-Same props, same fragment shape, same action. Renders **no element at all**: it holds the overlay's open state and hands it to its single overlay child. Unlike the delivery-options controller, a successful method selection does **not** close the surface — the shopper still has a card to type — so close it from a `DrawerClose` / `DialogClose` particle or from the leaf that finishes the flow.
+Same props (including `groupOrder`, which orders the popup's `PaymentMethodList` the same way), same fragment shape, same action. Renders **no element at all**: it holds the overlay's open state and hands it to its single overlay child. Unlike the delivery-options controller, a successful method selection does **not** close the surface — the shopper still has a card to type — so close it from a `DrawerClose` / `DialogClose` particle or from the leaf that finishes the flow.
 
 ### PaymentMethodList
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `legend` | string | `"Payment method"` | 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. |
-| `cardLabel` | string | `"Pay with Credit / Debit Card"` | The card option's own name (T171). One control stands for every in-scope credit and debit method at once, so it cannot be labelled from one method's name — this is the copy instead. An authored empty or whitespace-only string falls back to this default rather than rendering a nameless control. |
+No copy props.
+
+**Content model** (`payment-method-list`):
+
+- `legend`: the radio group's accessible name, rendered as a visible fieldset legend above the rows (T38).
+- `cardLabel`: the card option's own name (T171). One control stands for every in-scope credit and debit method at once, so it cannot be labelled from one method's name — this is the copy instead.
+
+- `genericErrorMessage`: the inline alert for a refused method selection. Every `PaymentMethodSelectErrorCode` and `NETWORK_ERROR` reads it: none is one the shopper can fix from this list. A code the package does not know (one a newer server added) also reads it and logs `message.unknown-code`.
+
+Every message is read only from `$content`. A missing message renders empty and logs `message.missing`.
 
 Renders the inline selection error (`role="alert"`) and the payment options, inside a fieldset named by `legend`. Requires a payment-section ancestor.
 
-**Every in-scope credit and debit method is one option**, named by `cardLabel` — not one row per network. Which card network the shopper is paying with comes from the number they type into the card form, which is the only mechanism that can be right: a shopper who picked "Visa" and then typed a Mastercard number had their pick silently overwritten. Every other in-scope method (e.g. Pix) keeps its own row, labelled with the method's name from the order form and bound to that method's own id, exactly as before. Only the two card groups fold into the card option — a card-like custom method in another group keeps a row of its own. Set `group` to `""` on the root to switch the folding off entirely and get one row per method; the card form still hides for a non-card row and comes back for a card row (see below).
+**Every in-scope credit and debit method is one option**, named by `cardLabel` — not one row per network. Which card network the shopper is paying with comes from the number they type into the card form, which is the only mechanism that can be right: a shopper who picked "Visa" and then typed a Mastercard number had their pick silently overwritten. Every other in-scope method (e.g. Pix) keeps its own row, labelled with the method's name from the order form and bound to that method's own id, exactly as before. Only methods whose `type` is `CREDIT_CARD` or `DEBIT_CARD` fold into the card option — a card-like custom method the API types as `OTHER` keeps a row of its own. Set `group` to `""` on the root to switch the folding off entirely and get one row per method; the card form still hides for a non-card row and comes back for a card row (see below).
 
 The card option reads as checked while the persisted selection is one of the methods it stands for, **and while nothing is persisted at all** — the card option is the default — and while the section is in card mode (below). It is not bound to any single method id, so activating it dispatches the same candidate the preselection rule would choose (the sole in-scope method, else the sole method in the credit group). When neither is singular — a store with Visa and Mastercard — it dispatches nothing and puts the section in **card mode** instead: the card form comes back at once, the option reads checked, and the method arrives from the typed number. No made-up `"card"` method id is ever sent: the only ids that reach `payment.setMethod` are ids the order form offered.
 
@@ -110,11 +127,11 @@ The container always carries `data-fs-payment-method-list-state` — `"loading"`
 
 ### Preselection and the card-payment collapse
 
-When the order form carries no persisted selection and the scoped method list resolves to exactly one method, the section preselects it automatically — one silent `payment.setMethod` dispatch, keyed on that method's id, never on row position. When the scoped list holds more than one method, the section falls back to the sole method in the credit group, if there is exactly one — so a store offering one credit and one debit method keeps preselecting the credit one, the same method it preselected before debit was admitted. **"The credit group" here is always the fixed name `creditCardPaymentGroup`, not whichever member of `group` the store authored** — a store that renamed its credit payment group and listed the new name in `group` gets that method rendered and selectable, but not preselected, and its `add_payment_info` `payment_type` stays unset once picked, because both derive from this same hardcoded name rather than from the store's authored scope. Every other shape preselects nothing. Nothing is preselected while loading, while an order-placement sequence is in flight, when a method or saved-card account is already persisted (in scope or out of it), once a candidate id has already been attempted once, or when `group` is `""` (fix pass, finding R4). Preselection takes no card expression: under `group=""` it stays off even for a single card method, and naming the credit group for the tiebreak never runs there at all. A failed preselection is logged, never shown as `role="alert"` — the shopper never asked for that dispatch.
+When the order form carries no persisted selection and the scoped method list resolves to exactly one method, the section preselects it automatically — one silent `payment.setMethod` dispatch, keyed on that method's id, never on row position. When the scoped list holds more than one method, the section falls back to the sole method in the credit group, if there is exactly one — so a store offering one credit and one debit method keeps preselecting the credit one, the same method it preselected before debit was admitted. **"The credit group" here is always the methods whose `type` is `CREDIT_CARD`, not whichever member of `group` the store authored** — a store that renamed its credit payment group and listed the new name in `group` gets that method rendered and selectable, but not preselected (the API types an unknown group `OTHER`), and its `add_payment_info` `payment_type` stays unset once picked, because both derive from `PaymentMethod.type` rather than from the store's authored scope. Every other shape preselects nothing. Nothing is preselected while loading, while an order-placement sequence is in flight, when a method or saved-card account is already persisted (in scope or out of it), once a candidate id has already been attempted once, or when `group` is `""` (fix pass, finding R4). Preselection takes no card expression: under `group=""` it stays off even for a single card method, and naming the credit group for the tiebreak never runs there at all. A failed preselection is logged, never shown as `role="alert"` — the shopper never asked for that dispatch.
 
 The rule lives in the shared selection engine, not in `PaymentMethodList`: it fires even when no picker is composed, and before a `PaymentSectionController`'s overlay is ever opened.
 
-The same engine derives the one collapse fact every card leaf reads (T191). **The card payment collapses** while the persisted selection is a method this section does not serve — an id that does not resolve inside the scoped list — or a method that is **not a card**: one in neither card group (`creditCardPaymentGroup`, `debitCardPaymentGroup`) whose validator carries no card-number pattern. A store's card-like custom method, in another group but with a number pattern, is a card and hides nothing. While collapsed, `CardEntry` hides itself and stays mounted, and `SavedCards`, `CardholderDocument`, `Installments`, `InstallmentsSelect`, `SaveCard` and `BillingAddress` render nothing; `PlaceOrder`, `PaymentMethodList` and `PaymentMethodBadges` stay. See each leaf's own doc for what it keeps for the way back.
+The same engine derives the one collapse fact every card leaf reads (T191). **The card payment collapses** while the persisted selection is a method this section does not serve — an id that does not resolve inside the scoped list — or a method that is **not a card**: one whose `type` is neither `CREDIT_CARD` nor `DEBIT_CARD` and whose validator carries no card-number pattern. A store's card-like custom method, typed `OTHER` but with a number pattern, is a card and hides nothing. While collapsed, `CardEntry` hides itself and stays mounted, and `SavedCards`, `CardholderDocument`, `Installments`, `InstallmentsSelect`, `SaveCard` and `BillingAddress` render nothing; `PlaceOrder`, `PaymentMethodList` and `PaymentMethodBadges` stay. See each leaf's own doc for what it keeps for the way back.
 
 **The card option brings them back**, with or without a method it can name. With one, it dispatches it, and the leaves return once the order form confirms the selection. With none, it puts the section in card mode, locally — nothing is sent — and the leaves return at once; a card number already typed with at least eight digits is then sent again, once, for its own network. Card mode ends when another method that is not a card is picked and the order form accepts it; a refused pick leaves the shopper on the card, with the refusal in this component's `role="alert"`. Card mode is not persisted: a reload starts over from the order form's selection. Under `group=""` the collapse classifies the same way: a non-card row hides the leaves and a card row brings them back.
 
@@ -158,15 +175,17 @@ Hiding is also conditioned on a composed `PaymentMethodList` being able to bring
 | `PaymentSectionRoot` (root `div`) | Stacks the section's parts | `flex flex-col gap-6` |
 | `PaymentMethodList` (root `div`) | Stacks the payment options and the error | `flex flex-col gap-2` |
 | Fieldset (`data-fs-payment-method-list-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]` |
+| Legend (`data-fs-fieldset-legend`, native `<legend>`) | The group's visible name, from `legend` | `text-[14px] font-medium text-[var(--color-ink)]` |
 | Empty / loading picker (`data-fs-payment-method-list-state`) | Keeps the row-less container visible | `data-[fs-payment-method-list-state=empty]:min-h-12` |
-| Option row (`data-fs-radio-root`) | Each selectable option — the card option and any standalone method row alike | `flex items-center gap-3 border border-[#E0E0E0] p-3` |
-| Indicator (`data-fs-payment-method-indicator`) | The selected dot. Present on the card option too | `size-2 rounded-full bg-[#1A1A1A]` |
-| Method name (`data-fs-payment-method-name`) | The option's label — `cardLabel` on the card option, `method.name` on a standalone row | `text-[14px] text-[#1A1A1A]` |
-| Error (`data-fs-payment-method-list-error`) | Rejected-selection message | `text-[12px] text-[#B00020]` |
+| Option row (`data-fs-radio-root`) | Each selectable option — the card option and any standalone method row alike | `flex items-center gap-3 border border-[color-mix(in_srgb,var(--color-ink)_20%,transparent)] p-3` |
+| Indicator (`data-fs-payment-method-indicator`) | The selected dot. Present on the card option too | `size-2 rounded-full bg-[var(--color-primary)]` |
+| Method name (`data-fs-payment-method-name`) | The option's label — `cardLabel` on the card option, `method.name` on a standalone row | `text-[14px] text-[var(--color-ink)]` |
+| Error (`data-fs-payment-method-list-error`) | Rejected-selection message | `text-[12px]` |
 | Placing, section (`data-fs-payment-section-placing`) | Present on `PaymentSectionRoot`'s own container while an order-placement sequence is in flight (T28) — presence only; this container is never made `inert` (see the warning below) | `opacity-90` |
 | Placing, method list (`data-fs-payment-method-list-placing`) | Present on `PaymentMethodList`'s own root while placing; the picker is also `inert` and `aria-disabled` at that point | `opacity-60 cursor-not-allowed` |
 
+A status color is a `visualIdentity` feedback role of the foundation: when the store declares them, color the error row `text-[var(--color-feedback-danger)]`, the success row `text-[var(--color-feedback-success)]` and the notice row `text-[var(--color-feedback-warning)]`, never with a hex.
+
 State hooks worth styling:
 
 - `data-fs-payment-section-path="new-card"` / `="saved-card"` on the section container — present only once a path resolves, so a swatch can emphasize the active half of the section.
@@ -195,9 +214,9 @@ Styled example:
 ## Accessibility Contract
 
 **What the platform promises:** `PaymentMethodList`'s radio group carries a visible, programmatic
-accessible name (`legend`, default `"Payment method"`) — a screen-reader user hears what the rows are
-a choice *between*, not just "radio button, 1 of 3." 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
+accessible name (the `legend` message) — a screen-reader user hears what the rows are a choice
+*between*, not just "radio button, 1 of 3." A store that leaves `legend` unauthored ships a nameless
+group, and the formatter logs `message.missing`. Each row keeps its own accessible name
 from the method's own display name. The group is a native `<fieldset>`/`<legend>` pair (not `aria-label`
 on a `<div>`), so it is also visible to sighted and low-vision shoppers and reachable by page-level
 translation tooling. Keyboard: the group is one Tab stop — Tab lands on the checked row, and the arrow

package/dist/docs/phone-field.md

@@ -57,13 +57,13 @@ RFC's named double-binder hole.
 | `defaultValue` | string | `''` | Uncontrolled initial raw value (pre-fill). |
 | `onValueChange` | `(value: string) => void` | — | Fires on every change with the raw (unmasked) value. |
 | `country` | `'US' \| 'BR'` | `'US'` | Selects the mask and validation rule; other codes fall back to US. |
-| `label` | string | `'Phone'` | Accessible label. |
+| `label` | string | — | Accessible label, formatted by the owner from its own message field. Unbound and omitted, it renders empty. |
 | `isDisabled` | boolean | `false` | Disables the input (e.g. while a write is in flight). |
 | `placeholder` | string | — | Input placeholder. |
 | `invalid` | boolean | — | Host-forced invalid state; overrides the internal blur validation when set. |
 | `error` | string | — | Host-supplied error text; overrides the internal error string when set. |
-| `errorInvalid` | string | `'Invalid phone number'` | Inline error for an invalid format. |
-| `errorRequired` | string | `'Phone number is required'` | Inline error when a mandatory field is empty. |
+| `errorInvalid` | string | — | Inline error for an invalid format, formatted by the owner. Omitted, the field is still invalid but shows no text. |
+| `errorRequired` | string | — | Inline error when a mandatory field is empty, formatted by the owner. Omitted, the field is still invalid but shows no text. |
 | `requirement` | `'mandatory' \| 'optional'` | — | `mandatory`: empty blocks; `optional`: empty allowed, format still checked when present. Unset is no opinion, so a phone with no fieldset baseline is optional. It only ever raises — bound to a fieldset whose rule already says required, `'optional'` does not lower it. There is no value that suppresses the field: a store that does not want it removes the particle from the page instead (`rfc-user-identity.md` F9). |
 | `onBlur` | `() => void` | — | Fires on blur, after validation runs. |
 | `ref` | `Ref<HTMLInputElement>` | — | Lands on the masked `<input type="tel">`. Composed with react-hook-form's own ref on the bound path — a caller ref and react-hook-form's ref are both honoured. |
@@ -148,7 +148,7 @@ trade of Decision 4; widen store CSS keyed on the specific hooks if it must also
 
 - **Validating on every keystroke.** Format validation runs on blur/submit only.
 - **Wiring GraphQL into this particle.** It is data-agnostic; use `ClientProfilePhoneControl` for the checkout-bound binding.
-- **Localizing via a message id.** There is no `react-intl`; pass `label` / `errorInvalid` / `errorRequired` as strings.
+- **Expecting package copy.** The particle has none. Its owner (`ClientProfilePhoneControl`, `ClientProfileFieldsetPhoneControl`, `MyAccountProfilePhoneControl`) formats `label` / `errorInvalid` / `errorRequired` from its own message fields and passes the strings.
 - **Reading the masked value.** `onValueChange` emits the raw (unmasked) value — persist that, not the display string.
 
 ---

package/dist/docs/place-order.md

@@ -1,7 +1,7 @@
 # PlaceOrder
 
 **Category:** commerce
-**Purpose:** The checkout's place-order CTA. Runs the three-call payment sequence (start transaction, the holder's direct-to-gateway submission, gateway callback), blocks interaction while it runs, and renders one inline outcome — an error message or a success confirmation — once it settles, plus an optional status message while it runs.
+**Purpose:** The checkout's place-order CTA. Runs the three-call payment sequence (start transaction, the holder's direct-to-gateway submission, gateway callback), blocks interaction while it runs, and renders one inline outcome — an error message or a success confirmation — once it settles, plus an optional status message while it runs. When the bank asks for a 3D Secure challenge and the store authored a return page (`challengeReturnHref`), it sends the shopper to the bank instead, and the [[challenge-return]] page finishes the order.
 
 ---
 
@@ -43,7 +43,7 @@ PaymentSectionRoot (or PaymentSectionController)
 
 Child order reflects visual order. `PlaceOrder` composes under **either** payment root with no change — both provide the same `payment` context and the same submission channel (ADR-0009).
 
-`PlaceOrder` never reads or holds a card field. It calls `usePlaceOrder`, the T13 orchestration hook, which resolves a continuation that `CardEntry`/`SavedCards` registered on a submission channel by the shopper's entry path — this component only knows there is a hook to call, a loading state to block on, and an outcome to render. It also reads `usePayment().draft.billingAddressDifferent` (T11) and forwards it into `usePlaceOrder`, so the gateway descriptor carries whether the shopper picked a different billing address — the one other fact this component touches, and still not a card field.
+`PlaceOrder` never reads or holds a card field. It calls `usePlaceOrder`, the orchestration hook, which resolves a continuation that `CardEntry`/`SavedCards` registered on a submission channel by the shopper's entry path — this component only knows there is a hook to call, a loading state to block on, and an outcome to render. It also reads `usePayment().draft.billingAddressDifferent` and forwards it into `usePlaceOrder`, so the gateway descriptor carries whether the shopper picked a different billing address — the one other fact this component touches, and still not a card field.
 
 ---
 
@@ -51,32 +51,73 @@ Child order reflects visual order. `PlaceOrder` composes under **either** paymen
 
 ### PlaceOrder
 
-No sub-components. Renders a button, an optional status region while the sequence runs (only when `placingMessage` is authored), and, once the sequence has settled, one inline outcome region (error or success).
+No sub-components. Renders a button, an optional status region while the sequence runs (only when the `placingMessage` message is authored), and, once the sequence has settled, one inline outcome region (error or success).
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | `"Place order"` | Button label while idle. |
-| `placingLabel` | string | `"Placing order..."` | Button label while the sequence is in flight. |
-| `placingMessage` | string | *(none)* | Status message in its own `role="status"` region beside the button while the order is being placed. Absent or blank renders nothing. The button text while placing stays `placingLabel`. |
-| `resumeLabel` | string | `"Complete your order"` | Button label while a surviving attempt offers a resume — the card already left the browser (or its fate is unknown) and the next click finalizes it instead of running the full sequence again. |
-| `successMessage` | string | `"Order placed successfully."` | Shown once the sequence settles with no errors. |
-| `missingSubmissionMessage` | string | `"Enter your payment details before placing the order."` | Shown when `placeOrder()` is invoked with no registered submission for the current path (e.g. the shopper never finished entering a card). |
-| `missingMethodMessage` | string | `"Choose a payment method before placing the order."` | Shown when no payment method is selected yet. |
-| `invalidTransactionMessage` | string | `"Unable to start the payment. Please try again."` | Shown when `startTransaction` resolves incomplete transaction data. |
-| `networkErrorMessage` | string | `"Unable to complete the request. Please try again."` | Shown for an infrastructure-level failure reaching the payment gateway action. |
-| `missingDocumentMessage` | string | `"Enter your document before placing the order."` | Shown when the selected method requires a cardholder document and none is set. |
-| `invalidDocumentMessage` | string | `"Enter a valid document before placing the order."` | Shown when the typed cardholder document fails validation. |
-| `unavailableMethodMessage` | string | `"Choose another payment method before placing the order."` | Shown instead of the two document messages above when the selected method calls for a cardholder document the page is not showing — a method the card form cannot pay with, or one outside the payment root's `group` — so the shopper has to choose another payment method. |
-| `unsavedBillingAddressMessage` | string | `"Save your billing address before placing the order."` | Shown when the shopper declined "same as delivery" but never saved a custom billing address. |
-| `invalidCardDataMessage` | string | `"Enter valid card details before placing the order."` | Shown when the new-card draft itself fails validation before ever reaching the gateway. |
-| `unsupportedNetworkMessage` | string | `"This card is not from a network the store accepts. Use another card or choose another payment method."` | Shown when the typed card number is well-formed but no network the store accepts claims it, whether or not a payment method is selected. |
-| `invalidSecurityCodeMessage` | string | `"Enter a valid security code before placing the order."` | Shown when a saved-card submission is refused for a missing or invalid CVV. |
-| `gatewayErrorMessage` | string | `"Unable to complete the payment. Please try again."` | Shown when the payment gateway itself refuses the submitted card. |
-| `inFlightMessage` | string | `"This order is already being placed. Please wait."` | Shown when a click lands on an order-placement attempt whose own sequence is still running — a transaction this instance did not open, and which nothing here may finalize or re-run. |
-| `unconfirmedMessage` | string | `"We could not confirm your order yet. Your payment may still be processing, so please do not pay again."` | Shown when the payment was handed to the gateway but the order could not be confirmed, so it may still be processing. Renders in its own `role="status"` node, never in the error alert. |
-| `successHref` | page reference or string | `{ "standard": "order-placed" }` | Page navigated to after a successful placement. A page reference gets the placed order's group as its `orderGroup` param, percent-encoded. A string is a logical path of this store, navigated as written under the binding's base path. **Success-gated**: the navigation is requested only once an attempt settles with no errors and a non-null order group — never on a refusal. |
-
-Every message prop above is resolved by the `code` of the client-synthesized `PaymentUserError` this CTA renders — in its alert, or in its status node for `unconfirmedMessage` — never by which component produced the error. A `PaymentUserError` whose code this component does not author (a server-returned code) renders that error's own `message` unchanged.
+| `successHref` | page reference or string | `{ "standard": "order-placed" }` | Page navigated to after a successful placement. A page reference gets the placed order's Node id (`orderNodeId`) as its `orderId` param, percent-encoded. A string is a logical path of this store, navigated as written under the binding's base path. **Success-gated**: the navigation is requested only once an attempt settles with no errors and a non-null order Node id — never on a refusal. |
+| `challengeReturnHref` | page reference | *(none)* | The page the bank sends the shopper back to after a 3D Secure challenge: a page of this store that composes [[challenge-return]], e.g. `{ "page": "checkout-challenge-return" }`. A page reference only; a string, or a page the route map does not hold, is refused with a dev-only `console.warn` naming this prop. No default, because a standard page cannot name a return page. Absent: no return URL is sent and a bank challenge is refused as before. |
+
+**Content model** (`place-order`): every label and message below is an ICU message field with no arguments. Each reads only from `$content`: an unauthored label or refusal message renders empty and logs `message.missing`. A store without CMS authors the fields on the element, as below; a CMS-bound store keeps them in content.
+
+| Field | Message source | Notes |
+|-------|----------------|-------|
+| `label` | `"Place order"` | Button label while idle. |
+| `placingLabel` | `"Placing order..."` | Button label while the sequence is in flight. |
+| `placingMessage` | `"Processing your payment. Please keep this page open."` | Status message in its own `role="status"` region beside the button while the order is being placed. Read only while placing: a missing or blank message renders no region, and a missing one logs `message.missing`. The button text while placing stays `placingLabel`. |
+| `resumeLabel` | `"Complete your order"` | Button label while a surviving attempt offers a resume — the card already left the browser (or its fate is unknown) and the next click finalizes it instead of running the full sequence again. |
+| `successMessage` | `"Order placed successfully."` | Shown once the sequence settles with no errors. |
+| `missingSubmissionMessage` | `"Enter your payment details before placing the order."` | Shown when `placeOrder()` is invoked with no registered submission for the current path (e.g. the shopper never finished entering a card). |
+| `missingMethodMessage` | `"Choose a payment method before placing the order."` | Shown when no payment method is selected yet. |
+| `invalidTransactionMessage` | `"Unable to start the payment. Please try again."` | Shown when `startTransaction` resolves incomplete transaction data. |
+| `networkErrorMessage` | `"Unable to complete the request. Please try again."` | Shown for an infrastructure-level failure reaching the payment gateway action. |
+| `missingDocumentMessage` | `"Enter your document before placing the order."` | Shown when the selected method requires a cardholder document and none is set. |
+| `invalidDocumentMessage` | `"Enter a valid document before placing the order."` | Shown when the typed cardholder document fails validation. |
+| `unavailableMethodMessage` | `"Choose another payment method before placing the order."` | Shown instead of the two document messages above when the selected method calls for a cardholder document the page is not showing — a method the card form cannot pay with, or one outside the payment root's `group` — so the shopper has to choose another payment method. |
+| `unsavedBillingAddressMessage` | `"Save your billing address before placing the order."` | Shown when the shopper declined "same as delivery" but never saved a custom billing address. |
+| `missingProfileNameMessage` | `"Enter your first and last name before placing the order."` | Shown when the cart's profile has no first name or no last name. See the cart-profile check below. |
+| `missingProfilePhoneMessage` | `"Enter your phone number before placing the order."` | Shown when the cart's profile has a first and last name but no phone. See the cart-profile check below. |
+| `invalidCardDataMessage` | `"Enter valid card details before placing the order."` | Shown when the new-card draft itself fails validation before ever reaching the gateway. |
+| `unsupportedNetworkMessage` | `"This card is not from a network the store accepts. Use another card or choose another payment method."` | Shown when the typed card number is well-formed but no network the store accepts claims it, whether or not a payment method is selected. |
+| `invalidSecurityCodeMessage` | `"Enter a valid security code before placing the order."` | Shown when a saved-card submission is refused for a missing or invalid CVV. |
+| `gatewayErrorMessage` | `"Unable to complete the payment. Please try again."` | Shown when the payment gateway itself refuses the submitted card. |
+| `inFlightMessage` | `"This order is already being placed. Please wait."` | Shown when a click lands on an order-placement attempt whose own sequence is still running — a transaction this instance did not open, and which nothing here may finalize or re-run. |
+| `unconfirmedMessage` | `"We could not confirm your order yet. Your payment may still be processing, so please do not pay again."` | Shown when the payment was handed to the gateway but the order could not be confirmed, so it may still be processing. Renders in its own `role="status"` node, never in the error alert. |
+| `declinedMessage` | `"Check your payment information or choose another payment method."` | Shown when the payment gateway answered the callback and refused the payment (server code `PAYMENT_DECLINED`). Renders in the error alert, and the shopper may submit again. One sentence for every refusal: the API never forwards the gateway's own words. |
+| `lapsedTransactionMessage` | `"We could not confirm your order yet. Your payment may still be processing, so please do not pay again."` | Shown when the payment window lapsed before the order was confirmed (server code `MISSING_TRANSACTION_COOKIES`), or the order group the callback sent is not the one this session started (`ORDER_GROUP_MISMATCH`). Renders in the error alert, and the attempt stays resume-only, so the source tells the shopper not to pay again. |
+| `challengeUnavailableMessage` | `"Your bank asked for an extra verification step that we could not open. Your payment may still be processing, so please do not pay again."` | Shown when the bank asks for a challenge this CTA cannot follow (server code `REDIRECT_REQUIRED` with no usable address, or no return page authored). The attempt stays resume-only. |
+
+### The cart-profile check
+
+The payment root reads the cart's `clientProfile` (first name, last name and phone, never the profile's document) and the place-order check refuses a click while a name or the phone is blank, after the document and billing-address checks. The profile page may be a different page from the payment page: the check reads the cart, not what the page composes. A profile that the root did not receive, because it is still resolving or because a hand-written `$data` omits it, never refuses and VTEX stays the backstop. A profile that arrived with every field `null` is a read, empty profile and does refuse. Only the code is logged, never a name or a phone.
+
+### The placing state
+
+While this CTA's own sequence runs, the button reads `placingLabel`, is disabled and carries `aria-busy`. When the `placingMessage` message is authored, an `<output data-fs-place-order-placing>` follows the button with that text. The field is read only while placing: a missing or blank message renders the busy button and nothing else, and a missing one logs `message.missing`. The message is rendered as a text node, so markup in it shows as typed. `placingLabel` stays the button's text; the message is a separate surface for copy that explains the wait, such as asking the shopper to keep the page open.
+
+The surface cannot show without the form being blocked. The CTA publishes its `placing` onto the payment context in a layout effect, and `PaymentMethodList`, `CardEntry`, `SavedCards`, `CardholderDocument`, `Installments`, `InstallmentsSelect`, `SaveCard` and `BillingAddress` read it and render `inert` and `aria-disabled` in the same commit that mounts the surface. The payment root's own container only gets a presence attribute, never `inert`, because this CTA's alert and status regions live inside it (see [[payment]]).
+
+The surface follows the CTA that is running the sequence, not the section:
+
+- A click refused before any call (no registered submission, no method, the document gate, a pre-flight refusal) never mounts it, not even for one frame.
+- With two `PlaceOrder` elements under one root, only the one that was clicked shows it. The other is disabled without one.
+- A CTA that remounts over an attempt waiting for a resume shows it only after the shopper clicks `resumeLabel`, while the callback is pending, although the section is already blocked.
+- If the CTA unmounts mid-sequence, the surface leaves with it and the leaves stay `inert` until the attempt settles.
+- It is a status region, never an alert, and the error, unconfirmed and success regions are absent while it shows, including on the second attempt after a refused one.
+
+These are pinned in the "authored placing surface" suite of `place-order.test.tsx`. The bank-challenge redirect keeps the surface on screen while the page leaves (below).
+
+### The bank challenge (3D Secure)
+
+When `challengeReturnHref` names a page, the request to the payment gateway carries the absolute URL of that page, `<origin><public path>?orderGroup=<group>&redirect=true`, built under the current binding's base path, and `redirect=false`. If the gateway callback then answers that the bank needs a challenge and gives an absolute `http(s)` address, this CTA navigates the document to it once, keeps the button disabled and busy, keeps the authored `placingMessage` message showing and the rest of the payment form blocked, and draws neither the error alert nor the success line while the page leaves. The result of the click still carries `REDIRECT_REQUIRED`, and the attempt stays `unresolved`: the order is finished on the return page, never by this CTA, and nothing is paid twice.
+
+The redirect is followed only when a return URL was sent, the answer carries `REDIRECT_REQUIRED` and no order, and the address is absolute `http(s)`. A site-relative or protocol-relative address, any other scheme, or an answer without a usable address is refused like any other callback answer: the alert shows `challengeUnavailableMessage` and the attempt stays resume-only. A store that authored no return page keeps exactly that refusal.
+
+A resume (the button reading `resumeLabel`) that gets a challenge answer redirects the same way. A resume that finishes the order reports its `purchase` analytics event, reading the value and currency from the settled order, once per order (the marker is kept in `localStorage`, see ADR-0023).
+
+The once-per-order rule spans all three ways an order can finish: a single pass of this CTA, its in-page resume, and the [[challenge-return]] page. Each goes through `claimPurchase` in `sdk/payment/resumed-purchase.ts`, a synchronous check-and-set on `fs:purchase-sent:<order group>` that is written before the event is sent, so an emission that throws is never repeated, and that falls back to an in-memory set for one page lifetime when storage refuses. A resume reads the order because the attempt record deliberately carries no value or currency. It reports for `APPROVED`, `PENDING` (anti-fraud review) and `UNKNOWN`, and not for `DENIED` or an order with no total. The marker is claimed only after those checks, so an order that was not reported is not marked as reported. A hook consumer that passes no `readSettledOrder` gets no event from a resume and no error.
+
+Every refusal message above is resolved by the `code` of the `PaymentUserError` this CTA renders — in its alert, or in its status node for `unconfirmedMessage` — never by which component produced the error. The server codes are those of `paymentStartTransaction` and `paymentGatewayCallback`: `PAYMENT_DECLINED` (`declinedMessage`), `MISSING_TRANSACTION_COOKIES` and `ORDER_GROUP_MISMATCH` (`lapsedTransactionMessage`), `REDIRECT_REQUIRED` (`challengeUnavailableMessage`), `MISSING_PAYMENT_METHOD_SELECTION`, `INVALID_TRANSACTION_DATA`, and the cart faults `MISSING_CART_CONTEXT` and `CART_NOT_FOUND`, which share `networkErrorMessage`. The card form's `CARD_ENTRY_COLLAPSED` reads `unavailableMethodMessage`. Every `message` is diagnostic and never renders: a code this component does not word (one a newer server added) shows `networkErrorMessage` and logs `message.unknown-code`.
 
 **Data:** declares its own thin `fragment PlaceOrderData on Query` selecting `payment.selectedMethodId`, `payment.selectedInstallment`, and `payment.methods { id groupName }` — the exact slice the orchestration hook needs, no more. **Actions:** declares `actions: { payment: ['startTransaction', 'gatewayCallback'], analytics: ['track'] }`. Must be inside a payment root (`requiresContext: 'payment'`).
 
@@ -97,6 +138,7 @@ Every message prop above is resolved by the `code` of the client-synthesized `Pa
     "props": {
       "label": "Place order",
       "placingLabel": "Placing order...",
+      "resumeLabel": "Complete your order",
       "successMessage": "Order placed successfully.",
       "successHref": { "standard": "order-placed" }
     }
@@ -104,7 +146,7 @@ Every message prop above is resolved by the `code` of the client-synthesized `Pa
 }
 ```
 
-`successHref` is shown here with its default value. A string must be a logical path of this store, such as `/obrigado`; an absolute URL, a protocol-relative URL, or a non-http(s) scheme is refused rather than navigated to.
+`successHref` is shown here with its default value. The example authors only the button labels and the success message; a store authors every message field of the content type, refusals included. A string must be a logical path of this store, such as `/obrigado`; an absolute URL, a protocol-relative URL, or a non-http(s) scheme is refused rather than navigated to.
 
 ---
 
@@ -113,18 +155,22 @@ Every message prop above is resolved by the `code` of the client-synthesized `Pa
 - **Nesting `PlaceOrder` inside `CardEntry` or `SavedCards`.** It must be a sibling of both under the same payment root, so one CTA serves both the new-card and saved-card paths.
 - **Placing `PlaceOrder` outside any `PaymentSectionRoot`/`PaymentSectionController`.** It throws at render — there is no payment context or submission channel to resolve.
 - **Confusing it with `BuyButtonButton`.** `BuyButtonButton` adds a product to the cart on a PDP; `PlaceOrder` runs the payment sequence in checkout. They are never composed together.
-- **Expecting a redirect or a 3D Secure challenge.** v1 is the direct-API mode only — the shopper stays on the page and the outcome renders inline. The redirect mode is phase 2.
+- **Expecting a 3D Secure challenge without a return page.** The shopper is sent to the bank only when `challengeReturnHref` names a page of the store that composes `ChallengeReturn`. Without it the shopper reads the server's `REDIRECT_REQUIRED` message and the attempt stays locked. Only accounts that deliver 3D Secure by redirect are supported; payment-app delivery is out of scope.
+- **Authoring `challengeReturnHref` as a string.** It is a page reference. A string cannot be turned into the absolute return URL the bank must come back to, so it is refused with a dev-only warning and no return URL is sent.
 
 ---
 
 ## Known limitations
 
-- **A remount reads the surviving attempt instead of losing it — but the attempt itself does not survive a page reload.** T29 (`specs/make-an-order-attempt-survive-a.md`) gave the place-order sequence an identity-and-phase record on the payment context, above this component's own mount, alongside `placing`. Closing and reopening a `Dialog`/`Drawer` popup with no `keepMounted` no longer resets it: a settled attempt renders disabled with no further calls (`succeeded` is derived from the record, not only from this instance's own `attempted`/`userErrors`), and an attempt whose card already reached the gateway before the remount offers a resume (`resumeLabel`) that finalizes the same transaction — never a fresh `startTransaction` or a second card submission. This closes the case this bullet used to attribute to "a settled-order read model that outlives the overlay (T16/T17)": both are merged, and the limitation still stood, because neither one ever touched this component's own mount-scoped guard, which is what actually caused the duplicate-order risk. What is still not covered: a full page reload loses the attempt (no `sessionStorage` or equivalent persists it today — T29's own OQ-3), and the direct-to-gateway POST's abort budget (30s, `sdk/payment/gateway.ts`) is an unconfirmed placeholder pending a number from payments (OQ-7).
+- **A remount reads the surviving attempt instead of losing it, but the attempt does not survive a page reload.** The place-order sequence keeps an identity-and-phase record on the payment context, above this component's own mount, next to `placing`. Closing and reopening a `Dialog` or `Drawer` popup with no `keepMounted` does not reset it: a settled attempt renders disabled with no further calls (`succeeded` is derived from the record, not only from this instance's own `attempted` and `userErrors`), and an attempt whose card already reached the gateway offers a resume (`resumeLabel`) that finalizes the same transaction, never a fresh `startTransaction` or a second card submission. A full page reload loses the attempt, because nothing persists it in `sessionStorage` or elsewhere. The one exception is a shopper sent to the bank, who returns to the `ChallengeReturn` page, which holds no attempt and finishes the order from the order group in its own URL. The direct-to-gateway POST's abort budget (30 seconds, `GATEWAY_REQUEST_TIMEOUT_MS` in `sdk/payment/gateway.ts`) is a placeholder that has not been confirmed with payments.
 - **A refusal raised before the card POST leaves the CTA on `label`, not `resumeLabel`.** A card form that refuses after the transaction opened but before any request was issued (a missing `sendPayments` action, an origin the gateway builder will not post to, its own draft check) reports `reachedGateway: false`, so the attempt is recorded as refused: nothing was paid, the button keeps its `label`, and the next click opens a fresh transaction. A request that reached the gateway, or that cannot be shown not to have (a rejected request, a holder that throws or resolves a malformed result), stays resume-only and reads `resumeLabel`.
-- **A failed `gatewayCallback` stays on `resumeLabel` today; the retry rule is in place but dormant.** Once the card POST was accepted, the hook only frees the next click for a callback error whose server code is neither `REDIRECT_REQUIRED` nor `MISSING_TRANSACTION_COOKIES` and that carries no `orderId`. The server sends no such code yet (task T225 will), so every callback failure that exists today (a timeout, a network failure, an unreadable result, a bank challenge, a lapsed transaction cookie) stays on `resumeLabel` and only re-issues the callback. A shopper whose card was refused still cannot enter another card without a reload until T225 lands.
-- **Sibling placement (never nested inside `CardEntry`/`SavedCards`) is a convention, not something the compiler enforces.** `requiresContext: 'payment'` only fails a build with no payment-providing ancestor at any depth; it cannot detect that this component was nested one level too deep. Getting this wrong compiles clean and still leaves the other entry path with no CTA at all (see `specs/place-order.md`'s Open items).
+- **A refused `gatewayCallback` frees the next click; every other callback failure stays on `resumeLabel`.** Once the card POST was accepted, the hook frees the next click for a callback error whose server code is none of `REDIRECT_REQUIRED`, `MISSING_TRANSACTION_COOKIES` and `ORDER_GROUP_MISMATCH` and that carries no `orderId`. `ORDER_GROUP_MISMATCH` is the API's answer when the order group sent with the callback is not the one this browser session's own start bound (or the session holds none): nothing is sent to VTEX, and because the card POST was already accepted the attempt stays locked, exactly like the other two. The API answers a refusal from the gateway with `PAYMENT_DECLINED`, so a shopper whose card was refused reads `declinedMessage` and can enter another card without a reload. The freed attempt is recorded as refused with no order group, so the next click opens a fresh transaction and never calls the callback again with the old group. A timeout, a network failure, an unreadable result, a gateway that was unreachable (502 to 504), a bank challenge, a lapsed transaction cookie or an order group that does not match the session stays on `resumeLabel` and only re-issues the callback, because the payment may still be processing.
+- **A shopper who presses Back from the bank page may find a blocked form.** The browser may restore this page from its back-forward cache with `placing` still true, so the button stays disabled until a reload. Nothing was charged by this checkout; VTEX cancels the order it opened after five minutes. A reload clears the block and the shopper places a new order.
+- **The return URL carries the order group.** `?orderGroup=<group>&redirect=true` sits in the browser history and, for same-origin requests, in the `Referer`. The order's Node id is a reversible base64 of the same group, so this exposes nothing the confirmation URL did not already.
+- **Sibling placement (never nested inside `CardEntry`/`SavedCards`) is a convention, not something the compiler enforces.** `requiresContext: 'payment'` only fails a build with no payment-providing ancestor at any depth; it cannot detect that this component was nested one level too deep. Getting this wrong compiles clean and still leaves the other entry path with no CTA at all.
 - **`successHref` navigates with `replace`, not `push`.** The payment step is removed from the history stack, so the Back button from the confirmation page returns to whatever preceded payment, not to the payment step itself — deliberate (placing an order is terminal, and a live place-order CTA one Back press away risks a duplicate transaction), but a divergence from this package's other redirect-on-success component, `CartRedirectOnAdd`, which uses `push`.
 - **A string `successHref` that is not a path of this store fails closed.** An absolute URL, a protocol-relative URL (`//host/...`), or a non-http(s) scheme is refused rather than navigated to, with a dev-only `console.warn`. This keeps a store schema from turning the CTA into a redirect off the storefront right after a real purchase. A store without a confirmation page in its route map also stays on the payment page.
+- **A saved card that needs no security code uses Start Transaction without gateway calls; platform order creation remains unconfirmed.** Its submission sends no request and resolves with `completesWithoutGateway: true`. The hook honours the flag only as the literal `true` with an empty `userErrors` list: it then skips Send Payments and the gateway callback, takes the order group as the order id, and reports `reachedGateway: true`; the client treats the attempt as terminal, so a second run is not legal. Any other value, including a truthy non-boolean, keeps the callback leg. A failed start still refuses the attempt. Whether the platform creates the order on that route alone is not proven in this repository.
 - **Focus moves on a refused click only, never for a result the gateway returned.** When a click is refused because the cardholder document is missing or malformed, or the custom billing address was never saved, `PlaceOrder` asks the payment root to move keyboard focus to that field or form. This applies to any result that did not reach the gateway (`reachedGateway: false`) whose first error carries one of those three codes, including a code a registered submission returned itself after the transaction opened. A refusal carrying any other code, and any result that reached the gateway (a decline included, whatever its code), moves nothing, and neither does a re-render or a remount. The reason stays in the existing outcome alert.
 
 ## Styling
@@ -132,12 +178,14 @@ Every message prop above is resolved by the `code` of the client-synthesized `Pa
 | Component | What you style | Plausible classes |
 |---|---|---|
 | `PlaceOrder` (root `div`) | Layout wrapper stacking the button and the outcome region | `flex flex-col gap-[8px] items-start` |
-| Button (`data-fs-place-order-button`) | The CTA itself — full-width pill, disabled/busy states | `inline-flex items-center justify-center w-full h-[44px] px-[20px] bg-[#C8102E] text-white rounded-[4px] text-[14px] font-bold uppercase cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed` |
-| Placing (`data-fs-place-order-placing`) | The status region, present only while this CTA's own sequence runs and only when `placingMessage` is authored. Every payment leaf is `inert` for as long as it exists. | `text-[13px] text-[#666666]` |
-| Error (`data-fs-place-order-error`) | Inline error line, `role="alert"` | `text-[13px] text-[#C0392B]` |
-| Unconfirmed (`data-fs-place-order-unconfirmed`) | Inline notice that the order could not be confirmed yet, `role="status"` | `text-[13px] text-[#8A6D3B]` |
-| Success (`data-fs-place-order-success`) | Inline success line, `role="status"` | `text-[13px] text-[#1E8E3E]` |
-| Success order id (`data-fs-place-order-success-order-id`) | The placed order's id, inside the success line | `font-mono text-[12px] text-[#666666]` |
+| Button (`data-fs-place-order-button`) | The CTA itself — full-width pill, disabled/busy states | `inline-flex items-center justify-center w-full h-[44px] px-[20px] bg-[var(--color-primary)] text-[var(--color-surface)] rounded-[var(--radius-base)] text-[14px] font-bold uppercase cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed` |
+| Placing (`data-fs-place-order-placing`) | The status region, present only while this CTA's own sequence runs and only when the `placingMessage` message is authored. Every payment leaf is `inert` for as long as it exists. | `text-[13px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]` |
+| Error (`data-fs-place-order-error`) | Inline error line, `role="alert"` | `text-[13px]` |
+| Unconfirmed (`data-fs-place-order-unconfirmed`) | Inline notice that the order could not be confirmed yet, `role="status"` | `text-[13px]` |
+| Success (`data-fs-place-order-success`) | Inline success line, `role="status"` | `text-[13px]` |
+| Success order id (`data-fs-place-order-success-order-id`) | The placed order's id, inside the success line | `font-mono text-[12px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]` |
+
+A status color is a `visualIdentity` feedback role of the foundation: when the store declares them, color the error row `text-[var(--color-feedback-danger)]`, the success row `text-[var(--color-feedback-success)]` and the notice row `text-[var(--color-feedback-warning)]`, never with a hex.
 
 Always include `disabled:` styling on the button — it disables automatically while the sequence runs and again once it succeeds.
 

package/dist/docs/postal-code-field.md

@@ -115,7 +115,9 @@ The element `id` is the durable content key for the `postal-code-field` entry sl
 | `data-fs-postal-code-field` | The field container (stacks label, input, error) | `flex flex-col gap-[8px]` |
 | `data-fs-postal-code-field-label` | The label typography | `text-[13px] font-semibold text-[#1a1a1a]` |
 | `data-fs-postal-code-field-input` | The input box; compose with `data-invalid`, `data-focused`, `data-disabled` | `h-11 rounded-lg border border-[#d4d4d4] px-4 text-[15px]` |
-| `data-fs-postal-code-field-error` | The inline error text | `text-[12px] text-[#c1272d]` |
+| `data-fs-postal-code-field-error` | The inline error text | `text-[12px] text-[var(--color-feedback-danger)]` |
+
+The role colors above are the foundation's `visualIdentity` roles (`--color-feedback-danger`), so they follow the store when it changes them.
 
 ---
 

package/dist/docs/pricing.md

@@ -135,7 +135,8 @@ Discount badge for the `listPrice`-vs-`price` markdown. Renders `null` when ther
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `format` | `"percentage"` \| `"absolute"` | `"percentage"` | `percentage` shows `-25%`; `absolute` shows the currency-formatted markdown `-R$ 10,00` (`listPrice - price`, using the active storefront context). Mirrors `ProductCardDiscount`. |
-| `template` | string | format-derived (`"-{percentage}%"` or `"-{amount}"`) | Placeholders: `{percentage}` (integer markdown) and `{amount}` (currency-formatted `listPrice - price`). Left unset, it defaults to the format-appropriate template; an explicit value overrides it. |
+
+**Content model** (`pricing-discount`): `percentageTemplate`, an ICU message with a `percentage` argument (integer markdown), rendered for `format: "percentage"`, and `amountTemplate`, with an `amount` argument (currency-formatted `listPrice - price`), rendered for `format: "absolute"`. Only the message the format picks is formatted.
 
 ### PricingInstallments
 
@@ -175,20 +176,15 @@ Renders the surrounding plan's `paymentMethod` (e.g. *"Visa"*, *"Pix"*) as a `<s
 
 ### PricingInstallment
 
-Single installment line. Must be a descendant of `PricingInstallments`, `PricingInstallmentPlan`, or `PricingInstallmentsForPlan`. If `children` are provided, they replace the template text entirely (useful for CTAs like *"Buy with store card"*).
+Single installment line. Must be a descendant of `PricingInstallments`, `PricingInstallmentPlan`, or `PricingInstallmentsForPlan`. If `children` are provided, they replace the text entirely (useful for CTAs like *"Buy with store card"*). No props.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `template` | string | `"{count}x de {value}"` | placeholders: `{count}`, `{value}` |
-| `interestFreeLabel` | string | `"sem juros"` | appended when the plan is interest-free; pass `""` to omit |
+**Content model** (`pricing-installment`): `template`, an ICU message with `count` and `value` (currency-formatted) arguments, and `interestFreeLabel`, appended when the installment is interest-free.
 
 ### PricingSpotDiscount
 
-Discount badge for the cash/Pix difference between `spotPrice` and `price` (e.g. *"com mais 9% OFF no Pix"*). Renders `null` when `spotPrice >= price`. Symmetric to `PricingDiscount` but for the spot-price percentage. Rounding is nearest-integer.
+Discount badge for the cash/Pix difference between `spotPrice` and `price` (e.g. *"com mais 9% OFF no Pix"*). Renders `null` when `spotPrice >= price`. Symmetric to `PricingDiscount` but for the spot-price percentage. Rounding is nearest-integer. No props.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `template` | string | `"-{percentage}%"` | placeholder: `{percentage}` (the rounded spot-discount percentage) |
+**Content model** (`pricing-spot-discount`): `template`, an ICU message with a `percentage` argument (the rounded spot-discount percentage).
 
 ### PricingHighlights
 
@@ -204,11 +200,11 @@ Iterator over `Offer.promotions` — structured deals like *"Compre 3 leve 2"*,
 
 ### PricingPromotion
 
-Renders the current promotion via the `template` prop. Reads from the context set by `PricingPromotions`. Children override the default text.
+Renders the current promotion from its `$content` template. Reads from the context set by `PricingPromotions`. Children override the text. No props.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `template` | string | `"{name}"` | placeholder: `{name}` (the promotion's display name) |
+**Content model** (`pricing-promotion`): `template`, an ICU message with a `name` argument (the promotion's display name).
+
+Every `Pricing*` message is read only from `$content`. A missing message renders empty and logs `message.missing`; with `children`, no message is formatted.
 
 ---
 
@@ -230,7 +226,7 @@ A full PDP pricing block as it would appear in a generated page schema:
   },
   "pricing-list":      { "type": "PricingListPrice" },
   "pricing-selling":   { "type": "PricingSellingPrice" },
-  "pricing-discount":  { "type": "PricingDiscount", "props": { "template": "-{percentage}%" } },
+  "pricing-discount":  { "type": "PricingDiscount", "props": { "percentageTemplate": "-{percentage}%" } },
   "pricing-spot":      { "type": "PricingSpotPrice" },
   "pricing-installments": {
     "type": "PricingInstallments",
@@ -451,12 +447,12 @@ Style `PricingRoot` as a vertical stack and each price line as its own typograph
 | Component | What you style | Plausible classes |
 |---|---|---|
 | `PricingRoot` | Stacks the price lines | `flex flex-col gap-[4px] mt-[8px] w-full` |
-| `PricingSellingPrice` | The headline price — large, bold, often the brand color | `text-[28px] leading-[1.15] font-bold text-[#C8102E] tracking-[-0.01em] block` |
-| `PricingListPrice` | The struck-through original price — small and muted | `text-[13px] leading-[1.4] font-normal text-[#8A8A8A] line-through` |
-| `PricingDiscount` / `PricingSpotDiscount` | Savings badge — small, often a colored chip | `inline-flex items-center px-[6px] py-[2px] rounded-[4px] bg-[#C8102E] text-white text-[12px] font-semibold` |
-| `PricingInstallments` / `PricingInstallment` | Installment line — small, secondary | `text-[13px] leading-[1.4] text-[#666666] mt-[2px] block` |
+| `PricingSellingPrice` | The headline price — large, bold, often the brand color | `text-[28px] leading-[1.15] font-bold text-[var(--color-primary)] tracking-[-0.01em] block` |
+| `PricingListPrice` | The struck-through original price — small and muted | `text-[13px] leading-[1.4] font-normal text-[var(--color-text-subtle)] line-through` |
+| `PricingDiscount` / `PricingSpotDiscount` | Savings badge — small, often a colored chip | `inline-flex items-center px-[6px] py-[2px] rounded-[4px] bg-[var(--color-primary)] text-white text-[12px] font-semibold` |
+| `PricingInstallments` / `PricingInstallment` | Installment line — small, secondary | `text-[13px] leading-[1.4] text-[var(--color-text-muted)] mt-[2px] block` |
 
-Read the selling-price color straight off the image as an arbitrary hex; reuse it on the discount chip. `line-through` is what makes the list price read as the old price.
+When the selling price is in the brand color, write it as the role's variable (`var(--color-primary)`), not as its hex, and reuse it on the discount chip. A muted grey that several lines share, such as the list and installment color, is a variable of the page or layout `theme`; a grey used once stays an arbitrary hex read off the image. `line-through` is what makes the list price read as the old price.
 
 Styled minimal example (list + selling + installments):
 
@@ -469,11 +465,11 @@ Styled minimal example (list + selling + installments):
   },
   "pricing-list": {
     "type": "PricingListPrice",
-    "style": ["text-[13px]", "leading-[1.4]", "font-normal", "text-[#8A8A8A]", "line-through"]
+    "style": ["text-[13px]", "leading-[1.4]", "font-normal", "text-[var(--color-text-subtle)]", "line-through"]
   },
   "pricing-selling": {
     "type": "PricingSellingPrice",
-    "style": ["text-[28px]", "leading-[1.15]", "font-bold", "text-[#C8102E]", "tracking-[-0.01em]", "block"]
+    "style": ["text-[28px]", "leading-[1.15]", "font-bold", "text-[var(--color-primary)]", "tracking-[-0.01em]", "block"]
   },
   "pricing-installments": {
     "type": "PricingInstallments",
@@ -483,11 +479,13 @@ Styled minimal example (list + selling + installments):
   "pricing-installment": {
     "type": "PricingInstallment",
     "props": { "template": "ou em até {count}x de {value}", "interestFreeLabel": "sem juros" },
-    "style": ["text-[13px]", "leading-[1.4]", "text-[#666666]"]
+    "style": ["text-[13px]", "leading-[1.4]", "text-[var(--color-text-muted)]"]
   }
 }
 ```
 
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-text-subtle": "#8A8A8A", "--color-text-muted": "#666666"}`. A color used once stays a hex.
+
 ---
 
 ## Related