@vtex/faststore 0.0.10 → 0.0.11

package/dist/docs/cart-totalizer.md

@@ -50,8 +50,8 @@ CartTotalizerRoot          ← reactive data provider (totalizers + total)
 |---|---|---|
 | `CartTotalizerRoot` | `$data` | Provides `CartTotalizerContext` and `CartTotalValueContext`; lines format from the active storefront context |
 | `CartTotalizerLine` | `totalizerId`, `label?`, `variant?`, `zeroLabel?` | `variant="discount"` auto-hides when the amount is numerically zero, whatever its wire form (`0`, `"0.00"`, `"-0.00"`); in any variant the line renders nothing when the amount is not a finite number |
-| `CartDiscountLine` | `otherLabel?` | Itemized discount breakdown: one line per promotion/coupon plus the residual. Self-hides when empty. Owns its own `Cart.discounts` slice |
-| `CartMarkdownLine` | `label?` | Aggregate item-level catalog markdown (`Σ listPrice − price`): a single negative line, self-hides at zero. Distinct money from the `Discounts` totalizer / `CartDiscountLine` — may be shown alongside them. Owns its own `Cart.itemMarkdownTotal` slice |
+| `CartDiscountLine` | `$content.otherLabel` | Itemized discount breakdown: one line per promotion/coupon plus the residual. Self-hides when empty. Owns its own `Cart.discounts` slice |
+| `CartMarkdownLine` | `$content.label` | Aggregate item-level catalog markdown (`Σ listPrice − price`): a single negative line, self-hides at zero. Distinct money from the `Discounts` totalizer / `CartDiscountLine` — may be shown alongside them. Owns its own `Cart.itemMarkdownTotal` slice |
 | `CartTotal` | `label?` | The single root-agnostic grand total; reads `CartTotalValueContext` provided by either root. Set `label` to render a labeled total row (e.g. "Total") |
 
 ---
@@ -75,8 +75,9 @@ storefront context wherever it renders.
 single "Discounts" figure is enough.
 
 The `name` a promotion or coupon carries comes from the platform; the API leaves the residual (and any
-unnamed promotion) without a name, so `otherLabel` supplies the label for those (default
-`"Other discounts"`, override per store).
+unnamed promotion) without a name, so the `otherLabel` message (content type `cart-discount-line`)
+supplies the label for those. It reads only from `$content`: an unauthored message renders empty and logs
+`message.missing`. A store without CMS authors it on the element, as below.
 
 Style hooks: `data-fs-cart-discount-lines` on the group, and per row
 `data-fs-cart-discount-line` (with `data-fs-cart-discount-line-kind` = `promotion` / `coupon` / `other`),
@@ -125,7 +126,8 @@ from the running total. What you must not do is interleave it as a plain negativ
 subtotal and the total, because it is not part of that sum. The `ItemMarkdown` story shows the
 list-price framing.
 
-The `label` prop words the row (default `"Item discounts"`, override per store).
+The `label` message (content type `cart-markdown-line`) words the row. It reads only from `$content`: an
+unauthored message renders empty and logs `message.missing`.
 
 Style hooks: `data-fs-cart-markdown-line` on the row (also `data-fs-text`), with
 `data-fs-cart-markdown-line-label` and `data-fs-cart-markdown-line-value`.

package/dist/docs/cart.md

@@ -55,7 +55,7 @@ Layout
 
 Cart **read** particles (`CartCount`, `CartTotal`, `CartList`, and the `CartItem*` line-item particles) read from `CartRoot` via the `useCart()` hook and throw at render time if no `CartRoot` ancestor exists. The layout's instance satisfies that requirement for every page it hosts — a provider declared on the layout satisfies a consumer declared on the page.
 
-Cart **write** consumers (`BuyButtonButton`, `ProductCardAddToCart`, `CartItemQuantity`, `CartItemRemove`) declare `actions: { cart: [...] }` and dispatch via `$actions.cart.*`. They need no `CartRoot` ancestor; the compiler wraps each one with a provider that supplies the handlers. `CartError` surfaces cart write errors from a module-level reactive var, so it too works without reading the cart context.
+Cart **write** consumers (`BuyButtonButton`, `ProductCardAddToCart`, `CartItemQuantity`, `CartItemRemove`) declare `actions: { cart: [...] }` and dispatch via `$actions.cart.*`. They need no `CartRoot` ancestor; the compiler wraps each one with a provider that supplies the handlers. `CartError` surfaces cart write errors from a module-level reactive var, so it too works without reading the cart context. It words the first error by its code from the `$content` of `cart-error`: `invalidQuantityMessage` (`INVALID_QUANTITY`), `itemNotFoundMessage` (`ITEM_NOT_FOUND`), and `genericErrorMessage` for `NETWORK_ERROR` and every refusal the shopper cannot act on (`MISSING_CART_CONTEXT`, `CART_NOT_FOUND`, `INVALID_VARIANT_ID`, `INVALID_SELLER_ID`, `NO_LINE_IDS_PROVIDED`, `UPSTREAM_ERROR`). A code it does not know (one a newer server added) shows `genericErrorMessage` and logs `message.unknown-code`; composed `children` replace the message.
 
 ---
 
@@ -107,39 +107,60 @@ locale and currency), not from props — there is nothing to author here.
 
 ### CartItemDiscountPercentage
 
-Per-line discount badge. Renders the integer discount percentage of the current cart line — the `listPrice`-vs-`sellingPrice` difference (e.g. `-20%`) — so a shopper sees how deep each line's promotion is. It reads the line from the surrounding `CartList` item context and **renders null when the line has no discount** (`sellingPrice >= listPrice`), so it only ever appears on promotional lines. Place it alongside `CartItemPrice` and `CartItemListPrice` in the line-item template. Must be inside `CartList`.
+Per-line discount badge. Renders the integer discount percentage of the current cart line — the `listPrice`-vs-`sellingPrice` difference (e.g. `-20%`) — so a shopper sees how deep each line's promotion is. It reads the line from the line context that `CartItemRoot` provides and **renders null when the line has no discount** (`sellingPrice >= listPrice`), so it only ever appears on promotional lines. Place it alongside `CartItemPrice` and `CartItemListPrice` in the line-item template. Must be inside `CartItemRoot`, which can sit under `CartList`, `CartAvailableItems` or `CartUnavailableItems`.
 
 The percentage matches the PDP `PricingDiscount` badge for the same product — both round with `Math.round` — so a 19.5% discount shows `-20%` on both surfaces.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `template` | string | `"-{percentage}%"` | Output format; `{percentage}` is replaced by the integer percent (e.g. `"{percentage}% OFF"`) |
+| `$content` field | Notes |
+|------------------|-------|
+| `template` | ICU message; the `percentage` argument is the integer percent (e.g. `"-{percentage}%"` or `"{percentage}% OFF"`) |
 
 ---
 
 ### CartEmptyMessage
 
-The empty-cart message, rendered as a paragraph (`data-fs-cart-empty-message`, plus the `data-fs-text` identity). Place it inside `CartEmpty`. The wording is **merchant-editable**: a published CMS entry for the element wins over the `text` prop, and blank copy (an empty or whitespace-only string, from either source) renders nothing. It carries **no layout** — group and space it with `Container`.
+The empty-cart message, rendered as a paragraph (`data-fs-cart-empty-message`, plus the `data-fs-text` identity). Place it inside `CartEmpty`. The text comes from the `$content` field `text` of the `cart-empty-message` content model; a blank or missing message renders nothing (a missing one also logs `message.missing`). It carries **no layout** — group and space it with `Container`.
+
+| `$content` field | Notes |
+|------------------|-------|
+| `text` | ICU message, e.g. `"Your cart is empty"` |
+
+---
+
+### CartUnavailableLabel
+
+The heading of the unavailable section, rendered as a paragraph (`data-fs-cart-unavailable-label`, plus the `data-fs-text` identity). Compose one inside `CartUnavailableSection` as its header; group it with an `Icon` in a `Container` when the header carries an icon. The text comes from the `$content` field `text` of the `cart-unavailable-label` content model; a blank or missing message renders nothing (a missing one also logs `message.missing`). It also hides itself when no line is unavailable, wherever it is placed.
+
+| `$content` field | Notes |
+|------------------|-------|
+| `text` | ICU message, e.g. `"Unavailable"` |
+
+---
+
+### CartAllUnavailableMessage
+
+The warning that nothing in the cart can be bought. Its root is a `div` with `role="alert"` (`data-fs-cart-all-unavailable-message`) holding a paragraph with the copy (`data-fs-cart-all-unavailable-message-text`, plus `data-fs-text`) and, when configured, one link after it (`data-fs-cart-all-unavailable-message-link`). Compose it inside `CartAllUnavailable`. The copy is the `$content` field `text` of the `cart-all-unavailable-message` content model; a blank or missing message renders nothing, link included (a missing one also logs `message.missing`). Its `CartAllUnavailable` then hides too. It also hides itself whenever the cart still has something to buy, wherever it is placed.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `text` | string | `"Your cart is empty"` | Non-CMS fallback. A CMS entry's `text` wins over it |
+| `linkText` | string | none | Link label. A non-blank CMS `linkText` wins over it |
+| `linkHref` | link | none | Link destination, a page reference in a store schema. A non-blank CMS `linkHref` wins over it |
 
-**Content:** declares the `cart-empty-message` content model (one `text` property), so the copy can change without a deploy.
+**Content:** declares the `cart-all-unavailable-message` content model: the message field `text`, and the optional editorial `linkText` and `linkHref`. The link fields are not messages: the link is optional, and a missing message field is an error.
 
 ---
 
 ### CartContinueShopping
 
-The control that returns the shopper to browsing, rendered as a button (`data-fs-cart-continue-shopping`, alongside `data-fs-drawer-close` and `data-fs-button`). It **dismisses the overlay and dispatches no cart write**. Composed children replace the label, which is how an icon goes inside the button.
+The control that returns the shopper to browsing, rendered as a button (`data-fs-cart-continue-shopping`, alongside `data-fs-drawer-close` and `data-fs-button`). It **dismisses the overlay and dispatches no cart write**. Composed children are the button content, which is how an icon goes inside the button; without them the text is the `$content` field `label`.
 
 It is the drawer's own close control, so it **requires a `DrawerRoot` ancestor** — on a cart page with no drawer, compose a `NavigationLink` back to browsing instead. Placing it outside a drawer fails the render rather than degrading.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | `"Continue shopping"` | Non-CMS fallback. A CMS entry's `label` wins over it; composed children win over both |
+| `$content` field | Notes |
+|------------------|-------|
+| `label` | ICU message, e.g. `"Continue shopping"`. Formatted only when no children are composed; blank renders nothing |
 
-**Content:** declares the `cart-continue-shopping` content model (one `label` property). Authored independently of the message, so publishing one does not require restating the other.
+**Content:** declares the `cart-continue-shopping` content model (one `label` field). Authored independently of the message, so publishing one does not require restating the other.
 
 ---
 
@@ -151,17 +172,17 @@ The applied coupons are a **list of chips (1..N)**, not a single-coupon slot —
 
 | Component | Element | Purpose | Notes |
 |-----------|---------|---------|-------|
-| `CartCouponForm` | `form` | Coupon code input + apply button | Dispatches `$actions.cart.applyCoupon`. Disables input + button and exposes `data-fs-cart-coupon-pending` while an apply is in flight; clears the input on success. Raises one success toast titled `appliedMessage` (default `Coupon applied`) only when the apply returns no errors and the submitted code comes back matched (compared ignoring case); an unmatched code, an error or a blank or `null` `appliedMessage` raises none. The toast still shows when `CartCouponEmpty` removes the form, and nothing shows without a `ToastProvider` (the apply still works). |
-| `CartAppliedCoupons` | `div` | Renders one chip per applied coupon | Reads `cart.appliedCoupons`; renders nothing when empty (no container). Each chip shows the `code` inline and a `CartCouponRemove`. An applied-but-no-discount coupon (`isUnmatchedCondition`) is exposed via the `data-fs-cart-coupon-unmatched` hook for the store to style/label (no baked copy); compose `CartCouponUnmatched` in the chip template for a text notice. A chip template replaces the built-in remove control, so one that composes the notice must also compose `CartCouponRemove`. |
+| `CartCouponForm` | `form` | Coupon code input + apply button | Dispatches `$actions.cart.applyCoupon`. Disables input + button and exposes `data-fs-cart-coupon-pending` while an apply is in flight; clears the input on success. Its `$content` (`cart-coupon-form`) carries `placeholder` (also the input's accessible name), `applyLabel` and `appliedMessage`; composed children replace the input and button. Raises one success toast titled `appliedMessage` only when the apply returns no errors and the submitted code comes back matched (compared ignoring case); an unmatched code, an error or a blank or missing `appliedMessage` raises none. The toast still shows when `CartCouponEmpty` removes the form, and nothing shows without a `ToastProvider` (the apply still works). |
+| `CartAppliedCoupons` | `div` | Renders one chip per applied coupon | Reads `cart.appliedCoupons`; renders nothing when empty (no container). Each chip shows the `code` inline and a `CartCouponRemove`; the built-in one is named by the `$content` field `removeLabel` (`cart-applied-coupons`, an ICU message with a `code` argument, e.g. `"Remove coupon {code}"`). An applied-but-no-discount coupon (`isUnmatchedCondition`) is exposed via the `data-fs-cart-coupon-unmatched` hook for the store to style/label (no baked copy); compose `CartCouponUnmatched` in the chip template for a text notice. A chip template replaces the built-in remove control, so one that composes the notice must also compose `CartCouponRemove`. |
 | `CartCouponRemove` | `button` | The per-chip remove control (the X) | Dispatches `$actions.cart.removeCoupon` for the chip's code. Use inside a `CartAppliedCoupons` chip, which supplies the code via context. |
-| `CartCouponError` | `div` (`role="alert"`) | Inline coupon error banner | Reads a **dedicated** coupon error channel, separate from `CartError` (which carries item-write errors). Renders the first error, or nothing when there are none. |
+| `CartCouponError` | `div` (`role="alert"`) | Inline coupon error banner | Reads a **dedicated** coupon error channel, separate from `CartError` (which carries item-write errors). Renders the first error, or nothing when there are none, worded by its code from the `$content` of `cart-coupon-error`: `couponNotFoundMessage` (`COUPON_NOT_FOUND`), `couponExpiredMessage` (`COUPON_EXPIRED`), `couponNotCombinedMessage` (`COUPON_NOT_COMBINED`), and `genericErrorMessage` for `NETWORK_ERROR`, `MISSING_CART_CONTEXT` and `CART_NOT_FOUND`. A code it does not know (one a newer server added) shows `genericErrorMessage` and logs `message.unknown-code`; composed `children` replace the message. |
 | `CartCouponEmpty` | `div` | Coupon entry gate | Renders its children only while the resolved cart has no applied coupon; renders nothing while the cart loads or once any coupon (matched or not) is applied. Copy-free, no schema props. Wrap the coupon entry in it for a single-coupon store; omit it for a multi-coupon store. |
-| `CartCouponUnmatched` | `output` | Per-chip notice for an unmatched coupon | Reads the chip's coupon from context; renders the `message` copy only while that coupon has `isUnmatchedCondition`, and nothing when it matches, outside a chip, or when the copy is blank. `children` override `message`. Never removes the coupon. Not part of the built-in chip: compose it next to `CartCouponRemove`. |
-| `CartCouponSavings` | `span` | Per-chip amount a fixed-amount coupon took off | Reads the chip's coupon from context and sums the `COUPON` entries of `cart.discounts` named after its code; renders the amount with the currency's own minus sign (`-R$ 20,00`), and nothing for an unmatched, free-shipping or percentage coupon (the API attributes no amount to them), outside a chip, or when the sum is not above zero. `template` words the text (default `{amount}`): every `{amount}` is the formatted saving and every `{code}` the chip's code; other `{…}` text stays literal, and a blank template counts as unset. The chip already shows the code before its children, so `{code}` repeats it. Not part of the built-in chip: compose it next to `CartCouponRemove`. |
+| `CartCouponUnmatched` | `output` | Per-chip notice for an unmatched coupon | Reads the chip's coupon from context; renders the `$content` field `message` (`cart-coupon-unmatched`) only while that coupon has `isUnmatchedCondition`, and nothing when it matches, outside a chip, or when the message is blank or missing. `children` render instead of the message. Never removes the coupon. Not part of the built-in chip: compose it next to `CartCouponRemove`. |
+| `CartCouponSavings` | `span` | Per-chip amount a fixed-amount coupon took off | Reads the chip's coupon from context and sums the `COUPON` entries of `cart.discounts` named after its code; renders the amount with the currency's own minus sign (`-R$ 20,00`), and nothing for an unmatched, free-shipping or percentage coupon (the API attributes no amount to them), outside a chip, or when the sum is not above zero. The `$content` field `template` (`cart-coupon-savings`) words the text as an ICU message whose one argument, `{amount}`, is the formatted saving (e.g. `{amount}` or `Economia de {amount}`); an unknown argument renders the message as authored and logs an error, and a blank or missing message renders empty and logs `message.missing`. The chip already shows the code before its children. Not part of the built-in chip: compose it next to `CartCouponRemove`. |
 
 `CartAppliedCoupons` repeats its `children` once per applied coupon (like `CartList` repeats per item): place the chip template — an optional code element plus a `CartCouponRemove` — as its children, and it is cloned per coupon with the coupon supplied via context. Omit `children` to get a built-in chip (code inline + a remove X). A template that composes `CartCouponUnmatched` or `CartCouponSavings` must also compose `CartCouponRemove`, because composed children replace the built-in remove control.
 
-**Errors:** coupon apply/remove `userErrors` (e.g. `COUPON_NOT_FOUND`, `COUPON_EXPIRED`) publish to a dedicated reactive var that only `CartCouponError` reads, so coupon feedback never collides with item-write errors shown by `CartError`. A code rejected while another coupon is applied returns `COUPON_NOT_COMBINED` (whatever the account allows) with a neutral message, and the applied coupons stay; a store can override the text with `CartCouponError` children. `cartCouponErrorsVar` is cleared when a coupon write starts (item writes and `validate` leave it alone) and when a CartRoot mounts, never on re-render, so a rejected code from a layout mini-cart form does not show under the Cart page's coupon form. Two cases stay:
+**Errors:** coupon apply/remove `userErrors` (e.g. `COUPON_NOT_FOUND`, `COUPON_EXPIRED`) publish to a dedicated reactive var that only `CartCouponError` reads, so coupon feedback never collides with item-write errors shown by `CartError`. A code rejected while another coupon is applied returns `COUPON_NOT_COMBINED` (whatever the account allows), and the applied coupons stay; `couponNotCombinedMessage` words it, so write it without claiming the code is unknown or cannot be combined. `cartCouponErrorsVar` is cleared when a coupon write starts (item writes and `validate` leave it alone) and when a CartRoot mounts, never on re-render, so a rejected code from a layout mini-cart form does not show under the Cart page's coupon form. Two cases stay:
 
 - A coupon apply still in flight when a CartRoot mounts shows its failure after the clear, for example from a layout mini-cart form (known limitation).
 - An error from the Cart page's form stays visible in a persistent `CartCouponError` after the shopper leaves (known limitation).
@@ -281,8 +302,8 @@ This is pure composition with three mutually-exclusive self-hide branches — `C
 
 The empty panel's copy lives in two leaves, one string each, so the panel is a composition rather than a configured block:
 
-- **`CartEmptyMessage`** renders the message as a paragraph (`data-fs-cart-empty-message`). The wording is merchant-editable: a CMS entry wins over the `text` prop, which defaults to "Your cart is empty"; blank copy renders nothing.
-- **`CartContinueShopping`** renders the control that returns the shopper to browsing (`data-fs-cart-continue-shopping`). Its `label` is merchant-editable the same way, and composed children replace the label when you want an icon inside the button.
+- **`CartEmptyMessage`** renders the message as a paragraph (`data-fs-cart-empty-message`). The text is the `$content` field `text`; a blank or missing message renders nothing.
+- **`CartContinueShopping`** renders the control that returns the shopper to browsing (`data-fs-cart-continue-shopping`). Its text is the `$content` field `label`, and composed children replace it when you want an icon inside the button.
 
 Neither leaf renders a wrapper or carries spacing, so **order, grouping, and any illustration are yours**: put an `Icon` above the message, wrap the pair in a `Container`, pin the control to a footer `Container`. Both self-hide independently, so composing only one is valid.
 
@@ -303,7 +324,7 @@ CartRoot (layout)
     │   └── CartGoCheckout
     └── CartEmpty             ← only when the cart resolved to 0 items
         ├── Icon                    ← optional illustration (any particle, any position)
-        ├── CartEmptyMessage        ← "sua cesta está vazia" (CMS copy + prop fallback)
+        ├── CartEmptyMessage        ← "sua cesta está vazia" ($content message)
         └── Container               ← the store's footer grouping
             └── CartContinueShopping ← "continuar comprando" (closes the drawer; no cart action)
 ```
@@ -338,7 +359,7 @@ On a cart/checkout page there is no drawer to close, so the empty branch keeps `
 }
 ```
 
-The `text` and `label` props are the non-CMS fallback. When the store publishes a content entry for the element, that entry's copy wins — the two elements are authored independently, so publishing the message does not force you to restate the label.
+`text` and `label` are message fields: the generator delivers what the schema authors under those names as `$content`. The two elements are authored independently, so publishing the message does not force you to restate the label.
 
 ---
 
@@ -355,7 +376,7 @@ The `text` and `label` props are the non-CMS fallback. When the store publishes
 - **Putting the empty message inside `CartEmpty` as a component prop.** `CartEmpty` is copy-free; the copy belongs to the `CartEmptyMessage` leaf composed inside it.
 - **Placing `CartContinueShopping` outside a drawer.** It is the drawer's close control, so a cart page without a `DrawerRoot` ancestor fails to render — compose a `NavigationLink` there instead.
 - **Wrapping the empty copy to get spacing you expect the leaves to provide.** Neither leaf ships layout by design; use `Container` and swatches.
-- **Hard-coding the checkout wording when a CMS is bound.** `CartGoCheckout`'s `label` (and the older `children`) is the fallback; content editors expect the `cart-checkout-label` entry to win.
+- **Hard-coding the checkout wording when a CMS is bound.** Authored `children` render before the `cart-checkout-label` message, so a CTA labelled through `children` ignores what content editors write. Author the `label` field instead.
 - **Expecting a CMS entry to change where checkout goes.** The content channel is the label alone. `href` stays an authored prop.
 
 ---
@@ -366,23 +387,22 @@ The mini-cart drawer (the layout composition described on `CartRoot`) ends in a
 
 - **`CartCheckoutGuard`** is the outer wrapper. It reads cart availability and, while any line item is not `AVAILABLE`, makes its whole subtree non-interactive (`inert` + `aria-disabled`) and exposes `data-fs-cart-checkout-blocked` for styling the disabled state. The shopper cannot proceed with an undeliverable item. It updates reactively from cache — no refetch, no reload — so the block clears the moment the offending line is removed or becomes available.
 - **`CartTotal`** sits inside the guard, on or next to the button, so the grand total the shopper is about to pay is visible at the CTA. It reads the nearest `CartRoot`/`CartTotalizerRoot` and reformats reactively on every cart change.
-- **`CartGoCheckout`** is the link to checkout (default `href` the checkout page, `{ "standard": "checkout" }`). During a **client-side** route transition it surfaces a loading state on its content wrapper — `aria-busy` plus `data-fs-cart-go-checkout-pending` — so the shopper sees the click registered. There is **no built-in spinner**: opt into one by styling that attribute (or composing a `Spinner` on it). For an **external or hard** checkout navigation (a non-Next route, a different origin, or a full page load — common for the real VTEX checkout) there is no client-side transition window, so the loading state simply does not show. That is the documented, graceful no-op, not a bug.
+- **`CartGoCheckout`** is the link to checkout (default `href` the checkout page, `{ "standard": "checkout" }`). During a **client-side** route transition it surfaces a loading state on its content wrapper — `aria-busy` plus `data-fs-cart-go-checkout-pending` — so the shopper sees the click registered. There is **no built-in spinner**: opt into one by styling that attribute (or composing a `Spinner` on it). For an **external or hard** checkout navigation (a non-Next route, a different origin, or a full page load — common for the real VTEX checkout) there is no client-side transition window, so the loading state simply does not show. That is the documented, graceful no-op, not a bug. When it leaves for the checkout it also closes the mini-cart drawer it sits in, so the shopper sees the checkout and not a drawer over it: with a wired stock check, right before the navigation, so a navigation the stock check cancelled, a modifier click (new tab or window) and a click another `onClick` cancelled leave the drawer open; without one, on the click itself. Do not wrap it in `DrawerClose`. Because the drawer closes with the click, the pending state is visible only briefly on that native path (it never shows on the validated one).
 
-**The button wording is CMS content.** It resolves in a fixed order: the `cart-checkout-label` entry, then the `label` prop, then `children`, then the package default `"Checkout"`. So a merchant rewords the CTA — `"Finalizar compra"`, `"Ir para o pagamento"` — with a CMS save and no deployment, while a store with no CMS binding renders its authored value. `children` stays supported because that is where stores labelled the button before `label` existed; a CMS entry overrides it with no schema edit. A blank or whitespace-only entry value counts as unconfigured and falls through. Non-compiler hosts (Storybook, tests) pass a typed `$content` fixture directly.
+**The button wording is a message.** Composed `children` render first, as for every other cart leaf; without them the button shows the `$content` field `label` of the `cart-checkout-label` content model, so a merchant rewords the CTA — `"Finalizar compra"`, `"Ir para o pagamento"` — with a CMS save and no deployment. A blank or whitespace-only string child counts as unset and the message fills the slot. A missing message renders empty and logs `message.missing`. Non-compiler hosts (Storybook, tests) pass a typed `$content` fixture directly.
 
 **The destination is not content-editable.** `href` is an authored prop only. The content channel carries the label alone, so a content editor can change what the button says but never where it goes.
 
 | Prop | Type | Required | Notes |
 |-------|------|----------|-------|
 | `href` | page reference or string | no | Checkout destination, default `{ "standard": "checkout" }`. A string is a logical path or an off-site URL. Never content-editable |
-| `label` | string | no | Authored fallback for the wording. Ignored when an entry supplies a label |
-| `children` | node | no | Legacy label channel, still honoured. Element children are replaced when an entry supplies a label |
+| `children` | node | no | Button content; renders instead of the message |
 
-Content model (`cart-checkout-label`) fields, edited in the CMS:
+Content model (`cart-checkout-label`) fields:
 
-| Field | Type | Required | Notes |
-|-------|------|----------|-------|
-| `label` | string | yes | The button wording, rendered verbatim |
+| Field | Type | Notes |
+|-------|------|-------|
+| `label` | ICU message | The button wording, e.g. `"Checkout"` |
 
 Schema shape (inside the `DrawerPopup` footer `Container`):
 
@@ -405,22 +425,21 @@ Everything stays a layout composition: the guard, total, and link are independen
 
 `CartCount` renders `<span data-fs-cart-count>` with the number of units in the cart: the sum of `quantity` over the non-gift lines (two lines of 1 read 2; one line of 3 reads 3; a gift-only cart reads 0). Must be inside `CartRoot`.
 
-- `template` — the output format, `{count}` replaced by the count; default `'{count}'`. Children override the text.
-- `templateOne` — the output format used **only when the count is exactly 1**. It has no default: when unset, or blank, `template` is used at 1 as well. **0 uses `template`**, never `templateOne`, because the selector is the literal count and not a locale plural rule (in `pt-BR` the plural rule would call 0 singular).
+- `template` — the `$content` field (`cart-count`) that words the count, an ICU message with a `count` argument, e.g. `'{count}'`. A plain `{count}` is formatted in the locale (`1.000` in `pt-BR`). Word the count with a plural: `=1` selects exactly 1, while `one` follows the locale's plural rule (in `pt-BR` it also covers 0). Children override the text; a missing message renders empty and logs `message.missing`.
 - A count that is not a finite number renders **nothing**. A non-gift line whose `quantity` is missing, `null`, `NaN`, infinite or a string makes the count unreliable, so the span is not rendered, even with `children`; a partial sum would undercount. 0 is finite: an empty or gift-only cart still renders `0`.
 
-`CartUnavailableCount` takes the same `template` and `templateOne` pair (see [below](#unavailable-item-recovery)), selected on the number of unavailable lines.
+`CartUnavailableCount` has the same `template` field (see [below](#unavailable-item-recovery)), counted on the number of unavailable lines.
 
 ```json
 {
   "cart-title-count": {
     "type": "CartCount",
-    "props": { "template": "{count} itens", "templateOne": "{count} item" }
+    "props": { "template": "{count, plural, =1 {# item} other {# itens}}" }
   }
 }
 ```
 
-Only the first `{count}` in a template is replaced.
+An invalid message renders as authored and logs an error.
 
 ---
 
@@ -428,8 +447,8 @@ Only the first `{count}` in a template is replaced.
 
 `CartCheckoutGuard` blocks checkout while any line is not `AVAILABLE`; the recovery affordances let the shopper resolve the block from inside the cart. Three pieces, all reading the availability already on the cart:
 
-- **`CartUnavailableCount`** — cart-level summary of how many lines are unavailable (e.g. "2 items unavailable"). Renders a `<span data-fs-cart-unavailable-count>` with a `template` prop (`{count}` is replaced by the integer count; default `'{count} items unavailable'`; children override the text) and an optional `templateOne` used only when exactly one line is unavailable (it falls back to `template` when unset or blank). **Self-hides** (`null`) when every line is available — including while the cart is still loading — so it never shows a false "0 items unavailable". Must be inside `CartRoot`.
-- **`CartRemoveUnavailable`** — the bulk "remove all unavailable" button (`<button data-fs-cart-remove-unavailable>`). On click it dispatches **one** `$actions.cart.removeItems({ ids })` call carrying every unavailable line id: one mutation, one upstream write, one cache update — no per-line flicker. **Self-hides** when there is nothing to remove. Children are the label (default "Remove unavailable items"). Must be inside `CartRoot` (it reads the cart for the ids; the write itself is context-free).
+- **`CartUnavailableCount`** — cart-level summary of how many lines are unavailable (e.g. "2 items unavailable"). Renders a `<span data-fs-cart-unavailable-count>` with the `$content` field `template` (`cart-unavailable-count`, an ICU message with a `count` argument, e.g. `'{count, plural, one {# item unavailable} other {# items unavailable}}'`; children override the text). **Self-hides** (`null`) when every line is available — including while the cart is still loading — so it never shows a false "0 items unavailable". Must be inside `CartRoot`.
+- **`CartRemoveUnavailable`** — the bulk "remove all unavailable" button (`<button data-fs-cart-remove-unavailable>`). On click it dispatches **one** `$actions.cart.removeItems({ ids })` call carrying every unavailable line id: one mutation, one upstream write, one cache update — no per-line flicker. **Self-hides** when there is nothing to remove. Children are the label; without them it is the `$content` field `label` (`cart-remove-unavailable`, e.g. "Remove unavailable items"). Must be inside `CartRoot` (it reads the cart for the ids; the write itself is context-free).
 - **Per-item remove-on-alert** — a `CartItemRemove` nested inside `CartItemUnavailable` in the line-item template, so each unavailable alert carries its own remove control. Composition only, no new component — see `cart-item.md` (including the label-vs-children nuance: children replace the built-in label).
 
 Both cart-level components update reactively: removing the last unavailable line hides them and clears the `CartCheckoutGuard` block with no refetch. Mutation errors surface through the existing `CartError` banner.
@@ -447,9 +466,84 @@ Schema shape (mini-cart footer, above the checkout CTA):
 
 ---
 
+## Separating purchasable and unavailable lines
+
+`CartList` renders every line in one run. A store that wants the lines the shopper can buy apart from the ones it cannot replaces `CartList` with a pair of lists and a labelled section:
+
+- **`CartAvailableItems`** renders its children once per line whose availability is `AVAILABLE`, in cart order. While the cart is loading it renders `skeletonCount` (default 3) skeletons; it renders nothing when no line is purchasable.
+- **`CartUnavailableItems`** renders its children once per line whose availability is anything else (`OUT_OF_STOCK`, `UNAVAILABLE`, `UNKNOWN`), in cart order. It renders nothing when no line is unavailable, and while loading. It uses the same predicate as `CartCheckoutGuard`, `CartUnavailableCount` and `CartRemoveUnavailable`, so the two lists partition the cart exactly.
+- **`CartUnavailableSection`** is a gate: it renders a `div` around its children only while at least one line is unavailable, so the card, its header and the list disappear together. It carries no copy.
+- **`CartUnavailableLabel`** is the section's heading copy (see Components).
+
+Both lists provide the `cart-item` context, so `CartItemRoot` and the other per-line components compose inside either one. Gift lines follow their availability like any other line; an unavailable gift line has no per-line remove (`CartItemRemove` renders nothing on a gift), and `CartRemoveUnavailable` removes it. Unavailable lines still count in the order total until removed.
+
+Replace `CartList`, do not compose both: with `CartList` beside the pair every line would render twice.
+
+```json
+{
+  "page-body": { "type": "CartFilled", "children": ["cart-items-list", "unavailable-section"] },
+  "cart-items-list": { "type": "CartAvailableItems", "children": ["cart-item-root"] },
+  "cart-item-root": { "type": "CartItemRoot", "children": ["item-name"] },
+  "item-name": { "type": "CartItemName" },
+  "unavailable-section": {
+    "type": "CartUnavailableSection",
+    "children": ["unavailable-section-header", "unavailable-section-divider", "unavailable-items-list"]
+  },
+  "unavailable-section-header": {
+    "type": "Container",
+    "style": ["flex", "items-center", "gap-2"],
+    "children": ["unavailable-section-icon", "unavailable-section-title"]
+  },
+  "unavailable-section-icon": { "type": "Icon", "props": { "name": "lucide:package-x" } },
+  "unavailable-section-title": { "type": "CartUnavailableLabel", "props": { "text": "Unavailable" } },
+  "unavailable-section-divider": { "type": "Separator", "props": { "orientation": "horizontal" } },
+  "unavailable-items-list": { "type": "CartUnavailableItems", "children": ["unavailable-item-root"] },
+  "unavailable-item-root": { "type": "CartItemRoot", "children": ["unavailable-item-name", "unavailable-item-remove"] },
+  "unavailable-item-name": { "type": "CartItemName" },
+  "unavailable-item-remove": { "type": "CartItemRemove", "children": ["unavailable-item-remove-icon"] },
+  "unavailable-item-remove-icon": { "type": "Icon", "props": { "name": "trash" } }
+}
+```
+
+---
+
+## Nothing left to buy
+
+When every line the shopper added is unavailable, the order cannot be placed, and `CartCheckoutGuard` already makes the checkout CTA inert. `CartAllUnavailable` and `CartAllUnavailableMessage` say so in words.
+
+- **`CartAllUnavailable`** is a gate: it renders a `div` around its children only while the cart has at least one shopper-added line and every shopper-added line is unavailable (a line counts as unavailable by the same per-line test as `CartUnavailableSection`, so `UNKNOWN` counts; the gate differs from the section, which shows when any line is unavailable, because it needs every shopper-added line to be). It carries no copy and no role. While it holds no rendered `CartAllUnavailableMessage` (blank copy, or no message composed), the store stylesheet hides it (`display: none !important`, through `:has`), so put the box on the gate, not on a wrapper around it: blank copy leaves no empty box, and a `display` class on the gate cannot show it. Browsers without `:has` show the gate as before.
+- **Gift lines are ignored.** A promotional gift is not something the shopper can buy, so a cart whose only available line is a gift still shows the warning, and a cart holding only gift lines never does.
+- **Not `CartEmpty`.** `CartEmpty` owns the cart with zero lines; `CartAllUnavailable` needs at least one shopper-added line, so the two never render together. It renders nothing while the cart is loading or the query failed.
+- **`CartAllUnavailableMessage`** is the copy (see Components). It is an alert region (`role="alert"`), so a screen reader announces it when it appears, for example after the shopper removes the last purchasable line.
+- **The link is optional.** It renders after the text only when both `linkText` and `linkHref` resolve; one without the other renders no link and no anchor. There is no default destination and no default text. A CMS field wins over its prop field by field, so a CMS store authors no link props. A destination that is not a page reference or an http, https, mailto, tel or site-relative URL is dropped.
+
+Place the gate under `CartFilled`, beside the lists:
+
+```json
+{
+  "page-body": { "type": "CartFilled", "children": ["all-unavailable", "cart-items-list", "unavailable-section"] },
+  "cart-items-list": { "type": "CartAvailableItems", "children": ["cart-item-root"] },
+  "cart-item-root": { "type": "CartItemRoot" },
+  "unavailable-section": { "type": "CartUnavailableSection", "children": ["unavailable-items-list"] },
+  "unavailable-items-list": { "type": "CartUnavailableItems", "children": ["unavailable-item-root"] },
+  "unavailable-item-root": { "type": "CartItemRoot" },
+  "all-unavailable": { "type": "CartAllUnavailable", "children": ["all-unavailable-message"] },
+  "all-unavailable-message": {
+    "type": "CartAllUnavailableMessage",
+    "props": {
+      "text": "No items are available for purchase right now",
+      "linkText": "Review your selection",
+      "linkHref": { "page": "<page name>" }
+    }
+  }
+}
+```
+
+---
+
 ## Clearing the cart
 
-`ClearCartButton` empties the cart in one click (`<button data-fs-clear-cart-button>`). It reads every line id from the cart and dispatches **one** `$actions.cart.removeItems({ ids })` call: every line goes, gift and unavailable lines included, in cart order. No confirmation dialog and no toast. Children are the label (default "Clear cart"). Must be inside `CartRoot`.
+`ClearCartButton` empties the cart in one click (`<button data-fs-clear-cart-button>`). It reads every line id from the cart and dispatches **one** `$actions.cart.removeItems({ ids })` call: every line goes, gift and unavailable lines included, in cart order. No confirmation dialog and no toast. Children are the label; without them it is the `$content` field `label` (`clear-cart-button`, e.g. "Clear cart"). Must be inside `CartRoot`.
 
 - **Self-hides** (`null`) when the cart has no lines or has not resolved, as `CartRemoveUnavailable` does.
 - **Disabled while pending.** The button carries the native `disabled` attribute plus `data-fs-clear-cart-button-pending` until the call settles, and a second click in the same tick is swallowed, so one click is one mutation. Style the pending look with `disabled:` classes or the pending hook. A caller `disabled` prop also disables it.
@@ -466,7 +560,7 @@ Schema shape (Cart page):
   "cart-error": { "type": "CartError" },
   "page-body": { "type": "CartFilled", "children": ["clear-cart-row"] },
   "clear-cart-row": { "type": "Container", "children": ["clear-cart-btn"] },
-  "clear-cart-btn": { "type": "ClearCartButton", "props": { "children": "Limpar carrinho" } }
+  "clear-cart-btn": { "type": "ClearCartButton", "props": { "label": "Clear cart", "children": "Limpar carrinho" } }
 }
 ```
 

package/dist/docs/challenge-return.md

@@ -0,0 +1,135 @@
+# ChallengeReturn
+
+**Category:** commerce
+**Purpose:** The whole of the page the bank sends the shopper back to after a 3D Secure challenge. Finishes the order with no click, then replaces the page with the order confirmation; a shopper who returns too late is told the verification expired and offered a link back to the checkout.
+
+---
+
+## Visual cues (how to identify in an image)
+
+**None, deliberately.** This component has no visual identity and must never be selected from a screenshot. It is a route's behavior rather than a block on a page: what it draws is a short status line, and only for the moment before the shopper is moved on. A design showing the bank's verification screen is showing the *bank's* page, which this stack does not render, and nothing in that image maps to this component.
+
+The image is the source of truth for layout, and this component is not in any layout.
+
+## When to use
+
+- On the page named by `PlaceOrder`'s `challengeReturnHref`, as its only element, when the store accepts cards whose bank may ask for a 3D Secure challenge.
+
+## When NOT to use
+
+- For the confirmation page the shopper lands on afterwards → use the order-placed components; this page only finishes the order and leaves.
+- For the place-order button → use [[place-order]], which sends the shopper to the bank. This page is where the bank sends them back.
+- Anywhere a shopper is meant to read the page. Anything composed beside it is replaced as soon as the order is finished.
+
+---
+
+## Composition
+
+`ChallengeReturn` is a leaf element in the PageSchema and takes no children. It owns the whole page. It requires no payment root and declares no context and no fragment: it reads the order group from its own URL, calls the gateway callback once, and reads the settled order once.
+
+```text
+ChallengeReturn
+```
+
+The page is an ordinary page of the store (no standard page name fits it), and the store names it from `PlaceOrder`:
+
+```json
+{
+  "place-order": {
+    "type": "PlaceOrder",
+    "props": { "challengeReturnHref": { "page": "checkout-challenge-return" } }
+  }
+}
+```
+
+The page itself is a `page.json` named `checkout-challenge-return`, containing one `ChallengeReturn` element. Give it `robots` noindex.
+
+## Components
+
+### ChallengeReturn
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `checkoutHref` | page reference or string | `{ "standard": "checkout" }` | Where that link goes. |
+| `successHref` | page reference or string | `{ "standard": "order-placed" }` | Where the shopper lands once the order is finished. A page reference gets the order's Node id as its `orderId` param. |
+
+**Content model** (`challenge-return`), each field read only from `$content` (a missing message renders empty and logs `message.missing`):
+
+- `resumingMessage`: status shown while the order is being finished.
+- `lateReturnMessage`: shown in an alert when the gateway callback answered a refusal: the verification lapsed and the order was not placed.
+- `unconfirmedMessage`: shown as a status when the callback gave no answer, answered with no order to show, or when the confirmation page cannot be reached. The payment may still be processing, so there is no link to buy again.
+- `checkoutLabel`: label of the link back to the checkout, inside the late-return alert.
+
+**Actions:** declares `actions: { payment: ['gatewayCallback'], analytics: ['track'] }` and nothing else. It never opens a transaction and never posts a card: a return never pays.
+
+### What the page does, in order
+
+1. Reads the order group from the URL. The query must be exactly one `orderGroup` and `redirect=true`; anything else (a missing or repeated group, a dot segment, a group with a slash, a longer-than-64-character group, `redirect` absent or not `true`) makes no request at all and shows the late-return alert. Any other parameter the bank adds is ignored and never used.
+2. Calls the gateway callback once for that group, asking it to accept the challenge. A repeated mount never calls it twice.
+3. On success, reads the settled order once (within ten seconds), reports one `purchase` analytics event with the order's reference as the transaction id and its total as the value, and replaces the history entry with the confirmation page. The event is skipped for an order the read says is `DENIED`, for one with no total, when the read fails or is not answered in time, and when this browser already reported that order. The shopper still reaches the confirmation page in every one of those cases. The event goes out before the history entry is replaced, and the once-per-order marker is the one `PlaceOrder` uses for its own single-pass and resume paths, so an order is reported once whichever path finished it (see [[place-order]]).
+4. On a refusal the server coded, shows the late-return alert. On no answer, a success with no order to show, or a confirmation page the store cannot reach (or a router that throws), shows the unconfirmed status. Nothing moves the shopper on a timer, and the page never sends the shopper back to the bank.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "challenge-return": {
+    "type": "ChallengeReturn",
+    "props": {
+      "resumingMessage": "Finishing your order...",
+      "lateReturnMessage": "3D Secure expired. Go back to the checkout to place your order again.",
+      "checkoutLabel": "Back to the checkout"
+    }
+  }
+}
+```
+
+## Common mistakes
+
+- **Composing it beside anything else.** The page is replaced as soon as the order is finished, so copy authored next to it is rarely seen.
+- **Forgetting to author `challengeReturnHref` on `PlaceOrder`.** Without it the store sends no return URL, so a bank challenge cannot be followed and the shopper reads the refusal instead.
+- **Linking the late-return message to a payment page.** The link goes to the checkout, where the shopper places a new order; it never retries the old one.
+- **Selecting it from a screenshot.** It has no visual identity.
+
+## Known limitations
+
+- **If the transaction cookies do not survive the round trip to the bank, every return reads as expired.** The callback needs the cookies the checkout set; a browser that drops them answers a refusal even when the shopper completed the challenge, and VTEX cancels the order five minutes after it was placed.
+- **A shopper who never returns from the bank triggers nothing.** Neither `PlaceOrder` nor this page sets a timer, listens for the page being left, sends a cancel or void call, or polls the order after the redirect. VTEX's Checkout API asks for the payment to be confirmed within five minutes of placing the order, and VTEX cancels the order it opened after that window. Nothing in this repository observes the cancel. Whether it also releases the authorization held on the card is a question for Payments that the storefront does not answer: it never sends a reversal.
+- **The callback only runs for the order group this browser session started.** `paymentStartTransaction` sets the `HttpOnly` `__Host-fs_order_group` cookie (see [ADR-0023](../../../../../docs/storefront-core/adr-0023-credit-card-guarantees-and-deviations.md)), and `paymentGatewayCallback` checks the transaction cookies first (with them missing the result is `MISSING_TRANSACTION_COOKIES`). Once they are present, it answers `ORDER_GROUP_MISMATCH` before calling VTEX when the group in the URL differs from the cookie or the cookie is missing. This page treats that code like any server-coded refusal and shows the late-return alert, so a link carrying someone else's group finishes nothing and a return in another browser reads as expired. The cookie lives 15 minutes and survives the return, so reloading this page after the order is placed repeats the callback instead of turning into a refusal. With two 3D Secure checkouts pending in one browser the cookie holds the later group, and the first return reads as expired even if its challenge was completed.
+- **A shopper told to buy again may see two holds on the card** until the bank releases the first.
+- **The page undercounts `purchase` in four cases**: the settled-order read fails or takes over ten seconds, the order is `DENIED`, the order has no total, or the shopper's browser blocks storage and the page is reloaded before it leaves. It overcounts only when two different browsers each report the same order once.
+- **The order group is in the return URL**, so it sits in the browser history and, for same-origin requests, the `Referer`. The order's Node id is a reversible base64 of the same group.
+- **Payment-app delivery of 3D Secure is not supported.** Only accounts that deliver the challenge by redirect are.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `ChallengeReturn` (root `div`, `data-fs-challenge-return`) | Layout wrapper for whichever state is showing | `flex min-h-[420px] flex-col items-center justify-center gap-[12px] text-center` |
+| Resuming (`data-fs-challenge-return-resuming`) | The status line while the order is being finished, an `<output>` | `text-[14px] font-medium text-[#6B7280]` |
+| Late return (`data-fs-challenge-return-late`) | The alert, `role="alert"`, holding the message and the link | `flex flex-col items-center gap-[8px] text-[14px] text-[var(--color-feedback-danger)]` |
+| Message (`data-fs-challenge-return-message`) | The late-return sentence inside the alert | `text-[14px]` |
+| Checkout link (`data-fs-challenge-return-checkout-link`) | The real anchor back to the checkout | `text-[14px] font-bold underline text-[#1A1A1A]` |
+| Unconfirmed (`data-fs-challenge-return-unconfirmed`) | The status that says the payment may still be processing, an `<output>` | `text-[14px] text-[var(--color-feedback-warning)]` |
+
+```json
+{
+  "challenge-return": {
+    "type": "ChallengeReturn",
+    "style": ["flex", "min-h-[420px]", "flex-col", "items-center", "justify-center", "gap-[12px]", "text-center"]
+  }
+}
+```
+
+The role colors above are the foundation's `visualIdentity` roles (`--color-feedback-danger`, `--color-feedback-warning`), so they follow the store when it changes them.
+
+---
+
+## Related
+
+- [[place-order]] — the CTA that sends the shopper to the bank and names this page with `challengeReturnHref`.
+- [[sign-in-redirect]] — the other whole-page handover component, with the same rule: place it alone on its page.

package/dist/docs/client-preferences-fieldset.md

@@ -59,8 +59,15 @@ SessionRoot                                (required ancestor; session tri-state
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `skeletonCount` | number | `2` | Placeholder rows drawn while the preferences resolve. Set it to the number of controls composed. |
-| `loadingLabel` | string | `'Loading your preferences'` | Announced politely while the preferences resolve. Blank means no announcement. |
-| `loadedLabel` | string | `'Your preferences are ready'` | Announced politely once the controls mount. Blank means no announcement. |
+
+Content model (`client-preferences-fieldset`), ICU message fields with no package default; an unauthored one renders empty and logs `message.missing`:
+
+| Field | Source (English) | Notes |
+|-------|------------------|-------|
+| `loadingLabel` | `Loading your preferences` | Announced politely while the preferences resolve. |
+| `loadedLabel` | `Your preferences are ready` | Announced politely once the controls mount. |
+| `groupLabel` | `Your preferences` | Accessible name of the `<fieldset>` group; unauthored, no `aria-label` is emitted. |
+| `genericErrorMessage` | `Unable to save your preferences. Please try again.` | Shown by `FormError` for every refusal of the write (`MISSING_CART_CONTEXT`, `CART_NOT_FOUND`, `NO_PREFERENCE_PROVIDED`) and for a network failure; none is one the shopper can fix. A code this fieldset does not know shows it too and logs `message.unknown-code`. |
 
 Declares `requiresContext: ['form', 'session']` (needs both a `FormRoot` and a `SessionRoot` ancestor), `providesContext: 'client-preferences'`, `actions: { identity: ['clientPreferencesUpdate'] }`, and its own fragment on `Query.clientPreferences`. Renders `Fieldset.Root` with `disabled={readOnly}`; carries `-pending` until its entity resolves, and `-readonly` when the session reports `canEditData: false`.
 
@@ -72,9 +79,7 @@ The definition also declares that same component as its `skeleton`, which is the
 
 ### ClientPreferencesNewsletterControl / ClientPreferencesSavePersonalDataControl
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | `'Email me with news and offers'` / `'Save my information for next time'` | |
+Content models `client-preferences-newsletter` / `client-preferences-save-data`, one ICU message field each with no package default: `label` (source `Email me with news and offers` / `Save my information for next time`).
 
 Childless, renders `Field.Root > Field.Label > Field.Checkbox` (with the checkmark icon), the label text following. Composed children replace that default anatomy and still bind to the same field. Defaults to unchecked (opt-in, not opt-out) — a `null` saved value reads as `false`.