sagadeck 1.2.0

package/docs/EXPERIENCIAS.md

@@ -0,0 +1,39 @@
+# Experiências do SagaDeck
+
+Na biblioteca, escolha uma experiência para abrir um roteiro pronto e editável. A criação é local: não depende de configurar IA nem de baixar imagens. O roteiro é um exemplo, e as notas orientam sua adaptação; informar um título não reescreve automaticamente o conteúdo.
+
+| Experiência | Uso | Linguagem visual e recursos |
+|---|---|---|
+| Sala de decisão | Estratégia e diretoria | Grafite e ouro, gráficos limpos, recomendação → evidências → riscos → decisão |
+| Matéria de capa | História e investigação | Serifas, papel claro, enquadramentos amplos, pistas e virada narrativa |
+| Modo espetáculo | Palco e keynote | Contraste luminoso, escala monumental, pausas, escolhas da plateia e revelação por clique |
+| Clube criativo | Workshop | Formas primárias, composição geométrica, desafios e timer |
+| Laboratório vivo | Programação | Código por etapas, saída ilustrativa, screenshot com focos e previsão antes da resposta |
+| Essencial | Produto e comunicação objetiva | Espaço vazio, uma ideia por vez, tipografia discreta e comparação |
+
+Cada modelo tem de 8 a 9 slides e notas do apresentador. Os dados de exemplo são identificados como ilustrativos. As figuras ficam no próprio YAML, para a apresentação continuar funcionando offline.
+
+## Código e screenshots
+
+O Laboratório vivo demonstra `codewalk`, que destaca linhas e revela explicações e saídas preparadas, e `spotlight`, que guia o olhar por regiões de uma imagem. O código e as saídas são material de aula: não são executados pelo navegador da apresentação. As perguntas vêm antes da explicação, para criar espaço de previsão e discussão.
+
+## Variedade entre decks gerados por IA
+
+A geração automática alterna doze direções criativas em uma ordem embaralhada. Nesta sessão do servidor, todas são usadas antes de repetir; a passagem entre ciclos também evita duas direções idênticas seguidas. As direções variam a estrutura da história, a abertura, a tipografia, as imagens e o ritmo. O briefing, o público e o tema explicitamente escolhido continuam tendo precedência. Uma direção explícita é preservada.
+
+Esse estado é pequeno, fica na memória e reinicia com o servidor. A decisão final de composição continua sendo do modelo; a revisão de ritmo identifica excesso de listas, repetição de layouts e ausência de pausas visuais.
+
+## API e uso em JavaScript
+
+`GET /api/experiences` retorna `{ experiences: [...] }`, com metadados para a galeria.
+
+`POST /api/library/experience` aceita `{ experience: "aula", title: "Minha aula" }` e salva um novo deck na biblioteca. `topic` é um contexto opcional do briefing, sem geração de conteúdo.
+
+```js
+import { EXPERIENCES, createExperienceDeck } from "../src/experiences.js";
+
+const deck = createExperienceDeck("aula", { title: "Minha aula de APIs" });
+// deck é a especificação nativa; salvar em YAML mantém a edição por slide.
+```
+
+Cada chamada cria objetos independentes: editar uma apresentação não altera o catálogo nem outra apresentação.

package/docs/PLANO-EXPERIENCIAS.md

@@ -0,0 +1,39 @@
+# Experiências exploráveis e autonomia — 02/10/2026
+
+Pedido autorizado: implementar as sete prioridades discutidas, registrar avanços e publicar etapas validadas.
+Não reescrever apresentações pessoais. Pasta oficial: C:\Users\narum\src\sagadeck; biblioteca: C:\Users\narum\sagadeck.
+
+## Etapas e critérios de conclusão
+
+- [x] 1. Avaliação de autonomia: pedidos variados inéditos, execução pelo agente interno, relatório de qualidade, custo/tempo e intervenções. Mocks verificam infraestrutura; execução real separada e explicitamente identificada.
+- [x] 2. Ciclo de criação/revisão: validar modelos interativos, revisar resultados renderizados e devolver achados ao agente, sem confundir YAML válido com qualidade comprovada.
+- [x] 3. Experiências conectadas: entradas compartilhadas, saídas e representações sincronizadas; cenários, comparação congelada, restaurar, mudanças destacadas e explicação. Testar estados e erros.
+- [x] 4. Curiosidade: prever antes de revelar; explorar limites/falhas/comparar hipóteses sem dependência de um assunto específico. Exemplos de fábrica acessíveis.
+- [x] 5. Continuidade: objetos identificáveis entre cenas, transição ligada à explicação, alternativa com movimento reduzido.
+- [x] 6. Direção de arte: alternativas realmente diferentes com mesmo conteúdo, contexto visual do conjunto e detecção de repetição. Camadas editáveis usando recursos existentes.
+- [x] 7. Apresentar/estudar/exportar: exploração guiada e livre, material de estudo com estados relevantes e explicações, sem duplicação manual do conteúdo.
+
+## Protocolo de trabalho
+
+Cada etapa: implementar motor + interface necessária + referência da IA + testes; bundle; npm test; commit/push/PR/merge. Registrar evidência real, limitações e próximo passo aqui e em ANDAMENTO.md. Reiniciar serviço local verificado na porta 3517 quando necessário. Sem deploy Oracle neste pedido.
+
+## Estado de retomada
+
+- 02/10: regras e código atual inspecionados; árvore limpa em main 62d36f9. Branch codex/experiencias-exploraveis.
+- Base existente: calc, science, algo, widgets, estudo, variantes de slide, revisão visual de transformação. Evoluir estes caminhos em vez de criar sistemas paralelos.
+- Implementação e validação local concluídas; PR #115 mergeado na main (5b7e20d).
+- As sete frentes têm implementação inicial verificável; os limites abaixo fazem parte da entrega.
+
+## Avanço verificável
+
+- Implementação inicial das sete frentes publicada na main pelo PR #115.
+- Testes específicos: 9 de motor/navegador/estudo/revisão; teste Studio com dois subcasos verifica gravação da pergunta e aplicação da direção escolhida. Passaram.
+- Estudo HTML agora permite exploração offline dos mesmos controles; impressão mantém os estados nomeados e explicações.
+- Primeira avaliação real: cinco casos gerados, todos marcados needs-work. Achados incluíam preferências estéticas tratadas como defeitos e frames intermediários confundidos com o final. A revisão foi ajustada para evidência concreta; snapshots amostram início e fim. Nenhum deck da avaliação foi retocado manualmente.
+- Limites conhecidos: continuidade é de posição/tamanho, não morph de geometria; direção aplica tema ao conjunto e composição ao slide escolhido; validação numérica amostra extremos individuais, não prova domínio contínuo. Tokens/custo medidos por tarefa quando o provedor informa; dados ausentes permanecem indisponíveis.
+- Validação final: npm test, 691 testes (671 passaram, 20 pulados, zero falhas), 894,7 s. Alterações finais cobertas novamente pelos testes específicos de IA, navegador, Studio e guardas. Bundle atualizado.
+- Segunda rodada real: geometria e narrativa conferidas; capacidade, algoritmo e consulta com pendências. Terceira sondagem de capacidade identificou falta de escala na curva e feedback dos controles: motor corrigido, teste de contraste incluído. Não houve retoque manual de deck. A avaliação é um instrumento de melhoria contínua, não uma promessa de perfeição autônoma.
+- Inspeção visual da demo: controles e resultados dentro do palco; contraste legível. Studio reiniciado em http://127.0.0.1:3517/editor?model=explorar.
+- Publicação concluída: https://github.com/naruminho/sagadeck/pull/115, merge 5b7e20d; serviço local reiniciado na porta 3517. CI remoto estava em andamento no merge; validação local passou conforme acima.
+
+- Porta local atualizada por instrução expressa do usuário: 3517. Processo SagaDeck anterior identificado nessa porta; wotan-router ocupa 3001 e não deve ser encerrado.

package/docs/PLANO-TESTE-AULAS-TECNICAS.md

@@ -0,0 +1,44 @@
+# Avaliação com aulas técnicas — HTTPX e grafos
+
+## Objetivo
+Gerar e testar duas aulas pelo agente do próprio SagaDeck, na biblioteca oficial. Sem retoques manuais nos YAMLs nem regras específicas para esses assuntos. Público desenvolvedor; palco e estudo no mesmo material.
+
+## Casos
+1. HTTPX avançado: clientes, configurações, timeouts, pool, concorrência limitada, streaming, falhas, retry, hooks, testes com MockTransport e HTTP/2. 14 slides iniciais, 45 minutos. Testar código longo, saídas, controles e material de consulta.
+2. Grafos: conceitos antes das ferramentas; BFS e Dijkstra passo a passo, NetworkX e Neo4j/Cypher. 18 slides iniciais, 60 minutos. Mesmo grafo de cinco nós nas três abordagens, pesos não negativos. Menor custo A-C-B-D-E = 7, menos saltos A-B-E = 11. Testar traço, diagramas, código e preservação de dados.
+
+## Execução
+- Fontes oficiais consultadas em 03/10/2026: python-httpx.org; networkx.org/documentation/stable; neo4j.com/docs.
+- Criar via /api/library/decks/ai no tópico Laboratório técnico; guardar revisão automática junto de cada deck.
+- Inspecionar ordem, cobertura e conteúdo. Executar exemplos Python reais; não confundir saídas guiadas com execução no navegador.
+- Conferir interação, legibilidade e estudo no navegador; qualquer falha geral ganha teste que falha antes da correção.
+- Registrar evidência e limites; bundle, suíte completa, commit/push/PR/merge e reinício na 3517 para alterações de produto.
+- Não requer instalar ou deployar Neo4j remoto, nem mudar Oracle. Exemplos que dependam de instância real devem dizer isso.
+
+## Avanços
+- Plano registrado; geração HTTPX iniciada pelo Studio. Grafos será gerado na sequência.
+- Correções da avaliação anterior ainda em validação final, sem descarte de trabalho.
+- HTTPX gerado: 17 slides, revisão visual do agente aprovada; alertas de ritmo (três códigos consecutivos e todos claros). Leitura encontrou URL relativa sem base_url, fórmula ceil exibida mas não calculada e MockTransport com endpoints diferentes em vez de retry do mesmo pedido. Corrigir pelo chat e testar código. Primeira geração de grafos falhou por DNS do provedor durante a escrita; repetir sem descartar a aula de HTTPX.
+- HTTPX corrigido pelo chat com execução real de Python (comandos liberados): 200 respostas offline, retry da mesma URL503→200 e ceil210/20=11. Verificação independente executou o código exato dos slides, validou sintaxe de sete snippets e confirmou11/3,3 no navegador, zero erros JavaScript. A aula tem18 slides após inserir respiro visual.
+- Grafos gerado na segunda tentativa:20 slides; uma pendência visual de BFS e alertas de ritmo. Encontradas duas falhas gerais: código longo não rolava até a linha da etapa; capturas de revisão usavam exportação, que ocultava os painéis interativos. Testes reproduziram linha fora da caixa e painel invisível; corrigidos no motor/captura,53 regressões específicas passaram. A captura agora traz o estado observado e usa palco sem movimento.
+
+## Ampliação solicitada: laboratório de produto
+- [x] Reproduzir a piscada e remover animação do quadro inteiro em algo, preservando sinais locais de mudança.
+- [x] Rede explorável com cartões semânticos, seleção, cor, vizinhança/BFS, menor custo, foco, zoom/pan, edição e restauração. Exemplo de logística demonstra generalização.
+- [x] Laboratório de código com edição de programa/entrada e execução rastreada offline; explicitar a diferença para Python com pacotes reais.
+- [x] Pesquisa preserva inventário visual; agente pode importar imagem observada ou capturar página oficial pública, com origem e arquivo local.
+- [x] Testar funções e fluxos reais no browser/Studio, aplicar às aulas pelo chat, verificar imagens oficiais reais e desafios dos alunos.
+- [x] Bundle, suíte completa, publicar e reiniciar na 3517. Sem deploy Oracle nesta etapa.
+
+## Próxima etapa autorizada — execução, coleções e mídia
+- [x] Python nativo e JavaScript nativo, com saída real e erros visíveis.
+- [x] Coleções de APIs: importar/adicionar, selecionar serviço, editar pedido e executar; avaliar expansão para PDF/PPTX.
+- [x] Player do YouTube e importação opcional de vídeo MP4 para a biblioteca.
+- [x] Quadro isolado de HTML/CSS/JavaScript para animações personalizadas geradas pelo agente.
+- [x] Validar código e interações reais, documentar limites, publicar e reiniciar na porta 3517.
+
+- Etapa de laboratórios: 716 testes, 696 passaram, 20 pulados, zero falhas; bundle atualizado. Próxima etapa de execução nativa, coleções e mídia ainda em implementação.
+
+- Recursos seguintes implementados e documentados; suíte final com 729 testes, 709 aprovados e 20 pulados. Nenhum deploy Oracle. Publicação final em andamento.
+
+- Entrega publicada e mergeada: PR #120 (https://github.com/naruminho/sagadeck/pull/120), merge 1fb5a6f. Bundle atualizado, serviço local reiniciado na 3517. HTML de divulgação verificado sem controles de votação ou notas internas. CI remoto em andamento no momento do merge; suíte local e regressões finais aprovadas conforme acima.

package/docs/PLANO-TESTE-DESINFORMACAO.md

@@ -0,0 +1,38 @@
+# Avaliação em um tema novo: desinformação
+
+Pedido de 03/10/2026: testar a autonomia do SagaDeck fora da hidrologia.
+
+## Entrega
+
+- Duas apresentações geradas pelo agente do Studio: executivos e estudantes, com o mesmo conteúdo e sequenciamento.
+- Tema: Como uma mentira vira verdade na internet? O título é provocativo; a explicação distingue verdade de percepção de credibilidade.
+- Casos fictícios, sem acusações contra pessoas reais. Referência conceitual: alfabetização midiática da UNESCO.
+- Experiências: três publicações e revelação de evidências; propagação parametrizada; gráfico com escala/recorte; enquadramento de imagem; decisão de verificação.
+- Notas para palco e material de estudo com explicações e limites dos modelos.
+
+## Execução e critérios
+
+1. Gerar pela API pública do Studio, na biblioteca oficial, sem escrever slides por script externo.
+2. Inspecionar ambos os decks: narrativa preservada, identidade distinta, dados fictícios sinalizados, controles que alteram resultados.
+3. Testar extremos, restaurar, comparação, previsão e revelação; conferir estudo e ausência de erros no navegador.
+4. Registrar falhas reais. Correções no produto precisam de reprodução automatizada e devem funcionar fora deste assunto.
+5. Para alterações de código: suíte, bundle, commit, push, PR, merge; reinício na 3517 quando necessário.
+
+## Avanços
+
+- Plano registrado. Configuração local usa DeepSeek V4.1 Flash. Oracle permanece fora desta rodada.
+- Próximo passo: geração real das duas versões pelo Studio.
+- Primeira geração executiva: 10 slides, duas imagens, cerca de 341 s; três rodadas de correção visual deixaram uma pendência. Gráfico foi substituído por painel numérico e decisão por diagrama estático.
+- Correção pelo chat: 11 slides, gráfico Plotly com seis valores preservados, comparação entre escalas, hub com três destinos e retorno. Revisão do agente aprovada; cliques reais confirmaram navegação, zoom e restauração.
+- Experiência de propagação: cenário inicial 20 pessoas; cenário Viral 538. Comparação e restauração funcionaram no palco e no HTML de estudo offline. Exportação de estudo abriu com 11 imagens, nenhuma quebrada e nenhum erro JavaScript.
+- Primeira geração estudantil caiu durante a correção por falha de DNS do provedor. Reproduzido: a geração descartava um deck já válido quando a etapa opcional de reparo falhava.
+- Repetição estudantil: 10 slides em cerca de 450 s, com duas pendências explícitas. Também mudou exemplos e sequência. Guardada como diagnóstico na biblioteca; a versão final parte de uma cópia da executiva e recebe direção visual pelo chat.
+- Correções gerais com testes reproduzindo as falhas: preservar geração válida em falha do reparo; informar progresso por slide; devolver e guardar relatório de geração; impedir corte do painel calc com duas curvas, inclusive após comparação.
+- Testes específicos: 18 passaram. Suíte inicial: 700 testes, um teste de inspetor falhou e passou isoladamente; suíte final em andamento.
+- Versões finais: 11 slides cada, editorial para executivos e Bauhaus para estudantes. A variante estudantil foi feita pelo chat em cerca de 30 s a partir do conteúdo aprovado. Conferência visual do agente aprovada; comparação estrutural encontrou zero diferenças nos textos de estudo/notas, dados, fórmulas, cenários, imagens dos exemplos e navegação.
+- Verificação adicional em ambos os HTMLs: nenhuma imagem quebrada, zero erros JavaScript, painel calc dentro da área útil. Material de estudo HTML gerado para ambas as versões; cenário e restauração também funcionam nele offline.
+- Mais uma falha geral reproduzida: `consulta` era contada como texto do palco no aviso de excesso de palavras. Corrigida com teste que mantém a contagem ao adicionar explicação de estudo longa.
+- Limites encontrados: gerar duas versões independentemente não garantiu fidelidade entre elas; mudanças visuais sobre uma cópia do conteúdo aprovado funcionaram nesta rodada. A geração precisou de orientação adicional para aproveitar gráficos e caminhos nativos. Não é evidência de autonomia completa.
+- O diagnóstico com oito curvas revelou painel além do rodapé. Teste reproduziu término em 1946 px para uma área útil até 976 px. Corrigida distribuição automática em grade com controles acima; conferência real confirmou oito resultados visíveis, comparação e total 362,2 no cenário de 70%. Persistência do relatório extraída para módulo próprio após o guard de tamanho do servidor falhar; nova suíte completa em andamento.
+- A verificação na página local revelou também a explicação inicial longa além do rodapé. Teste adicional falhou (1027 px para limite 976 px); ajuste inclui a explicação. Após correção, página real confirmou texto e painel dentro da área útil, sem erros JavaScript. Os três caminhos e retornos funcionaram em ambas as versões finais; restaurar voltou ao resultado inicial 20.
+- Validação final: npm test passou com 705 testes, 685 aprovados, 20 pulados e zero falhas; bundle atualizado. Código pronto para publicação da etapa.