Compatibilidade com o iframe do editor

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:

Canvas do builder (iframe, data-corvex-editor-preview="true")
/preview (aba)
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

DevTools → iframe .cx-canvas-iframe
Existe #cx-preview-content[data-corvex-editor-preview="true"]?
.cx-theme-scope inclui suas classes de editorPreviewRootClasses?
Hero/slider com altura computada > 0?
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:

Ler AGENTS.md na pasta da documentação e Runtime API
Aplicar este guia + Escopo CSS
Nunca assumir que ThemeLayout roda no editor
Sempre incluir checklist §6 na entrega

Introdução

Temas

Seções

Guias

Exemplos

Storefront Components

Schema

CLI

Dados

SDK

Contratos

Marketplace

Compatibilidade com o iframe do editor

Compatibilidade com o iframe do editor

Regra de ouro

Diferença builder vs `/preview`

1. Escopo CSS (MUST)

2. Declarar classes raiz no `theme.json`

3. Altura no iframe — carrosséis e heroes

4. Portais (modais, sticky, drawers)

5. Blocks no canvas

6. Publicar e testar

Diagnóstico rápido

O que a plataforma já faz por você

Para agentes de IA

​Compatibilidade com o iframe do editor

​Regra de ouro

​Diferença builder vs /preview

​1. Escopo CSS (MUST)

​2. Declarar classes raiz no theme.json

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

​4. Portais (modais, sticky, drawers)

​5. Blocks no canvas

​6. Publicar e testar

​Diagnóstico rápido

​O que a plataforma já faz por você

​Para agentes de IA

Compatibilidade com o iframe do editor

Regra de ouro

Diferença builder vs `/preview`

1. Escopo CSS (MUST)

2. Declarar classes raiz no `theme.json`

3. Altura no iframe — carrosséis e heroes

4. Portais (modais, sticky, drawers)

5. Blocks no canvas

6. Publicar e testar

Diagnóstico rápido

O que a plataforma já faz por você

Para agentes de IA