18 KiB
Impl: Jingles e rádio na home — a seção de som (S22)
Status: aprovado — modo --auto Atualizado em: 2026-09-20 Issue: #1228 Intenção: docs/plans/jingles-radio-homepage.md Appetite restante: herdado (~1 dia eng; uma seção nova na home, sem rota nova) — sem ajuste de escopo; cortes em Rabbit holes.
Leitura da intenção
- Outcome: a home passa a ter uma seção de som curta com a Rádio Jorge Solla 1313 (player do zeno só após o clique) e até 3 jingles publicados (capa, play um por vez, download MP3), linkando
/jinglesquando houver mais; zero jingles publicados deixa a rádio e esconde a grade (fail-closed); nada de terceiro, áudio ou PII antes do gesto do visitante. - O que NÃO negociar:
/jinglescontinua canônica, indexável e no rodapé (não mudar player nem página do S21); facade click-to-load da rádio (zero request de terceiro antes do clique; link externo como alternativa); até 3 jingles + "Ver todos" só quando houver mais; posição entreCampaignStorySectioneCampaignCardsSection; fonte única é a collectionjingleviagetPublishedJingleItems()(sem collection/mídia nova); home estática (nada depayload.findcru); kill switch do S21 preservado; sem formulário/consent/PII. - O que reavaliar (hipóteses do plano de intenção): (a) o
JinglePlayerdo S21 é reusável como está? — não: ele hardcoda o shell de página inteira (JinglePlayer.tsx:134-135,261) e a grade; a hipótese correta é extrair o core; (b) o fixturee2eTest.ts"aborta requests externos"? — não em geral: ele só roteiayoutube-nocookie(:108) efacebook.net(:114); o iframe do zeno exigepage.routepróprio no spec, senão vira rede real/erro de console no guard; (c) o e2e da home mede overflow? — sim (frontend.e2e.spec.ts:553-557), mas não da seção nova: ela ganha asserção própria.
Abordagem recomendada
flowchart LR
RSC["(home)/page.tsx (RSC)<br/>getPublishedJingleItems() · cache tag jingles"] --> SEC["JingleHomeSection (server)<br/>data-home-section='sound'"]
RSC -- "slice(0,3)" --> GRID["JingleCards (client, extraído)<br/>article[data-jingle] · data-state · preload=none"]
RSC -- ">>> 3" --> ALL["Link 'Ver todos os jingles' → /jingles"]
SEC --> RADIO["RadioFacade (client)<br/>data-radio-state: facade → loading → loaded"]
RADIO -- "clique" --> IFRAME["iframe zeno.fm/player/jorge-solla-1313/"]
S21["JinglePlayer (shell S21) · /jingles"] --> GRID
Opções consideradas: A | B | C | D (por decisão, abaixo)
Recomendação: extrair o core do player (JingleCards) e montar a seção da home com ele + uma facade de rádio sob src/components/jingles/; leitura única do listing cacheado na page.
Rejeitadas: props de shell no JinglePlayer (arrisca /jingles sem ganho), grade reimplementada na home (duplica a máquina de estado), iframe direto da rádio (viola o aceite), spec e2e novo (segundo dono das linhas de jingle + entrada de manifest).
Decisões de engenharia
D1 — Reuso do player (caro: fronteira de módulo)
Opções: A) props de shell/compacto no JinglePlayer; B) extrair JingleCards (core client) e deixar JinglePlayer como shell do S21; C) montar a grade na home sem reusar.
Recomendação: B — uma única dona da exclusividade (activeId/playback/refs em JinglePlayer.tsx:83-131), /jingles visual e contratualmente intacta (seletores pinados article[data-jingle], data-state, button[data-play], audio[preload="none"], download={downloadFilename}) e nenhum branching novo no componente que o e2e frontendJingles pina.
Alternativas rejeitadas: A porque move o branching para o shell pinado e arrisca regressão visual em /jingles; C porque duplica a exclusividade, o catch do play() abortado e o progresso — drift garantido contra jinglePlayer.unit.spec.tsx.
D2 — Facade da rádio (caro: componente client + contrato de terceiro)
Opções: A) RadioFacade client em src/components/jingles/, sem sandbox, estados facade/loading/loaded, iframe oficial só no clique; B) iframe direto (como o YouTube da story); C) só link externo; D) facade com sandbox restritivo.
Recomendação: A — entrega o "embed tocável" pedido sem expor GA (G-2T527NZWVM) e redes de anúncio da zeno em todo pageview; fica sob o prefixo src/components/jingles (manifest frontendJingles, sem entrada nova); iframe com src do widget, title em pt-BR, allow="autoplay", altura reservada; clique monta, onLoad promove loading → loaded; aria-busy no botão de carga; link "Abrir no Zeno" target="_blank" rel="noopener noreferrer" sempre visível na facade.
Alternativas rejeitadas: B porque carrega third-party/ads em toda abertura da home e viola o aceite; C porque não entrega o player pedido; D porque sandbox sem contrato do widget pode quebrar o player sem ganho de isolamento (o vendor já vê o que veria) — reavaliar apenas se a zeno documentar requisitos.
Lacuna de design: o artefato só tem facade/loaded (a cena 03 é "loaded", sem pending). Fase 0 estende o artefato com a cena de loading antes de qualquer markup.
D3 — Leitura na home e derivação do rodapé (caro: cache/estático)
Opções: A) uma chamada getPublishedJingleItems() na page e derivar showJingles e a seleção; B) manter hasPublishedJingles() + chamada extra ao listing; C) mover o slice para dentro de JingleHomeSection.
Recomendação: A — o listing cacheado (unstable_cache tag jingles, jingleReads.ts:32-35) já é a fonte do rodapé e o padrão existente é o dono da lista derivar o flag (/jingles/page.tsx:84-100, comentário em CampaignFooter.tsx:21); uma leitura só evita divergir "tem jingles" de "tem grade"; slice(0,3) em memória (limit 0 devolve todos; volume trivial).
Alternativas rejeitadas: B porque hasPublishedJingles vira pass-through de length > 0 quando a lista já está em mãos (depth check); C porque esconde a regra de produto no componente e tira do teste da page a seleção.
hasPublishedJingles continua usado por (home)/cards/page.tsx:27 — não fica órfão (knip ok). O mock de tests/unit/campaignHome.unit.spec.tsx:41-43 passa a exportar getPublishedJingleItems.
D4 — Posição e pino de ordem (caro: pin de e2e)
Opções: A) data-home-section="sound" entre story e cards + atualizar o pino; B) renderizar sem data-home-section para não tocar o teste.
Recomendação: A — o pino (frontend.e2e.spec.ts:1700-1706) existe para proteger a ordem do bloco de conversão; a seção nova é parte da home e deve aparecer no contrato. Atualizar para sound === story + 1 e cards === sound + 1 (e manter cards === newsletter - 1).
Alternativa rejeitada: B porque deixa a seção invisível ao teste de ordem e qualquer reordenação futura passa silenciosa.
D5 — Estratégia de testes (caro: superfície de spec/manifest)
Opções: A) estender frontendJingles.e2e.spec.ts (serial, dono das linhas de jingle) + update do pino/overflow em frontend.e2e.spec.ts; B) criar frontendJinglesHome.e2e.spec.ts; C) só unit.
Recomendação: A — o spec serial controla publicação/kill switch e já visita a home (frontendJingles.e2e.spec.ts:200-201,231-232), então grade/facade/zero/overflow-com-conteúdo cabem nele; o dono da home mantém ordem e overflow independente-de-conteúdo. Os prefixos atuais do manifest (src/components/jingles → frontendJingles, :99-108; src/app/(frontend) → frontend, :77) já cobrem todos os arquivos tocados — sem mudança no manifest.
Alternativas rejeitadas: B porque exige entrada nova no manifest e cria segundo dono das linhas de jingle (serialização/limpeza duplicadas) sem cobertura extra; C porque não prova o facade sem request de terceiro nem o estado real da home.
Componentes / mudanças
src/app/(frontend)/(home)/page.tsx— troca o import dehasPublishedJingles(:9) porgetPublishedJingleItems;const jingles = await getPublishedJingleItems();const homeJingles = jingles.slice(0, 3);showJingles={jingles.length > 0}; render<JingleHomeSection jingles={homeJingles} showAll={jingles.length > homeJingles.length} />entre<CampaignStorySection/>(:241) e<CampaignCardsSection/>(:242).src/components/jingles/JingleCards.tsx(novo,'use client') — core extraído deJinglePlayer.tsx:83-259: estado de exclusividade, progresso e o grid (max-w-6xl,gap-5 sm:gap-6 md:grid-cols-3), com todo o markup/contrato dos cards (capanext/image fillsizes 33vw, título,data-play,data-state, progressbar, download comdownloadFilenamee<audio preload="none">). Props{ jingles: readonly JingleViewModel[] }; sem props de shell.src/components/jingles/JinglePlayer.tsx— fica só com o shell do S21 (section[aria-label="Jingles publicados"]+ nota "Sem autoplay…",:134,261) renderizando<JingleCards jingles={jingles} />; sem'use client'(não guarda mais estado). Markup/contrato visual inalterados;/jingles/page.tsxintocado.src/components/jingles/JingleHomeSection.tsx(novo, server) —section[data-home-section="sound"][aria-labelledby="sound-title"]com o eyebrow "A trilha da nossa caminhada", h2 "Cante, baixe e espalhe" e a copy do design;<RadioFacade />; sub-bloco "Jingles oficiais / Dê o play. O próximo ritmo é seu." + "Um jingle toca por vez." com<JingleCards jingles={jingles} />somente sejingles.length > 0; link "Ver todos os jingles" →/jinglessomente seshowAll. SemJingleEmptyStatena home (o vazio da home é a rádio sozinha, sem estado de página).src/components/jingles/RadioFacade.tsx(novo,'use client') — card[data-radio][data-radio-state]; facade com logo (numero-negativo.png),button[data-load-radio]"Ouvir a rádio", link "Abrir no Zeno" e nota "O player do zeno.fm só é carregado depois do seu clique."; clique monta o iframe oficial e marcaloading;onLoad→loaded; altura reservada para CLS zero; copy pós-carregamento "Player fornecido por zeno.fm. Ao usar, você acessa um serviço externo."src/app/(frontend)/styles.css— regras novas no fim, padrãocampaign-radio-*(arte/gradiente do card, wave decorativaaria-hidden,motion-reduce), reusandocampaign-section-eyebrow/title/copy(:371-389) e os tokens[data-theme='campaign-site']; layout em utilitários Tailwind como os cards do S21. Nada de CSS existente alterado.docs/plans/jingles-radio-homepage-ui-design.html— estender (fase 0) com a cena da rádio emloadinge a nota/cena de 1–2 jingles (grade sem "Ver todos").- Migration: nenhuma (nenhum schema; sem
generate:types). - Access / Consent: N/A — leitura pública, sem formulário, sem PII, sem chave de Consent.
- UI: Impeccable C — nova seção em página existente; shells a reusar:
campaign-section-*, card do S21, tokenscampaign-site, linguagem doCampaignStorySectionpara a section band; processo shape (fase 0) → craft (fase 3) → critique → polish sobre o artefato aprovado no gate.
Dados → forma (se aplicável)
- N/A — a intenção declara "Vou apresentar dados? Não"; superfície de mídia (áudio + capa), sem agregação, sem PII e sem pergunta de data-presentation a responder.
Fases verificáveis
- Fase 0 — design gate (~0,5 h): estender
docs/plans/jingles-radio-homepage-ui-design.htmlcom o estadoloadingda rádio (pós-clique, altura reservada,aria-busy, affordance de carregando) e a nota de 1–2 jingles; sem markup antes disso. Checkpoint: artefato commitado e aprovado. - Fase 1 — tracer behavior-preserving (~2 h): criar
JingleCards, emagrecerJinglePlayer; rodarpnpm test:unit -- jinglePlayere e2efrontendJingles(fluxo/jingles) — verdes sem nenhuma mudança de/jingles. Checkpoint: extração sem regressão. - Fase 2 — facade da rádio (~2 h):
RadioFacade+ unit novo (sem iframe no idle; iframe edata-radio-stateapós clique;onLoad→ loaded; link externonoopener noreferrer). Checkpoint:pnpm test:unitverde. - Fase 3 — seção na home (~2,5 h):
JingleHomeSection,styles.css, page.tsx (leitura única/slice/showAll/rodapé derivado), update detests/unit/campaignHome.unit.spec.tsx+tests/unit/jingleHomeSection.unit.spec.tsx(novo) e pino de ordem nofrontend.e2e.spec.ts. Checkpoint: home renderiza 0 / 1–3 / 4+. - Fase 4 — e2e da home (~1,5 h): estender
frontendJingles.e2e.spec.ts(facade sem request zeno antes do clique compage.route('https://zeno.fm/**'), iframe após clique, >3 → 3 cards + "Ver todos" →/jingles, kill switch zero → só rádio, sem request de MP3 antes do play, overflow 390 com 3 cards) e a asserção de overflow da seção nofrontend.e2e.spec.ts; nav da home por/?e2e=<ts>(padrãogotoHomeFresh, ISR + cache heurístico). Rodarpnpm test:e2e -- frontendJingles frontend. - Gates (~0,5 h):
pnpm gate:fast; registro emdocs/changelog/2026-09-20-s22.md; push viapnpm push(CI roda o restante).
Rabbit holes / Não escopo (engenharia)
- "Melhorar o player" durante a extração: o core mantém o S21 como está (sem velocidade, playlist, waveform, scrub).
- Player de rádio próprio ou stream direto em
<audio>(CORS/mixed content sem aviso): fica o iframe oficial sob clique + link externo. - Analytics de play/download, contagem de ouvintes, status "no ar", share kit, letras/transcrição/páginas por jingle.
- Sandbox do iframe, CSP para zeno, consent de terceiro: a mitigação é a facade; nada além disso.
- Novo schema/collection/mídia e migration; publicação dos 3 jingles no admin é dependência de ops do S21 (o código do S22 não publica conteúdo — sem isso a home mostra só a rádio).
- Embed da rádio em nav/rodapé/outras páginas e redesign do shell/home.
- Novo spec e2e ou entrada nova no manifest (prefixos atuais cobrem); abstrair uma "media section" genérica com <3 call sites (DRY <3).
Riscos e mitigação
- Regressão do S21 na extração: fase 1 é movimentação pura de estado/markup; rodar
jinglePlayer.unit.spec.tsx(pina um-por-vez,preload="none", download) e e2efrontendJinglesde/jinglesantes/depois; nenhum seletor oudata-*muda. - Terceiro antes do clique (aceite central): unit pina "sem iframe no idle"; e2e coleta requests
zeno.fme exige zero antes do clique;page.route('https://zeno.fm/**', fulfill vazio)no spec antes do clique evita rede real/GA no CI (o fixturee2eTestnão intercepta zeno e o guard de console trata erro externo como falha). - Home deixa de ser estática ou ganha read cru: só
getPublishedJingleItems()(cache tagjingles); nenhumpayload.findnovo; slice em memória; rodapé derivado do mesmo listing (padrão de/jingles). - Pino de ordem quebra: atualização deliberada e registrada (D4); o teste passa a pinar
soundentrestoryecards. - Overflow mobile: medir em 390 nos dois specs (com 3 cards no
frontendJingles, rádio-only nofrontend);min-w-0/truncatejá presentes nos cards, arte do rádio com largura fluida e logo limitado. - Corrida de conteúdo no
frontend.e2e.spec.ts(roda em paralelo com o spec que mexe nas linhas de jingle): na home do specfrontend, assertar só o que independe de publicação (seção, ordem, facade, overflow), nunca contagem de cards; contagens ficam nofrontendJingles(serial, dono das linhas). - CLS/estado de loading não desenhado: fase 0 estende o artefato (altura reservada +
aria-busy) antes do markup. - 1–2 jingles: regra
length > 3cobre; nota/cena na fase 0. - A11y:
titleno iframe,aria-busyno botão de carga, nota de serviço externo, wave decorativaaria-hiddencommotion-reduce. - knip/ciclos/import map:
JingleCards/RadioFacadeno mesmo diretório sem ciclo;hasPublishedJinglessegue usado por(home)/cards; sem campos novos, sem import map novo.
Simplify + débitos (2026-09-20)
Dois revisores (estrutural + qualidade) sobre o diff: 11 achados, 9 resolvidos no
lugar (grid mobile do card sem col-start-2 condicional, arte sem faixa branca
com md:h-auto, CLS facade↔loaded zerado com footprint reservado 330/312 medido,
classe/hooks sem consumidor removidos, anel de foco em focusRing.ts, heading
level dos cards na home, foco do teclado movido para a região de status, mock
morto, testes redundantes) e 2 descartados com respaldo:
- Asserções da seção de som em dois specs. O
frontendcobre ordem/estrutura independentes de publicação (roda em paralelo ao spec serial que flipa jingles); ofrontendJinglescobre conteúdo/clique. Decisão D5; DRY <3. aria-busypersistente norole="status". Contrato do artefato (Cena 04) pinado no unit; o loading é transitório e o foco vai para a região.
Nenhum débito virou Issue nova (0 expensive_lock score ≥4).
Aceite de engenharia
- Aceite de produto da intenção ainda coberto: seção na home com jingles (capa/play um por vez/download), rádio sob clique sem terceiro antes, kill switch individual + zero-jingles→só rádio,
/jinglescanônica intacta + "Ver todos" quando houver mais, home estática sem áudio/iframe no load, mobile/LGPD. - Invariantes AGENTS/engineering-standards: sem collection/Consent/migration;
unstable_cachepreservado;push:falseintocado; nenhuma URL pública nova ou alterada;/jinglese rodapé intocados. - Testes de domínio previstos: unit (facade idle→loading→loaded sem iframe no idle; home 0/1–3/4+ com slice e "Ver todos"; player do S21 preservado) e e2e (home no
frontendJingles; ordem/overflow nofrontend); int N/A (sem write path).
Self-score decision-quality
- Decisões caras com rejeitadas: sim — D1 (A/C), D2 (B/C/D), D3 (B/C), D4 (B), D5 (B/C).
- Abordagem dentro do appetite: sim — uma seção, sem rota/schema; fases somam ~1 dia e a fase 1 é behavior-preserving.
- Rabbit holes nomeados: sim — player, stream direto, analytics/"no ar", sandbox/CSP, share kit, spec novo, publicação ops, DRY <3.
- Depth check: sim — extrai o core em vez de duplicar; reusa
jingleReads,campaign-section-*, tokenscampaign-sitee o vocabulário de testedata-home-section/data-radio. - Outcome preservado: sim — nenhuma decisão de engenharia reescreveu o produto (facade, até 3 + ver todos, fail-closed,
/jinglescanônica).
Self-score: 5/5 — gate ≥4 atendido.