> ## 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.

# Compatibilidade com o iframe do editor

> Evite canvas branco no builder — regras obrigatórias para temas Corvex no iframe do editor, além do /preview.

> **Leia isto se:** a loja aparece em `/preview`, mas o **canvas do builder fica branco** (sem erro no console).

O editor Corvex renderiza a loja dentro de um **iframe isolado**. Esse ambiente **não é idêntico** ao `/preview` em CSS e carregamento de bundle. Temas MUST ser escritos para funcionar nos **dois**.

***

## Regra de ouro

O tema MUST renderizar a **mesma árvore React** em:

1. **Canvas do builder** (iframe, `data-corvex-editor-preview="true"`)
2. **`/preview`** (aba)
3. **Vitrine** publicada

Inspecionar no builder só adiciona a camada de seleção. Não altere o layout por causa disso.

***

## Diferença builder vs `/preview`

| | Canvas do builder | `/preview` |
| - | - | - |
| DOM | iframe | página principal |
| Marcador | `[data-corvex-editor-preview="true"]` | ausente |
| CSS do editor | chrome + patches da plataforma | não aplica |
| Bundle | rascunho da loja, com fallback para o catálogo | a versão da URL quando ela traz `version`; senão a versão instalada |

Um tema que funciona só no `/preview` **violou o contrato** — não é “opcional” corrigir.

***

## 1. Escopo CSS (MUST)

**MUST NOT** definir layout/tokens em `:root`, `html`, `body` ou seletores globais (`*`, `.container` sem prefixo).

**MUST** prefixar com a classe raiz do `layout/theme.jsx`.

Guia completo: [Escopo CSS — tema vs editor](https://docs-loja.usecorvex.com.br/themes/css-scoping.md)

***

## 2. Declarar classes raiz no `theme.json`

O editor **não monta** `layout/theme.jsx`. A plataforma aplica `.cx-theme-scope` e classes extras do manifest:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "manifestVersion": 2,
  "slug": "meu-tema",
  "editorPreviewRootClasses": [
    "my-theme-root",
    "my-theme-root--shop"
  ]
}
```

**MUST** listar as **mesmas classes** do wrapper em `layout/theme.jsx`.

Se o CSS do tema só funciona com `.my-theme-root--shop` e você omitir este campo, o canvas pode ficar em branco ou sem espaçamento.

***

## 3. Altura no iframe — carrosséis e heroes

Bibliotecas como Embla/Flickity medem o viewport no iframe. Enquanto não medem, a seção pode ter **altura 0** → canvas branco **sem erro no console**.

**MUST** adicionar regras com `[data-corvex-editor-preview='true']` em sections de altura dinâmica:

```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
[data-corvex-editor-preview='true'] .dm-slideshow:not(.dm-slideshow--preserve-ratio) {
  min-height: var(--dm-slideshow-height-mobile, 420px);
}

@media screen and (min-width: 641px) {
  [data-corvex-editor-preview='true'] .dm-slideshow:not(.dm-slideshow--preserve-ratio) {
    min-height: var(--dm-slideshow-height-tablet, 480px);
  }
}

@media screen and (min-width: 1000px) {
  [data-corvex-editor-preview='true'] .dm-slideshow:not(.dm-slideshow--preserve-ratio) {
    min-height: var(--dm-slideshow-height-desktop, 530px);
  }
}
```

A plataforma aplica patches globais para padrões Dropmeta conhecidos, mas **sections custom** MUST incluir regras próprias.

Referência: cookbook [Slider](https://docs-loja.usecorvex.com.br/cookbook/slider.md) · guia [Bibliotecas de terceiros](https://docs-loja.usecorvex.com.br/guides/third-party-libraries.md)

***

## 4. Portais (modais, sticky, drawers)

**MUST** usar `useThemePortalTarget()` de `@corvex/runtime`.

**MUST NOT** usar `createPortal(..., document.body)`.

**MUST NOT** portalizar um wrapper de página (`min-height: 100vh`, fundo opaco, clone do layout). A plataforma colapsa **qualquer** filho em fluxo do portal — a classe do tema não importa. Portalize só o overlay (`position: fixed`).

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
// ❌ Cobre o canvas — qualquer className
createPortal(
  <div className="my-theme-root" style={{ minHeight: '100vh', background: '#fff' }}>
    <ToastStack />
  </div>,
  useThemePortalTarget()
);

// ✅
createPortal(<ToastStack />, useThemePortalTarget());
```

Ver [Runtime API](https://docs-loja.usecorvex.com.br/reference/runtime-api.md)

***

## 5. Blocks no canvas

No builder iframe:

* Use `{children}` como árvore principal. Não use `blocks.map()`.
* **MUST** manter `SectionBlockCanvas` na mesma árvore que na vitrine

Detalhes: [Sections — Blocks](https://docs-loja.usecorvex.com.br/sections/blocks.md) · [Erros comuns §10](https://docs-loja.usecorvex.com.br/data/pitfalls.md)

***

## 6. Publicar e testar

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
corvex validate
corvex build
corvex sync
```

**Checklist antes de entregar:**

* [ ] `editorPreviewRootClasses` no `theme.json`
* [ ] CSS escopado (sem `:root` de layout)
* [ ] Regras `[data-corvex-editor-preview='true']` em sliders/heroes
* [ ] Portais via `useThemePortalTarget()`
* [ ] Builder iframe **não** branco (desktop + mobile)
* [ ] `/preview` idêntico ao canvas
* [ ] Smoke na vitrine após publish

***

## Diagnóstico rápido

1. DevTools → iframe `.cx-canvas-iframe`
2. Existe `#cx-preview-content[data-corvex-editor-preview="true"]`?
3. `.cx-theme-scope` inclui suas classes de `editorPreviewRootClasses`?
4. Hero/slider com **altura computada > 0**?
5. Network: CSS `/api/theme-bundle/...?asset=css` retorna 200 com conteúdo?

| Sintoma | Correção |
| - | - |
| Canvas branco, preview ok, seções na árvore | Shell no portal — plataforma colapsa; no tema, só overlay `position: fixed` |
| Canvas branco, preview ok | CSS de page-root; plataforma aplica classes `*theme-root*` no `.cx-theme-scope` |
| Slider altura 0 | Regras `[data-corvex-editor-preview='true']` |
| Modal/header some | `useThemePortalTarget()` |
| Só uma loja | Republish pack; verificar draft vs catálogo |

***

## O que a plataforma já faz por você

* Portal do builder é âncora 0×0; shells de página em fluxo (qualquer classe) são colapsados
* CSS `*theme-root*` / `*layout-root*` do bundle é aplicado no wrapper `.cx-theme-scope` (ThemeLayout não monta no canvas). O CSS do tema não é reescrito.
* Fallback CSS draft → catálogo quando o draft falha
* Isolamento builder ↔ tema (sem vazamento de CSS)
* Patches pontuais só para packs antigos conhecidos (não são o suporte a tema novo)

Isso cobre temas e seções **novos** sem checklist por fork. O contrato abaixo evita lutar contra o runtime.

***

## Para agentes de IA

Antes de gerar um tema ou section com carrossel/blocks:

1. Ler `AGENTS.md` na pasta da documentação e [Runtime API](https://docs-loja.usecorvex.com.br/reference/runtime-api.md)
2. Aplicar este guia + [Escopo CSS](https://docs-loja.usecorvex.com.br/themes/css-scoping.md)
3. Nunca assumir que `ThemeLayout` roda no editor
4. Sempre incluir checklist §6 na entrega


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