@vtex/faststore 0.0.1

package/dist/docs/identity-edit.md

@@ -0,0 +1,88 @@
+# IdentityEdit
+
+The identity section's summary/form toggle. `IdentityEditController` shows who the shopper is until they
+ask to change it, and returns to the summary when they press cancel. `IdentitySummaryView` holds the
+summary side of the swap and `IdentityEditForm` the form side; `IdentityEditButton` opens the form and
+`IdentityEditCancelButton` returns to the summary.
+
+The sibling of the delivery section's `ShippingAddressEditController`, and deliberately its own component
+rather than a shared mechanism: the two differ in exactly the parts that are domain knowledge. This one
+starts on the summary and needs an explicit cancel; that one derives its starting state from whether an
+address exists and closes itself with no cancel at all.
+
+The mode is owned here, not authored in a page (ADR-0006). `ClientProfileForm` announces nothing and never
+learns whether anything collapses around it, which is what lets the same form sit in a section, in a wizard
+step, or on a page of its own.
+
+## Why no mode name reaches the schema
+
+Which state a part gates is which component it is, so no part takes a mode prop. A page cannot misspell a
+mode, because there is nothing to spell: `page.json` names a component, and an unknown component name is a
+resolution error rather than a silently dead branch that blanks the section.
+
+## Parts
+
+| Part | Role |
+|---|---|
+| `IdentityEditController` | Owns the mode. Moves only on this section's own buttons. Renders no DOM. |
+| `IdentitySummaryView` | Renders children while the section shows the summary. |
+| `IdentityEditForm` | Renders children while the section shows the form. |
+| `IdentityEditButton` | Opens the form. Carries `data-fs-identity-edit-button`. |
+| `IdentityEditCancelButton` | Returns to the summary without saving. Carries `data-fs-identity-edit-cancel-button`. |
+
+## Props
+
+### IdentitySummaryView / IdentityEditForm
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `children` | ReactNode | — | Rendered only while the section is in this component's state. Nothing else: the state is the component. |
+
+### IdentityEditButton / IdentityEditCancelButton
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `label` | string | `'editar'` / `'cancelar'` | Text shown when no children are composed. |
+| `children` | ReactNode | — | Custom content, e.g. an `Icon` plus text; falls back to `label`. |
+| `className` | string | — | |
+
+## Behavior
+
+- Starts on the summary. Unlike the delivery section, nothing about the profile data decides this: the
+  summary is always the right first thing to show a shopper who has one.
+- The mode moves only on this section's own buttons, `EditButton` and `CancelButton`. Saving the form does
+  not close the section, which is what keeps `ClientProfileForm`'s confirmation on screen long enough to
+  read.
+- **Self-contained.** It observes nothing outside itself and reports nothing: no other section opens or
+  closes as a result of anything happening here. Whether finishing a form should collapse the section that
+  holds it is a sequencing question, deliberately left to the flow-of-steps RFC (#611) rather than
+  answered here.
+
+## Composition
+
+```
+IdentityEditController
+├─ heading
+│  ├─ IdentitySummaryView   → the "identified" badge
+│  ├─ IdentityEditForm      → the "editing" badge
+│  └─ IdentitySummaryView   → IdentityEditButton
+└─ IdentitySummaryRoot
+   ├─ IdentitySummaryView   → IdentitySummarySelectedSummary
+   └─ IdentityEditForm      → ClientProfileFormRoot + IdentityEditCancelButton
+```
+
+## Accessibility
+
+Switching modes moves no focus and announces nothing, and because each button sits inside the branch that
+unmounts, focus falls to the document body on every switch. There is no `aria-expanded`/`aria-controls`
+pair. No issue tracks this yet.
+
+## Known gaps
+
+Found by review and deliberately left for the dedicated revision of these components.
+
+- **The mode survives a sign-out.** The controller is never remounted when the session goes anonymous, so a
+  shopper who opens the form and then signs out leaves it in `edit`. Any part composed above
+  `IdentitySummaryRoot` — a heading badge, for instance — keeps its editing appearance over the anonymous
+  panel, and once the shopper identifies again the section opens straight onto the form, contradicting
+  "starts on the summary" above.

package/dist/docs/identity-summary.md

@@ -0,0 +1,106 @@
+# IdentitySummary
+
+Compound for the read-only identity section of an identified or logged-in shopper. The `Root`
+self-gates: it renders nothing in the anonymous state (via `useSession()`). The summary/form swap is
+owned by `IdentityEditController`, composed around these parts — this matter owns only the identity
+data and the sign-out action.
+
+## Anatomy
+
+```
+IdentityEditController                           // owns the summary/form swap; starts on the summary
+  ├─ heading
+  │    ├─ IdentitySummaryView  → the "identified" badge
+  │    ├─ IdentityEditForm     → the "editing" badge
+  │    └─ IdentitySummaryView  → IdentityEditButton   // → the form (compose an Icon + text as children)
+  └─ IdentitySummary.Root                        // data root: profile + sign-out, self-gates on session
+       ├─ IdentitySummaryView
+       │    ├─ IdentitySummary.SelectedSummary   // badge + name/email/phone/document (read-only)
+       │    ├─ IdentitySummary.SignOutButton     // dispatches session.logout
+       │    └─ IdentitySummary.Error             // inline sign-out error
+       └─ IdentityEditForm
+            ├─ ClientProfileForm                 // the edit surface (composed directly)
+            └─ IdentityEditCancelButton          // Cancel → back to the summary
+```
+
+The controller sits **outside** `IdentitySummary.Root`, not inside it. The Root self-gates to `null` in the
+anonymous state, so anything that must survive that state — the section heading, its badge, the sign-in path
+— has to be composed above the Root rather than within it. `identity-edit.md` and
+`examples/store-americanas/pages/checkout/page.json` use this same nesting.
+
+## What it shows
+
+- **SelectedSummary** — a session-state badge (`identified` → guest label; `loggedIn` → signed-in
+  label), plus full name, email, phone, and document. Each line is omitted when the value is absent.
+  The stored phone is E.164; the phone leaf's `country` (US/BR) selects the display mask, so the summary
+  matches the edit form's masking, and a number belonging to another country renders as stored rather
+  than being reformatted as a local one. Compose custom `children` to replace the default presentation —
+  the leaves then carry their own props. `SelectedSummary`'s own `country` and badge-label props apply to
+  the default composition only, and are not offered in the schema for that reason.
+- **SignOutButton** — async/pessimistic: `data-fs-identity-summary-pending` is present while the
+  mutation is in flight, the button is disabled to prevent double-dispatch, and any returned
+  `userErrors` surface via `Error`. Renders composed `children` (e.g. an `Icon` + text) or `label`.
+- **Summary/form swap** — `IdentityEditController` with its guards and triggers. The edit and cancel
+  buttons are `IdentityEditButton` and `IdentityEditCancelButton`; a leading icon composes as their children.
+  The controller moves only on those buttons — saving does not collapse the section — so neither this
+  compound nor `ClientProfileForm` learns anything about a section around it (ADR-0006).
+
+## The summary is composed, not fixed
+
+`IdentitySummarySelectedSummary` is a **shortcut**: it renders the default order (badge, name, e-mail,
+phone, document) so a page wanting exactly that composes one element. It is not the only way, and it
+offers no props to the schema — configure the leaf, not the wrapper. Its `country` and badge-label props
+reach the default composition only, so composing children silently replaces whatever they would have set.
+
+Each line is its own component reading the same `IdentitySummaryRoot` context, so the order, the presence
+and anything interleaved between them are the page's decision (ADR-0011):
+
+| Leaf | Renders | Nothing when |
+|---|---|---|
+| `IdentitySummaryBadge` | the session-state badge | never |
+| `IdentitySummaryName` | first + last name | the profile carries neither |
+| `IdentitySummaryEmail` | the e-mail | absent |
+| `IdentitySummaryPhone` | the phone, masked when the stored value belongs to `country` | absent |
+| `IdentitySummaryDocument` | the tax document | absent |
+
+```
+IdentitySummaryRoot
+├─ IdentitySummaryName          // e-mail after the name, before it, or omitted:
+├─ IdentitySummaryEmail         // that is composition, and no prop expresses it
+└─ IdentitySummaryPhone country="BR"
+```
+
+## Data attributes
+
+| Attribute | Element | When |
+|---|---|---|
+| `data-fs-identity-summary` | Root `<div>` | always (when not anonymous) |
+| `data-fs-identity-summary-pending` | Root `<div>` and sign-out `<button>` | while logout is in flight |
+| `data-fs-identity-summary-summary` | SelectedSummary `<div>` | always |
+| `data-fs-identity-summary-badge` | `<Badge>` | wherever `IdentitySummaryBadge` is composed |
+| `data-fs-identity-summary-state` | `<Badge>` | `identified` or `loggedIn` |
+| `data-fs-identity-summary-name` | `<p>` | when name is present |
+| `data-fs-identity-summary-email` | `<p>` | when email is present |
+| `data-fs-identity-summary-phone` | `<p>` | when phone is present (masked only for its own country) |
+| `data-fs-identity-summary-document` | `<p>` | when document is present |
+| `data-fs-identity-summary-sign-out` | `<button>` | on the summary |
+| `data-fs-identity-summary-error` | `<div role="alert">` | when logout returns user errors |
+| `data-fs-identity-edit-button`, `data-fs-identity-edit-cancel-button` | edit / cancel `<button>` | provided by `IdentityEditButton` and `IdentityEditCancelButton` |
+
+## Requirements
+
+- `Root` must be a descendant of `SessionRoot` (declares `requiresContext: 'session'`), and provides
+  `identity-summary`. `SelectedSummary`, `Badge`, `Name`, `Email`, `Phone`, `Document`, `SignOutButton`
+  and `Error` all require it — the compiler enforces the ancestor. The `IdentityEditController` and its
+  guards/triggers require only each other.
+- Fragment ownership: `Root` reads only `clientProfile` (email, firstName, lastName, phone, document).
+  The edit surface is a separately-composed `ClientProfileForm`, which owns its own fragment and the
+  `identity.clientProfileUpdate` / `clientPreferencesUpdate` actions.
+- Actions: `Root` declares only `session.logout`.
+
+## Do not
+
+- Do not place two `ClientProfileForm`s for the same fields; the edit guard hosts the single one.
+- Do not use this compound for an anonymous shopper; the Root renders nothing and has no anonymous fallback.
+- Do not expect the section to close after a save — nothing here does that. Where a finished section
+  leads is left to the flow-of-steps RFC (#611).

package/dist/docs/incentives.md

@@ -0,0 +1,151 @@
+# Incentives
+
+**Category:** content
+**Purpose:** The store's value propositions — free shipping, easy returns, secure checkout — rendered as a strip of items that each pair an icon with a title and up to two short lines of copy. An item may also carry a destination, which makes its whole block a link and lets the same component render a footer shortcut row. The content arrives through the compiler-injected `$content` prop, backed by the `incentives` content model declared next to the component; the `items` prop is the authored fallback for stores with no CMS binding. One element renders the whole strip.
+
+---
+
+## Visual cues (how to identify in an image)
+
+The image is the source of truth for layout. An Incentives strip is present when you see:
+
+- A **row of repeated blocks** — usually three to five, though nothing caps the count — each one an icon above or beside a **bold short title**, over zero, one, or two lighter lines of copy. A row of title-only blocks matches; the lines are supplementary.
+- The copy is a **short label per block**, either a benefit (*Frete grátis*, *Compra segura*) or a destination (*Como comprar*, *Manuais*). Both are this component: an item's `href` is optional, so the same strip renders a reassurance band and a shortcut row.
+- The icons are **line-art pictograms** (a truck, a shield, a gift box), not brand marks. A row of Visa/Mastercard logos is `PaymentMethods`; circular monochrome social glyphs are the social particle.
+- **An unfamiliar pictogram does not rule this out.** Only five names are predefined — `truck`, `calendar`, `gift`, `store`, `shield-check` — and every other glyph arrives as an uploaded `iconUrl`. Uploads are a first-class channel the PRD requires, not a fallback, so a strip where four of five icons are custom is still `Incentives`.
+- Usually a full-width band, often with a rule above or below it, near the top of the footer or directly under the header.
+- On a narrow screen the blocks **wrap or scroll** rather than shrinking their copy.
+
+---
+
+## When to use
+
+- The benefit or reassurance band in a footer, or the equivalent strip under a header.
+- One instance per strip. Every block in the row is one item of this component's content, not its own element.
+
+## When NOT to use
+
+- A row of **payment brand flags** (Visa, Pix, Boleto) → use `PaymentMethods`; those items are bare brand marks with no copy beneath them.
+- A row of **social network icons** → use the social particle; different content model and different glyph set.
+- **Institutional link columns** (*Sobre nós*, *Trabalhe conosco*) → use `FooterLinkGroup`. Both components can link, so the split is the shape: text links under a heading, collapsing to an accordion on mobile, is `FooterLinkGroup`; a glyph above each label with no heading is this. `FooterLinkGroup` renders no per-item icon, so an icon-and-label row belongs here even when every label is a destination.
+- A **single promotional message or banner** → use `Promotion`; one message, not a repeated set.
+- A **product's shipping estimate or a cart's free-shipping progress bar** → those read commerce data for one shopper. This strip is store-level configuration.
+
+---
+
+## Composition
+
+`Incentives` is a leaf in the schema — it has no sub-components and takes no children. The items come from content, not from child elements.
+
+```
+FooterRoot
+├─ Incentives           ← the benefit strip
+├─ FooterLinkGroup      ← "Ajuda"        (siblings; order is visual order)
+├─ FooterLinkGroup      ← "Institucional"
+├─ PaymentMethods
+└─ FooterCopyright
+```
+
+**Content, then prop, whole list.** The list resolves from the CMS entry first and the `items` prop second. It is replaced whole rather than merged — an entry supplying an empty list wins over an authored list, because a merchant who cleared the items cleared them, and index alignment would be meaningless once they reorder. When no item survives the filter below, the component renders `null` (self-hide) and the footer omits the strip. Non-compiler hosts (Storybook, tests) pass a typed `$content` fixture directly.
+
+**`items` is optional in the model, so a half-filled entry still renders.** Only `title` is required per item, which keeps the blast radius of one under-filled item as small as possible: a nested required property is validated at read time and a violation omits the *whole strip*, not the one item. An item may legally carry a title alone.
+
+**What the component drops is per item, never the whole strip.** An item is skipped when its title is blank — an icon with no label is not an incentive. A blank or absent description line costs only that line, because the title is the item's identity and a line is supplementary.
+
+**A refused destination costs the anchor and nothing else.** No read-time gate enforces the model's `pattern`, so an authored `javascript:` value reaches the component intact; the same render-time allowlist `FooterLinkGroup` and the social particle use — `http:`, `https:`, `mailto:`, `tel:`, and single-slash paths — is what stands between it and an `href`. Where those two drop the entry, this one renders the item unlinked with its glyph and copy intact, because an unlinked item is this component's ordinary shape and losing a benefit over a bad destination would be the larger failure. The refusal logs the item's index and the reason, never the authored value.
+
+**Every predefined name must be registered.** An `icon` resolves to a sprite symbol the store's build has to include; the store's `global.json` writes the names out under `icons.include` — it is JSON, so it cannot import `INCENTIVE_ICON_NAMES`, and a test that derives the expected set from the exported constant is what keeps the two in step. A name the store never registered renders an empty `<svg>` — no build error and no runtime error, just a missing pictogram. All five names resolve in the default collection; a store on a different collection maps them with `icons.aliases`.
+
+---
+
+## Components
+
+### Incentives
+
+| Prop | Type | Required | Notes |
+|-------|------|----------|-------|
+| `items` | array | no | Authored fallback list of `{ title, firstLineText?, secondLineText?, href?, icon?, iconUrl?, alt? }`. Ignored when a CMS entry supplies `items` |
+
+Content model (`incentives`) fields, edited in the CMS:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `items` | array | no | Ordered benefit blocks. Adding, removing, and reordering here changes the strip with no deployment. Optional so an entry without it falls back to the authored list. Declares `minItems: 1` and no ceiling — Admin-form guidance only, unenforced on the read path, so an empty list still reaches the component and self-hides there |
+| `items[].title` | string | yes | The benefit's short bold label. The only required field per item; a blank one drops that item |
+| `items[].firstLineText` | string | no | The first line of supporting copy. Optional, so a title-only item is legal; a blank one renders no line |
+| `items[].secondLineText` | string | no | The second line. Absent or blank renders no element, so an item shows zero, one, or two lines |
+| `items[].href` | string | no | The block's destination. Optional, because a benefit strip links nowhere and a shortcut row links everywhere. Wraps the whole block — glyph included — in a same-tab link. Absent or blank renders the item unlinked; a value the render-time allowlist refuses also renders it unlinked, keeping the glyph and copy |
+| `items[].icon` | enum | no | One of `truck`, `calendar`, `gift`, `store`, `shield-check`. Renders the collection glyph, decorative |
+| `items[].iconUrl` | string | no | An uploaded image, for a benefit the predefined set has no glyph for. Wins over `icon` when both are set |
+| `items[].alt` | string | no | Alt text for an uploaded image. Defaults to empty, keeping the image decorative — the visible title beside it is already the item's accessible content, so repeating it would announce the same words twice |
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "footer-incentives": {
+    "type": "Incentives",
+    "style": ["flex", "flex-wrap", "gap-[32px]", "list-none", "p-0", "m-0"]
+  }
+}
+```
+
+The element id is the content key, so name it for the section rather than its styling. Renaming it orphans the merchant's entry: the items stay in the Content Platform while the component reads a key nobody writes.
+
+---
+
+## Common mistakes
+
+- **`IncentivesStrip`, `Benefits`, `BenefitsBar`, `ValueProps`, `USPBar`.** The correct name is `Incentives`.
+- **One element per benefit.** One element renders the whole strip; each block is an item in its content.
+- **Giving it children.** It is a leaf; the blocks are content, which is what makes adding one a CMS save instead of a deployment.
+- **Expecting a `variant` or `colored` prop.** Legacy carried `horizontal`/`vertical` and `colored` as props; both are the swatch's job now. Nothing about this component's appearance travels through a prop.
+- **Expecting a fixed three-slot grid.** Legacy hardcoded three. The count is content here, so style the strip to lay out at whatever count the merchant configures — the model declares no ceiling, and no read-time gate would enforce one if it did.
+- **Passing it over because the strip's pictograms are not in the enum.** The five predefined names are carried over from legacy verbatim, not a vocabulary chosen to cover every strip, so most real strips need at least one upload. Reaching for `Container` + `Icon` + `Text` instead trades one CMS-editable element for three schema elements per block.
+- **Setting `iconUrl` and `icon` and expecting the glyph.** The upload wins; drop `iconUrl` to get the collection glyph back.
+- **Copying the title into `alt`.** The title is already visible beside the image; a screen reader would announce it twice. Leave `alt` empty unless the image says something the title does not.
+- **Shipping without the layout swatch.** The strip ships unstyled, so without one the items stack vertically with list markers and the glyphs sit at 24×24.
+
+---
+
+## Styling
+
+`Incentives` renders one root you style directly, plus per-part hooks. The glyph hook covers both the `<svg>` and the `<img>` path, which is what makes a mixed strip line up.
+
+Size and box classes reach both paths, but **colour does not**. A predefined glyph is an inline `<svg>` that inherits `currentColor`, while an upload is an `<img>` rendering an external document that cannot see the page's colour at all. So in a strip mixing the two, a `text-*` class on the glyph hook tints only the sprite icons and the uploads stay whatever colour their file declares — bake the colour into the uploaded SVG rather than trying to style it from here.
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `Incentives` | The strip itself, wrapping on narrow screens | `flex flex-wrap gap-[32px] list-none p-0 m-0` |
+| `data-fs-incentive` | The block one benefit occupies | `flex flex-col items-center text-center gap-[4px] flex-1` |
+| `data-fs-incentive-link` | The anchor wrapping a linked block; absent on unlinked items, so style the layout on `data-fs-incentive` and only the link affordances here | `flex flex-col items-center gap-[4px] no-underline hover:text-brand` |
+| `data-fs-incentive-icon` | Both glyph paths, sized to match | `w-[32px] h-[32px] object-contain` |
+| `data-fs-incentive-title` | The bold benefit label | `text-[14px] font-bold text-[#1a1a1a]` |
+| `data-fs-incentive-description` | Each supporting line | `text-[12px] text-[#616161]` |
+
+The root carries an explicit `role="list"`. Keep it: WebKit drops the implicit list role from a `<ul>` whose computed `list-style` is `none`, and `list-none` is exactly what the strip needs, so the attribute is what holds the semantics the list was chosen for.
+
+Styled example:
+
+```json
+{
+  "footer-incentives": {
+    "type": "Incentives",
+    "style": ["flex", "flex-wrap", "gap-[32px]", "list-none", "p-0", "m-0"]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[footer-root]] — the `<footer>` landmark the strip usually sits inside.
+- [[payment-methods]] — the brand flag strip below it; same `$content` mechanics, bare marks instead of icon-and-copy blocks.
+- [[footer-link-group]] — the headed link columns beside it; same `$content` mechanics, text links instead of glyphs.
+- [[footer-copyright]] — the legal line below it; same `$content` mechanics, plain text.
+- [[promotion]] — a single CMS-driven message, where this renders a repeated set.
+- `Icon` — the particle each predefined benefit renders. It carries no `.md` of its own; read its schema from `catalog.json`.
+- `Image` — the particle an uploaded icon renders. It carries no `.md` of its own; read its schema from `catalog.json`.

package/dist/docs/logo.md

@@ -0,0 +1,135 @@
+# Logo
+
+**Category:** content
+**Purpose:** Brand logo image that links to the configured home destination.
+
+---
+
+## Visual cues (how to identify in an image)
+
+- A brand mark or wordmark image, usually the store's name or symbol.
+- Rendered as a single clickable image; clicking it navigates home.
+- Typically small and sized to fit a header row.
+
+The image is the source of truth for layout.
+
+## When to use
+
+- To display the store's brand logo as a link back to the configured home.
+
+## When NOT to use
+
+- For a generic, non-branded, or non-linking image → use [[image]].
+- For a text-only site title with no asset → use [[text]] inside a [[navigation-link]].
+
+---
+
+## Composition
+
+`Logo` is a leaf element in the PageSchema — it owns its internal composition (a navigation link wrapping an image) and takes no children.
+
+```text
+Logo
+```
+
+## Components
+
+### Logo
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `src` | string | — | Brand logo asset URL. Optional, so an element can be authored from the CMS alone. |
+| `alt` | string | — | Accessible alt text for the logo image. Optional for the same reason. |
+| `href` | string | `/` | Navigation destination (configured home). |
+| `loading` | `'lazy' \| 'eager'` | `'eager'` | Set `lazy` below the fold; the default suits the header. |
+
+Content model (`logo`) fields, edited in the CMS:
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `src` | string | no | Picked via the media gallery widget. Cleared or absent keeps the authored `src` |
+| `alt` | string | yes | Accessible alt text |
+| `href` | string | no | Cleared or absent keeps the authored `href` |
+
+**Props and content both work.** The props stay the authoring surface, and a CMS entry overrides them field by field, so a merchant can swap the brand mark for a campaign without a deploy. A store with no CMS binding receives no `$content` and renders from the props alone. The `logo` model puts no `format` on `src`, because a store's logo is usually a root-relative path served from `public/` (`/logo.svg`), which JSON Schema's `uri` format rejects. `href` carries `uri-reference` and the same destination pattern the link-bearing footer models declare, which admits a root-relative path.
+
+**Nothing renders without a resolved `src` and `alt`.** Both props are optional and only `alt` 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 values: an unconfigured logo renders no element at all rather than a broken image. An optional field that arrives blank reads as unauthored and falls through to the prop; a blank `alt` renders nothing, since an unnamed link is worse than no link.
+
+**A destination that is not a plain web address is dropped.** The resolved `href` is checked at render, and only `http:`, `https:`, `mailto:`, `tel:`, and single-slash site-relative paths are kept. Anything else — a `javascript:` URL, a protocol-relative `//host`, a scheme-less relative path — renders the image with no link around it and logs the reason. No read-time validator enforces a URL pattern, so this is the only gate on a destination the CMS supplied.
+
+---
+
+## Canonical schema example
+
+```json
+{
+  "header-logo": {
+    "type": "Logo",
+    "props": {
+      "src": "https://store.example/logo.svg",
+      "alt": "Acme Store",
+      "href": "/"
+    },
+    "style": ["$logo"]
+  }
+}
+```
+
+Bound to a CMS entry, the element authors no content props at all — the entry supplies `src`, `alt`, and `href`, and an unconfigured store renders nothing rather than a placeholder. Below the fold, author `loading`:
+
+```json
+{
+  "footer-logo": {
+    "type": "Logo",
+    "props": {
+      "loading": "lazy"
+    },
+    "style": ["$logo"]
+  }
+}
+```
+
+## Common mistakes
+
+- **Wrapping `Logo` in a `NavigationLink`.** `Logo` already composes its own navigation link; nesting it in another link is invalid.
+- **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.
+- **Authoring a placeholder `src` as a fallback.** An unconfigured store then renders the developer's logo instead of no logo, and the self-hide can never trip. Author nothing and let the CMS supply it.
+- **Omitting `alt` in a store with no CMS.** The prop is optional so a CMS-only element can exist, but nothing renders without a resolved `alt` — a silent blank, not a type error.
+- **Leaving `loading` at its default below the fold.** A footer logo authored without `loading="lazy"` is fetched during the initial page load on every page.
+- **Using `Image` for the brand mark.** Prefer `Logo` so the link and the alt-text gate come for free.
+
+---
+
+## Styling
+
+| Component | What you style | Plausible classes |
+|---|---|---|
+| `Logo` | Sizes the brand mark; the `data-fs-logo` root drives dimensions and `data-fs-logo-image` reaches the image itself | `w-[140px] md:w-[220px]` |
+
+```json
+{
+  "header-logo": {
+    "type": "Logo",
+    "props": { "src": "https://store.example/logo.svg", "alt": "Acme Store", "href": "/" },
+    "style": ["w-[140px]", "md:w-[220px]"]
+  }
+}
+```
+
+The image carries no size of its own, so the width above only constrains the mark once the store tells it
+to fill the wrapper. Author that once per store as the `Logo` base swatch in `global.json → styles`:
+
+```json
+{
+  "Logo": {
+    "base": ["[&_[data-fs-logo-image]]:w-full", "[&_[data-fs-logo-image]]:h-auto"]
+  }
+}
+```
+
+---
+
+## Related
+
+- [[image]] — the inert asset renderer `Logo` composes; use directly for non-branded images.
+- [[navigation-link]] — the client-side link `Logo` composes; use directly for text or custom link content.

package/dist/docs/meter.md

@@ -0,0 +1,67 @@
+# Meter
+
+**Category:** content
+**Purpose:** Determinate meter primitive — renders a scalar value along a known range (ARIA `role="meter"`). Reusable and business-agnostic: use it for any progress-toward-a-goal indicator (free-shipping progress, loyalty tiers, storage/quota, upload). Wraps Base UI's `Meter`, which owns the ARIA (`aria-valuenow/min/max`, `aria-valuetext`) and sizes the indicator to the value.
+
+---
+
+## Visual cues (how to identify in an image)
+
+A Meter is present when you see a **horizontal bar partially filled** to represent a fixed value within a range (as opposed to an indeterminate spinner):
+
+- A track with a colored fill that stops at some point along its length.
+- Often paired with a label and/or a value read-out (e.g. "27%", "R$ 270 / R$ 999").
+
+Use `Meter` for determinate values. For indeterminate loading, use `Spinner`.
+
+---
+
+## When to use
+
+- A determinate value along a known min/max (progress toward a goal, a percentage, a quota).
+- Any bar that should expose `role="meter"` and an accessible value to screen readers.
+
+## When NOT to use
+
+- Indeterminate loading — use `Spinner`.
+- A slider the user can drag — use a form range input, not a meter.
+
+---
+
+## Composition
+
+`MeterRoot` owns `value`/`min`/`max` and the ARIA. Wrap a `MeterTrack` containing a `MeterIndicator`; optionally add a `MeterLabel` and `MeterValue`.
+
+```
+MeterRoot            (value, min=0, max=100)
+├── MeterLabel       (optional accessible label)
+├── MeterValue       (optional value read-out)
+└── MeterTrack
+    └── MeterIndicator   (Base UI sizes it to the value)
+```
+
+### Key parts
+
+| Component | Props | Notes |
+|---|---|---|
+| `MeterRoot` | `value`, `min?`, `max?`, `locale?`, `getAriaValueText?` | `role="meter"`; owns the ARIA. `getAriaValueText` overrides the spoken value text |
+| `MeterTrack` | — | The full-range groove |
+| `MeterIndicator` | — | The filled portion; Base UI sets its size inline |
+| `MeterLabel` | — | Accessible label text |
+| `MeterValue` | `children?: (formatted, value) => ReactNode` | Value read-out; render-function child |
+
+Style via `data-fs-meter-root`, `data-fs-meter-track`, `data-fs-meter-indicator`, `data-fs-meter-label`, `data-fs-meter-value`.
+
+---
+
+## Schema
+
+```json
+{
+  "type": "MeterRoot",
+  "props": { "value": 27, "min": 0, "max": 100 },
+  "children": [
+    { "type": "MeterTrack", "children": [{ "type": "MeterIndicator" }] }
+  ]
+}
+```