feat(export): embed the final map state in the saved chat log (#324) (#326)

The 💾 export dropped the map entirely. Capture the map as it stood at
Save time — one map per log — as an interactive MapLibre embed (live,
pannable) rather than a raster screenshot, so the transcript shows the
layers/styling/filters that were on screen and stays inspectable.

- MapManager.getExportState(): serializable {style, camera, projection};
  terrain (keyed MapTiler DEM) stripped so its token can't leak.
- chat-ui buildMapEmbedHtml(): pure helper that re-hydrates a map from the
  captured state via the same pinned CDN builds the app uses
  (maplibre-gl@5.22.0, pmtiles@3.0.7). Runs the state through the existing
  credential scrub + redacts MapTiler key= params; escapes < so a
  </script> in a source name/URL can't break out of the JSON block.
- Wire into exportHtml() (guarded — a ChatUI without a map still exports)
  and pass mapManager into ChatUI from main.js.
- Tests for both helpers; docs updated (Chat export § Embedded map).

Author: cboettig

app/chat-ui.js

@@ -67,6 +67,88 @@ export function scrubCredentials(text) {
  */
 export const REDACTED_KEYS = ['s3_key', 's3_secret', 's3_endpoint', 's3_scope', 'catalog_token'];
 
+/*
+ * CDN builds used to re-hydrate the map in an exported transcript. Pinned to
+ * match what the app itself loads (see app/index.html and
+ * docs/guide/quickstart.md) so the embedded style renders under the same
+ * MapLibre/PMTiles version that produced it. Bump alongside the app's pins.
+ */
+export const EXPORT_MAP_MAPLIBRE_VERSION = '5.22.0';
+export const EXPORT_MAP_PMTILES_VERSION = '3.0.7';
+
+/**
+ * Build a self-rendering, interactive MapLibre map from a captured map state,
+ * as HTML for embedding in the exported transcript. The map re-hydrates from
+ * the embedded style + camera in the recipient's browser — it is live
+ * (pan/zoom), not a raster snapshot, so it needs network access to the same
+ * public tile sources that produced it.
+ *
+ * The serialized state is credential-scrubbed: AWS signatures / bearer tokens
+ * (via {@link scrubCredentials}) and MapTiler `key=` params must never ride
+ * along into a shared file. `<` is escaped to `<` so a source name or URL
+ * containing `</script>` can't break out of the embedded JSON block.
+ *
+ * @param {object|null} state - from MapManager.getExportState(); null/empty → no map
+ * @returns {{ headTags: string, body: string }} empty strings when there is no map
+ */
+export function buildMapEmbedHtml(state) {
+    if (!state || !state.style) return { headTags: '', body: '' };
+
+    let stateJson = JSON.stringify(state);
+    stateJson = scrubCredentials(stateJson);
+    // Redact MapTiler-style API keys in any surviving source URL.
+    stateJson = stateJson.replace(/([?&]key=)[^&"'\\]+/g, '$1[REDACTED]');
+    // Neutralize a </script> breakout hiding in the embedded JSON.
+    const safeJson = stateJson.replace(/</g, '\\u003c');
+
+    const ml = EXPORT_MAP_MAPLIBRE_VERSION;
+    const pm = EXPORT_MAP_PMTILES_VERSION;
+
+    const headTags =
+`<link href="https://unpkg.com/maplibre-gl@${ml}/dist/maplibre-gl.css" rel="stylesheet" crossorigin="anonymous">
+<script src="https://unpkg.com/maplibre-gl@${ml}/dist/maplibre-gl.js" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/pmtiles@${pm}/dist/pmtiles.js" crossorigin="anonymous"></script>`;
+
+    const body =
+`<section class="export-map-section">
+  <h2 class="export-map-title">Map at time of export</h2>
+  <div id="export-map" class="export-map"></div>
+  <p class="export-map-note">Interactive map re-rendered from the saved state. Needs a network
+     connection to the original public tile sources; private or signed layers may not appear.</p>
+  <script type="application/json" id="export-map-state">${safeJson}</script>
+  <script>
+  (function () {
+    var el = document.getElementById('export-map');
+    try {
+      if (typeof maplibregl === 'undefined') throw new Error('MapLibre GL JS did not load');
+      var state = JSON.parse(document.getElementById('export-map-state').textContent);
+      if (window.pmtiles && maplibregl.addProtocol) {
+        maplibregl.addProtocol('pmtiles', new pmtiles.Protocol().tile);
+      }
+      var map = new maplibregl.Map({
+        container: 'export-map',
+        style: state.style,
+        center: state.center,
+        zoom: state.zoom,
+        bearing: state.bearing,
+        pitch: state.pitch,
+        renderWorldCopies: false,
+      });
+      map.addControl(new maplibregl.NavigationControl(), 'top-left');
+      if (state.projection === 'globe') {
+        map.on('load', function () { map.setProjection({ type: 'globe' }); });
+      }
+    } catch (e) {
+      if (el) el.innerHTML = '<p class="export-map-error">Could not render the saved map: ' +
+        (e && e.message ? e.message : e) + '</p>';
+    }
+  })();
+  </script>
+</section>`;
+
+    return { headTags, body };
+}
+
 /**
  * Render LLM-derived text to HTML for innerHTML insertion. The model can be
  * steered by anything it reads (dataset values, STAC descriptions), so its
@@ -104,10 +186,14 @@ export class ChatUI {
      *   {
      *     container, messages, input, send, mic, header, footer, footerRight,
      *   }
+     * @param {import('./map-manager.js').MapManager} [mapManager] - used by the
+     *   HTML export to embed the final map state; optional so tests and
+     *   headless harnesses can construct a ChatUI without a live map.
      */
-    constructor(agent, config, mount) {
+    constructor(agent, config, mount, mapManager = null) {
         this.agent = agent;
         this.config = config;
+        this.mapManager = mapManager;
         this.busy = false;
 
         // Cache DOM refs from layout-manager (no getElementById here).
@@ -1087,13 +1173,24 @@ export class ChatUI {
         const appTitle = document.title || 'GLEN';
         const exportedAt = new Date().toLocaleString();
 
+        // Capture the final map state (one map per saved log). Guarded so a
+        // ChatUI built without a map still exports the transcript.
+        let mapState = null;
+        try {
+            mapState = this.mapManager?.getExportState?.() ?? null;
+        } catch (err) {
+            console.warn('[ChatUI] map capture for export failed:', err);
+        }
+        const mapEmbed = buildMapEmbedHtml(mapState);
+
         const html =
 `<!doctype html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
 <title>${this.escapeHtml(title)}</title>
 <style>${css}</style>
+${mapEmbed.headTags}
 </head>
 <body>
 <header class="export-header">
@@ -1103,6 +1200,7 @@ export class ChatUI {
      (<code>https://s3-west.nrp-nautilus.io/</code>) so they can be re-run from any DuckDB
      with the <code>httpfs</code> extension loaded.</p>
 </header>
+${mapEmbed.body}
 <main id="chat-messages">${clone.innerHTML}</main>
 </body>
 </html>`;
@@ -1233,6 +1331,11 @@ body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-
 .welcome-message { background: #f9fafb; padding: 8px 10px; border-radius: 6px;
                    font-size: 13px; color: #6b7280; }
 .welcome-examples { display: none; }
+.export-map-section { margin: 0 0 1rem; }
+.export-map-title { font-size: 1rem; margin: 0 0 0.5rem; }
+.export-map { width: 100%; height: 480px; border: 1px solid #ddd; border-radius: 6px; }
+.export-map-note { font-size: 12px; color: #6b7280; margin: 6px 0 0; }
+.export-map-error { padding: 1rem; color: #991b1b; font-size: 13px; }
 `;
     }
 

app/main.js

@@ -386,7 +386,7 @@ async function main() {
     console.log('[main] Agent ready');
 
     /* ── 8. Create UI ─────────────────────────────────────────────────── */
-    const ui = new ChatUI(agent, appConfig, layoutRefs.chatMount);
+    const ui = new ChatUI(agent, appConfig, layoutRefs.chatMount, mapManager);
 
     // Draw event → chat notifications.
     // Replace (not append) synthetic draw messages so repeated draw/clear

app/map-manager.js

@@ -147,6 +147,36 @@ export class MapManager {
         document.body.appendChild(this._tooltip);
     }
 
+    /**
+     * Snapshot the current map for embedding in an exported chat transcript.
+     * Returns a plain, JSON-serializable object: the full MapLibre style
+     * (sources + layers, with current paint / filter / visibility baked in)
+     * plus the camera. A consumer can re-hydrate a live map from this alone.
+     *
+     * Terrain is stripped: its DEM source is keyed to a private MapTiler
+     * token that must not leak into a shared export, and a flat map is fine
+     * for a transcript. Remaining credential scrubbing happens at embed time.
+     *
+     * @returns {{center:[number,number], zoom:number, bearing:number,
+     *            pitch:number, projection:string, style:object}}
+     */
+    getExportState() {
+        const style = this.map.getStyle();
+        if (style.terrain) delete style.terrain;
+        if (style.sources && style.sources['terrain-dem']) {
+            delete style.sources['terrain-dem'];
+        }
+        const c = this.map.getCenter();
+        return {
+            center: [c.lng, c.lat],
+            zoom: this.map.getZoom(),
+            bearing: this.map.getBearing(),
+            pitch: this.map.getPitch(),
+            projection: this._globeEnabled ? 'globe' : 'mercator',
+            style,
+        };
+    }
+
     /**
      * Register and add layers to the map from catalog configs.
      * @param {Array} layerConfigs - From DatasetCatalog.getMapLayerConfigs()

docs/guide/configuration.md

@@ -719,12 +719,21 @@ The checkpoint is the only per-turn cap on tool use. Setting a value to `0` remo
 
 A 💾 save button in the chat footer saves the current conversation as a self-contained HTML document you can share or print. The button is disabled until the first user message and enables automatically after. No configuration — it's always present.
 
-The saved file mirrors what the user sees in the live chat: user prompts, assistant prose, and tool-call rows with collapsible SQL and result blocks. Everything is in a single `.html` with inlined CSS — no external assets, no JavaScript required to view it.
+The saved file mirrors what the user sees in the live chat: user prompts, assistant prose, and tool-call rows with collapsible SQL and result blocks, plus the **map as it stood when Save was clicked** (see below).
 
 Two guarantees apply to the export:
 
 - **Reproducible SQL.** Every `s3://bucket/...` URL inside a SQL block is rewritten to `https://s3-west.nrp-nautilus.io/bucket/...`. Pasting the SQL into any DuckDB with `INSTALL httpfs; LOAD httpfs;` will run it against the public endpoint without secret configuration (public buckets only).
-- **Credential scrubbing.** On top of the live-chat redaction described in the agent-loop docs, the export pass replaces credential-shaped tokens with `[REDACTED]` — DuckDB `CREATE SECRET` key/value pairs, AWS access keys (`aws_access_key_id`, `aws_secret_access_key`), `Authorization: Bearer …` tokens, and pre-signed-URL `X-Amz-Signature` / `X-Amz-Credential` / `X-Amz-Security-Token` query parameters.
+- **Credential scrubbing.** On top of the live-chat redaction described in the agent-loop docs, the export pass replaces credential-shaped tokens with `[REDACTED]` — DuckDB `CREATE SECRET` key/value pairs, AWS access keys (`aws_access_key_id`, `aws_secret_access_key`), `Authorization: Bearer …` tokens, and pre-signed-URL `X-Amz-Signature` / `X-Amz-Credential` / `X-Amz-Security-Token` query parameters. This scrubbing also covers the embedded map state (below).
+
+### Embedded map
+
+The export captures the final map state — one map per saved log — as an **interactive MapLibre map**, not a static image. It serializes `map.getStyle()` (all sources, layers, and their current paint / filter / visibility) plus the camera (center, zoom, bearing, pitch, and globe-vs-mercator projection), embeds it in the HTML, and re-renders a live, pannable map when the file is opened. Because it's the real style rather than a screenshot, the recipient sees exactly the layers and styling that were on screen and can zoom and inspect them.
+
+Trade-offs, by design:
+
+- **Not fully offline.** The embedded map loads MapLibre GL JS and PMTiles from the same pinned CDN builds the app uses (`maplibre-gl@5.22.0`, `pmtiles@3.0.7`) and fetches tiles from the original public sources at view time. Without a network connection, the map area shows an error message; the rest of the transcript still renders.
+- **Public layers only.** Terrain (whose DEM source is keyed to a private MapTiler token) is stripped, and any signed or private tile URL is redacted by the credential scrub — so such layers may not appear for a recipient. The transcript text remains complete.
 
 ## Finding STAC asset IDs
 

test/chat-export.test.js

@@ -115,3 +115,84 @@ describe('scrubCredentials', () => {
         expect(scrubCredentials(null)).toBe(null);
     });
 });
+
+import {
+    buildMapEmbedHtml,
+    EXPORT_MAP_MAPLIBRE_VERSION,
+    EXPORT_MAP_PMTILES_VERSION,
+} from '../app/chat-ui.js';
+
+describe('buildMapEmbedHtml', () => {
+    const sampleState = () => ({
+        center: [-119.4, 36.8],
+        zoom: 6.5,
+        bearing: 0,
+        pitch: 0,
+        projection: 'mercator',
+        style: {
+            version: 8,
+            sources: { natgeo: { type: 'raster', tiles: ['https://example/{z}/{x}/{y}.png'] } },
+            layers: [{ id: 'natgeo-base', type: 'raster', source: 'natgeo' }],
+        },
+    });
+
+    // Pull the JSON out of the <script type="application/json"> block and
+    // reverse the < escaping so it can be JSON.parsed back.
+    const extractState = (body) => {
+        const m = body.match(
+            /<script type="application\/json" id="export-map-state">([\s\S]*?)<\/script>/
+        );
+        expect(m).toBeTruthy();
+        return JSON.parse(m[1].replace(/\\u003c/g, '<'));
+    };
+
+    it('returns empty strings when there is no map state', () => {
+        expect(buildMapEmbedHtml(null)).toEqual({ headTags: '', body: '' });
+        expect(buildMapEmbedHtml(undefined)).toEqual({ headTags: '', body: '' });
+        expect(buildMapEmbedHtml({})).toEqual({ headTags: '', body: '' });
+    });
+
+    it('pins the CDN builds to the versions the app loads', () => {
+        const { headTags } = buildMapEmbedHtml(sampleState());
+        expect(headTags).toContain(`maplibre-gl@${EXPORT_MAP_MAPLIBRE_VERSION}/dist/maplibre-gl.js`);
+        expect(headTags).toContain(`maplibre-gl@${EXPORT_MAP_MAPLIBRE_VERSION}/dist/maplibre-gl.css`);
+        expect(headTags).toContain(`pmtiles@${EXPORT_MAP_PMTILES_VERSION}/dist/pmtiles.js`);
+    });
+
+    it('embeds a parseable state and a container the init script targets', () => {
+        const { body } = buildMapEmbedHtml(sampleState());
+        expect(body).toContain('id="export-map"');
+        expect(body).toContain("maplibregl.addProtocol('pmtiles'");
+        const parsed = extractState(body);
+        expect(parsed.center).toEqual([-119.4, 36.8]);
+        expect(parsed.zoom).toBe(6.5);
+        expect(parsed.style.layers[0].id).toBe('natgeo-base');
+    });
+
+    it('scrubs AWS signatures and MapTiler keys from source URLs', () => {
+        const state = sampleState();
+        state.style.sources.natgeo.tiles = [
+            'https://api.maptiler.com/tiles/x/{z}/{x}/{y}.png?key=SECRETKEY123',
+        ];
+        state.style.sources.signed = {
+            type: 'raster',
+            tiles: ['https://s3-west.nrp-nautilus.io/b/x?X-Amz-Signature=abc123def456'],
+        };
+        const { body } = buildMapEmbedHtml(state);
+        expect(body).not.toContain('SECRETKEY123');
+        expect(body).not.toContain('abc123def456');
+        // Still valid JSON after scrubbing.
+        expect(() => extractState(body)).not.toThrow();
+    });
+
+    it('neutralizes a </script> breakout hidden in the state', () => {
+        const state = sampleState();
+        state.style.name = 'evil</script><script>alert(1)</script>';
+        const { body } = buildMapEmbedHtml(state);
+        // The only real closing tags are the two we emit; the injected one is escaped.
+        expect(body).not.toContain('<script>alert(1)');
+        expect(body).toContain('\\u003c/script');
+        // And it still round-trips.
+        expect(extractState(body).style.name).toBe('evil</script><script>alert(1)</script>');
+    });
+});

test/map-manager.export.test.js

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import { MapManager } from '../app/map-manager.js';
+
+/**
+ * Stub the small MapLibre surface getExportState() reads. getStyle() returns
+ * a fresh object each call (as MapLibre does) so the method's mutation can't
+ * leak back into the live map.
+ */
+function createManager({ globe = false, style } = {}) {
+    const map = {
+        getStyle: () => JSON.parse(JSON.stringify(style)),
+        getCenter: () => ({ lng: -119.4, lat: 36.8 }),
+        getZoom: () => 6.5,
+        getBearing: () => 12,
+        getPitch: () => 30,
+    };
+    const mm = Object.create(MapManager.prototype);
+    mm.map = map;
+    mm._globeEnabled = globe;
+    return mm;
+}
+
+describe('MapManager.getExportState', () => {
+    const styleWithTerrain = () => ({
+        version: 8,
+        terrain: { source: 'terrain-dem', exaggeration: 1.5 },
+        sources: {
+            'terrain-dem': { type: 'raster-dem', url: 'https://api.maptiler.com/x?key=SECRET' },
+            natgeo: { type: 'raster', tiles: ['https://example/{z}/{x}/{y}.png'] },
+        },
+        layers: [{ id: 'natgeo-base', type: 'raster', source: 'natgeo' }],
+    });
+
+    it('captures the camera and projection', () => {
+        const s = createManager({ globe: true, style: styleWithTerrain() }).getExportState();
+        expect(s.center).toEqual([-119.4, 36.8]);
+        expect(s.zoom).toBe(6.5);
+        expect(s.bearing).toBe(12);
+        expect(s.pitch).toBe(30);
+        expect(s.projection).toBe('globe');
+    });
+
+    it('reports mercator when the globe is off', () => {
+        const s = createManager({ globe: false, style: styleWithTerrain() }).getExportState();
+        expect(s.projection).toBe('mercator');
+    });
+
+    it('strips terrain and its keyed DEM source (must not leak the MapTiler key)', () => {
+        const s = createManager({ style: styleWithTerrain() }).getExportState();
+        expect(s.style.terrain).toBeUndefined();
+        expect(s.style.sources['terrain-dem']).toBeUndefined();
+        expect(s.style.sources.natgeo).toBeDefined();
+        expect(JSON.stringify(s.style)).not.toContain('SECRET');
+    });
+
+    it('keeps the full style (sources + layers) for re-hydration', () => {
+        const s = createManager({ style: styleWithTerrain() }).getExportState();
+        expect(s.style.layers[0].id).toBe('natgeo-base');
+        expect(s.style.version).toBe(8);
+    });
+});