@thatopen/services 0.17.0 → 0.19.0

package/dist/types/base.d.ts

@@ -2,7 +2,15 @@ export interface Base {
     _id: ObjectId;
     createdAt: Date;
     updatedAt?: Date;
-    creatingUser: ObjectId;
+    /**
+     * The human user who performed the action (audit trail). This used to be
+     * declared as a required `creatingUser`, a field the API has never
+     * returned — the server sends `createdBy`, optionally. Matching the wire
+     * is what a type is for.
+     */
+    createdBy?: ObjectId;
+    /** The human user who last updated the entity (audit trail). */
+    lastUpdatedBy?: ObjectId;
     creatingToken?: ObjectId;
     archived?: boolean;
 }

package/dist/types/notifications.d.ts

@@ -1,5 +1,7 @@
-export type NotificationCategoryDto = 'automation' | 'invitation';
-export type NotificationTypeDto = 'automation.run.started' | 'automation.run.finished' | 'invitation.added' | 'invitation.accepted' | 'project.role_changed';
+export type NotificationCategoryDto = 'automation' | 'invitation' | 'file';
+export type NotificationTypeDto = 'automation.run.started' | 'automation.run.finished' | 'invitation.added' | 'invitation.accepted' | 'project.role_changed' | 'project.transfer.proposed'
+/** A file version landed in a project the recipient belongs to. */
+ | 'file.version_added';
 /**
  * One notification as the API returns it.
  *

package/docs/ai-quickstart.md

@@ -51,8 +51,8 @@ Steps 0–2 are identical for both; they diverge only at `create` (step 3) and h
 
 - **Node.js ≥ 18** and **npm** — verify with `node -v`.
 - A **That Open Platform API token**. The user creates it themselves:
-  → **https://platform.thatopen.com/dashboard → Account → Tokens → create → copy.**
-  (The Data overview shows the same Tokens card; both paths work.)
+  → **https://platform.thatopen.com/dashboard/data → API Tokens → Add → copy.**
+  (Account Settings — avatar menu → Account Settings → API Tokens — shows the same card.)
   Ask the user to paste it. **Never print it back, never write it into a file, never commit it.**
 
 ## 1. Install the CLI
@@ -64,7 +64,7 @@ npm install -g @thatopen/services@latest
 ## 2. Log in (do this BEFORE creating the project)
 
 Get the token from the platform dashboard — **https://platform.thatopen.com/dashboard**
-→ **Account → Tokens** → create → copy (the Data overview shows the same card). Ask the
+→ **Data → API Tokens** → Add → copy (Account Settings shows the same card). Ask the
 user to paste it, then run:
 
 ```bash
@@ -81,6 +81,22 @@ first: the next step's install pulls the private `@thatopen-platform/*-beta` pac
 `create` uses your logged-in token to write an authenticated `.npmrc` so that install can
 resolve them. No npm account or manual npm token is involved.
 
+### The two credentials, side by side (misusing them is the classic first failure)
+
+| | **Platform API token** | **User session JWT** |
+|---|---|---|
+| Where it comes from | Dashboard → Data → API Tokens | The platform session (Auth0); inside an app, `PlatformClient.fromPlatformContext()` |
+| Lifetime | Long-lived until revoked | Hours |
+| Client | `EngineServicesClient` | `PlatformClient` (extends the other, so it can do both) |
+| Can | Files, folders, versions, components, executions — anything with an explicit `projectId` | All of that **plus** the JWT-only routes: `listProjects`, `getProject`, `getProjectData`, `checkPermission`, notifications |
+| Cannot | The JWT-only routes above — they identify a *person*, a token identifies a *token* | Run unattended: it expires with the session |
+| How it travels | `Authorization: Bearer` (the CLI does this for you); the `?accessToken=` query form is legacy | `Authorization: Bearer` |
+
+The failure mode this table prevents: building a service on an API token and discovering
+that `checkPermission` or `listProjects` answers 401 — not because of a bug, but because
+those questions are only answerable about a person. If a feature needs them unattended,
+that is a platform gap to report, not a header to keep fiddling with.
+
 ## 3. Scaffold a beta project
 
 **[app]**
@@ -190,7 +206,11 @@ Copy this skeleton. It is the boot of an app that works.
 async function main() {
   const client = PlatformClient.fromPlatformContext();
 
-  // 1 ── built-ins registered, UI shell up
+  // 1 ── built-ins registered, UI shell up. This is the FULL globals set a
+  //      built-in may ask for: OBC, OBF, BUI, THREE, FRAGS, MARKERJS (plus
+  //      CUI only if your app still uses the deprecated @thatopen/ui-obc).
+  //      Only OBC and BUI are strictly required, but a built-in that needs
+  //      a missing one fails at init, so pass everything you import.
   const { components } = await client.setup<OBC.Components>(
     { OBC, OBF, BUI, THREE, FRAGS, MARKERJS },
     { uuid: UIManager.uuid },
@@ -278,7 +298,7 @@ system: the platform relays messages between app tabs and external tools.
 To command the app from outside (a script, an MCP server, your own tool):
 
 1. The user creates a **platform token** with the **API** permission
-   (dashboard → Account → Tokens). Same secrecy rules as always.
+   (dashboard → Data → API Tokens). Same secrecy rules as always.
 2. Connect with `socket.io-client` and subscribe, then publish:
 
 ```bash
@@ -288,7 +308,13 @@ npm i socket.io-client   # in the external tool's own project, not the app
 ```js
 import { io } from "socket.io-client";
 
-const socket = io(`https://platform.thatopen.com?accessToken=${process.env.THATOPEN_TOKEN}`);
+// WebSocket-only matters: the default long-polling handshake spreads several
+// HTTP requests across the platform's load-balanced instances and can die
+// before it upgrades. The token rides the auth payload, not the URL.
+const socket = io("https://platform.thatopen.com", {
+  transports: ["websocket"],
+  auth: { accessToken: process.env.THATOPEN_TOKEN },
+});
 // While iterating with `thatopen serve`, OMIT appId (the dev channel is keyed
 // to the account); pass the appId once the app is published.
 socket.emit("channelSubscribe", { projectId, appId, kind: "cli" });
@@ -323,6 +349,32 @@ is the reply. The full walkthrough (typed contracts, collaboration events,
 presence) is `node_modules/@thatopen/services/src/core/examples/channel.ts`,
 indexed in the client API index you already loaded.
 
+## 5c. The desktop MCP server: `thatopen mcp`
+
+The raw socket above is for tools you write. For an LLM on the desktop (Claude
+Desktop, Claude Code, anything that speaks MCP), the CLI ships the same bridge
+as a ready-made MCP server over stdio:
+
+```json
+{
+  "mcpServers": {
+    "thatopen-platform": {
+      "command": "npx",
+      "args": ["-y", "@thatopen/services", "mcp"]
+    }
+  }
+}
+```
+
+Credentials come from `thatopen login` (`~/.thatopen/config.json`); to inject
+them instead, set `THATOPEN_TOKEN` and `THATOPEN_API_URL` in the server's
+`env`. Two tools: `platform-status` (can the platform be reached, is the
+subscription alive) and `send-app-command` (publish a command to a running
+app — `ping`, `get-loaded-models`, or whatever the app declares — and return
+its reply). The project is named per call, by id or dashboard URL, so one MCP
+session can drive whichever project the user has open; while iterating with
+`thatopen serve`, `app_id` is omitted, same rule as the raw socket.
+
 ## 6. Publish (when ready)
 
 ```bash

package/docs/builtin/paths.json

@@ -39,6 +39,10 @@
     "path": "src/built-in/ClashesManager/example.ts",
     "description": "ClashesManager — Structural engineers and BIM coordinators routinely detect geometric clashes between disciplines — structural steel penetrating ductwork, pipes clashing with slabs — and need to track the status of each issue through resolution without leaving their BIM environment."
   },
+  {
+    "path": "src/built-in/GISManager/example.ts",
+    "description": "GISManager — Georeferenced BIM projects need their surroundings: the real terrain and buildings around the model, and the project's GIS layers (parcels, networks, boundaries) drawn at the right place in the 3D scene and on a 2D map."
+  },
   {
     "path": "src/built-in/ProjectManager/example.ts",
     "description": "ProjectManager — Project-level configuration and data — GIS origin, georeferencing, app settings, and other project-scoped concerns — need a single canonical place to live. Without it, every builtin that needs to persist something at the project level (not per-file, not per-user) ends up inventing its own file, its own save/load pattern, and its own place to put it."
@@ -87,10 +91,22 @@
     "path": "src/built-in/UIManager/src/clashes-panel/example.ts",
     "description": "clashes-panel — BIM coordinators need a dedicated review environment where they can see all detected clashes, filter by status, navigate to each issue in the 3D viewer, and mark items as resolved — without writing any UI code themselves."
   },
+  {
+    "path": "src/built-in/UIManager/src/gis-panel/example.ts",
+    "description": "gis-panel — A georeferenced project is much easier to review with its real surroundings around the model, and with the GIS layers of the site (networks, parcels, boundaries) switched on and off from a list. Streaming the terrain and buildings needs a Cesium Ion token and a way to load and unload them, and fine-tuning their position needs a few controls."
+  },
+  {
+    "path": "src/built-in/UIManager/src/gis-properties-panel/example.ts",
+    "description": "gis-properties-panel — A GIS feature (a pipe, a parcel, a manhole) is useless without its attributes: diameter, material, owner, installation date. Users want to click a feature, in the 3D view or on the map, and read them."
+  },
   {
     "path": "src/built-in/UIManager/src/git-history-panel/example.ts",
     "description": "git-history-panel — `top-git-history` is a GitKraken-style commit timeline for the **revit-flow** feature. It lists the commits pushed by the Revit add-in (newest first) and, when you click a commit, drives the shared 3D viewer to color that commit's changed elements — created green, modified blue, deleted red — on the loaded baseline model."
   },
+  {
+    "path": "src/built-in/UIManager/src/map-panel/example.ts",
+    "description": "map-panel — In a large site, the 3D camera alone is a poor way to get oriented: users want a plan view to see where they are, where the GIS features are, and to jump somewhere else with a click."
+  },
   {
     "path": "src/built-in/UIManager/src/models-list/example.ts",
     "description": "top-models-list — top-models-list is the project's 3D-viewable-files tree: it mirrors the real storage folder structure, converts IFC to fragments, and loads `.frag`/`.potree`/`.splat` models into the 3D scene. Its loaders are PLUGGABLE — the panel owns the UI and the orchestration (progress, refresh, association), but the HOST decides how each extra file format is loaded, so you can teach it new formats without forking the built-in."

package/docs/cli/mcp.md

@@ -0,0 +1,41 @@
+---
+description: "Start an MCP server over stdio that lets an LLM on the desktop (Claude Desktop, Claude Code, any MCP client) drive a running That Open app through the platform channel: send it commands and read the replies."
+---
+
+## thatopen mcp
+
+Runs an MCP (Model Context Protocol) server on stdio. Register it in an MCP
+client's config and the LLM can command a running That Open app through the
+platform channel — the same relay the app's `src/setups/channel.ts` listens
+to, as one external channel of kind `mcp`.
+
+**Usage (in the MCP client's config, not a terminal):**
+
+```json
+{
+  "mcpServers": {
+    "thatopen-platform": {
+      "command": "npx",
+      "args": ["-y", "@thatopen/services", "mcp"]
+    }
+  }
+}
+```
+
+**Credentials:** resolved like every other CLI command — the project's
+`.thatopen`, then `~/.thatopen/config.json` from `thatopen login`. Or inject
+`THATOPEN_TOKEN` and `THATOPEN_API_URL` through the MCP server's `env`.
+
+**Tools exposed:**
+
+- `platform-status` — which API the server points at, whether credentials were
+  found, and whether the channel subscription works. The first call to make
+  when another tool fails.
+- `send-app-command` — publish a command (`ping`, `get-loaded-models`, or
+  whatever the app declares in `AppCommands`) to a running app and return its
+  reply. Takes the project per call (id or dashboard URL); `app_id` is omitted
+  while the app runs under `thatopen serve` and passed once it is published.
+
+**The app must be open.** `delivered: 0` means no tab of that app has the
+channel joined — the LLM is told to ask the user to open or reload the app
+tab, the same rule as the raw socket in the quickstart's section 5b.

package/docs/cli/paths.json

@@ -11,6 +11,10 @@
     "path": "docs/cli/login.md",
     "description": "Authenticate with the ThatOpen platform by validating an access token against the API. Saves credentials globally (~/.thatopen/config.json) by default, or locally to the project's .thatopen file with --local. Local config takes priority over global."
   },
+  {
+    "path": "docs/cli/mcp.md",
+    "description": "Start an MCP server over stdio that lets an LLM on the desktop (Claude Desktop, Claude Code, any MCP client) drive a running That Open app through the platform channel: send it commands and read the replies."
+  },
   {
     "path": "docs/cli/publish.md",
     "description": "Build and upload the project to the platform. Automatically detects app vs cloud component from the local .thatopen config. On first publish, saves the assigned item ID back to .thatopen so subsequent runs update the same item instead of creating a new one."

package/docs/platform-token.md

@@ -8,7 +8,7 @@ here rather than in each of them.
 Say this to the user, and wait:
 
 > "To log in I need a That Open Platform **access token**. You create it yourself:
-> **https://platform.thatopen.com/dashboard → Account → Tokens → create → copy** (the Data overview shows the same card), then paste it
+> **https://platform.thatopen.com/dashboard/data → API Tokens → Add → copy** (Account Settings shows the same card), then paste it
 > here."
 
 **Never print it back, never write it into a file, never commit it.** Not into a script, not into a

package/package.json

@@ -15,7 +15,7 @@
     "access": "public"
   },
   "private": false,
-  "version": "0.17.0",
+  "version": "0.19.0",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/index.d.ts",
@@ -48,6 +48,7 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.27.7",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@thatopen/components": "~3.4.0",
     "@thatopen/components-front": "~3.4.0",
     "@thatopen/fragments": "~3.4.0",
@@ -70,9 +71,11 @@
     "vite": "^5.2.0",
     "vite-plugin-dts": "^3.9.1",
     "vite-plugin-eslint": "^1.8.1",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.4",
+    "zod": "^3.25.76"
   },
   "dependencies": {
+    "@types/geojson": "7946.0.16",
     "dotenv": "^16.4.5",
     "socket.io": "^4.8.0",
     "socket.io-client": "^4.8.0"

package/src/built-in/GISManager/example.ts

@@ -0,0 +1,326 @@
+/* MD
+  ## GISManager
+  ---
+  Georeferenced BIM projects need their surroundings: the real terrain and
+  buildings around the model, and the project's GIS layers (parcels, networks,
+  boundaries) drawn at the right place in the 3D scene and on a 2D map.
+
+  GISManager is the component that owns all of that. It streams Cesium Ion 3D
+  Tiles (Google Photorealistic 3D Tiles by default) around the project origin,
+  loads vector layers (shapefile zip or GeoJSON) declared in the project's
+  layer manifest, and renders a 2D minimap with markers.
+
+  This tutorial covers initializing the manager from the platform client;
+  enabling the 3D tiles; the layer manifest and how heights, styles and
+  coordinate systems are read; selecting and focusing features; and the 2D
+  minimap with its markers. The recommended UI is provided by `top-gis-panel`,
+  `top-map-panel` and `top-gis-properties-panel`.
+
+  GISManager reads the project origin from `ProjectManager`, so initialize
+  `ProjectManager` first.
+
+  ### 🖖 Importing our libraries
+*/
+
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+import * as BUI from "@thatopen/ui";
+import * as THREE from "three";
+import * as FRAGS from "@thatopen/fragments";
+import { PlatformClient, GISManager, ProjectManager } from "@thatopen/services";
+
+
+/* MD
+  ### 🚀 Initializing GISManager
+  Both components are set up through the platform client.
+  `client.setup(...)` resolves the shared `OBC.Components` instance.
+*/
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: ProjectManager.uuid },
+  { uuid: GISManager.uuid },
+)) as { components: OBC.Components };
+
+await components.get(ProjectManager).init(client);
+
+const gis = components.get(GISManager);
+
+/* MD
+  `init(client)` restores the project origin from `ProjectManager` and reads
+  the project's layer manifest (see below). It never throws: with no project or
+  no stored file the manager just keeps its defaults, and an empty layer list.
+*/
+
+await gis.init(client);
+console.log("layers:", gis.vectorLayersConfig);
+
+/* MD
+  ### 🌍 3D tiles
+  Streaming the tiles needs a Cesium Ion token. The component does not persist
+  the token anywhere: your application provides it (from its own settings, or
+  typed by the user in `top-gis-panel`) before enabling the tiles.
+
+  `enableTiles()` resolves once the first tiles are loaded and rejects with a
+  readable message if the token is invalid or has no access to the tileset (the
+  same message is also fired through `onLoadError`).
+*/
+
+gis.onLoadError.add((message) => console.warn("GIS tiles:", message));
+
+gis.apiToken = "<your Cesium Ion token>";
+await gis.enableTiles();
+
+/* MD
+  `onStateChanged` fires whenever the token, origin, tiles visibility, tiles
+  offset or tiles opacity change, with a plain snapshot of all of them.
+  `setTilesOpacity(0.5)` makes the tiles see-through (1 = opaque), which lets
+  you see vector layers that run underground. `disableTiles()` unloads
+  everything.
+
+  On hosts whose engine supports the deferred postproduction pipeline, the
+  tiles and the vector layers are drawn through an occlusion pass, which is what
+  makes the see-through effect possible. On other hosts they are added to the
+  scene directly and stay opaque. You do not need to do anything for this: the
+  component detects it.
+*/
+
+gis.onStateChanged.add((state) => console.log("tiles visible:", state.tilesVisible));
+gis.setTilesOpacity(0.6);
+
+/* MD
+  A small East/North/Up correction (in metres) can be applied to the tiles to
+  compensate for the tileset's own positioning error. Persist it with
+  `saveTilesOffset()`; it is stored in the same file as the layer manifest and
+  restored by `init`.
+*/
+
+gis.onOffsetSaveComplete.add((success) => console.log("offset saved:", success));
+gis.setTilesOffset(0.5, -0.3, 0);
+gis.saveTilesOffset();
+
+/* MD
+  ### 🗂️ The layer manifest
+  The vector layers of a project are declared in one JSON file,
+  `{GISManager.uuid}.json`, stored loose in the project's `__project_data`
+  folder. `init(client)` reads it into `gis.vectorLayersConfig`; it only holds
+  metadata (the geometry stays in the layer's own file, referenced by `fileId`
+  and downloaded when the layer is loaded).
+
+  There is no user interface to register layers yet: the manifest is written by
+  your application (or by hand). The component only reads it, and rewrites it
+  (keeping `layers` as they are) when the tiles offset is saved.
+
+  Each entry of `layers` has:
+
+  - `id` — unique id, used by every API below.
+  - `name` — display name (shown by the panels).
+  - `fileId` — id of the layer's file in the project.
+  - `type` — `"shapefile"` (a zip with the `.shp`, `.dbf`, `.prj`… files) or
+    `"geojson"`. If it is missing or unrecognised the downloaded bytes decide:
+    a zip signature means shapefile, a leading `{` means GeoJSON.
+  - `style` — `stroke` (CSS colour), `stroke-width` (pixels), `fill` (CSS
+    colour, polygons) and `fill-opacity` (0 to 1). All optional.
+  - `height` — optional, how features get their height (next section).
+
+  Here is a complete manifest with a points layer whose vertices carry their
+  own height, and a lines layer whose heights come from its attributes:
+
+  ```json
+  {
+    "layers": [
+      {
+        "id": "manholes",
+        "name": "Manholes",
+        "fileId": "<file id of manholes.zip>",
+        "type": "shapefile",
+        "style": { "stroke": "#ffb300", "stroke-width": 6 },
+        "height": { "source": "geometry" }
+      },
+      {
+        "id": "pipes",
+        "name": "Pipes",
+        "fileId": "<file id of pipes.geojson>",
+        "type": "geojson",
+        "style": { "stroke": "#1e88e5", "stroke-width": 3 },
+        "height": {
+          "source": "attributes",
+          "startProperty": "z_start",
+          "endProperty": "z_end",
+          "startDepthProperty": "depth_start",
+          "endDepthProperty": "depth_end",
+          "nodeLayers": ["manholes"],
+          "nodeSnapDistance": 0.5
+        }
+      }
+    ],
+    "tilesOffset": { "east": 0.5, "north": -0.3, "up": 0 }
+  }
+  ```
+
+  Once `init` has read it, every layer can be loaded and unloaded by id.
+  `loadVectorLayer` downloads and parses the file; it never throws, failures
+  are reported through `onVectorLayerError`.
+*/
+
+gis.onLayersLoaded.add((layers) => console.log("manifest read:", layers.length, "layers"));
+gis.onVectorLayerError.add(({ id, message }) => console.warn(`Layer ${id}:`, message));
+
+await gis.loadVectorLayer("manholes");
+await gis.loadVectorLayer("pipes");
+
+console.log("loaded:", gis.vectorLayers.isLayerLoaded("pipes"));
+
+gis.unloadVectorLayer("manholes");
+
+/* MD
+  ### 📏 Layer heights
+  The `height` option of a layer decides at what height its features are drawn:
+
+  - **No `height`** — the layer is drawn flat, at the origin's height.
+  - **`{ "source": "geometry" }`** — every vertex is placed at its own Z (the
+    third GeoJSON coordinate). If any vertex of the layer has no Z, the whole
+    layer is drawn flat instead (with a console warning).
+  - **`{ "source": "attributes", … }`** — for line features only (other
+    geometry types are drawn flat). A line gets a height at its first vertex
+    and at its last one, and the vertices in between are interpolated along
+    the line. Each end is resolved in this order:
+      1. its own height property (`startProperty` / `endProperty`);
+      2. otherwise the surface height of the nearest node minus its depth
+         property (`startDepthProperty` / `endDepthProperty`). Nodes are the
+         points with a Z found in the layers listed in `nodeLayers`, and
+         "nearest" means within `nodeSnapDistance` metres (0.5 by default) of
+         the line end;
+      3. otherwise the height resolved for the other end (the line is drawn
+         level);
+      4. otherwise the surface height of the nearest node.
+
+    A property counts as missing when it is not a finite number or is exactly
+    `0`. Rules 1 and 2 are tried on both ends before rule 3 is applied, so a
+    copied height never comes from another copy. A line for which no rule can
+    give a height to both ends is not drawn (one console warning per layer
+    summarizes how many).
+
+  All heights are orthometric (the usual survey heights above the geoid). The
+  component adds the project's geoid undulation, taken from the `ProjectManager`
+  CRS, to place them in the scene, and re-places the loaded layers if it changes.
+*/
+
+/* MD
+  ### 🧭 GeoJSON coordinate systems
+  Shapefiles are read with their `.prj`. For GeoJSON layers, the coordinate
+  system comes from the legacy `crs` member of the file:
+
+  - Longitude/latitude (`CRS84`, or `EPSG:4326`) is read as it is.
+  - `EPSG:3857` and the UTM zones (`EPSG:326xx`, `327xx`, `258xx` and `269xx`)
+    are reprojected to longitude/latitude when the layer loads.
+  - Any other declared CRS is rejected, and so are projected coordinates in a
+    file that declares no `crs`.
+
+  A rejected layer is not loaded, and the reason (for example `Unsupported CRS
+  "EPSG:2154"…`) is delivered through `onVectorLayerError`, which is what the
+  GIS panel shows as a toast.
+*/
+
+/* MD
+  ### 🖱️ Selection and focus
+  Clicking a feature in the 3D view selects it. `onFeatureSelected` delivers
+  the selection (`layerId`, `layerName`, `featureIndex`, `geometryType` and the
+  feature's `properties`), or `null` when the selection is cleared. The current
+  selection can also be read at any time from `gis.vectorLayers.selection`.
+
+  Your application can select a feature too, optionally flying the camera to
+  it. `onFocusRequested` fires with the bounding sphere the camera is sent to,
+  which is how the 2D map follows.
+*/
+
+gis.onFeatureSelected.add((selection) => {
+  if (!selection) return console.log("selection cleared");
+  console.log(selection.layerName, selection.geometryType, selection.properties);
+});
+
+gis.onFocusRequested.add(({ layerId, featureIndex, sphere }) => {
+  console.log("focusing", layerId, featureIndex, "radius:", sphere.radius);
+});
+
+gis.selectVectorFeature("pipes", 0, { focus: true });
+gis.vectorLayers.clearSelection();
+
+/* MD
+  ### 🗺️ The 2D minimap
+  `gis.minimap` renders a top-down, north-up image of the 3D tiles that
+  `top-map-panel` draws together with the vector layers, the camera and the
+  markers.
+
+  `captureMap()` takes the picture. The 3D tiles must be loaded (without them
+  the image is empty). The captured area is the bounding box of all the
+  manifest's layers, whether they are displayed or not; with no usable layers it
+  is a square of `2 * halfExtent` metres (250 by default) centred on the origin.
+  The image has a fixed side of `resolution` pixels (2048 by default, limited by
+  the GPU), so the larger the area, the coarser the map.
+*/
+
+gis.minimap.onCaptured.add((capture) => console.log("map captured:", capture.size, "px"));
+
+gis.minimap.halfExtent = 400;
+gis.minimap.resolution = 4096;
+const capture = await gis.minimap.captureMap();
+document.body.appendChild(capture.image);
+
+/* MD
+  `worldToMap` converts a scene position into normalized image coordinates
+  (0 to 1, origin at the top-left), and `mapToWorld` does the opposite for a
+  horizontal plane at a given height. Both return `null` until a map has been
+  captured.
+*/
+
+const point = gis.vectorLayers.geoToWorld(gis.latitude, gis.longitude, gis.height);
+const onMap = gis.minimap.worldToMap(point);
+console.log("origin on the map:", onMap);
+console.log("back to the scene:", onMap && gis.minimap.mapToWorld(onMap.x, onMap.y, point.y));
+
+/* MD
+  ### 📍 Minimap markers
+  Markers are HTML elements drawn over the map by `top-map-panel`. They live in
+  the minimap, not in the panel, so they survive the panel being recreated.
+
+  A marker has an `id`, a scene `position` (read on every redraw, so changing
+  it moves the marker), an optional `label` and an optional `createElement`
+  factory. Without the factory the panel draws a default badge with the label
+  and reports its clicks through `onMarkerClicked`. With it, the marker is your
+  own element and it owns its click behaviour. It is a factory and not an
+  element because each panel needs its own DOM node.
+
+  `geoToWorld(lat, lon, height)` turns a geographic position into a scene
+  position.
+*/
+
+gis.minimap.onMarkersChanged.add(({ kind, id }) => console.log("markers:", kind, id));
+gis.minimap.onMarkerClicked.add((id) => console.log("clicked:", id));
+
+gis.minimap.addMarker({
+  id: "site-office",
+  label: "Site office",
+  position: gis.vectorLayers.geoToWorld(gis.latitude, gis.longitude, gis.height),
+});
+
+gis.minimap.addMarker({
+  id: "crane",
+  position: new THREE.Vector3(-20, 0, 35),
+  createElement: () => {
+    const pin = document.createElement("div");
+    pin.textContent = "🏗️";
+    pin.style.fontSize = "1.4rem";
+    pin.style.cursor = "pointer";
+    pin.onclick = () => console.log("crane clicked");
+    return pin;
+  },
+});
+
+gis.minimap.updateMarker("site-office", { label: "Main office" });
+console.log("markers:", [...gis.minimap.markers.keys()]);
+
+gis.minimap.removeMarker("crane");
+gis.minimap.clearMarkers();

package/src/built-in/UIManager/src/app/examples/Sidebar/example.ts

@@ -73,8 +73,11 @@ app.elements = {
 };
 
 app.layouts = {
-  // Each layout defines its own CSS grid template. Only areas used in a template
-  // are rendered for that layout — unused elements are not created.
+  // Each layout defines its own CSS grid template. The app mounts the UNION
+  // of every layout's areas ONCE and switching layouts toggles which are
+  // visible (the rest stay mounted with display:none), so panel state
+  // survives a switch - element factories run on mount, not per layout.
+  // To react to a switch, listen for the `top:layout-changed` event.
   viewer: {
     label: "Viewer",
     icon: "solar:3d-square-bold",