@thatopen/services 0.3.10 → 0.3.12

package/src/cli/templates/app/README.md

@@ -1,241 +1,217 @@
-# ThatOpen BIM App
-
-This is a BIM (Building Information Modeling) app built for the That Open Platform.
-It runs in the browser inside the platform's iframe and has access to a 3D viewer,
-UI components, and the platform API.
-
-## How this app works
-
-- **Entry point**: `src/main.ts` — runs as an IIFE when the platform loads the app.
-- **Build output**: `dist/bundle.js` — a single IIFE file built by Vite.
-- **Platform context**: The platform injects `window.__THATOPEN_CONTEXT__` with:
-  - `appId` — this app's unique ID
-  - `projectId` — the project this app belongs to
-  - `accessToken` — Auth0 JWT for API calls
-  - `apiUrl` — base URL for the That Open API
-
-## Commands
-
-```bash
-npm run dev        # Start dev server (esbuild watch + serve on :4000)
-npm run build               # Build dist/bundle.js (Vite/Rollup production build)
-npm run login               # Authenticate with the platform (saves token locally)
-npm run publish             # Publish to the platform
-```
-
-### Local development
-
-Apps run inside the That Open Platform (platform.thatopen.com) within a project —
-not as standalone websites. To develop locally:
-
-1. Run `npm run dev` — this watches source files with esbuild and serves the bundle on port 4000.
-2. Open your project on the platform and click the debug button.
-3. Live reload is enabled — save a file to rebuild automatically.
-
-The dev server (`thatopen serve`) uses esbuild for near-instant incremental rebuilds.
-**Important**: Do NOT run `vite`, `vite build --watch`, or `npx vite` directly for development.
-Always use `npm run dev` which runs `thatopen serve` under the hood.
-
-## Key libraries
-
-| Package | Import | Purpose |
-|---------|--------|---------|
-| `@thatopen/components` | `OBC` | BIM engine — components, fragments, worlds |
-| `@thatopen/components-front` | `OBF` | Front-end BIM components (Highlighter, measurements, etc.) |
-| `@thatopen/fragments` | `FRAGS` | Fragment geometry format |
-| `@thatopen/ui` | `BUI` | UI web components (`<bim-panel>`, `<bim-grid>`, etc.) |
-| `three` | `THREE` | 3D rendering engine |
-| `@thatopen/services` | `EngineServicesClient` | Platform API client + built-in components |
-
-## Architecture pattern
-
-```
-1. Create EngineServicesClient from platform context
-2. Call client.setup(globals, ...builtIns) — creates OBC.Components,
-  inits BUI, loads built-in components, calls components.init()
-3. Create viewport(s) and UI elements
-4. Configure AppManager with elements + layouts
-5. Call app.init()
-```
-
-## Built-in components
-
-Built-in components are platform-hosted UI modules loaded at runtime via the API client.
-They are fetched, evaluated, and registered with the OBC component system.
-
-| Component | Purpose |
-|-----------|---------|
-| **AppManager** | App shell — CSS grid layout system with sidebar for switching layouts |
-| **ViewportsManager** | Factory for 3D viewports with pre-configured world (scene, camera, renderer) |
-| **LoadModelButton** | Button + dropdown for loading IFC and Fragments files |
-| **ViewerToolbar** | Toolbar with Show/Hide/Focus/Isolate actions and color palette |
-| **ModelsPanel** | Panel listing loaded models with search bar and load button |
-| **ModelsDropdown** | Dropdown selector listing loaded models |
-| **ClassificationsList** | Hierarchical table of IFC classification data |
-| **ClashesList** | Interactive clash detection results with click-to-highlight |
-| **ClippingsList** | Panel listing clipping planes with enable/delete controls |
-| **LengthMeasuringsList** | Panel listing length measurements with cumulative total |
-| **AreaMeasuringsList** | Panel listing area measurements with area/perimeter totals |
-| **ColorsPalette** | Color picker grid with custom input and Highlighter styles |
-| **HighlightersList** | Panel listing Highlighter styles with manage/apply actions |
-| **QtoComparisonList** | Side-by-side quantity comparison for two selected elements |
-| **QueriesHierarchy** | Recursive multi-level query browser for IFC data |
-| **CustomViewLegend** | Color legend overlay with colored circles and labels |
-| **ScreenshotAnnotator** | Modal for annotating screenshots (arrows, text, freehand) via MarkerJS |
-
-**Full API reference**: Each component has detailed JSDoc with `@example` blocks in the
-`@thatopen/services` package source (`src/built-in/index.ts`). Read that file for config
-interfaces, method signatures, and code examples.
-
-### Loading pattern
-
-Use `setup` to create the component system and load built-in components in one call:
-
-```ts
-import { PlatformClient, AppManager, ViewportsManager } from "@thatopen/services";
-
-const client = PlatformClient.fromPlatformContext();
-
-// Creates OBC.Components, inits BUI, loads built-ins, calls components.init()
-const { components } = await client.setup(
-  { OBC, OBF, BUI, THREE, FRAGS },
-  AppManager, ViewportsManager,
-);
-
-const app = components.get(AppManager);
-const viewports = components.get(ViewportsManager);
-```
-
-You can also load components individually if needed:
-
-```ts
-// Batch load (parallel)
-await client.initBuiltInComponents(components, AppManager, ViewportsManager);
-
-// Or one at a time
-await client.initBuiltInComponent(AppManager, components);
-```
-
-### Required globals per component
-
-| Component | Globals to pass | Extra npm packages needed |
-|-----------|----------------|--------------------------|
-| AppManager | `{ OBC, BUI }` | — |
-| ViewportsManager | `{ OBC, BUI, THREE, FRAGS }` | — |
-| LoadModelButton | `{ OBC, BUI }` | — |
-| ModelsDropdown | `{ OBC, BUI }` | — |
-| ViewerToolbar | `{ OBC, OBF, BUI, THREE }` | `@thatopen/components-front` |
-| ColorsPalette | `{ OBC, OBF, BUI }` | `@thatopen/components-front` |
-| ClashesList | `{ OBC, OBF, BUI, THREE }` | `@thatopen/components-front` |
-| ClassificationsList | `{ OBC, OBF, BUI }` | `@thatopen/components-front` |
-| ClippingsList | `{ OBC, BUI }` | — |
-| HighlightersList | `{ OBC, OBF, BUI }` | `@thatopen/components-front` |
-| LengthMeasuringsList | `{ OBC, OBF, BUI, THREE }` | `@thatopen/components-front` |
-| AreaMeasuringsList | `{ OBC, OBF, BUI, THREE }` | `@thatopen/components-front` |
-| QtoComparisonList | `{ OBC, OBF, BUI }` | `@thatopen/components-front` |
-| QueriesHierarchy | `{ OBC, OBF, BUI }` | `@thatopen/components-front` |
-| CustomViewLegend | `{ OBC, BUI }` | — |
-| ScreenshotAnnotator | `{ OBC, BUI, MARKERJS }` | `@markerjs/markerjs3` |
-
-### Global abbreviations
-
-```ts
-import * as OBC from "@thatopen/components";
-import * as OBF from "@thatopen/components-front";   // needed for Toolbar, Highlighters, Clashes, etc.
-import * as BUI from "@thatopen/ui";
-import * as THREE from "three";
-import * as FRAGS from "@thatopen/fragments";
-import * as MARKERJS from "@markerjs/markerjs3";      // needed for ScreenshotAnnotator
-```
-
-### AppManager — app shell with CSS grid layouts
-
-Creates a grid-based layout system. Define named element slots and named layouts.
-A sidebar for switching layouts appears automatically when multiple layouts exist.
-
-```ts
-const Layouts = ["Viewer", "Split"];
-const Elements = ["viewer", "panel"];
-
-await app.init({
-  client,
-  icons: undefined, // pass Record<K, string> when using typed App interface with icon keys
-  grid: (grid: BUI.Grid<Layouts, Elements>) => {
-    grid.elements = {
-      viewer: viewportElement,
-      panel: panelFunction, // Can be HTMLElement, () => BUI.TemplateResult, or { template, initialState }
-    };
-    grid.layouts = {
-      Viewer: { template: `"viewer" 1fr / 1fr` },
-      Split: {
-        template: `"panel viewer" 1fr / 20rem 1fr`,
-        icon: "solar:settings-bold",
-      },
-    };
-  },
-});
-```
-
-The `template` string uses CSS `grid-template` shorthand: `"areas" rows / columns`.
-
-### ViewportsManager — 3D viewport factory
-
-Creates viewports with pre-configured world (scene, camera, renderer) and auto-initialized fragments.
-
-```ts
-const viewports = components.get(ViewportsManager);
-const { element, world } = await viewports.create();
-// element is an HTMLElement to place in a layout slot
-// world has world.scene, world.camera, world.renderer
-```
-
-## Loading a BIM model
-
-```ts
-const fragments = components.get(OBC.FragmentsManager);
-
-// From URL
-const response = await fetch("https://example.com/model.frag");
-const buffer = await response.arrayBuffer();
-await fragments.core.load(buffer, { modelId: "my-model" });
-
-// From platform storage
-const fileResponse = await client.downloadFile(fileId);
-const fileBuffer = await fileResponse.arrayBuffer();
-await fragments.core.load(fileBuffer, { modelId: "my-model" });
-```
-
-## EngineServicesClient API (commonly used in apps)
-
-```ts
-// Recommended: auto-reads window.__THATOPEN_CONTEXT__ and sets useBearer: true
-const client = PlatformClient.fromPlatformContext();
-console.log(client.context.projectId); // access the platform context
-
-// Files
-const files = await client.listFiles();
-const file = await client.getFile(fileId);
-const response = await client.downloadFile(fileId);
-await client.createFile({ file: blob, name: "model.ifc", versionTag: "v1" });
-
-// Folders
-const folders = await client.listFolders();
-await client.createFolder("My Folder");
-
-// Execute cloud components
-const { executionId } = await client.executeComponent(componentId, { param: "value" });
-client.onExecutionProgress(executionId, (data) => {
-  // data.progressUpdate — progress percentage
-  // data.messageUpdate — status messages
-});
-
-// Test against a local cloud component (requires thatopen local-server running in the component project)
-client.localServerUrl = "http://localhost:4001";
-const local = await client.executeComponent("any-id", { param: "value" });
-client.localServerUrl = null; // reset to use the cloud API
-```
-
-## Configuration
-
-- `.thatopen` — local config (gitignored). Created by `npm run login`. Contains `accessToken`, `apiUrl`, and `appId` after first publish.
-- `vite.config.js` — builds to IIFE format as `dist/bundle.js`. All dependencies are bundled.
+# ThatOpen BIM App
+
+This is a BIM (Building Information Modeling) app built for the That Open Platform.
+It runs in the browser inside the platform's iframe and has access to a 3D viewer,
+UI components, and the platform API.
+
+> IMPORTANT for AI assistants: the authoritative, always-current reference for the
+> platform rules, the built-in components, and how to wire each one is shipped
+> inside the installed package. Read these before writing code:
+>
+> - `node_modules/@thatopen/services/resources/AGENTS.md` — platform rules + the
+>   full navigation table.
+> - `node_modules/@thatopen/services/docs/builtin/paths.json` — the index of every
+>   built-in component, with a one-line description and the path to its example.
+> - `node_modules/@thatopen/services/src/built-in/<Component>/example.ts` — a
+>   complete, copy-adaptable integration example per component.
+>
+> This README explains the app's shape and the general pattern. For the exact API
+> of any built-in, trust `paths.json` + the example files over any list here.
+
+## How this app works
+
+- **Entry point**: `src/main.ts` — runs as an IIFE when the platform loads the app.
+- **Build output**: `dist/bundle.js` — a single IIFE file.
+- **Platform context**: the platform injects the app's context (project id, access
+  token, API url). `PlatformClient.fromPlatformContext()` reads it for you.
+
+## Commands
+
+```bash
+npm run dev        # Start the dev server (esbuild watch + serve on :4000)
+npm run build      # Build dist/bundle.js
+npm run login      # Authenticate with the platform (saves token locally)
+npm run publish    # Publish to the platform
+```
+
+### Local development
+
+Apps run inside the That Open Platform within a project, not as standalone websites.
+To develop locally:
+
+1. Run `npm run dev` — watches source with esbuild and serves the bundle on port 4000.
+2. Open your project on the platform and click the debug button.
+3. Live reload is enabled — save a file to rebuild automatically.
+
+**Important**: use `npm run dev` (it runs `thatopen serve` under the hood). Do NOT run
+`vite` / `vite build --watch` directly for development — `thatopen serve` applies the
+correct build settings (including the beta engine-library aliases for beta projects).
+
+## Key libraries
+
+| Package | Import as | Purpose |
+|---------|-----------|---------|
+| `@thatopen/components` | `OBC` | BIM engine — components, fragments, worlds |
+| `@thatopen/components-front` | `OBF` | Front-end BIM components (Highlighter, measurements, …) |
+| `@thatopen/fragments` | `FRAGS` | Fragment geometry format |
+| `@thatopen/ui` | `BUI` | UI web components (`<bim-panel>`, `<bim-grid>`, …) |
+| `three` | `THREE` | 3D rendering engine |
+| `@markerjs/markerjs3` | `MARKERJS` | Screenshot annotation |
+| `@thatopen/services` | (named exports) | Platform API client (`PlatformClient`) + built-in components |
+
+```ts
+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 * as THREE from "three";
+import * as MARKERJS from "@markerjs/markerjs3";
+import { PlatformClient, UIManager } from "@thatopen/services";
+```
+
+## Architecture
+
+The app boots on the **`UIManager`** built-in. `UIManager` registers the platform's
+web components — the app shell and viewport plus every panel — as custom elements you
+place with plain HTML/`BUI.html`:
+
+- `<top-app>` — the app shell: a CSS-grid layout system with a sidebar (activity bar)
+  for switching named layouts.
+- `<top-viewer>` — the 3D viewport (pre-configured world: scene, camera, renderer,
+  fragments), with its own tools baked in.
+- `<top-viewer-toolbar>` — the bottom viewer toolbar (visibility/inspect, clip, measure).
+- Side panels — `<top-model-tree>`, `<top-properties-panel>`, `<top-models-list>`,
+  `<top-data-table-panel>`, `<top-objects-panel>`, `<top-settings-panel>`, … — each
+  self-wires from the contexts `<top-app>` provides (no `components` plumbing needed).
+
+The scaffolded `src/main.ts` already sets this up. The shape is:
+
+```ts
+const client = PlatformClient.fromPlatformContext();
+
+// 1. Register the platform web components. UIManager MUST be in setup — it
+//    defines <top-app>, <top-viewer>, the panels, etc. before the DOM renders.
+const { components } = await client.setup<OBC.Components>(
+  { OBC, OBF, BUI, THREE, FRAGS, MARKERJS },
+  { uuid: UIManager.uuid },
+);
+components.get(UIManager).init();
+
+// 2. Build the shell: <top-app> with named element slots + named layouts.
+const app = document.createElement("top-app") as any;
+app.elements = {
+  viewer: () => BUI.html`<top-viewer></top-viewer>`,
+  tree: () => BUI.html`<top-model-tree></top-model-tree>`,
+  // …more panels…
+};
+app.layouts = {
+  Explorer: { icon: "mdi:file-tree", template: `"tree viewer" 1fr / 22rem 1fr` },
+  // …more layouts…
+};
+app.layout = "Explorer";
+app.sidebar = true;
+document.getElementById("that-open-app")?.appendChild(app);
+```
+
+A layout `template` is CSS `grid-template` shorthand: `"areas" rows / columns`, where
+each area name maps to a key in `app.elements`. Each layout with an `icon` becomes a
+sidebar (activity-bar) button.
+
+Built-ins are loaded from the platform at runtime **by uuid** through the `setup`
+call. You import each one as a named export from `@thatopen/services` (a ready
+`{ uuid }` stub with types), never by a deep/internal path.
+
+## Built-in components
+
+The current, authoritative list lives in
+`node_modules/@thatopen/services/docs/builtin/paths.json` (index) with a full example
+per component under `node_modules/@thatopen/services/src/built-in/`. At a high level:
+
+- **`UIManager`** — the shell + viewport + all `top-*` panels above (already wired by
+  the scaffold).
+- **`CDEManager`** — the platform CDE: files, folders, versions, metadata.
+- **`ClashesManager`** + `<top-clashes-panel>` — clash detection and the ready-made
+  clash review UI (detection matrix, run controls, status filters, markers, highlights).
+- **`FileList`** — a simple file list.
+
+Read the matching `example.ts` for each before using it — the examples are the
+source of truth for imports, ordering constraints, and wiring.
+
+### Adding a built-in feature (the general pattern)
+
+Every manager-style built-in follows the same three steps. Example — adding clash
+detection (see `ClashesManager/example.ts` and `UIManager/src/clashes-panel/example.ts`):
+
+```ts
+// 1. Import the built-in as a named export from @thatopen/services.
+import { PlatformClient, UIManager, ClashesManager } from "@thatopen/services";
+
+// 2. Register it by uuid in the SAME setup call as UIManager.
+const { components } = await client.setup<OBC.Components>(
+  { OBC, OBF, BUI, THREE, FRAGS, MARKERJS },
+  { uuid: UIManager.uuid },
+  { uuid: ClashesManager.uuid },
+);
+
+// 3a. Init the manager. Do this BEFORE its panel mounts — the panel reads its
+//     initial data in connectedCallback and only subscribes to changes afterward.
+await components.get(ClashesManager).init(client);
+
+// 3b. Mount the panel web component in a layout slot (UIManager registered it).
+app.elements = {
+  // …existing elements…
+  clashes: () => BUI.html`<top-clashes-panel></top-clashes-panel>`,
+};
+app.layouts = {
+  // …existing layouts…
+  Clashes: { icon: "mdi:vector-intersection", template: `"clashes viewer" 1fr / 22rem 1fr` },
+};
+```
+
+The panel self-wires to its manager — you do not pass props or wire events by hand.
+
+## Loading a BIM model
+
+```ts
+const fragments = components.get(OBC.FragmentsManager);
+
+// From URL
+const buffer = await (await fetch("https://example.com/model.frag")).arrayBuffer();
+await fragments.core.load(buffer, { modelId: "my-model" });
+
+// From platform storage
+const fileBuffer = await (await client.downloadFile(fileId)).arrayBuffer();
+await fragments.core.load(fileBuffer, { modelId: "my-model" });
+```
+
+(The scaffold's `<top-models-list>` panel already loads models the user picks, so you
+usually don't need to do this by hand.)
+
+## PlatformClient API (commonly used in apps)
+
+```ts
+const client = PlatformClient.fromPlatformContext();
+console.log(client.context.projectId);
+
+// Files / folders
+const files = await client.listFiles();
+const response = await client.downloadFile(fileId);
+await client.createFile({ file: blob, name: "model.ifc", versionTag: "v1" });
+await client.createFolder("My Folder");
+
+// Execute cloud components
+const { executionId } = await client.executeComponent(componentId, { param: "value" });
+client.onExecutionProgress(executionId, (data) => {
+  // data.progressUpdate — progress %, data.messageUpdate — status
+});
+
+// Test against a local cloud component (thatopen local-server running in that project)
+client.localServerUrl = "http://localhost:4001";
+```
+
+## Configuration
+
+- `.thatopen` — local config (gitignored). Created by `npm run login`; also holds
+  `beta: true` for beta projects and the `appId` after the first publish.
+- `vite.config.js` — builds the IIFE `dist/bundle.js`; for beta projects it aliases
+  the `@thatopen/*` engine imports to their `@thatopen-platform/*-beta` packages.

package/src/cli/templates/app/package.json

@@ -1,33 +1,33 @@
-{
-  "name": "{{PROJECT_NAME}}",
-  "version": "1.0.0",
-  "private": true,
-  "scripts": {
-    "dev": "thatopen serve",
-    "build": "vite build",
-    "login": "thatopen login --local",
-    "publish": "thatopen publish"
-  },
-  "dependencies": {
-    "@lit/context": "^1.1.6",
-    "lit": "^3.0.0",
-    "@markerjs/markerjs3": "^3.9.0",
-    "@thatopen/components": "~3.4.0",
-    "@thatopen/components-front": "~3.4.0",
-    "@thatopen/fragments": "~3.4.0",
-    "@thatopen/services": "file:../../../..",
-    "@thatopen/ui": "~3.4.4",
-    "three": "0.185.0",
-    "@sparkjsdev/spark": "^0.1.10",
-    "3d-tiles-renderer": "^0.4.28",
-    "camera-controls": "^3.1.2",
-    "opentype.js": "1.3.4",
-    "potree-core": "^2.0.15",
-    "web-ifc": "^0.0.77"
-  },
-  "devDependencies": {
-    "@types/three": "^0.182.0",
-    "typescript": "^5.2.0",
-    "vite": "^5.2.0"
-  }
-}
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "thatopen serve",
+    "build": "vite build",
+    "login": "thatopen login --local",
+    "publish": "thatopen publish"
+  },
+  "dependencies": {
+    "@lit/context": "^1.1.6",
+    "lit": "^3.0.0",
+    "@markerjs/markerjs3": "^3.9.0",
+    "@thatopen/components": "~3.4.0",
+    "@thatopen/components-front": "~3.4.0",
+    "@thatopen/fragments": "~3.4.0",
+    "@thatopen/services": "file:../../../..",
+    "@thatopen/ui": "~3.4.0",
+    "three": "0.185.0",
+    "@sparkjsdev/spark": "^0.1.10",
+    "3d-tiles-renderer": "^0.4.28",
+    "camera-controls": "^3.1.2",
+    "opentype.js": "1.3.4",
+    "potree-core": "^2.0.15",
+    "web-ifc": "^0.0.77"
+  },
+  "devDependencies": {
+    "@types/three": "^0.182.0",
+    "typescript": "^5.2.0",
+    "vite": "^5.2.0"
+  }
+}

package/src/cli/templates/app/src/setups/camera-tools.ts

@@ -1,63 +0,0 @@
-import * as THREE from "three";
-import * as OBC from "@thatopen/components";
-
-/**
- * Camera tools for the viewer toolbar. Returns controllers matching the
- * toolbar's integration contract:
- *  - `fitAll`  — ACTION: fit the camera to the whole loaded model.
- *  - `orthoToggle` — TOGGLE: switch the projection Perspective ⇄ Orthographic.
- */
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const firstWorld = (components: OBC.Components): any =>
-  [...components.get(OBC.Worlds).list.values()][0];
-
-export interface CameraTools {
-  fitAll: { label: string; icon: string; run(): Promise<void> };
-  orthoToggle: {
-    label: string;
-    icon: string;
-    active(): boolean;
-    activate(): Promise<void>;
-    deactivate(): Promise<void>;
-  };
-}
-
-export const cameraTools = (components: OBC.Components): CameraTools => {
-  const fragments = components.get(OBC.FragmentsManager);
-
-  return {
-    fitAll: {
-      label: "Zoom to fit",
-      icon: "mdi:fit-to-page-outline",
-      async run() {
-        const controls = firstWorld(components)?.camera?.controls;
-        if (!controls) return;
-        // Union every loaded model's bounding box, then frame its sphere —
-        // fitToSphere preserves the current view direction (no rotation snap).
-        const box = new THREE.Box3();
-        for (const model of fragments.list.values()) {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          const b = (model as any).box as THREE.Box3 | undefined;
-          if (b && !b.isEmpty()) box.union(b);
-        }
-        if (box.isEmpty()) return;
-        const sphere = box.getBoundingSphere(new THREE.Sphere());
-        await controls.fitToSphere(sphere, true);
-      },
-    },
-    orthoToggle: {
-      label: "Orthographic",
-      icon: "mdi:angle-right",
-      active() {
-        return firstWorld(components)?.camera?.projection?.current === "Orthographic";
-      },
-      async activate() {
-        await firstWorld(components)?.camera?.projection?.set?.("Orthographic");
-      },
-      async deactivate() {
-        await firstWorld(components)?.camera?.projection?.set?.("Perspective");
-      },
-    },
-  };
-};