stevensun1005/stock-html

stock-html: Página Ilustrada para Entender de Uma Vez

Transforme materiais em uma única página HTML: dois temas de ilustração à mão (papel quadriculado / lousa), quadrinhos com personagens fixos e todos os números verificáveis. Dois usos:

• Relatório de Ações (kind="stock", padrão): uma ação, um relatório financeiro, uma fusão ou notícia importante → um relatório ilustrado completo.
• Página de Aprendizado Geral (kind="general"): artigos, trabalhos acadêmicos, documentação técnica, anotações de curso → linha principal + cadeia de dependência de conceitos + cartões de quadrinhos + rota de aprendizado.

Este diretório contém ferramentas próprias, não escreva HTML do zero:

Arquivo	O que faz
scripts/sketch.py	Tela, quadrinhos de dois painéis, gráficos prontos, montagem da página; save() faz verificação offline automática de layout
scripts/blocks.py	Blocos semiprontos: linha principal, fosso, gráfico de conciliação futura, três formatos de quadrinhos, tabela de simulação de preço — usado ao fazer vários relatórios de uma vez
scripts/verify.py	Renderização real com Chrome headless, lê resultados de autoverificação embutidos na página, tira screenshots por seção
assets/template.html	Modelo de página: dois temas, filtro de tremor, selo de progresso, script de autoverificação embutido
examples/boba_merger.py	Exemplo de referência completo (relatório de ação de empresa fictícia), leia antes de começar
references/stock-report.md	Como escrever cada seção do relatório de ações, disciplina de dados
references/visual-style.md	Especificações visuais, coordenadas da tela, regras para SVG desenhado à mão
references/qa.md	Verificação em três camadas, pontos-chave para olhar as figuras, solução alternativa sem Chrome

Três Regras Inegociáveis

1. Leitor é iniciante absoluto. Cada termo técnico na primeira aparição deve ser explicado em uma frase, com o termo original em inglês entre parênteses. Proibido "como você sabe", "obviamente", "não é difícil entender".
2. Primeiro a conclusão, depois o princípio. A primeira frase de cada seção deve ser a conclusão, não a contextualização.
3. Números não podem ser de memória. Todos os números devem ser verificados primeiro, calculados com script e depois desenhados. Valores estimados devem ser marcados como "ilustrativo", probabilidades como "estimativa subjetiva, não previsão".

Fluxo de Trabalho

1. Leia todo o material — arquivos fornecidos pelo usuário, capturas de tela, links, todos.
2. Verificação online — priorize fontes primárias (comunicados da empresa, 8-K, press releases, relatórios financeiros), confirme cada número a ser usado. Detalhes em references/stock-report.md na seção "Disciplina de Dados".
3. Escreva script de build, números no topo — todas as entradas e cálculos como variáveis, use assert para conciliação cruzada (decomposição de variação, spread, diluição/aumento, múltiplos × EPS). Não desenhe se não fechar.
4. Organize a cadeia de dependência de conceitos (8–13 conceitos) — organize por "o próximo conceito resolve um problema do anterior", não na ordem original do material. Se um conceito não resolve um problema do anterior, a ordem está errada.
5. Monte a página — siga o exemplo examples/boba_merger.py:

   import sys; sys.path.insert(0, "<diretório deste skill>/scripts")
   from sketch import *
   p = Page("Título", "Subtítulo")            # padrão kind="stock"
   p.mainline(...); p.checkup(...); p.section(..., role="moat"); p.chain(...); p.card(...)  # …
   p.save("out.html")                     # escreve arquivo + pré-verificação offline, corrija qualquer ERROR
   

6. Verificação de renderização real — python3 scripts/verify.py out.html --shots shots/. Deve ver [CHECK light] PASS e [CHECK dark] PASS, depois olhe cada screenshot (pelo menos duas seções de cada tema). Detalhes em references/qa.md.
7. Entrega — se o ambiente tiver ferramenta de publicação de Artifact, publique (após publicação, leia o console para confirmar que ambos os temas estão PASS); caso contrário, entregue o arquivo HTML ao usuário.
8. Responda ao usuário — primeiro responda diretamente à pergunta dele em 2–3 frases (ex.: "A base fundamental mudou?"), depois explique com 5–8 pontos o que contém a página, anote diferenças do esperado (datas não confirmadas, números inferidos, fallback de fonte), e por fim liste as fontes.

Estrutura Padrão do Relatório de Ações

Cada seção abaixo é obrigatória por padrão (Page.save() alertará sobre seções faltantes). Isto é o "mínimo", não o "único": se o material tiver outros pontos importantes (valuation vs concorrentes, gestão e alocação de capital, fluxo de caixa e dívidas, concentração de clientes…), adicione mais section(). Cada seção com ≤ 4 frases, priorizando figuras.

#	Seção	Como chamar	Perguntas a responder	Que figura usar
1	Linha Principal	mainline()	O que realmente está acontecendo? (ciclo principal / pipeline / contradição central — escolha um)	Uma frase + uma figura
2	Check-up	checkup()	A base fundamental mudou? Cada linha com número e escopo	✓ verde / — laranja / ✗ vermelho
3	Fosso Competitivo	section(role="moat")	Quais 2–3 coisas os outros realmente não copiam? Qual é a evidência numérica? Onde está a fraqueza?	Figura de fosso + tiles
4	Cadeia de Dependência de Conceitos	chain()	Para entender esta empresa / notícia, quais 8–13 conceitos preciso saber?	Fluxograma em cobra
5	Cartões de Conceitos	card() × N	Cada conceito: o problema sem ele → sua solução → o que resolveu e o custo	Quadrinhos de dois painéis
6	Roteiro Técnico	section(role="roadmap")	O que já foi feito, o próximo passo, o que é apenas visão?	Figura de escada roadmap()
7	Plano de Longo Prazo	section(role="vision")	Para onde a gestão quer ir em 3–5 anos? Com a velocidade atual, chega lá? Quanto falta?	Gráfico comparativo meta vs velocidade atual
8	Crise Oculta	section(role="risks")	4–6 coisas que não estão no comunicado ou na narrativa otimista; qual é o sinal de alerta de cada uma?	risk_matrix() + tabela de alertas
9	Marcos Temporais Chave	section(role="timeline")	Quais dias nos próximos 6–12 meses trarão resultados? Quais datas ainda não confirmadas?	timeline() + tabela de agenda
10	Simulação de Preço	section(role="paths")	2–3 caminhos, o que precisa acontecer em cada um, em que preço cai, probabilidade subjetiva?	paths_chart() + tabela de simulação
11	Régua	section(role="ruler")	2–3 indicadores para medir o bom e o ruim; cada solução melhora qual e sacrifica qual?	ruler_chart() + tabela de comparação
12	Versão para Iniciantes (sob demanda)	section(role="eli5")	O mecanismo mais contraintuitivo, passo a passo com cálculos	Gráfico cascata + passos + tabela comparativa
13	Rota de Aprendizado	route()	3–4 paradas: por que ir, quanto tempo, link	Mapa de metrô
—	Rodapé	sources()	Todas as fontes + "Apenas para fins educacionais, não constitui recomendação de investimento"	—

A escrita de cada seção, lugares-comuns e contraexemplos estão em references/stock-report.md (leia antes de escrever relatórios de ações).

Estrutura da Página de Aprendizado Geral

Page(..., kind="general"): linha principal → cadeia de dependência de conceitos → cartões de conceitos → régua (2–3 indicadores para medir o domínio, desenhados na mesma figura) → versão para iniciantes (sob demanda) → rota de aprendizado. Sem check-up, simulação de preço e aviso legal.

Regras que Atravessam a Página Inteira

• Personagens fixos. Todas as figuras usam o mesmo conjunto de personagens; não troque entre conceitos. Padrão para ações: A, B, C como três acionistas antigos + D como um novo acionista; círculo = ações, moeda = lucro. Abaixo da linha principal, coloque uma linha pequena explicando os personagens.
• Números em escala reduzida. Desenhe 921 milhões de ações como 6 círculos, US$1 bilhão de lucro como 10 moedas; a proporção deve ser consistente com os dados reais, e marque na figura "valores ilustrativos".
• Cartões de conceitos escrevem apenas duas linhas: "O que resolveu" e "Qual o custo". O custo não pode ficar vazio nem ser "praticamente nenhum custo" — se não encontrar custo, não pensou o suficiente.
• Cores com significado fixo (consistente em toda a página): verde = em andamento (negócio, lucro); laranja = novo (novo evento, novo acionista); azul = armazenado (ações, caixa, valor); vermelho tracejado = cancelado / liberado (perda). Selo em roxo.

Requisitos Rigorosos (verifique um por um antes de publicar)

1. Texto explicativo de cada quadrinho ≤ 15 caracteres (contando números e símbolos; em página em inglês ≤ 32 caracteres).
2. Texto nunca encosta nas bordas, nunca se sobrepõe.
3. Priorize figuras; cada seção de texto ≤ 4 frases.
4. Todas as figuras são SVG inline desenhado à mão (gerado com sketch.py). Não use Chart.js / D3 / Mermaid.
5. CSS, JS, SVG tudo inline em um único arquivo HTML; sem links externos (incluindo Google Fonts — a CSP de alguns ambientes Artifact bloqueia).
6. Texto não entra no filtro de tremor, não leva transform (Canvas.text() já garante; ao escrever SVG manualmente, tome cuidado).
7. Links da rota de aprendizado devem ser abertos e verificados com ferramenta de captura; só escreva verified=True se o conteúdo corresponder. Se bloqueado ou inacessível, troque ou não forneça url (a página mostrará "necessita busca própria"). Inventar links é a falha mais grave deste skill.
8. Não mencione posições ou opções do usuário; analise apenas a ação em si; não dê ordens de compra ou venda.
9. verify.py deve mostrar PASS em ambos os temas, e você deve ter visto os screenshots.

Referência Rápida da Caixa de Ferramentas

# Tela: use apenas cores semânticas ink / ink2 / green / orange / blue / red / purple
c = Canvas(760, 300, "nome")                    # figura grande 760 de largura, tamanho de fonte ≥ 12
c.rect / line / arrow / curve / circle / path / poly / bar      # fill="green" claro, "green!" sólido
c.text(x, y, "texto", size=14, anchor="middle", color="ink", bold=False)
c.person(cx, top, "A", "blue", mood="happy")    # personagem fixo (aprox. 30×60)
c.pie(cx, cy, r, ["blue"]*6 + ["orange"]*2, labels)   c.coins(x, y, 12, "green", cols=4)
c.shop(cx, base, label="BOBA")   c.doc(x, y)   c.bubble(x, y, w, h)   c.tick / cross / minus

# Quadrinhos de dois painéis: 560×232; centro do painel esquerdo x=140, direito x=420; sua área de desenho y 44–188
k = Comic("Explicação esquerda ≤15 caracteres", "Explicação direita ≤15 caracteres")

# Gráficos prontos (todos retornam Canvas)
snake(nodes)   metro(stations)   timeline(events)   roadmap(stages)   risk_matrix(items)
paths_chart(history, scenarios)   ruler_chart(points, xr, yr, iso, gauge)   waterfall(steps)

# Página
p = Page(title, subtitle, kind="stock", notice=None)
p.mainline(uma_frase, canvas, kind="contradição_central", note="Personagens fixos:…")
p.checkup([("ok" | "mid" | "bad", "linha com número"), ...])
p.chain([(nome_conceito, novo_problema_que_traz), ...])
p.card(name, en, definition, comic, solves, cost, stamp="next" | "redo" | "done")
p.section(title, prose, canvas=, table=(cabeçalho, linhas), steps=[…], tiles=[…], after=, note=, role=)
p.route([Stop(name, why, time, url, link_text, verified=True), ...])
p.sources([(título, url), ...]);  p.save("out.html")

Para página em inglês: chame set_lang("en") antes de criar qualquer Comic / Page. Os detalhes dos parâmetros de cada função estão nos docstrings de scripts/sketch.py.

Ao fazer vários relatórios de uma vez (ex.: top 10 componentes de um ETF), use os blocos de scripts/blocks.py, cada relatório só precisa dos números e texto:

from blocks import *          # também importa todas as ferramentas do sketch
m  = mainline_tug(título_esq, [(rótulo, valor, é_guia)×3], nota_unidade, problema, subproblema, [(força, cor)×3], título_dir, [(data, preço), ...], "−6%")
mo = moat(["① Mais profundo", "② Segundo", "③ Mais raso"], "TICK")
vi = vision([(valor, rótulo1, rótulo2, cor, tracejado)×3], gap_between=(1, 2), note="algoritmo…")
c1 = C_bars(expl_esq, expl_dir, [(rótulo, valor, cor)], [(rótulo, valor, cor)], lnote=, rnote=, fmt="%g")   # barras comparativas antes/depois
c2 = C_talk(expl_esq, expl_dir, "A", "fala na bolha", "objeto_problema", "D", "objeto_solução", "nota_uma_linha")  # personagem + objeto
c3 = C_flow(expl_esq, expl_dir, ["caixa", "caixa"], ["caixa", "caixa", "caixa"], rnote="nota_uma_linha")  # fluxo de caixas
sc = [scen("caminho", prob, EPS_ilustrativo, múltiplo_baixo, múltiplo_alto, "green"), ...];  expect(sc);  scen_table(sc, o_que_precisa_acontecer)
p = Page(..., notice=disclaimer("2026-11-11"))

Figuras feitas com blocos tendem a ser "padronizadas"; para relatórios individuais que exigem mais refinamento, ainda desenhe manualmente com Canvas / Comic, ambos podem ser misturados.

Quando os gráficos prontos não forem suficientes, desenhe diretamente com gráficos básicos do Canvas — a caixa de ferramentas é um ponto de partida, não uma gaiola; desde que o texto use c.text(), a verificação ainda funciona.

Quando não é possível rodar Python

Copie assets/template.html, substitua {{BODY}} pelo HTML + SVG inline manual, e preencha os demais placeholders ({{TITLE}} {{LANG}} {{CAPMAX}} {{PAGE_KEY}} {{LABELS}}) conforme os valores em Page.html() no sketch.py. SVG manual deve seguir as coordenadas da tela e convenções de classe (svg.chk, rect.panel, text.cap) em references/visual-style.md para que a autoverificação embutida reconheça. Abra pagina.html?check=1 no navegador; a barra de verificação no rodapé deve ser verde PASS.

Modos de Falha Comuns

• ❌ Conceitos organizados na ordem original do material → a cadeia de dependência não tem valor informativo, reorganize
• ❌ "Qual o custo" escrito como "quase nenhum custo" → não pensou o suficiente, repense
• ❌ Personagens diferentes em figuras de conceitos diferentes → leitor precisa reaprender quem é quem, padronize
• ❌ Fosso competitivo só com adjetivos ("marca forte", "tecnologia líder"), sem números e escopo → substitua por evidências
• ❌ Visão da gestão escrita como guidance no plano de longo prazo → marque como objetivo e confronte com a velocidade atual
• ❌ Crise oculta escrita como clichês genéricos ("incerteza macro", "concorrência aumentada") → escreva o caminho de transmissão específico e o número a monitorar
• ❌ Data não anunciada escrita como definitiva → escreva "previsto início de dezembro (ano passado foi 2/12, sujeito a comunicado oficial)"
• ❌ Probabilidade e preço não marcados como "estimativa subjetiva / ilustrativo" → leitor tratará como previsão
• ❌ Mídia secundária diz "sem nova informação" e você acredita → primeiro verifique comunicados da empresa e documentos SEC
• ❌ Links da rota de aprendizado não abertos e verificados → o mais grave
• ❌ Texto principal escrito como ensaio longo → cada seção ≤ 4 frases
• ❌ Não rodou verify.py, não viu screenshots antes de entregar → página com texto sobreposto é enviada