@vtex/faststore 0.0.5 → 0.0.6

package/dist/catalog.json

@@ -144,7 +144,7 @@
       "category": "content"
     },
     "schema": {},
-    "guideline": "The address block: recipient, street line, locality line, in that order by default. Compose AddressSummaryRecipient / Street / Locality as children to choose the order or drop a line; the wrapper, and any styling on it, is the same either way. Must be a descendant of AddressSummaryRoot.",
+    "guideline": "The address block: recipient, street line, locality line, in that order by default. Compose AddressSummaryRecipient / Street / Locality as children to choose the order or drop a line; the wrapper, and any styling on it, is the same either way. AddressSummaryName, AddressSummaryCountry and AddressSummaryField are also available for a custom composition — none of them join the default. Must be a descendant of AddressSummaryRoot.",
     "docPath": "src/particles/address-summary/address-summary.md"
   },
   "AddressSummaryRecipient": {
@@ -183,6 +183,158 @@
     "guideline": "Neighborhood, city, state and postal code on one line, or nothing when all are absent. Must be a descendant of AddressSummaryRoot.",
     "docPath": "src/particles/address-summary/address-summary.md"
   },
+  "AddressSummaryName": {
+    "name": "AddressSummaryName",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "address-summary",
+    "editor": {
+      "label": "Address Summary Name",
+      "category": "content"
+    },
+    "schema": {},
+    "guideline": "The shopper's own label for the address, or nothing when there is none. An unnamed address is identified by its contents. Must be a descendant of AddressSummaryRoot.",
+    "docPath": "src/particles/address-summary/address-summary.md"
+  },
+  "AddressSummaryCountry": {
+    "name": "AddressSummaryCountry",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "address-summary",
+    "editor": {
+      "label": "Address Summary Country",
+      "category": "content"
+    },
+    "schema": {},
+    "guideline": "The address's country, shown exactly as provided, or nothing when there is none. Provide a display name, not a raw code: the address stores an ISO alpha-3 code, which Intl.DisplayNames rejects. Must be a descendant of AddressSummaryRoot.",
+    "docPath": "src/particles/address-summary/address-summary.md"
+  },
+  "AddressSummaryField": {
+    "name": "AddressSummaryField",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "address-summary",
+    "editor": {
+      "label": "Address Summary Field",
+      "category": "content"
+    },
+    "schema": {
+      "field": {
+        "type": [
+          "recipientName",
+          "name",
+          "street",
+          "number",
+          "complement",
+          "neighborhood",
+          "city",
+          "state",
+          "postalCode",
+          "country",
+          "reference"
+        ],
+        "label": "Field"
+      }
+    },
+    "guideline": "One address field, rendered inline, or nothing when it is empty. Compose several to build a line in a country's own order (e.g. number before street), with the separators the composition supplies; a separator beside a field that turns out empty is the composition's to drop. Must be a descendant of AddressSummaryRoot.",
+    "docPath": "src/particles/address-summary/address-summary.md"
+  },
+  "AlertDialogRoot": {
+    "name": "AlertDialogRoot",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Alert Dialog Root",
+      "category": "layout"
+    },
+    "schema": {},
+    "guideline": "Root of a confirmation prompt for an irreversible action. Compose as: AlertDialogRoot > (AlertDialogTrigger + AlertDialogPortal > (AlertDialogBackdrop + AlertDialogViewport > AlertDialogPopup > (AlertDialogTitle + AlertDialogDescription + AlertDialogClose + your confirm Button))). Always modal and never closes on an outside click; only Escape or an AlertDialogClose dismisses it. Use Dialog instead when a stray click may close the overlay.",
+    "docPath": "src/particles/alert-dialog/alert-dialog.md"
+  },
+  "AlertDialogTrigger": {
+    "name": "AlertDialogTrigger",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Alert Dialog Trigger",
+      "category": "action"
+    },
+    "schema": {},
+    "guideline": "Opens the alert dialog when clicked. Direct child of AlertDialogRoot. Accepts any children (text, Icon). Base UI connects it to AlertDialogRoot via context — no explicit wiring needed.",
+    "docPath": "src/particles/alert-dialog/alert-dialog.md"
+  },
+  "AlertDialogPortal": {
+    "name": "AlertDialogPortal",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Alert Dialog Portal",
+      "category": "layout"
+    },
+    "schema": {},
+    "guideline": "Renders its children outside the DOM tree (into document.body). Place AlertDialogBackdrop and AlertDialogViewport as direct children, in that order.",
+    "docPath": "src/particles/alert-dialog/alert-dialog.md"
+  },
+  "AlertDialogBackdrop": {
+    "name": "AlertDialogBackdrop",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Alert Dialog Backdrop",
+      "category": "layout"
+    },
+    "schema": {},
+    "guideline": "Semi-transparent overlay behind the popup. Direct child of AlertDialogPortal, before AlertDialogViewport. Clicking it does not close the alert dialog.",
+    "docPath": "src/particles/alert-dialog/alert-dialog.md"
+  },
+  "AlertDialogViewport": {
+    "name": "AlertDialogViewport",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Alert Dialog Viewport",
+      "category": "layout"
+    },
+    "schema": {},
+    "guideline": "Positioning container for AlertDialogPopup. Direct child of AlertDialogPortal, after AlertDialogBackdrop. Apply fixed positioning and centering here (e.g. fixed inset-0 flex items-center justify-center). Place AlertDialogPopup inside.",
+    "docPath": "src/particles/alert-dialog/alert-dialog.md"
+  },
+  "AlertDialogPopup": {
+    "name": "AlertDialogPopup",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Alert Dialog Popup",
+      "category": "layout"
+    },
+    "schema": {},
+    "guideline": "The visible prompt, inside AlertDialogViewport, with role alertdialog. Place AlertDialogTitle (required), AlertDialogDescription, an AlertDialogClose for cancel, and a confirm Button inside. Focus starts on the first focusable element, except when opened by touch, where Base UI focuses the popup itself: put the cancel control first, and pass initialFocus (a ref) when Cancel must receive focus for every kind of interaction.",
+    "docPath": "src/particles/alert-dialog/alert-dialog.md"
+  },
+  "AlertDialogTitle": {
+    "name": "AlertDialogTitle",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Alert Dialog Title",
+      "category": "layout"
+    },
+    "schema": {},
+    "guideline": "Required heading inside AlertDialogPopup — sets the accessible name of the alert dialog for screen readers. State the question, e.g. \"Delete this address?\".",
+    "docPath": "src/particles/alert-dialog/alert-dialog.md"
+  },
+  "AlertDialogDescription": {
+    "name": "AlertDialogDescription",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Alert Dialog Description",
+      "category": "layout"
+    },
+    "schema": {},
+    "guideline": "Description inside AlertDialogPopup, after AlertDialogTitle. Screen readers announce it with the prompt, so use it to state the consequence of confirming.",
+    "docPath": "src/particles/alert-dialog/alert-dialog.md"
+  },
+  "AlertDialogClose": {
+    "name": "AlertDialogClose",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Alert Dialog Close",
+      "category": "action"
+    },
+    "schema": {},
+    "guideline": "Closes the alert dialog when clicked. Use it for the cancel control inside AlertDialogPopup. The confirm control is a separate Button that runs the consumer action.",
+    "docPath": "src/particles/alert-dialog/alert-dialog.md"
+  },
   "Badge": {
     "name": "Badge",
     "importPath": "@vtex/faststore/components",
@@ -442,6 +594,7 @@
   "DocumentField": {
     "name": "DocumentField",
     "importPath": "@vtex/faststore/components",
+    "providesContext": "document-field",
     "editor": {
       "label": "Document Field",
       "category": "content"
@@ -464,10 +617,12 @@
         "default": "CPF",
         "label": "Document type"
       },
-      "required": {
-        "type": "boolean",
-        "default": false,
-        "label": "Required"
+      "requirement": {
+        "type": [
+          "mandatory",
+          "optional"
+        ],
+        "label": "Requirement"
       },
       "disabled": {
         "type": "boolean",
@@ -475,7 +630,19 @@
         "label": "Disabled"
       }
     },
-    "guideline": "Presentational tax-document input composing the Field particle; applies the locale mask on change and runs check-digit validation on blur/submit. Data-agnostic (value/defaultValue/onValueChange); a host wires it to the shopper profile. CPF is optional by default.",
+    "guideline": "Presentational tax-document input composing the Field particle; applies the locale mask on change and runs check-digit validation on blur/submit. Data-agnostic (value/defaultValue/onValueChange); a host wires it to the shopper profile. CPF is optional by default: requirement only ever raises the field to required, announced as aria-required, and bound to a fieldset whose rule already says required it cannot lower it back. Recomposable (RFC:503): given children, they replace the default Field.Label + DocumentFieldInput + Field.Error anatomy, in any order.",
+    "docPath": "src/particles/document-field/document-field.md"
+  },
+  "DocumentFieldInput": {
+    "name": "DocumentFieldInput",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "document-field",
+    "editor": {
+      "label": "Document Field Input",
+      "category": "action"
+    },
+    "schema": {},
+    "guideline": "The masked document <input> DocumentField owns. Must sit inside DocumentField, in either the default anatomy or an author's composed children. Carries the locale mask, the composed ref, and DocumentField's own onChange/onBlur — a composed Field.Control here instead re-registers the field with react-hook-form and loses the mask (unsupported, RFC's named double-binder hole).",
     "docPath": "src/particles/document-field/document-field.md"
   },
   "DrawerRoot": {
@@ -611,6 +778,7 @@
   "FieldRoot": {
     "name": "FieldRoot",
     "importPath": "@vtex/faststore/components",
+    "providesContext": "field",
     "editor": {
       "label": "Field Root",
       "category": "layout"
@@ -622,57 +790,80 @@
         "label": "Disabled"
       }
     },
-    "guideline": "Form field container that connects a label, input, and validation messages via ARIA. Use Field.Control as the input element, or place a compatible Base UI input (Input, Checkbox, Select) as a direct child. Set invalid=true to trigger Field.Error display."
+    "guideline": "Form field container that connects a label, input, and validation messages via ARIA. Use Field.Control as the input element, or place a compatible Base UI input (Input, Checkbox, Select) as a direct child. Set invalid=true to trigger Field.Error display. Wrapping a bound Control feeds invalid/dirty/touched from react-hook-form automatically.",
+    "docPath": "src/particles/field/field.md"
   },
   "FieldLabel": {
     "name": "FieldLabel",
     "importPath": "@vtex/faststore/components",
+    "requiresContext": "field",
     "editor": {
       "label": "Field Label",
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Accessible label inside Field.Root. Automatically associated with Field.Control's input via ARIA. Place before Field.Control in the DOM."
+    "guideline": "Accessible label inside Field.Root. Automatically associated with Field.Control's input via ARIA. Place before Field.Control in the DOM. Under a bound Control, a childless Field.Label renders the field contract's label.",
+    "docPath": "src/particles/field/field.md"
   },
   "FieldControl": {
     "name": "FieldControl",
     "importPath": "@vtex/faststore/components",
+    "requiresContext": "field",
     "editor": {
       "label": "Field Control",
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Renders a native `<input>` element directly. It IS the input — do not place any child inside it. Pass input attributes (type, placeholder, required, etc.) directly as props. It is automatically linked to Field.Label and Field.Error via ARIA."
+    "guideline": "Renders a native `<input>` element directly. It IS the input — do not place any child inside it. Pass input attributes (type, placeholder, required, etc.) directly as props. It is automatically linked to Field.Label and Field.Error via ARIA. Under a bound Control, it registers with react-hook-form using the field contract's name, seed value, and validation rule.",
+    "docPath": "src/particles/field/field.md"
   },
   "FieldDescription": {
     "name": "FieldDescription",
     "importPath": "@vtex/faststore/components",
+    "requiresContext": "field",
     "editor": {
       "label": "Field Description",
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Helper text inside Field.Root. Automatically linked to the control via aria-describedby. Always visible regardless of validation state."
+    "guideline": "Helper text inside Field.Root. Automatically linked to the control via aria-describedby. Always visible regardless of validation state.",
+    "docPath": "src/particles/field/field.md"
   },
   "FieldError": {
     "name": "FieldError",
     "importPath": "@vtex/faststore/components",
+    "requiresContext": "field",
     "editor": {
       "label": "Field Error",
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Validation error message inside Field.Root. Shown when the field is in an invalid state. Linked to the control via aria-describedby."
+    "guideline": "Validation error message inside Field.Root. Shown when the field is in an invalid state. Linked to the control via aria-describedby. Under a bound Control, it renders react-hook-form's error message for the field contract's name.",
+    "docPath": "src/particles/field/field.md"
   },
   "FieldValidity": {
     "name": "FieldValidity",
     "importPath": "@vtex/faststore/components",
+    "requiresContext": "field",
     "editor": {
       "label": "Field Validity",
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Validation feedback slot using a render prop for custom messages derived from the field's validity state. Use for dynamic messages when Field.Error text is not fixed."
+    "guideline": "Validation feedback slot using a render prop for custom messages derived from the field's validity state. Use for dynamic messages when Field.Error text is not fixed.",
+    "docPath": "src/particles/field/field.md"
+  },
+  "FieldCheckbox": {
+    "name": "FieldCheckbox",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "field",
+    "editor": {
+      "label": "Field Checkbox",
+      "category": "action"
+    },
+    "schema": {},
+    "guideline": "Bound boolean control over the shipped Checkbox particle: reads the enclosing field contract and drives Checkbox.Root through react-hook-form. Compose Checkbox.Indicator as a child for the visual check mark. Place inside Field.Root, the only ancestor that provides the field context it requires today — a bound Control will satisfy it too, once one ships.",
+    "docPath": "src/particles/field/field.md"
   },
   "FieldsetRoot": {
     "name": "FieldsetRoot",
@@ -682,7 +873,7 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Root of an accessible fieldset for grouping related form controls. Compose as: FieldsetRoot > FieldsetLegend + [form controls]. Set disabled on the root to disable all contained inputs."
+    "guideline": "Root of an accessible fieldset for grouping related form controls. Compose as: FieldsetRoot > FieldsetLegend + [form controls]. `disabled` marks the group with `data-disabled` and disables Field-family descendants through context — it does not set the native `fieldset[disabled]` attribute, so plain inputs, `CheckboxRoot` and `RadioGroup` inside it stay interactive."
   },
   "FieldsetLegend": {
     "name": "FieldsetLegend",
@@ -692,7 +883,7 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Visible title for a Fieldset.Root. Renders as a styled <legend> element."
+    "guideline": "Visible title for a `FieldsetRoot`. Renders a `div` — not a native `<legend>` — and names the enclosing fieldset through `aria-labelledby`, so it must sit inside a `FieldsetRoot` to label anything; when two are composed, the last one wins."
   },
   "FooterCopyright": {
     "name": "FooterCopyright",
@@ -764,6 +955,103 @@
     "guideline": "The store's official social profiles as a row of icon links, both the heading and the list CMS-editable. Every link opens in a new tab. Every predefined platform name must be listed in the store's icons.include. See footer-social.md.",
     "docPath": "src/particles/footer-social/footer-social.md"
   },
+  "FormRoot": {
+    "name": "FormRoot",
+    "importPath": "@vtex/faststore/components",
+    "providesContext": "form",
+    "editor": {
+      "label": "Form",
+      "category": "action"
+    },
+    "schema": {},
+    "guideline": "The only <form> its own fieldset registry dispatches from — a composed CartCouponForm, ShippingSimulatorForm or RegionForm renders its own, and a submit-origin check keeps theirs out of this one. Calls react-hook-form's useForm() once and holds the registry a submit dispatches in registration order. Compose FormSubmit/FormEnterSubmit/FormError/FormClear/FormReset anywhere inside it, and a fieldset as a descendant to give the submit something to persist — FormRoot itself declares no actions.",
+    "docPath": "src/particles/form/form.md"
+  },
+  "FormSubmit": {
+    "name": "FormSubmit",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "form",
+    "editor": {
+      "label": "Form Submit",
+      "category": "action"
+    },
+    "schema": {
+      "label": {
+        "type": "string",
+        "label": "Label"
+      }
+    },
+    "guideline": "Submits every registered fieldset the shopper changed, in registration order, and disables itself while a write is in flight. Renders children, then label, then the message catalog (fs/form.submit) — never a hard-coded English default. A fieldset with nothing changed contributes no request; an invalid field blocks every dispatch and moves focus to it instead of submitting. Enter in a text input does not submit — see FormEnterSubmit for a form where it does.",
+    "docPath": "src/particles/form/form.md"
+  },
+  "FormEnterSubmit": {
+    "name": "FormEnterSubmit",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "form",
+    "editor": {
+      "label": "Form Enter Submit",
+      "category": "action"
+    },
+    "schema": {
+      "label": {
+        "type": "string",
+        "label": "Label"
+      }
+    },
+    "guideline": "Renders the same button as FormSubmit, sharing its children/label/fs/form.submit resolution, and additionally allows Enter to submit this form from any text-entry input while mounted. The allowance is form-scoped: placed inside one fieldset of a multi-fieldset FormRoot, it allows Enter for every text input in the enclosing form, not only that fieldset. Enter that commits an IME candidate never submits.",
+    "docPath": "src/particles/form/form.md"
+  },
+  "FormError": {
+    "name": "FormError",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "form",
+    "editor": {
+      "label": "Form Error",
+      "category": "content"
+    },
+    "schema": {
+      "fallbackMessage": {
+        "type": "string",
+        "label": "Fallback message"
+      }
+    },
+    "guideline": "Renders the last submit's write failures grouped by fieldset, or nothing when there were none. Set fallbackMessage for a fieldset whose write rejected rather than resolving with userErrors.",
+    "docPath": "src/particles/form/form.md"
+  },
+  "FormClear": {
+    "name": "FormClear",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "form",
+    "editor": {
+      "label": "Form Clear",
+      "category": "action"
+    },
+    "schema": {
+      "label": {
+        "type": "string",
+        "label": "Label"
+      }
+    },
+    "guideline": "Empties every field registered by every fieldset inside the enclosing FormRoot, not only the nearest one, but marks dirty only the fields whose value actually changed — a field already empty stays clean. Renders children, then label, then the message catalog (fs/form.clear). The following submit dispatches a write for every fieldset that had something to clear, and nothing for one where clearing was a no-op. There is no way to scope it to a single fieldset; place it only where clearing the whole form is the intended action, not by analogy with a per-field clear.",
+    "docPath": "src/particles/form/form.md"
+  },
+  "FormReset": {
+    "name": "FormReset",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "form",
+    "editor": {
+      "label": "Form Reset",
+      "category": "action"
+    },
+    "schema": {
+      "label": {
+        "type": "string",
+        "label": "Label"
+      }
+    },
+    "guideline": "Returns every registered field to react-hook-form's baseline for that name and clears its dirty/touched state. Renders children, then label, then the message catalog (fs/form.reset). Before a fieldset's first successful write, that baseline is whatever the field's own seed resolves to — not empty — so Reset reverts to the original value rather than clearing it; only after a successful submit does the baseline become what was last written.",
+    "docPath": "src/particles/form/form.md"
+  },
   "GalleryRoot": {
     "name": "GalleryRoot",
     "importPath": "@vtex/faststore/components",
@@ -1964,6 +2252,7 @@
   "PhoneField": {
     "name": "PhoneField",
     "importPath": "@vtex/faststore/components",
+    "providesContext": "phone-field",
     "editor": {
       "label": "Phone Field",
       "category": "action"
@@ -1980,8 +2269,10 @@
         "label": "Label"
       },
       "requirement": {
-        "type": "string",
-        "default": "mandatory",
+        "type": [
+          "mandatory",
+          "optional"
+        ],
         "label": "Requirement"
       },
       "errorInvalid": {
@@ -1995,7 +2286,19 @@
         "label": "Required error message"
       }
     },
-    "guideline": "Locale-aware, business-agnostic phone number input composed from the field + input particles. Applies country masking, validates on blur, and exposes its value via onValueChange. Bind it to a data source (e.g. ClientProfilePhoneControl for checkout) to persist the value.",
+    "guideline": "Locale-aware, business-agnostic phone number input composed from the field + input particles. Applies country masking, validates on blur, and exposes its value via onValueChange. Bind it to a data source (e.g. ClientProfilePhoneControl for checkout) to persist the value. Recomposable (RFC:503): given children, they replace the default Field.Label + PhoneFieldInput + Field.Error anatomy, in any order.",
+    "docPath": "src/particles/phone-field/phone-field.md"
+  },
+  "PhoneFieldInput": {
+    "name": "PhoneFieldInput",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "phone-field",
+    "editor": {
+      "label": "Phone Field Input",
+      "category": "action"
+    },
+    "schema": {},
+    "guideline": "The masked <input type=\"tel\"> PhoneField owns. Must sit inside PhoneField, in either the default anatomy or an author's composed children. Carries the country mask, the composed ref, and PhoneField's own onChange/onBlur — a composed Field.Control here instead re-registers the field with react-hook-form and loses the mask (unsupported, RFC's named double-binder hole).",
     "docPath": "src/particles/phone-field/phone-field.md"
   },
   "PopoverRoot": {
@@ -2171,6 +2474,7 @@
     "schema": {
       "mask": {
         "type": "string",
+        "default": "99999-999",
         "label": "Mask pattern"
       },
       "label": {
@@ -2360,6 +2664,60 @@
     "schema": {},
     "guideline": "Corner piece displayed when both vertical and horizontal scrollbars are visible."
   },
+  "FieldSelectRoot": {
+    "name": "FieldSelectRoot",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "field",
+    "editor": {
+      "label": "Field Select Root",
+      "category": "layout"
+    },
+    "schema": {
+      "modal": {
+        "type": "boolean",
+        "default": true,
+        "label": "Modal"
+      }
+    },
+    "guideline": "Bound select over the shipped Select particle: reads the enclosing field contract and drives Select.Root through react-hook-form. Childless, it renders the full default anatomy (trigger, value, icon, popup, list, one item per option); given children, place FieldSelect.Trigger/Value/Options among the generic Select.* parts to recompose it.",
+    "docPath": "src/particles/select/select.md"
+  },
+  "FieldSelectTrigger": {
+    "name": "FieldSelectTrigger",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "field",
+    "editor": {
+      "label": "Field Select Trigger",
+      "category": "action"
+    },
+    "schema": {},
+    "guideline": "Bound select's trigger: announces the field's resolved requiredness as aria-required (never native required, so react-hook-form's validation runs instead of the browser's). A select carries no raise of its own, so the fieldset's rule is the whole of it. Place FieldSelect.Value and, optionally, Select.Icon inside it.",
+    "docPath": "src/particles/select/select.md"
+  },
+  "FieldSelectValue": {
+    "name": "FieldSelectValue",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "field",
+    "editor": {
+      "label": "Field Select Value",
+      "category": "layout"
+    },
+    "schema": {},
+    "guideline": "Resolves the trigger's label from the field contract's options, so the chosen option's label shows on first paint instead of the raw stored value. Falls back to the raw value when nothing matches, and to the placeholder when empty.",
+    "docPath": "src/particles/select/select.md"
+  },
+  "FieldSelectOptions": {
+    "name": "FieldSelectOptions",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "field",
+    "editor": {
+      "label": "Field Select Options",
+      "category": "content"
+    },
+    "schema": {},
+    "guideline": "Renders one Select.Item per field contract option, in contract order — the option list is platform data, never authored here. Pass children (e.g. a Select.ItemIndicator) to render inside every item, after its text.",
+    "docPath": "src/particles/select/select.md"
+  },
   "SelectRoot": {
     "name": "SelectRoot",
     "importPath": "@vtex/faststore/components",
@@ -2389,7 +2747,8 @@
         "label": "Read Only"
       }
     },
-    "guideline": "Root of a select dropdown. Manages selection state, modal overlay, and form integration. Compose as: SelectRoot > (SelectLabel + SelectTrigger > (SelectValue + SelectIcon) + SelectPortal > (SelectBackdrop + SelectPositioner > SelectPopup > (SelectScrollUpArrow + SelectList > [SelectItem > (SelectItemText + SelectItemIndicator)] + SelectScrollDownArrow))). Use SelectGroup > (SelectGroupLabel + [SelectItem]) for grouped options. Set modal=false to allow interacting with background elements while open."
+    "guideline": "Root of a select dropdown. Manages selection state, modal overlay, and form integration. Compose as: SelectRoot > (SelectLabel + SelectTrigger > (SelectValue + SelectIcon) + SelectPortal > (SelectBackdrop + SelectPositioner > SelectPopup > (SelectScrollUpArrow + SelectList > [SelectItem > (SelectItemText + SelectItemIndicator)] + SelectScrollDownArrow))). Use SelectGroup > (SelectGroupLabel + [SelectItem]) for grouped options. Set modal=false to allow interacting with background elements while open.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectLabel": {
     "name": "SelectLabel",
@@ -2399,7 +2758,8 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Accessible label associated with the trigger. Always place outside Select.Trigger so screen readers announce it separately."
+    "guideline": "Accessible label associated with the trigger. Always place outside Select.Trigger so screen readers announce it separately.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectTrigger": {
     "name": "SelectTrigger",
@@ -2415,7 +2775,8 @@
         "label": "Disabled"
       }
     },
-    "guideline": "Opens and closes the popup on click. Use data-open and data-placeholder CSS attributes for open-state and empty-state styling."
+    "guideline": "Opens and closes the popup on click. Use data-open and data-placeholder CSS attributes for open-state and empty-state styling.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectValue": {
     "name": "SelectValue",
@@ -2425,7 +2786,8 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Renders the selected item's text, or placeholder when nothing is selected. Style the placeholder state via [data-fs-select-value][data-placeholder]."
+    "guideline": "Renders the selected item's text, or placeholder when nothing is selected. Style the placeholder state via [data-fs-select-value][data-placeholder].",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectIcon": {
     "name": "SelectIcon",
@@ -2435,7 +2797,8 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Decorative indicator (e.g. chevron) inside the trigger. Rotates or changes when the popup opens via data-open."
+    "guideline": "Decorative indicator (e.g. chevron) inside the trigger. Rotates or changes when the popup opens via data-open.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectPortal": {
     "name": "SelectPortal",
@@ -2445,7 +2808,8 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Teleports popup content to <body>. Always wrap Select.Positioner with this to avoid overflow/z-index issues."
+    "guideline": "Teleports popup content to <body>. Always wrap Select.Positioner with this to avoid overflow/z-index issues.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectBackdrop": {
     "name": "SelectBackdrop",
@@ -2455,7 +2819,8 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Invisible overlay that closes the select when clicked outside. Required when modal=true to trap interaction."
+    "guideline": "Invisible overlay that closes the select when clicked outside. Required when modal=true to trap interaction.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectPositioner": {
     "name": "SelectPositioner",
@@ -2495,7 +2860,8 @@
         "label": "Align Item With Trigger"
       }
     },
-    "guideline": "Positions the popup relative to the trigger. Use side and align to control placement; alignItemWithTrigger=true overlaps the trigger to align the selected item visually."
+    "guideline": "Positions the popup relative to the trigger. Use side and align to control placement; alignItemWithTrigger=true overlaps the trigger to align the selected item visually.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectScrollUpArrow": {
     "name": "SelectScrollUpArrow",
@@ -2511,7 +2877,8 @@
         "label": "Keep Mounted"
       }
     },
-    "guideline": "Scrolls the list upward when hovered. Appears automatically when the list overflows at the top."
+    "guideline": "Scrolls the list upward when hovered. Appears automatically when the list overflows at the top.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectPopup": {
     "name": "SelectPopup",
@@ -2521,7 +2888,8 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Visible container for the select list. Apply background, shadow, and border styles here."
+    "guideline": "Visible container for the select list. Apply background, shadow, and border styles here.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectArrow": {
     "name": "SelectArrow",
@@ -2531,7 +2899,8 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Pointing arrow attached to the popup indicating the anchor. Optional — omit when not using an arrow indicator."
+    "guideline": "Pointing arrow attached to the popup indicating the anchor. Optional — omit when not using an arrow indicator.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectList": {
     "name": "SelectList",
@@ -2541,7 +2910,8 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Scrollable container for all Select.Item elements. Apply max-height and overflow for scrolling."
+    "guideline": "Scrollable container for all Select.Item elements. Apply max-height and overflow for scrolling.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectItem": {
     "name": "SelectItem",
@@ -2561,7 +2931,8 @@
         "label": "Disabled"
       }
     },
-    "guideline": "One selectable option. Requires a unique value prop. Style selected and highlighted states via data-selected and data-highlighted attributes."
+    "guideline": "One selectable option. Requires a unique value prop. Style selected and highlighted states via data-selected and data-highlighted attributes.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectItemText": {
     "name": "SelectItemText",
@@ -2571,7 +2942,8 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "The visible text label of an item. Base UI uses this for keyboard navigation matching."
+    "guideline": "The visible text label of an item. Base UI uses this for keyboard navigation matching.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectItemIndicator": {
     "name": "SelectItemIndicator",
@@ -2587,7 +2959,8 @@
         "label": "Keep Mounted"
       }
     },
-    "guideline": "Checkmark or indicator shown only on the selected item. Set keepMounted=true to animate in/out."
+    "guideline": "Checkmark or indicator shown only on the selected item. Set keepMounted=true to animate in/out.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectSeparator": {
     "name": "SelectSeparator",
@@ -2597,7 +2970,8 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Visual divider between items or groups. Use between unrelated option groups."
+    "guideline": "Visual divider between items or groups. Use between unrelated option groups.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectGroup": {
     "name": "SelectGroup",
@@ -2607,7 +2981,8 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Groups related items under a shared SelectGroupLabel for semantic and visual grouping."
+    "guideline": "Groups related items under a shared SelectGroupLabel for semantic and visual grouping.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectGroupLabel": {
     "name": "SelectGroupLabel",
@@ -2617,7 +2992,8 @@
       "category": "layout"
     },
     "schema": {},
-    "guideline": "Non-interactive label for a Select.Group. Announced by screen readers as a group name."
+    "guideline": "Non-interactive label for a Select.Group. Announced by screen readers as a group name.",
+    "docPath": "src/particles/select/select.md"
   },
   "SelectScrollDownArrow": {
     "name": "SelectScrollDownArrow",
@@ -2633,7 +3009,8 @@
         "label": "Keep Mounted"
       }
     },
-    "guideline": "Scrolls the list downward when hovered. Appears when the list overflows at the bottom."
+    "guideline": "Scrolls the list downward when hovered. Appears when the list overflows at the bottom.",
+    "docPath": "src/particles/select/select.md"
   },
   "Separator": {
     "name": "Separator",
@@ -3298,54 +3675,167 @@
     "guideline": "The account menu's navigation landmark and its items, and nothing else — it surrounds the items alone so the section's own content stays outside the navigation region. Author the label: a landmark with no accessible name is one a screen-reader user cannot tell from any other. The current section carries aria-current, page for the section itself and true for a page inside it, with data-fs-account-menu-item-current beside it as a style target and never as the only signal. When the list scrolls, the current item is brought into view on mount and on every route change. Must be a descendant of AccountMenuRoot.",
     "docPath": "src/matter/account-menu/account-menu.md"
   },
-  "BreadcrumbRoot": {
-    "name": "BreadcrumbRoot",
+  "BillingAddress": {
+    "name": "BillingAddress",
     "importPath": "@vtex/faststore/components",
-    "fragment": "\n  fragment BreadcrumbData on Query {\n    productBySlug(slug: $slug) {\n      breadcrumbs {\n        name\n        url\n        position\n      }\n    }\n  }\n",
+    "requiresContext": "payment",
+    "actions": {
+      "payment": [
+        "setBillingAddress"
+      ]
+    },
     "editor": {
-      "label": "Breadcrumb Root",
-      "category": "navigation"
+      "label": "Billing Address",
+      "category": "commerce"
     },
     "schema": {
-      "label": {
+      "sameAsDeliveryLabel": {
         "type": "string",
-        "default": "Breadcrumb",
-        "label": "Aria Label"
-      }
-    },
-    "guideline": "Root container for breadcrumb navigation; compose as BreadcrumbRoot > BreadcrumbList > [BreadcrumbLink + BreadcrumbSeparator]."
-  },
-  "BreadcrumbList": {
-    "name": "BreadcrumbList",
-    "importPath": "@vtex/faststore/components",
-    "editor": {
-      "label": "Breadcrumb List",
-      "category": "navigation"
-    },
-    "schema": {},
-    "guideline": "Ordered list of breadcrumb items; must be a direct child of BreadcrumbRoot."
-  },
-  "BreadcrumbLink": {
-    "name": "BreadcrumbLink",
-    "importPath": "@vtex/faststore/components",
-    "editor": {
-      "label": "Breadcrumb Link",
-      "category": "navigation"
-    },
-    "schema": {},
-    "guideline": "Renders the label and link for a breadcrumb item; must be inside BreadcrumbList."
-  },
-  "BreadcrumbSeparator": {
-    "name": "BreadcrumbSeparator",
-    "importPath": "@vtex/faststore/components",
-    "editor": {
-      "label": "Breadcrumb Separator",
-      "category": "navigation"
-    },
-    "schema": {},
-    "guideline": "Decorative separator rendered between breadcrumb items; must be inside BreadcrumbList."
-  },
-  "BuyButtonRoot": {
+        "default": "Billing address same as delivery address",
+        "label": "Same-as-delivery toggle label"
+      },
+      "defaultCountry": {
+        "type": "string",
+        "default": "BRA",
+        "label": "Default country (ISO-3)"
+      },
+      "countryLabel": {
+        "type": "string",
+        "default": "Country",
+        "label": "Country field label"
+      },
+      "submitLabel": {
+        "type": "string",
+        "default": "Save billing address",
+        "label": "Submit button label"
+      },
+      "submitPendingLabel": {
+        "type": "string",
+        "default": "Saving...",
+        "label": "Submit button pending label"
+      },
+      "requiredNoticeLabel": {
+        "type": "string",
+        "default": "This payment method requires a billing address.",
+        "label": "Required-billing-address notice label"
+      },
+      "unsavedAddressNoticeLabel": {
+        "type": "string",
+        "default": "No billing address has been saved yet — the delivery address will be used unless you save one below.",
+        "label": "Unsaved-address notice label"
+      },
+      "billingMatchNoticeLabel": {
+        "type": "string",
+        "default": "Your billing address must match the one on your card or bank statement, or your bank may decline the order.",
+        "label": "Billing-match disclaimer"
+      },
+      "billingMatchNoticeVisible": {
+        "type": "boolean",
+        "default": true,
+        "label": "Show the billing-match disclaimer"
+      },
+      "recipientNameLabel": {
+        "type": "string",
+        "default": "Recipient's name",
+        "label": "Recipient name field label"
+      },
+      "streetLabel": {
+        "type": "string",
+        "default": "Street",
+        "label": "Street field label"
+      },
+      "numberLabel": {
+        "type": "string",
+        "default": "Number",
+        "label": "Number field label"
+      },
+      "complementLabel": {
+        "type": "string",
+        "default": "Complement (optional)",
+        "label": "Complement field label"
+      },
+      "neighborhoodLabel": {
+        "type": "string",
+        "default": "Neighborhood",
+        "label": "Neighborhood field label"
+      },
+      "cityLabel": {
+        "type": "string",
+        "default": "City",
+        "label": "City field label"
+      },
+      "stateLabel": {
+        "type": "string",
+        "default": "State",
+        "label": "State field label"
+      },
+      "postalCodeLabel": {
+        "type": "string",
+        "default": "Postal code",
+        "label": "Postal code field label"
+      },
+      "fieldRequiredMessage": {
+        "type": "string",
+        "default": "This field is required.",
+        "label": "Field required message"
+      },
+      "disabled": {
+        "type": "boolean",
+        "default": false,
+        "label": "Disabled"
+      }
+    },
+    "guideline": "Same-as-delivery toggle (default on) for the billing address; when off, mounts a country-specific address form (reusing shipping-address's country descriptors) and persists it via $actions.payment.setBillingAddress on an explicit submit control. Re-checking the toggle dispatches sameAsDelivery: true only once an address was actually persisted (otherwise it's a local no-op — there's nothing on the server to revert). Publishes only a boolean (never the address) onto the shared payment draft for usePlaceOrder to read. While the form is open and nothing has been saved yet, renders an inline status notice — the required attribute on the form's own fields is not a submit gate; Place Order can still complete billed to the delivery address if the shopper never saves. Must be inside a PaymentSectionRoot or PaymentSectionController; place as a sibling of CardEntry/SavedCards/Installments/SaveCard/PlaceOrder, never nested inside any of them. See billing-address.md.",
+    "docPath": "src/matter/billing-address/billing-address.md"
+  },
+  "BreadcrumbRoot": {
+    "name": "BreadcrumbRoot",
+    "importPath": "@vtex/faststore/components",
+    "fragment": "\n  fragment BreadcrumbData on Query {\n    productBySlug(slug: $slug) {\n      breadcrumbs {\n        name\n        url\n        position\n      }\n    }\n  }\n",
+    "editor": {
+      "label": "Breadcrumb Root",
+      "category": "navigation"
+    },
+    "schema": {
+      "label": {
+        "type": "string",
+        "default": "Breadcrumb",
+        "label": "Aria Label"
+      }
+    },
+    "guideline": "Root container for breadcrumb navigation; compose as BreadcrumbRoot > BreadcrumbList > [BreadcrumbLink + BreadcrumbSeparator]."
+  },
+  "BreadcrumbList": {
+    "name": "BreadcrumbList",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Breadcrumb List",
+      "category": "navigation"
+    },
+    "schema": {},
+    "guideline": "Ordered list of breadcrumb items; must be a direct child of BreadcrumbRoot."
+  },
+  "BreadcrumbLink": {
+    "name": "BreadcrumbLink",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Breadcrumb Link",
+      "category": "navigation"
+    },
+    "schema": {},
+    "guideline": "Renders the label and link for a breadcrumb item; must be inside BreadcrumbList."
+  },
+  "BreadcrumbSeparator": {
+    "name": "BreadcrumbSeparator",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Breadcrumb Separator",
+      "category": "navigation"
+    },
+    "schema": {},
+    "guideline": "Decorative separator rendered between breadcrumb items; must be inside BreadcrumbList."
+  },
+  "BuyButtonRoot": {
     "name": "BuyButtonRoot",
     "importPath": "@vtex/faststore/components",
     "fragment": "\n  fragment BuyButtonData on Query {\n    productBySlug(slug: $slug) {\n      id\n      title\n      slug\n      images(first: 1) {\n        edges {\n          node {\n            url\n            altText\n          }\n        }\n      }\n      variants(first: 1) {\n        edges {\n          node {\n            id\n            sku\n            availableForSale\n            sellers {\n              id\n              isDefault\n              offer {\n                price { amount currencyCode }\n                listPrice { amount currencyCode }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n",
@@ -3391,6 +3881,144 @@
     "guideline": "The add-to-cart button; must be a descendant of BuyButtonRoot. Cart writes flow through $actions.cart, so no CartRoot ancestor is required.",
     "docPath": "src/matter/buy-button/buy-button.md"
   },
+  "CardEntry": {
+    "name": "CardEntry",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "card-capture",
+    "editor": {
+      "label": "Card Entry",
+      "category": "commerce"
+    },
+    "schema": {
+      "legend": {
+        "type": "string",
+        "default": "Card details",
+        "label": "Legend"
+      },
+      "numberLabel": {
+        "type": "string",
+        "default": "Card number",
+        "label": "Number label"
+      },
+      "numberPlaceholder": {
+        "type": "string",
+        "label": "Number placeholder"
+      },
+      "holderNameLabel": {
+        "type": "string",
+        "default": "Cardholder name",
+        "label": "Holder name label"
+      },
+      "holderNamePlaceholder": {
+        "type": "string",
+        "label": "Holder name placeholder"
+      },
+      "expirationLabel": {
+        "type": "string",
+        "default": "Expiration date",
+        "label": "Expiration label"
+      },
+      "expirationPlaceholder": {
+        "type": "string",
+        "default": "MM/YY",
+        "label": "Expiration placeholder"
+      },
+      "cvvLabel": {
+        "type": "string",
+        "default": "Security code",
+        "label": "CVV label"
+      },
+      "cvvPlaceholder": {
+        "type": "string",
+        "label": "CVV placeholder"
+      },
+      "cvvDescription": {
+        "type": "string",
+        "default": "The 3-4 digit number on your card",
+        "label": "CVV description"
+      },
+      "numberRequiredMessage": {
+        "type": "string",
+        "default": "Card number is required",
+        "label": "Number required message"
+      },
+      "numberInvalidMessage": {
+        "type": "string",
+        "default": "Enter a valid card number",
+        "label": "Number invalid message"
+      },
+      "holderNameRequiredMessage": {
+        "type": "string",
+        "default": "Cardholder name is required",
+        "label": "Holder name required message"
+      },
+      "expirationRequiredMessage": {
+        "type": "string",
+        "default": "Expiration date is required",
+        "label": "Expiration required message"
+      },
+      "expirationInvalidMessage": {
+        "type": "string",
+        "default": "Enter a valid expiration date",
+        "label": "Expiration invalid message"
+      },
+      "expirationExpiredMessage": {
+        "type": "string",
+        "default": "This card has expired",
+        "label": "Expiration expired message"
+      },
+      "cvvRequiredMessage": {
+        "type": "string",
+        "default": "Security code is required",
+        "label": "CVV required message"
+      },
+      "cvvInvalidMessage": {
+        "type": "string",
+        "default": "Enter a valid security code",
+        "label": "CVV invalid message"
+      },
+      "disabled": {
+        "type": "boolean",
+        "default": false,
+        "label": "Disabled"
+      }
+    },
+    "guideline": "New-card entry: masked number with live network detection, holder name, expiration, and CVV, each shown and required per the detected network's validator config from the 'card-capture' context. Must be placed inside a card-capture provider: PaymentSectionRoot or PaymentSectionController at checkout. Owns the card values itself — it builds the card and hands it only to the submission target its provider supplies; no other component ever needs the card number or CVV. Card number and CVV are never schema props, fragment fields, or action payloads — do not add one. See card-entry.md.",
+    "docPath": "src/matter/card-entry/card-entry.md"
+  },
+  "CardholderDocument": {
+    "name": "CardholderDocument",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "payment",
+    "editor": {
+      "label": "Cardholder Document",
+      "category": "commerce"
+    },
+    "schema": {
+      "label": {
+        "type": "string",
+        "default": "CPF",
+        "label": "Label"
+      },
+      "placeholder": {
+        "type": "string",
+        "default": "000.000.000-00",
+        "label": "Placeholder"
+      },
+      "errorMessage": {
+        "type": "string",
+        "default": "Invalid CPF",
+        "label": "Error message"
+      },
+      "disabled": {
+        "type": "boolean",
+        "default": false,
+        "label": "Disabled"
+      }
+    },
+    "guideline": "Cardholder tax-document field for the currently selected payment method (CPF only in this build): renders only when that method's validator marks a document displayable, and marks the input required when the validator marks the document required — the particle, not this leaf, decides whether a typed value is well-formed. Place as a sibling of CardEntry and SavedCards inside a PaymentSectionRoot or PaymentSectionController; renders nothing before a method is selected or when the selected method has no document to collect. The collected value is a plain draft fact — never a schema prop, a fragment field, or an action payload — and is unrelated to the shopper's saved profile document, which this component never reads. See cardholder-document.md.",
+    "docPath": "src/matter/cardholder-document/cardholder-document.md"
+  },
   "CartRoot": {
     "name": "CartRoot",
     "importPath": "@vtex/faststore/components",
@@ -4205,12 +4833,93 @@
     },
     "docPath": "src/matter/cart-totalizer/cart-totalizer.md"
   },
+  "ClientPreferencesFieldset": {
+    "name": "ClientPreferencesFieldset",
+    "importPath": "@vtex/faststore/components",
+    "fragment": "\n  fragment ClientPreferencesFieldsetData on Query {\n    clientPreferences {\n      __typename\n      id\n      optinNewsLetter\n      savePersonalData\n    }\n  }\n",
+    "fetchStrategy": "reactive",
+    "skeleton": "ClientPreferencesFieldsetSkeleton",
+    "requiresContext": [
+      "form",
+      "session"
+    ],
+    "providesContext": "client-preferences",
+    "actions": {
+      "identity": [
+        "clientPreferencesUpdate"
+      ]
+    },
+    "editor": {
+      "label": "Client Preferences Fieldset",
+      "category": "identity"
+    },
+    "schema": {
+      "skeletonCount": {
+        "type": "number",
+        "default": 2,
+        "label": "Skeleton rows"
+      },
+      "loadingLabel": {
+        "type": "string",
+        "default": "Loading your preferences",
+        "label": "Loading announcement"
+      },
+      "loadedLabel": {
+        "type": "string",
+        "default": "Your preferences are ready",
+        "label": "Loaded announcement"
+      },
+      "groupLabel": {
+        "type": "string",
+        "default": "Your preferences",
+        "label": "Accessible group name"
+      }
+    },
+    "guideline": "Registers a batched write of the ClientPreferences entity with the enclosing FormRoot; renders one Fieldset.Root and no <form>. Distinct from ClientPreferencesRoot (matter/client-preferences), which writes on toggle and requires client-preferences-toggle — the two cannot compile into each other's container. Must be inside a FormRoot with a SessionRoot ancestor. Compose ClientPreferencesNewsletterControl and/or ClientPreferencesSavePersonalDataControl as children. The controls mount only once the preferences have resolved, with skeletonCount placeholder rows in their place until then — set it to the number of controls composed, or the form jumps by the difference. Style the announcement sr-only. Dispatches only the flags the shopper changed. groupLabel names the group as its accessible name; blank emits no aria-label, and a composed FieldsetLegend wins over it.",
+    "docPath": "src/matter/client-preferences/client-preferences-fieldset.md"
+  },
+  "ClientPreferencesNewsletterControl": {
+    "name": "ClientPreferencesNewsletterControl",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "client-preferences",
+    "providesContext": "field",
+    "editor": {
+      "label": "Client Preferences Newsletter Control",
+      "category": "identity"
+    },
+    "schema": {
+      "label": {
+        "type": "string",
+        "label": "Label"
+      }
+    },
+    "guideline": "The bound newsletter opt-in control; must be a descendant of ClientPreferencesFieldset. Renders Field.Root > Field.Label > Field.Checkbox by default, or the composed children in the author's own order. Defaults to unchecked.",
+    "docPath": "src/matter/client-preferences/client-preferences-fieldset.md"
+  },
+  "ClientPreferencesSavePersonalDataControl": {
+    "name": "ClientPreferencesSavePersonalDataControl",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "client-preferences",
+    "providesContext": "field",
+    "editor": {
+      "label": "Client Preferences Save Personal Data Control",
+      "category": "identity"
+    },
+    "schema": {
+      "label": {
+        "type": "string",
+        "label": "Label"
+      }
+    },
+    "guideline": "The bound save-personal-data opt-in control; must be a descendant of ClientPreferencesFieldset. Renders Field.Root > Field.Label > Field.Checkbox by default, or the composed children in the author's own order. Defaults to unchecked.",
+    "docPath": "src/matter/client-preferences/client-preferences-fieldset.md"
+  },
   "ClientPreferencesRoot": {
     "name": "ClientPreferencesRoot",
     "importPath": "@vtex/faststore/components",
     "fragment": "\n  fragment ClientPreferencesData on Query {\n    clientPreferences {\n      __typename\n      id\n      optinNewsLetter\n      savePersonalData\n    }\n  }\n",
     "fetchStrategy": "reactive",
-    "providesContext": "client-preferences",
+    "providesContext": "client-preferences-toggle",
     "requiresContext": "session",
     "editor": {
       "label": "Client Preferences Root",
@@ -4223,7 +4932,7 @@
   "NewsletterOptInControl": {
     "name": "NewsletterOptInControl",
     "importPath": "@vtex/faststore/components",
-    "requiresContext": "client-preferences",
+    "requiresContext": "client-preferences-toggle",
     "actions": {
       "identity": [
         "clientPreferencesUpdate"
@@ -4245,7 +4954,7 @@
   "SavePersonalDataOptInControl": {
     "name": "SavePersonalDataOptInControl",
     "importPath": "@vtex/faststore/components",
-    "requiresContext": "client-preferences",
+    "requiresContext": "client-preferences-toggle",
     "actions": {
       "identity": [
         "clientPreferencesUpdate"
@@ -4304,7 +5013,10 @@
         "label": "Country (US or BR)"
       },
       "requirement": {
-        "type": "string",
+        "type": [
+          "mandatory",
+          "optional"
+        ],
         "default": "mandatory",
         "label": "Requirement"
       },
@@ -4322,22 +5034,25 @@
     "guideline": "The bound phone field; must be a descendant of ClientProfileRoot. Reads the saved phone from the ClientProfile entity and persists it on blur via $actions.identity.clientProfileUpdate({ phone }). Composes the reusable PhoneField particle.",
     "docPath": "src/matter/client-profile/client-profile.md"
   },
-  "ClientProfileFormRoot": {
-    "name": "ClientProfileFormRoot",
+  "ClientProfileFieldset": {
+    "name": "ClientProfileFieldset",
     "importPath": "@vtex/faststore/components",
-    "fragment": "\n  fragment ClientProfileFormData on Query {\n    clientProfile {\n      __typename\n      id\n      email\n      firstName\n      lastName\n      phone\n      document\n    }\n    clientPreferences {\n      __typename\n      id\n      optinNewsLetter\n      savePersonalData\n    }\n  }\n",
+    "fragment": "\n  fragment ClientProfileFieldsetData on Query {\n    clientProfile {\n      __typename\n      id\n      firstName\n      lastName\n      phone\n      document\n    }\n  }\n",
     "fetchStrategy": "reactive",
-    "requiresContext": "session",
-    "providesContext": "client-profile-form",
+    "skeleton": "ClientProfileFieldsetSkeleton",
+    "requiresContext": [
+      "form",
+      "session"
+    ],
+    "providesContext": "client-profile-fieldset",
     "actions": {
       "identity": [
-        "clientProfileUpdate",
-        "clientPreferencesUpdate"
+        "clientProfileUpdate"
       ]
     },
     "editor": {
-      "label": "Client Profile Form Root",
-      "category": "action"
+      "label": "Client Profile Fieldset",
+      "category": "identity"
     },
     "schema": {
       "country": {
@@ -4348,205 +5063,143 @@
       "documentType": {
         "type": "string",
         "label": "Document type (e.g. CPF)"
+      },
+      "skeletonCount": {
+        "type": "number",
+        "default": 4,
+        "label": "Skeleton rows"
+      },
+      "loadingLabel": {
+        "type": "string",
+        "default": "Loading your details",
+        "label": "Loading announcement"
+      },
+      "loadedLabel": {
+        "type": "string",
+        "default": "Your details are ready",
+        "label": "Loaded announcement"
+      },
+      "groupLabel": {
+        "type": "string",
+        "default": "Your details",
+        "label": "Accessible group name"
       }
     },
-    "guideline": "Data root + form mechanics for the batched customer-information form: owns the draft across clientProfile + clientPreferences, dirty tracking, format-only validation (never requiredness), one batched Save (dispatches only touched fields), and the confirmation on a clean save. It reports nothing to anything outside itself. Requires a SessionRoot ancestor. Compose the field/fieldset/feedback parts as children in any order/subset. See client-profile-form.md.",
-    "docPath": "src/matter/client-profile-form/client-profile-form.md"
+    "guideline": "Registers a batched write of the ClientProfile entity with the enclosing FormRoot; renders one Fieldset.Root and no <form>. Must be inside a FormRoot with a SessionRoot ancestor. Compose ClientProfileFirstNameControl / ClientProfileLastNameControl / ClientProfileFieldsetPhoneControl / ClientProfileDocumentControl as children, in any order. The controls mount only once the profile has resolved, with skeletonCount placeholder rows in their place until then — set it to the number of controls composed, or the form jumps by the difference. Style the announcement sr-only. Dispatches only the fields the shopper changed. groupLabel names the group as its accessible name; blank emits no aria-label, and a composed FieldsetLegend wins over it.",
+    "docPath": "src/matter/client-profile-form/client-profile-fieldset.md"
   },
-  "ClientProfileFormFieldset": {
-    "name": "ClientProfileFormFieldset",
+  "ClientProfileFirstNameControl": {
+    "name": "ClientProfileFirstNameControl",
     "importPath": "@vtex/faststore/components",
-    "requiresContext": "client-profile-form",
+    "requiresContext": "client-profile-fieldset",
+    "providesContext": "field",
     "editor": {
-      "label": "Client Profile Form Fieldset",
-      "category": "layout"
+      "label": "Client Profile First Name Control",
+      "category": "identity"
     },
     "schema": {
-      "legend": {
+      "label": {
         "type": "string",
-        "label": "Legend"
+        "label": "Label"
       },
-      "section": {
+      "placeholder": {
         "type": "string",
-        "label": "Section name (data-fs hook)"
+        "label": "Placeholder"
       }
     },
-    "guideline": "Optional grouping wrapper: a Fieldset whose disabled state follows the form, with an optional legend and a `section` name emitted on data-fs-client-profile-form-section for scoped styling. Compose any subset of the field parts as children. Must be inside ClientProfileForm.Root.",
-    "docPath": "src/matter/client-profile-form/client-profile-form.md"
+    "guideline": "The bound first-name control; must be a descendant of ClientProfileFieldset. Renders Field.Root > Field.Label + Field.Control + Field.Error by default, or the composed children in the author's own order.",
+    "docPath": "src/matter/client-profile-form/client-profile-fieldset.md"
   },
-  "ClientProfileFormEmailField": {
-    "name": "ClientProfileFormEmailField",
+  "ClientProfileLastNameControl": {
+    "name": "ClientProfileLastNameControl",
     "importPath": "@vtex/faststore/components",
-    "requiresContext": "client-profile-form",
+    "requiresContext": "client-profile-fieldset",
+    "providesContext": "field",
     "editor": {
-      "label": "Client Profile Email Field",
-      "category": "action"
+      "label": "Client Profile Last Name Control",
+      "category": "identity"
     },
     "schema": {
       "label": {
         "type": "string",
-        "default": "Email",
         "label": "Label"
-      }
-    },
-    "guideline": "Read-only email display, seeded from the profile. Must be inside ClientProfileForm.Root.",
-    "docPath": "src/matter/client-profile-form/client-profile-form.md"
-  },
-  "ClientProfileFormFirstNameField": {
-    "name": "ClientProfileFormFirstNameField",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "client-profile-form",
-    "editor": {
-      "label": "Client Profile First Name Field",
-      "category": "action"
-    },
-    "schema": {
-      "label": {
+      },
+      "placeholder": {
         "type": "string",
-        "default": "First name",
-        "label": "Label"
+        "label": "Placeholder"
       }
     },
-    "guideline": "First-name text field bound to the form draft. Must be inside ClientProfileForm.Root.",
-    "docPath": "src/matter/client-profile-form/client-profile-form.md"
+    "guideline": "The bound last-name control; must be a descendant of ClientProfileFieldset. Renders Field.Root > Field.Label + Field.Control + Field.Error by default, or the composed children in the author's own order.",
+    "docPath": "src/matter/client-profile-form/client-profile-fieldset.md"
   },
-  "ClientProfileFormLastNameField": {
-    "name": "ClientProfileFormLastNameField",
+  "ClientProfileFieldsetPhoneControl": {
+    "name": "ClientProfileFieldsetPhoneControl",
     "importPath": "@vtex/faststore/components",
-    "requiresContext": "client-profile-form",
+    "requiresContext": "client-profile-fieldset",
+    "providesContext": [
+      "field",
+      "phone-field"
+    ],
     "editor": {
-      "label": "Client Profile Last Name Field",
-      "category": "action"
+      "label": "Client Profile Fieldset Phone Control",
+      "category": "identity"
     },
     "schema": {
       "label": {
         "type": "string",
-        "default": "Last name",
         "label": "Label"
-      }
-    },
-    "guideline": "Last-name text field bound to the form draft. Must be inside ClientProfileForm.Root.",
-    "docPath": "src/matter/client-profile-form/client-profile-form.md"
-  },
-  "ClientProfileFormPhoneField": {
-    "name": "ClientProfileFormPhoneField",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "client-profile-form",
-    "editor": {
-      "label": "Client Profile Phone Field",
-      "category": "action"
-    },
-    "schema": {
-      "label": {
+      },
+      "placeholder": {
         "type": "string",
-        "default": "Phone number",
-        "label": "Label"
-      }
-    },
-    "guideline": "Country-masked phone field (country from Root); format-validated on Save. Must be inside ClientProfileForm.Root.",
-    "docPath": "src/matter/client-profile-form/client-profile-form.md"
-  },
-  "ClientProfileFormDocumentField": {
-    "name": "ClientProfileFormDocumentField",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "client-profile-form",
-    "editor": {
-      "label": "Client Profile Document Field",
-      "category": "action"
-    },
-    "schema": {
-      "label": {
+        "label": "Placeholder"
+      },
+      "requirement": {
+        "type": [
+          "mandatory",
+          "optional"
+        ],
+        "label": "Requirement"
+      },
+      "errorInvalid": {
         "type": "string",
-        "default": "CPF",
-        "label": "Label"
-      }
-    },
-    "guideline": "Tax-document field; self-gates on Root.documentType and check-digit-validates on Save. Must be inside ClientProfileForm.Root.",
-    "docPath": "src/matter/client-profile-form/client-profile-form.md"
-  },
-  "ClientProfileFormNewsletterCheckbox": {
-    "name": "ClientProfileFormNewsletterCheckbox",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "client-profile-form",
-    "editor": {
-      "label": "Client Profile Newsletter Checkbox",
-      "category": "action"
-    },
-    "schema": {
-      "label": {
+        "label": "Invalid error message"
+      },
+      "errorRequired": {
         "type": "string",
-        "default": "Email me with news and offers",
-        "label": "Label"
+        "label": "Required error message"
       }
     },
-    "guideline": "Newsletter opt-in checkbox bound to the form draft. Must be inside ClientProfileForm.Root.",
-    "docPath": "src/matter/client-profile-form/client-profile-form.md"
+    "guideline": "The bound phone control; must be a descendant of ClientProfileFieldset. Distinct from ClientProfilePhoneControl (matter/client-profile), which writes on blur and requires the client-profile context — the two cannot compile into each other's container. Composes the PhoneField particle: recomposable (RFC:503) — given children, they replace PhoneField's default Field.Label + PhoneFieldInput + Field.Error anatomy, in any order; childless keeps today's order. Its className styles PhoneField's own root, the node that lays out label, input and error — not the wrapper, which carries only the data-fs-client-profile-fieldset-field=\"phone\" styling hook. A store that does not want a phone field omits this element from the page: requirement only governs required validation, never visibility.",
+    "docPath": "src/matter/client-profile-form/client-profile-fieldset.md"
   },
-  "ClientProfileFormSavePersonalDataCheckbox": {
-    "name": "ClientProfileFormSavePersonalDataCheckbox",
+  "ClientProfileDocumentControl": {
+    "name": "ClientProfileDocumentControl",
     "importPath": "@vtex/faststore/components",
-    "requiresContext": "client-profile-form",
+    "requiresContext": "client-profile-fieldset",
+    "providesContext": [
+      "field",
+      "document-field"
+    ],
     "editor": {
-      "label": "Client Profile Save-Personal-Data Checkbox",
-      "category": "action"
+      "label": "Client Profile Document Control",
+      "category": "identity"
     },
     "schema": {
       "label": {
         "type": "string",
-        "default": "Save my information for next time",
         "label": "Label"
-      }
-    },
-    "guideline": "Save-personal-data opt-in checkbox bound to the form draft. Must be inside ClientProfileForm.Root.",
-    "docPath": "src/matter/client-profile-form/client-profile-form.md"
-  },
-  "ClientProfileFormError": {
-    "name": "ClientProfileFormError",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "client-profile-form",
-    "editor": {
-      "label": "Client Profile Form Error",
-      "category": "content"
-    },
-    "schema": {},
-    "guideline": "Renders the inline server error (role=\"alert\") from the last Save, or nothing. Must be inside ClientProfileForm.Root.",
-    "docPath": "src/matter/client-profile-form/client-profile-form.md"
-  },
-  "ClientProfileFormConfirmation": {
-    "name": "ClientProfileFormConfirmation",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "client-profile-form",
-    "editor": {
-      "label": "Client Profile Form Confirmation",
-      "category": "content"
-    },
-    "schema": {
-      "message": {
+      },
+      "placeholder": {
         "type": "string",
-        "default": "Your information has been saved.",
-        "label": "Confirmation message"
-      }
-    },
-    "guideline": "Renders the success confirmation (an <output>) after a Save with no errors, cleared on the next edit. Must be inside ClientProfileForm.Root.",
-    "docPath": "src/matter/client-profile-form/client-profile-form.md"
-  },
-  "ClientProfileFormSubmitButton": {
-    "name": "ClientProfileFormSubmitButton",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "client-profile-form",
-    "editor": {
-      "label": "Client Profile Form Submit Button",
-      "category": "action"
-    },
-    "schema": {
-      "label": {
+        "label": "Placeholder"
+      },
+      "errorMessage": {
         "type": "string",
-        "default": "Save and continue",
-        "label": "Button label"
+        "label": "Error message"
       }
     },
-    "guideline": "The batched-Save submit button (type=submit). Disabled while a write is in flight; renders nothing when the session is read-only. Compose an Icon + text as children, or rely on `label`. Must be inside ClientProfileForm.Root.",
-    "docPath": "src/matter/client-profile-form/client-profile-form.md"
+    "guideline": "The bound tax-document control; must be a descendant of ClientProfileFieldset. 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 default Field.Label + DocumentFieldInput + Field.Error anatomy, in any order; childless keeps today's order.",
+    "docPath": "src/matter/client-profile-form/client-profile-fieldset.md"
   },
   "DeliveryOptionsAccordion": {
     "name": "DeliveryOptionsAccordion",
@@ -4770,7 +5423,7 @@
       "category": "commerce"
     },
     "schema": {},
-    "guideline": "Owns the identity section's summary/form toggle: starts on the summary, opens on IdentityEditButton and returns on IdentityEditCancelButton. Saving does not move it, so the form's confirmation stays readable and ClientProfileForm never needs to know about a section around it. Self-contained: collapsing tells nothing else, so no other section opens as a result. Compose an IdentitySummaryView holding the summary parts and an IdentityEditForm holding a ClientProfileForm, plus an IdentityEditButton in the heading and an IdentityEditCancelButton next to the form. No state is named anywhere: which state a part belongs to is which component it is. Renders no DOM of its own.",
+    "guideline": "Owns the identity section's summary/form toggle: starts on the summary, opens on IdentityEditButton and returns on IdentityEditCancelButton. Saving does not move it, so the form stays open and no descendant needs to know about a section around it. Self-contained: collapsing tells nothing else, so no other section opens as a result. Compose an IdentitySummaryView holding the summary parts and an IdentityEditForm holding a FormRoot over ClientProfileFieldset, plus an IdentityEditButton in the heading and an IdentityEditCancelButton next to the form. No state is named anywhere: which state a part belongs to is which component it is. Renders no DOM of its own.",
     "docPath": "src/matter/identity-edit/identity-edit.md"
   },
   "IdentitySummaryView": {
@@ -4794,7 +5447,7 @@
       "category": "commerce"
     },
     "schema": {},
-    "guideline": "Renders its children only while the identity section shows the form, and nothing while it shows the summary. Compose ClientProfileFormRoot and its parts inside, plus an IdentityEditCancelButton. Must be inside an IdentityEditController.",
+    "guideline": "Renders its children only while the identity section shows the form, and nothing while it shows the summary. Compose a FormRoot holding ClientProfileFieldset and its controls inside, plus an IdentityEditCancelButton. Must be inside an IdentityEditController.",
     "docPath": "src/matter/identity-edit/identity-edit.md"
   },
   "IdentityEditButton": {
@@ -4856,7 +5509,7 @@
         "label": "Sign-out error message"
       }
     },
-    "guideline": "Read-only identity summary data root: reads the shopper profile, provides it plus a sign-out action to descendants, and self-gates (renders nothing in the anonymous state). Must be inside SessionRoot. Wrap the parts in an IdentityEditController for the summary/form swap: an IdentitySummaryView holding these parts, an IdentityEditForm holding a ClientProfileForm. See identity-summary.md.",
+    "guideline": "Read-only identity summary data root: reads the shopper profile, provides it plus a sign-out action to descendants, and self-gates (renders nothing in the anonymous state). Must be inside SessionRoot. Wrap the parts in an IdentityEditController for the summary/form swap: an IdentitySummaryView holding these parts, an IdentityEditForm holding a FormRoot over ClientProfileFieldset. See identity-summary.md.",
     "docPath": "src/matter/identity-summary/identity-summary.md"
   },
   "IdentitySummarySelectedSummary": {
@@ -4977,6 +5630,91 @@
     "guideline": "Renders the inline sign-out error (role=\"alert\") when the logout mutation returns a user error, else nothing. Must be a descendant of IdentitySummaryRoot.",
     "docPath": "src/matter/identity-summary/identity-summary.md"
   },
+  "InstallmentsSelect": {
+    "name": "InstallmentsSelect",
+    "importPath": "@vtex/faststore/components",
+    "fragment": "\n  fragment InstallmentsSelectData on Query {\n    payment {\n      __typename\n      id\n      installmentOptions {\n        __typename\n        methodId\n        bin\n        installments {\n          __typename\n          count\n          value {\n            amount\n            currencyCode\n          }\n          interestRate\n        }\n      }\n      selectedInstallment {\n        __typename\n        count\n      }\n    }\n  }\n",
+    "fetchStrategy": "reactive",
+    "requiresContext": "payment",
+    "actions": {
+      "payment": [
+        "setInstallments"
+      ]
+    },
+    "docPath": "src/matter/installments/installments.md",
+    "editor": {
+      "label": "Installments Select",
+      "category": "commerce"
+    },
+    "schema": {
+      "installmentTemplate": {
+        "type": "string",
+        "default": "{count}x of {value}",
+        "label": "Installment template"
+      },
+      "interestFreeLabel": {
+        "type": "string",
+        "default": "interest-free",
+        "label": "Interest-free label"
+      },
+      "interestTemplate": {
+        "type": "string",
+        "default": "{rate}% interest",
+        "label": "Interest template"
+      },
+      "label": {
+        "type": "string",
+        "default": "Installments",
+        "label": "Accessible label"
+      },
+      "placeholder": {
+        "type": "string",
+        "default": "Select an installment plan",
+        "label": "Placeholder"
+      }
+    },
+    "guideline": "Collapsed installment picker for checkout: a single closed control (Base UI Select) showing the persisted selection's label, expanding into one option per tier the matched option carries — count, per-installment value, and interest, formatted identically to Installments (the API guarantees a 1x tier is present in every option). Reads the same Query.payment data and dispatches the same $actions.payment.setInstallments as Installments — the two are alternative renderings of one engine, so pick whichever fits the layout: this one for a narrow column, a drawer, or a mobile checkout; Installments when stacked rows fit. Must be inside a PaymentSectionRoot or PaymentSectionController — place it as a sibling of CardEntry and SavedCards, never nested inside either. Renders its own options from real data — no children. The popup is portalled to <body>: the label, trigger, value, icon, and inline error stay reachable from a store's style array, but the option list does not — see installments.md."
+  },
+  "Installments": {
+    "name": "Installments",
+    "importPath": "@vtex/faststore/components",
+    "fragment": "\n  fragment InstallmentsData on Query {\n    payment {\n      __typename\n      id\n      installmentOptions {\n        __typename\n        methodId\n        bin\n        installments {\n          __typename\n          count\n          value {\n            amount\n            currencyCode\n          }\n          interestRate\n        }\n      }\n      selectedInstallment {\n        __typename\n        count\n      }\n    }\n  }\n",
+    "fetchStrategy": "reactive",
+    "requiresContext": "payment",
+    "actions": {
+      "payment": [
+        "setInstallments"
+      ]
+    },
+    "editor": {
+      "label": "Installments",
+      "category": "commerce"
+    },
+    "schema": {
+      "installmentTemplate": {
+        "type": "string",
+        "default": "{count}x of {value}",
+        "label": "Installment template"
+      },
+      "interestFreeLabel": {
+        "type": "string",
+        "default": "interest-free",
+        "label": "Interest-free label"
+      },
+      "interestTemplate": {
+        "type": "string",
+        "default": "{rate}% interest",
+        "label": "Interest template"
+      },
+      "legend": {
+        "type": "string",
+        "default": "Installments",
+        "label": "Legend"
+      }
+    },
+    "guideline": "Installment selector for checkout: shows count, per-installment value, and interest for the card currently being entered (matched by BIN) or the saved card currently selected (matched by the persisted BIN, falling back to method), rendering exactly the tiers the matched option returns (the API guarantees a 1x tier is present in every option, so one is always shown and selectable — see specs/installments.md). Must be inside a PaymentSectionRoot or PaymentSectionController — place it as a sibling of CardEntry and SavedCards, never nested inside either, so one instance serves both entry paths. Picking a row dispatches $actions.payment.setInstallments and the order total updates elsewhere from the normalized cache with no wiring here. Renders its own rows from real data — no children.",
+    "docPath": "src/matter/installments/installments.md"
+  },
   "MyAccountProfileRoot": {
     "name": "MyAccountProfileRoot",
     "importPath": "@vtex/faststore/components",
@@ -5001,10 +5739,12 @@
       },
       "saveFailedMessage": {
         "type": "string",
+        "default": "Unable to save your profile. Please try again.",
         "label": "Save failure message"
       },
       "savedMessage": {
         "type": "string",
+        "default": "Your profile has been saved.",
         "label": "Save success message"
       }
     },
@@ -5247,94 +5987,374 @@
     "guideline": "Draft-bound, optional gender field over a store-configurable set of options (the options prop). Free-string storage — no server-side enum. A Clear button erases a selected value back to empty, since the Select itself offers no such option. Must be a descendant of MyAccountProfileRoot.",
     "docPath": "src/matter/my-account-profile/my-account-profile.md"
   },
-  "PricingRoot": {
-    "name": "PricingRoot",
+  "OrderPlacedPaymentSummary": {
+    "name": "OrderPlacedPaymentSummary",
     "importPath": "@vtex/faststore/components",
-    "fragment": "\n  fragment PricingData on Query {\n    productBySlug(slug: $slug) {\n      __typename\n      id\n      variants(first: 1) {\n        edges {\n          node {\n            sellers {\n              isDefault\n              offer {\n                price { amount currencyCode }\n                listPrice { amount currencyCode }\n                spotPrice { amount currencyCode }\n                installmentPlans {\n                  paymentMethod\n                  paymentType\n                  installments {\n                    count\n                    value { amount currencyCode }\n                    totalAmount { amount currencyCode }\n                    interestRate\n                    interestFree\n                  }\n                }\n                discountHighlights\n                promotions {\n                  name\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n",
-    "fetchStrategy": "lazy",
-    "skeleton": "PricingSkeleton",
+    "fragment": "\n  fragment OrderPlacedPaymentSummaryData on Query {\n    order(orderGroup: $orderGroup) {\n      __typename\n      id\n      network\n      lastFourDigits\n      label\n      installment {\n        count\n        total {\n          amount\n          currencyCode\n        }\n      }\n    }\n  }\n",
+    "fetchStrategy": "reactive",
     "editor": {
-      "label": "Pricing",
+      "label": "Order Placed Payment Summary",
       "category": "commerce"
     },
     "schema": {
-      "selectedVariantId": {
+      "lastFourTemplate": {
         "type": "string",
-        "label": "Selected Variant ID"
+        "default": "•••• {lastFour}",
+        "label": "Last-four template"
+      },
+      "noPaymentRecordLabel": {
+        "type": "string",
+        "default": "Payment method not available",
+        "label": "No payment record label"
+      },
+      "unresolvedOrderLabel": {
+        "type": "string",
+        "default": "Could not load the payment details",
+        "label": "Unresolved order label"
+      },
+      "multiSellerNotice": {
+        "type": "string",
+        "default": "This order was split across {count} sellers; the payment summary does not cover split orders",
+        "label": "Multi-seller notice"
+      },
+      "installmentTemplate": {
+        "type": "string",
+        "default": "{count}x of {total}",
+        "label": "Installment template"
       }
     },
-    "guideline": "Root container for the PDP pricing block; all other Pricing sub-components must be descendants of it. Automatically recomputes the offer when a shopper picks a VariantSelector swatch (it reads the published variant selection); the selectedVariantId prop is an optional pre-selection fallback. Falls back silently to the product-level offer on variant fetch error. See pricing.md.",
-    "docPath": "src/matter/pricing/pricing.md"
+    "guideline": "Read-only recap, on a post-purchase confirmation surface, of the card the shopper paid with — sourced from the settled order (Query.order), never the live order form. Owns its own fragment; requires no ancestor context, so it composes standalone. Renders exactly one of five states, in strict precedence: a role=\"alert\" notice for a split (multi-seller) order — the projection never covers one; nothing while the query is in flight; a role=\"alert\" notice when the order group does not resolve; an informational line when the order resolves with no payment record; or the recap itself (network, plus last four whenever the projection carries one, plus the saved-card label when set, plus an installment line — count and settled total only, never a per-installment amount or interest rate — whenever the settled record reports one). Never compose it in checkout — the order group it reads does not exist until the order is placed, and no component renders a payment recap there. Never renders a full card number or CVV. See order-placed-payment-summary.md.",
+    "docPath": "src/matter/order-placed-payment-summary/order-placed-payment-summary.md"
   },
-  "PricingSellingPrice": {
-    "name": "PricingSellingPrice",
+  "PaymentSectionController": {
+    "name": "PaymentSectionController",
     "importPath": "@vtex/faststore/components",
+    "fragment": "\n  fragment PaymentSectionControllerData on Query {\n    payment {\n      __typename\n      id\n      methods {\n        __typename\n        id\n        name\n        groupName\n        validator {\n          __typename\n          numberMask\n          numberRegex\n          cvvMask\n          cvvRegex\n          cvvRequired\n          expirationRequired\n          holderNameRequired\n          billingAddressRequired\n          documentDisplayable\n          documentRequired\n        }\n      }\n      selectedMethodId\n      selectedAccountId\n      selectedBin\n    }\n    cart {\n      __typename\n      id\n      total {\n        __typename\n        amount\n        currencyCode\n      }\n    }\n  }\n",
+    "fetchStrategy": "reactive",
+    "actions": {
+      "payment": [
+        "setMethod",
+        "sendPayments"
+      ],
+      "analytics": [
+        "track"
+      ]
+    },
+    "providesContext": [
+      "payment",
+      "card-capture"
+    ],
     "editor": {
-      "label": "Selling Price",
+      "label": "Payment Section Controller",
       "category": "commerce"
     },
-    "schema": {},
-    "guideline": "Displays the current selling price; must be a descendant of PricingRoot.",
-    "docPath": "src/matter/pricing/pricing.md"
+    "schema": {
+      "group": {
+        "type": "array",
+        "default": [
+          "creditCardPaymentGroup",
+          "debitCardPaymentGroup"
+        ],
+        "label": "Payment method group"
+      }
+    },
+    "guideline": "State-only controller for a collapsed payment section: wrap a single DialogRoot (centered modal) or DrawerRoot (slide-in) child and it becomes controlled. Renders no markup and bakes no styling — compose the overlay particles (DialogTrigger/DialogPortal/DialogBackdrop/DialogPopup or the Drawer equivalents) directly as page nodes, put a static label (Text) inside the trigger — no component echoes the current choice there, and put PaymentMethodList plus the payment leaves (CardEntry, Installments, SavedCards, PlaceOrder, …) inside the popup. Provides the same 'payment' and 'card-capture' contexts as PaymentSectionRoot, so every leaf composes under either with no change. Unlike the delivery-options controller it does NOT close on a successful selection — picking a method is mid-flow — so close it from a DrawerClose/DialogClose particle or from the leaf that finishes the flow. See payment.md.",
+    "docPath": "src/matter/payment/payment.md"
   },
-  "PricingListPrice": {
-    "name": "PricingListPrice",
+  "PaymentMethodBadges": {
+    "name": "PaymentMethodBadges",
     "importPath": "@vtex/faststore/components",
+    "requiresContext": "payment",
     "editor": {
-      "label": "List Price",
+      "label": "Payment Method Badges",
       "category": "commerce"
     },
-    "schema": {},
-    "guideline": "Displays the original (strikethrough) list price; only renders when a discount exists. Must be a descendant of PricingRoot.",
-    "docPath": "src/matter/pricing/pricing.md"
+    "schema": {
+      "heading": {
+        "type": "string",
+        "label": "Heading"
+      }
+    },
+    "guideline": "A read-only strip of one badge per payment method the store currently accepts, derived from the live order form on every render — never authored, never CMS content — so it updates the moment a method is enabled or disabled in the payment configuration. Place it inside a PaymentSectionRoot or PaymentSectionController, alongside PaymentMethodList and CardEntry; it renders nothing selectable and dispatches no action. Not PaymentMethods, which is the CMS-authored footer strip that cannot reflect the store's live configuration. See payment-method-badges.md.",
+    "docPath": "src/matter/payment/payment-method-badges.md"
   },
-  "PricingSpotPrice": {
-    "name": "PricingSpotPrice",
+  "AcceptedPaymentMethodBadges": {
+    "name": "AcceptedPaymentMethodBadges",
     "importPath": "@vtex/faststore/components",
+    "fragment": "\n  fragment AcceptedPaymentMethodBadgesData on Query {\n    payment {\n      __typename\n      id\n      methods {\n        __typename\n        id\n        name\n      }\n    }\n  }\n",
+    "fetchStrategy": "reactive",
     "editor": {
-      "label": "Spot Price",
+      "label": "Accepted Payment Method Badges",
       "category": "commerce"
     },
-    "schema": {},
-    "guideline": "Displays the best cash/instant-payment price (e.g. Pix); only renders when spotPrice is lower than the selling price. Must be a descendant of PricingRoot.",
-    "docPath": "src/matter/pricing/pricing.md"
+    "schema": {
+      "heading": {
+        "type": "string",
+        "label": "Heading"
+      }
+    },
+    "guideline": "A read-only strip of one badge per payment method the store currently accepts, derived from the live order form on every render — never authored, never CMS content. Owns its own Query.payment fragment — no PaymentSectionRoot or PaymentSectionController ancestor required — so place it on the cart order summary or another checkout-adjacent surface that already has a live cart. Placing it on a page with no cart context (a footer, home, or PDP) still resolves Query.payment on every server render, which mints a fresh upstream order form each time — a real cost in logs and upstream state, not a correctness error. Use PaymentMethodBadges instead for the strip inside a payment section; the two share one render contract and differ only in where their data comes from. Not PaymentMethods, the CMS-authored footer strip that cannot reflect the store's live configuration; not PaymentMethodList, the selectable picker; not CardEntry's own in-field network row. See payment-method-badges.md.",
+    "docPath": "src/matter/payment/payment-method-badges.md"
   },
-  "PricingInstallments": {
-    "name": "PricingInstallments",
+  "PaymentSectionRoot": {
+    "name": "PaymentSectionRoot",
     "importPath": "@vtex/faststore/components",
+    "fragment": "\n  fragment PaymentSectionData on Query {\n    payment {\n      __typename\n      id\n      methods {\n        __typename\n        id\n        name\n        groupName\n        validator {\n          __typename\n          numberMask\n          numberRegex\n          cvvMask\n          cvvRegex\n          cvvRequired\n          expirationRequired\n          holderNameRequired\n          billingAddressRequired\n          documentDisplayable\n          documentRequired\n        }\n      }\n      selectedMethodId\n      selectedAccountId\n      selectedBin\n    }\n    cart {\n      __typename\n      id\n      total {\n        __typename\n        amount\n        currencyCode\n      }\n    }\n  }\n",
+    "fetchStrategy": "reactive",
+    "actions": {
+      "payment": [
+        "setMethod",
+        "sendPayments"
+      ],
+      "analytics": [
+        "track"
+      ]
+    },
+    "providesContext": [
+      "payment",
+      "card-capture"
+    ],
     "editor": {
-      "label": "Installments",
+      "label": "Payment Section",
       "category": "commerce"
     },
-    "schema": {},
-    "guideline": "Shortcut container that exposes the single best installment across all plans; use PricingInstallmentPlans instead when a per-payment-method breakdown is needed. Must be a descendant of PricingRoot.",
-    "docPath": "src/matter/pricing/pricing.md"
+    "schema": {
+      "group": {
+        "type": "array",
+        "default": [
+          "creditCardPaymentGroup",
+          "debitCardPaymentGroup"
+        ],
+        "label": "Payment method group"
+      }
+    },
+    "guideline": "Root of the checkout payment section: reads the payment methods and the current selection from the order form and provides the 'payment' context every payment leaf needs and the 'card-capture' context CardEntry needs, so place CardEntry, CardholderDocument, Installments, SaveCard, BillingAddress, SavedCards, PlaceOrder, and PaymentMethodList as its children — none of them render without a payment root ancestor. Renders one container div and no chrome or copy of its own; headings and layout belong to the composition. Selecting a payment option dispatches $actions.payment.setMethod and every subscriber re-renders from the cache with no refetch — and for a card it is the number the shopper types that decides the network, not an option they pick, so PaymentMethodList shows every in-scope credit and debit method as ONE card option. Which methods exist is always real data — never author them as props; group only scopes the list by the store's payment group(s) — defaults to credit and debit together, accepts one group name or a set of them, and set it to \"\" to show every method, one option each, with no card option. Use PaymentSectionController instead when the section should live in a drawer or modal. See payment.md.",
+    "docPath": "src/matter/payment/payment.md"
   },
-  "PricingInstallmentPlans": {
-    "name": "PricingInstallmentPlans",
+  "PaymentMethodList": {
+    "name": "PaymentMethodList",
     "importPath": "@vtex/faststore/components",
+    "requiresContext": "payment",
     "editor": {
-      "label": "Installment Plans",
+      "label": "Payment Method List",
       "category": "commerce"
     },
-    "schema": {},
-    "guideline": "Renders one row per payment method; use PricingInstallments instead when only the single best plan is needed. Must be a descendant of PricingRoot.",
-    "docPath": "src/matter/pricing/pricing.md"
+    "schema": {
+      "legend": {
+        "type": "string",
+        "default": "Payment method",
+        "label": "Legend"
+      },
+      "cardLabel": {
+        "type": "string",
+        "default": "Pay with Credit / Debit Card",
+        "label": "Card option label"
+      }
+    },
+    "guideline": "The payment-method picker: a radio group of the payment options the order form offers, plus the inline selection error (role=\"alert\"). Every in-scope credit and debit method is ONE option — the network comes from the card number the shopper types, never from a row they pick — and any other in-scope method (e.g. Pix) keeps a row of its own; set group to \"\" on the root to switch that off and get one row per method. Selecting an option dispatches the method selection. Selecting a non-card option hides the card form, and the card option brings it back. Place it inside a PaymentSectionRoot, or inside the DialogPopup/DrawerPopup of a PaymentSectionController. It renders its own options from real data, so it takes no children and no method props; author the card option's wording with cardLabel. Keep it composed: it is the only element that surfaces a rejected selection, and the only control that can recover a selection this section does not serve — omit it and a shopper whose persisted method sits outside group has no reachable way back. Must be inside a payment root.",
+    "docPath": "src/matter/payment/payment.md"
   },
-  "PricingInstallmentPlan": {
-    "name": "PricingInstallmentPlan",
+  "PlaceOrder": {
+    "name": "PlaceOrder",
     "importPath": "@vtex/faststore/components",
+    "fragment": "\n  fragment PlaceOrderData on Query {\n    payment {\n      __typename\n      id\n      selectedMethodId\n      selectedInstallment {\n        __typename\n        count\n        value {\n          amount\n          currencyCode\n        }\n        interestRate\n      }\n      methods {\n        __typename\n        id\n        groupName\n      }\n    }\n  }\n",
+    "fetchStrategy": "reactive",
+    "actions": {
+      "payment": [
+        "startTransaction",
+        "gatewayCallback"
+      ],
+      "analytics": [
+        "track"
+      ]
+    },
+    "requiresContext": "payment",
     "editor": {
-      "label": "Installment Plan",
+      "label": "Place Order",
       "category": "commerce"
     },
-    "schema": {},
-    "guideline": "Renders a single plan row inside PricingInstallmentPlans; nest PricingInstallmentsForPlan inside it to list every installment tier instead of just the best one. Must be a descendant of PricingInstallmentPlans.",
-    "docPath": "src/matter/pricing/pricing.md"
-  },
-  "PricingInstallmentsForPlan": {
-    "name": "PricingInstallmentsForPlan",
-    "importPath": "@vtex/faststore/components",
+    "schema": {
+      "label": {
+        "type": "string",
+        "default": "Place order",
+        "label": "Button label"
+      },
+      "placingLabel": {
+        "type": "string",
+        "default": "Placing order...",
+        "label": "Button label while placing"
+      },
+      "resumeLabel": {
+        "type": "string",
+        "default": "Complete your order",
+        "label": "Button label while a surviving attempt offers a resume"
+      },
+      "successMessage": {
+        "type": "string",
+        "default": "Order placed successfully.",
+        "label": "Success message"
+      },
+      "missingSubmissionMessage": {
+        "type": "string",
+        "default": "Enter your payment details before placing the order.",
+        "label": "Missing payment submission message"
+      },
+      "missingMethodMessage": {
+        "type": "string",
+        "default": "Choose a payment method before placing the order.",
+        "label": "Missing payment method message"
+      },
+      "invalidTransactionMessage": {
+        "type": "string",
+        "default": "Unable to start the payment. Please try again.",
+        "label": "Invalid transaction message"
+      },
+      "networkErrorMessage": {
+        "type": "string",
+        "default": "Unable to complete the request. Please try again.",
+        "label": "Network error message"
+      },
+      "missingDocumentMessage": {
+        "type": "string",
+        "default": "Enter your document before placing the order.",
+        "label": "Missing document message"
+      },
+      "invalidDocumentMessage": {
+        "type": "string",
+        "default": "Enter a valid document before placing the order.",
+        "label": "Invalid document message"
+      },
+      "unavailableMethodMessage": {
+        "type": "string",
+        "default": "Choose another payment method before placing the order.",
+        "label": "Unavailable payment method message"
+      },
+      "unsavedBillingAddressMessage": {
+        "type": "string",
+        "default": "Save your billing address before placing the order.",
+        "label": "Unsaved billing address message"
+      },
+      "invalidCardDataMessage": {
+        "type": "string",
+        "default": "Enter valid card details before placing the order.",
+        "label": "Invalid card data message"
+      },
+      "invalidSecurityCodeMessage": {
+        "type": "string",
+        "default": "Enter a valid security code before placing the order.",
+        "label": "Invalid security code message"
+      },
+      "gatewayErrorMessage": {
+        "type": "string",
+        "default": "Unable to complete the payment. Please try again.",
+        "label": "Gateway error message"
+      },
+      "inFlightMessage": {
+        "type": "string",
+        "default": "This order is already being placed. Please wait.",
+        "label": "Order already in flight message"
+      },
+      "unconfirmedMessage": {
+        "type": "string",
+        "default": "We could not confirm your order yet. Your payment may still be processing, so please do not pay again.",
+        "label": "Unconfirmed order message"
+      },
+      "successHref": {
+        "type": "string",
+        "label": "Confirmation route template ({orderGroup} token)"
+      }
+    },
+    "guideline": "The place-order CTA: invokes usePlaceOrder's three-call sequence (start transaction, the registered submission's own direct-to-gateway leg, then the gateway callback) and blocks interaction while it runs. Compose it as a sibling — never a child — of every other payment-entry leaf under the same PaymentSectionRoot or PaymentSectionController, so the one CTA serves every entry path. Renders one inline outcome after settling: the first userError's message, or successMessage on a clean settle. This component reaches no payment-sensitive input. Must be inside a payment root. See place-order.md.",
+    "docPath": "src/matter/place-order/place-order.md"
+  },
+  "PricingRoot": {
+    "name": "PricingRoot",
+    "importPath": "@vtex/faststore/components",
+    "fragment": "\n  fragment PricingData on Query {\n    productBySlug(slug: $slug) {\n      __typename\n      id\n      variants(first: 1) {\n        edges {\n          node {\n            sellers {\n              isDefault\n              offer {\n                price { amount currencyCode }\n                listPrice { amount currencyCode }\n                spotPrice { amount currencyCode }\n                installmentPlans {\n                  paymentMethod\n                  paymentType\n                  installments {\n                    count\n                    value { amount currencyCode }\n                    totalAmount { amount currencyCode }\n                    interestRate\n                    interestFree\n                  }\n                }\n                discountHighlights\n                promotions {\n                  name\n                }\n              }\n            }\n          }\n        }\n      }\n    }\n  }\n",
+    "fetchStrategy": "lazy",
+    "skeleton": "PricingSkeleton",
+    "editor": {
+      "label": "Pricing",
+      "category": "commerce"
+    },
+    "schema": {
+      "selectedVariantId": {
+        "type": "string",
+        "label": "Selected Variant ID"
+      }
+    },
+    "guideline": "Root container for the PDP pricing block; all other Pricing sub-components must be descendants of it. Automatically recomputes the offer when a shopper picks a VariantSelector swatch (it reads the published variant selection); the selectedVariantId prop is an optional pre-selection fallback. Falls back silently to the product-level offer on variant fetch error. See pricing.md.",
+    "docPath": "src/matter/pricing/pricing.md"
+  },
+  "PricingSellingPrice": {
+    "name": "PricingSellingPrice",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Selling Price",
+      "category": "commerce"
+    },
+    "schema": {},
+    "guideline": "Displays the current selling price; must be a descendant of PricingRoot.",
+    "docPath": "src/matter/pricing/pricing.md"
+  },
+  "PricingListPrice": {
+    "name": "PricingListPrice",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "List Price",
+      "category": "commerce"
+    },
+    "schema": {},
+    "guideline": "Displays the original (strikethrough) list price; only renders when a discount exists. Must be a descendant of PricingRoot.",
+    "docPath": "src/matter/pricing/pricing.md"
+  },
+  "PricingSpotPrice": {
+    "name": "PricingSpotPrice",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Spot Price",
+      "category": "commerce"
+    },
+    "schema": {},
+    "guideline": "Displays the best cash/instant-payment price (e.g. Pix); only renders when spotPrice is lower than the selling price. Must be a descendant of PricingRoot.",
+    "docPath": "src/matter/pricing/pricing.md"
+  },
+  "PricingInstallments": {
+    "name": "PricingInstallments",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Installments",
+      "category": "commerce"
+    },
+    "schema": {},
+    "guideline": "Shortcut container that exposes the single best installment across all plans; use PricingInstallmentPlans instead when a per-payment-method breakdown is needed. Must be a descendant of PricingRoot.",
+    "docPath": "src/matter/pricing/pricing.md"
+  },
+  "PricingInstallmentPlans": {
+    "name": "PricingInstallmentPlans",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Installment Plans",
+      "category": "commerce"
+    },
+    "schema": {},
+    "guideline": "Renders one row per payment method; use PricingInstallments instead when only the single best plan is needed. Must be a descendant of PricingRoot.",
+    "docPath": "src/matter/pricing/pricing.md"
+  },
+  "PricingInstallmentPlan": {
+    "name": "PricingInstallmentPlan",
+    "importPath": "@vtex/faststore/components",
+    "editor": {
+      "label": "Installment Plan",
+      "category": "commerce"
+    },
+    "schema": {},
+    "guideline": "Renders a single plan row inside PricingInstallmentPlans; nest PricingInstallmentsForPlan inside it to list every installment tier instead of just the best one. Must be a descendant of PricingInstallmentPlans.",
+    "docPath": "src/matter/pricing/pricing.md"
+  },
+  "PricingInstallmentsForPlan": {
+    "name": "PricingInstallmentsForPlan",
+    "importPath": "@vtex/faststore/components",
     "editor": {
       "label": "Installments For Plan",
       "category": "commerce"
@@ -5863,7 +6883,7 @@
   "ProductShelfRoot": {
     "name": "ProductShelfRoot",
     "importPath": "@vtex/faststore/components",
-    "fragment": "\n  fragment ProductShelfData on Query {\n    products(first: 12, orderBy: { field: RELEVANCE, direction: DESC }) {\n      edges {\n        node {\n          id\n          title\n          slug\n          images(first: 1) {\n            edges {\n              node {\n                url\n                altText\n              }\n            }\n          }\n          variants(first: 1) {\n            edges {\n              node {\n                availableForSale\n                quantityAvailable\n                price {\n                  amount\n                  currencyCode\n                }\n                compareAtPrice {\n                  amount\n                  currencyCode\n                }\n                sellers {\n                  isDefault\n                  offer {\n                    price {\n                      amount\n                      currencyCode\n                    }\n                    listPrice {\n                      amount\n                      currencyCode\n                    }\n                    spotPrice {\n                      amount\n                      currencyCode\n                    }\n                    tax {\n                      amount\n                      currencyCode\n                    }\n                    taxPercentage\n                    availableQuantity\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n      totalCount\n    }\n  }\n",
+    "fragment": "\n  fragment ProductShelfData on Query {\n    products(first: 12, orderBy: { field: RELEVANCE, direction: DESC }) {\n      edges {\n        node {\n          id\n          title\n          slug\n          routeSlug\n          images(first: 1) {\n            edges {\n              node {\n                url\n                altText\n              }\n            }\n          }\n          variants(first: 1) {\n            edges {\n              node {\n                availableForSale\n                quantityAvailable\n                price {\n                  amount\n                  currencyCode\n                }\n                compareAtPrice {\n                  amount\n                  currencyCode\n                }\n                sellers {\n                  isDefault\n                  offer {\n                    price {\n                      amount\n                      currencyCode\n                    }\n                    listPrice {\n                      amount\n                      currencyCode\n                    }\n                    spotPrice {\n                      amount\n                      currencyCode\n                    }\n                    tax {\n                      amount\n                      currencyCode\n                    }\n                    taxPercentage\n                    availableQuantity\n                  }\n                }\n              }\n            }\n          }\n        }\n      }\n      totalCount\n    }\n  }\n",
     "fetchStrategy": "lazy",
     "skeleton": "ProductShelfSkeleton",
     "editor": {
@@ -6138,6 +7158,117 @@
     "guideline": "The \"I don't know my postal code\" escape hatch, pointing at a postal-code lookup service. Renders nothing until a destination is set, so a store without a lookup service composes it and simply gets no link rather than a dead one. Its text comes from authored content or its children. Must be inside a RegionModalController dialog.",
     "docPath": "src/matter/region/region.md"
   },
+  "SaveCard": {
+    "name": "SaveCard",
+    "importPath": "@vtex/faststore/components",
+    "fragment": "\n  fragment SaveCardData on Query {\n    clientPreferences {\n      __typename\n      id\n      savePersonalData\n    }\n  }\n",
+    "fetchStrategy": "reactive",
+    "requiresContext": [
+      "payment",
+      "session"
+    ],
+    "actions": {
+      "payment": [
+        "saveCard"
+      ]
+    },
+    "editor": {
+      "label": "Save Card",
+      "category": "commerce"
+    },
+    "schema": {
+      "label": {
+        "type": "string",
+        "default": "Save this card for next time",
+        "label": "Toggle label"
+      },
+      "nicknameLabel": {
+        "type": "string",
+        "default": "Card nickname",
+        "label": "Nickname field label"
+      },
+      "nicknamePlaceholder": {
+        "type": "string",
+        "label": "Nickname field placeholder"
+      },
+      "consentNoticeLabel": {
+        "type": "string",
+        "default": "Checking this also lets us store your personal data for future purchases.",
+        "label": "Consent notice label"
+      },
+      "disabled": {
+        "type": "boolean",
+        "default": false,
+        "label": "Disabled"
+      }
+    },
+    "guideline": "Opt-in save-card control for authenticated shoppers only: off by default; checking it writes the draft save-card flag/label AND grants the broader save-personal-data consent ($actions.payment.saveCard(true)); unchecking clears only the draft flag and never revokes that consent (see save-card-control.md Decision 1). The nickname field appears only while checked. Must be inside both a PaymentSectionRoot/PaymentSectionController (T5) and a SessionRoot — self-gates to null while the session is loading or the shopper is not logged in. Renders no card data; the flag and label are folded into the card object by CardEntry/SavedCards at submit time.",
+    "docPath": "src/matter/save-card/save-card.md"
+  },
+  "SavedCards": {
+    "name": "SavedCards",
+    "importPath": "@vtex/faststore/components",
+    "fragment": "\n  fragment SavedCardsListData on Query {\n    payment {\n      __typename\n      id\n      savedCards {\n        __typename\n        id\n        accountId\n        methodId\n        bin\n      }\n    }\n  }\n",
+    "fetchStrategy": "reactive",
+    "requiresContext": "payment",
+    "providesContext": "saved-card",
+    "editor": {
+      "label": "Saved Cards",
+      "category": "commerce"
+    },
+    "schema": {
+      "legend": {
+        "type": "string",
+        "default": "Saved cards",
+        "label": "Legend"
+      }
+    },
+    "guideline": "Radio list of the shopper's saved cards (network, last four, label); expired cards render present but disabled, never selectable. Place a SavedCardOption inside as the per-card template, itself wrapping a SavedCardCvvField so the shopper can complete payment with a stored card — omitting the CVV field means a shopper can select a card but never pay with it. Picking a row dispatches the payment method selection by methodId and accountId only, never a card number or BIN, plus the inline selection error (role=\"alert\") if the server rejects it. \"Use a new card\" is CardEntry composed as a sibling, not a control inside this list. Renders one container div and no chrome of its own; always carries a loading/empty/ready state hook. Must be inside a PaymentSectionRoot or PaymentSectionController. See saved-cards.md.",
+    "docPath": "src/matter/saved-cards/saved-cards.md"
+  },
+  "SavedCardOption": {
+    "name": "SavedCardOption",
+    "importPath": "@vtex/faststore/components",
+    "fragment": "\n  fragment SavedCardOptionData on Query {\n    payment {\n      savedCards {\n        __typename\n        id\n        accountId\n        methodId\n        network\n        lastFourDigits\n        bin\n        label\n        expired\n        cvvRequired\n      }\n    }\n  }\n",
+    "fetchStrategy": "reactive-list-item",
+    "requiresContext": "saved-card",
+    "providesContext": "saved-card-data",
+    "editor": {
+      "label": "Saved Card Option",
+      "category": "commerce"
+    },
+    "schema": {},
+    "guideline": "One saved card as a radio row: network, masked last four, and its label when set; disabled when expired. Place a SavedCardCvvField inside so the CVV appears once this row is selected. Must be inside SavedCards.",
+    "docPath": "src/matter/saved-cards/saved-cards.md"
+  },
+  "SavedCardCvvField": {
+    "name": "SavedCardCvvField",
+    "importPath": "@vtex/faststore/components",
+    "requiresContext": "saved-card-data",
+    "actions": {
+      "payment": [
+        "sendPayments"
+      ]
+    },
+    "editor": {
+      "label": "Saved Card CVV Field",
+      "category": "commerce"
+    },
+    "schema": {
+      "securityCodeLabel": {
+        "type": "string",
+        "default": "Security code",
+        "label": "Security code label"
+      },
+      "securityCodeDescription": {
+        "type": "string",
+        "default": "The 3-4 digit number on your card",
+        "label": "Security code description"
+      }
+    },
+    "guideline": "The CVV re-entry field for its saved card row; renders nothing until that row is selected and requires a CVV. Registers the direct-to-gateway submission for the saved-card path on selection — the CVV never transits our backend, only the gateway leg's userErrors return. Must be inside SavedCardOption.",
+    "docPath": "src/matter/saved-cards/saved-cards.md"
+  },
   "SessionRoot": {
     "name": "SessionRoot",
     "importPath": "@vtex/faststore/components",
@@ -6174,328 +7305,245 @@
     "guideline": "Declarative gate: renders its children only when the current session state is one of the values in `when` (e.g. {\"when\":[\"identified\",\"loggedIn\"]}), else renders nothing. Use it in page or layout JSON to show or hide an identity subtree by state without writing the gate into a component. Must be inside SessionRoot, which may be hosted by the page or by its layout.",
     "docPath": "src/matter/session/session.md"
   },
-  "ShippingAddressRoot": {
-    "name": "ShippingAddressRoot",
+  "ShippingAddressFieldset": {
+    "name": "ShippingAddressFieldset",
     "importPath": "@vtex/faststore/components",
-    "fragment": "\n  fragment ShippingAddressData on Query {\n    shipping {\n      __typename\n      id\n      address {\n        __typename\n        id\n        recipientName\n        postalCode\n        country\n        street\n        number\n        complement\n        neighborhood\n        city\n        state\n      }\n      savedAddresses {\n        __typename\n        id\n        recipientName\n        postalCode\n        country\n        street\n        number\n        complement\n        neighborhood\n        city\n        state\n      }\n    }\n    clientProfile {\n      __typename\n      firstName\n      lastName\n    }\n  }\n",
+    "fragment": "\n  fragment ShippingAddressFieldsetData on Query {\n    shipping {\n      __typename\n      id\n      address {\n        __typename\n        id\n        recipientName\n        postalCode\n        country\n        street\n        number\n        complement\n        neighborhood\n        city\n        state\n      }\n    }\n    clientProfile {\n      __typename\n      id\n      firstName\n      lastName\n    }\n  }\n",
     "fetchStrategy": "reactive",
-    "providesContext": "shipping-address",
+    "skeleton": "ShippingAddressFieldsetSkeleton",
     "actions": {
       "shipping": [
         "setAddress"
       ]
     },
+    "requiresContext": "form",
+    "providesContext": "shipping-address",
     "editor": {
-      "label": "Shipping Address Root",
-      "category": "content"
+      "label": "Shipping Address Fieldset",
+      "category": "commerce"
     },
     "schema": {
       "defaultCountry": {
         "type": "string",
         "default": "BRA",
         "label": "Default country (ISO-3)"
+      },
+      "skeletonCount": {
+        "type": "number",
+        "default": 9,
+        "label": "Skeleton rows"
+      },
+      "loadingLabel": {
+        "type": "string",
+        "default": "Loading your delivery address",
+        "label": "Loading announcement"
+      },
+      "loadedLabel": {
+        "type": "string",
+        "default": "Your delivery address is ready",
+        "label": "Loaded announcement"
+      },
+      "groupLabel": {
+        "type": "string",
+        "default": "Your delivery address",
+        "label": "Accessible group name"
       }
     },
-    "guideline": "Country-adaptive single-address delivery form; batches all fields and writes once via shipping.setAddress. See shipping-address.md.",
+    "guideline": "Composable delivery-address entity: registers under \"shippingAddress\" with the enclosing FormRoot and dispatches shipping.setAddress only when the shopper changed something. Compose the nine ShippingAddress*Control parts inside it; place FormSubmit/FormEnterSubmit/FormError as siblings of the fieldset, not inside it — this fieldset renders no submit or error part of its own. The Controls mount only once the address has resolved, with skeletonCount placeholder rows in their place until then — set it to the number of Controls composed, or the form jumps by the difference. Style the announcement sr-only. groupLabel names the group as its accessible name; blank emits no aria-label, and a composed FieldsetLegend wins over it. See shipping-address.md.",
     "docPath": "src/matter/shipping-address/shipping-address.md"
   },
   "ShippingAddressRecipientNameControl": {
     "name": "ShippingAddressRecipientNameControl",
     "importPath": "@vtex/faststore/components",
     "requiresContext": "shipping-address",
+    "providesContext": "field",
     "editor": {
       "label": "Recipient Name Control",
       "category": "action"
     },
-    "schema": {},
-    "guideline": "Recipient-name input field; required for submit. Must be a descendant of ShippingAddressRoot.",
+    "schema": {
+      "label": {
+        "type": "string",
+        "label": "Field label"
+      },
+      "placeholder": {
+        "type": "string",
+        "label": "Placeholder"
+      }
+    },
+    "guideline": "Recipient-name input field; required for submit. ",
     "docPath": "src/matter/shipping-address/shipping-address.md"
   },
   "ShippingAddressStreetControl": {
     "name": "ShippingAddressStreetControl",
     "importPath": "@vtex/faststore/components",
     "requiresContext": "shipping-address",
+    "providesContext": "field",
     "editor": {
       "label": "Street Control",
       "category": "action"
     },
-    "schema": {},
-    "guideline": "Street name input field. Must be a descendant of ShippingAddressRoot.",
+    "schema": {
+      "label": {
+        "type": "string",
+        "label": "Field label"
+      },
+      "placeholder": {
+        "type": "string",
+        "label": "Placeholder"
+      }
+    },
+    "guideline": "Street name input field. ",
     "docPath": "src/matter/shipping-address/shipping-address.md"
   },
   "ShippingAddressNumberControl": {
     "name": "ShippingAddressNumberControl",
     "importPath": "@vtex/faststore/components",
     "requiresContext": "shipping-address",
+    "providesContext": "field",
     "editor": {
       "label": "Number Control",
       "category": "action"
     },
-    "schema": {},
-    "guideline": "Street number input field. Must be a descendant of ShippingAddressRoot.",
+    "schema": {
+      "label": {
+        "type": "string",
+        "label": "Field label"
+      },
+      "placeholder": {
+        "type": "string",
+        "label": "Placeholder"
+      }
+    },
+    "guideline": "Street number input field. ",
     "docPath": "src/matter/shipping-address/shipping-address.md"
   },
   "ShippingAddressCityControl": {
     "name": "ShippingAddressCityControl",
     "importPath": "@vtex/faststore/components",
     "requiresContext": "shipping-address",
+    "providesContext": "field",
     "editor": {
       "label": "City Control",
       "category": "action"
     },
-    "schema": {},
-    "guideline": "City name input field. Must be a descendant of ShippingAddressRoot.",
+    "schema": {
+      "label": {
+        "type": "string",
+        "label": "Field label"
+      },
+      "placeholder": {
+        "type": "string",
+        "label": "Placeholder"
+      }
+    },
+    "guideline": "City name input field. ",
     "docPath": "src/matter/shipping-address/shipping-address.md"
   },
   "ShippingAddressStateControl": {
     "name": "ShippingAddressStateControl",
     "importPath": "@vtex/faststore/components",
     "requiresContext": "shipping-address",
+    "providesContext": "field",
     "editor": {
       "label": "State Control",
       "category": "action"
     },
-    "schema": {},
-    "guideline": "State/province input field. Must be a descendant of ShippingAddressRoot.",
-    "docPath": "src/matter/shipping-address/shipping-address.md"
-  },
-  "ShippingAddressPostalCodeControl": {
-    "name": "ShippingAddressPostalCodeControl",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "shipping-address",
-    "editor": {
-      "label": "Postal Code Control",
-      "category": "action"
-    },
-    "schema": {},
-    "guideline": "Postal code input field. Must be a descendant of ShippingAddressRoot.",
-    "docPath": "src/matter/shipping-address/shipping-address.md"
-  },
-  "ShippingAddressComplementControl": {
-    "name": "ShippingAddressComplementControl",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "shipping-address",
-    "editor": {
-      "label": "Complement Control",
-      "category": "action"
-    },
-    "schema": {},
-    "guideline": "Complement (apartment, suite, etc.) input field. Must be a descendant of ShippingAddressRoot.",
-    "docPath": "src/matter/shipping-address/shipping-address.md"
-  },
-  "ShippingAddressNeighborhoodControl": {
-    "name": "ShippingAddressNeighborhoodControl",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "shipping-address",
-    "editor": {
-      "label": "Neighborhood Control",
-      "category": "action"
-    },
-    "schema": {},
-    "guideline": "Neighborhood (bairro) input field; shown only for countries that have this field (BR in v1). Must be a descendant of ShippingAddressRoot.",
-    "docPath": "src/matter/shipping-address/shipping-address.md"
-  },
-  "ShippingAddressCountryControl": {
-    "name": "ShippingAddressCountryControl",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "shipping-address",
-    "editor": {
-      "label": "Country Control",
-      "category": "action"
-    },
     "schema": {
       "label": {
         "type": "string",
-        "default": "país",
         "label": "Field label"
-      }
-    },
-    "guideline": "Country selector; lists only countries with an implemented descriptor. Must be a descendant of ShippingAddressRoot.",
-    "docPath": "src/matter/shipping-address/shipping-address.md"
-  },
-  "ShippingAddressSavedList": {
-    "name": "ShippingAddressSavedList",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "shipping-address",
-    "editor": {
-      "label": "Saved Address List",
-      "category": "commerce"
-    },
-    "schema": {},
-    "guideline": "List of saved addresses for logged-in shoppers; renders only if savedAddresses is non-empty. Must be a descendant of ShippingAddressRoot.",
-    "docPath": "src/matter/shipping-address/shipping-address.md"
-  },
-  "ShippingAddressSavedOption": {
-    "name": "ShippingAddressSavedOption",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "shipping-address",
-    "editor": {
-      "label": "Saved Address Option",
-      "category": "commerce"
-    },
-    "schema": {
-      "id": {
+      },
+      "placeholder": {
         "type": "string",
-        "label": "Saved address ID"
+        "label": "Placeholder"
       }
     },
-    "guideline": "A single saved address option; renders its address via the same AddressSummary particle (through its own AddressSummaryRoot) used by ShippingAddressSelectedSummary, so both share one formatting implementation. Must be a descendant of ShippingAddressSavedList.",
+    "guideline": "State/province input field. ",
     "docPath": "src/matter/shipping-address/shipping-address.md"
   },
-  "ShippingAddressSubmit": {
-    "name": "ShippingAddressSubmit",
+  "ShippingAddressPostalCodeControl": {
+    "name": "ShippingAddressPostalCodeControl",
     "importPath": "@vtex/faststore/components",
     "requiresContext": "shipping-address",
+    "providesContext": "field",
     "editor": {
-      "label": "Shipping Address Submit",
+      "label": "Postal Code Control",
       "category": "action"
     },
     "schema": {
       "label": {
         "type": "string",
-        "default": "salvar endereço",
-        "label": "Button label"
+        "label": "Field label"
       },
-      "pendingLabel": {
+      "placeholder": {
         "type": "string",
-        "default": "salvando...",
-        "label": "Pending label"
+        "label": "Placeholder"
       }
     },
-    "guideline": "Submit button; dispatches the batched address write. Disabled until recipient name is non-blank. Must be a descendant of ShippingAddressRoot.",
-    "docPath": "src/matter/shipping-address/shipping-address.md"
-  },
-  "ShippingAddressError": {
-    "name": "ShippingAddressError",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "shipping-address",
-    "editor": {
-      "label": "Shipping Address Error",
-      "category": "commerce"
-    },
-    "schema": {},
-    "guideline": "Error banner; shows domain validation errors inline or a generic upstream-error state. Must be a descendant of ShippingAddressRoot.",
-    "docPath": "src/matter/shipping-address/shipping-address.md"
-  },
-  "ShippingAddressSavedAddressDrawerController": {
-    "name": "ShippingAddressSavedAddressDrawerController",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "shipping-address",
-    "editor": {
-      "label": "Saved Address Drawer Controller",
-      "category": "action"
-    },
-    "schema": {},
-    "guideline": "Wraps a single DrawerRoot child (the saved-address selection drawer) and makes it controlled by the shipping-address drawer state: open state and blocked-dismissal-while-submitting are handled here, so do not set raw open/onOpenChange on the wrapped DrawerRoot. Compose as the parent of DrawerRoot, with the drawer trigger and popup as DrawerRoot descendants, same pattern as CartOpenOnAdd wrapping the mini-cart DrawerRoot. Must be inside ShippingAddressRoot.",
+    "guideline": "Postal code input field. ",
     "docPath": "src/matter/shipping-address/shipping-address.md"
   },
-  "ShippingAddressSavedAddressSubmit": {
-    "name": "ShippingAddressSavedAddressSubmit",
+  "ShippingAddressComplementControl": {
+    "name": "ShippingAddressComplementControl",
     "importPath": "@vtex/faststore/components",
     "requiresContext": "shipping-address",
+    "providesContext": "field",
     "editor": {
-      "label": "Saved Address Submit",
+      "label": "Complement Control",
       "category": "action"
     },
     "schema": {
       "label": {
         "type": "string",
-        "default": "selecionar",
-        "label": "Button label"
+        "label": "Field label"
       },
-      "pendingLabel": {
+      "placeholder": {
         "type": "string",
-        "default": "selecionando...",
-        "label": "Pending label"
+        "label": "Placeholder"
       }
     },
-    "guideline": "The drawer's \"selecionar\" submit button; independent submitting state from the main form's Submit (Decision 7); no-ops when the selected saved address is already the current one (Decision 8). Must be inside the saved-address drawer's DrawerPopup and inside ShippingAddressRoot.",
+    "guideline": "Complement (apartment, suite, etc.) input field. ",
     "docPath": "src/matter/shipping-address/shipping-address.md"
   },
-  "ShippingAddressSelectedSummary": {
-    "name": "ShippingAddressSelectedSummary",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "shipping-address",
-    "providesContext": "address-summary",
-    "editor": {
-      "label": "Selected Address Summary",
-      "category": "commerce"
-    },
-    "schema": {},
-    "guideline": "Provides the current delivery address to the generic AddressSummary particle via AddressSummaryRoot context, and renders the default AddressSummary when composed with no children. Compose AddressSummaryRecipient / Street / Locality directly to choose the order or drop a line. Self-gates to null when there is no current address yet. Must be a descendant of ShippingAddressRoot.",
-    "docPath": "src/matter/shipping-address/shipping-address.md"
-  },
-  "ShippingAddressEditController": {
-    "name": "ShippingAddressEditController",
+  "ShippingAddressNeighborhoodControl": {
+    "name": "ShippingAddressNeighborhoodControl",
     "importPath": "@vtex/faststore/components",
     "requiresContext": "shipping-address",
-    "providesContext": "shipping-address-section",
+    "providesContext": "field",
     "editor": {
-      "label": "Shipping Address Edit Controller",
-      "category": "commerce"
-    },
-    "schema": {},
-    "guideline": "Owns the view/edit toggle for the delivery address section: defaults to view when a current address exists, edit otherwise; switches back to view automatically whenever setAddress succeeds (main form submit or saved-address drawer submit), without ShippingAddressSubmit/ShippingAddressSavedAddressSubmit needing to know about this mode. Compose a ShippingAddressSummaryView holding SelectedSummary + EditButton and a ShippingAddressEditForm holding the form Controls/Submit/Error. Self-contained: it decides from its own data and the shopper's own presses, so no other section opens it and finishing it opens nothing. Must be inside ShippingAddressRoot.",
-    "docPath": "src/matter/shipping-address/shipping-address.md"
-  },
-  "ShippingAddressSummaryView": {
-    "name": "ShippingAddressSummaryView",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "shipping-address-section",
-    "editor": {
-      "label": "Shipping Address Summary View",
-      "category": "commerce"
-    },
-    "schema": {},
-    "guideline": "Renders its children only while the delivery section shows the saved-address summary, and nothing while it shows the form. Compose SelectedSummary and a ShippingAddressEditButton inside. Takes no props: which state it gates is which component it is. Must be inside a ShippingAddressEditController.",
-    "docPath": "src/matter/shipping-address/shipping-address.md"
-  },
-  "ShippingAddressEditForm": {
-    "name": "ShippingAddressEditForm",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "shipping-address-section",
-    "editor": {
-      "label": "Shipping Address Edit Form",
-      "category": "commerce"
-    },
-    "schema": {},
-    "guideline": "Renders its children only while the delivery section shows the address form, and nothing while it shows the summary. Compose the Controls, Submit and Error parts inside. Must be inside a ShippingAddressEditController.",
-    "docPath": "src/matter/shipping-address/shipping-address.md"
-  },
-  "ShippingAddressEditButton": {
-    "name": "ShippingAddressEditButton",
-    "importPath": "@vtex/faststore/components",
-    "requiresContext": "shipping-address-section",
-    "editor": {
-      "label": "Shipping Address Edit Button",
+      "label": "Neighborhood Control",
       "category": "action"
     },
     "schema": {
       "label": {
         "type": "string",
-        "default": "editar",
-        "label": "Button label"
+        "label": "Field label"
+      },
+      "placeholder": {
+        "type": "string",
+        "label": "Placeholder"
       }
     },
-    "guideline": "CTA that switches the view/edit mode to edit. Typically placed inside a ShippingAddressSummaryView, next to SelectedSummary. Must be inside ShippingAddressEditController.",
+    "guideline": "Neighborhood (bairro) input field; shown only for countries that have this field (BR in v1). ",
     "docPath": "src/matter/shipping-address/shipping-address.md"
   },
-  "ShippingAddressCancelButton": {
-    "name": "ShippingAddressCancelButton",
+  "ShippingAddressCountryControl": {
+    "name": "ShippingAddressCountryControl",
     "importPath": "@vtex/faststore/components",
-    "requiresContext": "shipping-address-section",
+    "requiresContext": "shipping-address",
+    "providesContext": "field",
     "editor": {
-      "label": "Shipping Address Cancel Button",
+      "label": "Country Control",
       "category": "action"
     },
     "schema": {
       "label": {
         "type": "string",
-        "default": "cancelar",
-        "label": "Button label"
+        "label": "Field label"
       }
     },
-    "guideline": "Returns the delivery section to its summary without saving. Place it inside a ShippingAddressEditForm so a shopper who opened the form has a way back that does not depend on a successful write. Must be inside ShippingAddressEditController.",
+    "guideline": "Country selector; lists only countries with an implemented descriptor. Must be a descendant of ShippingAddressFieldset, which provides the shipping-address context this control requires. Recomposable: compose Field.Label, FieldSelect.Root and Field.Error as children, in any order; a childless composition keeps the default label-select-error order.",
     "docPath": "src/matter/shipping-address/shipping-address.md"
   },
   "ShippingSimulatorRoot": {