@vtex/faststore 0.0.1

package/dist/docs/buy-button.md

@@ -0,0 +1,162 @@
+# BuyButton
+
+**Category:** commerce
+**Purpose:** Add-to-cart button. Reads a product variant and dispatches the cart `addItem` action on click. Disables automatically when the variant is unavailable. Canonical use is on PDPs, but also valid in any product card context (related products, shelf) when product data is passed via `$data`.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A BuyButton block is present when you see:
+
+- A **primary CTA button** with a label like "Comprar", "Adicionar ao carrinho", "Buy now", or similar.
+- The button may appear **disabled or grayed out** with text like "Indisponível" or "Out of stock" — that is still a `BuyButtonButton`.
+
+---
+
+## When to use
+
+- PDP purchase CTA — the canonical use, with data from the GraphQL fragment.
+- Product cards in shelves or related products sections — pass the product data via `$data` prop instead of relying on the fragment.
+
+## When NOT to use
+
+- Cart summary page CTAs — use cart-specific components.
+- Non-purchasable links (wishlist, share) — use a plain button or link element.
+
+---
+
+## Composition
+
+`BuyButtonRoot` is the data provider. `BuyButtonButton` is the rendered button. Always use both together.
+
+```
+BuyButtonRoot
+└── BuyButtonButton
+```
+
+`BuyButtonButton` dispatches the cart `addItem` action through the compiler-injected `$actions.cart.addItem` prop. The add-to-cart write is **context-free** — it reads and writes the Apollo cache directly — so `BuyButton` needs **no `CartRoot` ancestor** (specs/actions.md, ADR-0010). Drop it on a PDP, a product card, a shelf, or the header alike.
+
+Child order reflects visual order.
+
+---
+
+## Adding the selected quantity (ProductQuantity)
+
+By default `BuyButtonButton` adds quantity 1. To add the quantity chosen in a PDP quantity selector, wrap the purchase area in a `ProductQuantityRoot` (a headless provider that holds the selected quantity): `BuyButtonButton` reads it via `useProductQuantity()`. Without a `ProductQuantityRoot` ancestor it falls back to quantity 1, so the BuyButton stays usable standalone.
+
+`ProductQuantityRoot` renders no DOM, so it can sit high in the tree and the BuyButton and selector may live in different layout blocks:
+
+```text
+ProductQuantityRoot              (headless — no DOM; holds the quantity)
+├── ... BuyButtonRoot → BuyButtonButton ...
+└── ... ProductQuantitySelector → NumberFieldGroup → controls ...
+```
+
+See product-quantity.md.
+
+---
+
+## Components
+
+### BuyButtonRoot
+
+Root data provider. Declares the GraphQL fragment and exposes product/variant context to `BuyButtonButton`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `selectedVariantId` | string | — | Page-supplied viewed SKU (a variant Node ID). Pre-selects the variant to add before the shopper interacts; a published swatch selection wins over it once set. |
+
+**Data:** declares `fragment BuyButtonData on Query`. Fetches the first variant's `availableForSale` flag, `skuId`, and default seller ID as the fallback slice.
+
+**Variant reactivity:** `BuyButtonRoot` reads the shopper's published variant selection (the same reactive state the VariantSelector swatches write). When a swatch is picked, the button adds **that variant** to the cart — its SKU (`variantId`) and its default seller — and its **availability** (disabled state and available/unavailable label) reflects the selected variant. The selected variant is fetched lazily and scoped to the product on screen; on a fetch error or null result it falls back to the product's first variant for both the payload and availability. Before any swatch interaction the optional `selectedVariantId` prop pre-selects the variant to add, and the live published selection wins once set. If the selected variant has no purchasable offer the button does not render, consistent with the pricing block.
+
+---
+
+### BuyButtonButton
+
+The rendered button. Dispatches `$actions.cart.addItem(...)` on click.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `availableLabel` | string | `"Comprar"` | Label shown when the variant is available for sale |
+| `unavailableLabel` | string | `"Indisponivel"` | Label shown when the variant is not available |
+
+**Actions:** declares `actions: { cart: ['addItem'] }`; the compiler threads the `addItem` handler in via `$actions.cart`. Renders `null` when `BuyButtonRoot` has no valid variant data. Disabled (and `aria-busy`) while the add is in-flight (the button tracks its own pending state). Must be a descendant of `BuyButtonRoot`.
+
+---
+
+## No CartRoot requirement
+
+`BuyButtonButton` writes through `$actions.cart.addItem`, which the compiler injects from its `actions` selector. The handler reads and writes the cache directly, so **`BuyButton` needs no `CartRoot` ancestor**. A PDP schema can render `BuyButtonRoot` → `BuyButtonButton` directly under the page `Container`.
+
+A `CartRoot` is still hosted by the layout so cart **reads** (mini-cart count, total, line items) work — but that is the layout's concern, not the buy button's, and it is never declared in the page schema.
+
+---
+
+## Canonical schema example
+
+Minimal PDP buy button — no `CartRoot` in the page schema:
+
+```json
+{
+  "root": {
+    "type": "Container",
+    "children": ["gallery", "product-info", "pricing", "buy-button"]
+  },
+  "buy-button": {
+    "type": "BuyButtonRoot",
+    "children": ["buy-button-action"]
+  },
+  "buy-button-action": {
+    "type": "BuyButtonButton",
+    "props": { "availableLabel": "Comprar", "unavailableLabel": "Indisponível" }
+  }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Inventing `BuyButton` (without Root).** There is no standalone `BuyButton` component. The entry point is `BuyButtonRoot` and the button itself is `BuyButtonButton`.
+- **Adding `CartRoot` to the page for the buy button.** Add-to-cart is context-free — it does not need a cart provider. The layout already hosts `CartRoot` for cart reads; never add one to a PDP schema just to enable the buy button.
+- **Passing a `disabled` prop to control availability.** Availability is handled automatically from the variant's `availableForSale` flag — do not set `disabled` manually.
+
+---
+
+## Styling
+
+Fill each element's `style` array with Tailwind classes read off the image. Typical patterns:
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `BuyButtonRoot` | Layout wrapper only — it renders no box of its own | `block w-full mt-[8px]` |
+| `BuyButtonButton` | The CTA: full-width pill in the brand color, with hover and disabled states | `inline-flex items-center justify-center w-full h-[44px] px-[20px] bg-[#C8102E] text-white rounded-[4px] text-[14px] font-bold uppercase cursor-pointer transition-colors hover:bg-[#A50D26] disabled:opacity-50 disabled:cursor-not-allowed` |
+
+Read the button's fill color straight off the image as an arbitrary hex (`bg-[#C8102E]`); derive the hover shade as a slightly darker value. Always include `disabled:` styling — the button auto-disables when the variant is unavailable. Do not invent a swatch or token for the brand color; inline hex only.
+
+Styled example:
+
+```json
+{
+  "buy-button": {
+    "type": "BuyButtonRoot",
+    "children": ["buy-button-action"],
+    "style": ["block", "w-full", "mt-[8px]"]
+  },
+  "buy-button-action": {
+    "type": "BuyButtonButton",
+    "props": { "availableLabel": "Comprar", "unavailableLabel": "Indisponível" },
+    "style": ["inline-flex", "items-center", "justify-center", "w-full", "h-[44px]", "px-[20px]", "bg-[#C8102E]", "text-white", "rounded-[4px]", "text-[14px]", "font-bold", "tracking-[0.06em]", "uppercase", "cursor-pointer", "transition-colors", "duration-150", "hover:bg-[#A50D26]", "active:bg-[#8A0B20]", "disabled:opacity-50", "disabled:cursor-not-allowed"]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[cart]] — cart read provider (`CartRoot`) and line-item particles; the buy button shares the cart via the cache, not via this provider.
+- [[pricing]] — price block that sits alongside the buy button on a PDP.
+- [[product-information]] — title and description block on the same PDP.

package/dist/docs/carousel.md

@@ -0,0 +1,105 @@
+# Carousel
+
+**Category:** layout
+**Purpose:** Generic horizontal carousel. Arranges arbitrary children into a navigable, paged track with previous/next arrows and pagination bullets. Holds no product, media, or GraphQL data — it is pure layout, reusable anywhere a set of children needs a navigable track (e.g. a product shelf).
+
+---
+
+## When to use
+
+- Any horizontally-paged track of arbitrary children: product cards, banners, testimonials, thumbnails.
+- When you need infinite looping, native-scroll vs. transform-slide movement, and composable controls.
+
+## When NOT to use
+
+- Product media on a PDP → use `ProductGalleryRoot`. For a non-PDP media array → use `GalleryRoot`. `Gallery` is media-typed (image/video, zoom, fullscreen); `Carousel` arranges any children and knows nothing about their content.
+
+---
+
+## Behavior model
+
+- **Paging is derived from children.** `CarouselTrack` counts its children; `totalPages = ceil(itemCount / itemsPerPage)`. There is no `itemCount` prop.
+- **Controls are composed parts, not an enum.** Place `CarouselPrevious` / `CarouselNext` / `CarouselBullets` to get "arrows only", "bullets only", or "complete". Omit what you don't want.
+- **`infiniteMode`** wraps navigation seamlessly and never disables the arrows. With it off, the arrow at the reached end is `disabled`.
+- **`variant`** — `slide` moves the track with a `translateX` transform; `scroll` uses native overflow scrolling with scroll-snap.
+
+---
+
+## Props
+
+### CarouselRoot
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `infiniteMode` | boolean | `false` | Loop seamlessly; arrows never disable |
+| `variant` | `'slide' \| 'scroll'` | `'slide'` | Transform slide vs. native overflow scroll |
+| `itemsPerPage` | number | `1` | How many children are visible per page |
+| `defaultPage` | number | `0` | Page selected on first render |
+| `label` | string | `'Carousel'` | `aria-label` for the carousel region |
+
+### CarouselTrack
+
+Lays out and counts the children. No props beyond standard `div` attributes. Place the items (e.g. product cards) directly inside.
+
+### CarouselPrevious / CarouselNext
+
+Buttons that move one page. No props beyond standard `button` attributes; accept any children (Icon, text). Disabled at the respective end when `infiniteMode` is off.
+
+### CarouselBullets
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `ariaLabel` | string | `'Choose page'` | Label for the bullets group |
+| `bulletLabel` | string | `'Go to page {page}'` | Per-bullet label; `{page}` is the 1-based page number |
+| `hideWhenSingle` | boolean | `true` | Render nothing when there is a single page |
+
+Bullets support `ArrowLeft` / `ArrowRight` / `Home` / `End` keyboard navigation and mark the active page with `data-fs-carousel-bullet-selected="true"` and `aria-current`.
+
+---
+
+## Composition
+
+```text
+CarouselRoot
+├── CarouselTrack
+│   ├── <item 1>
+│   ├── <item 2>
+│   └── …
+├── CarouselPrevious
+├── CarouselNext
+└── CarouselBullets
+```
+
+Every part must be inside `CarouselRoot`. `useCarousel()` throws if used outside it.
+
+---
+
+## Minimal schema example
+
+```json
+{
+  "carousel": {
+    "type": "CarouselRoot",
+    "props": { "infiniteMode": false, "variant": "slide", "itemsPerPage": 4 },
+    "children": ["carousel-track", "carousel-prev", "carousel-next", "carousel-bullets"]
+  },
+  "carousel-track": {
+    "type": "CarouselTrack",
+    "children": ["card"]
+  },
+  "carousel-prev": { "type": "CarouselPrevious", "children": ["icon-chevron-left"] },
+  "carousel-next": { "type": "CarouselNext", "children": ["icon-chevron-right"] },
+  "carousel-bullets": { "type": "CarouselBullets" }
+}
+```
+
+---
+
+## Styling
+
+Functional layout (flex track, `translateX`, overflow, scroll-snap) is built in. All appearance is chosen by swatches keyed off the `data-fs-carousel-*` hooks:
+
+- `data-fs-carousel` / `data-fs-carousel-variant`
+- `data-fs-carousel-track` / `data-fs-carousel-viewport` / `data-fs-carousel-item`
+- `data-fs-carousel-previous` / `data-fs-carousel-next` (native `disabled` at ends)
+- `data-fs-carousel-bullets` / `data-fs-carousel-bullet` / `data-fs-carousel-bullet-selected`

package/dist/docs/cart-item.md

@@ -0,0 +1,162 @@
+# CartItem
+
+**Category:** commerce
+**Purpose:** The reusable cart **line-item template** — the unit both the mini-cart and the checkout compose once per cart line. `CartItemRoot` owns the per-line core data and delivers each line its own slice; the `CartItem*` particles render fields of that slice.
+
+This matter is delivered on ADR-0012 **Option B**: `CartItemRoot` (`fetchStrategy: 'reactive-list-item'`) owns the core-scalar fragment and subscribes per line to `CartItem:<id>` in the normalized cache, so a per-line change re-renders only that line. `CartRoot` (the cart read root, in the layout) provides only item refs.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A **cart line** — a repeated row in a cart or mini-cart list: a product thumbnail, name, price, a quantity stepper, a remove control, one row per item. Each such row is one `CartItemRoot` wrapping the row's particles.
+
+---
+
+## Composition
+
+**`CartItemRoot` wraps the line-item template inside `CartList`.** The nesting is always:
+
+```text
+CartList              (iterator — renders its children once per cart line)
+  └─ CartItemRoot     (per-line data provider — owns the core slice)
+       ├─ CartItemImage             (optionally wrapped in CartItemProductLink; see below)
+       ├─ CartItemName
+       ├─ CartItemPrice / CartItemListPrice / CartItemDiscountPercentage
+       ├─ CartItemQuantity (stepper) / CartItemQuantityValue
+       ├─ CartItemLineTotal
+       ├─ CartItemOwnTotal / CartItemAggregateTotal
+       ├─ CartItemRemove
+       ├─ CartItemAvailable / CartItemUnavailable
+       ├─ CartItemGift              (free marker; renders only on a gift line)
+       ├─ CartItemSellerInfo        (optional per-line owner; see below)
+       ├─ CartItemDiscounts         (optional per-line owner; see below)
+       ├─ CartItemCustomizations    (optional per-line owner; see below)
+       ├─ CartItemCompositions      (optional per-line owner; see below)
+       └─ CartItemVariations        (optional per-line owner; see below)
+```
+
+- **`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.
+
+## 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:
+
+```text
+CartItemRoot
+  └─ CartItemProductLink        (anchor to this line's product page)
+       └─ CartItemImage         (unchanged — its alt text names the link)
+```
+
+**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.
+
+**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.
+
+**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.
+
+Navigation is client-side through the `NavigationLink` particle, which also owns `rel` hardening. The link is same-tab, and `target` is omitted from the props type rather than merely left out of the schema, because an image-only link cannot carry the "(opens in new tab)" cue a `_blank` destination needs.
+
+**Known gap:** a mini-cart drawer does **not** dismiss itself when a client-side navigation leaves it, so the overlay stays open over the product page. This is not specific to this leaf — `CartGoCheckout` behaves the same way — and it belongs to the drawer composition, not to a line leaf.
+
+Renders `a[data-fs-cart-item-product-link]`, which also carries the particle's `data-fs-navigation-link`.
+
+## Remove-on-alert composition
+
+`CartItemUnavailable` renders its children, so a `CartItemRemove` placed inside it gives the unavailable alert its own remove control — no new component, both require the same `cart-item-data` context under `CartItemRoot`:
+
+```text
+CartItemRoot
+  └─ CartItemUnavailable        (renders only when the line is NOT available)
+       ├─ Text "Out of stock"   (explicit label — see the nuance below)
+       └─ CartItemRemove        (removes this line from within its alert)
+```
+
+**Label-vs-children nuance:** passing children to `CartItemUnavailable` **replaces** its built-in state label (`children ?? unavailableLabel(availability)`). A remove-on-alert composition therefore renders the label as an explicit child (e.g. a `Text`) next to the `CartItemRemove`; nesting the remove control alone leaves the alert without a label. The whole subtree is availability-gated: when the line is `AVAILABLE`, neither the label nor the nested remove control renders.
+
+For the cart-level counterparts (the "N items unavailable" summary and the bulk "remove all unavailable" button), see `cart.md` — Unavailable-item recovery.
+
+## 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:
+
+```text
+CartItemRoot                    (row carries data-fs-cart-item-gift-line on a gift line)
+  ├─ CartItemListPrice          (renders: a gift's sellingPrice is 0, so listPrice > sellingPrice)
+  ├─ CartItemGift               (renders "Free")
+  └─ CartItemRemove             (renders nothing)
+```
+
+- **`CartItemGift`** is the free marker: a `span[data-fs-cart-item-gift][data-fs-text]` that renders **only** on a gift line, with the built-in English label `Free`. Passing children **replaces** the label (`children ?? 'Free'`), the same nuance `CartItemUnavailable` has. It is an **inline marker, not a wrapper** — its children are the label, so do not nest a block subtree in it. Place it beside `CartItemPrice`/`CartItemListPrice`.
+- **`CartItemRemove` suppresses itself** on a gift line. A gift is not the shopper's to discard in this phase, and since one template serves every row, the rule lives in the component rather than in the composition. This covers the remove-on-alert composition too: an unavailable gift renders its alert with no remove control, and recovery is the cart-level `CartRemoveUnavailable` batch (which still batches gift lines) plus server-side cart validation.
+- **`CartItemQuantity` suppresses itself** on a gift line too, the same way `CartItemRemove` does: a gift's quantity is promotion-controlled, and a `removeOnDecrement` stepper would otherwise let a shopper discard the gift by stepping it below the minimum — the one path the remove-control suppression did not cover. A store showing a gift's fixed quantity composes the read-only `CartItemQuantityValue`, which dispatches nothing.
+- **The row is marked** with `data-fs-cart-item-gift-line`, so a swatch can restyle a gift row without a component per variation — that is how a store hides the `R$ 0,00` selling price on a gift row.
+
+A gift whose `listPrice` is also 0 renders no list price (`CartItemListPrice`'s existing `listPrice <= sellingPrice` rule) and the marker carries the row alone.
+
+## Owned data
+
+`CartItemRoot`'s core fragment owns each line's `id`, `quantity`, `price`/`listPrice`/`sellingPrice`, `gift`, `ownTotal`/`total`, `variant { variantId, sku, name, image, availability }`, and the `product` core. `variant.availability` stays here (not a sub-matter) because it is read cross-cuttingly: `CartItemAvailable`/`CartItemUnavailable` gate on it, and `CartCheckoutGuard` reads it across all lines. `gift` stays here for the same reason — `CartItemGift`, `CartItemRemove`'s suppression, and the row's state hook all read it.
+
+Every per-line field this fragment selects must also be selected by the **mutation** fragment (`CartItemFragment` in `sdk/cart/operations.ts`). The per-line subscriber resolves `complete ? data : fallbackData`, and the fallback is the cart-level slice, which carries no product or prices — so a field selected here but not there makes every row incomplete after a cart write. Two tests in `cart-item.test.tsx` guard it.
+
+### CartItemOwnTotal and CartItemAggregateTotal
+
+Two core-slice leaves render the line total, siblings to `CartItemLineTotal`:
+
+- **`CartItemOwnTotal`** renders `ownTotal` — the line's **own** total (own unit selling price × quantity, rounding-exact), **excluding** composition children.
+- **`CartItemAggregateTotal`** renders `total` — the line's **aggregate** total, **including** all nested composition children recursively. On a bundled line this is the price the shopper actually pays.
+
+`total == ownTotal` on any line with no compositions, so either leaf is safe to place unconditionally: a plain line renders the same value from both. Both `Number()`-coerce the string `Money.amount` before formatting from the active storefront context, emit `data-fs-cart-item-own-total` / `data-fs-cart-item-aggregate-total` (both with `data-fs-text`), and accept a `children` override. `CartItemLineTotal` (`sellingPrice × quantity`, the line's own total) is unchanged and independent — the `Own`/`Aggregate` naming is deliberately self-documenting.
+
+## CartItemQuantity and the unit multiplier
+
+The stepper shows the line's quantity **in the unit the merchant sells in**, not the raw purchasable count. The order form counts purchasable units, so a SKU sold in 500 g portions carries `unitMultiplier: 0.5` and a shopper holding 1.5 kg has `quantity: 3` — the stepper reads `1.5`. A six-pack SKU (`unitMultiplier: 6`) at `quantity: 2` reads `12`. The multiplier is read from the line, never configured: `1` is the identity, so a SKU sold by the unit behaves exactly as before.
+
+`unitMultiplier` is **optional per-line data owned by `CartItemQuantity`'s own fragment** (ADR-0011), not by `CartItemRoot`'s core slice, so a cart or checkout line that shows only the read-only `CartItemQuantityValue` never fetches it. The stepper still reads `id` and `quantity` from the core slice, which is why it keeps requiring `cart-item-data` and must stay inside `CartItemRoot`.
+
+**`min`, `max`, and `step` are authored in purchasable units** and converted for display by the component. `min: 1, max: 10` on a 0.5-multiplier line yields a reachable range of `0.5` to `5` in steps of `0.5`. That is deliberate: one line template renders SKUs with different multipliers, so bounds expressed in purchasable units keep meaning the same thing across every line and need no re-authoring when a SKU's packaging changes. A merchant wanting a 500 g floor writes `min: 1`, not `min: 0.5`.
+
+Enforcement happens **on commit** — blur after typing, pointer release on the buttons, or a keyboard interaction — not per keystroke. A committed amount that is out of bounds or off the multiplier grid is clamped and snapped to the nearest valid amount (ties round up), then the remaining delta is dispatched as `increaseQuantity` / `decreaseQuantity` in purchasable units. No non-integer quantity can reach a mutation. Nothing is corrected at render time: a quantity already outside the authored bounds is displayed as-is and fires no write.
+
+A snap renders a notice as the last child of the stepper: `div[role="alert"][data-fs-cart-item-quantity-validation]`, carrying the `validationMessage` prop, whose `{value}` placeholder is replaced with the corrected displayed amount (default `Quantity adjusted to {value}.`). The root also carries `data-fs-cart-item-quantity-adjusted` plus `data-fs-cart-item-quantity-adjusted-reason="min" | "max" | "multiple"` for per-reason styling, and `data-fs-cart-item-quantity-multiplier="<value>"` whenever the multiplier is not `1`, so a measured line can be styled differently from a counted one.
+
+`removeOnDecrement`: a committed amount below the configured minimum removes the line instead of clamping, and no notice is raised. In that mode the decrement control is **not** disabled at the minimum — removal is the intended outcome there — and `data-fs-cart-item-at-min` still keys off the purchasable count. This never applies to a gift line: the stepper renders nothing there, so `removeOnDecrement` cannot discard a gift.
+
+The measurement unit itself (`kg`, `un`) is not fetched, so a measured line renders `1.5` with no suffix.
+
+## Optional per-line owners
+
+`CartItemSellerInfo` is an **optional** per-line data owner: it owns `variant.seller.name` via its own `reactive-list-item` fragment and requires only `cart-item` (so it sits inside `CartList`, alongside or within `CartItemRoot`). Its seller subtree is fetched **only** on pages that place it — stores that omit it never over-fetch `variant.seller`.
+
+### CartItemDiscounts
+
+`CartItemDiscounts` is another **optional** per-line data owner: it owns the line's `discounts` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders one labeled row per featured promotion applied to the current cart line — the promotion `name` plus its amount (e.g. `Black Friday −R$ 20,00`, `Cupom −10%`) — so a shopper sees *which* promotion took *how much* off *this* item. It is the itemized companion to the aggregated `Discounts` totalizer line in the footer.
+
+Each row branches on `isPercentual`: a currency discount (`false`) formats the amount from the active storefront context; a percentual discount (`true`) renders `−N%` and is **not** currency-formatted. Every amount carries a presentational leading `−` — the source `value` is a positive amount. It **renders null when the line has no discounts** (empty or unresolved), so it appears only where a promotion actually fired. Place it under the line, near the price area. Must be inside `CartList`.
+
+**Distinct from `CartItemDiscountPercentage`.** `CartItemDiscountPercentage` is a single derived `−N%` **badge** computed from `listPrice`/`sellingPrice` with **no** promotion name; `CartItemDiscounts` is the **named list** of promotions sourced from the line's `discounts` field. They cover different concerns and may coexist on a line — the badge next to the price, the named list beneath it.
+
+Renders a `div[data-fs-cart-item-discounts]` container with one `span[data-fs-cart-item-discount]` per discount; each row wraps a `span[data-fs-cart-item-discount-name]` (the promotion name) and a `span[data-fs-cart-item-discount-value]` (the amount). No props beyond the standard `div` attributes; the list is data-driven and `children` is not used to override it.
+
+### CartItemCustomizations
+
+`CartItemCustomizations` is an **optional** per-line data owner: it owns the line's `customizations` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders the form-based personalization a shopper applied to the line — engraving text, a size selection, an uploaded file's URL — as one group per assembly, each group listing its `entries` as `name` / `value` rows (e.g. `Text: MARIA`). It **renders null when the line has no customizations** (empty or unresolved). Must be inside `CartList`.
+
+The group heading is the raw assembly `id` (e.g. `Engraving`); pretty display names are deferred (836 Decision 2). An uploaded-file value surfaces as its URL string and is rendered verbatim — there is no file-preview/download widget in v0 (836 exposes no file metadata; at parity with fastcheckout).
+
+Renders a `div[data-fs-cart-item-customizations]` container with one `div[data-fs-cart-item-customization]` per group (carrying `data-fs-cart-item-customization-id` for per-group styling); each entry is a `span[data-fs-cart-item-customization-entry]` wrapping a `span[data-fs-cart-item-customization-name]` and a `span[data-fs-cart-item-customization-value]`. The list is data-driven; `children` is not used to override it.
+
+### CartItemCompositions
+
+`CartItemCompositions` is an **optional** per-line data owner: it owns the line's `compositions` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders the nested bundle/assembly tree a shopper built under the line — each child row shows the child's `name`, `quantity` (`×N`), and formatted unit `price`. It **renders null when the line has no compositions** (empty or unresolved). Must be inside `CartList`.
+
+**Recursion.** A composition child is itself an order-form line, so it can carry its own nested `compositions` (a sub-bundle) and its own `customizations` (836 Decision 8). The matter recurses over the in-slice `compositions` array with an internal render function: each node renders its row, its own customization groups (using the same `name`/`value` anatomy as `CartItemCustomizations`, so one swatch styles both), then its nested children at `depth + 1`. Recursion is over finite data — the server guarantees acyclic compositions (836 visited-index) and depth is bounded by the assembly config. React keys use the node `id`.
+
+Renders a `div[data-fs-cart-item-compositions]` container with one `div[data-fs-cart-item-composition]` per child; each child carries `data-fs-cart-item-composition-depth="N"` (the indent hook for nesting) and wraps `span[data-fs-cart-item-composition-name]`, `span[data-fs-cart-item-composition-quantity]`, `span[data-fs-cart-item-composition-price]`, then any customization groups, then its nested children. The tree is data-driven; `children` is not used to override it.
+
+### CartItemVariations
+
+`CartItemVariations` is another **optional** per-line data owner: it owns the line's `variant.selectedOptions` subtree via its own `reactive-list-item` fragment and requires only `cart-item`, so its data is fetched **only** on pages that place it. It renders one labeled row per variation selected on the current cart line (e.g. `Cor: Vermelho`, `Tamanho: M`), so a shopper can tell two lines of the same product apart. It **renders null when the line has no selected options** (empty or unresolved), so it appears only where the SKU actually has variations. Place it near the product name. Must be inside `CartList`.
+
+Renders a `div[data-fs-cart-item-variations]` container with one `span[data-fs-cart-item-variation]` per option; each row wraps a `span[data-fs-cart-item-variation-name]` (e.g. `Cor`), a `span[data-fs-cart-item-variation-separator]` holding the `": "` delimiter, and a `span[data-fs-cart-item-variation-value]` (e.g. `Vermelho`). The separator is a hook of its own so a store can restyle or hide the delimiter without the punctuation riding along with the label; with no swatch applied a row still reads `Cor: Vermelho`. No props beyond the standard `div` attributes; the list is data-driven and `children` is not used to override it.

package/dist/docs/cart-totalizer.md

@@ -0,0 +1,197 @@
+# CartTotalizer
+
+**Category:** commerce
+**Purpose:** Focused reactive data provider for cart totalizers and grand total. Fetches only the `totalizers` and `total` fields — a narrower slice than `CartRoot`. Use it to compose an **order summary** — the subtotal / discount / shipping / total breakdown — in either a **mini-cart drawer footer** (alongside the layout `CartRoot`) or a **checkout summary panel** (standalone). Use it on summary-only pages where it is the sole reactive data root, or alongside `CartRoot` when the page already hosts the full cart context.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Look for an **order summary** listing individual cost lines (subtotal, discounts, shipping) and a grand total, typically with a checkout CTA below. Examples:
+
+- A card labeled "Order Summary" or "Resumo do Pedido" with line-by-line cost breakdown.
+- A sidebar showing subtotal + discount + shipping + total, separated from the cart item list.
+- The **footer of a mini-cart drawer**, below the item list: a subtotal row, an optional discount row, a shipping row, and a bold grand-total row, above the checkout button.
+
+---
+
+## When to use
+
+- In a **mini-cart drawer footer** — the layout root is a `CartRoot` wrapping the drawer (item list + footer), and the footer composes a `CartTotalizerRoot` subtree for the order summary. Both roots select the same top-level `cart {}` field, so the compiler merges them into one query and the runtime issues one fetch. This is the mini-cart order-summary pattern; the americanas `default.json` footer uses it.
+- On a **summary-only page** (no cart item list) — `CartTotalizerRoot` wraps the summary card and acts as the sole reactive data root. The checkout page currently uses this pattern.
+- **Alongside `CartRoot`** on the same page — the compiler merges both components' fragments into one query (same `cart {}` field, no double fetch). Use this when the page already needs full cart context and you want to add a separate summary widget.
+
+## When NOT to use
+
+- As a replacement for `CartRoot` when the page also renders `CartList`, `CartCount`, or other `useCart()`-dependent components — those require `CartRoot`.
+- Nested inside `CartRoot` as a redundant provider — the contexts compose automatically when both are on the same page; no explicit nesting is needed.
+
+> **Note (americanas checkout layout):** The current `checkout` layout hosts no `CartRoot` — it is intentionally bare. The checkout page uses `CartTotalizerRoot` standalone. When a future checkout step needs full cart mutations, the layout (or page) should add `CartRoot`.
+
+---
+
+## Composition
+
+```
+CartTotalizerRoot          ← reactive data provider (totalizers + total)
+├── CartTotalizerLine      ← one cost row, selected by totalizerId
+│     totalizerId="Items"
+├── CartTotalizerLine
+│     totalizerId="Discounts"  variant="discount"   ← hides when amount = 0
+├── CartTotalizerLine
+│     totalizerId="Shipping"   zeroLabel="Free"
+├── <hr /> / Separator
+└── CartTotal label="Total" ← root-agnostic grand total (set label for a labeled total row)
+```
+
+### Key particles
+
+| 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` |
+| `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") |
+
+---
+
+## CartDiscountLine — itemized discounts (F11)
+
+`CartDiscountLine` renders the cart's discounts as **one labeled line per promotion and coupon**, plus a
+residual line for anything they do not account for. It reads `Cart.discounts` (each entry a `name`, a
+positive `value`, and a `kind` of `PROMOTION | COUPON | OTHER`) and renders each amount as a negative
+value formatted in the store's currency. It renders nothing when the cart has no discounts.
+
+It owns its own cart slice: the `Cart.discounts` selection is fetched only when this leaf is placed and
+merges with the `CartTotalizerRoot` / `CartRoot` cart query into one fetch. Place it in the order
+summary, typically inside `CartTotalizerRoot` for the cart slice; money formats from the active
+storefront context wherever it renders.
+
+**Itemized versus aggregate — choose one.** The itemized entries are the companion to the aggregate
+`Discounts` totalizer and sum to it, so compose **either** `CartDiscountLine` **or**
+`CartTotalizerLine totalizerId="Discounts"`, never both — showing both double-counts the same money. Use
+`CartDiscountLine` when the summary should name each promotion and coupon; use the aggregate line when a
+single "Discounts" figure is enough.
+
+The `name` a promotion or coupon carries comes from the platform; the API leaves the residual (and any
+unnamed promotion) without a name, so `otherLabel` supplies the label for those (default
+`"Other discounts"`, override per store).
+
+Style hooks: `data-fs-cart-discount-lines` on the group, and per row
+`data-fs-cart-discount-line` (with `data-fs-cart-discount-line-kind` = `promotion` / `coupon` / `other`),
+`data-fs-cart-discount-line-label`, and `data-fs-cart-discount-line-value`.
+
+```json
+{
+  "type": "CartTotalizerRoot",
+  "children": [
+    { "type": "CartTotalizerLine", "props": { "totalizerId": "Items" } },
+    { "type": "CartDiscountLine", "props": { "otherLabel": "Other discounts" } },
+    { "type": "CartTotalizerLine", "props": { "totalizerId": "Shipping", "zeroLabel": "Free" } },
+    { "type": "CartTotal", "props": { "label": "Total" } }
+  ]
+}
+```
+
+---
+
+## CartMarkdownLine — item-level catalog markdown (F11 scenario 1)
+
+`CartMarkdownLine` renders the cart's **aggregate item-level catalog markdown** — the sum of
+`(listPrice − price) × quantity` across non-gift lines — as a single negative summary line. This is the
+"de/por" savings baked into the catalog price, computed server-side and exposed as `Cart.itemMarkdownTotal`;
+the component reads that one `Money` field, negates it so the currency format supplies the sign, and renders
+nothing when it is zero.
+
+It owns its own cart slice: `Cart.itemMarkdownTotal` is fetched only when this leaf is placed and merges with
+the `CartTotalizerRoot` / `CartRoot` cart query into one fetch. Place it in the order summary, typically inside
+`CartTotalizerRoot` for the cart slice; money formats from the active storefront context wherever it renders.
+
+**Distinct money — coexists with the discount line.** Item markdown is `listPrice − price`, the reduction from
+list *down to* the "Items" subtotal; the `Discounts` totalizer and `CartDiscountLine` are `price − sellingPrice`,
+the cart-level promotions and coupons *below* the subtotal. They are different money, so — unlike the
+itemized-versus-aggregate choice for `CartDiscountLine` — you compose `CartMarkdownLine` **alongside** the
+discount line, not instead of it. It is never part of `totalizers` and never summed into `total`; it is an
+informational savings line.
+
+**Presentation — give the reduction a referent.** Because the `Items` subtotal already reflects the
+markdown, a bare `−R$ 36,00` row dropped into the running column does not foot (`Items − markdown −
+Discounts ≠ total`) and reads as an error. Compose it so the reduction reconciles something visible:
+either render a **"List price" row** (the pre-markdown `Σ listPrice × qty` — a derived display value no
+totalizer carries) immediately above it, so `list − markdown = Items subtotal` and the column foots
+(`346 − 36 = 310`, then `310 − 40 = 270`); or present it as a **distinct "you saved" note** set apart
+from the running total. What you must not do is interleave it as a plain negative line between the
+subtotal and the total, because it is not part of that sum. The `ItemMarkdown` story shows the
+list-price framing.
+
+The `label` prop words the row (default `"Item discounts"`, override per store).
+
+Style hooks: `data-fs-cart-markdown-line` on the row (also `data-fs-text`), with
+`data-fs-cart-markdown-line-label` and `data-fs-cart-markdown-line-value`.
+
+Per the reconciliation rule above, this example places `CartMarkdownLine` **after** `CartTotal` — an
+informational savings note set apart from the running total, not a line between the subtotal and the
+total (the markdown is already reflected in `Items`).
+
+```json
+{
+  "type": "CartTotalizerRoot",
+  "children": [
+    { "type": "CartTotalizerLine", "props": { "totalizerId": "Items", "label": "Items subtotal" } },
+    { "type": "CartDiscountLine", "props": { "otherLabel": "Other discounts" } },
+    { "type": "CartTotalizerLine", "props": { "totalizerId": "Shipping", "zeroLabel": "Free" } },
+    { "type": "CartTotal", "props": { "label": "Total" } },
+    { "type": "CartMarkdownLine", "props": { "label": "Savings off list price" } }
+  ]
+}
+```
+
+---
+
+## Schema
+
+```json
+{
+  "type": "CartTotalizerRoot",
+  "children": [
+    { "type": "CartTotalizerLine", "props": { "totalizerId": "Items" } },
+    { "type": "CartTotalizerLine", "props": { "totalizerId": "Discounts", "variant": "discount" } },
+    { "type": "CartTotalizerLine", "props": { "totalizerId": "Shipping", "zeroLabel": "Free" } },
+    { "type": "CartTotal" }
+  ]
+}
+```
+
+### Mini-cart drawer footer
+
+In a mini-cart, the layout root is a `CartRoot` wrapping the drawer (item list + footer). The footer composes a `CartTotalizerRoot` subtree as the order summary — the two roots select the same top-level `cart {}` field, so the compiler merges them into one query (no double fetch). Render the grand total with `CartTotal label="Total"`; there is no `CartTotalizerTotal`. A divider above the total is purely visual — style it, do not model it as a structural node.
+
+```json
+{
+  "footer-summary": {
+    "type": "CartTotalizerRoot",
+    "children": ["summary-subtotal", "summary-discount", "summary-shipping", "summary-total"]
+  },
+  "summary-subtotal": {
+    "type": "CartTotalizerLine",
+    "props": { "totalizerId": "Items" },
+    "children": []
+  },
+  "summary-discount": {
+    "type": "CartTotalizerLine",
+    "props": { "totalizerId": "Discounts", "variant": "discount" },
+    "children": []
+  },
+  "summary-shipping": {
+    "type": "CartTotalizerLine",
+    "props": { "totalizerId": "Shipping", "zeroLabel": "Free" },
+    "children": []
+  },
+  "summary-total": {
+    "type": "CartTotal",
+    "props": { "label": "Total" },
+    "children": []
+  }
+}
+```