sagadeck 1.2.0

package/src/ai/usage.js

@@ -0,0 +1,17 @@
+// Medição por tarefa, isolada de outras pessoas/requisições concorrentes.
+import { AsyncLocalStorage } from 'node:async_hooks';
+const scope = new AsyncLocalStorage();
+export const currentUsage = () => scope.getStore();
+export async function measureLLM(run) {
+  const usage = { calls: 0, failedCalls: 0, promptTokens: 0, completionTokens: 0, missingUsage: 0, reportedCost: 0, missingCost: 0 };
+  const result = await scope.run(usage, run);
+  return { result, usage };
+}
+export function recordUsage(metrics, result) {
+  const u = result?.usage;
+  if (Number.isFinite(u?.prompt_tokens) && Number.isFinite(u?.completion_tokens)) {
+    metrics.promptTokens += u.prompt_tokens; metrics.completionTokens += u.completion_tokens;
+  } else metrics.missingUsage++;
+  if (Number.isFinite(u?.cost)) metrics.reportedCost += u.cost;
+  else metrics.missingCost++;
+}

package/src/ai/variety.js

@@ -0,0 +1,80 @@
+// Variedade de um deck: mede o que deixa uma apresentação repetitiva (e todos os decks com a mesma cara).
+// É métrica, não decisão: quem decide como variar é a IA (generateDeck revisa; o Studio oferece no Ritmo).
+
+const LISTY = new Set(["cards", "list", "steps", "stats", "bento", "agenda", "references"]);
+const IMPACT = new Set(["headline", "number", "statement", "full", "quote", "question", "poll", "image", "section"]);
+const FRAME = new Set(["cover", "end"]);
+
+export function varietyReport(spec) {
+  const slides = (spec?.slides || []).map((s) => ({ layout: s.layout || "blocks", tone: s.tone || "light" }));
+  const body = slides.filter((s) => !FRAME.has(s.layout));
+  const n = body.length;
+  const problems = [];
+  const distinct = new Set(body.map((s) => s.layout)).size;
+
+  // 3+ slides seguidos com o mesmo layout
+  const runs = [];
+  for (let i = 0; i < slides.length;) {
+    let j = i;
+    while (j + 1 < slides.length && slides[j + 1].layout === slides[i].layout) j++;
+    if (j - i + 1 >= 3 && !FRAME.has(slides[i].layout)) runs.push({ layout: slides[i].layout, from: i + 1, to: j + 1 });
+    i = j + 1;
+  }
+  runs.forEach((r) => problems.push(`${r.to - r.from + 1} slides seguidos no mesmo layout (${r.layout}, slides ${r.from}–${r.to})`));
+
+  if (n >= 6) {
+    const want = Math.min(8, Math.ceil(n * 0.5));
+    if (distinct < want) problems.push(`só ${distinct} layouts diferentes em ${n} slides de conteúdo (bom: ${want} ou mais)`);
+    const listy = body.filter((s) => LISTY.has(s.layout)).length;
+    if (listy / n > 0.45) problems.push(`${listy} de ${n} slides são listas/cartões — falta respiro (manchete, número grande, imagem, pergunta)`);
+    if (!body.some((s) => IMPACT.has(s.layout))) problems.push("nenhum slide de impacto (manchete, número grande, frase, página inteira, pergunta)");
+    if (new Set(slides.map((s) => s.tone)).size === 1) problems.push(`todos os slides no mesmo tom (${slides[0].tone}) — alterne com escuro/destaque nos momentos-chave`);
+  }
+  const counts = {};
+  body.forEach((s) => (counts[s.layout] = (counts[s.layout] || 0) + 1));
+  return { slides: slides.length, distinct, runs, counts, problems, ok: problems.length === 0 };
+}
+
+// Direções criativas: cada deck gerado sorteia um jeito de contar (e de se parecer), para dois decks sobre
+// assuntos parecidos não saírem iguais.
+export const CREATIVE_DIRECTIONS = [
+  "Keynote minimalista: uma frase de abertura sem ilustração, grandes espaços vazios, composição central, um número por ideia. Considere prata; destaque em cor apenas na virada.",
+  "Investigação editorial: abra com uma cena concreta, revele pistas por enquadramentos e comparações, entregue a conclusão no final. Considere editorial; serifas, linhas finas, papel claro e um único contraste escuro.",
+  "Workshop geométrico: abra com uma escolha da plateia, alterne desafios curtos, diagramas e timer. Considere bauhaus ou pop; formas primárias, assimetria e revelação por clique.",
+  "Estudo de caso documental: contexto → problema → tentativa → resultado → lição. Considere jornal; manchetes, evidências visuais, cronologia e legendas curtas. Só use dados do briefing ou dados verificados.",
+  "Contraponto: abra com duas possibilidades em comparação, questione uma crença e mostre uma evidência decisiva. Considere sinal; contraste firme, pouco ornamento e uma frase final que retoma a abertura.",
+  "Atlas visual: conte a história com páginas inteiras, diagramas e detalhes ampliados; texto como legenda. Considere oceano; alterne escala, posição e composição, sem usar um mosaico em toda página.",
+  "Sala de decisão: peça a decisão no começo, mostre evidências, opções, riscos e o próximo marco. Considere noite; ouro discreto, tipografia leve, gráficos limpos e transições suaves.",
+  "Palco elétrico: abra com uma pergunta provocadora em tamanho gigante, crie expectativa, pause e revele. Considere aurora; tela escura, uma cor luminosa, números monumentais e participação real da plateia.",
+  "Caderno de descoberta: uma pergunta inicial, um mapa de hipóteses, uma tentativa e uma descoberta. Considere rabisco; desenhos, setas e anotações visuais, com espaço para a audiência pensar.",
+  "Laboratório vivo: prever → observar → explicar → experimentar. Considere terminal; use codewalk para ler código por etapas, spotlight para screenshots e uma pergunta antes da resposta. Saídas simuladas devem ser identificadas.",
+  "Lançamento de produto: primeiro o benefício, depois uma demonstração visual, um detalhe ampliado, prova e convite. Considere prata ou oceano; mostre o produto em escala, evitando uma sequência de cartões de funcionalidades.",
+  "Manifesto tipográfico: alterne frases muito curtas, uma pausa visual, contrastes de escala e uma conclusão coletiva. Considere editorial ou bauhaus; capa assimétrica sem ícone decorativo e cada ato com composição própria.",
+  "Cinema hacker de bom gosto: capa escura e cinematográfica com poeira de luz à deriva, transições morph entre cenas e saída nas viradas, cada slide estático com um detalhe vivo discreto que ecoa a capa sem repeti-la, e uma demonstração visual escolhida pelo problema de negócio. Points é 2D; para areia 3D girando, planeje vídeo e aguarde autorização quando exigida. Respeite o fundo solicitado; Considere noite ou prisma; paleta luzquente; brancos quentes e âmbar de luz de prédio, nunca neon chapado; fundo escuro quente ou branco quente, cor de joia só no detalhe.",
+];
+
+export function pickDirection(seed = Math.random()) {
+  return CREATIVE_DIRECTIONS[Math.floor(seed * CREATIVE_DIRECTIONS.length) % CREATIVE_DIRECTIONS.length];
+}
+
+// Um baralho embaralhado distribui todas as direções antes de repetir. O estado tem tamanho fixo,
+// dura só nesta sessão do servidor e não armazena o conteúdo das apresentações.
+export function createDirectionPicker(random = Math.random) {
+  let remaining = [];
+  let previous;
+  return () => {
+    if (!remaining.length) {
+      remaining = [...CREATIVE_DIRECTIONS];
+      for (let i = remaining.length - 1; i > 0; i--) {
+        const j = Math.min(i, Math.max(0, Math.floor(random() * (i + 1)) || 0));
+        [remaining[i], remaining[j]] = [remaining[j], remaining[i]];
+      }
+      // Também evita a repetição na fronteira entre dois baralhos.
+      if (remaining.at(-1) === previous) [remaining[0], remaining[remaining.length - 1]] = [remaining.at(-1), remaining[0]];
+    }
+    previous = remaining.pop();
+    return previous;
+  };
+}
+
+export const nextDirection = createDirectionPicker();

package/src/ai/video-frames.js

@@ -0,0 +1,24 @@
+// Frame nativo da apresentação: referência visual local para gerar um clipe.
+import fs from 'node:fs';
+import path from 'node:path';
+import {loadSpec} from '../build.js';
+import {slideSnapshots} from '../studio/snapshot.js';
+
+export async function videoFrame(request,{cwd,snapshot=slideSnapshots}={}) {
+ if(!cwd)throw Error('Abra uma apresentação salva para capturar um frame.');
+ const root=path.resolve(cwd);
+ const within=name=>{const file=path.resolve(root,name),rel=path.relative(root,file);if(!rel||rel.startsWith('..')||path.isAbsolute(rel))throw Error('O frame e o deck devem ficar na pasta da apresentação.');return file;};
+ const files=fs.readdirSync(root).filter(name=>/\.ya?ml$/i.test(name));
+ const name=request.deck||files.find(name=>path.basename(name,path.extname(name))===path.basename(root))||(files.length===1?files[0]:null);
+ if(!name)throw Error('Informe deck com o nome do YAML desta apresentação.');
+ const spec=loadSpec(within(name));
+ const index=Number(request.slide)-1;
+ if(!Number.isInteger(index)||!spec.slides[index])throw Error('slide deve ser o número de um slide existente, começando em 1.');
+ const output=within(request.out||`imagens/frame-slide-${index+1}.jpg`);
+ if(!/\.jpe?g$/i.test(output))throw Error('O frame nativo deve ser salvo como JPG.');
+ if(fs.existsSync(output))throw Error('O frame de saída já existe; escolha outro nome.');
+ const frames=await snapshot(spec,index,{mode:'final',width:1920,maxFrames:1});
+ if(!frames[0]?.dataUrl?.startsWith('data:image/jpeg;base64,'))throw Error('Não foi possível capturar o slide.');
+ fs.mkdirSync(path.dirname(output),{recursive:true});fs.writeFileSync(output,Buffer.from(frames[0].dataUrl.split(',')[1],'base64'),{flag:'wx'});
+ return {action:'frame',costIncurred:false,slide:index+1,file:path.relative(root,output).split(path.sep).join('/'),width:1920};
+}

package/src/ai/video-generation.js

@@ -0,0 +1,126 @@
+import { mediaPrompt } from './art-direction.js';
+// Operações curtas e retomáveis: o chat não fica preso esperando o render do provedor.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const BASE='https://openrouter.ai/api/v1';
+export function parseVideoArgs(args){
+ const result={};for(let i=0;i<args.length;i++){
+  const m=args[i].match(/^--([^=]+)(?:=(.*))?$/);if(!m)throw new Error(`Argumento inesperado: ${args[i]}`);
+  result[m[1]]=m[2]??(args[i+1]&&!args[i+1].startsWith('--')?args[++i]:true);
+ }return result;
+}
+export function videoApiURL(value){
+  const url=new URL(String(value).startsWith('/api/v1/')?value:String(value).replace(/^\//,''),BASE+'/');
+  if(url.origin!=='https://openrouter.ai'||!url.pathname.startsWith('/api/v1/videos'))throw new Error('Polling precisa usar a API de vídeo do OpenRouter.');
+  return url.href;
+}
+// quanto custa ANTES de gerar (para mostrar na aprovação): catálogo é de graça; null se não der para estimar
+export async function estimateVideoCost({model,duration,resolution},{key=process.env.SAGADECK_VIDEO_KEY||process.env.OPENROUTER_API_KEY,fetcher=fetch}={}){
+  try{
+   if(!key)return null;
+   const r=await fetcher(`${BASE}/videos/models`,{headers:{Authorization:`Bearer ${key}`},signal:AbortSignal.timeout(15000)});
+   if(!r.ok)return null;
+   const meta=(await r.json()).data?.find((m)=>m.id===model||m.canonical_slug===model);
+   const skus=meta?.pricing_skus||meta?.pricing||null;
+   const perSec=Number(skus?.[/1080|1k|2k|4k/i.test(String(resolution||''))?'per-video-second-1080p':'per-video-second']);
+   if(!Number.isFinite(perSec)||perSec<0)return null;
+   const total=perSec*Number(duration||0);
+   return Number.isFinite(total)&&total>0?`~$${total.toFixed(2)}`:null;
+  }catch{return null;}
+}
+function within(dir,name){
+ const target=path.resolve(dir,name),rel=path.relative(path.resolve(dir),target);
+ if(!rel||rel.startsWith('..')||path.isAbsolute(rel))throw new Error('Salve o vídeo dentro da pasta da apresentação.');
+ return target;
+}
+export async function videoOperation(request,{cwd,key=process.env.SAGADECK_VIDEO_KEY||process.env.OPENROUTER_API_KEY,fetcher=fetch}={}){
+ if(request.action==='frame'){const {videoFrame}=await import('./video-frames.js');return videoFrame(request,{cwd});}
+ if(!key)throw new Error('Configure SAGADECK_VIDEO_KEY ou OPENROUTER_API_KEY para a API de vídeo. O modelo de texto não gera vídeo.');
+ const api=async(value,body)=>{
+  const r=await fetcher(videoApiURL(value),{method:body?'POST':'GET',headers:{Authorization:`Bearer ${key}`,'Content-Type':'application/json'},...(body?{body:JSON.stringify(body)}:{}),signal:AbortSignal.timeout(30000)});
+  if(!r.ok)throw new Error(`API de vídeo retornou HTTP ${r.status}.`);return r.json();
+ };
+ const action=request.action||'plan';
+ if(['plan','submit'].includes(action)){
+  const model=request.model||'google/veo-3.1-lite',catalog=await api('/videos/models');
+  const meta=catalog.data?.find(m=>m.id===model||m.canonical_slug===model);if(!meta)throw new Error(`Modelo de vídeo indisponível: ${model}`);
+  const body={model,prompt:String(request.prompt||''),duration:Number(request.duration||4),resolution:request.resolution||'720p',aspect_ratio:request.aspect||'16:9',generate_audio:false};
+  if(!body.prompt.trim())throw new Error('Descreva o clipe antes de gerar.');
+  body.prompt=mediaPrompt(body.prompt); // plan mostra exatamente o prompt que submit enviará.
+  if(!Number.isInteger(body.duration)||body.duration<1)throw new Error('Duração precisa ser um número inteiro positivo.');
+  for(const [field,list] of [['duration',meta.supported_durations],['resolution',meta.supported_resolutions],['aspect_ratio',meta.supported_aspect_ratios]])if(list?.length&&!list.map(String).includes(String(body[field])))throw new Error(`${field} não suportado por ${model}.`);
+  if(request.seed!=null){body.seed=Number(request.seed);if(!Number.isInteger(body.seed)||body.seed<0)throw new Error('seed precisa ser inteiro não negativo.');}
+  const frames=[];
+  for(const [field,type] of [['firstFrame','first_frame'],['lastFrame','last_frame']])if(request[field]){
+    if(!cwd)throw new Error('Abra a apresentação para usar frames locais.');
+    const file=within(cwd,request[field]),ext=path.extname(file).toLowerCase();
+    if(!['.png','.jpg','.jpeg','.webp'].includes(ext))throw new Error('Frame precisa ser PNG, JPEG ou WebP.');
+    if(fs.statSync(file).size>10*1024*1024)throw new Error('Frame excede 10 MB.');
+    frames.push({type:'image_url',frame_type:type,image_url:{url:`data:image/${ext==='.jpg'?'jpeg':ext.slice(1)};base64,${fs.readFileSync(file).toString('base64')}`}});
+  }
+  if(frames.length)body.frame_images=frames;
+  const summary={...body,...(frames.length?{frame_images:frames.map(f=>({frame_type:f.frame_type,local:true}))}:{})};
+  if(action==='plan')return{action,costIncurred:false,request:summary,pricing:meta.pricing_skus||meta.pricing||null};
+  if(!cwd)throw new Error('Abra uma apresentação salva antes de gerar vídeo.');
+  const output=within(cwd,request.out||`videos/clip-${crypto.randomUUID()}.mp4`);if(fs.existsSync(output))throw new Error('O arquivo de saída já existe; escolha outro nome.');
+  const job=await api('/videos',body);
+  if(!/^[\w-]+$/.test(job.id||''))throw new Error('A API não devolveu um identificador de job válido.');
+  const folder=path.join(cwd,'.sagadeck','videos');fs.mkdirSync(folder,{recursive:true});
+  const record={id:job.id,polling_url:videoApiURL(job.polling_url||`/videos/${job.id}`),output:path.relative(cwd,output).split(path.sep).join("/"),request:summary,createdAt:new Date().toISOString()};
+  fs.writeFileSync(path.join(folder,job.id+'.json'),JSON.stringify(record,null,2),{flag:'wx'});
+  return{id:job.id,status:job.status,output:record.output,nextAction:'status'};
+ }
+ if(!['status','download'].includes(action))throw new Error('Ação de vídeo: plan, submit, status ou download.');
+ if(!/^[\w-]+$/.test(request.id||''))throw new Error('Informe o id da geração.');
+ const file=within(cwd,`.sagadeck/videos/${request.id}.json`),record=JSON.parse(fs.readFileSync(file,'utf8'));
+ const job=await api(record.polling_url);
+ if(action==='status'||job.status!=='completed')return{id:record.id,status:job.status,error:job.error||null,cost:job.usage?.cost??null};
+ const output=within(cwd,record.output);if(fs.existsSync(output))return{id:record.id,status:'downloaded',video:record.output,cached:true};
+ const url=new URL(job.unsigned_urls?.[0]||`${BASE}/videos/${record.id}/content?index=0`);
+ if(url.protocol!=='https:')throw new Error('Download do vídeo exige HTTPS.');
+ const r=await fetcher(url.href,{headers:url.origin==='https://openrouter.ai'?{Authorization:`Bearer ${key}`}:{},signal:AbortSignal.timeout(30000)});
+ if(!r.ok)throw new Error(`Download retornou HTTP ${r.status}.`);
+ const mime=r.headers.get('content-type')||'';if(!/^video\/|application\/octet-stream/i.test(mime))throw new Error('O provedor não retornou um arquivo de vídeo.');
+ const chunks=[];let bytes=0;for await(const chunk of r.body){bytes+=chunk.length;if(bytes>100*1024*1024)throw new Error('Vídeo excede 100 MB.');chunks.push(chunk);}
+  const data=Buffer.concat(chunks);if(data.length<12||data.toString('ascii',4,8)!=='ftyp')throw new Error('O resultado não é um MP4 válido.');
+  fs.mkdirSync(path.dirname(output),{recursive:true});fs.writeFileSync(output,data,{flag:'wx'});
+  return{id:record.id,status:'downloaded',video:record.output,bytes,cost:job.usage?.cost??null};
+}
+
+// vigia os jobs do deck: confere andamento (grátis), baixa sozinho o que terminou.
+// para o ticker do Studio avisar "clipe pronto" sem a pessoa ficar olhando.
+const lastCheck = new Map(); // polling_url -> { at, status }
+export async function pollVideoJobs(cwd,{key=process.env.SAGADECK_VIDEO_KEY||process.env.OPENROUTER_API_KEY,fetcher=fetch,cooldownMs=60000}={}){
+  const dir=path.join(path.resolve(cwd),'.sagadeck','videos');
+  let files=[];
+  try{files=fs.readdirSync(dir).filter((f)=>f.endsWith('.json'));}catch{return[];}
+  const out=[];
+  for(const f of files){
+   let record;try{record=JSON.parse(fs.readFileSync(path.join(dir,f),'utf8'));}catch{continue;}
+   if(!record?.id||!record?.polling_url)continue;
+   const done=record.downloadedAt||(record.output&&fs.existsSync(path.join(path.resolve(cwd),record.output))&&record.status==='completed');
+   const cached=lastCheck.get(record.polling_url);
+   let status=record.status||'unknown';
+   if(cached&&Date.now()-cached.at<cooldownMs) status=cached.status;
+   else if(!done&&key){
+    try{
+     const r=await fetcher(record.polling_url,{headers:{Authorization:`Bearer ${key}`},signal:AbortSignal.timeout(15000)});
+     if(r.ok){const job=await r.json();status=job.status||status;lastCheck.set(record.polling_url,{at:Date.now(),status});}
+    }catch{/* sem rede: mantém o último */}
+   }
+   let video=record.output&&fs.existsSync(path.join(path.resolve(cwd),record.output))?record.output:null;
+   if(status==='completed'&&!video&&key){
+    try{
+     const dl=await videoOperation({action:'download',id:record.id},{cwd,key,fetcher});
+     video=dl.video;status='downloaded';
+     record.downloadedAt=new Date().toISOString();record.status='completed';
+     try{fs.writeFileSync(path.join(dir,f),JSON.stringify(record,null,2));}catch{}
+    }catch{/* tenta de novo no próximo ciclo */}
+   }
+   if(video)status='downloaded'; // arquivo em disco manda: pronto para usar, em qualquer chamada
+   out.push({id:record.id,status,video:video||null});
+  }
+  return out;
+}

package/src/ai/web-operation.js

@@ -0,0 +1,31 @@
+import { defaultWeb } from '../research/research.js';
+
+export function webOnlyRunner({signal,onProgress=()=>{},web=defaultWeb}={}) {
+  const run = async command => {
+    if (command.language !== 'web') return {denied:true,stderr:'Este servidor oferece pesquisa web; execução de código local está indisponível.'};
+    onProgress({phase:'command',text:'Pesquisando na web…'});
+    try {return {exitCode:0,stdout:JSON.stringify(await webOperation(JSON.parse(command.code),{web,signal})),stderr:''};}
+    catch(e) {if(signal?.aborted)throw e;return {exitCode:1,stdout:'',stderr:e.message};}
+  };
+  run.description = 'PESQUISA WEB disponível: responda com bloco YAML run: {language: web, why: motivo, code: JSON}. JSON aceita {"action":"search","query":"busca"} ou {"action":"read","url":"URL observada"}. Leia a fonte antes de afirmar fatos. Anexos são exclusivos sem autorização explícita para complementar; blogs e memes servem para humor/opiniões. Não afirme falta de acesso sem tentar. Não peça javascript/python/shell/video: esses comandos estão indisponíveis neste servidor.';
+  return run;
+}
+
+// Ferramenta de leitura explícita: disponível ao chat, sem depender de o LLM ter navegação própria.
+export async function webOperation(request,{web=defaultWeb,signal}={}) {
+  signal?.throwIfAborted();
+  if (process.env.SAGADECK_WEB === '0') throw Error('Pesquisa web desligada neste servidor.');
+  if (request.action === 'search') {
+    const query = String(request.query || '').trim();
+    if (!query || query.length > 1000) throw Error('Informe uma busca de até 1000 caracteres.');
+    const results = await web.search(query);
+    signal?.throwIfAborted();
+    return {query,results:results.slice(0,10)};
+  }
+  if (request.action === 'read') {
+    const doc = await web.fetch(String(request.url || ''));
+    signal?.throwIfAborted();
+    return {...doc,text:String(doc.text || '').slice(0,20000)};
+  }
+  throw Error('web.action: use search ou read.');
+}

package/src/algo-catalog.js

@@ -0,0 +1,153 @@
+// Catálogo de algoritmos prontos para o layout algo, por área (como as toolboxes do MATLAB). Cada um é um programa no
+// Python simples de src/pytrace.js; o slide só passa os dados. Algoritmo novo entra aqui como mais um programa:
+//   program: o código · call(s): a chamada com os dados do slide · view: o que desenhar e onde ficam os ponteiros
+import { pyLiteral } from "./pytrace.js";
+
+const str = (v, d) => pyLiteral(String(v ?? d));
+const graphOf = (s, d) => pyLiteral(s.graph && typeof s.graph === "object" ? s.graph : d);
+const firstKey = (s, d) => (s.graph && typeof s.graph === "object" ? Object.keys(s.graph)[0] : Object.keys(d)[0]);
+
+const GRAFO = { A: ["B", "C"], B: ["A", "D", "E"], C: ["A", "F"], D: ["B"], E: ["B", "F"], F: ["C", "E"] };
+const GRAFO_PESOS = { A: [["B", 4], ["C", 1]], B: [["A", 4], ["C", 2], ["D", 5]], C: [["A", 1], ["B", 2], ["D", 8]], D: [["B", 5], ["C", 8]] };
+
+export const CATALOG = {
+  naive: {
+    area: "texto", name: "Busca ingênua",
+    program: `def busca(texto, padrao):
+    n, m = len(texto), len(padrao)
+    achados = []
+    for i in range(n - m + 1):  # encaixa o padrão na posição {i}
+        j = 0
+        while j < m and texto[i + j] == padrao[j]:  # texto[{i + j}] com padrao[{j}]: {'igual, avança' if j < m and texto[i + j] == padrao[j] else 'para aqui'}
+            j += 1
+        if j == m:
+            achados.append(i)  # achou na posição {i}
+    return achados`,
+    call: (s) => `busca(${str(s.text, "abracadabra")}, ${str(s.pattern, "abra")})`,
+    view: [{ var: "texto", pointers: ["i + j"] }, { var: "padrao", under: "texto", offset: "i", pointers: ["j"] }, { var: "achados" }],
+  },
+  kmp: {
+    area: "texto", name: "KMP (Knuth-Morris-Pratt)",
+    program: `def prefixos(padrao):
+    m = len(padrao)
+    pi = [0] * m
+    k = 0
+    for q in range(1, m):
+        while k > 0 and padrao[k] != padrao[q]:
+            k = pi[k - 1]  # não casou: k volta para {k}
+        if padrao[k] == padrao[q]:
+            k += 1  # casou: {k} letras de prefixo que também são sufixo
+        pi[q] = k  # pi[{q}] = {k}
+    return pi
+
+def kmp(texto, padrao):
+    n, m = len(texto), len(padrao)
+    pi = prefixos(padrao)  # a tabela diz quanto o padrão anda sem voltar no texto
+    achados = []
+    q = 0
+    for i in range(n):
+        ini = i - q  # janela começa em {ini}
+        while q > 0 and padrao[q] != texto[i]:
+            q = pi[q - 1]
+            ini = i - q  # não casou: o padrão pula para {ini}, e o texto não volta
+        if padrao[q] == texto[i]:
+            q += 1  # casou: {q} de {m} letras
+        if q == m:
+            achados.append(i - m + 1)  # achou na posição {i - m + 1}
+            q = pi[q - 1]
+    return achados`,
+    call: (s) => `kmp(${str(s.text, "abababcabababab")}, ${str(s.pattern, "ababab")})`,
+    view: [{ var: "texto", pointers: ["i"] }, { var: "padrao", under: "texto", offset: "ini", pointers: ["q", "k"] }, { var: "pi", as: "cells" }, { var: "achados" }],
+  },
+  quicksearch: {
+    area: "texto", name: "Quick Search (Sunday)",
+    program: `def quick_search(texto, padrao):
+    n, m = len(texto), len(padrao)
+    salto = {}
+    for j in range(m):
+        salto[padrao[j]] = m - j  # letra '{padrao[j]}': pula {m - j}
+    achados = []
+    i = 0
+    while i <= n - m:  # {'encaixa o padrão na posição ' + str(i) if i <= n - m else 'a janela passou do fim do texto'}
+        j = 0
+        while j < m and texto[i + j] == padrao[j]:  # texto[{i + j}] com padrao[{j}]: {'igual, avança' if j < m and texto[i + j] == padrao[j] else 'para aqui'}
+            j += 1
+        if j == m:
+            achados.append(i)  # achou na posição {i}
+        if i + m >= n:
+            break
+        c = texto[i + m]  # olha a letra logo depois da janela: '{c}'
+        i += salto.get(c, m + 1)  # '{c}' manda a janela para {i}
+    return achados`,
+    call: (s) => `quick_search(${str(s.text, "gcatcgcagagagtatacagtacg")}, ${str(s.pattern, "gcagagag")})`,
+    view: [{ var: "texto", pointers: ["i + j", "i + m"] }, { var: "padrao", under: "texto", offset: "i", pointers: ["j"] }, { var: "salto", as: "table" }, { var: "achados" }],
+  },
+  bfs: {
+    area: "grafos", name: "Busca em largura (BFS)",
+    program: `from collections import deque
+
+def bfs(grafo, inicio):
+    visitado = {inicio}
+    fila = deque([inicio])
+    ordem = []
+    while fila:
+        v = fila.popleft()  # sai da fila: {v}
+        ordem.append(v)
+        for w in grafo[v]:  # vizinho de {v}: {w}
+            if w not in visitado:
+                visitado.add(w)
+                fila.append(w)  # {w} ainda não foi visto: entra na fila
+    return ordem`,
+    call: (s) => `bfs(${graphOf(s, GRAFO)}, ${pyLiteral(s.start ?? firstKey(s, GRAFO))})`,
+    view: [{ var: "grafo", as: "graph" }, { var: "fila" }, { var: "ordem" }],
+  },
+  dijkstra: {
+    area: "grafos", name: "Dijkstra (menor caminho)",
+    program: `import heapq
+
+def dijkstra(grafo, origem):
+    dist = {v: float('inf') for v in grafo}
+    dist[origem] = 0
+    fila = [(0, origem)]
+    feito = set()
+    while fila:
+        d, v = heapq.heappop(fila)  # o mais perto ainda aberto: {v} (distância {d})
+        if v in feito:
+            continue
+        feito.add(v)
+        for w, peso in grafo[v]:
+            if d + peso < dist[w]:
+                dist[w] = d + peso  # caminho melhor até {w}: {dist[w]}
+                heapq.heappush(fila, (dist[w], w))
+    return dist`,
+    call: (s) => `dijkstra(${graphOf(s, GRAFO_PESOS)}, ${pyLiteral(s.start ?? firstKey(s, GRAFO_PESOS))})`,
+    view: [{ var: "grafo", as: "graph" }, { var: "dist", as: "table" }, { var: "fila" }],
+  },
+  bst: {
+    area: "árvores", name: "Árvore binária de busca",
+    program: `class No:
+    def __init__(self, valor):
+        self.valor = valor
+        self.esq = None
+        self.dir = None
+
+def insere(raiz, valor):
+    if raiz is None:
+        return No(valor)  # lugar vazio: {valor} vira folha
+    if valor < raiz.valor:  # {valor} < {raiz.valor}? {'sim: desce à esquerda' if valor < raiz.valor else 'não: desce à direita'}
+        raiz.esq = insere(raiz.esq, valor)
+    else:
+        raiz.dir = insere(raiz.dir, valor)
+    return raiz
+
+def monta(valores):
+    raiz = None
+    for x in valores:  # insere {x}
+        raiz = insere(raiz, x)
+    return raiz`,
+    call: (s) => `monta(${pyLiteral(Array.isArray(s.array) ? s.array : [50, 30, 70, 20, 40, 60, 80])})`,
+    view: [{ var: "raiz", from: "monta", as: "tree" }, { var: "valores" }],
+  },
+};
+
+export const CATALOG_AREAS = [...new Set(Object.values(CATALOG).map((c) => c.area))];

package/src/algo-trace.js

@@ -0,0 +1,139 @@
+// Passo a passo de algoritmos (layout algo): o motor roda o algoritmo de verdade sobre o vetor do slide e grava cada
+// passo (comparar, trocar, escrever, pivô, faixa, achou). Quem escreve o slide só diz qual algoritmo e o vetor.
+//   algorithm: bubble | insertion | selection | merge | quick | linear | binary     array: [5, 1, 4]   target: 4
+// Cada passo: { arr, compare: [i, j], swap: [i, j], write: i, pivot: i, range: [lo, hi], sorted: [índices],
+//               found: i, line: n (linha do pseudocódigo), text, comparisons, swaps }
+
+export const ALGO_CODE = {
+  bubble: ["para i de 0 até n-2:", "  para j de 0 até n-2-i:", "    se v[j] > v[j+1]:", "      troca v[j] e v[j+1]", "  (o maior chegou ao fim)"],
+  insertion: ["para i de 1 até n-1:", "  chave = v[i]; j = i - 1", "  enquanto j >= 0 e v[j] > chave:", "    v[j+1] = v[j]; j = j - 1", "  v[j+1] = chave"],
+  selection: ["para i de 0 até n-2:", "  menor = i", "  para j de i+1 até n-1:", "    se v[j] < v[menor]: menor = j", "  troca v[i] e v[menor]"],
+  merge: ["ordena(v, ini, fim):", "  se fim - ini < 1: volta", "  meio = (ini + fim) / 2", "  ordena(v, ini, meio); ordena(v, meio+1, fim)", "  intercala as duas metades"],
+  quick: ["ordena(v, ini, fim):", "  pivô = v[fim]; i = ini", "  para j de ini até fim-1:", "    se v[j] < pivô: troca v[i] e v[j]; i++", "  troca v[i] e v[fim]  (pivô no lugar)", "  ordena os dois lados"],
+  linear: ["para i de 0 até n-1:", "  se v[i] == alvo:", "    achou na posição i", "não achou"],
+  binary: ["ini = 0; fim = n-1", "enquanto ini <= fim:", "  meio = (ini + fim) / 2", "  se v[meio] == alvo: achou", "  se v[meio] < alvo: ini = meio + 1", "  senão: fim = meio - 1", "não achou"],
+};
+export const ALGO_NAMES = { bubble: "Bubble sort", insertion: "Insertion sort", selection: "Selection sort", merge: "Merge sort", quick: "Quicksort", linear: "Busca linear", binary: "Busca binária" };
+
+export function traceAlgorithm(algorithm, input, { target } = {}) {
+  const a = [...input].map(Number);
+  if (!ALGO_CODE[algorithm]) throw new Error(`algoritmo "${algorithm}" não existe (${Object.keys(ALGO_CODE).join(" | ")})`);
+  if (!a.length || a.some((x) => !Number.isFinite(x))) throw new Error("array: uma lista de números, ex.: [5, 1, 4, 2]");
+  if (a.length > 16) throw new Error("array: até 16 números (acima disso não dá para ver o passo a passo)");
+  const steps = [];
+  let comparisons = 0, swaps = 0;
+  const sorted = new Set();
+  const push = (o) => steps.push({ arr: [...a], sorted: [...sorted], comparisons, swaps, ...o });
+  const n = a.length;
+  push({ line: 0, text: `Começo: ${n} números fora de ordem.` });
+  if (algorithm === "bubble") {
+    for (let i = 0; i < n - 1; i++) {
+      let trocou = false;
+      for (let j = 0; j < n - 1 - i; j++) {
+        comparisons++;
+        push({ compare: [j, j + 1], line: 2, text: `Compara ${a[j]} com ${a[j + 1]}.` });
+        if (a[j] > a[j + 1]) { [a[j], a[j + 1]] = [a[j + 1], a[j]]; swaps++; trocou = true; push({ swap: [j, j + 1], line: 3, text: `${a[j + 1]} > ${a[j]}: troca.` }); }
+      }
+      sorted.add(n - 1 - i);
+      push({ line: 4, text: `${a[n - 1 - i]} chegou ao lugar dele.` });
+      if (!trocou) { for (let k = 0; k < n; k++) sorted.add(k); push({ line: 4, text: "Nenhuma troca nesta volta: já está ordenado." }); break; }
+    }
+    sorted.add(0);
+  } else if (algorithm === "insertion") {
+    sorted.add(0);
+    for (let i = 1; i < n; i++) {
+      const key = a[i];
+      let j = i - 1;
+      push({ pivot: i, line: 1, text: `Pega ${key} e procura o lugar dele à esquerda.` });
+      while (j >= 0) {
+        comparisons++;
+        push({ compare: [j, j + 1], pivot: j + 1, line: 2, text: `${a[j]} > ${key}?` });
+        if (a[j] <= key) break;
+        a[j + 1] = a[j]; a[j] = key; swaps++;
+        push({ swap: [j, j + 1], pivot: j, line: 3, text: `Sim: ${a[j + 1]} anda uma casa para a direita.` });
+        j--;
+      }
+      for (let k = 0; k <= i; k++) sorted.add(k);
+      push({ write: j + 1, line: 4, text: `${key} entra na posição ${j + 1}.` });
+    }
+  } else if (algorithm === "selection") {
+    for (let i = 0; i < n - 1; i++) {
+      let min = i;
+      push({ pivot: min, line: 1, text: `Procura o menor a partir da posição ${i}.` });
+      for (let j = i + 1; j < n; j++) {
+        comparisons++;
+        push({ compare: [j, min], pivot: min, line: 3, text: `${a[j]} < ${a[min]}?` });
+        if (a[j] < a[min]) { min = j; push({ pivot: min, line: 3, text: `Novo menor: ${a[min]}.` }); }
+      }
+      if (min !== i) { [a[i], a[min]] = [a[min], a[i]]; swaps++; push({ swap: [i, min], line: 4, text: `Troca: ${a[i]} vai para a posição ${i}.` }); }
+      sorted.add(i);
+      push({ line: 4, text: `${a[i]} está no lugar.` });
+    }
+    sorted.add(n - 1);
+  } else if (algorithm === "merge") {
+    const sort = (lo, hi) => {
+      if (hi - lo < 1) return;
+      const mid = Math.floor((lo + hi) / 2);
+      push({ range: [lo, hi], line: 2, text: `Divide [${lo}..${hi}] ao meio.` });
+      sort(lo, mid); sort(mid + 1, hi);
+      const left = a.slice(lo, mid + 1), right = a.slice(mid + 1, hi + 1);
+      let i = 0, j = 0, k = lo;
+      while (i < left.length && j < right.length) {
+        comparisons++;
+        push({ range: [lo, hi], compare: [lo + i, mid + 1 + j], line: 4, text: `Intercala: ${left[i]} ou ${right[j]}?` });
+        a[k] = left[i] <= right[j] ? left[i++] : right[j++]; swaps++;
+        push({ range: [lo, hi], write: k, line: 4, text: `Escreve ${a[k]} na posição ${k}.` }); k++;
+      }
+      while (i < left.length) { a[k] = left[i++]; swaps++; push({ range: [lo, hi], write: k, line: 4, text: `Sobrou ${a[k]}: vai para a posição ${k}.` }); k++; }
+      while (j < right.length) { a[k] = right[j++]; swaps++; push({ range: [lo, hi], write: k, line: 4, text: `Sobrou ${a[k]}: vai para a posição ${k}.` }); k++; }
+      if (lo === 0 && hi === n - 1) for (let x = 0; x < n; x++) sorted.add(x);
+      push({ range: [lo, hi], line: 4, text: `[${lo}..${hi}] ordenado.` });
+    };
+    sort(0, n - 1);
+  } else if (algorithm === "quick") {
+    const sort = (lo, hi) => {
+      if (lo > hi) return;
+      if (lo === hi) { sorted.add(lo); return; }
+      const p = a[hi];
+      let i = lo;
+      push({ range: [lo, hi], pivot: hi, line: 1, text: `Pivô: ${p}.` });
+      for (let j = lo; j < hi; j++) {
+        comparisons++;
+        push({ range: [lo, hi], pivot: hi, compare: [j, hi], line: 3, text: `${a[j]} < ${p}?` });
+        if (a[j] < p) {
+          if (i !== j) { [a[i], a[j]] = [a[j], a[i]]; swaps++; push({ range: [lo, hi], pivot: hi, swap: [i, j], line: 3, text: `Sim: ${a[i]} vai para o lado dos menores.` }); }
+          i++;
+        }
+      }
+      if (i !== hi) { [a[i], a[hi]] = [a[hi], a[i]]; swaps++; }
+      sorted.add(i);
+      push({ range: [lo, hi], swap: i !== hi ? [i, hi] : undefined, line: 4, text: `O pivô ${p} vai para a posição ${i}: menores à esquerda, maiores à direita.` });
+      sort(lo, i - 1); sort(i + 1, hi);
+    };
+    sort(0, n - 1);
+    for (let x = 0; x < n; x++) sorted.add(x);
+  } else if (algorithm === "linear") {
+    let found = -1;
+    for (let i = 0; i < n; i++) {
+      comparisons++;
+      push({ compare: [i], line: 1, text: `${a[i]} é ${target}?` });
+      if (a[i] === Number(target)) { found = i; push({ found: i, line: 2, text: `Achou ${target} na posição ${i}, depois de ${comparisons} comparações.` }); break; }
+    }
+    if (found < 0) push({ line: 3, text: `Não achou ${target}: olhou os ${n} números.` });
+  } else if (algorithm === "binary") {
+    if (a.some((x, i) => i && a[i - 1] > x)) { a.sort((x, y) => x - y); steps[0] = { ...steps[0], arr: [...a], text: "A busca binária precisa do vetor ordenado: ordenei antes." }; }
+    let lo = 0, hi = n - 1, found = -1;
+    push({ range: [lo, hi], line: 0, text: `Procura ${target} entre as posições ${lo} e ${hi}.` });
+    while (lo <= hi) {
+      const mid = Math.floor((lo + hi) / 2);
+      comparisons++;
+      push({ range: [lo, hi], compare: [mid], line: 2, text: `Meio: posição ${mid} (${a[mid]}).` });
+      if (a[mid] === Number(target)) { found = mid; push({ range: [lo, hi], found: mid, line: 3, text: `Achou ${target} em ${comparisons} comparações (a busca linear levaria até ${n}).` }); break; }
+      if (a[mid] < Number(target)) { lo = mid + 1; push({ range: [lo, hi], line: 4, text: `${a[mid]} < ${target}: descarta a metade da esquerda.` }); }
+      else { hi = mid - 1; push({ range: [lo, hi], line: 5, text: `${a[mid]} > ${target}: descarta a metade da direita.` }); }
+    }
+    if (found < 0) push({ line: 6, text: `Não achou ${target}.` });
+  }
+  if (["bubble", "insertion", "selection", "merge", "quick"].includes(algorithm)) push({ sorted: a.map((_, i) => i), line: -1, text: `Pronto: ${comparisons} comparações e ${swaps} ${algorithm === "merge" ? "escritas" : "trocas"}.` });
+  return steps;
+}