@vtex/faststore 0.0.1

package/dist/docs/product-shelf.md

@@ -0,0 +1,141 @@
+# 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.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Use these signals to detect that a ProductShelf block is present. Position on the page is irrelevant for detection — a shelf can appear inline on a PDP (cross-sell), between hero and footer on the homepage, or below the results grid on a PLP.
+
+A ProductShelf block contains any combination of:
+
+- A **horizontal strip of three or more visually similar product cards**, each rendering the same template (product image + product name + product price, sometimes plus a list-price strikethrough or a discount chip).
+- **Previous/Next arrows** (usually circular) sitting to the left and right of the strip — a carousel affordance for overflow items.
+- **Carousel bullets / dots** below the strip indicating pages.
+- A **section heading** naming the shelf's intent — e.g. *"Você também pode gostar"*, *"Compre também"*, *"Produtos similares"*, *"Você também vai gostar"*, *"Related products"*, *"You may also like"*, *"Customers also bought"*, *"Recommended for you"*.
+
+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.
+
+---
+
+## When to use
+
+- A cross-sell / discovery shelf on the PDP (Related Products), PLP, or Search Results: a facet-scoped, navigable carousel of product cards configured entirely in the VTEX Studio.
+
+## When NOT to use
+
+- A full-page product listing driven by the route/search → use `ProductListRoot` (prop-driven) with the PLP grid.
+- PDP single-product pricing → use `PricingRoot` (it fetches one `productBySlug`; it cannot price a per-card item in a list).
+- A generic non-product track of children → use the `Carousel` particle directly.
+
+---
+
+## 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.
+- **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.
+- **The heading is composed, not baked.** `ProductShelfRoot` does not own the title; compose `ProductShelfHeading` where it should sit (usually above `CarouselRoot`) with the text as its `children`. It renders an `<h2>` and provides the section's `aria-labelledby` label. Omit it to render no heading.
+
+---
+
+## Props
+
+### ProductShelfRoot
+
+| 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") |
+| `$data` | slice | — | Compiler-injected fragment result |
+| `products` | `ProductShelfItem[]` | — | Pre-shaped items (stories/tests; bypasses `$data`) |
+
+### ProductShelfItems
+
+Repeats the shelf products into the carousel track, publishing one product per slide through the per-item context. Renders `CarouselTrack`, so place it directly inside `CarouselRoot`. Put the card template as its children. No props beyond standard `div` attributes.
+
+### ProductShelfHeading
+
+Renders its `children` as the shelf title — an `<h2>` (`data-fs-product-shelf-heading`) — and supplies the section's `aria-labelledby` label. Author the title text as its `children` (`props.children`), exactly like a `Text` element. Renders nothing when it has no children. Place it inside `ProductShelfRoot` where the title should appear (typically above `CarouselRoot`). No schema props beyond standard `h2` attributes.
+
+---
+
+## Per-item context
+
+`ProductShelfItems` publishes a `ProductShelfItem` per slide (the widened `ProductListItem`), wide enough for every card part:
+
+| Field | Used by |
+|-------|---------|
+| `id`, `slug`, `name`, `image` | T3 image/title |
+| `price`, `listPrice` | T3 selling/list price |
+| `spotPrice` | T4 discount = `round((listPrice − spotPrice) × 100 / listPrice)` |
+| `tax`, `taxPercentage` | T6 tax-inclusive price |
+| `availableForSale`, `availableQuantity` | T5 out-of-stock state |
+| `currency` | price formatting (falls back to the storefront context currency) |
+
+Card parts read it via `useProductShelfItem()` (throws when used outside `ProductShelfItems`). The existing `ProductList.CardImage / CardName / CardPrice / CardListPrice` read the same context, so they compose unchanged.
+
+---
+
+## Composition
+
+```text
+ProductShelfRoot            (owns data + config)
+├── ProductShelfHeading     (title as its children; optional)
+└── CarouselRoot            (itemsPerPage, infiniteMode, variant)
+    ├── ProductShelfItems   (repeats products; renders CarouselTrack)
+    │   └── <card template: ProductCardImage, ProductCardName, ProductCardPrice, ProductCardListPrice, …>
+    ├── CarouselPrevious
+    ├── CarouselNext
+    └── CarouselBullets
+```
+
+---
+
+## Minimal schema example
+
+```json
+{
+  "shelf": {
+    "type": "ProductShelfRoot",
+    "props": { "first": 12, "itemsPerPage": 4, "sort": "relevance", "categoryId": "Category:42" },
+    "children": ["shelf-heading", "shelf-carousel"]
+  },
+  "shelf-heading": { "type": "ProductShelfHeading", "props": { "children": "You may also like" } },
+  "shelf-carousel": {
+    "type": "CarouselRoot",
+    "props": { "itemsPerPage": 4 },
+    "children": ["shelf-items", "shelf-prev", "shelf-next", "shelf-bullets"]
+  },
+  "shelf-items": { "type": "ProductShelfItems", "children": ["card-image", "card-name", "card-price"] },
+  "shelf-prev": { "type": "CarouselPrevious" },
+  "shelf-next": { "type": "CarouselNext" },
+  "shelf-bullets": { "type": "CarouselBullets" }
+}
+```
+
+---
+
+## Styling
+
+All appearance is chosen by swatches keyed off the structural hooks:
+
+- `data-fs-product-shelf` — the shelf section
+- `data-fs-product-shelf-heading` — the heading
+- `data-fs-product-shelf-items` — the items track (also carries `data-fs-carousel-track`)
+- `data-fs-product-shelf-skeleton` / `data-fs-product-shelf-skeleton-item` — the loading skeleton
+
+Card and carousel looks come from their own `data-fs-product-card-*` and `data-fs-carousel-*` hooks.

package/dist/docs/promotion.md

@@ -0,0 +1,109 @@
+# Promotion
+
+**Category:** content
+**Purpose:** Editorial promotional callout — a title, a body paragraph, and an optional image — driven entirely by CMS content. It has no props for its copy: every field arrives through the compiler-injected `$content` prop, backed by the `promotion` content model declared next to the component.
+
+---
+
+## Visual cues (how to identify in an image)
+
+The image is the source of truth for layout. A Promotion block is present when you see:
+
+- An **editorial callout** with a short heading and a supporting sentence — e.g. *"Frete grátis acima de R$ 199"*, *"Compre 3, leve 2"*.
+- Optionally a **banner-style image** above or beside the text.
+- Copy that is **campaign-like and merchant-authored**, not derived from a product offer (no prices, no installments).
+
+---
+
+## When to use
+
+- Editorial campaign callouts on any page — home, PLP, PDP, cart.
+- Any block whose copy is owned by content editors in the CMS rather than by the page schema.
+
+## When NOT to use
+
+- Offer-derived promotion text (e.g. *"Compre 3 leve 2"* coming from the product's offer data) → use `PricingPromotions` + `PricingPromotion`.
+- Discount highlight pills (*"Black Friday"*, *"Exclusivo"*) on a price block → use `PricingHighlights` + `PricingHighlight`.
+- A plain static heading or paragraph authored in the schema → use `Text`.
+
+---
+
+## Composition
+
+`Promotion` is a standalone leaf — no sub-components, no children.
+
+```
+Promotion
+```
+
+It renders a `<section data-fs-promotion>` containing, in order: the optional image (the `Image` particle, layered with `data-fs-promotion-image`), an `<h2 data-fs-text data-fs-text-variant="heading" data-fs-promotion-title>`, and a `<p data-fs-promotion-body>`.
+
+**Content, not props.** The title, body, image, and image alt come from a CMS entry of the `promotion` content type, injected as `$content` by the compiler from the element's content locator. When no content is available the component renders `null` (self-hide) — the page omits only this block. Non-compiler hosts (Storybook, tests) pass a typed `$content` fixture directly.
+
+---
+
+## Components
+
+### Promotion
+
+No schema props.
+
+Content model (`promotion`) fields, edited in the CMS:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `title` | string | yes | The heading |
+| `body` | string | yes | Supporting paragraph |
+| `image` | string (uri) | no | Picked via the media gallery widget |
+| `imageAlt` | string | no | Editorial alt text; empty means decorative (`alt=""`) |
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "promo": {
+    "type": "Promotion",
+    "style": ["flex", "flex-col", "gap-[8px]", "w-full"]
+  }
+}
+```
+
+---
+
+## Common mistakes
+
+- **Passing `title` / `body` / `image` as props.** Promotion has no content props — copy lives in the CMS entry, not in the schema.
+- **Using `Promotion` for offer-derived deals.** Offer promotions come from product data; use `PricingPromotions` + `PricingPromotion`.
+- **Giving `Promotion` children.** It is a leaf; it renders its own image/title/body.
+- **Expecting a placeholder without content.** Without `$content` it renders nothing at all.
+
+---
+
+## Styling
+
+`Promotion` renders one DOM container you style directly; the inner nodes carry `data-fs-promotion-*` attributes (and the title inherits the `Text` identity via `data-fs-text`) for CSS targeting.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `Promotion` | The callout container — stacks image, title, and body | `flex flex-col gap-[8px] p-[16px] rounded-[8px] bg-[#F5F5F5] w-full` |
+
+Styled example:
+
+```json
+{
+  "promo": {
+    "type": "Promotion",
+    "style": ["flex", "flex-col", "gap-[8px]", "p-[16px]", "rounded-[8px]", "bg-[#F5F5F5]", "w-full"]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[pricing]] — `PricingPromotions` / `PricingPromotion` render offer-derived promotion text; Promotion is CMS-authored and product-independent.
+- [[text]] — plain schema-authored typography; the Promotion title layers the `Text` identity so project typography cascades.
+- [[image]] — the particle Promotion uses for its optional image.

package/dist/docs/region.md

@@ -0,0 +1,225 @@
+# Region
+
+**Category:** content
+**Purpose:** The header's region control. `RegionRoot` reads the shopper's active postal code and the city it resolves to, and broadcasts them to its subtree. `RegionTrigger` opens a modal where the shopper types a postal code; `RegionValue` echoes the active one back in the header. The write goes through the `region` action namespace, and the display updates from the cache — never from local state.
+
+---
+
+## Visual cues (how to identify in an image)
+
+Look in the **top bar or utility strip of the header**, usually beside the account and cart controls:
+
+- A **pin or location glyph** followed by either a prompt like "Informe seu CEP" / "Enter your zip code" (no region set) or a **city and postal code** such as "São Paulo, 01310-100" (region set).
+- Tapping it opens a **small centered modal** with one masked input, a submit button, and often a secondary link reading "I don't know my postal code".
+- On a first visit the control reads as a **call to action**; on a return visit it reads as **a value the shopper can correct**. Both are the same component in two states.
+
+A city shown without any postal code is not this component — that is usually a store-locator or a delivery-promise widget.
+
+---
+
+## When to use
+
+- In the **shared header layout**, once per storefront, so the region reads the same on every page.
+- Whenever the design shows a persistent postal code the shopper can edit from the header.
+
+## When NOT to use
+
+- **For the delivery address on checkout** — that is `ShippingAddress`, which captures a full address, not a region.
+- **For a shipping-cost estimate on a product page** — that is `ShippingSimulator`.
+- **As a bare masked input** — that is the `PostalCodeField` particle, which this component composes. Use the particle directly when a host owns the submit.
+- More than once per page: two `RegionRoot` elements mean two modals and two drafts over the same server value.
+
+---
+
+## Composition
+
+`RegionRoot` provides the `'region'` context (ADR-0009): it declares `providesContext: 'region'`, and every other part declares `requiresContext: 'region'`, so the schema compiler's `validateContextConstraints` rejects — before emitting any file — a `RegionValue` with no `RegionRoot` ancestor. `useRegion()` throws at render time for the same mistake off the compiled path.
+
+```
+RegionRoot                            (header layout; provides 'region' context)
+├── RegionLoading                     (renders its skeleton child only while unresolved)
+│   └── <skeleton placeholder>
+├── RegionTrigger                     (opens the modal)
+│   └── RegionValue                   (the active city + postal code, once set)
+└── RegionModalController             (makes the DialogRoot below controlled)
+    └── DialogRoot
+        └── DialogPortal
+            ├── DialogBackdrop
+            └── DialogViewport
+                └── DialogPopup
+                    ├── DialogTitle           (names the dialog)
+                    ├── DialogDescription     (describes it)
+                    ├── RegionForm            (so Enter in the field submits)
+                    │   ├── RegionPostalCodeControl
+                    │   └── RegionSubmit
+                    ├── RegionError
+                    ├── RegionUnknownLink
+                    └── DialogClose
+```
+
+Every part is independently placeable and **self-gates on region state** — none takes a visibility prop. `RegionValue` renders nothing until a region resolves, `RegionLoading` renders only while it has not, `RegionError` renders only after a refused write, and `RegionUnknownLink` renders only once a destination is set.
+
+The `DialogRoot` under `RegionModalController` must **not** carry raw `open` / `onOpenChange`: the controller supplies both, which is what lets the trigger open the modal and a successful write close it.
+
+---
+
+## Components
+
+### RegionRoot
+
+Root region provider. Reads the resolved `Region` slice reactively and broadcasts `{ postalCode, city, loading, draft, setDraft, pending, errors, open, setOpen, submit }` through `useRegion()`. Owns the modal's draft, the in-flight flag, and the latest write's errors. No props.
+
+**Data:** declares `fragment RegionData on Query` (spreads `RegionFragment`: `id`, `postalCode`, `city`) with `fetchStrategy: 'reactive'`. `Query.region` takes no arguments, so the fragment composes into the layout query with no variable to wire.
+
+**Write:** declares `actions: { region: ['setPostalCode'] }`. A successful write updates the display purely by the mutation payload normalizing into the Apollo cache — the root never copies the resolved value into state, so a refused write needs no rollback and can never leave the header showing a postal code the server rejected.
+
+### RegionTrigger
+
+Opens the modal. Shows its unset label while no region is set; compose `RegionValue` as its child so the active region reads inside the control once one is. Not interactive while the region is unresolved.
+
+Its accessible name carries the active region, so a screen reader announces where the shopper is shopping rather than a label that reads the same in every state. An authored `aria-label` **prefixes** the visible text rather than replacing it — `"Alterar região: São Paulo 01310-100"`, and `"Alterar região: Informe seu CEP"` while unset — because WCAG 2.5.3 requires the accessible name to contain the visible label, and a name a voice-control user cannot read off the screen is one they cannot speak. Author the verb alone (`"Alterar região"`); the component appends the state.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `unsetLabel` | string | `"Informe seu CEP"` | Shown while no region is set |
+
+**Content model** (`region-trigger`): `unsetLabel`, `ariaLabel`.
+
+### RegionValue
+
+The active region, as city plus postal code. Renders nothing while the region is unresolved or unset. The city sits in its own element (`data-fs-region-value-city`) so a store can style or hide it; when the contract resolves no city, the postal code renders alone with no separator. No props.
+
+A plain space separates the two values in the text itself, so the reading is `São Paulo 01310-100` — that run is the trigger's accessible name whenever no `aria-label` is authored, and CSS cannot put a separator into an accessible name. A flex container strips it as leading whitespace, so a store's `gap` still governs the visible spacing.
+
+### RegionLoading
+
+Renders its children only while the region read has not resolved. Supply a skeleton placeholder as its child, sized like the resolved display so the header does not reflow when the region arrives. No props.
+
+### RegionModalController
+
+Wraps a single `DialogRoot` child and makes it controlled by the region state: the trigger opens it, Escape and the backdrop close it, and a successful write closes it. A refused write always leaves it open, so the message has somewhere to show. Closing clears the draft and the error. No props.
+
+### RegionForm
+
+Form wrapper holding `RegionPostalCodeControl` and `RegionSubmit`, so pressing **Enter** in the field submits — the same role `ShippingSimulatorForm` plays for the shipping calculator. Compose it whenever both parts sit together. Without it the shopper has to reach the button, which works but is not what a one-field form leads them to expect.
+
+Inside it `RegionSubmit` becomes the form's submit button; on its own it dispatches directly. That is what keeps the form optional instead of load-bearing. Takes all `form` props except `onSubmit`, which it owns.
+
+### RegionPostalCodeControl
+
+The postal-code input inside the modal: a `PostalCodeField` bound to the region draft, seeded from the persisted value **every time the modal opens**, so a reopened modal shows the truth rather than an abandoned edit. Server rejections mark the field invalid; their message is `RegionError`'s to show, not repeated here. The first keystroke after a rejection clears it, which restores this field's own incomplete-value copy.
+
+A refusal also takes focus back to the field, so the shopper lands on the value they have to correct. Without it they land nowhere: the write disables the input, which blurs it, and the document body takes focus — inside an open dialog that means Enter does nothing and Tab restarts from the top.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `mask` | string | `"99999-999"` | Country format, set at build time (default BR CEP) |
+| `label` | string | — | Field label |
+| `placeholder` | string | — | Field placeholder |
+| `errorMessage` | string | — | The field's own incomplete-value message |
+
+### RegionSubmit
+
+Submits the draft. Inert while the draft is empty and while a write is in flight, so a double activation dispatches exactly one mutation. The pending state is exposed as `aria-busy` with no built-in spinner. The value is passed to the server exactly as the shopper typed it, mask included — the server is authoritative on format.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `label` | string | `"Aplicar"` | Button label |
+| `pendingLabel` | string | `"Aplicando..."` | Shown while the write is in flight |
+
+**Content model** (`region-submit`): `label`, `pendingLabel`.
+
+### RegionError
+
+Shows why the latest write was refused, announced as an alert when it appears. Renders nothing when there is no error. A rejection the server codes (`INVALID_POSTAL_CODE`, `UNSERVED_POSTAL_CODE`) and a transport failure (`NETWORK_ERROR`) render the message catalog's copy in the store's language; the server's own English message is shown only for a code the catalog does not know. The authored generic message covers a transport failure, where there is no server message to show, and wins over the catalog there. No props.
+
+**Content model** (`region-error`): `genericMessage`.
+
+### RegionUnknownLink
+
+The "I don't know my postal code" escape hatch, pointing at a postal-code lookup service. Renders nothing until a destination is set, so a store without one composes it and simply gets no link rather than a dead one. The destination passes the same allowlist the link particles use, so a `javascript:` value is refused rather than rendered.
+
+A lookup service is a natural new-tab destination, so a store may compose this with `target="_blank"`; the component then adds `noopener` and `noreferrer` to `rel` itself, the same contract `NavigationLink` states. Do not pass `rel` for that reason.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `href` | string | — | Lookup service URL; authored content wins over it |
+| `target` | `"_self"` \| `"_blank"` | `"_self"` | `_blank` adds the tab-nabbing defense |
+
+Link text comes from authored content, else from `children`.
+
+**Content model** (`region-unknown-link`): `text`, `href`.
+
+---
+
+## Canonical schema example
+
+Header region control with the full modal:
+
+```json
+{
+  "region": { "type": "RegionRoot", "children": ["region-trigger", "region-modal"] },
+  "region-trigger": { "type": "RegionTrigger", "children": ["region-value"] },
+  "region-value": { "type": "RegionValue" },
+  "region-modal": { "type": "RegionModalController", "children": ["region-dialog"] },
+  "region-dialog": { "type": "DialogRoot", "children": ["region-portal"] },
+  "region-portal": { "type": "DialogPortal", "children": ["region-backdrop", "region-viewport"] },
+  "region-backdrop": { "type": "DialogBackdrop" },
+  "region-viewport": { "type": "DialogViewport", "children": ["region-popup"] },
+  "region-popup": {
+    "type": "DialogPopup",
+    "children": ["region-title", "region-form", "region-error", "region-unknown"]
+  },
+  "region-title": { "type": "DialogTitle", "props": { "children": "Escolha sua região" } },
+  "region-form": { "type": "RegionForm", "children": ["region-input", "region-submit"] },
+  "region-input": { "type": "RegionPostalCodeControl", "props": { "label": "CEP" } },
+  "region-submit": { "type": "RegionSubmit" },
+  "region-error": { "type": "RegionError" },
+  "region-unknown": { "type": "RegionUnknownLink" }
+}
+```
+
+---
+
+## Styling hooks
+
+| Attribute | On | Present when |
+|---|---|---|
+| `data-fs-region-root` | `RegionRoot` | Always |
+| `data-fs-region-trigger` | `RegionTrigger` | Always |
+| `data-fs-region-trigger-unset` | `RegionTrigger` | No region is set |
+| `data-fs-region-value` | `RegionValue` | A region is set |
+| `data-fs-region-value-city` | The city element | The contract resolved a city |
+| `data-fs-region-loading` | `RegionLoading` | The region is unresolved |
+| `data-fs-region-form` | `RegionForm` | Always |
+| `data-fs-region-postal-code-control` | `RegionPostalCodeControl` | Always |
+| `data-fs-region-submit` | `RegionSubmit` | Always |
+| `data-fs-region-submit-pending` | `RegionSubmit` | A write is in flight |
+| `data-fs-region-error` | `RegionError` | The latest write was refused |
+| `data-fs-region-unknown-link` | `RegionUnknownLink` | A destination is authored |
+
+No part ships visual CSS of its own; the visible spacing between city and postal code, the modal's box, and the skeleton's shape are all swatch decisions.
+
+---
+
+## Common mistakes
+
+- **Inventing `Region` (without `Root`).** The provider is `RegionRoot`.
+- **Setting `open` or `onOpenChange` on the `DialogRoot` inside `RegionModalController`.** The controller owns both; a raw value fights it and the modal stops responding to the trigger.
+- **Placing `RegionPostalCodeControl`, `RegionSubmit`, or `RegionError` outside the dialog.** They render fine but the shopper meets a postal-code form sitting in the header.
+- **Omitting `RegionForm`.** The parts still work and the button is still keyboard-reachable, but Enter in the field does nothing — the one thing a shopper typing a postal code expects.
+- **Authoring the state into `RegionTrigger`'s `aria-label`** (`"Alterar região: São Paulo"`). The component appends the state; author only the verb, or the name repeats itself.
+- **Looking for a `showCity` or `hideWhenEmpty` prop.** There is none: `RegionValue` self-gates on region state, and a store that shows only the postal code styles the city element away.
+- **Expecting `RegionValue` to show the value the shopper just typed.** It shows what the server confirmed. The draft is the field's, and it is discarded when the modal closes.
+- **Stripping the mask before submitting.** Pass the value through; the server normalizes it and echoes back a formatted one.
+- **Authoring link text but no destination on `RegionUnknownLink`.** Without a destination the link is omitted entirely.
+- **Passing a static `errorMessage` to `RegionPostalCodeControl` and expecting it on a refused write.** That copy describes an incomplete value and is withheld while a server rejection stands, so `RegionError` carries the reason alone.
+- **Using two `RegionRoot` elements.** One per storefront, in the shared header layout.
+
+---
+
+## Related
+
+- [[../../particles/postal-code-field/postal-code-field]] — the masked input this component composes; use it directly when a host owns the submit.
+- [[shipping-address]] — the full delivery address on checkout, and the closest structural sibling (reactive root, draft-bearing context, overlay controller, submit through `$actions`).
+- [[session]] — the other read-oriented header-adjacent provider; same ADR-0009 provider/consumer contract and the same Symbol-guarded hook shape.

package/dist/docs/session.md

@@ -0,0 +1,123 @@
+# Session
+
+**Category:** identity
+**Purpose:** Read-only identity-state provider, normally hosted by the shared layout. `SessionRoot` reads the shopper's `Session`, derives the **anonymous / identified / logged-in** tri-state, and broadcasts it (plus the raw `loggedIn` and `canEditData` flags) to its subtree. `SessionGuard` is a declarative gate that shows or hides a subtree by that state. It carries session state only — profile fields (name, email, document, phone) live on other components and are read separately.
+
+---
+
+## Visual cues (how to identify in an image)
+
+`SessionRoot` is a data provider, not a visible widget — you do not see it directly. The image is the source of truth for layout. What signals a session-aware page is content that **changes by identity state**:
+
+- A **"welcome back" / identified-shopper** greeting versus a generic **login prompt** for anonymous visitors.
+- An identity step that shows **editable fields** for a logged-in shopper but **masked / read-only** values for an identified guest (this maps to `canEditData`).
+- A subtree that is **only shown once the shopper is identified or logged in** (e.g. saved addresses, order history entry points).
+
+When the image shows identity-conditional content — on the identity step or in the header — that tree is hosted under a `SessionRoot`, and the conditional subtrees are gated with `SessionGuard`.
+
+---
+
+## When to use
+
+- As the **root of the shared layout**, wrapping the header subtree and the `Slot`, when identity state is read shell-wide — an account entry point in the header, identity-conditional content on any page. This is the default: like `CartRoot`, `SessionRoot` is shell-wide.
+- As the **page root**, only when exactly one page reads session state and no layout element does.
+- Wrap any subtree that should appear only in certain states in a `SessionGuard` inside that `SessionRoot`.
+
+Exactly one `SessionRoot` per rendered tree. A layout-hosted provider already covers every page it serves, so those pages must not add their own.
+
+## When NOT to use
+
+- **On a page whose layout already hosts one** — the nested provider makes the inner root re-fetch and shadow the outer context. Delete the page-level element instead.
+- **For profile field values** (name, email, document, phone) — those are separate components, not derived from session state.
+- As a generic layout wrapper — that is `Container`.
+
+## Layout hosting and the server-side fetch
+
+Hosting `SessionRoot` in a layout is safe, and safer than page hosting. The two scopes fetch differently:
+
+- **Layout scope** emits `LAYOUT_QUERY` inside a client component with no SSR seed — no `serverVariables`, no `initialData`. The read happens in the browser, where the shopper's cookie is present.
+- **Page scope** emits a server-side `fetchPageData` and seeds the reactive root with `initialData`. That server fetch carries no user cookie, so the seed is an anonymous session — and the root then reads `cache-first` against the cache it just seeded, so that anonymous session is what the page keeps. It does not correct itself.
+
+So the cookie hazard belongs to page hosting, not layout hosting. Cost is per layout, not per element: `LAYOUT_QUERY` is composed from the component types used in the layout, with no notion of tree position, so the provider's depth does not change what is fetched.
+
+---
+
+## Composition
+
+`SessionRoot` provides the `'session'` context (ADR-0009): it declares `providesContext: 'session'`, and downstream session consumers declare `requiresContext: 'session'`, so the schema compiler's `validateContextConstraints` rejects — before emitting any file — any session consumer that has no `SessionRoot` ancestor. The ancestor may live in the page or in the layout that hosts it: the compiler composes the layout's provider set with the page's before validating, so a layout-hosted `SessionRoot` satisfies consumers on every page it serves. `SessionGuard` reads that context via `useSession()` and throws at render time if placed outside a `SessionRoot`.
+
+```
+SessionRoot                       (layout or page root; provides 'session' context)
+├── SessionGuard (when=[...])     (renders children only in the listed states)
+│   └── <identity subtree>
+└── <identity components>         (read session state directly)
+```
+
+`SessionGuard` elements are siblings/children inside the `SessionRoot` `children` array; child order reflects visual order. A `SessionGuard` renders its children only when the current state is one of its `when` values and renders nothing otherwise (including when `when` is omitted).
+
+---
+
+## Components
+
+### SessionRoot
+
+Root identity-state provider. Reads the resolved `Session` slice reactively and broadcasts a memoized `{ state, loggedIn, canEditData, loading }` to descendants via `useSession()`. Derives `state` from the raw flags: `loggedIn` wins, else `isIdentified` → `identified`, else `anonymous`. While the entity is unresolved it broadcasts `loading: true` and `state: 'anonymous'` (the least-privileged default). No props.
+
+**Data:** declares `fragment SessionData on Query` (spreads `SessionFragment`: `id`, `loggedIn`, `canEditData`, `isIdentified`) with `fetchStrategy: 'reactive'` — cache writes (e.g. a post-login refresh) re-render descendants without a refetch. The compiler injects the resolved slice; no explicit data wiring needed.
+
+### SessionGuard
+
+Declarative state gate. Renders its children only when the current session state is one of the values in `when`; renders nothing for any other state, and nothing when `when` is omitted. Must be inside `SessionRoot`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `when` | array of `"anonymous"` \| `"identified"` \| `"loggedIn"` | — | The states under which the children render (e.g. `["identified", "loggedIn"]`) |
+
+**A guard shows the anonymous branch until the layout read resolves.** `SessionGuard` gates on `state` alone, and `state` is `anonymous` while `loading` is true — so under a layout-hosted provider, whose read is client-only with no SSR seed, every page load starts with the anonymous branch and swaps once the session arrives. Reveal-once-identified subtrees are fine with that; a control whose wrong state actively misleads the shopper is not, and belongs in a component that reads `loading` itself rather than behind a guard.
+
+---
+
+## Canonical schema example
+
+Shared layout with `SessionRoot` as the root, above both the header and the `Slot`, and a `SessionGuard` revealing an order-history entry point once the shopper is identified:
+
+```json
+{
+  "name": "default",
+  "root": "layout-session",
+  "elements": {
+    "layout-session": { "type": "SessionRoot", "children": ["layout-root"] },
+    "layout-root": { "type": "Container", "children": ["header", "slot"] },
+    "header": { "type": "Container", "children": ["orders-block"] },
+    "orders-block": {
+      "type": "SessionGuard",
+      "props": { "when": ["identified", "loggedIn"] },
+      "children": ["orders-link"]
+    },
+    "orders-link": { "type": "NavigationLink", "props": { "href": "/orders", "children": "Meus pedidos" } },
+    "slot": { "type": "Slot", "props": {}, "children": [] }
+  }
+}
+```
+
+Pages served by this layout add no `SessionRoot` of their own; their session consumers resolve the layout's. Note that `SessionRoot` carries no `style` — it is not a box, so visual framing belongs on the `Container` beneath it.
+
+---
+
+## Common mistakes
+
+- **Inventing `Session` (without `Root`).** The provider is `SessionRoot`.
+- **Avoiding the shared layout out of a cookie concern.** Layout scope is client-only and has the cookie; it is page scope that fetches server-side without one.
+- **Keeping a page-level `SessionRoot` when the layout already hosts one.** That nests two reactive roots — the inner one re-fetches and shadows the outer context.
+- **Placing `SessionRoot` beside the `Slot` instead of above it.** A sibling provider still serves the consumers in its own branch, so the header keeps working while every consumer under the `Slot` fails; it must be an ancestor of both the header subtree and the `Slot`.
+- **Placing `SessionGuard` outside a `SessionRoot`.** It reads `useSession()` and throws at render time; the schema compiler also rejects it for missing the `'session'` context ancestor.
+- **Omitting `when` and expecting children to show.** With no `when`, `SessionGuard` renders nothing — pass the states that should render.
+- **Gating the header's account entry point with a pair of guards.** That is `AccountEntryPoint`, which reads the session itself and renders a resolving state; guards would hide that state and flash the wrong label. See [[account-entry-point]].
+- **Reading profile fields (name, email, document, phone) from `SessionRoot`.** It broadcasts session state only; profile values come from separate identity components.
+
+---
+
+## Related
+
+- [[cart]] — the other reactive data provider, hosted in the shared layout the same way and for the same reason.
+- [[product-information]] — another context provider (`providesContext: 'product-information'`); same ADR-0009 provider/consumer contract, different domain.