sagadeck 1.3.1 → 1.5.0

package/README.md

@@ -26,7 +26,7 @@ A IA funciona apontando para um modelrelay ou gateway compatível (`SAGADECK_LLM
 
 ## Como usar
 
-Toda apresentação mora na **biblioteca**: `SAGADECK_HOME`, ou `~/sagadeck` (no Windows, `C:Users<você>sagadeck`). Uma pasta por tópico, uma por apresentação.
+Toda apresentação mora na **biblioteca**: `SAGADECK_HOME`, senão a pasta `sagadeck` dentro de **Documentos** no Windows (a pasta Documentos que o Explorer mostra, mesmo redirecionada para o OneDrive ou outro disco) e `~/sagadeck` no Mac e no Linux. Quem usava a biblioteca antiga em `C:\Users\<você>\sagadeck` tem ela movida para Documentos na primeira execução; o caminho antigo continua levando até lá. Uma pasta por tópico, uma por apresentação.
 
 ```bash
 sagadeck new "Minha palestra" --topic=Palestras --theme=editorial
@@ -74,7 +74,7 @@ Se o código de uma ferramenta em Python quiser chamar o sagadeck diretamente (s
 ```python
 import sagadeck
 sagadeck.autofix("palestra.yaml")               # corrige sobreposições e margens automaticamente
-sagadeck.studio()                               # abre a biblioteca (~/sagadeck)
+sagadeck.studio()                               # abre a biblioteca (Documentos/sagadeck no Windows)
 sagadeck.studio("palestra.yaml", port=3517)     # abre direto o editor de um deck
 sagadeck.export("palestra.yaml", out="saida")   # {'html': …, 'pptx': …, 'pdf': …, 'roteiro': …}
 print(sagadeck.check("palestra.yaml"))           # relatório do fiscal em texto
@@ -193,7 +193,7 @@ formato avisa para atualizar o sagadeck. Se um filtro de e-mail barrar a extens
 ## Biblioteca
 
 `sagadeck studio` sem arquivo abre a biblioteca: suas apresentações organizadas em tópicos, com capa, busca,
-lixeira (30 dias) e o menu **⋯** de cada cartão (apresentar, renomear, duplicar, mover, baixar tudo/.sagadeck/PPTX/PDF).
+lixeira (um dia) e o menu **⋯** de cada cartão (apresentar, renomear, duplicar, mover, baixar tudo/.sagadeck/PPTX/PDF).
 
 **Nova apresentação** tem três caminhos: *Descrever com IA* (o assunto, quanto tempo você tem, que vira o número de
 slides, o estilo e, se quiser, material de apoio: PDF, Word, PowerPoint, Excel ou um link), *A partir de um arquivo
@@ -205,7 +205,7 @@ Arraste um cartão para um tópico para movê-lo. O ícone da biblioteca, no can
 Não tem banco de dados: a biblioteca é uma pasta comum, que dá para abrir no Explorer e fazer backup.
 
 ```text
-~/sagadeck/                  (ou SAGADECK_HOME, ou --library=PASTA)
+Documentos/sagadeck/         (Windows; ~/sagadeck no Mac/Linux; ou SAGADECK_HOME, ou --library=PASTA)
   Palestras/                 tópico = pasta (a cor fica em .topico.json)
     Minha palestra/          apresentação = pasta com o YAML e os arquivos dela
       Minha palestra.yaml

package/bin/sagadeck.js

@@ -57,7 +57,7 @@ const HELP = `sagadeck — YAML -> apresentação (HTML animado + PowerPoint edi
   sagadeck estudo <deck.yaml> [--html]         gera <deck> - material de estudo.pdf (cada slide + texto de consulta)
   sagadeck all <deck.yaml>                     build + check + pptx + pdf + roteiro
   sagadeck studio [deck.yaml|x.sagadeck] [--port=3517] [--library=PASTA]  sem arquivo: abre a biblioteca; já aberto: usa o aberto
-                                   (PASTA padrão: SAGADECK_HOME ou ~/sagadeck); com arquivo: abre o editor dele
+                                   (PASTA padrão: SAGADECK_HOME, senão Documentossagadeck no Windows, ~/sagadeck fora dele); com arquivo: abre o editor dele
                                    --host=0.0.0.0 abre para a rede (padrão: só esta máquina)
                                    --multiuser: uma biblioteca por usuário, atrás de um proxy que envia X-Sagadeck-User
                                    --agentes=naru,ana: no multiusuário, quem pode deixar a IA rodar comandos (padrão: ninguém)
@@ -124,6 +124,14 @@ async function doShots(p, dir = p.shots) {
 }
 
 async function main() {
+  // biblioteca antiga (~/sagadeck) vai para Documentos\sagadeck no Windows, uma vez (src/library.js)
+  if (!flags.library) {
+    const { migrateLegacyLibrary } = await import("../src/library.js");
+    const m = migrateLegacyLibrary();
+    if (m.moved) console.log(`✓ biblioteca movida para ${m.target} (o caminho antigo ${m.legacy} continua levando até ela)`);
+    else if (m.error) console.log(`! não deu para mover a biblioteca para ${m.target} (${m.error}); sigo usando ${m.legacy}`);
+    else if (m.skipped === "as duas têm conteúdo") console.log(`! há apresentações em ${m.legacy} e em ${m.target}; uso ${m.target}. Junte as duas pelo Explorer se quiser.`);
+  }
   switch (cmd) {
     case "napkin":
     case "visual": {

package/docs/ANDAMENTO.md

@@ -8,6 +8,382 @@ começar. Trabalho em curso vai para o GitHub (commit + push) a cada etapa, nunc
 
 ---
 
+## Próximas frentes (levantadas em 08/10/2026, ainda não começadas)
+
+**Para quem pega isto numa sessão nova, sem a conversa de origem.** O projeto é o **sagadeck**:
+- Repositório GitHub `naruminho/sagadeck`, clonado em `C:\Users\narum\src\sagadeck`, branch `main`.
+- Publicado no npm como `sagadeck` (1.5.0, com as mudanças de 08 e 09/10).
+- Ferramenta Node (ESM) que transforma apresentações escritas em YAML em HTML/PPTX.
+- Tem um editor web, o Studio (`sagadeck studio`, porta 3517).
+- Tem uma IA (via modelrelay em `http://127.0.0.1:8765/v1`) que cria e edita decks, inclusive a partir de PDFs de
+  artigos científicos para apresentar em congresso.
+
+Os itens abaixo vieram de duas rodadas de 08/10/2026, ambas descritas nas seções logo abaixo deste diário:
+- **Paper → congresso.** Geramos decks a partir de três PDFs, olhamos o resultado e corrigimos o motor (figuras,
+  equações, crítica, autoria, idioma).
+- **Biblioteca no OneDrive.** A pasta das apresentações passou de `C:\Users\narum\sagadeck` para a pasta Documentos
+  do Windows, que nesta máquina é redirecionada para o OneDrive: `C:\Users\narum\OneDrive\Documents\sagadeck`. O
+  caminho antigo virou junção.
+
+**Ordem combinada com quem mantém o projeto (Narumi):** 1, depois 4, depois 8: os três entraram em 08/10 (seções
+datadas abaixo). O resto fica para depois e só entra se for pedido. Antes de começar, leia o `CLAUDE.md`
+(regras). Para cada item:
+- teste que falha antes da correção;
+- `npm test` passando;
+- uma branch por item, PR e merge na hora, sem perguntar;
+- este diário atualizado no mesmo commit. Item feito sai desta lista e vira uma seção datada com o que entrou.
+
+**OneDrive (a biblioteca agora mora em `C:\Users\narum\OneDrive\Documents\sagadeck` e sincroniza)**
+
+2. **Cache fora da nuvem.** A lixeira passou a durar um dia (seção "Lixeira de um dia" abaixo). Sobram `.cache`
+   (5 MB) e `.historico` indo para o OneDrive; só pesa se a pasta Documentos estiver no OneDrive (comum no Windows 11
+   e em empresa, mas não universal). O histórico de versões talvez deva continuar junto do deck (portável).
+3. **Arquivos só na nuvem (Files On-Demand).** Com espaço liberado, o OneDrive deixa só o marcador do arquivo, e
+   ler o conteúdo força o download. Conferir se listar a biblioteca (`openLibrary`, `/api/library`) lê o YAML de
+   cada deck; se lê, listar só pelo nome/metadado e abrir o conteúdo sob demanda.
+
+## Pacote Python: escape inválido numa docstring — 09/10/2026
+
+Antes da release 1.5.0. `python/sagadeck/api.py` tinha "Documentos\sagadeck" numa docstring: `\s` é escape inválido,
+`SyntaxWarning` no Python 3.12 (a CI no Linux acusava; aqui, no 3.11, passava calado) e erro nas versões seguintes.
+Virou "Documentos/sagadeck". Teste novo em `test/python-relay.test.js`: compila todo o pacote com `-W error` (qualquer
+Python; falhava antes).
+
+## Crítica acionável: cada ponto vira um cartão com Aplicar e Ignorar — 09/10/2026
+
+Item 7 das próximas frentes. A leitura crítica (botão do chat) chegava como um texto único, com opções gerais ("leve
+os achados para os slides").
+
+- Cada ponto vem com `id` e, quando o deck vai junto, o `slide` a que se liga (antes só o tipo "slide a rever" tinha;
+  regra no prompt de `critiqueMaterials`; número que não existe no deck é descartado).
+- No chat, cada ponto é um cartão: tipo, título, texto, o trecho conferido e "Slide N" (leva até ele). **Aplicar**
+  vai ao slide e pede à IA só aquele ponto, mirando aquele slide (a autoria decide: achado no slide, crítica e
+  pergunta nas notes). **Ignorar** fica gravado (`/api/ai/critique/item`, `status` no `.sagadeck/leitura-critica.json`)
+  e o ponto sai do material que acompanha os próximos pedidos (`critiqueMaterial`).
+- Teste (`test/studio-critique.test.js`): dois pontos viram dois cartões; slide inexistente não vira link; Ignorar
+  grava e tira o ponto do próximo pedido; Aplicar vai ao slide 2, pede o ponto e grava "aplicado". Falha sem a mudança.
+- **Item 5 (equações que a visão não listou) já estava feito**: `assignEquations` põe as numeradas esquecidas em
+  `missed`, elas entram no inventário com a caixa exata do texto e passam pela mesma releitura do recorte
+  (`transcribeEquation`) que escreve o LaTeX das outras. Saiu da lista.
+
+## Studio avisa quando o código mudou por baixo dele — 09/10/2026
+
+Continuação do incidente "nenhum slide abre" de 08/10: um Studio aberto antes de uma atualização segue com o servidor
+velho, enquanto os arquivos da página vêm novos do disco. Corrigir a lista de scripts resolveu aquele caso, mas
+qualquer mudança de API quebraria do mesmo jeito, em silêncio.
+
+- `src/studio/code-version.js`: impressão do código (caminho, data e tamanho de cada arquivo de `src/`; no pacote do
+  pip, do motor empacotado). O Studio guarda a de quando subiu; `/api/code-version` diz se mudou (recalcula no máximo
+  a cada 3 s).
+- `update-notice.js` (editor e biblioteca): confere ao abrir, ao voltar para a aba e a cada 30 s; mudou, mostra a
+  faixa "O sagadeck foi atualizado. Feche e abra o Studio de novo…", que dá para fechar.
+- Teste (`test/studio-scripts.test.js`): o Studio sobe com uma raiz de código temporária (`codeRoot`, só para testes,
+  para não acender o aviso num Studio de verdade aberto ao lado); sem mudança, sem aviso; mudou a data de um arquivo,
+  editor e biblioteca mostram a faixa e ela fecha; zero erros de JavaScript. Falha sem o recurso.
+
+## Testes instáveis sob carga — 09/10/2026
+
+Item 9 das próximas frentes. Testes que passavam sozinhos e caíam com a suíte inteira trocaram tempo fixo por espera
+da condição de verdade:
+
+- `developer-labs` (frame executa JavaScript): o clique chegava antes de o script do iframe ligar o `onclick` e o
+  resultado ficava 0. Espera o `onclick` existir e o texto virar 1 (e 0 depois do reinício).
+- `motion-scenes`: comparava o quadro da animação depois de 100–300 ms. Agora espera o quadro mudar (anima) ou parar
+  de mudar (pausou fora do slide), com prazo.
+- `library-ui` (aula de APIs ao vivo): só clica em Executar com o slide montado.
+- **Defeito de verdade achado no caminho**: com `motion: none`, a cena de terminal começava digitando ("first l_")
+  porque só sabia do movimento reduzido pela mensagem da página, que sob carga chegava tarde. A cena agora nasce
+  sabendo (`still` no documento dela, `motionHTML` em `src/motion.js`). O teste de captura confere que, no instante em
+  que o texto aparece, ele já está completo; e um teste rápido confere o `still` no documento (falhava antes).
+
+## Geração por etapas: o aviso diz a etapa e o documento é lido em paralelo — 08/10/2026
+
+Item 6 das próximas frentes. Gerar com documento leva minutos e a tela ficava em "Pensando…" sem dizer pensando em
+quê; e o inventário do documento (a visão lendo página a página) rodava inteiro antes de qualquer outra coisa.
+
+- **Quadro de etapas** (`src/ai/progress.js`, `stageBoard`): `generateDeck` passa cada etapa por ele (Entendendo o
+  pedido, Pesquisa, Leitura crítica, Lendo o documento, Escrevendo a apresentação, Conferindo as figuras do material,
+  Conferindo os números, Imagens, Revisão dos slides). Todo aviso sai como "Etapa: detalhe"; duas etapas ao mesmo
+  tempo aparecem juntas ("Lendo o documento: página 3 de 12… · Leitura crítica: …"). O evento leva `stages` (as em
+  curso) e `done` (as terminadas). A biblioteca mostra também o tempo decorrido.
+- **Em paralelo** (`generateForStudio`): o inventário começa na hora e corre junto com entender o pedido, a pesquisa
+  e a leitura crítica (que usam só o texto; `worthCritique` aceita documento ainda sem inventário, marcado
+  `document`). A escrita espera o inventário (`pendingMaterials`). Se a geração para antes (a IA perguntou, deu
+  erro), o inventário é cancelado (`AbortController`) e a pasta fica livre.
+- Testes (`test/ai.test.js`): o quadro com duas etapas juntas; a crítica começa enquanto o inventário ainda não
+  terminou (o inventário falso só termina depois que a crítica começa: com a ordem antiga, travava), a escrita recebe
+  o material inventariado e nenhum aviso sai sem etapa; e a pergunta antes de escrever cancela o inventário.
+
+## Lixeira de um dia — 08/10/2026
+
+Pedido de Narumi: a lixeira da biblioteca guardava 30 dias e estava com 407 MB (23 apresentações, quase todas
+gerações de teste), tudo sincronizando com o OneDrive. Agora guarda um dia (`TRASH_DAYS = 1` em `src/library.js`;
+`purgeOld` apaga de vez o que passou disso). Textos da biblioteca e README falam em um dia. A lixeira do projeto
+(`.sagadeck/lixeira`, arquivos dentro de uma apresentação) não muda. Teste: `test/library.test.js` (excluída há uma
+hora continua restaurável; há dois dias some do disco).
+
+## Studio aberto antes da atualização não abria slide — 08/10/2026
+
+Retorno logo depois do item 8: "tentando abrir um slide e não abre". O Studio da pessoa tinha subido antes do merge.
+O servidor lia o `app.js` do disco a cada pedido (veio o novo, que chama `window.SagaHeaderFooter`), mas a lista de
+scripts que ele entregava (`PUBLIC_SCRIPTS`) era fixa na memória: `header-footer.js` e `preferences-ui.js` davam 404,
+o `app.js` quebrava ao carregar e nada abria. Reiniciar o Studio resolvia; a correção evita a próxima vez.
+
+- `publicScript` (`src/studio/public-files.js`): todo `.js` direto na pasta `public` é entregue, decidido a cada
+  pedido olhando o disco (só nome simples: nada de subir de pasta). A lista fixa acabou; módulo novo não precisa
+  mais ser registrado em lugar nenhum além do `index.html`.
+- Teste (`test/studio-scripts.test.js`): todo `<script src>` do `index.html` e do `library.html` responde 200, e um
+  módulo criado depois que o Studio subiu também (falhava com 404 antes); `..`, arquivo inexistente e nome estranho
+  não passam.
+
+## Bancada de qualidade da geração a partir de paper — 08/10/2026
+
+Item 4 das próximas frentes. Saber se a geração a partir de PDF melhorou dependia de gerar decks e olhar um por um.
+Agora há uma avaliação repetível do motor: gera a partir de PDFs quaisquer e dá nota ao que saiu.
+
+- **Nota** (`src/ai/bench.js`, `scoreDeck`): de 0 a 100 por quesito, com as mesmas ferramentas da autocrítica:
+  figuras/tabelas numeradas com slide (`uncoveredVisuals`), recorte de figura sem legenda nem "Fonte:" dentro (linha
+  de legenda/crédito da camada de texto do PDF cruzando a caixa do recorte), equações numeradas do texto com LaTeX
+  (`equationGroups` × inventário), números na tela sem base no documento (`unsupportedNumbers`), autor do documento
+  e não o das Preferências, sem votação em deck acadêmico, sem slide de frase gigante (`auditText`) e idioma pedido
+  (texto e `lang`). Quesito sem como medir fica "—" (não conta como bom). Total = média.
+- **Mesmo caminho do Studio**: as opções da geração saíram do servidor para `src/studio/generate.js`
+  (`generateForStudio`: Preferências, anexos com inventário na pasta do deck, revisão pelos slides renderizados); o
+  `generateIntoLibrary` e a bancada usam a mesma função. A bancada passa Preferências fixas (autor de mentira para
+  pegar autor errado, sem perguntar, sem imagens geradas).
+- **Rodar** (lento; ao vivo): `SAGADECK_LIVE=1 SAGADECK_BENCH_DIR=<pasta com PDFs> node --test test/bench-live.test.js`.
+  Gera a partir de cada PDF da pasta com um pedido genérico (`SAGADECK_BENCH_PEDIDO` troca; `SAGADECK_BENCH_IDIOMA`
+  liga a conferência de idioma). Os PDFs são exemplos quaisquer: nada de caso fixo, nome de paper ou de pessoa no
+  repositório. O objetivo é medir o motor, não acertar um deck.
+- **Relatório**: `<data>-<versão>.json` e `.md` em `SAGADECK_BENCH_OUT` (senão `<SAGADECK_BENCH_DIR>\sagadeck-bancada`),
+  com o quadro PDF × quesito, a diferença para a rodada anterior (a média só quando os PDFs são os mesmos) e o que
+  puxou cada nota para baixo (figura que faltou, recorte com legenda, número sem base).
+- Testes: `test/bench.test.js` (cada quesito num deck e material montados à mão, legenda na coluna vizinha não
+  conta, relatório com a comparação) e `test/bench-live.test.js` (só com `SAGADECK_LIVE=1` e `SAGADECK_BENCH_DIR`).
+
+## app.js abaixo do limite: Preferências e Cabeçalho/Rodapé em módulos — 08/10/2026
+
+Item 8 das próximas frentes. O `src/studio/public/app.js` estava com 249.491 dos 250.000 bytes que a trava do monólito
+(`test/guards.test.js`) permite: qualquer acréscimo quebrava. O chat já tinha saído (`chat.js`); saíram dois blocos
+inteiros e autocontidos, no molde de `slide-select.js` (fábrica que recebe o estado e os ajudantes e devolve a API):
+
+- `header-footer.js` (`window.SagaHeaderFooter`): modelos prontos, campos com variáveis e prévia do cabeçalho/rodapé.
+- `preferences-ui.js` (`window.SagaPrefs`): a tela única de Preferências, com busca e gravação automática.
+- Carregados no `index.html`, antes do `app.js` (o servidor entrega todo `.js` da pasta `public`; ver a seção
+  seguinte).
+- `app.js` foi a 235.619 bytes; o limite desceu para 240.000 (a trava continua sendo catraca: sobra espaço para
+  ajustes pequenos, recurso novo vai para módulo próprio).
+- Testes: os de Preferências e de cabeçalho e rodapé do `test/studio.test.js` (clicam de verdade e conferem o deck e
+  o arquivo salvos, sem erro de JavaScript) passam iguais; comportamento não mudou.
+
+## Gravação tolerante a arquivo travado (OneDrive) — 08/10/2026
+
+Item 1 das próximas frentes. Com a biblioteca no OneDrive, a sincronização (e antivírus, indexador) segura o arquivo
+por um instante e o `rename` falha com `EPERM`/`EBUSY`/`EACCES`: o salvamento da pessoa se perdia com erro.
+
+- `renameRetry` (`src/fs-retry.js`): tenta de novo só nesses três códigos, com espera curta e crescente (20 → 450 ms,
+  ~1 s no total); outro erro (disco cheio, destino inexistente) sobe na hora. Espera síncrona (`Atomics.wait`), para
+  servir aos chamadores síncronos sem mudar a assinatura deles.
+- Usado em todo rename do código: `writeDeckFile`, biblioteca (lixeira, restaurar, mover, renomear deck e tópico,
+  publicar a geração, migração), arquivos do projeto, Preferências, conversa do chat, links compartilhados e
+  ambientes do slide api.
+- Testes (`test/deck-file.test.js`, `test/library.test.js`): stub do `fs.renameSync` que falha N vezes com cada código
+  e o deck é gravado; erro de outro tipo sobe na primeira tentativa; trava que não solta desiste em ~1 s sem estragar
+  o arquivo; lixeira/restaurar/mover/renomear com a pasta travada; e uma trava de código: `fs.renameSync` direto em
+  `src/` ou `bin/` faz o teste falhar.
+
+## Biblioteca padrão em Documentos\sagadeck — 08/10/2026
+
+Pedido: a biblioteca padrão no Windows é a pasta `sagadeck` dentro de Documentos (antes, `~/sagadeck`, direto na
+pasta do usuário). `defaultLibraryRoot`: `SAGADECK_HOME`, senão `<Documentos>\sagadeck` no Windows (a pasta
+conhecida "Personal" do registro: a que o Explorer mostra, inclusive redirecionada; aqui é
+`C:\Users\narum\OneDrive\Documents`, então a biblioteca sincroniza com o OneDrive) e `~/sagadeck` fora dele.
+`migrateLegacyLibrary` (na partida do `sagadeck`): move a biblioteca antiga inteira (mesma unidade: instantâneo) e
+deixa uma junção no caminho antigo; não mistura se as duas têm conteúdo; falhou, a antiga continua valendo (nunca
+abre vazia). CLAUDE.md, README, ajuda, MCP e Python atualizados. Teste: `test/library.test.js`.
+
+## Apresentação da Maria Clara em inglês — 08/10/2026
+
+Gerada pelo caminho do Studio ("…que a Maria Clara vai fazer no ICFM10 sobre o artigo dela, em inglês"): 19 slides,
+`lang: en`, autor "Maria Clara Fava et al.", sem votação, figuras inteiras, trade-off em gráfico. Problemas do motor:
+
+- **Números em português num deck em inglês**: contador, gráficos, mapas, calculadora e laboratório de decisão
+  formatavam sempre em pt-BR ("1.403", "0,93"). `src/locale.js`: o idioma do deck (`lang`) vale para os números
+  (build define antes de renderizar; na apresentação, `<html lang>`); ler "1,403"/"37.67%" segue o idioma. Deck
+  gerado sem `lang` ganha o idioma pelo texto (`guessDeckLang`, palavras de ligação).
+- **Precisão do paper perdida**: "0.90" sem aspas virava 0.9 no YAML (tabela do NSE em inglês com 0.9, 7.8, 0.2).
+  Em tabela (rows/head/cells) e em value exibido, o número fica como foi escrito; dado de gráfico continua número. E o
+  gráfico mostrava 1 casa abaixo de 10 (0.93 → 0.9) e 0 acima (37.67 → 38): agora as casas do próprio valor, até 2.
+- **Texto vazando da caixa do diagrama flow** ("Low-lying areas near the drainage network" a 36 px fixos):
+  `boxFontSize` simula a quebra e desce até caber.
+- Nome da pasta cortado no meio da palavra ("…Urban Flood Predic"): corta no último espaço antes de 80.
+- Sem texto do motor em português no HTML (conferido no build: nenhum rótulo automático em pt).
+
+## Retorno dos decks do ICFM10: autor errado, figura cortada, "^^≠^^", votação — 08/10/2026
+
+- **Autor**: os dois decks saíram "Narumi Abe" (o autor das Preferências), não Maria Clara Fava. Bug da rodada
+  anterior: a regra "autor = a pessoa apresenta o próprio trabalho" + o autor padrão viraram "quem usa é o autor do
+  artigo". Agora, com documento anexado, o autor das Preferências não vai como padrão nem é colado no deck; regra:
+  quem assina é quem assina o documento (o primeiro apresenta em `autor`; em `livre`, quem apresenta vai em `role`).
+- **Figura 2 cortada**: a caixa da visão era larga demais (a imagem cobria 44% dela) e a regra exigia 50%: caía no
+  corte pela camada de texto, que comia a ponta do mapa e trazia um pedaço da linha de cima. Imagem de tamanho de
+  figura (≥ 1% da página) que cobre um quarto da caixa já é a figura.
+- **"^^≠^^"** no compare: o `vs` saía com esc(), sem a marcação. Corrigido, e a revisão de texto agora renderiza o
+  slide e acusa qualquer marcação crua visível (^^, ==, **), fora dos slides de código: pega os outros campos assim.
+- **Votação no journal club**: apresentação acadêmica (deck de artigo, congresso, defesa, seminário, journal club)
+  não leva enquete, votação, quiz ou cronômetro sem pedido de interação: regra no prompt e achado da revisão.
+- Prova ao vivo ("apresentação que a Maria Clara vai fazer no ICFM10 sobre o artigo dela"): capa "Maria Clara Fava et
+  al. · UFSCar", `autoria: autor`, sem votação, Figura 2 inteira. Achou outro defeito: duas capas idênticas (até as
+  notes; o "slide repetido" que o diário já registrava). Cópia exata sai na geração (`dropDuplicateSlides`), e
+  mesmo layout + mesmo título vira achado da revisão.
+- **Opinião sem foco** ("o que você acha desse slide?"): a foto do slide puxava a resposta para o design. Regra 1c:
+  responder conteúdo PRIMEIRO (fiel ao material? falta o porquê, o número? o que a banca pergunta?) e forma depois,
+  com opções para aprofundar cada um; foco dito pela pessoa vale sozinho. Ao vivo, no slide da Tabela 1 do ICFM10:
+  apontou que o achado mais forte (HYMOD empata com o HEC-HMS) passava batido e só depois o texto lateral longo.
+- Biblioteca: os decks de teste do ICFM10 superados foram para a lixeira (recuperáveis); ficaram o do congresso
+  (Maria Clara) e o do journal club.
+
+## Leitura crítica do material, autoria e origem do conteúdo — 08/10/2026
+
+Retorno: num brainstorm pelo chat, a IA achou o que a geração não achou (o resumo do ICFM10 promete variáveis
+socioeconômicas que o método não usa; o trade-off pico × volume escondido na tabela; o donut mostrando composição da
+amostra como resultado). Pedido: por que a geração não fez isso; é válido "interferir" se o original é ruim; botão de
+criticar; saber o que é do paper e o que é inclusão do sagadeck; e liberdade total fora do caso "autor apresenta o
+próprio paper".
+
+- Causa: a geração lia o paper para APRESENTAR, nunca para criticar. Agora há uma etapa de **leitura crítica**
+  (`src/ai/critique.js`): inconsistências, achados que passam batido, perguntas prováveis, limitações, slide que
+  representa mal o material e pontos fortes, cada item com trecho LITERAL do material, conferido pelo código (letras
+  e números, tolerando os espaços e hifens do PDF): sem trecho no texto, o item é descartado (anti-alucinação).
+  Roda na geração quando há documento (vai no pedido e fica em `.sagadeck/leitura-critica.json`) e no botão
+  **Leitura crítica** do chat (`/api/ai/critique`, ícone scan-search): vira mensagem com opções, nada muda nos slides,
+  e acompanha os próximos pedidos rotulada "feita pelo sagadeck, NÃO pelo autor".
+- **Autoria** (`context.autoria`): `autor` (congresso, simpósio, defesa: fiel ao material; o achado do material vai ao
+  slide, a crítica e as perguntas vão nas notes "Prepare-se: …") × `livre` (aula sobre o trabalho de outros, journal
+  club, resenha, divulgação, tema geral: conteúdo próprio liberado). Responde à dúvida "é válido interferir": no
+  modo autor, o sagadeck não reescreve a ciência do paper, prepara o autor; a decisão de mudar é da pessoa.
+- **Origem** (`provenance: material | derivado | proprio` + `provenanceNote`; `origin` já era a etimologia do layout
+  definition): selo na miniatura do Studio para o que o sagadeck incluiu ou calculou; a apresentação não mostra.
+- Ao vivo (deck do ICFM10): 12 pontos em 153 s, todos com trecho conferido; repetiu os do brainstorm e achou mais:
+  PEV e PBIAS idênticos na Tabela 1 (conferido no PDF: mesmas linhas, sinais trocados), validação com um evento só,
+  resumo promete "flood extents" que não existem, bacia "com poucos dados" muito bem instrumentada, referência
+  interna errada (2.1.1 × 2.2.1).
+- Geração ao vivo, mesmo paper, dois pedidos: "apresentação oral em congresso" → `autoria: autor`, todo slide com
+  provenance, o trade-off virou slide ("Volume simples, pico detalhado"), o donut virou "a base de treino tem três
+  classes bem desiguais" (derivado), e a crítica foi para as notes como "PREPARE-SE" (PEV = PBIAS no slide da
+  tabela, socioeconômicas no das variáveis, referência errada nas limitações). "Journal club da disciplina" →
+  `autoria: livre`: a crítica virou conteúdo marcado `proprio` (Prometido × entregue; Os números que não fecham;
+  Três furos no desenho; pergunta para a turma). Essa levou 43 min: o modelo travou pensando e a tentativa sem
+  raciocínio (da rodada anterior) destravou a tarefa.
+- Testes: `test/critique.test.js` (trecho conferido × inventado, bloco no prompt, geração com a leitura),
+  `test/studio-critique.test.js` (botão, trecho na conversa, arquivo salvo, próximo pedido leva a leitura, selo).
+
+## O chat pode VER o material anexado (ver:) — 08/10/2026
+
+Retorno: no chat do deck do ICFM10, "vc tem acesso ao pdf?" levou a IA a dizer que "consegue ler as figuras
+recortadas e abrir a página inteira", o que era falso: do documento o chat recebe o texto e o inventário (legendas,
+caminhos), nunca as imagens. Sem jeito de olhar, ela não conseguia consultar o material de verdade.
+
+- `ver: [arquivos]` na resposta da IA (como o `test:` dos slides api): o Studio carrega as imagens pedidas (só de
+  dentro da pasta da apresentação, até 6: recortes em items[].image e páginas inteiras em pages), chama de novo com
+  elas anexadas ("material: <arquivo>") e a IA responde já vendo; até 2 rodadas (`lookableFiles`, `ai-chat-route.js`).
+- Regra no formato da resposta: pedir para ver antes de responder sobre o que a figura mostra; nunca dizer que viu o
+  que não pediu; nunca dizer que não tem acesso ao material.
+- Ao vivo (deck do ICFM10, modelo de verdade): "qual a ordem das 5 variáveis mais importantes da Figura 4b?" — pediu
+  o recorte e a página 6, leu hand ≈ 100, elevation ≈ 45… e avisou que são leituras do eixo; 22 s, nada mudou.
+- Teste: `test/document-visuals.test.js` (pede, recebe a imagem rotulada, caminho para fora da pasta recusado).
+
+## Paper para congresso, 2ª rodada: equações, redesenho com volta ao original, dados corrompidos — 08/10/2026
+
+Pedido: equação não precisa de recorte se vira LaTeX (e, se precisar, que o recorte preste); gráfico pode ser
+redesenhado, desde que o chat consiga voltar ao original; a IA cria gráficos dos números do texto por iniciativa.
+Teste com o paper do eucalipto (o das equações) e o ICFM10 (Aricanduva).
+
+- **Equação pela camada de texto** (`equationGroups`, `assignEquations`): equação de Word/LaTeX é texto (𝑑, 𝜋, ∑);
+  os grupos de caracteres matemáticos da página dão a caixa exata (sem a vizinha, a prosa e o "(4)"). A visão punha
+  as caixas deslocadas uma equação para baixo (a Eq. 4 sumia e a 5 levava o recorte e o LaTeX da 6): agora casa
+  pelo número impresso, depois pelo conteúdo (letras do LaTeX × texto do PDF, 𝑅𝑀𝑆𝐸→RMSE), por último pela
+  posição. Numerada que a visão esqueceu entra; item repetido sai; equação como imagem cai na régua da imagem.
+- **Releitura no recorte** (`transcribeEquation`): cada equação é relida na própria imagem; a leitura que encolhe
+  (recorte parcial) não troca a da página; "\quad (3)" sai. Com LaTeX, o inventário vai ao modelo SEM o arquivo do
+  recorte (`promptInventory`): o slide usa a fórmula nativa. Resultado: 16/16 equações dos dois papers corretas.
+- **Tabela sem rows** relida no recorte (`transcribeTable`): vira table nativa e a cobertura reconhece.
+- Um item com caixa inválida sai sozinho (antes a página inteira virava uma imagem só).
+- "Figure 5 shows…" não é legenda (`captionLineStrict`): parava de cobrar "legenda sem arte" na página.
+- **Redesenho com volta**: `sourcePx` (tamanho nativo da imagem embutida) no inventário; regra: esquema → diagram
+  nativo, gráfico com valores no paper → chart nativo, gráfico sem dados/ilustração → modelo de imagem, mapa e foto
+  ficam. O redesenho guarda `original` no elemento (antes o caminho sumia com o image_ref); reconstrução nativa
+  leva `sourceFigure` no slide; "volte ao original" troca o visual por ele (REFERENCIA). Iniciativa: números do
+  texto/tabelas viram chart criado pela IA, com `source`.
+- **Dado corrompido**: `[07/04/2017, HEC-HMS, 0,93, 0,97]` partia "0,93" em 0 e 93 (YAML) e a tabela do ICFM saiu
+  com NSE 0 e R² 93, colunas deslocadas, sem erro. `quoteFlowDecimals` põe entre aspas "dígitos,dígitos" sem espaço
+  em lista separada por ", " (`[10,20,30]` fica); `sanitizeCheck` recusa tabela com linha de tamanho diferente do
+  cabeçalho (volta para a IA).
+- **"NaN" e "km^2^"**: `number` com valor "37,67%" ou "1521 km^2^" mostrava NaN (o contador só aceitava número):
+  `parseCounterValue` lê no formato brasileiro e separa prefixo/sufixo; expoente/índice viram ²/₂; valor do
+  `stats` passa pela marcação.
+- **Título encolhido pela IA** (titleSize 40 "para dar espaço à figura"): regra no prompt e achado da revisão.
+- **Tarefa parada horas em "Pensando…"**: o relay manda "estou vivo" e o raciocínio enquanto o modelo pensa, e cada
+  pedaço zerava o relógio; um modelo em laço nunca terminava. Agora o limite da 1ª palavra de TEXTO (600 s) vale
+  mesmo com os sinais de vida (`AI_THINKING_LOOP`), e a chamada ganha uma tentativa a mais SEM raciocínio (a mesma
+  tarefa sai em segundos). Aconteceu duas vezes seguidas com o DeepSeek Flash na conferência de cobertura.
+- **Checagem de números** (`unsupportedNumbers` + `checkNumbers`, na geração e no chat com anexo): todo número
+  visível (texto e dados de gráfico/tabela) que não está no material volta para a IA corrigir, mostrar a conta ou
+  tirar; arredondamento do valor do paper vale, contagem pequena não é cobrada. Pegou "ANOVA p = 0,109" que o artigo
+  do eucalipto não tem (lido errado do gráfico); nos outros dois decks, nenhum alarme falso.
+- Resultado (mesmos PDFs): eucalipto com o fluxograma como diagram nativo (`sourceFigure`), equações nativas com as
+  variáveis explicadas, dois gráficos criados dos números do texto; ICFM10 com a tabela certa, km² e todas as
+  figuras. "Volte para a figura original" pelo chat (modelo de verdade) trocou o donut pelo mapa em 8 s, citando o
+  `sourcePx` baixo. Regra nova: gráfico criado por iniciativa não substitui mapa ou foto.
+
+## Apresentação de congresso a partir de paper: figuras, cobertura e frase gigante — 08/10/2026
+
+Retorno de quem usa: figuras ignoradas, com a legenda junto, cortadas ou fora de proporção; conteúdo fraco (contexto,
+objetivos, metodologia); slides de uma frase gigante; a IA sem senso crítico/ferramenta para se corrigir. Método:
+dois PDFs quaisquer (Rev. Bras. Cartogr. 2025, volume de eucalipto por ETR; RBGF 2020, LiDAR na bacia do Beberibe)
+gerados pelo caminho do Studio (`/api/ai/context` + `/api/library/decks/ai`, modelo do modelrelay), tópico
+"Laboratório congresso" da biblioteca. Os decks são diagnóstico, não foram retocados.
+
+- **Recorte pela imagem embutida** (`snapToImages`, `pdfLayout` em `src/ai/document-visuals.js`): o pdf.js dá a
+  posição exata de cada imagem da página (lista de operações). Caixa da visão sobre imagem(ns) vira a imagem (ou a
+  união dos painéis): sem legenda, sem "Fonte:", sem prosa, proporção do original. Antes: legenda de cima curta
+  (ABNT, centralizada) entrava sempre (a regra exigia linha mais larga que meia figura), "Fonte: Os autores" e o
+  parágrafo de baixo também, e os mapas de dois painéis do RBGF saíam em dois recortes com tira do vizinho.
+  Fundo de página escaneada e logo pequeno não servem de régua; prancha enorme fica com a caixa aparada.
+- **Duplicatas fundidas** (`mergeDuplicateCrops`): dois itens no mesmo recorte viram um, com a legenda numerada.
+- **Camada de texto** (gráfico vetorial, tabela, equação): legenda de cima de qualquer largura e linha de crédito
+  (`creditLineStart`: Fonte/Source/Elaboração) ficam de fora; linha de prosa passando pela borda não estica o recorte.
+- **Margem branca aparada** no recorte (`cropRegions` com `trim`; a tinta é medida antes de aparar) e o inventário
+  traz `width`/`height` do recorte. Cache do inventário: `visualVersion` 5 (recorta de novo o que já foi anexado).
+- **Cobertura** (`uncoveredVisuals` + `coverDocumentVisuals` em `deck-ai.js`): `ensureVisualCoverage` existia mas
+  ninguém chamava. Agora, depois do rascunho, figura/tabela NUMERADA sem slide volta para a IA encaixar no ponto da
+  narrativa (uma rodada; o resto vai em `coverage.missing`, sem slide enfiado no fim). Vale no Criar com IA e no
+  chat quando a mensagem anexa documento e a resposta monta a maior parte do deck (`changed` exposto pelo editDeck).
+- **Revisão de texto sem visão** (`auditText` em `src/ai/quality.js`, sempre roda dentro da revisão): frase longa
+  em statement/headline/quote e excesso de telas de frase única (mais de 2 ou 15%) viram achados para a correção.
+- **Legenda colada na imagem** (`clearCaptionEdges`): a caixa de texto do pdf.js termina na linha de base, então as
+  pernas da legenda logo acima da imagem entravam como uma tira; linha de legenda/crédito na borda empurra a borda.
+- **Motor**: `full` com figura do documento (ou `fit: contain`) e texto vira a composição de figura inteira (título
+  no alto, legenda embaixo; decidido em `inferLayout` via `fullAsFigure`, para a casca do slide não ser a de página
+  inteira que escondia o título), mesmo com `overlay: none`; `headline` longa sai em title/h2 (era o objetivo
+  inteiro a 300 px); cartão cujo texto é só fórmula mostra a fórmula grande (`cd-math`).
+- **Proporção e corte**: figura do documento é sempre `contain` (o cover automático de até 20% comia eixo e
+  legenda; `fill`/`stretch` achatavam o mapa). `crop:` em caixa de outra proporção esticava: a apresentação mede a
+  caixa e encaixa a região inteira (`fitCrops` em `src/runtime/fit.js`, `data-crop` no `<img>`).
+- Antes × depois (mesmos PDFs, mesmo modelo): Beberibe 16 → 24 slides, 4 → 7 figuras, nenhuma com texto por cima,
+  objetivo virou lista com três objetivos, arco completo; eucalipto 21 slides, todas as figuras limpas (antes com
+  legenda, "Fonte" e prosa no recorte). Ainda aberto: recorte de equação pela visão é impreciso (pega a vizinha e a
+  prosa); como toda equação vem com `latex`, o slide usa a fórmula nativa e o recorte não aparece.
+- Testes antigos que falhavam na main: `api-ai-loop` (o mock não previa a decisão de pesquisa do chat, fase 2) e
+  o da exploração (mesmo achado em todas as rodadas, desde a regra "achado idêntico encerra as tentativas").
+- **Prompt**: arco de apresentação de paper (contexto com dado, lacuna, objetivo geral/específicos em slide de
+  conteúdo, área/dados, método com variáveis e unidades, cada figura numerada no seu resultado com título-afirmação,
+  discussão, conclusões, limitações) e composição pela proporção do recorte. REFERENCIA: `full` e `headline`.
+- Testes: `test/document-visuals.test.js` (PDF real do Chrome com legenda, imagem 2:1, "Fonte" e painel duplicado;
+  snap, fusão, crédito, legenda curta, borda da legenda, cobertura pelo chat), `test/ai.test.js` (cobertura na
+  geração, auditText), `test/engine.test.js` (full, headline, cartão com fórmula), `test/fit-wide.test.js` (figura
+  do documento contain, crop sem esticar, no navegador).
+
 ## Avaliação fora da hidrologia — 03/10/2026
 
 - Plano: `docs/PLANO-TESTE-DESINFORMACAO.md`.

package/docs/REFERENCIA.md

@@ -66,7 +66,7 @@ slides:
 | `back` | id (ou número) do slide para onde o botão **Voltar** do canto leva; o botão mostra o título do destino |
 | `next` | id (ou número) do slide para onde o avanço leva **no fim deste slide** (o fim de um caminho volta ao mapa, em vez de seguir a ordem) |
 
-Títulos equilibram as linhas sem quebrar palavras arbitrariamente. A hifenização automática respeita o idioma do deck (`lang`, padrão `pt-BR`).
+Títulos equilibram as linhas sem quebrar palavras arbitrariamente. A hifenização automática respeita o idioma do deck (`lang`, padrão `pt-BR`). Deck em outro idioma grava `lang` (`en`, `es`…): os números de contadores, gráficos e mapas seguem o idioma (em inglês, `1,403` e `0.93`).
 
 ## Marcação inline (qualquer texto)
 
@@ -110,8 +110,8 @@ Tabela em markdown no meio de um texto (`problem`, `body`, `text`, passo do `sol
 | `canvas` | `elements: [{…, x, y, w, h}]` | posicionamento absoluto em 1920 × 1080 |
 | `end` | `title, subtitle, contacts, figure, qr, qrLabel` | encerramento; `qr: <link>` põe um QR code ao lado (ex.: LinkedIn) |
 | `references` | `title, items` | fontes (2 colunas) |
-| `headline` | `kicker, text, as, size, caption` | manchete: uma frase enorme ocupando o slide |
-| `full` | `figure` (ou `image`/`image_prompt`), `kicker, title, caption, overlay: bottom\|left\|center\|none, fit, titleSize` | figura/imagem de página inteira com texto por cima; com `image_prompt` a IA gera a página toda |
+| `headline` | `kicker, text, as, size, caption` | manchete: uma frase CURTA (até ~12 palavras) enorme ocupando o slide; frase longa sai menor (como no `statement`) e conta como slide de frase única (no máximo 2 por deck) |
+| `full` | `figure` (ou `image`/`image_prompt`), `kicker, title, caption, overlay: bottom\|left\|center\|none, fit, titleSize` | figura/imagem de página inteira com texto por cima; com `image_prompt` a IA gera a página toda. Figura do documento (`contexto/visuais/…`) ou `fit: contain` com texto não leva véu: sai com o título no alto, a figura inteira e a legenda embaixo (como `image`) |
 | `kinetic` | `figure, beats: [{text, style, position, color, size, tag}], autoplay, interval` | frases curtas em sequência sobre uma cena; avanço manual ou automático |
 | `bento` | `title, tiles: [{title, text, value, icon, figure, size: big\|wide\|tall, hl}], cols, build` | mosaico de blocos de tamanhos diferentes |
 | `funnel` | `title, stages: [{title, value, text, hl}], build` | funil que afunila etapa a etapa |
@@ -539,7 +539,7 @@ aparecem (`showValues: true` força os valores).
 **SVG próprio**: `{ svg: "<svg viewBox='0 0 100 100'>…</svg>" }` — use `style="fill:var(--fg)"`, `var(--hi)`, `var(--em)` para seguir o tema.
 **Imagem**: `{ image: foto.jpg, fit: cover }` (caminho relativo ao YAML; é embutida no HTML). Sem `fit`, a imagem preenche a caixa, mas cabe inteira (`contain`) quando o corte passaria de 20% (gráfico com eixo e legenda na borda, esquema largo numa coluna alta); solta no fluxo (num `add`) e sem altura, não passa de 420 px. Para foto que pode ser cortada, `fit: cover`; para gráfico, `fit: contain`.
 **Imagem gerada por IA**: `{ image_prompt: "descrição visual, em inglês", fit: cover }` (sai sem texto: rótulos, números e títulos vão no slide; se a ilustração precisa de rótulos dentro dela, diga quais no prompt, em português e entre aspas: `with labels "Divisor de água", "Rio"`) — `sagadeck imagens deck.yaml` gera o arquivo em `imagens/` com o modelo de imagem e troca por `image:`.
-**Redesenhar uma figura do deck** (xerox, escaneada, borrada): `{ image_prompt: "Clean up and redraw THIS EXACT figure… (o que ela mostra, as cores)", image_ref: imagens/original/mapa.png, fit: contain }` — o modelo de imagem recebe a figura como base e devolve o redesenho; se não sair, fica a figura de base.
+**Redesenhar uma figura do deck** (xerox, escaneada, borrada): `{ image_prompt: "Clean up and redraw THIS EXACT figure… (o que ela mostra, as cores)", image_ref: imagens/original/mapa.png, fit: contain }` — o modelo de imagem recebe a figura como base e devolve o redesenho; se não sair, fica a figura de base. Depois do redesenho, o elemento guarda a figura de base em `original` (ex.: `{ image: imagens/ia-1a2b.png, original: contexto/visuais/…/fig.png, fit: contain }`). Figura de documento anexado (PDF) traz no inventário `sourcePx` (tamanho nativo da imagem): esquema de caixas e setas borrado vira `diagram` nativo fiel; gráfico com os valores no paper vira `chart` nativo com os números exatos; gráfico sem os dados à mão e ilustração podem ser redesenhados assim; mapa e foto ficam. Reconstrução nativa de figura do documento leva no slide `sourceFigure: contexto/visuais/…/fig.png`. **Origem do conteúdo** (deck com material anexado): cada slide de conteúdo leva `provenance: material` (o que afirma está no material), `provenance: derivado` (reorganização, cálculo ou gráfico feito a partir dos números do material) ou `provenance: proprio` (inclusão da IA: contexto, analogia, exemplo, crítica), com `provenanceNote` curta quando não for `material`; o Studio mostra um selo na miniatura, a apresentação não. O deck grava `context.autoria`: `autor` (a pessoa apresenta o próprio trabalho: fiel ao material, crítica e perguntas prováveis nas notes) ou `livre` (aula, resenha, journal club, divulgação, tema geral: conteúdo próprio liberado, marcado). A **leitura crítica** do material (inconsistências, achados escondidos, perguntas prováveis, limitações, slide que representa mal o material, cada item com trecho literal conferido) fica em `.sagadeck/leitura-critica.json` e acompanha os pedidos ao chat. **Voltar ao original** ("mantenha a figura original", "volte para o gráfico do paper"): o visual do slide vira `figure: { image: <sourceFigure ou original>, fit: contain }`, sem mexer no texto. Números que o paper só dá no texto ou em tabela podem virar `chart` criado pela IA, com os valores exatos e `source` dizendo de onde vieram. Equação com `latex` no inventário vai como fórmula nativa (`math`, `equations`), nunca como o recorte.
 
 ## Notas / roteiro (`notes`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sagadeck",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "Gerador de apresentações: YAML -> HTML animado + PowerPoint editável, com temas e figuras geradas na hora.",
   "type": "module",
   "bin": {