@vtex/faststore 0.0.4 → 0.0.6

package/dist/docs/identity-summary.md

@@ -19,7 +19,7 @@ IdentityEditController                           // owns the summary/form swap;
        │    ├─ IdentitySummary.SignOutButton     // dispatches session.logout
        │    └─ IdentitySummary.Error             // inline sign-out error
        └─ IdentityEditForm
-            ├─ ClientProfileForm                 // the edit surface (composed directly)
+            ├─ FormRoot → ClientProfileFieldset  // the edit surface (batched write on submit)
             └─ IdentityEditCancelButton          // Cancel → back to the summary
 ```
 
@@ -43,7 +43,7 @@ anonymous state, so anything that must survive that state — the section headin
 - **Summary/form swap** — `IdentityEditController` with its guards and triggers. The edit and cancel
   buttons are `IdentityEditButton` and `IdentityEditCancelButton`; a leading icon composes as their children.
   The controller moves only on those buttons — saving does not collapse the section — so neither this
-  compound nor `ClientProfileForm` learns anything about a section around it (ADR-0006).
+  compound nor the edit form learns anything about a section around it (ADR-0006).
 
 ## The summary is composed, not fixed
 
@@ -94,13 +94,13 @@ IdentitySummaryRoot
   and `Error` all require it — the compiler enforces the ancestor. The `IdentityEditController` and its
   guards/triggers require only each other.
 - Fragment ownership: `Root` reads only `clientProfile` (email, firstName, lastName, phone, document).
-  The edit surface is a separately-composed `ClientProfileForm`, which owns its own fragment and the
-  `identity.clientProfileUpdate` / `clientPreferencesUpdate` actions.
+  The edit surface is a separately-composed `FormRoot` over `ClientProfileFieldset`, which owns its own
+  fragment and the `identity.clientProfileUpdate` / `clientPreferencesUpdate` actions.
 - Actions: `Root` declares only `session.logout`.
 
 ## Do not
 
-- Do not place two `ClientProfileForm`s for the same fields; the edit guard hosts the single one.
+- Do not place two `ClientProfileFieldset`s for the same fields; the edit guard hosts the single one.
 - Do not use this compound for an anonymous shopper; the Root renders nothing and has no anonymous fallback.
 - Do not expect the section to close after a save — nothing here does that. Where a finished section
   leads is left to the flow-of-steps RFC (#611).

package/dist/docs/installments.md

@@ -0,0 +1,248 @@
+# Installments
+
+**Category:** commerce
+**Purpose:** Installment selection for checkout — lets a shopper pick how many installments to pay a card in, showing each option's count, per-installment value, and interest (or an interest-free label). Two registered components share one engine and one data shape: `Installments` renders every tier as a stacked radio list; `InstallmentsSelect` collapses the same tiers into a single closed dropdown. Both serve a freshly typed new card (matched by BIN) and a selected saved card (matched by the persisted BIN, falling back to payment method), rendering exactly the tiers the matched option provides (the API guarantees a 1x tier is present in every option, so one is always shown and selectable). Pick whichever control fits the layout — never both on the same instance, though composing one of each on a page is harmless (they stay in sync through the shared cache).
+
+---
+
+## Visual cues (how to identify in an image)
+
+Use these signals to detect that an installment picker is present, and which of the two components it is. Position on the page is irrelevant for detection — it can appear anywhere, in any orientation. The image is the source of truth for layout.
+
+**`Installments` (radio list)** — any combination of:
+
+- A **vertical list of selectable rows**, each a radio button or radio-styled row.
+- Each row reading something like **"1x de R$ 100,00 sem juros"** or **"3x de R$ 35,00 2,5% de juros"** — a count, a currency-formatted value, and an interest note.
+- One row visibly marked as the current selection (a filled radio dot, a highlighted background, or a checkmark).
+
+**`InstallmentsSelect` (collapsed dropdown)** — any combination of:
+
+- A **single closed control** (a bordered box or button) showing one line of text in the same "count de value interest" shape, with a dropdown chevron/arrow glyph.
+- No option rows visible until the control is opened — the closed state never lists every tier, unlike the radio surface.
+- An optional label above the control (e.g. "Installments" / "Parcelamento") — the accessible name, always present even when visually suppressed.
+
+Both always sit **inside a checkout payment section** (near a card-number field or a saved-card list) — never on a product page. A similar-looking installment list on a PDP is `PricingInstallments` / `PricingInstallmentPlans`, not either of these components (see [When NOT to use](#when-not-to-use)).
+
+If the image shows a selectable list of installment counts inside a checkout/payment flow, use `Installments` for a stacked list of rows, or `InstallmentsSelect` for a single closed control that expands on interaction. If the list is read-only (no radio, no dropdown, no visible interactivity) and sits next to a recap of the chosen card, it is neither component — no component renders a read-only payment recap in checkout.
+
+---
+
+## When to use
+
+- Inside a checkout's payment section, as a sibling of the card-entry fields and/or the saved-cards list, so the shopper can choose an installment count for the card they are paying with.
+- Choose `Installments` when the layout has room for a stacked list of rows (every tier visible at once, no extra click).
+- Choose `InstallmentsSelect` when the layout is narrow — a slim column, a drawer, a mobile checkout — where a dozen stacked rows would not fit; it collapses the same tiers into one control that expands on interaction.
+
+## When NOT to use
+
+- A PDP's advertised installment plans (display-only, no selection) → use `Pricing`'s `PricingInstallments` / `PricingInstallmentPlans` instead. Different data source (`productBySlug` offer, not `Query.payment`), no write, not reusable here.
+- A read-only recap of the installment already chosen (e.g. at Order Review) — no component renders one in checkout. Both installment components always show every available option and let the shopper change the selection.
+- Outside a payment section → both components require a `PaymentSectionRoot` or `PaymentSectionController` ancestor (they read the shopper's in-progress card draft from that context). Placing either anywhere else is a build/runtime error, not a silent no-op.
+- A saved-card picker itself (network icon, last four, label) → use `SavedCards`, not either installment component.
+- A page needing both a stacked list AND a collapsed control at once → compose two separate instances (one of each). There is no single component with a prop that switches between the two looks (see [Common mistakes](#common-mistakes)).
+
+---
+
+## Composition
+
+Both components are leaves — no root, no required children, no sub-components. A page composes exactly one of them per payment section (composing one of each is harmless but redundant — they read the same data and stay in sync):
+
+```
+PaymentSectionRoot (or PaymentSectionController)
+├── CardEntry              (sibling — new-card fields)
+├── SavedCards             (sibling — saved-card picker)
+└── Installments           (sibling — stacked radio list)
+    …or…
+└── InstallmentsSelect     (sibling — collapsed dropdown)
+```
+
+Either component must be a descendant of `PaymentSectionRoot` or `PaymentSectionController` — each reads the shopper's in-progress card draft (`draft.bin`) and the currently selected method from that context. Place it as a **sibling** of `CardEntry` and `SavedCards`, never nested inside either: one instance serves both the new-card and saved-card paths, matched automatically from the same context data.
+
+Both self-gate to an empty state when nothing is selected yet, and to a loading state before their data resolves — safe to include speculatively inside any payment section, but for image-to-schema work only include one when the image actually shows a selectable installment control, and pick the variant (list vs. dropdown) the image actually shows.
+
+Both render 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]]) — and come back with it. A method's own installment options apply only when it is a card: over a persisted non-card method, card mode included, both read `empty` until a card is recorded, never that method's own tiers.
+
+---
+
+## Components
+
+### Installments
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `installmentTemplate` | string | `"{count}x of {value}"` | Placeholders `{count}` / `{value}`, matching `PricingInstallment`'s convention. |
+| `interestFreeLabel` | string | `"interest-free"` | Appended when a row's interest rate is `0`. |
+| `interestTemplate` | string | `"{rate}% interest"` | Appended instead of `interestFreeLabel` when a row's interest rate is above `0`. `{rate}` is the order form's `interestRate`, which is in hundredths of a percent, divided by 100 and locale-formatted: `100` renders `1`. |
+| `legend` | string | `"Installments"` | The radio group's accessible name, rendered as a visible fieldset legend above the rows (T38). An authored empty or whitespace-only string falls back to this default rather than rendering a nameless group. |
+
+**Data:** declares its own `fragment InstallmentsData on Query` (selects `Query.payment.installmentOptions` and `Query.payment.selectedInstallment` — the compiler merges it into the page query alongside `PaymentSectionRoot`'s own, smaller `payment` selection; no explicit `dataSources` entry needed). `fetchStrategy: 'reactive'` — the option list updates live from the cache, no refetch.
+
+**Matching:** resolves one installment option to show by preferring a match on `draft.bin ?? selectedBin` — the client's detected BIN, or the persisted BIN when the client asserts none (e.g. after a page reload with a card already selected). Falls back to a match on the currently selected payment method when neither BIN match exists. This is the same precedence the backend itself uses. The `binConfirmation` signal from `usePaymentMethodSelection` gates dispatch while the persisted BIN and the client draft disagree or a method selection is in flight, so the rows a shopper sees always agree with what a selection would actually validate against.
+
+**The 1x option:** the component renders exactly the tiers the matched option's own data carries. The API guarantees a `count: 1` tier is present in every projected `installmentOptions` entry — passed through untouched (including its interest rate) when upstream supplies one, synthesized from the option's own `value` with no interest when it does not — so a 1x row is always shown and selectable.
+
+**Selecting a row** dispatches the installment write action; on success the order total (interest-inclusive) updates elsewhere on the page with no further action from this component. On rejection, the first error message renders inline.
+
+### InstallmentsSelect
+
+The collapsed sibling: same tiers, same matching, same write path, same `installmentTemplate`/`interestFreeLabel`/`interestTemplate` defaults as `Installments`, and the same formatting locale — the storefront context's, since neither component takes a `locale` prop — only the control itself differs (a Base UI Select instead of a radio group), plus two extra copy props for the closed control's own text.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `installmentTemplate` | string | `"{count}x of {value}"` | Same as `Installments`. |
+| `interestFreeLabel` | string | `"interest-free"` | Same as `Installments`. |
+| `interestTemplate` | string | `"{rate}% interest"` | Same as `Installments`: `{rate}` is the order form's hundredths-of-a-percent `interestRate` divided by 100. |
+| `label` | string | `"Installments"` | Accessible name for the control, rendered as the particle's own label element. Always renders — there is no mode that hides it; a store that already has its own heading suppresses it visually via its own `data-fs-installments-label` hook. An authored empty or whitespace-only string falls back to this default (T38) rather than rendering a nameless combobox. |
+| `placeholder` | string | `"Select an installment plan"` | Shown on the closed control when the bound count matches no tier in the currently matched option (a stale selection — see below). As of T31, every copy prop across both `Installments` and `InstallmentsSelect` defaults to en-US, while values and interest rates format in the storefront context's locale, which no prop overrides. A pt-BR store now authors every copy prop explicitly, not just these two. |
+
+**Data:** declares its own `fragment InstallmentsSelectData on Query`, with a selection set identical to `InstallmentsData` under a distinct name (two registered components on one page must not share a fragment name). Same `fetchStrategy: 'reactive'`.
+
+**Matching, the 1x option, and dispatch** are identical to `Installments` — both components read and write through the same shared engine, so they cannot drift.
+
+**The closed control** always shows the persisted selection's own label — resolved from the component's own tier data, correct even before the popup is ever opened — or the `placeholder` text when the persisted count matches no tier in the currently matched option (e.g. the shopper switched to a card whose options offer fewer tiers). It never invents a label.
+
+**No plan count.** The closed control never shows how many tiers exist — only the current selection or the placeholder, mirroring `DeliveryOptionsSummary`'s "echo the selection, not the inventory" precedent.
+
+**The popup is portalled to `<body>`.** This avoids clipping when the component sits inside a dialog or drawer, but it also means a store's `style` array cannot reach the option list's internals (padding, hover, the selected-row treatment) the way it can reach a radio row — see [Styling](#styling).
+
+---
+
+## Canonical schema example
+
+Radio list:
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "children": ["card-entry", "saved-cards", "installments"]
+  },
+  "installments": {
+    "type": "Installments",
+    "style": ["flex", "flex-col", "gap-2"]
+  }
+}
+```
+
+Collapsed dropdown — same payment section, `InstallmentsSelect` in place of `Installments`:
+
+```json
+{
+  "payment-section": {
+    "type": "PaymentSectionRoot",
+    "children": ["card-entry", "saved-cards", "installments-select"]
+  },
+  "installments-select": {
+    "type": "InstallmentsSelect",
+    "props": { "label": "Parcelamento", "placeholder": "Selecione o parcelamento" }
+  }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Inventing `InstallmentSelector` or `PaymentInstallments`.** The two shipped components are `Installments` (radio list) and `InstallmentsSelect` (collapsed dropdown).
+- **Adding a `control` / `variant` prop to switch `Installments` between a list and a dropdown.** There is no such prop, and none should be authored — the look is chosen by which component the page composes, never by a prop that bakes a visual decision into one component. Compose `InstallmentsSelect` instead.
+- **Nesting either component inside `CardEntry` or `SavedCards`.** Each must be a sibling of both under the same `PaymentSectionRoot` — nesting it inside either would tie the selector to only one entry path, which is exactly the gap these components close.
+- **Using either component on a PDP.** A PDP's advertised plans are `Pricing`'s `PricingInstallments` / `PricingInstallmentPlans` — different data source, display-only, not reusable here.
+- **Using either component for a read-only recap.** A recap of the already-chosen installment (e.g. Order Review) is not `Installments` or `InstallmentsSelect`; both are selectors.
+- **Placing either component outside a payment section.** Both require a `PaymentSectionRoot`/`PaymentSectionController` ancestor and throw without one.
+- **Expecting a rendered order total.** Neither component ever shows a total — selecting an option updates the cart total elsewhere on the page through the normalized cache.
+- **Expecting a full card number or CVV field.** Both fragments structurally select neither — only installment counts, values, and interest rates.
+- **Expecting `InstallmentsSelect`'s option list to be styleable from the page's `style` array.** Its popup is portalled to `<body>` — see [Styling](#styling).
+
+---
+
+## Styling
+
+### Installments
+
+Single DOM root wrapping a list of selectable rows.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `Installments` (root `div`) | Stacks the option rows | `flex flex-col gap-2` |
+| Fieldset (`data-fs-installments-fieldset`, native `<fieldset>`) | Wraps the legend and the radio rows (T38) — gives the group its visible, accessible name | usually left unstyled; a merchant border/padding choice |
+| Legend (`data-fs-fieldset-legend`, native `<legend>`) | The group's visible name, from `legend` | `text-[14px] font-medium text-[#1A1A1A]` |
+| Empty state (`data-fs-installments-state="empty"`) | Neutral placeholder sizing | `min-h-12 border border-dashed border-[#CCCCCC]` |
+| Loading state (`data-fs-installments-state="loading"`) | Skeleton affordance | `min-h-12 animate-pulse bg-[#F5F5F5]` |
+| Pending state (`data-fs-installments-state="pending"`) | Rows visible but disabled while the persisted BIN settles | `opacity-50 pointer-events-none` |
+| Inline error (`data-fs-installments-error`) | Warning-toned alert text | `text-[12px] font-medium text-[#B00020]` |
+| Option row label (`data-fs-installments-option-label`) | Row text | `text-[14px] text-[#1A1A1A]` |
+| Placing (`data-fs-installments-placing`) | Present while an order-placement sequence is in flight (T28) — distinct from the `pending` state above, which is this component's own BIN-confirmation wait; the root is also `inert` and `aria-disabled` at that point | `opacity-60 cursor-not-allowed` |
+
+Styled example:
+
+```json
+{
+  "installments": {
+    "type": "Installments",
+    "style": ["flex", "flex-col", "gap-2"]
+  }
+}
+```
+
+There is no per-row styling hook exposed as a separate schema element — `Installments` renders its own rows directly (no Root/particle split); style the checked/unchecked row state via the `Radio` particle's own `data-checked` attribute, and the row text via `data-fs-installments-option-label`, per the `style-components` skill.
+
+### InstallmentsSelect
+
+Root `div` plus a Base UI Select. Only the parts that stay inside the component root are reachable from a store's own `style` array by descendant variants (the same mechanism the radio surface's own rows use); the popup subtree — teleported to `<body>` — is not.
+
+| Component | Reachable from `style`? | What you style | Plausible classes |
+|---|---|---|---|
+| `InstallmentsSelect` (root `div`, `data-fs-installments`) | Yes | Positions the label + trigger | `flex flex-col gap-1` |
+| `data-fs-installments-control="select"` | Yes | Discriminates this surface from the radio one when a store styles both from one shared selector | — |
+| Empty / loading state (`data-fs-installments-state`) | Yes | Same neutral/skeleton treatment as `Installments` | `min-h-12 border border-dashed border-[#CCCCCC]` / `min-h-12 animate-pulse bg-[#F5F5F5]` |
+| Pending state (`data-fs-installments-state="pending"`) | Yes | Trigger visible but disabled while the persisted BIN settles | `opacity-50 pointer-events-none` |
+| Inline error (`data-fs-installments-error`) | Yes | Warning-toned alert text | `text-[12px] font-medium text-[#B00020]` |
+| Label (`data-fs-installments-label`) | Yes | The accessible-name text above the trigger | `text-[12px] text-[#666666]`, or `sr-only` to hide it visually |
+| Trigger (`data-fs-installments-trigger`) | Yes | The closed control's own box | `flex items-center justify-between border border-[#CCCCCC] rounded px-3 py-2` |
+| Value (`data-fs-installments-value`) | Yes | The selected label / placeholder text | `text-[14px] text-[#1A1A1A]` |
+| Icon (`data-fs-installments-icon`) | Yes | The `▾` glyph | `text-[#666666]` |
+| Option (`data-fs-installments-option`) | **No — portalled** | One row inside the open popup | not authorable from this page's `style` array today |
+| Option label (`data-fs-installments-option-label`) | **No — portalled** | An option's text | not authorable from this page's `style` array today |
+| Placing (`data-fs-installments-placing`) | Yes | Present while an order-placement sequence is in flight (T28) — the same hook and presence attribute name `Installments` uses (both surfaces read the shared engine's own `placing`); the root is also `inert` and `aria-disabled` at that point | `opacity-60 cursor-not-allowed` |
+
+Styled example (only the reachable parts):
+
+```json
+{
+  "installments-select": {
+    "type": "InstallmentsSelect",
+    "style": ["flex", "flex-col", "gap-1"]
+  }
+}
+```
+
+The popup's own visual defaults (spacing, hover, the selected-row treatment) come from the particle's own baseline styling, not from this page's `style` array — there is currently no platform mechanism for a store to restyle a portalled subtree's internals.
+
+---
+
+## Accessibility Contract
+
+**What the platform promises:** `Installments`' radio group and `InstallmentsSelect`'s combobox each
+carry a visible, programmatic accessible name (`legend`/`label`, both defaulting to `"Installments"`) —
+a screen-reader user hears what the rows are a choice *between*. An authored empty or whitespace-only
+value on either falls back to the default rather than shipping a nameless control. Each tier keeps its
+own accessible name/text from `installmentLabel`. `Installments`' group is a native `<fieldset>`/
+`<legend>` pair, visible to sighted and low-vision shoppers, not only `aria-label`. Keyboard:
+`Installments`' group is one Tab stop — Tab lands on the checked row, and the arrow keys move the
+checked row and change the selection. A default `:focus-visible` outline is painted from the
+platform's own stylesheet on every element these two components render directly — `Installments`'
+radio rows and `InstallmentsSelect`'s own trigger. `InstallmentsSelect`'s *portalled* option list
+carries the same selector defensively (`[data-fs-installments-option]:focus-visible`), but whether a
+browser ever gives a portalled option real focus, rather than driving the list with
+`aria-activedescendant` (which this selector would never match), is unverified — no jsdom test can
+answer it (open question, resolvable with one Storybook keyboard pass).
+
+**What the platform does not promise:** colour contrast. Both components expose `data-fs-*` hooks so a
+merchant can author contrast-compliant swatches, but neither measures or guarantees any contrast
+ratio — that is the merchant's theme, not this platform.
+
+---
+
+## Related
+
+- [[pricing]] — `PricingInstallments` / `PricingInstallmentPlans` render a PDP's *advertised* installment plans, never a *selection*; distinct data source, distinct concern, explicitly not reusable for either installment component.

package/dist/docs/my-account-profile.md

@@ -173,6 +173,7 @@ Add each field Control id to `profile-root`'s `children` array for the fields th
 - **Rendering a frame part or field Control outside `MyAccountProfileRoot`.** Every part except `Skeleton` `requiresContext: 'my-account-profile'` and throws otherwise.
 - **Giving a required Control's native input a `required` HTML attribute.** Requiredness is expressed only through the registered `validate` function (Decision 2 of SFS-3288/3289/3290); a native `required` attribute makes the browser block the form's `submit` event before the Root's own validation and focus logic ever runs.
 - **Hiding the `TaxIdControl` in the edit state when a CPF is already saved.** It must render a disabled, locked input instead — a field disappearing between view and edit reads as a bug (product-confirmed, 2026-09-03).
+- **Composing only the `mobilePhone` Control on a store whose shoppers check out.** The checkout reads its phone from `homePhone`, and it treats a profile without one as incomplete: a new cart imports only the email and drops the shopper's saved addresses. Compose a `PhoneControl` with `field: "homePhone"` whenever the store sells, alongside the mobile one if the page shows both.
 - **Adding a `showPhone`/`visible` boolean prop to a Control.** Presence is composition; a boolean visibility prop contradicts compose-or-omit and is out of scope for every Control in this group.
 
 ---

package/dist/docs/order-placed-payment-summary.md

@@ -0,0 +1,138 @@
+# OrderPlacedPaymentSummary
+
+**Category:** commerce
+**Purpose:** Read-only recap, on a post-purchase confirmation surface, of the card the shopper paid with — sourced from the settled order (`Query.order`) rather than the live order form. The only payment recap that keeps resolving after the order is placed.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Use these signals to detect that an OrderPlacedPaymentSummary block is present. Position on the page is irrelevant for detection — it can appear anywhere, in any orientation. The image is the source of truth for layout.
+
+An OrderPlacedPaymentSummary block, on an order-confirmation / "thank you" screen, contains any ONE of:
+
+- A short **line naming a card network** (e.g. "Visa", "Mastercard") optionally followed by **masked last four digits** (e.g. "•••• 1111"), optionally with a **custom card label/nickname** line below it (e.g. "Meu cartão pessoal").
+- A **non-card method's own name** (e.g. "Boleto Bancário"), with no masked digits at all.
+- An **inline alert/notice line** (visually a warning or error banner) saying the payment details could not be loaded, or that the order was split across sellers.
+- An **informational line** (visually plain, not a warning) saying no payment record is available.
+
+No copy is baked into this block beyond those lines — any surrounding "Payment" heading is host-page chrome, not part of this component.
+
+If the image shows this recap on an **in-checkout** surface (Order Review, still-live cart) instead, this is not the component — see [When NOT to use](#when-not-to-use).
+
+---
+
+## When to use
+
+- A post-purchase order-confirmation ("thank you") screen, to show the shopper the card/method their order was charged with.
+- Anywhere else that reads the settled order's payment recap by order group, after the order form itself may no longer exist.
+
+## When NOT to use
+
+- **The in-checkout Order Review step**, or any surface where the cart is still live → no component renders a payment recap in checkout. `Query.order` (this component's source) requires a settled `orderGroup`; it does not exist yet before the order is placed.
+- Letting the shopper pick or enter a card, or choose an installment → this component has no write affordance at all; see `PaymentSection` (card entry, installments, saved-card picker).
+- A settled order's shipping/billing address, items, or totals → out of scope; this component recaps only the payment method.
+- A **per-installment amount or interest rate** on the placed order → not deliverable from this data source; VTEX's settled-order payment record carries only the installment **count** and the settled **total**, never a per-installment amount or a rate (unlike the live order form). This component shows the count and total; it does not, and structurally cannot, show either of the other two.
+
+---
+
+## Composition
+
+`OrderPlacedPaymentSummary` is a single leaf component — no root, no required children, no sub-components:
+
+```
+OrderPlacedPaymentSummary
+```
+
+It requires no ancestor context and provides none — composable standalone on a confirmation page. For image-to-schema work, only include it when the image actually shows a payment recap on a confirmation-style screen.
+
+---
+
+## Components
+
+### OrderPlacedPaymentSummary
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `lastFourTemplate` | string | `"•••• {lastFour}"` | Rendered whenever the projection carries a last four digit — for both a saved and a freshly-entered card. |
+| `noPaymentRecordLabel` | string | `"Payment method not available"` | Shown when the order resolves but carries no projectable payment record (all of network/last-four/label are null). Informational — not an alert. |
+| `unresolvedOrderLabel` | string | `"Could not load the payment details"` | Shown, as an inline `role="alert"`, when the order group does not resolve to a settled order. |
+| `multiSellerNotice` | string | `"This order was split across {count} sellers; the payment summary does not cover split orders"` | Shown, as an inline `role="alert"`, for a split (multi-seller) order; `{count}` placeholder, omitted (token dropped, no literal "undefined"/"NaN") when the seller count is unknown. |
+| `installmentTemplate` | string | `"{count}x of {total}"` | Rendered whenever the projection carries an `installment` (count always present when it does); `{count}`/`{total}` placeholders — when the source carries the count but not enough to build a settled total from, everything between `{count}`'s own glued suffix (if any) and `{total}` is dropped together with the token itself (e.g. " of " in the shipped default), so the line reads "6x" rather than ending mid-sentence. A run glued directly to `{count}`, with no separating whitespace, is that count's own suffix rather than a connector, and is kept: `"{count}x {total}"` and `"{count}x{total}"` both degrade to "6x", never to a bare "6" or an empty line. This applies to the WHOLE run between the glued suffix and `{total}`, not just one word — a self-contained unit noun with no glued suffix (e.g. `"{count} parcelas de {total}"`) degrades to a bare "6", the same as a dangling preposition would, because no algorithm can tell the two apart (T31). Never a per-installment amount or interest rate — the source carries neither (see [When NOT to use](#when-not-to-use)). |
+
+**Data:** declares its own `fragment OrderPlacedPaymentSummaryData on Query` selecting `Query.order(orderGroup: $orderGroup)` — `network`, `lastFourDigits`, `label`, `installment { count total { amount currencyCode } }`. `$orderGroup` is resolved by the compiler from a route segment or page search param, never passed as a prop. `fetchStrategy: 'reactive'` — required so the compiler hoists the `PageReactiveDataRoot` this component reads the multi-seller signal through.
+
+**Resolution:** exactly one of five states renders, in this fixed precedence:
+
+1. **Multi-seller** — the reactive root's query error carries `extensions.code === 'UNSUPPORTED_MULTI_SELLER_ORDER'`. Wins over everything else, including a resolved recap, because a split order's one-seller card would otherwise be shown as if it were the whole payment.
+2. **In flight** — `loading` is true and no data has resolved yet. Renders nothing; never flashes an alert on first paint.
+3. **Unresolved** — the order group does not resolve (`order: null`) and the query is no longer in flight. Inline `role="alert"`.
+4. **No payment record** — the order resolves but `network`, `lastFourDigits`, and `label` are all null. Informational line, not an alert — `Query.order` treats this as a legitimate resolved state. Unchanged by the installment widening: an order carrying only an installment still renders this state, never a recap with just the installment line.
+5. **Recap** — the network (and last four, whenever present, and the saved-card label, whenever set, and the installment count + settled total, whenever the settled record reports one).
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "order-placed-payment-summary": {
+    "type": "OrderPlacedPaymentSummary",
+    "props": {}
+  }
+}
+```
+
+There is no surface-specific prop or variant — the same element renders the same recap wherever `Query.order` resolves for the page's `$orderGroup`.
+
+---
+
+## Common mistakes
+
+- **Using this component on an in-checkout surface (Order Review).** Its data source is the settled order, keyed on an order group that does not exist until the order is placed. No component renders a payment recap in checkout.
+- **Adding a per-installment amount or interest rate.** The settled-order source carries neither; only the installment count and settled total are shown.
+- **Treating "no payment record" the same as "unresolved".** They are visually and semantically distinct: the former is informational (the order is real, it just has nothing to project), the latter is an alert (the order group itself did not resolve).
+- **Aggregating a multi-seller order's cards.** A split order always renders the notice, never a per-seller breakdown.
+- **Expecting a full card number or CVV field.** The fragment structurally selects neither.
+
+---
+
+## Styling
+
+Single DOM root, with up to three text lines beneath it for the recap state (method, label, installment), or a single text line for every other visible state.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `OrderPlacedPaymentSummary` (root `div`) | Stacks the recap lines | `flex flex-col gap-[2px]` |
+| Method line (`data-fs-order-placed-payment-summary-method`) | The primary recap line — network + masked last four | `text-[14px] font-medium text-[#1A1A1A]` |
+| Label line (`data-fs-order-placed-payment-summary-label`) | Shopper-assigned card nickname — quieter, secondary | `text-[12px] text-[#666666]` |
+| Installment line (`data-fs-order-placed-payment-summary-installment`) | Installment count + settled total, whenever the settled record reports one | `text-[12px] text-[#666666]` |
+| No-record line (`data-fs-order-placed-payment-summary-no-record`) | Informational, not a warning | `text-[13px] text-[#666666]` |
+| Unresolved notice (`data-fs-order-placed-payment-summary-unresolved`, `role="alert"`) | Warning-toned notice | `text-[13px] font-medium text-[#B00020]` |
+| Multi-seller notice (`data-fs-order-placed-payment-summary-multi-seller`, `role="alert"`) | Warning-toned notice | `text-[13px] font-medium text-[#B00020]` |
+
+Styled example:
+
+```json
+{
+  "order-placed-payment-summary": {
+    "type": "OrderPlacedPaymentSummary",
+    "props": {},
+    "style": ["flex", "flex-col", "gap-[2px]"]
+  }
+}
+```
+
+There is no per-line styling hook exposed as separate schema elements — `OrderPlacedPaymentSummary` renders its own markup directly (no Root/particle split); style via the `data-fs-order-placed-payment-summary*` attribute hooks with compound swatches, per the `style-components` skill.
+
+---
+
+## Testing
+
+The correspondence between what `buildGatewayPaymentsRequest` submits to the gateway and what this recap renders — which submitted fields are shown, which are deliberately not, and why — is pinned as a correspondence-contract test in `order-placed-recap-parity.test.tsx` (same directory; not linked, since `build-docs.mjs` ships only `.md` files into the published `dist/docs/`), alongside this component's own `order-placed-payment-summary.test.tsx`.
+
+---
+
+## Related
+
+- [[identity-summary]] — closest structural precedent for a single-file, self-contained, reactive, self-gating summary that owns its own fragment rather than an ancestor's context.