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

---

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:

{
  "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:

[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 · guia Bibliotecas de terceiros

---

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

// ❌ 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

---

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 · Erros comuns §10

---

6. Publicar e testar

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
2. Aplicar este guia + Escopo CSS
3. Nunca assumir que ThemeLayout roda no editor
4. Sempre incluir checklist §6 na entrega