@tomtom-org/maps-sdk-plugin-agent-toolkit 0.2.4 → 0.2.5

package/dist/index.d.ts

@@ -1,34 +1,52 @@
-import { BaseMapModule } from '../../map/dist';
-import { GeometriesModule } from '../../map/dist';
-import { GeometryTheme } from '../../map/dist';
-import { HillshadeModule } from '../../map/dist';
+import { BaseMapModule } from '../../../../map/dist';
+import { BBox } from '../../../../core/dist';
+import { BBox as BBox_2 } from '../../../../../core/dist';
+import { CommonPlaceProps } from '../../../core/dist';
+import { CommonPlaceProps as CommonPlaceProps_2 } from '../../../../core/dist';
+import { GeometriesModule } from '../../../map/dist';
+import { GeometriesModule as GeometriesModule_2 } from '../../../../map/dist';
+import { GeometryTheme } from '../../../../map/dist';
+import { HillshadeModule } from '../../../../map/dist';
 import { LanguageModel } from 'ai';
 import { Map as Map_2 } from 'maplibre-gl';
 import { ModelMessage } from 'ai';
 import { Place } from '../../../core/dist';
-import { Place as Place_2 } from '../../core/dist';
-import { Places } from '../../core/dist';
-import { PlacesModule } from '../../map/dist';
-import { PlanningWaypoint } from '../../map/dist';
-import { POIsModule } from '../../map/dist';
+import { Place as Place_2 } from '../../../../core/dist';
+import { PlaceConnectionDisplay } from '../../../map/dist';
+import { PlaceConnectionDisplay as PlaceConnectionDisplay_2 } from '../../../../map/dist';
+import { Places } from '../../../../core/dist';
+import { PlacesModule } from '../../../map/dist';
+import { PlacesModule as PlacesModule_2 } from '../../../../map/dist';
+import { PlanningWaypoint } from '../../../../map/dist';
+import { POIsModule } from '../../../../map/dist';
+import { PolygonFeature } from '../../../core/dist';
+import { PolygonFeature as PolygonFeature_2 } from '../../../../core/dist';
 import { PolygonFeatures } from '../../../core/dist';
 import { Position } from 'geojson';
 import { PrepareStepFunction } from 'ai';
 import { ReachableRangeBudget } from '../../../services/dist';
 import { Routes } from '../../../core/dist';
-import { Routes as Routes_2 } from '../../core/dist';
-import { RoutingModule } from '../../map/dist';
-import { TomTomMap } from '../../map/dist';
+import { Routes as Routes_2 } from '../../../../core/dist';
+import { RoutingModule } from '../../../map/dist';
+import { RoutingModule as RoutingModule_2 } from '../../../../map/dist';
+import { TomTomMap } from '../../../../map/dist';
+import { TomTomMap as TomTomMap_2 } from '../../map/dist';
 import { ToolLoopAgent } from 'ai';
-import { TrafficAreaAnalytics } from '../../core/dist';
-import { TrafficAreaAnalyticsConfig } from '../../map/dist';
-import { TrafficAreaAnalyticsModule } from '../../map/dist';
-import { TrafficFlowModule } from '../../map/dist';
-import { TrafficIncidentsModule } from '../../map/dist';
+import { TrafficAreaAnalytics } from '../../../../core/dist';
+import { TrafficAreaAnalyticsConfig } from '../../../../map/dist';
+import { TrafficAreaAnalyticsModule } from '../../../../map/dist';
+import { TrafficFlowModule } from '../../../../map/dist';
+import { TrafficIncident } from '../../../../core/dist';
+import { TrafficIncident as TrafficIncident_2 } from '../../../../../core/dist';
+import { TrafficIncidentDetailsByBBoxParams } from '../../../../services/dist';
+import { TrafficIncidentOverlayModule } from '../../../../map/dist';
+import { TrafficIncidentsModule } from '../../../../map/dist';
 import { WaypointLike } from '../../../core/dist';
-import { WaypointLike as WaypointLike_2 } from '../../core/dist';
+import { WaypointLike as WaypointLike_2 } from '../../../../core/dist';
 import { z } from 'zod';
 
+declare type AnalysisOutputFormat = 'json' | 'chart';
+
 /**
  * The base system prompt that teaches the LLM how to use the agent toolkit tools.
  *
@@ -48,7 +66,7 @@ import { z } from 'zod';
  *
  * @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.\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 showPlaces / showRoute / showWaypoints only when displaying results already in context from a previous step.\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 / 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";
 
 /**
  * State for base map display: style, language, viewport, layers, and hillshade.
@@ -206,83 +224,218 @@ export declare const createDefaultClassifier: (options: {
  * ```
  * @group Agent Toolkit
  */
-export declare const createMapAgent: <CS extends ToolState = ToolState>(map: TomTomMap, options: MapAgentOptions<CS>) => MapAgentInstance<CS>;
+export declare const createMapAgent: <CS extends ToolState = ToolState>(map: TomTomMap_2, options: MapAgentOptions<CS>) => MapAgentInstance<CS>;
 
 /**
- * Factory that creates a fully initialized ToolState from a TomTomMap instance.
- * Optionally merges custom state slices alongside built-in state.
+ * A single aggregation/analysis result attached to a custom-geometries entry.
+ * Produced by the `analyseGeometries` tool; `data` is whatever the dynamic code returned.
  *
- * @param map - TomTomMap instance for module initialization
- * @param customSlices - Additional state slices accessible by custom tools
+ * @group Agent Toolkit
+ */
+export declare type CustomGeometriesAnalysis = {
+    /** 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 custom-geometries history — output of
+ * processGeometries (and any future polygon-producing tool that doesn't
+ * naturally belong to places or ranges).
  *
  * @group Agent Toolkit
  */
-export declare const createToolState: <T extends Record<string, unknown> = Record<string, never>>(map: TomTomMap, customSlices?: T) => ToolState & T;
+export declare type CustomGeometriesEntry = {
+    id: string;
+    timestamp: number;
+    label: string;
+    /** The polygons stored on this entry (Polygon / MultiPolygon GeoJSON Features). */
+    features: PolygonFeature[];
+    /** Inputs and operation that produced this entry. */
+    provenance: GeometryProvenance;
+    /** Accumulated analysis results linked to this entry. */
+    _analysis?: CustomGeometriesAnalysis[];
+    /**
+     * Per-entry GeometriesModule. Each entry owns its own module so display state
+     * (theme, current features) lives on the entry instead of a shared slice-level
+     * module. Lazy-initialised via CustomGeometriesState helpers.
+     */
+    _module?: GeometriesModule;
+    /** Theme that the geometries module is currently configured with. */
+    _shownTheme?: 'filled' | 'outline' | 'inverted';
+    /** True while this entry's `_module` is rendering on the map. */
+    _shown?: boolean;
+};
 
 /**
- * Default tool set for the agent toolkit.
+ * State for derived / custom geometries — output of `processGeometries` 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
+ * the per-entry display model used by {@link RangeState}. Provenance metadata captures the
+ * input sources (tagged ids) and the operation that produced the polygons.
+ *
+ * @group Agent Toolkit
+ */
+declare class CustomGeometriesState implements ShownEntriesSlice, StateSlice {
+    private readonly _ttMap;
+    private _entries;
+    private _entryMode;
+    /** Subscribe to state changes — see {@link CustomGeometriesStateEvents}. */
+    readonly events: StateEvents<CustomGeometriesStateEvents>;
+    constructor(_ttMap: TomTomMap);
+    get entries(): readonly CustomGeometriesEntry[];
+    get latestEntry(): CustomGeometriesEntry | undefined;
+    /** Set of custom-geometries entry ids currently rendered on the map. */
+    get shownEntryIds(): ReadonlySet<string>;
+    /**
+     * Display policy: `multiple` (default) lets several derived-geometry entries render side
+     * by side; `single` enforces "at most one entry on the map" — switching to it auto-hides
+     * older entries.
+     */
+    get entryMode(): EntryMode;
+    setEntryMode(mode: EntryMode): Promise<void>;
+    findById(entryId: string): CustomGeometriesEntry | undefined;
+    /**
+     * 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_2<CommonPlaceProps_2>[], provenance: CustomGeometriesEntry['provenance'], label: string, explicitId?: string): 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. */
+    getEntryGeometriesModule(entryId: string, theme?: GeometryTheme): Promise<GeometriesModule_2>;
+    /**
+     * Render this entry's polygons. `mode` is scoped to this entry's own layer:
+     * - `'replace'` (default) — show exactly `entry.features`, clearing whatever the
+     *   entry's module had rendered before.
+     * - `'add'` — merge `entry.features` with the polygons currently shown on this entry's
+     *   layer (deduped by feature id). Mostly only meaningful when re-showing the same entry.
+     *
+     * Cross-entry visibility is handled separately: under `entryMode === 'single'` other
+     * shown entries are hidden first; otherwise the caller uses `hideEntry` / the
+     * tools' `hidePreviousEntries` option.
+     */
+    showEntry(entryId: string, theme?: GeometryTheme, mode?: 'add' | 'replace'): 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;
+    private _uniqueEntryId;
+    reset(): void;
+}
+
+/**
+ * Events fired by {@link CustomGeometriesState}. Subscribe via
+ * `state.customGeometries.events.on(type, handler)`.
+ *
+ * @group Agent Toolkit
+ */
+declare type CustomGeometriesStateEvents = {
+    /** History changed — entry added or cleared via `reset()`. */
+    'entries-change': readonly CustomGeometriesEntry[];
+    /** Set of entries currently rendered on the map changed. */
+    'shown-change': ReadonlySet<string>;
+    /** A new analysis was attached to (or replaced on) an entry. */
+    'analysis-added': {
+        entryId: string;
+        analysis: CustomGeometriesAnalysis;
+    };
+    /** Display policy switched between `single` and `multiple`. */
+    'mode-change': EntryMode;
+};
+
+/**
+ * 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
+ * {@link ToolBuildOptions} (e.g. feature flags) at agent-creation time.
+ *
  * Included automatically by createMapAgent unless includeDefaultTools is false.
  * Use resolveTools() for manual composition outside createMapAgent.
  *
  * @group Agent Toolkit
  */
 export declare const DEFAULT_TOOLS: {
-    locatePlace: ToolEntry;
-    reverseGeocode: ToolEntry;
-    discoverPlaces: ToolEntry;
-    setRouteLocations: ToolEntry;
-    setRouteParameters: ToolEntry;
-    addStopToRoute: ToolEntry;
-    removeStopFromRoute: ToolEntry;
-    getPOICategoryCodes: ToolEntry;
-    getTrafficIncidents: ToolEntry;
-    getTrafficAreaAnalytics: ToolEntry;
-    queryTrafficAnalytics: ToolEntry;
-    showPlaces: ToolEntry;
-    managePlaces: ToolEntry;
-    showRoute: ToolEntry;
-    showTrafficAreaAnalytics: ToolEntry;
-    showWaypoints: ToolEntry;
-    getShownPlaces: ToolEntry;
-    getShownRoutes: ToolEntry;
-    getShownWaypoints: ToolEntry;
-    getShownRouteTrafficIncidents: ToolEntry;
-    getShownRouteSections: ToolEntry;
-    getShownIncidents: ToolEntry;
-    clearMap: ToolEntry;
-    flyTo: ToolEntry;
-    fitRouteSection: ToolEntry;
-    getViewport: ToolEntry;
-    recallPlaces: ToolEntry;
-    recallRoutes: ToolEntry;
-    getCurrentWaypoints: ToolEntry;
-    getStandardMapStyles: ToolEntry;
-    setMapStandardStyle: ToolEntry;
-    setRouteTheme: ToolEntry;
-    setLanguage: ToolEntry;
-    toggleBaseMapLayerGroups: ToolEntry;
-    togglePOIs: ToolEntry;
-    toggleTrafficFlow: ToolEntry;
-    toggleTrafficIncidents: ToolEntry;
-    getMapStyleLayers: ToolEntry;
-    setLayoutProperties: ToolEntry;
-    setPaintProperties: ToolEntry;
-    setPitchBearing: ToolEntry;
-    zoomInOrOut: ToolEntry;
-    executeMaplibreCode: ToolEntry;
-    calculateBBox: ToolEntry;
-    formatDistance: ToolEntry;
-    formatDuration: ToolEntry;
-    getSectionProgress: ToolEntry;
-    getSectionBBox: ToolEntry;
-    getRouteProgress: ToolEntry;
-    getCurrentLocation: ToolEntry;
-    help: ToolEntry;
-    searchAlongRoute: ToolEntry;
-    findReachableArea: ToolEntry;
-    recallRanges: ToolEntry;
+    locatePlace: ToolDefinition;
+    reverseGeocode: ToolDefinition;
+    discoverPlaces: ToolDefinition;
+    processPlaces: ToolDefinition;
+    processGeometries: ToolDefinition;
+    processRoutes: ToolDefinition;
+    analyseGeometries: ToolDefinition;
+    analysePlaces: ToolDefinition;
+    analyseRoutes: ToolDefinition;
+    setRoute: ToolDefinition;
+    addWaypointsToRoute: ToolDefinition;
+    removeWaypointsFromRoute: ToolDefinition;
+    replaceWaypointInRoute: ToolDefinition;
+    getPOICategoryCodes: ToolDefinition;
+    getTrafficIncidents: ToolDefinition;
+    analyseIncidents: ToolDefinition;
+    focusIncidents: ToolDefinition;
+    startTrafficIncidentsMonitor: ToolDefinition;
+    stopTrafficIncidentsMonitor: ToolDefinition;
+    getTrafficAreaAnalytics: ToolDefinition;
+    queryTrafficAnalytics: ToolDefinition;
+    updatePlacesDisplay: ToolDefinition;
+    updateRoutesDisplay: ToolDefinition;
+    showTrafficAreaAnalytics: ToolDefinition;
+    showWaypoints: ToolDefinition;
+    getShownPlaces: ToolDefinition;
+    getShownRoutes: ToolDefinition;
+    getShownWaypoints: ToolDefinition;
+    getShownRouteTrafficIncidents: ToolDefinition;
+    getShownIncidents: ToolDefinition;
+    clearMap: ToolDefinition;
+    flyTo: ToolDefinition;
+    getViewport: ToolDefinition;
+    recallGeometries: ToolDefinition;
+    recallPlaces: ToolDefinition;
+    recallRoutes: ToolDefinition;
+    getCurrentWaypoints: ToolDefinition;
+    getStandardMapStyles: ToolDefinition;
+    setMapStandardStyle: ToolDefinition;
+    setRouteTheme: ToolDefinition;
+    setLanguage: ToolDefinition;
+    toggleBaseMapLayerGroups: ToolDefinition;
+    togglePOIs: ToolDefinition;
+    toggleTrafficFlow: ToolDefinition;
+    toggleTrafficIncidents: ToolDefinition;
+    getMapStyleLayers: ToolDefinition;
+    setLayoutProperties: ToolDefinition;
+    setPaintProperties: ToolDefinition;
+    setPitchBearing: ToolDefinition;
+    zoomInOrOut: ToolDefinition;
+    executeMaplibreCode: ToolDefinition;
+    calculateBBox: ToolDefinition;
+    formatDistance: ToolDefinition;
+    formatDuration: ToolDefinition;
+    getCurrentLocation: ToolDefinition;
+    help: ToolDefinition;
+    findReachableAreas: ToolDefinition;
+    recallRanges: ToolDefinition;
+    recallState: ToolDefinition;
+    resetState: ToolDefinition;
+    setEntryMode: ToolDefinition;
 };
 
+/**
+ * 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
+ * `single` automatically drops every entry except the latest (and clears their modules) so
+ * the map matches the new policy immediately.
+ *
+ * @group Agent Toolkit
+ */
+export declare type EntryMode = 'single' | 'multiple';
+
 /**
  * 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.
@@ -291,6 +444,271 @@ export declare const DEFAULT_TOOLS: {
  */
 export declare const extractLastUserText: (messages: ReadonlyArray<ModelMessage>) => string | null;
 
+/**
+ * Feature-flag bag for {@link createMapAgent}. Toggles in-flight or
+ * opt-in agent-toolkit behaviour. Individual flags vary in stability —
+ * some may graduate to stable public options, others are internal-only
+ * experiments that can change or disappear without notice. Check each
+ * flag's own doc for its current status.
+ *
+ * @experimental
+ *
+ * @group Agent Toolkit
+ */
+export declare type FeatureFlags = {
+    /* Excluded from this release type: experimentalSearch */
+};
+
+/**
+ * Produce a compact, LLM-readable summary of the differences between two digests, or `null` when
+ * nothing changed. The output is short enough to prepend to a user prompt without bloating the
+ * conversation; longer per-field diffs are deliberately omitted.
+ *
+ * @example
+ * ```ts
+ * const prev = getStateDigest(state);
+ * // ... user clicks around in the UI ...
+ * const diff = formatStateDigestDiff(prev, getStateDigest(state));
+ * // → '[map state changed since last response: places shown as pins: "amsterdam-cinemas"; route now "routes-2"]'
+ * ```
+ *
+ * @group Agent Toolkit
+ */
+export declare const formatStateDigestDiff: (prev: StateDigest, next: StateDigest) => string | null;
+
+/** Tagged id for any polygon source in session state. */
+export declare type GeometriesId = z.infer<typeof geometriesIdSchema>;
+
+/** Possible kinds in a geometries id. */
+export declare type GeometriesIdKind = 'place' | 'places' | 'ranges' | 'custom';
+
+/**
+ * Tagged geometries id. The Zod schema is exposed so tools can plug it
+ * straight into their input shape (`z.array(geometriesIdSchema).min(1)`)
+ * — no string parsing on the way in.
+ *
+ * @group Agent Toolkit
+ */
+export declare const geometriesIdSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"place">;
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"places">;
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"ranges">;
+    id: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"custom">;
+    id: z.ZodString;
+}, z.core.$strip>], "kind">;
+
+/**
+ * Provenance metadata for a custom-geometries entry — captures every input
+ * source that fed the polygon-producing operation. `sourceIds` holds tagged
+ * 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
+ * the kind of computation that produced the entry (e.g. `'union'`, `'buffer'`,
+ * `'h3-coverage'`).
+ *
+ * @group Agent Toolkit
+ */
+export declare type GeometryProvenance = {
+    /** Short label for the operation that produced this entry (free-form). */
+    operation?: string;
+    /** Tagged source ids that fed the producing operation. */
+    sourceIds: readonly GeometriesId[];
+};
+
+/**
+ * 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).
+ *
+ * @group Agent Toolkit
+ */
+export declare const getStateDigest: (state: ToolState) => StateDigest;
+
+/**
+ * Snapshot of an entry's focus subset. Returned by `getFocus` / payload on `focus-change`.
+ *
+ * @group Agent Toolkit
+ */
+declare type IncidentFocus = {
+    ids: Set<string>;
+    reason?: string;
+};
+
+/**
+ * One-shot polling loop scoped to a single bbox. Owns its timer, status, error,
+ * and captured area. Re-starting after `stop()` is allowed and resets all state.
+ *
+ * The monitor never knows about the entry that owns it — it surfaces ticks/errors
+ * through `events`, and the caller decides what to do with the snapshot.
+ *
+ * @group Agent Toolkit
+ */
+declare class IncidentMonitor {
+    private readonly _bbox;
+    readonly events: StateEvents<IncidentMonitorEvents>;
+    private _status;
+    private _area?;
+    private _error?;
+    private _intervalHandle?;
+    private _clearInterval?;
+    private _fetchIncidents?;
+    constructor(_bbox: BBox_2);
+    get status(): PollingStatus;
+    get monitoredArea(): MonitoredArea | undefined;
+    get error(): string | undefined;
+    /**
+     * True when the monitor is *currently* polling. Distinct from {@link isActive},
+     * which also covers `stopped-error` — a state where the timer is gone but the
+     * monitor still carries an unacknowledged error. Use this for "is the entry
+     * being polled right now"; use `isActive` for "is there anything to clean up".
+     */
+    get isRunning(): boolean;
+    /** True when the monitor has any polling activity (running or stopped-error). */
+    get isActive(): boolean;
+    /**
+     * Begin polling. Captures `deps` for the lifetime of the run, fires the first tick
+     * immediately, then schedules an interval. No-op when already running.
+     */
+    start(area: MonitoredArea, deps: IncidentMonitorDeps, intervalMs?: number): void;
+    /** Stop polling and reset state. No-op when idle. */
+    stop(): void;
+    private _tick;
+    private _failed;
+    private _releaseTimer;
+}
+
+/**
+ * Dependency injection for an {@link IncidentMonitor}. Production code wires
+ * `fetchIncidents` to `trafficIncidentDetails`; tests can pass a deterministic fake
+ * and override the timer.
+ *
+ * The fetcher returns just the incidents — the monitor stamps `takenAt` itself
+ * so every consumer of one tick (entry data, derived analyses, sandbox `now`)
+ * agrees on the same canonical moment.
+ *
+ * @group Agent Toolkit
+ */
+declare type IncidentMonitorDeps = {
+    fetchIncidents: (bbox: BBox_2) => Promise<TrafficIncident_2[]>;
+    /** Override for tests. Defaults to the global `setInterval`. */
+    setInterval?: (fn: () => void, ms: number) => unknown;
+    clearInterval?: (handle: unknown) => void;
+};
+
+/**
+ * Events fired by {@link IncidentMonitor}. The slice subscribes once and re-emits
+ * translated copies (`monitor-tick` / `monitor-error`) keyed by entry id.
+ */
+declare type IncidentMonitorEvents = {
+    /** A poll succeeded. Payload: the fresh snapshot. */
+    tick: IncidentSnapshot;
+    /** A poll failed — the monitor has cleared its timer and moved to `stopped-error`. */
+    error: string;
+};
+
+/**
+ * Per-entry analysis registry: owns re-executing specs *and* the timeline of
+ * their results. One thing, three parts — name, recipe (spec), output history —
+ * kept together instead of split across sibling fields.
+ *
+ * Each named analysis keeps a bounded chronological history (see
+ * {@link MAX_HISTORY_PER_ANALYSIS}) so consumers can trend results over time;
+ * `getResult(name)` returns the most recent, `history(name)` the full timeline.
+ *
+ * Errors from individual specs are dropped silently — replay should never break
+ * the monitor tick that triggered it.
+ *
+ * @group Agent Toolkit
+ */
+declare class IncidentsAnalyses {
+    private _specs;
+    private readonly _historyByName;
+    get specs(): readonly IncidentsAnalysisSpec[];
+    /**
+     * Latest result for each registered spec, in registration order. Specs whose
+     * history is empty (e.g. only failed runs) are skipped. UI layers that "render
+     * whatever analyses this entry has" should iterate this instead of poking at
+     * private history state.
+     */
+    get results(): readonly IncidentsAnalysis[];
+    /** Full timeline for a single named analysis, oldest first. Empty when unknown. */
+    history(name: string): readonly IncidentsAnalysis[];
+    /** Most recent result for a given analysis name, or undefined. */
+    getResult(name: string): IncidentsAnalysis | undefined;
+    /**
+     * Register a spec, or replace an existing one with the same name. When the new spec
+     * differs from the existing one (code, outputFormat, or description), drops history
+     * for that name — old results belong to a different analysis and must not leak into
+     * `getResult` / `results`, which describe the *current* spec. Identical re-registers
+     * are no-ops and preserve history (so trend continuity survives idempotent retries).
+     */
+    register(spec: IncidentsAnalysisSpec): void;
+    /** Drop a spec by name. No-op when unknown. Result history is preserved. */
+    unregister(name: string): void;
+    /**
+     * Append a result to the timeline for its name, evicting the oldest entry
+     * when the per-name cap is hit. Used by the slice for one-shot tool runs and
+     * by {@link replay} for each fresh tick.
+     */
+    attach(result: IncidentsAnalysis): void;
+    /**
+     * Re-run every registered spec against `data`, threading the previous result
+     * from the timeline. `sampledAt` is the canonical moment for this replay —
+     * shared with the entry data and the sandbox's `now`, so consumers can join
+     * across them safely. Each fresh result is appended before being returned.
+     * Failed specs are skipped.
+     */
+    replay(data: TrafficIncident[], sampledAt: number): Promise<IncidentsAnalysis[]>;
+}
+
+/**
+ * A single aggregation/analysis result attached to a traffic-incidents entry.
+ * Produced by the `analyseIncidents` tool; `data` is whatever the dynamic code returned.
+ *
+ * @group Agent Toolkit
+ */
+declare type IncidentsAnalysis = {
+    /** 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 registered, re-executing analysis. Produced by `analyseIncidents`; replayed by
+ * an entry's {@link IncidentsAnalyses} on every monitor-tick of its source.
+ *
+ * @group Agent Toolkit
+ */
+declare type IncidentsAnalysisSpec = {
+    name: string;
+    description?: string;
+    outputFormat: AnalysisOutputFormat;
+    code: string;
+    /** Source entry id the spec reads from. */
+    source: string;
+};
+
+export declare type IncidentSnapshot = {
+    takenAt: number;
+    incidents: TrafficIncident_2[];
+};
+
+declare type JSONValue = null | string | number | boolean | {
+    [key: string]: JSONValue;
+} | JSONValue[];
+
 /**
  * The return type of createMapAgent().
  * A real ToolLoopAgent instance with state access and cleanup.
@@ -396,6 +814,50 @@ export declare type MapAgentOptions<CS extends ToolState = ToolState> = {
     outputSchemas?: boolean;
     /** Max multi-step tool loop iterations. Default: 10. */
     maxSteps?: number;
+    /**
+     * Opt into in-flight or experimental agent-toolkit behaviour. Stability
+     * varies per flag — see {@link FeatureFlags} and each flag's own doc.
+     *
+     * @experimental
+     */
+    featureFlags?: FeatureFlags;
+    /**
+     * Provider-specific options forwarded to the AI SDK on every step. Keyed by
+     * provider id (`openai`, `azure`, `anthropic`, ...).
+     *
+     * Use this to enable reasoning summaries for gpt-5.x via the Responses API
+     * — without `reasoningSummary` the model thinks but returns no reasoning text:
+     *
+     * @example
+     * ```typescript
+     * createMapAgent(map, {
+     *     model: azure.responses(deploymentId),
+     *     providerOptions: {
+     *         openai: { reasoningEffort: 'low', reasoningSummary: 'auto' },
+     *     },
+     * });
+     * ```
+     */
+    providerOptions?: ProviderOptions;
+    /**
+     * Per-step `providerOptions` override. Called once per step with the
+     * classifier-narrowed active toolset; the returned object is merged on top
+     * of `providerOptions` for that step. Use it to bump reasoning effort on
+     * turns that include a code-execution tool without paying the cost on
+     * simple fetch/toggle turns.
+     *
+     * @example
+     * ```typescript
+     * stepProviderOptions: ({ activeTools }) =>
+     *     activeTools?.some((t) => CODE_EXEC.has(t))
+     *         ? { openai: { reasoningEffort: 'medium' } }
+     *         : undefined,
+     * ```
+     */
+    stepProviderOptions?: (info: {
+        activeTools: string[] | undefined;
+        stepNumber: number;
+    }) => ProviderOptions | undefined;
 };
 
 /**
@@ -415,6 +877,30 @@ declare class MapPOIsState implements StateSlice {
     reset(): void;
 }
 
+export declare type MonitoredArea = {
+    bbox: BBox_2;
+    capturedAt: number;
+    label?: string;
+};
+
+/**
+ * A single aggregation/analysis result attached to a places entry.
+ * Produced by the `analysePlaces` tool; `data` is whatever the dynamic code returned.
+ *
+ * @group Agent Toolkit
+ */
+export declare type PlacesAnalysis = {
+    /** 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 place search history.
  *
@@ -424,65 +910,234 @@ export declare type PlacesEntry = {
     id: string;
     timestamp: number;
     label: string;
-    data: Place[];
+    places: Place[];
+    /** Connections (lines between places) produced alongside this entry, rendered via PlacesModule.showConnections. */
+    connections?: PlaceConnectionDisplay[];
+    /**
+     * 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
+     * (`place.properties.dataSources.geometry.id`), matching the response shape of `geometryData`.
+     */
+    geometries?: PolygonFeature<CommonPlaceProps>[];
+    /** Accumulated analysis results linked to this entry. */
+    _analysis?: PlacesAnalysis[];
+    /** Lazy place-id → Place index, built on first ID lookup through PlacesState.findPlaceById. */
+    _byId?: Record<string, Place>;
+    /** 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.
+     */
+    _modules?: {
+        pin?: PlacesModule;
+        baseMap?: PlacesModule;
+        pinClustered?: PlacesModule;
+        geometries?: GeometriesModule;
+    };
+    /** The marker theme currently rendering this entry, or undefined when hidden. */
+    _shownAs?: 'pin' | 'base-map' | 'pin-clustered';
 };
 
+/** How an entry is rendered on the map: as individual pins, base-map POIs, or clustered pins. */
+declare type PlacesMarkerType = 'pin' | 'base-map' | 'pin-clustered';
+
 /**
- * State for place search, geocoding, and geometries.
+ * State for the places layer: an append-only history of place results plus per-entry display
+ * modules.
  *
- * Holds lazy-initialized PlacesModule and GeometriesModule alongside an
- * append-only history of place and search results produced during the session.
+ * 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.
  *
  * @group Agent Toolkit
  */
 declare class PlacesState implements StateSlice {
     private readonly _ttMap;
-    private _placesModule?;
     private _entries;
-    /** IDs of entries currently rendered on the map. */
-    private _shownEntryIds;
+    private _entryMode;
+    /** Subscribe to state changes — see {@link PlacesStateEvents}. */
+    readonly events: StateEvents<PlacesStateEvents>;
     constructor(_ttMap: TomTomMap);
-    getPlacesModule(): Promise<PlacesModule>;
-    get placesModule(): PlacesModule | undefined;
+    /**
+     * Display policy: `multiple` (default) keeps every history entry available to render
+     * simultaneously; `single` enforces "at most one entry on the map at a time" and trims
+     * the history down to the latest entry whenever it's set.
+     */
+    get entryMode(): EntryMode;
+    /**
+     * Switch the display policy. When moving from `multiple` → `single` we hide every entry
+     * older than the latest, drop them from history, and emit `entries-change` so listeners
+     * (the recents rail, recall tools, …) re-render. No-op when the mode hasn't changed.
+     */
+    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.
+     */
+    getEntryPlacesModule(entryId: string, markerType: PlacesMarkerType): Promise<PlacesModule_2>;
+    /**
+     * Lazy-init and return the entry's place-geometries module (for POI footprints, municipality
+     * outlines). Re-applies themed config when the theme changes. Throws on unknown entry id.
+     */
+    getEntryGeometriesModule(entryId: string, theme?: GeometryTheme): Promise<GeometriesModule_2>;
+    private _requireEntry;
     get entries(): readonly PlacesEntry[];
     /**
      * This is used purely to pass data between tools in a context-dependent way,
      * so we assume the most recent entry is the relevant one to show on the map.
      */
     get latestPlace(): Place_2[] | undefined;
-    addPlaceResult(place: Place_2 | Places, label: string): string;
-    /** IDs of entries currently shown on the map. */
-    get shownEntryIds(): ReadonlySet<PlacesEntry['id']>;
+    addPlaceResult(place: Place_2 | Places, label: string, explicitId?: string, connections?: PlaceConnectionDisplay_2[], geometries?: PolygonFeature_2<CommonPlaceProps_2>[]): string;
+    private _uniqueEntryId;
+    /**
+     * Attach an analysis result to an existing entry. Analysis names are unique
+     * within a single entry — adding one with an existing name replaces it.
+     * Returns true on success, false if the entry doesn't exist.
+     */
+    addAnalysisToEntry(entryId: string, analysis: PlacesAnalysis): boolean;
+    findPlaceById(placeId: string): {
+        place: Place_2;
+        entryId: string;
+    } | undefined;
+    /**
+     * Returns the cached boundary polygon for a place id, or undefined if no geometry has been
+     * fetched for it yet. Builds a lazy place-id → feature index per entry on first lookup.
+     */
+    getGeometryForPlace(placeId: string): PolygonFeature_2<CommonPlaceProps_2> | undefined;
+    /**
+     * Fetches the boundary polygon for a place from the Geometry Data service and stores it on
+     * the owning entry. Returns the cached feature if already fetched, or undefined if the place
+     * is unknown or has no geometry data source.
+     */
+    fetchPlaceGeometry(placeId: string): Promise<PolygonFeature_2<CommonPlaceProps_2> | undefined>;
+    /**
+     * Batch-fetches boundary polygons for every place in an entry that has a geometry data source
+     * but is not yet cached. Issues one Geometry Data request per chunk of {@link GEOMETRY_DATA_BATCH_SIZE}
+     * place ids (the API caps each request) and stores the merged result on `entry.geometries`.
+     * Returns the full geometries list for the entry, or an empty array if the entry is unknown.
+     */
+    fetchGeometriesForEntry(entryId: string): Promise<PolygonFeature_2<CommonPlaceProps_2>[]>;
+    /**
+     * Render the given polygons via the entry's GeometriesModule. The `mode` flag is
+     * scoped to **this entry's layer only** — it does not touch other entries (use
+     * the slice's per-entry hide/show methods for cross-entry visibility).
+     *
+     * - `mode: 'replace'` (default) — calls `module.show` with exactly these features, replacing
+     *   whatever was previously on this entry's layer. An empty array clears the layer.
+     * - `mode: 'add'` — merges the new features with the polygons currently shown on this
+     *   entry's layer (deduped by `feature.id`) and re-renders the union. An empty array is a
+     *   no-op.
+     *
+     * `entryId` defaults to the latest entry that owns geometries — handy when callers only ever
+     * render the most-recently produced footprints. Pass an explicit id to target an older one.
+     */
+    showPlaceGeometries(features: PolygonFeature_2<CommonPlaceProps_2>[], theme?: GeometryTheme, mode?: 'add' | 'replace', entryId?: string): Promise<void>;
+    private _latestGeometriesEntryId;
+    private _buildGeometryIndex;
+    /** IDs of all entries currently shown on the map. */
+    get shownEntryIds(): ReadonlySet<string>;
+    /** IDs of entries currently shown as individual pins. */
+    get shownAsPinIds(): ReadonlySet<string>;
+    /** IDs of entries currently shown as base-map POIs. */
+    get shownAsBaseMapIds(): ReadonlySet<string>;
+    /** IDs of entries currently shown as clustered pins. */
+    get shownAsPinClusteredIds(): ReadonlySet<string>;
+    private _idsShownAs;
+    /** Marker type for a specific entry, or undefined if it is not shown. */
+    getShownMarkerType(id: string): PlacesMarkerType | undefined;
     /** Return the union of all features belonging to currently-shown entries. */
     getShownFeatures(): Place_2[];
-    /** Replace the shown set with exactly these ids and re-render. */
-    setShownEntries(ids: readonly PlacesEntry['id'][]): Promise<Place_2[]>;
-    /** Add ids to the shown set and re-render. */
-    addShownEntries(ids: readonly PlacesEntry['id'][]): Promise<Place_2[]>;
-    /** Remove ids from the shown set and re-render. */
-    removeShownEntries(ids: readonly PlacesEntry['id'][]): Promise<Place_2[]>;
+    /**
+     * Replace the shown set for `markerType` with exactly these ids and re-render.
+     * Entries currently shown as `markerType` but absent from `ids` are hidden;
+     * entries in `ids` are switched to `markerType` (lazy-creating their module).
+     */
+    setShownEntries(ids: readonly string[], markerType: PlacesMarkerType): Promise<Place_2[]>;
+    /**
+     * Add ids to the shown set under `markerType`. Any id previously shown as
+     * a different marker type is moved (its previous module is cleared, the
+     * new theme's module renders).
+     *
+     * Under `entryMode === 'single'` everything else is hidden first, so the
+     * effective behaviour collapses to "show exactly the last id in the list".
+     */
+    addShownEntries(ids: readonly string[], markerType: PlacesMarkerType): Promise<Place_2[]>;
+    /** Remove ids from the shown set and clear their modules. */
+    removeShownEntries(ids: readonly string[]): Promise<Place_2[]>;
     /** Clear everything from the map (does not touch entries history). */
     clearShownEntries(): Promise<void>;
-    private _renderShown;
+    clearShownGeometries(ids?: readonly string[]): Promise<void>;
+    /**
+     * Drop a single entry from history. Hides it from the map first (clears every theme module
+     * it owns) then removes it from `_entries`. Emits `entries-change` and, when the entry was
+     * shown, `shown-change`. No-op when the id is unknown.
+     */
+    removeEntry(id: string): Promise<void>;
+    private _showEntryAs;
+    private _hideEntry;
     reset(): void;
 }
 
 /**
- * A single entry in the reachable range history.
+ * Events fired by {@link PlacesState}. Subscribe via `state.places.events.on(type, handler)`.
+ *
+ * @group Agent Toolkit
+ */
+declare type PlacesStateEvents = {
+    /** History changed — entry added, replaced, or cleared via `reset()`. Payload: the full entries snapshot. */
+    'entries-change': readonly PlacesEntry[];
+    /** Set of entries currently rendered on the map changed (or marker type swapped). */
+    'shown-change': ReadonlySet<string>;
+    /** A new analysis was attached to (or replaced on) an entry. */
+    'analysis-added': {
+        entryId: string;
+        analysis: PlacesAnalysis;
+    };
+    /** Boundary polygons were fetched and cached on an entry. */
+    'geometries-change': {
+        entryId: string;
+        count: number;
+    };
+    /** Display policy switched between `single` and `multiple`. */
+    'mode-change': EntryMode;
+};
+
+export declare type PollingStatus = 'idle' | 'running' | 'stopped-error';
+
+declare type ProviderOptions = Record<string, Record<string, JSONValue | undefined>>;
+
+/**
+ * A single entry in the reachable range history. Holds one or more
+ * {@link ReachableRange} results that were computed together — typically
+ * one per origin in a multi-origin call to `findReachableAreas`.
  *
  * @group Agent Toolkit
  */
-export declare type RangeEntry = {
+export declare type RangesEntry = {
     id: string;
     timestamp: number;
     label: string;
-    origin: {
-        query?: string;
-        position: Position;
+    /** One or more ranges sharing this entry — typically one per origin. */
+    ranges: ReachableRange[];
+    /**
+     * Per-entry display modules. Each entry owns a dedicated GeometriesModule (for the
+     * isochrone polygons) and PlacesModule (for the origin pin(s)), so display state lives
+     * on the entry instead of a shared slice-level module. Lazy-initialised via RangeState
+     * helpers — undefined until first show.
+     */
+    _modules?: {
+        geometries?: GeometriesModule;
+        places?: PlacesModule;
     };
-    budgets: ReachableRangeBudget[];
-    /** Raw polygon result for use in subsequent geometry searches. Not exposed to the agent. */
-    polygon?: PolygonFeatures;
+    /** Theme that the geometries module is currently configured with. */
+    _shownTheme?: 'filled' | 'outline' | 'inverted';
+    /** True while any of this entry's modules are rendering on the map. */
+    _shown?: boolean;
 };
 
 /**
@@ -494,40 +1149,115 @@ export declare type RangeEntry = {
  *
  * @group Agent Toolkit
  */
-declare class RangeState implements StateSlice {
+declare class RangeState implements ShownEntriesSlice {
     private readonly _ttMap;
     private _entries;
-    private _placesModule?;
-    private _geometriesModule?;
-    private _currentTheme?;
+    private _entryMode;
+    /** Subscribe to state changes — see {@link RangeStateEvents}. */
+    readonly events: StateEvents<RangeStateEvents>;
     constructor(_ttMap: TomTomMap);
-    getPlacesModule(): Promise<PlacesModule>;
-    getGeometriesModule(theme: GeometryTheme): Promise<GeometriesModule>;
-    get geometriesModule(): GeometriesModule | undefined;
-    get entries(): readonly RangeEntry[];
-    get latestEntry(): RangeEntry | undefined;
-    addEntry(entry: Omit<RangeEntry, 'id' | 'timestamp'>): string;
+    /** Set of ranges-entry ids currently rendered on the map. */
+    get shownEntryIds(): ReadonlySet<string>;
+    /**
+     * Display policy: `multiple` (default) lets several reachable-area entries render side
+     * by side; `single` forces "at most one ranges entry on the map" — `markEntryShown`
+     * then hides any previously-shown entry first.
+     */
+    get entryMode(): EntryMode;
+    /**
+     * Switch the display policy. When moving from `multiple` → `single` we hide every
+     * non-latest entry, drop them from history, and emit `entries-change`. No-op when the
+     * mode hasn't changed.
+     */
+    setEntryMode(mode: EntryMode): Promise<void>;
+    /**
+     * Lazy-init the entry's GeometriesModule (for the isochrone/isodistance polygons),
+     * applying the requested theme. Throws on unknown id.
+     */
+    getEntryGeometriesModule(entryId: string, theme?: GeometryTheme): Promise<GeometriesModule_2>;
+    /**
+     * Lazy-init the entry's origin-pin PlacesModule. Each entry maintains its own pin module
+     * so multiple ranges entries can be on the map simultaneously without the pins of one
+     * overwriting another.
+     */
+    getEntryPlacesModule(entryId: string): Promise<PlacesModule_2>;
+    /**
+     * Mark this entry as shown — records `_shown = true` and emits `shown-change`. The
+     * caller is expected to push features into the lazy modules itself; this method only
+     * keeps the `_shown` flag in sync with what the user sees.
+     *
+     * Under `entryMode === 'single'` any other shown entry is hidden first so two range
+     * layers don't overlap.
+     */
+    markEntryShown(entryId: string): Promise<void>;
+    /** Hide every module on the entry (clear). No-op when the entry is unknown. */
+    hideEntry(entryId: string): Promise<void>;
+    /**
+     * Drop a single entry from history. Hides it from the map first (clears its geometries +
+     * origin-pin modules) then removes it from `_entries`. Emits `entries-change`. No-op when
+     * the id is unknown.
+     */
+    removeEntry(entryId: string): Promise<void>;
+    private _requireEntry;
+    get entries(): readonly RangesEntry[];
+    get latestEntry(): RangesEntry | undefined;
+    addEntry(entry: Omit<RangesEntry, 'id' | 'timestamp'>): string;
     reset(): void;
 }
 
+/**
+ * Events fired by {@link RangeState}. Subscribe via `state.ranges.events.on(type, handler)`.
+ *
+ * @group Agent Toolkit
+ */
+declare type RangeStateEvents = {
+    /** Range history changed — entry added or cleared via `reset()`. */
+    'entries-change': readonly RangesEntry[];
+    /** Set of ranges entries currently rendered on the map changed (multi-show under `multiple`). */
+    'shown-change': ReadonlySet<string>;
+    /** Display policy switched between `single` and `multiple`. */
+    'mode-change': EntryMode;
+};
+
+/**
+ * A single reachable area, scoped to one origin and one set of budgets.
+ * One {@link RangesEntry} bundles one or more of these — useful for comparing
+ * coverage from several origins under the same query.
+ *
+ * @group Agent Toolkit
+ */
+export declare type ReachableRange = {
+    origin: {
+        query?: string;
+        position: Position;
+    };
+    budgets: ReachableRangeBudget[];
+    /** Raw polygon result for use in subsequent geometry searches. Not exposed to the agent. */
+    polygon?: PolygonFeatures;
+};
+
 /**
  * Merges default tools with user overrides.
  *
- * - `ToolEntry` values add or replace tools in `defaults`.
+ * - `ToolEntry` (or builder) values add or replace tools in `defaults`.
  * - `false` values remove tools from `defaults`.
  * - Returns a new object — `defaults` is never mutated.
  *
+ * Default entries may be {@link ToolEntryBuilder builders} that produce
+ * their {@link ToolEntry} from build-time options. Builders pass through
+ * untouched and are materialized later by `setupTools`.
+ *
  * @param defaults - Base tool record (typically DEFAULT_TOOLS or empty).
  * @param overrides - User-provided additions, replacements, and exclusions.
  * @returns Resolved tool record ready for setupTools.
  *
  * @group Agent Toolkit
  */
-export declare const resolveTools: <S extends ToolState>(defaults: Record<string, ToolEntry<S>>, overrides?: { [K in ToolNameHint]?: ToolEntry<S> | false | undefined; }) => Record<string, ToolEntry<S>>;
+export declare const resolveTools: <S extends ToolState>(defaults: Record<string, ToolDefinition<S>>, overrides?: { [K in ToolNameHint]?: ToolEntry<S> | false | undefined; }) => Record<string, ToolDefinition<S>>;
 
 /**
  * Route planning parameters stored in routing state.
- * Consumed by setRouteLocations, addStopToRoute, and removeStopFromRoute.
+ * Consumed by setRoute, addWaypointsToRoute, removeWaypointsFromRoute, and replaceWaypointInRoute.
  *
  * @group Agent Toolkit
  */
@@ -545,6 +1275,24 @@ 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.
+ *
+ * @group Agent Toolkit
+ */
+export declare type RoutesAnalysis = {
+    /** 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 route calculation history.
  *
@@ -557,38 +1305,226 @@ export declare type RoutesEntry = {
     data: Routes;
     waypoints: WaypointLike[];
     params: RouteParams;
+    /** Accumulated analysis results linked to this entry. */
+    _analysis?: RoutesAnalysis[];
+    /**
+     * Per-entry RoutingModule. Each entry owns its own module so display state (which route
+     * variant is selected, which waypoints are shown, layer theme) lives on the entry instead
+     * of a shared slice-level module. Lazy-initialised via RoutingState helpers — undefined
+     * until first show.
+     */
+    _module?: RoutingModule;
+    /** True while this entry's `_module` is rendering routes/waypoints on the map. */
+    _shown?: boolean;
 };
 
 /**
  * State for route calculation, waypoint management, and route planning parameters.
  *
- * Holds the lazy-initialized RoutingModule alongside an append-only history of
- * calculated routes, sparse planning slots (being assembled before a calculation),
- * and current route parameters.
+ * Each entry carries its own lazy-initialised RoutingModule (`entry._module`), so display
+ * state lives on the entry instead of a shared slice-level module. Two routes can be rendered
+ * concurrently by showing both entries, and switching the active route hides the previous
+ * entry's module without disturbing its calculated data.
  *
  * @group Agent Toolkit
  */
-declare class RoutingState implements StateSlice {
+declare class RoutingState implements ShownEntriesSlice {
     private readonly _ttMap;
-    private _routingModule?;
     private _entries;
     private _planningSlots;
     private _params;
+    private _entryMode;
+    /**
+     * 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).
+     */
+    private _lastShownEntryId?;
+    /** Subscribe to state changes — see {@link RoutingStateEvents}. */
+    readonly events: StateEvents<RoutingStateEvents>;
     constructor(_ttMap: TomTomMap);
-    getRoutingModule(): Promise<RoutingModule>;
-    get routingModule(): RoutingModule | undefined;
+    /** Set of routes-entry ids currently rendered on the map. */
+    get shownEntryIds(): ReadonlySet<string>;
+    /**
+     * Display policy: `multiple` (default) lets several entries render side-by-side;
+     * `single` forces "at most one route on the map" — `showEntry` then hides any
+     * previously-shown entry first.
+     */
+    get entryMode(): EntryMode;
+    /**
+     * Switch the display policy. When moving from `multiple` → `single` we hide every
+     * non-latest entry, drop them from history, and emit `entries-change`. No-op when the
+     * mode hasn't changed.
+     */
+    setEntryMode(mode: EntryMode): Promise<void>;
+    /**
+     * Lazy-init and return an entry's RoutingModule. Throws on unknown id. Callers that need
+     * to show/hide should prefer the higher-level {@link showEntry} / {@link hideEntry}.
+     */
+    getEntryRoutingModule(entryId: string): Promise<RoutingModule_2>;
+    /**
+     * Render the given entry's routes + waypoints on its own RoutingModule.
+     *
+     * Under `entryMode === 'single'` any other shown entry is hidden first so two route
+     * layers don't pile up. Under `entryMode === 'multiple'` previously-shown entries stay
+     * rendered, letting the caller overlay several routes at once.
+     *
+     * Emits `shown-change` once the new entry is up.
+     */
+    showEntry(entryId: string): Promise<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.
+     */
+    hideEntry(entryId: string): Promise<void>;
+    /**
+     * Drop a single entry from history. Hides it from the map first (clears its routing module)
+     * then removes it from `_entries`. Emits `entries-change`. No-op when the id is unknown.
+     */
+    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.
+     */
+    get currentEntryModule(): RoutingModule_2 | undefined;
     get entries(): readonly RoutesEntry[];
     get currentRoutes(): Routes_2 | undefined;
     get currentWaypoints(): WaypointLike_2[] | undefined;
     /** Sparse nullable slots being assembled before triggering a route calculation. */
     get planningSlots(): PlanningWaypoint[];
     get params(): RouteParams;
-    addRoutes(routes: Routes_2, waypoints: WaypointLike_2[], label: string): void;
+    addRoutes(routes: Routes_2, waypoints: WaypointLike_2[], label: string): 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
+     * the entry doesn't exist.
+     */
+    addAnalysisToEntry(entryId: string, analysis: RoutesAnalysis): boolean;
     setWaypointAt(index: number, waypoint: WaypointLike_2): void;
     setParams(params: Partial<RouteParams>): void;
     reset(): void;
 }
 
+/**
+ * Events fired by {@link RoutingState}. Subscribe via `state.routing.events.on(type, handler)`.
+ *
+ * @group Agent Toolkit
+ */
+declare type RoutingStateEvents = {
+    /** Route history changed — new calculation stored, analysis attached, or cleared via `reset()`. */
+    'entries-change': readonly RoutesEntry[];
+    /** Sparse waypoint planning slots changed (origin/stop/destination assignment). */
+    'planning-change': readonly PlanningWaypoint[];
+    /** Route parameters (alternatives, cost model, depart/arrive time) changed. */
+    'params-change': RouteParams;
+    /** A new analysis was attached to (or replaced on) a routes entry. */
+    'analysis-added': {
+        entryId: string;
+        analysis: RoutesAnalysis;
+    };
+    /** Set of routes entries currently rendered on the map changed (multi-show under `multiple`). */
+    'shown-change': ReadonlySet<string>;
+    /** Display policy switched between `single` and `multiple`. */
+    'mode-change': EntryMode;
+};
+
+/**
+ * State slice that owns a set of "entries" (routes, ranges) where each entry can be hidden
+ * individually by id and the slice exposes the currently-shown set. Implemented by
+ * {@link RoutingState} and {@link RangeState}; consumed by helpers that need to hide
+ * previously-shown entries before rendering a new one (see `hidePreviousShownEntries`).
+ *
+ * Not implemented by {@link PlacesState}, which uses a wider per-entry marker-type model
+ * (`removeShownEntries(ids)` rather than `hideEntry(id)`).
+ *
+ * @group Agent Toolkit
+ */
+declare interface ShownEntriesSlice extends StateSlice {
+    readonly entryMode: EntryMode;
+    readonly shownEntryIds: ReadonlySet<string>;
+    hideEntry(entryId: string): Promise<void>;
+}
+
+/**
+ * Compact snapshot of the user-visible parts of `ToolState`. Designed to be diffable: every field
+ * is serialisable to JSON and stable for `===` comparison when the underlying state hasn't changed.
+ *
+ * @group Agent Toolkit
+ */
+export declare type StateDigest = {
+    places: {
+        /** Entry ids currently rendered as individual pins, sorted ascending. */
+        shownAsPin: string[];
+        /** Entry ids currently rendered as base-map POIs, sorted ascending. */
+        shownAsBaseMap: string[];
+        /** Display policy in force on the slice — `multiple` (default) or `single`. */
+        entryMode: EntryMode;
+    };
+    routes: {
+        /** Routes-entry ids currently drawn on the map, sorted ascending. */
+        shown: string[];
+        /** Display policy in force on the slice — `multiple` (default) or `single`. */
+        entryMode: EntryMode;
+    };
+    ranges: {
+        /** Range-entry ids currently drawn on the map, sorted ascending. */
+        shown: string[];
+        /** Display policy in force on the slice — `multiple` (default) or `single`. */
+        entryMode: EntryMode;
+    };
+    traffic: {
+        /** Whether a TrafficAreaAnalytics visualization is active. */
+        analyticsActive: boolean;
+    };
+    incidents: {
+        /** Traffic-incidents entry ids currently rendered on the map, sorted ascending. */
+        shown: string[];
+        /** Entry ids currently being polled by the per-entry network monitor, sorted ascending. */
+        monitored: string[];
+        /** Display policy in force on the slice — `multiple` (default) or `single`. */
+        entryMode: EntryMode;
+    };
+};
+
+/**
+ * @module agent-toolkit-state
+ *
+ * Tiny typed event emitter used by every state slice (PlacesState, RoutingState, ...) to notify
+ * subscribers when their internals change. The shape mirrors the SDK's `ModuleEvents` API
+ * (`on(type, handler) => unsubscribe`, `off(type)`) so consumers see one consistent pattern across
+ * the SDK and the agent toolkit. Designed to plug straight into React's `useSyncExternalStore`.
+ *
+ * @group Agent Toolkit
+ */
+/**
+ * Generic typed event bus. The `EventMap` parameter declares the set of event names this emitter
+ * supports along with each event's payload type — `on` and `emit` are then strongly typed against it.
+ *
+ * Usage from outside the slice (subscribe-only):
+ * ```ts
+ * const unsub = state.places.events.on('entries-change', (entries) => render(entries));
+ * // ...
+ * unsub();
+ * ```
+ *
+ * @group Agent Toolkit
+ */
+declare class StateEvents<EventMap extends Record<string, unknown>> {
+    private readonly handlers;
+    /**
+     * Subscribe to an event. Returns an unsubscribe function that removes only this handler.
+     */
+    on<K extends keyof EventMap>(type: K, handler: (payload: EventMap[K]) => void): () => void;
+    /** Remove all handlers for a given event type. Use the unsubscribe from `on` for single-handler removal. */
+    off<K extends keyof EventMap>(type: K): void;
+    /* Excluded from this release type: emit */
+    /** Drop every handler for every type. Used by slice `reset()` to detach lingering listeners. */
+    clear(): void;
+}
+
 /**
  * Common interface for state slices. Implement `reset()` to participate
  * in cleanup when `destroy()` is called on the agent.
@@ -609,6 +1545,30 @@ export declare interface StateSlice {
  */
 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.
+ *
+ * @group Agent Toolkit
+ */
+export declare type ToolBuildOptions = {
+    /** Active feature flags. */
+    featureFlags?: FeatureFlags;
+};
+
+/**
+ * A registered tool definition: either a static {@link ToolEntry} or a
+ * {@link ToolEntryBuilder} that builds one from {@link ToolBuildOptions} at
+ * agent-creation time. Used wherever the tool registry, resolver, and
+ * setup pipeline accept either form interchangeably.
+ *
+ * @typeParam S - The ToolState shape this tool requires. Default: base `ToolState`.
+ *
+ * @group Agent Toolkit
+ */
+export declare type ToolDefinition<S extends ToolState = ToolState> = ToolEntry<S> | ToolEntryBuilder<S>;
+
 /**
  * A tool definition — the universal format for both built-in and third-party tools.
  * Combines execution (inputSchema + execute) with classifier metadata.
@@ -640,6 +1600,17 @@ export declare type ToolEntry<S extends ToolState = ToolState> = {
     dependsOn?: 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).
+ *
+ * @typeParam S - The ToolState shape this tool requires. Default: base `ToolState`.
+ *
+ * @group Agent Toolkit
+ */
+export declare type ToolEntryBuilder<S extends ToolState = ToolState> = (options: ToolBuildOptions) => ToolEntry<S>;
+
 /**
  * Metadata for an agent toolkit tool.
  *
@@ -691,7 +1662,7 @@ export declare type ToolNameHint = ToolName | (string & {});
  * function createMyTool(state: ToolState) {
  *   return tool({
  *     execute: async () => {
- *       const module = await state.places.getPlacesModule();
+ *       const pins = await state.places.getPinPlacesModule();
  *       state.routing.currentRoutes;  // most recent routes
  *       state.baseMap.mapLibreMap;    // MapLibre instance
  *     }
@@ -700,7 +1671,7 @@ export declare type ToolNameHint = ToolName | (string & {});
  * ```
  */
 export declare type ToolState = {
-    /** Place search, geocoding, and geometries state. */
+    /** Places layer: PlacesModule plus an append-only search history. */
     places: PlacesState;
     /** Map POI layer: visibility, filtering, and category management. */
     mapPOIs: MapPOIsState;
@@ -708,36 +1679,335 @@ export declare type ToolState = {
     routing: RoutingState;
     /** Base map display: style, language, viewport, layers, and hillshade. */
     baseMap: BaseMapState;
-    /** Traffic flow and incident overlay state. */
-    traffic: TrafficState;
+    /** Traffic tile overlays: flow tiles + incident overlay tiles. */
+    trafficTiles: TrafficTilesState;
+    /** Traffic area analytics: aggregation module + last result + viz config. */
+    trafficAreaAnalytics: TrafficAreaAnalyticsState;
+    /** Traffic incidents: fetched entry history and per-entry rendering. */
+    trafficIncidents: TrafficIncidentsState;
     /** Reachable range results: origin, budgets, and bbox summaries. */
     ranges: RangeState;
+    /** Derived/custom polygon entries — output of processGeometries. */
+    customGeometries: CustomGeometriesState;
 };
 
 /**
- * State for traffic: flow layer, incident overlay, and area analytics modules.
+ * 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}.
  *
  * @group Agent Toolkit
  */
-declare class TrafficState implements StateSlice {
+declare class TrafficAreaAnalyticsState implements StateSlice {
     private readonly _ttMap;
-    private _trafficFlowModule?;
-    private _trafficIncidentsModule?;
     private _trafficAreaAnalyticsModule?;
     private _lastAreaAnalytics?;
     private _currentAnalyticsConfig?;
     private _configChangeUnsub?;
+    /** Subscribe to state changes — see {@link TrafficAreaAnalyticsStateEvents}. */
+    readonly events: StateEvents<TrafficAreaAnalyticsStateEvents>;
     constructor(_ttMap: TomTomMap);
-    getTrafficFlowModule(): Promise<TrafficFlowModule>;
-    getTrafficIncidentsModule(): Promise<TrafficIncidentsModule>;
     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;
-    onAnalyticsShown?: (analytics: TrafficAreaAnalytics, module: TrafficAreaAnalyticsModule) => void;
-    onAnalyticsCleared?: () => void;
+    /**
+     * 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;
+    reset(): void;
+}
+
+/**
+ * Events fired by {@link TrafficAreaAnalyticsState}. Subscribe via
+ * `state.trafficAreaAnalytics.events.on(type, handler)`.
+ *
+ * @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;
+    };
+    /** The active analytics visualization was cleared or replaced. */
+    'analytics-cleared': void;
+    /** Module-level visualization config changed (mode, metric, scaleMode, ...). */
+    'config-change': TrafficAreaAnalyticsConfig | undefined;
+};
+
+declare type TrafficIncidentsEntry = {
+    id: string;
+    timestamp: number;
+    label: string;
+    data: TrafficIncident[];
+    /**
+     * The captured query that produced this entry. Replayed by the monitor on each tick so
+     * polling stays in the same slice the entry was loaded with. Reuses the loader's own
+     * params shape; the entry stores a resolved {@link BBox} tuple in `bbox` (the loader
+     * normalises any GeoJSON value before handing the params off).
+     */
+    params: TrafficIncidentDetailsByBBoxParams & {
+        bbox: BBox;
+    };
+    /**
+     * Per-entry analysis registry: owns re-executing specs *and* their results.
+     * Lazy-created on first {@link TrafficIncidentsState.setAnalysisSpec} or
+     * {@link TrafficIncidentsState.addAnalysisToEntry}.
+     */
+    _analyses?: IncidentsAnalyses;
+    /**
+     * Per-entry incident-details module. Each entry owns its own module so two areas can be
+     * rendered on the map at the same time without sharing a single source. Lazy-initialised
+     * via `TrafficIncidentsState.getEntryModule` — undefined until first show. Subscribe to
+     * clicks via `module.events.on('click', ...)` once retrieved.
+     */
+    _module?: TrafficIncidentOverlayModule;
+    /** True while this entry is currently rendered on the map. */
+    _shown?: boolean;
+    /**
+     * Focused subset on this entry — the agent's `focusIds` write-side. Drives the dim/highlight
+     * affordance on `_module` and feeds `focusedFeatures(entryId)` for stepping through.
+     */
+    _focus?: {
+        ids: Set<string>;
+        reason?: string;
+    };
+    /**
+     * Per-entry polling loop. Lazy-created on first {@link TrafficIncidentsState.startMonitoring}
+     * call; reused across stop/start cycles. Owns timer, status, error, captured area.
+     */
+    _monitor?: IncidentMonitor;
+    /**
+     * Monotonic counter incremented on every {@link TrafficIncidentsState.replaceEntryData}
+     * call. Used to detect out-of-order ticks: if a slow `module.show()` from an earlier
+     * tick resolves after a newer tick has already overwritten `data`, the late path bails
+     * before reapplying focus / replaying analyses.
+     */
+    _tick?: number;
+};
+
+/**
+ * State for traffic incidents: entry history and map rendering via per-entry
+ * TrafficIncidentOverlayModule. Each entry can be a separate area; under the default
+ * `multiple` mode several entries can render at once.
+ *
+ * Each entry owns its own module (lazy-init on first show) plus an optional per-entry
+ * background monitor. Subscribe to changes via `events.on('...')`.
+ *
+ * @group Agent Toolkit
+ */
+declare class TrafficIncidentsState implements StateSlice {
+    private readonly _ttMap;
+    private _entries;
+    private _entryMode;
+    /** Subscribe to state changes — see {@link TrafficIncidentsStateEvents}. */
+    readonly events: StateEvents<TrafficIncidentsStateEvents>;
+    constructor(_ttMap: TomTomMap);
+    get entries(): readonly TrafficIncidentsEntry[];
+    /**
+     * Display policy: `multiple` (default) keeps every history entry available to render
+     * simultaneously; `single` enforces "at most one entry on the map at a time" and trims
+     * the history down to the latest entry whenever it's set.
+     */
+    get entryMode(): EntryMode;
+    /**
+     * Switch the display policy. When moving from `multiple` → `single` we hide every entry
+     * older than the latest, drop them from history, and emit `entries-change`. No-op when the
+     * mode hasn't changed.
+     */
+    setEntryMode(mode: EntryMode): Promise<void>;
+    /** Set of entries currently rendered on the map. */
+    get shownEntryIds(): ReadonlySet<TrafficIncidentsEntry['id']>;
+    /**
+     * Append a new entry to the history. Under `single` mode the new entry replaces every
+     * older one (and tears their modules + monitors down). `sampledAt` is the moment the
+     * data was captured — pass one canonical value per "moment" so future joins (entry
+     * data ↔ derived analyses) are byte-equal. Returns the assigned id.
+     */
+    addIncidentsEntry(data: TrafficIncident[], params: TrafficIncidentDetailsByBBoxParams & {
+        bbox: BBox;
+    }, label: string, sampledAt: number, explicitId?: string): 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
+     * panel stay in sync with the freshest snapshot. `sampledAt` is the canonical moment
+     * for this update — propagated to the entry timestamp and to every analysis the
+     * registry replays, so all derived data shares one tick. Returns true on success,
+     * false when the entry is unknown.
+     */
+    replaceEntryData(entryId: TrafficIncidentsEntry['id'], data: TrafficIncident[], sampledAt: number): Promise<boolean>;
+    /**
+     * Lazy-init and return the entry's TrafficIncidentOverlayModule. Consumers subscribe to
+     * clicks directly on the returned module via `module.events.on('click', ...)`; use
+     * `module.distinctIncidents(features)` inside the handler if a stacked-click count is
+     * needed. Throws on unknown entry id.
+     */
+    getEntryModule(entryId: TrafficIncidentsEntry['id']): Promise<TrafficIncidentOverlayModule>;
+    /**
+     * Render an entry on the map. Lazy-inits its module, pushes the entry's incidents, and
+     * (when `fitBounds` is true) fits the camera to the entry's bbox. Emits `shown-change`
+     * once the entry transitions to shown.
+     */
+    showEntry(entryId: TrafficIncidentsEntry['id'], fitBounds?: boolean): Promise<void>;
+    /**
+     * Hide an entry — clears its module + drops focus. The module reference stays on the
+     * entry for cheap re-show. No-op when the entry is unknown or already hidden.
+     */
+    hideEntry(entryId: TrafficIncidentsEntry['id']): Promise<void>;
+    /**
+     * Drop an entry from history. Hides it from the map and stops its monitor if any.
+     * Emits `entries-change` and, when the entry was shown, `shown-change`. No-op when the
+     * id is unknown.
+     */
+    removeEntry(entryId: TrafficIncidentsEntry['id']): Promise<void>;
+    /**
+     * Attach an analysis result to an existing entry. Names are unique within a single
+     * entry — adding one with an existing name replaces it. Returns true on success, false
+     * if the entry doesn't exist. Lazy-creates the entry's {@link IncidentsAnalyses}.
+     */
+    addAnalysisToEntry(entryId: TrafficIncidentsEntry['id'], analysis: IncidentsAnalysis): boolean;
+    /**
+     * Register (or replace) a re-executing analysis spec on its source entry. Names are unique
+     * per entry — adding one with an existing name replaces it. Lazy-creates the entry's
+     * {@link IncidentsAnalyses} on first call.
+     */
+    setAnalysisSpec(spec: IncidentsAnalysisSpec): void;
+    /** Remove a spec by name from every entry that carries it. */
+    removeAnalysisSpec(name: string): void;
+    /** Snapshot of an entry's focus subset, or null when no focus is active or the entry is unknown. */
+    getFocus(entryId: TrafficIncidentsEntry['id']): IncidentFocus | null;
+    /**
+     * Set the focus subset on a specific entry. Filters ids against the entry's current
+     * incidents (drops unknown ones) and pushes the result onto the entry's module.
+     * Returns the kept count and any dropped ids.
+     */
+    setFocus(entryId: TrafficIncidentsEntry['id'], ids: readonly string[], reason?: string): {
+        focusedCount: number;
+        droppedIds: string[];
+    };
+    clearFocus(entryId: TrafficIncidentsEntry['id']): void;
+    /**
+     * The focused incidents in the order passed to {@link setFocus}. Empty when no focus is
+     * active on the entry or when the entry is unknown. Used by UI layers that step through
+     * the focused subset (prev/next).
+     */
+    focusedFeatures(entryId: TrafficIncidentsEntry['id']): TrafficIncident[];
+    /**
+     * Fly the camera to the i-th focused incident on an entry (0-based). Wraps out-of-range
+     * indices so callers can pass raw prev/next counters. No-op when the entry has no active
+     * focus. Line geometries fitBounds; points flyTo with a sensible zoom.
+     */
+    navigateFocus(entryId: TrafficIncidentsEntry['id'], index: number): void;
+    /**
+     * Walk entries newest-first to find which one currently holds an incident with this id.
+     * Useful for UI layers that hold an incident id without remembering which entry produced it.
+     */
+    findEntryWithIncident(incidentId: string): TrafficIncidentsEntry | undefined;
+    /**
+     * Start polling for an entry. Lazy-creates an {@link IncidentMonitor}, wires its events
+     * once, then delegates to {@link IncidentMonitor.start}. No-op when polling is already
+     * running. Throws on unknown entry id.
+     */
+    startMonitoring(entryId: TrafficIncidentsEntry['id'], area: MonitoredArea, deps: IncidentMonitorDeps, opts?: {
+        intervalMs?: number;
+    }): void;
+    /** Stop polling. No-op when idle or unknown. */
+    stopMonitoring(entryId: TrafficIncidentsEntry['id']): void;
+    /**
+     * True when the entry is *currently* being polled. A monitor stuck in
+     * `stopped-error` returns false here so the start tool can report a truthful
+     * `alreadyRunning` and a fresh `start` call actually re-arms the timer
+     * instead of silently being treated as a no-op.
+     */
+    isMonitored(entryId: TrafficIncidentsEntry['id']): boolean;
+    private _createMonitorForEntry;
+    private _requireEntry;
+    private _uniqueEntryId;
+    private _rerunRegisteredSpecs;
+    private _teardownEntry;
+    reset(): void;
+}
+
+/**
+ * Events fired by {@link TrafficIncidentsState}. Subscribe via
+ * `state.trafficIncidents.events.on(type, handler)` — returns an unsubscribe function.
+ *
+ * @group Agent Toolkit
+ */
+declare type TrafficIncidentsStateEvents = {
+    /** History changed — entry added, replaced, removed, or cleared via `reset()`. Payload: full entries snapshot. */
+    'entries-change': readonly TrafficIncidentsEntry[];
+    /** Set of entries currently rendered on the map changed. */
+    'shown-change': ReadonlySet<TrafficIncidentsEntry['id']>;
+    /**
+     * A fresh analysis result landed on an entry. Fires when a spec is first
+     * registered, when it is replaced under the same name, AND on every monitor-tick
+     * replay — the event is intentionally agnostic about whether the spec is new
+     * or recomputed; subscribers re-render off the latest result either way.
+     */
+    'analysis-change': {
+        entryId: TrafficIncidentsEntry['id'];
+        analysis: IncidentsAnalysis;
+    };
+    /** Focus subset for an entry changed (or cleared, when `focus === null`). */
+    'focus-change': {
+        entryId: TrafficIncidentsEntry['id'];
+        focus: IncidentFocus | null;
+    };
+    /** Display policy switched between `single` and `multiple`. */
+    'mode-change': EntryMode;
+    /** A monitored entry produced a fresh snapshot (per-tick). */
+    'monitor-tick': {
+        entryId: TrafficIncidentsEntry['id'];
+        snap: IncidentSnapshot;
+    };
+    /** A monitored entry's poll failed — slice has cleared the timer. */
+    'monitor-error': {
+        entryId: TrafficIncidentsEntry['id'];
+        error: string;
+    };
+    /**
+     * Polling began on an entry (idle → running). Skipped when `startMonitoring`
+     * was a no-op against an already-running monitor.
+     */
+    'monitor-start': {
+        entryId: TrafficIncidentsEntry['id'];
+    };
+    /**
+     * Polling halted on an entry. `reason: 'manual'` covers explicit
+     * `stopMonitoring` and entry teardown (remove / single-mode trim / reset).
+     * `reason: 'error'` fires alongside `monitor-error` — error-only listeners
+     * keep using `monitor-error`; lifecycle listeners can rely on this alone.
+     */
+    'monitor-stop': {
+        entryId: TrafficIncidentsEntry['id'];
+        reason: 'manual' | 'error';
+    };
+};
+
+/**
+ * State for traffic tile overlays — flow tiles and incident overlay tiles. These are
+ * raster/tile layers that the user toggles on top of the base map; result caching and
+ * per-result rendering for incident *features* lives in {@link TrafficIncidentsState},
+ * and analytics aggregations in {@link TrafficAreaAnalyticsState}.
+ *
+ * @group Agent Toolkit
+ */
+declare class TrafficTilesState implements StateSlice {
+    private readonly _ttMap;
+    private _trafficFlowModule?;
+    private _trafficIncidentsModule?;
+    constructor(_ttMap: TomTomMap);
+    getTrafficFlowModule(): Promise<TrafficFlowModule>;
+    getTrafficIncidentsModule(): Promise<TrafficIncidentsModule>;
+    get trafficFlowModule(): TrafficFlowModule | undefined;
+    get trafficIncidentsModule(): TrafficIncidentsModule | undefined;
     reset(): void;
 }