@vtex/faststore 0.0.10 → 0.0.12

package/dist/docs/card-entry.md

@@ -50,7 +50,7 @@ PaymentSectionRoot                  (or PaymentSectionController)
 ├── … other payment leaves (installments, save-card, billing, place-order)
 ```
 
-`CardEntry` renders its own four fields internally (number, holder name, expiration, CVV) — none of them are separately placeable schema elements. Holder name, expiration, and CVV each render conditionally, based on the detected payment method's validator config; the number field always renders. The CVV field is `type="text"`, same as the others, but carries an inline `-webkit-text-security: disc` style that renders its digits as dots — from the keystroke that completes the code, not from the first one. "Complete" is the detected method's own `cvvMask` length: three digits for most networks, four for Amex. Where that mask is pipe-delimited — one method id covering a 3-and-4-digit family — it is the *shortest* alternative, not the longest the field accepts: a shopper holding the 3-digit card of such a family never reaches a fourth digit, so the longer length would leave their complete, valid code legible for the rest of the flow. Below it the digits render in the clear, so a shopper can read back what they just typed and catch a typo; at it, the mask engages on that same render, never on blur and never after a delay, so a paste that delivers every digit in one event opens no legible window. The mask is derived from the value on every render rather than latched once, so backspacing below the length reveals what is left, and a network switch that widens the expectation (a 3-digit code against a newly detected Amex) reveals the code again until its fourth digit. `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 — pairing the expiration field as a fake "username" — which PCI-DSS forbids for a value that must not be retained past authorization. The CSS property obscures the digits without tripping that heuristic, since it never touches `type`. It is 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, exactly what shipped 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). A helper line (`cvvDescription`) renders under the field by default, telling the shopper where to find the code; an empty string suppresses it (see Components below).
+`CardEntry` renders its own four fields internally (number, holder name, expiration, CVV) — none of them are separately placeable schema elements. Holder name, expiration, and CVV each render conditionally, based on the detected payment method's validator config; the number field always renders. The CVV field is `type="text"`, same as the others, but carries an inline `-webkit-text-security: disc` style that renders its digits as dots while the field does not have focus: readable while the shopper is in the field, so they can read back what they just typed and catch a typo, and obscured the moment focus leaves it, with no length involved — 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; the focus flag is also reset when the card form collapses and when the input unmounts. The style is derived from the value and the focus flag on every render, never from an effect or a timer, so a paste or a browser autofill that delivers every digit while the field is unfocused, and the blur itself, open no legible window. The trade-off is deliberate: while the field has focus, a code the shopper just typed is on screen in the clear. `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 — pairing the expiration field as a fake "username" — which PCI-DSS forbids for a value that must not be retained past authorization. The CSS property obscures the digits without tripping that heuristic, since it never touches `type`. It is supported in Chromium and WebKit (and Firefox 114+, unverified on this branch); an engine without it renders the digits in the clear, exactly what shipped 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. A helper line (`cvvDescription`) renders under the field by default, telling the shopper where to find the code; an empty string suppresses it (see Components below).
 
 **Composition rules:**
 
@@ -72,7 +72,7 @@ Collapsing clears the security code field, and only the security code. The card
 
 The authored `disabled` prop is independent of the collapse: a store that freezes the form with `disabled` sees no change, and a collapsed form may also be `disabled` — neither implies the other.
 
-In the checkout, the card number, holder name, expiration, and security code are cleared after every outcome in which the card target ran: the card POST resolved clean, resolved with errors or threw, or the target refused before any request. They are kept when the submission was refused before the target ran (the form's own check, a refused or untrusted transaction, the submit gate, no method selected) so the shopper can fix them.
+In the checkout, the card number, holder name, expiration, and security code are cleared after every outcome in which the card target ran: the card POST resolved clean, resolved with errors or threw, or the target refused before any request. They are kept when the submission was refused before the target ran (the form's own check, a refused or untrusted transaction, the submit gate, no method selected) so the shopper can fix them. The values stay while the card request is open and clear as soon as it settles, ahead of the confirmation callback, so a callback error or timeout finds the form already empty. While the order attempt is resume-only the form accepts no input, so a card cannot be typed into a form that the next click would ignore.
 
 ---
 
@@ -115,7 +115,7 @@ The card number and security code are typed into `CardEntry`'s raw fields and PO
     {
       "routes": ["/checkout"],
       "headers": {
-        "Content-Security-Policy": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' https://acme.vtexvault.com; frame-ancestors 'none'; base-uri 'self'; object-src 'none'",
+        "Content-Security-Policy": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https://acme.vtexassets.com; font-src 'self' data:; connect-src 'self' https://acme.vtexvault.com; form-action 'self'; frame-ancestors 'none'; base-uri 'self'; object-src 'none'",
         "Referrer-Policy": "strict-origin-when-cross-origin"
       }
     }
@@ -126,7 +126,7 @@ The card number and security code are typed into `CardEntry`'s raw fields and PO
 - **The vault host in `connect-src` is `https://{account}.vtexvault.com`, for the account the store serves.** That is the `NEXT_PUBLIC_ACCOUNT` the store is built with, which is not always `store.account` in `foundation.json`. Write the served account, with no wildcard: `https://*.vtexvault.com` would let a compromised script send the card to any tenant's vault.
 - **A policy that names the legacy payments host (`vtexpayments.com.br`) makes the browser block the card POST.** The order cannot be placed and nothing else on the page reports why. The generated app calls its own GraphQL at the relative `/api/graphql`, so `'self'` covers it; a store built with an absolute `NEXT_PUBLIC_STOREFRONT_API_URL` must add that origin.
 - **A rule's `routes` must name the page that composes `CardEntry`**, as the page's `route` spells it (`/checkout`, `/reserva/checkout/payment`). Renaming that page fails the compile instead of dropping the policy. A page added later that composes `CardEntry` carries nothing until its route is added to the rule.
-- **`script-src 'unsafe-inline'` is a known limit, and the policy does not stop injected script from sending the card off the page.** A static header cannot carry a nonce, so the inline scripts Next.js emits need it, and script injected into the page runs with the same rights. `connect-src` closes only `fetch`, XHR, beacons and WebSocket. The policy still leaves three channels open to any https host: an image request (`img-src https:`, which the page needs for catalog images), a form submission (no `form-action`) and a navigation (CSP cannot restrict one). What today's ruled policy does give is the vault origin pinned, no `'unsafe-eval'`, a page no other site can frame (`frame-ancestors 'none'`) and no `http:` or wildcard source. It does not replace keeping untrusted script off the payment page.
+- **`script-src 'unsafe-inline'` is a known limit, and the policy does not stop injected script from sending the card off the page.** A static header cannot carry a nonce, so the inline scripts Next.js emits need it, and script injected into the page runs with the same rights. `connect-src` closes only `fetch`, XHR, beacons and WebSocket. The policy still leaves one channel open to any https host: a navigation (CSP cannot restrict one). The image and form-post channels are closed: `img-src` names exactly one image origin, `https://{account}.vtexassets.com`, so a store whose page loads images from another origin must list that origin exactly (a bare `https:` fails the header check), and `form-action 'self'` stops a form from posting to another origin (the check accepts `'self'` or `'none'` and nothing else). What today's ruled policy does give is the vault origin pinned, no `'unsafe-eval'`, a page no other site can frame (`frame-ancestors 'none'`) and no `http:` or wildcard source. It does not replace keeping untrusted script off the payment page.
 - **`frame-ancestors 'none'`** blanks the page inside any iframe, including an editor preview.
 - **reCAPTCHA needs the anti-bot origins, and the ruled policy above does not declare them yet.** The challenge frame and script come from `https://www.google.com` and `https://www.gstatic.com`, the origins `sdk/anti-bot` declares. The frame is blocked by `default-src 'self'` (no `frame-src`) and the script by `script-src 'self' 'unsafe-inline'`, so both need the anti-bot origins. The stores add them together with whoever wires `getAntiBotToken`; the header check accepts a `frame-src` that names only those two origins and rejects any other.
 - **Under `next dev` the served `script-src` also carries `'unsafe-eval'`; production does not.** React Refresh evaluates code in the browser, so the generated `next.config.ts` adds `'unsafe-eval'` to the `script-src` of every Content-Security-Policy it serves only when `NODE_ENV` is `development` (what `next dev` sets), which is what `pnpm dev:example` runs. Any build whose `NODE_ENV` is not `development` (the default for `next build` and `next start`) serves the declared policy byte for byte, so the live header check still runs against them: a dev response shows a `script-src` the store never declared, which `scripts/assert-payment-page-headers.mjs` rejects by design, so run that script against `next start`.
@@ -143,33 +143,44 @@ The only component. No internal sub-parts are separately schema-addressable.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `legend` | string | `"Card details"` | Fieldset legend/title. |
-| `numberLabel` | string | `"Card number"` | Card-number field label. |
 | `numberPlaceholder` | string | — | Card-number field placeholder. |
-| `holderNameLabel` | string | `"Cardholder name"` | Holder-name field label. Same noun as `holderNameRequiredMessage`, deliberately. |
 | `holderNamePlaceholder` | string | — | Holder-name field placeholder. |
-| `expirationLabel` | string | `"Expiration date"` | Expiration field label. |
-| `expirationPlaceholder` | string | `"MM/YY"` | Expiration field placeholder. |
-| `cvvLabel` | string | `"Security code"` | CVV field label. |
 | `cvvPlaceholder` | string | — | CVV field placeholder. |
-| `cvvDescription` | string | `"The 3-4 digit number on your card"` | Helper text under the CVV field. Empty string renders nothing. |
-| `numberRequiredMessage` | string | `"Card number is required"` | Shown when the card-number field is left blank. |
-| `numberInvalidMessage` | string | `"Enter a valid card number"` | Shown for a Luhn-invalid number, or one a configured network claims only as a prefix (the wrong length, or two networks at once). |
-| `networkNotAcceptedMessage` | string | `"This card is not from a network the store accepts"` | Shown for a Luhn-valid number that no configured network claims at all. |
-| `holderNameRequiredMessage` | string | `"Cardholder name is required"` | Shown when the holder-name field is left blank and the detected method requires it. |
-| `expirationRequiredMessage` | string | `"Expiration date is required"` | Shown when the expiration field is left blank and the detected method requires it. |
-| `expirationInvalidMessage` | string | `"Enter a valid expiration date"` | Shown for a structurally malformed `MM/YY`. |
-| `expirationExpiredMessage` | string | `"This card has expired"` | Shown for a structurally valid `MM/YY` that has already passed. |
-| `cvvRequiredMessage` | string | `"Security code is required"` | Shown when the CVV field is left blank and the detected method requires it. |
-| `cvvInvalidMessage` | string | `"Enter a valid security code"` | Shown for a CVV that fails the detected method's format. |
 | `disabled` | boolean | `false` | Disables every field. |
 
+**Content model** (`card-entry`), every field read only from `$content` (a missing message renders empty and logs `message.missing`):
+
+| Field | Source copy | Notes |
+|-------|-------------|-------|
+| `legend` | "Card details" | Fieldset legend/title. |
+| `numberLabel` | "Card number" | Card-number field label. |
+| `holderNameLabel` | "Cardholder name" | Holder-name field label. Same noun as `holderNameRequiredMessage`, deliberately. |
+| `expirationLabel` | "Expiration date" | Expiration field label. |
+| `expirationPlaceholder` | "MM/YY" | Expiration field placeholder. |
+| `cvvLabel` | "Security code" | CVV field label. |
+| `cvvDescription` | "The 3-4 digit number on your card" | Helper text under the CVV field. A blank message renders nothing. |
+| `numberRequiredMessage` | "Card number is required" | Shown when the card-number field is left blank. |
+| `numberInvalidMessage` | "Enter a valid card number" | Shown for a Luhn-invalid number, or one a configured network claims only as a prefix (the wrong length, or two networks at once). |
+| `networkNotAcceptedMessage` | "This card is not from a network the store accepts" | Shown for a Luhn-valid number that no configured network claims at all. |
+| `holderNameRequiredMessage` | "Cardholder name is required" | Shown when the holder-name field is left blank and the detected method requires it. |
+| `expirationRequiredMessage` | "Expiration date is required" | Shown when the expiration field is left blank and the detected method requires it. |
+| `expirationInvalidMessage` | "Enter a valid expiration date" | Shown for a structurally malformed `MM/YY`. |
+| `expirationExpiredMessage` | "This card has expired" | Shown for a structurally valid `MM/YY` that has already passed. |
+| `cvvRequiredMessage` | "Security code is required" | Shown when the CVV field is left blank and the detected method requires it. |
+| `cvvInvalidMessage` | "Enter a valid security code" | Shown for a CVV that fails the detected method's format. |
+
 **Data:** declares no fragment and no actions. Card masks, required-ness, and network regexes come from the `card-capture` context — at checkout, the payment section's own methods. It reads no cart, so it works where no purchase is underway; the `add_payment_info` event and the cart total it needs belong to the payment section root.
 
 **Never a schema prop:** the card number and CVV. They exist only in this component's local state, for the lifetime of the mounted instance, and are never exposed as a bindable prop, a fragment field, or a value another component can read.
 
 **Validation timing:** the draft is validated before the place-order sequence opens a transaction, not only when the order is submitted — an invalid number, holder name, expiration, or CVV refuses with an inline field message before anything is charged or opened. The submission itself re-validates the same way, so the two can never disagree.
 
+**Field timing:** each field validates when the shopper leaves it. A blur writes or clears only that field's error, and editing a field clears its own error. A blur never moves focus: pulling focus back to a half-typed expiration would trap a shopper who tabs away. The first invalid field takes focus only when Place order refuses the draft.
+
+**Keyboard hint:** the number, expiration, and security code inputs carry `inputmode="numeric"`; the holder name input carries none. The attribute is advisory, so a keyboard that ignores it still shows letters.
+
+**A card from a network the store does not accept:** a Luhn-valid number that no configured network claims, exactly or as a prefix, is told apart from a malformed one. The number field shows `networkNotAcceptedMessage` when the shopper leaves it, and Place order refuses with the code `UNSUPPORTED_CARD_NETWORK`, rendered through `PlaceOrder`'s `unsupportedNetworkMessage`, whether or not a payment method is selected. The refusal comes before any transaction opens. With no method selected, the form gives the place-order sequence a side-effect-free explanation, asked only at the missing-method step, so the order of the checks (path, method, submit gate, card check) does not change; that click sets no field error and moves no focus, because the blur message is already on the field. With a method selected, the card check itself refuses with the same code, shows the field error, and focuses the number. A prefix claimed at the wrong length, a prefix two networks both claim, a Luhn-invalid number, and a blank number keep their existing refusals, and so does a store whose methods carry no number pattern, where detection never ran. The code and both messages are fixed copy: nothing derived from the typed number appears in them or in a log line.
+
 **Selection timing:** network detection, the network mark, and the number's grouping follow every keystroke, but the detected method and the card's BIN (its first eight digits) reach the server only once the number field holds eight digits — never as a shorter prefix. Below eight digits nothing is sent, so the installments control and the persisted selection keep whatever was last recorded. The first digit typed off the new-card path does record that path, locally and with nothing sent, so a saved card that was checked stops being the selection as soon as the shopper starts a new number.
 
 ---
@@ -234,14 +245,16 @@ Style `CardEntry`'s root as a vertical stack of fields, matching a typical card
 | Network mark slot (`data-fs-card-entry-networks`) | Positions the single mark inside the input's box; absent entirely until a network is recognized | `absolute right-[12px] top-1/2 -translate-y-1/2 flex items-center` |
 | Network mark (`data-fs-card-entry-network`) | The recognized network itself — **at most one**, never a row. Carries `data-fs-card-entry-network-id` with the detected method's id | `flex items-center justify-center` |
 | Network icon (`data-fs-card-entry-network-icon`) | The icon, when the recognized network's name maps to one | `w-[20px] h-[20px]` |
-| Network fallback text (`data-fs-card-entry-network-fallback`) | The recognized network's name as text, when it maps to no icon; mutually exclusive with the icon | `text-[13px] font-medium text-[#333333]` |
-| Field labels (`data-fs-field-label`) | Small, muted label above each input | `text-[13px] font-medium text-[#333333] mb-[4px] block` |
-| Field inputs (`data-fs-field-control`) | The bordered text input | `border border-[#CCCCCC] rounded-[6px] px-[12px] py-[10px] text-[15px] w-full` |
-| Field errors (`data-fs-field-error`) | Inline validation message, small and red | `text-[12px] text-[#C8102E] mt-[4px] block` |
-| CVV helper text (`data-fs-card-entry-cvv-description`) | Small muted line under the CVV field | `text-[12px] text-[#666666] mt-[4px] block` |
+| Network fallback text (`data-fs-card-entry-network-fallback`) | The recognized network's name as text, when it maps to no icon; mutually exclusive with the icon | `text-[13px] font-medium text-[var(--color-ink)]` |
+| Field labels (`data-fs-field-label`) | Small, muted label above each input | `text-[13px] font-medium text-[var(--color-ink)] mb-[4px] block` |
+| Field inputs (`data-fs-field-control`) | The bordered text input | `border border-[color-mix(in_srgb,var(--color-ink)_20%,transparent)] rounded-[var(--radius-base)] px-[12px] py-[10px] text-[15px] w-full` |
+| Field errors (`data-fs-field-error`) | Inline validation message, small | `text-[12px] mt-[4px] block` |
+| CVV helper text (`data-fs-card-entry-cvv-description`) | Small muted line under the CVV field | `text-[12px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)] mt-[4px] block` |
 | Placing (`data-fs-card-entry-placing`) | Present while an order-placement sequence is in flight (T28), and while the order attempt is resume-only (its card may already have been sent, so the fields do not accept input) until the attempt is freed; the whole root is also `inert` and `aria-disabled` at that point, so style this hook rather than relying on pointer events alone | `opacity-60 cursor-not-allowed` |
 | Collapsed (`data-fs-card-entry-collapsed`) | Present on the styled root while the card payment is collapsed — the persisted selection is a method this section does not serve or one that is not a card, and a picker is composed to un-hide it (see Reveal and collapse); the root is also `inert`. **No transition or animation can run on it**: the actual hide is a `hidden` attribute one level up, on an unstyled wrapper this node cannot reach with any class, and an ancestor's `display:none` removes the whole subtree from rendering the instant it applies, before any transition on a descendant could ever paint. Use this hook only for one-shot conditional styling of the (already-unrendered) subtree, never for an entrance/exit animation | `opacity-60` |
 
+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.
+
 Styled minimal example:
 
 ```json
@@ -260,7 +273,7 @@ Styled minimal example:
 ## Accessibility Contract
 
 **What the platform promises:** the four fields sit inside a native `<fieldset>`/`<legend>` pair
-(`legend`, default `"Card details"`) — the pattern every other grouped payment control now follows
+(the `legend` message) — the pattern every other grouped payment control now follows
 (T38, Decision 1). Each field carries its own `Field.Label`, `aria-invalid`, and an error message
 associated through `aria-describedby` once it fails validation; the CVV field's helper text
 (`cvvDescription`) is linked the same way. There is no composite keyboard widget here — every rendered

package/dist/docs/card-summary.md

@@ -59,7 +59,15 @@ Code only: it has no catalog entry and is never placed in a schema, because a sc
 
 ### CardSummary
 
-The wrapper, `<span data-fs-card-summary>`. Carries `data-fs-card-summary-network="<icon>"` when the network has a mark and `data-fs-card-summary-labeled` when a label is present. No props.
+The wrapper, `<span data-fs-card-summary>`. Carries `data-fs-card-summary-network="<icon>"` when the network has a mark and `data-fs-card-summary-labeled` when a label is present. No props besides `$content`.
+
+It formats its `endingIn` message and hands it to the `CardSummaryDigits` inside it. A missing message logs an error, and the digits are then read bare. A `CardSummary` has `$content` only when the store places it or a parent forwards a message to it, as `AccountSavedCardRemoveDescription` forwards its `cardEndingIn`.
+
+Content type `card-summary`:
+
+| Content field | Description |
+|---|---|
+| endingIn | The last digits as read to assistive technology, with the `lastDigits` argument |
 
 ### CardSummaryMark
 
@@ -90,7 +98,7 @@ Decoration for the hidden digits, always `aria-hidden`. Nothing when empty or wh
 
 ### CardSummaryDigits
 
-The last four digits. Screen readers hear "ending in 1234" (message id `fs/card.ending-in`, in en-US, es-ES, and pt-BR); the visible digits are hidden from them. Nothing when the card has no digits. No props.
+The last four digits. Screen readers hear the `endingIn` message of the `CardSummary` around them, such as "ending in 1234"; the visible digits are hidden from them. Outside a `CardSummary`, or with its message missing, screen readers hear the bare digits. Nothing when the card has no digits. No props.
 
 ---
 
@@ -150,9 +158,9 @@ Digits first, with another mask:
 |---|---|---|
 | `CardSummary` | Lines the parts up | `inline-flex items-center gap-[8px]` |
 | `CardSummaryMark` | Mark box; size the glyph through it | `inline-flex items-center [&_svg]:h-[24px] [&_svg]:w-[32px]` |
-| `CardSummaryName` | Name typography | `text-[14px] font-medium text-[#1F1F1F]` |
-| `CardSummaryMask` | Mask color and spacing | `text-[14px] tracking-[2px] text-[#6B6B6B]` |
-| `CardSummaryDigits` | Digit typography | `text-[14px] tabular-nums text-[#1F1F1F]` |
+| `CardSummaryName` | Name typography | `text-[14px] font-medium text-[var(--color-text)]` |
+| `CardSummaryMask` | Mask color and spacing | `text-[14px] tracking-[2px] text-[var(--color-text-muted)]` |
+| `CardSummaryDigits` | Digit typography | `text-[14px] tabular-nums text-[var(--color-text)]` |
 
 `CardSummaryRoot` renders no element and is not styled.
 
@@ -160,12 +168,14 @@ Digits first, with another mask:
 {
   "card-summary": { "type": "CardSummary", "style": ["inline-flex", "items-center", "gap-[8px]"], "children": ["card-mark", "card-name", "card-mask", "card-digits"] },
   "card-mark": { "type": "CardSummaryMark", "style": ["inline-flex", "items-center", "[&_svg]:h-[24px]", "[&_svg]:w-[32px]"] },
-  "card-name": { "type": "CardSummaryName", "style": ["text-[14px]", "font-medium", "text-[#1F1F1F]"] },
-  "card-mask": { "type": "CardSummaryMask", "style": ["text-[14px]", "tracking-[2px]", "text-[#6B6B6B]"] },
-  "card-digits": { "type": "CardSummaryDigits", "style": ["text-[14px]", "tabular-nums", "text-[#1F1F1F]"] }
+  "card-name": { "type": "CardSummaryName", "style": ["text-[14px]", "font-medium", "text-[var(--color-text)]"] },
+  "card-mask": { "type": "CardSummaryMask", "style": ["text-[14px]", "tracking-[2px]", "text-[var(--color-text-muted)]"] },
+  "card-digits": { "type": "CardSummaryDigits", "style": ["text-[14px]", "tabular-nums", "text-[var(--color-text)]"] }
 }
 ```
 
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-text": "#1F1F1F", "--color-text-muted": "#6B6B6B"}`. A color used once stays a hex.
+
 ---
 
 ## Related

package/dist/docs/cardholder-document.md

@@ -69,6 +69,8 @@ The field itself. Renders the `DocumentField` particle for the type `usePayment(
 | `errorMessage` | `string` | `'Invalid '` + the type's name | Shown inline when the typed value fails the type's validation on blur. |
 | `disabled` | `boolean` | `false` | Disables the input without hiding it — independent of the data-driven presence gate. |
 
+The method decides whether the field shows and whether it is mandatory; the store's country decides which document it is. The type is the first displayable document the store's country row lists that this build knows, and a country row's own `required` flag is read by nobody. The SSN and SIN inputs carry `autocomplete="off"` so a browser does not offer them for autofill; the CPF and RFC inputs carry no `autocomplete` attribute, and every type stays `type="text"`.
+
 No `documentType` prop — the store's country decides it. No `required` prop — requiredness is always read from the selected method's validator, never authored.
 
 **Data:** declares no `fragment` of its own. It reads `selectedMethod`, `countryDocumentType`, `draft`, and `setDraftDocument` off the ambient `payment` context that `PaymentSectionRoot` / `PaymentSectionController` already fetches for.
@@ -109,8 +111,8 @@ No `documentType` prop — the store's country decides it. No `required` prop
 
 ## Known limitations
 
-- **Four person documents, by store country.** The country comes from `Payment.storeCountryCode` and `Payment.countries`. A store whose country resolves to no document type shows no field, refuses nothing and sends no document. A document typed while the field was shown is posted only while the selected method still asks for one and the country still resolves a type; the draft itself is not cleared. `label`, `placeholder` and `errorMessage` have no catalog default (the right copy depends on the country), so leave them unset unless the store serves one country.
-- **Server-driven requiredness renders the field correctly and is also enforced at submit time — but not by this component or by `CardEntry`.** This component marks the field required when the validator says so; a required-but-blank or malformed value (whether or not required) blocks Place Order client-side, before any transaction opens, **while the selected method's validator also says the document is displayable**. That gate lives in `matter/payment/use-payment-submit-gate.ts` (T24) and is consumed by `PlaceOrder`, not by this component or by `CardEntry`'s own `validateDraft` — this component's only job stays publishing `draft.document` via `setDraftDocument`. When the *currently* selected method's validator says `documentDisplayable: false`, the gate treats `draft.document` as inert either way (fix pass, findings R1/S4/S5): there is no field on screen for the shopper to read a leftover value from or correct it in, whether that value is left over from a previously selected, displayable method or simply blank. See `specs/cardholder-document-submit-gate.md` for the gate's full contract.
+- **Four person documents, by store country.** The country comes from `Payment.storeCountryCode` and `Payment.countries`. A store whose country resolves to no document type shows no field, refuses nothing and sends no document, even when the selected method says a document is required, so the order is not refused client-side for it. A document typed while the field was shown is posted only while the selected method still asks for one and the country still resolves a type; the draft itself is not cleared. `label`, `placeholder` and `errorMessage` have no catalog default (the right copy depends on the country), so leave them unset unless the store serves one country.
+- **Server-driven requiredness renders the field correctly and is also enforced at submit time — but not by this component or by `CardEntry`.** This component marks the field required when the validator says so; a required-but-blank or malformed value (whether or not required) blocks Place Order client-side, before any transaction opens, **while the selected method's validator also says the document is displayable**. That gate lives in `matter/payment/use-payment-submit-gate.ts` (T24) and is consumed by `PlaceOrder`, not by this component or by `CardEntry`'s own `validateDraft` — this component's only job stays publishing `draft.document` via `setDraftDocument`. The gate checks the value against the same country-resolved type the field shows. When the *currently* selected method's validator says `documentDisplayable: false`, the gate treats `draft.document` as inert either way (fix pass, findings R1/S4/S5): there is no field on screen for the shopper to read a leftover value from or correct it in, whether that value is left over from a previously selected, displayable method or simply blank.
 
 ---
 
@@ -120,7 +122,7 @@ No `documentType` prop — the store's country decides it. No `required` prop
 
 | Component | What you style | Plausible classes |
 |---|---|---|
-| `CardholderDocument` | The field's own label, input box, and inline error — same shape as a `Field.Root` | `flex flex-col gap-[4px] w-full` on the root; `text-[14px] font-medium text-[#1A1A1A]` for the label; `border border-[#CCCCCC] rounded-[6px] px-[12px] py-[8px] text-[14px]` for the input |
+| `CardholderDocument` | The field's own label, input box, and inline error — same shape as a `Field.Root` | `flex flex-col gap-[4px] w-full` on the root; `text-[14px] font-medium text-[var(--color-ink)]` for the label; `border border-[color-mix(in_srgb,var(--color-ink)_20%,transparent)] rounded-[var(--radius-base)] px-[12px] py-[8px] text-[14px]` for the input |
 | Placing (`data-fs-cardholder-document-placing`) | Present while an order-placement sequence is in flight (T28); the field is also `inert` and `aria-disabled` at that point | `opacity-60 cursor-not-allowed` |
 
 Styled example:

package/dist/docs/carousel.md

@@ -35,7 +35,8 @@
 | `variant` | `'slide' \| 'scroll'` | `'slide'` | Transform slide vs. native overflow scroll |
 | `itemsPerPage` | number | `1` | How many children are visible per page |
 | `defaultPage` | number | `0` | Page selected on first render |
-| `label` | string | `'Carousel'` | `aria-label` for the carousel region |
+
+The region's `aria-label` comes from the `$content` field `label` (content type `carousel-root`).
 
 ### CarouselTrack
 
@@ -43,16 +44,16 @@ Lays out and counts the children. No props beyond standard `div` attributes. Pla
 
 ### CarouselPrevious / CarouselNext
 
-Buttons that move one page. No props beyond standard `button` attributes; accept any children (Icon, text). Disabled at the respective end when `infiniteMode` is off.
+Buttons that move one page. No props beyond standard `button` attributes; accept any children (Icon, text). Disabled at the respective end when `infiniteMode` is off. Their `aria-label` comes from the `$content` field `label` (content types `carousel-previous` and `carousel-next`).
 
 ### CarouselBullets
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `ariaLabel` | string | `'Choose page'` | Label for the bullets group |
-| `bulletLabel` | string | `'Go to page {page}'` | Per-bullet label; `{page}` is the 1-based page number |
 | `hideWhenSingle` | boolean | `true` | Render nothing when there is a single page |
 
+The labels come from `$content` (content type `carousel-bullets`): `ariaLabel` names the bullets group, and `bulletLabel` names each bullet, an ICU message whose `{page}` argument is the 1-based page number.
+
 Bullets support `ArrowLeft` / `ArrowRight` / `Home` / `End` keyboard navigation and mark the active page with `data-fs-carousel-bullet-selected="true"` and `aria-current`.
 
 ---

package/dist/docs/cart-destination.md

@@ -10,8 +10,8 @@
 Look in the **top of the cart page's main column**, above the free-shipping bar and the line items:
 
 - A single line reading **"Entregando em"** (or "Delivering to") followed by a **postal code and city, state**, beside a link such as **"Trocar localização?"**.
-- With no destination yet, the line reads a prompt such as **"Informe seu CEP"** beside the same link.
-- Pressing the link swaps the line for **one masked postal code field**, an **"Atualizar"** button, a **"Cancelar"** button and a short help line.
+- With no destination yet, the bar shows just a prompt such as **"Informe seu CEP"**, often with a pin icon. Pressing it opens the field.
+- Pressing the link (or the prompt) swaps the line for **one postal code field**, an **"Atualizar"** button and a **"Cancelar"** button.
 
 The image is the source of truth for layout.
 
@@ -40,14 +40,14 @@ A postal code control in the **site header** is not this component: that is `Reg
 CartDestinationRoot                      (provides 'cartDestination'; starts in read mode)
 ├── CartDestinationRead                  (read mode only)
 │   ├── CartDestinationValue             (the destination, once set)
-│   ├── CartDestinationUnset             (the store's invitation, while none is set)
+│   ├── CartDestinationUnset             (button: the invitation, while none is set; opens edit mode)
+│   │   ├── Icon                         (optional pin)
 │   │   └── Text                         ("Informe seu CEP")
 │   └── CartDestinationChange            (opens edit mode)
 └── CartDestinationForm                  (edit mode only)
     ├── CartDestinationPostalCodeControl
     ├── CartDestinationSubmit
     ├── CartDestinationCancel
-    ├── Text                             (the help line, placed by the store)
     └── CartDestinationError
 ```
 
@@ -85,7 +85,7 @@ The destination as prefix, postal code, city and state, each in its own element.
 
 ### CartDestinationUnset
 
-Renders its children only once the destination resolved and none is set. Place the invitation inside it, within `CartDestinationRead`. No props.
+A button that opens edit mode, with `aria-expanded` tied to the mode, exactly like `CartDestinationChange`. It renders only once the destination resolved and none is set. Its children are the invitation content (a `Text`, an `Icon`). Place it within `CartDestinationRead`. Its props are the props of a button; a consumer `onClick` runs before edit mode opens. When edit mode closes with no destination set, focus returns to this button. It ships no style of its own: like the change link, the store gives it a pointer cursor and an underline so it reads as clickable.
 
 ### CartDestinationChange
 
@@ -103,18 +103,23 @@ Renders only in edit mode. Enter in the field runs the submit, which flags an in
 
 ### CartDestinationPostalCodeControl
 
-A `PostalCodeField` bound to the draft, empty every time edit mode opens.
+A plain text field bound to the draft, empty every time edit mode opens. Its limits (`maxLength`, `inputMode`) and its placeholder, the country's example postal code (`01310-100` for BRA), come from the postal code rules of the cart's country (`@vtex/country-forms`), which load when edit mode opens. There is no input mask: the shopper types the code as they know it, and Submit validates it against the country's rules.
+
+While the rules load, the field and `CartDestinationSubmit` are disabled, and the field takes focus once it is enabled. If the load fails, the field is enabled as free text and nothing validates it. A country the rules do not cover (anything but ARG, BRA, CAN, CHL, COL, DEU, ECU, ESP, FRA, GBR, IRL, ITA, MEX, PER and USA) is free text too: no mask, no limit and no validation beyond a non-blank value.
+
+The component keeps no mask table and does not read the shared country descriptors that `BillingAddress` and `ShippingAddress` use, so a Canadian or Mexican cart address is judged by the library's own rules for those countries and never by the Brazilian `99999-999` mask. For `CAN` the field takes at most 7 characters, shows the example `K1A 0A9`, accepts `k1a0b1` and writes it as `K1A 0B1`; the library refuses a first letter of D, F, I, O, Q, U or W and is looser than Canada Post elsewhere (`Z1A 0A9` passes). For `MEX` the field takes at most 5 characters on a numeric keyboard and refuses `00999` and `6600`; there is no mask. No case in `cart-destination.test.tsx` uses `CAN` or `MEX`: the behaviour comes from the same `@vtex/country-forms` rules and `sdk/address` functions the billing and shipping suites pin for those countries.
+
+Because the rules come from the library, the cart can disagree with the other two forms where their descriptor patterns differ from the library. A US ZIP+4 typed without the hyphen (`021011234`) is refused here (`cart-destination.test.tsx` pins it) and accepted by billing and shipping.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `mask` | string | the country's mask | `99999-999` for BRA; also the mask Submit checks the draft against, and the typed value must still match the country's pattern, so a mask the pattern rejects (9 digits in BRA, for example) keeps Submit disabled |
 | `label` | string | — | Field label |
-| `placeholder` | string | — | Field placeholder |
-| `invalidMessage` | string | — | Shown for a draft that is incomplete or fails the country's pattern |
+| `placeholder` | string | the country's example postal code | Field placeholder; wins over the example the rules give |
+| `invalidMessage` | string | — | Shown for a typed code the country's rules refuse, once the field loses focus or Submit is attempted |
 
 ### CartDestinationSubmit
 
-Writes the typed postal code. Disabled until the draft is complete for the field's mask (the control's `mask`, else the country's), matches its pattern and differs from the current postal code, and while a write is pending (`aria-busy`). A pending write also waits for any cart line write in flight.
+Writes the typed postal code. Disabled until the country's rules have loaded, the draft passes the country's postal code validation (any non-blank text when the rules failed to load or the country is not covered) and differs from the current postal code, and while a write is pending (`aria-busy`). The write sends the code in the country's own form (`04538132` becomes `04538-132`). A pending write also waits for any cart line write in flight.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
@@ -135,13 +140,16 @@ Closes edit mode, discards the draft and any error, and writes nothing. Disabled
 
 ### CartDestinationError
 
-An alert announcing a failed write; renders nothing otherwise. A refused postal code and a network failure reach the client as the same error, so author one message that covers both.
+An alert announcing a failed write; renders nothing otherwise. It words the error's `code` from its own content and never shows the server's text. A code it does not know (a newer server) shows `genericMessage` and logs `message.unknown-code`.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `genericMessage` | string | — | Authored message; the server's own is the fallback |
+| Code | Message field |
+|------|---------------|
+| `INVALID_POSTAL_CODE` | `invalidPostalCodeMessage` |
+| `NETWORK_ERROR` and every other `ShippingAddressUpdateErrorCode` | `genericMessage` |
+
+A postal code the platform refuses upstream reaches the client as `NETWORK_ERROR` today, so write `genericMessage` to cover it.
 
-**Content model** (`cart-destination-error`): `genericMessage`.
+**Content model** (`cart-destination-error`): `genericMessage`, `invalidPostalCodeMessage` (messages, no arguments).
 
 ---
 
@@ -160,7 +168,12 @@ An alert announcing a failed write; renders nothing otherwise. A refused postal
     "children": ["cart-destination-value", "cart-destination-unset", "cart-destination-change"]
   },
   "cart-destination-value": { "type": "CartDestinationValue", "props": { "prefix": "Entregando em" }, "style": ["flex", "gap-1"] },
-  "cart-destination-unset": { "type": "CartDestinationUnset", "children": ["cart-destination-invitation"] },
+  "cart-destination-unset": {
+    "type": "CartDestinationUnset",
+    "style": ["flex", "items-center", "gap-1", "cursor-pointer", "underline"],
+    "children": ["cart-destination-unset-icon", "cart-destination-invitation"]
+  },
+  "cart-destination-unset-icon": { "type": "Icon", "props": { "name": "map-pin" } },
   "cart-destination-invitation": { "type": "Text", "props": { "as": "span", "children": "Informe seu CEP" } },
   "cart-destination-change": {
     "type": "CartDestinationChange",
@@ -174,20 +187,18 @@ An alert announcing a failed write; renders nothing otherwise. A refused postal
       "cart-destination-control",
       "cart-destination-submit",
       "cart-destination-cancel",
-      "cart-destination-help",
       "cart-destination-error"
     ]
   },
   "cart-destination-control": { "type": "CartDestinationPostalCodeControl", "props": { "label": "CEP" } },
   "cart-destination-submit": { "type": "CartDestinationSubmit", "props": { "label": "Atualizar", "pendingLabel": "Atualizando…" } },
   "cart-destination-cancel": { "type": "CartDestinationCancel", "props": { "label": "Cancelar" } },
-  "cart-destination-help": {
-    "type": "Text",
-    "props": { "as": "span", "children": "Após confirmar, a barra volta ao modo leitura com o novo CEP e cidade." }
-  },
   "cart-destination-error": {
     "type": "CartDestinationError",
-    "props": { "genericMessage": "Não foi possível usar esse CEP. Confira o número e tente de novo." },
+    "props": {
+      "genericMessage": "Não foi possível usar esse CEP. Confira o número e tente de novo.",
+      "invalidPostalCodeMessage": "CEP inválido. Confira o número e tente de novo."
+    },
     "style": ["text-sm", "text-red-700"]
   }
 }
@@ -205,7 +216,7 @@ An alert announcing a failed write; renders nothing otherwise. A refused postal
 | `data-fs-cart-destination-read` | `CartDestinationRead` | Read mode |
 | `data-fs-cart-destination-value` | `CartDestinationValue` | A destination is set |
 | `data-fs-cart-destination-value-prefix`, `-postal-code`, `-city`, `-state` | The piece's element | The piece exists |
-| `data-fs-cart-destination-unset` | `CartDestinationUnset` | No destination is set |
+| `data-fs-cart-destination-unset` | `CartDestinationUnset` (a button) | No destination is set |
 | `data-fs-cart-destination-change` | `CartDestinationChange` | Always |
 | `data-fs-cart-destination-form` | `CartDestinationForm` | Edit mode |
 | `data-fs-cart-destination-postal-code-control` | `CartDestinationPostalCodeControl` | Always |
@@ -225,14 +236,16 @@ No part ships CSS of its own. Spacing, the link look of the change control and t
 - **Placing the postal code control, `CartDestinationSubmit` or `CartDestinationCancel` outside `CartDestinationForm`.** Only the form is bound to edit mode: outside it they render in read mode too, and Enter in the field no longer reaches the submit.
 - **Looking for an `open` prop or a controller.** The root owns edit mode; nothing outside it can open it.
 - **Omitting `CartDestinationUnset`.** With no destination the page then shows only the change link and no invitation.
+- **Leaving `CartDestinationUnset` unstyled.** It is a button with no style of its own, so without a pointer cursor and an underline the invitation does not read as clickable. Give it the same look as `CartDestinationChange`.
+- **Placing `CartDestinationChange` inside `CartDestinationUnset`.** The invitation is already a button, and a button cannot hold another. With no destination the regular change link repeats the invitation, so the store usually hides it while unset (for example with a `[&:has([data-fs-cart-destination-unset])>[data-fs-cart-destination-change]]:hidden` rule on `CartDestinationRead`).
 - **Expecting the Value to show what the shopper just typed.** It shows what the cart confirms.
-- **Authoring a "CEP não encontrado" message.** A refused code and a network failure are the same error today: author one message in `CartDestinationError`.
+- **Passing a `mask` to the postal code control.** There is none: the field is plain text and the country's rules validate it.
+- **Authoring only `invalidPostalCodeMessage` for "CEP não encontrado".** A postal code the platform refuses upstream reaches the client as a network failure today, so `genericMessage` must cover it too.
 
 ---
 
 ## Related
 
 - [[../free-shipping-progress/free-shipping-progress]] — the bar beside this component; it follows the destination write through the cache with no wiring.
-- [[../region/region]] — the header's region control; same postal code field, but a cookie and no cart write.
+- [[../region/region]] — the header's region control; it keeps the masked postal code field and sets a cookie, with no cart write.
 - [[../shipping-address/shipping-address]] — the full delivery address on checkout, which this component's write shares with.
-- [[../../particles/postal-code-field/postal-code-field]] — the masked input this component composes.

package/dist/docs/cart-item.md

@@ -15,10 +15,11 @@ A **cart line** — a repeated row in a cart or mini-cart list: a product thumbn
 
 ## Composition
 
-**`CartItemRoot` wraps the line-item template inside `CartList`.** The nesting is always:
+**`CartItemRoot` wraps the line-item template inside `CartList`, `CartAvailableItems` or `CartUnavailableItems`.** The nesting is always:
 
 ```text
-CartList              (iterator — renders its children once per cart line)
+CartList              (iterator — renders its children once per cart line; CartAvailableItems and
+                       CartUnavailableItems iterate the purchasable and the unavailable lines the same way)
   └─ CartItemRoot     (per-line data provider — owns the core slice)
        ├─ CartItemImage             (optionally wrapped in CartItemProductLink; see below)
        ├─ CartItemName
@@ -37,7 +38,7 @@ CartList              (iterator — renders its children once per cart line)
 ```
 
 - **`CartItemRoot` is required.** Every `CartItem*` core particle reads its data from the nearest `CartItemRoot` (build-time `requiresContext: 'cart-item-data'`). Placing a core particle directly inside `CartList` with no `CartItemRoot` between them is a build error. When authoring a cart or mini-cart line template, always insert a `CartItemRoot` between the `CartList` and the row's particles — it carries no visible styling of its own, so put the row layout classes on it (or on a `Container` inside it).
-- **`CartItemRoot` must be inside `CartList`.** It requires the `cart-item` iteration context that `CartList` provides.
+- **`CartItemRoot` must be inside `CartList`, `CartAvailableItems` or `CartUnavailableItems`.** It requires the `cart-item` iteration context that each of the three provides.
 
 ## Image placeholder
 
@@ -66,7 +67,7 @@ CartItemRoot
 
 Navigation is client-side through the `NavigationLink` particle, which also owns `rel` hardening. The link is same-tab, and `target` is omitted from the props type rather than merely left out of the schema, because an image-only link cannot carry the "(opens in new tab)" cue a `_blank` destination needs.
 
-**Known gap:** a mini-cart drawer does **not** dismiss itself when a client-side navigation leaves it, so the overlay stays open over the product page. This is not specific to this leaf — `CartGoCheckout` behaves the same way — and it belongs to the drawer composition, not to a line leaf.
+**Known gap:** a mini-cart drawer does **not** dismiss itself when a client-side navigation leaves it, so the overlay stays open over the product page. The product link behaves that way, and it belongs to the drawer composition, not to a line leaf. `CartGoCheckout` closes the drawer itself when it leaves for the checkout.
 
 Renders `a[data-fs-cart-item-product-link]`, which also carries the particle's `data-fs-navigation-link`.
 
@@ -81,7 +82,7 @@ CartItemRoot
        └─ CartItemRemove        (removes this line from within its alert)
 ```
 
-**Label-vs-children nuance:** passing children to `CartItemUnavailable` **replaces** its built-in state label (`children ?? unavailableLabel(availability)`). A remove-on-alert composition therefore renders the label as an explicit child (e.g. a `Text`) next to the `CartItemRemove`; nesting the remove control alone leaves the alert without a label. The whole subtree is availability-gated: when the line is `AVAILABLE`, neither the label nor the nested remove control renders.
+**Label-vs-children nuance:** passing children to `CartItemUnavailable` **replaces** its state label, which is one `$content` message per state (`outOfStockLabel` for `OUT_OF_STOCK`, `cannotBeDeliveredLabel` for `UNAVAILABLE`, `unavailableLabel` for any other state; content type `cart-item-unavailable`), formatted only when no children are given. A remove-on-alert composition therefore renders the label as an explicit child (e.g. a `Text`) next to the `CartItemRemove`; nesting the remove control alone leaves the alert without a label. The whole subtree is availability-gated: when the line is `AVAILABLE`, neither the label nor the nested remove control renders.
 
 For the cart-level counterparts (the "N items unavailable" summary and the bulk "remove all unavailable" button), see `cart.md` — Unavailable-item recovery.
 
@@ -90,8 +91,8 @@ For the cart-level counterparts (the "N items unavailable" summary and the bulk
 `CartItemRemove` awaits the removal and tells the shopper when it went through:
 
 - **Disabled while pending.** The button carries the native `disabled` attribute from the click until `removeItem` settles, so a second click sends no second request. A caller-passed `disabled` is kept.
-- **Toast on a clean result only.** When `removeItem` resolves with an empty `userErrors` list, the button raises one `success` toast titled `removedMessage` (default `Item removed`, editable per store). A non-empty list, a missing `removeItem`, or a rejection raises no toast; failures keep surfacing through `CartError`.
-- **`removedMessage`** is the only schema prop. The toast carries the title alone: no description, no action.
+- **Toast on a clean result only.** When `removeItem` resolves with an empty `userErrors` list, the button raises one `success` toast titled by the `removedMessage` message (content type `cart-item-remove`). A non-empty list, a missing `removeItem`, or a rejection raises no toast; failures keep surfacing through `CartError`.
+- **`removedMessage`** is a `$content` field, not a prop. The toast carries the title alone: no description, no action.
 - **Needs a `ToastProvider`.** The toast shows through the layout's `ToastList`. Without a `ToastProvider` above the line, no toast shows and the removal still works.
 
 ## Gift lines
@@ -101,17 +102,29 @@ A promotion can add a line the shopper never chose. `CartItem.gift` marks it, an
 ```text
 CartItemRoot                    (row carries data-fs-cart-item-gift-line on a gift line)
   ├─ CartItemListPrice          (renders: a gift's sellingPrice is 0, so listPrice > sellingPrice)
-  ├─ CartItemGift               (renders "Free")
+  ├─ CartItemGift               (renders its label message)
   └─ CartItemRemove             (renders nothing)
 ```
 
-- **`CartItemGift`** is the free marker: a `span[data-fs-cart-item-gift][data-fs-text]` that renders **only** on a gift line, with the built-in English label `Free`. Passing children **replaces** the label (`children ?? 'Free'`), the same nuance `CartItemUnavailable` has. It is an **inline marker, not a wrapper** — its children are the label, so do not nest a block subtree in it. Place it beside `CartItemPrice`/`CartItemListPrice`.
+- **`CartItemGift`** is the free marker: a `span[data-fs-cart-item-gift][data-fs-text]` that renders **only** on a gift line, with the `label` message (content type `cart-item-gift`). Passing children **replaces** the label, which is then not formatted, the same nuance `CartItemUnavailable` has. It is an **inline marker, not a wrapper** — its children are the label, so do not nest a block subtree in it. Place it beside `CartItemPrice`/`CartItemListPrice`.
 - **`CartItemRemove` suppresses itself** on a gift line. A gift is not the shopper's to discard in this phase, and since one template serves every row, the rule lives in the component rather than in the composition. This covers the remove-on-alert composition too: an unavailable gift renders its alert with no remove control, and recovery is the cart-level `CartRemoveUnavailable` batch (which still batches gift lines) plus server-side cart validation.
 - **`CartItemQuantity` suppresses itself** on a gift line too, the same way `CartItemRemove` does: a gift's quantity is promotion-controlled, and a `removeOnDecrement` stepper would otherwise let a shopper discard the gift by stepping it below the minimum — the one path the remove-control suppression did not cover. A store showing a gift's fixed quantity composes the read-only `CartItemQuantityValue`, which dispatches nothing.
 - **The row is marked** with `data-fs-cart-item-gift-line`, so a swatch can restyle a gift row without a component per variation — that is how a store hides the `R$ 0,00` selling price on a gift row.
 
 A gift whose `listPrice` is also 0 renders no list price (`CartItemListPrice`'s existing `listPrice <= sellingPrice` rule) and the marker carries the row alone.
 
+## Copy
+
+Every copy-bearing leaf reads its text only from its own `$content`, whose fields are ICU messages. An unauthored message renders empty and logs `message.missing`. A store without CMS authors the fields on the element; a CMS-bound store keeps them in content.
+
+| Component | Content type | Fields |
+|---|---|---|
+| `CartItemDiscountPercentage` | `cart-item-discount-percentage` | `template` (`percentage`, the integer percent) |
+| `CartItemQuantity` | `cart-item-quantity` | `validationMessage` (`value`, the corrected amount) |
+| `CartItemRemove` | `cart-item-remove` | `removedMessage` |
+| `CartItemUnavailable` | `cart-item-unavailable` | `outOfStockLabel`, `cannotBeDeliveredLabel`, `unavailableLabel` |
+| `CartItemGift` | `cart-item-gift` | `label` |
+
 ## Owned data
 
 `CartItemRoot`'s core fragment owns each line's `id`, `quantity`, `price`/`listPrice`/`sellingPrice`, `gift`, `ownTotal`/`total`, `variant { variantId, sku, name, image, availability }`, and the `product` core. `variant.availability` stays here (not a sub-matter) because it is read cross-cuttingly: `CartItemAvailable`/`CartItemUnavailable` gate on it, and `CartCheckoutGuard` reads it across all lines. `gift` stays here for the same reason — `CartItemGift`, `CartItemRemove`'s suppression, and the row's state hook all read it.
@@ -137,7 +150,9 @@ The stepper shows the line's quantity **in the unit the merchant sells in**, not
 
 Enforcement happens **on commit** — blur after typing, pointer release on the buttons, or a keyboard interaction — not per keystroke. A committed amount that is out of bounds or off the multiplier grid is clamped and snapped to the nearest valid amount (ties round up), then the remaining delta is dispatched as `increaseQuantity` / `decreaseQuantity` in purchasable units. No non-integer quantity can reach a mutation. Nothing is corrected at render time: a quantity already outside the authored bounds is displayed as-is and fires no write.
 
-A snap renders a notice as the last child of the stepper: `div[role="alert"][data-fs-cart-item-quantity-validation]`, carrying the `validationMessage` prop, whose `{value}` placeholder is replaced with the corrected displayed amount (default `Quantity adjusted to {value}.`). The root also carries `data-fs-cart-item-quantity-adjusted` plus `data-fs-cart-item-quantity-adjusted-reason="min" | "max" | "multiple"` for per-reason styling, and `data-fs-cart-item-quantity-multiplier="<value>"` whenever the multiplier is not `1`, so a measured line can be styled differently from a counted one.
+A snap renders a notice as the last child of the stepper: `div[role="alert"][data-fs-cart-item-quantity-validation]`, carrying the `validationMessage` message (content type `cart-item-quantity`), whose `value` argument is the corrected displayed amount, formatted in the locale. The root also carries `data-fs-cart-item-quantity-adjusted` plus `data-fs-cart-item-quantity-adjusted-reason="min" | "max" | "multiple" | "platform"` for per-reason styling, and `data-fs-cart-item-quantity-multiplier="<value>"` whenever the multiplier is not `1`, so a measured line can be styled differently from a counted one.
+
+`"platform"` appears when the line lands below the amount the stepper asked for, after the write succeeds: the platform stores the quantity it has in stock (or the per-item limit) instead of the one requested. The notice reuses the `validationMessage` message and reports the quantity the line holds, replaces a local snap from the same commit, and goes away when the shopper types again, commits again, or the line reaches the requested amount. A write that fails (`userErrors`) raises no platform notice, though a local snap from the same commit still shows. The stepper remembers the requested amount until the next commit or typing, so a line the platform lowers on cart load shows none, but a line that later drops below an amount this stepper already asked for shows the notice again.
 
 `removeOnDecrement`: a committed amount below the configured minimum removes the line instead of clamping, and no notice is raised. In that mode the decrement control is **not** disabled at the minimum — removal is the intended outcome there — and `data-fs-cart-item-at-min` still keys off the purchasable count. This never applies to a gift line: the stepper renders nothing there, so `removeOnDecrement` cannot discard a gift.
 
@@ -151,7 +166,7 @@ The measurement unit itself (`kg`, `un`) is not fetched, so a measured line rend
 
 `CartItemDiscounts` is another **optional** per-line data owner: it owns the line's `discounts` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders one labeled row per featured promotion applied to the current cart line — the promotion `name` plus its amount (e.g. `Black Friday −R$ 20,00`, `Cupom −10%`) — so a shopper sees *which* promotion took *how much* off *this* item. It is the itemized companion to the aggregated `Discounts` totalizer line in the footer.
 
-Each row branches on `isPercentual`: a currency discount (`false`) formats the amount from the active storefront context; a percentual discount (`true`) renders `−N%` and is **not** currency-formatted. Every amount carries a presentational leading `−` — the source `value` is a positive amount. It **renders null when the line has no discounts** (empty or unresolved), so it appears only where a promotion actually fired. Place it under the line, near the price area. Must be inside `CartList`.
+Each row branches on `isPercentual`: a currency discount (`false`) formats the amount from the active storefront context; a percentual discount (`true`) renders `−N%` and is **not** currency-formatted. Every amount carries a presentational leading `−` — the source `value` is a positive amount. It **renders null when the line has no discounts** (empty or unresolved), so it appears only where a promotion actually fired. Place it under the line, near the price area. Must be inside `CartList`, `CartAvailableItems` or `CartUnavailableItems`.
 
 **Distinct from `CartItemDiscountPercentage`.** `CartItemDiscountPercentage` is a single derived `−N%` **badge** computed from `listPrice`/`sellingPrice` with **no** promotion name; `CartItemDiscounts` is the **named list** of promotions sourced from the line's `discounts` field. They cover different concerns and may coexist on a line — the badge next to the price, the named list beneath it.
 
@@ -159,7 +174,7 @@ Renders a `div[data-fs-cart-item-discounts]` container with one `span[data-fs-ca
 
 ### CartItemCustomizations
 
-`CartItemCustomizations` is an **optional** per-line data owner: it owns the line's `customizations` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders the form-based personalization a shopper applied to the line — engraving text, a size selection, an uploaded file's URL — as one group per assembly, each group listing its `entries` as `name` / `value` rows (e.g. `Text: MARIA`). It **renders null when the line has no customizations** (empty or unresolved). Must be inside `CartList`.
+`CartItemCustomizations` is an **optional** per-line data owner: it owns the line's `customizations` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders the form-based personalization a shopper applied to the line — engraving text, a size selection, an uploaded file's URL — as one group per assembly, each group listing its `entries` as `name` / `value` rows (e.g. `Text: MARIA`). It **renders null when the line has no customizations** (empty or unresolved). Must be inside `CartList`, `CartAvailableItems` or `CartUnavailableItems`.
 
 The group heading is the raw assembly `id` (e.g. `Engraving`); pretty display names are deferred (836 Decision 2). An uploaded-file value surfaces as its URL string and is rendered verbatim — there is no file-preview/download widget in v0 (836 exposes no file metadata; at parity with fastcheckout).
 
@@ -167,7 +182,7 @@ Renders a `div[data-fs-cart-item-customizations]` container with one `div[data-f
 
 ### CartItemCompositions
 
-`CartItemCompositions` is an **optional** per-line data owner: it owns the line's `compositions` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders the nested bundle/assembly tree a shopper built under the line — each child row shows the child's `name`, `quantity` (`×N`), and formatted unit `price`. It **renders null when the line has no compositions** (empty or unresolved). Must be inside `CartList`.
+`CartItemCompositions` is an **optional** per-line data owner: it owns the line's `compositions` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders the nested bundle/assembly tree a shopper built under the line — each child row shows the child's `name`, `quantity` (`×N`), and formatted unit `price`. It **renders null when the line has no compositions** (empty or unresolved). Must be inside `CartList`, `CartAvailableItems` or `CartUnavailableItems`.
 
 **Recursion.** A composition child is itself an order-form line, so it can carry its own nested `compositions` (a sub-bundle) and its own `customizations` (836 Decision 8). The matter recurses over the in-slice `compositions` array with an internal render function: each node renders its row, its own customization groups (using the same `name`/`value` anatomy as `CartItemCustomizations`, so one swatch styles both), then its nested children at `depth + 1`. Recursion is over finite data — the server guarantees acyclic compositions (836 visited-index) and depth is bounded by the assembly config. React keys use the node `id`.
 
@@ -175,6 +190,6 @@ Renders a `div[data-fs-cart-item-compositions]` container with one `div[data-fs-
 
 ### CartItemVariations
 
-`CartItemVariations` is another **optional** per-line data owner: it owns the line's `variant.selectedOptions` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders one labeled row per variation selected on the current cart line (e.g. `Cor: Vermelho`, `Tamanho: M`), so a shopper can tell two lines of the same product apart. It **renders null when the line has no selected options** (empty or unresolved), so it appears only where the SKU actually has variations. Place it near the product name. Must be inside `CartList`.
+`CartItemVariations` is another **optional** per-line data owner: it owns the line's `variant.selectedOptions` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders one labeled row per variation selected on the current cart line (e.g. `Cor: Vermelho`, `Tamanho: M`), so a shopper can tell two lines of the same product apart. It **renders null when the line has no selected options** (empty or unresolved), so it appears only where the SKU actually has variations. Place it near the product name. Must be inside `CartList`, `CartAvailableItems` or `CartUnavailableItems`.
 
 Renders a `div[data-fs-cart-item-variations]` container with one `span[data-fs-cart-item-variation]` per option; each row wraps a `span[data-fs-cart-item-variation-name]` (e.g. `Cor`), a `span[data-fs-cart-item-variation-separator]` holding the `": "` delimiter, and a `span[data-fs-cart-item-variation-value]` (e.g. `Vermelho`). The separator is a hook of its own so a store can restyle or hide the delimiter without the punctuation riding along with the label; with no swatch applied a row still reads `Cor: Vermelho`. No props beyond the standard `div` attributes; the list is data-driven and `children` is not used to override it.