Skip to content

Objetos Liquid ​

Contexto Liquid: contrato de dados do Storefront V3 ​

Dados comerciais (shop, catalog, content, page, category, product) são fornecidos pela aplicação em tempo de renderização. Eles não são arquivos nem configuração do tema. theme e section são metadados de renderização. Um objeto específico, como category ou product, pode não existir fora de seu contexto de página; teste sua presença quando um component for compartilhado.

Toda página recebe o mesmo contexto global:

Objetos comuns ​

js
shop = {
  id,
  name,
  seo: { description, keywords },
  customerPolicy: { individual: boolean, company: boolean },
  shippingEnabled: boolean,
  paymentMethods: [{ id, name, audience: null | 'Pessoa física' | 'Pessoa jurídica' }],
  shippingMethods: [{ id, name }],
  logo: null | {
    url,
    width,
    height,
    alt
  },
  favicon: null | {
    url,
    type
  }
}

catalog = {
  categories: category[]
}

content = {
  pages: [{ id, title, slug }]
}

theme = {
  id,
  revision,
  assets: {
    css,
    js
  }
}

section = {
  id,
  type
}

shop.paymentMethods lista modalidades cadastradas, ativas e visíveis atendidas pelo checkout Node. Respeita o público da loja, deduplica Pix/cartão/boleto e não contém credenciais, chaves Pix ou dados bancários. Não exige desconto nem mais de uma parcela. shop.shippingMethods contém apenas ID e nome das modalidades ativas; fica vazio com frete global desligado. APIs diretas usam os nomes dos serviços salvos e a ativação Node, por exemplo “Correios — PAC”; o nome histórico do registro não substitui os serviços da integração. Vínculos ambíguos ou sem configuração Node ativa e serviços válidos não são anunciados. Nomes personalizados são textos, sempre escapados pelo Liquid. Ambas as listas são informativas: disponibilidade, endereço, valor, prazo, autorização e limites são revalidados no checkout/cotação.

Os vinte temas oficiais incluem essas listas em components/store_methods.liquid, no rodapé e no produto. Os cards e o detalhe do produto incluem ofertas calculáveis. Blocos vazios são omitidos. Essa composição é um padrão dos bundles oficiais, não uma configuração visual obrigatória; temas publicados exigem nova revisão.

shop.customerPolicy informa os tipos de comprador habilitados no painel: individual para CPF e company para CNPJ. São permissões comerciais, não settings visuais. Os temas oficiais limitam as opções do cadastro/perfil e identificam o campo de documento do checkout conforme essas flags. Com ambos desabilitados, não oferecem finalização de compra. O servidor revalida cadastro, perfil e novos pedidos sob transação, inclusive visitantes e o tipo da conta autenticada. Apenas ocultar campos no Liquid não substitui essa validação. Replays de pedidos já concluídos permanecem consultáveis. Temas já publicados recebem a nova apresentação somente ao publicar uma nova revisão; a proteção no backend vale imediatamente.

SEO no HTML ​

shop.seo = { description, keywords } contém a descrição e as palavras-chave cadastradas no painel administrativo. São fatos comerciais, sem configuração paralela no tema. O renderer entrega page.seo com title, description, keywords, image, robots e canonical. Título e descrição específicos de produto, categoria ou página institucional têm precedência; valores vazios usam os da loja. Produtos também usam suas palavras-chave cadastradas quando disponíveis.

A plataforma gera no <head> o título, meta description, meta keywords, Open Graph (og:title, og:description, og:site_name, og:locale, og:type, og:url, og:image, og:image:alt) e Twitter Cards (twitter:card, twitter:title, twitter:description, twitter:image). A imagem da página usa a imagem principal do produto ou a capa da categoria; nas demais páginas, usa a primeira imagem do conteúdo principal e, na ausência dela, a logo da loja. As URLs de imagem são absolutas no HTML público. Campos vazios são omitidos e os valores são escapados. Tags gerenciadas pelo renderer são substituídas sem duplicatas, inclusive nas revisões já instaladas; o tema continua controlando livremente a estrutura e a aparência do corpo da página.

A URL canônica pública usa a origem validada da requisição e seu caminho, preservando page/perPage válidos e removendo rastreamento. Não redireciona entre domínios da mesma loja. Busca, carrinho, checkout, confirmação, conta e prévias recebem noindex,nofollow e não publicam canonical ou og:url. O cadastro de metatags/scripts arbitrários do legado não é executado automaticamente por esse contrato. Códigos antigos não são convertidos automaticamente. Para reutilizar um trecho, solicite sua inclusão no tema em Códigos personalizados e confira antes de publicar. As tags básicas são geradas no HTML inicial, sem depender de JavaScript.

catalog.categories e content.pages são dados disponíveis ao tema. A maneira como esses dados aparecem na interface é inteiramente responsabilidade dos arquivos Liquid e CSS. Não existe sistema obrigatório de menu ou navegação no Theme V3, nem é preciso criar registros de menu, navigation.json, menu.json ou configurações de header e footer.

No servidor de desenvolvimento, uma origem STOREFRONT_DEVELOPMENT_ORIGIN configurada permite que Visitar loja abra a revisão publicada da loja do painel nessa origem. A entrada __storefront_host seleciona um domínio público validado e um cookie mantém a seleção nas páginas seguintes, com nova validação a cada requisição. Os caminhos Liquid continuam normais (/produto, /categoria etc.), usando storefront_url; não acrescente parâmetros ou domínios locais ao tema. Essa seleção é exclusiva do servidor local e do painel de testes (admin-teste.lojavirtual.com.br) e é ignorada na produção.

shop.logo é a identidade global da loja, compartilhada com o legado por loja.fk_id_imagem_logomarca → imagem.id_imagem. Ela não é um asset do tema, não deve ser copiada para a revisão nem substituída por uma imagem gerada pela IA. O tema controla somente sua apresentação (posição, tamanho, margens e layout) e deve usar shop.name como fallback quando shop.logo for null.

shop.favicon é a identidade global equivalente para a aba do navegador, compartilhada com o legado por loja.fk_id_imagem_favicon → imagem.id_imagem. A plataforma injeta o <link rel="icon"> correspondente no <head> de toda página, inclusive em revisões já publicadas, substituindo ícones declarados pelo tema. O tema não deve embutir um favicon próprio nem copiá-lo para a revisão. O lojista envia o arquivo (PNG, ICO, JPEG ou WebP, até 1 MB) no cartão “Favicon da loja” do editor de temas; a troca fica pendente na prévia e entra na loja somente ao Publicar, na mesma operação atômica da revisão e da logo. O editor também pode gerar o favicon a partir da logo. Se a edição por IA falhar, o servidor recorta a própria logo localmente e informa esse resultado no editor; nenhuma das duas opções publica o favicon automaticamente. Na preparação inicial, se a loja ainda não tiver favicon, a IA gera um símbolo quadrado próprio em paralelo à logo, sem aguardar seus bytes. O resultado usa o mesmo vínculo global do favicon, com validação e variações do armazenamento legado. Um favicon já cadastrado ou enviado durante a geração sempre prevalece.

O manifesto pode declarar um contrato opcional e explícito de cores de marca:

json
{
  "branding": {
    "colors": {
      "primary": "--color-primary",
      "primaryHover": "--color-primary-hover",
      "primaryContrast": "--color-primary-contrast",
      "accent": "--color-accent"
    }
  }
}

Cada chave semântica autoriza somente a variável CSS indicada. Revisões que armazenam a paleta no JSON podem declarar também, dentro de branding:

json
"editor": {
  "shared": "palette",
  "colors": {
    "primary": "primary",
    "primaryHover": "primary_hover",
    "primaryContrast": "primary_contrast"
  }
}

Esse mapa deve corresponder às chaves de branding.colors e apontar para campos color da área compartilhada. Nessas revisões, a aplicação muda somente valores em editor.json. Sem esse mapa, continua modificando as variáveis declaradas em assets/theme.css, preservando revisões anteriores sem conversão automática. A operação usa o rascunho atual, não publica e não procura cores arbitrárias. A paleta sugerida é extraída localmente e de forma determinística com sharp, sem IA. A troca de logo no editor permanece no rascunho em memória junto com as alterações de layout e cores, até Publicar. A prévia usa os bytes validados, sem gravar imagem no cadastro ou no storage legado. Na publicação, a plataforma grava a nova imagem e ativa sua referência global junto com a revisão do tema, em uma operação atômica. Conflito na revisão ou na logo atual recusa ambas. Trocar/restaurar um tema mantém a logo global atual: a logo não integra bundles, ZIPs ou o histórico visual. Descartar a troca pendente preserva a logo publicada.

Revisões anteriores que não declaram branding.colors continuam renderizáveis, mas recusam a aplicação automática com uma mensagem funcional; restaurar ou atualizar para uma revisão oficial habilita o contrato. O editor também pode extrair a paleta da logo global já cadastrada, sem exigir um novo upload. A URL pública de shop.logo usa a variação média do armazenamento legado para reduzir o peso nos headers, enquanto a original permanece preservada.

Um tema pode usar todas as categorias no header, selecionar apenas algumas, colocar as páginas no footer ou ignorar ambos os conjuntos. Por exemplo, um pedido como "coloque Quem Somos no menu" pode ser atendido alterando components/header.liquid para percorrer ou selecionar itens de content.pages. Da mesma forma, todas as páginas institucionais podem ir para o rodapé apenas alterando components/footer.liquid.

Categoria ​

js
category = {
  id,
  parentId,
  name,
  slug,
  url,
  description,
  featured,
  position,
  image,
  banner,
  children: category[]
}

category.image é a imagem de capa que representa a categoria em vitrines, cards e menus. Quando o tema usar uma imagem de categoria, priorize category.image; recorra a uma foto de produto ou asset editorial somente se a capa estiver ausente. A capa é carregada independentemente da presença de banner. category.banner é o banner exibido no topo da página da própria categoria. Ambos seguem o formato image descrito na seção de produto, são cadastrados pelo lojista no painel de categorias e podem ser null. Um não substitui o outro: sem capa, o tema decide a alternativa (inicial, foto de um produto da seleção ou imagem editorial do bundle). O banner costuma ser largo e a capa quadrada; para o banner prefira banner.originalUrl, pois url é a variação média. Os dois estão disponíveis em catalog.categories (inclusive em children) e no objeto category da página de categoria. Em product.categories, image e banner são sempre null: localize a categoria pelo id em catalog.categories quando precisar da imagem. Os temas oficiais expõem em category_products os campos show_banner, show_content, content_position (before_products ou after_products), show_title, show_eyebrow, show_breadcrumb e show_subcategories. Os booleanos começam habilitados; o conteúdo começa antes dos produtos. Preserve essas escolhas ao editar a seção. Renderize a descrição/HTML com {{ category.description | editor_html | raw }} em um contêiner de bloco, nunca dentro de um parágrafo ou sem sanitização. As opções pertencem ao layout, não ao cadastro individual da categoria, e não devem ocultar a listagem.

Os produtos de page.products na Home carregam suas categorias ativas da mesma loja. Assim, o Aura pode usar uma foto de produto vinculado quando a categoria ainda não tem capa, sem novas consultas por card e sem confundir banner com capa.

category.url é o caminho interno canônico produzido pela plataforma, sem o prefixo da prévia. Use {{ category.url | storefront_url }} em qualquer link de categoria, inclusive menus, vitrines e categorias relacionadas ao produto. Não concatene slug no Liquid nem aplique encoding novamente. slug preserva o dado legado e pode ser null ou vazio; não é o destino de navegação.

Slugs utilizáveis e únicos entre categorias ativas da mesma loja mantêm a URL amigável com encoding de segmento. Ausência, ambiguidade pela collation do banco, caminhos inseguros, slugs com /, ? ou # e identificadores que a rota interpreta como números usam /categoria/{id}. Isso evita depender da interpretação de delimitadores codificados em proxies. Espaços, acentos e % continuam usando encoding normal. O resolvedor mantém o isolamento por loja e não escolhe uma categoria arbitrária quando o slug é ambíguo. Breadcrumbs e paginação já recebem URLs prontas, incluindo o prefixo da prévia quando aplicável.

Na árvore de catalog.categories, children contém as subcategorias. No contexto da página de categoria, o objeto raiz category acrescenta:

js
category.products = product[]
category.pagination = {
  page,
  perPage,
  total,
  totalPages,
  hasPreviousPage,
  hasNextPage,
  previousUrl,
  nextUrl
}

Esses campos são saída do servidor. page vem da URL e assume 1; perPage vem do parâmetro válido da requisição ou da constante DEFAULT_CATEGORY_PER_PAGE em src/modules/storefront/product-selection.js, atualmente 24 e com máximo 100; total é a contagem da mesma seleção autorizada; os demais campos são derivados desses valores. Entradas inválidas retornam 400 e não são salvas no tema. Página além do fim retorna 404; categoria vazia na primeira página retorna totalPages: 0. Os links são relativos e preservam um perPage não padrão.

No preview navegável, filtros e paginação usam GET dentro do mesmo namespace temporário e mantêm o rascunho ao trocar de página.

Produto ​

js
product = {
  id,
  name,
  slug,
  url,
  shortDescription,
  description,
  descriptionIsHtml,
  brand,
  model,
  specifications,
  price,
  compareAtPrice,
  priceRange,
  hasVariablePrices,
  hasVariants,
  variantsLoaded,
  requiresSelection,
  salesState,
  visible,
  priceVisible,
  purchasable,
  inStock,
  stock,
  lowStock,
  minimumQuantity,
  maximumQuantity,
  mainImage,
  secondaryImage,
  isNew,
  freeShipping,
  paymentOffers,
  images,
  video,
  categories,
  optionGroups,
  variants,
};

product.url é o caminho interno canônico do produto, sem o prefixo da prévia. Use {{ product.url | storefront_url }} em cards, vitrines, carrinho (item.product.url) e demais links de produto. Não concatene slug no Liquid nem aplique encoding novamente. Quando o slug do cadastro está ausente, contém /, ?, # ou é formado só por dígitos (que a rota interpreta como ID), a plataforma usa /produto/{id}, que abre o mesmo produto da loja. Nesses casos, product.slug também recebe o ID, pois é sempre o identificador usado em product.url; ele nunca é null para produtos da vitrine.

product.specifications é uma lista de { label, value } com as informações preenchidas no cadastro: marca, modelo, garantia e entrega. Os títulos respeitam as personalizações do painel; títulos vazios ou placeholders históricos usam o nome padrão. Valores vazios são omitidos. São textos escapados pelo Liquid, não HTML nem opções de variante. Os temas oficiais exibem a lista junto à descrição curta do produto. O campo de entrega é informativo e não substitui a cotação por CEP.

Quando descriptionIsHtml for verdadeiro, description já foi sanitizada pela aplicação e pode usar saída sem escape no Liquid. Quando for falso, o tema deve manter a saída escapada.

Valores monetários são { amount, currency }, com amount em centavos, ou null quando o preço não pode ser exibido. Use o filtro Liquid money, por exemplo {{ product.price | money }}, e respeite priceVisible e purchasable. price é o menor preço do primeiro conjunto não vazio nesta ordem: itens com estoque físico, itens compráveis por venda sem estoque e itens válidos esgotados. A quantidade mínima permanece uma condição separada de purchasable. Filtros e ordenação usam a mesma prioridade. priceRange = { minimum, maximum } descreve esse conjunto e hasVariablePrices autoriza o texto “A partir de”. Em uma combinação, price já é o preço unitário final (preço-base + ajuste, somados antes do arredondamento): Liquid e navegador nunca devem somá-lo. compareAtPrice é null em produtos com variações porque o legado não fornece preço anterior confiável por combinação.

hasVariants considera tanto os indicadores quanto os relacionamentos comerciais carregados. No contrato V3 os estados são inseparáveis: hasVariants: true sempre implica requiresSelection: true, e hasVariants: false sempre implica requiresSelection: false. Produto variável usa exclusivamente variantes como unidades compráveis; produto simples usa exclusivamente o pai. A antiga flg_subproduto_obrigatorio não é exposta nem decide esse contrato. variantsLoaded distingue o resumo (false, com optionGroups e variants vazios) do detalhe completo (true). Resumos de home, categoria e dataSources já usam combinações reais para preço e disponibilidade sem enviar todas as combinações a cada card.

inStock significa saldo físico positivo pertinente; purchasable também considera estado comercial, venda sem estoque e quantidade mínima. Saldos negativos persistidos pelos fluxos legados significam produto esgotado e são apresentados como stock: 0. Nas combinações, loja_link_subproduto.num_link_estoque = NULL também representa saldo zero: a variante permanece válida, com inStock: false, e só permite compra se a venda sem estoque estiver habilitada e as demais regras comerciais forem atendidas. Essa interpretação não se aplica ao estoque obrigatório do produto simples nem a campos ausentes ou formatos ilegíveis, que continuam interrompendo a normalização em vez de virarem mínimo 1 ou estoque zero. maximumQuantity é o estoque pertinente quando a venda sem estoque não é permitida, e null quando essa camada não deriva um limite. Antes da escolha em todo produto variável, stock e maximumQuantity também são null: isso significa limite ainda não determinado, não estoque ilimitado. A variante retornada pela resolução contém o limite específico. Esses campos são informativos e não reservam estoque; uma futura operação de carrinho deverá revalidá-los no servidor.

Neste MVP, a política central combina o estado individual flg_estado_produto com loja.flg_habilita_precos_loja, loja.flg_ocultar_precos, loja.flg_mostrar_preco_login e loja.flg_preco_apos_login. Quando a loja exige login, somente uma sessão de comprador válida da própria loja autoriza preço: price, compareAtPrice e preços de variações ficam null para visitantes na home, categoria, detalhe e vitrines. Uma vitrine monetária anônima recebe status: 'restricted' sem consultar produtos; uma vitrine não monetária pode listar os produtos com preços ausentes. Após o login, a mesma política libera preços, filtros monetários, variantes, carrinho e checkout. Ocultação global e restrições individuais continuam valendo. O backend resolve a sessão antes de calcular preços, com isolamento por loja e cache privado; flags do navegador e o DTO viewer não autorizam valores. Prévia/editor não usam a sessão do comprador e permanecem restritos. Não há preço personalizado por cliente. Falha de banco continua sendo erro; não é convertida em vitrine vazia ou restrita.

Depois que a IA gera uma proposta para a Home, o laboratório conserva em memória no navegador a lista de arquivos retornada. Trocas entre os contextos suportados e páginas da categoria enviam esses mesmos arquivos ao endpoint autenticado de reapresentação; o servidor reaplica as permissões do editor, limites de tamanho e validação completa sobre uma única fotografia do tema de desenvolvimento. Produtos, preços e identidade continuam sendo carregados no servidor, e o rascunho não é publicado nem gravado no tema padrão.

O rascunho navegável aceita até 30 arquivos. Arquivos textuais mantêm o limite individual de 1 MiB, imagens WebP geradas podem ter até 1,5 MiB depois da decodificação, e a requisição serializada completa fica limitada a 8 MiB em UTF-8. O Base64, a estrutura JSON, os caminhos e os caracteres escapados contam no limite total. A proposta da IA passa pela mesma medição antes de ser oferecida como rascunho navegável; excesso retorna HTTP 413 sem registrar o conteúdo dos arquivos.

js
image = {
  id,
  url,
  thumbUrl,
  originalUrl,
  name,
  type,
  width,
  height,
};

optionGroup = {
  id,
  name,
  options: [{ id, name, image }],
};

variant = {
  id,
  optionIds,
  price,
  compareAtPrice,
  stock,
  lowStock,
  active,
  inStock,
  purchasable,
  minimumQuantity,
  maximumQuantity,
};

Benefícios comerciais e segunda foto na listagem ​

Home, categoria, busca e produtos consultados por dataSources/query_products recebem os mesmos campos. Estão disponíveis para qualquer tema, sem opções visuais obrigatórias. A IA pode editar os componentes Liquid e CSS para mostrá-los; não deve recusar um pedido de parcelamento por ausência de um setting visual. Revisões existentes não são reescritas: adote os campos no rascunho e publique uma nova revisão. Os cards dos temas oficiais já usam estes dados.

  • isNew: marcação de lançamento cadastrada pelo lojista; não deduzir pela data.
  • example: identifica produto demonstrativo na prévia autenticada. Exemplos são excluídos das consultas públicas antes de paginação e facetas; continuam sem capacidade de compra. Mostre sua identificação na prévia, sem deduzir pelo nome.
  • secondaryImage: imagem secundária cadastrada, com o mesmo contrato de mainImage, ou null. Não carrega a galeria completa. Compare os IDs antes de oferecer troca.
  • freeShipping: entrega gratuita deste produto confirmada pelo cadastro e modalidade de frete fixo ativa, com entrega habilitada e sem adicional global em reais. Use “Frete grátis neste produto”; outros itens podem gerar frete. Não transformar retirada, produto digital, benefício por CEP, peso, cupom ou valor mínimo em selo incondicional. Regras condicionais continuam sendo avaliadas na cotação.
  • Cada item de product.variants também recebe paymentOffers, calculado com seu preço e quantidade mínima. product.selectedVariantId, quando presente, identifica a combinação solicitada pela URL. No detalhe, o hook opcional data-product-payment-offers com data-offers-variant alterna os blocos já calculados pelo servidor, sem recalcular dinheiro no navegador. Veja o runtime.
  • No PagBank com juros do comprador e sem duas parcelas sem juros, a oferta informa apenas o teto configurado compatível com a parcela mínima. amount, total e additions ficam nulos e interest é provider; o tema deve informar que valores e juros dependem do cartão no checkout, sem afirmar “sem juros”.
  • paymentOffers = { installments, cash }: cada oferta pode ser null. Respeita preço visível, possibilidade de compra e configurações ativas/exibidas do painel. Valores representam uma unidade sem frete, cupons ou benefícios de carrinho. Compra mínima maior que uma unidade não recebe oferta unitária. O checkout recalcula.
js
paymentOffers = {
  installments: {
    count, amount, total, interest, additions, provider, audience, startingAt,
  },
  cash: { method, label, amount, discount, provider, audience, startingAt },
};

Os campos monetários são objetos money. Em installments, interest: 'none' permite mostrar “Até Xx de VALOR sem juros”. Se additions.amount > 0, informar também o total e o acréscimo da forma de pagamento; não ocultar esse custo. interest: 'provider' significa que valor/juros dependem do cartão: amount, total e additions são null. Mostrar “Até Xx — valores e juros conforme cartão no checkout”; nunca dividir o preço nem afirmar “sem juros”.

Pagar.me usa o cálculo de cartão do checkout. PagBank respeita somente o limite sem juros que o checkout suporta. A listagem e o checkout leem o mesmo cadastro de regras; alterações no responsável pelos juros ou no início das parcelas com juros invalidam a preparação anterior do cartão PagBank. O comprador precisa recalcular antes de continuar. Mercado Pago depende da condição do cartão. Tabelas de juros legadas incompatíveis não geram ofertas; esta funcionalidade não amplia o financiamento aceito no checkout. Entre condições verificáveis, prefere mais parcelas e menor total; uma oferta verificável precede uma dependente de cartão.

cash apresenta o menor preço com desconto efetivo, identificado por label e method (pix, boleto, manual). Aproveita Pix/boleto Pagar.me e os descontos de depósito/Pix manual/pagamento personalizado compatíveis com o checkout. Não atribuir todo desconto à forma Pix. Condições de Pix com adicionais/descontos não suportados pelo gateway são omitidas. audience, quando presente, deve ser exibido (pessoa física/jurídica), assim como provider. startingAt: true exige “A partir de”: variantes podem mudar a condição. Nunca inventar valores quando uma oferta for null, nem usar valores fixos de exemplo no tema da loja.

Para a segunda foto, use os hooks documentados no runtime: imagem principal, secundária e botão nativo fora do link. Hover funciona no mouse; o botão permite toque e teclado, inclusive retorno à primeira foto. Falha na segunda imagem mantém a principal. Toda alteração visual continua pertencendo aos arquivos do tema.

product.video é null ou { url, provider: 'youtube', id, embedUrl, thumbnailUrl }, derivado do link do YouTube cadastrado no produto pelo painel (loja_produto.desc_link_video_produto). embedUrl aponta para o player youtube-nocookie.com e thumbnailUrl para a miniatura oficial do vídeo. Templates Liquid não podem conter <iframe>: os temas oficiais apresentam o vídeo como uma miniatura na galeria (data-gallery-video) e o runtime da plataforma insere o player no container data-gallery-media quando o comprador escolhe essa miniatura, devolvendo a foto ao escolher outra imagem ou opção. Links que não são do YouTube resultam em null e não interrompem a página.

mainImage pode ser null. Na listagem da home, categoria e vitrines, images, optionGroups e variants são arrays vazios e variantsLoaded é falso; o resumo comercial calculado no servidor permanece disponível nos campos do produto. Os dados completos aparecem apenas no contexto de produto. Opções inativas e combinações incoerentes nunca são escolhas comerciais válidas, e a ausência de uma combinação é diferente de uma combinação existente com inStock: false.

Alerta de estoque baixo — Está Acabando ​

product.lowStock e variant.lowStock são sinais booleanos calculados nativamente pelo Node, sem ativação ou consulta a aplicativo. A presença do aviso nos arquivos Liquid define se o tema apresenta esse recurso. O limite vem de loja_produto.num_estoque_minimo para produto simples e de loja_link_subproduto.num_link_estoque_critico para a combinação selecionada. Esses booleanos preservam o limite comercial cadastrado. Não dependem do antigo aplicativo “Está Acabando” do admin_loja. O tema pode usar esse sinal pronto ou definir seu próprio limite de apresentação comparando o saldo real disponível.

Para um produto simples, por exemplo, a IA pode exibir o aviso somente entre uma e cinco unidades, sem configuração adicional no admin:

liquid
{% if product.requiresSelection == false and product.visible and product.priceVisible and product.purchasable and product.stock != nil and product.stock > 0 and product.stock <= 5 %}
  <p>Está acabando! Últimas unidades.</p>
{% endif %}

O número 5, o texto e o CSS pertencem ao tema. stock é o saldo físico, não o limite de compra. Não apresente escassez para estoque zero com venda por encomenda, preço oculto, compra indisponível ou produto variável sem seleção. Essa condição muda somente a apresentação, nunca a reserva ou as validações de estoque.

O alerta exige limite positivo, saldo real maior que zero e menor ou igual ao limite, produto visível, compra permitida e preço público. Saldo insuficiente para o mínimo de compra sem venda por encomenda não gera urgência. Limite ausente, zero ou negativo desativa o aviso; formato inválido é registrado e omite o aviso sem interromper a compra. Venda sem estoque com saldo zero também não gera aviso. Com saldo positivo, a regra continua indicando somente o estoque físico baixo.

Produto variável mantém product.lowStock = false antes da seleção; cada variante usa exclusivamente seu próprio limite, sem herdar o do pai. Produtos simples também fornecem o sinal nos resumos de home, categoria e vitrines; cada tema decide se o utiliza. Não inferir escassez agregando estoques de variantes nos cards. Nenhum saldo, maximumQuantity, validação do carrinho ou checkout é substituído pelo limite crítico. Isso difere explicitamente do V2, que podia apresentar o limite crítico no lugar de um saldo real maior. O aviso não reserva estoque nem faz atualização contínua de saldo enquanto a página permanece aberta.

O tema escolhe texto, posição e CSS. Use um elemento opcional dentro de [data-product-detail], mantendo-o presente e oculto quando o sinal for falso:

liquid
<p data-product-low-stock role="status" aria-live="polite"{% unless product.lowStock %} hidden{% endunless %}>Últimas unidades</p>

Em cada [data-product-variant], declare data-low-stock="{% if variant.lowStock %}true{% else %}false{% endif %}". O runtime compartilhado atualiza apenas hidden, preservando o texto do tema; seleção incompleta, inválida ou esgotada oculta o aviso. Para adotar um limite visual próprio em produtos variáveis, calcule o booleano em Liquid usando variant.stock > 0 and variant.stock <= 5, também exigindo variant.purchasable e product.priceVisible, e use o resultado em data-low-stock de cada opção [data-product-variant]. Preserve os demais atributos funcionais. Mantenha [data-product-low-stock] inicialmente oculto até uma combinação ser selecionada; o runtime usa o sinal daquela combinação, sem somar estoques. Aura e Default exibem o aviso próximo à compra; outros temas podem adotar o mesmo hook sem copiar lógica funcional. Revisões publicadas recebem a apresentação somente em uma nova revisão explícita.

Página e contextos ​

Contato usa o papel opcional contact em theme.json, apontando para um template livre como templates/contact.json. /contato recebe o contexto global e page.type = 'contact', título e SEO. /contato?produto=ID acrescenta o product da própria loja. Nome e imagem no formulário vêm desse objeto, nunca da query. capabilities.contact informa se backend e revisão suportam o formulário; na prévia permite visualizar sem enviar. Os vinte temas oficiais incluem esse papel, a section de contato e links no produto/rodapé. Revisões anteriores sem o papel continuam válidas; o sistema não injeta apresentação em bundles publicados. Use os hooks da seção Contato e dúvidas de produtos do contrato do runtime. Não criar configuração visual paralela, destinatário editável no tema ou chamada direta a SMTP. A publicação de uma nova revisão é necessária nas lojas instaladas.

Adicionar contato a uma revisão antiga pelo editor: se o pedido exige a página de contato ou dúvidas de produto e o manifesto não declara contact, solicite a preparação oficial com prepareContact: true, patch: "", images: [] e question: null. Essa resposta é interna: o servidor prepara os arquivos oficiais e chama a edição novamente na mesma tarefa em segundo plano. Não use essa preparação para mudanças de cor, textos ou links para WhatsApp; não a solicite para contatos personalizados já declarados. A exceção é um contato preparado anteriormente em templates/platform_contact_v1.json que ainda não tem o marcador /* LojaVirtual: contact presentation v1 */ em assets/theme.css: quando o lojista pedir para corrigir sua apresentação, solicite prepareContact para acrescentar somente os estilos básicos, preservando o formulário e o rascunho. Se faltar informação essencial, faça a pergunta antes da preparação, sem alterações.

A plataforma cria templates/platform_contact_v1.json e sections/platform_contact_v1.liquid com o formulário oficial, exclusivamente no rascunho. Acrescenta também uma base responsiva a assets/theme.css, sem remover o CSS anterior: largura de leitura, espaçamento, labels, campos, botão, foco e legend acessível. As regras ficam restritas a .contact-page na camada CSS lojavirtual-contact, de menor prioridade que regras comuns do tema. Não dependem de utilitários ou variáveis exclusivos do Aura. A IA pode personalizar por regras fora dessa camada, preservando a base e as demais páginas. Acrescenta somente templates.contact ao manifesto efetivo da prévia, do ZIP exportado e da nova revisão publicada. Nunca substitui arquivos existentes nesses caminhos: colisões exigem revisão técnica. Temas com controladores anteriores ao runtime compartilhado também exigem atualização técnica antes do contato. O manifesto e assets/theme.js continuam somente leitura. A IA não cria templates; a existência de um arquivo arbitrário templates/contact.json não habilita contato. Ler um tema ou editar outros arquivos nunca executa a preparação.

Ao receber os arquivos preparados, retorne prepareContact: false, adapte a aparência do formulário ao tema e inclua o botão solicitado por patch localizado. Preserve a composição oficial do template durante a preparação e todos os campos, hooks, condicionais e destino do formulário. Não gere o formulário do zero. Antes de devolver a proposta, o servidor renderiza o contato e verifica formulário, destino, campos obrigatórios, produto e hooks de envio. Uma adaptação que remova esses elementos é recusada. A preparação não se repete quando os estilos já estão presentes. Contato já declarado mantém seu caminho e seu formulário; a correção de apresentação descrita acima apenas acrescenta o CSS ausente. Se a edição falhar ou pedir esclarecimento, a preparação em memória é descartada; o rascunho anterior e a loja publicada permanecem intactos. Uma preparação válida é informada explicitamente no resumo, mesmo se não houver patch visual adicional.

O template pode compor sections livremente. O formulário usa data-contact-form, method="post" e action="{{ '/api/contact' | storefront_url }}". Inclua labels e campos name, email, phone opcional e message, o honeypot oculto website e, quando houver product, um campo oculto productId com product.id. Agrupe os campos visíveis em fieldset; mantenha o submit e [data-contact-message] com role="status" e aria-live="polite" fora dele. O runtime faz o envio; não crie JavaScript, tokens ou destinatário no tema. Para dúvidas, use o link {{ '/contato?produto=' | append: product.id | storefront_url }} condicionado a capabilities.contact. Adapte o CSS ao tema atual, sem substituir seu layout. Nome, e-mail e mensagem são obrigatórios, com limites de 2–150, até 100 e 10–5.000 caracteres, respectivamente; telefone tem até 45 caracteres.

Na resposta, explique que página e botão foram preparados no rascunho e precisam de revisão e publicação. Se não houver preparação nem patch aplicável, explique o motivo e o próximo passo em linguagem de lojista, sem afirmar que o recurso foi instalado.

Home

js
page = {
  type: 'home',
  products: product[]
}

Além de page, a home recebe o contexto global (shop, catalog e content).

Categoria recebe o contexto global, page = { type: 'category' } e o objeto raiz category, incluindo category.products e category.pagination.

Categoria e busca recebem também listing, a fonte compartilhada de produtos, total, ordenação, facets reais, filtros ativos com URLs de remoção e paginação que preserva a query. category.products e category.pagination são aliases de compatibilidade. Opções de variante possuem value opaco gerado pelo servidor; Liquid somente o devolve em option=<valor>. Filtros usam formulários GET e não devem recalcular regras comerciais.

Nos vinte temas oficiais, components/listing_results.liquid compõe uma barra com Filtrar, total e ordenação. O details.listing-filters começa sem open em todas as larguras, inclusive sem JavaScript. Seu summary abre um painel ancorado na barra, com grupos de filtros e rolagem limitada à altura da janela. No celular, a ordenação ocupa outra linha e os grupos ficam em uma coluna. Não é um modal: o foco não fica preso no painel. O JavaScript visual fecha ao clicar ou mover o foco para fora; Escape fecha e devolve o foco ao acionador. Sem JavaScript, abrir/fechar e enviar os formulários continuam nativos; Escape e fechamento externo são melhorias do JavaScript.

Os filtros ativos ficam fora do painel recolhido, com remoção individual e Limpar filtros. O acionador mostra sua quantidade. Ao ordenar, preserve filtros, termo de busca e tamanho da página; ao filtrar, preserve ordenação, termo e tamanho da página. Ambos omitem page para reiniciar a paginação. Use as URLs prontas de remoção, limpeza e paginação, incluindo o namespace da prévia. listing_filters.liquid só apresenta preço quando autorizado pelos dados, marcas e variantes disponíveis, além do controle existente de disponibilidade.

Os campos GET priceMin e priceMax são opcionais: ausentes ou vazios significam sem limite naquele lado, inclusive sem JavaScript. Zero é um limite válido. Valores preenchidos aceitam até duas casas decimais, com ponto ou vírgula, de 0 a 999999999,99; o mínimo não pode superar o máximo. Arrays e valores malformados continuam sendo recusados pelo servidor. Nos formulários GET com inputs type="number" e esses nomes, o runtime compartilhado apresenta a validação nativa junto ao campo antes do envio, incluindo intervalos invertidos. Preserve min="0" e step="0.01". A navegação permanece GET, sem fetch ou cálculo de produtos no navegador. Revisões com controladores próprios não recebem essa melhoria do runtime; a aceitação de campos vazios no servidor independe da revisão do tema.

Essa apresentação é uma escolha dos bundles oficiais, não uma estrutura visual obrigatória do V3. Temas externos podem usar outras composições com o mesmo contrato comercial. Não há novo setting, endpoint ou hook no runtime compartilhado. Lojas já publicadas recebem essas mudanças apenas por uma nova revisão explícita.

Busca usa o template semântico search e recebe page = { type: 'search' }, search = { term } e listing. A rota pública é /busca?q=...; termo vazio não carrega o catálogo e páginas de busca usam noindex,follow.

O laboratório e o editor oferecem Busca como contexto de prévia. O formulário navega por GET dentro da sessão temporária e preserva os mesmos arquivos ainda não publicados usados nos demais contextos.

Produto recebe o contexto global, page = { type: 'product' } e o objeto raiz product, incluindo galeria (images), optionGroups e variants.

Página institucional recebe o contexto global e:

js
page = {
  type: 'static',
  id,
  title,
  slug,
  content,
  contentIsHtml,
  seo: {
    title,
    description,
  },
};

O conteúdo editorial marcado pela aplicação como HTML é previamente sanitizado. Somente use saída sem escape para page.content quando page.contentIsHtml for verdadeiro; os demais valores devem permanecer escapados.

Temas V3 · Liquid estrutura, CSS desenha, JSON compõe.