sagadeck 1.8.0 → 1.10.0

package/src/studio/ai-chat-route.js

@@ -105,8 +105,23 @@ _${c.naoConfirmados.length} observação(ões) descartada(s): o trecho citado n
     res.on('close', onClose);
     // Capture o arquivo da tarefa: abrir outro deck não redireciona a escrita.
     const taskWorkspace = { ...owner, spec: structuredClone(owner.spec) };
+    const originFile = owner.file, originPreview = owner.preview;
+    let materialized = null;
     const prompt = body.message || "";
     const spec = body.spec || taskWorkspace.spec;
+    // Conversar com uma prévia não cria arquivo. Edição/imagem ou documento binário precisam da cópia pessoal.
+    const imageOptionsFor = (deck = spec) => {
+      const options = imageOptions(taskWorkspace, withBase(taskWorkspace, deck));
+      if (originPreview && !originFile && taskWorkspace.file && !materialized) {
+        materialized = { id: taskWorkspace.library.idOf(taskWorkspace.file), title: taskWorkspace.spec.title,
+          topic: originPreview.topic, file: taskWorkspace.file };
+        if (owner.file === originFile && owner.preview === originPreview) {
+          owner.file = taskWorkspace.file;
+          owner.preview = null;
+        }
+      }
+      return materialized ? { ...options, baseDir: path.dirname(taskWorkspace.file) } : options;
+    };
     const issues = body.issues || [];
     // a IA vê (e testa) os slides api no ambiente atual, que pode ser o embutido "ensaio"
     if (!apiBlocked(req) && (spec.slides || []).some((sl) => sl && sl.layout === "api")) await ensureEnsaio();
@@ -128,8 +143,11 @@ _${c.naoConfirmados.length} observação(ões) descartada(s): o trecho citado n
         const target = typeof body.targetSlide === "number" ? body.targetSlide : null;
         const visuals = await lookAt(withBase(taskWorkspace, spec), target, prompt, emit);
         // anexos: imagens vão como visão; documentos (id do /api/ai/context) vão como texto
-        let materials = await prepareDocumentMaterials(takeMaterials(taskWorkspace, (Array.isArray(body.attachments) ? body.attachments : [])
-          .filter((a) => a && typeof a === "object" && a.type === "doc").map((a) => a.id)), path.dirname(taskWorkspace.file), {signal,onProgress:emit});
+        let materials = takeMaterials(taskWorkspace, (Array.isArray(body.attachments) ? body.attachments : [])
+          .filter((a) => a && typeof a === "object" && a.type === "doc").map((a) => a.id));
+        if (!taskWorkspace.file && taskWorkspace.preview && materials.some(m => m.bytes)) imageOptionsFor();
+        const materialDir = taskWorkspace.file && !isBundledTemplate(taskWorkspace.file) ? path.dirname(taskWorkspace.file) : null;
+        if (materialDir) materials = await prepareDocumentMaterials(materials, materialDir, {signal,onProgress:emit});
         for (const [i, url] of (Array.isArray(body.attachments) ? body.attachments : []).entries()) {
           if (typeof url === "string" && url.startsWith("data:image/")) visuals.push({ label: `imagem colada pelo usuário ${i + 1}`, dataUrl: url });
         }
@@ -154,7 +172,7 @@ _${c.naoConfirmados.length} observação(ões) descartada(s): o trecho citado n
           targetSlide: target,
           issues,
           images: true, // a IA decide (regra no prompt: só quando pedirem ou aceitarem)
-          imageOptions: imageOptions(taskWorkspace, withBase(taskWorkspace, spec)),
+          imageOptions: () => imageOptionsFor(),
           history,
           onProgress: emit,
           visuals,
@@ -212,6 +230,7 @@ _${c.naoConfirmados.length} observação(ões) descartada(s): o trecho citado n
           result.actions = [...(before.actions || []), ...r.feitos.map((f) => `Mapa: gravei ${f.arquivo} (${f.linhas} ${f.tipo === "contorno" ? "contorno" : "itens"}${f.fonte ? `; fonte: ${f.fonte}` : ""})`), ...r.falhas.map((x) => `Mapa: não deu (${x})`), ...(result.actions || [])];
         }
         if (result.geo?.length) result = { ...result, geo: undefined, talk: true, reply: P ? `${result.reply}\n(Já busquei os dados duas vezes; me diga o que ainda falta.)` : "Os dados do mapa ficam na pasta da apresentação: abra-a pela biblioteca e peça de novo." };
+        if (!taskWorkspace.file && taskWorkspace.preview && !result.talk && !result.variants) imageOptionsFor(result.spec);
         // documento anexado NESTA mensagem e a resposta montou/reescreveu a maior parte do deck (criar a apresentação
         // do paper pelo chat): a mesma conferência de cobertura da geração. Pedido pontual ("use a figura 3 no slide
         // 5") não dispara: mexe em poucos slides.
@@ -220,12 +239,12 @@ _${c.naoConfirmados.length} observação(ões) descartada(s): o trecho citado n
           const rewritten = Array.isArray(result.changed) ? result.changed.length : 0;
           if (rewritten >= Math.max(5, result.spec.slides.length / 2)) {
             const covered = await coverDocumentVisuals(result.spec, { materials, briefing: prompt, say: (s) => emit({ phase: "step", text: s }),
-              edit: (o) => editDeck({ signal, images: true, imageOptions: imageOptions(taskWorkspace, withBase(taskWorkspace, spec)), onProgress: emit, materials, drawCheck: diagramCheck, ...o }) });
+              edit: (o) => editDeck({ signal, images: true, imageOptions: () => imageOptionsFor(), onProgress: emit, materials, drawCheck: diagramCheck, ...o }) });
             signal.throwIfAborted();
             if (covered.spec !== result.spec) { result.spec = covered.spec; result.actions = [...(result.actions || []), ...covered.actions]; }
             if (covered.coverage?.missing.length) result.actions = [...(result.actions || []), `Sem slide (figuras/tabelas do material): ${covered.coverage.missing.join("; ")}`];
             const checked = await checkNumbers(result.spec, { materials, say: (s) => emit({ phase: "step", text: s }),
-              edit: (o) => editDeck({ signal, images: true, imageOptions: imageOptions(taskWorkspace, withBase(taskWorkspace, spec)), onProgress: emit, materials, drawCheck: diagramCheck, ...o }) });
+              edit: (o) => editDeck({ signal, images: true, imageOptions: () => imageOptionsFor(), onProgress: emit, materials, drawCheck: diagramCheck, ...o }) });
             signal.throwIfAborted();
             if (checked.spec !== result.spec) { result.spec = checked.spec; result.actions = [...(result.actions || []), ...checked.actions]; }
             if (checked.facts?.unsupported.length) result.actions = [...(result.actions || []), `Números sem base no material: ${checked.facts.unsupported.map((b) => `${b.number} (slide ${b.slide})`).join(", ")}`];
@@ -264,7 +283,7 @@ _${c.naoConfirmados.length} observação(ões) descartada(s): o trecho citado n
           emit({ phase: "test", text: reports.every((x) => x.ok) ? "Os testes passaram; conferindo…" : "Corrigindo com base no resultado…" });
           const next = await editDeck({
             spec: withBase(taskWorkspace, result.spec), signal, instruction, targetSlide: target, images: false,
-            imageOptions: imageOptions(taskWorkspace, withBase(taskWorkspace, result.spec)), history: convo, onProgress: emit, apiContext: apiContextFor(req, taskWorkspace),
+            imageOptions: () => imageOptionsFor(result.spec), history: convo, onProgress: emit, apiContext: apiContextFor(req, taskWorkspace),
             drawCheck: diagramCheck, runCommand: commandRunner(req, emit, body, taskWorkspace, signal),
           });
           convo.push({ role: "user", text: instruction });
@@ -286,7 +305,7 @@ _${c.naoConfirmados.length} observação(ões) descartada(s): o trecho citado n
       persist(taskWorkspace);
       if (owner.file === taskWorkspace.file) owner.spec = taskWorkspace.spec;
       return { ...result, spec: taskWorkspace.spec, conflicts: merged.conflicts, kept: merged.kept };
-    }, signal)); } finally { owner.aiChats.delete(requestId); res.off("close", onClose); }
+    }, signal).then(result => materialized ? { ...result, materialized } : result)); } finally { owner.aiChats.delete(requestId); res.off("close", onClose); }
     return true;
   }
   return false;

package/src/studio/command-approval.js

@@ -26,10 +26,9 @@ export async function estimateSubmitCost(command, { commandEnv, W }) {
   try {
     const req = typeof command.code === "object" && command.code !== null ? command.code : JSON.parse(String(command.code || "{}"));
     if (String(command.language || "").toLowerCase() !== "video" || req?.action !== "submit") return null;
-    const { estimateVideoCost } = await import("../ai/video-generation.js");
+    const { estimateVideoCost, videoSetup } = await import("../ai/video-generation.js");
     const { env } = await commandEnv(W).catch(() => ({ env: {} }));
-    const key = env.SAGADECK_VIDEO_KEY || env.OPENROUTER_API_KEY || process.env.SAGADECK_VIDEO_KEY || process.env.OPENROUTER_API_KEY;
-    return await estimateVideoCost({ model: req.model, duration: req.duration, resolution: req.resolution }, { key });
+    return await estimateVideoCost({ model: req.model, duration: req.duration, resolution: req.resolution }, { setup: videoSetup({ env: { ...process.env, ...env } }) });
   } catch { return null; }
 }
 

package/src/studio/demo-decks.js

@@ -4,16 +4,18 @@ import { COLLECTION_NAMES, COLLECTION_ASSETS, collectionDeck } from './template-
 import { LAYOUT_SAMPLES } from './layout-samples.js';
 import { explorationDemo } from './exploration-demo.js';
 import { tourDeck, TOUR_TITLE } from './tour.js';
-export function demoAssets(kind) { return kind === 'lavanda' || kind === 'novidades' ? ['lavanda-cover.jpg'] : COLLECTION_ASSETS[kind] || []; }
+import { featureDemo, FEATURE_DEMO_NAMES } from './feature-demos.js';
+export function demoAssets(kind) { return kind === 'lavanda' || kind === 'novidades' ? ['lavanda-cover.jpg'] : kind === 'conheca' || kind === 'mapas' ? ['tour-mapa-botao.jpg', 'tour-mapa-editor.jpg'] : COLLECTION_ASSETS[kind] || []; }
 // arquivos do projeto que o modelo traz (fora de imagens/): a planilha e as anotações da demo de novidades
 export function demoProjectFiles(kind) { return kind === 'novidades' ? ['contexto/vendas.csv', 'contexto/leia-me.md'] : []; }
 const item=(title,text,extra={})=>({title,text,...extra});
 const route='flowchart LR\n  A([Pedido]):::hi --> B{Dados válidos?}\n  B -->|sim| C[Executar tarefa]\n  B -.->|não| D[Informar erro]:::vazado\n  C ==> E[Guardar resultado]:::em';
-export const DEMO_NAMES={conheca:TOUR_TITLE,cinematica:"Demo — mundos que se transformam",explorar:'Demo — explore uma ideia',lavanda:'Estúdio lavanda',executivo:'Relatório executivo',workshop:'Workshop visual',compacto:'Demo — material de consulta',avancado:'Demo — recursos avançados',diagramas:'Demo — diagramas vivos',novidades:'Demo — novidades',hidraulica:'Aula de hidráulica',algoritmos:'Aula de algoritmos',...COLLECTION_NAMES};
+export const DEMO_NAMES={conheca:TOUR_TITLE,...FEATURE_DEMO_NAMES,cinematica:"Demo — mundos que se transformam",explorar:'Demo — explore uma ideia',lavanda:'Estúdio lavanda',executivo:'Relatório executivo',workshop:'Workshop visual',compacto:'Demo — material de consulta',avancado:'Demo — recursos avançados',diagramas:'Demo — diagramas vivos',novidades:'Demo — novidades',hidraulica:'Aula de hidráulica',algoritmos:'Aula de algoritmos',...COLLECTION_NAMES};
 export function demoDeck(kind) {
   if(kind==='conheca')return tourDeck();
   if(kind==='cinematica')return portalDemo();
   if(kind==='explorar')return explorationDemo();
+  const feature=featureDemo(kind);if(feature)return feature;
   if(Object.hasOwn(COLLECTION_NAMES,kind))return collectionDeck(kind);
   if(!DEMO_NAMES[kind])throw Error('Modelo não encontrado.');
   // cada demo com a sua cara (tema, tom e figura da capa): na vitrine, as capas não podem parecer a mesma

package/src/studio/developer-starters.js

@@ -0,0 +1,46 @@
+// Bases curtas para começar uma apresentação técnica sem esperar pela IA.
+// São modelos de fábrica; cada uso cria uma instância pela biblioteca.
+export function developerStarter(kind, { title } = {}) {
+  const code = 'function normalizar(nome) {\n  return nome.trim().toLowerCase();\n}\n\nconst usuario = normalizar("  Ada  ");\nconsole.log(usuario);';
+  const curl = ['curl --request POST "$BASE/echo" \\', '  --header "Content-Type: application/json" \\', '  --data \'{"mensagem":"Olá, API"}\''].join("\n");
+  if (!["programacao", "apis"].includes(kind)) throw new Error("Escolha uma base de programação ou APIs com cURL.");
+  const programming = kind === "programacao";
+  const name = String(title || (programming ? "Meu código, passo a passo" : "Minha primeira API com cURL")).trim();
+  return {
+    title: name, theme: programming ? "terminal-pro" : "aurora-dev", duration: 6, purpose: "palestra", maxWords: 70,
+    ...(!programming ? { env: "ensaio" } : {}),
+    slides: [
+      { layout: "cover", kicker: "Exemplo para editar", title: name,
+        subtitle: programming ? "Entrada, transformação e resultado" : "Entenda o comando e experimente uma chamada",
+        figure: { motion: { type: "console", caption: programming ? "normalizar.js · saída de exemplo" : "curl · saída de exemplo", scenes: [{ cmd: programming ? "node normalizar.js" : 'curl --request POST "$BASE/echo"', out: programming ? ["ada"] : ['200 OK', '{ "mensagem": "Olá, API" }'] }] } },
+        notes: "Este é um exemplo de fábrica para você editar. Use Inserir › Código / cURL para colar seu conteúdo. A animação da capa mostra uma saída ilustrativa." },
+      programming ? {
+        layout: "codewalk", title: "Uma transformação em ==três passos==", filename: "normalizar.js", language: "JavaScript", code,
+        steps: [
+          { title: "Definir a regra", text: "A função recebe um nome. trim remove os espaços nas pontas; toLowerCase converte as letras para minúsculas.", highlight: [1, 2, 3] },
+          { title: "Aplicar à entrada", text: "Os espaços e as letras maiúsculas entram no mesmo exemplo.", highlight: [5] },
+          { title: "Conferir a saída", text: "O resultado pode ser copiado e usado no restante do programa.", highlight: [6], output: "ada" },
+        ], notes: "Troque o código em Formatar. Selecione as linhas e crie uma etapa para explicar o trecho. A saída deste guia é ilustrativa, sem executar o código."
+      } : {
+        layout: "codewalk", title: "O cURL em ==três partes==", filename: "pedido.sh", language: "Bash", code: curl,
+        steps: [
+          { title: "Método e destino", text: "POST envia os dados para o endpoint. BASE é o endereço do ambiente.", highlight: [1] },
+          { title: "Formato dos dados", text: "Content-Type avisa ao servidor que o corpo é JSON.", highlight: [2] },
+          { title: "O corpo enviado", text: "A mensagem é o dado que vamos conferir na resposta.", highlight: [3] },
+        ], notes: "Este comando explica a chamada, sem executá-la. O próximo slide chama a API de ensaio do Studio local."
+      },
+      programming ? {
+        layout: "diagram", title: "Veja o ==caminho== dos dados", mermaid: 'flowchart LR\n  A["Entrada: espaços e maiúsculas"] --> B["trim + toLowerCase"] --> C["Saída: ada"]',
+        notes: "Troque os nós pelo fluxo do seu programa. Use a mesma entrada e a mesma saída em toda a explicação."
+      } : {
+        layout: "api", title: "Experimente ==ao vivo==", text: "No Studio local, clique em Executar. Troque a mensagem no Corpo e execute novamente.", tab: "curl",
+        request: { method: "POST", url: "{{base}}/echo", auth: false, body: { mensagem: "Olá, API" } }, answer: "$.recebido",
+        notes: "Ambiente ENSAIO: API de mentira que o Studio local fornece. No servidor multiusuário, chamadas não são executadas. Para usar seu serviço, troque o ambiente e importe seu cURL por Inserir › Código / cURL."
+      },
+      { layout: "code", title: programming ? "Conferir a ==entrada e saída==" : "Ler a ==resposta==", filename: "resposta.json", language: "JSON",
+        code: programming ? '{\n  "entrada": "  Ada  ",\n  "saida": "ada"\n}' : '{\n  "metodo": "POST",\n  "recebido": { "mensagem": "Olá, API" },\n  "consulta": {}\n}',
+        note: programming ? "Mantenha um exemplo concreto do começo ao fim da explicação." : "O campo recebido contém os mesmos dados enviados no corpo." },
+      { layout: "end", title: "Agora, o ==seu exemplo==", subtitle: "Cole seu conteúdo em Inserir › Código / cURL ou peça ao assistente para explicar os trechos.", notes: "Você pode aplicar outro tema em Design. O exemplo é seu para editar; cada uso cria uma apresentação independente." },
+    ],
+  };
+}

package/src/studio/export-jobs.js

@@ -0,0 +1,86 @@
+// Gerações pertencem à pessoa, não à aba. O arquivo fica fora da biblioteca/nuvem por até 24 h,
+// enquanto este Studio estiver ligado. Uma geração por vez limita o uso de Chrome e memória.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { generateExport, exportHeaders } from './exporting.js';
+import { removeRetry } from '../fs-retry.js';
+
+export const EXPORT_KINDS = ['sagadeck', 'pptx', 'pdf', 'roteiro', 'tudo', 'estudo', 'estudo-html'];
+const TTL = 24 * 3600_000;
+export function createExportJobs({ generate = generateExport, now = () => Date.now(), ttl = TTL } = {}) {
+  const jobs = new Map(), queue = [];
+  let active = null, closed = false, dir;
+  const visible = j => ({ id: j.id, kind: j.kind, name: j.name, title: j.title, status: j.status,
+    progress: j.progress, createdAt: j.createdAt, finishedAt: j.finishedAt || null,
+    expiresAt: j.finishedAt ? j.finishedAt + ttl : null, error: j.error || null, warnings: j.warnings || [] });
+  const remove = j => { if (j.path) fs.rmSync(j.path, { force: true }); jobs.delete(j.id); };
+  function prune() {
+    for (const j of jobs.values()) if (j.finishedAt && now() - j.finishedAt >= ttl) remove(j);
+  }
+  const timer = setInterval(prune, 60_000); timer.unref();
+  async function run(j) {
+    j.status = 'running';
+    try {
+      const result = await generate(j.kind, j.spec, j.name, { ...j.options, onProgress: p => { j.progress = { ...j.progress, ...p }; } });
+      if (closed) return;
+      dir ||= fs.mkdtempSync(path.join(os.tmpdir(), 'sagadeck-export-jobs-'));
+      j.path = path.join(dir, j.id);
+      fs.writeFileSync(j.path, result.body, { mode: 0o600 });
+      j.headers = exportHeaders(result);
+      j.name = result.file;
+      j.warnings = [...(result.warnings || []), ...(result.missing || []).map(file => `Arquivo não encontrado: ${file}`)];
+      j.progress = { ...j.progress, phase: 'ready', completed: j.progress.total };
+      j.status = 'ready';
+    } catch (e) {
+      j.status = 'failed'; j.error = e.message || String(e);
+    } finally {
+      j.finishedAt = now(); delete j.spec; delete j.options;
+      // Mantém as dez exportações recentes da pessoa; não guarda arquivos sem limite.
+      const done = [...jobs.values()].filter(x => x.owner === j.owner && x.finishedAt).sort((a, b) => b.finishedAt - a.finishedAt);
+      for (const old of done.slice(10)) remove(old);
+    }
+  }
+  function drain() {
+    if (closed || active || !queue.length) return;
+    const j = queue.shift();
+    active = run(j).finally(() => { active = null; setImmediate(drain); });
+  }
+  return {
+    create(owner, kind, spec, name, options = {}) {
+      if (closed) throw new Error('O Studio está encerrando. Tente novamente depois de reiniciar.');
+      if (!EXPORT_KINDS.includes(kind)) throw new Error('Formato de exportação inválido.');
+      prune();
+      const key = crypto.createHash('sha256').update(JSON.stringify([kind, spec, name, options])).digest('hex');
+      const pending = [...jobs.values()].filter(j => !j.finishedAt);
+      const same = pending.find(j => j.owner === owner && j.key === key);
+      if (same) return visible(same);
+      if (pending.filter(j => j.owner === owner).length >= 4 || pending.length >= 32) throw new Error('Há muitas exportações em andamento. Espere uma delas terminar.');
+      const j = { id: crypto.randomUUID(), owner, key, kind, spec: structuredClone(spec), name, title: spec.title || name,
+        options: { ...options }, status: 'queued', createdAt: now(), progress: { phase: 'queued', completed: 0, total: spec.slides?.length || 0 } };
+      jobs.set(j.id, j); queue.push(j); setImmediate(drain);
+      return visible(j);
+    },
+    list(owner) { prune(); return [...jobs.values()].filter(j => j.owner === owner).sort((a, b) => b.createdAt - a.createdAt).map(visible); },
+    download(owner, id, res) {
+      prune();
+      const j = jobs.get(id);
+      const code = !j || j.owner !== owner ? 404 : j.status !== 'ready' ? 409 : 200;
+      if (code !== 200) {
+        res.writeHead(code, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+        res.end(JSON.stringify({ error: code === 404 ? 'Exportação não encontrada ou expirada. Gere novamente.' : j.error || 'A exportação ainda não terminou.' }));
+        return;
+      }
+      res.writeHead(200, { ...j.headers, 'Content-Length': fs.statSync(j.path).size });
+      const stream = fs.createReadStream(j.path);
+      stream.on('error', () => res.destroy());
+      res.on('close', () => stream.destroy()); stream.pipe(res);
+    },
+    async close() {
+      closed = true; clearInterval(timer); queue.length = 0;
+      await active;
+      jobs.clear(); if (dir) removeRetry(dir);
+    },
+  };
+}

package/src/studio/exporting.js

@@ -1,4 +1,5 @@
 import { expandApiCollections } from '../api-collections.js';
+import { removeRetry } from '../fs-retry.js';
 import {meetingSpec} from '../meeting.js';
 // Exportar a apresentação aberta ou da biblioteca: .sagadeck, PowerPoint, PDF, roteiro, material de estudo e "Baixar
 // tudo". PPTX/PDF/roteiro/estudo usam o Chrome invisível (os mesmos exportadores do CLI), numa pasta temporária.
@@ -21,14 +22,12 @@ export function sendHtml(res,spec,audience){
 
 // Gera e envia um arquivo da apresentação. PPTX/PDF/roteiro usam o Chrome invisível (os mesmos
 // exportadores de "sagadeck pptx | pdf | roteiro"), numa pasta temporária.
-export async function sendExport(res, kind, spec, name, { notes = true, inline = false, audience, macFonts = false } = {}) {
+export async function generateExport(kind, spec, name, { notes = true, audience, macFonts = false, onProgress = () => {} } = {}) {
   spec=meetingSpec(spec,audience);
-  const cd = (file) => `attachment; filename="${slugify(file.replace(/\.\w+$/, ""))}${path.extname(file)}"; filename*=UTF-8''${encodeURIComponent(file)}`;
+  onProgress({ phase: 'preparing', completed: 0, total: spec.slides?.length || 0 });
   if (kind === "sagadeck") {
     const { zip, missing } = await packDeck(spec, { baseDir: spec._dir || process.cwd(), name, generator: "sagadeck studio" });
-    res.writeHead(200, { "Content-Type": MIME, "Content-Disposition": cd(name + EXTENSION), "X-Sagadeck-Missing": encodeURIComponent(JSON.stringify(missing)) });
-    res.end(zip);
-    return;
+    return { body: zip, file: name + EXTENSION, mime: MIME, missing, warnings: [] };
   }
   const kinds = {
     pptx: { file: `${name}.pptx`, mime: "application/vnd.openxmlformats-officedocument.presentationml.presentation" },
@@ -41,6 +40,7 @@ export async function sendExport(res, kind, spec, name, { notes = true, inline =
     tudo: { file: `${name}.zip`, mime: "application/zip" },
   };
   const k = kinds[kind];
+  if (!k) throw new Error('Formato de exportação inválido.');
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), `sagadeck-${kind}-`));
   try {
     if (["pptx","pdf","tudo"].includes(kind)) spec=expandApiCollections(spec);
@@ -49,27 +49,31 @@ export async function sendExport(res, kind, spec, name, { notes = true, inline =
     fs.writeFileSync(htmlFile, r.html);
     const errors = [];
     const make = async (what) => {
+      const progress = event => onProgress({ ...event, format: what });
+      progress({ phase: 'opening', completed: 0, total: r.slidesMeta.length });
       const out = path.join(tmp, `saida-${what}`);
       if (what === "pptx") {
         const { exportPptx } = await import("../export/pptx.js");
-        errors.push(...(await exportPptx(htmlFile, out, { theme: r.theme, meta: { ...r.meta, slides: r.slidesMeta }, notes, fontFallback: macFonts ? "mac" : undefined })).errors);
+        errors.push(...(await exportPptx(htmlFile, out, { theme: r.theme, meta: { ...r.meta, slides: r.slidesMeta }, notes, fontFallback: macFonts ? "mac" : undefined, onProgress: progress })).errors);
       } else if (what === "pdf") {
         const { pdf } = await import("../export/shots.js");
         // Preferências › Exportação: tema escuro com par claro (manual-noite → manual) sai claro no PDF, bom para imprimir
         const light = loadPreferences().exportacao.pdfClaro === true ? lightVariant(spec) : null;
         let file = htmlFile;
         if (light) { file = path.join(tmp, "deck-claro.html"); fs.writeFileSync(file, buildHTML(light).html); }
-        await pdf(file, out);
+        await pdf(file, out, { onProgress: progress });
       } else if (what === "estudo" || what === "estudo-html") {
         const { shots } = await import("../export/shots.js");
         const { estudoHTML, estudoPDF } = await import("../export/estudo.js");
-        const { files } = await shots(htmlFile, path.join(tmp, "fotos"), { scale: what === "estudo" ? 0.6 : 0.75, jpeg: true });
+        const { files } = await shots(htmlFile, path.join(tmp, "fotos"), { scale: what === "estudo" ? 0.6 : 0.75, jpeg: true, onProgress: progress });
+        progress({ phase: 'packing', completed: files.length, total: files.length });
         const html = estudoHTML({ title: r.meta.title, author: r.meta.author, date: spec.date, slidesMeta: r.slidesMeta, shotFiles: files });
         if (what === "estudo-html") fs.writeFileSync(out, html); else await estudoPDF(html, out);
       } else {
         const { shots } = await import("../export/shots.js");
         const { roteiroPDF } = await import("../export/roteiro.js");
-        const { files } = await shots(htmlFile, path.join(tmp, "miniaturas"), { scale: 0.5, jpeg: true });
+        const { files } = await shots(htmlFile, path.join(tmp, "miniaturas"), { scale: 0.5, jpeg: true, onProgress: progress });
+        progress({ phase: 'packing', completed: files.length, total: files.length });
         await roteiroPDF({ slidesMeta: r.slidesMeta, shotFiles: files, outFile: out, title: r.meta.title, author: r.meta.author, duration: spec.duration });
       }
       return fs.readFileSync(out);
@@ -78,20 +82,34 @@ export async function sendExport(res, kind, spec, name, { notes = true, inline =
     if (kind === "tudo") {
       const zip = new JSZip();
       for (const what of ["pptx", "pdf", "roteiro"]) zip.file(kinds[what].file, await make(what));
+      onProgress({ phase: 'packing', format: 'tudo', completed: r.slidesMeta.length, total: r.slidesMeta.length });
       body = await zip.generateAsync({ type: "nodebuffer", compression: "DEFLATE" });
     } else body = await make(kind);
-    res.writeHead(200, {
-      "Content-Type": k.mime, "Content-Disposition": inline ? "inline" : cd(k.file),
-      // só o que afeta o arquivo (falha ao exportar, arquivo não encontrado); o fiscal de conteúdo fica no Revisar
-      "X-Sagadeck-Warnings": encodeURIComponent(JSON.stringify([...(r.warnings || []).filter((w) => /não encontrado/.test(w)), ...errors].slice(0, 20))),
-    });
-    res.end(body);
+    // só o que afeta o arquivo; o fiscal de conteúdo fica no Revisar
+    return { body, file: k.file, mime: k.mime, warnings: [...(r.warnings || []).filter(w => /não encontrado/.test(w)), ...errors].slice(0, 20) };
+  } finally {
+    removeRetry(tmp);
+  }
+}
+
+export function exportHeaders(result, inline = false) {
+  const cd = file => `attachment; filename="${slugify(file.replace(/\.\w+$/, ''))}${path.extname(file)}"; filename*=UTF-8''${encodeURIComponent(file)}`;
+  return { 'Content-Type': result.mime, 'Content-Disposition': inline ? 'inline' : cd(result.file),
+    'Cache-Control': 'private, no-store',
+    'X-Sagadeck-Warnings': encodeURIComponent(JSON.stringify(result.warnings || [])),
+    ...(result.missing ? { 'X-Sagadeck-Missing': encodeURIComponent(JSON.stringify(result.missing)) } : {}) };
+}
+
+// Links de compartilhamento e CLI seguem recebendo o arquivo na própria resposta.
+export async function sendExport(res, kind, spec, name, options = {}) {
+  try {
+    const result = await generateExport(kind, spec, name, options);
+    res.writeHead(200, exportHeaders(result, options.inline));
+    res.end(result.body);
   } catch (e) {
     console.error(`[Studio] exportação ${kind} falhou:`, e.message);
-    res.writeHead(500, { "Content-Type": "application/json" });
+    res.writeHead(500, { 'Content-Type': 'application/json' });
     res.end(JSON.stringify({ error: e.message }));
-  } finally {
-    fs.rmSync(tmp, { recursive: true, force: true });
   }
 }
 

package/src/studio/feature-demos.js

@@ -0,0 +1,144 @@
+// Demos de um assunto só (mapas, programação, APIs com curl): curtas, para mostrar um recurso a quem vai usá-lo, sem
+// passar pelo Conheça o SagaDeck inteiro. Reaproveitam os exemplos de layout (layout-samples.js) e as demos de mapa do
+// tour; cada slide diz o que é e a frase para pedir à IA (no rodapé e nas notas). Abrem em prévia, como os modelos.
+import { LAYOUT_INFO, LAYOUT_SAMPLES, LAYOUT_ASK } from "./layout-samples.js";
+import { mapDemos } from "./tour.js";
+
+export const FEATURE_DEMO_NAMES = { mapas: "Demo — mapas", programacao: "Demo — programação", apis: "Demo — APIs com curl" };
+
+const asked = (ask) => `Peça à IA: “${ask}”`;
+const told = (label, desc, ask) => ({ source: `**${label}**: ${desc}. ${asked(ask)}`, notes: [`${label}: ${desc}.`, asked(ask)].join("\n\n") });
+// o exemplo do layout, com o nome do recurso e a frase para a IA; extra troca o conteúdo quando o exemplo é genérico
+const sample = (name, extra = {}) => {
+  const [label, desc] = LAYOUT_INFO[name] || [name, ""];
+  return { ...structuredClone(LAYOUT_SAMPLES[name]), layout: name, ...told(label, desc, LAYOUT_ASK[name] || ""), ...extra };
+};
+const cover = (title, subtitle, figure) => ({ layout: "cover", kicker: "SAGADECK · DEMO", title, subtitle, figure });
+
+// ---- Mapas: mostrar, calcular, editar
+export function mapasDemo() {
+  const [bolhas, regioes, linhas, rota, raio, faixa, comIA, ondeEdita, telaMapa, noStudio] = mapDemos();
+  return {
+    title: FEATURE_DEMO_NAMES.mapas, theme: "oceano", duration: 15, maxWords: 140, slides: [
+      cover("Mapas ==ao vivo==", "Pontos, linhas e áreas sobre o mapa de verdade, com as contas feitas pelo código", { icon: "map", size: 320 }),
+      { layout: "statement", kicker: "a ideia", text: "A ==planilha== é a fonte; o mapa é a vista.",
+        notes: "Os pontos vêm de uma planilha do projeto (contexto/*.csv), as linhas e áreas de GeoJSON, GPX ou KML. A mesma planilha serve tabela e gráfico. Nada de mapa chapado em imagem: ele é ao vivo." },
+      { layout: "section", number: "01", kicker: "mostrar", title: "Dados no ==mapa==", subtitle: "pontos por categoria, bolhas, regiões por valor, linhas e áreas" },
+      sample("map"), bolhas, regioes, linhas,
+      { layout: "section", number: "02", kicker: "calcular", title: "As ==contas==", subtitle: "rota pelas ruas, alcance, raio e faixa: calculados, nunca desenhados à mão" },
+      rota, raio, faixa,
+      { layout: "section", number: "03", kicker: "editar", title: "Com a IA e no ==Studio==", subtitle: "a IA busca os dados; o Editar mapa mexe em cada ponto" },
+      comIA, ondeEdita, telaMapa, noStudio,
+      { layout: "end", title: "Agora, o seu ==mapa==.", subtitle: "Peça à IA: “Ponha no mapa os endereços da minha planilha”." },
+    ],
+  };
+}
+
+// ---- Programação: mostrar código, rodar ao vivo, Git a dois, explicar a arquitetura
+const PEDIDOS = [
+  "def total_do_pedido(itens, cupom=None):",
+  "    subtotal = sum(i.preco * i.qtd for i in itens)",
+  "    if cupom and cupom.valido():",
+  "        subtotal -= cupom.desconto(subtotal)",
+  "    frete = 0 if subtotal >= 200 else 19.90",
+  "    return round(subtotal + frete, 2)",
+].join("\n");
+export function programacaoDemo() {
+  return {
+    title: FEATURE_DEMO_NAMES.programacao, theme: "musgo", duration: 15, maxWords: 140, slides: [
+      cover("Código no ==palco==", "Do trecho destacado ao algoritmo rodando, com a plateia acompanhando linha a linha", { motion: { type: "console", caption: "projeto · terminal", scenes: [
+        { cmd: "pytest -q", out: ["42 passed in 1.84s"] },
+        { cmd: "git log --oneline -3", out: ["a1f9c2e calcula o frete", "77b03d4 aplica o cupom", "3c0e1aa primeira versão"] },
+        { cmd: "python -m pedidos --demo", out: ["total: R$ 187,40", "frete: R$ 19,90"] },
+      ] } }),
+      { layout: "section", number: "01", kicker: "mostrar", title: "Código ==legível== de longe", subtitle: "destaque, linha a linha e material de consulta" },
+      sample("code", { title: "Destaque o que ==importa==", filename: "pedidos.py", language: "python", code: PEDIDOS, highlight: [3, 4],
+        note: "O cupom só vale se for válido: é aqui que o desconto entra." }),
+      sample("codewalk"),
+      sample("dossier"),
+      { layout: "section", number: "02", kicker: "rodar", title: "Executar na ==frente== de todos", subtitle: "a plateia muda o código e vê o resultado" },
+      sample("codelab"),
+      sample("algo"),
+      { layout: "section", number: "03", kicker: "colaborar", title: "Git e ==revisão==", subtitle: "duas pessoas, um clique por jogada" },
+      sample("terminals"),
+      sample("duel"),
+      sample("turns"),
+      { layout: "section", number: "04", kicker: "explicar", title: "A ==arquitetura==", subtitle: "fluxos, sequências e redes que dá para explorar" },
+      sample("diagram", { title: "Do pedido ao ==pagamento==", mermaid: "sequenceDiagram\n  participant App\n  participant API\n  participant Pagamentos\n  App->>API: POST /pedidos\n  API->>Pagamentos: cobra o total\n  Pagamentos-->>API: aprovado\n  API-->>App: 201 Created" }),
+      sample("graphlab"),
+      { layout: "end", title: "Agora, o seu ==código==.", subtitle: "Peça à IA: “Explique este arquivo linha a linha, com a saída de cada passo”." },
+    ],
+  };
+}
+
+// ---- APIs com curl: anatomia de um curl, executar de verdade (no ambiente ENSAIO, a API de mentira que o Studio
+// sobe sozinho), polling, streaming, as opções que mais ajudam e o cuidado com o token
+const CURL = [
+  'curl -X POST "https://api.exemplo.com/v1/pedidos" \\',
+  '  -H "Authorization: Bearer $API_TOKEN" \\',
+  '  -H "Content-Type: application/json" \\',
+  `  -d '{"item": "livro", "quantidade": 2}' \\`,
+  "  -i",
+].join("\n");
+const ensaio = "Roda no ambiente ENSAIO, a API de mentira que o Studio sobe sozinho: nada sai da sua máquina. Com o seu serviço, troque o endereço em Inserir › Ambientes.";
+const apiSlide = (s) => {
+  const t = told("API ao vivo", "Requisição que executa na hora, com o curl equivalente na aba curl", LAYOUT_ASK.api || "Mostre esta chamada ao vivo com o curl");
+  return { layout: "api", tab: "curl", ...s, source: t.source, notes: [s.notes, ensaio, t.notes].filter(Boolean).join("\n\n") };
+};
+export function apisDemo() {
+  return {
+    title: FEATURE_DEMO_NAMES.apis, theme: "wine", duration: 15, maxWords: 140, slides: [
+      cover("APIs com ==curl==", "Uma chamada por slide, executada na frente de todos, com o curl pronto para copiar", { motion: { type: "console", caption: "curl · ao vivo", scenes: [
+        { cmd: `curl -X POST /v1/echo -d '{"mensagem":"Olá, API"}'`, out: ["200 OK", `{ "metodo": "POST", "recebido": { "mensagem": "Olá, API" } }`] },
+        { cmd: "curl /v1/echo?cidade=Recife", out: ["200 OK", `{ "consulta": { "cidade": "Recife" } }`] },
+        { cmd: "curl -N /v1/stream", out: ["200 OK · text/event-stream", "data: a resposta chega aos poucos..."] },
+      ] } }),
+      { layout: "statement", kicker: "a ideia", text: "O curl é a chamada de API ==mais curta== que existe.",
+        notes: "Todo slide de API do SagaDeck mostra o pedido, executa de verdade e traz o curl equivalente na aba curl (e também JavaScript e Python)." },
+      { layout: "codewalk", kicker: "anatomia", title: "Um curl em ==quatro partes==", filename: "pedido.sh", language: "bash", code: CURL,
+        steps: [
+          { title: "Verbo e endereço", text: "-X diz o que fazer (POST cria); a URL diz onde.", highlight: [1] },
+          { title: "Quem está pedindo", text: "O token vai no cabeçalho Authorization. Ele vem de uma variável: nunca escrito no comando.", highlight: [2] },
+          { title: "O que vai junto", text: "Content-Type avisa que o corpo é JSON; -d leva o corpo.", highlight: [3, 4] },
+          { title: "Ver a resposta inteira", text: "-i mostra o status e os cabeçalhos antes do corpo.", highlight: [5], output: "HTTP/1.1 201 Created\ncontent-type: application/json\n\n{ \"id\": \"ped-42\", \"status\": \"criado\" }" },
+        ], ...told("Código guiado", "Explique uma linha por vez, com destaques e saída simulada", "Explique este curl parte por parte") },
+      { layout: "section", number: "01", kicker: "executar", title: "Ao ==vivo==, de verdade", subtitle: "o Executar faz a chamada; a aba curl mostra o comando" },
+      apiSlide({ id: "post", kicker: "POST", title: "Mandar um ==corpo==", request: { method: "POST", url: "{{base}}/echo", body: { mensagem: "Olá, API", turma: "noite" } }, answer: "$.recebido",
+        notes: "Edite a mensagem na aba Corpo e execute de novo: a aba curl acompanha." }),
+      apiSlide({ id: "get", kicker: "GET", title: "Perguntar pela ==URL==", request: { method: "GET", url: "{{base}}/echo?cidade=Recife&dias=3" }, answer: "$.consulta",
+        notes: "GET não tem corpo: os parâmetros vão na URL, depois do ?." }),
+      apiSlide({ id: "token", kicker: "Token", title: "Com ==autorização==", request: { method: "POST", url: "{{base}}/sync", body: { q: "Qual é o status do pedido 42?" } }, answer: "$.choices[0].message.content",
+        notes: "O token sai do ambiente (o Studio pede e renova sozinho). No curl ele aparece como $API_TOKEN: o valor nunca vai para o slide." }),
+      { layout: "section", number: "02", kicker: "esperar", title: "Quando a resposta ==demora==", subtitle: "acompanhar até terminar, ou receber aos poucos" },
+      apiSlide({ id: "polling", kicker: "Polling", title: "Inicia e ==acompanha==", mode: "polling",
+        request: { url: "{{base}}/start", body: { workflow: "{{wf}}", input: { texto: "Resuma o contrato" } } },
+        polling: { id: "$.executionId", check: { url: "{{base}}/status/{{id}}" }, status: "$.status", done: ["FINISHED"], failed: ["ERROR"], interval: 0.8 },
+        steps: "$.responses", stepText: "$.output", notes: "O início devolve só o código da execução; a consulta repete até FINISHED. Na aba curl: o laço com sleep." }),
+      apiSlide({ id: "stream", kicker: "Streaming", title: "A resposta chega ==aos poucos==", mode: "stream", request: { method: "POST", url: "{{base}}/stream", body: { stream: true } },
+        notes: "No curl, -N desliga o buffer e o texto aparece enquanto chega." }),
+      { layout: "section", number: "03", kicker: "dia a dia", title: "As opções que ==salvam== o dia", subtitle: "clique em cada cartão para ver para que serve" },
+      // (oito cartões ocupam a área toda: aqui a frase para a IA fica só nas notas, sem a linha de rodapé)
+      { layout: "cards", title: "Clique para ==virar==", cols: 4, notes: told("Cartão que vira", "A frente mostra a opção; o verso explica, no clique", "Faça cartões que viram com a explicação no verso").notes, items: [
+        { icon: "file-text", title: "-i", text: "status e cabeçalhos", flip: "Mostra a linha de status e os cabeçalhos antes do corpo. O primeiro passo de toda investigação." },
+        { icon: "bug", title: "-v", text: "conversa inteira", flip: "Mostra tudo: o pedido que saiu, o certificado, o que voltou. Para quando nada faz sentido." },
+        { icon: "shield-alert", title: "--fail", text: "erro vira erro", flip: "Status 4xx ou 5xx faz o curl sair com erro. Essencial em script, que senão segue feliz." },
+        { icon: "corner-down-right", title: "-L", text: "segue o redirecionamento", flip: "Vai atrás do 301 e do 302 até o endereço final." },
+        { icon: "volume-x", title: "-s", text: "sem barra de progresso", flip: "Silencia o progresso; combine com -S para ainda ver os erros." },
+        { icon: "download", title: "-o arquivo", text: "grava a resposta", flip: "Salva o corpo num arquivo em vez de jogar na tela." },
+        { icon: "timer", title: "-w", text: "tempo e status", flip: "-w '%{http_code} %{time_total}s' imprime o status e quanto demorou." },
+        { icon: "braces", title: "| jq", text: "JSON legível", flip: "Mande a saída para o jq: indenta, colore e filtra campos, como jq '.itens[0]'." },
+      ] },
+      { layout: "statement", kicker: "cuidado", text: "O token ==nunca== vai para o slide.",
+        add: { aviso: { tipo: "perigo", titulo: "Segredo exposto", texto: "No deck, use {{secret.nome}}; no curl, $API_TOKEN. Os valores ficam nos Ambientes da sua máquina." } },
+        notes: "Os segredos ficam em ~/.sagadeck/ambientes.yaml (no Windows, cifrados para o seu usuário). O deck pode ir para outras pessoas sem vazar nada." },
+      { layout: "end", title: "Agora, a sua ==API==.", subtitle: "Peça à IA: “Monte um slide que chama o meu serviço e mostra o curl”." },
+    ],
+  };
+}
+
+export function featureDemo(kind) {
+  if (kind === "mapas") return mapasDemo();
+  if (kind === "programacao") return programacaoDemo();
+  if (kind === "apis") return apisDemo();
+  return null;
+}

package/src/studio/ia-routes.js

@@ -29,6 +29,15 @@ export async function iaRoutes({ req, res, pathname, opts, readJSON }) {
     json(res, 200, { config: maskedIA(loadIA()), file: iaFile(), source: cfg.source, configured: !!(cfg.url || cfg.adaptador), problem: cfg.problem || "", providers: PROVIDERS, roles: ROLES, recommended: RECOMMENDED, editable: !opts.multiuser });
     return true;
   }
+  // diagnóstico de todos os recursos (src/ai/ia-check.js), o mesmo do `sagadeck ia-check`: no multiusuário, só quem
+  // administra (diz quais modelos estão configurados)
+  if (pathname === "/api/ia/check" && req.method === "POST") {
+    if (opts.multiuser) { json(res, 403, { error: "No servidor multiusuário, o diagnóstico da IA é de quem administra: rode sagadeck ia-check no servidor." }); return true; }
+    const body = await readJSON(req);
+    const { iaCheck } = await import("../ai/ia-check.js");
+    json(res, 200, await iaCheck({ only: Array.isArray(body.so) ? body.so : null, rapido: !!body.rapido, videoReal: !!body.video_real }));
+    return true;
+  }
   if ((pathname === "/api/ia" || pathname === "/api/ia/test") && req.method === "POST") {
     if (opts.multiuser) { json(res, 403, { error: "No servidor multiusuário, a IA é configurada por quem administra." }); return true; }
     const body = await readJSON(req);