sagadeck 1.7.1 → 1.8.0

package/README.md

@@ -150,6 +150,46 @@ ilustrar" e `--no-images` proíbe. Imagens só são geradas para os slides que a
 
 Todo YAML vindo do LLM é validado (renderiza cada slide); se falhar, o erro volta para o LLM corrigir (até 3 tentativas). Decks gerados passam por uma rodada de enxugamento quando o fiscal anti-sono reclamaria.
 
+## Mapa (opcional)
+
+O slide de mapa (`layout: map`) mostra pontos, linhas e áreas sobre um mapa ao vivo: sensores, medidores, unidades de
+atendimento, cinemas, trajetos, bairros, o que for. Os dados vêm de uma planilha do projeto (CSV com latitude e
+longitude, ou só com o endereço) ou de arquivos GeoJSON, GPX e KML. **Nada aqui é obrigatório**: quem não usa mapa
+não precisa configurar coisa nenhuma, e o sagadeck não pede nada à internet por causa dele.
+
+**Sem chave nenhuma, já funciona** com os serviços públicos gratuitos do OpenStreetMap:
+
+| serviço | para quê | padrão (sem configurar) |
+|---|---|---|
+| mapa de fundo | as ruas por baixo das camadas | OpenStreetMap |
+| endereço e coordenada | **Achar coordenadas** de uma planilha só com endereço | Nominatim (1 endereço por segundo) |
+| busca de lugares | achar cinemas, escolas, unidades de saúde… pelo nome do tipo | Overpass |
+| rotas | "seguir as ruas" ao desenhar, distância e tempo | OSRM (servidor de demonstração) |
+
+**Chave opcional: OpenRouteService**, para rotas a pé, de carro e de bicicleta e para a **área alcançável em X
+minutos**. É gratuita:
+1. Crie a conta em [openrouteservice.org](https://openrouteservice.org) e confirme o e-mail.
+2. No painel, gere um token do plano gratuito (Standard).
+3. No Studio, **Configurar mapa** (no alto da biblioteca, ou no formulário do slide de mapa) › Rotas › **Usar o
+   OpenRouteService**, cole a chave e clique em **Testar**.
+
+A configuração fica só nesta máquina, em `~/.sagadeck/mapa.json` (como a da IA); a chave nunca volta inteira para a
+página e nunca vai para dentro da apresentação. Também vale pôr a chave numa variável de ambiente e indicar o nome dela
+em `keyEnv` (no servidor, por exemplo):
+
+```json
+{ "rotas": { "provedor": "openrouteservice", "url": "https://api.openrouteservice.org", "keyEnv": "OPENROUTESERVICE_API_KEY" } }
+```
+
+Os serviços públicos têm regras de uso que o sagadeck respeita sozinho: identifica cada pedido, mostra a atribuição
+"© colaboradores do OpenStreetMap", busca um endereço por segundo, guarda o que já achou e nunca baixa mapa fora da
+tela. Eles são para uso leve e não comercial; no trabalho, prefira o servidor de mapas da empresa ou um provedor com
+chave (os endereços se trocam em **Configurar mapa**). Antes de mandar os endereços de uma planilha sua para um
+serviço de fora, o sagadeck pergunta.
+
+Se a rede barrar um serviço (autorização negada, proxy, bloqueio), o sagadeck faz **uma tentativa e para**: avisa
+na tela, as camadas continuam desenhadas e nada é tentado de novo até você clicar em **Tentar de novo**.
+
 ## Desenvolvimento
 
 ```bash

package/docs/ANDAMENTO.md

@@ -42,6 +42,128 @@ datadas abaixo). O resto fica para depois e só entra se for pedido. Antes de co
    ler o conteúdo força o download. Conferir se listar a biblioteca (`openLibrary`, `/api/library`) lê o YAML de
    cada deck; se lê, listar só pelo nome/metadado e abrir o conteúdo sob demanda.
 
+## Frente: mapa (planejada em 10/10/2026, em andamento)
+
+Pedido de Narumi, depois de muita conversa. **Leia antes de mexer.** Recurso de nicho, mas completo: mostrar e
+explicar algo geográfico (pontos de interesse de qualquer tipo, linhas, áreas), com a IA montando a partir de dados.
+Não é um QGIS: análise pesada fica lá; aqui é apresentar bem, com contas simples feitas pelo código.
+
+**Decisões (não reabrir):**
+- **Internet não é limitação.** Recurso online é bem-vindo e fica disponível onde funciona; onde não funciona, some ou
+  avisa. Nada de "assar/chapar" o mapa de fundo no deck (ela odiou): mapa **ao vivo** (Leaflet, embutido no pacote).
+- **Nada bancário nem de setor nenhum**: pontos de interesse genéricos (sensor, hidrômetro, placa solar, cinema,
+  órgão público…). Exemplos, REFERENCIA e testes com casos variados.
+- **A planilha é a fonte, o mapa é a vista**: pontos em CSV do projeto (`contexto/*.csv`, importa XLSX); linhas e
+  polígonos em GeoJSON do projeto (importa GPX/KML). O slide diz qual arquivo e quais colunas (posição, cor, tamanho,
+  rótulo). A mesma planilha serve tabela e gráfico.
+- **Carregamento preguiçoso** em quatro níveis: o Leaflet só entra no HTML de deck com mapa; o mapa só liga (e só pede
+  tiles) quando o slide aparece; o editor de mapa no Studio vem por import dinâmico; os módulos de serviço no servidor
+  só no primeiro pedido. Teste para os três primeiros.
+- **Uma tentativa e para**: erro de autorização ou bloqueio (401, 403, 407, recusa, certificado, até 429) marca o
+  serviço indisponível na sessão; só volta com "Tentar de novo" ou reabrindo o Studio. Tiles: se os primeiros falham
+  sem nenhum sucesso, a camada de fundo desliga e aparece aviso (camadas continuam). **Sem teste proativo** de
+  serviço: o primeiro uso real é o teste. Teste: serviço com 403 recebe exatamente um pedido.
+- **Pedidos saem do navegador no Studio local** (mesmo caminho/proxy do Google Maps, que abre na rede do trabalho; o
+  Node não usa o proxy do sistema). No multiusuário, do servidor (a chave não vai para a página dos outros).
+- **Serviços padrão gratuitos**, todos configuráveis em **Configurar mapa** (`~/.sagadeck/mapa.json`, como o ia.json):
+  tiles do OpenStreetMap, Nominatim (endereço↔coordenada), Overpass (busca de lugares/linhas/áreas), OSRM
+  (rotas, encaixe de GPS) e OpenRouteService (rotas e isócronas; chave da Narumi já está no mapa.json desta máquina,
+  nunca no repositório). Respeitar as políticas: atribuição visível "© colaboradores do OpenStreetMap", identificação
+  do sagadeck, Nominatim 1/s e cache obrigatório (lote grande: avisar e sugerir provedor com chave), nada de baixar
+  tiles fora da tela. Públicos de OSRM/Overpass são não comerciais: para uso no trabalho, servidor da empresa ou chave.
+- **A IA**: recebe no prompt o estado de cada serviço (funcionando, não usado, bloqueado) e decide; o código recusa
+  sem pedido de rede o que está bloqueado. Pergunta antes de mandar **dados da pessoa** a serviço de fora (primeira vez
+  por planilha) e antes de lote grande (tempo estimado). Geometria nunca inventada: vem de dados, do OSM ou do cálculo.
+  Testes: mock (encanamento) e ao vivo (decisão).
+- PDF/PPTX capturam o mapa como está na tela na exportação; camada por clique vira animação no PPTX.
+
+**Entregas (uma branch/PR cada, com testes e CI verde):**
+1. **Feita (10/10).** Slide `map`: motor `src/map.js` (CSV com colunas de posição achadas pelo nome, GeoJSON, GPX,
+   KML, `areas` por UF/país com os contornos embutidos `src/runtime/vendor/geo-contornos.json`; cor por categoria
+   na paleta do tema `c1…c5` ou escala por número, tamanho, rótulo, cartão; prévia SVG para miniaturas), mapa ao vivo
+   `src/runtime/map.js` (Leaflet 1.9.4 embutido por `scripts/vendor-map.mjs`, só em deck com mapa; monta só no slide
+   atual; testa **um** tile antes de ligar o fundo e, se falhar, nenhum outro mapa da sessão tenta; legenda que liga e
+   desliga; camada por clique com marcadores `data-step` e câmera por camada), configuração da máquina
+   `src/map-config.js` (`~/.sagadeck/mapa.json`; só o fundo vai para o deck), exportação abrindo o deck com mapa por
+   endereço local (Referer) e esperando o mapa de cada slide (`settleSlide`), formulário `map-fields.js`, REFERENCIA,
+   exemplo de layout (entra no Conheça o SagaDeck). Testes: `test/map.test.js` (motor, apresentação com servidor de
+   tiles falso, 403 recebe exatamente um pedido, exportação) e `studio.test.js` (inserir mapa, monta, trocar fundo
+   salva). Achados no caminho: coordenada "-46.702" lida como milhar pelo leitor de números (agora `coordNum`); a
+   classe `widget` na caixa fazia o runtime trocar o conteúdo; rota do `map.js` com cache servia código velho.
+   Pendente para depois: geocodificar `at: "Recife"` (entrega 2) e contornos de reserva quando o fundo falha.
+2. **Feita (10/10).** A tela de dados é a planilha da aba Arquivos (`sheetGrid`, já editável e colando do Excel),
+   com as ferramentas de mapa (`src/studio/public/map-data.js`): **Pôr no mapa** (adivinha cor pela coluna de
+   categorias que se repetem e rótulo pela de nome; `.xlsx` ganha um CSV ao lado), **Achar coordenadas** (pergunta o
+   plano antes e mostra quantos endereços, para qual serviço e quanto tempo; só envia com o sim; progresso; o que não
+   achou fica listado; cache em `.sagadeck/geocodificacao.json`, consentimento em `.sagadeck/mapa-consentimento.json`)
+   e a **seleção ligada** (clicar no ponto seleciona a linha; selecionar a linha abre o cartão). Servidor:
+   `src/map-services.js` (pedidos identificados `sagadeck/versão`, uma tentativa e para, estado de cada serviço) e
+   `src/studio/geo-routes.js` (`/api/mapa`, `/api/mapa/tentar`, `/api/mapa/geocode` em ndjson). Tela **Configurar
+   mapa** (`map-settings.js`, botão no formulário do mapa). Decisão: a busca de endereço sai do servidor do Studio
+   (a política do Nominatim pede identificação, que o navegador não deixa mudar); os tiles saem do navegador.
+   Testes: `test/map-data.test.js`. Fica para depois: abrir GeoJSON como tabela.
+3. **Feita (10/10).** Editor `src/studio/public/map-editor.js`, carregado só no clique em **Editar no mapa** (botão e
+   barra no `#canvas-viewport`, fora do slide escalado): Mover (arrastar ponto atualiza a linha da planilha; clicar
+   numa linha/área abre os vértices: arrastar, apagar, dividir; juntar linhas pelas pontas mais próximas), Ponto
+   (linha nova na planilha da camada, endereço pelo `/reverse`), Linha e Área (GeoJSON da camada ou
+   `contexto/desenhos.geojson`; "Seguir as ruas" a pé/carro/bicicleta pelo `/api/mapa/rota`), Régua, Usar esta vista
+   (grava `view` no slide); comprimento e área ao vivo. O Studio guarda a vista entre redesenhos (`keepView`). Rotas,
+   endereço de um ponto e área alcançável em `src/map-routing.js` (OpenRouteService com chave, testado ao vivo com a
+   chave da Narumi: 817 m a pé, isócrona de 5 min; ou OSRM). Chave do mapa como a da IA: tela Configurar mapa com
+   "Usar o OpenRouteService" e Testar, botão na biblioteca, `keyEnv` (variável de ambiente, para o servidor). README
+   com a seção "Mapa (opcional)". Achados: o editor visual capturava o clique no mapa (agora ignora `.map-live`); o
+   projeto não gravava `.geojson/.gpx/.kml` como texto. Testes: `test/map-editor.test.js` e `map-data.test.js`.
+   Retomada: PR #178 mergeado após CI verde no Ubuntu e no Windows. A corrida do arrastar passou; a falha restante era
+   uma releitura ao clicar na aba de planilha já ativa, que substituía a grade e apagava a seleção feita pelo mapa.
+   O clique agora mantém a aba ativa. Regressão com resposta atrasada reproduziu a falha antes da correção e passou
+   depois; mapa/planilha e editor: 6 testes passando. Suíte completa: 950 passaram, 22 pulados, zero falhas.
+4. **Feita (10/10).** A IA que edita o deck pede dados com um bloco `mapa:` (como o `ver:` do material; nenhuma
+   chamada a mais quando o pedido não é de mapa): `lugares` e `linhas` (Overpass, com o filtro de tags que ela
+   escolhe e o centro achado no Nominatim), `contorno` (Nominatim com polígono), `web` (a pesquisa existente + uma
+   extração que só usa o que leu, com a URL de cada linha; as coordenadas vêm depois) e `coordenadas` (planilha da
+   pessoa; sem `confirmado: true`, o código pergunta "Posso enviar?" com opções e não envia nada). O Studio executa
+   (`src/ai/map-data.js`), grava em `contexto/` com a coluna `fonte` e chama a IA de novo (até 2 rodadas). O prompt
+   (`mapDataPrompt`) leva o estado de cada serviço; bloqueado não recebe pedido e a IA fica sabendo. Testes:
+   `test/map-ai.test.js` (encanamento, LLM falso) e 3 ao vivo em `test/ai-live.test.js` (pede `amenity=cinema` perto
+   de Campinas; não se dá o sim sozinha; com a busca bloqueada, não pede e oferece alternativa), todos passando com o
+   modelo de verdade. Conferido com o OpenStreetMap real: 5 cinemas num raio de 8 km do centro de Campinas (o
+   Overpass público às vezes responde 504 por sobrecarga; o sagadeck registra e não insiste).
+5. **Feita (10/10), no mesmo PR da 4.** Contas puras em `src/map-analysis.js` (haversine, mais próximo, raio, ponto em
+   polígono com buraco, distância a linha, círculo, faixa em volta de linha para desenhar, "onde instalar" por grade e
+   escolha gulosa) e as ações do bloco `mapa:` em `src/ai/map-analysis-run.js`: `mais_proximo` (CSV com
+   `mais_proximo` e `distancia_m`), `contar` (por área ou raio, grava o círculo), `faixa` (GeoJSON da faixa e quantos
+   pontos dentro, pela distância exata à linha), `sugerir` (CSV de sugestões, avisando que é geométrico), `rota`
+   (distância e tempo), `alcance` (isócronas, só com OpenRouteService) e `encaixar` (OSRM `/match`, amostrando até 100
+   pontos). A IA só narra os números. Achado: pontos todos alinhados deixavam o "onde instalar" sem resposta (retângulo
+   de altura zero). Testes: `test/map-analysis.test.js` e o ao vivo "qual loja fica mais perto de cada pedido" (pede
+   `mais_proximo`).
+
+**Publicação 1.8.0 (retomada em 10/10):** versão preparada em `package.json` e lockfile, incluindo as cinco entregas
+e o Conheça o SagaDeck. O #178 já foi mergeado; falta concluir a CI e mergear o #179, conferir a CI da `main`, criar a
+release e atualizar a instalação local e o Oracle. No Oracle, o ambiente e os dois `mapa.json` já estão preparados
+com `OPENROUTESERVICE_API_KEY` (modo 600, dono de cada serviço); os serviços aguardam o código da release para
+reiniciar. Os quatro testes de mapa com o modelo real passaram novamente. Suíte completa da 1.8.0: 982 testes,
+956 passaram, 26 pulados, zero falhas; mapa/editor/exportação/leitores e regras: 22 testes direcionados passaram.
+Na revisão com cliques reais, a planilha cobria o mapa inteiro e a legenda interceptava um ponto no enquadramento
+automático. Corrigidos: a planilha fica ao lado do mapa (sugestões de gráfico recolhidas, com botão para abrir), a
+seleção funciona nas duas direções e o enquadramento reserva espaço para a legenda. O teste reproduziu a obstrução
+antes da correção e agora clica no ponto e na célula, sem disparar eventos sintéticos.
+
+## Conheça o SagaDeck — 10/10/2026
+
+Pergunta de Narumi: a pessoa nem sabe o que dá para gerar. Agora a biblioteca tem, na lateral, **Conheça o
+SagaDeck** (também na vitrine, em Recursos do SagaDeck): uma apresentação com um slide por recurso, agrupada em
+seções, que abre em prévia (nada é gravado; "Usar como base" cria a cópia em Modelos).
+
+- `src/studio/tour.js` monta-se sozinha dos exemplos de layout (`LAYOUT_SAMPLES`): layout novo entra sem ninguém
+  lembrar; layout fora dos grupos cai em "Mais recursos". Fecha com o que não é layout (criar e conversar com a IA,
+  leitura crítica, importar PowerPoint, gráfico da planilha, temas, apresentador, PDF/PowerPoint, link).
+- Cada slide traz nas **notas** (visíveis abaixo do slide no Studio e na visão do apresentador) o nome, a descrição e
+  a frase para pedir à IA (`LAYOUT_ASK` em `layout-samples.js`, exemplos de áreas variadas); no rodapé (`source`)
+  também, nos layouts que o desenham. Os links de navegação dos exemplos saem (apontariam para slides inexistentes).
+- Testes: `engine.test.js` (todo layout tem pedido e aparece no tour, com nome e pedido; renderiza) e
+  `library-ui.test.js` (a lateral abre em prévia e nada é criado na biblioteca).
+
 ## Sem citar o programa de apresentações da maçã (1.7.1) — 10/10/2026
 
 Pedido de Narumi: o código e a documentação não citam o programa de apresentações da maçã, a empresa nem os

package/docs/REFERENCIA.md

@@ -96,6 +96,7 @@ Tabela em markdown no meio de um texto (`problem`, `body`, `text`, passo do `sol
 | `timeline` | `title, events: [{when, title, text, tag}], highlight, after, build` | linha do tempo |
 | `chart` | `title, chart: {…}, side (texto ou elemento), chartHeight` | gráfico + comentário |
 | `table` | `title, head, rows, style, color, highlight, total, side, caption, source` | tabela de verdade nas cores do tema |
+| `map` | `kicker, title, basemap, layers: [{name, points \| geojson \| gpx \| kml \| areas, color, size, label, colors, popup, step, view}], build, view, caption` | **mapa ao vivo** com pontos, linhas e áreas (sensores, medidores, unidades de atendimento, cinemas, trajetos, regiões…): os dados vêm da planilha do projeto ou de arquivos GeoJSON/GPX/KML; ver [Mapa](#mapa-map) |
 | `compare` | `title, left: {label, value, title, text, items, figure, hl}, right: {…}, vs, after, build` | A × B |
 | `matrix` | `title, x: [esq, dir], y: [cima, baixo], cells: [4 × {title, text, example, hl}], build` | matriz 2×2 |
 | `question` | `question, options: [texto ou {key, text, sub}], keys, cols, timer, hint, optionSize` | pergunta para a plateia (com timer) |
@@ -665,6 +666,63 @@ Como o slide mestre do PowerPoint: `master:` no deck desenha em todo slide o que
 
 Quando melhorar ou reescrever uma apresentação que já existia (principalmente uma importada), marque cada slide que mudou para a pessoa validar: `review: { status: alterado, note: "o que mudou, em uma frase", original: 7 }` (`original` = o número do slide no original) ou `review: { status: novo, note: "por que entrou" }` para slide que não existia. O Studio mostra um selo na miniatura, uma faixa no slide com **Ver original**, **Aceitar** e **Desfazer** (volta ao slide de `original/original.yaml`; slide novo sai) e a lista em Revisar › **Mudanças**. A transformação da apresentação inteira ainda usa dois estados: `pendente` (a proposta ficou ao lado do original porque faltava algo dele; aceitar tira o original, desfazer tira a proposta) e `revisar` (a conferência pela foto achou um problema de desenho). A apresentação e a exportação não mostram as marcas. Nunca apague dados do original: números, nomes, fórmulas, fontes e figuras específicas (um mapa, um experimento de uma cidade) continuam, só mais claros.
 
+## Mapa (`map`)
+
+Mapa ao vivo (ruas por baixo, arrastável e com zoom ao apresentar) com **camadas** por cima. A planilha é a fonte e o
+mapa é a vista: os pontos vêm de um CSV do projeto (normalmente em `contexto/`), e as linhas e áreas de GeoJSON, GPX
+(rastro de GPS) ou KML. Serve para qualquer ponto de interesse (sensor, medidor, placa solar, unidade de atendimento,
+escola, cinema…) e qualquer traçado ou área (rede, trajeto, bairro, área de obra).
+
+```yaml
+- layout: map
+  kicker: Monitoramento
+  title: Onde estão os ==sensores==
+  basemap: claro                 # ruas (padrão) | claro | escuro | satelite (se configurado) | nenhum
+  build: true                    # uma camada por clique
+  layers:
+    - name: Sensores             # nome na legenda
+      points: contexto/sensores.csv   # colunas de latitude e longitude achadas pelo nome (lat/latitude, lon/longitude)
+      color: status              # coluna: categoria vira cor (legenda clicável); número vira escala
+      colors: { ativo: s3, sem sinal: alert }   # cor de cada categoria (opcional)
+      size: vazao                # coluna numérica vira o tamanho do ponto (opcional)
+      label: nome                # rótulo fixo ao lado de cada ponto (até 60 pontos)
+      popup: [nome, status, vazao]   # campos do cartão ao clicar (padrão: as primeiras colunas)
+    - name: Rede de água
+      geojson: contexto/rede.geojson  # linhas e polígonos; ou gpx: / kml:
+      color: material
+      view: fit                  # quando a camada aparece, a câmera enquadra ela
+    - name: Consumo por estado
+      areas: { SP: 320, RJ: 140, MG: 150 }   # siglas de UF ou códigos de país (BR, PT…): pinta pela escala
+      legend: mil m³
+```
+
+- `points:` também aceita a lista no próprio slide: `[{ nome: Centro, lat: -23.55, lon: -46.63, status: ativo }]`.
+  Uma coluna só com "lat, lon" vale (`coordenadas`, `posicao`). Use ponto ou vírgula decimal; nunca invente
+  coordenadas: elas vêm da planilha, do arquivo ou de uma busca. Linha sem posição válida fica de fora (o fiscal avisa).
+- `color:` aceita também uma cor fixa (`s1`, `em`, `hi`, `alert`, `#1F6FB2`). `step` (número) diz em que clique a
+  camada aparece; `view` da camada (`fit` ou `{ center: [lat, lon], zoom }`) leva a câmera até ela nesse clique.
+- `view:` do slide fixa o enquadramento (`{ center: [-23.55, -46.63], zoom: 13 }`); sem ele, o mapa enquadra os dados.
+- Planilha só com endereço (sem latitude e longitude): no Studio, a planilha aberta (aba Arquivos) tem **Achar
+  coordenadas**, que pergunta antes de mandar os endereços para o serviço de fora e grava as colunas `latitude` e
+  `longitude`; **Pôr no mapa** cria o slide a partir dela. Sugira esses botões em vez de inventar coordenadas.
+  Com um slide de mapa selecionado, a planilha fica ao lado dele: clicar num ponto seleciona a linha e selecionar
+  uma linha abre o cartão do ponto. O enquadramento automático deixa os pontos livres da legenda.
+- **Editar no mapa** (botão na prévia do slide, no Studio): a pessoa clica para criar pontos (vão para a planilha da
+  camada, com o endereço preenchido), desenha linhas e áreas (vão para o GeoJSON da camada; "Seguir as ruas" liga os
+  cliques pelo serviço de rotas), arrasta pontos e vértices, divide e junta linhas, mede com a régua e grava o
+  enquadramento ("Usar esta vista"). Quando a pessoa quiser marcar algo à mão no mapa, indique esse botão.
+- **Dados de fora** (lugares de um tipo, linhas como ciclovias, o contorno de um lugar com nome, uma lista da web,
+  coordenadas da planilha da pessoa): peça com o bloco `mapa:` (as regras vêm no prompt); o Studio busca, grava os
+  arquivos em `contexto/` com a fonte de cada linha e te devolve o que gravou. Nunca invente coordenada nem contorno.
+- **Análises** (o mais próximo e a distância, quantos num raio ou numa área, faixa em volta de uma linha, onde
+  instalar o próximo, rota com tempo, área alcançável em X minutos, rastro de GPS encaixado nas ruas): também pelo
+  bloco `mapa:`; o Studio calcula e devolve os números. Nunca calcule distância, contagem ou tempo de cabeça.
+- Serviços (Configurar mapa, opcional): sem chave, tudo funciona com os serviços públicos do OpenStreetMap; a chave
+  gratuita do OpenRouteService só acrescenta rotas a pé/de carro/de bicicleta confiáveis e área alcançável.
+- Ao apresentar: clicar num ponto, linha ou área abre o cartão com os dados; clicar na legenda liga e desliga uma
+  categoria ou a camada inteira. O fundo vem da internet; sem rede, aparece um aviso e as camadas continuam. No PDF e
+  no PowerPoint o mapa sai como estava na tela.
+
 ## Tabelas (`table`)
 
 Tabela é tabela, nunca imagem: dados de um livro ou de um PowerPoint que vieram como figura viram `table` quando os valores estão legíveis (o sagadeck alinha os números à direita, com algarismos de mesma largura, e pinta nas cores do tema). Layout `table` (o slide inteiro) ou o elemento `{ table: {…} }` em qualquer lugar (`content`, `add`, `canvas`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sagadeck",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Gerador de apresentações: YAML -> HTML animado + PowerPoint editável, com temas e figuras geradas na hora.",
   "type": "module",
   "bin": {
@@ -33,6 +33,7 @@
     "@material-symbols/svg-400": "^0.47.5",
     "esbuild": "^0.28.2",
     "jsqr": "^1.4.0",
+    "leaflet": "1.9.4",
     "mermaid": "^11.17.2"
   },
   "scripts": {

package/src/ai/deck-ai.js

@@ -782,7 +782,7 @@ export function applyPatch(base, patch) {
 const STUDIO_KEYS = ["layout", "notes", "time", "id", "uid", "review", "original", "master", "visualEdits", "auto", "fiscalOk", "from", "image_prompt", "image_ref", "density", "deco", "theme", "palette", "tone",
   "bg", "fg", "background", "backgroundStyle", "footer", "header", "transition", "steps", "markStyle", "maxWords", "fit", "titleAs", "context"];
 const FREE_TEXT_KEYS = new Set(["code", "mermaid", "svg", "html", "request", "realtime", "body", "headers", "response", "notes", "consulta", "output", "json"]);
-const PATCH_WORDS = new Set(["slides", "insert", "delete", "edit", "deck", "variants", "test", "ver"]);
+const PATCH_WORDS = new Set(["slides", "insert", "delete", "edit", "deck", "variants", "test", "ver", "mapa"]);
 let knownKeysCache = null;
 function knownSlideKeys() {
   if (knownKeysCache) return knownKeysCache;
@@ -925,6 +925,13 @@ function parseEditText(text, base) {
   const raw = parseYaml(yaml);
   if (!raw || typeof raw !== "object") throw new Error("O bloco yaml precisa ser um objeto com deck/slides/insert/delete (ou variants).");
   if (raw.variants) return parseVariants(raw.variants, base, prose);
+  // mapa: [ações] → a IA precisa de dados geográficos (lugares, linhas, contornos, web, coordenadas); quem busca é o
+  // Studio (src/ai/map-data.js), que chama de novo com o que gravou
+  if (raw.mapa) {
+    const acoes = [].concat(raw.mapa?.acoes || raw.mapa).filter((a) => a && typeof a === "object" && a.tipo);
+    if (!acoes.length) throw new Error("mapa: mande a lista de ações (tipo: lugares | linhas | contorno | web | coordenadas).");
+    return { spec: base, prose, changed: [], geo: acoes.slice(0, 4) };
+  }
   // ver: [arquivos] → a IA quer OLHAR o material (recorte, página inteira) antes de responder; quem mostra é o Studio
   if (raw.ver || raw.look) {
     const files = [].concat(raw.ver || raw.look).map((f) => String(f || "").trim()).filter(Boolean);
@@ -974,7 +981,7 @@ function commandEnvNames(apiContext) {
 
 // Chat lateral do Studio: aplica um pedido em linguagem natural ao deck.
 export async function editDeck({ spec, instruction, targetSlide = null, issues = [], images = false, imageOptions = {}, history = [], onProgress,
-  visuals = [], renderNotes = [], apiContext = null, drawCheck = null, runCommand = null, materials = [], deferImages = false, maxImages, styles = null, signal, reviewCheck = null, reviewDepth = 0, repairSlides = null }) {
+  visuals = [], renderNotes = [], apiContext = null, drawCheck = null, runCommand = null, materials = [], deferImages = false, maxImages, styles = null, signal, reviewCheck = null, reviewDepth = 0, repairSlides = null, mapData = null }) {
   const deck = promptSpec(spec);
   const { slides: _slides, ...numbered } = deck;
   const slidesYaml = deck.slides.map((s, i) => `# ── slide ${i + 1} ──\n${YAML.stringify([s], { indent: 2 })}`).join("");
@@ -1012,7 +1019,7 @@ Antes de responder, verifique (e siga as Regras de edição):
     : text;
   const convo = conversationFor(history);
   const messages = [
-    { role: "system", content: `${systemPrompt({ images, ...(maxImages ? { maxImages } : {}) })}\n\n${AUTOMATION_NOTES}\n\n${EDIT_RULES}\n\n${CONVERSATION_RULES}\n\n${PATCH_FORMAT}\n\n${VARIANTS_FORMAT}\n\n${API_RULES}\n\n${runCommand ? runCommand.description || `${COMMAND_RULES}\n${VIDEO_COMMAND_RULES}${commandEnvNames(apiContext)}` : "Comandos: indisponíveis aqui (só no Studio local, com a apresentação salva na biblioteca). Não peça run:."}` },
+    { role: "system", content: `${systemPrompt({ images, ...(maxImages ? { maxImages } : {}) })}\n\n${AUTOMATION_NOTES}\n\n${EDIT_RULES}\n\n${CONVERSATION_RULES}\n\n${PATCH_FORMAT}\n\n${VARIANTS_FORMAT}\n\n${API_RULES}\n\n${runCommand ? runCommand.description || `${COMMAND_RULES}\n${VIDEO_COMMAND_RULES}${commandEnvNames(apiContext)}` : "Comandos: indisponíveis aqui (só no Studio local, com a apresentação salva na biblioteca). Não peça run:."}${mapData ? `\n\n${mapData}` : ""}` },
     // a conversa deste deck: o que a pessoa disse lá atrás (compactado) + as últimas trocas inteiras
     ...(convo.memory ? [{ role: "user", content: convo.memory }, { role: "assistant", content: "Certo, levo isso em conta." }] : []),
     ...convo.recent,
@@ -1020,7 +1027,7 @@ Antes de responder, verifique (e siga as Regras de edição):
   ];
   let motifObjected = false;
   const drawWarned = new Set();
-  const { spec: edited, prose, attempts, changed = [], talk, options = [], variants, imagesDropped, visionRouted, test = [], commands = [], transform, style, review, look } =
+  const { spec: edited, prose, attempts, changed = [], talk, options = [], variants, imagesDropped, visionRouted, test = [], commands = [], transform, style, review, look, geo } =
     await askUntilValid(messages, async (t) => {
       const parsed = parseEditText(t, spec);
       if (repairSlides && (parsed.spec.slides.length !== spec.slides.length || parsed.changed?.some(i => !repairSlides.includes(i)))) throw new Error('A revisão só pode corrigir os slides indicados, sem inserir, excluir ou alterar outros slides.');
@@ -1043,6 +1050,8 @@ Antes de responder, verifique (e siga as Regras de edição):
   if (transform) return { reply: prose || "Vou transformar a apresentação.", spec, actions, targetSlide, transform };
   // quer ver o material antes de responder: o Studio mostra as imagens e chama de novo (src/studio/ai-chat-route.js)
   if (look) return { reply: prose || "Vou olhar o material.", spec, actions, targetSlide, look };
+  // precisa de dados para o mapa: o Studio busca e chama de novo (src/studio/ai-chat-route.js)
+  if (geo) return { reply: prose || "Vou buscar os dados para o mapa.", spec, actions, targetSlide, geo };
   // estilo (Brand Kit): quem aplica/salva é o servidor, com a biblioteca
   if (style) return { reply: prose || "Certo.", spec, actions, targetSlide, style };
   // versões para escolher: nada muda até a pessoa escolher uma

package/src/ai/map-analysis-run.js

@@ -0,0 +1,119 @@
+// Análises do mapa pedidas pela IA no bloco `mapa:` (entrega 5): o código calcula, grava o resultado no projeto e
+// devolve números para a IA narrar. mais_proximo, contar (em raio ou em área), faixa em volta de uma linha, sugerir
+// onde instalar, rota com tempo, área alcançável e encaixar um rastro de GPS nas ruas. Lê as camadas do projeto (CSV
+// de pontos, GeoJSON, GPX, KML). Quem chama é runMapData (src/ai/map-data.js), que já cuidou do serviço bloqueado.
+import fs from "node:fs";
+import * as Project from "../studio/project.js";
+import { parseCSV } from "../csv.js";
+import { pointsFromRows, fromGPX, fromKML } from "../map.js";
+import { geocodeOne } from "../map-services.js";
+import { nearest, withinRadius, inPolygon, pointLine, circle, lineBuffer, suggestSites, fmtMetros } from "../map-analysis.js";
+import { route, isochrone, matchTrace, MODOS } from "../map-routing.js";
+
+export const ANALYSES = new Set(["mais_proximo", "contar", "faixa", "sugerir", "rota", "alcance", "encaixar"]);
+
+const okFile = (f, ext) => typeof f === "string" && /^contexto\/[\w\-. /]+$/.test(f) && f.toLowerCase().endsWith(ext) && !f.includes("..");
+const nameOf = (props, i) => props?.nome || props?.name || props?.titulo || `item ${i + 1}`;
+const fc = (features) => JSON.stringify({ type: "FeatureCollection", features });
+
+async function readPoints(P, file) {
+  const { rows } = parseCSV(fs.readFileSync(Project.resolveIn(P, file), "utf8"));
+  const head = (rows[0] || []).map((h) => String(h).trim());
+  return pointsFromRows(head, rows.slice(1)).features.map((f) => ({ lat: f.geometry.coordinates[1], lon: f.geometry.coordinates[0], props: f.properties }));
+}
+function readShapes(P, file) {
+  const text = fs.readFileSync(Project.resolveIn(P, file), "utf8");
+  if (/\.gpx$/i.test(file)) return fromGPX(text);
+  if (/\.kml$/i.test(file)) return fromKML(text);
+  const j = JSON.parse(text);
+  return j.type === "FeatureCollection" ? j.features : j.type === "Feature" ? [j] : [{ type: "Feature", properties: {}, geometry: j }];
+}
+async function placeOf(x, cfg) {
+  if (Array.isArray(x) && x.length === 2) return [Number(x[0]), Number(x[1])];
+  const hit = await geocodeOne(String(x), { cfg });
+  if (!hit) throw new Error(`não achei "${x}" no mapa`);
+  return [hit.lat, hit.lon];
+}
+
+export async function runAnalysis(a, { P, cfg, onProgress = () => {} }) {
+  if (a.tipo === "mais_proximo") {
+    const A = await readPoints(P, a.de), B = await readPoints(P, a.ate);
+    if (!A.length || !B.length) throw new Error("as planilhas precisam de pontos com posição");
+    const res = nearest(A.map((p) => [p.lat, p.lon]), B.map((p) => [p.lat, p.lon]));
+    const arquivo = okFile(a.arquivo, ".csv") ? a.arquivo : `${a.de.replace(/\.csv$/i, "")}-mais-proximo.csv`;
+    const cols = Object.keys(A[0].props).filter((c) => !c.startsWith("_"));
+    const rows = [[...cols, "latitude", "longitude", "mais_proximo", "distancia_m"],
+      ...A.map((p, i) => [...cols.map((c) => p.props[c] ?? ""), String(p.lat), String(p.lon), nameOf(B[res[i].j]?.props, res[i].j), String(Math.round(res[i].metros))])];
+    Project.writeSheet(P, arquivo, rows);
+    const media = res.reduce((s, r) => s + r.metros, 0) / res.length, far = res.reduce((m, r) => (r.metros > m.metros ? r : m), res[0]);
+    return { tipo: a.tipo, arquivo, linhas: A.length, oque: `distância de cada item de ${a.de} até o mais próximo de ${a.ate}: média ${fmtMetros(media)}, maior ${fmtMetros(far.metros)} (${nameOf(A[far.i].props, far.i)} até ${nameOf(B[far.j].props, far.j)})` };
+  }
+  if (a.tipo === "contar") {
+    const pts = await readPoints(P, a.pontos);
+    if (a.area) {
+      const areas = readShapes(P, a.area).filter((f) => /Polygon/.test(f.geometry?.type || ""));
+      const counts = areas.map((f, k) => ({ nome: nameOf(f.properties, k), n: pts.filter((p) => inPolygon([p.lat, p.lon], f.geometry)).length }));
+      return { tipo: a.tipo, arquivo: a.area, linhas: counts.length, oque: `pontos de ${a.pontos} dentro de cada área: ${counts.map((c) => `${c.nome}: ${c.n}`).join("; ")}` };
+    }
+    const centro = await placeOf(a.centro, cfg), metros = Number(a.metros) || 1000;
+    const dentro = withinRadius(pts.map((p) => [p.lat, p.lon]), centro, metros);
+    const arquivo = okFile(a.arquivo, ".geojson") ? a.arquivo : `contexto/raio-${Math.round(metros)}m.geojson`;
+    Project.writeText(P, arquivo, fc([{ type: "Feature", properties: { nome: `raio de ${fmtMetros(metros)}`, dentro: dentro.length }, geometry: circle(centro, metros) }]));
+    const nomes = dentro.slice(0, 8).map((i) => nameOf(pts[i].props, i)).join(", ");
+    return { tipo: a.tipo, arquivo, linhas: dentro.length, oque: `${dentro.length} de ${pts.length} pontos de ${a.pontos} ficam a até ${fmtMetros(metros)}${nomes ? ` (${nomes}${dentro.length > 8 ? "…" : ""})` : ""}; o círculo foi gravado` };
+  }
+  if (a.tipo === "faixa") {
+    const metros = Number(a.metros) || 50;
+    const lines = readShapes(P, a.linha).filter((f) => /LineString/.test(f.geometry?.type || ""));
+    if (!lines.length) throw new Error(`${a.linha} não tem linhas`);
+    const arquivo = okFile(a.arquivo, ".geojson") ? a.arquivo : `${a.linha.replace(/\.[^.]+$/, "")}-faixa-${Math.round(metros)}m.geojson`;
+    Project.writeText(P, arquivo, fc(lines.map((f, k) => ({ type: "Feature", properties: { nome: `${nameOf(f.properties, k)} (faixa de ${fmtMetros(metros)})` }, geometry: lineBuffer(f.geometry, metros) }))));
+    let extra = "";
+    if (a.pontos) {
+      const pts = await readPoints(P, a.pontos);
+      const perto = pts.filter((p) => lines.some((f) => pointLine([p.lat, p.lon], f.geometry) <= metros));
+      extra = `; ${perto.length} de ${pts.length} pontos de ${a.pontos} ficam a até ${fmtMetros(metros)} da linha${perto.length ? ` (${perto.slice(0, 8).map((p, i) => nameOf(p.props, i)).join(", ")}${perto.length > 8 ? "…" : ""})` : ""}`;
+    }
+    return { tipo: a.tipo, arquivo, linhas: lines.length, oque: `faixa de ${fmtMetros(metros)} em volta de ${a.linha}${extra}` };
+  }
+  if (a.tipo === "sugerir") {
+    const pts = await readPoints(P, a.existentes);
+    const area = a.area ? readShapes(P, a.area).find((f) => /Polygon/.test(f.geometry?.type || ""))?.geometry : null;
+    const sug = suggestSites(pts.map((p) => [p.lat, p.lon]), { area, quantos: Math.min(Number(a.quantos) || 3, 10) });
+    const arquivo = okFile(a.arquivo, ".csv") ? a.arquivo : "contexto/sugestoes.csv";
+    Project.writeSheet(P, arquivo, [["nome", "latitude", "longitude", "distancia_m"], ...sug.map((s, k) => [`Sugestão ${k + 1}`, s.lat.toFixed(6), s.lon.toFixed(6), String(Math.round(s.metros ?? 0))])]);
+    return { tipo: a.tipo, arquivo, linhas: sug.length, oque: `lugares mais longe dos existentes em ${a.existentes}${a.area ? ` dentro de ${a.area}` : ""}: ${sug.map((s, k) => `Sugestão ${k + 1} a ${fmtMetros(s.metros)} do mais próximo`).join("; ")} (sugestão geométrica: confira acesso, terreno e regras antes)` };
+  }
+  if (a.tipo === "rota") {
+    onProgress("calculando a rota…");
+    const de = await placeOf(a.de, cfg), para = await placeOf(a.para, cfg);
+    const r = await route([de, para], { modo: a.modo, cfg });
+    const arquivo = okFile(a.arquivo, ".geojson") ? a.arquivo : "contexto/rota.geojson";
+    Project.writeText(P, arquivo, fc([{ type: "Feature", properties: { nome: `${typeof a.de === "string" ? a.de : "origem"} até ${typeof a.para === "string" ? a.para : "destino"}`, distancia_m: Math.round(r.distancia), minutos: Math.round(r.duracao / 60), modo: MODOS[r.modo] }, geometry: { type: "LineString", coordinates: r.coords } }]));
+    return { tipo: a.tipo, arquivo, linhas: 1, oque: `rota ${MODOS[r.modo]}: ${fmtMetros(r.distancia)}, cerca de ${Math.round(r.duracao / 60)} min` };
+  }
+  if (a.tipo === "alcance") {
+    onProgress("calculando a área alcançável…");
+    const minutos = Math.min(Math.max(Number(a.minutos) || 10, 1), 60);
+    const origens = typeof a.de === "string" && /\.csv$/i.test(a.de)
+      ? (await readPoints(P, a.de)).slice(0, 8).map((p, i) => ({ at: [p.lat, p.lon], nome: nameOf(p.props, i) }))
+      : [{ at: await placeOf(a.de, cfg), nome: String(a.de) }];
+    const feats = [];
+    for (const o of origens) feats.push({ type: "Feature", properties: { nome: `${o.nome}: ${minutos} min ${MODOS[a.modo] || "a pé"}` }, geometry: await isochrone(o.at, minutos, { modo: a.modo, cfg }) });
+    const arquivo = okFile(a.arquivo, ".geojson") ? a.arquivo : `contexto/alcance-${minutos}min.geojson`;
+    Project.writeText(P, arquivo, fc(feats));
+    return { tipo: a.tipo, arquivo, linhas: feats.length, oque: `área alcançável em ${minutos} min ${MODOS[a.modo] || "a pé"} a partir de ${origens.length} ${origens.length === 1 ? "ponto" : "pontos"}` };
+  }
+  if (a.tipo === "encaixar") {
+    onProgress("encaixando o rastro nas ruas…");
+    const f = readShapes(P, a.trilha).find((x) => /LineString/.test(x.geometry?.type || ""));
+    if (!f) throw new Error(`${a.trilha} não tem um rastro (linha)`);
+    const coords = f.geometry.type === "LineString" ? f.geometry.coordinates : f.geometry.coordinates.flat();
+    const step = Math.max(1, Math.ceil(coords.length / 100)); // o serviço aceita até 100 pontos: amostra o rastro
+    const out = await matchTrace(coords.filter((_, i) => i % step === 0).map(([lon, lat]) => [lat, lon]), { modo: a.modo, cfg });
+    const arquivo = okFile(a.arquivo, ".geojson") ? a.arquivo : `${a.trilha.replace(/\.[^.]+$/, "")}-nas-ruas.geojson`;
+    Project.writeText(P, arquivo, fc([{ type: "Feature", properties: { nome: `${nameOf(f.properties, 0)} (nas ruas)` }, geometry: { type: "LineString", coordinates: out } }]));
+    return { tipo: a.tipo, arquivo, linhas: 1, oque: `rastro de ${a.trilha} encaixado nas ruas (${out.length} pontos)` };
+  }
+  throw new Error(`análise desconhecida: ${a.tipo}`);
+}