@thatopen/services 0.12.0 → 0.14.0

package/dist/built-in/index.d.ts

@@ -1585,19 +1585,21 @@ export interface OriginData {
     height: number;
     rotation: number;
 }
-export interface BimSite {
-    label: string;
-    description?: string;
-    lat: number;
-    lon: number;
-    height: number;
-    rotation: number;
-    /** Column-major 4x4 matrix (16 values) mapping BIM local space to the site's georeferenced frame. */
-    baseMatrix: number[];
-}
-export interface BimCoordinatesData {
-    defaultSiteId?: string;
-    sites: Record<string, BimSite>;
+/** Project-wide coordinate reference system + vertical datum config, shared by
+ *  every asset type that needs to decode raw projected coordinates (point
+ *  clouds, BIM) — see automatic-file-derived-georeferencing.md
+ *  (VisorUnificadoAqualia/docs/adrs). One value per project, not per asset:
+ *  every file at the same real-world site shares the same CRS/geoid. */
+export interface CrsData {
+    /** EPSG code of the project's projected CRS (e.g. 25830 for ETRS89/UTM 30N).
+     *  EPSG is a global registry, not region-specific — every project has an
+     *  applicable code, most commonly a standard UTM zone. */
+    epsgCode: number;
+    /** Geoid undulation in meters at the project's origin (orthometric ->
+     *  ellipsoidal height correction). Sampled once from a geoid model
+     *  (client-supplied, or a global EGM2008 fallback) — varies negligibly
+     *  across a single project's extent, so one scalar per project suffices. */
+    geoidUndulation: number;
 }
 export type AssetCoordinateType = "splat" | "ifc" | "point-cloud" | (string & {});
 export interface AssetCoordinate {
@@ -1653,7 +1655,7 @@ export interface ProjectManagerData {
     namespaces: Record<ProjectNamespaceKey, ProjectNamespace>;
     entities: {
         origin: ProjectEntity<OriginData>;
-        bimCoordinates: ProjectEntity<BimCoordinatesData>;
+        crs: ProjectEntity<CrsData>;
         assetCoordinates: ProjectEntity<AssetCoordinate[]>;
         graphicsSettings: ProjectEntity<GraphicsSettingsData>;
     };
@@ -1663,19 +1665,15 @@ export interface SingletonEntity<T> {
     set(data: T): Promise<void>;
     update(partial: Partial<T>): Promise<void>;
 }
-export interface BimCoordinatesEntity {
-    get(): BimCoordinatesData;
-    getSites(): Record<string, BimSite>;
-    getSite(siteId: string): BimSite | undefined;
-    getDefaultSite(): BimSite | undefined;
-    /** Creates a new site. `ProjectManager` generates the opaque `siteId` — callers
-     *  never invent their own (see the class-level JSDoc on `ProjectManager` for why). */
-    createSite(site: BimSite): Promise<string>;
-    /** Updates a site that already exists (from `createSite`). Throws if `siteId`
-     *  isn't in `sites` — this is not an upsert; use `createSite` to add one. */
-    setSite(siteId: string, site: BimSite): Promise<void>;
-    setDefaultSite(siteId: string): Promise<void>;
-    removeSite(siteId: string): Promise<void>;
+/**
+ * A singleton entity that also announces its own changes — for values other
+ * code needs to react to live (recompute/reposition something) rather than
+ * just read on demand. `onChange` fires with the new value on every
+ * `set`/`update`, regardless of whether that change has been persisted yet
+ * (see `ProjectManager.dirty`/`onDirtyChange`).
+ */
+export interface ReactiveSingletonEntity<T> extends SingletonEntity<T> {
+    onChange: import('@thatopen/components').Event<T>;
 }
 export interface AssetCoordinatesEntity {
     getAll(): AssetCoordinate[];
@@ -1698,18 +1696,10 @@ export interface AssetCoordinatesEntity {
  * Schema shape (see `src/types.ts` for the full rationale):
  * - `namespaces`/`entities` are maps keyed by a fixed, readable slug — a
  *   closed set this code defines, never created at runtime.
- * - `bimCoordinates.data.sites` is the one open, runtime-created collection
- *   today, so its keys are opaque generated ids instead of slugs.
- * - `origin`/`graphicsSettings` are singletons; `sites`/`assetCoordinates`
- *   are collections.
+ * - `origin`/`crs`/`graphicsSettings` are singletons; `assetCoordinates` is
+ *   a collection.
  * - `entities[id]` is a uniform envelope: `namespaceId`, mandatory `label`,
  *   optional `description` (omitted, not stored empty), free-form `data`.
- *
- * Id generation rule: whenever a collection needs an opaque id (today just
- * `sites`, potentially more collections later), `ProjectManager` generates it
- * internally (`crypto.randomUUID()`, no prefix) — callers never invent their
- * own. `createSite` is the current example; follow the same pattern for any
- * future `create*` method.
  */
 declare class _ProjectManager extends OBC.Component {
     static readonly uuid: "6f3a9c2e-8b1d-4e6a-9c3f-1d7b5a8e2c4f";
@@ -1720,6 +1710,31 @@ declare class _ProjectManager extends OBC.Component {
     private _loadingData;
     readonly onSaveStart: OBC.Event<void>;
     readonly onSaveComplete: OBC.Event<boolean>;
+    /**
+     * Entity ids (e.g. `"origin"`) with changes not yet persisted. Most entities
+     * auto-save (see `_scheduleSave`) so they're only ever dirty for the instant
+     * before their debounce fires — `origin` is the exception: its `set`/`update`
+     * mark it dirty WITHOUT scheduling a save (see `origin` below), so a caller
+     * driving it continuously (e.g. a drag gizmo) can update it every frame
+     * without spamming the network, and a UI can surface "unsaved changes" +
+     * call `flush()` once the user explicitly confirms.
+     *
+     * KNOWN GAP: `_doSave()` persists the whole `_data` blob (one JSON file for
+     * every entity), so an auto-saving entity's save will also flush out
+     * whatever `origin` currently holds in memory, even if the user hasn't
+     * confirmed it yet — there's no separate "committed vs. draft" copy of
+     * `origin`'s data. Accepted for now as a v1 gap (same spirit as this
+     * package's other documented v1 gaps, see the ProjectManager ADR); revisit
+     * if that coincidence turns out to matter in practice.
+     */
+    private _dirtyEntities;
+    /** True while any entity has unsaved changes. */
+    get dirty(): boolean;
+    /** Ids of entities with unsaved changes right now. */
+    get dirtyEntities(): string[];
+    /** Fires with the current `dirtyEntities` list every time it changes. */
+    readonly onDirtyChange: OBC.Event<string[]>;
+    private _markDirty;
     private _client?;
     private _fileId?;
     private _data;
@@ -1728,15 +1743,26 @@ declare class _ProjectManager extends OBC.Component {
     private _scheduleSave;
     private _queueSave;
     private _doSave;
-    /** Cancels the pending debounce and runs the save immediately. Awaits completion. */
+    /**
+     * Cancels the pending debounce (if any) and runs the save immediately.
+     * Also the only way to persist an entity that marks itself dirty WITHOUT
+     * auto-scheduling (currently just `origin`) — call this once the user
+     * explicitly confirms. Awaits completion.
+     */
     flush(): Promise<void>;
     init(client: PlatformClient): Promise<void>;
-    /** Opaque id generator for any collection needing one (currently just
-     *  `bimCoordinates.sites`) — see the class-level JSDoc's id-generation rule. */
-    private _generateId;
-    origin: SingletonEntity<OriginData>;
+    /**
+     * NOT auto-saving, unlike every other entity below — `set`/`update` mark it
+     * dirty and fire `onChange` immediately, but leave persisting up to an
+     * explicit `flush()` call. This is what lets a continuous interaction (e.g.
+     * a drag gizmo) update `origin` every frame — live for anyone listening to
+     * `onChange` — without writing to the network on every tick, while still
+     * surfacing "there's an unconfirmed change" via `dirty`/`onDirtyChange` for
+     * a UI to gate behind an explicit save action.
+     */
+    origin: ReactiveSingletonEntity<OriginData>;
+    crs: ReactiveSingletonEntity<CrsData>;
     graphicsSettings: SingletonEntity<GraphicsSettingsData>;
-    bimCoordinates: BimCoordinatesEntity;
     assetCoordinates: AssetCoordinatesEntity;
     getNamespaces(): Record<ProjectNamespaceKey, ProjectNamespace>;
     getNamespace(key: ProjectNamespaceKey): Record<string, unknown>;
@@ -1755,18 +1781,10 @@ declare class _ProjectManager extends OBC.Component {
  * Schema shape (see `src/types.ts` for the full rationale):
  * - `namespaces`/`entities` are maps keyed by a fixed, readable slug — a
  *   closed set this code defines, never created at runtime.
- * - `bimCoordinates.data.sites` is the one open, runtime-created collection
- *   today, so its keys are opaque generated ids instead of slugs.
- * - `origin`/`graphicsSettings` are singletons; `sites`/`assetCoordinates`
- *   are collections.
+ * - `origin`/`crs`/`graphicsSettings` are singletons; `assetCoordinates` is
+ *   a collection.
  * - `entities[id]` is a uniform envelope: `namespaceId`, mandatory `label`,
  *   optional `description` (omitted, not stored empty), free-form `data`.
- *
- * Id generation rule: whenever a collection needs an opaque id (today just
- * `sites`, potentially more collections later), `ProjectManager` generates it
- * internally (`crypto.randomUUID()`, no prefix) — callers never invent their
- * own. `createSite` is the current example; follow the same pattern for any
- * future `create*` method.
  */
 export type ProjectManager = InstanceType<typeof _ProjectManager>;
 /**
@@ -1783,18 +1801,10 @@ export type ProjectManager = InstanceType<typeof _ProjectManager>;
  * Schema shape (see `src/types.ts` for the full rationale):
  * - `namespaces`/`entities` are maps keyed by a fixed, readable slug — a
  *   closed set this code defines, never created at runtime.
- * - `bimCoordinates.data.sites` is the one open, runtime-created collection
- *   today, so its keys are opaque generated ids instead of slugs.
- * - `origin`/`graphicsSettings` are singletons; `sites`/`assetCoordinates`
- *   are collections.
+ * - `origin`/`crs`/`graphicsSettings` are singletons; `assetCoordinates` is
+ *   a collection.
  * - `entities[id]` is a uniform envelope: `namespaceId`, mandatory `label`,
  *   optional `description` (omitted, not stored empty), free-form `data`.
- *
- * Id generation rule: whenever a collection needs an opaque id (today just
- * `sites`, potentially more collections later), `ProjectManager` generates it
- * internally (`crypto.randomUUID()`, no prefix) — callers never invent their
- * own. `createSite` is the current example; follow the same pattern for any
- * future `create*` method.
  */
 export declare const ProjectManager: typeof _ProjectManager & {
     uuid: "6f3a9c2e-8b1d-4e6a-9c3f-1d7b5a8e2c4f";

package/dist/cli/lib/engine-script.d.ts

@@ -1,10 +1,17 @@
+/** Mirrors the platform-supplied `executionContext` global (see cloud-component template). */
+export interface EngineExecutionContext {
+    projectId?: string;
+    executionId: string;
+    toolId: string;
+    toolVersion: string;
+}
 /**
  * Generates the local execution engine script.
  *
  * Mirrors the server-side `v1/thatOpenEngine.js` template:
  * - Provides the same globals (OBC, THREE, WEBIFC, fs, executionReporter,
- *   thatOpenServices, executionParams).
+ *   thatOpenServices, executionParams, executionContext).
  * - Inlines the IIFE bundle code (which ends with `var main = ...`).
  * - Calls `main()` and sends the result back via IPC.
  */
-export declare function buildEngineScript(bundleCode: string, accessToken: string, apiUrl: string, executionParams: object): string;
+export declare function buildEngineScript(bundleCode: string, accessToken: string, apiUrl: string, executionParams: object, executionContext: EngineExecutionContext): string;

package/dist/cli.js

@@ -11246,7 +11246,7 @@ function detectGlobalName(cwd) {
   }
   return "ThatOpenApp";
 }
-function buildEngineScript(bundleCode, accessToken, apiUrl, executionParams) {
+function buildEngineScript(bundleCode, accessToken, apiUrl, executionParams, executionContext) {
   return `/* eslint-disable */
 const { EngineServicesClient } = require('@thatopen/services');
 
@@ -11271,6 +11271,7 @@ const executionReporter = {
 };
 
 let thatOpenServices, executionParams;
+const executionContext = ${JSON.stringify(executionContext)};
 
 // --- User bundle code (IIFE) ---
 ${bundleCode}
@@ -11356,13 +11357,20 @@ const runCommand = new Command2("run").description("Build and run a cloud compon
       process.exit(1);
     }
     const bundleCode = require$$3.readFileSync(bundlePath, "utf-8");
+    const executionId = node_crypto.randomUUID();
+    const localConfig = readLocalConfig(cwd);
     const engineScript = buildEngineScript(
       bundleCode,
       config.accessToken,
       config.apiUrl,
-      executionParams
+      executionParams,
+      {
+        executionId,
+        toolId: localConfig?.componentId ?? "local",
+        toolVersion: "local"
+      }
     );
-    const tmpFile = require$$2.join(node_os.tmpdir(), `thatopen-run-${node_crypto.randomUUID()}.js`);
+    const tmpFile = require$$2.join(node_os.tmpdir(), `thatopen-run-${executionId}.js`);
     require$$3.writeFileSync(tmpFile, engineScript);
     console.log("Running cloud component...\n");
     const startTime = Date.now();
@@ -11478,7 +11486,12 @@ class ExecutionManager {
       bundleCode,
       config.accessToken,
       config.apiUrl,
-      executionParams
+      executionParams,
+      {
+        executionId,
+        toolId: componentId,
+        toolVersion: "local"
+      }
     );
     const tmpFile = require$$2.join(node_os.tmpdir(), `thatopen-local-${executionId}.js`);
     require$$3.writeFileSync(tmpFile, engineScript);

package/docs/builtin/paths.json

@@ -95,6 +95,10 @@
     "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."
   },
+  {
+    "path": "src/built-in/UIManager/src/settings-panel/example.ts",
+    "description": "top-settings-panel — Every viewer app ends up needing the same settings screen: rendering options, clip/measurement styling, a \"which cloud component converts this format\" picker, a keyboard-shortcut reference — plus a search box that filters all of it and a \"restore defaults\" button that resets whatever has persisted state. Building that, and keeping it in sync with the tools it configures, is real work before you've added a single setting of your own."
+  },
   {
     "path": "src/built-in/UIManager/src/topics-panel/example.ts",
     "description": "topics-panel — Every coordination workflow needs a place to track issues, clashes, and action items against a 3D model — who's responsible, what still needs review, and where in the model it actually is. Building that from scratch means a BCF-compatible data model, a form, comment threads, viewpoint capture/navigation, document links, and a persistence layer — all before a single issue gets tracked."

package/package.json

@@ -15,7 +15,7 @@
     "access": "public"
   },
   "private": false,
-  "version": "0.12.0",
+  "version": "0.14.0",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/index.d.ts",

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

@@ -14,10 +14,9 @@
   per-builtin data.
 
   This tutorial covers initializing the manager from the platform client; the
-  `origin` and `graphicsSettings` singletons; the `bimCoordinates` sites
-  collection used for BIM georeferencing; the `assetCoordinates` collection
-  used for splats and point clouds; auto-save and its events; and the
-  read-only namespace introspection API.
+  `origin` and `graphicsSettings` singletons; the `assetCoordinates`
+  collection used for splats and point clouds; auto-save and its events; and
+  the read-only namespace introspection API.
 
   ProjectManager has no built-in UI panel — it's a pure data layer. Apps that
   need georeferencing or project-settings UI (like Aqualia's viewer) build it
@@ -76,44 +75,6 @@ await manager.flush();
 
 console.log("origin after update+flush:", manager.origin.get());
 
-/* MD
-  ### 🗺️ bimCoordinates — the sites collection
-  Sites are how a project keeps georeferencing for more than one BIM model,
-  each with its own origin and transform matrix. Because sites are created by
-  users at runtime, their ids are opaque and generated internally —
-  `createSite` mints the id and returns it, while `setSite` only updates a
-  site that already exists (it throws otherwise). This split keeps storage
-  keys decoupled from mutable data like a site's label.
-*/
-
-const siteId = await manager.bimCoordinates.createSite({
-  label: "Site 1",
-  description: "Primary IFC export.",
-  lat: 40.41647848134075,
-  lon: -3.703451491164702,
-  height: 699.970526176243,
-  rotation: 0,
-  baseMatrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, -498477.20216, -719.2375, 4389662.11289, 1],
-});
-
-await manager.bimCoordinates.setDefaultSite(siteId);
-await manager.flush();
-
-console.log("default site:", manager.bimCoordinates.getDefaultSite());
-console.log("all sites:", manager.bimCoordinates.getSites());
-
-/* MD
-  Updating an existing site goes through `setSite`, not `createSite`:
-*/
-
-await manager.bimCoordinates.setSite(siteId, {
-  ...manager.bimCoordinates.getSite(siteId)!,
-  label: "Site 1 (revised)",
-});
-await manager.flush();
-
-console.log("site after update:", manager.bimCoordinates.getSite(siteId));
-
 /* MD
   ### 🖼️ assetCoordinates — the files collection
   `assetCoordinates` georeferences individual files — splats, point clouds —
@@ -159,5 +120,5 @@ console.log("georeferencing namespace:", manager.getNamespace("georeferencing"))
   ### 🤖 What's not covered here
   ProjectManager ships without a UI panel — everything above is the data
   layer only. Building georeferencing or project-settings UI on top of
-  `origin`/`bimCoordinates`/`assetCoordinates` is up to the consuming app.
+  `origin`/`crs`/`assetCoordinates` is up to the consuming app.
 */

package/src/built-in/UIManager/src/settings-panel/example.ts

@@ -0,0 +1,298 @@
+/* MD
+  ## top-settings-panel
+  ---
+  Every viewer app ends up needing the same settings screen: rendering
+  options, clip/measurement styling, a "which cloud component converts this
+  format" picker, a keyboard-shortcut reference — plus a search box that
+  filters all of it and a "restore defaults" button that resets whatever has
+  persisted state. Building that, and keeping it in sync with the tools it
+  configures, is real work before you've added a single setting of your own.
+
+  `top-settings-panel` is a ready-made web component that delivers exactly
+  that. Mounted as-is, it's a complete, self-wiring Settings panel. But like
+  `top-viewer-toolbar` (see that tutorial), it's built out of standalone,
+  individually-importable `<top-*-settings>` elements — so you can drop the
+  panel it builds for you and compose your own layout out of the same
+  pieces, mixed freely with sections of your own.
+
+  This tutorial covers the prerequisites; the default, batteries-included
+  panel; what it manages automatically; building your own section with
+  `bim-panel-section`; and composing a custom layout with `headless`.
+
+  By the end, you'll have a working default panel plus your own custom
+  section, both wired into the same shared search box and reset button as
+  the stock ones.
+*/
+
+import { html, LitElement } from "lit";
+import { customElement, state } from "lit/decorators.js";
+import { consume } from "@lit/context";
+import * as THREE from "three";
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+import * as FRAGS from "@thatopen/fragments";
+import * as BUI from "@thatopen/ui";
+import { PlatformClient, UIManager } from "@thatopen/services";
+// TODO(#34 follow-up): `settingsSearchContext` is not part of the published
+// `@thatopen/services` surface yet — see the TODO in settings-panel/index.ts.
+// Imported by local relative path until the distribute pipeline exports
+// context objects too; same workaround `app/examples/Contexts/example.ts`
+// uses for `componentsContext`/`clientContext`.
+import { settingsSearchContext } from "./src/context";
+import type { App } from "../app/index";
+
+/* MD
+  ### ✅ Prerequisites
+
+  `UIManager` must be in the setup call so `<top-settings-panel>` and every
+  `<top-*-settings>` element are registered. `<top-settings-panel>` must be
+  mounted as a descendant of `<top-app>` — it and its sections consume
+  `componentsContext`/`clientContext`, which `top-app` provides. It does
+  **not** need to be a descendant of `<top-viewer>` specifically — but the
+  sections that talk to the 3D engine (Graphics, Clip styling, Measurement,
+  Commands) render an empty placeholder until a `<top-viewer>` exists
+  somewhere in the same app, since that's what actually builds the tools they
+  configure.
+*/
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: UIManager.uuid },
+)) as { components: OBC.Components };
+
+components.get(UIManager).init();
+
+/* MD
+  ### 🖥️ Default panel (batteries included)
+
+  Add it as a plain element anywhere under `top-app` — a side-by-side layout
+  with the 3D viewer is the most natural arrangement, since most of its
+  sections act on what's in the scene:
+
+  ```html
+  <top-viewer>...</top-viewer>
+  <top-settings-panel></top-settings-panel>
+  ```
+
+  ### 🤖 What the default panel manages automatically
+
+  **Graphics** — point/line/edge styling, background, shadows, ambient
+  occlusion — whatever `top-viewer` supports, persisted across reloads.
+
+  **Clip styling** — fill/edge color, opacity, width for the clip tool,
+  shared live with `top-viewer-toolbar`'s clip button.
+
+  **Measurement** — units (length/area/angle), color, decimals, per-snap-kind
+  toggles, shared live with the toolbar's measurement buttons.
+
+  **File conversion** — which provisioned cloud component converts each
+  format when a file is opened, per project.
+
+  **Commands** — a click-to-run shortcut reference (focus, hide, isolate,
+  ghost, show all, clear selection) that also registers the actual keyboard
+  shortcuts while mounted.
+
+  **Search box** — filters every section's own rows by label, stock or
+  custom, as long as a section opts in (see below).
+
+  **Restore defaults** — a two-click-confirm button that resets every
+  section with persisted state (currently: Graphics) back to its defaults.
+
+  ### 🧩 Building your own section
+
+  A custom section is a `LitElement` that renders its own `<bim-panel-section>`
+  — nothing about it is specific to `top-settings-panel` beyond that. Consume
+  `settingsSearchContext` if you want the shared search box to filter your
+  rows too; skip it and your section simply never filters.
+*/
+
+@customElement("my-lidar-settings")
+class MyLidarSettings extends LitElement {
+  @consume({ context: settingsSearchContext, subscribe: true })
+  searchQuery = "";
+
+  @state() private _pointBudget = 2_000_000;
+  @state() private _showIntensity = false;
+
+  render() {
+    const rows = [
+      {
+        label: "Point budget",
+        control: html`<bim-number-input
+          label="Point budget"
+          slider
+          value=${this._pointBudget}
+          min="100000"
+          max="10000000"
+          step="100000"
+          @change=${(e: Event) => {
+            this._pointBudget = Number((e.target as HTMLInputElement).value);
+          }}
+        ></bim-number-input>`,
+      },
+      {
+        label: "Show intensity",
+        control: html`<bim-checkbox
+          label="Show intensity"
+          toggle
+          ?checked=${this._showIntensity}
+          @change=${(e: Event) => {
+            this._showIntensity = (e.target as HTMLInputElement).checked;
+          }}
+        ></bim-checkbox>`,
+      },
+    ];
+
+    const q = this.searchQuery.trim().toLowerCase();
+    const visible = q
+      ? rows.filter((r) => r.label.toLowerCase().includes(q))
+      : rows;
+
+    return html`<bim-panel-section label="LIDAR" icon="mdi:radar">
+      ${visible.length
+        ? visible.map((r) => r.control)
+        : html`<bim-label style="opacity: 0.6; font-size: 0.78rem;"
+            >No settings match "${this.searchQuery}".</bim-label
+          >`}
+    </bim-panel-section>`;
+  }
+}
+
+/* MD
+  ### 🧱 Composing a custom layout with `headless`
+
+  Set the `headless` attribute to skip the panel's own 5 stock sections —
+  everything else (the search box, the reset button, both contexts) keeps
+  running. Slot whatever `top-*-settings` elements and/or your own sections
+  as light-DOM children, in whatever order you want; that's exactly what
+  renders.
+
+  The most common case: keep every stock section and just add your own —
+  this is the live demo below.
+
+  ```html
+  <top-settings-panel headless>
+    <top-graphic-settings></top-graphic-settings>
+    <top-clipstyling-settings></top-clipstyling-settings>
+    <top-measurement-settings></top-measurement-settings>
+    <top-fileconversion-settings></top-fileconversion-settings>
+    <top-commands-settings></top-commands-settings>
+    <my-lidar-settings></my-lidar-settings>
+  </top-settings-panel>
+  ```
+*/
+
+const app = document.createElement("top-app") as unknown as App;
+
+app.setup = (waitUntil) => {
+  waitUntil(
+    (async () => {
+      const fragments = components.get(OBC.FragmentsManager);
+      const workerUrl = await FRAGS.FragmentsModels.getWorker();
+      fragments.init(await FRAGS.toClassicWorker(workerUrl), { classicWorker: true });
+    })(),
+    "Fragments Core",
+  );
+  return { components, client };
+};
+
+app.elements = {
+  viewer: () =>
+    html`<top-viewer><top-viewer-toolbar></top-viewer-toolbar></top-viewer>`,
+  settings: () => html`
+    <top-settings-panel headless>
+      <top-graphic-settings></top-graphic-settings>
+      <top-clipstyling-settings></top-clipstyling-settings>
+      <top-measurement-settings></top-measurement-settings>
+      <top-fileconversion-settings></top-fileconversion-settings>
+      <top-commands-settings></top-commands-settings>
+      <my-lidar-settings></my-lidar-settings>
+    </top-settings-panel>
+  `,
+};
+
+app.layouts = {
+  main: {
+    label: "Main",
+    icon: "solar:3d-square-bold",
+    template: `"viewer settings" 1fr / 1fr 22rem`,
+  },
+};
+
+app.layout = "main";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";
+
+/* MD
+  ### 🔀 A few other ways to compose it
+
+  A lighter viewer that only needs Graphics plus its own section — drop
+  everything else:
+
+  ```html
+  <top-settings-panel headless>
+    <top-graphic-settings></top-graphic-settings>
+    <my-lidar-settings></my-lidar-settings>
+  </top-settings-panel>
+  ```
+
+  Reordering — `headless` respects DOM order, so Commands first is just:
+
+  ```html
+  <top-settings-panel headless>
+    <top-commands-settings></top-commands-settings>
+    <top-graphic-settings></top-graphic-settings>
+    <top-clipstyling-settings></top-clipstyling-settings>
+    <top-measurement-settings></top-measurement-settings>
+    <top-fileconversion-settings></top-fileconversion-settings>
+  </top-settings-panel>
+  ```
+
+  Swapping a single stock section for your own (e.g. Measurement with
+  different units) — the same `headless` list, just with that one tag
+  replaced:
+
+  ```html
+  <top-settings-panel headless>
+    <top-graphic-settings></top-graphic-settings>
+    <top-clipstyling-settings></top-clipstyling-settings>
+    <my-measurement-settings></my-measurement-settings>
+    <top-fileconversion-settings></top-fileconversion-settings>
+    <top-commands-settings></top-commands-settings>
+  </top-settings-panel>
+  ```
+
+  Keeping the full stock default and only ADDING a section, without going
+  `headless` at all — the non-headless layout also projects a trailing
+  `<slot>`, so any light-DOM children you give it render after the 5 stock
+  sections:
+
+  ```html
+  <top-settings-panel>
+    <my-lidar-settings></my-lidar-settings>
+  </top-settings-panel>
+  ```
+
+  ### ⚠️ Gotchas
+
+  - **Never `document.createElement` a `bim-*` element** — same rule as
+    `top-viewer-toolbar`. Render them with lit's `html`/`render` (or, as
+    here, from inside your own `LitElement`'s `render()`); never build them
+    imperatively.
+  - **A custom section renders its OWN `<bim-panel-section>`**, in its own
+    shadow root — there's no API to inject rows into a stock section, only
+    to sit alongside it.
+  - **`fixed` layout quirk**: `<bim-panel-section>`'s default logic checks
+    `this.closest("bim-panel")`, which can't see past your own section's
+    shadow boundary — so, like the stock sections, a custom one may render
+    with `fixed` behavior until the upstream `@thatopen/ui` fix ships. Not
+    something to work around here; tracked separately.
+  - **Search filtering is opt-in per section** — consuming
+    `settingsSearchContext` is what makes a section respond to the shared
+    search box; forgetting it just means that section never filters, not an
+    error.
+*/

package/src/built-in/index.ts

@@ -1594,19 +1594,21 @@ export interface OriginData {
     height: number;
     rotation: number;
 }
-export interface BimSite {
-    label: string;
-    description?: string;
-    lat: number;
-    lon: number;
-    height: number;
-    rotation: number;
-    /** Column-major 4x4 matrix (16 values) mapping BIM local space to the site's georeferenced frame. */
-    baseMatrix: number[];
-}
-export interface BimCoordinatesData {
-    defaultSiteId?: string;
-    sites: Record<string, BimSite>;
+/** Project-wide coordinate reference system + vertical datum config, shared by
+ *  every asset type that needs to decode raw projected coordinates (point
+ *  clouds, BIM) — see automatic-file-derived-georeferencing.md
+ *  (VisorUnificadoAqualia/docs/adrs). One value per project, not per asset:
+ *  every file at the same real-world site shares the same CRS/geoid. */
+export interface CrsData {
+    /** EPSG code of the project's projected CRS (e.g. 25830 for ETRS89/UTM 30N).
+     *  EPSG is a global registry, not region-specific — every project has an
+     *  applicable code, most commonly a standard UTM zone. */
+    epsgCode: number;
+    /** Geoid undulation in meters at the project's origin (orthometric ->
+     *  ellipsoidal height correction). Sampled once from a geoid model
+     *  (client-supplied, or a global EGM2008 fallback) — varies negligibly
+     *  across a single project's extent, so one scalar per project suffices. */
+    geoidUndulation: number;
 }
 export type AssetCoordinateType = "splat" | "ifc" | "point-cloud" | (string & {});
 export interface AssetCoordinate {
@@ -1662,7 +1664,7 @@ export interface ProjectManagerData {
     namespaces: Record<ProjectNamespaceKey, ProjectNamespace>;
     entities: {
         origin: ProjectEntity<OriginData>;
-        bimCoordinates: ProjectEntity<BimCoordinatesData>;
+        crs: ProjectEntity<CrsData>;
         assetCoordinates: ProjectEntity<AssetCoordinate[]>;
         graphicsSettings: ProjectEntity<GraphicsSettingsData>;
     };
@@ -1672,19 +1674,15 @@ export interface SingletonEntity<T> {
     set(data: T): Promise<void>;
     update(partial: Partial<T>): Promise<void>;
 }
-export interface BimCoordinatesEntity {
-    get(): BimCoordinatesData;
-    getSites(): Record<string, BimSite>;
-    getSite(siteId: string): BimSite | undefined;
-    getDefaultSite(): BimSite | undefined;
-    /** Creates a new site. `ProjectManager` generates the opaque `siteId` — callers
-     *  never invent their own (see the class-level JSDoc on `ProjectManager` for why). */
-    createSite(site: BimSite): Promise<string>;
-    /** Updates a site that already exists (from `createSite`). Throws if `siteId`
-     *  isn't in `sites` — this is not an upsert; use `createSite` to add one. */
-    setSite(siteId: string, site: BimSite): Promise<void>;
-    setDefaultSite(siteId: string): Promise<void>;
-    removeSite(siteId: string): Promise<void>;
+/**
+ * A singleton entity that also announces its own changes — for values other
+ * code needs to react to live (recompute/reposition something) rather than
+ * just read on demand. `onChange` fires with the new value on every
+ * `set`/`update`, regardless of whether that change has been persisted yet
+ * (see `ProjectManager.dirty`/`onDirtyChange`).
+ */
+export interface ReactiveSingletonEntity<T> extends SingletonEntity<T> {
+    onChange: import("@thatopen/components").Event<T>;
 }
 export interface AssetCoordinatesEntity {
     getAll(): AssetCoordinate[];
@@ -1708,18 +1706,10 @@ export interface AssetCoordinatesEntity {
  * Schema shape (see `src/types.ts` for the full rationale):
  * - `namespaces`/`entities` are maps keyed by a fixed, readable slug — a
  *   closed set this code defines, never created at runtime.
- * - `bimCoordinates.data.sites` is the one open, runtime-created collection
- *   today, so its keys are opaque generated ids instead of slugs.
- * - `origin`/`graphicsSettings` are singletons; `sites`/`assetCoordinates`
- *   are collections.
+ * - `origin`/`crs`/`graphicsSettings` are singletons; `assetCoordinates` is
+ *   a collection.
  * - `entities[id]` is a uniform envelope: `namespaceId`, mandatory `label`,
  *   optional `description` (omitted, not stored empty), free-form `data`.
- *
- * Id generation rule: whenever a collection needs an opaque id (today just
- * `sites`, potentially more collections later), `ProjectManager` generates it
- * internally (`crypto.randomUUID()`, no prefix) — callers never invent their
- * own. `createSite` is the current example; follow the same pattern for any
- * future `create*` method.
  */
 declare class _ProjectManager extends OBC.Component {
     static readonly uuid: "6f3a9c2e-8b1d-4e6a-9c3f-1d7b5a8e2c4f";
@@ -1730,6 +1720,31 @@ declare class _ProjectManager extends OBC.Component {
     private _loadingData;
     readonly onSaveStart: OBC.Event<void>;
     readonly onSaveComplete: OBC.Event<boolean>;
+    /**
+     * Entity ids (e.g. `"origin"`) with changes not yet persisted. Most entities
+     * auto-save (see `_scheduleSave`) so they're only ever dirty for the instant
+     * before their debounce fires — `origin` is the exception: its `set`/`update`
+     * mark it dirty WITHOUT scheduling a save (see `origin` below), so a caller
+     * driving it continuously (e.g. a drag gizmo) can update it every frame
+     * without spamming the network, and a UI can surface "unsaved changes" +
+     * call `flush()` once the user explicitly confirms.
+     *
+     * KNOWN GAP: `_doSave()` persists the whole `_data` blob (one JSON file for
+     * every entity), so an auto-saving entity's save will also flush out
+     * whatever `origin` currently holds in memory, even if the user hasn't
+     * confirmed it yet — there's no separate "committed vs. draft" copy of
+     * `origin`'s data. Accepted for now as a v1 gap (same spirit as this
+     * package's other documented v1 gaps, see the ProjectManager ADR); revisit
+     * if that coincidence turns out to matter in practice.
+     */
+    private _dirtyEntities;
+    /** True while any entity has unsaved changes. */
+    get dirty(): boolean;
+    /** Ids of entities with unsaved changes right now. */
+    get dirtyEntities(): string[];
+    /** Fires with the current `dirtyEntities` list every time it changes. */
+    readonly onDirtyChange: OBC.Event<string[]>;
+    private _markDirty;
     private _client?;
     private _fileId?;
     private _data;
@@ -1738,15 +1753,26 @@ declare class _ProjectManager extends OBC.Component {
     private _scheduleSave;
     private _queueSave;
     private _doSave;
-    /** Cancels the pending debounce and runs the save immediately. Awaits completion. */
+    /**
+     * Cancels the pending debounce (if any) and runs the save immediately.
+     * Also the only way to persist an entity that marks itself dirty WITHOUT
+     * auto-scheduling (currently just `origin`) — call this once the user
+     * explicitly confirms. Awaits completion.
+     */
     flush(): Promise<void>;
     init(client: PlatformClient): Promise<void>;
-    /** Opaque id generator for any collection needing one (currently just
-     *  `bimCoordinates.sites`) — see the class-level JSDoc's id-generation rule. */
-    private _generateId;
-    origin: SingletonEntity<OriginData>;
+    /**
+     * NOT auto-saving, unlike every other entity below — `set`/`update` mark it
+     * dirty and fire `onChange` immediately, but leave persisting up to an
+     * explicit `flush()` call. This is what lets a continuous interaction (e.g.
+     * a drag gizmo) update `origin` every frame — live for anyone listening to
+     * `onChange` — without writing to the network on every tick, while still
+     * surfacing "there's an unconfirmed change" via `dirty`/`onDirtyChange` for
+     * a UI to gate behind an explicit save action.
+     */
+    origin: ReactiveSingletonEntity<OriginData>;
+    crs: ReactiveSingletonEntity<CrsData>;
     graphicsSettings: SingletonEntity<GraphicsSettingsData>;
-    bimCoordinates: BimCoordinatesEntity;
     assetCoordinates: AssetCoordinatesEntity;
     getNamespaces(): Record<ProjectNamespaceKey, ProjectNamespace>;
     getNamespace(key: ProjectNamespaceKey): Record<string, unknown>;
@@ -1766,18 +1792,10 @@ declare class _ProjectManager extends OBC.Component {
  * Schema shape (see `src/types.ts` for the full rationale):
  * - `namespaces`/`entities` are maps keyed by a fixed, readable slug — a
  *   closed set this code defines, never created at runtime.
- * - `bimCoordinates.data.sites` is the one open, runtime-created collection
- *   today, so its keys are opaque generated ids instead of slugs.
- * - `origin`/`graphicsSettings` are singletons; `sites`/`assetCoordinates`
- *   are collections.
+ * - `origin`/`crs`/`graphicsSettings` are singletons; `assetCoordinates` is
+ *   a collection.
  * - `entities[id]` is a uniform envelope: `namespaceId`, mandatory `label`,
  *   optional `description` (omitted, not stored empty), free-form `data`.
- *
- * Id generation rule: whenever a collection needs an opaque id (today just
- * `sites`, potentially more collections later), `ProjectManager` generates it
- * internally (`crypto.randomUUID()`, no prefix) — callers never invent their
- * own. `createSite` is the current example; follow the same pattern for any
- * future `create*` method.
  */
 export type ProjectManager = InstanceType<typeof _ProjectManager>;
 /**
@@ -1794,18 +1812,10 @@ export type ProjectManager = InstanceType<typeof _ProjectManager>;
  * Schema shape (see `src/types.ts` for the full rationale):
  * - `namespaces`/`entities` are maps keyed by a fixed, readable slug — a
  *   closed set this code defines, never created at runtime.
- * - `bimCoordinates.data.sites` is the one open, runtime-created collection
- *   today, so its keys are opaque generated ids instead of slugs.
- * - `origin`/`graphicsSettings` are singletons; `sites`/`assetCoordinates`
- *   are collections.
+ * - `origin`/`crs`/`graphicsSettings` are singletons; `assetCoordinates` is
+ *   a collection.
  * - `entities[id]` is a uniform envelope: `namespaceId`, mandatory `label`,
  *   optional `description` (omitted, not stored empty), free-form `data`.
- *
- * Id generation rule: whenever a collection needs an opaque id (today just
- * `sites`, potentially more collections later), `ProjectManager` generates it
- * internally (`crypto.randomUUID()`, no prefix) — callers never invent their
- * own. `createSite` is the current example; follow the same pattern for any
- * future `create*` method.
  */
 export const ProjectManager = { uuid: '6f3a9c2e-8b1d-4e6a-9c3f-1d7b5a8e2c4f' } as typeof _ProjectManager & { uuid: '6f3a9c2e-8b1d-4e6a-9c3f-1d7b5a8e2c4f' };