Guia do tema em código da Hystore

Um tema em código da Hystore é uma pasta de arquivos Liquid, CSS e JSON que desenha a vitrine da loja: cabeçalho, rodapé, início, loja, páginas de produto, notícias, jogadores. O código da própria loja cuida do carrinho, do pagamento, da conta e do login, que nunca carregam o tema.

Este guia é a referência para pessoas e para assistentes de IA que editam um tema. Tudo aqui é conferido pelos servidores da Hystore: um arquivo que quebra uma regra é recusado ao salvar, com o arquivo, a linha e o motivo.

Fluxo de trabalho

npx @hystudios/hystore login            # aprove no painel (sem token para colar)
npx @hystudios/hystore theme pull       # baixe o rascunho para esta pasta
npx @hystudios/hystore theme dev        # acompanhe a pasta, envie a cada gravação, prévia ao vivo
npx @hystudios/hystore theme check      # confira na sua máquina, sem enviar
npx @hystudios/hystore theme push       # envie as mudanças para o rascunho
npx @hystudios/hystore theme publish    # peça a publicação; quem tem permissão aprova no painel
npx @hystudios/hystore theme versions   # as últimas 30 versões publicadas
npx @hystudios/hystore theme rollback 3 # traga a versão 3 de volta para o rascunho
npx @hystudios/hystore theme new        # comece uma pasta a partir do tema Base da Hystore

• As edições vão sempre para o rascunho. A loja no ar só muda quando um pedido de publicação é aprovado no painel (Personalização > Tema em código).
• O link de prévia (do theme dev) mostra o rascunho no endereço real da loja por 24 horas e recarrega sozinho a cada envio.
• Se alguém mudou um arquivo no painel depois do seu último pull, o envio desse arquivo é recusado como conflito: faça o pull, junte e envie de novo.

Regras fixas

Isto é recusado (o arquivo não é salvo):

• <script>, <style>, <iframe>, <form>, <input>, <textarea>, <select>, <object>, <embed>, <base>, <meta>, <link>, <foreignObject> de SVG.
• Atributos de evento (onclick, onload, ...), links javascript:, vbscript: e data: (exceto data:image/png|jpeg|gif|webp;base64), srcdoc, http-equiv, referências numéricas de caractere (&#...;): escreva o próprio caractere.
• No CSS: @import, expression(), behavior, -moz-binding, @namespace, @document, image-set(), escapes com barra invertida fora de strings, e url() que não seja assets/<nome>, um arquivo https://fonts.gstatic.com/... ou uma imagem pequena data:image/...;base64. A classe hystore-required é reservada.
• As tags Liquid include, layout e block (use render, o arquivo de layout e hystore_block).

Não existe JavaScript nas páginas do tema. A interação vem de atributos data-hystore-* e de elementos <hystore-*> (veja Peças interativas). A loja limpa o HTML desenhado de novo, e a política de segurança de conteúdo bloqueia scripts. O que precisa de JavaScript vai num app isolado (veja Apps).

Um tema só lê dados públicos da loja e o nick e a skin de quem está olhando. Ele nunca vê saldo, e-mail, pedido ou pagamento, e não muda preços: a compra passa por data-hystore-add-to-cart, tratado pela loja.

Pasta

theme.json                 nome, modos de cor, configurações gerais (obrigatório)
layout/theme.liquid        moldura de todas as páginas; precisa mostrar {{ content }} (obrigatório)
pages/<página>.liquid      um arquivo por página (pages/home.liquid é obrigatório)
templates/<página>.json    seções de uma página, em ordem, editáveis em "Personalizar tema"
sections/<nome>.liquid     blocos com um {% schema %}, usados por templates ou {% section %}
components/<nome>.liquid   peças usadas com {% render 'nome' %}
styles/<nome>.css          todos os arquivos são carregados, em ordem de nome
locales/pt.json en.json es.json   textos do filtro | t
config/values.json         valores escolhidos em "Personalizar tema"
assets/<nome>.<ext>        imagens (png, jpg, webp, gif, avif até 3 MB) e fontes (woff, woff2 até 1 MB)
apps/<app>/<arquivo>       apps isolados com JavaScript: html, js, css, json (veja Apps)

• Nomes: letras minúsculas, números, - e _, um nível dentro de cada pasta (sections/hero.liquid, não sections/home/hero.liquid); apps usam dois (apps/roleta/app.js).
• Limites: 400 arquivos de texto, 256 KB por arquivo, 5 MB de texto; 100 arquivos de mídia, 40 MB. Arquivos SVG não entram como mídia (<svg> direto no Liquid pode).
• Páginas: home, shop, category, product, search, news, post, page, players, 404, maintenance. Uma página que o tema não tem é desenhada pelo layout clássico da loja.

Carrinho (/carrinho), pagamento, perfil (/perfil), compras, senha e entrar (/entrar) são páginas da própria loja: aponte links para elas, nunca as refaça.

theme.json

{
  "name": "Meu tema",
  "version": "1.0.0",
  "author": "Eu",
  "color_modes": ["dark", "light"],
  "settings": [
    { "id": "accent", "type": "color", "label": "Cor de destaque", "default": "" },
    { "id": "radius", "type": "range", "label": "Arredondamento", "min": 0, "max": 28, "default": 14 },
    { "id": "show_search", "type": "checkbox", "label": "Busca no cabeçalho", "default": true }
  ]
}

• color_modes: os modos que o tema desenha (dark, light); escuro quando ausente. No modo claro a página não tem a classe dark no <html>: estilize com html:not(.dark) ... ou html.dark ....
• Tipos de configuração: text, textarea, richtext, image, url, color, number, range (min, max, step), checkbox, select (options: textos ou { "value", "label" }), product, category, server, list (linhas de texto). Até 60 configurações, id em minúsculas.
• As configurações gerais são {{ settings.<id> }} em qualquer lugar, e cores e números também viram variáveis CSS --theme-<id> na raiz do tema.
• A cor primária da loja é hsl(var(--primary)) (texto sobre ela: hsl(var(--primary-foreground))).

config/values.json guarda o que o dono da loja escolheu: { "settings": { "accent": "#ff5500" } }. Mantenha esse formato ao editá-lo.

Layout e páginas

layout/theme.liquid envolve todas as páginas e precisa ter {{ content }} onde a página entra. A loja põe uma área obrigatória depois do tema (anúncios nos planos gratuitos, links legais); ela não pode ser escondida nem estilizada.

Uma página é pages/<página>.liquid, templates/<página>.json ou os dois. Com os dois, o arquivo da página põe as seções do template com {{ template_sections }}.

{%- comment -%} pages/home.liquid {%- endcomment -%}
<div class="intro">{{ 'home.welcome' | t }}</div>
{{ template_sections }}

Seções

Uma seção é sections/<nome>.liquid, terminando com um {% schema %}:

<section class="hero">
  <h1>{{ section.settings.title | default: store.name }}</h1>
  {%- for block in section.blocks -%}
    <p>{{ block.settings.text }}</p>
  {%- endfor -%}
</section>
{% schema %}
{
  "name": "Destaque",
  "settings": [
    { "id": "title", "type": "text", "label": "Título", "default": "" }
  ],
  "blocks": [
    { "type": "line", "name": "Linha", "settings": [{ "id": "text", "type": "text", "label": "Texto" }] }
  ]
}
{% endschema %}

• section é { id, type, settings, blocks }; as configurações vêm com os padrões. Uma seção vê o que a página dela vê (product, dados carregados...).
• Um template lista seções (no máximo 40 desenhadas por página):

{
  "sections": {
    "hero": { "type": "hero", "settings": { "title": "Bem-vindo" } },
    "news": { "type": "latest-news", "disabled": true }
  },
  "order": ["hero", "news"]
}

type é o nome do arquivo em sections/; "disabled": true esconde.

• {% section 'hero' %} desenha uma seção num lugar fixo (layout, página); os valores vêm de config/values.json em sections.hero.settings.

Componentes

components/<nome>.liquid, usados com {% render 'nome', chave: valor %}. Um componente vê só o que recebe (mais as variáveis globais).

{% render 'product-card', product: item %}

Textos em três línguas

locales/pt.json, en.json e es.json guardam textos (objetos aninhados podem). {{ 'nav.shop' | t }} mostra o texto na língua de quem visita, caindo no português e depois na própria chave. Um arquivo de língua faltando é um aviso.

Dados

Em todo lugar:

Mais dados, quando precisar, com {% load %} (no máximo 24 por página; o mesmo carregamento é buscado uma vez só):

{% load products, limit: 8, featured: true as featured %}
{% for p in featured %}{% render 'product-card', product: p %}{% endfor %}

• Produto: id, name, slug, url, price, original_price, on_sale, image, short_description, description (HTML), duration_days, min_quantity, featured, sold_out, digital, category_slug, server_id.
• Categoria: id, name, slug, url, description, image, product_count.
• Post: id, title, slug, url, author, image, excerpt, content (HTML), published_at.

Filtros

Da Hystore:

• t: texto na língua de quem visita, {{ 'cart.add' | t }}.
• money: preço na moeda da loja, {{ product.price | money }}.
• asset_url: endereço de uma mídia enviada, {{ 'logo.webp' | asset_url }}.
• skin_url: cabeça do Minecraft de um nick, {{ customer.nick | skin_url: 64 }}.
• raw: só para HTML que a loja já limpou (product.description, post.content). Todo o resto é escapado.

Do Liquid: abs, append, at_least, at_most, capitalize, ceil, compact, concat, date, default, divided_by, downcase, escape, escape_once, first, floor, join, json, last, lstrip, map, minus, modulo, newline_to_br, plus, prepend, remove, remove_first, replace, replace_first, reverse, round, rstrip, size, slice, sort, sort_natural, split, strip, strip_html, strip_newlines, sum, times, truncate, truncatewords, uniq, upcase, url_decode, url_encode, where.

Tags: if/elsif/else, unless, case/when, for (break, continue), assign, capture, echo, liquid, comment, raw, cycle, increment, decrement, tablerow, mais render, section, load, hystore_block, schema.

Blocos prontos

{% hystore_block 'nome', chave: valor %} põe uma peça da loja que precisa de dados ao vivo ou da lógica da loja:

heading, image, button, icon, video, card, testimonial, countdown, banner, spacer, divider, server-hero, products, featured-product, categories, servers, ranking, top-supporter, goal, news, discord, launcher, server-status, server-ip, socials, logo, menu, account-actions, language, color-mode, legal-links, copyright.

O nome vai entre aspas. As opções são texto, números ou true/false.

Peças interativas

Atributos (a loja faz o trabalho, sem JavaScript no tema):

Elementos que a loja preenche: <hystore-cart-count>, <hystore-account> (entrar ou o menu da conta; com data-cart mostra também o botão do carrinho da loja), <hystore-server-status>, <hystore-online-players>, <hystore-search data-placeholder="...">, <hystore-skin data-nick="Steve" data-size="128">, <hystore-video data-youtube="<id ou link>">, <hystore-app data-app="<nome>"> (um app isolado, veja Apps).

Links dentro da loja (<a href="/loja">) trocam de página sem recarregar; páginas de conta e pagamento sempre abrem como página nova.

Imagens e fontes

Ponha em assets/ (a ferramenta envia; o servidor confere os bytes).

<img src="{{ 'banner.webp' | asset_url }}" alt="{{ store.name }}">

@font-face { font-family: "Display"; src: url(assets/display.woff2) format("woff2"); font-display: swap; }
.hero { background-image: url(assets/banner.webp); }

Apps

Um app é uma pequena página com JavaScript (calculadora, roleta de prêmios, mini jogo, animação) que o tema coloca com <hystore-app data-app="roleta"></hystore-app>. Ele fica em apps/<app>/ e começa pelo index.html:

apps/roleta/index.html   a página (obrigatória)
apps/roleta/app.js       o script
apps/roleta/app.css      o estilo
apps/roleta/app.json     { "name": "Roleta de prêmios", "height": 420, "permissions": ["customer"] }

Ele roda isolado, num quadro em outro domínio (hystoreapps.cloud): sem rede (fetch, XHR e WebSocket bloqueados), sem cookies nem armazenamento, sem formulários, sem janelas novas, e não consegue mudar nem navegar a página da loja. Ele fala com a loja só pela ponte:

<script src="/sdk/v1.js"></script>
<script src="app.js"></script>

hystore.products({ category: 'vips', limit: 6 }).then(function (products) {
  // [{ id, name, url, price, priceText, originalPrice, onSale, image, shortDescription, ... }]
});
hystore.categories();                    // categorias ativas
hystore.addToCart(productId, 1);         // 'added', ou 'login' (a loja pede para entrar)
hystore.navigate('/loja');               // uma página da loja
hystore.open('cart');                    // 'cart' | 'login' | 'account' | 'search'
hystore.context();                       // { locale, colorMode, store: { name, currency } }
hystore.customer();                      // { loggedIn, nick, skinUrl }, só com "customer" no app.json
hystore.resize(600);                     // ou hystore.autosize() para seguir a página

• Tudo é dado público: o preço vem da loja, e o carrinho recebe só o id do produto. Páginas de dinheiro e de conta nunca mostram apps.
• Carregue só os arquivos do próprio app e o /sdk/v1.js; scripts e estilos de outros sites, quadros e formulários são recusados ao salvar. Imagens podem ser imagens data: ou as imagens e fontes do tema pelo endereço completo (https://theme-assets.hystore.com.br/..., como GET /v1/theme/assets e a ferramenta list_assets do MCP informam).
• app.json é opcional: height de 40 a 2000 pixels (320 se faltar), name para leitores de tela, permissions só customer.
• Limites: 10 apps por tema, 20 arquivos e 512 KB por app.
• Mensagens demais são ignoradas; pôr no carrinho e trocar de página têm limites próprios, pequenos.

Antes de publicar

• npx @hystudios/hystore theme check sem erros.
• Todo texto que o visitante lê passa por | t, em pt, en e es.
• O tema funciona nos modos de cor que declara e no celular.
• Os links de carrinho, conta e login apontam para /carrinho, /perfil e /entrar (ou usam data-hystore-open).