sagadeck 1.7.1 → 1.8.0

package/src/ai/map-data.js

@@ -0,0 +1,221 @@
+// A IA busca dados geográficos para o mapa (entrega 4), no mesmo molde do "ver o material": a IA que edita o deck,
+// quando precisa de dados de fora, responde um bloco `mapa:` com as ações (lugares do OpenStreetMap, linhas, contornos,
+// uma tabela da web, coordenadas de uma planilha da pessoa). O código executa, grava planilha ou GeoJSON no projeto
+// com a FONTE de cada linha e chama a IA de novo com o que gravou; ela monta o slide. Regras:
+//  - a decisão é do modelo (prompt), com o estado de cada serviço à vista; o código recusa, sem pedido de rede, o
+//    serviço bloqueado nesta execução (uma tentativa e para);
+//  - dados da pessoa (endereços de uma planilha dela) só saem com o sim dela: sem confirmação na conversa, o código
+//    não envia e a resposta pergunta (quantos, para qual serviço, quanto tempo);
+//  - geometria nunca inventada: vem do OpenStreetMap, da web com fonte, ou dos arquivos.
+import fs from "node:fs";
+import path from "node:path";
+import { loadMapConfig, mapaFile } from "../map-config.js";
+import { callService, serviceState, geocodeOne, geocodeInterval, ServiceBlocked, SERVICES } from "../map-services.js";
+import * as Project from "../studio/project.js";
+import { addressPlan } from "../studio/geo-routes.js";
+import { chat } from "./llm.js";
+import { jsonOf, runResearch, defaultWeb } from "../research/research.js";
+import { runAnalysis } from "./map-analysis-run.js";
+
+// tabela da web: a pesquisa que já existe (busca, lê, anota com a URL) e uma extração que só usa o que leu
+export async function webResearchDefault(pergunta, { saveDir = null } = {}) {
+  const r = await runResearch({ pesquisar: true, motivo: pergunta, buscas: [pergunta], academico: false }, { briefing: pergunta, web: defaultWeb, saveDir, maxSources: 5 });
+  return r.materials;
+}
+export async function extractTableDefault(pergunta, cols, docs) {
+  if (!docs.length) return [];
+  const fontes = docs.map((d) => `${d.name}\n${d.detail || ""}\n${clip(d.text, 6000)}`).join("\n\n---\n\n");
+  const r = await chat([{ role: "user", content: `Monte a tabela pedida SÓ com o que está nas fontes abaixo. Pedido: ${pergunta}
+Colunas: ${cols.join(", ")}. Cada linha leva também "fonte": a URL da fonte de onde ela saiu (está no detalhe de cada fonte).
+Não invente linhas, nomes nem endereços; o que a fonte não diz fica vazio. Responda só JSON: {"linhas": [{${cols.map((c) => `"${c}": "…"`).join(", ")}, "fonte": "https://…"}]}
+
+Fontes:
+${fontes}` }], { maxTokens: 6000, think: false, allowTruncated: true, retries: 0 });
+  const j = jsonOf(r.text) || {};
+  return (Array.isArray(j.linhas) ? j.linhas : []).filter((x) => x && typeof x === "object");
+}
+
+const clip = (s, n) => (String(s ?? "").length > n ? `${String(s).slice(0, n)}…` : String(s ?? ""));
+const slug = (s) => String(s || "dados").normalize("NFD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 40) || "dados";
+const okFile = (f, ext) => typeof f === "string" && /^contexto\/[\w\-. /]+$/.test(f) && f.toLowerCase().endsWith(ext) && !f.includes("..");
+
+const stateLine = (st) => Object.entries(st).map(([k, v]) => `- ${SERVICES[k]}: ${v.status === "bloqueado" ? `BLOQUEADO nesta rede (${v.motivo}); não peça` : v.status === "ok" ? "funcionando" : "ainda não usado (deve funcionar)"}`).join("\n");
+
+// ---- 1. o que a IA principal sabe (vai no prompt de src/ai/deck-ai.js quando há projeto) --------------------------
+// Quem decide é a IA que edita o deck: quando precisa de dados geográficos, ela responde um bloco `mapa:` com as
+// ações (como o `ver:` do material); o Studio executa (runMapData) e chama de novo com o resultado. Sem pedido de
+// mapa, nenhuma chamada a mais.
+export function mapDataPrompt() {
+  return `DADOS PARA O MAPA (slide layout: map): quando a pessoa pedir para mostrar no mapa algo que ela NÃO deu (lugares de um
+tipo, linhas como ciclovias ou rios, o contorno de um lugar com nome, uma lista que só existe na web, ou as coordenadas
+dos endereços de uma planilha dela), NÃO invente coordenadas nem geometria: responda uma frase e um bloco yaml só com
+\`\`\`yaml
+mapa:
+  - { tipo: lugares, oque: cinemas, filtro_osm: '["amenity"="cinema"]', perto_de: "Centro, Campinas, SP, Brasil", raio_km: 5, arquivo: contexto/cinemas.csv }
+  - { tipo: linhas, oque: ciclovias, filtro_osm: '["highway"="cycleway"]', perto_de: "…", raio_km: 3, arquivo: contexto/ciclovias.geojson }
+  - { tipo: contorno, nome: "Centro, Campinas, SP, Brasil", arquivo: contexto/centro.geojson }
+  - { tipo: web, pergunta: "unidades do INSS em Pernambuco com endereço", colunas: [nome, endereco, cidade], arquivo: contexto/inss-pe.csv }
+  - { tipo: coordenadas, planilha: contexto/unidades.csv, confirmado: false }
+\`\`\`
+O Studio busca (OpenStreetMap, web), grava os arquivos com a fonte de cada linha e te devolve o que gravou; aí você monta o
+slide com points:/geojson: e a fonte. filtro_osm são as tags do OpenStreetMap do tipo de lugar. Até 4 ações. Dados que já
+estão nas planilhas do projeto com latitude e longitude não precisam de busca.
+ANÁLISES (contas que o Studio faz sobre os arquivos do projeto; você só narra os números que ele devolver, nunca calcule
+distância, contagem ou tempo de cabeça), no mesmo bloco mapa:
+  - { tipo: mais_proximo, de: contexto/pedidos.csv, ate: contexto/lojas.csv }          # cada ponto de "de" com o mais próximo de "ate" e a distância
+  - { tipo: contar, pontos: contexto/sensores.csv, area: contexto/bairros.geojson }    # quantos em cada área (ou centro: [lat, lon] ou "endereço", metros: 500)
+  - { tipo: faixa, linha: contexto/rede.geojson, metros: 50, pontos: contexto/imoveis.csv }  # faixa em volta da linha e quantos pontos dentro
+  - { tipo: sugerir, existentes: contexto/sensores.csv, area: contexto/area.geojson, quantos: 3 }  # onde instalar: os lugares mais longe dos existentes
+  - { tipo: rota, de: "Rua A, 10, Recife", para: [-8.06, -34.9], modo: pe }           # rota pelas ruas com distância e tempo (pe, carro, bicicleta)
+  - { tipo: alcance, de: contexto/unidades.csv, minutos: 10, modo: pe }               # área alcançável em X minutos (precisa do OpenRouteService)
+  - { tipo: encaixar, trilha: contexto/percurso.gpx, modo: carro }                    # rastro de GPS tremido encaixado nas ruas
+Depois, ponha o resultado no slide (a camada gravada e uma frase com o número) e diga a fonte e o limite da conta.
+Mandar endereços de uma planilha DA PESSOA para um serviço de fora (tipo coordenadas) só com o sim explícito dela nesta
+conversa, dado depois de você dizer quantos endereços, para qual serviço e quanto tempo leva; sem esse sim,
+confirmado: false (o Studio pergunta por você). Dados públicos (lugares, contornos, web) não precisam perguntar.
+Serviços do mapa nesta máquina:
+${stateLine(serviceState())}
+Nunca peça um serviço BLOQUEADO: diga à pessoa o que não está disponível e ofereça a alternativa (planilha com
+coordenadas, os contornos embutidos de estados e países, a planilha do projeto).`;
+}
+
+
+// ---- 2. executar -------------------------------------------------------------------------------------------------
+// serviços que cada ação usa (as análises sem rede não usam nenhum; rota com endereço em texto usa o geocoder também)
+const NEEDS = { lugares: ["geocoder", "busca"], linhas: ["geocoder", "busca"], contorno: ["geocoder"], web: ["geocoder"], coordenadas: ["geocoder"],
+  mais_proximo: [], contar: [], faixa: [], sugerir: [], rota: ["rotas"], alcance: ["rotas"], encaixar: ["rotas"] };
+const ANALYSES = new Set(["mais_proximo", "contar", "faixa", "sugerir", "rota", "alcance", "encaixar"]); // src/ai/map-analysis-run.js
+
+async function centerOf(where, cfg) {
+  const hit = await geocodeOne(where, { cfg });
+  if (!hit) throw new Error(`não achei "${where}" no mapa`);
+  return hit;
+}
+
+async function overpass(query, cfg) {
+  const res = await callService("busca", cfg.busca.url, { method: "POST", cfg, headers: { "Content-Type": "application/x-www-form-urlencoded" }, body: `data=${encodeURIComponent(query)}`, timeoutMs: 40000 });
+  return (await res.json()).elements || [];
+}
+
+const tagAddress = (t) => [t["addr:street"] && `${t["addr:street"]}${t["addr:housenumber"] ? `, ${t["addr:housenumber"]}` : ""}`, t["addr:suburb"], t["addr:city"]].filter(Boolean).join(" - ");
+
+export async function runMapData(acoes, { P, cfg = loadMapConfig(mapaFile()), onProgress = () => {}, webResearch = (q) => webResearchDefault(q, { saveDir: P?.dir }), extractTable = extractTableDefault } = {}) {
+  const feitos = [], perguntas = [], falhas = [];
+  Project.ensureMeta(P); // contexto/ existe antes de gravar (writeSheet não cria a pasta)
+  for (const a of acoes) {
+    if (!NEEDS[a.tipo]) { falhas.push(`${a.tipo}: ação desconhecida`); continue; }
+    const blocked = NEEDS[a.tipo].map((s) => serviceState()[s]).find((s) => s.status === "bloqueado");
+    if (blocked) { falhas.push(`${a.tipo}${a.oque || a.nome ? ` (${a.oque || a.nome})` : ""}: serviço bloqueado nesta rede (${blocked.motivo}); não tentei`); continue; }
+    try {
+      if (a.tipo === "lugares" || a.tipo === "linhas") {
+        const arquivo = okFile(a.arquivo, a.tipo === "lugares" ? ".csv" : ".geojson") ? a.arquivo : `contexto/${slug(a.oque)}.${a.tipo === "lugares" ? "csv" : "geojson"}`;
+        const filtro = String(a.filtro_osm || "").replace(/[;(){}]/g, "");
+        if (!/^(\[[^\]]+\])+$/.test(filtro)) throw new Error(`filtro do OpenStreetMap inválido: ${filtro}`);
+        onProgress(`procurando ${a.oque || a.tipo} perto de ${a.perto_de}…`);
+        const c = await centerOf(a.perto_de, cfg);
+        const r = Math.round(Math.min(Math.max(Number(a.raio_km) || 3, 0.2), 30) * 1000);
+        if (a.tipo === "lugares") {
+          const els = await overpass(`[out:json][timeout:30];(node${filtro}(around:${r},${c.lat},${c.lon});way${filtro}(around:${r},${c.lat},${c.lon}););out center tags 300;`, cfg);
+          const rows = [["nome", "endereco", "latitude", "longitude", "fonte"]];
+          for (const e of els) {
+            const lat = e.lat ?? e.center?.lat, lon = e.lon ?? e.center?.lon;
+            if (lat == null || lon == null) continue;
+            rows.push([e.tags?.name || "(sem nome)", tagAddress(e.tags || {}), String(lat), String(lon), `https://www.openstreetmap.org/${e.type}/${e.id}`]);
+          }
+          Project.writeSheet(P, arquivo, rows);
+          feitos.push({ tipo: a.tipo, arquivo, linhas: rows.length - 1, oque: a.oque, perto_de: a.perto_de, fonte: "OpenStreetMap (© colaboradores do OpenStreetMap)" });
+        } else {
+          const els = await overpass(`[out:json][timeout:30];way${filtro}(around:${r},${c.lat},${c.lon});out geom tags 300;`, cfg);
+          const features = els.filter((e) => Array.isArray(e.geometry) && e.geometry.length > 1).map((e) => ({ type: "Feature", properties: { nome: e.tags?.name || "(sem nome)", fonte: `https://www.openstreetmap.org/way/${e.id}` }, geometry: { type: "LineString", coordinates: e.geometry.map((g) => [g.lon, g.lat]) } }));
+          Project.writeText(P, arquivo, JSON.stringify({ type: "FeatureCollection", features }));
+          feitos.push({ tipo: a.tipo, arquivo, linhas: features.length, oque: a.oque, perto_de: a.perto_de, fonte: "OpenStreetMap (© colaboradores do OpenStreetMap)" });
+        }
+      } else if (a.tipo === "contorno") {
+        const arquivo = okFile(a.arquivo, ".geojson") ? a.arquivo : `contexto/${slug(a.nome)}.geojson`;
+        onProgress(`procurando o contorno de ${a.nome}…`);
+        const g = cfg.geocoder;
+        const res = await callService("geocoder", `${g.url.replace(/\/+$/, "")}/search?format=jsonv2&limit=1&polygon_geojson=1&polygon_threshold=0.0005&q=${encodeURIComponent(a.nome)}`, { cfg });
+        const hit = (await res.json())?.[0];
+        if (!hit?.geojson || !/Polygon/.test(hit.geojson.type)) throw new Error(`não achei o contorno de "${a.nome}"`);
+        Project.writeText(P, arquivo, JSON.stringify({ type: "FeatureCollection", features: [{ type: "Feature", properties: { nome: a.nome, fonte: `https://www.openstreetmap.org/${hit.osm_type}/${hit.osm_id}` }, geometry: hit.geojson }] }));
+        feitos.push({ tipo: a.tipo, arquivo, linhas: 1, oque: a.nome, fonte: "OpenStreetMap (© colaboradores do OpenStreetMap)" });
+      } else if (a.tipo === "web") {
+        if (!webResearch || !extractTable) throw new Error("pesquisa na web indisponível");
+        const arquivo = okFile(a.arquivo, ".csv") ? a.arquivo : `contexto/${slug(a.pergunta)}.csv`;
+        onProgress(`pesquisando na web: ${a.pergunta}…`);
+        const docs = await webResearch(a.pergunta);
+        const cols = (Array.isArray(a.colunas) && a.colunas.length ? a.colunas : ["nome", "endereco"]).map(String).slice(0, 8);
+        const table = await extractTable(a.pergunta, cols, docs); // [{…colunas, fonte}]
+        const rows = [[...cols, "latitude", "longitude", "fonte"]];
+        const wait = geocodeInterval(cfg);
+        let last = 0;
+        for (const t of table.slice(0, 200)) {
+          const q = [t.endereco, t.cidade, t.uf].filter(Boolean).join(", ") || t.nome;
+          let hit = null;
+          if (q) { const pause = last + wait - Date.now(); if (pause > 0) await new Promise((r) => setTimeout(r, pause)); last = Date.now(); hit = await geocodeOne(q, { cfg }).catch((e) => { if (e instanceof ServiceBlocked) throw e; return null; }); }
+          rows.push([...cols.map((c) => String(t[c] ?? "")), hit ? String(hit.lat) : "", hit ? String(hit.lon) : "", String(t.fonte || "")]);
+        }
+        Project.writeSheet(P, arquivo, rows);
+        feitos.push({ tipo: a.tipo, arquivo, linhas: rows.length - 1, oque: a.pergunta, fonte: "web (a coluna fonte de cada linha diz de onde veio; revise antes de apresentar)" });
+      } else if (ANALYSES.has(a.tipo)) {
+        feitos.push(await runAnalysis(a, { P, cfg, onProgress }));
+      } else if (a.tipo === "coordenadas") {
+        const abs = Project.resolveIn(P, a.planilha);
+        const sheet = (await Project.readSheet(abs)).sheets[0];
+        const pl = addressPlan(sheet.rows, a.coluna);
+        if (pl.error) throw new Error(pl.error);
+        if (!pl.items.length) { feitos.push({ tipo: a.tipo, arquivo: a.planilha, linhas: 0, oque: "todas já tinham coordenadas" }); continue; }
+        if (a.confirmado !== true) {
+          const host = (() => { try { return new URL(cfg.geocoder.url).host; } catch { return cfg.geocoder.url; } })();
+          perguntas.push(`Para pôr no mapa, preciso achar as coordenadas de ${pl.items.length} endereço${pl.items.length === 1 ? "" : "s"} da planilha ${a.planilha} (coluna ${pl.column}). Isso envia esses endereços ao serviço ${host} e leva cerca de ${Math.max(1, Math.ceil((pl.items.length * geocodeInterval(cfg)) / 60000))} min. Posso enviar? (Também dá para fazer pela planilha, no botão Achar coordenadas.)`);
+          continue;
+        }
+        onProgress(`achando as coordenadas de ${pl.items.length} endereços…`);
+        const rows = sheet.rows.map((r) => [...r]);
+        let { iLat, iLon } = pl;
+        if (iLat < 0 || iLon < 0) { rows[0].push("latitude", "longitude"); iLat = rows[0].length - 2; iLon = rows[0].length - 1; }
+        const wait = geocodeInterval(cfg);
+        let ok = 0, last = 0;
+        for (const it of pl.items) {
+          const pause = last + wait - Date.now(); if (pause > 0) await new Promise((r) => setTimeout(r, pause)); last = Date.now();
+          const hit = await geocodeOne(it.q, { cfg });
+          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); }
+        }
+        const out = /\.(csv|tsv)$/i.test(a.planilha) ? a.planilha : a.planilha.replace(/\.[^.]+$/, "") + ".csv";
+        Project.writeSheet(P, out, rows);
+        feitos.push({ tipo: a.tipo, arquivo: out, linhas: ok, oque: `coordenadas de ${ok} de ${pl.items.length} endereços` });
+      }
+    } catch (e) {
+      falhas.push(`${a.tipo}${a.oque || a.nome ? ` (${a.oque || a.nome})` : ""}: ${e.message}`);
+      if (e instanceof ServiceBlocked) continue;
+    }
+  }
+  return { feitos, perguntas, falhas };
+}
+
+// o que a IA recebe junto do pedido: o que foi gravado (para usar no slide) e o que falhou (para dizer à pessoa)
+export function mapDataInstruction({ feitos, falhas }) {
+  if (!feitos.length && !falhas.length) return "";
+  const lines = feitos.map((f) => `- ${f.arquivo}: ${f.linhas} ${f.tipo === "contorno" ? "contorno" : f.tipo === "linhas" ? "linhas" : "linhas"} (${f.oque}${f.perto_de ? `, perto de ${f.perto_de}` : ""}); fonte: ${f.fonte || "planilha da pessoa"}`);
+  const vazios = feitos.filter((f) => (f.tipo === "lugares" || f.tipo === "linhas") && !f.linhas);
+  return `[Dados geográficos buscados pelo sagadeck agora]\n${lines.join("\n")}${vazios.length ? `\nA busca não achou nada em ${vazios.map((f) => f.oque).join(", ")} nesse raio: diga isso e ofereça buscar num raio maior (ou outro lugar), sem montar mapa vazio.` : ""}${falhas.length ? `\nNão deu: ${falhas.join("; ")}. Diga isso à pessoa sem inventar o que faltou.` : ""}
+Use esses arquivos no slide de mapa (points: para .csv, geojson: para .geojson), com a fonte numa nota ou em source: ("Fonte: OpenStreetMap"). Dado da web: avise que vale revisar.`;
+}
+
+// planilhas do projeto, para a decisão saber o que já existe
+export async function projectSheets(P) {
+  const out = [];
+  const dir = path.join(P.dir, "contexto");
+  const walk = (d) => { for (const e of fs.existsSync(d) ? fs.readdirSync(d, { withFileTypes: true }) : []) { const f = path.join(d, e.name); if (e.isDirectory()) walk(f); else if (/\.(csv|tsv|xlsx)$/i.test(e.name)) out.push(f); } };
+  walk(dir);
+  const sheets = [];
+  for (const f of out.slice(0, 12)) {
+    try {
+      const rows = (await Project.readSheet(f)).sheets[0].rows;
+      const rel = path.relative(P.dir, f).split(path.sep).join("/");
+      const pl = addressPlan(rows);
+      sheets.push({ path: rel, columns: (rows[0] || []).map(String).slice(0, 12), rows: Math.max(0, rows.length - 1), semPosicao: pl.error ? 0 : pl.items.length });
+    } catch { /* planilha que não abre: fica de fora */ }
+  }
+  return sheets;
+}

package/src/build.js

@@ -20,6 +20,7 @@ import { normalizeSpec } from "./fiscal/normalize.js";
 import { readRecordings } from "./api-client.js";
 import { explorationStates } from './exploration.js';
 import { calcModel } from './lessons.js';
+import { loadMapConfig, mapaFile, tilesForDeck } from "./map-config.js";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const read = (p) => fs.readFileSync(path.join(HERE, p), "utf8");
@@ -132,7 +133,9 @@ export function buildHTML(rawSpec, opts = {}) {
   const theme = resolveTheme(spec.theme, spec.palette, identityOf(spec));
   const warnings = [];
   if (spec.identity && !theme.identity) warnings.push(`identidade "${spec.identity}" não está em ${identitiesFile()} nesta máquina: a apresentação saiu com as fontes do tema`);
-  const ctx = { baseDir: spec._dir || process.cwd(), theme, spec, warnings };
+  // serviços do mapa desta máquina (só o fundo vai para o HTML; nunca chave de rotas/endereços): src/map-config.js
+  const mapTiles = (spec.slides || []).some((x) => x?.layout === "map") ? tilesForDeck(loadMapConfig(mapaFile())) : null;
+  const ctx = { baseDir: spec._dir || process.cwd(), theme, spec, warnings, mapTiles };
   const id = spec.id || slug(spec.title);
   const slidesMeta = [];
   let html = "";
@@ -231,6 +234,7 @@ ${spec.slides.some((s) => s.layout === "diagram") ? `<script>${read("runtime/ven
 ${spec.slides.some(s => s.layout === "science") ? `<script>${read("runtime/vendor/plotly.min.js").replace(/<\/script/gi,"<\\/script")}</script><script>${read("runtime/formula.js")}</script><script>${read("runtime/science.js")}</script>` : ""}
 ${spec.slides.some(s => s.layout === "calc") ? `${spec.slides.some(s => s.layout === "science") ? "" : `<script>${read("runtime/formula.js")}</script>`}<script>${read("runtime/calc.js")}</script>` : ""}
 ${spec.slides.some(s=>s.layout==="portal") ? `<script>${read("runtime/portal-scene.js")}</script>` : ""}
+${spec.slides.some((s) => s.layout === "map") ? `<style>${read("runtime/vendor/leaflet.css")}</style><script>${read("runtime/vendor/leaflet.js").replace(/<\/script/gi, "<\\/script")}</script><script>${read("runtime/map.js")}</script>` : ""}
 ${JSON.stringify(spec.slides || []).includes('"points"') ? `<script>${read("runtime/points.js")}</script>` : ""}
 ${spec.slides.some(s=>s.layout==="playground") ? `<script>${read("runtime/playground.js")}</script>` : ""}
 ${hasApi ? `${apiScripts}\n<script>${read("runtime/api-ui.js")}</script><script>${read("runtime/api-collection-ui.js")}</script>` : ""}
@@ -313,7 +317,7 @@ export function renderSlide(raw, i = 0, spec = {}) {
   const deckTheme = resolveTheme(spec.theme, spec.palette, identityOf(spec));
   const s = { ...(spec.defaults || {}), ...raw };
   const theme = slideTheme(s, deckTheme, spec);
-  const ctx = { baseDir: spec._dir || process.cwd(), theme, spec, warnings: [] };
+  const ctx = { baseDir: spec._dir || process.cwd(), theme, spec, warnings: [], mapTiles: inferLayout(s) === "map" ? tilesForDeck(loadMapConfig(mapaFile())) : null };
   const layout = inferLayout(s);
   const fn = LAYOUTS[layout];
   if (!fn) throw new Error(`Slide ${i + 1}: layout "${layout}" não existe.`);

package/src/export/browser.js

@@ -1,5 +1,7 @@
 // Abre o deck num Chrome/Edge headless (usa o navegador já instalado; nada é baixado).
 import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { chromium } from "playwright-core";
 
@@ -20,14 +22,34 @@ export function findBrowser() {
   return p;
 }
 
+// Deck com mapa abre por um endereço local (http://127.0.0.1), não como arquivo: o servidor de tiles do OpenStreetMap
+// pede que o navegador diga de onde vem o pedido, e página aberta do disco não diz. Só lê a pasta do deck.
+async function serveDir(dir) {
+  const server = http.createServer((req, res) => {
+    const rel = decodeURIComponent(new URL(req.url, "http://x").pathname).replace(/^\/+/, "");
+    const file = path.resolve(dir, rel);
+    if (req.method !== "GET" || !file.startsWith(path.resolve(dir)) || !fs.existsSync(file) || !fs.statSync(file).isFile()) { res.writeHead(404); return res.end(); }
+    res.writeHead(200, { "Content-Type": file.endsWith(".html") ? "text/html; charset=utf-8" : "application/octet-stream" });
+    fs.createReadStream(file).pipe(res);
+  });
+  await new Promise((r) => server.listen(0, "127.0.0.1", r));
+  return server;
+}
+
+// a exportação, depois de ir a um slide, espera o mapa dele (tiles carregados ou desistência; no máximo 8 s)
+export const settleSlide = (page) => page.evaluate(() => window.SagaMap?.settled?.() ?? null);
+
 export async function openDeck(htmlFile, { scale = 1 } = {}) {
   const browser = await chromium.launch({ executablePath: findBrowser() });
+  const hasMap = fs.readFileSync(htmlFile, "utf8").includes('class="map-box');
+  const server = hasMap ? await serveDir(path.dirname(htmlFile)) : null;
+  if (server) { const close = browser.close.bind(browser); browser.close = async () => { await close(); server.close(); }; }
   try {
   const page = await browser.newPage({ viewport: { width: 1920, height: 1080 }, deviceScaleFactor: scale });
   const errors = [];
   page.on("pageerror", (e) => errors.push(e.message));
   page.on("console", (m) => { if (m.type() === "error") errors.push(m.text()); });
-  await page.goto(pathToFileURL(htmlFile).href + "?export=1");
+  await page.goto((server ? `http://127.0.0.1:${server.address().port}/${encodeURIComponent(path.basename(htmlFile))}` : pathToFileURL(htmlFile).href) + "?export=1");
   await page.waitForFunction(() => window.sagadeck && window.sagadeck.cur >= 0 && document.fonts.status === "loaded");
   // a janela com o tamanho do slide (deck.aspect: 4:3 → 1920 × 1440): foto, PDF e PPTX sem faixa nem corte
   const size = await page.evaluate(() => window.sagadeck.size || { w: 1920, h: 1080 });

package/src/export/pptx.js

@@ -9,7 +9,7 @@
 import fs from "node:fs";
 import PptxGenJS from "pptxgenjs";
 import JSZip from "jszip";
-import { openDeck } from "./browser.js";
+import { openDeck, settleSlide } from "./browser.js";
 import { pptxFontMap, macFallbackFace } from "../themes.js";
 import { notesPlain } from "../markup.js";
 
@@ -353,6 +353,7 @@ export async function exportPptx(htmlFile, outFile, { theme, meta, nativeCharts
   for (let i = 0; i < n; i++) {
     const S = await page.evaluate((j) => window.sagadeck.steps(j), i);
     await page.evaluate(([j, k]) => window.sagadeck.goto(j, k, true), [i, S]);
+    await settleSlide(page);
     await page.waitForTimeout(40);
     const data = await page.evaluate(collectInPage, [i, nativeCharts]);
     const slide = pres.addSlide();

package/src/export/shots.js

@@ -1,7 +1,7 @@
 // PNG de cada slide, folha de contato, PDF e verificação automática de qualidade.
 import fs from "node:fs";
 import path from "node:path";
-import { openDeck, waitForResources } from "./browser.js";
+import { openDeck, waitForResources, settleSlide } from "./browser.js";
 
 // Estado final de cada slide (todos os cliques revelados)
 export async function shots(htmlFile, outDir, { steps = false, scale = 1, only, jpeg = false } = {}) {
@@ -17,6 +17,7 @@ export async function shots(htmlFile, outDir, { steps = false, scale = 1, only,
     const list = steps ? Array.from({ length: S + 1 }, (_, k) => k) : [S];
     for (const k of list) {
       await page.evaluate(([j, kk]) => window.sagadeck.goto(j, kk), [i, k]);
+      await settleSlide(page);
       await page.waitForTimeout(60);
       const f = path.join(outDir, `slide-${String(i + 1).padStart(2, "0")}${steps ? `-${k}` : ""}.${jpeg ? "jpg" : "png"}`);
       await page.screenshot(jpeg ? { path: f, type: "jpeg", quality: 82 } : { path: f });
@@ -56,6 +57,7 @@ export async function pdf(htmlFile, outFile) {
   for (let i = 0; i < n; i++) {
     const S = await page.evaluate((j) => window.sagadeck.steps(j), i);
     await page.evaluate(([j, k]) => window.sagadeck.goto(j, k), [i, S]);
+    await settleSlide(page);
     await page.waitForTimeout(50);
     imgs.push((await page.screenshot({ type: "jpeg", quality: 92 })).toString("base64"));
     links.push(await page.evaluate(gotoRects, i));

package/src/layouts.js

@@ -22,6 +22,7 @@ import { slideSize } from "./aspect.js";
 import { recreatedFrame } from "./master.js";
 import { solutionHTML, calcHTML, algoHTML } from "./lessons.js";
 import "./runtime/api-core.js"; // globalThis.SagadeckApiCore (o mesmo núcleo que roda na apresentação)
+import { mapModel, mapPreviewSVG, mapSummary } from "./map.js";
 
 const plainTitle = (s) => String(s.title || s.kicker || s.layout || "").replace(/[*=^~`]/g, "").slice(0, 40);
 const kicker = (s, d = 0) => (s.kicker ? `<div class="kicker t f-label e" style="--d:${d}">${md(s.kicker)}</div>` : "");
@@ -733,6 +734,15 @@ export const LAYOUTS = {
   calc(s, ctx) { return `${calcHTML(s, ctx, head)}${src(s)}${add(s, ctx)}`; },
   algo(s, ctx) { return `${algoHTML(s, ctx, head)}${src(s)}${add(s, ctx)}`; },
 
+  // Mapa: camadas de planilha, GeoJSON, GPX, KML ou valores por estado/país (src/map.js), desenhadas ao vivo pelo
+  // Leaflet só quando o slide aparece (src/runtime/map.js). A prévia em SVG fica por baixo (miniaturas, reserva).
+  // Cada camada com passo ganha um marcador invisível data-step: o clique que a revela é o mesmo dos outros slides.
+  map(s, ctx) {
+    const m = mapModel(s, ctx);
+    const steps = m.layers.map((l, i) => (l.step ? `<i class="map-step" data-step="${l.step}" data-layer="${i}" hidden></i>` : "")).join("");
+    const data = JSON.stringify(m).replace(/</g, "\\u003c");
+    return `<div class="L-map">${head(s)}<div class="map-box e" style="--d:2" data-basemap="${m.basemap}" aria-label="Mapa: ${esc(mapSummary(m))}">${mapPreviewSVG(m)}<div class="map-live"></div><script type="application/json" class="map-data">${data}</script>${steps}</div>${s.caption ? text(s.caption, "small", { class: "map-caption muted" }) : ""}</div>${src(s)}${add(s, ctx)}`;
+  },
   science(s, ctx) {
     return `<div class="L-science">${head(s)}<div class="science-body${s.plot === false ? ' equations-only' : !(s.equations || []).length ? ' plot-only' : ''}"><div class="science-equations">${mathHTML(s.equations || [])}</div>${s.plot === false ? '' : plotHTML(s.plot || {}, ctx)}</div>${s.caption ? text(s.caption,'small') : ''}</div>${add(s,ctx)}`;
   },

package/src/map-analysis.js

@@ -0,0 +1,106 @@
+// Análises do mapa (entrega 5): contas que o CÓDIGO faz e a IA só narra. Sem rede (as que precisam de serviço,
+// como rota com tempo e área alcançável, ficam em src/map-routing.js). Coordenadas em [lat, lon]; GeoJSON em
+// [lon, lat]. Distâncias na esfera (haversine), boas para cidade e região.
+import { distance } from "./map-routing.js";
+
+const R = 6371008.8, rad = Math.PI / 180;
+
+// ponto mais próximo de cada ponto de A, entre os pontos de B: [{ i, j, metros }]
+export function nearest(A, B) {
+  return A.map((a, i) => {
+    let best = -1, d = Infinity;
+    B.forEach((b, j) => { const x = distance(a, b); if (x < d) { d = x; best = j; } });
+    return { i, j: best, metros: Number.isFinite(d) ? d : null };
+  });
+}
+
+// quantos pontos ficam a até `metros` de um centro
+export const withinRadius = (points, center, metros) => points.map((p, i) => [i, distance(p, center)]).filter(([, d]) => d <= metros).map(([i]) => i);
+
+// ponto dentro de polígono (anéis GeoJSON [lon, lat]; o primeiro é o contorno, os outros são buracos)
+function inRing([lat, lon], ring) {
+  let inside = false;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+    const [xi, yi] = ring[i], [xj, yj] = ring[j];
+    if ((yi > lat) !== (yj > lat) && lon < ((xj - xi) * (lat - yi)) / (yj - yi) + xi) inside = !inside;
+  }
+  return inside;
+}
+export function inPolygon(p, geometry) {
+  const polys = geometry.type === "Polygon" ? [geometry.coordinates] : geometry.type === "MultiPolygon" ? geometry.coordinates : [];
+  return polys.some((rings) => inRing(p, rings[0]) && !rings.slice(1).some((h) => inRing(p, h)));
+}
+
+// distância de um ponto a um segmento (metros), numa projeção local equiretangular (boa até dezenas de km)
+function toXY([lat, lon], lat0) { return [lon * rad * R * Math.cos(lat0 * rad), lat * rad * R]; }
+export function pointSegment(p, a, b) {
+  const lat0 = p[0], [px, py] = toXY(p, lat0), [ax, ay] = toXY(a, lat0), [bx, by] = toXY(b, lat0);
+  const dx = bx - ax, dy = by - ay, L = dx * dx + dy * dy;
+  const t = L ? Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / L)) : 0;
+  return Math.hypot(px - (ax + t * dx), py - (ay + t * dy));
+}
+// distância de um ponto a uma linha GeoJSON (LineString ou MultiLineString)
+export function pointLine(p, geometry) {
+  const lines = geometry.type === "LineString" ? [geometry.coordinates] : geometry.type === "MultiLineString" ? geometry.coordinates : [];
+  let d = Infinity;
+  for (const l of lines) for (let k = 1; k < l.length; k++) d = Math.min(d, pointSegment(p, [l[k - 1][1], l[k - 1][0]], [l[k][1], l[k][0]]));
+  return d;
+}
+
+// círculo como polígono (para raio e para a faixa): n vértices
+export function circle([lat, lon], metros, n = 32) {
+  const ring = [];
+  for (let k = 0; k <= n; k++) {
+    const a = (2 * Math.PI * k) / n;
+    ring.push([lon + (metros * Math.sin(a)) / (R * Math.cos(lat * rad)) / rad, lat + (metros * Math.cos(a)) / R / rad]);
+  }
+  return { type: "Polygon", coordinates: [ring] };
+}
+
+// faixa de `metros` em volta de uma linha, para DESENHAR: retângulos dos trechos e círculos nos vértices (MultiPolygon).
+// Para CONTAR o que está dentro, use pointLine (exato).
+export function lineBuffer(geometry, metros) {
+  const lines = geometry.type === "LineString" ? [geometry.coordinates] : geometry.type === "MultiLineString" ? geometry.coordinates : [];
+  const polys = [];
+  for (const l of lines) {
+    for (let k = 0; k < l.length; k++) {
+      polys.push(circle([l[k][1], l[k][0]], metros, 16).coordinates);
+      if (!k) continue;
+      const [lon1, lat1] = l[k - 1], [lon2, lat2] = l[k];
+      const lat0 = (lat1 + lat2) / 2, kx = 1 / (R * Math.cos(lat0 * rad)) / rad, ky = 1 / R / rad;
+      const dx = (lon2 - lon1) / kx, dy = (lat2 - lat1) / ky, len = Math.hypot(dx, dy) || 1;
+      const ox = (-dy / len) * metros * kx, oy = (dx / len) * metros * ky;
+      polys.push([[[lon1 + ox, lat1 + oy], [lon2 + ox, lat2 + oy], [lon2 - ox, lat2 - oy], [lon1 - ox, lat1 - oy], [lon1 + ox, lat1 + oy]]]);
+    }
+  }
+  return { type: "MultiPolygon", coordinates: polys };
+}
+
+// "onde instalar o próximo": os `quantos` lugares mais longe de todos os existentes (e uns dos outros), dentro da área
+// (polígono) ou do retângulo que cobre os existentes. Grade + escolha gulosa; devolve [{ lat, lon, metros }] com a
+// distância até o existente (ou sugerido) mais próximo.
+export function suggestSites(existing, { area = null, quantos = 3, grade = 40 } = {}) {
+  let s = 90, w = 180, n = -90, e = -180;
+  const add = ([lat, lon]) => { s = Math.min(s, lat); n = Math.max(n, lat); w = Math.min(w, lon); e = Math.max(e, lon); };
+  if (area) { const walk = (c) => (typeof c[0] === "number" ? add([c[1], c[0]]) : c.forEach(walk)); walk(area.coordinates); } else existing.forEach(add);
+  if (s > n) return [];
+  // pontos alinhados (todos na mesma latitude ou longitude): o retângulo ganha a metade do outro lado de folga
+  if (!area) { const padLat = n - s < 1e-9 ? Math.max((e - w) / 2, 0.005) : 0, padLon = e - w < 1e-9 ? Math.max((n - s) / 2, 0.005) : 0; s -= padLat; n += padLat; w -= padLon; e += padLon; }
+  if (!(n > s) || !(e > w)) return [];
+  const cand = [];
+  for (let i = 0; i < grade; i++) for (let j = 0; j < grade; j++) {
+    const p = [s + ((n - s) * (i + 0.5)) / grade, w + ((e - w) * (j + 0.5)) / grade];
+    if (!area || inPolygon(p, area)) cand.push(p);
+  }
+  const chosen = [], base = [...existing];
+  for (let k = 0; k < quantos && cand.length; k++) {
+    let best = null, bd = -1;
+    for (const c of cand) { const d = base.length ? Math.min(...base.map((b) => distance(c, b))) : Infinity; if (d > bd) { bd = d; best = c; } }
+    if (!best) break;
+    chosen.push({ lat: best[0], lon: best[1], metros: Number.isFinite(bd) ? bd : null });
+    base.push(best);
+  }
+  return chosen;
+}
+
+export const fmtMetros = (m) => (m == null ? "?" : m >= 1000 ? `${(m / 1000).toLocaleString("pt-BR", { maximumFractionDigits: 1 })} km` : `${Math.round(m)} m`);

package/src/map-config.js

@@ -0,0 +1,83 @@
+// Os serviços do mapa desta máquina (~/.sagadeck/mapa.json, ou SAGADECK_MAPA): tiles do fundo, satélite, endereço↔
+// coordenada, busca de lugares e rotas. Fora do código e fora da biblioteca, como a configuração da IA. Sem arquivo,
+// valem os serviços públicos gratuitos (OpenStreetMap e companhia), com as regras de uso deles respeitadas pelo
+// sagadeck (identificação, atribuição visível, um pedido por segundo no Nominatim, nada de baixar tiles fora da tela).
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { renameRetry } from "./fs-retry.js";
+
+export function mapaFile(env = process.env, home = os.homedir()) {
+  return env.SAGADECK_MAPA || path.join(home, ".sagadeck", "mapa.json");
+}
+
+const OSM = "© colaboradores do OpenStreetMap";
+export const MAP_DEFAULTS = {
+  // fundo de ruas; "claro" e "escuro" são o mesmo fundo com filtro de cor (sem outro provedor)
+  tiles: { url: "https://tile.openstreetmap.org/{z}/{x}/{y}.png", attribution: OSM, maxZoom: 19 },
+  // satélite só com provedor configurado (costuma pedir chave); sem ele, o slide usa as ruas e avisa
+  satelite: null,
+  geocoder: { provedor: "nominatim", url: "https://nominatim.openstreetmap.org", porSegundo: 1 },
+  busca: { provedor: "overpass", url: "https://overpass-api.de/api/interpreter" },
+  rotas: { provedor: "osrm", url: "https://router.project-osrm.org" },
+};
+
+const str = (v, max = 500) => (typeof v === "string" ? v.trim().slice(0, max) : "");
+const service = (raw, base) => {
+  if (raw === null) return null;
+  if (!raw || typeof raw !== "object") return base;
+  const out = { ...(base || {}) };
+  for (const [k, v] of Object.entries(raw)) if (typeof v === "string") out[k] = str(v, 1000); else if (typeof v === "number" && Number.isFinite(v)) out[k] = v;
+  return out.url ? out : base;
+};
+
+// a configuração que vale: o arquivo por cima do padrão, campo a campo (arquivo editado à mão não quebra nada). A
+// chave pode vir de uma variável de ambiente indicada em keyEnv (no servidor), como no ia.json.
+export function loadMapConfig(file = mapaFile(), env = process.env) {
+  let raw = {};
+  try { raw = JSON.parse(fs.readFileSync(file, "utf8")) || {}; } catch { raw = {}; }
+  return Object.fromEntries(Object.entries(MAP_DEFAULTS).map(([k, base]) => {
+    const s = service(raw[k], base);
+    if (s && !s.key && s.keyEnv && env[s.keyEnv]) return [k, { ...s, key: env[s.keyEnv], keyFrom: "variável" }];
+    return [k, s];
+  }));
+}
+
+// grava o que veio da tela Configurar mapa por cima do arquivo (campo a campo; chave em branco mantém a gravada),
+// de forma atômica e só para quem é dono da conta (as chaves moram aqui)
+export function saveMapConfig(patch, file = mapaFile()) {
+  let cur = {};
+  try { cur = JSON.parse(fs.readFileSync(file, "utf8")) || {}; } catch { cur = {}; }
+  for (const [k, v] of Object.entries(patch || {})) {
+    if (!(k in MAP_DEFAULTS)) continue;
+    if (v === null) { cur[k] = null; continue; }
+    if (!v || typeof v !== "object") continue;
+    const next = { ...(cur[k] && typeof cur[k] === "object" ? cur[k] : {}) };
+    for (const [f, x] of Object.entries(v)) {
+      if (f === "key" && !String(x ?? "").trim()) continue; // em branco: mantém a chave gravada
+      if (typeof x === "string") next[f] = str(x, 1000); else if (typeof x === "number" && Number.isFinite(x)) next[f] = x;
+    }
+    cur[k] = next;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(cur, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+  renameRetry(tmp, file);
+  return loadMapConfig(file);
+}
+
+// para a tela: a chave nunca sai inteira
+export function maskedMapConfig(cfg) {
+  return Object.fromEntries(Object.entries(cfg).map(([k, v]) => {
+    if (!v) return [k, v];
+    const { key, ...rest } = v;
+    return [k, { ...rest, keySet: !!key, keyHint: key ? `••••${String(key).slice(-4)}` : "", keyFrom: key ? rest.keyFrom || "arquivo" : "" }];
+  }));
+}
+
+// o que pode ir para dentro do HTML da apresentação: só o fundo (o navegador busca os tiles). Chave de rotas e de
+// geocodificação nunca vai para o deck.
+export function tilesForDeck(cfg = loadMapConfig()) {
+  const pick = (t) => (t ? { url: t.url, attribution: t.attribution || OSM, maxZoom: t.maxZoom || 19 } : null);
+  return { tiles: pick(cfg.tiles), satelite: pick(cfg.satelite) };
+}