# Corvex Store V2 — Documentation Map for LLMs

> Canonical **public** developer documentation for Corvex Store V2 themes.
> Audience: external theme developers, agencies, partners, coding agents.
> Corvex Store V1 docs: https://corvex.mintlify.app — do NOT copy V1 contracts into V2.

## What is Corvex Store V2

React-based ecommerce storefront platform. Developers ship **Themes** (JSX sections, JSON schemas, templates). Merchants compose pages in the visual Editor. Public data via **@corvex/theme-sdk**.

**Stack for theme developers:** React sections + Theme SDK + Corvex CLI.

## Mental model

```text
Theme Code (local JSX, corvex build/sync)
Theme Defaults (templates/*.json, settings.data.json)
Merchant Content (Editor draft → Publish → live store)
```

```text
Theme → Layout → Layout Groups (header/footer) → Template sections → Blocks (optional)
Snippets: import-only reuse (@corvex/snippets/{id})
```

## Read order for agents

1. AGENTS.md (rules + checklist)
2. reference/runtime-api (imports @corvex/runtime, blocks patterns A/B, anti-patterns)
3. themes/css-scoping (NEVER :root / documentElement for theme tokens — builder shares the page)
3b. guides/editor-iframe-compatibility (builder iframe MUST work — not just /preview)
4. themes/locales (currency + i18n for themes)
4. cookbook/overview
5. reference/contracts/* (normative)
6. schema/overview (stable field types)
6b. schema/visible-when (conditional inspector fields)
6c. guides/schema-organization (UX best practices for schemas)
6d. guides/theme-defaults (schema default vs template blocks vs JSX empty-field fallback — never fake slides)
6e. guides/section-presets (presets[] in schema — editor Add section/block variants; not storefront runtime)
6f. guides/system-page-templates (404, password, maintenance — published storefront routing and theme templates)
7. guides/create-theme, create-hero-section, create-product-grid
7b. cookbook/catalog-product-grid (card de grade editável por blocos — Padrão C)
8. data/resources/* for object shapes

## Canonical contracts

reference/contracts/theme · section · block · snippet · schema · page · data · product · cart · preview · publish · runtime-api

## Theme V2 structure (required)

```text
theme.json (manifestVersion: 2)
  editorPreviewRootClasses[]  # OPTIONAL but STRONGLY RECOMMENDED — same as layout/theme.jsx className
layout/theme.jsx
config/settings.schema.json + settings.data.json
templates/index|product|collection|cart|search.json (REQUIRED)
sections/{id}/section.jsx + schema.json
groups/{groupId}.json (layout group defaults)
locales/*.json (UI strings — pt-BR.default.json + optional en.json, es.json, …)
```

Build output `.corvex/` — MUST NOT commit to git.

## Section contract (minimum)

- sections/{id}/section.jsx (default export) + schema.json (name + category)
- Props: settings, optional data, optional isEditing/onSettingsChange
- theme.json sections[] lists every section id
- Data: schema.data[] or defineSectionData() from @corvex/theme-sdk
- enabledOn: page types (index, product, collection, cart, search, blog, article, page)
- **Do NOT** set a static property on the section component (displayName, schema, block list, custom inspector, aliases). Do NOT import schema.json or blocks.json in JSX. CLI ≥ 2.3.5 attaches them on `corvex build`. Old draft labels: `schema.json` `nameAliases`. See reference/contracts/section (Fazer / não fazer). Do not name the editor engine in public docs.
- **`schema.name` is a label** — it may change. Stable ID is the folder / `schema.type`. `schema.identity.json` keeps previous labels as aliases. Do not change the folder id after pages exist. See reference/contracts/section (Identidade).

## Block / Snippet

- Blocks: blocks/{id}/block.jsx + schema.json; settings prop namespace
- Section lists allowed types in sections/{id}/blocks.json (file on disk only)
- Snippets: snippets/{id}/snippet.jsx; import @corvex/snippets/{id}; NOT in theme.json sections

## Stable schema field types

text, textarea, richtext, number, range, color, checkbox, select, radio, image, image_picker, url, product, product_list, collection, collection_list, font_picker, color_scheme, menu, header, paragraph

Experimental (not stable): inline_richtext, html, video, video_url, page, blog, link_list

Video in themes: guides/video-library (hub) · video-schema · video-patterns · video-carousel · cookbook/video-hero

## Public packages

| Import | Use |
|--------|-----|
| @corvex/theme-sdk | createStorefront, usePage, useCorvexCart, useTranslation, useLocalization, defineSection, defineSectionData, useCaptureLead, formatPrice, formatMoney |
| @corvex/runtime | PUBLIC APIs only — see reference/runtime-api. Editor canvas: always `{children}` + `useEditorPreviewCanvas()`. Do not import the editor engine. Do not use manual blocks.map in the builder. |
| @corvex/sdk | Legacy alias — prefer @corvex/theme-sdk |

## CLI (public)

```bash
npm install -g @corvex/theme-cli
corvex init | auth | link | validate | build | sync | pull | publish | pack
`corvex validate` writes `schema.identity.json` (current `name` + seen aliases). Commit the lockfile. Renaming `name` is allowed.
```


## Public packages

| Import | Use |
|--------|-----|
| @corvex/theme-sdk | createStorefront, usePage, useCorvexCart, useTranslation, useLocalization, defineSection, defineSectionData, useCaptureLead, formatPrice, formatMoney |
| @corvex/runtime | PUBLIC APIs only — see reference/runtime-api. Editor canvas: always `{children}` + `useEditorPreviewCanvas()`. Do not import the editor engine. Do not use manual blocks.map in the builder. |
| @corvex/sdk | Legacy alias — prefer @corvex/theme-sdk |
| @corvex/storefront-elements | **Web Components** (Lit Custom Elements) for embeddable catalog/product/cart. NOT a React theme. Docs: storefront-components/*. Skill: packages/corvex-storefront-elements/agent-skills/corvex-storefront-components. Playground: apps/corvex-storefront-playground (separate from `corvex dev`). |

## Agent Skills

Official theme-agent instructions ship inside `@corvex/theme-cli` and install to `.agents/skills/`. Skills `1.0.0` match `manifestVersion: 2` and CLI `>= 2.3.6`. Commands: `corvex skills install|update|status|list|doctor|disable`. `corvex init` installs them unless `--no-skills`. Guide: guides/agent-skills. Do not paste the eight skills into AGENTS.md.

## Preview vs Publish

- Editor canvas: live settings preview
- corvex sync: uploads theme CODE to linked store (`--keep-content` preserves editor templates/content)
- corvex pull: downloads remote store theme (code + templates + settings) to local folder
- corvex pull --version X: downloads published catalog version source archive (semver or themeVersionId)
- Editor Publish: merchant CONTENT to live storefront
- corvex publish: theme CATALOG version (not merchant layout)

## Cookbooks (15)

cookbook/overview — header, faq, slider, featured-product, product-card, catalog-product-grid, variant-selector, cart-drawer, search-results, product-recommendations, product-reviews, newsletter-capture, blog-article, collection-grid, video-hero

Each cookbook documents public APIs only. Validate your theme with `corvex validate .` after implementing.

## Localization

- Store: `shop.localization` → currency, language, moneyFormat (automatic via SDK)
- Theme: `locales/*.json` → UI strings via `useTranslation()` / `t('key')`
- Prices: prefer `product.price.formatted`; manual: `formatMoney()` / `useLocalization()`
- Guide: themes/locales

## Anti-patterns

- Templates V1 ou formatos legados de tema, private API fetch, cart.lines (use cart.items)
- Hardcoded currency symbols or UI strings (use locales/ + .formatted)
- Changing the section folder / `schema.type` after pages exist (identity). `name` may change.
- Manual block cards in editor canvas (blocks.map from block_order) — use {children}; see runtime-api ghost blocks
- Product grid: snippet product-card vs catalog-product-* blocks — do not mix; see cookbook/catalog-product-grid
- Hardcoded default banners in JSX when children is empty — use templates/*.json blocks; see guides/theme-defaults
- Assuming /preview is enough — builder iframe must work for every theme; platform copies page-root classes onto `.cx-theme-scope` and collapses in-flow portal shells
- :root or document.documentElement for theme CSS vars — scope to .my-theme-root / header / footer; see themes/css-scoping
- Portal a page-layout wrapper into useThemePortalTarget (min-height 100vh + opaque background, any class) — portal only overlays
- Editor-engine imports or undocumented block renderers in theme code — use @corvex/runtime only
- Static displayName, schema, aliases, or block list on the section component, or import blocks.json in section.jsx — the V2 contract forbids it. Use schema.json `nameAliases` for old draft names.
- Assuming product context without schema.data
- checkout template as V2 required file
- Documenting unstable field types as guaranteed
- Internal platform paths, monorepo, backend setup, JWT workarounds in public tutorials

## Known contract gaps (do not invent APIs)

- Product public type vs extra mapper fields (stock, metafields)
- Field product UUID vs getByHandle in featured-product sample
- No global openCartDrawer() — local React state (GAP-011)
- Variant match helpers are cookbook-local, not SDK

## Stack Corvex Store V2

- React JSX sections + Theme SDK + Corvex CLI
- Merchant draft/publish via Corvex Editor
- Collection URLs `/collections/`; SDK `categories` alias para coleções