@vtex/faststore 0.0.6 → 0.0.8

package/dist/docs/card-entry.md

@@ -70,7 +70,9 @@ While collapsed, `CardEntry` still answers a place-order attempt: it keeps its s
 
 Collapsing clears the security code field, and only the security code. The card number, holder name, and expiration survive, so a shopper who switches method and switches back finds what they typed — no credit-card component in this package retains a security code across a visibility change.
 
-The authored `disabled` prop is independent of this: a store that freezes the form with `disabled` sees no change, and a collapsed form may also be `disabled` — neither implies the other.
+The authored `disabled` prop is independent of the collapse: a store that freezes the form with `disabled` sees no change, and a collapsed form may also be `disabled` — neither implies the other.
+
+In the checkout, the card number, holder name, expiration, and security code are cleared after every outcome in which the card target ran: the card POST resolved clean, resolved with errors or threw, or the target refused before any request. They are kept when the submission was refused before the target ran (the form's own check, a refused or untrusted transaction, the submit gate, no method selected) so the shopper can fix them.
 
 ---
 
@@ -78,12 +80,12 @@ The authored `disabled` prop is independent of this: a store that freezes the fo
 
 `CardEntry` renders the detected card network's icon at runtime, once the typed number matches a configured payment method's `validator.numberRegex` — the icon name is computed in component code, not read from a schema prop, so the compiler's prop-type-driven icon collection never sees it.
 
-**Any store composing `CardEntry` (or `SavedCards` / `SavedCardOption`) must declare the five network icon names in `global.icons.include`:**
+**Any store composing `CardEntry` (or `SavedCards` / `SavedCardOption`) must declare the six network icon names in `global.icons.include`:**
 
 ```json
 {
   "icons": {
-    "include": ["amex", "diners", "elo-card", "mastercard", "visa"]
+    "include": ["amex", "diners", "discover", "elo-card", "mastercard", "visa"]
   }
 }
 ```
@@ -94,7 +96,7 @@ The authored `disabled` prop is independent of this: a store that freezes the fo
 {
   "icons": {
     "collection": "ph",
-    "include": ["amex", "diners", "elo-card", "mastercard", "visa"]
+    "include": ["amex", "diners", "discover", "elo-card", "mastercard", "visa"]
   }
 }
 ```
@@ -103,6 +105,34 @@ Copying the first snippet verbatim over an existing `icons` object silently drop
 
 Omitting `include` entirely is silent too. The network icon renders as an empty 24×24 box instead of the card mark.
 
+## Store setup: response headers
+
+The card number and security code are typed into `CardEntry`'s raw fields and POSTed from the browser straight to the VTEX payment gateway, so the page that composes it needs a policy that names the vault host the card is POSTed to, forbids framing the page, and narrows what the page may load and call. The generator ships no default: the store declares it in `global.json` under `responseHeaders`, scoped by `routes` to the page that composes `CardEntry`.
+
+```json
+{
+  "responseHeaders": [
+    {
+      "routes": ["/checkout"],
+      "headers": {
+        "Content-Security-Policy": "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' https://acme.vtexvault.com; frame-ancestors 'none'; base-uri 'self'; object-src 'none'",
+        "Referrer-Policy": "strict-origin-when-cross-origin"
+      }
+    }
+  ]
+}
+```
+
+- **The vault host in `connect-src` is `https://{account}.vtexvault.com`, for the account the store serves.** That is the `NEXT_PUBLIC_ACCOUNT` the store is built with, which is not always `account.name` in `global.json`. Write the served account, with no wildcard: `https://*.vtexvault.com` would let a compromised script send the card to any tenant's vault.
+- **A policy that names the legacy payments host (`vtexpayments.com.br`) makes the browser block the card POST.** The order cannot be placed and nothing else on the page reports why. The generated app calls its own GraphQL at the relative `/api/graphql`, so `'self'` covers it; a store built with an absolute `NEXT_PUBLIC_STOREFRONT_API_URL` must add that origin.
+- **A rule's `routes` must name the page that composes `CardEntry`**, as the page's `route` spells it (`/checkout`, `/reserva/checkout/payment`). Renaming that page fails the compile instead of dropping the policy. A page added later that composes `CardEntry` carries nothing until its route is added to the rule.
+- **`script-src 'unsafe-inline'` is a known limit, and the policy does not stop injected script from sending the card off the page.** A static header cannot carry a nonce, so the inline scripts Next.js emits need it, and script injected into the page runs with the same rights. `connect-src` closes only `fetch`, XHR, beacons and WebSocket. The policy still leaves three channels open to any https host: an image request (`img-src https:`, which the page needs for catalog images), a form submission (no `form-action`) and a navigation (CSP cannot restrict one). What today's ruled policy does give is the vault origin pinned, no `'unsafe-eval'`, a page no other site can frame (`frame-ancestors 'none'`) and no `http:` or wildcard source. It does not replace keeping untrusted script off the payment page.
+- **`frame-ancestors 'none'`** blanks the page inside any iframe, including an editor preview.
+- **reCAPTCHA needs the anti-bot origins, and the ruled policy above does not declare them yet.** The challenge frame and script come from `https://www.google.com` and `https://www.gstatic.com`, the origins `sdk/anti-bot` declares. The frame is blocked by `default-src 'self'` (no `frame-src`) and the script by `script-src 'self' 'unsafe-inline'`, so both need the anti-bot origins. The stores add them together with whoever wires `getAntiBotToken`; the header check accepts a `frame-src` that names only those two origins and rejects any other.
+- **Under `next dev` the served `script-src` also carries `'unsafe-eval'`; production does not.** React Refresh evaluates code in the browser, so the generated `next.config.ts` adds `'unsafe-eval'` to the `script-src` of every Content-Security-Policy it serves only when `NODE_ENV` is `development` (what `next dev` sets), which is what `pnpm dev:example` runs. Any build whose `NODE_ENV` is not `development` (the default for `next build` and `next start`) serves the declared policy byte for byte, so the live header check still runs against them: a dev response shows a `script-src` the store never declared, which `scripts/assert-payment-page-headers.mjs` rejects by design, so run that script against `next start`.
+
+To check a served page, run `node scripts/assert-payment-page-headers.mjs --url <page url> --vault-host https://<account>.vtexvault.com`.
+
 ---
 
 ## Components
@@ -124,7 +154,8 @@ The only component. No internal sub-parts are separately schema-addressable.
 | `cvvPlaceholder` | string | — | CVV field placeholder. |
 | `cvvDescription` | string | `"The 3-4 digit number on your card"` | Helper text under the CVV field. Empty string renders nothing. |
 | `numberRequiredMessage` | string | `"Card number is required"` | Shown when the card-number field is left blank. |
-| `numberInvalidMessage` | string | `"Enter a valid card number"` | Shown for a Luhn-invalid number, or one that matches no configured method — the same string covers both. |
+| `numberInvalidMessage` | string | `"Enter a valid card number"` | Shown for a Luhn-invalid number, or one a configured network claims only as a prefix (the wrong length, or two networks at once). |
+| `networkNotAcceptedMessage` | string | `"This card is not from a network the store accepts"` | Shown for a Luhn-valid number that no configured network claims at all. |
 | `holderNameRequiredMessage` | string | `"Cardholder name is required"` | Shown when the holder-name field is left blank and the detected method requires it. |
 | `expirationRequiredMessage` | string | `"Expiration date is required"` | Shown when the expiration field is left blank and the detected method requires it. |
 | `expirationInvalidMessage` | string | `"Enter a valid expiration date"` | Shown for a structurally malformed `MM/YY`. |
@@ -208,7 +239,7 @@ Style `CardEntry`'s root as a vertical stack of fields, matching a typical card
 | Field inputs (`data-fs-field-control`) | The bordered text input | `border border-[#CCCCCC] rounded-[6px] px-[12px] py-[10px] text-[15px] w-full` |
 | Field errors (`data-fs-field-error`) | Inline validation message, small and red | `text-[12px] text-[#C8102E] mt-[4px] block` |
 | CVV helper text (`data-fs-card-entry-cvv-description`) | Small muted line under the CVV field | `text-[12px] text-[#666666] mt-[4px] block` |
-| Placing (`data-fs-card-entry-placing`) | Present while an order-placement sequence is in flight (T28); the whole root is also `inert` and `aria-disabled` at that point, so style this hook rather than relying on pointer events alone | `opacity-60 cursor-not-allowed` |
+| Placing (`data-fs-card-entry-placing`) | Present while an order-placement sequence is in flight (T28), and while the order attempt is resume-only (its card may already have been sent, so the fields do not accept input) until the attempt is freed; the whole root is also `inert` and `aria-disabled` at that point, so style this hook rather than relying on pointer events alone | `opacity-60 cursor-not-allowed` |
 | Collapsed (`data-fs-card-entry-collapsed`) | Present on the styled root while the card payment is collapsed — the persisted selection is a method this section does not serve or one that is not a card, and a picker is composed to un-hide it (see Reveal and collapse); the root is also `inert`. **No transition or animation can run on it**: the actual hide is a `hidden` attribute one level up, on an unstyled wrapper this node cannot reach with any class, and an ancestor's `display:none` removes the whole subtree from rendering the instant it applies, before any transition on a descendant could ever paint. Use this hook only for one-shot conditional styling of the (already-unrendered) subtree, never for an entrance/exit animation | `opacity-60` |
 
 Styled minimal example:

package/dist/docs/cardholder-document.md

@@ -1,7 +1,7 @@
 # CardholderDocument
 
 **Category:** commerce
-**Purpose:** A single tax-document input (CPF) for the checkout payment step, shown or hidden and marked required by the currently selected payment method's server-driven configuration.
+**Purpose:** A single tax-document input for the checkout payment step. The store's country picks the document (SSN for the United States, CPF for Brazil, SIN for Canada, RFC for Mexico); the currently selected payment method's server-driven configuration shows or hides it and marks it required.
 
 ---
 
@@ -11,12 +11,12 @@ Use these signals to detect that a CardholderDocument block is present. Position
 
 A CardholderDocument block is:
 
-- A **single labeled text input**, formatted with dots and a dash like `123.456.789-01` (the CPF mask).
-- Labeled **"CPF"** or a similar tax-document label — never "Card number", "Expiration", or "CVV".
+- A **single labeled text input**, formatted like `123.456.789-01` (CPF), `123-45-6789` (SSN), `046-454-286` (SIN) or `ABCD010101AB1` (RFC).
+- Labeled **"CPF"**, **"SSN"**, **"SIN"**, **"RFC"** or a similar tax-document label — never "Card number", "Expiration", or "CVV".
 - Not accompanied by a network icon, a "•••• 1234" masked number, or any card-brand logo — those belong to `CardEntry` or `SavedCards`, not this block.
 - Sometimes marked with a required indicator (an asterisk or similar) next to its label; sometimes not — both are valid, since requiredness is server-driven per payment method.
 
-If the image shows a **card-entry form with one extra plain text field formatted like a Brazilian tax ID**, use `CardholderDocument`. Do not use it for the shopper's account/profile document field — that is a different, identity-step component this block never composes with or reads from.
+If the image shows a **card-entry form with one extra plain text field formatted like a tax ID (CPF, SSN, SIN or RFC)**, use `CardholderDocument`. Do not use it for the shopper's account/profile document field — that is a different, identity-step component this block never composes with or reads from.
 
 ---
 
@@ -28,7 +28,7 @@ If the image shows a **card-entry form with one extra plain text field formatted
 
 - The shopper's saved profile/identity document (a client-identity or user-profile field) → use the identity-step document component instead. `CardholderDocument` is a payment-time value, deliberately separate — it never reads or writes the stored profile document, because the epic's RFC records that the two may differ.
 - A generic, data-agnostic tax-document input with no server-driven presence/requiredness → use the `DocumentField` particle directly instead; `CardholderDocument` exists specifically to wire that particle to the selected payment method's validator.
-- More than one document type or country → out of scope today. Only CPF renders; see this component's own spec for the recorded deferral.
+- A business document (CNPJ, EIN, BN, the corporate RFC) → not offered; only the four person documents render.
 
 ---
 
@@ -50,7 +50,7 @@ Child order reflects visual order. There is no parent/child relationship for thi
 **Composition rules:**
 
 - Must be inside `PaymentSectionRoot` or `PaymentSectionController`. Outside either, it throws.
-- Renders `null` (no DOM at all) when the selected payment method's validator does not mark a document displayable, or when no method is selected yet. This is normal, not an error — most methods most of the time render nothing here.
+- Renders `null` (no DOM at all) when the selected payment method's validator does not mark a document displayable, when no method is selected yet, or when the store's country has no document type (an unlisted country, or no country data). This is normal, not an error — most methods most of the time render nothing here.
 - Also renders `null` 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]]) — whatever that method's own validator says. When the card comes back, the field re-seeds from the value already typed.
 - Takes no children; passing any is a no-op.
 
@@ -60,18 +60,20 @@ Child order reflects visual order. There is no parent/child relationship for thi
 
 ### CardholderDocument
 
-The field itself. Renders the `DocumentField` particle for CPF, with presence and requiredness resolved from `usePayment().selectedMethod.validator` (`documentDisplayable` / `documentRequired`) rather than from any prop.
+The field itself. Renders the `DocumentField` particle for the type `usePayment().countryDocumentType` resolves (`USA` SSN, `BRA` CPF, `CAN` SIN, `MEX` RFC), with presence and requiredness resolved from `usePayment().selectedMethod.validator` (`documentDisplayable` / `documentRequired`) rather than from any prop.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | `string` | `'CPF'` | The field's visible label. |
-| `placeholder` | `string` | `'000.000.000-00'` | Shown in the empty input as a format hint. |
-| `errorMessage` | `string` | `'Invalid CPF'` | Shown inline when the typed value fails CPF check-digit validation on blur. |
+| `label` | `string` | the type's name (`SSN`, `CPF`, `SIN`, `RFC`) | The field's visible label. |
+| `placeholder` | `string` | the type's own (`000-00-0000`, `000.000.000-00`, `000-000-000`, `AAAA000000AAA`) | Shown in the empty input as a format hint. |
+| `errorMessage` | `string` | `'Invalid '` + the type's name | Shown inline when the typed value fails the type's validation on blur. |
 | `disabled` | `boolean` | `false` | Disables the input without hiding it — independent of the data-driven presence gate. |
 
-No `documentType` prop — this build supports CPF only. No `required` prop — requiredness is always read from the selected method's validator, never authored.
+No `documentType` prop — the store's country decides it. No `required` prop — requiredness is always read from the selected method's validator, never authored.
 
-**Data:** declares no `fragment` of its own. It reads `selectedMethod`, `draft`, and `setDraftDocument` off the ambient `payment` context that `PaymentSectionRoot` / `PaymentSectionController` already fetches for.
+**Data:** declares no `fragment` of its own. It reads `selectedMethod`, `countryDocumentType`, `draft`, and `setDraftDocument` off the ambient `payment` context that `PaymentSectionRoot` / `PaymentSectionController` already fetches for.
+
+**Focus on refusal:** while the field is on screen and not `disabled`, it registers itself so that when `PlaceOrder` refuses an order because the document is missing or malformed, keyboard focus moves to the `<input>`. The reason stays in `PlaceOrder`'s existing alert. Focus moves only on the refused click, and never for a refusal the gateway returned. With the field absent or `disabled`, nothing moves.
 
 ---
 
@@ -98,7 +100,7 @@ No `documentType` prop — this build supports CPF only. No `required` prop —
 ## Common mistakes
 
 - **Nesting `CardholderDocument` inside `CardEntry`.** It is a sibling under the same `PaymentSectionRoot`, never a child — `CardEntry` does not accept children.
-- **Passing a `documentType`, `required`, `countryCode`, or `document` prop.** None exist. Document type is fixed to CPF; requiredness and presence are always read from the selected method's validator, never authored; the typed value is not a prop at all — it flows into the shared payment draft internally.
+- **Passing a `documentType`, `required`, `countryCode`, or `document` prop.** None exist. The document type follows the store's country; requiredness and presence are always read from the selected method's validator, never authored; the typed value is not a prop at all — it flows into the shared payment draft internally.
 - **Using this component for the shopper's saved profile document.** That is a different, identity-step field this component never reads from or writes to — the two are intentionally separate, even for the same shopper.
 - **Expecting it to render outside a `PaymentSectionRoot` / `PaymentSectionController`.** It throws — the same requirement every other payment leaf (`CardEntry`, `Installments`, `SavedCards`, …) has.
 - **Treating a blank render as broken.** Most of the time, for most payment methods, this component correctly renders nothing — that is the "not displayable" state, not a bug.
@@ -107,7 +109,7 @@ No `documentType` prop — this build supports CPF only. No `required` prop —
 
 ## Known limitations
 
-- **CPF only.** The underlying read model carries no document-type or country signal (see this component's own spec for the full, measured deferral) — a store outside Brazil cannot get a different document type from this component today.
+- **Four person documents, by store country.** The country comes from `Payment.storeCountryCode` and `Payment.countries`. A store whose country resolves to no document type shows no field, refuses nothing and sends no document. A document typed while the field was shown is posted only while the selected method still asks for one and the country still resolves a type; the draft itself is not cleared. `label`, `placeholder` and `errorMessage` have no catalog default (the right copy depends on the country), so leave them unset unless the store serves one country.
 - **Server-driven requiredness renders the field correctly and is also enforced at submit time — but not by this component or by `CardEntry`.** This component marks the field required when the validator says so; a required-but-blank or malformed value (whether or not required) blocks Place Order client-side, before any transaction opens, **while the selected method's validator also says the document is displayable**. That gate lives in `matter/payment/use-payment-submit-gate.ts` (T24) and is consumed by `PlaceOrder`, not by this component or by `CardEntry`'s own `validateDraft` — this component's only job stays publishing `draft.document` via `setDraftDocument`. When the *currently* selected method's validator says `documentDisplayable: false`, the gate treats `draft.document` as inert either way (fix pass, findings R1/S4/S5): there is no field on screen for the shopper to read a leftover value from or correct it in, whether that value is left over from a previously selected, displayable method or simply blank. See `specs/cardholder-document-submit-gate.md` for the gate's full contract.
 
 ---

package/dist/docs/cart-item.md

@@ -53,7 +53,7 @@ CartItemRoot
 
 **It names itself from what it wraps.** The link adds no `aria-label`, so its accessible name is the image's alt text (`image.altText ?? variant.name`). On a line whose `variant.image` is `null` the leaf renders its children unwrapped instead of wrapping nothing, because an anchor with no content is a keyboard focus stop with no accessible name.
 
-**No usable product URL, no link.** The leaf runs `detailUrl` through `resolveSafeHref`, the same allowlist the navigation particle applies to CMS-authored destinations, and renders its children unwrapped when the destination is blank or refused: `javascript:`, `data:`, protocol-relative, or malformed. The particle gates only `$content.href`, so a platform URL arriving on the `href` prop is this leaf's to validate. Either way the image still shows: the leaf never self-hides, unlike the data-bearing leaves below, because hiding a wrapper would take its content with it. A refusal logs its reason and never the value; a blank URL is ordinary and stays quiet.
+**No usable product URL, no link.** The leaf runs `detailUrl` through `resolveSafeHref`, the same allowlist the navigation particle applies to CMS-authored destinations, and renders its children unwrapped when the destination is blank or refused: `javascript:`, `data:`, protocol-relative, or malformed. A safe `detailUrl` is a logical path: `NavigationLink` prefixes it for the current binding. The particle gates only `$content.href`, so a platform URL arriving on the `href` prop is this leaf's to validate. Either way the image still shows: the leaf never self-hides, unlike the data-bearing leaves below, because hiding a wrapper would take its content with it. A refusal logs its reason and never the value and still renders the children unwrapped; a blank URL is ordinary and stays quiet.
 
 Navigation is client-side through the `NavigationLink` particle, which also owns `rel` hardening. The link is same-tab, and `target` is omitted from the props type rather than merely left out of the schema, because an image-only link cannot carry the "(opens in new tab)" cue a `_blank` destination needs.
 

package/dist/docs/cart.md

@@ -65,7 +65,7 @@ What happens after a successful add to cart is a **per-store choice made by comp
 
 - **Mini-cart store → `CartOpenOnAdd`.** When the store has a mini-cart drawer, compose `CartOpenOnAdd` as the **parent of the mini-cart `DrawerRoot`** (its single child). It opens the drawer automatically on each successful add, with the new item visible and the count updated. It controls the drawer internally, so **do not set raw `open` / `onOpenChange` on `DrawerRoot`** — those are not authorable props, and the header `DrawerTrigger` plus manual close (Escape / backdrop / close button) keep working through the encapsulated wiring.
 
-- **No-mini-cart store → `CartRedirectOnAdd`.** When the store has **no** mini-cart and adding a product should send the shopper straight to checkout, compose `CartRedirectOnAdd` (and omit the drawer entirely). It navigates to `href` (default `/checkout`) after each successful add. It renders no UI of its own; place it once in the layout.
+- **No-mini-cart store → `CartRedirectOnAdd`.** When the store has **no** mini-cart and adding a product should send the shopper straight to checkout, compose `CartRedirectOnAdd` (and omit the drawer entirely). It navigates to `href` (default the checkout page, `{ "standard": "checkout" }`) after each successful add. It renders no UI of its own; place it once in the layout.
 
 The two are **mutually exclusive — compose exactly one**. A store with a mini-cart uses `CartOpenOnAdd` and never `CartRedirectOnAdd`; a store without one uses `CartRedirectOnAdd` and omits the drawer. Both react only to a **successful** add (a failed add or one returning user errors triggers neither).
 
@@ -87,7 +87,7 @@ CartRoot (layout)
 ```
 CartRoot (layout)
 ├── Header (add-to-cart CTAs elsewhere; no drawer)
-└── CartRedirectOnAdd          ← navigates to /checkout on a successful add
+└── CartRedirectOnAdd          ← navigates to the checkout page on a successful add
 ```
 
 ---
@@ -230,7 +230,7 @@ Neither leaf renders a wrapper or carries spacing, so **order, grouping, and any
 Continue-shopping is a **non-mutating** control, not a cart action. Which control depends on the surface:
 
 - **Inside the mini-cart drawer**, use `CartContinueShopping` — it closes the drawer through the drawer's own contract and dispatches no cart write.
-- **On a cart or checkout page** (no drawer to close), use a storefront `NavigationLink` (e.g. `href="/"`) back to browsing. Do **not** place `CartContinueShopping` there: it is a drawer close, and without a `DrawerRoot` ancestor the render fails.
+- **On a cart or checkout page** (no drawer to close), use a storefront `NavigationLink` (e.g. `href={{ page: 'home' }}`) back to browsing. Do **not** place `CartContinueShopping` there: it is a drawer close, and without a `DrawerRoot` ancestor the render fails.
 
 ```text
 CartRoot (layout)
@@ -259,7 +259,7 @@ CartRoot (layout)
   "popup-body": { "type": "CartList", "children": ["cart-item-template"] },
   "subtotal-row": { "type": "CartTotal", "props": { "label": "subtotal" } },
   "total-row": { "type": "CartTotal", "props": { "label": "total" } },
-  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": "/checkout", "children": "continuar" } },
+  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": { "standard": "checkout" }, "children": "continuar" } },
 
   "cart-empty": { "type": "CartEmpty", "children": ["empty-illustration", "empty-msg", "empty-footer"] },
   "empty-illustration": { "type": "Icon", "props": { "name": "shopping-bag" } },
@@ -275,7 +275,7 @@ On a cart/checkout page there is no drawer to close, so the empty branch keeps `
 {
   "cart-empty": { "type": "CartEmpty", "children": ["empty-msg", "keep-shopping-link"] },
   "empty-msg": { "type": "CartEmptyMessage", "props": { "text": "sua cesta está vazia" } },
-  "keep-shopping-link": { "type": "NavigationLink", "props": { "href": "/", "children": "continuar comprando" } }
+  "keep-shopping-link": { "type": "NavigationLink", "props": { "href": { "page": "home" }, "children": "continuar comprando" } }
 }
 ```
 
@@ -307,7 +307,7 @@ The mini-cart drawer (the layout composition described on `CartRoot`) ends in a
 
 - **`CartCheckoutGuard`** is the outer wrapper. It reads cart availability and, while any line item is not `AVAILABLE`, makes its whole subtree non-interactive (`inert` + `aria-disabled`) and exposes `data-fs-cart-checkout-blocked` for styling the disabled state. The shopper cannot proceed with an undeliverable item. It updates reactively from cache — no refetch, no reload — so the block clears the moment the offending line is removed or becomes available.
 - **`CartTotal`** sits inside the guard, on or next to the button, so the grand total the shopper is about to pay is visible at the CTA. It reads the nearest `CartRoot`/`CartTotalizerRoot` and reformats reactively on every cart change.
-- **`CartGoCheckout`** is the link to checkout (default `href` `/checkout`). During a **client-side** route transition it surfaces a loading state on its content wrapper — `aria-busy` plus `data-fs-cart-go-checkout-pending` — so the shopper sees the click registered. There is **no built-in spinner**: opt into one by styling that attribute (or composing a `Spinner` on it). For an **external or hard** checkout navigation (a non-Next route, a different origin, or a full page load — common for the real VTEX checkout) there is no client-side transition window, so the loading state simply does not show. That is the documented, graceful no-op, not a bug.
+- **`CartGoCheckout`** is the link to checkout (default `href` the checkout page, `{ "standard": "checkout" }`). During a **client-side** route transition it surfaces a loading state on its content wrapper — `aria-busy` plus `data-fs-cart-go-checkout-pending` — so the shopper sees the click registered. There is **no built-in spinner**: opt into one by styling that attribute (or composing a `Spinner` on it). For an **external or hard** checkout navigation (a non-Next route, a different origin, or a full page load — common for the real VTEX checkout) there is no client-side transition window, so the loading state simply does not show. That is the documented, graceful no-op, not a bug.
 
 **The button wording is CMS content.** It resolves in a fixed order: the `cart-checkout-label` entry, then the `label` prop, then `children`, then the package default `"Checkout"`. So a merchant rewords the CTA — `"Finalizar compra"`, `"Ir para o pagamento"` — with a CMS save and no deployment, while a store with no CMS binding renders its authored value. `children` stays supported because that is where stores labelled the button before `label` existed; a CMS entry overrides it with no schema edit. A blank or whitespace-only entry value counts as unconfigured and falls through. Non-compiler hosts (Storybook, tests) pass a typed `$content` fixture directly.
 
@@ -315,7 +315,7 @@ The mini-cart drawer (the layout composition described on `CartRoot`) ends in a
 
 | Prop | Type | Required | Notes |
 |-------|------|----------|-------|
-| `href` | string | no | Checkout destination, default `/checkout`. Never content-editable |
+| `href` | page reference or string | no | Checkout destination, default `{ "standard": "checkout" }`. A string is a logical path or an off-site URL. Never content-editable |
 | `label` | string | no | Authored fallback for the wording. Ignored when an entry supplies a label |
 | `children` | node | no | Legacy label channel, still honoured. Element children are replaced when an entry supplies a label |
 
@@ -332,7 +332,7 @@ Schema shape (inside the `DrawerPopup` footer `Container`):
   "popup-footer": { "type": "Container", "children": ["checkout-cta"] },
   "checkout-cta": { "type": "CartCheckoutGuard", "children": ["checkout-total", "checkout-btn"] },
   "checkout-total": { "type": "CartTotal", "props": { "label": "Total" } },
-  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": "/checkout", "label": "Finalizar compra" } }
+  "checkout-btn": { "type": "CartGoCheckout", "props": { "href": { "standard": "checkout" }, "label": "Finalizar compra" } }
 }
 ```
 

package/dist/docs/client-profile-fieldset.md

@@ -1,7 +1,7 @@
 # ClientProfileFieldset
 
 **Category:** identity
-**Purpose:** The composable, one-Save write of the `ClientProfile` entity. Registers itself with the enclosing `FormRoot` under the `clientProfile` namespace and dispatches at most one `identity.clientProfileUpdate` when the shopper presses that form's submit. Four bound controls — first name, last name, phone, document — compose freely inside it, in any order or subset.
+**Purpose:** The composable, one-Save write of the `ClientProfile` entity. Registers itself with the enclosing `FormRoot` under the `clientProfile` namespace and dispatches at most one `identity.clientProfileUpdate` when the shopper presses that form's submit. Four bound controls — first name, last name, phone, document (CPF, SSN, SIN or RFC) — compose freely inside it, in any order or subset.
 
 ---
 
@@ -65,7 +65,7 @@ SessionRoot                              (required ancestor; session tri-state +
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `country` | `'US' \| 'BR'` | `'US'` | Phone mask/validation country, provided to the phone control via context. |
-| `documentType` | string | — | e.g. `'CPF'`. The document control renders only when supported. |
+| `documentType` | string | — | One of `'CPF'`, `'SSN'`, `'SIN'` or `'RFC'` (upper case). The document control renders only when supported, and the payload carries `document` only for a supported type. |
 | `skeletonCount` | number | `4` | Placeholder rows drawn while the profile resolves. Set it to the number of controls composed. |
 | `loadingLabel` | string | `'Loading your details'` | Announced politely while the profile resolves. Blank means no announcement. |
 | `loadedLabel` | string | `'Your details are ready'` | Announced politely once the controls mount. Blank means no announcement. |
@@ -105,12 +105,14 @@ governs visibility (see *Switching the phone field off* below).
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | `'CPF'` | |
+| `label` | string | the document type's name (`'CPF'`, `'SSN'`, `'SIN'` or `'RFC'`) | |
 | `placeholder` | string | — | |
 | `errorMessage` | string | — | |
 
-Renders nothing, and registers no field name, when the fieldset's `documentType` is unsupported. Composes
-the `DocumentField` particle. Recomposable (RFC:503): given children, they replace `DocumentField`'s
+Renders nothing, and registers no field name, when the fieldset's `documentType` is unsupported. The mask,
+the validation and the `autocomplete` hint (`off` for SSN and SIN) come from the document type; the saved
+`document` string is the type's sanitised value (digits for CPF, SSN and SIN, letters kept for RFC), the
+same string the card form sends. Composes the `DocumentField` particle. Recomposable (RFC:503): given children, they replace `DocumentField`'s
 default `Field.Label` + `DocumentFieldInput` + `Field.Error` anatomy, in any order; childless keeps
 today's order and text.
 

package/dist/docs/copy-text.md

@@ -0,0 +1,84 @@
+# CopyText
+
+**Category:** action
+**Purpose:** Copies one string the caller supplies and confirms the result inline.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A small action beside an identifier, with a short confirmation that appears after the action and can be dismissed. The image is the source of truth for layout.
+
+## When to use
+
+Any screen that needs one action to copy a single string, such as an order number.
+
+## When NOT to use
+
+- Rendering the identifier itself. Pass the string in; do not ask `CopyText` to display the heading.
+- A toast or a page-level notification. The confirmation stays with the action.
+
+---
+
+## Composition
+
+```
+CopyText
+```
+
+`CopyText` is one element. The caller passes the visible label or icon as `children`.
+
+## Components
+
+### CopyText
+
+| Prop | Type | Default | Purpose |
+|---|---|---|---|
+| `accessibleName` | string | `Copy` | Accessible name of the action |
+| `successMessage` | string | `Copied` | Announced after a successful copy |
+| `failureMessage` | string | `Could not copy` | Announced when the clipboard rejects the write |
+| `dismissLabel` | string | `Dismiss` | Accessible name of the dismiss control |
+
+`text` is required and is not a schema prop. The caller supplies the exact string to copy. `children` is the visible label or icon, and it is not a schema prop either.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "copy-identifier": {
+    "type": "CopyText",
+    "props": {
+      "accessibleName": "Copy order number",
+      "successMessage": "Copied",
+      "failureMessage": "Could not copy",
+      "dismissLabel": "Dismiss"
+    },
+    "children": []
+  }
+}
+```
+
+The screen that owns the identifier passes `text` and `children` at runtime. Do not author the identifier in the page.
+
+## Common mistakes
+
+- **OrderDetailsHeader** renders the number. `CopyText` only copies the string it is given.
+- Passing the heading, including a prefix such as "Order #", copies that whole string. Pass the identifier alone.
+
+---
+
+## Styling
+
+| Component | What to style | Plausible classes |
+|---|---|---|
+| `CopyText` | The action and the inline confirmation | `inline-flex items-center gap-[8px] text-[14px]` |
+
+Style the hooks `data-fs-copy-text`, `data-fs-copy-text-action`, `data-fs-copy-text-message`, and `data-fs-copy-text-outcome`. The component ships no CSS.
+
+---
+
+## Related
+
+- [[button]] — the action primitive this control composes.

package/dist/docs/document-field.md

@@ -1,14 +1,14 @@
 # DocumentField
 
 **Category:** content
-**Purpose:** A presentational tax-document input that composes the `Field` particle (label + native `<input>` + inline error). It applies a locale-specific mask on every change (e.g. CPF `###.###.###-##`) and runs check-digit validation on blur/submit. It is data-agnostic — value flows through props; it consumes no GraphQL and no domain context.
+**Purpose:** A presentational tax-document input that composes the `Field` particle (label + native `<input>` + inline error). It applies the mask of its document type on every change (CPF `###.###.###-##`, SSN `###-##-####`, SIN `###-###-###`, or RFC, thirteen upper-case letters and digits) and runs that type's validation on blur/submit. It is data-agnostic — value flows through props; it consumes no GraphQL and no domain context.
 
 ---
 
 ## Visual cues (how to identify in an image)
 
-- A single-line text input labelled **"CPF"** (or another tax-document name), usually on a checkout identification step, near the email/phone fields.
-- Shows a masked placeholder like `000.000.000-00` and formats digits as they are typed.
+- A single-line text input labelled **"CPF"**, **"SSN"**, **"SIN"** or **"RFC"** (or another tax-document name), usually on a checkout identification step, near the email/phone fields.
+- Shows a masked placeholder like `000.000.000-00` (CPF), `000-00-0000` (SSN), `000-000-000` (SIN) or `AAAA000000AAA` (RFC) and formats characters as they are typed.
 - When invalid, an inline error below the input (e.g. *"Enter a valid CPF."*).
 
 If the image shows a checkout identification step with a tax-document field, use `DocumentField`.
@@ -61,15 +61,15 @@ react-hook-form and loses the mask — unsupported, the RFC's named double-binde
 | `label` | string | — | Accessible label. |
 | `placeholder` | string | — | Input placeholder. |
 | `disabled` | boolean | `false` | Disables the input (e.g. while a write is in flight). |
-| `requirement` | `'mandatory' \| 'optional'` | — | Raises the field to required, announced as `aria-required` (never the native attribute). Unset is no opinion, which is what keeps CPF Optional by Recommendation, unlike email. Bound to a fieldset whose rule already says required, `'optional'` does not lower it. |
+| `requirement` | `'mandatory' \| 'optional'` | — | Raises the field to required, announced as `aria-required` (never the native attribute). Unset is no opinion, which is what keeps the document Optional by Recommendation, unlike email. Bound to a fieldset whose rule already says required, `'optional'` does not lower it. |
 | `name` | string | `'document'` | Field/input name. |
-| `documentType` | `'CPF'` | `'CPF'` | Selects the mask + validator + digit-only input mode. |
+| `documentType` | `'CPF' \| 'SSN' \| 'SIN' \| 'RFC'` | `'CPF'` | Selects the mask, sanitiser, validator, digit-only input mode and `autocomplete`. `DOCUMENTS` holds one entry per type; the API's lower-case ids (`cpf`, `ssn`, `sin`, `rfc`) go through `documentTypeFromId`. |
 | `ref` | `Ref<HTMLInputElement>` | — | Lands on the `<input>` `Field.Control` renders — **not on the wrapper `<div>`, as it did before** (a deliberate, source-breaking change). Composed with react-hook-form's own ref on the bound path — a caller ref and react-hook-form's ref are both honoured. |
 | `children` | `ReactNode` | — | Given, replaces the default `Field.Label` + `DocumentFieldInput` + `Field.Error` anatomy, in any order (RFC:503). |
 
-**Masking:** applied progressively on every change; input is never blocked. Digit-only masks (CPF) strip non-digits and hint `inputMode="numeric"`.
+**Masking:** applied progressively on every change; input is never blocked. The type's sanitiser runs first: digit-only types (CPF, SSN, SIN) strip non-digits and hint `inputMode="numeric"`; RFC upper-cases and keeps only `A-Z` and `0-9`, and carries no `inputMode`. SSN and SIN inputs carry `autocomplete="off"` so the browser does not offer the number back; CPF and RFC carry no `autocomplete` attribute. The attribute is a request, not a guarantee.
 
-**Validation:** the check digit is checked on blur/submit only — never per keystroke. An **empty** value is valid (the field is optional). A prior error clears while the shopper edits and is re-evaluated on the next blur.
+**Validation:** the type's rule (CPF check digits; SSN area, group and serial ranges; SIN Luhn check; RFC structure with a plausible month and day) is checked on blur/submit only — never per keystroke. An **empty** value is valid (the field is optional). A prior error clears while the shopper edits and is re-evaluated on the next blur.
 
 ---
 
@@ -82,7 +82,7 @@ runs the plain, unbound behaviour documented above, unaltered.
 - **What the contract supplies**: `label` and `placeholder`, when the particle's own prop is omitted (an
   explicit prop always wins); `defaultValue`, seeded into `useController`; and `rule`, merged with the
   particle's own check-digit validator (below).
-- **What stays the particle's**: the CPF mask, `documentType`, and the `errorMessage` copy.
+- **What stays the particle's**: the mask of the `documentType`, the `documentType` itself, and the `errorMessage` copy.
 - **Single binder, real contract for the read-only parts (RFC:503)**: the composite remains the sole
   binder for its field — `useController` is called once, here. Its default (and a recomposed) anatomy's
   input is `DocumentFieldInput`, which renders the raw Base UI `Field.Control` directly rather than this

package/dist/docs/footer-link-group.md

@@ -58,7 +58,7 @@ It renders **both responsive forms at once**, each under its own hook: an accord
 | Prop | Type | Required | Notes |
 |-------|------|----------|-------|
 | `heading` | string | no | Authored fallback. Ignored when a CMS entry supplies a heading |
-| `links` | array | no | Authored fallback list of `{ label, href, target? }`. Ignored when a CMS entry supplies `links` |
+| `links` | array | no | Authored fallback list of `{ label, href, target? }`. An item `href` may be a page reference or a logical path. Ignored when a CMS entry supplies `links` |
 
 Content model (`footer-link-group`) fields, edited in the CMS:
 
@@ -67,7 +67,7 @@ Content model (`footer-link-group`) fields, edited in the CMS:
 | `heading` | string | no | The group heading and the accordion trigger's accessible name. Optional so a links-only entry falls back to the authored heading instead of omitting the group. A group with no heading resolved from either channel renders nothing |
 | `links` | array | no | Ordered links. Reordering here reorders the rendered list with no deployment. Optional so a heading-only entry falls back to the authored list instead of omitting the group |
 | `links[].label` | string | yes | Link text. A blank label drops that link — an anchor with no name is unusable |
-| `links[].href` | string | yes | Destination. `http:`, `https:`, `mailto:`, `tel:`, or a path starting with a single `/` |
+| `links[].href` | string | yes | A `uri-reference` string: `http:`, `https:`, `mailto:`, `tel:`, or a path starting with a single `/`. The binding prefix is applied at render |
 | `links[].target` | `_self` \| `_blank` | no | `_blank` opens a new tab and adds `rel="noopener noreferrer"` automatically |
 
 ---

package/dist/docs/header-root.md

@@ -80,7 +80,7 @@ A layout whose root holds a `HeaderRoot` and the page `Slot` beside it, with a l
   },
   "header-logo": {
     "type": "Logo",
-    "props": { "src": "/logo.svg", "alt": "Loja XYZ", "href": "/" }
+    "props": { "src": "/logo.svg", "alt": "Loja XYZ", "href": { "page": "home" } }
   },
   "header-nav": {
     "type": "NavigationMenuRoot",

package/dist/docs/incentives.md

@@ -64,7 +64,7 @@ FooterRoot
 
 | Prop | Type | Required | Notes |
 |-------|------|----------|-------|
-| `items` | array | no | Authored fallback list of `{ title, firstLineText?, secondLineText?, href?, icon?, iconUrl?, alt? }`. Ignored when a CMS entry supplies `items` |
+| `items` | array | no | Authored fallback list of `{ title, firstLineText?, secondLineText?, href?, icon?, iconUrl?, alt? }`. An item `href` may be a page reference or a logical path. Ignored when a CMS entry supplies `items` |
 
 Content model (`incentives`) fields, edited in the CMS:
 
@@ -74,7 +74,7 @@ Content model (`incentives`) fields, edited in the CMS:
 | `items[].title` | string | yes | The benefit's short bold label. The only required field per item; a blank one drops that item |
 | `items[].firstLineText` | string | no | The first line of supporting copy. Optional, so a title-only item is legal; a blank one renders no line |
 | `items[].secondLineText` | string | no | The second line. Absent or blank renders no element, so an item shows zero, one, or two lines |
-| `items[].href` | string | no | The block's destination. Optional, because a benefit strip links nowhere and a shortcut row links everywhere. Wraps the whole block — glyph included — in a same-tab link. Absent or blank renders the item unlinked; a value the render-time allowlist refuses also renders it unlinked, keeping the glyph and copy |
+| `items[].href` | string | no | A `uri-reference` string. Optional, because a benefit strip links nowhere and a shortcut row links everywhere. Wraps the whole block — glyph included — in a same-tab link. Absent or blank renders the item unlinked; a value the render-time allowlist refuses also renders it unlinked, keeping the glyph and copy. A safe string receives the binding prefix at render |
 | `items[].icon` | enum | no | One of `truck`, `calendar`, `gift`, `store`, `shield-check`. Renders the collection glyph, decorative |
 | `items[].iconUrl` | string | no | An uploaded image, for a benefit the predefined set has no glyph for. Wins over `icon` when both are set |
 | `items[].alt` | string | no | Alt text for an uploaded image. Defaults to empty, keeping the image decorative — the visible title beside it is already the item's accessible content, so repeating it would announce the same words twice |

package/dist/docs/logo.md

@@ -40,7 +40,7 @@ Logo
 |------|------|---------|-------|
 | `src` | string | — | Brand logo asset URL. Optional, so an element can be authored from the CMS alone. |
 | `alt` | string | — | Accessible alt text for the logo image. Optional for the same reason. |
-| `href` | string | `/` | Navigation destination (configured home). |
+| `href` | page reference or string | `{ "standard": "home" }` | A page reference or a logical path. The default names the home page. A store whose home page declares no `standard` authors `{ "page": "home" }`. |
 | `loading` | `'lazy' \| 'eager'` | `'eager'` | Set `lazy` below the fold; the default suits the header. |
 
 Content model (`logo`) fields, edited in the CMS:
@@ -49,13 +49,13 @@ Content model (`logo`) fields, edited in the CMS:
 |-------|------|----------|-------|
 | `src` | string | no | Picked via the media gallery widget. Cleared or absent keeps the authored `src` |
 | `alt` | string | yes | Accessible alt text |
-| `href` | string | no | Cleared or absent keeps the authored `href` |
+| `href` | string | no | A `uri-reference` string. Cleared or absent keeps the authored `href`. A safe string receives the binding prefix at render |
 
 **Props and content both work.** The props stay the authoring surface, and a CMS entry overrides them field by field, so a merchant can swap the brand mark for a campaign without a deploy. A store with no CMS binding receives no `$content` and renders from the props alone. The `logo` model puts no `format` on `src`, because a store's logo is usually a root-relative path served from `public/` (`/logo.svg`), which JSON Schema's `uri` format rejects. `href` carries `uri-reference` and the same destination pattern the link-bearing footer models declare, which admits a root-relative path.
 
 **Nothing renders without a resolved `src` and `alt`.** Both props are optional and only `alt` is required in the model, so an element can author nothing and take everything from the CMS. Presence is enforced once, at render, on the resolved values: an unconfigured logo renders no element at all rather than a broken image. An optional field that arrives blank reads as unauthored and falls through to the prop; a blank `alt` renders nothing, since an unnamed link is worse than no link.
 
-**A destination that is not a plain web address is dropped.** The resolved `href` is checked at render, and only `http:`, `https:`, `mailto:`, `tel:`, and single-slash site-relative paths are kept. Anything else — a `javascript:` URL, a protocol-relative `//host`, a scheme-less relative path — renders the image with no link around it and logs the reason. No read-time validator enforces a URL pattern, so this is the only gate on a destination the CMS supplied.
+**A string destination that is not a plain web address is dropped.** A CMS `href` is a `uri-reference` string. It is checked at render, and a safe one receives the binding's base path. A page reference, including the default `{ "standard": "home" }`, is not checked as a string. Only `http:`, `https:`, `mailto:`, `tel:`, and single-slash site-relative paths are kept. Anything else — a `javascript:` URL, a protocol-relative `//host`, a scheme-less relative path — renders the image with no link around it and logs the reason, and does not fall back to the prop. No read-time validator enforces a URL pattern, so this is the only gate on a destination the CMS supplied.
 
 ---
 
@@ -68,7 +68,7 @@ Content model (`logo`) fields, edited in the CMS:
     "props": {
       "src": "https://store.example/logo.svg",
       "alt": "Acme Store",
-      "href": "/"
+      "href": { "standard": "home" }
     },
     "style": ["$logo"]
   }
@@ -110,7 +110,7 @@ Bound to a CMS entry, the element authors no content props at all — the entry
 {
   "header-logo": {
     "type": "Logo",
-    "props": { "src": "https://store.example/logo.svg", "alt": "Acme Store", "href": "/" },
+    "props": { "src": "https://store.example/logo.svg", "alt": "Acme Store", "href": { "standard": "home" } },
     "style": ["w-[140px]", "md:w-[220px]"]
   }
 }

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

@@ -61,7 +61,7 @@ A field Control is absent from the composition means absent from both states and
 - **Save order**: compute dirtiness first → nothing dirty raises the saved toast without dispatching → otherwise validate only the dirty registered fields' current draft values (Decision 9) → any error blocks the dispatch and focuses the first invalid field in rendered DOM order → otherwise normalize dirty values and dispatch one `$actions.identity.customerProfileUpdate` → a `userError` raises an error toast and keeps the edit state with the draft intact → success returns to the view state and raises a success toast (Decision 10). A field the shopper never touched is neither validated nor sent.
 - **Edit always opens from the latest saved values**: pressing Edit re-seeds the draft from `savedValues` before switching modes, so a value the server normalized on a previous save (not this task's concern, but a sibling Control's) is what the shopper sees, not a stale local draft.
 - **Background re-delivery**: when `$data` delivers new values while editing, a field re-seeds only if its draft still equals the previously saved value; a dirty field is never clobbered.
-- **Self-gate**: renders nothing outside `state === 'loggedIn'`, even if the topology's `SessionGuard` is missing. Renders `MyAccountProfileSkeleton` while `$data` is unresolved and the shopper is logged in — never an empty summary.
+- **Self-gate**: renders nothing outside `state === 'loggedIn'`, even if the topology's `SessionGuard` is missing. Renders `MyAccountProfileSkeleton` while `$data` is unresolved and the shopper is logged in — never an empty summary. `customerProfile` is nullable, so `$data` is also `null` for an anonymous session (the self-gate renders nothing) and for a logged-in shopper whose read failed (the skeleton stays).
 - **PII**: no profile value appears in any log line. A write that throws (rather than resolving `userErrors`) logs only the error's name; the message shown to the shopper is the `saveFailedMessage` schema prop.
 
 ---
@@ -78,7 +78,7 @@ A field Control is absent from the composition means absent from both states and
 
 **`.PhoneControl`** — `field` (`'homePhone' | 'mobilePhone'`, default `'mobilePhone'`; compose the Control twice to expose both numbers), `country` (`'US' | 'BR'`, default `'US'`), `label`, `invalidMessage`.
 
-**`.TaxIdControl`** — `label` (default `'National tax ID'`), `invalidMessage`, `lockedReason` (the inline copy shown beside the disabled input when a CPF is already saved).
+**`.TaxIdControl`** — `label` (default `'National tax ID'`), `invalidMessage`, `lockedReason` (the inline copy shown beside the disabled input when a document is already saved). The control masks, validates and normalizes with the active document type: CPF, SSN, SIN or RFC. It sends `document` only (never `documentType`): digits for CPF, SSN and SIN, letters kept for RFC.
 
 **`.BirthDateControl`** — `label` (default `'Birth date'`).
 
@@ -93,8 +93,8 @@ Each Control is a thin binding over an existing presentational particle — it a
 - **Registration**: in a mount effect, a Control calls `registerField({ key, validate?, normalize? })` and returns the unregister function from the effect. `firstName`/`lastName` register a validator that rejects an empty draft value; every other Control either registers a format-only validator (a present value must be well-formed; empty is always valid) or no validator at all.
 - **Rendering**: `mode === 'view'` renders `savedValues[key]` as plain text (empty, never a placeholder, when the key was never saved); `mode === 'edit'` renders the bound particle over `draft[key]`, writing through `setField(key, value)`.
 - **Normalization**: `PhoneControl` registers `normalize = (v) => v ? toE164(v, country) : v`; `BirthDateControl` registers the native `yyyy-mm-dd` ↔ stored-format identity map. Normalization runs once, on Save, only for a field the shopper actually changed.
-- **The locked tax ID**: when a saved CPF exists, `TaxIdControl`'s edit branch renders a **disabled** input carrying the saved (masked) value, a `data-fs-my-account-profile-tax-id-readonly` hook, and `lockedReason` — never plain text, never omitted. It registers no validator in this branch and is never dirty. With no saved document, it renders an editable, optional `DocumentField` instead.
-- **Self-gate**: `TaxIdControl` renders nothing when the Root's `activeDocumentType` is undefined or unsupported (V0 supports CPF only).
+- **The locked tax ID**: when a saved document exists, `TaxIdControl`'s edit branch renders a **disabled** input carrying the saved (masked) value, a `data-fs-my-account-profile-tax-id-readonly` hook, and `lockedReason` — never plain text, never omitted. It registers no validator in this branch and is never dirty. With no saved document, it renders an editable, optional `DocumentField` instead.
+- **Self-gate**: `TaxIdControl` renders nothing when the Root's `activeDocumentType` is undefined or unsupported. The supported types are CPF, SSN, SIN and RFC; a saved `documentType` of any of them (any casing) wins over the Root's `documentType` prop.
 - **One phone Control, two bindings**: `PhoneControl`'s `field` prop selects which draft key an instance binds; composing it twice (once per `field` value) exposes both `homePhone` and `mobilePhone` as independent, independently-erasable fields.
 
 ---
@@ -172,7 +172,7 @@ Add each field Control id to `profile-root`'s `children` array for the fields th
 - **Reading `draft` in the view state, or `savedValues` in the edit state.** Each Control must branch on `mode` itself (Decision 2); the Root does not hide this for you.
 - **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).
+- **Hiding the `TaxIdControl` in the edit state when a document 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.