TomTom Maps SDK for JavaScript
This is the documentation of version 1.0.0-rc.4. Go to the latest version, 1.0.0-rc.5.

Code generation

Experimental. analyseData, processData, createTracker, clusterIncidents and executeMaplibreCode run model-written JavaScript. Their inputs, injected identifiers and output contracts may change without notice. In the browser, the data tools' code runs isolated with no DOM, storage or network. If the isolation can't start, they return an error instead. executeMaplibreCode, and the data tools under Node or SSR, run in your app's own realm, with its privileges. Read the threat model before shipping.

Five tools take JavaScript as a parameter instead of a fixed argument list (clusterIncidents optionally). The model writes the code. The plugin compiles it with new AsyncFunction(...paramNames, code) and calls it with the injected inputs.

This lets the agent answer open-ended questions, such as "bar chart of POI categories", "union the boundaries of these cities" or "focus the camera on the worst traffic on the route", without a dedicated parameter for every variation. Each tool covers one intent, with any computation inside.

Where it shows up

Family Tools What the code does
Analyse analyseData Aggregate state into a result, such as counts, group-bys, top-N, hex bins, Chart.js configs or cross-kind correlations. Read-only. The result is recorded against every contributing entry and returned to the model. monitor: true recomputes it whenever a source entry changes, and monitorAnalysis switches that on or off later.
Process processData Transform state into one new entry: places (with optional attached geometries and placeConnections), standalone geometries (a new customGeometries entry), or byod. fitOnMap moves the camera alongside any of them.
Track createTracker Return a verdict { active, members, summary } over the same inputs as analyseData, saying whether a watched condition holds now. It recomputes whenever a source entry changes.
Cluster clusterIncidents Optional: filter or combine the inputs, then return cluster(...). Without code, the tool runs its default clustering.
MapLibre executeMaplibreCode Run arbitrary JS against the live map for anything no other tool covers, such as custom layers, animations or raster overlays. Returns a diff of added / removed / updated sources and layers. Not a default tool, so you add it yourself.

Execution model

Each tool that accepts code builds an AsyncFunction whose parameters are a fixed set of injected identifiers, then calls it. analyseData, processData and clusterIncidents narrow their inputs per turn. See Scope-aware data tools.

Where the code runs:

The body works like any other async function body. Top-level await, locals and helper consts are fine, and the body must end with return …;. Note that:

Pre-flight sanitisation

LLMs regularly prepend const turf = require('@turf/turf'), const h3 = await import('h3-js') or const placesByEntry = arguments[0].placesByEntry out of habit. These collide with the injected parameters and would throw at parse time ("Identifier 'X' has already been declared") before the body runs.

The plugin removes those lines, but only if the right-hand side is one of:

A const geometriesByEntry = … that genuinely shadows an injected name (e.g. const geometriesByEntry = placesByEntry['places-2'].features.map(...)) stays untouched. This is deliberate, because a naive name-only filter would silently corrupt legitimate user code.

Input copying

The plugin copies the injected state inputs before they reach the code, on every path. These are the per-entry records such as placesByEntry, plus previous / now on monitored runs. The browser's isolated run receives a structured clone. Mutating them in place is safe and local:

// Sorting/splicing the injected collection touches a throwaway copy, never live state.
const places = placesByEntry['places-2'];
places.features.sort((a, b) => a.properties.score - b.properties.score);
return { places: { type: 'FeatureCollection', features: places.features.slice(0, 10) } };

Without the copy, an in-place mutation would corrupt the entry the data came from and leak into later turns. The libraries are passed through unchanged.

Shadowed globals

Inside the data tools' code (every tool above but executeMaplibreCode), the plugin binds a fixed set of network, storage, DOM and process globals to undefined, wherever the code runs. They are fetch, XMLHttpRequest, WebSocket, EventSource, localStorage, sessionStorage, indexedDB, document, window, globalThis, self, navigator, importScripts and process. Code that reaches for one fails loudly instead of making a network call or touching browser state.

This is a tripwire, not a security boundary. The same capabilities stay reachable through constructor walks (({}).constructor.constructor) and other realm escapes, so it catches accidental access, not a determined or jailbroken model. executeMaplibreCode is not shadowed, because it needs live browser access. In the browser, the isolated run is the boundary.

Injected identifiers

Tool Injected identifiers
analyseData placesByEntry, routesByEntry, incidentsByEntry, geometriesByEntry, trafficAreaAnalyticsByEntry, byodByEntry, h3, turf, routeUtils, cluster (plus previous, now, log when the analysis is monitored)
processData same as analyseData, without the monitor extras
clusterIncidents same as analyseData, with previous, now and log on every run (previous holds the last clustering while the recipe stays the same)
createTracker same as processData on the first run; re-runs add now and log, with previous always undefined
executeMaplibreCode map (live MapLibre Map instance)

There is one per-entry record per kind, mapping an entry id to that entry's data, and no merged variable:

Read one entry by id (placesByEntry['places-2']). To span every requested entry of a kind, merge with Object.values(...). Use Object.values(placesByEntry).flatMap((fc) => fc.features) for the FeatureCollection kinds (places / routes / byod / trafficAreaAnalytics), and Object.values(incidentsByEntry).flat() for the array kinds (incidents / geometries).

A record is undefined if the tool call left out its *EntryIDs argument, so code must guard before reading (if (placesByEntry) ..., placesByEntry['places-2']?.features.length, etc.). Scope narrowing trims which kinds the tool documents in its prompt, but the sandbox always carries the full set of names. Out-of-scope kinds arrive as undefined.

Shared libraries

The four data tools get four libraries. executeMaplibreCode gets none, only map:

All four are pure computation. None does spatial search, place lookup or HTTP. To fetch new places, the agent must call discoverPlaces (or locatePlace) before the code-generation tool and pass the resulting entry id in.

Turf input gotchas

Turf is fussy about input shape. If it throws, the runtime hints at the right pattern, but knowing the rules up front avoids the retry loop:

Performance hints

For large-N nearest/within queries, pre-bucket points with h3 before running turf:

const cells = points.map((p) => h3.latLngToCell(p.geometry.coordinates[1], p.geometry.coordinates[0], 8));
// Only run turf on same- or neighbour-cell pairs — O(N+M) instead of O(N·M).

Pick res so each cell is approximately your query radius (h3 res 8 ≈ 460 m edge, res 9 ≈ 175 m).

Output contract

analyseData: outputFormat

The accepted chart types are bar, line, pie, doughnut, radar, polarArea, scatter and bubble. The tool rejects a config with any other type before the result reaches the model.

For per-point detail you'd normally put in a Chart.js tooltip.callbacks function, use a string[] label, because functions don't survive the JSON boundary. Chart.js renders the label multi-line both on the axis tick and in the tooltip title.

processData envelope

processData code returns { places?, placeConnections?, geometries?, fitOnMap?, byod? }, with at least one of places, geometries, fitOnMap or byod:

Return-value validation

analyseData runs its return value through three checks before handing it to the model, as do clusterIncidents code and tracker re-runs. processData validates its envelope instead, and executeMaplibreCode returns its value as is:

  1. Not undefined. If the body doesn't return (e.g. the code was written as (args) => { return … } so the arrow is created and discarded), the tool surfaces a targeted error telling the model to drop the arrow wrapper.
  2. JSON.parse(JSON.stringify(value)). This converts NaN, Infinity, undefined object values and sparse arrays to null or drops them. These silent-poison values would otherwise break the next turn's ModelMessage validation. Circular references throw and surface as a clear error for the model.
  3. Chart shape check (for outputFormat: "chart" only). The type must be in the whitelist above and data must be a non-null object.

As a result, anything that comes out of the sandbox is either safe to round-trip through the model's next prompt, or surfaces a precise diagnostic the model can act on.

Self-correcting error hints

When sandbox code throws, the runtime matches the message against a curated list of common pitfalls and appends a targeted Hint: to the error returned to the model. The model usually fixes the code on the next attempt.

The recognised patterns include:

Pattern What the hint redirects toward
Cannot read property of undefined/null Missing ?. / ??, or a reduce callback without return acc / initial value.
h3.X is not a function / turf.X is not a function Library purpose (hex math / GeoJSON geometry). Rejects spatial-search / HTTP use and suggests discoverPlaces instead.
coordinates must be an Array / Unknown Geometry Type Pass the feature, not bare coordinates. Guard mixed-kind arrays like incidentsByEntry[id].
Illegal return statement Mismatched braces in a multi-line .map((item) => { ... }).
Identifier 'X' has already been declared Dropped redeclaration (rare after the sanitiser).
Unexpected token / identifier / end of input Body didn't parse as an async-function body, because of unbalanced braces or a stray import/export.
require is not defined / import outside a module The sandbox is not a Node module. Inputs and libraries are already injected.
functions / tools / discoverPlaces / recallState is not defined The sandbox can't call other tools. List entry ids in the tool input, or call the tool before this one.
is not iterable Default with ?? [] before for..of / spread / destructuring.
Cannot access 'X' before initialization Temporal dead zone. Move the declaration above the first use.
Assignment to constant variable Use let or mutate in place.
structuredClone / DataCloneError / could not be cloned The return value isn't pure JSON (no functions, no classes, no DOM/Map refs). Use string[] labels instead of tooltip callbacks.

The tool descriptions therefore needn't spell out every guardrail. The runtime corrects the model when it trips.

Threat model

In the browser, the data tools' code is isolated. Everywhere else, the security boundary is the model and the prompt path you let users drive, not the runtime. Input copying and shadowed globals stop accidental mutation and casual global access, not a determined model. Treat that code like a <script> tag controlled by your model provider:

If your deployment can't tolerate this, for example on a page with privileged session cookies or sensitive in-browser state, remove the code-generation tools:

const agent = createMapAgent(map, {
    model: openai('gpt-4o'),
    tools: {
        analyseData: false,
        processData: false,
        createTracker: false,
        clusterIncidents: false,
    },
});

The fixed-schema tools (locatePlace, setRoute, findReachableAreas, the display tools, …) stay usable either way.

Adding executeMaplibreCode

executeMaplibreCode isn't in DEFAULT_TOOLS, because its code runs in your page with no sandbox. Add it only where you trust the model and every prompt and tool result it reads, such as an internal tool behind your own sign-in:

import { createExecuteMaplibreCodeTool, createMapAgent } from '@tomtom-org/maps-sdk-plugin-agent-toolkit';

const agent = createMapAgent(map, {
    model: openai('gpt-4o'),
    tools: { executeMaplibreCode: createExecuteMaplibreCodeTool() },
});

Without it, the agent has no tool for raster overlays or time-based animations.

Data-tool execution isolation (experimental)

In the browser, the data tools' code runs off the main thread in a locked-down realm, a Web Worker inside a sandboxed, opaque-origin <iframe>. The environment picks where it runs (selection by environment). A page without a Content Security Policy needs no setup, and a page with one must allow what the sandbox needs. To tune the browser run, use the optional codeExecution:

const agent = createMapAgent(map, {
    model: openai('gpt-4o'),
    codeExecution: {
        timeoutMs: 5000, // wall-clock budget per isolated run (default 10000)
    },
});

What this buys you, and what it doesn't:

How the pieces fit

The generated code runs two hops away from your app, across an opaque-origin iframe and into a Web Worker. postMessage + structuredClone is the only channel between them:

Main thread (host realm)Opaque-origin sandboxed iframe · CSP default-src 'none'Node / SSR — no browser sandbox APIs → mainThreadExecutor (NOT a boundary)analyseData · processDatacreateTracker · clusterIncidentsIframeWorkerExecutor (splits args, 10 s timeout)bootstrap (relays parent ⇄ worker)Web Worker (Blob URL)worker-libs (lazy chunk) — self.turf · self.h3 · self.routeUtils · self.clusterworker-runtime — new AsyncFunction(…) runSandboxedFn(code, args) provides turf / h3 / routeUtils / clusterpostMessagepostMessage (structuredClone){ ok, value } | { error }

Each boundary stops one threat. The opaque origin stops DOM and storage access, the CSP stops network egress, and worker termination stops runaway loops. The libraries are bundled into the worker, so generated code never imports them.

Why a worker inside an iframe

The two-layer nesting isn't redundant. Each layer provides a boundary the other can't:

Running off the main thread is also why heavy turf/h3 computation over large FeatureCollections doesn't freeze the map UI. The postMessage + structuredClone hop still pays a serialization cost at each edge, so it's a net win for compute-heavy bodies, not zero main-thread work.

Worker libraries (turf / h3 / routeUtils / cluster)

The worker can't import your app's modules, so it needs the libraries as one self-contained script. The plugin ships them in a separate lazy chunk, loaded only when the isolated run first starts, so your main bundle is unaffected.

To pin a build, override it with loadWorkerLibrarySource. Return UMD or IIFE JavaScript that defines self.turf and self.h3, plus self.routeUtils and self.cluster if generated code uses them. The override replaces the bundled source, so re-supply every namespace your code relies on:

codeExecution: {
    loadWorkerLibrarySource: async () => {
        const turf = await (await fetch('/vendor/turf.min.js')).text();
        const h3 = await (await fetch('/vendor/h3-js.umd.js')).text();
        // turf first — routeUtils reads self.turf. Append your own routeUtils / cluster
        // scripts here too if your generated code calls them.
        return `${turf}\n;${h3}`;
    },
},

What your page must allow

The sandbox starts on the first code run. It needs three things from your page:

For example, a policy that lets the sandbox start:

Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; worker-src blob:

Note that browsers ignore 'unsafe-inline' when script-src also lists a nonce or a hash, so the sandbox can't start under such a policy. The sources above relax your page's own policy too. If your page can't allow them, remove the data tools instead.

If the sandbox does not start

If the iframe doesn't start, the code-running tool returns an error to the model, runs nothing and logs a console warning once. A monitored analysis or tracker skips that re-run. A call 30 seconds or more later tries to start the iframe again, so a failure that passes, such as a dropped download, recovers on its own. A page with no Worker fails the same way. With allowMainThreadFallback, that failure is final: later runs stay in the page and do not try the iframe again.

To see where generated code runs, call agent.getCodeExecutionMode():

Mode Where the code runs
not-started Nowhere yet. In the browser, the iframe starts on the first code run.
iframe-worker In the isolated Web Worker.
unavailable Nowhere. The last start failed, so the data tools return errors until a start 30 seconds or more later succeeds.
main-thread In your page, not isolated. This is Node or SSR, or a browser that set allowMainThreadFallback and whose iframe failed to start.

For example, to tell your users when data analysis is off:

const agent = createMapAgent(map, {
    model: openai('gpt-4o'),
    onToolExecute: () => {
        if (agent.getCodeExecutionMode() === 'unavailable') showNotice('Data analysis is unavailable on this page.');
    },
});

To run the code in your page when the iframe can't start, set allowMainThreadFallback. The code then has your page's privileges, as the threat model describes, so turn it on only where you trust the model:

codeExecution: {
    allowMainThreadFallback: true, // not isolated: runs generated code in the page if the iframe can't start
},

Selection by environment

The environment chooses where the code runs:

Environment Runs in Why
Browser iframe-worker The boundary is the iframe's opaque origin + CSP egress-block + worker termination.
Node / SSR main thread None of those layers exist server-side. A worker_thread would add only termination while exposing fs / net / child_process, which is isolation in name only, so we don't spin one up. The main-thread runner still deep-copies inputs so code can't corrupt live state, but it's defense-in-depth, not a boundary.

In the browser, the code runs in your page only if you set allowMainThreadFallback and the iframe fails to start. That choice does not retry the iframe.

Experimental. The isolation depends on real-browser behaviour — CSP enforcement, opaque-origin iframes, worker termination — which an end-to-end suite verifies in real Chromium on every CI run. executeMaplibreCode is not isolated, because it needs the live map.

Example

A user asks "Bar chart of how many places of each category we have." The classifier picks analyseData with toolScopes.analyseData = { kinds: ['places'] }, which narrows its schema to places. The model emits:

analyseData({
    placesEntryIDs: ['places-2'],
    name: 'category-bar',
    outputFormat: 'chart',
    code: `
        const counts = {};
        for (const p of placesByEntry['places-2'].features)
            for (const c of (p.properties.poi?.categories ?? []))
                counts[c] = (counts[c] ?? 0) + 1;
        const entries = Object.entries(counts).sort((a, b) => b[1] - a[1]);
        return {
            type: 'bar',
            data: {
                labels: entries.map((e) => e[0]),
                datasets: [{ label: 'Places', data: entries.map((e) => e[1]) }],
            },
        };
    `,
});

The plugin runs the body, validates the Chart.js config, records it as category-bar against the source entry, and returns it to the model. The chat UI receives the same config and renders the chart inline.

Cross-kind composition

turf and h3 work on every feature, whichever record it came from, so one call can combine placesByEntry (Points), routesByEntry (LineStrings), incidentsByEntry (Point or LineString), geometriesByEntry (Polygon / MultiPolygon), trafficAreaAnalyticsByEntry (Polygon tiles with metrics) and byodByEntry (mixed GeoJSON).

A few common bridges:

The arguments are GeoJSON Features. Pass the whole feature (placesByEntry[id].features[i], routesByEntry[id].features[0], geometriesByEntry[key][i], …), not the bare geometry.coordinates. A few helpers accept coordinates directly, but most expect Features.

Related