@unbox-plus/cli 0.20.4

package/template/lib/editable/rastreio-navegacao.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+// PAGE_VIEW POR ROTA (foundation 12): a parte de CLIENTE do rastreio. Quem monta os scripts é o
+// `<Rastreio>` de rastreio.tsx (servidor); este hook só avisa cada provedor que a página mudou.
+//
+// Dispara o page_view de cada NAVEGAÇÃO do App Router para quem NÃO conta a navegação sozinho: Meta
+// Pixel (fbq), TikTok Pixel (ttq) e Pinterest Tag (pintrk). O snippet de cada um só conta o
+// carregamento inicial; a navegação SPA não recarrega a página, e sem este hook a segunda página não
+// existe para nenhum deles.
+//
+// UM DONO DO PAGE_VIEW POR PROVEDOR. O GA4 fica DE FORA deste hook, de propósito: o gtag.js, com a
+// medição otimizada ligada (é o padrão de todo fluxo de dados do GA4), já manda um page_view a cada
+// mudança de histórico do navegador, que é exatamente o que a navegação do App Router faz (pushState).
+// Mandar outro daqui contava DUAS visualizações por navegação (Astra, B3). `send_page_view: false` não
+// resolveria: ele desliga só o page_view do carregamento, não a medição de mudanças de histórico.
+// Referência: https://developers.google.com/analytics/devguides/collection/ga4/views (page_view em
+// aplicações de página única). Meta, TikTok e Pinterest não acompanham o histórico: cada um precisa do
+// aviso, e é daqui que ele sai.
+//
+// QUEM ESTÁ NA PÁGINA é decidido no servidor (`rastreioEmVigor`): o que o lojista publicou no painel
+// vence o ambiente, e cada provedor é injetado UMA vez. Um provedor que não entrou não existe em
+// `window`, e este hook não o chama. É assim que ele nunca dispara o mesmo provedor duas vezes: um
+// script por provedor na página, uma chamada por provedor por navegação.
+//
+// CARREGAMENTO INICIAL: quem já conta sozinho (gtag 'config', fbq PageView, ttq.page, pintrk page) é
+// pulado. Quando NENHUM deles está na página, o page_view de entrada vai direto no dataLayer, que é de
+// onde os contêineres de GTM leem (o central da Unbox e o próprio da marca). Sem isso, uma loja só com
+// GTM ficava sem o evento de entrada.
+import * as React from "react";
+import { usePathname } from "next/navigation";
+
+type Rastreadores = {
+  gtag?: (...a: unknown[]) => void;
+  fbq?: (...a: unknown[]) => void;
+  ttq?: { page?: () => void };
+  pintrk?: (...a: unknown[]) => void;
+  dataLayer?: unknown[];
+};
+
+export function PageViewPorRota() {
+  const pathname = usePathname();
+  const first = React.useRef(true);
+
+  React.useEffect(() => {
+    const w = window as unknown as Rastreadores;
+    const primeiro = first.current;
+    first.current = false;
+
+    const contadoPorOutro = typeof w.gtag === "function" || typeof w.fbq === "function" || typeof w.ttq?.page === "function" || typeof w.pintrk === "function";
+    if (primeiro && contadoPorOutro) return;
+
+    // o GA4 (gtag) não está aqui de propósito: ele conta a navegação sozinho (ver o topo do arquivo)
+    try { w.fbq?.("track", "PageView"); } catch { /* ignora */ }
+    try { w.ttq?.page?.(); } catch { /* ignora */ }
+    try { w.pintrk?.("page"); } catch { /* ignora */ }
+    // sem gtag, o page_view vai direto no dataLayer: é dele que todos os contêineres de GTM leem
+    try {
+      if (typeof w.gtag !== "function" && Array.isArray(w.dataLayer)) {
+        w.dataLayer.push({ event: "page_view", page_path: pathname });
+      }
+    } catch { /* ignora */ }
+  }, [pathname]);
+
+  return null;
+}

package/template/lib/editable/rastreio.tsx

@@ -0,0 +1,168 @@
+// RASTREIO E MARKETING DA LOJA: o que entra na página, decidido em UM lugar (foundation 12).
+//
+// O app/layout.tsx da loja chama só isto, numa linha:
+//
+//   <Rastreio doc={conteudo} ambiente={process.env} unboxGtmId={UNBOX_GTM_ID} />
+//
+// e não conhece provedor nenhum. Daqui saem o contêiner central da Unbox (contrato: sempre ligado), o
+// contêiner PRÓPRIO do lojista, o Google Analytics 4, o Meta Pixel, o TikTok Pixel, a Pinterest Tag, o
+// page_view de cada navegação e o botão flutuante de WhatsApp. O próximo provedor entra por versão da
+// foundation, sem tocar no layout de loja nenhuma: foi o dono que recusou reescrever os sites a cada
+// capacidade nova.
+//
+// QUEM DECIDE O QUE ENTRA é `rastreioEmVigor` (document.ts): o que o lojista publicou na aba Apps do
+// painel vence o valor do ambiente, provedor a provedor, e cada provedor entra UMA vez. Este arquivo só
+// desenha o snippet de cada valor em vigor. O contêiner da Unbox não passa por essa regra: é contrato,
+// entra sempre, e o contêiner próprio do lojista só entra se for OUTRO (os dois leem o mesmo dataLayer;
+// o mesmo ID duas vezes seria o mesmo contêiner carregado em dobro).
+//
+// SERVIDOR SÓ: lê `process.env` inteiro (as variáveis são conhecidas pelo nome, `VARIAVEIS_DE_RASTREIO`),
+// e o que chega ao navegador é o snippet com o ID, que já é público de qualquer jeito. A parte que
+// precisa de hook de cliente (o page_view por rota) mora em rastreio-navegacao.tsx. Não importe este
+// arquivo de um componente de cliente.
+//
+// Os IDs chegam validados pela régua de formato (`recusaDeRastreio`): só letras, números e hífen, que
+// é o que permite interpolá-los dentro de um script inline sem escapar nada. O número e a mensagem do
+// WhatsApp vão num `href` (o React escapa o atributo) e a mensagem passa por encodeURIComponent em
+// `linkDoWhatsapp` (document.ts), que não lança nem para documento gravado com mensagem quebrada: este
+// componente está no layout de toda página, e uma exceção aqui derrubava a loja inteira.
+//
+// PAGE_VIEW: cada provedor tem UM dono. O GA4 conta a navegação sozinho (medição otimizada de mudanças
+// de histórico, ligada por padrão); Meta, TikTok e Pinterest não, e é `PageViewPorRota`
+// (rastreio-navegacao.tsx) que os avisa. O porquê está no comentário de lá.
+//
+// OS SCRIPTS SÓ MUDAM QUANDO O LOJISTA PUBLICA: é o documento publicado que chega aqui. E a camada herda
+// o comportamento de consentimento que a loja já tem: ela não põe banner, não segura pixel nem libera
+// nada a mais (ver README, "Apps: rastreio e marketing").
+import Script from "next/script";
+import { linkDoWhatsapp, rastreioEmVigor, type Ambiente, type ContentDocument } from "./document";
+import { PageViewPorRota } from "./rastreio-navegacao";
+
+const SNIPPET_GTM = (id: string) =>
+  `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer','${id}');`;
+
+/** um contêiner do Google Tag Manager: o noscript e o loader. `chave` distingue o da Unbox do próprio. */
+function Gtm({ id, chave }: { id: string; chave: string }) {
+  return (
+    <>
+      <noscript>
+        <iframe src={`https://www.googletagmanager.com/ns.html?id=${id}`} height="0" width="0" style={{ display: "none", visibility: "hidden" }} />
+      </noscript>
+      <Script id={chave} strategy="afterInteractive">
+        {SNIPPET_GTM(id)}
+      </Script>
+    </>
+  );
+}
+
+function Ga4({ id }: { id: string }) {
+  return (
+    <>
+      <Script src={`https://www.googletagmanager.com/gtag/js?id=${id}`} strategy="afterInteractive" />
+      <Script id="ga4" strategy="afterInteractive">
+        {`window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}gtag('js',new Date());gtag('config','${id}');`}
+      </Script>
+    </>
+  );
+}
+
+function MetaPixel({ id }: { id: string }) {
+  return (
+    <Script id="meta-pixel" strategy="afterInteractive">
+      {`!function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,document,'script','https://connect.facebook.net/en_US/fbevents.js');fbq('init','${id}');fbq('track','PageView');`}
+    </Script>
+  );
+}
+
+function TiktokPixel({ id }: { id: string }) {
+  return (
+    <Script id="tiktok-pixel" strategy="afterInteractive">
+      {`!function(w,d,t){w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie","holdConsent","revokeConsent","grantConsent"],ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e},ttq.load=function(e,n){var r="https://analytics.tiktok.com/i18n/pixel/events.js",o=n&&n.partner;ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=r,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};n=document.createElement("script");n.type="text/javascript",n.async=!0,n.src=r+"?sdkid="+e+"&lib="+t;e=document.getElementsByTagName("script")[0];e.parentNode.insertBefore(n,e)};ttq.load('${id}');ttq.page();}(window,document,'ttq');`}
+    </Script>
+  );
+}
+
+function PinterestTag({ id }: { id: string }) {
+  return (
+    <>
+      <Script id="pinterest-tag" strategy="afterInteractive">
+        {`!function(e){if(!window.pintrk){window.pintrk=function(){window.pintrk.queue.push(Array.prototype.slice.call(arguments))};var n=window.pintrk;n.queue=[],n.version="3.0";var t=document.createElement("script");t.async=!0,t.src=e;var r=document.getElementsByTagName("script")[0];r.parentNode.insertBefore(t,r)}}("https://s.pinimg.com/ct/core.js");pintrk('load','${id}');pintrk('page');`}
+      </Script>
+      <noscript>
+        {/* pixel 1x1 de quem está sem JavaScript: não é imagem da página, e next/image não se aplica */}
+        {/* eslint-disable-next-line @next/next/no-img-element */}
+        <img height="1" width="1" style={{ display: "none" }} alt="" src={`https://ct.pinterest.com/v3/?tid=${id}&noscript=1`} />
+      </noscript>
+    </>
+  );
+}
+
+// ── BOTÃO FLUTUANTE DE WHATSAPP ──────────────────────────────────────────────────────────────────
+//
+// Abre wa.me/<numero>?text=<mensagem> numa aba nova. Só existe com número em vigor; sem número o
+// layout fica exatamente como era. Padrão do CTA flutuante de uma loja piloto (components/floating-cta.tsx):
+// fixo, some no checkout junto com o resto do chrome (`.site-chrome`, regra que as lojas já têm em
+// globals.css) e no celular sobe acima da barra de navegação inferior. Canto direito, para não disputar
+// o centro com o CTA de compra.
+//
+// O CSS vai inline, num <style> próprio, de propósito: a foundation é copiada para lojas com Tailwind
+// configurado de jeitos diferentes, e uma classe utilitária que a loja não gera vira botão sem estilo.
+// Ícone só, sem texto visível: o rótulo está em `aria-label`/`title`. Não há copy aqui para o lojista
+// editar (`data-editor-ignore`): número e mensagem são configuração, e se editam na aba Apps.
+const CSS_DO_BOTAO = `.unbox-whatsapp{position:fixed;right:16px;bottom:96px;z-index:40;display:flex;align-items:center;justify-content:center;width:56px;height:56px;border-radius:9999px;background:#25D366;color:#fff;box-shadow:0 10px 28px rgba(0,0,0,.28);transition:transform .15s ease}.unbox-whatsapp:hover{transform:scale(1.05)}.unbox-whatsapp:focus-visible{outline:2px solid #25D366;outline-offset:2px}@media (min-width:768px){.unbox-whatsapp{right:24px;bottom:24px}}`;
+const CAMINHO_DO_ICONE =
+  "M17.472 14.382c-.297-.149-1.758-.867-2.03-.967-.273-.099-.471-.148-.67.15-.197.297-.767.966-.94 1.164-.173.199-.347.223-.644.075-.297-.15-1.255-.463-2.39-1.475-.883-.788-1.48-1.761-1.653-2.059-.173-.297-.018-.458.13-.606.134-.133.298-.347.446-.52.149-.174.198-.298.298-.497.099-.198.05-.371-.025-.52-.075-.149-.669-1.612-.916-2.207-.242-.579-.487-.5-.669-.51-.173-.008-.371-.01-.57-.01-.198 0-.52.074-.792.372-.272.297-1.04 1.016-1.04 2.479 0 1.462 1.065 2.875 1.213 3.074.149.198 2.096 3.2 5.077 4.487.709.306 1.262.489 1.694.625.712.227 1.36.195 1.871.118.571-.085 1.758-.719 2.006-1.413.248-.694.248-1.289.173-1.413-.074-.124-.272-.198-.57-.347m-5.421 7.403h-.004a9.87 9.87 0 01-5.031-1.378l-.361-.214-3.741.982.998-3.648-.235-.374a9.86 9.86 0 01-1.51-5.26c.001-5.45 4.436-9.884 9.888-9.884 2.64 0 5.122 1.03 6.988 2.898a9.825 9.825 0 012.893 6.994c-.003 5.45-4.437 9.884-9.885 9.884m8.413-18.297A11.815 11.815 0 0012.05 0C5.495 0 .16 5.335.157 11.892c0 2.096.547 4.142 1.588 5.945L.057 24l6.305-1.654a11.882 11.882 0 005.683 1.448h.005c6.554 0 11.89-5.335 11.893-11.893a11.821 11.821 0 00-3.48-8.413Z";
+
+/** o link do botão mora em document.ts (`linkDoWhatsapp`, testado no runner do editor); sai daqui também */
+export { linkDoWhatsapp };
+
+function BotaoDeWhatsapp({ numero, mensagem }: { numero: string; mensagem?: string }) {
+  return (
+    <>
+      <style>{CSS_DO_BOTAO}</style>
+      <a
+        href={linkDoWhatsapp(numero, mensagem)}
+        target="_blank"
+        rel="noopener noreferrer"
+        aria-label="Falar no WhatsApp"
+        title="Falar no WhatsApp"
+        data-editor-ignore
+        className="site-chrome unbox-whatsapp"
+      >
+        <svg viewBox="0 0 24 24" width="30" height="30" fill="currentColor" aria-hidden="true">
+          <path d={CAMINHO_DO_ICONE} />
+        </svg>
+      </a>
+    </>
+  );
+}
+
+/**
+ * A LINHA ÚNICA DO LAYOUT. Renderize no `<body>` (o fim dele é o melhor lugar: os scripts entram depois
+ * da hidratação em qualquer posição, e o botão de WhatsApp fica por último na ordem de tabulação).
+ *
+ * - `doc`: o documento publicado (`getPublishedContent()`); `null` = a loja renderiza só o ambiente.
+ * - `ambiente`: `process.env`, inteiro. Só as variáveis de `VARIAVEIS_DE_RASTREIO` são lidas.
+ * - `unboxGtmId`: o contêiner CONTRATUAL da Unbox, o literal carimbado no layout pelo CLI (o prebuild
+ *   da loja cobra a presença dele lá). Não é configuração do lojista e não passa pelo documento.
+ */
+export function Rastreio({ doc, ambiente, unboxGtmId }: { doc: ContentDocument | null | undefined; ambiente: Ambiente; unboxGtmId: string }) {
+  // `unboxGtmId` vai junto: o contêiner do lojista igual ao da Unbox seria o MESMO contêiner carregado duas
+  // vezes, e `rastreioEmVigor` o descarta (e não o conta como Tag Manager próprio para suprimir o Pixel)
+  const r = rastreioEmVigor(doc, ambiente, { unboxGtmId });
+  return (
+    <>
+      {/* GTM central da Unbox: contrato, sempre ligado, antes de qualquer outro */}
+      {unboxGtmId && <Gtm id={unboxGtmId} chave="unbox-gtm" />}
+      {r.gtm.valor && <Gtm id={r.gtm.valor} chave="gtm-loja" />}
+      {r.ga4.valor && <Ga4 id={r.ga4.valor} />}
+      {r.metaPixel.valor && <MetaPixel id={r.metaPixel.valor} />}
+      {r.tiktok.valor && <TiktokPixel id={r.tiktok.valor} />}
+      {r.pinterest.valor && <PinterestTag id={r.pinterest.valor} />}
+      {/* sempre: page_view de cada navegação para quem não o conta sozinho (Meta, TikTok, Pinterest; o GA4
+          conta), e o de entrada no dataLayer dos contêineres de GTM quando nenhum outro provedor o conta */}
+      <PageViewPorRota />
+      {r.whatsapp.valor && <BotaoDeWhatsapp numero={r.whatsapp.valor.numero} mensagem={r.whatsapp.valor.mensagem} />}
+    </>
+  );
+}

package/template/lib/editable/server.ts

@@ -0,0 +1,189 @@
+// Leitura do conteúdo PUBLICADO no servidor (layout/page, com ISR).
+//
+// Sem EDITOR_URL, nada é buscado e a loja renderiza o que está no código.
+// Falha de rede/5xx devolve null com aviso: a loja nunca cai por causa do
+// editor — no pior caso mostra o conteúdo do repositório até a próxima
+// revalidação (ISR de 300 s, ou publicação que chama /api/revalidate).
+//
+// Quem só RENDERIZA usa `getPublishedContent()`: null = conteúdo do código, seja
+// porque a loja nunca publicou, seja porque a leitura falhou. Quem DECIDE a partir
+// do publicado usa `lerPublicado()`, que diz qual dos dois foi (`falhou`): é o caso
+// da rota /api/capi, que não pode mandar conversão para o Pixel do cadastro só
+// porque a leitura do que o lojista publicou falhou (Astra, segunda rodada, 1).
+import { cache } from "react";
+import { documentoUsavel, isHtmlPath, leituraDoPublicado, presencaNoAmbiente as presencaPura, recusaDeHtml, type Ambiente, type ContentDocument, type LeituraDoPublicado, type ManifestApps } from "./document";
+import { EDITOR_URL, STORE_SLUG } from "./config";
+
+/**
+ * APPS: RASTREIO E MARKETING (foundation 12). As funções moram em document.ts (puras, testadas no runner
+ * do editor) e saem também por aqui porque é daqui que o app/layout.tsx da loja lê o que é do SERVIDOR:
+ * `presencaNoAmbiente(process.env, { unboxGtmId })` vai no manifesto pelo `EditableProvider` (só presença,
+ * nunca valor, o estado da CAPI e o contêiner contratual da Unbox). `rastreioEmVigor(doc, process.env)` é o
+ * que o `<Rastreio>` de rastreio.tsx (a linha
+ * única do layout) consulta para decidir o que dispara (documento vence ambiente, um script por
+ * provedor). `capiDaLeitura(await lerPublicado(), process.env)` é o que a rota /api/capi da loja obedece: o
+ * Pixel em vigor e se o token o atende, ou "leitura-falhou" quando não se conseguiu ler o publicado (aí a
+ * rota não envia: não se sabe qual Pixel o lojista publicou). `process.env` é lido inteiro no servidor de
+ * propósito: as variáveis são conhecidas pelo nome em `VARIAVEIS_DE_RASTREIO`, e o layout não precisa
+ * listá-las uma a uma.
+ */
+export { rastreioEmVigor, capiEmVigor, capiDaLeitura, type RastreioEmVigor, type ManifestApps, type EstadoDoCapi, type EstadoDaRotaCapi, type LeituraDoPublicado } from "./document";
+
+/**
+ * O DOCUMENTO PUBLICADO DESTE PEDIDO, para quem precisa dele sem o receber por parâmetro. `cache` do React
+ * é por pedido: o layout faz `await getPublishedContent()` e, na mesma renderização, chama
+ * `presencaNoAmbiente(process.env, { unboxGtmId })` sem passar o documento (é a linha que o CLI carimba em
+ * toda loja). O
+ * estado da CAPI depende do Pixel EM VIGOR, que pode ser o que o lojista publicou, então a presença tem de
+ * ver o documento: ela o pega daqui. Fora de uma renderização (rota de API), `cache` não guarda nada e o
+ * slot vem vazio: aí vale só o ambiente, e quem precisa do documento o passa (a rota /api/capi passa).
+ */
+const documentoDoPedido = cache((): { doc?: ContentDocument | null } => ({}));
+
+/**
+ * A presença no ambiente e o estado da CAPI para o manifesto, com o documento publicado que este pedido
+ * já leu (ou o `doc` passado, quando quem chama o tem), e o contêiner contratual da Unbox (`unboxGtmId`, o
+ * mesmo literal que o layout passa ao `<Rastreio>`), para o painel não anunciar supressão de Pixel que a
+ * loja não executa. A linha do layout: `presencaNoAmbiente(process.env, { unboxGtmId: UNBOX_GTM_ID })`. A
+ * regra está em `presencaNoAmbiente` de document.ts.
+ */
+export function presencaNoAmbiente(ambiente: Ambiente, opcoes?: { doc?: ContentDocument | null; unboxGtmId?: string }): ManifestApps {
+  return presencaPura(ambiente, { doc: opcoes?.doc === undefined ? (documentoDoPedido().doc ?? null) : opcoes.doc, unboxGtmId: opcoes?.unboxGtmId });
+}
+
+/**
+ * BLOCO DE HTML, CAMADA 2 DE 3 — a conferência da LOJA, na porta de entrada do documento publicado.
+ *
+ * As outras duas: o EDITOR ao gravar (limpa e RELATA ao lojista o que tirou — é a única que tem alguém
+ * na tela para avisar) e o PRIMITIVO no cliente (a única que existe na PRÉVIA, onde o rascunho chega
+ * por postMessage sem ver servidor). Esta aqui não tem a quem relatar: ela só derruba, e escreve o
+ * motivo no log da loja — silêncio total seria a loja mudando de conteúdo sem ninguém saber por quê.
+ *
+ * ── POR QUE ELA EXISTE, se `resolveValue` já recusa HTML no caminho `.html` ────────────────────────
+ * 1. REGRA NOVA VALE PARA QUEM JÁ PUBLICOU. A lista de recusa (`recusaDeHtml`) mora no código da loja.
+ *    No dia em que uma tag entrar nela, o documento publicado há seis meses continua o mesmo — é este
+ *    varrimento, na leitura, que aplica a regra nova sem ninguém precisar republicar. Cobre também
+ *    "voltar para uma versão antiga do documento", que é justamente um documento escrito sob a lista
+ *    antiga.
+ * 2. O QUE É RECUSADO NÃO CHEGA AO NAVEGADOR. O documento INTEIRO é entregue ao `EditableProvider`
+ *    (app/layout.tsx) e viaja serializado dentro do HTML da página. `resolveValue` defende o RENDER —
+ *    o bloco não é injetado —, mas o texto do `<script>` recusado ainda sairia impresso no payload da
+ *    página, para qualquer um ler ou copiar. Derrubando na porta, ele não sai do servidor.
+ *    MEDIDO em `next build` + `next start`: o HTML recusado não aparece nenhuma vez na página
+ *    servida (nem escapado como `\u003cscript\u003e`). Em `next dev` ele AINDA aparece, e não é esta
+ *    função falhando: o modo de desenvolvimento serializa a resposta crua do `fetch` e ecoa o
+ *    `console.warn` do servidor no fluxo da página, tudo isso ANTES de o documento chegar aqui. Quem
+ *    for conferir, confira no build de produção.
+ * 3. CAMINHO SEM PRIMITIVO NUNCA PASSA POR `resolveValue`. Um `.html` de seção que saiu do código, ou
+ *    de uma seção criada cujo tipo deixou o catálogo, não é lido por primitivo nenhum — e mesmo assim
+ *    viajaria no documento pelo motivo 2.
+ *
+ * Não depende do editor: `recusaDeHtml` é função pura do `document.ts` desta loja, sem rede e sem
+ * biblioteca. A loja não pede opinião a ninguém para decidir o que renderiza.
+ *
+ * O que ela NÃO faz: a LIMPEZA por allowlist (tirar uma tag fora da lista, um atributo que não serve)
+ * continua só no editor, e de propósito — ela roda no momento da colagem, com o relatório do que saiu
+ * na tela. Repeti-la aqui, muda, faria a página publicada divergir em silêncio da prévia que o lojista
+ * aprovou. Aqui vale a RECUSA, que é a decisão do dono: o bloco inteiro entra ou não entra.
+ */
+function htmlRecusadoDoDocumento(doc: ContentDocument): [string, string][] {
+  const recusados: [string, string][] = [];
+  for (const [path, v] of Object.entries(doc.values)) {
+    if (!isHtmlPath(path)) continue;
+    // valor que nem sequer é texto já é lixo neste caminho: `recusaDeHtml` só sabe ler string
+    const motivo = typeof v === "string" ? recusaDeHtml(v) : "o valor gravado não é texto";
+    if (motivo) recusados.push([path, motivo]);
+  }
+  return recusados;
+}
+
+function semHtmlRecusado(doc: ContentDocument): ContentDocument {
+  const recusados = htmlRecusadoDoDocumento(doc);
+  if (recusados.length === 0) return doc; // o caso normal: nada é copiado à toa
+  const values = { ...doc.values };
+  for (const [path, motivo] of recusados) {
+    delete values[path];
+    // apagar o caminho = a loja cai no `fallback` do código (bloco de HTML nasce vazio, então some).
+    console.warn(`[editable] bloco de HTML recusado na leitura do publicado (${path}): ${motivo}`);
+  }
+  return { ...doc, values };
+}
+
+/**
+ * A LEITURA do publicado deste pedido, dizendo qual dos dois casos foi: AUSÊNCIA (`doc: null`, `falhou:
+ * false`: 404, a loja nunca publicou, ou loja desligada do editor) ou FALHA DE LEITURA (`falhou: true`: rede,
+ * 5xx, JSON inválido, documento malformado ou de outra loja). A classificação é `leituraDoPublicado` de
+ * document.ts (pura, testada no runner do editor); aqui entram o `fetch` com ISR, o aviso no log e a
+ * conferência dos blocos de HTML. É o que a rota /api/capi lê (`capiDaLeitura`).
+ */
+export const lerPublicado = cache(async (): Promise<LeituraDoPublicado> => {
+  const leitura = await lerDoEditor();
+  documentoDoPedido().doc = leitura.doc; // o que o `presencaNoAmbiente` deste arquivo vê no mesmo pedido
+  return leitura;
+});
+
+/** o documento publicado, ou null: a loja nunca publicou OU a leitura falhou. Para RENDERIZAR, os dois são "vale o código". */
+export const getPublishedContent = cache(async (): Promise<ContentDocument | null> => (await lerPublicado()).doc);
+
+async function lerDoEditor(): Promise<LeituraDoPublicado> {
+  // loja desligada do editor: AUSÊNCIA, não falha (não há o que ler)
+  if (!EDITOR_URL || !STORE_SLUG) return { doc: null, falhou: false };
+  const leitura = await leituraDoPublicado(
+    () => fetch(`${EDITOR_URL}/api/content/${encodeURIComponent(STORE_SLUG)}/published`, {
+      next: { revalidate: 300, tags: ["unbox-editor-content"] },
+      headers: { accept: "application/json" },
+    }),
+    STORE_SLUG,
+  );
+  // A loja não cai por causa do editor: é a promessa do topo deste arquivo. Falhou = conteúdo do código, com
+  // o motivo no log (e `falhou: true` para quem decide a partir do publicado).
+  if (leitura.falhou) {
+    console.warn(`[editable] ${leitura.motivo}; usando conteúdo do código`);
+    return leitura;
+  }
+  // o documento só sai daqui depois da conferência dos blocos de HTML (ver `semHtmlRecusado`)
+  return { doc: leitura.doc && semHtmlRecusado(leitura.doc), falhou: false };
+}
+
+/**
+ * O RECIBO DA REVALIDAÇÃO — o que esta loja está servindo AGORA, para o editor poder (ou não) dizer
+ * "a loja já está no ar com a versão N".
+ *
+ * O editor publica e chama `/api/revalidate` daqui. Até hoje ele concluía "está no ar" porque a
+ * resposta trazia a palavra "revalidated" — e isso não prova nada: purgar o cache diz que a PRÓXIMA
+ * leitura vai buscar de novo, não que ela aconteceu nem que deu certo. Uma loja sem `EDITOR_URL` (que
+ * nunca lê o editor), uma loja que responde 401, ou um documento de outra loja no meio do caminho
+ * davam a MESMA frase de sucesso para o lojista.
+ *
+ * Então esta função vai ver: lê o conteúdo publicado SEM CACHE e devolve o `updatedAt` do documento
+ * que passou por todas as portas que a loja usa para renderizar (`documentoUsavel`, a conferência do
+ * slug e a dos blocos de HTML). O editor compara com o que acabou de publicar. Se bater, "no ar" é
+ * afirmação verificada; se não bater, ele diz o que sabe (atualização pedida).
+ *
+ * Não substitui `getPublishedContent` nem aquece o cache dele: é uma leitura à parte, curta, feita
+ * DEPOIS do `revalidateTag`. O que ela garante é que o conteúdo novo chegou até aqui e é utilizável,
+ * e que a próxima renderização vai buscar do mesmo lugar.
+ */
+export type ConteudoAgora = { ok: true; updatedAt?: string; blocosRecusados: number } | { ok: false; motivo: string };
+
+export async function conteudoPublicadoAgora(): Promise<ConteudoAgora> {
+  if (!EDITOR_URL || !STORE_SLUG) return { ok: false, motivo: "esta loja não está ligada ao editor (sem EDITOR_URL)" };
+  try {
+    const res = await fetch(`${EDITOR_URL}/api/content/${encodeURIComponent(STORE_SLUG)}/published`, {
+      cache: "no-store",
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(8_000),
+      redirect: "manual",
+    });
+    if (res.status === 404) return { ok: false, motivo: "o editor ainda não tem conteúdo publicado para esta loja" };
+    if (!res.ok) return { ok: false, motivo: `o editor respondeu ${res.status}` };
+    const doc = (await res.json()) as ContentDocument;
+    if (!documentoUsavel(doc)) return { ok: false, motivo: "o conteúdo publicado veio malformado" };
+    if (doc.shop !== STORE_SLUG) return { ok: false, motivo: `o conteúdo publicado é de outra loja (${String(doc.shop)})` };
+    // blocos recusados NÃO derrubam o recibo: o resto do documento está no ar, e é isso que o editor
+    // afirma. O número sobe junto para o editor poder avisar o lojista do pedaço que ficou de fora.
+    return { ok: true, updatedAt: typeof doc.updatedAt === "string" ? doc.updatedAt : undefined, blocosRecusados: htmlRecusadoDoDocumento(doc).length };
+  } catch (err) {
+    return { ok: false, motivo: err instanceof Error ? err.message : String(err) };
+  }
+}

package/template/lib/editable/tokens.ts

@@ -0,0 +1,22 @@
+// Tokens de cor que o lojista pode mudar. É a ÚNICA lista feita à mão do
+// editor — e é por loja: o construtor acrescenta os tokens próprios da marca.
+// Tudo que não está aqui fica fora do alcance do editor.
+import type { EditableTokenSpec } from "./provider";
+
+export const EDITABLE_TOKENS: EditableTokenSpec[] = [
+  { token: "--store-primary", label: "Cor principal" },
+  { token: "--store-cta", label: "Cor do botão de compra" },
+  { token: "--store-cta-fg", label: "Texto do botão de compra" },
+  { token: "--store-bg", label: "Fundo da página" },
+  { token: "--store-ink", label: "Cor do texto" },
+  { token: "--store-surface", label: "Fundo de cartões" },
+  { token: "--store-sale", label: "Cor de oferta" },
+  // O lojista pediu "trocar a cor da barra de cima" e não havia como: o cabeçalho pinta com
+  // `--store-surface-2` e o rodapé com `--store-chrome-bg`, e nenhum dos dois estava aqui. O chat
+  // então mexeu na cor da marca, disse "alterada" e a tela não mudou. Lista curta demais é uma
+  // forma de esconder a loja do dono dela.
+  { token: "--store-surface-2", label: "Fundo do cabeçalho" },
+  { token: "--store-chrome-bg", label: "Fundo do rodapé" },
+  { token: "--store-chrome-text", label: "Texto sobre o rodapé" },
+  { token: "--store-line", label: "Cor dos filetes" },
+];

package/template/lib/editable/verify.ts

@@ -0,0 +1,24 @@
+// Verificação dos tokens assinados pelo editor (ES256, chave pública via JWKS).
+// Roda no edge (middleware) e no Node (rotas). A loja NÃO guarda segredo do
+// editor: só busca a chave pública em EDITOR_URL/.well-known/jwks.json.
+import { createRemoteJWKSet, jwtVerify, type JWTPayload } from "jose";
+import { EDITOR_URL, STORE_SLUG } from "./config";
+
+let jwks: ReturnType<typeof createRemoteJWKSet> | null = null;
+
+// "catalogo": leitura do catálogo da loja pelo SELETOR de vitrine do editor. É só
+// leitura, e a loja continua sendo a única que fala com a Unbox — o editor nunca
+// vê credencial (ver app/api/unbox/catalogo/route.ts).
+export type EditorTokenPurpose = "preview" | "revalidate" | "catalogo";
+
+export async function verifyEditorToken(token: string, purpose: EditorTokenPurpose): Promise<JWTPayload | null> {
+  if (!EDITOR_URL || !token) return null;
+  try {
+    jwks ??= createRemoteJWKSet(new URL(`${EDITOR_URL}/.well-known/jwks.json`), { cooldownDuration: 30_000, cacheMaxAge: 600_000 });
+    const { payload } = await jwtVerify(token, jwks, { issuer: "unbox-editor", audience: `loja:${STORE_SLUG}`, algorithms: ["ES256"] });
+    if (payload.purpose !== purpose) return null;
+    return payload;
+  } catch {
+    return null;
+  }
+}

package/template/lib/enrichment/combos.ts

@@ -0,0 +1,184 @@
+// COMBOS: kits temáticos da loja. Substitua pelos combos da nova marca.
+// Cada item usa `family` (familyCode do products.json) para resolver contra o catálogo Unbox.
+// Para usar: popule lib/enrichment/products.json à mão, no formato de lib/enrichment/index.ts.
+//
+// ===== Combos (kits temáticos) =====
+// Bundles curados a partir das famílias do products.json (familyCode). Cada item aponta para uma
+// FAMÍLIA — na resolução escolhemos o produto comprável do catálogo (por nome+tamanho), então o
+// combo nunca quebra se um tamanho específico sair de linha. Preço e imagem vêm do catálogo Unbox;
+// o desconto do combo é distribuído por item (mesmo padrão de `add({ price })` da buy box).
+import { getEnrichmentByName, parseSize } from "./index";
+import { resolveProductPrice } from "../format";
+
+/** "min" = menor tamanho da família (combo mais acessível); "max" = maior. */
+export interface ComboItem {
+  family: string;
+  qty?: number;
+  size?: "min" | "max";
+}
+
+export interface ComboHighlight {
+  /** chave de ícone resolvida no componente */
+  icon: "box" | "fire" | "sparkle" | "star" | "shield" | "heart" | "tag" | "gift";
+  label: string;
+}
+
+export interface ComboDef {
+  id: string;
+  name: string;
+  description: string;
+  /** imagem temática do combo, composta a partir das fotos reais dos produtos */
+  imageUrl: string;
+  /** selo opcional, ex.: "MAIS VENDIDO" */
+  badge?: string;
+  highlights: ComboHighlight[];
+  /** % de desconto sobre a soma dos itens */
+  /** @deprecated ignorado: o preço final é sempre o do catálogo (ver resolveCombos). */
+  discountPct?: number;
+  items: ComboItem[];
+}
+
+// TODO: defina os combos/kits da sua loja aqui.
+// Cada item usa `family` (familyCode do products.json) para resolver contra o catálogo Unbox.
+// Para usar: popule lib/enrichment/products.json com os dados dos produtos e defina os familyCodes.
+//
+// Exemplo de combo:
+// {
+//   id: "kit-essencial",
+//   name: "Kit Essencial",
+//   description: "Tudo o que você precisa para começar.",
+//   imageUrl: "/brand/combos/kit-essencial.webp",
+//   badge: "MAIS VENDIDO",
+//   discountPct: 15,
+//   highlights: [
+//     { icon: "sparkle", label: "3 itens" },
+//     { icon: "box", label: "Pronto para usar" },
+//   ],
+//   items: [
+//     { family: "FAMILIA_A" },
+//     { family: "FAMILIA_B" },
+//     { family: "FAMILIA_C", size: "min" },
+//   ],
+// },
+export const COMBOS: ComboDef[] = [];
+
+// ----- Resolução contra o catálogo -----
+
+export interface ResolvedComboItem {
+  family: string;
+  qty: number;
+  name: string;
+  weight: string;
+  imageUrl: string | null;
+  slug: string;
+  productId: string;
+  variantId: string;
+  /** preço unitário cheio */
+  price: number;
+  /** preço unitário com o desconto do combo (para enviar ao carrinho) */
+  discountedPrice: number;
+}
+
+export interface ResolvedCombo {
+  id: string;
+  name: string;
+  description: string;
+  imageUrl: string;
+  badge?: string;
+  highlights: ComboHighlight[];
+  discountPct: number;
+  items: ResolvedComboItem[];
+  itemCount: number;
+  subtotal: number;
+  total: number;
+  save: number;
+}
+
+const round2 = (n: number) => Math.round(n * 100) / 100;
+
+/** "Nome ( Name in English )" → "Nome"; sem parênteses devolve o nome inteiro. */
+function familyLabel(name: string): string {
+  const pt = name.split("(")[0].trim().replace(/\s+/g, " ");
+  return pt || name.trim();
+}
+
+function fmtWeight(w: { value: number; unit: string } | null): string {
+  if (!w) return "";
+  const v = Number.isInteger(w.value) ? String(w.value) : String(w.value).replace(".", ",");
+  return `${v} ${w.unit}`;
+}
+
+/** Indexa os produtos do catálogo por familyCode (ordenados por peso crescente). */
+function indexByFamily(catalogProducts: any[]) {
+  const map = new Map<string, { product: any; weight: number }[]>();
+  for (const p of catalogProducts) {
+    if (!p?.slug) continue;
+    const e = getEnrichmentByName(p.title);
+    if (!e) continue;
+    const w = parseSize(p.title)?.value ?? e.weight?.value ?? 0;
+    const arr = map.get(e.familyCode) ?? [];
+    arr.push({ product: p, weight: w });
+    map.set(e.familyCode, arr);
+  }
+  for (const arr of map.values()) arr.sort((a, b) => a.weight - b.weight);
+  return map;
+}
+
+/** Resolve todos os combos contra a lista de produtos do catálogo. Descarta itens/combos sem match. */
+export function resolveCombos(catalogProducts: any[]): ResolvedCombo[] {
+  const byFamily = indexByFamily(catalogProducts);
+  const out: ResolvedCombo[] = [];
+
+  for (const def of COMBOS) {
+    const items: ResolvedComboItem[] = [];
+    for (const it of def.items) {
+      const fam = byFamily.get(it.family);
+      if (!fam || fam.length === 0) continue;
+      const list = fam;
+      const picked = it.size === "max" ? list[list.length - 1] : list[0];
+      const cp = picked.product;
+      const v0 = cp.variants?.[0];
+      const rp = resolveProductPrice(cp);
+      if (!v0?._id || rp.price == null) continue;
+      const e = getEnrichmentByName(cp.title);
+      const qty = it.qty ?? 1;
+      // O preço final de um item é sempre o do catálogo: o servidor recalcula o carrinho a
+      // partir dele (lib/unbox/types.ts). Um "preço do kit" calculado aqui vira promessa que o
+      // carrinho desmente. Desconto de kit real se configura como regra de preço/cupom no painel.
+      const discountedPrice = round2(rp.price);
+      items.push({
+        family: it.family,
+        qty,
+        name: familyLabel(e?.name ?? cp.title),
+        weight: fmtWeight(parseSize(cp.title) ?? e?.weight ?? null),
+        imageUrl: cp.imageUrls?.[0] ?? null,
+        slug: cp.slug,
+        productId: cp.productId,
+        variantId: v0._id,
+        price: rp.price,
+        discountedPrice,
+      });
+    }
+
+    if (items.length < 2) continue; // combo precisa de pelo menos 2 itens reais
+
+    const subtotal = round2(items.reduce((s, i) => s + i.price * i.qty, 0));
+    const total = round2(items.reduce((s, i) => s + i.discountedPrice * i.qty, 0));
+    out.push({
+      id: def.id,
+      name: def.name,
+      description: def.description,
+      imageUrl: def.imageUrl,
+      badge: def.badge,
+      highlights: def.highlights,
+      discountPct: 0,
+      items,
+      itemCount: items.reduce((s, i) => s + i.qty, 0),
+      subtotal,
+      total,
+      save: round2(subtotal - total),
+    });
+  }
+
+  return out;
+}