@vtex/faststore 0.0.1

package/dist/core/dist/index.js

@@ -0,0 +1,5 @@
+import { mockAction } from "./actions/mock-action.js";
+import { defineActions } from "./actions/registry.js";
+import { defineComponent } from "./define-component.js";
+import { defineContentType } from "./define-content-type.js";
+export { defineActions, defineComponent, defineContentType, mockAction };

package/dist/core/dist/schema/generated/schema.d.ts

@@ -0,0 +1,28 @@
+//#region ../core/dist/schema/generated/schema.d.ts
+/** Arbitrary JSON — the value type of the flattened catch-alls. */
+export type JsonValue = number | string | boolean | Array<JsonValue> | {
+  [key: string]: JsonValue;
+} | null;
+/**
+ * The immutable per-request storefront context — the public name of the contract.
+ * `Readonly` because the compiler emits it as a frozen module-level constant: one mutation
+ * would leak across every request a server process handles.
+ */
+export type StorefrontContext = Readonly<StorefrontContextShape>;
+export type Direction = "ltr" | "rtl";
+export type StorefrontContextShape = {
+  bindingId: string;
+  locale: string;
+  currency: string;
+  salesChannel: string;
+  country?: string;
+  timezone?: string;
+  direction: Direction;
+  /**
+   * Resolution-only, so absent while nothing resolves. Never an empty string.
+   */
+  origin?: string;
+  basePath: string;
+};
+//#endregion
+//# sourceMappingURL=schema.d.ts.map

package/dist/core/dist/types.d.ts

@@ -0,0 +1 @@
+import "./define-component.js";

package/dist/docs/access-code-field.md

@@ -0,0 +1,100 @@
+# AccessCodeField
+
+**Category:** content
+**Purpose:** A presentational one-time-code input that composes the `Field` particle (label + native `<input>` + inline error), mirroring `EmailField`'s shape. Unlike `EmailField`, it performs **no** client-side format validation — a code's validity is entirely server-decided. It is data-agnostic — value flows through props; it consumes no GraphQL and no domain context.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A single-line text input labelled something like **"Enter the code we sent you"**, **"Verification code"**, or **"Access code"**, usually the second step of a passwordless / access-code sign-in flow, right after an email or "send code" step.
+- Often shows a placeholder like `000000`.
+- When invalid, an inline error message below the input (e.g. *"That code is incorrect or expired."*).
+- Never rendered as a six-box segmented widget in this catalog — always a single text input.
+
+If the image shows a checkout sign-in step whose only field is a numeric/alphanumeric code entered after requesting it by email, use `AccessCodeField` — or, for the full request/validate flow wired to the session, use `AccessCodeSignIn.Validate`.
+
+---
+
+## When to use
+
+- A standalone, presentational one-time-code input where the host owns the value and the validation outcome.
+- As the field rendered by `AccessCodeSignIn.Validate` (the checkout-bound wrapper).
+
+## When NOT to use
+
+- When the field must dispatch the validate mutation and hold the stepper's `authenticationToken` → use `AccessCodeSignIn.Validate`, which wraps this particle.
+- For an email or generic text field → use `EmailField` or the `Field` particle directly.
+- For a segmented, per-digit box input → out of scope for this catalog; this particle is always a single `<input>`.
+
+---
+
+## Composition
+
+`AccessCodeField` is a single leaf particle. Internally it renders:
+
+```
+AccessCodeField             (data-fs-access-code-field + inherited data-fs-field-root)
+├── Field.Label              (data-fs-field-label; the `label` prop)
+├── Field.Control             (data-fs-field-control; native <input type="text" autocomplete="one-time-code">)
+└── Field.Error               (data-fs-field-error; the `errorMessage`, shown when invalid)
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `value` | string | — | Controlled value. Omit for uncontrolled use. |
+| `defaultValue` | string | `''` | Uncontrolled initial value. |
+| `onValueChange` | `(value: string) => void` | — | Fires on every input change. |
+| `onBlur` | `(event) => void` | — | Fires on blur. |
+| `invalid` | boolean | `false` | Host-driven invalid state — **never** self-derived. |
+| `errorMessage` | string | — | Inline error text, shown when `invalid` is true. |
+| `label` | string | — | Accessible label. |
+| `placeholder` | string | — | Input placeholder. |
+| `disabled` | boolean | `false` | Disables the input (e.g. while a dispatch is in flight). |
+| `required` | boolean | `true` | A code is always required at this step. |
+| `name` | string | `'accessCode'` | Field/input name. |
+| `autoComplete` | string | `'one-time-code'` | Enables OS/browser code autofill despite the single-line shape. |
+| `inputMode` | string | `'numeric'` | Mobile keypad hint; override (e.g. `'text'`) for alphanumeric codes. |
+| `maxLength` | number | — | Caps the entered length (the wrapper passes its `codeLength`). Not a validity check. |
+
+**Validation:** none, by design. A code's correctness (does it match what was emailed, is it still live) is exclusively decidable server-side; `invalid`/`errorMessage` are entirely host-driven, fed from `validateAccessCode`'s `userErrors`.
+
+---
+
+## Accessibility
+
+The label is associated with the input and the error is linked via `aria-describedby` automatically by the Base UI `Field` primitive (WCAG 2.1 AA). Standard text-input keyboard editing; nothing blocks typing.
+
+---
+
+## Styling
+
+`AccessCodeField` owns no CSS. Style it via compound swatches / Tailwind targeting the `data-fs-*` attributes:
+
+| Target | What you style |
+|---|---|
+| `data-fs-access-code-field` | The field container (stack the label, input, error). |
+| `data-fs-field-label` | The label typography. |
+| `data-fs-field-control` | The input box; use `data-invalid:` for the error border. |
+| `data-fs-field-error` | The inline error text (small, red). |
+
+---
+
+## Common mistakes
+
+- **Adding client-side format validation.** A code's validity is server-only; `invalid`/`errorMessage` must come from `userErrors`, never a local regex.
+- **Wiring GraphQL into this particle.** It is data-agnostic; use `AccessCodeSignIn.Validate` for the checkout-bound binding.
+- **Replacing it with a segmented multi-box widget.** This catalog deliberately composes `Field` + `Input` into a single-line input.
+- **Localizing via a message id.** There is no `react-intl`; pass `label` / `placeholder` / `errorMessage` as strings.
+
+---
+
+## Related
+
+- [[access-code-sign-in]] — the checkout-bound matter family (Root + Request + Validate) that composes this particle into the two-step sign-in flow.
+- [[email-field]] — the sibling particle for the email step; the shape this particle mirrors.
+- [[field]] — the underlying form-field particle this composes.

package/dist/docs/access-code-sign-in.md

@@ -0,0 +1,174 @@
+# AccessCodeSignIn (Root + Email + Request + Validate)
+
+**Category:** identity
+**Purpose:** A self-gating, cart-independent passwordless sign-in flow, available from the `anonymous` state onward. `AccessCodeSignInRoot` owns a locally-typed draft email (never written to the cart) and reads the account's provider config (`sessionAuthProviders.accessKeyAuthentication`); it renders nothing once the shopper is already `loggedIn` or the account disables the method. `AccessCodeEmailControl` collects the draft email; `AccessCodeRequestControl` sends the code; `AccessCodeValidateControl` collects and validates it. A successful validate flips `useSession()` to `loggedIn` (and the server persists the validated email onto the cart's profile as a side effect), which makes the whole Root disappear on its own.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- An **email input + "send a sign-in code" button**, usable with no prior identification step — this is `AccessCodeEmailControl` + `AccessCodeRequestControl`.
+- A **one-time-code input + submit button** shown right after activating the send-code button — this is `AccessCodeValidateControl` composing `AccessCodeField`.
+- Lives inside the checkout User Identity step as an optional method — never a step the shopper must complete to continue as a guest.
+- No third "blocked" or "rate limited" full-screen error state: those outcomes appear as small inline text under the button/field instead.
+
+Use `AccessCodeSignIn.*` whenever the image shows a passwordless "email me a code" affordance, distinct from a password field, especially one usable before any other identification step.
+
+---
+
+## When to use
+
+- The access-code (passwordless) sign-in method in the checkout User Identity step, for a shopper at any session state short of `loggedIn` — including fully `anonymous`, with no prior email identification.
+- Alongside the password `SignInForm` (FSPG-865), as one of possibly several sign-in methods a page composes — this family never assumes it's the only one.
+
+## When NOT to use
+
+- A blocking, must-complete-to-continue login gate → this flow is always optional; it self-gates to hidden and never blocks guest checkout.
+- Persisting the draft email as profile data on its own → `AccessCodeEmailControl` never writes to the cart; only a successful `validateAccessCode` does, server-side, as a side effect of authentication. Don't pair it with `EmailIdentificationControl` for the same field — that control's blur-triggered `clientProfileUpdate` is a different, cart-writing identification path.
+- Composing "sign in with a password instead" or "use another email" switch affordances → those are the hosting component's job (FSPG-865), not this family's.
+
+---
+
+## Composition
+
+```
+SessionRoot                              (provides the session tri-state; required ancestor)
+└── AccessCodeSignInRoot                 (data-fs-access-code-sign-in-root; self-gates; owns draft email + step + authenticationToken)
+    ├── AccessCodeEmailControl           (visible only in step 'request'; local draft email, never persisted)
+    ├── AccessCodeRequestControl         (visible only in step 'request')
+    │   └── (button)                     (dispatches $actions.session.requestAccessCode with the draft email)
+    └── AccessCodeValidateControl        (visible only in step 'validate')
+        ├── AccessCodeField              (the code input; value/invalid/errorMessage bound)
+        └── (submit button)              (dispatches $actions.session.validateAccessCode)
+```
+
+`AccessCodeSignInRoot` **must** have a `SessionRoot` ancestor — `useSession()` throws otherwise. `AccessCodeEmailControl`, `AccessCodeRequestControl`, and `AccessCodeValidateControl` **must** be descendants of `AccessCodeSignInRoot` — all three throw a descriptive error otherwise (runtime-only guard, not compiler-checked).
+
+`AccessCodeEmailControl` is optional: an identified shopper's `clientProfile.email` pre-fills the Root's draft even without it composed, so a page that only wants the identified-shopper case (skipping straight to `AccessCodeRequestControl`) may omit it — but then an anonymous shopper has no way to type an email, so the request control stays disabled (empty draft never passes its valid-email gate).
+
+---
+
+## Props
+
+### `AccessCodeSignInRoot`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `$data` | `{ clientProfile: { email } \| null, sessionAuthProviders: { accessKeyAuthentication } \| null } \| null` | injected | Colocated `on Query` fragment slice. An unresolved (`null`) read is treated the same as "provider disabled" — the flow stays hidden rather than flashing. |
+
+**Data:** declares `fragment AccessCodeSignInData on Query { clientProfile { email } sessionAuthProviders { accessKeyAuthentication } }` with `fetchStrategy: 'reactive'` and `requiresContext: 'session'`.
+
+**Gate:** renders its children whenever **both** hold: `useSession().state !== 'loggedIn'` and `sessionAuthProviders.accessKeyAuthentication === true`. Available from `anonymous` through `identified`; hides once `loggedIn` or when the account disables the method or the fragment hasn't resolved yet.
+
+### `AccessCodeEmailControl`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | Passed to `EmailField`. |
+| `placeholder` | string | — | Passed to `EmailField`. |
+| `invalidEmailMessage` | string | — | `EmailField`'s inline error text; format validation itself is `EmailField`'s own blur-triggered check, never per-keystroke. |
+
+Renders only at the request step. Declares no actions — it never dispatches a mutation, it only writes the Root's local draft state.
+
+### `AccessCodeRequestControl`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | Send-code button label. |
+| `pendingLabel` | string | — | Label while the request is in flight. |
+| `sendLimitMessage` | string | — | Inline message for `ACCESS_CODE_SEND_LIMIT`. |
+| `blockedMessage` | string | — | Inline message for `BLOCKED`. |
+| `networkErrorMessage` | string | — | Inline message for the synthetic `NETWORK_ERROR`. |
+| `onRequested` | `(authenticationToken: string) => void` | — | Fires after a successful request, alongside the Root's own step advance. |
+| `$actions` | injected | — | Carries `session.requestAccessCode` (compiler-injected, narrowed to that one method). |
+
+The button is disabled until the Root's draft email is a valid, non-empty address (checked with the same rule `EmailIdentificationControl` uses) — never a blocking error state, just an inert affordance.
+
+### `AccessCodeValidateControl`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | — | Passed to `AccessCodeField`. |
+| `placeholder` | string | — | Passed to `AccessCodeField`. |
+| `submitLabel` | string | — | Submit button label. |
+| `codeLength` | number | `6` | Disables submit below this length and caps the field maxLength — a UX gate, never a validity claim. |
+| `invalidCodeMessage` | string | — | Inline message for `INVALID_ACCESS_CODE`. |
+| `blockedMessage` | string | — | Inline message for `BLOCKED`. |
+| `missingAuthContextMessage` | string | — | Inline message for `MISSING_AUTH_CONTEXT` (should not occur on a correct flow). |
+| `networkErrorMessage` | string | — | Inline message for the synthetic `NETWORK_ERROR`. |
+| `onValidated` | `() => void` | — | Fires after a successful validate. No local "success" UI is needed — the session flip hides the Root. |
+| `$actions` | injected | — | Carries `session.validateAccessCode` (compiler-injected, narrowed to that one method). |
+
+---
+
+## Behavior
+
+- **Draft email ownership:** the Root owns a local `email` string (`useState`), never the cart. It pre-fills from `clientProfile.email` when known (a convenience for an already-identified shopper) — untouched-field re-seed, mirroring `ClientProfileForm`'s draft/dirty tracking: the re-seed only runs while the flow is still at the `request` step and the draft is untouched, so once the shopper edits the draft or the flow advances past `request`, further profile-email updates never clobber it (and the email can't diverge between `requestAccessCode` and `validateAccessCode`). Editing it dispatches nothing; it is purely the argument `requestAccessCode`/`validateAccessCode` are called with.
+- **Profile persistence happens server-side, on success:** a successful `validateAccessCode` sets the cart's `clientProfileData.email` to the validated email as a side effect of authentication (see the auth module's `completeLoginWithEmail`) — this family itself never calls `clientProfileUpdate`.
+- **No account-existence pre-check:** `AccessCodeRequestControl` dispatches unconditionally once the draft email is valid — no separate lookup call.
+- **Stepper:** the Root owns `step: 'request' | 'validate'` and `authenticationToken: string | null` as local state — the session-action namespace itself holds none of this (a deliberate choice in the FSPG-880 session-actions design).
+- **Every failure is inline:** `ACCESS_CODE_SEND_LIMIT` / `BLOCKED` / `NETWORK_ERROR` surface at the request control; `INVALID_ACCESS_CODE` / `BLOCKED` / `MISSING_AUTH_CONTEXT` / `NETWORK_ERROR` surface on the `AccessCodeField` inside the validate control. The step never changes on error — the shopper can retry or abandon the method and continue as a guest.
+- **Success is entirely reactive:** on a successful validate, the mutation's normalized cache write flips `useSession().state` to `loggedIn` with no refetch and no imperative cache write; the Root's own `useSession()` read reacts and self-gates back to hidden.
+- **Pending states:** both controls expose `data-fs-access-code-request-pending` / `data-fs-access-code-validate-pending` while their dispatch is in flight, disabling their interactive elements — mirrors `CartCouponForm`'s `data-fs-cart-coupon-pending`.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "type": "SessionRoot",
+  "children": [
+    {
+      "type": "AccessCodeSignInRoot",
+      "children": [
+        {
+          "type": "AccessCodeEmailControl",
+          "props": {
+            "label": "Email",
+            "placeholder": "you@example.com",
+            "invalidEmailMessage": "Enter a valid email address."
+          }
+        },
+        {
+          "type": "AccessCodeRequestControl",
+          "props": {
+            "label": "Send a sign-in code",
+            "sendLimitMessage": "Too many codes requested. Try again later.",
+            "blockedMessage": "This account is blocked. Contact support.",
+            "networkErrorMessage": "Something went wrong. Please try again."
+          }
+        },
+        {
+          "type": "AccessCodeValidateControl",
+          "props": {
+            "label": "Enter the code we sent you",
+            "placeholder": "000000",
+            "submitLabel": "Sign in",
+            "invalidCodeMessage": "That code is incorrect or expired.",
+            "networkErrorMessage": "Something went wrong. Please try again."
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## Common mistakes
+
+- **Rendering the controls outside `AccessCodeSignInRoot`.** All three throw a descriptive error immediately.
+- **Persisting the draft email yourself, or pairing this with `EmailIdentificationControl` for the same field.** `AccessCodeEmailControl` never writes to the cart; the server sets the profile email on a successful validate, not before.
+- **Adding a blocking error screen for send-limit/blocked outcomes.** Every failure is inline at the control that produced it — there is no third "error" step.
+- **Manually unmounting or resetting the flow after login.** The Root's own `useSession()` read is what hides it; no explicit call is needed.
+- **Persisting or logging the `authenticationToken` or the entered code.** Both flow through mutation variables only.
+
+---
+
+## Related
+
+- [[access-code-field]] — the presentational one-time-code particle this family composes.
+- [[session]] — provides the identification tri-state and the required `SessionRoot` ancestor; also what makes the Root disappear post-login.
+- [[email-identification]] — a separate, cart-writing identification path (blur-triggered `clientProfileUpdate`); do not compose it for the same email field as this family.

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

@@ -0,0 +1,155 @@
+# AccountEntryPoint
+
+**Category:** identity
+**Purpose:** Header control that reads the session and renders one link — sign in, or the shopper's account.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A small icon-plus-label pair at the right end of a header row, beside the cart.
+- The label reads as an invitation to sign in ("Entrar", "Sign In") or as a destination ("Minha conta", "My Account"), never both.
+- Rendered as one clickable unit; the icon is decorative and the label carries the meaning.
+- A grey bar in that slot, with no label, is the resolving state rather than a separate control.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- For the header's single account entry, when it must adapt to whether the shopper is signed in.
+
+## When NOT to use
+
+- For a plain link to a fixed destination → use [[navigation-link]].
+- For showing or hiding an arbitrary subtree by session state → use `SessionGuard`, which gates on the tri-state declaratively.
+- For an account menu with logout and sub-destinations → out of scope; this is a link, not a dropdown.
+
+---
+
+## Composition
+
+`AccountEntryPoint` is a leaf element in the PageSchema. It owns its internal composition — a navigation link wrapping an icon and a label — and takes no children.
+
+```text
+AccountEntryPoint
+```
+
+It requires a `SessionRoot` ancestor. The compiler rejects a placement without one, and at runtime `useSession()` throws rather than degrading to a silently wrong state.
+
+## Components
+
+### AccountEntryPoint
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `signedOutLabel` | string | — | Label for anonymous and identified shoppers. Optional, so an element can be authored from the CMS alone. |
+| `signedInLabel` | string | — | Label for logged-in shoppers. Optional for the same reason. |
+| `icon` | string | — | Icon reference for the glyph. Absent renders the label alone. |
+| `loadingLabel` | string | — | Text announced while the session resolves. |
+
+Content model (`account-entry-point`) fields, edited in the CMS:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `signedOutLabel` | string | no | Cleared or absent keeps the authored prop |
+| `signedInLabel` | string | no | Same |
+| `icon` | string | no | Same, but the name must be listed in `global.json → icons.include` — see below |
+| `loadingLabel` | string | no | Same |
+
+**An icon chosen in the CMS has to be declared in the store first.** Icon references resolve at compile time: the compiler collects every value of every `icon`-typed prop across the page and layout schemas and emits one sprite per route. A name that arrives at runtime from a CMS entry is never seen by that pass, so it renders a `<use>` pointing at a symbol the route's sprite does not carry — no build error, no runtime error, no glyph. For a merchant to be able to pick the icon in the Admin, the store must list the candidates under `global.json → icons.include`, which puts them in the root sprite regardless of what any schema references.
+
+**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 deferred proxy can return the shopper where they started; the account link goes to the platform's account route. Both are module constants, so no schema edit and no CMS entry can misroute the auth flow. The `returnUrl` value is constrained to a same-origin relative path and dropped otherwise, which keeps the proxy from being turned into an open redirect — though the proxy has to validate it again on its own side. 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 proxy that may set a cookie or redirect, so 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.
+
+**Nothing renders without a resolved label for the active state.** Both label props are optional and neither is required in the model, so an element can author nothing and take everything from the CMS. Presence is enforced once, at render, on the resolved value: an unauthored state renders no element at all, because a focusable link a screen reader announces as its bare URL is worse than no control. The gate is per state, so an element authoring only `signedOutLabel` still serves logged-out shoppers and renders nothing for logged-in ones.
+
+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.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "header-account": {
+    "type": "AccountEntryPoint",
+    "props": {
+      "signedOutLabel": "Entrar",
+      "signedInLabel": "Minha conta",
+      "loadingLabel": "Carregando conta…",
+      "icon": "lucide:user"
+    },
+    "style": ["$account-entry-point"]
+  }
+}
+```
+
+Bound to a CMS entry, the element authors no content props at all — the entry supplies all four fields.
+
+## Common mistakes
+
+- **Wrapping it in a `SessionGuard`.** The component reads the session itself; a guard around it would hide the resolving state and reintroduce the wrong-label flash.
+- **Wrapping it in a `NavigationLink`.** It already composes its own link; nesting it in another is invalid.
+- **Placing it outside a `SessionRoot`.** The compiler rejects it, and the runtime throws.
+- **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 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.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `AccountEntryPoint` | The control as a whole; `data-fs-account-entry-point` is the root and `data-fs-account-entry-point-state` switches on which link rendered | `inline-flex items-center gap-2 px-3 py-2` |
+| Label | `data-fs-account-entry-point-label` reaches the text apart from the glyph | `text-sm font-medium` |
+| Placeholder | `data-fs-account-entry-point-loading` sizes the resolving state; match the resolved control so the header does not reflow | `h-9 w-24 animate-pulse rounded-md bg-gray-100` |
+| Announcement | `data-fs-account-entry-point-announcement` reaches the live region carrying `loadingLabel`. It is a *following sibling* of the control, not a descendant, so reach it with `~` rather than a descendant selector | `sr-only` |
+
+```json
+{
+  "header-account": {
+    "type": "AccountEntryPoint",
+    "props": { "signedOutLabel": "Entrar", "signedInLabel": "Minha conta", "icon": "lucide:user" },
+    "style": ["inline-flex", "items-center", "gap-2", "text-sm"]
+  }
+}
+```
+
+The glyph carries a fixed intrinsic size, so reach it through the root when the header needs another.
+Author that once per store as the `AccountEntryPoint` base swatch in `global.json → styles`:
+
+```json
+{
+  "AccountEntryPoint": {
+    "base": ["[&_[data-fs-icon]]:w-5", "[&_[data-fs-icon]]:h-5"]
+  }
+}
+```
+
+Hide the announced text visually without dropping it from the accessibility tree. The region trails
+the control as a sibling, so this one is `~` rather than a descendant selector:
+
+```json
+{
+  "AccountEntryPoint": {
+    "base": ["[&~[data-fs-account-entry-point-announcement]]:sr-only"]
+  }
+}
+```
+
+---
+
+## Related
+
+- `SessionRoot` — the provider this component requires; host it at the root of the shared layout.
+- `SessionGuard` — the declarative gate for showing an arbitrary subtree by session state.
+- [[navigation-link]] — the client-side link this component composes.
+- [[icon]] — the glyph renderer it composes.

package/dist/docs/address-summary.md

@@ -0,0 +1,50 @@
+# Address Summary
+
+**Category:** content
+**Purpose:** Reusable, context-driven formatted display of a postal address.
+
+---
+
+## Composition
+
+`AddressSummaryRoot` (provides address via context) → `AddressSummary` (reads and renders the address).
+
+---
+
+## Components
+
+| Component | Props | Notes |
+|-----------|-------|-------|
+| `AddressSummaryRoot` | `address: AddressSummaryFields` (required), `children?: ReactNode` | Provides the address to descendant components via context (no business coupling). Must wrap `AddressSummary` or another presentation component. |
+| `AddressSummary` | `className?: string`, `children?: ReactNode` | Read-only formatted display: recipient name, street/number/complement, neighborhood/city/state/postal code. Lines with no content are omitted. Composed `children` render inside the container in place of the default lines. Must be a descendant of `AddressSummaryRoot`. |
+
+---
+
+## Lines are composed, not fixed
+
+`AddressSummary` is a **shortcut** for the default order (recipient, street line, locality line). Each line
+is also its own component reading the same `AddressSummaryRoot` context, so a page that wants another order,
+or only one of them, composes the leaves instead:
+
+| Leaf | Renders | Nothing when |
+|---|---|---|
+| `AddressSummaryRecipient` | who the delivery is addressed to | no recipient |
+| `AddressSummaryStreet` | street, number, complement | all three absent |
+| `AddressSummaryLocality` | neighborhood, city, state, postal code | all absent |
+
+## Known gaps
+
+Found by review and deliberately left for the dedicated revision of these components.
+
+- **`AddressSummary` no longer enforces its own context requirement.** It stopped reading the context when
+  the lines became composable, so only the leaves throw now. `<AddressSummary><CustomLine /></AddressSummary>`
+  outside an `AddressSummaryRoot` renders an empty styled block instead of failing loudly, while the
+  definition still declares `requiresContext: 'address-summary'` — the declared contract and the runtime
+  check no longer agree.
+- **`AddressSummaryRecipient`, `AddressSummaryStreet` and `AddressSummaryLocality` have no stories and no
+  test file of their own.** They are registered in the catalog but covered only indirectly, from
+  `shipping-address.test.tsx`. The `create-base-component` contract asks for both.
+
+## Extensibility
+
+A future alternative presentation (e.g., `LeanAddressSummary` or `AddressSummaryCompact`) could read the same `AddressSummaryRoot` context and be swapped in its place without any changes to the matter component that provides the `AddressSummaryRoot`. This is a composition change, not a new data-binding, and exemplifies the Free Particle Model (ADR-0001) — presentational components reused via context, uncoupled from business logic.