@tomtom-org/maps-sdk-plugin-agent-toolkit 0.2.6 → 0.2.11

package/dist/index.d.ts

@@ -2,6 +2,9 @@ import { BaseMapModule } from '../../../../map/dist';
 import { BBox } from '../../../../core/dist';
 import { BBox as BBox_2 } from '../../../../../core/dist';
 import { CommonPlaceProps } from '../../../../core/dist';
+import { CustomGeoJSONLayerSpec } from '../../../../map/dist';
+import { CustomGeoJSONModule } from '../../../../map/dist';
+import { FeatureCollection } from 'geojson';
 import { GeometriesModule } from '../../../../map/dist';
 import { GeometryTheme } from '../../../../map/dist';
 import { HillshadeModule } from '../../../../map/dist';
@@ -36,6 +39,28 @@ import { TrafficIncidentsModule } from '../../../../map/dist';
 import { WaypointLike } from '../../../../core/dist';
 import { z } from 'zod';
 
+/**
+ * Options accepted by {@link BYODState.addEntry}.
+ *
+ * @group Agent Toolkit
+ */
+declare type AddBYODEntryOptions = {
+    /**
+     * Explicit MapLibre layer specs. When omitted, the slice inspects the
+     * FeatureCollection and picks defaults by geometry type
+     * (Point → circle, Line → line, Polygon → fill). Mixed-kind entries get
+     * one layer per kind present.
+     */
+    layers?: CustomGeoJSONLayerSpec[];
+    /** Provenance for the data. Defaults to `{ kind: 'integrator' }`. */
+    source?: BYODSource;
+    /**
+     * Semantic entry id. Auto-suffixed (`-2`, `-3`, …) on collision. Defaults
+     * to `byod-N`.
+     */
+    explicitId?: string;
+};
+
 declare type AnalysisOutputFormat = 'json' | 'chart';
 
 /**
@@ -57,7 +82,7 @@ declare type AnalysisOutputFormat = 'json' | 'chart';
  *
  * @group Agent Toolkit
  */
-export declare const BASE_SYSTEM_PROMPT = "You are a helpful map assistant with access to a TomTom interactive map and location services.\nIf a request is completely unrelated to geospatial topics, gracefully decline and steer the user back to map-related tasks you can help with.\n\nCOORDINATE ORDER:\n- All coordinates are [longitude, latitude] (GeoJSON standard)\n- All bounding boxes are [minLng, minLat, maxLng, maxLat]\n\nTOOL EXECUTION:\n- Call context-independent tools in the same step (parallel execution).\n- Many service tools have a show or showOnMap parameter \u2014 use it to display results on the map in one step instead of calling a separate show tool afterward.\n- Use standalone updatePlacesDisplay / updateRoutesDisplay / showWaypoints only when displaying results already in context from a previous step.\n\nSESSION STATE & ENTRIES:\n- Three append-only histories live in the session: `places`, `routes`, `ranges`. Each tool call that produces results stores a new ENTRY (id like `places-3`, `routes-1`, `ranges-0`) \u2014 these ids stay stable and are accepted by every show / recall / processX tool.\n- Each slice has an `entryMode`: `multiple` (default \u2014 overlay several entries on the map) or `single` (only the latest entry stays; switching to it auto-drops every older entry from history). Inspect via `recallState` / `recallPlaces` / `recallRoutes` / `recallRanges`. Flip with `setEntryMode({ slice, mode })` when the user asks to \"only show one at a time\" or \"let me overlay multiple\".\n- Mode is sticky across turns \u2014 under `single`, calling another `discoverPlaces` automatically replaces the previous places entry.\n- Always check `recallX` (or `recallState`) before guessing entry ids; never invent them.\n\nLOCATION REFERENCE:\n- \"near me\" / \"my location\" / \"where I am\" \u2192 getCurrentLocation (user's physical GPS position, may prompt permission)\n- \"in this area\" / \"here on the map\" / \"near the map center\" \u2192 getViewport (map's current view)\n- If getCurrentLocation fails due to permission denial, fall back to getViewport as the reference point\n\nRESPONSE FORMATTING:\n- Use markdown in all responses\n- Show key information in bold\n- Use bullet lists when presenting multiple items or results\n- Keep responses concise \u2014 lead with the most relevant information\n\n";
+export declare const BASE_SYSTEM_PROMPT = "You are a helpful map assistant with access to a TomTom interactive map and location services.\nIf a request is completely unrelated to geospatial topics, gracefully decline and steer the user back to map-related tasks you can help with.\n\nCOORDINATE ORDER:\n- All coordinates are [longitude, latitude] (GeoJSON standard)\n- All bounding boxes are [minLng, minLat, maxLng, maxLat]\n\nTOOL EXECUTION:\n- Call context-independent tools in the same step (parallel execution).\n- Many service tools have a show or showOnMap parameter \u2014 use it to display results on the map in one step instead of calling a separate show tool afterward.\n- Use standalone updatePlacesDisplay / updateRoutesDisplay / updateWaypointsDisplay only when displaying results already in context from a previous step.\n\nSESSION STATE & ENTRIES:\n- Seven append-only histories live in the session: `places`, `routes`, `ranges`, `customGeometries`, `trafficAreaAnalytics`, `trafficIncidents`, `byod`. Each tool call that produces results stores a new ENTRY (id like `places-3`, `routes-1`, `byod-0`) \u2014 these ids stay stable and are accepted by every show / recall / `processData` / `analyseData` tool via the matching `*EntryIDs` field.\n- Each slice has an `entryMode`: `multiple` (default \u2014 overlay several entries on the map) or `single` (only the latest entry stays; switching to it auto-drops every older entry from history). Inspect via `recallState` / `recallPlaces` / `recallRoutes` / `recallRanges` / `recallGeometries` / `recallByod` (traffic slices surface via `recallState`). Flip with `setEntryMode({ slice, mode })` when the user asks to \"only show one at a time\" or \"let me overlay multiple\".\n- Mode is sticky across turns \u2014 under `single`, calling another `discoverPlaces` automatically replaces the previous places entry.\n- Always check `recallX` (or `recallState`) before guessing entry ids; never invent them.\n\nLOCATION REFERENCE:\n- \"near me\" / \"my location\" / \"where I am\" \u2192 getCurrentLocation (user's physical GPS position, may prompt permission)\n- \"in this area\" / \"here on the map\" / \"near the map center\" \u2192 getViewport (map's current view)\n- If getCurrentLocation fails due to permission denial, fall back to getViewport as the reference point\n\nRESPONSE FORMATTING:\n- Use markdown in all responses\n- Show key information in bold\n- Use bullet lists when presenting multiple items or results\n- Keep responses concise \u2014 lead with the most relevant information\n\n";
 
 /**
  * State for base map display: style, language, viewport, layers, and hillshade.
@@ -80,6 +105,122 @@ declare class BaseMapState implements StateSlice {
 
 /* Excluded from this release type: buildSystemPrompt */
 
+/**
+ * A single entry in the BYOD (bring-your-own-data) GeoJSON history. Each entry
+ * is a customer-authored layer the agent can read, render, query, or pipe
+ * through analyseData / processData.
+ *
+ * @group Agent Toolkit
+ */
+export declare type BYODEntry = {
+    id: string;
+    timestamp: number;
+    label: string;
+    data: FeatureCollection;
+    /** Provenance for the data — used by recall tools and the UI. */
+    source: BYODSource;
+    /**
+     * MapLibre layer specs the slice will render this entry under. When omitted
+     * at `addEntry` time the slice fills this in with sensible defaults based
+     * on the entry's geometry types (Point → circle, Line → line, Polygon → fill).
+     */
+    layers: CustomGeoJSONLayerSpec[];
+    /**
+     * Per-entry CustomGeoJSONModule. Each entry owns its own module so display state
+     * (currently-rendered feature set, visibility) lives on the entry instead of a
+     * shared slice-level module. Lazy-initialised via BYODState helpers.
+     */
+    _module?: CustomGeoJSONModule;
+    /** True while this entry's `_module` is rendering on the map. */
+    _shown?: boolean;
+};
+
+/**
+ * Where a BYOD entry came from.
+ * - `integrator`: seeded programmatically by the embedding app (e.g. user-uploaded file).
+ * - `url`: fetched from a URL via `addByodLayer`.
+ * - `inline`: passed as inline GeoJSON via `addByodLayer`.
+ *
+ * @group Agent Toolkit
+ */
+export declare type BYODSource = {
+    kind: 'integrator';
+    description?: string;
+} | {
+    kind: 'url';
+    url: string;
+} | {
+    kind: 'inline';
+    description?: string;
+};
+
+/**
+ * State slice for BYOD (bring-your-own-data) GeoJSON layers — customer-owned
+ * data that doesn't fit places / routes / ranges / custom-geometries. Each
+ * entry wraps a {@link CustomGeoJSONModule} so the agent can render, query,
+ * and pipe it through analyseData / processData.
+ *
+ * Per-entry display model mirrors {@link CustomGeometriesState}: every entry
+ * owns its own module, lazy-initialised on first show.
+ *
+ * @group Agent Toolkit
+ */
+declare class BYODState implements ShownEntriesSlice, StateSlice {
+    private readonly _ttMap;
+    private _entries;
+    private _entryMode;
+    /** Subscribe to state changes — see {@link BYODStateEvents}. */
+    readonly events: StateEvents<BYODStateEvents>;
+    constructor(_ttMap: TomTomMap);
+    get entries(): readonly BYODEntry[];
+    get latestEntry(): BYODEntry | undefined;
+    /** Set of BYOD entry ids currently rendered on the map. */
+    get shownEntryIds(): ReadonlySet<string>;
+    get entryMode(): EntryMode;
+    setEntryMode(mode: EntryMode): Promise<void>;
+    findById(entryId: string): BYODEntry | undefined;
+    /**
+     * Append a new BYOD entry. Under `single` mode the new entry replaces every older one (hides
+     * + drops them before the new entry is pushed, so the caller never sees the new entry
+     * rendered on top of a still-visible old one). Returns the assigned id.
+     */
+    addEntry(data: FeatureCollection, label: string, options?: AddBYODEntryOptions): Promise<string>;
+    /**
+     * Lazy-init the entry's CustomGeoJSONModule. The module is created with a
+     * single source named `data`, configured with this entry's `layers`. Layer
+     * changes after creation are not supported — drop the entry and add it back
+     * to swap layers.
+     */
+    getEntryModule(entryId: string): Promise<CustomGeoJSONModule>;
+    /** Render this entry on the map. */
+    showEntry(entryId: string): Promise<void>;
+    private _hideOthersUnderSingleMode;
+    hideEntry(entryId: string): Promise<void>;
+    /** Drop a single entry from history (clears its module first). No-op when unknown. */
+    removeEntry(entryId: string): Promise<void>;
+    private _requireEntry;
+    /**
+     * Hide every BYOD layer currently on the map. Map-only — history is kept.
+     * Implements {@link ClearableMapSlice}.
+     */
+    clearShown(): Promise<void>;
+    reset(): void;
+}
+
+/**
+ * Events fired by {@link BYODState}. Subscribe via `state.byod.events.on(type, handler)`.
+ *
+ * @group Agent Toolkit
+ */
+declare type BYODStateEvents = {
+    /** History changed — entry added, removed, or cleared via `reset()`. */
+    'entries-change': readonly BYODEntry[];
+    /** Set of entries currently rendered on the map changed. */
+    'shown-change': ReadonlySet<string>;
+    /** Display policy switched between `single` and `multiple`. */
+    'mode-change': EntryMode;
+};
+
 /**
  * Result returned by {@link classifyUserIntent}.
  *
@@ -88,6 +229,14 @@ declare class BaseMapState implements StateSlice {
 export declare type ClassificationResult = {
     /** Tool names selected by the classifier. */
     activeToolNames: string[];
+    /**
+     * Optional per-tool scope. Keyed by tool name, value is the raw classifier
+     * output for that tool — validated against the tool's `scopeSchema` in
+     * `prepareStep` before any narrowing is applied. Tools without
+     * `scopeSchema`, or for which the classifier omitted a scope, retain
+     * their full description and inputSchema for the turn.
+     */
+    toolScopes?: Record<string, unknown>;
     /** Wall-clock time in ms for the classification step only (not the agent response). */
     timeMs: number;
     /** Token usage for the classification LLM call. */
@@ -219,7 +368,7 @@ export declare const createMapAgent: <CS extends ToolState = ToolState>(map: Tom
 
 /**
  * A single aggregation/analysis result attached to a custom-geometries entry.
- * Produced by the `analyseGeometries` tool; `data` is whatever the dynamic code returned.
+ * Produced by `analyseData`; `data` is whatever the dynamic code returned.
  *
  * @group Agent Toolkit
  */
@@ -236,9 +385,9 @@ export declare type CustomGeometriesAnalysis = {
 };
 
 /**
- * A single entry in the custom-geometries history — output of
- * processGeometries (and any future polygon-producing tool that doesn't
- * naturally belong to places or ranges).
+ * A single entry in the custom-geometries history — output of `processData`
+ * (and any future polygon-producing tool that doesn't naturally belong to
+ * places or ranges).
  *
  * @group Agent Toolkit
  */
@@ -265,7 +414,7 @@ export declare type CustomGeometriesEntry = {
 };
 
 /**
- * State for derived / custom geometries — output of `processGeometries` and any future
+ * State for derived / custom geometries — output of `processData` and any future
  * polygon-producing tool whose result doesn't belong to a place or a reachable-range entry.
  *
  * Each entry owns a dedicated GeometriesModule, lazy-initialised on first show, mirroring
@@ -297,7 +446,7 @@ declare class CustomGeometriesState implements ShownEntriesSlice, StateSlice {
      * Append a new entry. If `explicitId` collides, the slice auto-suffixes (`-2`, `-3`, ...).
      * Returns the assigned id. Under `single` mode the new entry replaces every older one.
      */
-    addEntry(features: PolygonFeature<CommonPlaceProps>[], provenance: CustomGeometriesEntry['provenance'], label: string, explicitId?: string): string;
+    addEntry(features: PolygonFeature<CommonPlaceProps>[], provenance: CustomGeometriesEntry['provenance'], label: string, explicitId?: string): Promise<string>;
     /** Attach an analysis to an existing entry (replace if a result of the same name exists). */
     addAnalysisToEntry(entryId: string, analysis: CustomGeometriesAnalysis): boolean;
     /** Lazy-init the entry's GeometriesModule, applying / re-applying the requested theme. */
@@ -319,7 +468,11 @@ declare class CustomGeometriesState implements ShownEntriesSlice, StateSlice {
     /** Drop a single entry from history (clears its module first). No-op when unknown. */
     removeEntry(entryId: string): Promise<void>;
     private _requireEntry;
-    private _uniqueEntryId;
+    /**
+     * Hide every custom-geometries entry currently on the map. Map-only — history is kept.
+     * Implements {@link ClearableMapSlice}.
+     */
+    clearShown(): Promise<void>;
     reset(): void;
 }
 
@@ -343,6 +496,57 @@ declare type CustomGeometriesStateEvents = {
     'mode-change': EntryMode;
 };
 
+/**
+ * Mapping from {@link DataEntryKind} (LLM-facing name) to the {@link ToolState} slice key
+ * that owns the entries for that kind. Used by `createMapAgent` to apply `entryMode` from
+ * `dataEntries[kind].entryMode` to the right slice.
+ *
+ * @group Agent Toolkit
+ */
+export declare const DATA_ENTRY_KIND_TO_SLICE: {
+    readonly places: "places";
+    readonly routes: "routing";
+    readonly incidents: "trafficIncidents";
+    readonly customGeometries: "customGeometries";
+    readonly trafficAreaAnalytics: "trafficAreaAnalytics";
+    readonly byod: "byod";
+    readonly ranges: "ranges";
+};
+
+/**
+ * Per-kind configuration accepted by `createMapAgent`'s `dataEntries` option.
+ *
+ * @group Agent Toolkit
+ */
+export declare type DataEntryConfig = {
+    /**
+     * When `false`, the kind is removed from the agent's tool surface entirely:
+     * - the kind disappears from `analyseData` / `processData` scope and input fields;
+     * - related recall / display / fetch tools are dropped from the registry
+     *   (see {@link TOOLS_BY_DATA_ENTRY_KIND}).
+     *
+     * Default: `true`.
+     */
+    enabled?: boolean;
+    /**
+     * Initial entry-display policy for the underlying slice. `single` keeps only the latest
+     * entry on the map (others auto-hide); `multiple` (default) lets several coexist.
+     */
+    entryMode?: EntryMode;
+};
+
+/**
+ * Data-entry kind names — the vocabulary used by `dataEntries` on `createMapAgent`. Superset
+ * of the analyse/process input kinds (`EntryDataKind`) — adds `ranges`, which has its own
+ * entry-mode-supporting slice but is not a top-level input kind for those tools.
+ *
+ * The kind names are LLM-facing (`routes`, `incidents`) rather than slice names (`routing`,
+ * `trafficIncidents`); the slice mapping is internal — see {@link DATA_ENTRY_KIND_TO_SLICE}.
+ *
+ * @group Agent Toolkit
+ */
+export declare type DataEntryKind = 'places' | 'routes' | 'incidents' | 'customGeometries' | 'trafficAreaAnalytics' | 'byod' | 'ranges';
+
 /**
  * Default tool set for the agent toolkit. Each entry is a {@link ToolDefinition}
  * — either a static `ToolEntry` or a `ToolEntryBuilder` that tailors the tool to
@@ -357,19 +561,14 @@ export declare const DEFAULT_TOOLS: {
     locatePlace: ToolDefinition;
     reverseGeocode: ToolDefinition;
     discoverPlaces: ToolDefinition;
-    processPlaces: ToolDefinition;
-    processGeometries: ToolDefinition;
-    processRoutes: ToolDefinition;
-    analyseGeometries: ToolDefinition;
-    analysePlaces: ToolDefinition;
-    analyseRoutes: ToolDefinition;
+    processData: ToolDefinition;
+    analyseData: ToolDefinition;
     setRoute: ToolDefinition;
     addWaypointsToRoute: ToolDefinition;
     removeWaypointsFromRoute: ToolDefinition;
     replaceWaypointInRoute: ToolDefinition;
     getPOICategoryCodes: ToolDefinition;
     getTrafficIncidents: ToolDefinition;
-    analyseIncidents: ToolDefinition;
     focusIncidents: ToolDefinition;
     startTrafficIncidentsMonitor: ToolDefinition;
     stopTrafficIncidentsMonitor: ToolDefinition;
@@ -377,28 +576,26 @@ export declare const DEFAULT_TOOLS: {
     queryTrafficAnalytics: ToolDefinition;
     updatePlacesDisplay: ToolDefinition;
     updateRoutesDisplay: ToolDefinition;
-    showTrafficAreaAnalytics: ToolDefinition;
-    showWaypoints: ToolDefinition;
-    getShownPlaces: ToolDefinition;
-    getShownRoutes: ToolDefinition;
-    getShownWaypoints: ToolDefinition;
-    getShownRouteTrafficIncidents: ToolDefinition;
-    getShownIncidents: ToolDefinition;
+    updateTrafficAreaAnalyticsDisplay: ToolDefinition;
+    updateWaypointsDisplay: ToolDefinition;
+    getShownTileIncidents: ToolDefinition;
     clearMap: ToolDefinition;
     flyTo: ToolDefinition;
     getViewport: ToolDefinition;
     recallGeometries: ToolDefinition;
     recallPlaces: ToolDefinition;
+    recallByod: ToolDefinition;
+    addByodLayer: ToolDefinition;
+    updateByodDisplay: ToolDefinition;
     recallRoutes: ToolDefinition;
     getCurrentWaypoints: ToolDefinition;
     getStandardMapStyles: ToolDefinition;
     setMapStandardStyle: ToolDefinition;
-    setRouteTheme: ToolDefinition;
     setLanguage: ToolDefinition;
-    toggleBaseMapLayerGroups: ToolDefinition;
-    togglePOIs: ToolDefinition;
-    toggleTrafficFlow: ToolDefinition;
-    toggleTrafficIncidents: ToolDefinition;
+    toggleTilesBaseMapLayerGroups: ToolDefinition;
+    toggleTilesPOIs: ToolDefinition;
+    toggleTilesTrafficFlow: ToolDefinition;
+    toggleTilesTrafficIncidents: ToolDefinition;
     getMapStyleLayers: ToolDefinition;
     setLayoutProperties: ToolDefinition;
     setPaintProperties: ToolDefinition;
@@ -417,6 +614,31 @@ export declare const DEFAULT_TOOLS: {
     setEntryMode: ToolDefinition;
 };
 
+/**
+ * Runtime enumeration of slice names that support entry mode. The `satisfies` clause
+ * makes drift a compile error: when a new {@link ToolState} slice gains `setEntryMode`,
+ * this constant has to be updated before the package will build.
+ *
+ * @group Agent Toolkit
+ */
+export declare const ENTRY_MODE_SLICE_NAMES: readonly EntryModeSliceName[];
+
+/**
+ * Tool-facing union of state slices that own analysable entries — the
+ * vocabulary used by tools that read from multiple slices (`analyseData`,
+ * `processData`) and by the classifier when proposing per-call scope.
+ *
+ * Distinct from {@link EntryModeSliceName}, which uses the literal state-slice
+ * keys (`routing`, `trafficIncidents`, …) for state-level operations.
+ *
+ * `ranges` is intentionally excluded: it feeds the analysis/processing tools
+ * only via `geometriesEntryIDs` (its isochrone polygons), not as a direct
+ * top-level input.
+ *
+ * @group Agent Toolkit
+ */
+export declare type EntryDataKind = 'places' | 'routes' | 'incidents' | 'customGeometries' | 'trafficAreaAnalytics' | 'byod';
+
 /**
  * Per-slice display policy. With `multiple` (default) several history entries can be on the
  * map at once; with `single` only the most recent one stays. Switching from `multiple` to
@@ -427,6 +649,38 @@ export declare const DEFAULT_TOOLS: {
  */
 export declare type EntryMode = 'single' | 'multiple';
 
+/**
+ * State slice that owns a history of entries and can be driven into `single` or `multiple`
+ * mode. Every {@link ToolState} slice with `setEntryMode` implements this shape, which lets
+ * callers (the `setEntryMode` tool, `createMapAgent`'s `dataEntries` option, …) handle the
+ * whole family uniformly without listing slice names.
+ *
+ * @group Agent Toolkit
+ */
+export declare interface EntryModeSlice {
+    readonly entryMode: EntryMode;
+    readonly entries: readonly {
+        readonly id: string;
+    }[];
+    setEntryMode(mode: EntryMode): Promise<void>;
+}
+
+/**
+ * Compile-time union of {@link ToolState} keys whose slice supports {@link EntryMode}.
+ * Names match the {@link ToolState} keys exactly — `routing` (not `routes`),
+ * `customGeometries` (not `geometries`) — so the slice name in the tool API never drifts
+ * from the property on `state`.
+ *
+ * Auto-grows when a new slice implements `setEntryMode`: the union picks up the new key,
+ * and the runtime list {@link ENTRY_MODE_SLICE_NAMES} fails to type-check until the key
+ * is added there too.
+ *
+ * @group Agent Toolkit
+ */
+export declare type EntryModeSliceName = {
+    [K in keyof ToolState]: ToolState[K] extends EntryModeSlice ? K : never;
+}[keyof ToolState];
+
 /**
  * Extracts the text content of the last user message in a message array.
  * Returns null if no user message is found or if content has no text.
@@ -471,7 +725,7 @@ export declare const formatStateDigestDiff: (prev: StateDigest, next: StateDiges
 export declare type GeometriesId = z.infer<typeof geometriesIdSchema>;
 
 /** Possible kinds in a geometries id. */
-export declare type GeometriesIdKind = 'place' | 'places' | 'ranges' | 'custom';
+export declare type GeometriesIdKind = 'place' | 'places' | 'ranges' | 'customGeometries';
 
 /**
  * Tagged geometries id. The Zod schema is exposed so tools can plug it
@@ -490,7 +744,7 @@ export declare const geometriesIdSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"ranges">;
     id: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
-    kind: z.ZodLiteral<"custom">;
+    kind: z.ZodLiteral<"customGeometries">;
     id: z.ZodString;
 }, z.core.$strip>], "kind">;
 
@@ -500,7 +754,7 @@ export declare const geometriesIdSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
  * ids in the same form `geometriesEntryIDs` accepts: `{ kind: 'place' }` for
  * a single place footprint, `{ kind: 'places' }` for every footprint in a
  * places entry, `{ kind: 'ranges' }` for an isochrone entry,
- * `{ kind: 'custom' }` for a derived entry. `operation` is a short label for
+ * `{ kind: 'customGeometries' }` for a derived entry. `operation` is a short label for
  * the kind of computation that produced the entry (e.g. `'union'`, `'buffer'`,
  * `'h3-coverage'`).
  *
@@ -513,6 +767,18 @@ export declare type GeometryProvenance = {
     sourceIds: readonly GeometriesId[];
 };
 
+/**
+ * Returns each default tool's `examplePrompts` keyed by tool name. Builders are
+ * materialised with empty {@link ToolBuildOptions} so the prompts reflect the
+ * tool's default (full-surface) shape. Tools without prompts map to `[]`.
+ *
+ * Surface these in chat UIs to keep starter suggestions in sync with what the
+ * tools can actually do — the registry stays the single source of truth.
+ *
+ * @group Agent Toolkit
+ */
+export declare const getDefaultToolPrompts: () => Record<ToolName, readonly string[]>;
+
 /**
  * Snapshot the user-visible state surface. Call after every assistant turn (to record the
  * "agent-known" baseline) and again before each user prompt (to detect what changed since).
@@ -660,11 +926,11 @@ declare class IncidentsAnalyses {
 
 /**
  * A single aggregation/analysis result attached to a traffic-incidents entry.
- * Produced by the `analyseIncidents` tool; `data` is whatever the dynamic code returned.
+ * Produced by `analyseData` (one-shot or `monitor`-rerun); `data` is whatever the dynamic code returned.
  *
  * @group Agent Toolkit
  */
-declare type IncidentsAnalysis = {
+export declare type IncidentsAnalysis = {
     /** Unique name within the parent entry (used as a key for future UI). */
     name: string;
     timestamp: number;
@@ -677,8 +943,8 @@ declare type IncidentsAnalysis = {
 };
 
 /**
- * A registered, re-executing analysis. Produced by `analyseIncidents`; replayed by
- * an entry's {@link IncidentsAnalyses} on every monitor-tick of its source.
+ * A registered, re-executing analysis. Produced by `analyseData` with `monitor: { entryId }`;
+ * replayed by an entry's {@link IncidentsAnalyses} on every monitor-tick of its source.
  *
  * @group Agent Toolkit
  */
@@ -782,6 +1048,31 @@ export declare type MapAgentOptions<CS extends ToolState = ToolState> = {
      * Accessible in custom tool `execute` via the state parameter.
      */
     state?: Omit<CS, keyof ToolState>;
+    /**
+     * Per-kind data-entry configuration. Each {@link DataEntryKind} accepts
+     * `{ enabled?, entryMode? }`. Setting `enabled: false` removes the kind from the
+     * agent's tool surface entirely — it disappears from `analyseData` / `processData`
+     * scope and input fields, and the slice-specific recall / display / fetch tools
+     * are dropped from the registry. `entryMode` is applied to the underlying slice
+     * right after the agent state is built — before any tool runs.
+     *
+     * Keys are LLM-facing kind names (`routes`, `incidents`) — not slice names
+     * (`routing`, `trafficIncidents`). The slice mapping is internal.
+     *
+     * @example
+     * ```typescript
+     * createMapAgent(map, {
+     *     model: openai('gpt-4o'),
+     *     dataEntries: {
+     *         routes: { entryMode: 'single' },
+     *         incidents: { entryMode: 'single' },
+     *         byod: { enabled: false }, // disables recallByod, addByodLayer, updateByodDisplay + byod scope on analyse/process
+     *         ranges: { enabled: false }, // disables findReachableAreas + recallRanges
+     *     },
+     * });
+     * ```
+     */
+    dataEntries?: Partial<Record<DataEntryKind, DataEntryConfig>>;
     /**
      * Pluggable classifier for automatic tool selection.
      * - Omit to use the default LLM-based classifier (uses main model)
@@ -876,7 +1167,7 @@ export declare type MonitoredArea = {
 
 /**
  * A single aggregation/analysis result attached to a places entry.
- * Produced by the `analysePlaces` tool; `data` is whatever the dynamic code returned.
+ * Produced by `analyseData`; `data` is whatever the dynamic code returned.
  *
  * @group Agent Toolkit
  */
@@ -907,7 +1198,7 @@ export declare type PlacesEntry = {
     /**
      * Boundary polygons attached to this entry. One feature per place that has a geometry data
      * source (populated lazily via PlacesState.fetchPlaceGeometry), or a standalone result list
-     * produced by tools like processGeometries. Each feature's `id` is the geometry-data-source id
+     * produced by tools like `processData`. Each feature's `id` is the geometry-data-source id
      * (`place.properties.dataSources.geometry.id`), matching the response shape of `geometryData`.
      */
     geometries?: PolygonFeature<CommonPlaceProps>[];
@@ -918,14 +1209,13 @@ export declare type PlacesEntry = {
     /** Lazy place-id → boundary polygon index, built on first lookup through PlacesState.getGeometryForPlace. */
     _geometryByPlaceId?: Record<string, PolygonFeature<CommonPlaceProps>>;
     /**
-     * Per-entry display modules. Each entry owns its own PlacesModule per marker theme and a
-     * dedicated GeometriesModule, so display state lives on the entry rather than on a shared
-     * slice-level module. Lazy-initialised via PlacesState helpers — undefined until first show.
+     * Per-entry display modules. An entry is rendered under at most one marker theme at a time,
+     * so a single PlacesModule covers all themes — `_showEntryAs` rethemes it via `applyTheme`.
+     * A dedicated GeometriesModule renders the entry's boundary polygons.
+     * Lazy-initialised via PlacesState helpers — undefined until first show.
      */
     _modules?: {
-        pin?: PlacesModule;
-        baseMap?: PlacesModule;
-        pinClustered?: PlacesModule;
+        places?: PlacesModule;
         geometries?: GeometriesModule;
     };
     /** The marker theme currently rendering this entry, or undefined when hidden. */
@@ -939,10 +1229,10 @@ declare type PlacesMarkerType = 'pin' | 'base-map' | 'pin-clustered';
  * State for the places layer: an append-only history of place results plus per-entry display
  * modules.
  *
- * Each entry owns its own PlacesModule (per marker theme: pin / base-map / pin-clustered) and
- * a dedicated GeometriesModule, lazy-initialised on first show. The slice no longer holds
- * shared modules — display state lives on the entry, so two entries can be rendered side by
- * side under different themes without sharing a single source.
+ * Each entry owns a single PlacesModule (rethemed in-place via `applyTheme` when the marker
+ * type changes — an entry only renders under one theme at a time) and a dedicated
+ * GeometriesModule, lazy-initialised on first show. Display state lives on the entry, so two
+ * entries can be rendered side by side under different themes without sharing a single source.
  *
  * @group Agent Toolkit
  */
@@ -966,9 +1256,9 @@ declare class PlacesState implements StateSlice {
      */
     setEntryMode(mode: EntryMode): Promise<void>;
     /**
-     * Lazy-init and return the entry's PlacesModule for the given marker theme. Each entry
-     * keeps a separate module per theme so flipping themes for one entry doesn't disturb
-     * another. Throws when the entry id is unknown.
+     * Lazy-init and return the entry's PlacesModule, rethemed to `markerType`. An entry only
+     * ever renders under one theme at a time, so the same module is reused — flipping themes
+     * calls `applyTheme` in place. Throws when the entry id is unknown.
      */
     getEntryPlacesModule(entryId: string, markerType: PlacesMarkerType): Promise<PlacesModule>;
     /**
@@ -983,8 +1273,7 @@ declare class PlacesState implements StateSlice {
      * so we assume the most recent entry is the relevant one to show on the map.
      */
     get latestPlace(): Place[] | undefined;
-    addPlaceResult(place: Place | Places, label: string, explicitId?: string, connections?: PlaceConnectionDisplay[], geometries?: PolygonFeature<CommonPlaceProps>[]): string;
-    private _uniqueEntryId;
+    addPlaceResult(place: Place | Places, label: string, explicitId?: string, connections?: PlaceConnectionDisplay[], geometries?: PolygonFeature<CommonPlaceProps>[]): Promise<string>;
     /**
      * Attach an analysis result to an existing entry. Analysis names are unique
      * within a single entry — adding one with an existing name replaces it.
@@ -1062,6 +1351,11 @@ declare class PlacesState implements StateSlice {
     removeShownEntries(ids: readonly string[]): Promise<Place[]>;
     /** Clear everything from the map (does not touch entries history). */
     clearShownEntries(): Promise<void>;
+    /**
+     * Hide every PlacesState rendering — pins AND attached boundary polygons. Map-only:
+     * history (`entries`) is untouched. Implements {@link ClearableMapSlice}.
+     */
+    clearShown(): Promise<void>;
     clearShownGeometries(ids?: readonly string[]): Promise<void>;
     /**
      * Drop a single entry from history. Hides it from the map first (clears every theme module
@@ -1192,7 +1486,12 @@ declare class RangeState implements ShownEntriesSlice {
     private _requireEntry;
     get entries(): readonly RangesEntry[];
     get latestEntry(): RangesEntry | undefined;
-    addEntry(entry: Omit<RangesEntry, 'id' | 'timestamp'>): string;
+    addEntry(entry: Omit<RangesEntry, 'id' | 'timestamp'>): Promise<string>;
+    /**
+     * Hide every reachable-range entry currently on the map. Map-only — history is kept.
+     * Implements {@link ClearableMapSlice}.
+     */
+    clearShown(): Promise<void>;
     reset(): void;
 }
 
@@ -1268,7 +1567,7 @@ export declare type RouteParams = {
 
 /**
  * A single aggregation/analysis result attached to a routes entry.
- * Produced by the `analyseRoutes` tool; `data` is whatever the dynamic code returned.
+ * Produced by `analyseData`; `data` is whatever the dynamic code returned.
  *
  * @group Agent Toolkit
  */
@@ -1325,11 +1624,16 @@ declare class RoutingState implements ShownEntriesSlice {
     private _planningSlots;
     private _params;
     private _entryMode;
+    /**
+     * Slice-level "main color" applied to every RoutingModule on first show / re-show. Sticky
+     * across entry swaps so the rendered route always uses the most recently requested color.
+     * Set via {@link setMainColor}; persists for the lifetime of the slice (cleared on `reset`).
+     */
+    private _mainColor?;
     /**
      * The most recently `.showEntry`-ed id. Tracks "who was last brought up" so tools that
-     * operate on the focused module (`set-route-theme`, `get-shown-routes`, …) have a single
-     * pointer to read; the authoritative shown set is `shownEntryIds` (derived from each
-     * entry's `_shown` flag).
+     * operate on the focused module have a single pointer to read; the authoritative shown
+     * set is `shownEntryIds` (derived from each entry's `_shown` flag).
      */
     private _lastShownEntryId?;
     /** Subscribe to state changes — see {@link RoutingStateEvents}. */
@@ -1364,6 +1668,15 @@ declare class RoutingState implements ShownEntriesSlice {
      * Emits `shown-change` once the new entry is up.
      */
     showEntry(entryId: string): Promise<void>;
+    /** Slice-level main color persisted across entry swaps. Undefined when no theme has been set. */
+    get mainColor(): string | undefined;
+    /**
+     * Set the slice-level main color. The colour is applied immediately to every currently-shown
+     * entry's RoutingModule and remembered so that subsequent {@link showEntry} calls apply it
+     * automatically. Pass `undefined` to clear the sticky theme — currently-shown modules keep
+     * their last paint until they're re-shown (MapLibre style restore handles full revert).
+     */
+    setMainColor(color: string | undefined): void;
     /**
      * Hide the entry's routes + waypoints on its module (clear; the module stays cached).
      * No-op when the entry is unknown or already hidden.
@@ -1376,9 +1689,8 @@ declare class RoutingState implements ShownEntriesSlice {
     removeEntry(entryId: string): Promise<void>;
     private _requireEntry;
     /**
-     * RoutingModule of the most-recently-shown entry, if any. Tools that operate on the
-     * "focused route" (e.g. setRouteTheme, getShownRoutes) read off it. Returns undefined
-     * when no entry is currently shown.
+     * RoutingModule of the most-recently-shown entry, if any. Returns undefined when no
+     * entry is currently shown.
      */
     get currentEntryModule(): RoutingModule | undefined;
     get entries(): readonly RoutesEntry[];
@@ -1387,7 +1699,7 @@ declare class RoutingState implements ShownEntriesSlice {
     /** Sparse nullable slots being assembled before triggering a route calculation. */
     get planningSlots(): PlanningWaypoint[];
     get params(): RouteParams;
-    addRoutes(routes: Routes, waypoints: WaypointLike[], label: string): string;
+    addRoutes(routes: Routes, waypoints: WaypointLike[], label: string): Promise<string>;
     /**
      * Attach an analysis result to an existing routes entry. Names are unique within a single
      * entry — adding one with an existing name replaces it. Returns true on success, false if
@@ -1396,6 +1708,11 @@ declare class RoutingState implements ShownEntriesSlice {
     addAnalysisToEntry(entryId: string, analysis: RoutesAnalysis): boolean;
     setWaypointAt(index: number, waypoint: WaypointLike): void;
     setParams(params: Partial<RouteParams>): void;
+    /**
+     * Hide every route + waypoint set currently on the map. Map-only — history (`entries`)
+     * stays intact. Implements {@link ClearableMapSlice}.
+     */
+    clearShown(): Promise<void>;
     reset(): void;
 }
 
@@ -1467,8 +1784,12 @@ export declare type StateDigest = {
         entryMode: EntryMode;
     };
     traffic: {
-        /** Whether a TrafficAreaAnalytics visualization is active. */
-        analyticsActive: boolean;
+        /** Traffic-area-analytics entry ids currently rendered on the map, sorted ascending. */
+        shown: string[];
+        /** Display policy in force on the slice — `multiple` (default) or `single`. */
+        entryMode: EntryMode;
+        /** Total traffic-area-analytics entries in history (shown + hidden). */
+        entryCount: number;
     };
     incidents: {
         /** Traffic-incidents entry ids currently rendered on the map, sorted ascending. */
@@ -1478,6 +1799,22 @@ export declare type StateDigest = {
         /** Display policy in force on the slice — `multiple` (default) or `single`. */
         entryMode: EntryMode;
     };
+    customGeometries: {
+        /** Custom-geometries entry ids currently rendered on the map, sorted ascending. */
+        shown: string[];
+        /** Display policy in force on the slice — `multiple` (default) or `single`. */
+        entryMode: EntryMode;
+        /** Total custom-geometries entries in history (shown + hidden). */
+        entryCount: number;
+    };
+    byod: {
+        /** BYOD entry ids currently rendered on the map, sorted ascending. */
+        shown: string[];
+        /** Display policy in force on the slice — `multiple` (default) or `single`. */
+        entryMode: EntryMode;
+        /** Total BYOD entries in history (shown + hidden). */
+        entryCount: number;
+    };
 };
 
 /**
@@ -1538,14 +1875,33 @@ export declare const TOOL_NAMES: ToolName[];
 
 /**
  * Build-time options passed to a {@link ToolEntryBuilder}. Lets each tool
- * tailor its description, schema, or executor to flags or other config that
- * are only known at agent-creation time.
+ * tailor its description, schema, or executor to flags or per-turn scope
+ * resolved by the classifier.
+ *
+ * @typeParam Scope - The per-tool scope shape. Defaults to `unknown` for the
+ *   generic builder signature; individual builders narrow this via their own
+ *   `Scope` generic so the `scope` argument is well-typed within the tool.
  *
  * @group Agent Toolkit
  */
-export declare type ToolBuildOptions = {
+export declare type ToolBuildOptions<Scope = unknown> = {
     /** Active feature flags. */
     featureFlags?: FeatureFlags;
+    /**
+     * Per-turn scope emitted by the classifier (already validated against the
+     * tool's {@link ToolEntry.scopeSchema}). `undefined` at agent-creation time
+     * or when the classifier omits a scope for this tool — builders should
+     * treat `undefined` as "produce the full surface".
+     */
+    scope?: Scope;
+    /**
+     * Subset of {@link EntryDataKind} the agent is configured to expose, derived
+     * from `createMapAgent`'s `dataEntries` option. Builders for `analyseData`
+     * and `processData` use this to narrow their static (unscoped) input surface
+     * to the agent's enabled kinds. `undefined` means "no agent-level filtering —
+     * every kind stays available".
+     */
+    enabledDataKinds?: readonly EntryDataKind[];
 };
 
 /**
@@ -1555,20 +1911,27 @@ export declare type ToolBuildOptions = {
  * setup pipeline accept either form interchangeably.
  *
  * @typeParam S - The ToolState shape this tool requires. Default: base `ToolState`.
+ * @typeParam Scope - Optional per-tool scope shape (only relevant for builder
+ *   form). Defaults to `never` for non-scopable tools.
  *
  * @group Agent Toolkit
  */
-export declare type ToolDefinition<S extends ToolState = ToolState> = ToolEntry<S> | ToolEntryBuilder<S>;
+export declare type ToolDefinition<S extends ToolState = ToolState, Scope = any> = ToolEntry<S, Scope> | ToolEntryBuilder<S, Scope>;
 
 /**
  * A tool definition — the universal format for both built-in and third-party tools.
  * Combines execution (inputSchema + execute) with classifier metadata.
  *
  * @typeParam S - The ToolState shape this tool requires. Default: base `ToolState`.
+ * @typeParam Scope - Optional per-tool scope shape. When set via `scopeSchema`, the
+ *   classifier may emit a value of this shape per turn so the tool's `description`
+ *   and `inputSchema` can be rebuilt narrower for that step. Tools without scope
+ *   leave this at the default `unknown`; `scopeSchema` is then absent and no rebuild
+ *   ever runs for the tool.
  *
  * @group Agent Toolkit
  */
-export declare type ToolEntry<S extends ToolState = ToolState> = {
+export declare type ToolEntry<S extends ToolState = ToolState, Scope = unknown> = {
     /** Description of the tool's purpose. */
     description: string;
     /** Zod schema defining the tool's input parameters. */
@@ -1589,18 +1952,36 @@ export declare type ToolEntry<S extends ToolState = ToolState> = {
     relatedTools?: string[];
     /** Tool names that must run before this one. */
     dependsOn?: string[];
+    /**
+     * Optional per-tool scope schema. When set, the classifier may emit a
+     * scope value (validated against this schema) and `prepareStep` will
+     * rebuild this tool's `description` + `inputSchema` by re-invoking its
+     * {@link ToolEntryBuilder} with the parsed scope. Tools without a builder
+     * cannot be scoped — `scopeSchema` is only meaningful on builder-produced
+     * entries.
+     */
+    scopeSchema?: z.ZodType<Scope>;
+    /**
+     * Compact one-line hint for the classifier explaining when and how to scope
+     * this tool (e.g. "Emit `{ kinds: ['places'] }` when only places entries
+     * are relevant"). Appended to the tool's classifier-prompt entry.
+     */
+    scopePrompt?: string;
 };
 
 /**
  * A builder that produces a {@link ToolEntry} from {@link ToolBuildOptions}.
  * Use this when a tool's metadata, schema, or executor depends on options
- * resolved at agent-creation time (e.g. feature flags).
+ * resolved at agent-creation time (e.g. feature flags) or per turn
+ * (classifier-emitted scope).
  *
  * @typeParam S - The ToolState shape this tool requires. Default: base `ToolState`.
+ * @typeParam Scope - The per-tool scope shape, propagated to the produced
+ *   {@link ToolEntry} so the `scopeSchema` and runtime `scope` stay in lockstep.
  *
  * @group Agent Toolkit
  */
-export declare type ToolEntryBuilder<S extends ToolState = ToolState> = (options: ToolBuildOptions) => ToolEntry<S>;
+export declare type ToolEntryBuilder<S extends ToolState = ToolState, Scope = unknown> = (options: ToolBuildOptions<Scope>) => ToolEntry<S, Scope>;
 
 /**
  * Metadata for an agent toolkit tool.
@@ -1624,6 +2005,8 @@ export declare type ToolMetadata = {
     relatedTools?: ToolNameHint[];
     /** Tool names that must run before this one. */
     dependsOn?: ToolNameHint[];
+    /** When set, the classifier may emit `toolScopes[name]` for this tool to narrow per-turn. */
+    scopePrompt?: string;
 };
 
 /**
@@ -1641,6 +2024,19 @@ export declare type ToolName = keyof typeof DEFAULT_TOOLS;
  */
 export declare type ToolNameHint = ToolName | (string & {});
 
+/**
+ * Default tool names that should be dropped from the registry when a {@link DataEntryKind}
+ * is disabled. Only default-tool names are listed here — user-supplied custom tools are
+ * never filtered automatically; integrators that want to gate their own tools on enabled
+ * kinds can read `dataEntries` themselves.
+ *
+ * Tools that span multiple kinds (`clearMap`, `recallState`, `setEntryMode`, …) are
+ * intentionally absent — they keep working regardless of which kinds are disabled.
+ *
+ * @group Agent Toolkit
+ */
+export declare const TOOLS_BY_DATA_ENTRY_KIND: Record<DataEntryKind, readonly string[]>;
+
 /**
  * State passed to tool factory functions. Organized by feature area,
  * each sub-state mixes lazy module access with the current service data
@@ -1678,39 +2074,122 @@ export declare type ToolState = {
     trafficIncidents: TrafficIncidentsState;
     /** Reachable range results: origin, budgets, and bbox summaries. */
     ranges: RangeState;
-    /** Derived/custom polygon entries — output of processGeometries. */
+    /** Derived/custom polygon entries — output of `processData`. */
     customGeometries: CustomGeometriesState;
+    /** Bring-your-own-data GeoJSON layers — customer-authored data the agent can read and render. */
+    byod: BYODState;
+};
+
+/**
+ * A single aggregation/analysis result attached to a traffic-area-analytics entry.
+ * Produced by `analyseData`; `data` is whatever the dynamic code returned.
+ *
+ * @group Agent Toolkit
+ */
+export declare type TrafficAreaAnalyticsAnalysis = {
+    /** Unique name within the parent entry (used as a key for future UI). */
+    name: string;
+    timestamp: number;
+    /** Optional human-readable description of what the analysis computed. */
+    description?: string;
+    /** How `data` should be interpreted — plain JSON or a Chart.js configuration. */
+    outputFormat: AnalysisOutputFormat;
+    /** Arbitrary aggregation result returned by the dynamic code. */
+    data: unknown;
+};
+
+/**
+ * A single entry in the traffic-area-analytics history — output of one
+ * `getTrafficAreaAnalytics` call. Mirrors the per-entry model used by
+ * `RoutingState` / `CustomGeometriesState`: each entry owns its own
+ * `TrafficAreaAnalyticsModule`, lazy-initialised on first show.
+ *
+ * @group Agent Toolkit
+ */
+export declare type TrafficAreaAnalyticsEntry = {
+    id: string;
+    timestamp: number;
+    label: string;
+    /** The aggregated FeatureCollection result. */
+    data: TrafficAreaAnalytics;
+    /** Request parameters that produced this entry — provenance only, opaque to consumers. */
+    params: TrafficAreaAnalyticsParams;
+    /**
+     * Per-entry TrafficAreaAnalyticsModule. Each entry owns its own so two entries can render
+     * side-by-side. Lazy-initialised via {@link TrafficAreaAnalyticsState.getEntryModule}.
+     */
+    _module?: TrafficAreaAnalyticsModule;
+    /** Latest viz config reflected from the module (mode / metric / scaleMode / …). */
+    _config?: TrafficAreaAnalyticsConfig;
+    /** Unsubscribe from this entry's module config-change wiring. Cleared on hide / remove. */
+    _configChangeUnsub?: () => void;
+    /** True while `_module` is rendering on the map. */
+    _shown?: boolean;
+    /** Accumulated analysis results linked to this entry. */
+    _analysis?: TrafficAreaAnalyticsAnalysis[];
 };
 
 /**
- * State for traffic area analytics — the lazy-init module, the last fetched
- * aggregation result, and its currently-applied visualization config. Tile
- * overlays (flow + incidents) live in {@link TrafficTilesState}.
+ * Compact provenance metadata for a traffic-area-analytics entry — the request
+ * parameters that produced the result. Kept opaque (`Record<string, unknown>`)
+ * because the SDK call accepts a wide param shape and we just want to surface
+ * enough context for `recall` / `digest` tools.
  *
  * @group Agent Toolkit
  */
-declare class TrafficAreaAnalyticsState implements StateSlice {
+export declare type TrafficAreaAnalyticsParams = Record<string, unknown>;
+
+/**
+ * Append-only history of traffic-area-analytics aggregations, with per-entry
+ * rendering. Each entry owns a dedicated {@link TrafficAreaAnalyticsModule},
+ * lazy-initialised on first show. Mirrors the per-entry pattern used by
+ * `RoutingState` / `CustomGeometriesState`.
+ *
+ * Live tile overlays (flow + incidents) live in {@link TrafficTilesState}.
+ *
+ * @group Agent Toolkit
+ */
+declare class TrafficAreaAnalyticsState implements ShownEntriesSlice, StateSlice {
     private readonly _ttMap;
-    private _trafficAreaAnalyticsModule?;
-    private _lastAreaAnalytics?;
-    private _currentAnalyticsConfig?;
-    private _configChangeUnsub?;
+    private _entries;
+    private _entryMode;
     /** Subscribe to state changes — see {@link TrafficAreaAnalyticsStateEvents}. */
     readonly events: StateEvents<TrafficAreaAnalyticsStateEvents>;
     constructor(_ttMap: TomTomMap);
-    getTrafficAreaAnalyticsModule(): Promise<TrafficAreaAnalyticsModule>;
-    get trafficAreaAnalyticsModule(): TrafficAreaAnalyticsModule | undefined;
-    get lastAreaAnalytics(): TrafficAreaAnalytics | undefined;
-    setLastAreaAnalytics(result: TrafficAreaAnalytics): void;
-    /** Current visualization config, updated by module configChange events. */
-    get currentAnalyticsConfig(): TrafficAreaAnalyticsConfig | undefined;
-    /**
-     * Notify subscribers that an analytics result is now active on the map. Called from
-     * tool implementations after `module.show(...)` succeeds.
-     */
-    notifyAnalyticsShown(analytics: TrafficAreaAnalytics, module: TrafficAreaAnalyticsModule): void;
-    /** Notify subscribers that the active analytics visualization was cleared. */
-    notifyAnalyticsCleared(): void;
+    get entries(): readonly TrafficAreaAnalyticsEntry[];
+    get latestEntry(): TrafficAreaAnalyticsEntry | undefined;
+    get shownEntryIds(): ReadonlySet<string>;
+    get entryMode(): EntryMode;
+    setEntryMode(mode: EntryMode): Promise<void>;
+    findById(entryId: string): TrafficAreaAnalyticsEntry | undefined;
+    /**
+     * Append a new entry. Auto-suffixes the id on collision. Under `single` mode the new entry
+     * replaces every older one (hidden + dropped from history).
+     */
+    addEntry(data: TrafficAreaAnalytics, label: string, params: TrafficAreaAnalyticsParams, explicitId?: string): Promise<string>;
+    /**
+     * Attach an analysis to an existing entry. Replaces the prior result keyed by `analysis.name`
+     * on the same entry (mirrors PlacesState / CustomGeometriesState semantics). Returns `false`
+     * when the entry id is unknown.
+     */
+    addAnalysisToEntry(entryId: string, analysis: TrafficAreaAnalyticsAnalysis): boolean;
+    /**
+     * Lazy-init the entry's TrafficAreaAnalyticsModule, wiring per-entry config-change events.
+     * Throws on unknown id.
+     */
+    getEntryModule(entryId: string): Promise<TrafficAreaAnalyticsModule>;
+    /** Render this entry's analytics on its own module. Under `single` mode, hides every other shown entry first. */
+    showEntry(entryId: string): Promise<void>;
+    /** Hide the entry's analytics on its module. No-op when unknown or already hidden. */
+    hideEntry(entryId: string): Promise<void>;
+    /** Drop a single entry from history. Hides it first, then removes; emits `entries-change`. No-op on unknown id. */
+    removeEntry(entryId: string): Promise<void>;
+    private _requireEntry;
+    /**
+     * Hide every traffic-area-analytics entry currently on the map. Map-only — history is kept.
+     * Implements {@link ClearableMapSlice}.
+     */
+    clearShown(): Promise<void>;
     reset(): void;
 }
 
@@ -1721,18 +2200,25 @@ declare class TrafficAreaAnalyticsState implements StateSlice {
  * @group Agent Toolkit
  */
 declare type TrafficAreaAnalyticsStateEvents = {
-    /** Last fetched analytics result and its module are now active on the map. */
-    'analytics-shown': {
-        analytics: TrafficAreaAnalytics;
-        module: TrafficAreaAnalyticsModule;
+    /** History changed — entry added, removed, or cleared via `reset()`. */
+    'entries-change': readonly TrafficAreaAnalyticsEntry[];
+    /** Set of entries currently rendered on the map changed. */
+    'shown-change': ReadonlySet<string>;
+    /** Per-entry viz config changed (mode / metric / scaleMode / …). */
+    'config-change': {
+        entryId: string;
+        config: TrafficAreaAnalyticsConfig | undefined;
+    };
+    /** A new analysis was attached to (or replaced on) an entry. */
+    'analysis-added': {
+        entryId: string;
+        analysis: TrafficAreaAnalyticsAnalysis;
     };
-    /** The active analytics visualization was cleared or replaced. */
-    'analytics-cleared': void;
-    /** Module-level visualization config changed (mode, metric, scaleMode, ...). */
-    'config-change': TrafficAreaAnalyticsConfig | undefined;
+    /** Display policy switched between `single` and `multiple`. */
+    'mode-change': EntryMode;
 };
 
-declare type TrafficIncidentsEntry = {
+export declare type TrafficIncidentsEntry = {
     id: string;
     timestamp: number;
     label: string;
@@ -1823,7 +2309,7 @@ declare class TrafficIncidentsState implements StateSlice {
      */
     addIncidentsEntry(data: TrafficIncident[], params: TrafficIncidentDetailsByBBoxParams & {
         bbox: BBox;
-    }, label: string, sampledAt: number, explicitId?: string): string;
+    }, label: string, sampledAt: number, explicitId?: string): Promise<string>;
     /**
      * Replace an entry's data in place and repaint its module without moving the camera.
      * Used by the per-entry monitor tick so incident geometries and any open detail
@@ -1919,9 +2405,13 @@ declare class TrafficIncidentsState implements StateSlice {
     isMonitored(entryId: TrafficIncidentsEntry['id']): boolean;
     private _createMonitorForEntry;
     private _requireEntry;
-    private _uniqueEntryId;
     private _rerunRegisteredSpecs;
     private _teardownEntry;
+    /**
+     * Hide every traffic-incidents entry currently on the map. Map-only — history is kept.
+     * Implements {@link ClearableMapSlice}.
+     */
+    clearShown(): Promise<void>;
     reset(): void;
 }