@vtex/faststore 0.0.6 → 0.0.7

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

@@ -60,7 +60,7 @@ Content model (`account-entry-point`) fields, edited in the CMS:
 
 **One element, two links, chosen by the session.** `loggedIn` renders the signed-in link; `anonymous` and `identified` both render the signed-out one, because an identified but unauthenticated shopper cannot reach their account yet. There is no prop that selects between them — the merchant authors one element and the session decides.
 
-**The destinations are not authored.** Sign in goes to `/login`, carrying a `returnUrl` with the current path so the shopper returns where they started; the account link goes to the storefront's own `/account`. Both are fixed constants, so no schema edit and no CMS entry can misroute the auth flow. The sign-in destination comes from the shared `resolveSignInHref` (`utils/safe-href.ts`) rather than from this component, so any other surface that has to send a signed-out shopper to sign in reaches the same place by the same rule. The `returnUrl` value is constrained to a same-origin relative path, which keeps the sign-in route from being turned into an open redirect; a path the narrowing refuses drops the parameter, and so does a router reporting no path, leaving a bare `/login` rather than a broken link. That is the sender's half of the guarantee. Nothing stops a hand-crafted link, so the receiving half — narrowing the parameter through `resolveSiteRelativeHref` on arrival — belongs to the route that will serve `/login`. The signed-out link also opts out of Next.js prefetching: a header control is always in the viewport, and the destination is an auth route rather than a page, so it can set a cookie or redirect and the default would fire that request on every page view.
+**The destinations are not authored.** Sign in goes to `/login`, carrying a `returnUrl` with the current path so the shopper returns where they started; the account link goes to the storefront's own `/pvt/account`. Both are fixed constants, so no schema edit and no CMS entry can misroute the auth flow. The sign-in destination comes from the shared `resolveSignInHref` (`utils/safe-href.ts`) rather than from this component, so any other surface that has to send a signed-out shopper to sign in reaches the same place by the same rule. The `returnUrl` value is constrained to a same-origin relative path, which keeps the sign-in route from being turned into an open redirect; a path the narrowing refuses drops the parameter, and so does a router reporting no path, leaving a bare `/login` rather than a broken link. That is the sender's half of the guarantee. Nothing stops a hand-crafted link, so the receiving half — narrowing the parameter through `resolveSiteRelativeHref` on arrival — belongs to the route that will serve `/login`. The signed-out link also opts out of Next.js prefetching: a header control is always in the viewport, and the destination is an auth route rather than a page, so it can set a cookie or redirect and the default would fire that request on every page view.
 
 **`returnUrl` carries the path only — not the query string, not the hash.** A shopper signing in from `/s?q=tenis` or a filtered listing returns to the bare path. This is a deliberate narrowing rather than a limitation of the router: recovering the query would mean reading it through `useSearchParams()` and wrapping the header in a Suspense boundary, and the hash never leaves the browser at all. Search and filter state is cheap to re-apply and the sign-in round trip is rare, so the entry point keeps the simpler shape. Revisit it if merchants report losing filters across sign-in.
 

package/dist/docs/account-menu-identity.md

@@ -0,0 +1,160 @@
+# AccountMenuIdentity
+
+**Category:** identity
+**Purpose:** The signed-in shopper's name and initials avatar, shown beside the account's section list so they can confirm whose account they are looking at.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A small circle with one or two capital letters (`JD`) next to a person's full name, above or beside a column of account section links.
+- It is shown only where the section list is a vertical column. On a narrow screen, where the same sections read as a horizontal row of pills, it is absent.
+- A name only, never an email address, phone number, or edit control next to it (unless the account has no saved name, when the email stands in for it).
+
+The image is the source of truth for layout.
+
+## When to use
+
+- In the account's shared layout, beside the section list, to show whose account it is.
+
+## When NOT to use
+
+- For a profile form or any editable field → use `MyAccountProfileRoot` and its controls.
+- For a read-only identity card with e-mail, phone, and document → use `IdentitySummaryRoot`.
+- For the header's sign-in or account control → use [[account-entry-point]].
+- For a bare avatar with no account data → use [[avatar]].
+
+---
+
+## Composition
+
+`AccountMenuIdentity` is a leaf that declares its own data read. It needs a `SessionRoot` ancestor and nothing else: it reads nothing from the menu, so it is valid anywhere under a session. In the `my-account` layout it is placed under `AccountAccessGate`, inside `AccountMenuRoot`, beside `AccountMenuList`.
+
+```
+SessionRoot
+└── AccountAccessGate
+    └── AccountMenuRoot
+        ├── AccountMenuIdentity    ← beside the list, never inside it
+        ├── AccountMenuList
+        └── Slot                   ← the section's own page
+```
+
+**Place it in the layout, never on a page.** It is `reactive`: its fragment joins the layout's query, which runs in the browser where the shopper's cookie is, and the profile is fetched once and reused as the shopper moves between sections.
+
+**A missing profile costs only this block.** `customerProfile` is nullable. It answers `null` with no error for an anonymous visitor, and `null` with an error at its own path (`UNAUTHORIZED`, `UPSTREAM_ERROR`) when the read fails. The rest of the layout query, the session included, resolves as usual, so the gate and the menu are unaffected.
+
+**Keep it outside `AccountMenuList`.** The list is the navigation landmark and surrounds its items alone; the identity block is not navigation.
+
+The profile is optional to the menu, so it lives in its own component with its own fragment. A store that does not compose this block does not fetch the profile for the menu.
+
+---
+
+## Components
+
+### AccountMenuIdentity
+
+No props in the schema. It accepts standard `<div>` attributes (`className`, `id`), and takes no children.
+
+The block renders:
+
+| State | What renders |
+|---|---|
+| Session not `loggedIn`, or still loading | Nothing |
+| `loggedIn`, layout query pending | An `aria-hidden` skeleton (`data-fs-account-menu-identity-skeleton`) |
+| `loggedIn`, `customerProfile` is `null` | Nothing |
+| `loggedIn`, profile has neither a name nor an email | Nothing |
+| `loggedIn`, profile resolved | The avatar and the name |
+
+**The name** is the first and last names, each trimmed, joined with a space. With neither, the trimmed email stands in for it. **The avatar** shows initials derived from that same name: the first letters of the first and last words, or one letter for a single word. It shows initials only, because the profile has no photo field.
+
+The avatar is hidden from assistive technology, so the name is announced once, as text.
+
+### AccountMenuIdentitySkeleton
+
+The loading placeholder `AccountMenuIdentity` renders while the profile read is pending. No props. It needs no context.
+
+---
+
+## Canonical schema example
+
+The my-account layout, with the identity block beside the section list:
+
+```json
+{
+  "account-session": { "type": "SessionRoot", "children": ["account-gate"] },
+  "account-gate": { "type": "AccountAccessGate", "children": ["account-menu"] },
+  "account-menu": {
+    "type": "AccountMenuRoot",
+    "children": ["account-sidebar", "account-slot"]
+  },
+  "account-sidebar": {
+    "type": "Container",
+    "children": ["account-identity", "account-menu-list"]
+  },
+  "account-identity": {
+    "type": "AccountMenuIdentity",
+    "style": ["$account-menu-identity"]
+  },
+  "account-menu-list": { "type": "AccountMenuList", "props": { "label": "Account" } },
+  "account-slot": { "type": "Slot" }
+}
+```
+
+## Common mistakes
+
+- **Putting it inside `AccountMenuList`.** The list takes no children; the block sits beside it, outside the landmark.
+- **Composing it on a page instead of the layout.** A page-scoped query runs on the server; the layout's runs in the browser with the shopper's cookie and is reused across sections.
+- **Omitting `SessionRoot`.** The block reads the session and throws without one.
+- **Expecting a photo.** It shows initials only. The profile has no photo field, so there is nothing to pass.
+- **Reaching for `IdentitySummaryRoot`.** That is checkout's order-form identity card and needs a cart. The account sidebar reads the persistent profile.
+- **Hiding it with a component prop.** There is none. Hide it below `md` through the swatch (`max-md:hidden`).
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `AccountMenuIdentity` | `data-fs-account-menu-identity` is the block: lays the avatar beside the name and hides it on narrow screens | `max-md:hidden flex items-center gap-3` |
+| Avatar | `data-fs-avatar`, with `data-fs-account-menu-identity-avatar`, is the circle | `size-10 rounded-full bg-gray-200 text-sm font-medium` |
+| Name | `data-fs-account-menu-identity-name` is the name text | `m-0 truncate font-semibold` |
+| Skeleton | `data-fs-account-menu-identity-skeleton`, with `-avatar` and `-line` parts, holds the block's place | `flex items-center gap-3` |
+
+The avatar is composed inside the block, so it is not a schema element a swatch can name. Its look reaches it through descendant selectors on the block's hooks, as a store's swatch does:
+
+```json
+{
+  "AccountMenuIdentity": {
+    "account-menu-identity": [
+      "max-md:hidden",
+      "flex",
+      "items-center",
+      "gap-3",
+      "[&_[data-fs-avatar]]:inline-flex",
+      "[&_[data-fs-avatar]]:size-10",
+      "[&_[data-fs-avatar]]:shrink-0",
+      "[&_[data-fs-avatar]]:items-center",
+      "[&_[data-fs-avatar]]:justify-center",
+      "[&_[data-fs-avatar]]:overflow-hidden",
+      "[&_[data-fs-avatar]]:rounded-full",
+      "[&_[data-fs-avatar]]:bg-gray-200",
+      "[&_[data-fs-avatar]]:text-sm",
+      "[&_[data-fs-avatar]]:font-medium",
+      "[&_[data-fs-account-menu-identity-name]]:m-0",
+      "[&_[data-fs-account-menu-identity-name]]:truncate",
+      "[&_[data-fs-account-menu-identity-name]]:font-semibold"
+    ]
+  }
+}
+```
+
+`max-md:hidden` is `display: none` below the `md` breakpoint, which removes the block from the layout and from the accessibility tree.
+
+---
+
+## Related
+
+- [[avatar]] — the particle the block composes for its initials circle.
+- [[account-menu]] — the section list the block sits beside.
+- [[account-access-gate]] — the gate the layout places above both.
+- `IdentitySummaryRoot` — checkout's read-only identity card, which reads the order form rather than the persistent profile.

package/dist/docs/account-menu.md

@@ -28,12 +28,14 @@ The image is the source of truth for layout.
 
 ## Composition
 
-Two parts, and the split is the point. `AccountMenuRoot` is the provider and `AccountMenuList` is the landmark.
+Two parts, and the split is the point. `AccountMenuRoot` is the provider and `AccountMenuList` is the landmark. A third, `AccountMenuIndexRedirect`, is the account root's only content and lives inside the slot. A fourth, `AccountMenuSignOut`, is the sidebar's way out and sits beside the list.
 
 ```text
 AccountMenuRoot
 ├── AccountMenuList
+├── AccountMenuSignOut   ← beside the list, outside the landmark
 └── Slot                 ← the section's own page
+    └── AccountMenuIndexRedirect   ← on /pvt/account only
 ```
 
 **The Root wraps the section's content; the landmark does not.** The Root's context has to reach consumers that live inside the slot — the account root's redirect, the sibling breadcrumb — and a context reaches only its descendants. A `<nav>` stretched that far would put every section's content inside a navigation region: a screen reader would announce the page as navigation and "skip to navigation" would skip nothing. So the Root wraps, and the `<nav>` stays around the items alone.
@@ -58,11 +60,11 @@ Content model (`account-menu`) fields, edited in the CMS:
 | `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 list comes from three channels, in order: a published entry, the authored `items` prop, then the library's five.** The default is Profile, Orders, Address, Payments, and Security, at `/pvt/profile` and its siblings — the set the PRD names. Presence decides, not emptiness: a channel supplying an empty list resolves to empty rather than falling through, because a merchant who cleared the list cleared it and the defaults must not override a deliberate publication.
 
-**The 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.
+**The current section is derived, never authored.** The component reads the current path and matches each entry's destination on segment boundaries. At most one entry is current: among the matches, the one with the longest destination wins, which makes an exact match beat every ancestor without a second rule. `/pvt/order` is not a match for `/pvt/orders` — a prefix that does not land on a segment boundary is not a match at all.
 
-**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.
+**An exact match announces `aria-current="page"`; an ancestor match announces `aria-current="true"`.** Inside `/pvt/orders/123`, Orders is the current item of its set but not the current page. That claim belongs to the breadcrumb's deep entry, and two surfaces announcing "current page" for two different things is worse than the menu claiming only its set.
 
 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.
 
@@ -80,6 +82,58 @@ It takes no children: one `<li>` per resolved section is what it renders. With n
 
 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.
 
+### AccountMenuIndexRedirect
+
+Exposed as `AccountMenu.IndexRedirect`. The account's root has no section of its own, and which section is first is the merchant's call, so the root is a page holding this part alone.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `loadingLabel` | string | — | Announced while the first section opens. |
+| `emptyMessage` | string | `'No account section is configured.'` | What the root says when there is no section to open. |
+| `className` | string | — | Applied to whichever element renders. |
+
+Content model (`account-menu-index-redirect`) fields, edited in the CMS, each winning over its prop when published; a blank field falls through:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `loadingLabel` | string | no | The waiting announcement |
+| `emptyMessage` | string | no | The no-section message |
+
+**It replaces the current history entry with the first section that stays in the account.** It reads the Root's resolved list and skips, in order: an entry marked `external`, a destination the allowlist refused, a destination that is not site-relative even though the merchant did not flag it, and the root itself in any spelling that matches it. Replace, never push: back from the section leaves the account instead of bouncing through its root.
+
+**While a destination exists it renders the access gate's loading look**, `AccountAccessGateLoading`, with `data-fs-account-menu-index-redirect` beside the part's own hook. The list itself never loads — the Root resolves it synchronously — so what the look covers is the navigation: the frame before the replace is issued and the time the section takes to land. In the `my-account` layout the gate's own wait for the session comes first, so the shopper sees one look throughout.
+
+**With nothing to open, the root is terminal.** A published empty list, or one holding external entries only, navigates nowhere and renders the message instead, under `data-fs-account-menu-index-redirect-empty`. The shell and the sidebar stay. The library's five defaults do not come back: the Root's presence rule is what keeps a published empty list empty, and this part reads the Root's result rather than choosing a channel of its own.
+
+It inherits the menu's V0 assumption that public paths carry no binding prefix. Where a store's public base path is its binding id, the root's own entry is not recognized as the current page and the replace targets an unprefixed destination.
+
+### AccountMenuSignOut
+
+Exposed as `AccountMenu.SignOut`. A button that ends the session and leaves the account for the home page. It reads nothing from the Root, so it works anywhere under the `my-account` layout's gate; the sidebar is where shoppers look for it.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `'Sign out'` | The button's text. |
+| `errorMessage` | string | `"We couldn't sign you out. Please try again."` | Shown when the sign-out did not happen. |
+| `className` | string | — | Applied to the wrapper. |
+
+Content model (`account-menu-sign-out`) fields, edited in the CMS, each winning over its prop when published; a blank field falls through:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `label` | string | no | The button's text |
+| `errorMessage` | string | no | The failure message |
+
+The component declares `actions: { session: ['logout'] }` and writes only through `$actions.session.logout()`.
+
+**It declares the sign-out intent before it awaits the logout.** The logout's payload flips the session to signed out in place, before any navigation can start. A gate that saw that session with no intent would read it as an expired session and send the shopper to sign in for the account they just left. With the intent declared first, the gate stands down — it renders nothing — from the click until the document is gone. The shopper sees the page empty while the request runs; that is the gate's look, not this part's.
+
+**Success is a document load of `/`.** It uses `location.assign`, not the router, so no client cache keeps the account behind the back control. What the browser's back-forward cache restores is the gate's to revalidate: it withdraws the intent on a restored page and re-reads the session. This part adds no `pageshow` handling of its own.
+
+**Failure keeps the shopper where they are.** When the logout reports any error, rejects, or has no handler to run, the part withdraws the intent, the gate brings the account back, and the message renders under `role="alert"`. A logout that reports an error is a sign-out that did not happen, so the shopper is never sent home still signed in. The failure is held outside the component, because the gate unmounts the part for the length of the attempt and mounts it anew on withdrawal. The next click clears it.
+
+**One activation, one logout.** While an attempt runs, a second click neither declares again nor dispatches a second mutation. The button is also disabled and `aria-busy` while any sign-out intent stands, so a second sign-out control on the page stops too.
+
 ### 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.
@@ -92,26 +146,45 @@ Returns `{ items, current }` — the resolved sections and the current one as `{
 {
   "account-menu": {
     "type": "AccountMenuRoot",
-    "children": ["account-menu-list", "account-slot"],
-    "style": ["$account-menu"]
+    "children": ["account-menu-list", "account-menu-sign-out", "account-slot"]
   },
   "account-menu-list": {
     "type": "AccountMenuList",
-    "props": { "label": "Minha conta" },
-    "style": ["$account-menu-list"]
+    "props": { "label": "Minha conta" }
+  },
+  "account-menu-sign-out": {
+    "type": "AccountMenuSignOut",
+    "props": { "label": "Sair", "errorMessage": "Não conseguimos encerrar sua sessão. Tente novamente." }
   }
 }
 ```
 
 Bound to a CMS entry, the Root authors no `items` at all — the entry supplies the whole list.
 
+No part carries a `style` reference: each takes its type's `base` swatch from `global.json → styles` on its own. Reference a named swatch only when the store defines one, since a `$name` the store does not define expands to nothing, without an error.
+
+The account root's page, whose only content is the redirect:
+
+```json
+{
+  "account-index-redirect": {
+    "type": "AccountMenuIndexRedirect",
+    "props": { "loadingLabel": "Abrindo sua conta…", "emptyMessage": "Nenhuma seção configurada." }
+  }
+}
+```
+
 ## 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.
+- **Publishing an empty list and expecting the defaults.** Empty is a configuration, not an absence. The account's root then has no section to open, and says so.
+- **Placing `AccountMenuIndexRedirect` on a section's page.** It navigates away from whatever page hosts it; it belongs on `/pvt/account` alone.
+- **Putting an external entry first and expecting the root to follow it.** It is skipped, as is an absolute destination left unflagged; the root opens the first section that stays in the account.
+- **Placing `AccountMenuSignOut` outside the gate.** Nothing stands down while the logout runs, so the page shows the signed-out session for the moment before it leaves. Compose it under the `my-account` layout's gate.
+- **Signing out with the router, or adding `pageshow` handling to the control.** The document load is what keeps the account off the back control, and the gate owns the back-forward cache.
 - **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.
 
@@ -128,37 +201,47 @@ Bound to a CMS entry, the Root authors no `items` at all — the entry supplies
 | 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` |
+| `AccountMenuIndexRedirect` | `data-fs-account-menu-index-redirect` is on both of its looks; the wait also carries the gate's `data-fs-account-access-gate-loading` | `text-sm text-gray-600` |
+| No-section message | `data-fs-account-menu-index-redirect-empty` marks the terminal state | `flex-1 p-6` |
+| `AccountMenuSignOut` | `data-fs-account-menu-sign-out` is the wrapper; `data-fs-account-menu-sign-out-pending` is on it while a sign-out runs | `flex flex-col gap-2 px-3` |
+| Sign-out button | `data-fs-account-menu-sign-out-button` is the `<button>`; style `:disabled` for the wait | `text-left text-sm underline` |
+| Sign-out failure | `data-fs-account-menu-sign-out-error` is the alert | `text-sm text-red-600` |
 
-The vertical-to-horizontal switch and the scroll affordance are one DOM styled two ways, authored as the `AccountMenu` swatch set in `global.json → styles`:
+The vertical-to-horizontal switch and the scroll affordance are one DOM styled two ways, in CSS alone. A store authors them as `AccountMenuList.base` in `global.json → styles`, abridged here:
 
 ```json
 {
-  "AccountMenuRoot": {
-    "account-menu": [
-      "flex",
-      "flex-col",
-      "gap-6",
-      "md:flex-row",
-      "md:gap-8",
+  "AccountMenuList": {
+    "base": [
       "[&_[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"
+      "max-md:[&_[data-fs-account-menu-items]]:overflow-x-auto",
+      "max-md:[&_[data-fs-account-menu-items]]:scroll-pe-[32px]",
+      "max-md:[&_[data-fs-account-menu-items]]:mask-[linear-gradient(to_right,#000_calc(100%-32px),transparent)]",
+      "max-md:[&_[data-fs-account-menu-item]:last-child]:pe-[32px]",
+      "[&_[data-fs-account-menu-item]]:shrink-0",
+      "[&_[data-fs-account-menu-link]]:whitespace-nowrap",
+      "[&_[data-fs-account-menu-link]]:border-transparent",
+      "max-md:[&_[data-fs-account-menu-link]]:border-b-2",
+      "md:[&_[data-fs-account-menu-link]]:border-l-2",
+      "[&_[data-fs-account-menu-item-current]_[data-fs-account-menu-link]]:border-gray-900"
     ]
   }
 }
 ```
 
-The current-item look reaches the anchor through the row, since the hook is on the `<li>` and the anchor is its child.
+- **The masked edge needs space as wide as its fade.** Give the last item a trailing padding and the `<ul>` a `scroll-padding-inline-end` equal to the fade width. Without the padding, a row scrolled to its end leaves the last label under the fade. Without the scroll padding, bringing a current last item into view parks it there.
+- **Reserve the current rule on every link in `transparent`.** Becoming current then changes a color, never a width, so the row does not shift on a route change.
+- **The current-item look reaches the anchor through the row**, since the hook is on the `<li>` and the anchor is its child.
+- **Keep the list's rules off the Root.** The Root wraps the section's content, so a descendant rule there reaches into every page. The Root's own classes and the layout's wrappers place the sidebar beside the section.
 
 ---
 
 ## Related
 
 - [[account-entry-point]] — the header control that links into the account.
+- [[account-access-gate]] — the loading look the root's redirect reuses, and the gate it runs under.
+- [[account-menu-identity]] — the shopper's name and avatar, composed beside the list inside the Root.
 - [[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/avatar.md

@@ -0,0 +1,103 @@
+# Avatar
+
+**Category:** content
+**Purpose:** A person or account marker: an image with an initials fallback derived from a name. It carries no account data of its own.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A small circle, usually 32–48px, holding one or two capital letters — `JD`, `A` — on a flat tinted background.
+- Or the same circle holding a round photo of a person.
+- It sits beside a person's name, in a comment, a profile header, or an account sidebar.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- Wherever a person or account needs a compact visual marker beside their name.
+- When there may be no photo: the initials are the fallback, not a separate component.
+
+## When NOT to use
+
+- For a product or content image → use `Image`.
+- For a status or count label → use `Badge`.
+- For a logo → use `Logo`.
+
+---
+
+## Composition
+
+`Avatar` is a leaf. It renders one `<span>` holding the image, when there is one, and the initials fallback. It has no children and requires no ancestor.
+
+```
+Container
+└── Avatar
+```
+
+---
+
+## Components
+
+### Avatar
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `name` | string | — | Whose avatar this is. The initials derive from it: the first letters of the first and last words, or one letter for a single word. |
+| `src` | string | — | Image URL. Absent or empty, the initials show. |
+| `alt` | string | — | Accessible name. Without it the avatar is decorative and hidden from assistive technology. |
+
+The fallback shows whenever there is no image, the image is still loading, or it failed to load. The image replaces it only once it has loaded.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "shopper-avatar": {
+    "type": "Avatar",
+    "props": { "name": "Jane Doe", "alt": "Jane Doe" },
+    "style": ["inline-flex", "size-10", "items-center", "justify-center", "rounded-full", "bg-gray-200", "text-sm", "font-medium"]
+  }
+}
+```
+
+## Common mistakes
+
+- **Leaving `alt` off a standalone avatar.** Without `alt` it is hidden from assistive technology, which is right beside text that already names the person and wrong anywhere else. Give it an `alt`.
+- **Giving it an `alt` beside the person's name.** The name is then announced twice.
+- **Expecting a photo from `name` alone.** `name` only derives initials; a photo needs `src`.
+- **Inventing `ProfilePicture` or `UserIcon`.** The component is `Avatar`.
+- **Styling without a size and shape.** The particle ships no look: give it a size, `rounded-full`, and overflow hidden, or the image and initials render unconstrained.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `Avatar` | `data-fs-avatar` is the circle: size, shape, background, and the initials' type | `inline-flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-full bg-[#E5E7EB] text-[14px] font-medium` |
+| Image | `data-fs-avatar-image` is the `<img>` once loaded | `size-full object-cover` |
+| Initials | `data-fs-avatar-fallback` is the initials span | `uppercase` |
+
+```json
+{
+  "shopper-avatar": {
+    "type": "Avatar",
+    "props": { "name": "Jane Doe", "alt": "Jane Doe" },
+    "style": [
+      "inline-flex", "size-10", "shrink-0", "items-center", "justify-center", "overflow-hidden",
+      "rounded-full", "bg-[#E5E7EB]", "text-[14px]", "font-medium", "[&_img]:size-full", "[&_img]:object-cover"
+    ]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[badge]] — a status or count label; distinct from a person marker.
+- `Image` — a content image with no fallback or initials.
+- [[account-menu-identity]] — the account sidebar's name-and-avatar block, which composes `Avatar`.

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

@@ -61,7 +61,7 @@ A field Control is absent from the composition means absent from both states and
 - **Save order**: compute dirtiness first → nothing dirty raises the saved toast without dispatching → otherwise validate only the dirty registered fields' current draft values (Decision 9) → any error blocks the dispatch and focuses the first invalid field in rendered DOM order → otherwise normalize dirty values and dispatch one `$actions.identity.customerProfileUpdate` → a `userError` raises an error toast and keeps the edit state with the draft intact → success returns to the view state and raises a success toast (Decision 10). A field the shopper never touched is neither validated nor sent.
 - **Edit always opens from the latest saved values**: pressing Edit re-seeds the draft from `savedValues` before switching modes, so a value the server normalized on a previous save (not this task's concern, but a sibling Control's) is what the shopper sees, not a stale local draft.
 - **Background re-delivery**: when `$data` delivers new values while editing, a field re-seeds only if its draft still equals the previously saved value; a dirty field is never clobbered.
-- **Self-gate**: renders nothing outside `state === 'loggedIn'`, even if the topology's `SessionGuard` is missing. Renders `MyAccountProfileSkeleton` while `$data` is unresolved and the shopper is logged in — never an empty summary.
+- **Self-gate**: renders nothing outside `state === 'loggedIn'`, even if the topology's `SessionGuard` is missing. Renders `MyAccountProfileSkeleton` while `$data` is unresolved and the shopper is logged in — never an empty summary. `customerProfile` is nullable, so `$data` is also `null` for an anonymous session (the self-gate renders nothing) and for a logged-in shopper whose read failed (the skeleton stays).
 - **PII**: no profile value appears in any log line. A write that throws (rather than resolving `userErrors`) logs only the error's name; the message shown to the shopper is the `saveFailedMessage` schema prop.
 
 ---

package/dist/docs/product-shelf.md

@@ -1,7 +1,7 @@
 # ProductShelf
 
 **Category:** commerce
-**Purpose:** A data-owning product shelf. `ProductShelfRoot` owns a facet-filtered `products(filter:)` query from the catalog module, receives its slice as `$data`, and publishes each product through a per-item context. `ProductShelfItems` repeats those products into a `Carousel` track, one card per slide. The card parts (`ProductCard*`) read each product from context — the shelf holds the data and config, the carousel arranges the rows, the cards render one product each.
+**Purpose:** A data-owning product shelf. `ProductShelfRoot` owns a facet-filtered `products(first:, orderBy:, filter:)` query from the catalog module whose arguments bind to this element's configuration (the merchant's CMS entry, else the props), receives its slice as `$data`, and publishes each product through a per-item context. `ProductShelfItems` repeats those products into a `Carousel` track, one card per slide. The card parts (`ProductCard*`) read each product from context — the shelf holds the data and config, the carousel arranges the rows, the cards render one product each.
 
 ---
 
@@ -18,7 +18,7 @@ A ProductShelf block contains any combination of:
 
 If the image shows **any of the above**, use `ProductShelfRoot` composed with `CarouselRoot` and `ProductShelfItems`. When a section heading is visible, compose `ProductShelfHeading` inside `ProductShelfRoot` (above `CarouselRoot`) with the title as its `children` (like any `Text`). Pick only the card parts (`ProductCardImage`, `ProductCardName`, `ProductCardPrice`, `ProductCardListPrice`, `ProductCardDiscount`, …) that match what's visible in each card.
 
-The image is the source of truth for the heading text, `first`/`itemsPerPage`, and which card parts to include. The **source of the shelf's products** (`categoryId` / `brandId` / `collectionId` / `searchTerm` / `specifications`) is a merchant configuration decision and cannot be read off the screenshot — leave those unset when the image gives no signal, and let the shelf fall back to catalog-wide relevance.
+The image is the source of truth for the heading text, `first`/`itemsPerPage`, and which card parts to include. The **source of the shelf's products** (`categoryId` / `brandId` / `collectionId` / `searchTerm`) is a merchant configuration decision and cannot be read off the screenshot — leave those unset when the image gives no signal, and let the shelf fall back to catalog-wide relevance.
 
 ---
 
@@ -36,8 +36,9 @@ The image is the source of truth for the heading text, `first`/`itemsPerPage`, a
 
 ## Behavior model
 
-- **The shelf owns the data.** `ProductShelfRoot` declares a `fragment ProductShelfData on Query` selecting `products(first: $first, orderBy: $orderBy, filter: $filter)` and receives the resolved slice as `$data`. `fetchStrategy: 'lazy'` defers the load (below-the-fold), and a skeleton shows while pending.
-- **Config feeds the query.** The serializable schema props map to the fragment variables: `first` → `$first`, `sort` → `$orderBy` (`ProductSortingInput`), and the facet props (`searchTerm`, `categoryId`, `brandId`, `collectionId`, `specifications`, `availableOnly`) → `$filter` (`ProductsFilterInput`). `buildProductShelfVariables(config)` is the pure mapping.
+- **The shelf owns the data.** `ProductShelfRoot` declares a `fragment ProductShelfData on Query` selecting `products(first: $first, orderBy: $orderBy, filter: { categoryIds: $categoryId, brandIds: $brandId, collectionId: $collectionId, searchTerm: $searchTerm, availableOnly: $availableOnly })` and receives the resolved slice as `$data`. `fetchStrategy: 'lazy'` defers the load (below-the-fold), and a skeleton shows while pending.
+- **The element's configuration feeds the query.** Every variable binds to this element: the compiler reads the field of the same name from the element's content slice (the `product-shelf` content model, in a store with a `cms` binding) and otherwise from the element's prop, then instances the fragment once per shelf on the page, so two shelves with different `first` or `sort` become two aliased `products` fields in one page query. `sort` reaches `$orderBy` (`ProductSortingInput`) through the `values` table in the definition's `variables` block, which equals `PRODUCT_SHELF_SORT_MAP`. A facet left empty is not sent, so the filter relaxes instead of sending `null`; `first` is honored by the API, never sliced on the client.
+- **Props beside content.** Each content field is also a schema prop of the same name. The CMS value wins per field; the prop is the developer default and the only source in a store with no `cms` binding (Vivara, Storybook, tests). No field is `required`, so an unfilled entry never omits the shelf. `useProductShelf()` exposes the resolved `config` (`$content?.field ?? field`), `itemsPerPage` and `count`.
 - **Two context boundaries.** The shelf owns product data + config; each row owns one item. Card parts read the item through a guarded hook and never take list-shaped props.
 - **Presence is state-driven.** Empty result → the shelf renders nothing (no empty carousel). Unresolved lazy source → skeleton.
 - **The carousel is composed, not baked.** Place `CarouselRoot` with `ProductShelfItems` inside it, plus `CarouselPrevious` / `CarouselNext` / `CarouselBullets` where you want them. `ProductShelfItems` renders the `CarouselTrack`, so the carousel counts one slide per product.
@@ -51,17 +52,23 @@ The image is the source of truth for the heading text, `first`/`itemsPerPage`, a
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `first` | number | `5` | Max products fetched (legacy `numberOfItems`) → `$first` |
 | `itemsPerPage` | number | `5` | Cards per page; bind to `CarouselRoot`'s `itemsPerPage` |
-| `sort` | `relevance \| price_asc \| price_desc \| name_asc \| name_desc \| release \| orders \| discount` | `relevance` | → `$orderBy` |
-| `searchTerm` | string | — | → `filter.searchTerm` |
-| `categoryId` | string | — | → `filter.categoryIds` |
-| `brandId` | string | — | → `filter.brandIds` |
-| `collectionId` | string | — | → `filter.collectionId` (legacy `productClusterIds`) |
-| `specifications` | `{ name, values }[]` | — | → `filter.specifications` (custom attributes) |
-| `availableOnly` | boolean | `false` | → `filter.availableOnly` (global "hide out-of-stock") |
+| `usePriceWithTaxes` | boolean | `false` | Card prices render tax-inclusive |
+| `taxesLabel` | string | `'Tax included'` | Text for the tax label part |
+| `first` | number | `5` | Content field. Products fetched (legacy `numberOfItems`) → `$first` |
+| `sort` | `relevance \| price_asc \| price_desc \| name_asc \| name_desc \| release \| orders \| discount` | `relevance` | Content field → `$orderBy` through the `values` table |
+| `searchTerm` | string | — | Content field → `filter.searchTerm` |
+| `categoryId` | string | — | Content field → `filter.categoryIds` |
+| `brandId` | string | — | Content field → `filter.brandIds` |
+| `collectionId` | string | — | Content field → `filter.collectionId` (legacy `productClusterIds`) |
+| `availableOnly` | boolean | `false` | Content field → `filter.availableOnly` (global "hide out-of-stock") |
+| `$content` | slice | — | Compiler-injected `product-shelf` entry; each field wins over the prop of the same name |
 | `$data` | slice | — | Compiler-injected fragment result |
-| `products` | `ProductShelfItem[]` | — | Pre-shaped items (stories/tests; bypasses `$data`) |
+| `products` | `ProductShelfItem[]` | — | Pre-shaped items (stories/tests; bypasses `$data`). Rendered as given: `first` does not limit them |
+
+### Content model `product-shelf`
+
+`ProductShelfContent` declares the merchant-facing fields: `first` (number, minimum 1), `sort` (the eight members above), `categoryId`, `brandId`, `collectionId`, `searchTerm` (string) and `availableOnly` (boolean). None is required. In a store with a `cms` binding the merchant fills them in the Content Platform entry keyed by the element id, and the shelf re-queries on the next request with no deploy; an empty field falls to the prop, and an empty facet relaxes the filter.
 
 ### ProductShelfItems
 

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { ActionSelector } from "./core/dist/actions/registry.js";
 import { MockActions, mockAction } from "./core/dist/actions/mock-action.js";
 import { JsonValue, StorefrontContext } from "./core/dist/schema/generated/schema.js";
 import { ContentArraySchema, ContentNestedObjectShape, ContentObjectPropertySchema, ContentObjectSchema, ContentPropertySchema, ContentPropertyType, ContentScalarSchema, ContentScalarType, ContentTypeDefinition, ContentValue, defineContentType } from "./core/dist/define-content-type.js";
-import { ComponentDefinition, EditorMetadata, FetchStrategy, PropSchema, PropSchemaField, PropType, defineComponent } from "./core/dist/define-component.js";
+import { ComponentDefinition, EditorMetadata, FetchStrategy, PropSchema, PropSchemaField, PropType, VariableBinding, VariableBindings, defineComponent } from "./core/dist/define-component.js";
 import "./core/dist/index.js";
 import { CartUserError } from "./sdk/cart/operations.js";
 import { AddItemPayload, CartActions, CartCouponPayload, CartLinePayload, CartLinesPayload, CartQuantityPayload } from "./sdk/cart/use-cart-actions.js";
@@ -19,4 +19,4 @@ import { ShippingOptionSelectUserError } from "./sdk/shipping/option-select-oper
 import { ShippingAddressInput, ShippingAddressUpdateErrorEntity } from "./sdk/shipping/shipping-operations.js";
 import { ShippingActions } from "./sdk/shipping/use-shipping-actions.js";
 import { ComponentActions } from "./sdk/actions/types.js";
-export { type ActionSelector, type AddItemPayload, type CartActions, type CartCouponPayload, type CartLinePayload, type CartLinesPayload, type CartQuantityPayload, type CartUserError, type ClientPreferenceKey, type ClientPreferencesUpdatePayload, type ClientProfileUpdatePayload, type ClientProfileUserError, type ComponentActions, type ComponentDefinition, type ContentArraySchema, type ContentNestedObjectShape, type ContentObjectPropertySchema, type ContentObjectSchema, type ContentPropertySchema, type ContentPropertyType, type ContentScalarSchema, type ContentScalarType, type ContentTypeDefinition, type ContentValue, type CustomerProfileUpdatePayload, type CustomerProfileUserError, type EditorMetadata, type FetchStrategy, type IdentityActions, type JsonValue, type MockActions, type PaymentActions, type PaymentBillingAddressUpdateInput, type PaymentGatewayCallbackResult, type PaymentGatewayCard, type PaymentGatewayNewCard, type PaymentGatewaySavedCard, type PaymentGatewayTransaction, type PaymentMethodSelectInput, type PaymentMoney, type PaymentStartTransactionResult, type PaymentUserError, type PropSchema, type PropSchemaField, type PropType, type RegionActions, type RegionUserError, type SendPaymentsRequest, type SessionAccessCodeRequestResult, type SessionActions, type SessionPasswordLoginPayload, type SessionRequestAccessCodePayload, type SessionUserError, type SessionValidateAccessCodePayload, type ShippingActions, type ShippingAddressInput, type ShippingAddressUpdateErrorEntity, type ShippingOptionSelectUserError, type StorefrontContext, defineComponent, defineContentType, mockAction };
+export { type ActionSelector, type AddItemPayload, type CartActions, type CartCouponPayload, type CartLinePayload, type CartLinesPayload, type CartQuantityPayload, type CartUserError, type ClientPreferenceKey, type ClientPreferencesUpdatePayload, type ClientProfileUpdatePayload, type ClientProfileUserError, type ComponentActions, type ComponentDefinition, type ContentArraySchema, type ContentNestedObjectShape, type ContentObjectPropertySchema, type ContentObjectSchema, type ContentPropertySchema, type ContentPropertyType, type ContentScalarSchema, type ContentScalarType, type ContentTypeDefinition, type ContentValue, type CustomerProfileUpdatePayload, type CustomerProfileUserError, type EditorMetadata, type FetchStrategy, type IdentityActions, type JsonValue, type MockActions, type PaymentActions, type PaymentBillingAddressUpdateInput, type PaymentGatewayCallbackResult, type PaymentGatewayCard, type PaymentGatewayNewCard, type PaymentGatewaySavedCard, type PaymentGatewayTransaction, type PaymentMethodSelectInput, type PaymentMoney, type PaymentStartTransactionResult, type PaymentUserError, type PropSchema, type PropSchemaField, type PropType, type RegionActions, type RegionUserError, type SendPaymentsRequest, type SessionAccessCodeRequestResult, type SessionActions, type SessionPasswordLoginPayload, type SessionRequestAccessCodePayload, type SessionUserError, type SessionValidateAccessCodePayload, type ShippingActions, type ShippingAddressInput, type ShippingAddressUpdateErrorEntity, type ShippingOptionSelectUserError, type StorefrontContext, type VariableBinding, type VariableBindings, defineComponent, defineContentType, mockAction };

package/dist/internal/client.js

@@ -1,11 +1,11 @@
 import { gql } from "../sdk/graphql-tag.js";
 import { DataOverrideContext, useDataOverride } from "../sdk/data/data-override-context.js";
+import { PageReactiveDataRoot, ReactiveRootContext } from "../sdk/data/page-reactive-data-root.js";
 import { HotDataProvider } from "../sdk/data/hot-data-provider.js";
 import { publishedVariantIdFor, selectedVariantVar } from "../sdk/state/variant-selector.js";
 import { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, miniCartOpenVar, orderFormIdVar } from "../sdk/state/cart.js";
 import { buildOptimisticDecrease, buildOptimisticIncrease, buildOptimisticRemove } from "../sdk/cart/optimistic.js";
 import { ListItemRefContext, useListItemRef } from "../sdk/data/list-item-ref-context.js";
-import { PageReactiveDataRoot, ReactiveRootContext } from "../sdk/data/page-reactive-data-root.js";
 import { AnalyticsActionProvider } from "../sdk/actions/analytics-action-provider.js";
 import { CartActionProvider } from "../sdk/actions/cart-action-provider.js";
 import { IdentityActionProvider } from "../sdk/actions/identity-action-provider.js";

package/dist/internal/content.d.ts

@@ -1,2 +1,2 @@
-import { ContentEntryBoundaryProps, ContentEntryResult, ContentRuntime, ContentRuntimeConfig, ContentSlices, ReadContentSlicesArgs, createContentRuntime } from "../sdk/content/create-content-runtime.js";
-export { type ContentEntryBoundaryProps, type ContentEntryResult, type ContentRuntime, type ContentRuntimeConfig, type ContentSlices, type ReadContentSlicesArgs, createContentRuntime };
+import { ContentEntryBoundaryProps, ContentEntryResult, ContentItemResult, ContentRuntime, ContentRuntimeConfig, ContentSlices, ReadContentItemArgs, ReadContentSlicesArgs, createContentRuntime } from "../sdk/content/create-content-runtime.js";
+export { type ContentEntryBoundaryProps, type ContentEntryResult, type ContentItemResult, type ContentRuntime, type ContentRuntimeConfig, type ContentSlices, type ReadContentItemArgs, type ReadContentSlicesArgs, createContentRuntime };

package/dist/internal/server.d.ts

@@ -2,6 +2,9 @@ import { buildStorefrontContextHeaders } from "../sdk/context/headers.js";
 import { CreateClientOptions, createClient } from "../sdk/client/create-client.js";
 import { FetchPageDataOptions, FetchPageDataResult, fetchPageData } from "../sdk/client/fetch-page-data.js";
 import { PreloadQueryRegistry, RegisterPreloadQueryOptions, registerPreloadQuery } from "../sdk/client/register-preload-query.js";
+import { ContentVariableField, ContentVariablesSpec, VariablesFromContentOptions, variablesFromContent } from "../sdk/data/variables-from-content.js";
 import { getIntl, loadMessages } from "../sdk/i18n/server.js";
+import { ServerSessionRead, readServerSession } from "../sdk/session/read-server-session.js";
+import { resolveSignInHref } from "../utils/safe-href.js";
 import { PreloadQueryProps } from "@apollo/client-integration-nextjs";
-export { type CreateClientOptions, type FetchPageDataOptions, type FetchPageDataResult, type PreloadQueryProps, type PreloadQueryRegistry, type RegisterPreloadQueryOptions, buildStorefrontContextHeaders, createClient, fetchPageData, getIntl, loadMessages, registerPreloadQuery };
+export { type ContentVariableField, type ContentVariablesSpec, type CreateClientOptions, type FetchPageDataOptions, type FetchPageDataResult, type PreloadQueryProps, type PreloadQueryRegistry, type RegisterPreloadQueryOptions, type ServerSessionRead, type VariablesFromContentOptions, buildStorefrontContextHeaders, createClient, fetchPageData, getIntl, loadMessages, readServerSession, registerPreloadQuery, resolveSignInHref, variablesFromContent };