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

# Erros comuns

> Pegadinhas ao consumir produtos, coleções e imagens nos temas Corvex — leia antes de gerar código.

# Erros comuns (temas e agências)

Guia rápido para evitar bugs recorrentes ao consumir a Storefront Data API.

***

## 1. Imagem de categoria/coleção

### ❌ Errado

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
// category.image é um objeto Image após o SDK — não use como src direto
<img src={category.image} alt={category.title} />
```

O browser recebe `[object Object]` e a imagem quebra.

### ✅ Correto

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
<img
  src={category.imageUrl || category.image?.url || ''}
  alt={category.image?.altText || category.title}
/>
```

| Origem | Formato |
| - | - |
| Backend `GET /categories` | `image: "https://cdn.../foto.png"` (string) |
| SDK `mapCategorySummary` | `image: { url, altText, ... }` + `imageUrl: string` |

Produtos seguem o mesmo padrão: use `product.featuredImage?.url` ou `getProductImage(product)`.

***

## 2. Coleção ≠ entidade separada

| Você pensa | Realidade no Corvex |
| - | - |
| API `/collections` | `GET /categories` |
| `storefront.collections.*` | alias de `storefront.categories.*` |
| URL `/collections/verao` | categoria com `slug: verao` |

Filtrar produtos por coleção:

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
storefront.products.list({ collection: 'uuid-da-categoria' });
// backend: ?categoryId=uuid
```

***

## 3. `useCorvexData` e formato do retorno

O hook legado retorna `Connection<T>` com `nodes`. Sempre normalize:

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const products = data?.nodes ?? [];
// ou
import { unwrapCorvexNodes } from '@corvex/theme-sdk';
const products = unwrapCorvexNodes(data);
```

Não assuma que `data` é array.

***

## 4. `limit` vs `first`

| Contexto | Parâmetro |
| - | - |
| `storefront.products.list()` | `first` |
| `useCorvexData('products', …)` | `limit` (mapeado para `first`) |
| `storefront.categories.list()` | `first` |
| `useCorvexData('collections', …)` | `limit` |

***

## 5. Produtos por categoria + `status`

### ❌ Evite

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
storefront.products.list({
  collection: categoryId,
  status: 'PUBLISHED', // costuma retornar 0 itens
});
```

### ✅ Prefira

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
storefront.products.list({
  collection: categoryId,
  inStock: true, // se quiser só com estoque
  // omita status na listagem geral
});
```

Detalhes: [products.list — Status e categoria](https://docs-loja.usecorvex.com.br/data/queries/products-list.md#⚠️-status-e-categoria).

***

## 6. Picker `collection` salva UUID

No inspector, `type: "collection"` persiste o **UUID** da categoria, não o handle:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "collection": "72a0c0d1-9c0d-41a0-a23c-64099ea04bfd" }
```

Passe esse valor direto para `collection` / `categoryId` na query de produtos.

***

## 7. Contexto de página vs fetch extra

Em template **product**, a plataforma já injeta o produto:

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
const { product } = usePage('product');
```

### ❌ Redundante na PDP

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
const product = await storefront.products.getByHandle(params.handle);
```

Em template **collection**, use `page.collection` e `page.products` — não busque de novo sem motivo.

***

## 8. Blocks e snippets não fazem fetch

Só **sections** (via `defineSectionData` ou `useCorvexData` no componente da section) buscam catálogo.

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
// ✅ snippet recebe dados da section pai
function CollectionCard({ category }) {
  return <img src={category.imageUrl} alt={category.title} />;
}
```

Ver [Regras de escopo](https://docs-loja.usecorvex.com.br/data/scope-rules.md).

***

## 9. `available` vs `inStock`

Código legado usava `available: true`. A API pública espera:

```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
inStock: true  // query ?inStock=true
```

***

## 10. Aliases de ordenação

O SDK aceita aliases comuns de ordenação e normaliza para o backend:

| Setting / SDK | Backend |
| - | - |
| `BEST_SELLING` | `createdAt` |
| `TITLE` | `name` |
| `PRICE` | `price` |

***

## 11. Preview no editor (URL)

Além de `?theme=` e `?version=`, o editor persiste estado de preview:

| Param | Exemplo | Restaura |
| - | - | - |
| `page` | `page=product` | Template ativo no editor |
| `product` | `product=uuid-ou-handle` | Produto no preview PDP |
| `collection` | `collection=uuid` | Coleção no preview |
| `q` | `q=tenis` | Termo de busca |
| `carouselPage` | `carouselPage=2` | Página do carrossel (se section suportar) |

Exemplo:

```
/?theme=...&version=...&page=home&carouselPage=1
/?theme=...&version=...&page=product&product=uuid-do-produto
```

Ver [Contexto de página](https://docs-loja.usecorvex.com.br/data/page-context.md).

***

## 12. Preview responsivo no editor

O canvas do editor **reduz a largura** do container (390px mobile, 768px tablet), mas `@media` e `window.matchMedia` usam a janela do browser por padrão.

O host emula o device quando você troca o ícone Desktop / Tablet / Mobile:

* Reaplica regras CSS do tema como se a viewport tivesse a largura do device
* Patcheia `matchMedia` para JS que usa breakpoints (ex.: menu mobile)

**No tema:** prefira `category.image?.url` e, se usar `window.innerWidth` / `matchMedia`, considere `useEditorPreviewState` ou CSS puro com `@media`.

Recarregue o editor após atualizar o host. O preview em `/preview` e no celular real não precisam dessa emulação.

***

## 13. Editor — blocks e carrossel

Erros do canvas, não da Data API.

| Sintoma | Causa provável |
| - | - |
| Tela branca ao remover bloco | `{children}` montado duas vezes no JSX |
| `removeChild` no console | O mesmo DOM duplicado ao excluir |
| `Cannot update … while rendering …` | `setState` dentro do updater de `useState` |
| Carrossel parado no editor | Bundle antigo. O modo inspecionar não troca a árvore: `useBuilderBlockEditLayout()` devolve sempre `false` |
| Inspector da section errado | Propriedade estática no componente. Apague, rode `corvex build` e `corvex sync`. [Contrato da section](https://docs-loja.usecorvex.com.br/reference/contracts/section.md) |

**Nunca:**

* Renderizar `{children}` em dois lugares.
* Usar `SectionBlockCanvas` na vitrine publicada.
* Chamar um callback dentro de `setPage((current) => { … return next })`.

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

***

## 14. Vazamento de CSS (tema para o builder)

No editor, tema e builder **compartilham a mesma página**. Se o tema grava cores em `:root` ou em `document.documentElement`, a UI do editor herda essas variáveis.

### ❌ Errado

```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
/* assets/theme.css */
:root {
  --color-primary: #1570c3;
}

.container { max-width: 1200px; }
```

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
document.documentElement.style.setProperty('--color_primary', settings.color_primary);
```

### ✅ Correto

Defina variáveis **só** nas raízes do tema (layout, header, footer):

```css theme={"theme":{"light":"github-light","dark":"github-dark"}}
.my-theme-root,
.header-pro-root,
.qvx-footer-pro {
  --color-primary: var(--brand-primary);
}

.my-theme-root .container {
  max-width: 1200px;
}
```

| Sintoma no builder | Causa |
| - | - |
| Botões Salvar/Publicar com cor da loja | `--color_primary` / `--brand-primary` no `:root` |
| Inspetor com tipografia do tema | `body`, `*` ou `button` sem escopo |
| Layout do inspetor quebrado | `.container` ou grid global sem prefixo |

A plataforma aplica settings do painel Tema em `.cx-theme-scope` — o CSS do tema **também** deve ficar escopado.

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

***

## 15. Canvas do builder branco

### Sintoma

* `/preview` e vitrine ok
* Canvas do editor (`/?store=…`) **branco**, sem erro no console
* Seções aparecem na árvore lateral

### Causas

| Causa | Correção |
| - | - |
| Overlay de portal (clone de layout com `100vh` + fundo) | Plataforma colapsa qualquer shell em fluxo; no tema, portalize só o overlay |
| CSS só no `ThemeLayout` | Plataforma aplica classes `*theme-root*` extraídas no `.cx-theme-scope`; declare `editorPreviewRootClasses` se o nome for atípico |
| Slideshow/hero altura 0 | Regras `[data-corvex-editor-preview='true']` + `min-height` |
| Portal em `document.body` | `useThemePortalTarget()` |
| Pack desatualizado | `corvex build` + sync/publish |

### ✅ Correto

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "editorPreviewRootClasses": ["my-theme-root", "my-theme-root--variant"]
}
```

```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);
}
```

**Guia completo:** [Compatibilidade iframe do editor](https://docs-loja.usecorvex.com.br/guides/editor-iframe-compatibility.md)

***

## 16. Vídeo com UUID no src

### ❌ Errado

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
// settings.heroVideo pode ser UUID da biblioteca — não é URL
<video src={settings.heroVideo} autoPlay muted playsInline />
```

O browser não reproduz UUID; o hero fica vazio ou quebra silenciosamente.

### ✅ Correto

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
import CorvexVideo from '@corvex/snippets/corvex-video';

<CorvexVideo
  value={settings.heroVideo}
  poster={settings.heroPoster || settings.heroImage}
  autoplay
  muted
  loop
  controls={false}
/>
```

| Origem do valor | Formato em `settings` | Renderização |
| - | - | - |
| Biblioteca / Enviar | UUID (`a1b2…`) | Classificar → resolver HLS ou poster |
| URL (YouTube/Vimeo/MP4) | `https://…` | Embed ou `<video src>` |

Guia completo: [Biblioteca de vídeos](https://docs-loja.usecorvex.com.br/guides/video-library.md) · [FAQ](https://docs-loja.usecorvex.com.br/guides/video-faq.md).

## 17. Carrossel de vídeos e loop HLS

### ❌ Errado — recriar HLS quando visibilidade muda

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
useEffect(() => {
  hls?.destroy();
  const hls = new Hls();
  hls.loadSource(src);
  if (shouldPlay) video.play();
}, [src, shouldPlay]); // marquee + IntersectionObserver → milhares de seg_*.mp4
```

Também evite:

* `playWhenVisible` em faixa **marquee** com autoplay (observer instável com animação CSS)
* `video.src = manifest.m3u8` após erro fatal do Hls.js
* Resolver UUID / fetch de `/playback` dentro do block em vez do snippet `CorvexVideo`

### ✅ Correto

```jsx theme={"theme":{"light":"github-light","dark":"github-dark"}}
// Snippet: setup HLS só quando src muda; play/pause em outro efeito
// Section marquee: playWhenVisible={false}
// Block: useCorvexVideoPlayback via CorvexVideo
```

| Modo | `playWhenVisible` | Streams ativos |
| - | - | - |
| Hero único | opcional | 1 |
| Embla (1 slide) | sim — pause inativos | 1 |
| Marquee autoplay | **false** | vários (buffer baixo, sem recriar HLS) |
| Grid | false — play no clique | 1 |

Guia completo: [Carrossel de vídeos (Reels)](https://docs-loja.usecorvex.com.br/guides/video-carousel.md).

***

## 18. Grade de produtos — snippet vs blocos de catálogo

### ❌ Errado — misturar modelos na mesma expectativa

* Editar blocos na seção **Início** (`main`) e esperar que o carrossel **Vitrine de produtos** (`product-list` + snippet) mude.
* Repetir `renderCatalogProductBlocks` com `blocks` desatualizados no editor sem `useSectionLiveBlocks()`.
* Colocar `type` errado em `blocks[id]` (todos `catalog-product-image`) — sintoma: várias imagens, sem título/descrição.
* `order` no template apontando para `"main"` sem objeto `sections.main` com `blocks` + `block_order`.

### ✅ Correto

* **Snippet:** `import ProductCard from '@corvex/snippets/product-card'` — card fixo; customização via settings da section ou props do snippet. Ver [Product Card](https://docs-loja.usecorvex.com.br/cookbook/product-card.md).
* **Blocos de catálogo:** section busca produtos; cada item da grade usa a mesma `block_order`; blocks leem produto via contexto. Ver [Grade com blocos de catálogo](https://docs-loja.usecorvex.com.br/cookbook/catalog-product-grid.md).
* Persistência: `blocks` e `block_order` (template e publicação). No editor, `useSectionLiveBlocks()` espelha os tipos ao vivo.
* O tipo é a pasta `blocks/{id}/`. Se `schema.json` tiver `type`, use o mesmo id. `name` é o rótulo no editor e pode mudar.
* No editor, monte `{children}` no **primeiro card** da grade — não em host oculto com `clip`/`aria-hidden` (seleção de bloco fica desalinhada).

***

## Checklist antes de publicar section

* [ ] Imagens usam `.url` ou `imageUrl`, nunca objeto `Image` no `src`
* [ ] Listas normalizam `data.nodes`
* [ ] Filtro por coleção usa UUID do picker
* [ ] `inStock` em vez de `status=PUBLISHED` com categoria
* [ ] Snippets/blocks não chamam API
* [ ] PDP/collection usam `usePage()` quando aplicável
* [ ] Sections com blocks: `{children}` uma vez, sem propriedade estática no componente, `corvex build` e sync. [Runtime API](https://docs-loja.usecorvex.com.br/reference/runtime-api.md)
* [ ] Carrossel com blocks: não mapear `children` como slides
* [ ] Vídeo: nunca `src={uuid}` — usar `CorvexVideo` ou classificar valor ([guia](https://docs-loja.usecorvex.com.br/guides/video-library.md))
* [ ] Carrossel de vídeos: HLS não recriado em `shouldPlay` — ver [Carrossel de vídeos](https://docs-loja.usecorvex.com.br/guides/video-carousel.md)
* [ ] CSS escopado: sem `:root` global; builder não herda cores do tema — [Escopo CSS](https://docs-loja.usecorvex.com.br/themes/css-scoping.md)
* [ ] Builder iframe não branco: `editorPreviewRootClasses` + regras iframe — [Compatibilidade iframe](https://docs-loja.usecorvex.com.br/guides/editor-iframe-compatibility.md)

***

## Referências

* [Data API — visão geral](https://docs-loja.usecorvex.com.br/data/overview.md)
* [Product](https://docs-loja.usecorvex.com.br/data/resources/product.md)
* [Coleção](https://docs-loja.usecorvex.com.br/data/resources/category.md)
* [Image](https://docs-loja.usecorvex.com.br/data/resources/image.md)
* [Biblioteca de vídeos](https://docs-loja.usecorvex.com.br/guides/video-library.md)
* [Carrossel de vídeos](https://docs-loja.usecorvex.com.br/guides/video-carousel.md)
* [products.list](https://docs-loja.usecorvex.com.br/data/queries/products-list.md)
* [categories.list](https://docs-loja.usecorvex.com.br/data/queries/categories-list.md)


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