@vtex/faststore 0.0.8 → 0.0.10

package/dist/docs/cart-destination.md

@@ -0,0 +1,238 @@
+# CartDestination
+
+**Category:** content
+**Purpose:** The Cart page's delivery location. `CartDestinationRoot` reads where the cart is delivered and writes a new destination from a postal code alone, so the free-shipping bar beside it follows. It has two modes: read ("Entregando em 01310-100 · São Paulo, SP" plus a change link) and edit (a postal code field with "Atualizar" and "Cancelar").
+
+---
+
+## Visual cues (how to identify in an image)
+
+Look in the **top of the cart page's main column**, above the free-shipping bar and the line items:
+
+- A single line reading **"Entregando em"** (or "Delivering to") followed by a **postal code and city, state**, beside a link such as **"Trocar localização?"**.
+- With no destination yet, the line reads a prompt such as **"Informe seu CEP"** beside the same link.
+- Pressing the link swaps the line for **one masked postal code field**, an **"Atualizar"** button, a **"Cancelar"** button and a short help line.
+
+The image is the source of truth for layout.
+
+A postal code control in the **site header** is not this component: that is `RegionRoot`.
+
+---
+
+## When to use
+
+- On the **Cart page**, once, where the design shows where the cart is delivered and lets the shopper change it.
+
+## When NOT to use
+
+- **In the header** — that is `Region`, which only sets a cookie and never touches the cart.
+- **For the full delivery address on checkout** — that is `ShippingAddressFieldset`.
+- **For a shipping-cost quote on a product page or in the cart drawer** — that is `ShippingSimulator`; it quotes and writes nothing.
+- More than once per page: two roots mean two drafts over the same destination.
+
+---
+
+## Composition
+
+`CartDestinationRoot` provides the `'cartDestination'` context; every other part declares `requiresContext: 'cartDestination'`.
+
+```
+CartDestinationRoot                      (provides 'cartDestination'; starts in read mode)
+├── CartDestinationRead                  (read mode only)
+│   ├── CartDestinationValue             (the destination, once set)
+│   ├── CartDestinationUnset             (the store's invitation, while none is set)
+│   │   └── Text                         ("Informe seu CEP")
+│   └── CartDestinationChange            (opens edit mode)
+└── CartDestinationForm                  (edit mode only)
+    ├── CartDestinationPostalCodeControl
+    ├── CartDestinationSubmit
+    ├── CartDestinationCancel
+    ├── Text                             (the help line, placed by the store)
+    └── CartDestinationError
+```
+
+Child order reflects visual order. The store cannot open edit mode from outside: the mode is local to the root, and the destination shown always comes from the cart, never from what was typed.
+
+---
+
+## Components
+
+### CartDestinationRoot
+
+Reads the cart destination reactively and broadcasts it, the edit-mode flag, the draft and the write state. Starts in read mode, also with no destination.
+
+**Data:** declares `fragment CartDestinationData on Query` (`shipping { id address { postalCode country city state } }`) with `fetchStrategy: 'reactive'`. It selects no name and no street.
+
+**Write:** declares `actions: { shipping: ['setAddress'] }`. A submit sends `{ postalCode, country }` and nothing else; the cart keeps its recipient name. The response updates the destination and the free-shipping bar through the cache.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `defaultCountry` | string | `"BRA"` | Used while the cart has no address; the address country wins |
+
+### CartDestinationRead
+
+Renders its children only in read mode. No props.
+
+### CartDestinationValue
+
+The destination as prefix, postal code, city and state, each in its own element. Renders nothing while loading or when none is set.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `prefix` | string | — | For example `"Entregando em"`; authored content wins |
+
+**Content model** (`cart-destination-value`): `prefix`.
+
+### CartDestinationUnset
+
+Renders its children only once the destination resolved and none is set. Place the invitation inside it, within `CartDestinationRead`. No props.
+
+### CartDestinationChange
+
+Button that opens edit mode, with `aria-expanded` tied to the mode. Styled as a link by the store.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | For example `"Trocar localização?"`; authored content wins |
+
+**Content model** (`cart-destination-change`): `label`.
+
+### CartDestinationForm
+
+Renders only in edit mode. Enter in the field runs the submit, which flags an incomplete or unchanged draft instead of sending it. Opening it focuses the field; leaving it focuses `CartDestinationChange`.
+
+### CartDestinationPostalCodeControl
+
+A `PostalCodeField` bound to the draft, empty every time edit mode opens.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `mask` | string | the country's mask | `99999-999` for BRA; also the mask Submit checks the draft against, and the typed value must still match the country's pattern, so a mask the pattern rejects (9 digits in BRA, for example) keeps Submit disabled |
+| `label` | string | — | Field label |
+| `placeholder` | string | — | Field placeholder |
+| `invalidMessage` | string | — | Shown for a draft that is incomplete or fails the country's pattern |
+
+### CartDestinationSubmit
+
+Writes the typed postal code. Disabled until the draft is complete for the field's mask (the control's `mask`, else the country's), matches its pattern and differs from the current postal code, and while a write is pending (`aria-busy`). A pending write also waits for any cart line write in flight.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | For example `"Atualizar"` |
+| `pendingLabel` | string | — | Shown while the write is in flight |
+
+**Content model** (`cart-destination-submit`): `label`, `pendingLabel`.
+
+### CartDestinationCancel
+
+Closes edit mode, discards the draft and any error, and writes nothing. Disabled while a write is pending.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | For example `"Cancelar"` |
+
+**Content model** (`cart-destination-cancel`): `label`.
+
+### CartDestinationError
+
+An alert announcing a failed write; renders nothing otherwise. A refused postal code and a network failure reach the client as the same error, so author one message that covers both.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `genericMessage` | string | — | Authored message; the server's own is the fallback |
+
+**Content model** (`cart-destination-error`): `genericMessage`.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "cart-destination": {
+    "type": "CartDestinationRoot",
+    "style": ["flex", "flex-col", "gap-2", "text-sm"],
+    "children": ["cart-destination-read", "cart-destination-form"]
+  },
+  "cart-destination-read": {
+    "type": "CartDestinationRead",
+    "style": ["flex", "items-center", "gap-2"],
+    "children": ["cart-destination-value", "cart-destination-unset", "cart-destination-change"]
+  },
+  "cart-destination-value": { "type": "CartDestinationValue", "props": { "prefix": "Entregando em" }, "style": ["flex", "gap-1"] },
+  "cart-destination-unset": { "type": "CartDestinationUnset", "children": ["cart-destination-invitation"] },
+  "cart-destination-invitation": { "type": "Text", "props": { "as": "span", "children": "Informe seu CEP" } },
+  "cart-destination-change": {
+    "type": "CartDestinationChange",
+    "props": { "label": "Trocar localização?" },
+    "style": ["text-[#2563eb]", "font-medium", "cursor-pointer"]
+  },
+  "cart-destination-form": {
+    "type": "CartDestinationForm",
+    "style": ["flex", "flex-col", "gap-2"],
+    "children": [
+      "cart-destination-control",
+      "cart-destination-submit",
+      "cart-destination-cancel",
+      "cart-destination-help",
+      "cart-destination-error"
+    ]
+  },
+  "cart-destination-control": { "type": "CartDestinationPostalCodeControl", "props": { "label": "CEP" } },
+  "cart-destination-submit": { "type": "CartDestinationSubmit", "props": { "label": "Atualizar", "pendingLabel": "Atualizando…" } },
+  "cart-destination-cancel": { "type": "CartDestinationCancel", "props": { "label": "Cancelar" } },
+  "cart-destination-help": {
+    "type": "Text",
+    "props": { "as": "span", "children": "Após confirmar, a barra volta ao modo leitura com o novo CEP e cidade." }
+  },
+  "cart-destination-error": {
+    "type": "CartDestinationError",
+    "props": { "genericMessage": "Não foi possível usar esse CEP. Confira o número e tente de novo." },
+    "style": ["text-sm", "text-red-700"]
+  }
+}
+```
+
+---
+
+## Styling hooks
+
+| Attribute | On | Present when |
+|---|---|---|
+| `data-fs-cart-destination` | `CartDestinationRoot` | Always |
+| `data-fs-cart-destination-editing` | `CartDestinationRoot` | Edit mode is open |
+| `data-fs-cart-destination-pending` | `CartDestinationRoot` | A write is in flight |
+| `data-fs-cart-destination-read` | `CartDestinationRead` | Read mode |
+| `data-fs-cart-destination-value` | `CartDestinationValue` | A destination is set |
+| `data-fs-cart-destination-value-prefix`, `-postal-code`, `-city`, `-state` | The piece's element | The piece exists |
+| `data-fs-cart-destination-unset` | `CartDestinationUnset` | No destination is set |
+| `data-fs-cart-destination-change` | `CartDestinationChange` | Always |
+| `data-fs-cart-destination-form` | `CartDestinationForm` | Edit mode |
+| `data-fs-cart-destination-postal-code-control` | `CartDestinationPostalCodeControl` | Always |
+| `data-fs-cart-destination-submit`, `-submit-pending` | `CartDestinationSubmit` | Always, and while a write is in flight |
+| `data-fs-cart-destination-cancel` | `CartDestinationCancel` | Always |
+| `data-fs-cart-destination-error` | `CartDestinationError` | The latest write failed |
+
+No part ships CSS of its own. Spacing, the link look of the change control and the two modes' boxes are swatch decisions; use `data-fs-cart-destination-editing` to style them apart.
+
+---
+
+## Common mistakes
+
+- **Inventing `CartDestination` (without `Root`).** The provider is `CartDestinationRoot`.
+- **Using `RegionRoot` on the cart page.** `Region` only sets the header cookie; it never changes the cart destination, so the free-shipping bar never moves.
+- **Placing `CartDestinationValue` or `CartDestinationChange` outside `CartDestinationRead`.** They stay on screen while the form is open.
+- **Placing the postal code control, `CartDestinationSubmit` or `CartDestinationCancel` outside `CartDestinationForm`.** Only the form is bound to edit mode: outside it they render in read mode too, and Enter in the field no longer reaches the submit.
+- **Looking for an `open` prop or a controller.** The root owns edit mode; nothing outside it can open it.
+- **Omitting `CartDestinationUnset`.** With no destination the page then shows only the change link and no invitation.
+- **Expecting the Value to show what the shopper just typed.** It shows what the cart confirms.
+- **Authoring a "CEP não encontrado" message.** A refused code and a network failure are the same error today: author one message in `CartDestinationError`.
+
+---
+
+## Related
+
+- [[../free-shipping-progress/free-shipping-progress]] — the bar beside this component; it follows the destination write through the cache with no wiring.
+- [[../region/region]] — the header's region control; same postal code field, but a cookie and no cart write.
+- [[../shipping-address/shipping-address]] — the full delivery address on checkout, which this component's write shares with.
+- [[../../particles/postal-code-field/postal-code-field]] — the masked input this component composes.

package/dist/docs/cart-item.md

@@ -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,12 +55,12 @@ 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. 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.
 
@@ -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,7 +61,7 @@ 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.
 
@@ -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
@@ -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/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 |
 

package/dist/docs/incentives.md

@@ -54,7 +54,7 @@ FooterRoot
 
 **A refused destination costs the anchor and nothing else.** No read-time gate enforces the model's `pattern`, so an authored `javascript:` value reaches the component intact; the same render-time allowlist `FooterLinkGroup` and the social particle use — `http:`, `https:`, `mailto:`, `tel:`, and single-slash paths — is what stands between it and an `href`. Where those two drop the entry, this one renders the item unlinked with its glyph and copy intact, because an unlinked item is this component's ordinary shape and losing a benefit over a bad destination would be the larger failure. The refusal logs the item's index and the reason, never the authored value.
 
-**Every predefined name must be registered.** An `icon` 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 `INCENTIVE_ICON_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 pictogram. All five names resolve in the default collection; a store on a different collection maps them with `icons.aliases`.
+**Every predefined name must be registered.** An `icon` 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 `INCENTIVE_ICON_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 pictogram. All five names resolve in the default collection; a store on a different collection maps them with `icons.aliases`.
 
 ---
 
@@ -120,7 +120,7 @@ Size and box classes reach both paths, but **colour does not**. A predefined gly
 |---|---|---|
 | `Incentives` | The strip itself, wrapping on narrow screens | `flex flex-wrap gap-[32px] list-none p-0 m-0` |
 | `data-fs-incentive` | The block one benefit occupies | `flex flex-col items-center text-center gap-[4px] flex-1` |
-| `data-fs-incentive-link` | The anchor wrapping a linked block; absent on unlinked items, so style the layout on `data-fs-incentive` and only the link affordances here | `flex flex-col items-center gap-[4px] no-underline hover:text-brand` |
+| `data-fs-incentive-link` | The anchor wrapping a linked block; absent on unlinked items, so style the layout on `data-fs-incentive` and only the link affordances here | `flex flex-col items-center gap-[4px] no-underline hover:text-primary` |
 | `data-fs-incentive-icon` | Both glyph paths, sized to match | `w-[32px] h-[32px] object-contain` |
 | `data-fs-incentive-title` | The bold benefit label | `text-[14px] font-bold text-[#1a1a1a]` |
 | `data-fs-incentive-description` | Each supporting line | `text-[12px] text-[#616161]` |

package/dist/docs/logo.md

@@ -117,7 +117,7 @@ Bound to a CMS entry, the element authors no content props at all — the entry
 ```
 
 The image carries no size of its own, so the width above only constrains the mark once the store tells it
-to fill the wrapper. Author that once per store as the `Logo` base swatch in `global.json → styles`:
+to fill the wrapper. Author that once per store as the `Logo` base swatch in `foundation.json → styles`:
 
 ```json
 {