From cd20d592b90be1d89d71b68bf3873f26ac311bcf Mon Sep 17 00:00:00 2001
From: isamu <isamu@to-kyo.to>
Date: Mon, 25 May 2026 14:12:12 +0900
Subject: [PATCH] =?UTF-8?q?feat:=20groupId=20=E2=80=94=20merge=20related?=
 =?UTF-8?q?=20map=20operations=20onto=20one=20shared=20map?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds an optional `groupId` so a host can accumulate several map
operations onto ONE map instead of spawning a card per call.

- types: `groupId?` on MapArgs / MapToolData / MapJsonData (echoed
  through execute + emitted result). Documented as distinct from
  Google Maps' own `mapId` (cloud style id).
- definition: `groupId` tool parameter with LLM guidance — reuse the
  same id for calls that share one map (and for later updates), a new
  id for a separate map.
- systemPrompt: "Grouping operations onto one map" section with a
  worked example.
- View: optional `results` prop — when the host passes the ordered
  group, the View replays the whole sequence onto its single map
  (markers accumulate, directions overlay, center follows the
  latest) and reconstructs that state on remount. Falls back to the
  single `selectedResult` (legacy one-result-per-map) when omitted.
- demo: groups results by `groupId` and renders one merged card per
  group; "Trip A ①→④" samples accumulate on one map, "Trip B" lands
  on a separate card.

Backward compatible: with no `groupId` / no `results`, behaviour is
unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 demo/vue/App.vue       | 53 +++++++++++++++++++++++++++-
 src/core/definition.ts |  5 +++
 src/core/plugin.ts     | 37 +++++++++++++++++---
 src/core/samples.ts    | 52 ++++++++++++++++++++++++++++
 src/core/types.ts      | 12 +++++++
 src/vue/View.vue       | 78 +++++++++++++++++++++++++++++++++++++-----
 6 files changed, 223 insertions(+), 14 deletions(-)

diff --git a/demo/vue/App.vue b/demo/vue/App.vue
index 43c2343..8fd6f84 100644
--- a/demo/vue/App.vue
+++ b/demo/vue/App.vue
@@ -21,7 +21,7 @@
             </span>
           </div>
           <button
-            @click="clearMessages"
+            @click="clearAll"
             class="px-3 py-1.5 text-sm bg-gray-200 text-gray-700 rounded-md hover:bg-gray-300"
           >
             Clear Chat
@@ -112,6 +112,31 @@
             </div>
           </div>
 
+          <!-- Grouped Maps (groupId) — one merged card per groupId.
+               Try the "Trip A ①→④" samples in order: markers + a
+               route accumulate here on ONE map. "Trip B" makes a
+               separate card. -->
+          <div
+            v-for="group in groups"
+            :key="group.groupId"
+            v-show="ViewComponent"
+            class="bg-white rounded-lg shadow-md overflow-hidden"
+          >
+            <div class="p-3 border-b border-gray-200 flex items-center justify-between">
+              <h2 class="text-lg font-semibold text-gray-700">Map: {{ group.groupId }}</h2>
+              <span class="text-xs text-gray-500">{{ group.results.length }} operation(s)</span>
+            </div>
+            <div class="h-96">
+              <component
+                :is="ViewComponent"
+                :results="group.results"
+                :selectedResult="group.results[group.results.length - 1]"
+                :googleMapKey="googleMapKey"
+                :sendTextMessage="handleSendTextMessage"
+              />
+            </div>
+          </div>
+
           <!-- Preview Component -->
           <div v-if="PreviewComponent && result" class="bg-white rounded-lg shadow-md overflow-hidden">
             <div class="p-3 border-b border-gray-200">
@@ -163,10 +188,28 @@ import { ref, computed, nextTick, watch } from "vue";
 import { plugin } from "../../src/vue";
 import { useChat } from "./useChat";
 import type { ToolPlugin, ToolSample, ToolResult } from "gui-chat-protocol/vue";
+import type { MapToolData } from "../../src/core/types";
 
 // Plugin configuration
 const currentPlugin = plugin as unknown as ToolPlugin;
 
+// Grouped maps: results carrying the same `groupId` accumulate into
+// ONE card (markers layer, route overlays) via the View's `results`
+// replay prop. This mirrors what a host (e.g. MulmoClaude) does to
+// merge same-groupId map operations onto one map surface.
+const groups = ref<{ groupId: string; results: ToolResult[] }[]>([]);
+
+const routeToGroup = (toolResult: ToolResult): void => {
+  const groupId = (toolResult.data as MapToolData | undefined)?.groupId;
+  if (!groupId) return;
+  const existing = groups.value.find((g) => g.groupId === groupId);
+  if (existing) {
+    existing.results = [...existing.results, toolResult];
+  } else {
+    groups.value.push({ groupId, results: [toolResult] });
+  }
+};
+
 // Google Map API Key
 const googleMapKey = import.meta.env.VITE_GOOGLE_MAP_KEY || "";
 
@@ -235,9 +278,17 @@ const handleUpdateResult = (updated: ToolResult) => {
   console.log("Result updated:", updated);
 };
 
+const clearAll = () => {
+  clearMessages();
+  groups.value = [];
+};
+
 const executeSample = async (sample: ToolSample) => {
   const toolResult = await executePlugin(sample.args);
   result.value = toolResult;
+  // Route into the grouped-maps section when the sample carries a
+  // groupId (same id → same card accumulates).
+  routeToGroup(toolResult);
 
   // Add messages in correct order for OpenAI API
   const toolCallId = `sample_${Date.now()}`;
diff --git a/src/core/definition.ts b/src/core/definition.ts
index 72af9bd..1ce7cd3 100644
--- a/src/core/definition.ts
+++ b/src/core/definition.ts
@@ -185,6 +185,11 @@ Available actions:
         description:
           "Single character label displayed on the marker when using addMarker.",
       },
+      groupId: {
+        type: "string",
+        description:
+          "Optional grouping key. Reuse the SAME groupId across calls that should appear on ONE shared map — e.g. searching places then drawing a route for the same trip, or later updating that map. Markers accumulate, directions overlay, and the center follows the latest call. Use a NEW groupId to start a separate, unrelated map. Omit for a one-off standalone map. (Unrelated to Google Maps' own map style id.)",
+      },
     },
     required: [],
   },
diff --git a/src/core/plugin.ts b/src/core/plugin.ts
index feaa090..f186b06 100644
--- a/src/core/plugin.ts
+++ b/src/core/plugin.ts
@@ -36,6 +36,10 @@ export const executeMapControl = async (
   args: MapArgs
 ): Promise<ToolResult<MapToolData, MapJsonData>> => {
   const action: MapAction = args.action || DEFAULT_ACTION;
+  // Threaded onto every returned data shape so the host can group
+  // results onto one map. Undefined stays undefined (ungrouped /
+  // legacy single-result behaviour).
+  const groupId = args.groupId;
 
   switch (action) {
     case "showLocation":
@@ -47,7 +51,7 @@ export const executeMapControl = async (
         );
       }
       const location = getLocationFromArgs(args);
-      const data: MapToolData = { action, location };
+      const data: MapToolData = { action, location, groupId };
 
       if (action === "addMarker") {
         data.marker = {
@@ -82,14 +86,14 @@ export const executeMapControl = async (
       }
       return {
         message: `Setting zoom level to ${zoom}`,
-        data: { action, zoom },
+        data: { action, zoom, groupId },
       };
     }
 
     case "clearMarkers": {
       return {
         message: "Clearing all markers from the map",
-        data: { action },
+        data: { action, groupId },
       };
     }
 
@@ -108,6 +112,7 @@ export const executeMapControl = async (
           action,
           searchQuery: args.searchQuery,
           placeType: args.placeType,
+          groupId,
         },
       };
     }
@@ -126,6 +131,7 @@ export const executeMapControl = async (
           origin: args.origin,
           destination: args.destination,
           travelMode,
+          groupId,
         },
       };
     }
@@ -196,13 +202,36 @@ mapControl(action: "getDirections", origin: "Tokyo Station", destination: "Tokyo
 \`\`\`
 Travel modes: DRIVING, WALKING, BICYCLING, TRANSIT
 
+## Grouping operations onto one map (groupId)
+
+By default each call renders its own map. To build ONE map from
+several calls — e.g. show a city, drop several markers, then draw a
+route — pass the SAME \`groupId\` on every related call. Markers
+accumulate, directions overlay, and the center follows the latest
+call, all on a single shared map.
+
+\`\`\`
+mapControl(action: "findPlaces", searchQuery: "ramen", location: "Shibuya", groupId: "tokyo-food-trip")
+mapControl(action: "addMarker", location: "Ichiran Shibuya", groupId: "tokyo-food-trip")
+mapControl(action: "getDirections", origin: "Shibuya Station", destination: "Ichiran Shibuya", travelMode: "WALKING", groupId: "tokyo-food-trip")
+\`\`\`
+
+To update that same map later (move a marker, change the route),
+reuse the same \`groupId\`. To start a separate, unrelated map, use a
+NEW \`groupId\`. Omit \`groupId\` for a one-off standalone map.
+
+Pick a short, descriptive, stable id per logical map (e.g.
+"tokyo-food-trip", "office-commute"). Reusing one id across
+unrelated topics will pile unrelated markers onto one map.
+
 ## Response Data
 
 The map will return JSON data with the results of each action, including:
 - Current center coordinates and zoom level
 - Markers on the map
 - Place search results with ratings and addresses
-- Route information with distance and duration`;
+- Route information with distance and duration
+- The \`groupId\` this result belongs to (echoed back)`;
 
 export const pluginCore: ToolPluginCore<MapToolData, MapJsonData, MapArgs> = {
   toolDefinition: TOOL_DEFINITION,
diff --git a/src/core/samples.ts b/src/core/samples.ts
index d2fccef..586c1da 100644
--- a/src/core/samples.ts
+++ b/src/core/samples.ts
@@ -130,4 +130,56 @@ export const samples: ToolSample[] = [
       travelMode: "DRIVING",
     },
   },
+
+  // groupId samples — click "Trip A ①→④" in order to watch markers
+  // and a route accumulate onto ONE map (they share groupId
+  // "tokyo-food-trip"). "Trip B" uses a different groupId, so in the
+  // grouped-maps demo it renders as a separate card instead of
+  // piling onto the first map.
+  {
+    name: "Trip A ①: center Shibuya",
+    args: {
+      action: "showLocation",
+      location: "Shibuya, Tokyo",
+      groupId: "tokyo-food-trip",
+    },
+  },
+  {
+    name: "Trip A ②: + marker Ichiran",
+    args: {
+      action: "addMarker",
+      location: "Ichiran Shibuya",
+      markerTitle: "Ichiran",
+      markerLabel: "I",
+      groupId: "tokyo-food-trip",
+    },
+  },
+  {
+    name: "Trip A ③: + marker Hachiko",
+    args: {
+      action: "addMarker",
+      location: "Hachiko Statue, Shibuya",
+      markerTitle: "Hachiko",
+      markerLabel: "H",
+      groupId: "tokyo-food-trip",
+    },
+  },
+  {
+    name: "Trip A ④: + walking route",
+    args: {
+      action: "getDirections",
+      origin: "Shibuya Station",
+      destination: "Ichiran Shibuya",
+      travelMode: "WALKING",
+      groupId: "tokyo-food-trip",
+    },
+  },
+  {
+    name: "Trip B: Paris (separate map)",
+    args: {
+      action: "showLocation",
+      location: "Eiffel Tower, Paris",
+      groupId: "paris-day",
+    },
+  },
 ];
diff --git a/src/core/types.ts b/src/core/types.ts
index f4ad913..fc48c48 100644
--- a/src/core/types.ts
+++ b/src/core/types.ts
@@ -158,6 +158,15 @@ export interface DirectionRoute {
   polyline: string;
 }
 
+// `groupId` (shared by the three shapes below) groups related map
+// operations onto ONE map: results carrying the same `groupId`
+// accumulate (markers layer, directions overlay, center follows the
+// latest) instead of each spawning a separate map; a new `groupId`
+// starts a fresh map. The host groups results by this key and
+// replays a group in order onto a single View. Undefined =
+// ungrouped (legacy single-result map). NOT to be confused with
+// Google Maps' own `mapId` (cloud styling id).
+
 // Tool data returned from execute function
 export interface MapToolData {
   action: MapAction;
@@ -169,6 +178,7 @@ export interface MapToolData {
   origin?: string | LatLng;
   destination?: string | LatLng;
   travelMode?: TravelMode;
+  groupId?: string;
 }
 
 // JSON data returned from View component to LLM
@@ -181,6 +191,7 @@ export interface MapJsonData {
   places?: PlaceResult[];
   route?: DirectionRoute;
   error?: string;
+  groupId?: string;
 }
 
 // Arguments passed to the tool
@@ -197,4 +208,5 @@ export interface MapArgs {
   travelMode?: TravelMode;
   markerTitle?: string;
   markerLabel?: string;
+  groupId?: string;
 }
diff --git a/src/vue/View.vue b/src/vue/View.vue
index 1610dd0..28cbe27 100644
--- a/src/vue/View.vue
+++ b/src/vue/View.vue
@@ -151,6 +151,13 @@ import type {
 
 const props = defineProps<{
   selectedResult: ToolResult<MapToolData> | null;
+  // Optional ordered group of results sharing one `groupId`. When the
+  // host provides this, the View replays the whole sequence onto a
+  // single map (markers accumulate, directions overlay, center
+  // follows the latest) and reconstructs that state on remount. When
+  // omitted, the View falls back to the single `selectedResult`
+  // (legacy one-result-per-map behaviour).
+  results?: ToolResult<MapToolData>[] | null;
   googleMapKey?: string | null;
   onUpdateResult?: (jsonData: MapJsonData) => void;
 }>();
@@ -174,9 +181,22 @@ const route = ref<DirectionRoute | null>(null);
 const currentCenter = ref<LatLng | null>(null);
 const currentZoom = ref(15);
 
+// True when the host drives the View with a result group.
+const isGroupMode = (): boolean => Array.isArray(props.results);
+
+// The "current" tool data the header / emit reflect: in group mode
+// it's the last result of the group; otherwise the single result.
+const latestData = computed<MapToolData | undefined>(() => {
+  if (isGroupMode()) {
+    const seq = props.results ?? [];
+    return seq[seq.length - 1]?.data ?? undefined;
+  }
+  return props.selectedResult?.data ?? undefined;
+});
+
 // Computed
 const headerTitle = computed(() => {
-  const action = props.selectedResult?.data?.action;
+  const action = latestData.value?.action;
   const titles: Record<string, string> = {
     showLocation: "Map Location",
     setCenter: "Map View",
@@ -190,7 +210,7 @@ const headerTitle = computed(() => {
 });
 
 const headerSubtitle = computed(() => {
-  const data = props.selectedResult?.data;
+  const data = latestData.value;
   if (!data) return "";
 
   switch (data.action) {
@@ -214,7 +234,7 @@ const showSidePanel = computed(() => {
 });
 
 const fallbackUrl = computed(() => {
-  const data = props.selectedResult?.data;
+  const data = latestData.value;
   if (!data?.location) return "";
   const loc = formatLocation(data.location);
   return `https://www.google.com/maps/search/?api=1&query=${encodeURIComponent(loc)}`;
@@ -258,10 +278,11 @@ const emitResult = (
 ) => {
   if (!props.onUpdateResult) return;
 
-  const data = props.selectedResult?.data;
+  const data = latestData.value;
   const jsonData: MapJsonData = {
     action: data?.action || "showLocation",
     success,
+    groupId: data?.groupId,
     center: currentCenter.value || undefined,
     zoom: currentZoom.value,
     markers: getMarkersData(),
@@ -371,8 +392,13 @@ const initializeMap = async () => {
       currentZoom.value = map.value?.getZoom() || 15;
     });
 
-    // Process initial action if data exists
-    if (props.selectedResult?.data) {
+    // Process initial action(s). In group mode replay the whole
+    // sequence so a remounted card reconstructs the accumulated map;
+    // otherwise apply the single result.
+    if (isGroupMode()) {
+      await syncGroupSequence();
+    } else if (props.selectedResult?.data) {
+      lastProcessedData = JSON.stringify(props.selectedResult.data);
       await handleAction(props.selectedResult.data);
     }
   } catch (err) {
@@ -728,15 +754,15 @@ const zoomOut = () => {
   }
 };
 
-// Track last processed data to avoid re-processing
+// ── Legacy single-result mode ──────────────────────────────────
+// Track last processed data to avoid re-processing the same action.
 let lastProcessedData: string | null = null;
 
-// Watch for result changes
 watch(
   () => props.selectedResult?.data,
   async (newData) => {
+    if (isGroupMode()) return; // group mode is driven by the watcher below
     if (newData && map.value) {
-      // Skip if same data was already processed
       const dataKey = JSON.stringify(newData);
       if (dataKey === lastProcessedData) return;
       lastProcessedData = dataKey;
@@ -745,6 +771,40 @@ watch(
   }
 );
 
+// ── Group replay mode ──────────────────────────────────────────
+// How many of the current group's results have been applied, and
+// which group they belong to. The group is normally append-only, so
+// new results are applied incrementally; if the group identity
+// changes or the list shrinks (a different/rebuilt group), the map
+// is reset and the whole sequence replayed.
+let appliedCount = 0;
+let appliedGroupKey: string | null | undefined;
+
+const syncGroupSequence = async (): Promise<void> => {
+  if (!map.value || !props.results) return;
+  const seq = props.results;
+  const seqGroup = seq[0]?.data?.groupId ?? null;
+  if (seqGroup !== appliedGroupKey || seq.length < appliedCount) {
+    clearAllMarkers();
+    route.value = null;
+    places.value = [];
+    appliedCount = 0;
+    appliedGroupKey = seqGroup;
+  }
+  for (let i = appliedCount; i < seq.length; i++) {
+    const data = seq[i]?.data;
+    if (data) await handleAction(data); // sequential — geocode/route order matters
+  }
+  appliedCount = seq.length;
+};
+
+watch(
+  () => (props.results ?? []).map((r) => JSON.stringify(r.data)).join("
"),
+  async () => {
+    if (isGroupMode() && map.value) await syncGroupSequence();
+  }
+);
+
 // Lifecycle
 onMounted(() => {
   if (props.googleMapKey) {