> ## Documentation Index
> Fetch the complete documentation index at: https://docs-loja.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Page Contract

> Contrato canônico de templates e composição de páginas na Corvex.

> Esta página é o **contrato canônico** para Templates e composição de páginas.

Uma **página** na loja é uma instância de um **template type** com uma lista ordenada de sections e seus settings.

***

## Template types (sistema)

| `type` | Uso público |
| - | - |
| `index` | Home |
| `product` | Detalhe do produto |
| `collection` | Listagem de coleção/categoria |
| `cart` | Carrinho |
| `search` | Busca |
| `blog` | Listagem de blog |
| `article` | Artigo |
| `page` | Página institucional custom (`PAGE:{handle}` no runtime) |

Templates `index`, `product`, `collection`, `cart`, `search` MUST existir no Theme ([Theme Contract](https://docs-loja.usecorvex.com.br/reference/contracts/theme.md)).

***

## MUST — arquivo `templates/{type}.json`

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "name": "Página inicial",
  "type": "index",
  "sections": {
    "hero": {
      "type": "hero",
      "settings": { "title": "Bem-vindo" }
    },
    "featured": {
      "type": "featured-products",
      "settings": { "limit": 4 }
    }
  },
  "order": ["hero", "featured"]
}
```

| Campo | Quem exige |
| - | - |
| Arquivo `templates/{type}.json` | O validador, para os cinco tipos obrigatórios |
| `sections` | O formato que o starter e o discover leem |
| `order` | O discover usa o array quando existe. Sem ele, a ordem vira a das chaves do objeto. O validador não reprova a ausência |
| `name` | Texto do starter. O validador não exige |

***

## MUST — instância de section

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "hero",
  "settings": { },
  "blocks": { },
  "block_order": []
}
```

| Campo | Obrigatório |
| - | - |
| `type` | REQUIRED — section type registrado no tema |
| `settings` | OPTIONAL |
| `blocks` | OPTIONAL |
| `block_order` | OPTIONAL — REQUIRED se `blocks` presente |

`type` MUST corresponder a um ID em `theme.json` → `sections`.

***

## Defaults vs instância da loja

| Artefato | Onde | Função |
| - | - | - |
| `templates/*.json` | Pacote do tema | Defaults ao instalar tema |
| Draft da loja | Persistido pelo Editor | Composição atual do merchant |
| Published | Revisão publicada | Loja ao vivo |

O merchant edita a **instância**; o arquivo no tema define **defaults**.

***

## Layout groups (global)

Sections em `layoutGroups` (header/footer) são injetadas **antes/depois** do conteúdo do template, não listadas em cada `templates/*.json`.

***

## URLs públicas (visitante)

| Path | Template |
| - | - |
| `/` | `index` |
| `/products/:handle`, `/produtos/:handle` | `product` |
| `/collections/:handle`, `/colecoes/:handle` | `collection` |
| `/cart` | `cart` |
| `/search`, `/busca` | `search` |
| `/blogs/:blog` | `blog` — o mapper monta essa URL. O parser de rota publicada deste repositório não trata `blogs` |
| `/blogs/:blog/articles/:article` | `article` — mesma ressalva |
| `/page/:handle` | `page` — não aparece em `publishedStorefrontRoute.js` |

***

## Contexto de página

Cada template type expõe objetos de página via Theme SDK (`usePage`, `useCorvexContext`). Ver [Data Contract](https://docs-loja.usecorvex.com.br/reference/contracts/data.md).

***

## Restrições

* MUST NOT usar `pages/*.json` no lugar de `templates/*.json`.
* O validador não pede `templates/checkout.json`. Checkout não é um template do tema.

***

## Veja também

* [Theme Contract](https://docs-loja.usecorvex.com.br/reference/contracts/theme.md)
* [Data Contract](https://docs-loja.usecorvex.com.br/reference/contracts/data.md)
* [Publish Contract](https://docs-loja.usecorvex.com.br/reference/contracts/publish.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.