@showmeonmap/mcp 0.7.0 → 0.7.1

package/README.md

@@ -101,6 +101,8 @@ Ask Claude Desktop things like:
 **Feedback channel (1)**: `report_blocker`.
 **Saved workflows (3)**: `save_workflow`, `list_workflows`, `run_workflow`.
 
+**0.7.1**: `build_map`'s `next_actions` come from the map itself (real data filters and the plan's own follow-ups, not generic suggestions); a Cloudflare error page from the backend reaches the model as a typed message with its code and Ray ID instead of raw HTML; shared maps keep the fields they paint and say when they hold a sample of the features.
+
 **0.7.0** (everything merged since 0.6.0): the three workflow tools (with `batch` runs over a value list); `run_analysis` adds spatial join, merge/append, near and dissolve; `rationale` is optional on every tool; no tuple schemas (Claude dropped `set_camera` / `add_annotation`); fact-only tool descriptions; `export_layer_data` works on a saved map; share links store the features the map shows after `filter_layer` and its counts follow the filter; the server reports its real version; and an npm install no longer writes rationale logs into your `node_modules`.
 
 `focus_area` (0.4.0) refines an existing map to a **named** area — no coordinates required. Pass a `layerId` plus an `areaRef` (`{kind:'corridor', street, from?, to?}`, `{kind:'place', name}`, or `{kind:'aroundIntersection', street, cross}`) and the server resolves the real geometry from OpenStreetMap, then applies one of three `mode`s: `filter` (hide non-matching), `select` (extract to a new layer), or `clip` (geometrically trim — lines are split at the boundary). The reply carries a grounded `contextAnswer` such as `"kept 37 of 150 features"`. A resolver miss returns a `clarification` with real nearby candidates rather than a guessed location.
@@ -118,14 +120,15 @@ Every tool returns a **three-channel envelope**:
   "shareable_url": "http://localhost:3000/m/…",
   "metadata": { "title": "…", "layer_count": 2, "last_updated": "…" },
   "next_actions": [
-    { "label": "Filter to features where name is not empty", "argsTemplate": { "instruction": "…" } }
+    { "label": "Show only Earthquakes with magnitude ≥ 5.3 (5 of 10 features)", "tool": "filter_layer",
+      "argsTemplate": { "layerId": "smo_usgs_earthquakes", "predicate": { "op": "gte", "field": "magnitude", "value": 5.3 } } }
   ],
   "outOfScope": { "reason": "…" },
   "clarification": { "question": "…", "candidates": [ … ] }
 }
 ```
 
-The calling agent reasons over `structured`, surfaces `shareable_url` to its end user for interactive drill-down, and uses `next_actions` as typed hints for follow-up tool calls.
+The calling agent reasons over `structured`, surfaces `shareable_url` to its end user for interactive drill-down, and uses `next_actions` as typed hints for follow-up tool calls: each hint's `argsTemplate` is exactly the args (minus `map_id`) of the named `tool`. Hints come from the map's own data, followups and current state; an empty list means nothing useful to suggest.
 
 For the full Op catalog and predicate grammar that the V2 tools accept, fetch the MCP resource at `showmeonmap://docs/workspace-ops-spec` — agents should not guess these shapes.
 

package/dist/nextActions.js

@@ -0,0 +1,340 @@
+/**
+ * build_map `next_actions` — state-aware, subject-aware follow-up hints.
+ *
+ * Until 2026-10-12 every build_map returned the same three constants
+ * ("Filter the layer to features where name is not empty", "Change the
+ * basemap to satellite", "Zoom the camera closer") whatever the map was. A
+ * live MCP test on three maps (M5+ earthquakes near Japan, California
+ * earthquakes, wildfires near Vancouver) showed all three were junk: every
+ * earthquake and fire detection HAS a name, the wildfire map was ALREADY on
+ * satellite, and the plan's own better follow-ups ("Smoke plume", "Air
+ * quality") never reached the caller. Agents learned to ignore the field.
+ *
+ * The rules this module enforces (pinned both directions in
+ * __tests__/tools/nextActions.test.ts):
+ *
+ *  - A filter hint names a field that exists on the layer AND varies across
+ *    its features, and its threshold/value comes from the features
+ *    themselves (a numeric threshold near the observed median, re-checked so
+ *    it keeps some features and drops some). Nothing is invented.
+ *  - Never suggest a state the map is already in (basemap already that
+ *    style, already zoomed close, already zoomed out).
+ *  - Surface the plan's own `followups` (handler + companion chips) — with
+ *    "this area" / "here" rewritten to the place in the caller's query,
+ *    because a fresh build_map has no "this area". When the place cannot be
+ *    read back out of the query, a region-neutral follow-up is dropped
+ *    rather than sent somewhere wrong.
+ *  - Nothing useful → `[]`. An empty list is a correct answer.
+ *
+ * Each hint is `{ label, argsTemplate, tool }`: `argsTemplate` is exactly
+ * the args (minus `map_id`) of `tool`, so it passes that tool's strict
+ * input validation as-is — `filter_layer` gets `{layerId, predicate}`,
+ * `mutate_map` gets `{instruction}`, `build_map` gets `{query}`.
+ */
+export const MAX_NEXT_ACTIONS = 3;
+const MAX_FILTER_HINTS = 2;
+const MAX_FOLLOWUP_HINTS = 2;
+// Measures worth thresholding when the layer itself does not name one
+// (valueField / filterConfig always qualify). Keys are normalized
+// (lower-case, alphanumerics only) so "Size (ha)" matches "sizeha".
+const KNOWN_MEASURES = [
+    'magnitude', 'mag', 'frp', 'brightness', 'sizeha', 'hectares', 'acres', 'areaha',
+    'containment', 'depth', 'significance', 'sig', 'population', 'pop',
+];
+// Measures where SMALLER is the notable end (shallow earthquakes do the damage).
+const LOWER_IS_NOTABLE = new Set(['depth']);
+// Categorical fields worth filtering, and the values that are the story when present.
+const KNOWN_CATEGORICAL = new Set([
+    'status', 'confidence', 'severity', 'alert', 'alertlevel', 'urgency', 'certainty', 'firestatus', 'stage',
+]);
+const SALIENT_VALUES = [
+    'out of control', 'active', 'high', 'h', 'extreme', 'severe', 'major', 'warning', 'emergency', 'red',
+];
+// Never a measure / filter dimension: coordinates (a coordinate column is
+// never a measure — CLAUDE.md), clocks, ids, links, free text.
+const EXCLUDED_FIELD = new RegExp('^(lat|latitude|lng|lon|long|longitude|x|y|easting|northing|' +
+    'time|timestamp|date|datetime|updated|hoursago|epoch|' +
+    'id|fid|objectid|gid|eventid|code|url|link|details|' +
+    'name|title|place|label|description|incident)$');
+function normKey(k) {
+    return k.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+function isInternalField(k) {
+    return k.startsWith('_');
+}
+function featuresOf(layer) {
+    const data = layer.source?.data;
+    if (!data || data.type !== 'FeatureCollection' || !Array.isArray(data.features))
+        return [];
+    return data.features.map((f) => (f && typeof f.properties === 'object' && f.properties ? f.properties : {}));
+}
+function layerName(layer) {
+    return (layer.title ?? layer.id ?? 'the layer').trim();
+}
+/** A threshold that reads cleanly AND still splits the observed values. */
+function niceThreshold(values, lowerIsNotable) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const n = sorted.length;
+    const median = n % 2 ? sorted[(n - 1) / 2] : (sorted[n / 2 - 1] + sorted[n / 2]) / 2;
+    const allInt = sorted.every((v) => Number.isInteger(v));
+    const range = sorted[n - 1] - sorted[0];
+    const candidates = [];
+    if (allInt)
+        candidates.push(Math.round(median));
+    else if (range <= 20)
+        candidates.push(Math.round(median * 10) / 10);
+    else {
+        const mag = Math.pow(10, Math.floor(Math.log10(Math.abs(median) || 1)) - 1);
+        candidates.push(Math.round(median / mag) * mag);
+    }
+    candidates.push(median);
+    for (const raw of candidates) {
+        const t = Number(raw.toPrecision(6));
+        const kept = sorted.filter((v) => (lowerIsNotable ? v <= t : v >= t)).length;
+        if (kept > 0 && kept < n)
+            return { t, kept };
+    }
+    return null;
+}
+function collectFieldStats(props) {
+    const stats = new Map();
+    for (const p of props) {
+        for (const [k, v] of Object.entries(p)) {
+            if (v === null || v === undefined || v === '')
+                continue;
+            let s = stats.get(k);
+            if (!s) {
+                s = { key: k, numeric: [], strings: new Map() };
+                stats.set(k, s);
+            }
+            if (typeof v === 'number' && Number.isFinite(v))
+                s.numeric.push(v);
+            else if (typeof v === 'string')
+                s.strings.set(v, (s.strings.get(v) ?? 0) + 1);
+        }
+    }
+    return stats;
+}
+/** Data-derived filter_layer hints for one layer, best first. */
+function filterHintsForLayer(layer) {
+    const layerId = layer.id;
+    if (!layerId)
+        return [];
+    const props = featuresOf(layer);
+    const n = props.length;
+    if (n < 3)
+        return [];
+    const stats = collectFieldStats(props);
+    const name = layerName(layer);
+    const preferred = new Set();
+    if (layer.viz?.valueField)
+        preferred.add(layer.viz.valueField);
+    for (const fc of layer.filterConfig ?? [])
+        if (fc.field)
+            preferred.add(fc.field);
+    const eligible = (k) => !isInternalField(k) && !EXCLUDED_FIELD.test(normKey(k));
+    // ── numeric thresholds ────────────────────────────────────────────────
+    const numericFields = [...stats.values()]
+        .filter((s) => eligible(s.key))
+        .filter((s) => s.numeric.length >= Math.ceil(n * 0.8))
+        .filter((s) => new Set(s.numeric).size >= 3)
+        .filter((s) => preferred.has(s.key) || KNOWN_MEASURES.includes(normKey(s.key)))
+        .sort((a, b) => rank(a.key) - rank(b.key));
+    function rank(k) {
+        if (layer.viz?.valueField === k)
+            return -2;
+        if (preferred.has(k))
+            return -1;
+        return KNOWN_MEASURES.indexOf(normKey(k));
+    }
+    const preferredNumeric = [];
+    const otherNumeric = [];
+    const seenSignatures = new Set();
+    for (const s of numericFields) {
+        // A synthetic duplicate (e.g. `value` = magnitude for sizing) says nothing new.
+        const signature = s.numeric.join(',');
+        if (seenSignatures.has(signature))
+            continue;
+        seenSignatures.add(signature);
+        const lower = LOWER_IS_NOTABLE.has(normKey(s.key));
+        const th = niceThreshold(s.numeric, lower);
+        if (!th)
+            continue;
+        const op = lower ? 'lte' : 'gte';
+        const sym = lower ? '≤' : '≥';
+        (preferred.has(s.key) ? preferredNumeric : otherNumeric).push({
+            label: `Show only ${name} with ${s.key} ${sym} ${th.t} (${th.kept} of ${n} features)`,
+            argsTemplate: { layerId, predicate: { op, field: s.key, value: th.t } },
+            tool: 'filter_layer',
+        });
+    }
+    const categorical = [];
+    // ── categorical: a salient value that some, not all, features carry ──
+    for (const s of stats.values()) {
+        if (!eligible(s.key))
+            continue;
+        const isKnown = KNOWN_CATEGORICAL.has(normKey(s.key)) ||
+            (layer.filterConfig ?? []).some((fc) => fc.field === s.key && fc.kind === 'category');
+        if (!isKnown)
+            continue;
+        const totalStrings = [...s.strings.values()].reduce((a, b) => a + b, 0);
+        if (totalStrings < Math.ceil(n * 0.8) || s.strings.size < 2 || s.strings.size > 12)
+            continue;
+        const salient = SALIENT_VALUES
+            .map((sv) => [...s.strings.keys()].find((v) => v.trim().toLowerCase() === sv))
+            .find((v) => typeof v === 'string');
+        if (!salient)
+            continue;
+        const count = s.strings.get(salient) ?? 0;
+        if (count === 0 || count === totalStrings)
+            continue;
+        categorical.push({
+            label: `Show only ${name} where ${s.key} is "${salient}" (${count} of ${n} features)`,
+            argsTemplate: { layerId, predicate: { op: 'eq', field: s.key, value: salient } },
+            tool: 'filter_layer',
+        });
+        break;
+    }
+    // The layer's own encoded measure, then the story value of a status-like
+    // field, then other known measures.
+    return [...preferredNumeric, ...categorical, ...otherNumeric];
+}
+// ── plan follow-ups ────────────────────────────────────────────────────────
+const TIME_WINDOW_TAIL_RE = /(?:^|\s+)(?:(?:in|over|during|for|within|from|since)\s+)?(?:the\s+)?(?:(?:this|last|past|next|recent|previous|current|coming)\s+|\d+\s+)(?:\d+\s+)?(?:hour|hours|day|days|week|weeks|month|months|year|years|decade|decades)(?:\s+ago)?$/i;
+const SIMPLE_TIME_TAIL_RE = /\s+(?:(?:in|during|since|for)\s+)?(?:today|tonight|now|right now|recently|yesterday|(?:19|20)\d{2})$/i;
+const PRESENTATION_TAIL_RE = /,\s*(?:sized|colou?red|shown|styled|drawn|rendered|displayed|with|using|as|on)\b.*$/i;
+const LOCATION_PREP_RE = /\b(?:in|near|around|across|over|at|within)\s+/gi;
+const BAD_PLACE_START = /^(?:the\s+)?(?:past|last|this|next|recent|previous|current|coming|today|tonight|least|most)\b/i;
+/**
+ * The place a build_map query names, or null. Conservative on purpose: a
+ * wrong place is worse than no follow-up, so anything doubtful returns null.
+ *   "earthquakes above magnitude 5 near Japan this month" → "Japan"
+ *   "earthquakes in California in the past year"         → "California"
+ *   "active wildfires near Vancouver, British Columbia"   → "Vancouver, British Columbia"
+ */
+export function placeFromQuery(query) {
+    const q = (query ?? '').trim().replace(/[.?!]+$/, '');
+    for (const m of q.matchAll(LOCATION_PREP_RE)) {
+        let place = q.slice((m.index ?? 0) + m[0].length);
+        place = place.replace(PRESENTATION_TAIL_RE, '');
+        for (let i = 0; i < 3; i++) {
+            const before = place;
+            place = place.replace(TIME_WINDOW_TAIL_RE, '').replace(SIMPLE_TIME_TAIL_RE, '').trim();
+            if (place === before)
+                break;
+        }
+        if (!place || place.length > 60 || /\d/.test(place) || BAD_PLACE_START.test(place))
+            continue;
+        return place;
+    }
+    return null;
+}
+// Phrases that only mean something next to the map the user is looking at.
+const CONTEXT_PHRASE_RE = /\b(?:this area|this region|the area|here|nearby|on screen|current view|neighbou?ring)\b/i;
+function localizeMessage(message, place) {
+    if (!CONTEXT_PHRASE_RE.test(message))
+        return message;
+    if (!place)
+        return null;
+    const out = message
+        .replace(/\b(?:this area|this region|the area)\b/gi, place)
+        .replace(/\bhere\b/gi, `near ${place}`);
+    // "nearby" / "on screen" / "neighbouring" have no faithful rewrite — drop.
+    return CONTEXT_PHRASE_RE.test(out) ? null : out;
+}
+const MUTATION_RE = /^(?:filter|only show|show only|zoom|switch|change|set|remove|hide|colou?r|restyle|clear)\b/i;
+const BASEMAP_STYLES = ['satellite', 'dark', 'light', 'streets', 'engineering'];
+/** True when the hint would put the map into a state it is already in. */
+export function isRedundantWithState(text, plan) {
+    const t = text.toLowerCase();
+    const current = plan.basemap?.style?.toLowerCase();
+    const aboutBasemap = /\b(?:basemap|base map|map style|satellite (?:view|imagery|basemap|map))\b/.test(t) ||
+        /\b(?:switch|change|set)\s+(?:the\s+)?(?:map\s+)?to\s+(?:satellite|dark|light|streets|engineering)\b/.test(t);
+    if (current && aboutBasemap) {
+        const target = BASEMAP_STYLES.find((s) => new RegExp(`\\b${s}\\b`).test(t));
+        if (target && target === current)
+            return true;
+    }
+    const cam = plan.camera;
+    if (cam && /\bzoom\b/.test(t)) {
+        const zoom = typeof cam.zoom === 'number' ? cam.zoom : undefined;
+        const span = cam.mode === 'fitBounds' && Array.isArray(cam.bounds)
+            ? Math.max(Math.abs(cam.bounds[2] - cam.bounds[0]), Math.abs(cam.bounds[3] - cam.bounds[1]))
+            : undefined;
+        const close = (zoom !== undefined && zoom >= 12) || (span !== undefined && span <= 0.1);
+        const far = cam.mode === 'globalView' || (zoom !== undefined && zoom <= 2) || (span !== undefined && span >= 300);
+        if (/\bzoom\b(?:\s+\w+){0,3}?\s+(?:in|closer)\b/.test(t) && close)
+            return true;
+        if (/\bzoom\b(?:\s+\w+){0,3}?\s+out\b/.test(t) && far)
+            return true;
+    }
+    return false;
+}
+function followupHints(plan, query) {
+    const followups = Array.isArray(plan.followups) ? plan.followups : [];
+    if (!followups.length)
+        return [];
+    const place = placeFromQuery(query);
+    const hints = [];
+    const seen = new Set();
+    for (const f of followups) {
+        const message = typeof f?.message === 'string' ? f.message.trim() : '';
+        const label = typeof f?.label === 'string' && f.label.trim() ? f.label.trim() : message;
+        if (!message)
+            continue;
+        if (isRedundantWithState(`${label} ${message}`, plan))
+            continue;
+        if (MUTATION_RE.test(message)) {
+            if (seen.has(message.toLowerCase()))
+                continue;
+            seen.add(message.toLowerCase());
+            hints.push({ label, argsTemplate: { instruction: message }, tool: 'mutate_map' });
+            continue;
+        }
+        const localized = localizeMessage(message, place);
+        if (!localized || seen.has(localized.toLowerCase()))
+            continue;
+        seen.add(localized.toLowerCase());
+        hints.push({ label: `${label} — new map: "${localized}"`, argsTemplate: { query: localized }, tool: 'build_map' });
+    }
+    return hints;
+}
+/**
+ * next_actions for a freshly built map. `plan` must be the full-resolution
+ * MapPlan the API returned (features inline), `query` the build_map query.
+ */
+export function buildMapNextActions(plan, query) {
+    if (!plan)
+        return [];
+    const layers = (Array.isArray(plan.layers) ? plan.layers : []);
+    const subjectLayers = layers
+        .filter((l) => l && l.role !== 'context' && !l.hideFromLegend && !l.hiddenByDefault)
+        .map((l) => ({ layer: l, count: featuresOf(l).length }))
+        .filter((x) => x.count >= 3)
+        .sort((a, b) => b.count - a.count);
+    // Best hint from each of the busiest layers first (diversity), then a
+    // second hint from the busiest layer if room remains.
+    const perLayer = subjectLayers.map((x) => filterHintsForLayer(x.layer));
+    const filters = [];
+    for (const hs of perLayer)
+        if (hs[0] && filters.length < MAX_FILTER_HINTS)
+            filters.push(hs[0]);
+    for (const hs of perLayer) {
+        for (const h of hs.slice(1))
+            if (filters.length < MAX_FILTER_HINTS)
+                filters.push(h);
+    }
+    const follow = followupHints(plan, query).slice(0, MAX_FOLLOWUP_HINTS);
+    // Best data filter, then the plan's own follow-ups, then the rest — so a
+    // map that has both surfaces both.
+    const out = [...filters.slice(0, 1), ...follow, ...filters.slice(1)];
+    return out.filter((h) => !isRedundantWithState(h.label, plan)).slice(0, MAX_NEXT_ACTIONS);
+}
+/** mutate_map's server-suggested strings → mutate_map hints. */
+export function instructionHints(strings) {
+    return (strings ?? []).slice(0, MAX_NEXT_ACTIONS).map((label) => ({
+        label,
+        argsTemplate: { instruction: label },
+        tool: 'mutate_map',
+    }));
+}

package/dist/tools.js

@@ -23,6 +23,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import { MCP_TOOL_META, mcpRequiresConfirmation } from "./toolMeta.js";
 import { buildAnalysisStory } from "./storyDraft.js";
+import { buildMapNextActions, instructionHints, MAX_NEXT_ACTIONS } from "./nextActions.js";
 import { fetchNoRedirect } from "./fetchNoRedirect.js";
 import { BUILD_MAP_DESCRIPTION, SERVER_INSTRUCTIONS } from "./serverInstructions.js";
 import { describeTolerance, generalizeLayers, storedBytes, WORKSPACE_CEILING } from "./generalizeGeometry.js";
@@ -252,7 +253,7 @@ function generalizedNote(generalized) {
     const parts = generalized.map((g) => `${g.title ?? g.layerId} (${describeTolerance(g.toleranceDeg)})`);
     return `Boundaries simplified to fit the conversation view: ${parts.join(', ')}. Data values are unchanged; the shareable link shows full detail until the map is edited.`;
 }
-function envelope(baseUrl, mapId, workspace, mapPlan, nextActionStrings, extras = {}) {
+function envelope(baseUrl, mapId, workspace, mapPlan, nextActions, extras = {}) {
     const layerCount = Array.isArray(mapPlan?.layers) ? mapPlan.layers.length : 0;
     const opsCount = Array.isArray(workspace?.opsLog) ? workspace.opsLog.length : 0;
     return {
@@ -268,10 +269,9 @@ function envelope(baseUrl, mapId, workspace, mapPlan, nextActionStrings, extras
             layer_count: layerCount,
             last_updated: new Date().toISOString(),
         },
-        next_actions: (nextActionStrings ?? []).slice(0, 3).map((label) => ({
-            label,
-            argsTemplate: { instruction: label },
-        })),
+        next_actions: (nextActions ?? []).every((a) => typeof a === 'string')
+            ? instructionHints(nextActions)
+            : nextActions.slice(0, MAX_NEXT_ACTIONS),
         ...(extras.outOfScope ? { outOfScope: extras.outOfScope } : {}),
         ...(extras.clarification ? { clarification: extras.clarification } : {}),
         ...(extras.opsApplied ? { opsApplied: extras.opsApplied } : {}),
@@ -422,6 +422,30 @@ function withConfirmation(toolName, handler) {
         return handler(rest, extra);
     });
 }
+/**
+ * The error text a failed backend call hands the calling model.
+ *
+ * Live failure (2026-10-12): a build_map came back as Cloudflare's edge error
+ * page (the Worker died before our own handler could answer), and the first
+ * 200 characters of that HTML — `<!DOCTYPE html><!--[if lt IE 7]>…` — were all
+ * the model saw: no error code, no Ray ID to find the request in Workers Logs,
+ * no hint that one retry is the right move. An HTML body is never ours, so say
+ * what it is and keep the two identifiers worth having.
+ */
+export function describeErrorBody(text) {
+    if (!/^\s*(<!DOCTYPE html|<html)/i.test(text))
+        return text.slice(0, 200);
+    const code = text.match(/cf-error-code[^>]*>\s*(\d+)\s*</i)?.[1];
+    const ray = text.match(/Ray ID:?\s*(?:<[^>]+>\s*)*([0-9a-f]{12,})/i)?.[1];
+    const title = text.match(/<title>\s*([^<|]+?)\s*(?:\||<\/title>)/i)?.[1];
+    const parts = [
+        'upstream error page, not a ShowMeOnMap response',
+        code ? `Cloudflare error ${code}` : null,
+        title ?? null,
+        ray ? `Ray ID ${ray}` : null,
+    ].filter(Boolean);
+    return `${parts.join(' · ')}. Transient — retry once.`;
+}
 async function apiFetch(baseUrl, apiKey, path, body) {
     const resp = await fetchNoRedirect(`${baseUrl}${path}`, {
         method: 'POST',
@@ -438,7 +462,7 @@ async function apiFetch(baseUrl, apiKey, path, body) {
     // success (one of four parallel build_map calls lost its map this way,
     // 2026-08-01).
     if (!resp.ok) {
-        throw new Error(`${path} ${resp.status}: ${text.slice(0, 200)}`);
+        throw new Error(`${path} ${resp.status}: ${describeErrorBody(text)}`);
     }
     try {
         return JSON.parse(text);
@@ -470,7 +494,11 @@ async function apiFetch(baseUrl, apiKey, path, body) {
 // own viz reads.
 const SHARE_MAX_VERTICES_PER_RING = 60;
 const SHARE_MAX_POLYS_PER_MULTI = 3;
-const SHARE_MAX_FEATURES_PER_LAYER = 2000;
+// Mirrors saveMapSnapshot: a byte budget for the whole geojsonLayers
+// sidecar replaces the old first-2000-features cut, which shared a
+// row-ordered analysis grid as a strip of the city (audited 2026-10-13).
+const SHARE_MAX_FEATURES_PER_LAYER = 20_000;
+export const SHARE_GEOJSON_BUDGET_BYTES = 4_000_000;
 const SHARE_BASE_KEEP_PROPS = new Set(['value', 'name', 'iso3', 'label', '_dataVintage']);
 function roundCoord(n) {
     return Math.round(n * 10_000) / 10_000;
@@ -514,23 +542,87 @@ function compactGeometry(geom) {
     }
     return geom;
 }
-/** Base whitelist + every field name the layer's viz reads + `_smo_*`
- *  internals (tooltip/popup dispatch). Exported for tests. */
-export function compactFeatureCollection(fc, viz, 
+/** A key that names a feature property: `field`, `valueField`, `fieldX`, … */
+const SHARE_FIELD_KEY = /^field$|Field$|^field[A-Z]/;
+/** Every feature property `node` reads: string values under field-named
+ *  keys at ANY depth, plus `["get", X]` expression refs. Mirrors
+ *  `keepSetForLayer` in src/lib/share/saveMapSnapshot.ts — a top-level-only
+ *  scan stripped the nested `viz.colorScale.field`, so shared opportunity
+ *  grids painted every cell the lowest class (2026-10-13). */
+export function collectReadFields(node, out = new Set()) {
+    if (Array.isArray(node)) {
+        if (node[0] === 'get' && typeof node[1] === 'string')
+            out.add(node[1]);
+        for (const item of node)
+            collectReadFields(item, out);
+        return out;
+    }
+    if (!node || typeof node !== 'object')
+        return out;
+    for (const [k, v] of Object.entries(node)) {
+        if (typeof v === 'string') {
+            if (SHARE_FIELD_KEY.test(k))
+                out.add(v);
+        }
+        else {
+            collectReadFields(v, out);
+        }
+    }
+    return out;
+}
+/** `n` of `items` by a seeded shuffle, returned in original order —
+ *  deterministic, spread over the whole extent, no stride moiré. Mirrors
+ *  `sampleSpread` in src/lib/share/saveMapSnapshot.ts. */
+export function sampleSpread(items, n) {
+    if (items.length <= n)
+        return [...items];
+    if (n <= 0)
+        return [];
+    const idx = Array.from(items, (_, i) => i);
+    let seed = (items.length * 2654435761) >>> 0;
+    const rand = () => {
+        // mulberry32
+        seed = (seed + 0x6d2b79f5) >>> 0;
+        let t = seed;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    for (let i = 0; i < n; i++) {
+        const j = i + Math.floor(rand() * (idx.length - i));
+        [idx[i], idx[j]] = [idx[j], idx[i]];
+    }
+    return idx.slice(0, n).sort((x, y) => x - y).map((i) => items[i]);
+}
+/** Base whitelist + every field the layer reads + `_smo_*` internals
+ *  (tooltip/popup dispatch). `reads` is the layer minus its source (or just
+ *  its viz) — walked at any depth. Exported for tests. */
+export function compactFeatureCollection(fc, reads, 
 /** Fields the layer's filter reads — /api/maps applies it after this strip. */
 filterFields = []) {
-    const keep = new Set([...SHARE_BASE_KEEP_PROPS, ...filterFields]);
-    for (const [k, v] of Object.entries(viz ?? {})) {
-        if (typeof v === 'string' && /(Field|^field[A-Z])/.test(k))
-            keep.add(v);
-    }
-    const features = (fc.features ?? []).slice(0, SHARE_MAX_FEATURES_PER_LAYER).map((f) => ({
+    const keep = collectReadFields(reads, new Set([...SHARE_BASE_KEEP_PROPS, ...filterFields]));
+    const features = sampleSpread(fc.features ?? [], SHARE_MAX_FEATURES_PER_LAYER).map((f) => ({
         ...f,
         geometry: compactGeometry(f.geometry),
         properties: Object.fromEntries(Object.entries(f.properties ?? {}).filter(([k]) => keep.has(k) || k.startsWith('_smo_'))),
     }));
     return { type: fc.type ?? 'FeatureCollection', features };
 }
+/** Shrink every compacted layer by one factor when the sidecar is over
+ *  budget, sampled spread; returns `{kept,total}` for each layer the share
+ *  carries only partly. Exported for tests. */
+export function budgetShareLayers(compacted, totals, budgetBytes = SHARE_GEOJSON_BUDGET_BYTES) {
+    const bytes = JSON.stringify(compacted).length;
+    const scale = bytes > budgetBytes ? budgetBytes / bytes : 1;
+    const sampled = {};
+    for (const [id, fc] of Object.entries(compacted)) {
+        if (scale < 1)
+            fc.features = sampleSpread(fc.features, Math.floor(fc.features.length * scale));
+        if (fc.features.length < (totals[id] ?? 0))
+            sampled[id] = { kept: fc.features.length, total: totals[id] };
+    }
+    return sampled;
+}
 /** Every `field` a predicate tree reads (attribute/temporal leaves). */
 export function predicateFields(predicate, out = []) {
     if (Array.isArray(predicate)) {
@@ -557,14 +649,23 @@ layerFilters) {
     // Callers pass the build query, or an edit's optional rationale label.
     const query = queryOrLabel || mapPlan.title || 'Map';
     const geojsonLayers = {};
+    const totals = {};
+    const temporalField = mapPlan.temporalHint?.field;
     const strippedLayers = mapPlan.layers.map((raw) => {
         const layer = raw;
         if (layer?.source?.kind === 'geojson' && layer.source.data && layer.id) {
-            geojsonLayers[layer.id] = compactFeatureCollection(layer.source.data, layer.viz, predicateFields(layerFilters?.[layer.id]));
+            const data = layer.source.data;
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars -- source carries the data, not field references
+            const { source: _source, ...reads } = layer;
+            totals[layer.id] = data.features?.length ?? 0;
+            geojsonLayers[layer.id] = compactFeatureCollection(data, reads, [...predicateFields(layerFilters?.[layer.id]), ...(typeof temporalField === 'string' ? [temporalField] : [])]);
             return { ...layer, source: { ...layer.source, data: undefined } };
         }
         return layer;
     });
+    // Budget the sidecar; /m/ reads `sampledLayers` and tells the viewer the
+    // copy is a sample — a partial map must never pass as the whole one.
+    const sampled = budgetShareLayers(geojsonLayers, totals);
     const title = mapPlan.title ?? mapPlan.layers[0]?.title ?? 'Untitled Map';
     const body = {
         id: mapId,
@@ -573,6 +674,7 @@ layerFilters) {
         blob: {
             mapPlan: { ...mapPlan, layers: strippedLayers },
             geojsonLayers,
+            ...(Object.keys(sampled).length ? { sampledLayers: sampled } : {}),
             query,
             version: 1,
             ...(story ? { story } : {}),
@@ -638,7 +740,7 @@ async function fetchPublicSnapshot(baseUrl, mapId) {
         return { status: 'deleted', plan: null };
     const text = await resp.text();
     if (!resp.ok)
-        throw new Error(`${path} ${resp.status}: ${text.slice(0, 200)}`);
+        throw new Error(`${path} ${resp.status}: ${describeErrorBody(text)}`);
     const body = JSON.parse(text);
     const plan = body.blob?.mapPlan;
     if (!plan)
@@ -989,11 +1091,10 @@ export function createServer(opts) {
             lastAccessed: Date.now(),
         });
         await store.put(mapId, prepared.entry);
-        const nextActions = [
-            'Filter the layer to features where name is not empty',
-            'Change the basemap to satellite',
-            'Zoom the camera closer',
-        ];
+        // Derived from THIS map: its fields, its basemap/camera, its own
+        // followups — computed on the full-resolution API plan (features
+        // inline), never the generalized stored copy. May be [] (nextActions.ts).
+        const nextActions = buildMapNextActions(resp.mapPlan, query);
         const note = generalizedNote(prepared.generalized);
         return toContent(envelope(baseUrl, mapId, prepared.entry.workspace, prepared.entry.mapPlan, nextActions, { ...(shared ? {} : { shareUnpersisted: true }), ...(note ? { note } : {}) }));
     }));
@@ -2217,7 +2318,7 @@ export function createServer(opts) {
         });
         const text = await resp.text();
         if (!resp.ok)
-            throw new Error(`/api/workflows ${resp.status}: ${text.slice(0, 200)}`);
+            throw new Error(`/api/workflows ${resp.status}: ${describeErrorBody(text)}`);
         const data = JSON.parse(text);
         return toContent({
             ok: true,

package/dist/version.js

@@ -1,3 +1,3 @@
 /** The npm package version, reported to MCP clients in `initialize`. Pinned
  *  equal to package.json by __tests__/tools/registration.test.ts. */
-export const PACKAGE_VERSION = '0.7.0';
+export const PACKAGE_VERSION = '0.7.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@showmeonmap/mcp",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "mcpName": "com.showmeonmap/maps",
   "description": "MCP server for ShowMeOnMap \u2014 geospatial visualization tools for any MCP-speaking agent (Claude Desktop, Cursor, Zed, ChatGPT Apps SDK)",
   "type": "module",