sagadeck 1.7.0 → 1.8.0

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

package/src/map-routing.js

@@ -0,0 +1,82 @@
+// Rotas pelas ruas e endereço de um ponto, para o editor do mapa (entrega 3) e as análises (entrega 5). Passam por
+// callService (src/map-services.js): identificação do sagadeck e "uma tentativa e para".
+//  - rota: OpenRouteService quando configurado com chave (a pé, de carro, de bicicleta; também isócronas) ou OSRM
+//    (padrão público; o servidor de demonstração só tem carro de forma garantida);
+//  - endereço de um ponto: Nominatim /reverse (ou compatível).
+import { loadMapConfig, mapaFile } from "./map-config.js";
+import { callService } from "./map-services.js";
+
+export const MODOS = { pe: "a pé", carro: "de carro", bicicleta: "de bicicleta" };
+const ORS_PROFILE = { pe: "foot-walking", carro: "driving-car", bicicleta: "cycling-regular" };
+const OSRM_PROFILE = { pe: "foot", carro: "driving", bicicleta: "bike" };
+
+const isORS = (r) => r && (r.provedor === "openrouteservice" || /openrouteservice/i.test(r.url || ""));
+
+// pontos: [[lat, lon], …] (2 ou mais). Devolve { coords: [[lon, lat], …], distancia (m), duracao (s), modo }
+export async function route(pontos, { modo = "pe", cfg = loadMapConfig(mapaFile()) } = {}) {
+  if (!Array.isArray(pontos) || pontos.length < 2) throw new Error("Rota: preciso de pelo menos dois pontos.");
+  const pts = pontos.map(([lat, lon]) => [Number(lat), Number(lon)]);
+  if (pts.some(([a, b]) => !Number.isFinite(a) || !Number.isFinite(b))) throw new Error("Rota: ponto sem coordenada.");
+  const r = cfg.rotas;
+  const m = MODOS[modo] ? modo : "pe";
+  if (isORS(r) && r.key) {
+    const base = (r.url || "https://api.openrouteservice.org").replace(/\/+$/, "");
+    const res = await callService("rotas", `${base}/v2/directions/${ORS_PROFILE[m]}/geojson`, {
+      method: "POST", cfg, headers: { Authorization: r.key, "Content-Type": "application/json", Accept: "application/json, application/geo+json" },
+      body: JSON.stringify({ coordinates: pts.map(([lat, lon]) => [lon, lat]) }),
+    });
+    const j = await res.json();
+    const f = j.features?.[0];
+    if (!f) throw new Error("Rota: o serviço não achou caminho entre os pontos.");
+    return { coords: f.geometry.coordinates, distancia: f.properties?.summary?.distance ?? 0, duracao: f.properties?.summary?.duration ?? 0, modo: m };
+  }
+  const base = (r?.url || "https://router.project-osrm.org").replace(/\/+$/, "");
+  const res = await callService("rotas", `${base}/route/v1/${OSRM_PROFILE[m]}/${pts.map(([lat, lon]) => `${lon},${lat}`).join(";")}?overview=full&geometries=geojson`, { cfg });
+  const j = await res.json();
+  const rt = j.routes?.[0];
+  if (!rt) throw new Error("Rota: o serviço não achou caminho entre os pontos.");
+  return { coords: rt.geometry.coordinates, distancia: rt.distance, duracao: rt.duration, modo: m };
+}
+
+// área alcançável em X minutos a partir de um ponto (só OpenRouteService): GeoJSON Polygon
+export async function isochrone([lat, lon], minutos, { modo = "pe", cfg = loadMapConfig(mapaFile()) } = {}) {
+  const r = cfg.rotas;
+  if (!isORS(r) || !r.key) throw new Error("Área alcançável precisa do OpenRouteService com chave (Configurar mapa).");
+  const base = (r.url || "https://api.openrouteservice.org").replace(/\/+$/, "");
+  const res = await callService("rotas", `${base}/v2/isochrones/${ORS_PROFILE[MODOS[modo] ? modo : "pe"]}`, {
+    method: "POST", cfg, headers: { Authorization: r.key, "Content-Type": "application/json", Accept: "application/json, application/geo+json" },
+    body: JSON.stringify({ locations: [[Number(lon), Number(lat)]], range: [Math.round(Number(minutos) * 60)], range_type: "time" }),
+  });
+  const j = await res.json();
+  const f = j.features?.[0];
+  if (!f) throw new Error("Área alcançável: o serviço não devolveu a área.");
+  return f.geometry;
+}
+
+// rastro de GPS tremido -> o caminho pelas ruas por onde passou (OSRM /match; com o OpenRouteService configurado
+// para rotas, o encaixe usa o OSRM público). pontos: [[lat, lon], …] (até 100). Devolve [[lon, lat], …]
+export async function matchTrace(pontos, { modo = "pe", cfg = loadMapConfig(mapaFile()) } = {}) {
+  const pts = pontos.slice(0, 100).map(([lat, lon]) => [Number(lat), Number(lon)]).filter(([a, b]) => Number.isFinite(a) && Number.isFinite(b));
+  if (pts.length < 2) throw new Error("Encaixar nas ruas: o rastro precisa de pelo menos dois pontos.");
+  const base = (!isORS(cfg.rotas) && cfg.rotas?.url ? cfg.rotas.url : "https://router.project-osrm.org").replace(/\/+$/, "");
+  const res = await callService("rotas", `${base}/match/v1/${OSRM_PROFILE[MODOS[modo] ? modo : "pe"]}/${pts.map(([lat, lon]) => `${lon},${lat}`).join(";")}?overview=full&geometries=geojson`, { cfg });
+  const j = await res.json();
+  const coords = (j.matchings || []).flatMap((m) => m.geometry?.coordinates || []);
+  if (coords.length < 2) throw new Error("Encaixar nas ruas: o serviço não achou as ruas desse rastro.");
+  return coords;
+}
+
+// endereço de um ponto (para preencher a coluna de endereço de um ponto novo)
+export async function reverseGeocode(lat, lon, { cfg = loadMapConfig(mapaFile()) } = {}) {
+  const g = cfg.geocoder;
+  const res = await callService("geocoder", `${g.url.replace(/\/+$/, "")}/reverse?format=jsonv2&lat=${Number(lat)}&lon=${Number(lon)}${g.key ? `&key=${encodeURIComponent(g.key)}` : ""}`, { cfg });
+  const j = await res.json();
+  return j?.display_name || "";
+}
+
+// distância em metros entre dois pontos [lat, lon] (haversine): a régua e o "mais próximo" (entrega 5)
+export function distance([lat1, lon1], [lat2, lon2]) {
+  const R = 6371008.8, rad = Math.PI / 180;
+  const a = Math.sin(((lat2 - lat1) * rad) / 2) ** 2 + Math.cos(lat1 * rad) * Math.cos(lat2 * rad) * Math.sin(((lon2 - lon1) * rad) / 2) ** 2;
+  return 2 * R * Math.asin(Math.sqrt(a));
+}

package/src/map-services.js

@@ -0,0 +1,60 @@
+// Chamadas aos serviços do mapa (endereço↔coordenada, busca de lugares, rotas), feitas pelo servidor do Studio com a
+// identificação do sagadeck (as políticas de uso pedem). Regras:
+//  - uma tentativa e para: erro de autorização ou bloqueio (401, 403, 407, 429, recusa, certificado, tempo esgotado)
+//    marca o serviço indisponível nesta execução, e nenhum pedido sai até alguém pedir "Tentar de novo";
+//  - sem teste proativo: o estado começa "não usado" e só muda com uso de verdade;
+//  - o estado de cada serviço vai para a IA (ela decide o que chamar) e para a tela Configurar mapa.
+import { loadMapConfig, mapaFile } from "./map-config.js";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const VERSION = (() => { try { return require("../package.json").version; } catch { return "?"; } })();
+export const USER_AGENT = `sagadeck/${VERSION} (+https://github.com/naruminho/sagadeck)`;
+export const SERVICES = { geocoder: "Endereço e coordenada", busca: "Busca de lugares", rotas: "Rotas" };
+
+const state = new Map(); // serviço -> { status: "ok" | "bloqueado", motivo, quando }
+export const serviceState = () => Object.fromEntries(Object.keys(SERVICES).map((k) => [k, state.get(k) || { status: "não usado" }]));
+export const resetService = (k) => (k ? state.delete(k) : state.clear());
+
+export class ServiceBlocked extends Error {
+  constructor(service, motivo) { super(`${SERVICES[service] || service}: ${motivo}`); this.service = service; this.motivo = motivo; this.code = "MAP_SERVICE_BLOCKED"; }
+}
+
+const hhmm = () => new Date().toLocaleTimeString("pt-BR", { hour: "2-digit", minute: "2-digit" });
+const BLOCK = { 401: "recusou a autorização (401)", 403: "recusou o acesso (403)", 407: "o proxy da rede pediu autenticação (407)", 429: "pediu para diminuir o ritmo (429)" };
+
+// um pedido a um serviço; se ele estiver bloqueado, nem tenta
+export async function callService(service, url, { method = "GET", headers = {}, body, timeoutMs = 15000, cfg = loadMapConfig(mapaFile()) } = {}) {
+  const st = state.get(service);
+  if (st?.status === "bloqueado") throw new ServiceBlocked(service, `${st.motivo}; não tentei de novo`);
+  let res;
+  try {
+    res = await fetch(url, { method, body, headers: { "User-Agent": USER_AGENT, Accept: "application/json", ...headers }, signal: AbortSignal.timeout(timeoutMs) });
+  } catch (e) {
+    const motivo = e.name === "TimeoutError" ? "não respondeu a tempo" : /certificate|self[- ]signed|CERT/i.test(String(e.cause?.message || e.message)) ? "o certificado foi barrado pela rede" : "não foi possível conectar (a rede pode estar bloqueando)";
+    state.set(service, { status: "bloqueado", motivo: `${motivo} às ${hhmm()}`, quando: Date.now() });
+    throw new ServiceBlocked(service, motivo);
+  }
+  if (BLOCK[res.status]) {
+    state.set(service, { status: "bloqueado", motivo: `${BLOCK[res.status]} às ${hhmm()}`, quando: Date.now() });
+    throw new ServiceBlocked(service, BLOCK[res.status]);
+  }
+  if (!res.ok) throw new Error(`${SERVICES[service] || service}: HTTP ${res.status}`);
+  state.set(service, { status: "ok", quando: Date.now() });
+  return res;
+}
+
+// ---------------------------------------------------------------------------------------------- endereço -> ponto
+// Nominatim (padrão) ou outro compatível com /search?format=jsonv2. Um pedido por vez, no ritmo do serviço
+// (porSegundo; o Nominatim público aceita 1). O cache é de quem chama (o projeto guarda o seu).
+export async function geocodeOne(q, { cfg = loadMapConfig(mapaFile()), signal } = {}) {
+  const g = cfg.geocoder;
+  const url = `${g.url.replace(/\/+$/, "")}/search?format=jsonv2&limit=1&addressdetails=0&q=${encodeURIComponent(q)}${g.key ? `&key=${encodeURIComponent(g.key)}` : ""}`;
+  if (signal?.aborted) throw new Error("cancelado");
+  const res = await callService("geocoder", url, { cfg });
+  const list = await res.json();
+  const hit = Array.isArray(list) ? list[0] : null;
+  return hit ? { lat: Number(hit.lat), lon: Number(hit.lon), nome: hit.display_name || "" } : null;
+}
+
+export const geocodeInterval = (cfg = loadMapConfig(mapaFile())) => Math.max(1, Math.ceil(1000 / Math.max(0.1, Number(cfg.geocoder?.porSegundo) || 1)));

package/src/map.js

@@ -0,0 +1,261 @@
+// Slide de mapa (layout: map). A planilha é a fonte, o mapa é a vista: cada camada lê um arquivo do projeto (CSV,
+// GeoJSON, GPX, KML) ou valores por estado/país, e vira GeoJSON com o estilo já decidido (cor por categoria ou por
+// valor, tamanho, rótulo, campos do cartão). Os dados vão dentro do HTML; o mapa ao vivo (src/runtime/map.js) desenha
+// com o Leaflet, e uma prévia em SVG (sem fundo) serve às miniaturas e de reserva.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseCSV } from "./csv.js";
+import { toNum } from "./science.js";
+
+const VENDOR = path.join(path.dirname(fileURLToPath(import.meta.url)), "runtime", "vendor");
+let contornos;
+export const geoContornos = () => (contornos ||= JSON.parse(fs.readFileSync(path.join(VENDOR, "geo-contornos.json"), "utf8")));
+
+// cores das categorias: a paleta do tema (o runtime resolve --s1…), na ordem
+// cores das categorias: a paleta do tema (c1…c5, as mesmas da tabela e dos gráficos), depois destaque e alerta
+export const MAP_COLORS = ["c1", "c2", "c3", "c4", "c5", "em", "hi", "alert"];
+// token de cor -> CSS: hex, paleta do tema (--c-c1… com recuo no destaque), ou variável do tom (s1, em, hi, fg…)
+export const mapColorCSS = (c) => (/^#?[0-9a-f]{6}$/i.test(c) ? `#${String(c).replace("#", "")}` : /^(c\d|accent|alert|ink|paper)$/.test(c) ? `var(--c-${c},var(--em))` : `var(--${c})`);
+const BASEMAPS = ["ruas", "claro", "escuro", "satelite", "nenhum"];
+
+const norm = (s) => String(s ?? "").normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "");
+const LAT = ["lat", "latitude", "y"], LON = ["lon", "lng", "long", "longitude", "x"], COORD = ["coordenadas", "coordenada", "coords", "latlon", "latlong", "posicao", "localizacao"];
+const findCol = (cols, want, names) => {
+  if (want) { const i = cols.findIndex((c) => norm(c) === norm(want)); return i; }
+  return cols.findIndex((c) => names.includes(norm(c)));
+};
+
+// ---------------------------------------------------------------------------------------------- leitura dos arquivos
+function readText(file, ctx, what) {
+  const full = path.resolve(ctx?.baseDir || process.cwd(), String(file).trim());
+  try { return fs.readFileSync(full, "utf8"); }
+  catch { ctx?.warnings?.push(`mapa: ${what} "${file}" não encontrado ao lado do deck`); return null; }
+}
+
+// coordenada não tem separador de milhar: "-46.702" é -46,702 (o leitor de números da planilha leria -46702) e
+// "-23,55" é -23,55 (vírgula decimal)
+export function coordNum(v) {
+  if (typeof v === "number") return v;
+  const s = String(v ?? "").trim().replace(/\s/g, "");
+  return /^[+-]?\d+([.,]\d+)?$/.test(s) ? Number(s.replace(",", ".")) : NaN;
+}
+// "lat, lon" numa coluna só: "-23.55, -46.63", "-23,55; -46,63", "-23.55 -46.63"
+export function splitCoords(v) {
+  const s = String(v ?? "").trim();
+  const parts = s.includes(";") ? s.split(";") : /,\s/.test(s) ? s.split(/,\s+/) : /\s/.test(s) ? s.split(/\s+/) : s.split(",");
+  return parts.length === 2 ? parts.map(coordNum) : [NaN, NaN];
+}
+
+// planilha (CSV) -> pontos. Colunas de posição reconhecidas pelo nome (lat/latitude, lon/longitude) ou indicadas.
+export function pointsFromRows(head, rows, layer = {}, warn = () => {}) {
+  const iLat = findCol(head, layer.lat, LAT), iLon = findCol(head, layer.lon, LON);
+  const iCoord = iLat < 0 || iLon < 0 ? findCol(head, layer.coords, COORD) : -1;
+  if ((iLat < 0 || iLon < 0) && iCoord < 0) {
+    warn(`mapa: a planilha não tem colunas de posição (latitude e longitude); colunas: ${head.join(", ")}`);
+    return { features: [], missing: rows.length };
+  }
+  const features = [];
+  let missing = 0;
+  rows.forEach((r, n) => {
+    if (!r.some((c) => String(c ?? "").trim())) return; // linha vazia não é ponto sem posição
+    let lat, lon;
+    if (iCoord >= 0) [lat, lon] = splitCoords(r[iCoord]);
+    else { lat = coordNum(r[iLat]); lon = coordNum(r[iLon]); }
+    if (!Number.isFinite(lat) || !Number.isFinite(lon) || Math.abs(lat) > 90 || Math.abs(lon) > 180) { missing++; return; }
+    // as colunas de posição não vão para o cartão (a posição já é o ponto no mapa)
+    const props = Object.fromEntries(head.map((h, i) => [h, r[i] ?? ""]).filter(([h], i) => h !== "" && i !== iLat && i !== iLon && i !== iCoord));
+    features.push({ type: "Feature", properties: { ...props, _linha: n + 2 }, geometry: { type: "Point", coordinates: [lon, lat] } });
+  });
+  if (missing) warn(`mapa: ${missing} linha${missing === 1 ? "" : "s"} da planilha sem posição válida ficaram de fora`);
+  return { features, missing };
+}
+
+const attr = (xml, name) => xml.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`))?.[1];
+const tag = (xml, name) => xml.match(new RegExp(`<${name}\\b[^>]*>([\\s\\S]*?)</${name}>`))?.[1]?.replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, "$1").trim();
+const tags = (xml, name) => [...xml.matchAll(new RegExp(`<${name}\\b[^>]*?(?:/>|>([\\s\\S]*?)</${name}>)`, "g"))].map((m) => m[0]);
+
+// GPX: trilhas e rotas viram linhas; pontos marcados (wpt) viram pontos
+export function fromGPX(xml) {
+  const pt = (s) => [Number(attr(s, "lon")), Number(attr(s, "lat"))];
+  const features = [];
+  for (const t of [...tags(xml, "trk"), ...tags(xml, "rte")]) {
+    const segs = tags(t, "trkseg").length ? tags(t, "trkseg").map((s) => tags(s, "trkpt").map(pt)) : [tags(t, "rtept").map(pt)];
+    const lines = segs.filter((l) => l.length > 1);
+    if (!lines.length) continue;
+    features.push({ type: "Feature", properties: { nome: tag(t, "name") || "" }, geometry: lines.length === 1 ? { type: "LineString", coordinates: lines[0] } : { type: "MultiLineString", coordinates: lines } });
+  }
+  for (const w of tags(xml, "wpt")) features.push({ type: "Feature", properties: { nome: tag(w, "name") || "" }, geometry: { type: "Point", coordinates: pt(w) } });
+  return features;
+}
+
+// KML: cada Placemark com nome, descrição e dados (ExtendedData); ponto, linha ou polígono (inclusive MultiGeometry)
+export function fromKML(xml) {
+  const coords = (s) => String(s || "").trim().split(/\s+/).map((c) => c.split(",").slice(0, 2).map(Number)).filter((c) => c.length === 2 && c.every(Number.isFinite));
+  const features = [];
+  for (const pm of tags(xml, "Placemark")) {
+    const props = { nome: tag(pm, "name") || "" };
+    const desc = tag(pm, "description"); if (desc) props.descricao = desc.replace(/<[^>]+>/g, " ").trim();
+    for (const d of tags(pm, "Data")) props[attr(d, "name") || "campo"] = tag(d, "value") || "";
+    for (const d of tags(pm, "SimpleData")) props[attr(d, "name") || "campo"] = d.replace(/<[^>]+>/g, "").trim();
+    const geoms = [
+      ...tags(pm, "Point").map((p) => ({ type: "Point", coordinates: coords(tag(p, "coordinates"))[0] })),
+      ...tags(pm, "LineString").map((l) => ({ type: "LineString", coordinates: coords(tag(l, "coordinates")) })),
+      ...tags(pm, "Polygon").map((p) => ({ type: "Polygon", coordinates: [coords(tag(tag(p, "outerBoundaryIs") || p, "coordinates")), ...tags(p, "innerBoundaryIs").map((b) => coords(tag(b, "coordinates")))] })),
+    ].filter((g) => g.coordinates && (g.type !== "Point" || g.coordinates.length === 2));
+    for (const g of geoms) features.push({ type: "Feature", properties: props, geometry: g });
+  }
+  return features;
+}
+
+function fromGeoJSON(obj) {
+  if (!obj || typeof obj !== "object") return [];
+  if (obj.type === "FeatureCollection") return (obj.features || []).filter((f) => f && f.geometry);
+  if (obj.type === "Feature") return obj.geometry ? [obj] : [];
+  if (obj.type && obj.coordinates) return [{ type: "Feature", properties: {}, geometry: obj }];
+  return [];
+}
+
+// valores por estado (sigla) ou país (código de 2 letras): o contorno embutido, pintado pelo valor
+function fromAreas(values, warn) {
+  const g = geoContornos();
+  const features = [];
+  for (const [k, v] of Object.entries(values || {})) {
+    const code = String(k).trim().toUpperCase();
+    const uf = g.uf[code], pais = g.paises[code];
+    if (!uf && !pais) { warn(`mapa: "${k}" não é uma UF (SP, RJ…) nem um país (BR, PT…)`); continue; }
+    const poly = uf || pais.poly;
+    features.push({ type: "Feature", properties: { nome: uf ? code : pais.nome, valor: v }, geometry: { type: "MultiPolygon", coordinates: poly } });
+  }
+  return features;
+}
+
+// ---------------------------------------------------------------------------------------------- estilo das camadas
+// cor: uma coluna (categoria -> cores da paleta; número -> escala da cor de destaque), uma cor fixa, ou nada
+function styleOf(features, layer, warn) {
+  const style = { color: null, colorBy: null, categories: null, scale: null, sizeBy: null, sizeScale: null, label: layer.label || null, popup: null, icon: layer.icon || null };
+  const props = features.map((f) => f.properties || {});
+  const has = (col) => col && props.some((p) => Object.hasOwn(p, col));
+  const by = layer.color ?? (layer.areas ? "valor" : null);
+  if (by && !has(by)) {
+    if (/^(#?[0-9a-f]{6}|s[1-5]|c\d|em|hi|alert|accent|fg|muted)$/i.test(String(by))) style.color = String(by);
+    else warn(`mapa: a camada "${layer.name || ""}" pinta pela coluna "${by}", que não existe`);
+  } else if (by) {
+    style.colorBy = by;
+    const vals = props.map((p) => p[by]);
+    const nums = vals.map(toNum).filter((n) => n != null);
+    if (nums.length === vals.filter((v) => String(v ?? "").trim() !== "").length && nums.length && !layer.colors) {
+      style.scale = { min: Math.min(...nums), max: Math.max(...nums) };
+    } else {
+      const order = [...new Set(vals.map((v) => String(v ?? "").trim()).filter(Boolean))];
+      const given = layer.colors && typeof layer.colors === "object" ? layer.colors : {};
+      if (order.length > MAP_COLORS.length && !Object.keys(given).length) warn(`mapa: "${by}" tem ${order.length} categorias; as cores se repetem a partir da ${MAP_COLORS.length + 1}ª (agrupe ou dê colors:)`);
+      style.categories = order.map((v, i) => ({ value: v, color: String(given[v] ?? MAP_COLORS[i % MAP_COLORS.length]) }));
+    }
+  }
+  if (layer.size) {
+    if (!has(layer.size)) warn(`mapa: a camada "${layer.name || ""}" usa a coluna "${layer.size}" para o tamanho, que não existe`);
+    else {
+      const nums = props.map((p) => toNum(p[layer.size])).filter((n) => n != null);
+      if (nums.length) { style.sizeBy = layer.size; style.sizeScale = { min: Math.min(...nums), max: Math.max(...nums) }; }
+    }
+  }
+  if (style.label && !has(style.label)) { warn(`mapa: a coluna "${style.label}" do rótulo não existe`); style.label = null; }
+  const cols = [...new Set(props.flatMap((p) => Object.keys(p)))].filter((c) => !c.startsWith("_"));
+  style.popup = Array.isArray(layer.popup) ? layer.popup.filter((c) => cols.includes(c)) : layer.popup === false ? [] : cols.slice(0, 8);
+  return style;
+}
+
+// ---------------------------------------------------------------------------------------------- o slide inteiro
+function bboxOf(layers) {
+  let s = 90, w = 180, n = -90, e = -180, any = false;
+  const visit = (c) => {
+    if (typeof c[0] === "number") { const [lon, lat] = c; if (Number.isFinite(lat) && Number.isFinite(lon)) { any = true; s = Math.min(s, lat); n = Math.max(n, lat); w = Math.min(w, lon); e = Math.max(e, lon); } return; }
+    c.forEach(visit);
+  };
+  for (const l of layers) for (const f of l.data.features) if (f.geometry?.coordinates) visit(f.geometry.coordinates);
+  return any ? [[s, w], [n, e]] : null;
+}
+
+const viewOf = (v) => {
+  if (v === "fit" || v === true) return "fit";
+  if (v && Array.isArray(v.center) && v.center.length === 2 && v.center.every(Number.isFinite)) return { center: v.center, zoom: Number.isFinite(v.zoom) ? v.zoom : 13 };
+  return null;
+};
+
+export function mapModel(s, ctx) {
+  const warn = (m) => ctx?.warnings?.push(m);
+  const list = Array.isArray(s.layers) ? s.layers : s.layers ? [s.layers] : [];
+  const layers = [];
+  list.forEach((layer, i) => {
+    if (!layer || typeof layer !== "object") return;
+    let features = [], kind = "shapes";
+    if (layer.points != null) {
+      kind = "points";
+      if (typeof layer.points === "string") {
+        const text = readText(layer.points, ctx, "planilha");
+        if (text != null) {
+          // sem tirar as linhas vazias: _linha é o número da linha na planilha (a seleção liga linha e ponto)
+          const { rows } = parseCSV(text);
+          features = pointsFromRows((rows[0] || []).map((h) => String(h).trim()), rows.slice(1), layer, warn).features;
+        }
+      } else if (Array.isArray(layer.points)) {
+        const rows = layer.points.filter((p) => p && typeof p === "object");
+        const head = [...new Set(rows.flatMap((p) => Object.keys(p)))];
+        features = pointsFromRows(head, rows.map((p) => head.map((h) => p[h] ?? "")), layer, warn).features;
+      }
+    } else if (layer.geojson) {
+      const text = readText(layer.geojson, ctx, "GeoJSON");
+      try { features = text == null ? [] : fromGeoJSON(JSON.parse(text)); } catch { warn(`mapa: "${layer.geojson}" não é um GeoJSON válido`); }
+    } else if (layer.gpx) {
+      const text = readText(layer.gpx, ctx, "GPX"); features = text == null ? [] : fromGPX(text);
+    } else if (layer.kml) {
+      const text = readText(layer.kml, ctx, "KML"); features = text == null ? [] : fromKML(text);
+    } else if (layer.areas) {
+      kind = "areas"; features = fromAreas(layer.areas, warn);
+    } else { warn(`mapa: a camada ${i + 1} não diz de onde vêm os dados (points, geojson, gpx, kml ou areas)`); return; }
+    if (!features.length && layer.areas == null) warn(`mapa: a camada "${layer.name || i + 1}" ficou vazia`);
+    const step = layer.step ?? (s.build ? i + 1 : undefined);
+    layers.push({
+      name: layer.name || layer.title || `Camada ${i + 1}`, kind,
+      source: typeof layer.points === "string" ? layer.points.trim() : layer.geojson || layer.gpx || layer.kml || null, step: Number.isFinite(Number(step)) ? Number(step) : undefined,
+      view: viewOf(layer.view), legend: layer.legend || null, prefix: layer.prefix || "", suffix: layer.suffix || "",
+      style: styleOf(features, layer, warn), data: { type: "FeatureCollection", features },
+    });
+  });
+  const basemap = BASEMAPS.includes(s.basemap) ? s.basemap : "ruas";
+  if (s.basemap && !BASEMAPS.includes(s.basemap)) warn(`mapa: fundo "${s.basemap}" não existe (use ${BASEMAPS.join(", ")})`);
+  return { basemap, view: viewOf(s.view), bounds: bboxOf(layers), layers, tiles: ctx?.mapTiles || null };
+}
+
+// ---------------------------------------------------------------------------------------------- prévia sem fundo
+// SVG das camadas em Web Mercator, enquadradas: miniaturas do Studio (sem pedir tile nenhum) e reserva se o mapa ao
+// vivo não montar
+const merc = ([lon, lat]) => { const y = Math.log(Math.tan(Math.PI / 4 + (Math.max(-85, Math.min(85, lat)) * Math.PI) / 360)); return [lon / 360, -y / (2 * Math.PI)]; };
+export function mapPreviewSVG(model, w = 1600, h = 760) {
+  if (!model.bounds) return `<svg class="map-preview" viewBox="0 0 ${w} ${h}" aria-hidden="true"></svg>`;
+  const [[s, wst], [n, e]] = model.bounds;
+  const [x0, y1] = merc([wst, s]), [x1, y0] = merc([e, n]);
+  const pad = 0.08, bw = Math.max(x1 - x0, 1e-6), bh = Math.max(y1 - y0, 1e-6);
+  const k = Math.min(w / (bw * (1 + 2 * pad)), h / (bh * (1 + 2 * pad)));
+  const ox = w / 2 - ((x0 + x1) / 2) * k, oy = h / 2 - ((y0 + y1) / 2) * k;
+  const P = (c) => { const [x, y] = merc(c); return `${(x * k + ox).toFixed(1)},${(y * k + oy).toFixed(1)}`; };
+  const out = [];
+  const color = (layer, f) => {
+    const st = layer.style, v = st.colorBy ? f.properties?.[st.colorBy] : null;
+    const cat = st.categories?.find((c) => c.value === String(v ?? "").trim());
+    return mapColorCSS(cat?.color || st.color || "c1");
+  };
+  for (const layer of model.layers) for (const f of layer.data.features) {
+    const g = f.geometry, col = color(layer, f);
+    const lines = (cs) => cs.map((l) => `M${l.map(P).join("L")}`).join("");
+    if (g.type === "Point") { const [x, y] = P(g.coordinates).split(","); out.push(`<circle cx="${x}" cy="${y}" r="9" fill="${col}" stroke="var(--bg)" stroke-width="3"/>`); }
+    else if (g.type === "LineString") out.push(`<path d="${lines([g.coordinates])}" fill="none" stroke="${col}" stroke-width="5"/>`);
+    else if (g.type === "MultiLineString") out.push(`<path d="${lines(g.coordinates)}" fill="none" stroke="${col}" stroke-width="5"/>`);
+    else if (g.type === "Polygon") out.push(`<path d="${lines(g.coordinates)}Z" fill="${col}" fill-opacity=".35" stroke="${col}" stroke-width="2"/>`);
+    else if (g.type === "MultiPolygon") out.push(`<path d="${g.coordinates.map((p) => lines(p) + "Z").join("")}" fill="${col}" fill-opacity=".35" stroke="${col}" stroke-width="2"/>`);
+  }
+  return `<svg class="map-preview" viewBox="0 0 ${w} ${h}" preserveAspectRatio="xMidYMid meet" aria-hidden="true">${out.join("")}</svg>`;
+}
+
+export const mapSummary = (model) => model.layers.map((l) => `${l.name}: ${l.data.features.length}`).join(" · ");

package/src/mcp/server.js

@@ -91,8 +91,8 @@ const TOOLS = [
         },
         type: {
           type: "string",
-          enum: ["keynote", "pitch", "palestra"],
-          description: "Tipo narrativo do esqueleto (padrão: keynote)",
+          enum: ["lancamento", "pitch", "palestra"],
+          description: "Tipo narrativo do esqueleto (padrão: lancamento)",
         },
         author: { type: "string", description: "Nome do autor ou palestrante" },
       },
@@ -110,7 +110,7 @@ const TOOLS = [
         theme: {
           type: "string",
           enum: ["sinal", "prata", "rabisco", "oceano", "pop", "aurora", "editorial", "noite", "bauhaus", "terminal", "jornal"],
-          description: "Tema visual do Sagadeck (ex.: prata para Apple Keynote, rabisco para artesanal, oceano para azul elétrico)",
+          description: "Tema visual do Sagadeck (ex.: prata para limpo e espaçoso, rabisco para artesanal, oceano para azul elétrico)",
         },
         author: { type: "string", description: "Nome do autor ou palestrante" },
       },
@@ -307,7 +307,7 @@ async function handleToolCall(name, args) {
       const spec = generateScaffold({
         title: args.title || "Nova Apresentação",
         theme: args.theme || "prata",
-        type: args.type || "keynote",
+        type: args.type || "lancamento",
         author: args.author || "Seu Nome",
       });
       fs.mkdirSync(path.dirname(targetPath), { recursive: true });