@vtex/faststore 0.0.7 → 0.0.10

package/dist/docs/account-entry-point.md

@@ -53,14 +53,14 @@ Content model (`account-entry-point`) fields, edited in the CMS:
 |-------|------|----------|-------|
 | `signedOutLabel` | string | no | Cleared or absent keeps the authored prop |
 | `signedInLabel` | string | no | Same |
-| `icon` | string | no | Same, but the name must be listed in `global.json → icons.include` — see below |
+| `icon` | string | no | Same, but the name must be listed in `foundation.json → icons.include` — see below |
 | `loadingLabel` | string | no | Same |
 
-**An icon chosen in the CMS has to be declared in the store first.** Icon references resolve at compile time: the compiler collects every value of every `icon`-typed prop across the page and layout schemas and emits one sprite per route. A name that arrives at runtime from a CMS entry is never seen by that pass, so it renders a `<use>` pointing at a symbol the route's sprite does not carry — no build error, no runtime error, no glyph. For a merchant to be able to pick the icon in the Admin, the store must list the candidates under `global.json → icons.include`, which puts them in the root sprite regardless of what any schema references.
+**An icon chosen in the CMS has to be declared in the store first.** Icon references resolve at compile time: the compiler collects every value of every `icon`-typed prop across the page and layout schemas and emits one sprite per route. A name that arrives at runtime from a CMS entry is never seen by that pass, so it renders a `<use>` pointing at a symbol the route's sprite does not carry — no build error, no runtime error, no glyph. For a merchant to be able to pick the icon in the Admin, the store must list the candidates under `foundation.json → icons.include`, which puts them in the root sprite regardless of what any schema references.
 
 **One element, two links, chosen by the session.** `loggedIn` renders the signed-in link; `anonymous` and `identified` both render the signed-out one, because an identified but unauthenticated shopper cannot reach their account yet. There is no prop that selects between them — the merchant authors one element and the session decides.
 
-**The destinations are not authored.** Sign in goes to `/login`, carrying a `returnUrl` with the current path so the shopper returns where they started; the account link goes to the storefront's own `/pvt/account`. Both are fixed constants, so no schema edit and no CMS entry can misroute the auth flow. The sign-in destination comes from the shared `resolveSignInHref` (`utils/safe-href.ts`) rather than from this component, so any other surface that has to send a signed-out shopper to sign in reaches the same place by the same rule. The `returnUrl` value is constrained to a same-origin relative path, which keeps the sign-in route from being turned into an open redirect; a path the narrowing refuses drops the parameter, and so does a router reporting no path, leaving a bare `/login` rather than a broken link. That is the sender's half of the guarantee. Nothing stops a hand-crafted link, so the receiving half — narrowing the parameter through `resolveSiteRelativeHref` on arrival — belongs to the route that will serve `/login`. The signed-out link also opts out of Next.js prefetching: a header control is always in the viewport, and the destination is an auth route rather than a page, so it can set a cookie or redirect and the default would fire that request on every page view.
+**The destinations are not authored.** Sign in goes to the sign-in page `{ standard: 'sign-in' }`, carrying a `returnUrl` with the current logical path so the shopper returns where they started; the sign-in page prefixes it on the way back. The account link goes to the account page `{ standard: 'account' }`. The route map resolves both for the current binding, for example `/pt-BR/login` and `/pt-BR/pvt/account`. Both are fixed constants, so no schema edit and no CMS entry can misroute the auth flow. The sign-in destination comes from the shared `signInTarget` (`utils/safe-href.ts`) rather than from this component, so any other surface that has to send a signed-out shopper to sign in reaches the same place by the same rule. The `returnUrl` value is constrained to a same-origin relative path, which keeps the sign-in route from being turned into an open redirect; a path the narrowing refuses drops the parameter, and so does a router reporting no path, leaving a bare sign-in page rather than a broken link. That is the sender's half of the guarantee. Nothing stops a hand-crafted link, so the receiving half — narrowing the parameter through `resolveSiteRelativeHref` on arrival — belongs to the route that serves the sign-in page. The signed-out link also opts out of Next.js prefetching: a header control is always in the viewport, and the destination is an auth route rather than a page, so it can set a cookie or redirect and the default would fire that request on every page view.
 
 **`returnUrl` carries the path only — not the query string, not the hash.** A shopper signing in from `/s?q=tenis` or a filtered listing returns to the bare path. This is a deliberate narrowing rather than a limitation of the router: recovering the query would mean reading it through `useSearchParams()` and wrapping the header in a Suspense boundary, and the hash never leaves the browser at all. Search and filter state is cheap to re-apply and the sign-in round trip is rare, so the entry point keeps the simpler shape. Revisit it if merchants report losing filters across sign-in.
 
@@ -98,7 +98,7 @@ Bound to a CMS entry, the element authors no content props at all — the entry
 - **Placing it outside a `SessionRoot`.** The compiler rejects it, and the runtime throws.
 - **Authoring `$content` in the schema.** `$content` is compiler-injected from the page's or layout's content entry; naming it in `props` fails the build.
 - **Expecting a default glyph.** The base icon dialect has no account icon, so a store that authors no `icon` gets a label-only link. Author one from the store's own collection.
-- **Letting a merchant pick the icon without declaring it.** An `icon` supplied by a CMS entry renders nothing at all unless the store lists the name in `global.json → icons.include`: the compiler builds each route's sprite from the schemas, and a runtime value never reaches that pass.
+- **Letting a merchant pick the icon without declaring it.** An `icon` supplied by a CMS entry renders nothing at all unless the store lists the name in `foundation.json → icons.include`: the compiler builds each route's sprite from the schemas, and a runtime value never reaches that pass.
 - **Hiding the announced text with `display:none`.** That removes it from the accessibility tree and defeats the announcement; use a clipping technique instead.
 
 ---
@@ -123,7 +123,7 @@ Bound to a CMS entry, the element authors no content props at all — the entry
 ```
 
 The glyph carries a fixed intrinsic size, so reach it through the root when the header needs another.
-Author that once per store as the `AccountEntryPoint` base swatch in `global.json → styles`:
+Author that once per store as the `AccountEntryPoint` base swatch in `foundation.json → styles`:
 
 ```json
 {

package/dist/docs/account-menu.md

@@ -35,7 +35,7 @@ AccountMenuRoot
 ├── AccountMenuList
 ├── AccountMenuSignOut   ← beside the list, outside the landmark
 └── Slot                 ← the section's own page
-    └── AccountMenuIndexRedirect   ← on /pvt/account only
+    └── AccountMenuIndexRedirect   ← on the account page only
 ```
 
 **The Root wraps the section's content; the landmark does not.** The Root's context has to reach consumers that live inside the slot — the account root's redirect, the sibling breadcrumb — and a context reaches only its descendants. A `<nav>` stretched that far would put every section's content inside a navigation region: a screen reader would announce the page as navigation and "skip to navigation" would skip nothing. So the Root wraps, and the `<nav>` stays around the items alone.
@@ -57,12 +57,12 @@ Content model (`account-menu`) fields, edited in the CMS:
 |-------|------|----------|-------|
 | `items` | array | no | One entry per section, in the order they should appear |
 | `items[].label` | string | yes | The section's name |
-| `items[].href` | string | yes | Its destination; `http(s)`, `mailto:`, `tel:`, or a site-relative path |
+| `items[].href` | page reference or string | yes | Its destination; a page reference such as `{ "page": "orders" }`, or `http(s)`, `mailto:`, `tel:`, or a logical site-relative path |
 | `items[].external` | boolean | no | The entry leaves the account; it is never marked current |
 
-**The list comes from three channels, in order: a published entry, the authored `items` prop, then the library's five.** The default is Profile, Orders, Address, Payments, and Security, at `/pvt/profile` and its siblings — the set the PRD names. Presence decides, not emptiness: a channel supplying an empty list resolves to empty rather than falling through, because a merchant who cleared the list cleared it and the defaults must not override a deliberate publication.
+**The list comes from three channels, in order: a published entry, the authored `items` prop, then the library's five.** The default is Profile, Orders, Address, Payments, and Security, the page references `{ standard: 'profile' }` and its siblings — the set the PRD names. The route map resolves each one for the current binding, for example `/pt-BR/pvt/profile`. Presence decides, not emptiness: a channel supplying an empty list resolves to empty rather than falling through, because a merchant who cleared the list cleared it and the defaults must not override a deliberate publication.
 
-**The current section is derived, never authored.** The component reads the current path and matches each entry's destination on segment boundaries. At most one entry is current: among the matches, the one with the longest destination wins, which makes an exact match beat every ancestor without a second rule. `/pvt/order` is not a match for `/pvt/orders` — a prefix that does not land on a segment boundary is not a match at all.
+**The current section is derived, never authored.** The component reads the current logical path, without the binding's base path, and matches each entry's logical destination on segment boundaries. At most one entry is current: among the matches, the one with the longest destination wins, which makes an exact match beat every ancestor without a second rule. `/pvt/order` is not a match for `/pvt/orders` — a prefix that does not land on a segment boundary is not a match at all.
 
 **An exact match announces `aria-current="page"`; an ancestor match announces `aria-current="true"`.** Inside `/pvt/orders/123`, Orders is the current item of its set but not the current page. That claim belongs to the breadcrumb's deep entry, and two surfaces announcing "current page" for two different things is worse than the menu claiming only its set.
 
@@ -161,7 +161,7 @@ Returns `{ items, current }` — the resolved sections and the current one as `{
 
 Bound to a CMS entry, the Root authors no `items` at all — the entry supplies the whole list.
 
-No part carries a `style` reference: each takes its type's `base` swatch from `global.json → styles` on its own. Reference a named swatch only when the store defines one, since a `$name` the store does not define expands to nothing, without an error.
+No part carries a `style` reference: each takes its type's `base` swatch from `foundation.json → styles` on its own. Reference a named swatch only when the store defines one, since a `$name` the store does not define expands to nothing, without an error.
 
 The account root's page, whose only content is the redirect:
 
@@ -181,7 +181,7 @@ The account root's page, whose only content is the redirect:
 - **Leaving `label` unauthored.** The default is `Account`; a store with its own wording should say so, because a landmark's name is how a screen-reader user tells it from every other one.
 - **Styling the current item and nothing else.** The hook exists beside `aria-current`, never instead of it. Removing the programmatic signal leaves position conveyed by appearance alone.
 - **Publishing an empty list and expecting the defaults.** Empty is a configuration, not an absence. The account's root then has no section to open, and says so.
-- **Placing `AccountMenuIndexRedirect` on a section's page.** It navigates away from whatever page hosts it; it belongs on `/pvt/account` alone.
+- **Placing `AccountMenuIndexRedirect` on a section's page.** It navigates away from whatever page hosts it; it belongs on the account page alone.
 - **Putting an external entry first and expecting the root to follow it.** It is skipped, as is an absolute destination left unflagged; the root opens the first section that stays in the account.
 - **Placing `AccountMenuSignOut` outside the gate.** Nothing stands down while the logout runs, so the page shows the signed-out session for the moment before it leaves. Compose it under the `my-account` layout's gate.
 - **Signing out with the router, or adding `pageshow` handling to the control.** The document load is what keeps the account off the back control, and the gate owns the back-forward cache.
@@ -207,7 +207,7 @@ The account root's page, whose only content is the redirect:
 | Sign-out button | `data-fs-account-menu-sign-out-button` is the `<button>`; style `:disabled` for the wait | `text-left text-sm underline` |
 | Sign-out failure | `data-fs-account-menu-sign-out-error` is the alert | `text-sm text-red-600` |
 
-The vertical-to-horizontal switch and the scroll affordance are one DOM styled two ways, in CSS alone. A store authors them as `AccountMenuList.base` in `global.json → styles`, abridged here:
+The vertical-to-horizontal switch and the scroll affordance are one DOM styled two ways, in CSS alone. A store authors them as `AccountMenuList.base` in `foundation.json → styles`, abridged here:
 
 ```json
 {

package/dist/docs/account-saved-cards.md

@@ -0,0 +1,301 @@
+# Account Saved Cards
+
+**Category:** identity
+**Purpose:** The signed-in shopper's saved cards in their account: a list of card summaries, or a statement that there are none, with loading and failure states, and a confirmed removal for each card. Needs no cart.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A section heading such as "Saved cards", "Payment methods", or "My cards" inside an account page.
+- A vertical list of rows, each a card-network logo, a network name, and `•••• 1234`, with a line such as "Expires 05/28" under it.
+- A dimmed row reading "Expired 05/24" or "This card can't be used".
+- A "Remove" link or button in each row, opening a confirmation such as "Remove this card?" with Cancel and "Remove card".
+- Or a single sentence such as "You have no saved cards yet." where the list would be.
+- Usually beside the account's side navigation, never inside a checkout step.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- Showing the shopper the cards saved to their account, outside any purchase: the account's Payments page, or a block inside another account page.
+
+## When NOT to use
+
+- Picking a saved card to pay with during checkout → [[saved-cards]] (`SavedCards`, cart-scoped, with CVV entry).
+- Describing one card on its own → [[card-summary]].
+- The store's accepted payment methods as a strip of logos → [[payment-methods]].
+
+---
+
+## Composition
+
+```
+AccountSavedCardsRoot             ← requires 'session'; provides 'account-saved-cards'; declares savedCard.remove
+├── AccountSavedCardsHeading
+├── AccountSavedCardsRemoveFeedback
+├── AccountSavedCardsLoading
+├── AccountSavedCardsError
+├── AccountSavedCardsEmpty
+└── AccountSavedCardsList         ← provides 'account-saved-card'
+    └── AccountSavedCardItem      ← one row per card; provides 'card-summary', 'account-saved-card-data'
+        ├── CardSummary           (default when the row has no children)
+        ├── AccountSavedCardExpiry (default when the row has no children)
+        └── AccountSavedCardRemove (default when the row has no children) ← provides 'account-saved-card-remove'
+            └── AlertDialogRoot
+                ├── AccountSavedCardRemoveTrigger
+                └── AlertDialogPortal > AlertDialogBackdrop + AlertDialogViewport > AlertDialogPopup
+                    ├── AccountSavedCardRemoveTitle
+                    ├── AccountSavedCardRemoveDescription
+                    ├── AccountSavedCardRemoveCancel
+                    └── AccountSavedCardRemoveConfirm
+```
+
+`AccountSavedCardRemove` with no children renders the prompt shown under it.
+
+The Root renders nothing unless the session is `loggedIn`, and no chrome: no navigation, no page title, no landmark. It derives one state and exposes it on `data-fs-account-saved-cards-state`:
+
+| State | When | Renders |
+|---|---|---|
+| `loading` | No cards yet and the read is in flight | `AccountSavedCardsLoading` |
+| `error` | No cards and the read failed | `AccountSavedCardsError` |
+| `empty` | The read resolved with no card | `AccountSavedCardsEmpty` |
+| `ready` | The read resolved with cards | `AccountSavedCardsList` |
+| `idle` | No cards and nothing in flight | Nothing but the heading |
+
+The heading and the removal feedback render in every state. Every part except the Item must be inside the Root; the Item must be inside the List; the CardSummary parts, `AccountSavedCardExpiry`, and `AccountSavedCardRemove` inside the Item; and the five prompt parts inside `AccountSavedCardRemove`. A part outside its provider fails the build with a `ContextConstraintError`.
+
+---
+
+## Components
+
+### AccountSavedCardsRoot
+
+Reads the card ids (`customerSavedCards`, reactive) and publishes the section state. No schema props.
+
+It also holds the section's removal: which card is being removed (one at a time) and how the last removal ended. It declares `actions: { savedCard: ['remove'] }`, so every remove control inside reaches the action, including the one a bare Item renders.
+
+### AccountSavedCardsHeading
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `as` | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` | `h2` | No `h1`: the page title belongs to the page shell. |
+
+### AccountSavedCardsLoading
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `skeletonCount` | number | `2` | Placeholder rows (`data-fs-account-saved-cards-loading-row`), hidden from assistive technology. |
+
+A polite live region (`data-fs-account-saved-cards-loading-announcement`) stays mounted and announces the wait.
+
+### AccountSavedCardsError
+
+An alert. An expired session (`UNAUTHORIZED`) says so and links to sign-in (`data-fs-account-saved-cards-sign-in`), returning the shopper to the current page; any other failure says the cards could not be loaded. `data-fs-account-saved-cards-error-code` is `unauthorized` or `failed`. The server's message never renders. Children replace the message for every failure and drop the link.
+
+### AccountSavedCardsEmpty
+
+The statement that no card is saved. Renders only once the read resolved with none.
+
+### AccountSavedCardsList
+
+A `<ul>` repeating its child once per card.
+
+### AccountSavedCardItem
+
+A `<li>` that provides its card to the CardSummary parts, `AccountSavedCardExpiry`, and `AccountSavedCardRemove`. With no children it renders `CardSummary`'s default (mark, network name, mask, last four digits), then `AccountSavedCardExpiry`, then `AccountSavedCardRemove`. It shows no label: the account's read does not return one.
+
+An expired card's row carries `data-fs-account-saved-card-expired`, and an unusable one's `data-fs-account-saved-card-unusable`, so a swatch can dim it. A working card's row carries neither. While its card is being removed, the row carries `data-fs-account-saved-card-removing`. Compose the three parts as children to rearrange the row or to reword it from the CMS. Leave `AccountSavedCardRemove` out only for a read-only list.
+
+### AccountSavedCardExpiry
+
+The line that says when the card expires, from the API's `status` and `expiry`. No schema props and no children.
+
+| Card | Line | `data-fs-account-saved-card-expiry-status` |
+|---|---|---|
+| Working, with a date | "Expires 05/28" | `usable` |
+| Expired, with a date | "Expired 05/24" | `expired` |
+| Expired, no date | "Expired" | `expired` |
+| Unusable (any other status) | "This card can't be used", never a date | `unusable` |
+| Working, no date | Nothing | — |
+
+The label is in `data-fs-account-saved-card-expiry-label`, the `MM/YY` date in `data-fs-account-saved-card-expiry-date` (a `<time>`). The short date is hidden from assistive technology; a visually hidden span reads the month and year in full ("May 2028") in the store's locale. A month outside 1–12 or a year outside four digits counts as no date.
+
+### AccountSavedCardRemove
+
+The controller for one row's removal prompt. It owns the prompt's open state and passes it to its single `AlertDialogRoot` child; the schema never sets `open`. With no children it renders the default prompt. No schema props.
+
+Opening the prompt dispatches nothing. Confirm dispatches `savedCard.remove` with the row's card id. The prompt then stays open until the server answers, and Escape and Cancel cannot close it meanwhile. On success the row leaves the list, and the prompt goes with it. On failure the prompt closes, focus returns to the trigger, and the row stays. An expired or unusable card is removed like any other.
+
+### AccountSavedCardRemoveTrigger
+
+The row's control that opens the prompt. Its visible text is short ("Remove"); a visually hidden span adds the card ("Visa ending in 1234"), so each trigger has its own accessible name. Disabled while any removal in the section is pending.
+
+### AccountSavedCardRemoveTitle, AccountSavedCardRemoveDescription
+
+The prompt's title and accessible description. With no children, the description renders the card's `CardSummary` before its text, so the prompt names the card it removes.
+
+### AccountSavedCardRemoveCancel
+
+Closes the prompt and keeps the card. Opened with a mouse or the keyboard, the prompt focuses it first, so the safe action is the default; opened by touch, the popup takes focus itself. Disabled while the removal is pending.
+
+### AccountSavedCardRemoveConfirm
+
+Removes the card. While the removal is pending it carries `aria-disabled="true"`, `aria-busy="true"`, and `data-fs-account-saved-card-remove-confirm-pending`, and shows its pending text ("Removing…"). It stays focusable, so focus does not leave the prompt.
+
+### AccountSavedCardsRemoveFeedback
+
+Tells the shopper how the last removal ended. Place it once in the Root, outside the list, because a removed card's row unmounts. No schema props and no children.
+
+| Outcome | Renders | `data-fs-account-saved-cards-remove-feedback-outcome` |
+|---|---|---|
+| Removed | "The card was removed." in a polite status region, which takes focus | `removed` |
+| Session expired (`UNAUTHORIZED`) | An alert saying so, with a sign-in link (`data-fs-account-saved-cards-remove-feedback-sign-in`) that returns to the page | `unauthorized` |
+| Any other failure | An alert: "We couldn't remove the card. Please try again." | `failed` |
+| None yet, or a new removal started | Nothing | — |
+
+The status region stays mounted so screen readers announce it. No message disappears on its own, and the server's message never renders.
+
+## Text
+
+Every text resolves in this order: `children`, then the part's CMS entry (`$content`, a blank field counts as unset), then the catalog message in the store's locale.
+
+| Part | CMS fields | Catalog ids |
+|---|---|---|
+| `AccountSavedCardsHeading` | `text` | `fs/saved-cards.heading` |
+| `AccountSavedCardsEmpty` | `text` | `fs/saved-cards.empty` |
+| `AccountSavedCardsLoading` | `text` | `fs/saved-cards.loading` |
+| `AccountSavedCardsError` | `text`, `sessionExpiredText`, `signInLabel` | `fs/saved-cards.load-failed`, `fs/saved-cards.session-expired`, `fs/saved-cards.sign-in` |
+| `AccountSavedCardExpiry` | `expiresLabel`, `expiredLabel`, `expiredText`, `unusableText` | `fs/saved-cards.expires`, `fs/saved-cards.expired`, `fs/saved-cards.expired-no-date`, `fs/saved-cards.unusable` |
+| `AccountSavedCardRemoveTrigger` | `text` | `fs/saved-cards.remove.trigger` |
+| `AccountSavedCardRemoveTitle` | `text` | `fs/saved-cards.remove.title` |
+| `AccountSavedCardRemoveDescription` | `text` | `fs/saved-cards.remove.description` |
+| `AccountSavedCardRemoveCancel` | `text` | `fs/saved-cards.remove.cancel` |
+| `AccountSavedCardRemoveConfirm` | `text`, `pendingText` | `fs/saved-cards.remove.confirm`, `fs/saved-cards.remove.pending` |
+| `AccountSavedCardsRemoveFeedback` | `successText`, `failureText`, `sessionExpiredText`, `signInLabel` | `fs/saved-cards.remove.success`, `fs/saved-cards.remove.failed`, `fs/saved-cards.session-expired`, `fs/saved-cards.sign-in` |
+
+`AccountSavedCardExpiry` and `AccountSavedCardsRemoveFeedback` take no children. `expiresLabel` and `expiredLabel` precede the date, which the component always places; `expiredText` and `unusableText` stand alone. The trigger's hidden card name follows its text whatever the source. Children on the Confirm replace only its idle label. Only a part placed in the schema reads its CMS entry: the expiry line and the prompt an Item renders by default always show the catalog wording.
+
+## Canonical schema example
+
+```json
+{
+  "saved-cards": {
+    "type": "AccountSavedCardsRoot",
+    "children": [
+      "saved-cards-heading",
+      "saved-cards-remove-feedback",
+      "saved-cards-loading",
+      "saved-cards-error",
+      "saved-cards-empty",
+      "saved-cards-list"
+    ]
+  },
+  "saved-cards-heading": { "type": "AccountSavedCardsHeading" },
+  "saved-cards-remove-feedback": { "type": "AccountSavedCardsRemoveFeedback" },
+  "saved-cards-loading": { "type": "AccountSavedCardsLoading" },
+  "saved-cards-error": { "type": "AccountSavedCardsError" },
+  "saved-cards-empty": { "type": "AccountSavedCardsEmpty" },
+  "saved-cards-list": { "type": "AccountSavedCardsList", "children": ["saved-card-item"] },
+  "saved-card-item": { "type": "AccountSavedCardItem" }
+}
+```
+
+Nested inside another account page, with a lower heading:
+
+```json
+{
+  "saved-cards-heading": { "type": "AccountSavedCardsHeading", "props": { "as": "h3" } }
+}
+```
+
+With the row composed, so the expiry line and the removal prompt can be reworded from the CMS:
+
+```json
+{
+  "saved-card-item": {
+    "type": "AccountSavedCardItem",
+    "children": ["saved-card-summary", "saved-card-expiry", "saved-card-remove"]
+  },
+  "saved-card-summary": { "type": "CardSummary" },
+  "saved-card-expiry": { "type": "AccountSavedCardExpiry" },
+  "saved-card-remove": { "type": "AccountSavedCardRemove", "children": ["saved-card-remove-dialog"] },
+  "saved-card-remove-dialog": {
+    "type": "AlertDialogRoot",
+    "children": ["saved-card-remove-trigger", "saved-card-remove-portal"]
+  },
+  "saved-card-remove-trigger": { "type": "AccountSavedCardRemoveTrigger" },
+  "saved-card-remove-portal": {
+    "type": "AlertDialogPortal",
+    "children": ["saved-card-remove-backdrop", "saved-card-remove-viewport"]
+  },
+  "saved-card-remove-backdrop": { "type": "AlertDialogBackdrop" },
+  "saved-card-remove-viewport": { "type": "AlertDialogViewport", "children": ["saved-card-remove-popup"] },
+  "saved-card-remove-popup": {
+    "type": "AlertDialogPopup",
+    "children": [
+      "saved-card-remove-title",
+      "saved-card-remove-description",
+      "saved-card-remove-cancel",
+      "saved-card-remove-confirm"
+    ]
+  },
+  "saved-card-remove-title": { "type": "AccountSavedCardRemoveTitle" },
+  "saved-card-remove-description": { "type": "AccountSavedCardRemoveDescription" },
+  "saved-card-remove-cancel": { "type": "AccountSavedCardRemoveCancel" },
+  "saved-card-remove-confirm": { "type": "AccountSavedCardRemoveConfirm" }
+}
+```
+
+## Common mistakes
+
+- **`AccountSavedCards`, `SavedCardsList`, `MyCards`.** The Root is `AccountSavedCardsRoot`; the list is `AccountSavedCardsList`.
+- **Using `SavedCards` or `SavedCardOption` in the account.** Those are the checkout's cart-scoped picker and need a payment section.
+- **Placing `AccountSavedCardItem` directly in the Root.** It must be inside `AccountSavedCardsList`.
+- **Composing `AccountSavedCardsEmpty` as the only state part.** Compose Loading and Error too, or a slow or failed read shows nothing under the heading.
+- **Setting `as: "h1"`.** Not accepted; the page title belongs to the page shell.
+- **Passing `text` as a schema prop.** Text comes from children, the CMS entry, or the catalog.
+- **Placing the Root outside the `my-account` layout.** It requires `session`; without a `SessionRoot` the build fails.
+- **Giving the Item custom children without `AccountSavedCardExpiry`.** The row then hides when the card expires and whether it can be used.
+- **Expecting CMS wording on an Item with no children.** Its default expiry line and removal prompt are not in the schema, so they read only the catalog; place `AccountSavedCardExpiry` and the `AccountSavedCardRemove` composition explicitly.
+- **Giving the Item custom children without `AccountSavedCardRemove`.** The shopper can no longer remove the card. Do it only for a read-only list.
+- **Leaving out `AccountSavedCardsRemoveFeedback`.** A removal then ends with no message: a success only drops the row, and a failure says nothing.
+- **Placing the feedback inside the Item.** A removed card's row unmounts, taking the message with it.
+- **Setting `open` on the `AlertDialogRoot` inside `AccountSavedCardRemove`.** The controller owns it.
+- **Adding a plain button as the confirm control.** Only `AccountSavedCardRemoveConfirm` dispatches the removal.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `AccountSavedCardsRoot` | Section spacing | `flex flex-col gap-[16px]` |
+| `AccountSavedCardsHeading` | Heading typography | `text-[20px] font-semibold text-[#1F1F1F]` |
+| `AccountSavedCardsList` | Row stack | `flex flex-col gap-[8px]` |
+| `AccountSavedCardItem` | Row box; dim expired and unusable rows | `rounded-[8px] border border-[#E5E5E5] p-[12px] data-[fs-account-saved-card-expired]:opacity-60 data-[fs-account-saved-card-unusable]:opacity-60` |
+| `AccountSavedCardExpiry` | Line typography; color by state | `mt-[4px] text-[13px] text-[#6B6B6B] data-[fs-account-saved-card-expiry-status=expired]:text-[#B42318] data-[fs-account-saved-card-expiry-status=unusable]:text-[#B42318]` |
+| `AccountSavedCardsEmpty` | Statement typography | `text-[14px] text-[#6B6B6B]` |
+| `AccountSavedCardsLoading` | Placeholder stack; rows via `[&_[data-fs-account-saved-cards-loading-row]]` | `flex flex-col gap-[8px] [&_[data-fs-account-saved-cards-loading-row]]:h-[48px] [&_[data-fs-account-saved-cards-loading-row]]:rounded-[8px] [&_[data-fs-account-saved-cards-loading-row]]:bg-[#F0F0F0]` |
+| `AccountSavedCardsError` | Alert box and link | `rounded-[8px] bg-[#FDECEC] p-[12px] text-[14px] text-[#B42318] [&_a]:underline` |
+| `AccountSavedCardItem` (removing) | Fade the row while it is removed | `data-[fs-account-saved-card-removing]:opacity-60` |
+| `AccountSavedCardRemoveTrigger` | Link-like control | `mt-[8px] text-[13px] text-[#B42318] underline disabled:opacity-50` |
+| `AlertDialogPopup` | Prompt box (style the AlertDialog parts directly) | `w-full max-w-[420px] rounded-[12px] bg-white p-[24px] shadow-xl` |
+| `AccountSavedCardRemoveConfirm` | Destructive button; dim while pending | `rounded-[6px] bg-[#B42318] px-[16px] py-[8px] text-white aria-disabled:opacity-70` |
+| `AccountSavedCardsRemoveFeedback` | Message typography; alert color | `text-[14px] [&_[role=alert]]:text-[#B42318] [&_a]:underline` |
+
+```json
+{
+  "saved-cards": { "type": "AccountSavedCardsRoot", "style": ["flex", "flex-col", "gap-[16px]"] },
+  "saved-card-item": { "type": "AccountSavedCardItem", "style": ["rounded-[8px]", "border", "border-[#E5E5E5]", "p-[12px]"] }
+}
+```
+
+---
+
+## Related
+
+- [[card-summary]]: the card description each row renders.
+- [[alert-dialog]]: the overlay the removal prompt is built on.
+- [[saved-cards]]: the checkout's saved-card picker; cart-scoped.
+- [[my-account-profile]]: the account's other session-scoped matter.

package/dist/docs/alert-dialog.md

@@ -72,9 +72,9 @@ No props.
 
 ### AlertDialogPortal
 
-Teleports its children to `<body>`. Context-only: no element of its own and no `className`.
+Teleports its children. With no `container`, they go to `<body>`. Pass `container` when a parent swatch has to reach the overlay.
 
-No props.
+No `className`.
 
 ### AlertDialogBackdrop
 

package/dist/docs/billing-address.md

@@ -108,6 +108,7 @@ a form the shopper cannot see.
 | `billingMatchNoticeLabel` | string | `"Your billing address must match the one on your card or bank statement, or your bank may decline the order."` | Always-on billing-match disclaimer. Gated only by this prop and `billingMatchNoticeVisible` — unlike the two notices above, it never changes with the toggle, the form, `billingAddressRequired`, or a saved address. |
 | `billingMatchNoticeVisible` | boolean | `true` | Switches the billing-match disclaimer above on or off. A blank `billingMatchNoticeLabel` also renders nothing, even while this is `true` — the two rules never combine into an empty element. |
 | `fieldRequiredMessage` | string | `"This field is required."` | Shown as an inline field error under a required, blank address field once it has been touched (T38) — see Accessibility Contract below. One prop, not one per field: every rendered field but `complement` shares the same rule. An authored empty or whitespace-only string falls back to this default. |
+| `postalCodeInvalidMessage` | string | `"Enter a valid postal code."` | Shown as an inline field error under a touched, non-blank postal code that does not match the selected country's format (the descriptor's `rule.pattern`, the same one the delivery form enforces). Only the postal code reads this prop; the English default matches every other default on this form, so an author localises it with the rest. A blank postal code reads `fieldRequiredMessage` instead, never this. The message never contains the typed value. An authored empty or whitespace-only string falls back to this default. |
 | `disabled` | boolean | `false` | Disables the toggle, every form field, the country selector, and the submit button. |
 
 **Data:** declares no fragment and no `fetchStrategy`, so it fetches no shopper data. It reads only the
@@ -132,9 +133,9 @@ fields does not prevent that either — there is no `<form>` element anywhere in
 `required` is real for assistive technology but not wired to anything that blocks a click on a
 different button in a different component. Since T38 each rendered field (all but `complement`) does
 announce its own validity once touched — see Accessibility Contract below — but that announcement is
-driven by a local blur-tracked state, never by `required`'s own native validity, and it still does not
-gate the submit control; the submit gate is `isBillingAddressFormValid`, read at the submit button's
-own `disabled`.
+driven by a local touched-field state (blur, or a refused submit focusing the field), never by
+`required`'s own native validity, and it still does not gate the submit control; the submit gate is
+`isBillingAddressFormValid`, read at the submit button's own `disabled`.
 
 **The hard block itself lives elsewhere.** This component also publishes the exact same fact the notice
 renders from onto the shared payment draft (`billingAddressUnsaved`), and T24's submit gate
@@ -154,10 +155,13 @@ stays checked and the shopper never opens the form. It never reacts to the toggl
 `data-fs-billing-address-match-notice`, and renders as a plain paragraph with no ARIA role — it is a
 static disclaimer, not a live region reacting to an event.
 
+**Focus on refusal:** while the custom-address form is open, it registers itself so that when `PlaceOrder` refuses an order because the address was never saved, keyboard focus moves into the form: to the first rendered required field that is still blank; if none is blank, to the first rendered field whose value fails its country's format (a postal code `123` for BRA); and only when every field is filled and well-formed, to the submit control. The field the focus lands on, blank or malformed, is marked touched, so its message (`required` for a blank field, `format` for a malformed one) shows with the focus and no blur is needed. The country selector is never the target, and a disabled field or a disabled submit control (for example while saving) takes no focus. The reason stays in `PlaceOrder`'s existing alert and this component's unsaved-address notice. Focus moves only on the refused click.
+
 **Country adaptivity is entirely data-driven**, reusing the same country descriptors the delivery
 address step uses: Brazil shows a neighborhood/bairro field, the United States does not, and adding a
 new country anywhere in this codebase is a data-only change that this component picks up automatically
-— never a code change here.
+— never a code change here. The postal code's format is the same data: the descriptor's `rule.pattern`
+gates the submit button and the field error, so a country's format is defined once for both forms.
 
 ---
 
@@ -228,7 +232,7 @@ while the box is unchecked, and an optional inline error.
 | Required-billing-address note (`data-fs-billing-address-required-note`) | De-emphasized helper text | `text-[12px] text-[#666666]` |
 | Unsaved-address notice (`data-fs-billing-address-unsaved-notice`) | De-emphasized, non-error helper text | `text-[12px] text-[#666666]` |
 | Billing-match disclaimer (`data-fs-billing-address-match-notice`) | De-emphasized helper text, first child of the root | `text-[12px] text-[#666666]` |
-| Field error (`data-fs-field-error`) | Per-field validation message, shown once a required field is touched and left blank (T38) | `text-[12px] font-medium text-[#B00020]` |
+| Field error (`data-fs-field-error`) | Per-field validation message, shown once a field is touched: a blank required field, or a non-blank postal code that fails the country's format (T38); a refused submit that focuses the field touches it without a blur | `text-[12px] font-medium text-[#B00020]` |
 | Inline error (`data-fs-billing-address-error`) | Warning-toned alert text | `text-[12px] font-medium text-[#B00020]` |
 | Placing (`data-fs-billing-address-placing`) | Present while an order-placement sequence is in flight (T28) — distinct from `data-fs-billing-address-pending`, which this component already emits for its own local submit dispatch; the root is also `inert` and `aria-disabled` while placing | `opacity-60 cursor-not-allowed` |
 
@@ -252,10 +256,14 @@ There is no per-field styling hook beyond the particles' own `data-fs-checkbox-*
 ## Accessibility Contract
 
 **What the platform promises:** every rendered custom-address field (all but `complement`) announces
-its own validity once the shopper has touched it — focus, type nothing, and blur a required field, and
-it carries `aria-invalid="true"` plus an error message (`fieldRequiredMessage`) associated through
-`aria-describedby`; nothing is marked invalid before it is touched, and `complement` — the one optional
-field — is never marked invalid. This mirrors `CardEntry`'s own field-level validity mechanism exactly.
+its own validity once the shopper has touched it. A field is touched when the shopper blurs it, or when a
+refused submit moves focus to it (no blur ever comes there). Focus, type nothing, and blur a required
+field, and it carries `aria-invalid="true"` plus an error message (`fieldRequiredMessage`) associated
+through `aria-describedby`; nothing is marked invalid before it is touched, and `complement` — the one
+optional field — is never marked invalid. A postal code that is non-blank but not in the selected country's format
+is marked the same way, with `postalCodeInvalidMessage` as its error; switching country re-judges the
+typed value at once. Blank wins over format: a blank postal code reads `fieldRequiredMessage`, never the
+format message. This mirrors `CardEntry`'s own field-level validity mechanism exactly.
 Each field also carries its own `Field.Label`, authorable per field. A default `:focus-visible` outline
 is painted from the platform's own stylesheet on every field in this component.
 

package/dist/docs/binding-switcher.md

@@ -0,0 +1,154 @@
+# BindingSwitcher
+
+**Category:** action
+**Purpose:** Lists the store's bindings and starts a binding switch (locale, currency, and sales channel) through `locale.set`.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A closed dropdown whose visible value is a language name, a chevron, and sometimes one short sentence in a status line. The image is the source of truth for layout.
+
+---
+
+## When to use
+
+A store that declares two or more bindings and wants the shopper to switch the whole binding. Pass `bindings` as `$data.Global.localization.bindings`. With fewer than two counted bindings the component renders nothing.
+
+## When NOT to use
+
+- A country list, a currency picker, or a CMS language field.
+- A store with one binding. It renders nothing and should not reserve an empty control.
+
+---
+
+## Composition
+
+The schema tree is one node. `BindingSwitcher` has no children. The `Select` parts are internal and are not schema children.
+
+```
+BindingSwitcher
+```
+
+---
+
+## Components
+
+### BindingSwitcher
+
+Renders a host `div` (`data-fs-binding-switcher`). No fragment. Declares `actions: { locale: ['set'] }`. Choosing another binding calls `$actions.locale.set({ bindingId })`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `bindings` | object | — | `foundation.json` `localization.bindings`, keyed by binding id. No library default. The store passes `$data.Global.localization.bindings`. |
+| `label` | string | `"Language"` | Accessible name, rendered as the select label. |
+| `notice` | string | `"This page isn't available in the selected language."` | Shown when the page loaded with `fs_notice=no-equivalent`. Inline `<output>` (implicit `status` role). |
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "binding-switcher": {
+    "type": "BindingSwitcher",
+    "props": {
+      "bindings": "$data.Global.localization.bindings"
+    },
+    "style": [
+      "flex",
+      "flex-col",
+      "gap-2",
+      "text-[14px]",
+      "[&_[data-fs-binding-switcher-notice]]:text-[13px]",
+      "[&_[data-fs-select-trigger]]:inline-flex",
+      "[&_[data-fs-select-trigger]]:items-center",
+      "[&_[data-fs-select-trigger]]:gap-2",
+      "[&_[data-fs-select-trigger]]:rounded-md",
+      "[&_[data-fs-select-trigger]]:border",
+      "[&_[data-fs-select-trigger]]:border-neutral-300",
+      "[&_[data-fs-select-trigger]]:bg-white",
+      "[&_[data-fs-select-trigger]]:px-3",
+      "[&_[data-fs-select-trigger]]:py-1.5",
+      "[&_[data-fs-select-positioner]]:z-50",
+      "[&_[data-fs-select-popup]]:min-w-[var(--anchor-width)]",
+      "[&_[data-fs-select-popup]]:overflow-hidden",
+      "[&_[data-fs-select-popup]]:rounded-md",
+      "[&_[data-fs-select-popup]]:border",
+      "[&_[data-fs-select-popup]]:border-neutral-200",
+      "[&_[data-fs-select-popup]]:bg-white",
+      "[&_[data-fs-select-popup]]:shadow-lg",
+      "[&_[data-fs-select-list]]:py-1",
+      "[&_[data-fs-select-item]]:cursor-pointer",
+      "[&_[data-fs-select-item]]:px-3",
+      "[&_[data-fs-select-item]]:py-2",
+      "[&_[data-fs-select-item][data-highlighted]]:bg-neutral-100"
+    ]
+  }
+}
+```
+
+---
+
+## Common mistakes
+
+- **LocaleSelector** or **LanguagePicker.** The name is `BindingSwitcher`.
+- **A toast for the notice.** The notice is an inline `<output>`.
+- **A default bindings list.** The store passes `$data.Global.localization.bindings`.
+- **Children that rebuild Select.** The schema element has no children.
+
+---
+
+## Styling
+
+The host stacks the notice above the control. The popup stays in the host and opens below the trigger, 4px clear of it, so the element `style` reaches `[data-fs-select-popup]`. Give that popup an opaque surface. A parent locked to a fixed height lets the notice paint outside the bar; `min-h-16` on that parent keeps the notice inside it.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `BindingSwitcher` | Stacks the notice and the control. The notice line is `text-[13px]`. The popup is `[data-fs-select-popup]`. | `flex flex-col gap-2 text-[14px] [&_[data-fs-binding-switcher-notice]]:text-[13px] [&_[data-fs-select-popup]]:bg-white [&_[data-fs-select-popup]]:border [&_[data-fs-select-popup]]:border-neutral-200 [&_[data-fs-select-popup]]:rounded-md [&_[data-fs-select-popup]]:shadow-lg` |
+
+```json
+{
+  "binding-switcher": {
+    "type": "BindingSwitcher",
+    "props": {
+      "bindings": "$data.Global.localization.bindings"
+    },
+    "style": [
+      "flex",
+      "flex-col",
+      "gap-2",
+      "text-[14px]",
+      "[&_[data-fs-binding-switcher-notice]]:text-[13px]",
+      "[&_[data-fs-select-trigger]]:inline-flex",
+      "[&_[data-fs-select-trigger]]:items-center",
+      "[&_[data-fs-select-trigger]]:gap-2",
+      "[&_[data-fs-select-trigger]]:rounded-md",
+      "[&_[data-fs-select-trigger]]:border",
+      "[&_[data-fs-select-trigger]]:border-neutral-300",
+      "[&_[data-fs-select-trigger]]:bg-white",
+      "[&_[data-fs-select-trigger]]:px-3",
+      "[&_[data-fs-select-trigger]]:py-1.5",
+      "[&_[data-fs-select-positioner]]:z-50",
+      "[&_[data-fs-select-popup]]:min-w-[var(--anchor-width)]",
+      "[&_[data-fs-select-popup]]:overflow-hidden",
+      "[&_[data-fs-select-popup]]:rounded-md",
+      "[&_[data-fs-select-popup]]:border",
+      "[&_[data-fs-select-popup]]:border-neutral-200",
+      "[&_[data-fs-select-popup]]:bg-white",
+      "[&_[data-fs-select-popup]]:shadow-lg",
+      "[&_[data-fs-select-list]]:py-1",
+      "[&_[data-fs-select-item]]:cursor-pointer",
+      "[&_[data-fs-select-item]]:px-3",
+      "[&_[data-fs-select-item]]:py-2",
+      "[&_[data-fs-select-item][data-highlighted]]:bg-neutral-100"
+    ]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[select]] — the empty dropdown this component composes. `Select` does not know about bindings.