@vtex/faststore 0.0.3 → 0.0.5

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

@@ -68,7 +68,7 @@ Content model (`account-entry-point`) fields, edited in the CMS:
 
 The placeholder does not know which state is coming, so it renders for the whole wait either way. A control that authors only `signedOutLabel` therefore shows the placeholder to a logged-in shopper and then removes it, reflowing the header once. Author both labels to avoid it — the half-authored control is supported, not recommended.
 
-**The resolving state is announced, not hidden.** The component renders a polite live region that stays mounted through the whole exchange: it is empty on the first pass, receives `loadingLabel` once mounted, and is cleared again when the session resolves. The order matters and is the entire reason the region is not part of the placeholder. Assistive technology reports changes *within* a region already in the tree, so a region that appears with its text already inside says nothing, and one that is removed along with the placeholder can never report that the wait ended. The visible bar beside it is `aria-hidden`, so the wait is spoken once rather than twice. All of this only pays off with a layout-hosted `SessionRoot` — a page-hosted one is seeded server-side without the shopper cookie, never reports loading, and sticks on the signed-out label.
+**The resolving state is announced, not hidden.** The component renders a polite live region that stays mounted through the whole exchange: it is empty on the first pass, receives `loadingLabel` once mounted, and is cleared again when the session resolves. The order matters and is the entire reason the region is not part of the placeholder. Assistive technology reports changes *within* a region already in the tree, so a region that appears with its text already inside says nothing, and one that is removed along with the placeholder can never report that the wait ended. The visible bar beside it is `aria-hidden`, so the wait is spoken once rather than twice. A page-hosted `SessionRoot` is seeded server-side with the shopper cookie, so it resolves on the first paint and may skip the loading state.
 
 ---
 
@@ -100,7 +100,6 @@ Bound to a CMS entry, the element authors no content props at all — the entry
 - **Expecting a default glyph.** The base icon dialect has no account icon, so a store that authors no `icon` gets a label-only link. Author one from the store's own collection.
 - **Letting a merchant pick the icon without declaring it.** An `icon` supplied by a CMS entry renders nothing at all unless the store lists the name in `global.json → icons.include`: the compiler builds each route's sprite from the schemas, and a runtime value never reaches that pass.
 - **Hiding the announced text with `display:none`.** That removes it from the accessibility tree and defeats the announcement; use a clipping technique instead.
-- **Hosting the `SessionRoot` on the page.** The session then resolves server-side without the shopper cookie, and every shopper sees the signed-out label.
 
 ---
 

package/dist/docs/account-menu.md

@@ -0,0 +1,164 @@
+# AccountMenu
+
+**Category:** navigation
+**Purpose:** The account's section list — a navigation landmark listing the sections a merchant configured, with the one the shopper is reading announced.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A column of text links down the left of an account page, beside the section's own content.
+- One entry stands out — heavier weight, a filled row, a rule down one edge — and it is the section the page is showing.
+- On a narrow screen the same entries read as a single horizontal row of pills above the content, scrolling sideways rather than collapsing behind a control.
+- Five entries is the untouched default; a different count or a different order is the merchant's configuration, not a different component.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- For the account's persistent section navigation, composed once in the `my-account` layout.
+
+## When NOT to use
+
+- For a general navigation list with no current-section marking → use [[navigation-link-list]].
+- For the trail down to a deep page → use `BreadcrumbRoot`, which keeps the "current page" claim.
+- For the header's sign-in / account control → use [[account-entry-point]].
+
+---
+
+## Composition
+
+Two parts, and the split is the point. `AccountMenuRoot` is the provider and `AccountMenuList` is the landmark.
+
+```text
+AccountMenuRoot
+├── AccountMenuList
+└── Slot                 ← the section's own page
+```
+
+**The Root wraps the section's content; the landmark does not.** The Root's context has to reach consumers that live inside the slot — the account root's redirect, the sibling breadcrumb — and a context reaches only its descendants. A `<nav>` stretched that far would put every section's content inside a navigation region: a screen reader would announce the page as navigation and "skip to navigation" would skip nothing. So the Root wraps, and the `<nav>` stays around the items alone.
+
+The sidebar still renders visually beside the section. That is the swatches' business, not the tree's.
+
+## Components
+
+### AccountMenuRoot
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `items` | `{ label, href, external? }[]` | the library's five | Authored fallback, used when no CMS entry supplies a list. |
+| `children` | ReactNode | — | The landmark and the section's slot. |
+
+Content model (`account-menu`) fields, edited in the CMS:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `items` | array | no | One entry per section, in the order they should appear |
+| `items[].label` | string | yes | The section's name |
+| `items[].href` | string | yes | Its destination; `http(s)`, `mailto:`, `tel:`, or a site-relative path |
+| `items[].external` | boolean | no | The entry leaves the account; it is never marked current |
+
+**The list comes from three channels, in order: a published entry, the authored `items` prop, then the library's five.** The default is Profile, Orders, Address, Payments, and Security, at `/account/profile` and its siblings — the set the PRD names. Presence decides, not emptiness: a channel supplying an empty list resolves to empty rather than falling through, because a merchant who cleared the list cleared it and the defaults must not override a deliberate publication.
+
+**The current section is derived, never authored.** The component reads the current path and matches each entry's destination on segment boundaries. At most one entry is current: among the matches, the one with the longest destination wins, which makes an exact match beat every ancestor without a second rule. `/account/order` is not a match for `/account/orders` — a prefix that does not land on a segment boundary is not a match at all.
+
+**An exact match announces `aria-current="page"`; an ancestor match announces `aria-current="true"`.** Inside `/account/orders/123`, Orders is the current item of its set but not the current page. That claim belongs to the breadcrumb's deep entry, and two surfaces announcing "current page" for two different things is worse than the menu claiming only its set.
+
+Two kinds of entry are excluded from the match entirely: one marked `external`, and one whose destination is not site-relative. A destination of `/` is excluded from ancestor matching alone — a root destination is an ancestor of every account path, so a merchant listing the storefront's home beside the sections would otherwise see it current on every page. It still matches the path `/` exactly.
+
+**V0 assumes the store's public paths carry no binding prefix.** The generated tree lives under a binding segment and a rewrite carries the unprefixed path inward, so the path the component reads matches the destination the merchant published. A store whose public base path *is* its binding id makes the prefixed URL canonical, and then no entry meets a segment boundary and nothing is current. The shipped `AccountEntryPoint` has the same exposure, so this is pre-existing rather than introduced here.
+
+### AccountMenuList
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `'Account'` | Accessible name of the navigation landmark. |
+
+It takes no children: one `<li>` per resolved section is what it renders. With no sections to render it renders nothing at all, rather than an empty landmark for a screen-reader user to land in.
+
+**The current item is brought into view when the list scrolls.** A horizontally scrolling row can start with the current item outside the viewport — the fifth section of five leaves the shopper opening the page with no idea which one they are in. So on mount and on every route change, a current item in an overflowing list is scrolled into view. It is a no-op when the item is already visible, and it does not run at all when the list fits, since an unconditional scroll would move the page instead.
+
+A refused destination keeps its label and loses its anchor, rendering as text under `data-fs-account-menu-text`. A blank label drops the entry outright: an anchor with no accessible name is a WCAG failure.
+
+### useAccountMenu()
+
+Returns `{ items, current }` — the resolved sections and the current one as `{ index, match }`. It throws outside an `AccountMenuRoot`. This is the contract the account root's redirect and the sibling breadcrumb read, so the two surfaces cannot disagree about which section is current.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "account-menu": {
+    "type": "AccountMenuRoot",
+    "children": ["account-menu-list", "account-slot"],
+    "style": ["$account-menu"]
+  },
+  "account-menu-list": {
+    "type": "AccountMenuList",
+    "props": { "label": "Minha conta" },
+    "style": ["$account-menu-list"]
+  }
+}
+```
+
+Bound to a CMS entry, the Root authors no `items` at all — the entry supplies the whole list.
+
+## Common mistakes
+
+- **Placing the Root beside the slot instead of around it.** The layout's own consumers would be satisfied and the page's would not: a context reaches only descendants. Context-constraint validation reports it as a build error rather than as an empty menu at runtime.
+- **Putting the `<nav>` around the section's content.** That is what the two-part split exists to prevent; do not wrap the slot in `AccountMenuList`.
+- **Leaving `label` unauthored.** The default is `Account`; a store with its own wording should say so, because a landmark's name is how a screen-reader user tells it from every other one.
+- **Styling the current item and nothing else.** The hook exists beside `aria-current`, never instead of it. Removing the programmatic signal leaves position conveyed by appearance alone.
+- **Publishing an empty list and expecting the defaults.** Empty is a configuration, not an absence. The account's root then has no section to open.
+- **Authoring `$content` in the schema.** `$content` is compiler-injected from the page's or layout's content entry; naming it in `props` fails the build.
+- **Expecting the default five to resolve.** Their routes exist only in a store that authored the account's route family; until then the default is correct in the example store alone.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `AccountMenuRoot` | `data-fs-account-menu` is the wrapper holding the sidebar and the section side by side | `flex gap-8 md:flex-row flex-col` |
+| `AccountMenuList` | `data-fs-account-menu-list` is the landmark; size the sidebar here | `w-56 shrink-0` |
+| Items | `data-fs-account-menu-items` is the `<ul>`, and the scroll container at narrow viewports | `flex flex-col gap-1` |
+| Item | `data-fs-account-menu-item` is one row | `list-none` |
+| Current item | `data-fs-account-menu-item-current` marks the current row | `font-semibold` |
+| Link | `data-fs-account-menu-link` is the anchor | `block rounded-md px-3 py-2 text-sm` |
+| Refused text | `data-fs-account-menu-text` replaces the anchor for a refused destination | `block px-3 py-2 text-gray-400` |
+
+The vertical-to-horizontal switch and the scroll affordance are one DOM styled two ways, authored as the `AccountMenu` swatch set in `global.json → styles`:
+
+```json
+{
+  "AccountMenuRoot": {
+    "account-menu": [
+      "flex",
+      "flex-col",
+      "gap-6",
+      "md:flex-row",
+      "md:gap-8",
+      "[&_[data-fs-account-menu-items]]:flex",
+      "[&_[data-fs-account-menu-items]]:gap-2",
+      "[&_[data-fs-account-menu-items]]:overflow-x-auto",
+      "md:[&_[data-fs-account-menu-items]]:flex-col",
+      "md:[&_[data-fs-account-menu-items]]:overflow-visible",
+      "[&_[data-fs-account-menu-item-current]_[data-fs-account-menu-link]]:bg-gray-100",
+      "[&_[data-fs-account-menu-item-current]_[data-fs-account-menu-link]]:font-semibold"
+    ]
+  }
+}
+```
+
+The current-item look reaches the anchor through the row, since the hook is on the `<li>` and the anchor is its child.
+
+---
+
+## Related
+
+- [[account-entry-point]] — the header control that links into the account.
+- [[navigation-link]] — the client-side link each item composes.
+- [[navigation-link-list]] — the general-purpose CMS-driven list this one is patterned on.
+- `BreadcrumbRoot` — the sibling trail that keeps the "current page" claim for the deep page.

package/dist/docs/buy-button.md

@@ -35,7 +35,7 @@ BuyButtonRoot
 └── BuyButtonButton
 ```
 
-`BuyButtonButton` dispatches the cart `addItem` action through the compiler-injected `$actions.cart.addItem` prop. The add-to-cart write is **context-free** — it reads and writes the Apollo cache directly — so `BuyButton` needs **no `CartRoot` ancestor** (specs/actions.md, ADR-0010). Drop it on a PDP, a product card, a shelf, or the header alike.
+`BuyButtonButton` dispatches the cart `addItem` action through the compiler-injected `$actions.cart.addItem` prop. The add-to-cart write is **context-free** — it reads and writes the Apollo cache directly — so `BuyButton` needs **no `CartRoot` ancestor** (docs/storefront-core/reference-free-particle-model.md § Write side — actions, ADR-0010). Drop it on a PDP, a product card, a shelf, or the header alike.
 
 Child order reflects visual order.
 

package/dist/docs/cart.md

@@ -3,7 +3,7 @@
 **Category:** commerce
 **Purpose:** Cart **read** layer for the store. `CartRoot` loads the active cart and exposes it (and the cart query error) to descendants, keeping them in sync as the cart changes. It is **hosted by the layout** (shared shell), wrapping the page slot — so every page, including PDPs, consumes its context without declaring it.
 
-Cart **writes** (add / remove / quantity) no longer flow through `CartRoot`. A component declares the cart methods it needs as an `actions: { cart: [...] }` selector on its definition and dispatches through the compiler-injected `$actions.cart.*` prop — the write-side mirror of `fragment` → `$data`. Cart writes are **context-free**: an add-to-cart button works on a PDP, a product card, a search result, or the header with **no `CartRoot` ancestor** (specs/actions.md, ADR-0010).
+Cart **writes** (add / remove / quantity) no longer flow through `CartRoot`. A component declares the cart methods it needs as an `actions: { cart: [...] }` selector on its definition and dispatches through the compiler-injected `$actions.cart.*` prop — the write-side mirror of `fragment` → `$data`. Cart writes are **context-free**: an add-to-cart button works on a PDP, a product card, a search result, or the header with **no `CartRoot` ancestor** (docs/storefront-core/reference-free-particle-model.md § Write side — actions, ADR-0010).
 
 This doc covers `CartRoot` — hosted in the layout, never emitted in page schemas — plus the **mini-cart footer checkout CTA** ([below](#mini-cart-footer-checkout-cta)), the composition of `CartCheckoutGuard` → (`CartTotal` + `CartGoCheckout`). The remaining cart line-item and summary particles (`CartList`, `CartItem*`, `CartCount`, `CartError`) exist in the catalog and will be documented when the full cart page enters scope.
 

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

@@ -0,0 +1,208 @@
+# MyAccountProfile
+
+**Category:** identity
+**Purpose:** The data root, frame, and field Controls for the My Account > Profile page — the Root owns the shopper's saved profile, the draft over it, the view↔edit toggle, and the single batched Save; the field Controls (name, phone, tax ID, birth date, gender — SFS-3288/3289/3290) register with the Root instead of it enumerating them, so which fields the page shows is a composition decision, in both states, from one act of composing.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A My Account > Profile page showing saved shopper data (name, email, phone, tax ID, birth date, gender) with a single "Edit" action.
+- Pressing Edit swaps the same fields into inputs, with "Save" and "Cancel" replacing "Edit".
+- Email always renders read-only, in both states — never an input.
+- Save success or failure surfaces as a toast (SFS-3366), not an inline line or banner near the fields.
+
+Use `MyAccountProfile` (not a hand-assembled combination of ad-hoc state) whenever the image shows this whole view/edit/save profile block, composing its own field Controls (`FirstNameControl`, `LastNameControl`, `PhoneControl`, `TaxIdControl`, `BirthDateControl`, `GenderControl`) for whichever fields the page shows.
+
+---
+
+## When to use
+
+- The My Account > Profile page's frame: the view↔edit toggle, the batched Save, Cancel, the read-only email, and the Toast-based save feedback.
+
+## When NOT to use
+
+- Rendering an individual profile field's presentation or input directly on the Root — that is each field Control's job. This Root owns no field's formatting or masking; the Controls delegate that to the `Field`, `PhoneField`, `DocumentField`, `Input`, and `Select` particles.
+- The signed-out prompt — compose the existing `SignInForm` alongside a `SessionGuard` in the store topology; this Root renders nothing for that audience.
+- Editing the email — it is the login identifier and is read-only by construction; there is no edit-state rendering for it.
+
+---
+
+## Composition
+
+`MyAccountProfile` is a **compound**: `Root` owns the data + mechanics; the frame parts and every field Control are composed freely (any order, any subset). A field the schema author does not compose is absent from both the view state and the edit state, and cannot reach the write payload — there is no separate flag to keep it out.
+
+```
+ToastProvider                             (required ancestor; SFS-3366 — hosts Save's success/error toasts)
+└── SessionRoot                           (required ancestor; must resolve to loggedIn)
+    └── MyAccountProfile.Root             (data-fs-my-account-profile; own fragment/data root; owns draft + Save)
+        ├── MyAccountProfile.Email        (read-only, both states)
+        ├── MyAccountProfile.FirstNameControl / .LastNameControl   (required; Field particle)
+        ├── MyAccountProfile.PhoneControl (optional; compose up to twice via the `field` prop)
+        ├── MyAccountProfile.TaxIdControl (optional; self-gates on activeDocumentType)
+        ├── MyAccountProfile.BirthDateControl (optional; Field + Input type="date")
+        ├── MyAccountProfile.GenderControl (optional; Select over a configurable options prop)
+        ├── MyAccountProfile.EditButton   (view state only)
+        ├── MyAccountProfile.SaveButton   (edit state only)
+        └── MyAccountProfile.CancelButton (edit state only)
+```
+
+A field Control is absent from the composition means absent from both states and never in the write payload — there is no separate `show*`/`visible` prop anywhere in this compound (compose-or-omit).
+
+`Root` is self-contained: it declares the colocated fragment over `customerProfile` — the identical field set SFS-3286's `customerProfileUpdate` mutation returns — and self-gates on the session's `loggedIn` state. Every frame part and field Control `requiresContext: 'my-account-profile'`, except `MyAccountProfileSkeleton`: it renders directly from the Root, before any Provider exists, so it declares no context requirement (mirrors `ProductShelfSkeleton`). Save calls `useToast()` for its success/error feedback (Decision 10), so `Root` also requires a `ToastProvider` ancestor.
+
+---
+
+## Behavior
+
+- **Field registration, not enumeration**: a Control calls `registerField({ key, validate?, normalize? })` in an effect on mount and unregisters on cleanup. The Root validates, batches, and focuses only over the live registry — it never names a field itself (Decision 1).
+- **Dirty is value comparison, not a touched flag**: `dirty(key) === draft[key] !== savedValues[key]`. Retyping a field back to its saved value makes Save a no-op for it, for free.
+- **Absent and empty are different instructions**: a dirty field cleared to `''` erases upstream; a field the shopper never touched is omitted from the payload entirely.
+- **Save order**: compute dirtiness first → nothing dirty raises the saved toast without dispatching → otherwise validate only the dirty registered fields' current draft values (Decision 9) → any error blocks the dispatch and focuses the first invalid field in rendered DOM order → otherwise normalize dirty values and dispatch one `$actions.identity.customerProfileUpdate` → a `userError` raises an error toast and keeps the edit state with the draft intact → success returns to the view state and raises a success toast (Decision 10). A field the shopper never touched is neither validated nor sent.
+- **Edit always opens from the latest saved values**: pressing Edit re-seeds the draft from `savedValues` before switching modes, so a value the server normalized on a previous save (not this task's concern, but a sibling Control's) is what the shopper sees, not a stale local draft.
+- **Background re-delivery**: when `$data` delivers new values while editing, a field re-seeds only if its draft still equals the previously saved value; a dirty field is never clobbered.
+- **Self-gate**: renders nothing outside `state === 'loggedIn'`, even if the topology's `SessionGuard` is missing. Renders `MyAccountProfileSkeleton` while `$data` is unresolved and the shopper is logged in — never an empty summary.
+- **PII**: no profile value appears in any log line. A write that throws (rather than resolving `userErrors`) logs only the error's name; the message shown to the shopper is the `saveFailedMessage` schema prop.
+
+---
+
+## Props
+
+**`MyAccountProfile.Root`** — `documentType` (string, e.g. `'CPF'`; the store-configured fallback used when the saved `documentType` is not a registered type), `savedMessage` (string, default `'Your profile has been saved.'`; the toast title on a successful Save), `saveFailedMessage` (string, default `'Unable to save your profile. Please try again.'`; the toast title on a failed Save). Declares `actions: { identity: ['customerProfileUpdate'] }`, `requiresContext: 'session'`, `providesContext: 'my-account-profile'`, `fetchStrategy: 'reactive'`.
+
+**`.EditButton` / `.SaveButton` / `.CancelButton`** — `label` (sensible default) or composed `children`.
+
+**`.Email` / `.Skeleton`** — no props beyond `className`.
+
+**`.FirstNameControl` / `.LastNameControl`** — `label` (default `'First name'` / `'Last name'`), `requiredMessage` (shown when Save is blocked on an empty value).
+
+**`.PhoneControl`** — `field` (`'homePhone' | 'mobilePhone'`, default `'mobilePhone'`; compose the Control twice to expose both numbers), `country` (`'US' | 'BR'`, default `'US'`), `label`, `invalidMessage`.
+
+**`.TaxIdControl`** — `label` (default `'National tax ID'`), `invalidMessage`, `lockedReason` (the inline copy shown beside the disabled input when a CPF is already saved).
+
+**`.BirthDateControl`** — `label` (default `'Birth date'`).
+
+**`.GenderControl`** — `label` (default `'Gender'`), `placeholder`, `clearLabel` (default `'Clear'`; the button shown once a draft value is set, since the Select itself offers no way back to empty), `options` (`{ value, label }[]`, defaults to a sensible set: female / male / other / prefer not to say).
+
+---
+
+## Field Controls anatomy (SFS-3288/3289/3290)
+
+Each Control is a thin binding over an existing presentational particle — it adds no validation or formatting logic of its own beyond wiring the particle into the Root's registration contract:
+
+- **Registration**: in a mount effect, a Control calls `registerField({ key, validate?, normalize? })` and returns the unregister function from the effect. `firstName`/`lastName` register a validator that rejects an empty draft value; every other Control either registers a format-only validator (a present value must be well-formed; empty is always valid) or no validator at all.
+- **Rendering**: `mode === 'view'` renders `savedValues[key]` as plain text (empty, never a placeholder, when the key was never saved); `mode === 'edit'` renders the bound particle over `draft[key]`, writing through `setField(key, value)`.
+- **Normalization**: `PhoneControl` registers `normalize = (v) => v ? toE164(v, country) : v`; `BirthDateControl` registers the native `yyyy-mm-dd` ↔ stored-format identity map. Normalization runs once, on Save, only for a field the shopper actually changed.
+- **The locked tax ID**: when a saved CPF exists, `TaxIdControl`'s edit branch renders a **disabled** input carrying the saved (masked) value, a `data-fs-my-account-profile-tax-id-readonly` hook, and `lockedReason` — never plain text, never omitted. It registers no validator in this branch and is never dirty. With no saved document, it renders an editable, optional `DocumentField` instead.
+- **Self-gate**: `TaxIdControl` renders nothing when the Root's `activeDocumentType` is undefined or unsupported (V0 supports CPF only).
+- **One phone Control, two bindings**: `PhoneControl`'s `field` prop selects which draft key an instance binds; composing it twice (once per `field` value) exposes both `homePhone` and `mobilePhone` as independent, independently-erasable fields.
+
+---
+
+## Context contract (`useMyAccountProfile()`)
+
+Every field Control consumes this hook — the seam SFS-3287 designs and SFS-3288/3289/3290 consumes as-is:
+
+| Field | Shape | Notes |
+|---|---|---|
+| `mode` | `'view' \| 'edit'` | A Control renders its own branch off this; there is no `show*` prop anywhere. |
+| `savedValues` / `draft` | `Record<key, string>` | Every editable key is always a string; a `null` upstream value is `''`. |
+| `fieldErrors` | `Partial<Record<key, string>>` | Set on a blocked Save; cleared on the field's own next change or on Cancel. |
+| `email` | `string` | The read-only login identifier. |
+| `activeDocumentType` | `string \| undefined` | The saved `documentType` when registered, else the Root's `documentType` prop. |
+| `pending` | `boolean` | Set while the Save dispatch is in flight; parts self-gate and disable off it. Save success/failure feedback surfaces as a toast (Decision 10), not through context. |
+| `registerField(registration)` | `() => unregister` | Call in an effect; the returned function unregisters on cleanup. |
+| `setField(key, value)` | — | Writes one draft value; clears that field's error. |
+| `edit()` / `cancel()` | — | Mode transitions; `cancel()` restores `draft` from `savedValues`. |
+
+The `data-fs-my-account-profile-field="<key>"` attribute on each Control's own wrapper element is part of this contract — it is the seam `focusFirstInvalid` queries by rendered DOM order on a blocked Save.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "toast-provider": { "type": "ToastProvider", "children": ["session"] },
+  "session": { "type": "SessionRoot", "children": ["profile-guard"] },
+  "profile-guard": {
+    "type": "SessionGuard",
+    "props": { "when": ["loggedIn"] },
+    "children": ["profile-root"]
+  },
+  "profile-root": {
+    "type": "MyAccountProfileRoot",
+    "props": { "documentType": "CPF" },
+    "children": [
+      "profile-email",
+      "profile-first-name",
+      "profile-last-name",
+      "profile-mobile-phone",
+      "profile-tax-id",
+      "profile-edit",
+      "profile-save",
+      "profile-cancel"
+    ]
+  },
+  "profile-email": { "type": "MyAccountProfileEmail", "children": [] },
+  "profile-edit": { "type": "MyAccountProfileEditButton", "children": [] },
+  "profile-save": { "type": "MyAccountProfileSaveButton", "children": [] },
+  "profile-cancel": { "type": "MyAccountProfileCancelButton", "children": [] },
+  "profile-first-name": { "type": "MyAccountProfileFirstNameControl", "children": [] },
+  "profile-last-name": { "type": "MyAccountProfileLastNameControl", "children": [] },
+  "profile-mobile-phone": {
+    "type": "MyAccountProfilePhoneControl",
+    "props": { "field": "mobilePhone", "country": "BR" },
+    "children": []
+  },
+  "profile-tax-id": { "type": "MyAccountProfileTaxIdControl", "children": [] }
+}
+```
+
+Add each field Control id to `profile-root`'s `children` array for the fields the store exposes. A sibling `SignInForm`, gated by a `SessionGuard` with `when: ["anonymous", "identified"]`, composes next to `profile-guard` for the signed-out audience.
+
+---
+
+## Common mistakes
+
+- **Rendering `MyAccountProfile.Root` outside `SessionRoot`.** `useSession()` throws; the page must host a `SessionRoot`.
+- **Rendering `MyAccountProfile.Root` outside a `ToastProvider`.** Save calls `useToast()` (Decision 10); without a `ToastProvider` ancestor that call throws.
+- **Expecting the email to be editable.** It is always read-only; there is no edit-state rendering for it anywhere in this compound.
+- **Composing a field Control without an unmount cleanup on its `registerField` effect.** A Control that never unregisters leaks a stale validator into the registry after it stops rendering — every shipped Control returns the unregister function from its effect; keep that pattern in a custom Control.
+- **Reading `draft` in the view state, or `savedValues` in the edit state.** Each Control must branch on `mode` itself (Decision 2); the Root does not hide this for you.
+- **Rendering a frame part or field Control outside `MyAccountProfileRoot`.** Every part except `Skeleton` `requiresContext: 'my-account-profile'` and throws otherwise.
+- **Giving a required Control's native input a `required` HTML attribute.** Requiredness is expressed only through the registered `validate` function (Decision 2 of SFS-3288/3289/3290); a native `required` attribute makes the browser block the form's `submit` event before the Root's own validation and focus logic ever runs.
+- **Hiding the `TaxIdControl` in the edit state when a CPF is already saved.** It must render a disabled, locked input instead — a field disappearing between view and edit reads as a bug (product-confirmed, 2026-09-03).
+- **Adding a `showPhone`/`visible` boolean prop to a Control.** Presence is composition; a boolean visibility prop contradicts compose-or-omit and is out of scope for every Control in this group.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `MyAccountProfile.Root` | The `data-fs-my-account-profile` root `<form>`; carries `-mode`/`-pending` | `flex flex-col gap-4` |
+| Every field Control's wrapper | `data-fs-my-account-profile-field="<key>"` — the Root's focus seam, on every Control | `flex flex-col gap-1` |
+| `.Email` | `[data-fs-my-account-profile-email]` | `text-sm text-neutral-600` |
+| Save feedback | Styled through the `[[toast]]` compound (`Toast.Root`/`Toast.Title`/`Toast.Description`), not through this Root's own `data-fs-*` hooks. | — |
+| `.EditButton` / `.SaveButton` / `.CancelButton` | `[data-fs-my-account-profile-edit\|save\|cancel]` | `rounded-md bg-blue-600 px-4 py-2 font-semibold text-white` |
+| `.Skeleton` | `[data-fs-my-account-profile-skeleton]`, lines via `[data-fs-my-account-profile-skeleton-line]` | `animate-pulse` |
+| `.FirstNameControl` / `.LastNameControl` | `[data-fs-my-account-profile-first-name]` / `[data-fs-my-account-profile-last-name]` | `flex flex-col gap-1` |
+| `.PhoneControl` | `[data-fs-my-account-profile-phone="<field>"]` | `flex flex-col gap-1` |
+| `.TaxIdControl` | `[data-fs-my-account-profile-tax-id]`; the locked input also carries `[data-fs-my-account-profile-tax-id-readonly]` | `flex flex-col gap-1` / disabled-input treatment |
+| `.BirthDateControl` | `[data-fs-my-account-profile-birth-date]` | `flex flex-col gap-1` |
+| `.GenderControl` | `[data-fs-my-account-profile-gender]`; its clear button carries `[data-fs-my-account-profile-gender-clear]` | `flex flex-col gap-1` |
+
+---
+
+## Known gaps
+
+- **The server's generic "invalid value" error carries no field key.** A blocked save whose failure came back from the schema, rather than from a registered `validate`, renders in the one error region with nothing to highlight and nowhere to move focus. Improving this needs an API-side change, tracked outside this task.
+
+## Related
+
+- [[session]] — provides the identity tri-state and the required `SessionRoot` ancestor.
+- [[client-profile-form]] — the closest precedent for the draft-plus-dirty-plus-batched-save mechanics and the raw-fragment/hand-typed-`$data` pattern this Root follows (Decision 8).
+- [[identity-edit]] — the closest precedent for the mode-lives-in-state, mode-is-which-component toggle model this Root follows (Decision 2); its context is scoped to checkout and is not reused here.
+- [[sign-in-form]] — composed alongside this Root's `SessionGuard` sibling for the signed-out audience; not this task's file.
+- [[toast]] — required `ToastProvider` ancestor; Save's success/error feedback surfaces through it (Decision 10, SFS-3366).

package/dist/docs/session.md

@@ -34,7 +34,7 @@ Exactly one `SessionRoot` per rendered tree. A layout-hosted provider already co
 ## Layout hosting vs. page hosting
 
 Layout and page scope still fetch differently, even though both now see the shopper's cookie
-([`specs/ssr-cookie-forwarding-fetch.md`](../../../../../specs/ssr-cookie-forwarding-fetch.md)):
+([SSR session cookie forwarding](../../../../../docs/storefront-core/reference-ssr-session-cookie-forwarding.md)):
 
 - **Layout scope** emits `LAYOUT_QUERY` inside a client component with no SSR seed — no `serverVariables`, no
   `initialData`. The read happens once in the browser and is reused from cache across client-side navigation.

package/dist/docs/sign-in-redirect.md

@@ -134,4 +134,4 @@ A spinner beside the text is a decoration the component does not render. Draw it
 
 - [[account-entry-point]] — the header control that produces one of this route's inbound URLs, encoding the `returnUrl` this component revalidates. It is what a design showing a "Sign In" control actually calls for.
 - [[navigation-link]] — an ordinary link the shopper chooses to follow, for any destination they read on arrival. This route is passed through, never read.
-- `AccountAccessGate` — the other producer of inbound URLs, redirecting an unauthenticated visitor here. Not in the library yet; until it ships, the header control is this route's only sender.
+- [[account-access-gate]] — the other producer of inbound URLs, redirecting an unauthenticated visitor here with the account page they were trying to reach as the return. Never place this route under it.

package/dist/matter/account-access-gate/account-access-gate.d.ts

@@ -0,0 +1,86 @@
+import { ContentValue } from "../../core/dist/define-content-type.js";
+import { ComponentDefinition } from "../../core/dist/define-component.js";
+import "../../core/dist/index.js";
+import { ComponentPropsWithRef, ReactNode } from "react";
+//#region src/matter/account-access-gate/account-access-gate.d.ts
+export declare const AccountAccessGateContent: {
+  readonly id: "account-access-gate";
+  readonly title: "Account Access Gate";
+  readonly description: "What the shopper is told while the account resolves and when it will not open for them.";
+  readonly schema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+      readonly loadingLabel: {
+        readonly type: "string";
+        readonly minLength: 1;
+        readonly title: "Loading announcement";
+      };
+      readonly expiredMessage: {
+        readonly type: "string";
+        readonly minLength: 1;
+        readonly title: "Session ended message";
+      };
+      readonly signInIncompleteMessage: {
+        readonly type: "string";
+        readonly minLength: 1;
+        readonly title: "Sign-in did not complete message";
+      };
+      readonly signInLabel: {
+        readonly type: "string";
+        readonly minLength: 1;
+        readonly title: "Sign-in link label";
+      };
+    };
+  };
+};
+/** Why the account will not open, as a bounded value: a style target and the choice of message. */
+export type AccountAccessGateNoticeReason = 'expired' | 'sign-in-incomplete';
+/** Props for {@link AccountAccessGate}. It renders a different element per outcome and forwards no
+ *  element props of its own; each rendered part carries its own. */
+export type AccountAccessGateProps = {
+  /** Text announced while the session resolves. */
+  loadingLabel?: string;
+  /** What a shopper whose session ended mid-visit is told. */
+  expiredMessage?: string;
+  /** What a shopper who came back from sign-in still signed out is told. */
+  signInIncompleteMessage?: string;
+  /** Label of the link out of either notice. Without it no link renders — a focusable link a screen
+   *  reader announces as its bare URL is worse than no control at all. */
+  signInLabel?: string;
+  /** Merchant-authored fields, sliced from the layout content entry; win over the props field by field
+   *  when present. Absent in a non-CMS store — the props are the fallback. */
+  $content?: ContentValue<typeof AccountAccessGateContent>;
+  /** The account. Rendered only for a signed-in shopper. */
+  children?: ReactNode;
+};
+/** Props for {@link AccountAccessGateLoading}. Extends native `<output>` attributes. */
+export type AccountAccessGateLoadingProps = ComponentPropsWithRef<'output'>;
+/** Props for {@link AccountAccessGateNotice}. Extends native `<output>` attributes. */
+export type AccountAccessGateNoticeProps = Omit<ComponentPropsWithRef<'output'>, 'children'> & {
+  reason: AccountAccessGateNoticeReason;
+  /** The message for this reason. Nothing renders in its place when unauthored. */
+  message?: string;
+  /** Where the link out leads, built by the gate from the page the shopper is on. */
+  signInHref: string;
+  /** Label of the link out. No label, no link. */
+  signInLabel?: string;
+};
+export declare const AccountAccessGateDefinition: ComponentDefinition<AccountAccessGateProps>;
+export declare function AccountAccessGate({ loadingLabel, expiredMessage, signInIncompleteMessage, signInLabel, $content, children }: Readonly<AccountAccessGateProps>): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * The look of a session that has not answered yet. A real part with its own hook rather than an ad hoc
+ * spinner, so a store can style it and a story can render it.
+ */
+export declare function AccountAccessGateLoading({ className, children, ...props }: AccountAccessGateLoadingProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * What renders in the account's place when it will not open: the message for this reason, and a link
+ * the shopper may take back into sign-in.
+ *
+ * The link is the whole of the escape from a sign-in loop. The gate stops redirecting after one
+ * automatic hop, so the next attempt is a click rather than a bounce — and a shopper who keeps landing
+ * here at least lands on a page that says so.
+ */
+export declare function AccountAccessGateNotice({ reason, message, signInHref, signInLabel, className, ...props }: AccountAccessGateNoticeProps): import("react/jsx-runtime").JSX.Element;
+//#endregion
+//# sourceMappingURL=account-access-gate.d.ts.map