sagadeck 1.7.1 → 1.9.0

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

@@ -9,6 +9,7 @@ import { writeRecording } from "../api-client.js";
 import { editDeck, coverDocumentVisuals, checkNumbers } from "../ai/deck-ai.js";
 import { reviewExperience } from "../ai/quality.js";
 import { maybeResearch } from "../research/chat-research.js";
+import { mapDataPrompt, runMapData, mapDataInstruction } from "../ai/map-data.js";
 import { chatErrorResult } from "./errors.js";
 import { cancellable, respond } from "./ai-response.js";
 import { prepareDocumentMaterials, takeMaterials, storedDocumentMaterials } from "../ai/document-materials.js";
@@ -164,6 +165,8 @@ _${c.naoConfirmados.length} observação(ões) descartada(s): o trecho citado n
           runCommand: commandRunner(req, emit, body, taskWorkspace, signal),
           reviewCheck: (deck, indices) => reviewExperience(deck, indices, { snapshot: slideSnapshots, onProgress: emit, signal, briefing:prompt }),
           styles: taskWorkspace.file && !isBundledTemplate(taskWorkspace.file) ? { list: taskWorkspace.library.listStyles(), current: taskWorkspace.spec?.style?.name || null } : null,
+          // dados para o mapa (bloco mapa:): só com a pasta da apresentação, que é onde os arquivos ficam
+          mapData: P ? mapDataPrompt() : null,
           ...extra,
         });
         result = await editDeck(editOpts());
@@ -192,6 +195,23 @@ _${c.naoConfirmados.length} observação(ões) descartada(s): o trecho citado n
           result.actions = [...before.actions, ...(result.actions || [])];
         }
         if (result.look?.length) result = { ...result, look: undefined, talk: true, reply: `${result.reply}\n(Já mostrei as imagens duas vezes; me diga o que procurar nelas.)` };
+        // A IA pediu dados para o mapa (mapa: [ações]): o Studio busca (OpenStreetMap, web, coordenadas), grava no
+        // projeto com a fonte de cada linha e chama de novo com o que gravou; até 2 rodadas. Endereços da pessoa só saem
+        // com o sim dela: sem ele, a resposta pergunta e nada é enviado (src/ai/map-data.js).
+        for (let round = 1; result.geo?.length && P && round <= 2; round++) {
+          const before = result;
+          emit({ phase: "step", text: "Buscando os dados para o mapa…" });
+          const r = await runMapData(before.geo, { P, onProgress: (t) => emit({ phase: "step", text: t }) });
+          signal.throwIfAborted();
+          if (r.perguntas.length && !r.feitos.length && !r.falhas.length) { result = { ...before, geo: undefined, talk: true, reply: r.perguntas.join("\n\n"), options: ["Pode enviar", "Não, deixa"] }; break; }
+          result = await editDeck(editOpts({
+            history: [...history, { role: "user", text: prompt }, { role: "assistant", text: before.reply }],
+            instruction: `${mapDataInstruction(r)}${r.perguntas.length ? `\nAinda falta o sim da pessoa para: ${r.perguntas.join(" ")} Pergunte na resposta.` : ""}\nContinue o pedido original: ${prompt}`,
+          }));
+          signal.throwIfAborted();
+          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." };
         // 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.

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

@@ -3,15 +3,19 @@ import { portalDemo } from '../portal-scene.js';
 import { COLLECTION_NAMES, COLLECTION_ASSETS, collectionDeck } from './template-collections.js';
 import { LAYOUT_SAMPLES } from './layout-samples.js';
 import { explorationDemo } from './exploration-demo.js';
-export function demoAssets(kind) { return kind === 'lavanda' || kind === 'novidades' ? ['lavanda-cover.jpg'] : COLLECTION_ASSETS[kind] || []; }
+import { tourDeck, TOUR_TITLE } from './tour.js';
+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={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/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/geo-routes.js

@@ -0,0 +1,138 @@
+// Rotas do mapa no Studio: a tela Configurar mapa (serviços desta máquina; a chave nunca volta inteira), o estado de
+// cada serviço (vai para a tela e para a IA), "Tentar de novo" e "Achar coordenadas pelo endereço" numa planilha do
+// projeto. Mandar endereços da pessoa para um serviço de fora pede consentimento explícito (`confirmo`), que fica
+// registrado por planilha; o resultado de cada endereço fica em cache no projeto (o Nominatim exige).
+import fs from "node:fs";
+import path from "node:path";
+import * as Project from "./project.js";
+import { renameRetry } from "../fs-retry.js";
+import { loadMapConfig, mapaFile, saveMapConfig, maskedMapConfig } from "../map-config.js";
+import { serviceState, resetService, geocodeOne, geocodeInterval, ServiceBlocked, SERVICES } from "../map-services.js";
+import { route, reverseGeocode, isochrone } from "../map-routing.js";
+
+const json = (res, status, data) => { res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" }); res.end(JSON.stringify(data)); };
+const norm = (s) => String(s ?? "").normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "");
+const ADDRESS = ["endereco", "address", "logradouro", "rua", "enderecocompleto"], CITY = ["cidade", "municipio", "city", "localidade"], UF = ["uf", "estado", "state"], CEP = ["cep", "postalcode", "codigopostal"];
+const LAT = ["lat", "latitude"], LON = ["lon", "lng", "long", "longitude"];
+const find = (head, names) => head.findIndex((h) => names.includes(norm(h)));
+
+const metaFile = (P, name) => path.join(path.dirname(Project.ensureMeta(P)), name); // ensureMeta devolve o arquivo da conversa, dentro de .sagadeck/
+const readJSONFile = (f) => { try { return JSON.parse(fs.readFileSync(f, "utf8")) || {}; } catch { return {}; } };
+const writeJSONFile = (f, v) => { const tmp = `${f}.tmp-${process.pid}`; fs.writeFileSync(tmp, JSON.stringify(v, null, 1)); renameRetry(tmp, f); };
+
+// o que procurar para uma linha: o endereço com cidade, UF e CEP quando a planilha tem essas colunas
+export function addressPlan(rows, column) {
+  const head = (rows[0] || []).map((h) => String(h).trim());
+  const iAddr = column ? head.findIndex((h) => norm(h) === norm(column)) : find(head, ADDRESS);
+  if (iAddr < 0) return { error: `A planilha não tem coluna de endereço (procurei ${ADDRESS.join(", ")}); diga qual é.` };
+  const extra = [find(head, CITY), find(head, UF), find(head, CEP)].filter((i) => i >= 0 && i !== iAddr);
+  const iLat = find(head, LAT), iLon = find(head, LON);
+  const items = [];
+  rows.slice(1).forEach((r, n) => {
+    if (!r.some((c) => String(c).trim())) return;
+    const has = iLat >= 0 && iLon >= 0 && String(r[iLat] ?? "").trim() && String(r[iLon] ?? "").trim();
+    const q = [r[iAddr], ...extra.map((i) => r[i])].map((x) => String(x ?? "").trim()).filter(Boolean).join(", ");
+    if (!has && q) items.push({ row: n + 1, q });
+  });
+  return { head, iAddr, iLat, iLon, items, column: head[iAddr] };
+}
+
+export async function geoRoutes({ req, res, pathname, opts, readJSON, W, isBundledTemplate }) {
+  if (pathname === "/api/mapa" && req.method === "GET") {
+    if (opts.multiuser) { json(res, 200, { editable: false, services: serviceState(), labels: SERVICES }); return true; }
+    json(res, 200, { editable: true, file: mapaFile(), config: maskedMapConfig(loadMapConfig()), services: serviceState(), labels: SERVICES });
+    return true;
+  }
+  if (pathname === "/api/mapa" && req.method === "POST") {
+    if (opts.multiuser) { json(res, 403, { error: "No servidor, os serviços do mapa são configurados por quem administra." }); return true; }
+    const saved = saveMapConfig(await readJSON(req));
+    resetService(); // configuração nova: os serviços podem tentar de novo
+    json(res, 200, { ok: true, config: maskedMapConfig(saved), services: serviceState() });
+    return true;
+  }
+  if (pathname === "/api/mapa/tentar" && req.method === "POST") {
+    const b = await readJSON(req);
+    resetService(b.service || null);
+    json(res, 200, { ok: true, services: serviceState() });
+    return true;
+  }
+  // rota pelas ruas (editor: "Seguir as ruas"), endereço de um ponto (ponto novo) e área alcançável
+  if (["/api/mapa/rota", "/api/mapa/endereco", "/api/mapa/alcance"].includes(pathname) && req.method === "POST") {
+    const b = await readJSON(req);
+    try {
+      if (pathname === "/api/mapa/rota") json(res, 200, await route(b.pontos, { modo: b.modo }));
+      else if (pathname === "/api/mapa/endereco") json(res, 200, { endereco: await reverseGeocode(b.lat, b.lon) });
+      else json(res, 200, { geometry: await isochrone([b.lat, b.lon], b.minutos, { modo: b.modo }) });
+    } catch (e) { json(res, e instanceof ServiceBlocked ? 503 : 400, { error: e.message, bloqueado: e instanceof ServiceBlocked }); }
+    return true;
+  }
+  // Testar (Configurar mapa): uma rota curta com o que está salvo, para ver se a chave e o serviço respondem
+  if (pathname === "/api/mapa/testar" && req.method === "POST") {
+    if (opts.multiuser) { json(res, 403, { error: "No servidor, quem testa é quem administra." }); return true; }
+    resetService("rotas");
+    const t0 = Date.now();
+    try {
+      const r = await route([[-23.5489, -46.6388], [-23.5505, -46.6333]], { modo: "pe" });
+      json(res, 200, { ok: true, distancia: Math.round(r.distancia), minutos: Math.round(r.duracao / 60), ms: Date.now() - t0 });
+    } catch (e) { json(res, 200, { ok: false, error: e.message, ms: Date.now() - t0 }); }
+    return true;
+  }
+  if (pathname === "/api/mapa/geocode" && req.method === "POST") {
+    const b = await readJSON(req);
+    const P = W.file && !isBundledTemplate(W.file) ? Project.projectOf(W.file) : null;
+    if (!P) { json(res, 400, { error: "Abra uma apresentação da biblioteca para usar as planilhas do projeto." }); return true; }
+    let abs, sheet;
+    try { abs = Project.resolveIn(P, b.path); sheet = (await Project.readSheet(abs)).sheets[0]; } catch (e) { json(res, 400, { error: e.message }); return true; }
+    const plan = addressPlan(sheet.rows, b.column);
+    if (plan.error) { json(res, 400, { error: plan.error }); return true; }
+    const cfg = loadMapConfig();
+    const cacheFile = metaFile(P, "geocodificacao.json"), consentFile = metaFile(P, "mapa-consentimento.json");
+    const cache = readJSONFile(cacheFile), consent = readJSONFile(consentFile);
+    const todo = plan.items.filter((it) => !(it.q in cache));
+    const host = (() => { try { return new URL(cfg.geocoder.url).host; } catch { return cfg.geocoder.url; } })();
+    const summary = { total: plan.items.length, enviar: todo.length, cache: plan.items.length - todo.length, servico: host, segundos: Math.ceil((todo.length * geocodeInterval(cfg)) / 1000), coluna: plan.column };
+    // dados da pessoa saem para fora só com consentimento explícito (uma vez por planilha e serviço)
+    const key = `${b.path}@${host}`;
+    // a tela pergunta o plano antes (200); quem tentar enviar sem confirmar recebe 409 e nada sai
+    if (b.planejar) { json(res, 200, { precisaConfirmar: !!(todo.length && !consent[key]), ...summary }); return true; }
+    if (todo.length && !b.confirmo && !consent[key]) { json(res, 409, { precisaConfirmar: true, ...summary }); return true; }
+    if (todo.length && b.confirmo && !consent[key]) { consent[key] = new Date().toISOString(); writeJSONFile(consentFile, consent); }
+    // daqui em diante, o progresso vai linha a linha (ndjson)
+    res.writeHead(200, { "Content-Type": "application/x-ndjson; charset=utf-8", "Cache-Control": "no-store" });
+    const send = (o) => res.write(JSON.stringify(o) + "\n");
+    let aborted = false;
+    req.on("close", () => { aborted = true; });
+    send({ type: "plano", ...summary });
+    const rows = sheet.rows.map((r) => [...r]);
+    let { iLat, iLon } = plan;
+    if (iLat < 0 || iLon < 0) { rows[0].push("latitude", "longitude"); iLat = rows[0].length - 2; iLon = rows[0].length - 1; }
+    const falhas = [];
+    let ok = 0, feitos = 0, bloqueado = null, last = 0;
+    const wait = geocodeInterval(cfg);
+    for (const it of plan.items) {
+      if (aborted) break;
+      let hit = cache[it.q];
+      if (!(it.q in cache)) {
+        const pause = last + wait - Date.now(); if (pause > 0) await new Promise((r) => setTimeout(r, pause));
+        last = Date.now();
+        try { hit = await geocodeOne(it.q, { cfg }); cache[it.q] = hit; }
+        catch (e) { if (e instanceof ServiceBlocked) { bloqueado = e.motivo; break; } hit = null; }
+      }
+      feitos++;
+      if (hit) { ok++; const r = rows[it.row]; while (r.length < rows[0].length) r.push(""); r[iLat] = String(hit.lat); r[iLon] = String(hit.lon); }
+      else falhas.push({ linha: it.row + 1, endereco: it.q });
+      if (feitos % 5 === 0 || feitos === plan.items.length) send({ type: "progresso", feitos, total: plan.items.length, ok });
+    }
+    writeJSONFile(cacheFile, cache);
+    // grava o que achou (CSV no mesmo arquivo; xlsx ganha um CSV ao lado, que é o que o mapa lê)
+    let out = b.path;
+    if (ok) {
+      if (/\.(csv|tsv)$/i.test(b.path)) Project.writeSheet(P, b.path, rows);
+      else { out = b.path.replace(/\.[^.]+$/, "") + ".csv"; Project.writeSheet(P, out, rows); }
+    }
+    send({ type: "fim", ok, falhas, bloqueado, cancelado: aborted, path: out });
+    res.end();
+    return true;
+  }
+  return false;
+}

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);