@vtex/faststore 0.0.7 → 0.0.10

package/dist/docs/cart-item.md

@@ -39,6 +39,15 @@ 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.
 
+## Image placeholder
+
+`CartItemImage` renders the `<img>` while the line has a usable image. It renders a placeholder `span` in the same slot when:
+
+- the line has no image, or its URL is blank; or
+- the image fails to load, including a failure that happened before hydration (an image already settled with no pixels at mount is treated as failed).
+
+The placeholder carries `data-fs-cart-item-image` and `data-fs-cart-item-image-broken`, and not `data-fs-image` because it is not an image element. It takes the image's `className` and `style`, so the slot keeps its size. It is hidden from assistive technology (`aria-hidden`, no role or name), so only a loaded image is announced. It has no built-in look: style it with a swatch keyed on the hook, for example `data-[fs-cart-item-image-broken]:bg-gray-100`. The placeholder keeps the image's display (`inline-block`, set inline) so the sizing classes keep working with no extra utility; a swatch overrides it only with an important utility, and the look stays the swatch's. A failure is remembered only for the URL that failed, so a line whose URL changes tries the new one. A consumer `onError` still runs when the browser delivers the `error` event; a failure found at mount is not reported through it. A `ref` reaches the `<img>` only.
+
 ## PDP link composition
 
 `CartItemProductLink` links a line to its product page. It reads the `product.detailUrl` the core slice already carries, so it owns no fragment and placing it adds nothing to the page query. Wrap the image in it:
@@ -46,14 +55,14 @@ CartList              (iterator — renders its children once per cart line)
 ```text
 CartItemRoot
   └─ CartItemProductLink        (anchor to this line's product page)
-       └─ CartItemImage         (unchanged — its alt text names the link)
+       └─ CartItemImage         (the link names itself with aria-label; see below)
 ```
 
-**Placing it is the switch.** There is no prop to turn the link on or off: a mini-cart line composes it, a checkout line omits it. That is why `CartItemImage` on its own still renders a plain `<img>` with no anchor, exactly as before.
+**Placing it is the switch.** There is no prop to turn the link on or off: a mini-cart line composes it, a checkout line omits it. That is why `CartItemImage` on its own renders the `<img>` (or, with no usable image, the placeholder described below) and never an anchor.
 
-**It names itself from what it wraps.** The link adds no `aria-label`, so its accessible name is the image's alt text (`image.altText ?? variant.name`). On a line whose `variant.image` is `null` the leaf renders its children unwrapped instead of wrapping nothing, because an anchor with no content is a keyboard focus stop with no accessible name.
+**It names itself.** The link sets `aria-label` to the image's alt text (`image.altText ?? variant.name`, trimmed), so it keeps that name when the wrapped image is replaced by the hidden placeholder (a load error, or a blank URL). A loaded image gives the same name as before. An `aria-label` passed to the link wins over it. On a line whose `variant.image` is `null`, or whose name is blank, the leaf still renders its children unwrapped instead of wrapping nothing, because an anchor with no accessible name is a keyboard focus stop.
 
-**No usable product URL, no link.** The leaf runs `detailUrl` through `resolveSafeHref`, the same allowlist the navigation particle applies to CMS-authored destinations, and renders its children unwrapped when the destination is blank or refused: `javascript:`, `data:`, protocol-relative, or malformed. The particle gates only `$content.href`, so a platform URL arriving on the `href` prop is this leaf's to validate. Either way the image still shows: the leaf never self-hides, unlike the data-bearing leaves below, because hiding a wrapper would take its content with it. A refusal logs its reason and never the value; a blank URL is ordinary and stays quiet.
+**No usable product URL, no link.** The leaf runs `detailUrl` through `resolveSafeHref`, the same allowlist the navigation particle applies to CMS-authored destinations, and renders its children unwrapped when the destination is blank or refused: `javascript:`, `data:`, protocol-relative, or malformed. A safe `detailUrl` is a logical path: `NavigationLink` prefixes it for the current binding. The particle gates only `$content.href`, so a platform URL arriving on the `href` prop is this leaf's to validate. Either way the image still shows: the leaf never self-hides, unlike the data-bearing leaves below, because hiding a wrapper would take its content with it. A refusal logs its reason and never the value and still renders the children unwrapped; a blank URL is ordinary and stays quiet.
 
 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.
 
@@ -76,6 +85,15 @@ CartItemRoot
 
 For the cart-level counterparts (the "N items unavailable" summary and the bulk "remove all unavailable" button), see `cart.md` — Unavailable-item recovery.
 
+## Removal feedback
+
+`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.
+- **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
 
 A promotion can add a line the shopper never chose. `CartItem.gift` marks it, and three things follow from that one flag — none of them requiring a different template, because `CartList` renders the same children for every row:

package/dist/docs/cart-totalizer.md

@@ -49,7 +49,7 @@ CartTotalizerRoot          ← reactive data provider (totalizers + total)
 | Component | Props | Notes |
 |---|---|---|
 | `CartTotalizerRoot` | `$data` | Provides `CartTotalizerContext` and `CartTotalValueContext`; lines format from the active storefront context |
-| `CartTotalizerLine` | `totalizerId`, `label?`, `variant?`, `zeroLabel?` | `variant="discount"` auto-hides when `amount === 0` |
+| `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 |
 | `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") |

package/dist/docs/cart.md

@@ -5,7 +5,7 @@
 
 Cart **writes** (add / remove / quantity) no longer flow through `CartRoot`. A component declares the cart methods it needs as an `actions: { cart: [...] }` selector on its definition and dispatches through the compiler-injected `$actions.cart.*` prop — the write-side mirror of `fragment` → `$data`. Cart writes are **context-free**: an add-to-cart button works on a PDP, a product card, a search result, or the header with **no `CartRoot` ancestor** (docs/storefront-core/reference-free-particle-model.md § Write side — actions, ADR-0010).
 
-This doc covers `CartRoot` — hosted in the layout, never emitted in page schemas — plus the **mini-cart footer checkout CTA** ([below](#mini-cart-footer-checkout-cta)), the composition of `CartCheckoutGuard` → (`CartTotal` + `CartGoCheckout`). The remaining cart line-item and summary particles (`CartList`, `CartItem*`, `CartCount`, `CartError`) exist in the catalog and will be documented when the full cart page enters scope.
+This doc covers `CartRoot` — hosted in the layout, never emitted in page schemas — plus the **mini-cart footer checkout CTA** ([below](#mini-cart-footer-checkout-cta)), the composition of `CartCheckoutGuard` → (`CartTotal` + `CartGoCheckout`). The remaining cart line-item and summary particles (`CartList`, `CartItem*`, `CartError`) exist in the catalog and will be documented when the full cart page enters scope. `CartCount` is documented in [Item count](#item-count).
 
 ---
 
@@ -61,11 +61,11 @@ Cart **write** consumers (`BuyButtonButton`, `ProductCardAddToCart`, `CartItemQu
 
 ## Post-add behavior (open the mini-cart vs. redirect to checkout)
 
-What happens after a successful add to cart is a **per-store choice made by composition**, not a config flag. The store composes exactly one of two behavior components — there is no `global.json` switch deciding it.
+What happens after a successful add to cart is a **per-store choice made by composition**, not a config flag. The store composes exactly one of two behavior components — there is no foundation switch deciding it.
 
 - **Mini-cart store → `CartOpenOnAdd`.** When the store has a mini-cart drawer, compose `CartOpenOnAdd` as the **parent of the mini-cart `DrawerRoot`** (its single child). It opens the drawer automatically on each successful add, with the new item visible and the count updated. It controls the drawer internally, so **do not set raw `open` / `onOpenChange` on `DrawerRoot`** — those are not authorable props, and the header `DrawerTrigger` plus manual close (Escape / backdrop / close button) keep working through the encapsulated wiring.
 
-- **No-mini-cart store → `CartRedirectOnAdd`.** When the store has **no** mini-cart and adding a product should send the shopper straight to checkout, compose `CartRedirectOnAdd` (and omit the drawer entirely). It navigates to `href` (default `/checkout`) after each successful add. It renders no UI of its own; place it once in the layout.
+- **No-mini-cart store → `CartRedirectOnAdd`.** When the store has **no** mini-cart and adding a product should send the shopper straight to checkout, compose `CartRedirectOnAdd` (and omit the drawer entirely). It navigates to `href` (default the checkout page, `{ "standard": "checkout" }`) after each successful add. It renders no UI of its own; place it once in the layout.
 
 The two are **mutually exclusive — compose exactly one**. A store with a mini-cart uses `CartOpenOnAdd` and never `CartRedirectOnAdd`; a store without one uses `CartRedirectOnAdd` and omits the drawer. Both react only to a **successful** add (a failed add or one returning user errors triggers neither).
 
@@ -87,7 +87,7 @@ CartRoot (layout)
 ```
 CartRoot (layout)
 ├── Header (add-to-cart CTAs elsewhere; no drawer)
-└── CartRedirectOnAdd          ← navigates to /checkout on a successful add
+└── CartRedirectOnAdd          ← navigates to the checkout page on a successful add
 ```
 
 ---
@@ -145,22 +145,28 @@ It is the drawer's own close control, so it **requires a `DrawerRoot` ancestor**
 
 ## Coupon
 
-Four root-agnostic components wire up the cart coupon flow — apply a code, list the applied coupons, remove one, and surface apply/remove errors. They read `useCart()` (for the applied list) and dispatch through `$actions.cart.applyCoupon` / `$actions.cart.removeCoupon`, so they compose anywhere inside a `CartRoot` subtree. In a mini-cart they sit in the `DrawerPopup` footer, above the totals.
+Six root-agnostic components wire up the cart coupon flow — apply a code, list the applied coupons, remove one, surface apply/remove errors, gate the entry on a single-coupon store, and tell the shopper when an applied coupon is not being applied. They read `useCart()` (for the applied list) and dispatch through `$actions.cart.applyCoupon` / `$actions.cart.removeCoupon`, so they compose anywhere inside a `CartRoot` subtree. In a mini-cart they sit in the `DrawerPopup` footer, above the totals.
 
 The applied coupons are a **list of chips (1..N)**, not a single-coupon slot — forward-compatible with multi-coupon stores. The server recomputes totals on every apply/remove and returns the updated cart, so `CartTotal` and the totalizer rows update automatically; no optimistic state is used.
 
 | 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. |
-| `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). |
+| `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`. |
 | `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. |
+| `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`. |
 
-`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).
+`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`. On a single-coupon store, a rejected second code surfaces here as a normal apply error.
+**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:
 
-**Styling split:** these components own behaviour and the `data-fs-*` hooks (`data-fs-cart-coupon-form`, `-input`, `-apply`, `-pending`, `data-fs-cart-applied-coupons`, `data-fs-cart-coupon`, `-code`, `-unmatched`, `data-fs-cart-coupon-remove`, `data-fs-cart-coupon-error`). Chip and X **visuals (swatch values) are authored by the styling pipeline**, not these components.
+- 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).
+
+**Styling split:** these components own behaviour and the `data-fs-*` hooks (`data-fs-cart-coupon-form`, `-input`, `-apply`, `-pending`, `data-fs-cart-applied-coupons`, `data-fs-cart-coupon`, `-code`, `-unmatched`, `data-fs-cart-coupon-remove`, `data-fs-cart-coupon-unmatched-notice`, `data-fs-cart-coupon-savings`, `data-fs-cart-coupon-error`, `data-fs-cart-coupon-empty`). Chip and X **visuals (swatch values) are authored by the styling pipeline**, not these components.
 
 Coupon block inside a mini-cart `DrawerPopup` footer, at the top of the footer above the totals and checkout CTA (the footer lives inside the `CartFilled` branch — coupons only matter for a non-empty cart):
 
@@ -168,13 +174,66 @@ Coupon block inside a mini-cart `DrawerPopup` footer, at the top of the footer a
 {
   "popup-footer": { "type": "Container", "children": ["coupon-block", "footer-summary", "checkout-cta", "footer-keep-shopping"] },
   "coupon-block": { "type": "Container", "children": ["coupon-form", "applied-coupons", "coupon-error"] },
-  "coupon-form": { "type": "CartCouponForm", "props": { "placeholder": "Coupon code", "applyLabel": "Apply" } },
+  "coupon-form": { "type": "CartCouponForm", "props": { "placeholder": "Coupon code", "applyLabel": "Apply", "appliedMessage": "Coupon applied" } },
+  "applied-coupons": { "type": "CartAppliedCoupons", "children": ["coupon-remove"] },
+  "coupon-remove": { "type": "CartCouponRemove" },
+  "coupon-error": { "type": "CartCouponError" }
+}
+```
+
+### Single- and multi-coupon entry
+
+Whether a store accepts one coupon or several is expressed by composition, with no flag. For a single-coupon store, wrap the collapsed entry (the accordion holding `CartCouponForm`) in `CartCouponEmpty`: the trigger and form disappear as soon as a code is applied and come back, collapsed, when the chip is removed. For a multi-coupon store, leave the gate out so the entry stays available for more codes, each shown as its own chip. `CartAppliedCoupons` and `CartCouponError` sit outside the gate in both compositions, so the chips and errors stay visible.
+
+Single-coupon:
+
+```json
+{
+  "coupon-section": { "type": "Container", "children": ["coupon-entry-gate", "applied-coupons", "coupon-error"] },
+  "coupon-entry-gate": { "type": "CartCouponEmpty", "children": ["coupon-accordion"] },
+  "coupon-accordion": { "type": "AccordionRoot", "children": ["coupon-accordion-item"] },
+  "applied-coupons": { "type": "CartAppliedCoupons", "children": ["coupon-remove"] },
+  "coupon-remove": { "type": "CartCouponRemove" },
+  "coupon-error": { "type": "CartCouponError" }
+}
+```
+
+Chip template with the saved amount and the unmatched-coupon notice (compose `CartCouponRemove` too, since composed children replace the built-in remove):
+
+```json
+{
+  "applied-coupons": { "type": "CartAppliedCoupons", "children": ["coupon-savings", "coupon-remove", "coupon-unmatched"] },
+  "coupon-savings": { "type": "CartCouponSavings", "props": { "template": "Economia de {amount}" } },
+  "coupon-remove": { "type": "CartCouponRemove", "props": { "children": "×" } },
+  "coupon-unmatched": { "type": "CartCouponUnmatched", "props": { "message": "Este cupom não está sendo aplicado" } }
+}
+```
+
+Multi-coupon (no gate):
+
+```json
+{
+  "coupon-section": { "type": "Container", "children": ["coupon-accordion", "applied-coupons", "coupon-error"] },
+  "coupon-accordion": { "type": "AccordionRoot", "children": ["coupon-accordion-item"] },
   "applied-coupons": { "type": "CartAppliedCoupons", "children": ["coupon-remove"] },
   "coupon-remove": { "type": "CartCouponRemove" },
   "coupon-error": { "type": "CartCouponError" }
 }
 ```
 
+`coupon-accordion-item` is the usual `AccordionItem > AccordionHeader > AccordionTrigger` plus `AccordionPanel > CartCouponForm`:
+
+```json
+{
+  "coupon-accordion-item": { "type": "AccordionItem", "props": { "value": "coupon" }, "children": ["coupon-accordion-header", "coupon-accordion-panel"] },
+  "coupon-accordion-header": { "type": "AccordionHeader", "children": ["coupon-accordion-trigger"] },
+  "coupon-accordion-trigger": { "type": "AccordionTrigger", "children": ["coupon-accordion-trigger-label"] },
+  "coupon-accordion-trigger-label": { "type": "Text", "props": { "as": "span", "children": "Have a coupon?" } },
+  "coupon-accordion-panel": { "type": "AccordionPanel", "children": ["coupon-form"] },
+  "coupon-form": { "type": "CartCouponForm" }
+}
+```
+
 ---
 
 ## Canonical schema example
@@ -230,7 +289,7 @@ Neither leaf renders a wrapper or carries spacing, so **order, grouping, and any
 Continue-shopping is a **non-mutating** control, not a cart action. Which control depends on the surface:
 
 - **Inside the mini-cart drawer**, use `CartContinueShopping` — it closes the drawer through the drawer's own contract and dispatches no cart write.
-- **On a cart or checkout page** (no drawer to close), use a storefront `NavigationLink` (e.g. `href="/"`) back to browsing. Do **not** place `CartContinueShopping` there: it is a drawer close, and without a `DrawerRoot` ancestor the render fails.
+- **On a cart or checkout page** (no drawer to close), use a storefront `NavigationLink` (e.g. `href={{ page: 'home' }}`) back to browsing. Do **not** place `CartContinueShopping` there: it is a drawer close, and without a `DrawerRoot` ancestor the render fails.
 
 ```text
 CartRoot (layout)
@@ -259,7 +318,7 @@ CartRoot (layout)
   "popup-body": { "type": "CartList", "children": ["cart-item-template"] },
   "subtotal-row": { "type": "CartTotal", "props": { "label": "subtotal" } },
   "total-row": { "type": "CartTotal", "props": { "label": "total" } },
-  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": "/checkout", "children": "continuar" } },
+  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": { "standard": "checkout" }, "children": "continuar" } },
 
   "cart-empty": { "type": "CartEmpty", "children": ["empty-illustration", "empty-msg", "empty-footer"] },
   "empty-illustration": { "type": "Icon", "props": { "name": "shopping-bag" } },
@@ -275,7 +334,7 @@ On a cart/checkout page there is no drawer to close, so the empty branch keeps `
 {
   "cart-empty": { "type": "CartEmpty", "children": ["empty-msg", "keep-shopping-link"] },
   "empty-msg": { "type": "CartEmptyMessage", "props": { "text": "sua cesta está vazia" } },
-  "keep-shopping-link": { "type": "NavigationLink", "props": { "href": "/", "children": "continuar comprando" } }
+  "keep-shopping-link": { "type": "NavigationLink", "props": { "href": { "page": "home" }, "children": "continuar comprando" } }
 }
 ```
 
@@ -307,7 +366,7 @@ 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` `/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.
 
 **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.
 
@@ -315,7 +374,7 @@ The mini-cart drawer (the layout composition described on `CartRoot`) ends in a
 
 | Prop | Type | Required | Notes |
 |-------|------|----------|-------|
-| `href` | string | no | Checkout destination, default `/checkout`. Never content-editable |
+| `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 |
 
@@ -332,7 +391,7 @@ Schema shape (inside the `DrawerPopup` footer `Container`):
   "popup-footer": { "type": "Container", "children": ["checkout-cta"] },
   "checkout-cta": { "type": "CartCheckoutGuard", "children": ["checkout-total", "checkout-btn"] },
   "checkout-total": { "type": "CartTotal", "props": { "label": "Total" } },
-  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": "/checkout", "label": "Finalizar compra" } }
+  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": { "standard": "checkout" }, "label": "Finalizar compra" } }
 }
 ```
 
@@ -342,11 +401,34 @@ Everything stays a layout composition: the guard, total, and link are independen
 
 ---
 
+## Item count
+
+`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).
+- 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.
+
+```json
+{
+  "cart-title-count": {
+    "type": "CartCount",
+    "props": { "template": "{count} itens", "templateOne": "{count} item" }
+  }
+}
+```
+
+Only the first `{count}` in a template is replaced.
+
+---
+
 ## Unavailable-item recovery
 
 `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). **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`.
+- **`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).
 - **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).
 
@@ -365,6 +447,31 @@ Schema shape (mini-cart footer, above the checkout CTA):
 
 ---
 
+## 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`.
+
+- **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.
+- **Optimistic.** `removeItems` writes an optimistic cart, so `CartEmpty` replaces `CartFilled` as soon as the button is clicked, before the server answers. The button itself unmounts at that point when it sits inside `CartFilled`.
+- **Failures go through `CartError`.** When the call fails, Apollo drops the optimistic layer, the lines come back, and the failure is published to the same `cartUserErrorsVar` that `CartError` shows. The button owns no rollback and raises no toast. `cartUserErrorsVar` is cleared when an item write starts (coupon writes and `validate` leave it alone) and when a CartRoot mounts, never on re-render, so an error from a write on another page does not show on the Cart page. Two cases stay, listed below. A rejection (no cart cached yet) is logged by error name and re-enables the button. Compose a `CartError` outside the `CartFilled` / `CartEmpty` branches so the message is visible after the lines return.
+  - A write still in flight when a CartRoot mounts shows its failure after the clear, for example an item write from a product page (known limitation).
+  - An error from the Cart page stays visible in a persistent `CartError` after the shopper leaves (known limitation).
+
+Schema shape (Cart page):
+
+```json
+{
+  "page-shell": { "type": "Container", "children": ["page-heading", "cart-error", "page-body", "cart-loading", "cart-empty"] },
+  "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" } }
+}
+```
+
+---
+
 ## Merchant alert banner
 
 `CartAlertRoot` + `CartAlertIcon` + `CartAlertText` carry the **merchant's own** message inside the overlay — a minimum order, a running promotion, a policy note. The copy is CMS-editable, so changing it needs no schema edit and no deploy.
@@ -421,7 +528,7 @@ The message, as `<span data-fs-cart-alert-text data-fs-text>`. Copy comes from t
 
 ### The `icons.include` obligation
 
-`Icon` resolves names against a **compile-time** sprite with no runtime fallback. An `icon` **prop** is a literal the compiler can see, so it is collected automatically. A **CMS-chosen** name does not exist at build time, so a store whose merchants pick the icon must register the admitted names in `global.json`:
+`Icon` resolves names against a **compile-time** sprite with no runtime fallback. An `icon` **prop** is a literal the compiler can see, so it is collected automatically. A **CMS-chosen** name does not exist at build time, so a store whose merchants pick the icon must register the admitted names in `foundation.json`:
 
 ```json
 { "icons": { "include": ["bell", "bell-ringing", "tag", "shopping-cart", "map-pin", "star"] } }

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

@@ -1,7 +1,7 @@
 # ClientProfileFieldset
 
 **Category:** identity
-**Purpose:** The composable, one-Save write of the `ClientProfile` entity. Registers itself with the enclosing `FormRoot` under the `clientProfile` namespace and dispatches at most one `identity.clientProfileUpdate` when the shopper presses that form's submit. Four bound controls — first name, last name, phone, document — compose freely inside it, in any order or subset.
+**Purpose:** The composable, one-Save write of the `ClientProfile` entity. Registers itself with the enclosing `FormRoot` under the `clientProfile` namespace and dispatches at most one `identity.clientProfileUpdate` when the shopper presses that form's submit. Four bound controls — first name, last name, phone, document (CPF, SSN, SIN or RFC) — compose freely inside it, in any order or subset.
 
 ---
 
@@ -65,7 +65,7 @@ SessionRoot                              (required ancestor; session tri-state +
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `country` | `'US' \| 'BR'` | `'US'` | Phone mask/validation country, provided to the phone control via context. |
-| `documentType` | string | — | e.g. `'CPF'`. The document control renders only when supported. |
+| `documentType` | string | — | One of `'CPF'`, `'SSN'`, `'SIN'` or `'RFC'` (upper case). The document control renders only when supported, and the payload carries `document` only for a supported type. |
 | `skeletonCount` | number | `4` | Placeholder rows drawn while the profile resolves. Set it to the number of controls composed. |
 | `loadingLabel` | string | `'Loading your details'` | Announced politely while the profile resolves. Blank means no announcement. |
 | `loadedLabel` | string | `'Your details are ready'` | Announced politely once the controls mount. Blank means no announcement. |
@@ -105,12 +105,14 @@ governs visibility (see *Switching the phone field off* below).
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | `'CPF'` | |
+| `label` | string | the document type's name (`'CPF'`, `'SSN'`, `'SIN'` or `'RFC'`) | |
 | `placeholder` | string | — | |
 | `errorMessage` | string | — | |
 
-Renders nothing, and registers no field name, when the fieldset's `documentType` is unsupported. Composes
-the `DocumentField` particle. Recomposable (RFC:503): given children, they replace `DocumentField`'s
+Renders nothing, and registers no field name, when the fieldset's `documentType` is unsupported. The mask,
+the validation and the `autocomplete` hint (`off` for SSN and SIN) come from the document type; the saved
+`document` string is the type's sanitised value (digits for CPF, SSN and SIN, letters kept for RFC), the
+same string the card form sends. Composes the `DocumentField` particle. Recomposable (RFC:503): given children, they replace `DocumentField`'s
 default `Field.Label` + `DocumentFieldInput` + `Field.Error` anatomy, in any order; childless keeps
 today's order and text.
 

package/dist/docs/copy-text.md

@@ -0,0 +1,84 @@
+# CopyText
+
+**Category:** action
+**Purpose:** Copies one string the caller supplies and confirms the result inline.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A small action beside an identifier, with a short confirmation that appears after the action and can be dismissed. The image is the source of truth for layout.
+
+## When to use
+
+Any screen that needs one action to copy a single string, such as an order number.
+
+## When NOT to use
+
+- Rendering the identifier itself. Pass the string in; do not ask `CopyText` to display the heading.
+- A toast or a page-level notification. The confirmation stays with the action.
+
+---
+
+## Composition
+
+```
+CopyText
+```
+
+`CopyText` is one element. The caller passes the visible label or icon as `children`.
+
+## Components
+
+### CopyText
+
+| Prop | Type | Default | Purpose |
+|---|---|---|---|
+| `accessibleName` | string | `Copy` | Accessible name of the action |
+| `successMessage` | string | `Copied` | Announced after a successful copy |
+| `failureMessage` | string | `Could not copy` | Announced when the clipboard rejects the write |
+| `dismissLabel` | string | `Dismiss` | Accessible name of the dismiss control |
+
+`text` is required and is not a schema prop. The caller supplies the exact string to copy. `children` is the visible label or icon, and it is not a schema prop either.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "copy-identifier": {
+    "type": "CopyText",
+    "props": {
+      "accessibleName": "Copy order number",
+      "successMessage": "Copied",
+      "failureMessage": "Could not copy",
+      "dismissLabel": "Dismiss"
+    },
+    "children": []
+  }
+}
+```
+
+The screen that owns the identifier passes `text` and `children` at runtime. Do not author the identifier in the page.
+
+## Common mistakes
+
+- **OrderDetailsHeader** renders the number. `CopyText` only copies the string it is given.
+- Passing the heading, including a prefix such as "Order #", copies that whole string. Pass the identifier alone.
+
+---
+
+## Styling
+
+| Component | What to style | Plausible classes |
+|---|---|---|
+| `CopyText` | The action and the inline confirmation | `inline-flex items-center gap-[8px] text-[14px]` |
+
+Style the hooks `data-fs-copy-text`, `data-fs-copy-text-action`, `data-fs-copy-text-message`, and `data-fs-copy-text-outcome`. The component ships no CSS.
+
+---
+
+## Related
+
+- [[button]] — the action primitive this control composes.

package/dist/docs/document-field.md

@@ -1,14 +1,14 @@
 # DocumentField
 
 **Category:** content
-**Purpose:** A presentational tax-document input that composes the `Field` particle (label + native `<input>` + inline error). It applies a locale-specific mask on every change (e.g. CPF `###.###.###-##`) and runs check-digit validation on blur/submit. It is data-agnostic — value flows through props; it consumes no GraphQL and no domain context.
+**Purpose:** A presentational tax-document input that composes the `Field` particle (label + native `<input>` + inline error). It applies the mask of its document type on every change (CPF `###.###.###-##`, SSN `###-##-####`, SIN `###-###-###`, or RFC, thirteen upper-case letters and digits) and runs that type's validation on blur/submit. It is data-agnostic — value flows through props; it consumes no GraphQL and no domain context.
 
 ---
 
 ## Visual cues (how to identify in an image)
 
-- A single-line text input labelled **"CPF"** (or another tax-document name), usually on a checkout identification step, near the email/phone fields.
-- Shows a masked placeholder like `000.000.000-00` and formats digits as they are typed.
+- A single-line text input labelled **"CPF"**, **"SSN"**, **"SIN"** or **"RFC"** (or another tax-document name), usually on a checkout identification step, near the email/phone fields.
+- Shows a masked placeholder like `000.000.000-00` (CPF), `000-00-0000` (SSN), `000-000-000` (SIN) or `AAAA000000AAA` (RFC) and formats characters as they are typed.
 - When invalid, an inline error below the input (e.g. *"Enter a valid CPF."*).
 
 If the image shows a checkout identification step with a tax-document field, use `DocumentField`.
@@ -61,15 +61,15 @@ react-hook-form and loses the mask — unsupported, the RFC's named double-binde
 | `label` | string | — | Accessible label. |
 | `placeholder` | string | — | Input placeholder. |
 | `disabled` | boolean | `false` | Disables the input (e.g. while a write is in flight). |
-| `requirement` | `'mandatory' \| 'optional'` | — | Raises the field to required, announced as `aria-required` (never the native attribute). Unset is no opinion, which is what keeps CPF Optional by Recommendation, unlike email. Bound to a fieldset whose rule already says required, `'optional'` does not lower it. |
+| `requirement` | `'mandatory' \| 'optional'` | — | Raises the field to required, announced as `aria-required` (never the native attribute). Unset is no opinion, which is what keeps the document Optional by Recommendation, unlike email. Bound to a fieldset whose rule already says required, `'optional'` does not lower it. |
 | `name` | string | `'document'` | Field/input name. |
-| `documentType` | `'CPF'` | `'CPF'` | Selects the mask + validator + digit-only input mode. |
+| `documentType` | `'CPF' \| 'SSN' \| 'SIN' \| 'RFC'` | `'CPF'` | Selects the mask, sanitiser, validator, digit-only input mode and `autocomplete`. `DOCUMENTS` holds one entry per type; the API's lower-case ids (`cpf`, `ssn`, `sin`, `rfc`) go through `documentTypeFromId`. |
 | `ref` | `Ref<HTMLInputElement>` | — | Lands on the `<input>` `Field.Control` renders — **not on the wrapper `<div>`, as it did before** (a deliberate, source-breaking change). Composed with react-hook-form's own ref on the bound path — a caller ref and react-hook-form's ref are both honoured. |
 | `children` | `ReactNode` | — | Given, replaces the default `Field.Label` + `DocumentFieldInput` + `Field.Error` anatomy, in any order (RFC:503). |
 
-**Masking:** applied progressively on every change; input is never blocked. Digit-only masks (CPF) strip non-digits and hint `inputMode="numeric"`.
+**Masking:** applied progressively on every change; input is never blocked. The type's sanitiser runs first: digit-only types (CPF, SSN, SIN) strip non-digits and hint `inputMode="numeric"`; RFC upper-cases and keeps only `A-Z` and `0-9`, and carries no `inputMode`. SSN and SIN inputs carry `autocomplete="off"` so the browser does not offer the number back; CPF and RFC carry no `autocomplete` attribute. The attribute is a request, not a guarantee.
 
-**Validation:** the check digit is checked on blur/submit only — never per keystroke. An **empty** value is valid (the field is optional). A prior error clears while the shopper edits and is re-evaluated on the next blur.
+**Validation:** the type's rule (CPF check digits; SSN area, group and serial ranges; SIN Luhn check; RFC structure with a plausible month and day) is checked on blur/submit only — never per keystroke. An **empty** value is valid (the field is optional). A prior error clears while the shopper edits and is re-evaluated on the next blur.
 
 ---
 
@@ -82,7 +82,7 @@ runs the plain, unbound behaviour documented above, unaltered.
 - **What the contract supplies**: `label` and `placeholder`, when the particle's own prop is omitted (an
   explicit prop always wins); `defaultValue`, seeded into `useController`; and `rule`, merged with the
   particle's own check-digit validator (below).
-- **What stays the particle's**: the CPF mask, `documentType`, and the `errorMessage` copy.
+- **What stays the particle's**: the mask of the `documentType`, the `documentType` itself, and the `errorMessage` copy.
 - **Single binder, real contract for the read-only parts (RFC:503)**: the composite remains the sole
   binder for its field — `useController` is called once, here. Its default (and a recomposed) anatomy's
   input is `DocumentFieldInput`, which renders the raw Base UI `Field.Control` directly rather than this

package/dist/docs/footer-link-group.md

@@ -58,7 +58,7 @@ It renders **both responsive forms at once**, each under its own hook: an accord
 | Prop | Type | Required | Notes |
 |-------|------|----------|-------|
 | `heading` | string | no | Authored fallback. Ignored when a CMS entry supplies a heading |
-| `links` | array | no | Authored fallback list of `{ label, href, target? }`. Ignored when a CMS entry supplies `links` |
+| `links` | array | no | Authored fallback list of `{ label, href, target? }`. An item `href` may be a page reference or a logical path. Ignored when a CMS entry supplies `links` |
 
 Content model (`footer-link-group`) fields, edited in the CMS:
 
@@ -67,7 +67,7 @@ Content model (`footer-link-group`) fields, edited in the CMS:
 | `heading` | string | no | The group heading and the accordion trigger's accessible name. Optional so a links-only entry falls back to the authored heading instead of omitting the group. A group with no heading resolved from either channel renders nothing |
 | `links` | array | no | Ordered links. Reordering here reorders the rendered list with no deployment. Optional so a heading-only entry falls back to the authored list instead of omitting the group |
 | `links[].label` | string | yes | Link text. A blank label drops that link — an anchor with no name is unusable |
-| `links[].href` | string | yes | Destination. `http:`, `https:`, `mailto:`, `tel:`, or a path starting with a single `/` |
+| `links[].href` | string | yes | A `uri-reference` string: `http:`, `https:`, `mailto:`, `tel:`, or a path starting with a single `/`. The binding prefix is applied at render |
 | `links[].target` | `_self` \| `_blank` | no | `_blank` opens a new tab and adds `rel="noopener noreferrer"` automatically |
 
 ---

package/dist/docs/footer-social.md

@@ -52,7 +52,7 @@ FooterRoot
 
 **A destination the allowlist refuses renders as text.** Every `url` passes through the shared render-time check, which admits `http:`, `https:`, `mailto:`, `tel:`, and site-relative paths. A refused one — a `javascript:` value, a protocol-relative `//host`, or a URL not yet pasted — renders the profile's label as visible text with no link and no glyph, rather than a mark that looks clickable and goes nowhere. The rejection logs once with the entry index and a bounded reason.
 
-**Every predefined name must be registered.** A `platform` resolves to a sprite symbol the store's build has to include; the store's `global.json` writes the names out under `icons.include` — it is JSON, so it cannot import `SOCIAL_PLATFORM_NAMES`, and a test that derives the expected set from the exported constant is what keeps the two in step. A name the store never registered renders an empty `<svg>` — no build error and no runtime error, just a missing mark. `linkedin` and `youtube` need provisioned icon data as well: unlike the other three they have no embedded fallback, so a store that registers them without running `sukima icon-data fetch` fails to build.
+**Every predefined name must be registered.** A `platform` resolves to a sprite symbol the store's build has to include; the store's `foundation.json` writes the names out under `icons.include` — it is JSON, so it cannot import `SOCIAL_PLATFORM_NAMES`, and a test that derives the expected set from the exported constant is what keeps the two in step. A name the store never registered renders an empty `<svg>` — no build error and no runtime error, just a missing mark. `linkedin` and `youtube` need provisioned icon data as well: unlike the other three they have no embedded fallback, so a store that registers them without running `sukima icon-data fetch` fails to build.
 
 ---
 

package/dist/docs/free-shipping-progress.md

@@ -1,7 +1,7 @@
 # FreeShippingProgress
 
 **Category:** commerce
-**Purpose:** Reactive progress bar for the cart's nearest free-shipping goal. Reads `cart.freeShippingProgress` and the reactive `cart.total`, then renders one of three states: below-threshold ("faltam {value} para frete grátis" + a partially filled bar), earned ("você ganhou frete grátis!" + a full bar), or absent (renders nothing). Composed at the **top of a cart / mini-cart drawer** to nudge the shopper to add a bit more.
+**Purpose:** Reactive progress bar for the cart's nearest free-shipping goal. Reads `cart.freeShippingProgress` and the cart's `Items` totalizer (the amount the server measures, so shipping and discounts do not count), then renders one of three states: below-threshold ("faltam {value} para frete grátis" + a partially filled bar), earned ("você ganhou frete grátis!" + a full bar), or absent (renders nothing). Composed at the **top of a cart / mini-cart drawer** to nudge the shopper to add a bit more.
 
 ---
 
@@ -18,19 +18,23 @@ Look for a **strip at the top of an open cart or mini-cart** with a horizontal p
 
 | State | Condition | Renders |
 |---|---|---|
-| Below threshold | `qualified === false`, cart total below `threshold` | Below-threshold message + a bar filled to `cartTotal / threshold` |
-| Earned | field `qualified === true`, OR the reactive cart total reaches `threshold` | Earned message + a full bar |
+| Below threshold | `qualified === false`, `Items` amount below `threshold` | Below-threshold message + a bar filled to `items / threshold` |
+| Earned | field `qualified === true`, OR the reactive `Items` amount reaches `threshold` | Earned message + a full bar |
 | Absent (self-hide) | `cart.freeShippingProgress === null` (no destination, no eligible promotion, empty cart, still loading, or degraded) | **Nothing** — no bar, no message, no wrapper |
 
 ## Reactive fill (no extra calls)
 
-`freeShippingProgress` is a lazy field kept out of `CartFragment`, so its cached value (`threshold`, `qualified`) does not refresh on cart mutations. The bar therefore derives the **live** fill and remaining from the reactive `cart.total` — which *is* fresh via cache-write propagation — against the fetched `threshold`:
+`freeShippingProgress` is kept out of `CartFragment`, so only some writes select it: the four line writes (remove, remove several, increase, decrease), the coupon removal and the shipping address update. Each returns the field and the bar takes the server's answer: below the goal it shows the amount still missing, and it comes back to qualified when a later write meets the goal again. The cart's `Items` totalizer is reactive too (the optimistic builders adjust it), so between a write's optimistic prediction and the server's answer the bar derives the **live** fill and remaining from the `Items` amount against the cached `threshold`. The server compares the same `Items` amount, so shipping charges and discounts never move the bar:
 
-- `isQualified = qualified || (threshold != null && cartTotal >= threshold)` — the field flag covers the already-earned case (where `threshold` is `null`); the reactive comparison flips it at the boundary between page loads.
-- `liveRemaining = isQualified ? 0 : max(threshold − cartTotal, 0)`
-- `fill = isQualified ? 1 : clamp(cartTotal / threshold, 0..1)`
+- `isQualified = qualified || (threshold != null && items >= threshold)` — the field flag covers the already-earned case (where `threshold` is `null`); the reactive comparison flips it at the boundary.
+- `liveRemaining = isQualified ? 0 : max(threshold − items, 0)`
+- `fill = isQualified ? 1 : clamp(items / threshold, 0..1)`
 
-The bar updates instantly on every add/remove with **no** refetch of `freeShippingProgress`. `threshold` refreshes only on a full page re-sync. `Money.amount` is a string at runtime and is always `Number()`-coerced before math/formatting.
+When the cart has no usable `Items` amount (no `Items` totalizer, or a blank or non-numeric amount), the bar shows the server's own answer instead: `isQualified = qualified`, `liveRemaining = max(remaining, 0)` from `freeShippingProgress.remaining`, and `fill = (threshold − liveRemaining) / threshold`.
+
+While a line write that lowers the items total of a qualified cart is pending, the bar hides: a qualified value has no threshold, so the client cannot tell whether the drop crosses the goal. It returns with the server's answer, and also when the write fails. An emptied cart renders nothing.
+
+`addItem`, coupon apply, validate, shipping option select, the region postal code and the cart shipping calculator do not select the field, so they do not refresh it: after one of those the bar keeps the value of the last write that returned it (or of the page load) and derives its state from the `Items` amount. A line write costs no extra read, because the server reuses the order form the write returned; a coupon removal costs one order-form read upstream when the cart has items and a postal code; the shipping address update costs none, because the server reuses the order form it just refreshed. There is no client refetch. `Money.amount` is a string at runtime and is always `Number()`-coerced before math/formatting.
 
 ---
 
@@ -58,7 +62,7 @@ FreeShippingProgressRoot        ← reactive provider; self-hides on null/loadin
 
 | Component | Props | Notes |
 |---|---|---|
-| `FreeShippingProgressRoot` | `$data` | Provides `FreeShippingProgressContext`; the copy formats from the active storefront context; renders nothing when the field is `null` |
+| `FreeShippingProgressRoot` | `threshold?`, `remaining?`, `qualified?`, `itemsTotal?`, `$data` | Provides `FreeShippingProgressContext`; the copy formats from the active storefront context; renders nothing when the field is `null` |
 | `FreeShippingProgressMessage` | `label?`, `qualifiedLabel?` | `label` is a `{value}`-token template (default `"faltam {value} para frete grátis"`); `qualifiedLabel` default `"você ganhou frete grátis!"`; `children` overrides the text |
 | `FreeShippingProgressBar` | — | Renders a `Meter` bar; `aria-valuetext` mirrors the visible copy |