@vtex/faststore 0.0.8 → 0.0.11

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

@@ -59,8 +59,15 @@ SessionRoot                                (required ancestor; session tri-state
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `skeletonCount` | number | `2` | Placeholder rows drawn while the preferences resolve. Set it to the number of controls composed. |
-| `loadingLabel` | string | `'Loading your preferences'` | Announced politely while the preferences resolve. Blank means no announcement. |
-| `loadedLabel` | string | `'Your preferences are ready'` | Announced politely once the controls mount. Blank means no announcement. |
+
+Content model (`client-preferences-fieldset`), ICU message fields with no package default; an unauthored one renders empty and logs `message.missing`:
+
+| Field | Source (English) | Notes |
+|-------|------------------|-------|
+| `loadingLabel` | `Loading your preferences` | Announced politely while the preferences resolve. |
+| `loadedLabel` | `Your preferences are ready` | Announced politely once the controls mount. |
+| `groupLabel` | `Your preferences` | Accessible name of the `<fieldset>` group; unauthored, no `aria-label` is emitted. |
+| `genericErrorMessage` | `Unable to save your preferences. Please try again.` | Shown by `FormError` for every refusal of the write (`MISSING_CART_CONTEXT`, `CART_NOT_FOUND`, `NO_PREFERENCE_PROVIDED`) and for a network failure; none is one the shopper can fix. A code this fieldset does not know shows it too and logs `message.unknown-code`. |
 
 Declares `requiresContext: ['form', 'session']` (needs both a `FormRoot` and a `SessionRoot` ancestor), `providesContext: 'client-preferences'`, `actions: { identity: ['clientPreferencesUpdate'] }`, and its own fragment on `Query.clientPreferences`. Renders `Fieldset.Root` with `disabled={readOnly}`; carries `-pending` until its entity resolves, and `-readonly` when the session reports `canEditData: false`.
 
@@ -72,9 +79,7 @@ The definition also declares that same component as its `skeleton`, which is the
 
 ### ClientPreferencesNewsletterControl / ClientPreferencesSavePersonalDataControl
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| `label` | string | `'Email me with news and offers'` / `'Save my information for next time'` | |
+Content models `client-preferences-newsletter` / `client-preferences-save-data`, one ICU message field each with no package default: `label` (source `Email me with news and offers` / `Save my information for next time`).
 
 Childless, renders `Field.Root > Field.Label > Field.Checkbox` (with the checkmark icon), the label text following. Composed children replace that default anatomy and still bind to the same field. Defaults to unchecked (opt-in, not opt-out) — a `null` saved value reads as `false`.
 

package/dist/docs/client-preferences.md

@@ -61,8 +61,17 @@ The bound newsletter checkbox (`optinNewsLetter`). Inlines `Field` + `Checkbox`
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `label` | string | — | The text shown beside the checkbox. |
+| `$content` | `ContentValue<typeof NewsletterOptInControlContent>` | — | The inline message for a refused save. |
 | `$actions` | injected | — | Carries `identity.clientPreferencesUpdate` (compiler-injected). |
 
+Content type `newsletter-opt-in-control`, keyed on the refusal's `code`:
+
+| Content field | Codes | Source (en) |
+|---|---|---|
+| genericErrorMessage | `NETWORK_ERROR`, `MISSING_CART_CONTEXT`, `CART_NOT_FOUND`, `NO_PREFERENCE_PROVIDED` | Unable to save your preference. Please try again. |
+
+None of these is something the shopper can fix by toggling again. A code the map does not know (one a newer server added) shows `genericErrorMessage` and logs `message.unknown-code`; a blank field renders an empty error and logs `message.missing`.
+
 **Write:** declares `actions: { identity: ['clientPreferencesUpdate'] }`. The write is pessimistic/async — while in flight the checkbox is disabled and the Control carries `data-fs-newsletter-opt-in-pending`. Server `userErrors` surface inline under this checkbox only.
 
 ### SavePersonalDataOptInControl
@@ -72,9 +81,12 @@ The bound save-personal-data checkbox (`savePersonalData`). Same shape as `Newsl
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `label` | string | — | The text shown beside the checkbox. |
+| `$content` | `ContentValue<typeof SavePersonalDataOptInControlContent>` | — | The inline message for a refused save. |
 | `$actions` | injected | — | Carries `identity.clientPreferencesUpdate` (compiler-injected). |
 
-Both Controls share one internal `OptInControl` implementation; each registered Control only fixes its `fieldKey` and `data-fs-*` attributes.
+Content type `save-personal-data-opt-in-control` has the same `genericErrorMessage` field, for the same codes.
+
+Both Controls share one internal `OptInControl` implementation; each registered Control only fixes its `fieldKey`, its `data-fs-*` attributes and its content type.
 
 ---
 
@@ -83,7 +95,7 @@ Both Controls share one internal `OptInControl` implementation; each registered
 - **Pre-fill:** each checkbox reflects its `clientPreferences` value; a `null` (shopper has not chosen) reads as unchecked.
 - **Toggle → persist:** dispatches `$actions.identity.clientPreferencesUpdate` with **only** the toggled field; the other flag is left untouched.
 - **In flight:** the toggled checkbox is disabled and its Control carries its `*-pending` attribute; the other Control is unaffected (per-field pending).
-- **Server `userErrors`:** surfaced inline under the Control that produced them (per-field error).
+- **Server `userErrors`:** surfaced inline under the Control that produced them (per-field error), worded by that Control's `genericErrorMessage`.
 - **Read-only session:** when `useSession()` reports `canEditData: false` (identified but unauthenticated claimed profile — VTEX refuses the write server-side), both checkboxes render disabled and each Control carries its `*-readonly` attribute (`data-fs-newsletter-opt-in-readonly`, `data-fs-save-personal-data-opt-in-readonly`), mirroring `EmailIdentificationControl`.
 
 ---
@@ -102,11 +114,17 @@ Both Controls share one internal `OptInControl` implementation; each registered
   },
   "newsletter-opt-in": {
     "type": "NewsletterOptInControl",
-    "props": { "label": "Quero receber novidades e ofertas por e-mail" }
+    "props": {
+      "label": "Quero receber novidades e ofertas por e-mail",
+      "genericErrorMessage": "Não foi possível salvar sua preferência. Tente novamente."
+    }
   },
   "save-data-opt-in": {
     "type": "SavePersonalDataOptInControl",
-    "props": { "label": "Salvar minhas informações para a próxima compra" }
+    "props": {
+      "label": "Salvar minhas informações para a próxima compra",
+      "genericErrorMessage": "Não foi possível salvar sua preferência. Tente novamente."
+    }
   }
 }
 ```
@@ -125,7 +143,10 @@ Both Controls share one internal `OptInControl` implementation; each registered
   },
   "newsletter-opt-in": {
     "type": "NewsletterOptInControl",
-    "props": { "label": "Sign me up for the newsletter" }
+    "props": {
+      "label": "Sign me up for the newsletter",
+      "genericErrorMessage": "Unable to save your preference. Please try again."
+    }
   }
 }
 ```
@@ -150,7 +171,7 @@ Both Controls share one internal `OptInControl` implementation; each registered
 | Component | What you style | Plausible classes |
 |---|---|---|
 | `ClientPreferencesRoot` | Stacks the opt-in rows | `flex flex-col gap-[8px]` |
-| `NewsletterOptInControl` / `SavePersonalDataOptInControl` | The checkbox + label row | `flex items-center gap-[8px] text-[14px] text-[#333333]` |
+| `NewsletterOptInControl` / `SavePersonalDataOptInControl` | The checkbox + label row | `flex items-center gap-[8px] text-[14px] text-[var(--color-text)]` |
 
 Styled example:
 
@@ -164,16 +185,18 @@ Styled example:
   "newsletter-opt-in": {
     "type": "NewsletterOptInControl",
     "props": { "label": "Quero receber novidades e ofertas por e-mail" },
-    "style": ["flex", "items-center", "gap-[8px]", "text-[14px]", "text-[#333333]"]
+    "style": ["flex", "items-center", "gap-[8px]", "text-[14px]", "text-[var(--color-text)]"]
   },
   "save-data-opt-in": {
     "type": "SavePersonalDataOptInControl",
     "props": { "label": "Salvar minhas informações para a próxima compra" },
-    "style": ["flex", "items-center", "gap-[8px]", "text-[14px]", "text-[#333333]"]
+    "style": ["flex", "items-center", "gap-[8px]", "text-[14px]", "text-[var(--color-text)]"]
   }
 }
 ```
 
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-text": "#333333"}`. A color used once stays a hex.
+
 ---
 
 ## Related

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

@@ -67,8 +67,15 @@ SessionRoot                              (required ancestor; session tri-state +
 | `country` | `'US' \| 'BR'` | `'US'` | Phone mask/validation country, provided to the phone control via context. |
 | `documentType` | string | — | One of `'CPF'`, `'SSN'`, `'SIN'` or `'RFC'` (upper case). The document control renders only when supported, and the payload carries `document` only for a supported type. |
 | `skeletonCount` | number | `4` | Placeholder rows drawn while the profile resolves. Set it to the number of controls composed. |
-| `loadingLabel` | string | `'Loading your details'` | Announced politely while the profile resolves. Blank means no announcement. |
-| `loadedLabel` | string | `'Your details are ready'` | Announced politely once the controls mount. Blank means no announcement. |
+
+Content model (`client-profile-fieldset`), ICU message fields with no package default; an unauthored one renders empty and logs `message.missing`:
+
+| Field | Source (English) | Notes |
+|-------|------------------|-------|
+| `loadingLabel` | `Loading your details` | Announced politely while the profile resolves. |
+| `loadedLabel` | `Your details are ready` | Announced politely once the controls mount. |
+| `groupLabel` | `Your details` | Accessible name of the `<fieldset>` group; unauthored, no `aria-label` is emitted. |
+| `genericErrorMessage` | `Unable to save your details. Please try again.` | Shown by `FormError` for every refusal of the write (`MISSING_CART_CONTEXT`, `CART_NOT_FOUND`, `NO_PROFILE_FIELD_PROVIDED`) and for a network failure; none is one the shopper can fix. A code this fieldset does not know shows it too and logs `message.unknown-code`. |
 
 Declares `requiresContext: ['form', 'session']` (needs both a `FormRoot` and a `SessionRoot` ancestor), `providesContext: 'client-profile-fieldset'`, `actions: { identity: ['clientProfileUpdate'] }`, and its own fragment on `Query.clientProfile`. Renders `Fieldset.Root` with `disabled={readOnly}`; carries `-pending` until its entity resolves, and `-readonly` when the session reports `canEditData: false`.
 
@@ -82,19 +89,26 @@ The definition also declares that same component as its `skeleton`, which is the
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | `'First name'` / `'Last name'` | |
 | `placeholder` | string | — | |
 
+Content models `client-profile-first-name` / `client-profile-last-name`, one ICU message field each with no package default: `label` (source `First name` / `Last name`).
+
 Childless, renders `Field.Root > Field.Label + Field.Control + Field.Error`. Composed children replace that default anatomy and still bind to the same field.
 
 ### ClientProfileFieldsetPhoneControl
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | `'Phone'` | |
+| `placeholder` | string | — | |
 | `requirement` | `'mandatory' \| 'optional'` | — | Requiredness only — the only source of it for this control, since the fieldset publishes no baseline. Unset raises nothing, so the phone is optional. A field the store does not want is omitted from the page, not switched off by a prop value. |
-| `errorInvalid` | string | `'Invalid phone number'` | |
-| `errorRequired` | string | `'Phone number is required'` | |
+
+Content model (`client-profile-fieldset-phone`), ICU message fields with no package default. The control formats them and hands the strings to `PhoneField`:
+
+| Field | Source (English) |
+|-------|------------------|
+| `label` | `Phone` |
+| `errorInvalid` | `Invalid phone number` |
+| `errorRequired` | `Phone number is required` |
 
 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

package/dist/docs/client-profile.md

@@ -56,13 +56,19 @@ Binds the reusable `PhoneField` particle to the profile. Reads the saved phone f
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | `'Phone'` | Visible field label. |
 | `country` | `'US' \| 'BR'` | `'US'` | Selects the phone mask and validation rule. |
 | `requirement` | `'mandatory' \| 'optional'` | `'mandatory'` | Controls required validation. A field the store does not want is omitted from the page rather than hidden by a prop. |
-| `errorInvalid` | string | `'Invalid phone number'` | Inline error for an invalid format. |
-| `errorRequired` | string | `'Phone number is required'` | Inline error when a mandatory field is empty. |
 | `$actions` | injected | — | Carries `identity.clientProfileUpdate` (compiler-injected). |
 
+Content model (`client-profile-phone-control`), ICU message fields with no package default. The control formats them and hands the strings to `PhoneField`:
+
+| Field | Source (English) | Notes |
+|-------|------------------|-------|
+| `label` | `Phone` | Visible field label. |
+| `errorInvalid` | `Invalid phone number` | Inline error for an invalid format. |
+| `errorRequired` | `Phone number is required` | Inline error when a mandatory field is empty. |
+| `genericErrorMessage` | `Unable to save your details. Please try again.` | Inline error for a refused save: `NETWORK_ERROR`, `MISSING_CART_CONTEXT`, `CART_NOT_FOUND` and `NO_PROFILE_FIELD_PROVIDED`, none of which the shopper can fix by editing the phone. A code it does not know (one a newer server added) shows it too and logs `message.unknown-code`. |
+
 **Write:** declares `actions: { identity: ['clientProfileUpdate'] }`. No write when the value is unchanged, empty-and-mandatory, or client-side invalid.
 
 ---
@@ -80,6 +86,9 @@ Binds the reusable `PhoneField` particle to the profile. Reads the saved phone f
           "type": "ClientProfilePhoneControl",
           "props": {
             "label": "Phone",
+            "errorInvalid": "Invalid phone number",
+            "errorRequired": "Phone number is required",
+            "genericErrorMessage": "Unable to save your details. Please try again.",
             "country": "US",
             "requirement": "mandatory"
           }

package/dist/docs/copy-text.md

@@ -26,18 +26,20 @@ Any screen that needs one action to copy a single string, such as an order numbe
 CopyText
 ```
 
-`CopyText` is one element. The caller passes the visible label or icon as `children`.
+`CopyText` is one element. The caller passes the visible label or icon as `children`. It has no content of its own: the component that owns the copy formats it and passes it as props. The order details header passes its `copyAccessibleName`, `copyCopied`, `copyFailure` and `copyDismiss` message fields.
 
 ## Components
 
 ### CopyText
 
-| Prop | Type | Default | Purpose |
-|---|---|---|---|
-| `accessibleName` | string | `Copy` | Accessible name of the action |
-| `successMessage` | string | `Copied` | Announced after a successful copy |
-| `failureMessage` | string | `Could not copy` | Announced when the clipboard rejects the write |
-| `dismissLabel` | string | `Dismiss` | Accessible name of the dismiss control |
+| Prop | Type | Purpose |
+|---|---|---|
+| `accessibleName` | string | Accessible name of the action |
+| `successMessage` | string | Announced after a successful copy |
+| `failureMessage` | string | Announced when the clipboard rejects the write |
+| `dismissLabel` | string | Accessible name of the dismiss control |
+
+None has a default. An omitted prop renders nothing: there is no fallback copy, so the owner formats and passes every one.
 
 `text` is required and is not a schema prop. The caller supplies the exact string to copy. `children` is the visible label or icon, and it is not a schema prop either.
 

package/dist/docs/document-field.md

@@ -141,7 +141,7 @@ The label is associated with the input and the error is linked via `aria-describ
 - **Blocking input during masking.** The mask is applied progressively and never rejects a keystroke.
 - **Treating an empty value as invalid.** The document is optional — blank is valid.
 - **Wiring GraphQL into this particle.** It is data-agnostic; the host form owns the profile read/write.
-- **Localizing via a message id.** There is no `react-intl`; pass `label` / `placeholder` / `errorMessage` as strings.
+- **Localizing via a message id.** Labels are plain strings; pass `label` / `placeholder` / `errorMessage` directly.
 
 ---
 

package/dist/docs/email-field.md

@@ -55,6 +55,7 @@ EmailField                 (data-fs-email-field + inherited data-fs-field-root)
 | `disabled` | boolean | `false` | Disables the input (e.g. while a write is in flight). |
 | `required` | boolean | `true` | Email is Always Mandatory at the identity step. |
 | `name` | string | `'email'` | Field/input name. |
+| `autoComplete` | string | — | The input's `autocomplete` token. Omitted, the attribute is not rendered. Set `"username"` when the field is the identifier half of a credential pair, so a password manager saves and fills it with its password. |
 
 **Validation:** format is checked on blur/submit only — never per keystroke. A prior format error clears while the shopper edits and is re-evaluated on the next blur.
 
@@ -83,7 +84,7 @@ The label is associated with the input and the error is linked via `aria-describ
 
 - **Validating on every keystroke.** Format validation runs on blur/submit only.
 - **Wiring GraphQL into this particle.** It is data-agnostic; use `EmailIdentificationControl` for the checkout-bound binding.
-- **Localizing via a message id.** There is no `react-intl`; pass `label` / `placeholder` / `errorMessage` as strings.
+- **Localizing via a message id.** Labels are plain strings; pass `label` / `placeholder` / `errorMessage` directly.
 
 ---
 

package/dist/docs/email-identification.md

@@ -46,9 +46,18 @@ SessionRoot                          (provides the session tri-state; required a
 | `label` | string | — | Passed to `EmailField`. |
 | `placeholder` | string | — | Passed to `EmailField`. |
 | `invalidEmailMessage` | string | — | Inline error text for an invalid email format. |
+| `$content` | `ContentValue<typeof EmailIdentificationControlContent>` | — | The inline message for a refused save. |
 | `$data` | `{ email?: string \| null } \| null` | injected | `clientProfile` slice from the reactive runtime. Not authored in schema. |
 | `$actions` | injected | — | Carries `identity.clientProfileUpdate` (compiler-injected). |
 
+Content type `email-identification-control`, keyed on the refusal's `code`:
+
+| Content field | Codes | Source (en) |
+|---|---|---|
+| genericErrorMessage | `NETWORK_ERROR`, `MISSING_CART_CONTEXT`, `CART_NOT_FOUND`, `NO_PROFILE_FIELD_PROVIDED` | Unable to save your details. Please try again. |
+
+None of these is something the shopper can fix by editing the email. A code the map does not know (one a newer server added) shows `genericErrorMessage` and logs `message.unknown-code`; a blank field renders an empty error and logs `message.missing`.
+
 **Data:** declares a colocated `fragment EmailIdentificationData on Query { clientProfile { email } }` with `fetchStrategy: 'reactive'`. The compiler merges it into the page query — no explicit `dataSources` entry needed.
 
 **Write:** declares `actions: { identity: ['clientProfileUpdate'] }`. The write is **pessimistic/async** — it awaits the persisted result. While in flight the field is disabled and the root carries `data-fs-email-identification-pending`, so a `CartCheckoutGuard`-style guard can block the checkout CTA.
@@ -63,7 +72,7 @@ SessionRoot                          (provides the session tri-state; required a
 - **Invalid format:** the field shows its inline error; no write, no step advance.
 - **Cleared field:** blurring an emptied field re-fills the saved email; no write. Clearing must not visually "un-identify" — changing email (= switching user) is a deliberate act done by typing a new one.
 - **`canEditData: false`:** the field renders **disabled** and the root carries `data-fs-email-identification-readonly`. VTEX refuses profile edits for an identified-but-unauthenticated claimed profile, so the control never offers a write that is doomed server-side.
-- **Server `userErrors`:** surfaced inline; the session is left unchanged.
+- **Server `userErrors`:** surfaced inline, worded by `genericErrorMessage`; the session is left unchanged.
 
 ---
 
@@ -78,7 +87,8 @@ SessionRoot                          (provides the session tri-state; required a
       "props": {
         "label": "Email",
         "placeholder": "you@example.com",
-        "invalidEmailMessage": "Enter a valid email address."
+        "invalidEmailMessage": "Enter a valid email address.",
+        "genericErrorMessage": "Unable to save your details. Please try again."
       }
     }
   ]

package/dist/docs/footer-copyright.md

@@ -90,7 +90,7 @@ The element id is the content key, so name it for the section rather than its st
 
 | Component | What you style | Plausible classes |
 |---|---|---|
-| `FooterCopyright` | The legal notice line | `text-[12px] leading-[1.5] text-[#666666] text-center py-[16px]` |
+| `FooterCopyright` | The legal notice line | `text-[12px] leading-[1.5] text-[var(--color-text-muted)] text-center py-[16px]` |
 
 Styled example:
 
@@ -98,11 +98,13 @@ Styled example:
 {
   "footer-copyright": {
     "type": "FooterCopyright",
-    "style": ["text-[12px]", "leading-[1.5]", "text-[#666666]", "text-center", "py-[16px]"]
+    "style": ["text-[12px]", "leading-[1.5]", "text-[var(--color-text-muted)]", "text-center", "py-[16px]"]
   }
 }
 ```
 
+The colors that several elements share are variables of the page or layout `theme`, which declares them: `{"--color-text-muted": "#666666"}`. A color used once stays a hex.
+
 ---
 
 ## Related

package/dist/docs/footer-social.md

@@ -52,7 +52,7 @@ FooterRoot
 
 **A destination the allowlist refuses renders as text.** Every `url` passes through the shared render-time check, which admits `http:`, `https:`, `mailto:`, `tel:`, and site-relative paths. A refused one — a `javascript:` value, a protocol-relative `//host`, or a URL not yet pasted — renders the profile's label as visible text with no link and no glyph, rather than a mark that looks clickable and goes nowhere. The rejection logs once with the entry index and a bounded reason.
 
-**Every predefined name must be registered.** A `platform` resolves to a sprite symbol the store's build has to include; the store's `global.json` writes the names out under `icons.include` — it is JSON, so it cannot import `SOCIAL_PLATFORM_NAMES`, and a test that derives the expected set from the exported constant is what keeps the two in step. A name the store never registered renders an empty `<svg>` — no build error and no runtime error, just a missing mark. `linkedin` and `youtube` need provisioned icon data as well: unlike the other three they have no embedded fallback, so a store that registers them without running `sukima icon-data fetch` fails to build.
+**Every predefined name must be registered.** A `platform` resolves to a sprite symbol the store's build has to include; the store's `foundation.json` writes the names out under `icons.include` — it is JSON, so it cannot import `SOCIAL_PLATFORM_NAMES`, and a test that derives the expected set from the exported constant is what keeps the two in step. A name the store never registered renders an empty `<svg>` — no build error and no runtime error, just a missing mark. `linkedin` and `youtube` need provisioned icon data as well: unlike the other three they have no embedded fallback, so a store that registers them without running `sukima icon-data fetch` fails to build.
 
 ---
 

package/dist/docs/form.md

@@ -124,6 +124,8 @@ cancels it, because the built-in guard's own `preventDefault()` runs after the a
 
 ## Components
 
+Each button part reads its text only from its own `$content`, whose `label` field is an ICU message, unless it has `children`; no part takes a copy prop. A missing message renders an empty button and logs `message.missing`.
+
 ### FormRoot
 
 The only `<form>` in a composition. Renders `noValidate`, wires
@@ -137,49 +139,65 @@ No props beyond the native `<form>` attributes (`onSubmit` is owned internally a
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | — | Rendered when there are no `children`. Falls through to the message catalog (`fs/form.submit`) when unset. |
-| `children` | ReactNode | — | Wins over `label` when present. |
-
-Text resolves `children ?? label ?? formatMessage({ id: 'fs/form.submit' })` — there is no hard-coded
-English default. An author who wants copy other than the catalog's own must set `label` or `children`
-explicitly.
+| `$content` | `ContentValue<typeof FormSubmitContent>` | — | Its `label` message is the button text when there are no `children`. |
+| `children` | ReactNode | — | Wins over `$content` when present; the message is then not read. |
 
 A `type="submit"` `Button`, disabled while `formState.isSubmitting`. Pressing it validates every
 registered field first; only once every field is valid does it skip untouched fieldsets, dispatch the
 dirty ones in registration order, and collect what failed. Pressing Enter in a text input does *not*
 submit — see *Implicit submission* above and `FormEnterSubmit` below for a form where it does.
 
+Content type `form-submit`:
+
+| Content field | Description |
+|---|---|
+| label | Button text |
+
 ### FormEnterSubmit
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | — | Rendered when there are no `children`. Falls through to the message catalog (`fs/form.submit`) when unset. |
-| `children` | ReactNode | — | Wins over `label` when present. |
+| `$content` | `ContentValue<typeof FormSubmitContent>` | — | Its `label` message is the button text when there are no `children`. |
+| `children` | ReactNode | — | Wins over `$content` when present; the message is then not read. |
 
-Renders the same button as `FormSubmit`, sharing its text resolution (the same `fs/form.submit` id —
-there is no separate id for the Enter variant, since both parts render the same word) and its
+Renders the same button as `FormSubmit`, sharing its content type (`form-submit` — there is no
+separate one for the Enter variant, since both parts render the same word) and its
 `data-fs-form-submit`/`data-fs-form-submit-pending` hooks — there is no separate styling hook for this
 part. While mounted, it additionally allows Enter to
 submit the enclosing `FormRoot` from any of its text-entry inputs (see *Implicit submission* above for
 the form-wide blast radius and the IME carve-out).
 
+Content type `form-submit`, shared with `FormSubmit`.
+
 ### FormError
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `fallbackMessage` | string | `'Something went wrong. Please try again.'` | Shown for a fieldset whose write threw rather than resolving `userErrors`. |
+| `$content` | `ContentValue<typeof FormErrorContent>` | — | Its `fallbackMessage` message is shown for a fieldset whose write threw rather than resolving `userErrors`. |
 
 Renders nothing when the last submit produced no failures. Otherwise, one group per failing fieldset,
 carrying `data-fs-form-error-item={label}` — a styling/selector hook, never rendered as text. The visible
-text inside each group is each failing `userError`'s own `message`, or `fallbackMessage` when the dispatch
-rejected or never settled.
+text inside each group is each failing `userError`'s `message`, or the `fallbackMessage` message when
+the dispatch rejected or never settled. An unauthored `fallbackMessage` renders empty and logs
+`message.missing`.
+
+Those messages are the fieldsets' own copy: a fieldset's `dispatch` maps each refusal's `code` to a message
+field of its own `$content` and resolves `{ code, message }` with the formatted text. `FormError` words
+nothing itself. A fieldset never passes the server's `message` through: for a code it has no message field
+for, one a newer server added, it hands over its generic message and logs `message.unknown-code`.
+
+Content type `form-error`:
+
+| Content field | Description |
+|---|---|
+| fallbackMessage | Shown for a write that failed without `userErrors` |
 
 ### FormClear
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | — | Rendered when there are no `children`. Falls through to the message catalog (`fs/form.clear`) when unset. |
-| `children` | ReactNode | — | Wins over `label` when present. |
+| `$content` | `ContentValue<typeof FormClearContent>` | — | Its `label` message is the button text when there are no `children`. |
+| `children` | ReactNode | — | Wins over `$content` when present; the message is then not read. |
 
 A `type="button"` `Button` that empties every field registered by every fieldset inside the enclosing
 `FormRoot` — not only the fieldset nearest to it in the tree. Each bound part registers how its own
@@ -189,18 +207,30 @@ no bound part currently mounted is left alone. The following submit dispatches a
 fieldset that had something to clear, and nothing for one where clearing was a no-op. There is no prop
 to scope it to one fieldset; place it only where clearing the whole form is the intended action.
 
+Content type `form-clear`:
+
+| Content field | Description |
+|---|---|
+| label | Button text |
+
 ### FormReset
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `label` | string | — | Rendered when there are no `children`. Falls through to the message catalog (`fs/form.reset`) when unset. |
-| `children` | ReactNode | — | Wins over `label` when present. |
+| `$content` | `ContentValue<typeof FormResetContent>` | — | Its `label` message is the button text when there are no `children`. |
+| `children` | ReactNode | — | Wins over `$content` when present; the message is then not read. |
 
 A `type="button"` `Button` that returns every registered field name to react-hook-form's baseline for
 that name, and clears its dirty/touched state. Before a fieldset's first successful write, that
 baseline is whatever the field's own seed resolves to; it becomes "what was last written" only after a
 successful submit.
 
+Content type `form-reset`:
+
+| Content field | Description |
+|---|---|
+| label | Button text |
+
 ---
 
 ## Canonical schema example
@@ -216,11 +246,17 @@ schema can author the form's boundary and its actions around wherever a fieldset
     "style": ["flex", "flex-col", "gap-4"],
     "children": ["shipping-address-fieldset", "step-error", "step-submit"]
   },
-  "step-error": { "type": "FormError" },
+  "step-error": {
+    "type": "FormError",
+    "props": { "fallbackMessage": "We couldn't save your details. Please try again." }
+  },
   "step-submit": { "type": "FormSubmit", "props": { "label": "Save and continue" } }
 }
 ```
 
+`fallbackMessage` on `step-error` and `label` on `step-submit` are messages, not props: a store without `store.cmsStoreId` compiles it into
+the element's `$content`, and a CMS-bound store authors it in the Content Platform instead.
+
 `shipping-address-fieldset` is a matter component (shipped by a later task) that renders its own
 fields and calls `registerFieldset` internally — it is placed in the schema like any other
 component, but nothing about its internals is schema-authorable.

package/dist/docs/free-shipping-progress.md

@@ -1,7 +1,7 @@
 # FreeShippingProgress
 
 **Category:** commerce
-**Purpose:** Reactive progress bar for the cart's nearest free-shipping goal. Reads `cart.freeShippingProgress` and the reactive `cart.total`, then renders one of three states: below-threshold ("faltam {value} para frete grátis" + a partially filled bar), earned ("você ganhou frete grátis!" + a full bar), or absent (renders nothing). Composed at the **top of a cart / mini-cart drawer** to nudge the shopper to add a bit more.
+**Purpose:** Reactive progress bar for the cart's nearest free-shipping goal. Reads `cart.freeShippingProgress` and the cart's `Items` totalizer (the amount the server measures, so shipping and discounts do not count), then renders one of three states: below-threshold (the `label` message, e.g. "faltam {value} para frete grátis", + a partially filled bar), earned (the `qualifiedLabel` message + a full bar), or absent (renders nothing). Composed at the **top of a cart / mini-cart drawer** to nudge the shopper to add a bit more.
 
 ---
 
@@ -18,19 +18,23 @@ Look for a **strip at the top of an open cart or mini-cart** with a horizontal p
 
 | State | Condition | Renders |
 |---|---|---|
-| Below threshold | `qualified === false`, cart total below `threshold` | Below-threshold message + a bar filled to `cartTotal / threshold` |
-| Earned | field `qualified === true`, OR the reactive cart total reaches `threshold` | Earned message + a full bar |
+| Below threshold | `qualified === false`, `Items` amount below `threshold` | Below-threshold message + a bar filled to `items / threshold` |
+| Earned | field `qualified === true`, OR the reactive `Items` amount reaches `threshold` | Earned message + a full bar |
 | Absent (self-hide) | `cart.freeShippingProgress === null` (no destination, no eligible promotion, empty cart, still loading, or degraded) | **Nothing** — no bar, no message, no wrapper |
 
 ## Reactive fill (no extra calls)
 
-`freeShippingProgress` is a lazy field kept out of `CartFragment`, so its cached value (`threshold`, `qualified`) does not refresh on cart mutations. The bar therefore derives the **live** fill and remaining from the reactive `cart.total` — which *is* fresh via cache-write propagation — against the fetched `threshold`:
+`freeShippingProgress` is kept out of `CartFragment`, so only some writes select it: the four line writes (remove, remove several, increase, decrease), the coupon removal and the shipping address update. Each returns the field and the bar takes the server's answer: below the goal it shows the amount still missing, and it comes back to qualified when a later write meets the goal again. The cart's `Items` totalizer is reactive too (the optimistic builders adjust it), so between a write's optimistic prediction and the server's answer the bar derives the **live** fill and remaining from the `Items` amount against the cached `threshold`. The server compares the same `Items` amount, so shipping charges and discounts never move the bar:
 
-- `isQualified = qualified || (threshold != null && cartTotal >= threshold)` — the field flag covers the already-earned case (where `threshold` is `null`); the reactive comparison flips it at the boundary between page loads.
-- `liveRemaining = isQualified ? 0 : max(threshold − cartTotal, 0)`
-- `fill = isQualified ? 1 : clamp(cartTotal / threshold, 0..1)`
+- `isQualified = qualified || (threshold != null && items >= threshold)` — the field flag covers the already-earned case (where `threshold` is `null`); the reactive comparison flips it at the boundary.
+- `liveRemaining = isQualified ? 0 : max(threshold − items, 0)`
+- `fill = isQualified ? 1 : clamp(items / threshold, 0..1)`
 
-The bar updates instantly on every add/remove with **no** refetch of `freeShippingProgress`. `threshold` refreshes only on a full page re-sync. `Money.amount` is a string at runtime and is always `Number()`-coerced before math/formatting.
+When the cart has no usable `Items` amount (no `Items` totalizer, or a blank or non-numeric amount), the bar shows the server's own answer instead: `isQualified = qualified`, `liveRemaining = max(remaining, 0)` from `freeShippingProgress.remaining`, and `fill = (threshold − liveRemaining) / threshold`.
+
+While a line write that lowers the items total of a qualified cart is pending, the bar hides: a qualified value has no threshold, so the client cannot tell whether the drop crosses the goal. It returns with the server's answer, and also when the write fails. An emptied cart renders nothing.
+
+`addItem`, coupon apply, validate, shipping option select, the region postal code and the cart shipping calculator do not select the field, so they do not refresh it: after one of those the bar keeps the value of the last write that returned it (or of the page load) and derives its state from the `Items` amount. A line write costs no extra read, because the server reuses the order form the write returned; a coupon removal costs one order-form read upstream when the cart has items and a postal code; the shipping address update costs none, because the server reuses the order form it just refreshed. There is no client refetch. `Money.amount` is a string at runtime and is always `Number()`-coerced before math/formatting.
 
 ---
 
@@ -58,11 +62,11 @@ FreeShippingProgressRoot        ← reactive provider; self-hides on null/loadin
 
 | Component | Props | Notes |
 |---|---|---|
-| `FreeShippingProgressRoot` | `$data` | Provides `FreeShippingProgressContext`; the copy formats from the active storefront context; renders nothing when the field is `null` |
-| `FreeShippingProgressMessage` | `label?`, `qualifiedLabel?` | `label` is a `{value}`-token template (default `"faltam {value} para frete grátis"`); `qualifiedLabel` default `"você ganhou frete grátis!"`; `children` overrides the text |
-| `FreeShippingProgressBar` | — | Renders a `Meter` bar; `aria-valuetext` mirrors the visible copy |
+| `FreeShippingProgressRoot` | `threshold?`, `remaining?`, `qualified?`, `itemsTotal?`, `$data` | Provides `FreeShippingProgressContext`; the copy formats from the active storefront context; renders nothing when the field is `null` |
+| `FreeShippingProgressMessage` | `$content` | Content type `free-shipping-progress-message`: `label` is an ICU message whose `value` argument is the formatted remaining amount; `qualifiedLabel` is the earned message. Both read only from `$content`: an unauthored message renders empty and logs `message.missing`. `children` replaces the text, and then no message is formatted |
+| `FreeShippingProgressBar` | — | Renders a `Meter` bar; `aria-valuetext` is its `valueText` message (`{value}` = the formatted remaining amount) or, once earned, `qualifiedValueText` (content type `free-shipping-progress-bar`) |
 
-Copy is front-localized and front-formatted from the Root's `locale`/`currency` (default `pt-BR`/`BRL`), not the payload `currencyCode`.
+Copy is front-localized and front-formatted from the active storefront context's `locale`/`currency`, not the payload `currencyCode`. A store without CMS authors the message fields on the element, as below; a CMS-bound store keeps them in content.
 
 ---
 
@@ -79,7 +83,8 @@ Copy is front-localized and front-formatted from the Root's `locale`/`currency`
     "props": { "label": "faltam {value} para frete grátis", "qualifiedLabel": "você ganhou frete grátis!" }
   },
   "free-shipping-progress-bar": {
-    "type": "FreeShippingProgressBar"
+    "type": "FreeShippingProgressBar",
+    "props": { "valueText": "{value} restantes para frete grátis", "qualifiedValueText": "frete grátis conquistado" }
   }
 }
 ```

package/dist/docs/identity-edit.md

@@ -42,10 +42,16 @@ resolution error rather than a silently dead branch that blanks the section.
 
 | Prop | Type | Default | Notes |
 |---|---|---|---|
-| `label` | string | `'editar'` / `'cancelar'` | Text shown when no children are composed. |
-| `children` | ReactNode | — | Custom content, e.g. an `Icon` plus text; falls back to `label`. |
+| `children` | ReactNode | — | Custom content, e.g. an `Icon` plus text; falls back to the `label` message. |
 | `className` | string | — | |
 
+Content models `identity-edit-button` and `identity-edit-cancel-button`, one ICU message field each, with
+no package default:
+
+| Field | Source (English) | Notes |
+|---|---|---|
+| `label` | `Edit` / `Cancel` | Text shown when no children are composed. |
+
 ## Behavior
 
 - Starts on the summary. Unlike the delivery section, nothing about the profile data decides this: the