@thatopen/services 0.3.8 → 0.3.9

package/docs/builtin/paths.json

@@ -1,86 +1,86 @@
-[
-  {
-    "path": "src/built-in/CDEManager/example.ts",
-    "description": "CDEManager — CDEManager is the central state machine for a Common Data Environment. It holds files, folders, metadata schemas, viewer groups, and user permissions, and exposes a typed state machine that all file operations — selecting, editing, uploading, viewing — route through. It has no DOM or Three.js dependencies and can run in Node, a browser, or a server-side worker wherever `@thatopen/components` is available."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/FileEditing/example.ts",
-    "description": "Bulk file editing — stage, preview, revert, and commit — A project manager preparing a deliverable handoff needs to update discipline tags across fifteen IFC files after a scope change, rename each to match the new naming convention, and archive three superseded models — all before anything is sent to the backend. Doing the changes one file at a time risks leaving the file list in a half-updated state if the session is interrupted, and there is no way to review exactly what will change before committing."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/FileMoves/example.ts",
-    "description": "Drag-and-drop file and folder moves — A coordinator restructures the project after a scope change: structural files move from the root into a dedicated discipline folder, a MEP sub-folder needs to be promoted to the top level, and a few documents need to come back to root to appear in the general view. Drag-and-drop is the natural gesture for all of this, but each drag session has intermediate stages — the file is \"in the air\", hovering over a candidate target — and every panel watching the file table should see the right state without coordinating directly with the drag component."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/FileOperations/example.ts",
-    "description": "File operations — inline edit, rename, view, download, archive — BIM coordinators reviewing a model drop repeat the same small actions throughout their session: correcting a discipline tag that changed after a scope revision, renaming a file to match the agreed convention, opening it alongside the structural model to check for clashes, handing it off to a sub-consultant, or removing a superseded version from the live set. If every panel in the platform handles these separately, two panels looking at the same file at the same time can show contradictory states — one says \"uploading\", another still shows the old name."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/FileTransfers/example.ts",
-    "description": "File uploads, versioning, and the download cache — A site coordinator drops a batch of files onto the CDE every Monday after the weekend review: some are entirely new models, some are revised versions of files already in the project, and sometimes the metadata group they upload into should be stamped automatically onto the new files. If the platform makes the coordinator sort this out manually, it slows the handoff and introduces naming errors. And if an upload fails halfway through a batch, the file table should land in a safe state rather than freeze at a loading spinner."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/FolderManagement/example.ts",
-    "description": "Folder management — create, rename, archive, and commit — A project reaches the construction phase and the coordination team needs to restructure the folder hierarchy: add a \"Facades\" discipline folder, rename \"Structural\" to its official abbreviation, and archive two superseded folders that have been merged. Doing these one at a time through separate API calls means the folder tree flickers between invalid states as each change lands — a freshly created folder appears before its sibling is renamed, and the archived folders briefly disappear before the new one is visible."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/MetadataSchema/example.ts",
-    "description": "Metadata schema — define, stage, and publish field definitions — Every project has its own vocabulary for describing files: discipline codes, revision phases, area zones, review statuses. A metadata schema defines which fields exist, what values they accept, and whether they are mandatory. Without a structured schema, each user invents their own labels and the file list becomes impossible to filter or report on consistently."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/MetadataViews/example.ts",
-    "description": "Metadata views — organize fields into named table layouts — A structural engineer and an MEP coordinator look at the same file list but care about completely different metadata. Showing every field to everyone produces a wide table that is hard to navigate. Metadata views let each role define which fields appear in which order — saving the layout so the table opens correctly next time without requiring a manual setup every session."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/ProjectConfig/example.ts",
-    "description": "Project configuration — read, write, and reload persistent data — A CDE application needs to store two kinds of configuration: project-wide settings that all team members share (the metadata schema, custom naming rules) and personal settings that belong to one user (which columns are visible, which metadata views are pinned). Both live inside the project's file storage under a reserved system folder, so they travel with the project and don't rely on a separate configuration service."
-  },
-  {
-    "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/UIManager/src/app/example.ts",
-    "description": "top-app — Front-end developers building BIM web apps need to coordinate several async initialization steps before the UI can be shown — loading the engine, preparing fragment workers, registering loaders — and users need visible feedback on what is happening during that wait, rather than a blank screen."
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/examples/AppState/example.ts",
-    "description": "Shared reactive state with AppState — Developers building interactive BIM panels often need sibling components — a filter selector and a results table, for example — to stay in sync without a shared parent. Lifting state to a common ancestor and threading it down as props works for shallow trees but becomes unwieldy as the component tree grows."
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/examples/Banner/example.ts",
-    "description": "Persistent banners with top:banner — Some application states need a persistent, visible indicator that stays on screen until the state is explicitly cleared — an archived-files mode, a read-only permission warning, a degraded-connectivity notice. A toast auto-dismisses after a few seconds, which is wrong for these cases. A modal blocks interaction entirely, which is too heavy."
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/examples/Contexts/example.ts",
-    "description": "Consuming platform contexts in child components — Developers building custom BIM panels need access to the 3D engine, the platform API, and the current project's metadata — but threading these objects down through props across multiple component layers forces every intermediate element to know about data it doesn't use, making trees brittle and hard to refactor."
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/examples/FileDrop/example.ts",
-    "description": "File drag-and-drop with top:files-dropped — Desktop BIM workflows often rely on dragging files straight from the OS file manager onto the browser window — but wiring a document-level dragenter, dragover, dragleave, and drop handler that correctly tracks nested enter/leave counts, shows a visual overlay, and forwards the files to the right component is tedious boilerplate to repeat for every app."
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/examples/FloatingLayout/example.ts",
-    "description": "Floating layout — Developers building BIM coordination tools often want the 3D model to fill the entire window while control panels float above it — but standard grid layouts give every area equal standing, shrinking the viewer into one cell and leaving visible seams between it and the panels."
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/examples/Modal/example.ts",
-    "description": "Confirmation modals with top:modal — Destructive or irreversible actions — deleting records, overwriting files, leaving unsaved changes — should ask the user to confirm before proceeding. Opening a custom dialog element from a deeply nested component means threading a reference to a controller up through every layer of the tree."
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/examples/Notifications/example.ts",
-    "description": "Toasts and cross-component notifications — Developers building BIM processing UIs need to surface status updates, errors, and async feedback to users from different points in the component tree — but reaching back to the app root to trigger a notification from a deeply nested component requires threading a reference through every layer in between."
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/examples/Sidebar/example.ts",
-    "description": "Sidebar navigation — Product teams building BIM apps often need multiple distinct views — a 3D model viewer, a data browser, a settings screen — but wiring a custom nav bar and managing view transitions from scratch adds complexity before any real feature work begins."
-  },
-  {
-    "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/models-list/example.ts",
-    "description": "top-models-list — top-models-list is the project files panel: it lists the project's files, uploads new ones, converts IFC to fragments, and loads `.frag` 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 file format is loaded, so you can teach it new formats without forking the built-in."
-  }
-]
+[
+  {
+    "path": "src/built-in/CDEManager/example.ts",
+    "description": "CDEManager — CDEManager is the central state machine for a Common Data Environment. It holds files, folders, metadata schemas, viewer groups, and user permissions, and exposes a typed state machine that all file operations — selecting, editing, uploading, viewing — route through. It has no DOM or Three.js dependencies and can run in Node, a browser, or a server-side worker wherever `@thatopen/components` is available."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/FileEditing/example.ts",
+    "description": "Bulk file editing — stage, preview, revert, and commit — A project manager preparing a deliverable handoff needs to update discipline tags across fifteen IFC files after a scope change, rename each to match the new naming convention, and archive three superseded models — all before anything is sent to the backend. Doing the changes one file at a time risks leaving the file list in a half-updated state if the session is interrupted, and there is no way to review exactly what will change before committing."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/FileMoves/example.ts",
+    "description": "Drag-and-drop file and folder moves — A coordinator restructures the project after a scope change: structural files move from the root into a dedicated discipline folder, a MEP sub-folder needs to be promoted to the top level, and a few documents need to come back to root to appear in the general view. Drag-and-drop is the natural gesture for all of this, but each drag session has intermediate stages — the file is \"in the air\", hovering over a candidate target — and every panel watching the file table should see the right state without coordinating directly with the drag component."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/FileOperations/example.ts",
+    "description": "File operations — inline edit, rename, view, download, archive — BIM coordinators reviewing a model drop repeat the same small actions throughout their session: correcting a discipline tag that changed after a scope revision, renaming a file to match the agreed convention, opening it alongside the structural model to check for clashes, handing it off to a sub-consultant, or removing a superseded version from the live set. If every panel in the platform handles these separately, two panels looking at the same file at the same time can show contradictory states — one says \"uploading\", another still shows the old name."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/FileTransfers/example.ts",
+    "description": "File uploads, versioning, and the download cache — A site coordinator drops a batch of files onto the CDE every Monday after the weekend review: some are entirely new models, some are revised versions of files already in the project, and sometimes the metadata group they upload into should be stamped automatically onto the new files. If the platform makes the coordinator sort this out manually, it slows the handoff and introduces naming errors. And if an upload fails halfway through a batch, the file table should land in a safe state rather than freeze at a loading spinner."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/FolderManagement/example.ts",
+    "description": "Folder management — create, rename, archive, and commit — A project reaches the construction phase and the coordination team needs to restructure the folder hierarchy: add a \"Facades\" discipline folder, rename \"Structural\" to its official abbreviation, and archive two superseded folders that have been merged. Doing these one at a time through separate API calls means the folder tree flickers between invalid states as each change lands — a freshly created folder appears before its sibling is renamed, and the archived folders briefly disappear before the new one is visible."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/MetadataSchema/example.ts",
+    "description": "Metadata schema — define, stage, and publish field definitions — Every project has its own vocabulary for describing files: discipline codes, revision phases, area zones, review statuses. A metadata schema defines which fields exist, what values they accept, and whether they are mandatory. Without a structured schema, each user invents their own labels and the file list becomes impossible to filter or report on consistently."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/MetadataViews/example.ts",
+    "description": "Metadata views — organize fields into named table layouts — A structural engineer and an MEP coordinator look at the same file list but care about completely different metadata. Showing every field to everyone produces a wide table that is hard to navigate. Metadata views let each role define which fields appear in which order — saving the layout so the table opens correctly next time without requiring a manual setup every session."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/ProjectConfig/example.ts",
+    "description": "Project configuration — read, write, and reload persistent data — A CDE application needs to store two kinds of configuration: project-wide settings that all team members share (the metadata schema, custom naming rules) and personal settings that belong to one user (which columns are visible, which metadata views are pinned). Both live inside the project's file storage under a reserved system folder, so they travel with the project and don't rely on a separate configuration service."
+  },
+  {
+    "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/UIManager/src/app/example.ts",
+    "description": "top-app — Front-end developers building BIM web apps need to coordinate several async initialization steps before the UI can be shown — loading the engine, preparing fragment workers, registering loaders — and users need visible feedback on what is happening during that wait, rather than a blank screen."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/AppState/example.ts",
+    "description": "Shared reactive state with AppState — Developers building interactive BIM panels often need sibling components — a filter selector and a results table, for example — to stay in sync without a shared parent. Lifting state to a common ancestor and threading it down as props works for shallow trees but becomes unwieldy as the component tree grows."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Banner/example.ts",
+    "description": "Persistent banners with top:banner — Some application states need a persistent, visible indicator that stays on screen until the state is explicitly cleared — an archived-files mode, a read-only permission warning, a degraded-connectivity notice. A toast auto-dismisses after a few seconds, which is wrong for these cases. A modal blocks interaction entirely, which is too heavy."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Contexts/example.ts",
+    "description": "Consuming platform contexts in child components — Developers building custom BIM panels need access to the 3D engine, the platform API, and the current project's metadata — but threading these objects down through props across multiple component layers forces every intermediate element to know about data it doesn't use, making trees brittle and hard to refactor."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/FileDrop/example.ts",
+    "description": "File drag-and-drop with top:files-dropped — Desktop BIM workflows often rely on dragging files straight from the OS file manager onto the browser window — but wiring a document-level dragenter, dragover, dragleave, and drop handler that correctly tracks nested enter/leave counts, shows a visual overlay, and forwards the files to the right component is tedious boilerplate to repeat for every app."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/FloatingLayout/example.ts",
+    "description": "Floating layout — Developers building BIM coordination tools often want the 3D model to fill the entire window while control panels float above it — but standard grid layouts give every area equal standing, shrinking the viewer into one cell and leaving visible seams between it and the panels."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Modal/example.ts",
+    "description": "Confirmation modals with top:modal — Destructive or irreversible actions — deleting records, overwriting files, leaving unsaved changes — should ask the user to confirm before proceeding. Opening a custom dialog element from a deeply nested component means threading a reference to a controller up through every layer of the tree."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Notifications/example.ts",
+    "description": "Toasts and cross-component notifications — Developers building BIM processing UIs need to surface status updates, errors, and async feedback to users from different points in the component tree — but reaching back to the app root to trigger a notification from a deeply nested component requires threading a reference through every layer in between."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Sidebar/example.ts",
+    "description": "Sidebar navigation — Product teams building BIM apps often need multiple distinct views — a 3D model viewer, a data browser, a settings screen — but wiring a custom nav bar and managing view transitions from scratch adds complexity before any real feature work begins."
+  },
+  {
+    "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/models-list/example.ts",
+    "description": "top-models-list — top-models-list is the project files panel: it lists the project's files, uploads new ones, converts IFC to fragments, and loads `.frag` 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 file format is loaded, so you can teach it new formats without forking the built-in."
+  }
+]

package/package.json

@@ -1,95 +1,95 @@
-{
-  "name": "@thatopen/services",
-  "description": "Client library and CLI for building BIM apps and cloud components on the That Open Platform",
-  "author": "That Open Company",
-  "license": "MIT",
-  "homepage": "https://github.com/ThatOpen/engine_services#readme",
-  "bugs": {
-    "url": "https://github.com/ThatOpen/engine_services/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ThatOpen/engine_services.git"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "private": false,
-  "version": "0.3.8",
-  "main": "dist/index.cjs.js",
-  "module": "dist/index.es.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "thatopen": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "src/cli/templates",
-    "src/built-in",
-    "docs",
-    "resources"
-  ],
-  "scripts": {
-    "dev": "vite",
-    "lint": "eslint src/",
-    "build": "eslint src/ && tsc && vite build && vite build --config vite.config.cli.mts && node scripts/generate-cli-docs-paths.mjs && node scripts/generate-client-examples-paths.mjs",
-    "build:lib": "tsc && vite build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "build:cli": "vite build --config vite.config.cli.mts",
-    "preview": "vite preview",
-    "test:ui": "vite --config test/vite.config.mts",
-    "template:app": "cd src/cli/templates/app && npm install && cd ../../../.. && node scripts/generate-template-tsconfig.mjs",
-    "template:app:dev": "cd src/cli/templates/app && npm run dev",
-    "changeset": "changeset",
-    "version": "changeset version",
-    "prepublishOnly": "npm run build"
-  },
-  "devDependencies": {
-    "@changesets/cli": "^2.27.7",
-    "@thatopen/components": "~3.4.0",
-    "@thatopen/components-front": "~3.4.0",
-    "@thatopen/fragments": "~3.4.0",
-    "@thatopen/ui": "~3.4.0",
-    "@thatopen/ui-obc": "~3.4.0",
-    "@types/node": "^20.12.12",
-    "@types/three": "^0.182.0",
-    "commander": "^14.0.3",
-    "esbuild": "^0.27.3",
-    "eslint": "9.x",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-prettier": "^5.1.3",
-    "globals": "^15.3.0",
-    "jszip": "^3.10.1",
-    "prettier": "^3.2.5",
-    "three": ">=0.182.0",
-    "tsx": "^4.16.2",
-    "typescript": "^5.2.2",
-    "typescript-eslint": "^7.10.0",
-    "vite": "^5.2.0",
-    "vite-plugin-dts": "^3.9.1",
-    "vite-plugin-eslint": "^1.8.1",
-    "vitest": "^4.1.4"
-  },
-  "dependencies": {
-    "dotenv": "^16.4.5",
-    "socket.io": "^4.8.0",
-    "socket.io-client": "^4.8.0"
-  },
-  "peerDependencies": {
-    "@thatopen/components": "~3.4.0",
-    "@thatopen/ui": "~3.4.0",
-    "three": ">=0.182.0"
-  },
-  "peerDependenciesMeta": {
-    "@thatopen/components": {
-      "optional": true
-    },
-    "@thatopen/ui": {
-      "optional": true
-    },
-    "three": {
-      "optional": true
-    }
-  }
-}
+{
+  "name": "@thatopen/services",
+  "description": "Client library and CLI for building BIM apps and cloud components on the That Open Platform",
+  "author": "That Open Company",
+  "license": "MIT",
+  "homepage": "https://github.com/ThatOpen/engine_services#readme",
+  "bugs": {
+    "url": "https://github.com/ThatOpen/engine_services/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ThatOpen/engine_services.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "private": false,
+  "version": "0.3.9",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "thatopen": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src/cli/templates",
+    "src/built-in",
+    "docs",
+    "resources"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "lint": "eslint src/",
+    "build": "eslint src/ && tsc && vite build && vite build --config vite.config.cli.mts && node scripts/generate-cli-docs-paths.mjs && node scripts/generate-client-examples-paths.mjs",
+    "build:lib": "tsc && vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build:cli": "vite build --config vite.config.cli.mts",
+    "preview": "vite preview",
+    "test:ui": "vite --config test/vite.config.mts",
+    "template:app": "cd src/cli/templates/app && npm install && cd ../../../.. && node scripts/generate-template-tsconfig.mjs",
+    "template:app:dev": "cd src/cli/templates/app && npm run dev",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.7",
+    "@thatopen/components": "~3.4.0",
+    "@thatopen/components-front": "~3.4.0",
+    "@thatopen/fragments": "~3.4.0",
+    "@thatopen/ui": "~3.4.0",
+    "@thatopen/ui-obc": "~3.4.0",
+    "@types/node": "^20.12.12",
+    "@types/three": "^0.182.0",
+    "commander": "^14.0.3",
+    "esbuild": "^0.27.3",
+    "eslint": "9.x",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "globals": "^15.3.0",
+    "jszip": "^3.10.1",
+    "prettier": "^3.2.5",
+    "three": ">=0.182.0",
+    "tsx": "^4.16.2",
+    "typescript": "^5.2.2",
+    "typescript-eslint": "^7.10.0",
+    "vite": "^5.2.0",
+    "vite-plugin-dts": "^3.9.1",
+    "vite-plugin-eslint": "^1.8.1",
+    "vitest": "^4.1.4"
+  },
+  "dependencies": {
+    "dotenv": "^16.4.5",
+    "socket.io": "^4.8.0",
+    "socket.io-client": "^4.8.0"
+  },
+  "peerDependencies": {
+    "@thatopen/components": "~3.4.0",
+    "@thatopen/ui": "~3.4.0",
+    "three": ">=0.182.0"
+  },
+  "peerDependenciesMeta": {
+    "@thatopen/components": {
+      "optional": true
+    },
+    "@thatopen/ui": {
+      "optional": true
+    },
+    "three": {
+      "optional": true
+    }
+  }
+}

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

@@ -1,285 +1,285 @@
-/* MD
-  ## 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.
-
-  ClashesManager is the platform-side component that owns clash data: it loads and
-  persists jobs, runs, and clashes; launches cloud-based clash detection in a Web
-  Worker; and exposes the events and methods needed to build review workflows on
-  top of it.
-
-  This tutorial covers initializing the manager from the platform client; the
-  recommended `clashes-panel` UI that works out of the box once `init` has been
-  called; defining queries and detection matrices for fine-grained control;
-  launching a detection run and tracking progress; updating clash status
-  programmatically; and rendering sphere markers and element highlights without
-  the built-in panel.
-
-  By the end, you'll understand every public surface of ClashesManager and know
-  which parts are handled automatically by `clashes-panel` so you can decide how
-  much of the stack you need for your use case.
-*/
-
-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 } from "thatopen-services";
-import clashesManagerDef from "./index";
-
-const ClashesManager = clashesManagerDef.componentDefinition;
-
-const client = PlatformClient.fromPlatformContext();
-
-const { components } = (await client.setup(
-  { OBC, OBF, BUI, THREE, FRAGS },
-  { uuid: ClashesManager.uuid },
-)) as { components: OBC.Components };
-
-/* MD
-  ### 🚀 Initializing the manager
-
-  `init(client)` is the only call required before using the manager. It:
-
-  - Loads all persisted clash data (jobs, runs, clashes, queries, matrices) from
-    the project's cloud storage into memory.
-  - Registers `save` and `reload` callbacks so writes are debounced to storage
-    automatically and the manager can refresh its data after a run completes.
-  - Reads any in-flight cloud executions so that a page reload mid-run doesn't
-    lose track of the job.
-  - Resolves the engine's active `World` in the background — if no world exists
-    yet, it waits until one is created, so the order of initialization does not
-    matter.
-
-  After `init` resolves, `manager.ready` is `true` and all data properties
-  (`jobs`, `runs`, `clashes`, `queries`, `matrices`) are populated.
-*/
-
-const manager = components.get(ClashesManager);
-await manager.init(client);
-
-console.log(
-  `Loaded ${manager.jobs.length} jobs, ` +
-  `${manager.runs.length} runs, ` +
-  `${manager.clashes.length} clashes.`,
-);
-
-/* MD
-  ### 🖥️ Adding the built-in panel (recommended)
-
-  Once `init` has been called, the `<clashes-panel>` web component is the
-  recommended way to interact with `ClashesManager`. It covers the full
-  review workflow — detection matrix, clash table, sphere markers, status
-  filters, run progress — with zero additional wiring.
-
-  `clashes-panel` is registered when `UIManager` is included in the platform
-  setup call. See the **clashes-panel** tutorial for the complete setup and a
-  detailed breakdown of everything the panel manages automatically.
-
-  The sections below are for cases where you need direct control: building a
-  custom UI, integrating clash data into your own panels, or automating status
-  updates from outside the panel.
-*/
-
-/* MD
-  ### 📐 Queries and matrices
-
-  A `ClashQuery` defines a named set of model elements: which files to scan and,
-  optionally, which IFC categories or attribute conditions to match. Queries have
-  no detection logic of their own — they are inputs to a matrix.
-
-  A `ClashMatrix` pairs queries in an upper-triangle grid. Each active cell
-  corresponds to one `ClashJob` that the cloud worker will execute. The matrix
-  also carries the clash type (`hard` or `clearance`) and, for clearance checks,
-  the tolerance in metres.
-
-  Assigning to `manager.queries` or `manager.matrices` triggers a debounced
-  auto-save (2 s). Call `await manager.flush()` to persist immediately before
-  navigating away.
-*/
-
-const structuralFileId = "file-id-of-structural-model";
-const mepFileId        = "file-id-of-mep-model";
-
-manager.queries = [
-  {
-    id:           "q-structural",
-    name:         "Structural",
-    modelFileIds: [structuralFileId],
-    query:        { categories: ["IFCBEAM", "IFCCOLUMN", "IFCSLAB"] },
-  },
-  {
-    id:           "q-mep",
-    name:         "MEP",
-    modelFileIds: [mepFileId],
-    // Omitting `query` matches all elements with geometry in the listed files.
-  },
-];
-
-// The matrix below defines a single hard-clash job between Structural and MEP.
-// `activePairs` lists the upper-triangle cell keys (queryAId:queryBId).
-// `jobIds` is managed by the platform when the matrix is saved; leave it empty
-// on first creation and the backend fills it after the first save.
-manager.matrices = [
-  {
-    id:          "matrix-main",
-    name:        "Structural vs MEP",
-    queryIds:    ["q-structural", "q-mep"],
-    activePairs: ["q-structural:q-mep"],
-    jobIds:      [],
-    jobType:     "hard",
-  },
-];
-
-await manager.flush();
-
-/* MD
-  ### ▶️ Running clash detection
-
-  `run(jobId)` launches a Web Worker that calls the cloud clash-detection
-  endpoint. It returns immediately — all feedback arrives through events.
-
-  | Event | Payload | When |
-  |-------|---------|------|
-  | `onRunProgress` | `{ message, progress }` | Periodically while the worker runs |
-  | `onRunComplete` | `{ runId, clashCount }` | Worker finished successfully |
-  | `onRunError`    | `{ code?, message }`    | Worker or cloud error |
-  | `onRunningJobsChanged` | `Set<string>` | A job starts or finishes |
-  | `onReloadingChanged`   | `boolean`     | Data reload after a successful run |
-
-  If the page is reloaded while a run is in progress, `init` re-reads the
-  in-flight execution from storage and populates `runningJobIds`. Call
-  `reconnectIfRunning(jobId)` to resume receiving progress events for that job.
-*/
-
-manager.onRunProgress.add(({ message, progress }) => {
-  console.log(`[${progress}%] ${message}`);
-});
-
-manager.onRunComplete.add(({ runId, clashCount }) => {
-  console.log(`Run ${runId} complete — ${clashCount} clash(es) found.`);
-});
-
-manager.onRunError.add(({ code, message }) => {
-  console.error(`Run failed (${code ?? "unknown"}): ${message}`);
-});
-
-manager.onReloadingChanged.add((reloading) => {
-  // Use this flag to show a loading state in a custom UI while fresh data
-  // is fetched from storage after the run. clashes-panel handles this automatically.
-  console.log(reloading ? "Reloading clash data…" : "Clash data ready.");
-});
-
-// Guard: only run if the manager is ready and the job is not already running.
-const jobToRun = manager.jobs[0];
-if (jobToRun && manager.ready && !manager.runningJobIds.has(jobToRun.id)) {
-  manager.run(jobToRun.id);
-}
-
-// If a run was already in progress before this page loaded, reconnect to it.
-for (const jobId of manager.runningJobIds) {
-  manager.reconnectIfRunning(jobId);
-}
-
-/* MD
-  ### ✅ Updating clash status
-
-  Each clash starts with status `"new"`. Reviewers move clashes through a
-  workflow by calling `updateClash`. Valid statuses are:
-
-  - `"new"` — detected, not yet reviewed
-  - `"active"` — under investigation
-  - `"acknowledged"` — known issue, not blocking
-  - `"resolved"` — fixed and verified
-
-  Status changes and comments are persisted automatically via the same
-  auto-save mechanism as queries and matrices.
-
-  `runsForJob(jobId)` and `clashesForRun(runId)` let you navigate the history:
-  a clash's `firstSeenRunId` / `lastSeenRunId` span shows across which runs it
-  was present, so you can determine whether a resolution actually closed it.
-*/
-
-manager.onClashStatusChanged.add((allClashes) => {
-  const open = allClashes.filter(c => c.status === "new" || c.status === "active");
-  console.log(`Open clashes: ${open.length}`);
-});
-
-const clashToAcknowledge = manager.clashes[0];
-if (clashToAcknowledge) {
-  manager.updateClash(clashToAcknowledge.id, {
-    status:   "acknowledged",
-    comments: "Coordination with MEP team scheduled for next sprint.",
-  });
-}
-
-// Navigate run history for the first job.
-const firstJob = manager.jobs[0];
-if (firstJob) {
-  const runs = manager.runsForJob(firstJob.id);    // newest first
-  const latestRun = runs[0];
-  if (latestRun) {
-    const clashesInRun = manager.clashesForRun(latestRun.id);
-    console.log(`Latest run has ${clashesInRun.length} active clash(es).`);
-  }
-}
-
-/* MD
-  ### 📍 Visualization without the built-in panel
-
-  If you are building a custom UI and not using `clashes-panel`, you can drive
-  the visualization layer directly.
-
-  **Sphere markers** — `showMarkers` places colored 3D spheres at clash
-  locations in the viewer. Call `hideMarkers` to remove them and re-enable
-  hover highlighting. Points are automatically transformed from IFC world space
-  to Three.js viewer space using `FragmentsManager.baseCoordinationMatrix`.
-
-  **Element highlights** — `highlightAllClashes` colors element A (green) and
-  element B (red) for every new/active clash in the provided list.
-  `clearClashHighlight` removes both styles. For single-clash focus, use
-  `highlightClash` and pair it with `ghostClashes` to dim everything else.
-
-  **Clustering** — `cluster(clashes, threshold)` groups spatially close clashes
-  into a single marker. Pass `threshold = 0` to show one sphere per clash.
-  `toViewerPoint` converts a raw IFC point to viewer space if you need to
-  position custom objects.
-*/
-
-const jobClashes = manager.clashes.filter(c => c.jobId === firstJob?.id);
-
-// Show one marker per clash, colored by status.
-manager.showMarkers(
-  jobClashes.map(c => ({ id: c.id, point: c.point, count: 1, status: c.status })),
-);
-
-// Highlight all open clashes across both element sets.
-manager.highlightAllClashes(jobClashes);
-
-// --- Clustered view ---
-// Group clashes within 2 m of each other into a single sphere.
-const clusters = manager.cluster(jobClashes, 2);
-manager.showMarkers(
-  clusters.map(group => ({
-    point:  group[0].point,
-    count:  group.length,
-    status: group[0].status,
-  })),
-);
-
-// Focus on a single clash: ghost everything else and zoom in.
-const focusClash = jobClashes[0];
-if (focusClash) {
-  manager.clearClashHighlight();
-  manager.highlightClash(focusClash);
-  await manager.ghostClash(focusClash);
-}
-
-// Restore full scene when done.
-manager.hideMarkers();
-manager.clearClashHighlight();
-await manager.clearGhostClash();
+/* MD
+  ## 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.
+
+  ClashesManager is the platform-side component that owns clash data: it loads and
+  persists jobs, runs, and clashes; launches cloud-based clash detection in a Web
+  Worker; and exposes the events and methods needed to build review workflows on
+  top of it.
+
+  This tutorial covers initializing the manager from the platform client; the
+  recommended `clashes-panel` UI that works out of the box once `init` has been
+  called; defining queries and detection matrices for fine-grained control;
+  launching a detection run and tracking progress; updating clash status
+  programmatically; and rendering sphere markers and element highlights without
+  the built-in panel.
+
+  By the end, you'll understand every public surface of ClashesManager and know
+  which parts are handled automatically by `clashes-panel` so you can decide how
+  much of the stack you need for your use case.
+*/
+
+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 } from "thatopen-services";
+import clashesManagerDef from "./index";
+
+const ClashesManager = clashesManagerDef.componentDefinition;
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: ClashesManager.uuid },
+)) as { components: OBC.Components };
+
+/* MD
+  ### 🚀 Initializing the manager
+
+  `init(client)` is the only call required before using the manager. It:
+
+  - Loads all persisted clash data (jobs, runs, clashes, queries, matrices) from
+    the project's cloud storage into memory.
+  - Registers `save` and `reload` callbacks so writes are debounced to storage
+    automatically and the manager can refresh its data after a run completes.
+  - Reads any in-flight cloud executions so that a page reload mid-run doesn't
+    lose track of the job.
+  - Resolves the engine's active `World` in the background — if no world exists
+    yet, it waits until one is created, so the order of initialization does not
+    matter.
+
+  After `init` resolves, `manager.ready` is `true` and all data properties
+  (`jobs`, `runs`, `clashes`, `queries`, `matrices`) are populated.
+*/
+
+const manager = components.get(ClashesManager);
+await manager.init(client);
+
+console.log(
+  `Loaded ${manager.jobs.length} jobs, ` +
+  `${manager.runs.length} runs, ` +
+  `${manager.clashes.length} clashes.`,
+);
+
+/* MD
+  ### 🖥️ Adding the built-in panel (recommended)
+
+  Once `init` has been called, the `<top-clashes-panel>` web component is the
+  recommended way to interact with `ClashesManager`. It covers the full
+  review workflow — detection matrix, clash table, sphere markers, status
+  filters, run progress — with zero additional wiring.
+
+  `clashes-panel` is registered when `UIManager` is included in the platform
+  setup call. See the **clashes-panel** tutorial for the complete setup and a
+  detailed breakdown of everything the panel manages automatically.
+
+  The sections below are for cases where you need direct control: building a
+  custom UI, integrating clash data into your own panels, or automating status
+  updates from outside the panel.
+*/
+
+/* MD
+  ### 📐 Queries and matrices
+
+  A `ClashQuery` defines a named set of model elements: which files to scan and,
+  optionally, which IFC categories or attribute conditions to match. Queries have
+  no detection logic of their own — they are inputs to a matrix.
+
+  A `ClashMatrix` pairs queries in an upper-triangle grid. Each active cell
+  corresponds to one `ClashJob` that the cloud worker will execute. The matrix
+  also carries the clash type (`hard` or `clearance`) and, for clearance checks,
+  the tolerance in metres.
+
+  Assigning to `manager.queries` or `manager.matrices` triggers a debounced
+  auto-save (2 s). Call `await manager.flush()` to persist immediately before
+  navigating away.
+*/
+
+const structuralFileId = "file-id-of-structural-model";
+const mepFileId        = "file-id-of-mep-model";
+
+manager.queries = [
+  {
+    id:           "q-structural",
+    name:         "Structural",
+    modelFileIds: [structuralFileId],
+    query:        { categories: ["IFCBEAM", "IFCCOLUMN", "IFCSLAB"] },
+  },
+  {
+    id:           "q-mep",
+    name:         "MEP",
+    modelFileIds: [mepFileId],
+    // Omitting `query` matches all elements with geometry in the listed files.
+  },
+];
+
+// The matrix below defines a single hard-clash job between Structural and MEP.
+// `activePairs` lists the upper-triangle cell keys (queryAId:queryBId).
+// `jobIds` is managed by the platform when the matrix is saved; leave it empty
+// on first creation and the backend fills it after the first save.
+manager.matrices = [
+  {
+    id:          "matrix-main",
+    name:        "Structural vs MEP",
+    queryIds:    ["q-structural", "q-mep"],
+    activePairs: ["q-structural:q-mep"],
+    jobIds:      [],
+    jobType:     "hard",
+  },
+];
+
+await manager.flush();
+
+/* MD
+  ### ▶️ Running clash detection
+
+  `run(jobId)` launches a Web Worker that calls the cloud clash-detection
+  endpoint. It returns immediately — all feedback arrives through events.
+
+  | Event | Payload | When |
+  |-------|---------|------|
+  | `onRunProgress` | `{ message, progress }` | Periodically while the worker runs |
+  | `onRunComplete` | `{ runId, clashCount }` | Worker finished successfully |
+  | `onRunError`    | `{ code?, message }`    | Worker or cloud error |
+  | `onRunningJobsChanged` | `Set<string>` | A job starts or finishes |
+  | `onReloadingChanged`   | `boolean`     | Data reload after a successful run |
+
+  If the page is reloaded while a run is in progress, `init` re-reads the
+  in-flight execution from storage and populates `runningJobIds`. Call
+  `reconnectIfRunning(jobId)` to resume receiving progress events for that job.
+*/
+
+manager.onRunProgress.add(({ message, progress }) => {
+  console.log(`[${progress}%] ${message}`);
+});
+
+manager.onRunComplete.add(({ runId, clashCount }) => {
+  console.log(`Run ${runId} complete — ${clashCount} clash(es) found.`);
+});
+
+manager.onRunError.add(({ code, message }) => {
+  console.error(`Run failed (${code ?? "unknown"}): ${message}`);
+});
+
+manager.onReloadingChanged.add((reloading) => {
+  // Use this flag to show a loading state in a custom UI while fresh data
+  // is fetched from storage after the run. clashes-panel handles this automatically.
+  console.log(reloading ? "Reloading clash data…" : "Clash data ready.");
+});
+
+// Guard: only run if the manager is ready and the job is not already running.
+const jobToRun = manager.jobs[0];
+if (jobToRun && manager.ready && !manager.runningJobIds.has(jobToRun.id)) {
+  manager.run(jobToRun.id);
+}
+
+// If a run was already in progress before this page loaded, reconnect to it.
+for (const jobId of manager.runningJobIds) {
+  manager.reconnectIfRunning(jobId);
+}
+
+/* MD
+  ### ✅ Updating clash status
+
+  Each clash starts with status `"new"`. Reviewers move clashes through a
+  workflow by calling `updateClash`. Valid statuses are:
+
+  - `"new"` — detected, not yet reviewed
+  - `"active"` — under investigation
+  - `"acknowledged"` — known issue, not blocking
+  - `"resolved"` — fixed and verified
+
+  Status changes and comments are persisted automatically via the same
+  auto-save mechanism as queries and matrices.
+
+  `runsForJob(jobId)` and `clashesForRun(runId)` let you navigate the history:
+  a clash's `firstSeenRunId` / `lastSeenRunId` span shows across which runs it
+  was present, so you can determine whether a resolution actually closed it.
+*/
+
+manager.onClashStatusChanged.add((allClashes) => {
+  const open = allClashes.filter(c => c.status === "new" || c.status === "active");
+  console.log(`Open clashes: ${open.length}`);
+});
+
+const clashToAcknowledge = manager.clashes[0];
+if (clashToAcknowledge) {
+  manager.updateClash(clashToAcknowledge.id, {
+    status:   "acknowledged",
+    comments: "Coordination with MEP team scheduled for next sprint.",
+  });
+}
+
+// Navigate run history for the first job.
+const firstJob = manager.jobs[0];
+if (firstJob) {
+  const runs = manager.runsForJob(firstJob.id);    // newest first
+  const latestRun = runs[0];
+  if (latestRun) {
+    const clashesInRun = manager.clashesForRun(latestRun.id);
+    console.log(`Latest run has ${clashesInRun.length} active clash(es).`);
+  }
+}
+
+/* MD
+  ### 📍 Visualization without the built-in panel
+
+  If you are building a custom UI and not using `clashes-panel`, you can drive
+  the visualization layer directly.
+
+  **Sphere markers** — `showMarkers` places colored 3D spheres at clash
+  locations in the viewer. Call `hideMarkers` to remove them and re-enable
+  hover highlighting. Points are automatically transformed from IFC world space
+  to Three.js viewer space using `FragmentsManager.baseCoordinationMatrix`.
+
+  **Element highlights** — `highlightAllClashes` colors element A (green) and
+  element B (red) for every new/active clash in the provided list.
+  `clearClashHighlight` removes both styles. For single-clash focus, use
+  `highlightClash` and pair it with `ghostClashes` to dim everything else.
+
+  **Clustering** — `cluster(clashes, threshold)` groups spatially close clashes
+  into a single marker. Pass `threshold = 0` to show one sphere per clash.
+  `toViewerPoint` converts a raw IFC point to viewer space if you need to
+  position custom objects.
+*/
+
+const jobClashes = manager.clashes.filter(c => c.jobId === firstJob?.id);
+
+// Show one marker per clash, colored by status.
+manager.showMarkers(
+  jobClashes.map(c => ({ id: c.id, point: c.point, count: 1, status: c.status })),
+);
+
+// Highlight all open clashes across both element sets.
+manager.highlightAllClashes(jobClashes);
+
+// --- Clustered view ---
+// Group clashes within 2 m of each other into a single sphere.
+const clusters = manager.cluster(jobClashes, 2);
+manager.showMarkers(
+  clusters.map(group => ({
+    point:  group[0].point,
+    count:  group.length,
+    status: group[0].status,
+  })),
+);
+
+// Focus on a single clash: ghost everything else and zoom in.
+const focusClash = jobClashes[0];
+if (focusClash) {
+  manager.clearClashHighlight();
+  manager.highlightClash(focusClash);
+  await manager.ghostClash(focusClash);
+}
+
+// Restore full scene when done.
+manager.hideMarkers();
+manager.clearClashHighlight();
+await manager.clearGhostClash();

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

@@ -1,164 +1,164 @@
-/* MD
-  ## 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.
-
-  `clashes-panel` is a ready-made web component that delivers exactly that. It
-  connects to `ClashesManager` automatically and manages the entire review
-  workflow: the detection matrix, the clash table with status filters, sphere
-  markers and element highlights in the viewer, run controls with live progress,
-  and a loading skeleton while fresh data reloads after a run completes.
-
-  This tutorial covers the prerequisites before mounting the panel; dropping it
-  into a `top-app` layout alongside a 3D viewer; and a detailed breakdown of
-  everything the panel handles automatically so you know what you do not need to
-  implement yourself.
-
-  By the end, you'll have a fully working clash-review environment running in
-  your application with a single line of markup.
-*/
-
-import { html } from "lit";
-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 } from "thatopen-services";
-import uiManagerDef from "../../../index";
-import clashesManagerDef from "../../../ClashesManager/index";
-import type { App } from "../app/index";
-
-const UIManager      = uiManagerDef.componentDefinition;
-const ClashesManager = clashesManagerDef.componentDefinition;
-
-/* MD
-  ### ✅ Prerequisites
-
-  Two conditions must be met before the panel mounts:
-
-  1. **`UIManager` must be in the setup call.** It registers all platform web
-     components, including `<clashes-panel>` itself. Without it the element is
-     unknown to the browser and renders as an empty box.
-
-  2. **`ClashesManager.init(client)` must have resolved.** The panel reads all
-     its initial data from the manager in `connectedCallback`. If `init` has not
-     finished, the panel mounts into an empty state and never catches up because
-     it only subscribes to change events — it does not poll.
-
-  Both conditions are naturally satisfied when you call `init` before appending
-  `top-app` to the document, which is the pattern shown below.
-*/
-
-const client = PlatformClient.fromPlatformContext();
-
-const { components } = (await client.setup(
-  { OBC, OBF, BUI, THREE, FRAGS },
-  { uuid: UIManager.uuid },
-  { uuid: ClashesManager.uuid },
-)) as { components: OBC.Components };
-
-components.get(UIManager).init();
-
-// init must resolve before top-app (and therefore clashes-panel) mounts.
-await components.get(ClashesManager).init(client);
-
-/* MD
-  ### 🖥️ Wiring the panel
-
-  Add `clashes-panel` as a named area in `app.elements` and reference it in your
-  layout template. A side-by-side layout with the 3D viewer is the most natural
-  arrangement — the panel controls markers and highlights directly in the scene.
-*/
-
-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",
-  );
-
-  waitUntil(
-    (async () => {
-      const loader = components.get(OBC.IfcLoader);
-      await loader.setup();
-    })(),
-    "IFC Loader",
-  );
-
-  return { components, client };
-};
-
-app.elements = {
-  viewer:  () => html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
-  clashes: () => html`<clashes-panel></clashes-panel>`,
-};
-
-app.layouts = {
-  main: {
-    label:    "Main",
-    icon:     "solar:3d-square-bold",
-    template: `"viewer clashes" 1fr / 1fr 22rem`,
-  },
-};
-
-app.layout = "main";
-
-const container = document.getElementById("that-open-app") ?? document.body;
-container.appendChild(app);
-document.body.style.margin = "0";
-
-/* MD
-  ### 🤖 What the panel manages automatically
-
-  Once mounted, `clashes-panel` takes ownership of the following without any
-  further code from you:
-
-  **Data synchronization** — the panel subscribes to every `ClashesManager`
-  event (`onJobsChanged`, `onRunsChanged`, `onClashesChanged`,
-  `onClashStatusChanged`, `onQueriesChanged`, `onRunningJobsChanged`) and keeps
-  its tables in sync. Changes made programmatically through the manager API are
-  reflected in the panel immediately.
-
-  **Run lifecycle** — a progress callout appears as soon as a run starts
-  (`onRunProgress`), updates its percentage and message in real time, and
-  disappears when the run completes or errors. If a run was already in progress
-  when the page loaded, the panel calls `reconnectIfRunning` automatically when
-  the user opens that job.
-
-  **Post-run reload skeleton** — after a successful run the manager reloads clash
-  data from storage. During that window (`onReloadingChanged = true`) the panel
-  replaces its entire content with an animated skeleton so the user is never left
-  looking at stale results that appear final.
-
-  **Sphere markers** — entering a job view places colored spheres in the 3D scene
-  at each clash location, transformed from IFC world space to viewer space.
-  Selecting a clash in the table zooms the camera, ghosts unrelated elements, and
-  re-focuses the markers on the selection. Leaving the job view removes all
-  markers and restores the full scene.
-
-  **Element highlights** — element A is highlighted green and element B red for
-  every new or active clash in the current job. Selecting a single clash refines
-  the highlight to that pair only. Clearing the selection or changing status
-  restores the full job highlight.
-
-  **Model awareness** — the panel tracks which fragment models are currently
-  loaded in the scene. Markers and highlights are activated only when the relevant
-  models are present, and are cleaned up automatically if a model is disposed
-  while the panel is open.
-
-  **Save indicator** — a subtle indicator appears while auto-save is in progress
-  (`onSaveStart`) and disappears once the write confirms (`onSaveComplete`), so
-  users know their status changes and query edits are persisted.
-
-  **Disconnection cleanup** — when the panel is removed from the DOM it calls
-  `hideMarkers` and `clearClashHighlight` on the manager, leaving the 3D scene
-  clean regardless of what was selected at the time.
-*/
+/* MD
+  ## 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.
+
+  `clashes-panel` is a ready-made web component that delivers exactly that. It
+  connects to `ClashesManager` automatically and manages the entire review
+  workflow: the detection matrix, the clash table with status filters, sphere
+  markers and element highlights in the viewer, run controls with live progress,
+  and a loading skeleton while fresh data reloads after a run completes.
+
+  This tutorial covers the prerequisites before mounting the panel; dropping it
+  into a `top-app` layout alongside a 3D viewer; and a detailed breakdown of
+  everything the panel handles automatically so you know what you do not need to
+  implement yourself.
+
+  By the end, you'll have a fully working clash-review environment running in
+  your application with a single line of markup.
+*/
+
+import { html } from "lit";
+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 } from "thatopen-services";
+import uiManagerDef from "../../../index";
+import clashesManagerDef from "../../../ClashesManager/index";
+import type { App } from "../app/index";
+
+const UIManager      = uiManagerDef.componentDefinition;
+const ClashesManager = clashesManagerDef.componentDefinition;
+
+/* MD
+  ### ✅ Prerequisites
+
+  Two conditions must be met before the panel mounts:
+
+  1. **`UIManager` must be in the setup call.** It registers all platform web
+     components, including `<top-clashes-panel>` itself. Without it the element is
+     unknown to the browser and renders as an empty box.
+
+  2. **`ClashesManager.init(client)` must have resolved.** The panel reads all
+     its initial data from the manager in `connectedCallback`. If `init` has not
+     finished, the panel mounts into an empty state and never catches up because
+     it only subscribes to change events — it does not poll.
+
+  Both conditions are naturally satisfied when you call `init` before appending
+  `top-app` to the document, which is the pattern shown below.
+*/
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: UIManager.uuid },
+  { uuid: ClashesManager.uuid },
+)) as { components: OBC.Components };
+
+components.get(UIManager).init();
+
+// init must resolve before top-app (and therefore clashes-panel) mounts.
+await components.get(ClashesManager).init(client);
+
+/* MD
+  ### 🖥️ Wiring the panel
+
+  Add `clashes-panel` as a named area in `app.elements` and reference it in your
+  layout template. A side-by-side layout with the 3D viewer is the most natural
+  arrangement — the panel controls markers and highlights directly in the scene.
+*/
+
+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",
+  );
+
+  waitUntil(
+    (async () => {
+      const loader = components.get(OBC.IfcLoader);
+      await loader.setup();
+    })(),
+    "IFC Loader",
+  );
+
+  return { components, client };
+};
+
+app.elements = {
+  viewer:  () => html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
+  clashes: () => html`<top-clashes-panel></top-clashes-panel>`,
+};
+
+app.layouts = {
+  main: {
+    label:    "Main",
+    icon:     "solar:3d-square-bold",
+    template: `"viewer clashes" 1fr / 1fr 22rem`,
+  },
+};
+
+app.layout = "main";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";
+
+/* MD
+  ### 🤖 What the panel manages automatically
+
+  Once mounted, `clashes-panel` takes ownership of the following without any
+  further code from you:
+
+  **Data synchronization** — the panel subscribes to every `ClashesManager`
+  event (`onJobsChanged`, `onRunsChanged`, `onClashesChanged`,
+  `onClashStatusChanged`, `onQueriesChanged`, `onRunningJobsChanged`) and keeps
+  its tables in sync. Changes made programmatically through the manager API are
+  reflected in the panel immediately.
+
+  **Run lifecycle** — a progress callout appears as soon as a run starts
+  (`onRunProgress`), updates its percentage and message in real time, and
+  disappears when the run completes or errors. If a run was already in progress
+  when the page loaded, the panel calls `reconnectIfRunning` automatically when
+  the user opens that job.
+
+  **Post-run reload skeleton** — after a successful run the manager reloads clash
+  data from storage. During that window (`onReloadingChanged = true`) the panel
+  replaces its entire content with an animated skeleton so the user is never left
+  looking at stale results that appear final.
+
+  **Sphere markers** — entering a job view places colored spheres in the 3D scene
+  at each clash location, transformed from IFC world space to viewer space.
+  Selecting a clash in the table zooms the camera, ghosts unrelated elements, and
+  re-focuses the markers on the selection. Leaving the job view removes all
+  markers and restores the full scene.
+
+  **Element highlights** — element A is highlighted green and element B red for
+  every new or active clash in the current job. Selecting a single clash refines
+  the highlight to that pair only. Clearing the selection or changing status
+  restores the full job highlight.
+
+  **Model awareness** — the panel tracks which fragment models are currently
+  loaded in the scene. Markers and highlights are activated only when the relevant
+  models are present, and are cleaned up automatically if a model is disposed
+  while the panel is open.
+
+  **Save indicator** — a subtle indicator appears while auto-save is in progress
+  (`onSaveStart`) and disappears once the write confirms (`onSaveComplete`), so
+  users know their status changes and query edits are persisted.
+
+  **Disconnection cleanup** — when the panel is removed from the DOM it calls
+  `hideMarkers` and `clearClashHighlight` on the manager, leaving the 3D scene
+  clean regardless of what was selected at the time.
+*/