@vtex/faststore 0.0.5 → 0.0.7

package/dist/docs/place-order.md

@@ -0,0 +1,157 @@
+# PlaceOrder
+
+**Category:** commerce
+**Purpose:** The checkout's place-order CTA. Runs the three-call payment sequence (start transaction, the holder's direct-to-gateway submission, gateway callback), blocks interaction while it runs, and renders one inline outcome — an error message or a success confirmation — once it settles.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A PlaceOrder block is present when you see:
+
+- A **primary CTA button** at the bottom of a payment/checkout section with a label like "Place order", "Finalizar compra", "Pay now", or similar.
+- The button may appear **greyed out with a spinner or busy indicator** and a label like "Placing order…" — that is still the same `PlaceOrder`, mid-sequence.
+- A **confirmation line or banner below the button** reading something like "Order placed successfully" once the button has been pressed and the order succeeded — this is `PlaceOrder`'s own inline success state, not a separate order-confirmation page.
+- An **inline error line below the button** (e.g. "Enter your payment details before placing the order.") is also part of this same block, not a separate error component.
+
+The image is the source of truth for layout.
+
+---
+
+## When to use
+
+- The final CTA in a credit-card checkout/payment section, once a method (and, for a new card, its fields) has been entered.
+
+## When NOT to use
+
+- Product-page purchase CTA (add to cart) — use [[buy-button]] instead. `PlaceOrder` is checkout-only and drives the payment sequence, not a cart write.
+- Do **not** nest it inside the card-entry form. It must be a **sibling** of card entry and saved cards under the same payment root — nesting it inside the card form would need a second CTA for the saved-card path, which is exactly the mistake this component's placement avoids.
+
+---
+
+## Composition
+
+`PlaceOrder` is a single, self-contained component — no Root/leaf split. It must be placed as a child of `PaymentSectionRoot` or `PaymentSectionController`, as a **sibling** of `CardEntry` / `SavedCards`, never nested inside either:
+
+```
+PaymentSectionRoot (or PaymentSectionController)
+├── PaymentMethodList
+├── CardEntry            (new-card path)
+├── SavedCards            (saved-card path)
+└── PlaceOrder             ← sibling, not a child of CardEntry/SavedCards
+```
+
+Child order reflects visual order. `PlaceOrder` composes under **either** payment root with no change — both provide the same `payment` context and the same submission channel (ADR-0009).
+
+`PlaceOrder` never reads or holds a card field. It calls `usePlaceOrder`, the T13 orchestration hook, which resolves a continuation that `CardEntry`/`SavedCards` registered on a submission channel by the shopper's entry path — this component only knows there is a hook to call, a loading state to block on, and an outcome to render. It also reads `usePayment().draft.billingAddressDifferent` (T11) and forwards it into `usePlaceOrder`, so the gateway descriptor carries whether the shopper picked a different billing address — the one other fact this component touches, and still not a card field.
+
+---
+
+## Components
+
+### PlaceOrder
+
+No sub-components. Renders a button and, once the sequence has settled, one inline outcome region (error or success).
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `"Place order"` | Button label while idle. |
+| `placingLabel` | string | `"Placing order..."` | Button label while the sequence is in flight. |
+| `resumeLabel` | string | `"Complete your order"` | Button label while a surviving attempt offers a resume — the card already left the browser (or its fate is unknown) and the next click finalizes it instead of running the full sequence again. |
+| `successMessage` | string | `"Order placed successfully."` | Shown once the sequence settles with no errors. |
+| `missingSubmissionMessage` | string | `"Enter your payment details before placing the order."` | Shown when `placeOrder()` is invoked with no registered submission for the current path (e.g. the shopper never finished entering a card). |
+| `missingMethodMessage` | string | `"Choose a payment method before placing the order."` | Shown when no payment method is selected yet. |
+| `invalidTransactionMessage` | string | `"Unable to start the payment. Please try again."` | Shown when `startTransaction` resolves incomplete transaction data. |
+| `networkErrorMessage` | string | `"Unable to complete the request. Please try again."` | Shown for an infrastructure-level failure reaching the payment gateway action. |
+| `missingDocumentMessage` | string | `"Enter your document before placing the order."` | Shown when the selected method requires a cardholder document and none is set. |
+| `invalidDocumentMessage` | string | `"Enter a valid document before placing the order."` | Shown when the typed cardholder document fails validation. |
+| `unavailableMethodMessage` | string | `"Choose another payment method before placing the order."` | Shown instead of the two document messages above when the selected method calls for a cardholder document the page is not showing — a method the card form cannot pay with, or one outside the payment root's `group` — so the shopper has to choose another payment method. |
+| `unsavedBillingAddressMessage` | string | `"Save your billing address before placing the order."` | Shown when the shopper declined "same as delivery" but never saved a custom billing address. |
+| `invalidCardDataMessage` | string | `"Enter valid card details before placing the order."` | Shown when the new-card draft itself fails validation before ever reaching the gateway. |
+| `invalidSecurityCodeMessage` | string | `"Enter a valid security code before placing the order."` | Shown when a saved-card submission is refused for a missing or invalid CVV. |
+| `gatewayErrorMessage` | string | `"Unable to complete the payment. Please try again."` | Shown when the payment gateway itself refuses the submitted card. |
+| `inFlightMessage` | string | `"This order is already being placed. Please wait."` | Shown when a click lands on an order-placement attempt whose own sequence is still running — a transaction this instance did not open, and which nothing here may finalize or re-run. |
+| `unconfirmedMessage` | string | `"We could not confirm your order yet. Your payment may still be processing, so please do not pay again."` | Shown when the payment was handed to the gateway but the order could not be confirmed, so it may still be processing. Renders in its own `role="status"` node, never in the error alert. |
+| `successHref` | string | *(none)* | Route **template** navigated to after a successful placement. The literal `{orderGroup}` is replaced with the placed order's group, percent-encoded. **Opt-in and success-gated**: no default is provided on purpose, so an absent prop keeps today's behavior byte-for-byte, and the navigation is requested only once an attempt settles with no errors and a non-null order group — never on a refusal. |
+
+Every message prop above is resolved by the `code` of the client-synthesized `PaymentUserError` this CTA renders — in its alert, or in its status node for `unconfirmedMessage` — never by which component produced the error. A `PaymentUserError` whose code this component does not author (a server-returned code) renders that error's own `message` unchanged.
+
+**Data:** declares its own thin `fragment PlaceOrderData on Query` selecting `payment.selectedMethodId`, `payment.selectedInstallment`, and `payment.methods { id groupName }` — the exact slice the orchestration hook needs, no more. **Actions:** declares `actions: { payment: ['startTransaction', 'gatewayCallback'], analytics: ['track'] }`. Must be inside a payment root (`requiresContext: 'payment'`).
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "children": ["payment-method-list", "card-entry", "place-order"]
+  },
+  "payment-method-list": { "type": "PaymentMethodList" },
+  "card-entry": { "type": "CardEntry" },
+  "place-order": {
+    "type": "PlaceOrder",
+    "props": {
+      "label": "Place order",
+      "placingLabel": "Placing order...",
+      "successMessage": "Order placed successfully.",
+      "successHref": "/checkout/order-placed/{orderGroup}"
+    }
+  }
+}
+```
+
+`successHref` is shown here for reference only — it is opt-in (see the props table above), and no store composes it today. It must be a path on the store's own origin (root-relative, like the example above, or an absolute URL on the same origin) — an absolute URL on a different origin, a protocol-relative URL, or a non-http(s) scheme is refused rather than navigated to.
+
+---
+
+## Common mistakes
+
+- **Nesting `PlaceOrder` inside `CardEntry` or `SavedCards`.** It must be a sibling of both under the same payment root, so one CTA serves both the new-card and saved-card paths.
+- **Placing `PlaceOrder` outside any `PaymentSectionRoot`/`PaymentSectionController`.** It throws at render — there is no payment context or submission channel to resolve.
+- **Confusing it with `BuyButtonButton`.** `BuyButtonButton` adds a product to the cart on a PDP; `PlaceOrder` runs the payment sequence in checkout. They are never composed together.
+- **Expecting a redirect or a 3D Secure challenge.** v1 is the direct-API mode only — the shopper stays on the page and the outcome renders inline. The redirect mode is phase 2.
+
+---
+
+## Known limitations
+
+- **A remount reads the surviving attempt instead of losing it — but the attempt itself does not survive a page reload.** T29 (`specs/make-an-order-attempt-survive-a.md`) gave the place-order sequence an identity-and-phase record on the payment context, above this component's own mount, alongside `placing`. Closing and reopening a `Dialog`/`Drawer` popup with no `keepMounted` no longer resets it: a settled attempt renders disabled with no further calls (`succeeded` is derived from the record, not only from this instance's own `attempted`/`userErrors`), and an attempt whose card already reached the gateway before the remount offers a resume (`resumeLabel`) that finalizes the same transaction — never a fresh `startTransaction` or a second card submission. This closes the case this bullet used to attribute to "a settled-order read model that outlives the overlay (T16/T17)": both are merged, and the limitation still stood, because neither one ever touched this component's own mount-scoped guard, which is what actually caused the duplicate-order risk. What is still not covered: a full page reload loses the attempt (no `sessionStorage` or equivalent persists it today — T29's own OQ-3), and the direct-to-gateway POST's abort budget (30s, `sdk/payment/gateway.ts`) is an unconfirmed placeholder pending a number from payments (OQ-7).
+- **Sibling placement (never nested inside `CardEntry`/`SavedCards`) is a convention, not something the compiler enforces.** `requiresContext: 'payment'` only fails a build with no payment-providing ancestor at any depth; it cannot detect that this component was nested one level too deep. Getting this wrong compiles clean and still leaves the other entry path with no CTA at all (see `specs/place-order.md`'s Open items).
+- **`successHref` navigates with `router.replace`, not `router.push`.** The payment step is removed from the history stack, so the Back button from the confirmation page returns to whatever preceded payment, not to the payment step itself — deliberate (placing an order is terminal, and a live place-order CTA one Back press away risks a duplicate transaction), but a divergence from this package's other redirect-on-success component, `CartRedirectOnAdd`, which uses `push`.
+- **A `successHref` authored without the literal `{orderGroup}` placeholder fails closed.** The component refuses to navigate rather than sending every shopper to the same unresolvable URL, and logs a `console.warn` outside production. This is a store-authoring mistake to fix in the template, not a runtime condition to handle.
+- **A `successHref` that resolves off the store's own origin also fails closed.** An absolute URL on a different origin, a protocol-relative URL (`//host/...`), or a non-http(s) scheme is refused rather than navigated to, with the same dev-only `console.warn`. This keeps a store schema from turning the CTA into a redirect off the storefront right after a real purchase.
+- **`successHref` is inert until a store authors it.** As of this writing no store composes it — see `specs/navigate-the-shopper-to-the-order.md` for the follow-up that wires Reserva's payment page to it, gated on the confirmation page's read path being fixed first.
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `PlaceOrder` (root `div`) | Layout wrapper stacking the button and the outcome region | `flex flex-col gap-[8px] items-start` |
+| Button (`data-fs-place-order-button`) | The CTA itself — full-width pill, disabled/busy 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 disabled:opacity-50 disabled:cursor-not-allowed` |
+| Error (`data-fs-place-order-error`) | Inline error line, `role="alert"` | `text-[13px] text-[#C0392B]` |
+| Unconfirmed (`data-fs-place-order-unconfirmed`) | Inline notice that the order could not be confirmed yet, `role="status"` | `text-[13px] text-[#8A6D3B]` |
+| Success (`data-fs-place-order-success`) | Inline success line, `role="status"` | `text-[13px] text-[#1E8E3E]` |
+| Success order id (`data-fs-place-order-success-order-id`) | The placed order's id, inside the success line | `font-mono text-[12px] text-[#666666]` |
+
+Always include `disabled:` styling on the button — it disables automatically while the sequence runs and again once it succeeds.
+
+Styled example:
+
+```json
+{
+  "place-order": {
+    "type": "PlaceOrder",
+    "style": ["flex", "flex-col", "gap-[8px]", "items-start"],
+    "props": { "label": "Place order" }
+  }
+}
+```
+
+---
+
+## Related
+
+- [[payment]] — `PaymentSectionRoot` / `PaymentSectionController`, the roots `PlaceOrder` must compose under.
+- [[buy-button]] — the PDP purchase CTA and this component's named precedent for the blocking loading-state pattern (disabled + `aria-busy` + a `-pending` hook).

package/dist/docs/product-shelf.md

@@ -1,7 +1,7 @@
 # ProductShelf
 
 **Category:** commerce
-**Purpose:** A data-owning product shelf. `ProductShelfRoot` owns a facet-filtered `products(filter:)` query from the catalog module, receives its slice as `$data`, and publishes each product through a per-item context. `ProductShelfItems` repeats those products into a `Carousel` track, one card per slide. The card parts (`ProductCard*`) read each product from context — the shelf holds the data and config, the carousel arranges the rows, the cards render one product each.
+**Purpose:** A data-owning product shelf. `ProductShelfRoot` owns a facet-filtered `products(first:, orderBy:, filter:)` query from the catalog module whose arguments bind to this element's configuration (the merchant's CMS entry, else the props), receives its slice as `$data`, and publishes each product through a per-item context. `ProductShelfItems` repeats those products into a `Carousel` track, one card per slide. The card parts (`ProductCard*`) read each product from context — the shelf holds the data and config, the carousel arranges the rows, the cards render one product each.
 
 ---
 
@@ -18,7 +18,7 @@ A ProductShelf block contains any combination of:
 
 If the image shows **any of the above**, use `ProductShelfRoot` composed with `CarouselRoot` and `ProductShelfItems`. When a section heading is visible, compose `ProductShelfHeading` inside `ProductShelfRoot` (above `CarouselRoot`) with the title as its `children` (like any `Text`). Pick only the card parts (`ProductCardImage`, `ProductCardName`, `ProductCardPrice`, `ProductCardListPrice`, `ProductCardDiscount`, …) that match what's visible in each card.
 
-The image is the source of truth for the heading text, `first`/`itemsPerPage`, and which card parts to include. The **source of the shelf's products** (`categoryId` / `brandId` / `collectionId` / `searchTerm` / `specifications`) is a merchant configuration decision and cannot be read off the screenshot — leave those unset when the image gives no signal, and let the shelf fall back to catalog-wide relevance.
+The image is the source of truth for the heading text, `first`/`itemsPerPage`, and which card parts to include. The **source of the shelf's products** (`categoryId` / `brandId` / `collectionId` / `searchTerm`) is a merchant configuration decision and cannot be read off the screenshot — leave those unset when the image gives no signal, and let the shelf fall back to catalog-wide relevance.
 
 ---
 
@@ -36,8 +36,9 @@ The image is the source of truth for the heading text, `first`/`itemsPerPage`, a
 
 ## Behavior model
 
-- **The shelf owns the data.** `ProductShelfRoot` declares a `fragment ProductShelfData on Query` selecting `products(first: $first, orderBy: $orderBy, filter: $filter)` and receives the resolved slice as `$data`. `fetchStrategy: 'lazy'` defers the load (below-the-fold), and a skeleton shows while pending.
-- **Config feeds the query.** The serializable schema props map to the fragment variables: `first` → `$first`, `sort` → `$orderBy` (`ProductSortingInput`), and the facet props (`searchTerm`, `categoryId`, `brandId`, `collectionId`, `specifications`, `availableOnly`) → `$filter` (`ProductsFilterInput`). `buildProductShelfVariables(config)` is the pure mapping.
+- **The shelf owns the data.** `ProductShelfRoot` declares a `fragment ProductShelfData on Query` selecting `products(first: $first, orderBy: $orderBy, filter: { categoryIds: $categoryId, brandIds: $brandId, collectionId: $collectionId, searchTerm: $searchTerm, availableOnly: $availableOnly })` and receives the resolved slice as `$data`. `fetchStrategy: 'lazy'` defers the load (below-the-fold), and a skeleton shows while pending.
+- **The element's configuration feeds the query.** Every variable binds to this element: the compiler reads the field of the same name from the element's content slice (the `product-shelf` content model, in a store with a `cms` binding) and otherwise from the element's prop, then instances the fragment once per shelf on the page, so two shelves with different `first` or `sort` become two aliased `products` fields in one page query. `sort` reaches `$orderBy` (`ProductSortingInput`) through the `values` table in the definition's `variables` block, which equals `PRODUCT_SHELF_SORT_MAP`. A facet left empty is not sent, so the filter relaxes instead of sending `null`; `first` is honored by the API, never sliced on the client.
+- **Props beside content.** Each content field is also a schema prop of the same name. The CMS value wins per field; the prop is the developer default and the only source in a store with no `cms` binding (Vivara, Storybook, tests). No field is `required`, so an unfilled entry never omits the shelf. `useProductShelf()` exposes the resolved `config` (`$content?.field ?? field`), `itemsPerPage` and `count`.
 - **Two context boundaries.** The shelf owns product data + config; each row owns one item. Card parts read the item through a guarded hook and never take list-shaped props.
 - **Presence is state-driven.** Empty result → the shelf renders nothing (no empty carousel). Unresolved lazy source → skeleton.
 - **The carousel is composed, not baked.** Place `CarouselRoot` with `ProductShelfItems` inside it, plus `CarouselPrevious` / `CarouselNext` / `CarouselBullets` where you want them. `ProductShelfItems` renders the `CarouselTrack`, so the carousel counts one slide per product.
@@ -51,17 +52,23 @@ The image is the source of truth for the heading text, `first`/`itemsPerPage`, a
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `first` | number | `5` | Max products fetched (legacy `numberOfItems`) → `$first` |
 | `itemsPerPage` | number | `5` | Cards per page; bind to `CarouselRoot`'s `itemsPerPage` |
-| `sort` | `relevance \| price_asc \| price_desc \| name_asc \| name_desc \| release \| orders \| discount` | `relevance` | → `$orderBy` |
-| `searchTerm` | string | — | → `filter.searchTerm` |
-| `categoryId` | string | — | → `filter.categoryIds` |
-| `brandId` | string | — | → `filter.brandIds` |
-| `collectionId` | string | — | → `filter.collectionId` (legacy `productClusterIds`) |
-| `specifications` | `{ name, values }[]` | — | → `filter.specifications` (custom attributes) |
-| `availableOnly` | boolean | `false` | → `filter.availableOnly` (global "hide out-of-stock") |
+| `usePriceWithTaxes` | boolean | `false` | Card prices render tax-inclusive |
+| `taxesLabel` | string | `'Tax included'` | Text for the tax label part |
+| `first` | number | `5` | Content field. Products fetched (legacy `numberOfItems`) → `$first` |
+| `sort` | `relevance \| price_asc \| price_desc \| name_asc \| name_desc \| release \| orders \| discount` | `relevance` | Content field → `$orderBy` through the `values` table |
+| `searchTerm` | string | — | Content field → `filter.searchTerm` |
+| `categoryId` | string | — | Content field → `filter.categoryIds` |
+| `brandId` | string | — | Content field → `filter.brandIds` |
+| `collectionId` | string | — | Content field → `filter.collectionId` (legacy `productClusterIds`) |
+| `availableOnly` | boolean | `false` | Content field → `filter.availableOnly` (global "hide out-of-stock") |
+| `$content` | slice | — | Compiler-injected `product-shelf` entry; each field wins over the prop of the same name |
 | `$data` | slice | — | Compiler-injected fragment result |
-| `products` | `ProductShelfItem[]` | — | Pre-shaped items (stories/tests; bypasses `$data`) |
+| `products` | `ProductShelfItem[]` | — | Pre-shaped items (stories/tests; bypasses `$data`). Rendered as given: `first` does not limit them |
+
+### Content model `product-shelf`
+
+`ProductShelfContent` declares the merchant-facing fields: `first` (number, minimum 1), `sort` (the eight members above), `categoryId`, `brandId`, `collectionId`, `searchTerm` (string) and `availableOnly` (boolean). None is required. In a store with a `cms` binding the merchant fills them in the Content Platform entry keyed by the element id, and the shelf re-queries on the next request with no deploy; an empty field falls to the prop, and an empty facet relaxes the filter.
 
 ### ProductShelfItems
 

package/dist/docs/save-card.md

@@ -0,0 +1,186 @@
+# SaveCard
+
+**Category:** commerce
+**Purpose:** Opt-in control for authenticated shoppers to save the card they are currently entering for a future purchase, with a custom nickname. Off by default. Checking it also grants the account's data-storage consent; unchecking it never revokes that consent.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Use these signals to detect that a SaveCard block is present. Position on the page is irrelevant for
+detection — it can appear anywhere inside a payment section. The image is the source of truth for
+layout.
+
+A SaveCard block contains any combination of:
+
+- A single **checkbox with a label reading something like "Save this card for next time"**, sitting
+  inside (or directly beside) a credit-card entry form.
+- Immediately below or beside the checkbox, **small, secondary-styled helper text** mentioning storing
+  or saving personal data — present only when the account has not already granted that consent.
+- When the checkbox is shown checked in the image, a **second text input labeled something like "Card
+  nickname" / "Name this card"** appears directly below it.
+- This block always sits **inside a checkout payment section**, near card-number fields or a saved-cards
+  list — never on a product page, cart page, or as a standalone marketing checkbox.
+
+If the image shows a single opt-in checkbox near card-entry fields, with an optional name/nickname text
+field conditionally shown, use `SaveCard`. If the checkbox instead controls a newsletter or general
+data-sharing preference with no relation to a card, that is `NewsletterOptInControl` /
+`SavePersonalDataOptInControl` (`ClientPreferencesRoot`'s Controls), not this component.
+
+---
+
+## When to use
+
+- Inside a checkout's payment section, as a sibling of the card-entry fields (and/or the saved-cards
+  list), so a logged-in shopper can opt in to saving the card they are currently using.
+
+## When NOT to use
+
+- A general "share my data with this store" consent, unrelated to a specific card → use
+  `SavePersonalDataOptInControl` (under `ClientPreferencesRoot`) instead. Different data ownership,
+  different section, and — critically — that surface's own `$data` read has a live defect (always reads
+  as unset); do not use it as a reference implementation for a new read.
+- A newsletter opt-in → use `NewsletterOptInControl` instead.
+- The list of already-saved cards → use `SavedCards` / `SavedCardOption` instead. `SaveCard` only offers
+  to save the card currently being entered; it never lists or selects an existing saved card.
+- Outside a payment section, or outside an identity/session context → `SaveCard` requires **both** a
+  `PaymentSectionRoot`/`PaymentSectionController` ancestor and a `SessionRoot` ancestor. Placing it
+  without either is a build/runtime error, not a silent no-op.
+- For a guest checkout flow with no login step at all → `SaveCard` self-gates to render nothing for
+  anyone who is not logged in; do not wrap it in an extra visibility condition in the schema.
+
+---
+
+## Composition
+
+`SaveCard` is a single leaf — no root, no required children, no sub-components:
+
+```
+PaymentSectionRoot (or PaymentSectionController)
+├── CardEntry            (sibling — new-card fields)
+├── SavedCards            (sibling — saved-card picker)
+├── Installments           (sibling — installment selector)
+└── SaveCard                (sibling — this component)
+```
+
+`SaveCard` must be a descendant of `PaymentSectionRoot` or `PaymentSectionController` (it reads and
+writes the shopper's in-progress card draft) **and** must also have a `SessionRoot` ancestor somewhere
+in the same composed page/layout tree (it reads the identity session state to self-gate). Place it as a
+**sibling** of `CardEntry` and `SavedCards`, never nested inside either — one `SaveCard` instance covers
+whichever entry path the shopper is on, the same way `Installments` does.
+
+It self-gates to render nothing while the session is loading, for a guest, or for an
+identified-but-not-logged-in shopper — safe to include speculatively inside any payment section, but for
+image-to-schema work only include it when the image actually shows the checkbox described above.
+
+It also renders nothing while the card payment is collapsed — the persisted selection is a method that
+is not a card, or one the section does not serve, and a composed `PaymentMethodList` can bring the card
+form back (see [[payment]]). The save-card flag and nickname stay on the draft, so the control comes back
+as the shopper left it.
+
+---
+
+## Components
+
+### SaveCard
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `"Save this card for next time"` | The toggle's own label text. |
+| `nicknameLabel` | string | `"Card nickname"` | Label for the nickname field; rendered only while checked. |
+| `nicknamePlaceholder` | string | — | Optional placeholder for the nickname field. |
+| `consentNoticeLabel` | string | `"Checking this also lets us store your personal data for future purchases."` | Shown beside the toggle while the account has not already granted the data-storage consent. |
+| `disabled` | boolean | `false` | Disables both the toggle and the nickname field. |
+
+**Data:** declares its own `fragment SaveCardData on Query` (selects `Query.clientPreferences.savePersonalData`
+only — a single boolean, not a card field) — a small, thin fragment the compiler merges into the page
+query alongside `PaymentSectionRoot`'s own selection; no explicit `dataSources` entry needed.
+`fetchStrategy: 'reactive'` — the consent notice updates live from the cache, no refetch.
+
+**The toggle never seeds from the standing consent.** It always starts unchecked, even when the account
+has already granted `savePersonalData` elsewhere — saving *this* card is always a fresh, per-transaction
+choice.
+
+**Checking the toggle** records the shopper's intent for this card *and* grants the account's
+data-storage consent in the same action; the nickname field appears immediately below. **Unchecking**
+withdraws only this transaction's intent — it never revokes a consent an unrelated control may have
+granted. On a rejected consent write, the first error message renders inline.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "children": ["card-entry", "saved-cards", "installments", "save-card"]
+  },
+  "save-card": {
+    "type": "SaveCard",
+    "props": { "label": "Save this card for next time" },
+    "style": ["flex", "flex-col", "gap-2"]
+  }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Inventing `SaveCardControl` or `SaveCardToggle`.** The component is `SaveCard`.
+- **Nesting `SaveCard` inside `CardEntry` or `SavedCards`.** It must be a sibling of both under the
+  same `PaymentSectionRoot`, exactly like `Installments`.
+- **Placing `SaveCard` without a `SessionRoot` ancestor somewhere in the page.** It requires session
+  context to self-gate and throws without one.
+- **Expecting the checkbox to start checked because the shopper already granted data-storage consent
+  elsewhere.** It always starts unchecked — the standing consent and the per-transaction save intent
+  are independent by design.
+- **Expecting unchecking to revoke a previously granted consent.** It deliberately does not; see
+  `specs/save-card-control.md` Decision 1 for the full rationale.
+- **Using `SaveCard` to render a general privacy/data-sharing consent form.** It is scoped to a single
+  boolean and a nickname for the card currently being entered — use `ClientPreferencesRoot`'s Controls
+  for anything broader.
+- **Expecting a full card number or CVV field.** The fragment structurally selects neither, and no prop
+  accepts one — this component never touches sensitive card data.
+
+---
+
+## Styling
+
+Single DOM root wrapping the toggle field, an optional nickname field, and an optional inline error.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `SaveCard` (root `div`) | Stacks the toggle field, nickname field, and error | `flex flex-col gap-[8px]` |
+| Consent notice (`data-fs-save-card-consent-notice`) | De-emphasized helper text | `text-[12px] text-[#666666]` |
+| Nickname field wrapper (`data-fs-save-card-nickname-field`) | Spacing above the field | `mt-[8px]` |
+| Inline error (`data-fs-save-card-error`) | Warning-toned alert text | `text-[12px] font-medium text-[#B00020]` |
+| Placing (`data-fs-save-card-placing`) | Present while an order-placement sequence is in flight (T28) — distinct from `data-fs-save-card-pending`, which this component already emits for its own local consent dispatch; the root is also `inert` and `aria-disabled` while placing | `opacity-60 cursor-not-allowed` |
+
+Styled example:
+
+```json
+{
+  "save-card": {
+    "type": "SaveCard",
+    "style": ["flex", "flex-col", "gap-2"]
+  }
+}
+```
+
+There is no per-field styling hook beyond the particles' own `data-fs-checkbox-*` / `data-fs-field-*`
+attributes (`Checkbox.Root`/`Checkbox.Indicator`, `Field.Root`/`Field.Label`/`Field.Control`) — style
+the checked state via Base UI's own `data-checked` on `Checkbox.Root`, per the `style-components` skill.
+
+---
+
+## Related
+
+- [[saved-cards]] — the list of already-saved cards, and the CVV re-entry for one; `SaveCard` only
+  offers to save the card currently being entered, never lists an existing one.
+- [[installments]] — the closest structural sibling: a single leaf requiring `PaymentSectionRoot`, no
+  Root/leaf split, sibling placement under the same section.
+- [[client-preferences]] — owns the broader `savePersonalData` / `optinNewsLetter` consent surface;
+  `SaveCard` reads the same underlying field but through its own fragment, never by composing under
+  `ClientPreferencesRoot` (whose own read of that field has a live, unrelated defect).