@vtex/faststore 0.0.10 → 0.0.11

package/dist/docs/order-payment.md

@@ -44,16 +44,16 @@ No schema props. The heading and the bank-invoice method name are content.
 
 | Content field | Description |
 |---|---|
-| heading | Section heading. Blank falls back to the catalogue sentence |
+| heading | Section heading |
 | bankInvoiceName | Method name shown on a payment that carries a bank-invoice number or print URL |
 | empty | Sentence when the order has no payment |
 | methodPlaceholder | Sentence when the method name is missing |
-| installments | Installment line. Keep `{count}` and `{amount}` |
+| installments | Installment line, an ICU message with `count` and `amount` arguments |
 | redemptionCode | Label of the gift-card code |
 | bankInvoiceNumber | Label of the bank-invoice number |
 | bankInvoicePrint | Print-link sentence |
 
-A blank field keeps the catalogue sentence. Amounts, recorded method names, and the last four digits stay data.
+Every field but `bankInvoiceName` is an ICU message. A missing message renders empty and logs. Amounts, recorded method names, and the last four digits stay data.
 
 ## Data
 
@@ -64,20 +64,22 @@ The fragment reads `customerOrder(id: $orderId)`: `allowCancellation` and, for e
 Style the region, the heading, each row, and each fact through their hooks. Inline classes only.
 
 - `data-fs-order-payment` — the region. `flex flex-col gap-[12px]`.
-- `data-fs-order-payment-heading` — the heading. `text-[18px] font-semibold text-[#111827]`.
+- `data-fs-order-payment-heading` — the heading. `text-[18px] font-semibold text-[var(--color-text)]`.
 - `data-fs-order-payment-empty` — the sentence shown when the order has no payment.
 - `data-fs-order-payment-list` — the list of rows. `flex flex-col gap-[8px]`.
 - `data-fs-order-payment-item` — one payment. `flex flex-wrap items-center gap-[8px] rounded-[8px] border border-[#E5E7EB] p-[12px]`.
 - `data-fs-order-payment-item-bank-invoice` — present on a bank-invoice row.
 - `data-fs-order-payment-method` — the icon and the name. `flex items-center gap-[8px]`.
 - `data-fs-order-payment-icon` — the brand mark, only for a known method. `h-[24px] w-[36px]`.
-- `data-fs-order-payment-method-name` — the method name. `text-[14px] font-medium text-[#111827]`.
-- `data-fs-order-payment-amount` — the full amount. `text-[14px] text-[#374151]`.
+- `data-fs-order-payment-method-name` — the method name. `text-[14px] font-medium text-[var(--color-text)]`.
+- `data-fs-order-payment-amount` — the full amount. `text-[14px] text-[var(--color-text-secondary)]`.
 - `data-fs-order-payment-installments` — the installment sentence. `text-[14px] text-[#6B7280]`.
-- `data-fs-order-payment-redemption-code`, `data-fs-order-payment-bank-invoice-number` — a labeled fact. Inside each, `data-fs-order-payment-label` and `data-fs-order-payment-value`. `text-[14px] text-[#374151]`.
+- `data-fs-order-payment-redemption-code`, `data-fs-order-payment-bank-invoice-number` — a labeled fact. Inside each, `data-fs-order-payment-label` and `data-fs-order-payment-value`. `text-[14px] text-[var(--color-text-secondary)]`.
 - `data-fs-order-payment-print` — the print link. `text-[14px] font-medium text-[#1D4ED8]`.
 - `data-fs-order-payment-skeleton`, `data-fs-order-payment-skeleton-row` — the loading placeholder.
 
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-text": "#111827", "--color-text-secondary": "#374151"}`. A color used once stays a hex.
+
 ## Canonical schema
 
 ```json

package/dist/docs/order-placed-date.md

@@ -39,7 +39,7 @@ Fragment on `Query`: `customerOrder(id: $orderId) { id placedAt }`. The generato
 
 ### OrderPlacedDate
 
-No schema props. The label is content (`order-placed-date`). A blank field keeps `fs/order.placed-at`.
+No schema props. The label is an ICU message in content (`order-placed-date.label`). A missing one renders empty and logs.
 
 ## Styling
 

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

@@ -27,7 +27,7 @@ If the image shows this recap on an **in-checkout** surface (Order Review, still
 ## 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.
+- Anywhere else that reads the settled order's payment recap by the order's Node id, after the order form itself may no longer exist.
 
 ## When NOT to use
 
@@ -54,21 +54,24 @@ It requires no ancestor context and provides none — composable standalone on a
 
 ### OrderPlacedPaymentSummary
 
-| Prop | Type | Default | Notes |
+No props of its own. Its copy is the content type `order-placed-payment-summary`, every field an ICU message read only from `$content`; an unauthored one renders empty and logs `message.missing`. A store without CMS authors the fields on the element.
+
+| Message field | Arguments | Source | 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 (network and last four are both 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. |
-| `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)). |
+| `lastFourTemplate` | `lastFour` | `"•••• {lastFour}"` | ICU message with a `lastFour` argument. Rendered whenever the projection carries a last four digit — for both a saved and a freshly-entered card. |
+| `noPaymentRecordLabel` | — | `"Payment method not available"` | Shown when the order resolves but carries no projectable payment record (network and last four are both null). Informational — not an alert. |
+| `unresolvedOrderLabel` | — | `"Could not load the payment details"` | Shown, as an inline `role="alert"`, when the order group does not resolve to a settled order. |
+| `installmentTemplate` | `count`, `total` | `"{count}x total {total}"` | ICU message with `count` and `total` arguments, rendered whenever the projection carries an `installment` with a settled total. The total is the settled payment's whole value, which is why the source says "total" instead of "of". Never a per-installment amount or interest rate — the source carries neither (see [When NOT to use](#when-not-to-use)). |
+| `installmentCountTemplate` | `count` | `"{count}x"` | ICU message with a `count` argument, rendered instead of `installmentTemplate` when the source carries the count but not enough to build a total from, so the line never ends mid-sentence. |
 
-**Data:** declares its own `fragment OrderPlacedPaymentSummaryData on Query` selecting `Query.order(orderGroup: $orderGroup)` — `network`, `lastFourDigits`, `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 its loading state through.
+**Data:** declares its own `fragment OrderPlacedPaymentSummaryData on Query` selecting `Query.order(id: $orderId)` — `reference`, `network`, `lastFourDigits`, `installment { count total { amount currencyCode } }`. `$orderId` is the order's Node id (`ID!`), 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 its loading state through.
 
 **Resolution:** exactly one of four states renders, in this fixed precedence. A purchase split across sellers is read whole, so no error has a state of its own: a failed read leaves `order: null` and renders the unresolved notice.
 
 1. **In flight** — `loading` is true and no data has resolved yet. Renders nothing; never flashes an alert on first paint.
 2. **Unresolved** — the order group does not resolve (`order: null`) and the query is no longer in flight. Inline `role="alert"`.
 3. **No payment record** — the order resolves but `network` and `lastFourDigits` are both 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.
-4. **Recap** — the network (and last four, whenever present, and the installment count + settled total, whenever the settled record reports one).
+4. **Recap** — the network (and last four, whenever present, and the installment count + settled total, whenever the settled record reports one). When the settled record carries a network but no last four, and the shopper typed a new card in this tab session, the last four digits they typed fill the gap (kept in memory only, matched to the order by `reference`); the settled record's own last four always wins, and a reload or a new tab shows only what the settled record carries. The digits are absent from the server render and appear when the browser hydrates, with no hydration warning.
 
 ---
 
@@ -78,12 +81,18 @@ It requires no ancestor context and provides none — composable standalone on a
 {
   "order-placed-payment-summary": {
     "type": "OrderPlacedPaymentSummary",
-    "props": {}
+    "props": {
+      "lastFourTemplate": "•••• {lastFour}",
+      "noPaymentRecordLabel": "Payment method not available",
+      "unresolvedOrderLabel": "Could not load the payment details",
+      "installmentTemplate": "{count}x total {total}",
+      "installmentCountTemplate": "{count}x"
+    }
   }
 }
 ```
 
-There is no surface-specific prop or variant — the same element renders the same recap wherever `Query.order` resolves for the page's `$orderGroup`.
+There is no surface-specific prop or variant — the same element renders the same recap wherever `Query.order` resolves for the page's `$orderId`.
 
 ---
 
@@ -104,10 +113,12 @@ Single DOM root, with up to two text lines beneath it for the recap state (metho
 | 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]` |
-| 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]` |
+| Method line (`data-fs-order-placed-payment-summary-method`) | The primary recap line — network + masked last four | `text-[14px] font-medium text-[var(--color-ink)]` |
+| Installment line (`data-fs-order-placed-payment-summary-installment`) | Installment count + settled total, whenever the settled record reports one | `text-[12px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]` |
+| No-record line (`data-fs-order-placed-payment-summary-no-record`) | Informational, not a warning | `text-[13px] text-[color-mix(in_srgb,var(--color-ink)_60%,transparent)]` |
+| Unresolved notice (`data-fs-order-placed-payment-summary-unresolved`, `role="alert"`) | Warning-toned notice | `text-[13px] font-medium` |
+
+A status color is a `visualIdentity` feedback role of the foundation: when the store declares them, color the error row `text-[var(--color-feedback-danger)]`, the success row `text-[var(--color-feedback-success)]` and the notice row `text-[var(--color-feedback-warning)]`, never with a hex.
 
 Styled example:
 
@@ -127,7 +138,9 @@ There is no per-line styling hook exposed as separate schema elements — `Order
 
 ## 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`.
+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`, which also covers the carried last four: it fills the gap only for the matching `reference`, the settled value wins, and the server markup omits it.
+
+`packages/faststore/src/matter/payment/confirmation-last-four-flow.test.tsx` drives the real `PlaceOrder`, place-order hook, submission registry and card-capture provider with a typed 16-digit number and finds its digits only in the gateway call and the in-memory carrier: not in a navigation, a console call, a `fetch`, an Apollo operation or a tracking call. `packages/faststore/src/sdk/payment/confirmation-last-four.test.ts` scans the carrier's own source against the card-field pattern.
 
 ---
 

package/dist/docs/order-placed.md

@@ -22,7 +22,7 @@ Section titles ("Customer information", "Summary") and the boxes around the bloc
 
 ## When to use
 
-- The order confirmation page, keyed on the order group from the route (`/checkout/order-placed/[orderGroup]`).
+- The order confirmation page, keyed on the order Node id from the route (`/checkout/order-placed/[orderId]`).
 - Under `OrderPlacedRoot`, any block that reads the placed order: the blocks below and the payment recap.
 
 ## When NOT to use
@@ -70,9 +70,17 @@ Reads the order and renders exactly one state, in this order:
 | Unresolved | The read settled with no order: an upstream or network error, or no order for the group | `unresolvedOrderLabel`, `role="alert"` |
 | Order | The order resolved | Its children |
 
-A refusal also arrives with `order: null`, which is why it is checked first. Neither message retries; a reload reads the order again. The server render and the first browser render show the skeleton: the browser always reads the order with the shopper's cookies.
+A refusal also arrives with `order: null`, which is why it is checked first. Neither message retries; a reload reads the order again. The server render and the first browser render show the skeleton: the browser always reads the order with the shopper's cookies. A refusal on the server render is never kept as an absent order: the browser asks again, and a later real answer renders the children after a remount.
 
-| Prop | Default |
+The route segment is the order's Node id: `Order.id`, which `PlaceOrder` receives as `orderNodeId` and writes into the URL percent-encoded (`...%3D` for `...=`). The API takes the id as written and after one percent-decode. Which message a bad id gets depends on the shopper's cookies:
+
+- Without the two transaction cookies (a link opened in another browser, or the cookies expired), every id gets the same refusal, so the page cannot tell a real order from an invented one.
+- With the cookies, an id that is malformed, belongs to another type or is a raw order group resolves to no order, with no error and no call to the order system, and the page shows `unresolvedOrderLabel`.
+- A VTEX 401 or 403 on a well-formed id reads like the refusal without cookies. A VTEX 404 resolves to no order.
+
+Content type `order-placed-root`:
+
+| Message field | Source |
 | --- | --- |
 | `refusedOrderLabel` | "This order can no longer be shown here" |
 | `unresolvedOrderLabel` | "Could not load this order" |
@@ -81,9 +89,11 @@ A refusal also arrives with `order: null`, which is why it is checked first. Nei
 
 ### OrderPlacedStatus
 
-The payment outcome. `APPROVED`, `PENDING` and `DENIED` render a title and a message; `UNKNOWN` renders nothing, so the page shows the order without asserting an outcome. A payment under anti-fraud review reads as pending. Each title and message is a prop authored in the page; a blank value leaves its line out. The banner declares no content model, so a page in a CMS-bound store needs no content entry for it: a content model would require a `content.entryId` seeded with `sukima cms publish`. It can return, for editing from the CMS admin, once the page has a seeded entry. An `Icon` child renders on every outcome, so never compose one that implies success.
+The payment outcome. `APPROVED`, `PENDING` and `DENIED` render a title and a message; `UNKNOWN` renders nothing, so the page shows the order without asserting an outcome. A payment under anti-fraud review reads as pending. Each title and message is a message field; an unauthored one leaves its line out and logs `message.missing`. An `Icon` child renders on every outcome, so never compose one that implies success.
 
-| Prop | Default |
+Content type `order-placed-status`:
+
+| Message fields | Source |
 | --- | --- |
 | `approvedTitle` / `approvedMessage` | "Your order is confirmed" / "Your payment was approved." |
 | `pendingTitle` / `pendingMessage` | "We're confirming your payment" / "Your order was placed, and its payment is still being processed or reviewed." |
@@ -91,19 +101,19 @@ The payment outcome. `APPROVED`, `PENDING` and `DENIED` render a title and a mes
 
 ### OrderPlacedReference
 
-The order group, one per purchase even when it was split across sellers, under `template` ("Order #{reference}"). Plain text, so it can be selected and copied.
+The order group, one per purchase even when it was split across sellers, under the `template` message of content type `order-placed-reference` (source "Order #{reference}", with a `reference` argument). Plain text, so it can be selected and copied.
 
 ### OrderPlacedCustomer
 
-The customer as the order recorded them: name (first and last name), email, phone and document, one row each, a row left out when its value is empty. Renders nothing when the order has no customer. Values show as the order system returns them, masked included (`J*** D***`). Labels: `nameLabel`, `emailLabel`, `phoneLabel`, `documentLabel`.
+The customer as the order recorded them: name (first and last name), email, phone and document, one row each, a row left out when its value is empty. Renders nothing when the order has no customer. Values show as the order system returns them, masked included (`J*** D***`). Labels: the messages `nameLabel`, `emailLabel`, `phoneLabel`, `documentLabel` of content type `order-placed-customer` (sources "Name", "Email", "Phone", "Document").
 
 ### OrderPlacedTotals
 
 One row per money line in the order the API returns them, then the total row, each formatted in the line's own currency and the storefront locale.
 
-- `Items`, `Shipping`, `Discounts` and `Tax` take `itemsLabel`, `shippingLabel`, `discountsLabel` and `taxLabel`; any other line (a custom tax) shows its own name.
+- `Items`, `Shipping`, `Discounts` and `Tax` take the messages `itemsLabel`, `shippingLabel`, `discountsLabel` and `taxLabel`, and the total row takes `totalLabel` (content type `order-placed-totals`; sources "Subtotal", "Shipping", "Discounts", "Tax", "Total"); any other line (a custom tax) shows its own name.
 - A zero discount line is left out; a discount shows as returned, negative.
-- `shippingZeroLabel` (e.g. "Free") replaces a zero shipping value.
+- `shippingZeroLabel` (e.g. "Free"), a plain prop with no default, replaces a zero shipping value.
 - No total row when the order has no total, rather than a partial sum.
 
 ### OrderPlacedDeliveryList
@@ -115,11 +125,26 @@ Renders its child, one `OrderPlacedDeliveryGroup`, once per delivery of the orde
 One delivery:
 
 - **Method**: the shipping option's name; left out when the order system sent none.
-- **Promise**: `dateTemplate` ("Arrives by {date}") with the date in the storefront locale and the store's timezone, when the order system dated the delivery. Otherwise the sentence the checkout's delivery step showed for the estimate ("in 2 business days", "arrives today"), from the message catalog.
-- **Item count**: `itemCountOneTemplate` ("{count} item") or `itemCountTemplate` ("{count} items"). It counts lines, one per item, as the API does.
+- **Promise**: `dateTemplate` ("Arrives by {date}") with the date in the storefront locale and the store's timezone, when the order system dated the delivery. Otherwise the sentence the checkout's delivery step showed for the estimate ("in 2 business days", "arrives today"), from its `$content`.
+- **Item count**: `itemCountTemplate` ("{count, plural, one {# item} other {# items}}"), an ICU plural by the locale's rule. It counts lines, one per item, as the API does.
 - **Pickup point**: `pickupPointTemplate` ("Pickup at {name}") for a pickup.
 - **Address**: provided to the `AddressSummary*` children: the shipping address, or the pickup point's for a pickup, masked as the order system returns it. A delivery without one renders no address, and its items still render.
 
+Every sentence is an ICU message field of its `$content`. The estimate sentences are formatted only when the order carries no date. A missing message renders empty (no promise for an estimate) and logs an error.
+
+Content type `order-placed-delivery-group`:
+
+| Content field | Description |
+|---|---|
+| dateTemplate | The dated promise, a `date` argument (formatted string) |
+| itemCountTemplate | The item count, a plural on `count` |
+| pickupPointTemplate | The pickup point, a `name` argument |
+| today | Estimate of zero, in any unit |
+| inBusinessDays | Estimate in business days, a plural on `days` |
+| inDays | Estimate in days, a plural on `days` |
+| inHours | Estimate in hours, a plural on `hours` |
+| inMinutes | Estimate in minutes, a plural on `minutes` |
+
 ### OrderPlacedItemRow
 
 Renders the cart's own `CartItemRoot` once per item of the delivery, so the cart's leaves composed under it present the item as the cart did. Compose the read-only leaves: `CartItemImage`, `-ProductLink`, `-Name`, `-Variant`, `-Sku`, `-Price`, `-ListPrice`, `-DiscountPercentage`, `-LineTotal`, `-OwnTotal`, `-AggregateTotal`, `-QuantityValue`, `-Gift`. Outside a delivery it renders nothing. `useOrderPlacedItem()` returns the nearest item.
@@ -142,10 +167,16 @@ An item's add-on services nested under it, with the cart's own composition marku
     },
     "children": ["order-status", "order-reference", "deliveries", "order-customer", "order-totals", "order-payment"]
   },
-  "order-status": { "type": "OrderPlacedStatus" },
+  "order-status": {
+    "type": "OrderPlacedStatus",
+    "props": { "approvedTitle": "Your order is confirmed", "approvedMessage": "Your payment was approved." }
+  },
   "order-reference": { "type": "OrderPlacedReference", "props": { "template": "Order #{reference}" } },
-  "order-customer": { "type": "OrderPlacedCustomer" },
-  "order-totals": { "type": "OrderPlacedTotals", "props": { "shippingZeroLabel": "Free" } },
+  "order-customer": {
+    "type": "OrderPlacedCustomer",
+    "props": { "nameLabel": "Name", "emailLabel": "Email", "phoneLabel": "Phone", "documentLabel": "Document" }
+  },
+  "order-totals": { "type": "OrderPlacedTotals", "props": { "shippingZeroLabel": "Free", "totalLabel": "Total" } },
   "deliveries": { "type": "OrderPlacedDeliveryList", "children": ["delivery-group"] },
   "delivery-group": {
     "type": "OrderPlacedDeliveryGroup",
@@ -173,6 +204,8 @@ An item's add-on services nested under it, with the cart's own composition marku
 
 ## Common mistakes
 
+- **Linking to the page with a raw order group** (`/checkout/order-placed/<group>`) → the segment is read as a Node id, so the page shows `unresolvedOrderLabel`. `PlaceOrder` reaches the page through the page reference `{ "standard": "order-placed" }` and fills `orderId` with the `orderNodeId`; a string `successHref` that carries a `{token}` is refused.
+- **Leaving `metadata.referrer` off the page** → the URL carries the Node id, which anyone can decode to the order group, and a same-origin request such as `/api/graphql` would send it in `Referer`. Declare `"referrer": "strict-origin"` in the page's `metadata`, as the example stores' order-placed pages do. The compiler does not require it; `packages/sukima/crates/sukima-core/tests/examples.rs` fails when an example order-placed page, recognised by `standard: "order-placed"` or by an `order-placed` segment followed by a dynamic one, omits it.
 - **Composing a leaf outside `OrderPlacedRoot`** → it throws. Every block here requires the `order-placed` context.
 - **Composing `CartTotalizerLine` or `IdentitySummary*` on this page** → they read the cart and the live profile, not the placed order.
 - **An `Icon` that implies success under `OrderPlacedStatus`** → it also shows on a denied payment.
@@ -215,6 +248,8 @@ Each row of the customer and the totals is a `div` holding one `dt` and one `dd`
 
 `order-placed.test.tsx` covers the root's four states and their precedence, each outcome and its authored copy, the reference template, the customer rows and the totals' labels, zero lines and null total.
 
+`order-placed-chain.test.tsx` runs a scripted answer through a real `ApolloClient`, `fetchPageData`, `PageReactiveDataRoot` and `OrderPlacedRoot`: both shapes of a refusal (`order: null` beside an `UNAUTHORIZED` error, and `data: null`) render the refused label and not the children, a later real order renders them, a miss with no error renders the unresolved label, and a real order renders neither label.
+
 `order-placed-deliveries.test.tsx` covers one group per delivery and every item exactly once, the dated and relative promises in the store's timezone, the channel, the pickup point and a missing address, every shipped cart leaf against the same cart line, the nested add-ons, and two checks that keep the list's fragment in step with the cart's.
 
 ---

package/dist/docs/order-progress.md

@@ -41,7 +41,7 @@ Child order is not applicable. The stage order is fixed.
 
 ### OrderProgress
 
-No schema props. Stage names, state sentences, and the accessible name are content (`order-progress`). A blank field keeps the message catalogue. `failed` and `not-applicable` render no sentence.
+No schema props. Stage names, state sentences, and the accessible name are ICU messages in content (`order-progress`). A missing one renders empty and logs. `failed` and `not-applicable` render no sentence.
 
 ## Data
 

package/dist/docs/order-status-badge.md

@@ -26,7 +26,7 @@ The image is the source of truth for layout.
 
 ## Composition
 
-`OrderStatusBadge` is a leaf. It renders one sentence and takes no children. A `messages` entry replaces the catalogue sentence for that label. The order details header fills `messages` from its content entry. The order list passes none, so it stays on the catalogue.
+`OrderStatusBadge` is a leaf. It renders one sentence and takes no children. It has no content of its own: the component that owns the status copy formats it and passes `messages`. The order details header and the order list fill `messages` from their own `status*` message fields.
 
 ```text
 OrderStatusBadge
@@ -41,10 +41,9 @@ No schema props. The caller passes these at runtime:
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `state` | `'ongoing' \| 'completed' \| 'cancelled'` | — | Completion view. Sets `data-fs-order-status-badge-state`. Does not select the sentence. |
-| `label` | string | — | Completion label id. Selects the catalogue sentence. Any other string renders the placeholder. |
+| `label` | string | — | Completion label id. Selects the sentence from `messages`. Any other string renders the placeholder. |
 | `tone` | `'neutral' \| 'progress' \| 'success' \| 'danger'` | — | Sets `data-fs-order-status-badge-tone`. Does not select the sentence. |
-
-The catalogue ids are `fs/order-status.cancelled`, `fs/order-status.cancellation-requested`, `fs/order-status.in-progress`, `fs/order-status.delivered`, `fs/order-status.shipped`, `fs/order-status.ready-for-pickup`, `fs/order-status.collected`, and `fs/order-status.placeholder`.
+| `messages` | `OrderStatusMessages` | — | Required. The formatted sentence for each label key: `cancelled`, `cancellation-requested`, `in-progress`, `delivered`, `shipped`, `ready-for-pickup`, `collected`, and `placeholder`. |
 
 ---
 
@@ -57,7 +56,17 @@ The catalogue ids are `fs/order-status.cancelled`, `fs/order-status.cancellation
     "props": {
       "state": "completed",
       "label": "delivered",
-      "tone": "success"
+      "tone": "success",
+      "messages": {
+        "cancelled": "Canceled",
+        "cancellation-requested": "Cancellation requested",
+        "in-progress": "In progress",
+        "delivered": "Delivered",
+        "shipped": "Shipped",
+        "ready-for-pickup": "Ready for pickup",
+        "collected": "Collected",
+        "placeholder": "Status unavailable"
+      }
     },
     "style": [
       "inline-flex items-center rounded-full px-[8px] py-[2px] text-[12px] font-medium bg-[#DCFCE7] text-[#14532D]"
@@ -69,7 +78,7 @@ The catalogue ids are `fs/order-status.cancelled`, `fs/order-status.cancellation
 ## Common mistakes
 
 - **`StatusBadge`.** The correct name is `OrderStatusBadge`.
-- **Passing an OMS code or `statusDescription` as the text.** Pass `label` as a completion label id. The catalogue supplies the sentence.
+- **Passing an OMS code or `statusDescription` as the text.** Pass `label` as a completion label id. `messages` supplies the sentence.
 - **Nesting a label inside `OrderStatusBadge`.** It does not render children.
 
 ---
@@ -80,12 +89,14 @@ The particle sets `data-fs-badge`, `data-fs-order-status-badge`, `data-fs-order-
 
 | Component | What you style | Plausible classes |
 |---|---|---|
-| `OrderStatusBadge` | Pill label. Pick the background and text from the tone. | `inline-flex items-center rounded-full px-[8px] py-[2px] text-[12px] font-medium bg-[#DCFCE7] text-[#14532D]` |
+| `OrderStatusBadge` | Pill label. Pick the background and text from the tone. | `inline-flex items-center rounded-full px-[8px] py-[2px] text-[12px] font-medium bg-[var(--color-green-surface)] text-[var(--color-green)]` |
+
+Tone pairs that meet WCAG AA: neutral `bg-[#F3F4F6] text-[#1F2937]`, progress `bg-[#DBEAFE] text-[#1E3A8A]`, success `bg-[var(--color-green-surface)] text-[var(--color-green)]`, danger `bg-[#FEE2E2] text-[#7F1D1D]`.
 
-Tone pairs that meet WCAG AA: neutral `bg-[#F3F4F6] text-[#1F2937]`, progress `bg-[#DBEAFE] text-[#1E3A8A]`, success `bg-[#DCFCE7] text-[#14532D]`, danger `bg-[#FEE2E2] text-[#7F1D1D]`.
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-green-surface": "#DCFCE7", "--color-green": "#14532D"}`. A color used once stays a hex.
 
 ---
 
 ## Related
 
-- [[badge]] — generic label. `OrderStatusBadge` composes it and replaces children with the catalogue sentence.
+- [[badge]] — generic label. `OrderStatusBadge` composes it and replaces children with the sentence from `messages`.

package/dist/docs/order-summary.md

@@ -37,12 +37,12 @@ OrderSummary
 
 ### OrderSummary
 
-No schema props. Every line the order carries renders, in the order the API returned them. The total row is the API's `total`; the component does not add the lines up. The heading, the grand total, and the labels for `Items`, `Shipping`, `Discounts`, `Tax`, `Change`, and `Interest` are content (`order-summary`). A blank field keeps the message catalogue. Any other id shows its upstream `name`. Interest is a total the read appends, not a line this component calculates.
+No schema props. Every line the order carries renders, in the order the API returned them. The total row is the API's `total`; the component does not add the lines up. The heading, the grand total, and the labels for `Items`, `Shipping`, `Discounts`, `Tax`, `Change`, and `Interest` are ICU messages in content (`order-summary`). A missing one renders empty and logs. Any other id shows its upstream `name`. Interest is a total the read appends, not a line this component calculates.
 
 ## Styling
 
 - `data-fs-order-summary` — the region. `flex flex-col gap-[8px]`.
-- `data-fs-order-summary-heading` — the visible title. Content wins; a blank field keeps `fs/order.totals.heading`.
+- `data-fs-order-summary-heading` — the visible title, from the `heading` message.
 - `data-fs-order-summary-lines` — the description list.
 - `data-fs-order-summary-line` — one total row. `flex justify-between`.
 - `data-fs-order-summary-line-id` — the total id (`Items`, `Shipping`, `Discounts`, …), for styling one row.

package/dist/docs/order-tracking-link.md

@@ -0,0 +1,58 @@
+# OrderTrackingLink
+
+**Category:** navigation
+**Purpose:** Offers each tracking address the order kept, so the shopper can follow a delivery.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A "Track package" link inside a delivery, near its estimate or its address.
+- With several addresses in one delivery, the links are numbered ("Track package 1", "Track package 2").
+- No status, no money, no product.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- Inside `OrderDeliveryGroup`, so each delivery shows only its own addresses.
+- Outside the group, to list every delivery's addresses, one group per option.
+
+## When NOT to use
+
+- For the order status → `OrderProgress` and `OrderDetailsHeader` own that.
+- For a link the merchant authors by hand → use a navigation link.
+
+---
+
+## Composition
+
+```text
+OrderDeliveryGroup
+└── OrderTrackingLink
+```
+
+Inside a group it shows only that option. It does not choose its place.
+
+## Data
+
+Fragment on `Query`: `customerOrder(id: $orderId) { progress { cancelled } deliveryOptions { trackingLinks } }`. The generator binds `$data` to that root field.
+
+- One address uses the label as is. Several add their position.
+- Each address opens in a new tab with `rel="noopener noreferrer"`.
+- An address the browser would execute (`javascript:`) is dropped.
+- A cancelled order still shows its addresses.
+- The component renders nothing when no address remains.
+
+## Components
+
+### OrderTrackingLink
+
+No schema props. The label is an ICU message in the `order-tracking-link` content model (`label`). A missing one renders empty and logs.
+
+## Styling
+
+- `data-fs-order-tracking-link` — the root.
+- `data-fs-order-tracking-link-group` — the list of one option's addresses.
+- `data-fs-order-tracking-link-anchor` — one link.
+- `data-fs-order-tracking-link-skeleton` — the loading placeholder.

package/dist/docs/payment-method-badges.md

@@ -140,6 +140,8 @@ and every other icon in that store re-resolves through the fallback default with
 
 **Data:** reads `usePayment()`'s method list; declares no fragment of its own. Reads the section's **unfiltered** list — every method the store returns, regardless of the section's `group` — not the group-scoped list `PaymentMethodList` and `CardEntry` read. A wallet method outside the default credit-card group still shows here, which is why this strip and the picker can show different sets on the same page.
 
+The strip lists methods in the order form's order. The section's `groupOrder` orders only `PaymentMethodList`, so a merchant who puts Pix first in the picker still sees the strip in the order form's order. `AcceptedPaymentMethodBadges` reads no section context, so it cannot follow the order.
+
 **Writes:** none. No action, no selection, no draft.
 
 ### AcceptedPaymentMethodBadges
@@ -196,7 +198,7 @@ and every other icon in that store re-resolves through the fallback default with
 - **Placing `PaymentMethodBadges` outside a payment root.** Like every payment leaf, it requires a `PaymentSectionRoot` or `PaymentSectionController` ancestor and fails the build otherwise. Placing it on a cart page is exactly this mistake — use `AcceptedPaymentMethodBadges` there instead.
 - **Adding a `PaymentSectionRoot` to a cart page just to host `PaymentMethodBadges` there.** Don't — that drags in a submission provider and a write action namespace that do not belong on a cart page. `AcceptedPaymentMethodBadges` needs no such root at all.
 - **Expecting `group`/`groupName` scoping on `AcceptedPaymentMethodBadges`.** There is no such prop on either component — both read the section's/read-model's unfiltered list, on purpose (a scoped strip could never show that a wallet method was enabled or disabled).
-- **Expecting brand-accurate multicolor marks.** The glyphs are single-colour sprite symbols that inherit `currentColor`; literal brand colours are not reachable through either component (see Styling).
+- **Expecting every glyph to recolour with the text colour.** Ten of the eleven glyphs are single-colour sprite symbols that carry `fill="currentColor"` and follow the swatch's `text-*`. `elo-card` is the exception: its three arcs keep fixed brand fills (`#fc0`, `#00a0de`, `#ec3413`), and its "elo" wordmark carries no `fill` at all, so it takes the CSS `fill` inherited from the `<svg>`, which is black unless the swatch sets `fill-current` on `data-fs-payment-method-badge-icon`. Without it the wordmark is black on a dark section. Literal brand colours for the other glyphs are not reachable through either component (see Styling).
 
 ---
 
@@ -207,10 +209,10 @@ and every other icon in that store re-resolves through the fallback default with
 | Component | What you style | Plausible classes |
 |---|---|---|
 | `PaymentMethodBadges` / `AcceptedPaymentMethodBadges` (root `div`) | Stacks the heading over the strip | `flex flex-col gap-[12px]` |
-| `data-fs-payment-method-badges-heading` | The strip heading | `text-[14px] font-bold uppercase text-[#1a1a1a]` |
+| `data-fs-payment-method-badges-heading` | The strip heading; leave `text-*` off so it takes the section's colour | `text-[14px] font-bold uppercase` |
 | `data-fs-payment-method-badges-list` | The badge row, wrapping on narrow screens | `flex flex-wrap items-center gap-[8px] list-none p-0 m-0` |
-| `data-fs-payment-method-badge` | The box one badge occupies | `flex items-center` |
-| `data-fs-payment-method-badge-icon` | The glyph, sized consistently across the row | `w-[32px] h-[20px] text-[#1a1a1a]` |
+| `data-fs-payment-method-badge` | The box one badge occupies | `flex items-center border border-current/25` |
+| `data-fs-payment-method-badge-icon` | The glyph, sized consistently across the row | `w-[32px] h-[20px] text-inherit fill-current` |
 
 State hooks worth styling:
 
@@ -218,6 +220,8 @@ State hooks worth styling:
 
 The list carries an explicit `role="list"`. Keep it: WebKit drops the implicit list role from a `<ul>` whose computed `list-style` is `none`, and `list-none` is exactly what the strip needs.
 
+Colour comes from the section, not from the strip. The component cannot know the background it sits on, and no dark-mode switch exists in the repo, so the reference swatch (`accepted-badges` in `examples/store-brandless/pages/checkout/page.json`) names no palette colour: the glyph is `text-inherit` plus `fill-current`, the badge border is `border-current/25`, and the heading inherits. The strip is as legible as the text colour the merchant chose for that section; a low-contrast section text gives a low-contrast strip. The Storybook stories `OnLightBackground` and `OnDarkBackground` render every mapped glyph through the same classes (`BADGE_SWATCH`), and a unit test keeps them equal to the brandless node.
+
 A method whose name maps to no glyph renders its name as plain text in place of the icon — style that case through `data-fs-payment-method-badge` itself (font, colour); there is no separate icon hook on a text-only badge.
 
 Styled example:
@@ -234,6 +238,28 @@ Styled example:
 
 ---
 
+## Audit
+
+What each mapped key renders and how it behaves on a light and on a dark section with the swatch above. `Source` and `Colour model` are read from `packages/sukima/crates/sukima-icons/src/reference.rs` and `base_dialect.json`. `Guideline URL` and `Verdict` (does the network's brand guideline permit a one-colour rendition) are recorded by the reviewer of the PR that changes this table; until then they read `pending reviewer`.
+
+| Method key | Icon | Source | Colour model | Light / dark with the swatch | Guideline URL | Verdict |
+|---|---|---|---|---|---|---|
+| `visa` | `visa` | simple-icons | `currentColor` | follows section text | pending reviewer | pending reviewer |
+| `mastercard` | `mastercard` | simple-icons | `currentColor` | follows section text | pending reviewer | pending reviewer |
+| `amex`, `americanexpress` | `amex` | simple-icons | `currentColor` | follows section text | pending reviewer | pending reviewer |
+| `diners`, `dinersclub` | `diners` | simple-icons | `currentColor` | follows section text | pending reviewer | pending reviewer |
+| `elo` | `elo-card` | logos | 3 fixed fills plus 1 unfilled path | arcs fixed; wordmark follows `fill-current` | pending reviewer | pending reviewer |
+| `paypal` | `paypal` | simple-icons | `currentColor` | follows section text | pending reviewer | pending reviewer |
+| `googlepay` | `google-pay` | simple-icons | `currentColor` | follows section text | pending reviewer | pending reviewer |
+| `pix` | `pix` | simple-icons | `currentColor` | follows section text | pending reviewer | pending reviewer |
+| `stripe` | `stripe` | simple-icons | `currentColor` | follows section text | pending reviewer | pending reviewer |
+| `discover` | `discover` (in the dialect, not mapped) | simple-icons | `currentColor` | not rendered; the key mapping is PEXP-1994 | n/a | n/a |
+| `apple-pay` | `apple-pay` (in the dialect, not mapped) | simple-icons | `currentColor` | not rendered; tracked as T133 | n/a | n/a |
+
+A name that maps to no key, or that only resolves to an inherited `Object` property such as `Constructor`, renders its name as text with no glyph.
+
+---
+
 ## Related
 
 - [[payment]] — `PaymentSectionRoot` / `PaymentMethodList`: the required ancestor and the sibling method picker. `PaymentMethodBadges` cannot render outside a `PaymentSectionRoot` (or `PaymentSectionController`); `AcceptedPaymentMethodBadges` needs none of it.

package/dist/docs/payment-methods.md

@@ -107,7 +107,7 @@ The element id is the content key, so name it for the section rather than its st
 | Component | What you style | Plausible classes |
 |---|---|---|
 | `PaymentMethods` | Stacks the heading over the strip | `flex flex-col gap-[12px]` |
-| `data-fs-payment-methods-heading` | The strip heading | `text-[14px] font-bold uppercase text-[#1a1a1a]` |
+| `data-fs-payment-methods-heading` | The strip heading | `text-[14px] font-bold uppercase text-[var(--color-ink)]` |
 | `data-fs-payment-methods-list` | The flag row, wrapping on narrow screens | `flex flex-wrap items-center gap-[8px] list-none p-0 m-0` |
 | `data-fs-payment-method` | The box one flag occupies | `flex items-center` |
 | `data-fs-payment-method-icon` | Both glyph paths, sized to match | `w-[40px] h-[26px] object-contain` |