@thatopen/services 0.0.1 → 0.0.3

package/docs/ui-components/sections-layout.md

@@ -0,0 +1,123 @@
+# Panel Section Layout
+
+## Composition mental model
+
+A panel section has zones that follow a natural sequence reflecting how the user processes the panel: first they act on the context (controls), then understand the current state (messages), then operate on the selected item (toolbar), then see the data (main content), and finally execute high-impact actions (bottom).
+
+```
+<bim-panel-section label="..." icon="..." fixed?>
+  [controls bar]      ← search or selector + action buttons
+  [status messages]   ← conditional bim-labels (warn, success, info)
+  [actions toolbar]   ← bim-toolbar when there are many actions on the active item
+  [main content]      ← table, list, or sub-component
+  [primary actions]   ← 1-2 high-impact buttons at the bottom
+</bim-panel-section>
+```
+
+Not all zones are always present. This sequence is a guide, not a mandatory template — if the panel's content breaks that flow in a way that improves the experience, propose the layout that makes the most sense and explain the reasoning.
+
+### Forbidden nesting
+
+Inside a `<bim-panel-section>` it is **never** valid to place:
+
+- Another `<bim-panel-section>`
+- A `<bim-panel>`
+
+This mistake is most tempting when the user asks to "group" sections. The correct answer is **not** nesting — it is creating independent templates. A template does not decide how it is grouped with others; that is the consumer's responsibility. If the content truly belongs in one section, use the existing internal zones (`controls bar`, `toolbar`, `main content`). If it needs to be split into multiple sections, each section is its own independent template.
+
+---
+
+## Controls bar
+
+Always a `<div style="display: flex; gap: 0.5rem;">`. There are two main variants:
+
+**Search** — when the user filters over a list or table:
+```ts
+return BUI.html`
+  <bim-panel-section label="Elements">
+    <div style="display: flex; gap: 0.5rem;">
+      <bim-text-input @input=${onSearch} vertical placeholder="Search..."></bim-text-input>
+      <bim-button icon=${icons.ADD} @click=${onCreate}></bim-button>
+    </div>
+    ${table}
+  </bim-panel-section>
+`
+```
+
+**Selector** — when the user picks the active item from a dropdown. The gap is tighter (`0.25rem`) because the dropdown already takes most of the width:
+```ts
+return BUI.html`
+  <bim-panel-section label="Proposals">
+    <div style="display: flex; gap: 0.25rem;">
+      ${proposalsDropdown}
+      <bim-button icon=${icons.ADD} @click=${onCreate}></bim-button>
+    </div>
+    ${content}
+  </bim-panel-section>
+`
+```
+
+Action buttons in the controls bar are always icon-only (`icon=` without `label=`). The search `<bim-text-input>` always has `vertical` and `debounce="200"`.
+
+---
+
+## Status messages
+
+Conditional `<bim-label>` elements that appear between the controls and the content to communicate the state of the active item — warnings, confirmations, relevant info. Built as optional variables:
+
+```ts
+let statusMessage: BUI.TemplateResult | undefined
+if (item?.status === "sent") {
+  statusMessage = BUI.html`<bim-label>This item has been sent and can't be modified.</bim-label>`
+}
+
+return BUI.html`
+  <bim-panel-section label="...">
+    ${controls}
+    ${statusMessage}
+    ${content}
+  </bim-panel-section>
+`
+```
+
+---
+
+## Actions toolbar
+
+When there are many actions on the active item (more than 3-4 buttons), use `<bim-toolbar>` with `<bim-toolbar-section>` instead of a plain flex div. The toolbar goes after the status messages and before the main content:
+
+```ts
+const toolbar = BUI.html`
+  <bim-toolbar style="border: 1px solid var(--bim-ui_bg-contrast-20);">
+    <bim-toolbar-section>
+      ${addItemBtn}
+      <bim-button style="flex: 0" icon=${icons.SELECT} @click=${onSelect}></bim-button>
+      <bim-button style="flex: 0" icon=${icons.DELETE} @click=${onDelete}></bim-button>
+    </bim-toolbar-section>
+  </bim-toolbar>
+`
+```
+
+Buttons inside the toolbar always have `style="flex: 0"` to prevent them from stretching.
+
+---
+
+## Conditional content
+
+When the panel content changes completely based on state (e.g. "select something first" vs. showing data), assign to a variable before the `return`:
+
+```ts
+let content: BUI.TemplateResult
+if (hasSelection) {
+  content = BUI.html`<bim-table ...></bim-table>`
+} else {
+  content = BUI.html`<bim-label>Select an element to see its data.</bim-label>`
+}
+
+return BUI.html`
+  <bim-panel-section label="...">
+    ${controls}
+    ${content}
+  </bim-panel-section>
+`
+```

package/docs/update-grid-elements.md

@@ -0,0 +1,46 @@
+# Update Grid Elements
+
+## When to use
+
+`app.grid.updateComponent` pushes a state update to a specific named grid element. Use it when a BIM component event needs to refresh the state of a template-based section mounted in the grid.
+
+This is different from `uis.custom.get(...).updateInstances()` — that re-renders all instances of a UIManager template regardless of where they're mounted. `updateComponent` targets a **specific grid slot by name**, which makes it the right choice when the element lives in the grid and you want precise, typed control over what state it receives.
+
+---
+
+## API
+
+```ts
+app.grid.updateComponent[componentName](updatedState)
+```
+
+- **`componentName`** — the element name as declared in the `App` type (e.g. `"qtosSection"`)
+- **`updatedState`** — partial state; only the provided fields are merged
+
+The call is fully typed: the accepted state shape is inferred from the `{ComponentName}GridElement` type in `app.ts`.
+
+---
+
+## Where to call it
+
+In a setup file (`setups/{custom}.ts`), in response to a BIM component event:
+
+```ts
+// setups/qto-manager.ts
+export const qtoManager = (components: OBC.Components) => {
+  const app = getAppManager(components)
+  const qtoManager = components.get(QtoManager)
+
+  qtoManager.onResultsChanged.add((results) => {
+    app.grid.updateComponent["qtosSection"]({ results })
+  })
+}
+```
+
+Never call `updateComponent` from inside a template function — templates receive state passively and should not trigger updates themselves.
+
+---
+
+## Type safety
+
+Because `app.grid` is typed via the `App` type in `app.ts`, TypeScript knows which names are valid and what state shape each one accepts. Passing an unknown name or a mismatched state shape produces a type error at the call site.

package/docs/using-colors.md

@@ -0,0 +1,32 @@
+# Using Colors
+
+## `globals.ts` shape
+
+```ts
+export const colors = {
+  GREEN: "#00FF00",
+  SOFT_BLUE: "#5B8CFF",
+}
+```
+
+**Colors are always stored as full hex codes, including the `#`.** This is required because some systems (like the highlighter) use the string itself as a style identifier in addition to a color value.
+
+## Rules
+
+- No hardcoded inline colors — not in the highlighter, not in palettes, not in any component. Always imported from `globals.ts`.
+- Before adding a new color, check whether an existing one already works.
+
+## Example: highlighter
+
+```ts
+const highlighter = components.get(OBF.Highlighter)
+if (!highlighter.styles.has(colors.GREEN)) {
+  highlighter.styles.set(colors.GREEN, {
+    color: new THREE.Color(colors.GREEN),
+    renderedFaces: 1,
+    opacity: 1,
+    transparent: false,
+  })
+}
+highlighter.highlightByID(colors.GREEN, modelIdMap)
+```

package/docs/using-icons.md

@@ -0,0 +1,37 @@
+# Using Icons
+
+## Icon registry rules
+
+**All icons in a platform app must be declared in `globals.ts` and accessed through `AppManager`.** This is not optional.
+
+The flow is always:
+1. Declare the icon in `globals.ts` with a `UPPER_SNAKE_CASE` key
+2. `app.ts` — the `App` type's `icons` field is typed as `(keyof typeof icons)[]`, which means any new key added to the registry is automatically reflected in the type — no manual update needed per icon, but this field must be present in the `App` type
+3. Pass the registry to `app.init()` as `icons: appIcons`
+4. Access icons elsewhere via `app.icons.KEY_NAME` (always through `getAppManager(components)`)
+
+```ts
+// ✗ Forbidden — inline icon string anywhere in the app
+<bim-button icon="ic:round-warning"></bim-button>
+grid.layouts = { Viewer: { icon: "ic:round-warning", template: `...` } }
+
+// ✓ Correct — always via the registry
+const app = getAppManager(components)
+<bim-button icon=${app.icons.WARNING}></bim-button>
+grid.layouts = { Viewer: { icon: app.icons.WARNING, template: `...` } }
+```
+
+## Before adding a new icon
+
+Before declaring a new icon in `globals.ts`, check if an existing one in the registry already serves the purpose. Reuse an existing icon when it communicates the same intent — avoid registry bloat.
+
+If no existing icon fits, add it to `globals.ts` first — then use it through `app.icons`.
+
+## `globals.ts` shape
+
+```ts
+export const icons = {
+  WARNING: "ic:round-warning",
+  COLLISION: "fa7-solid:explosion",
+}
+```

package/package.json

@@ -15,7 +15,7 @@
     "access": "public"
   },
   "private": false,
-  "version": "0.0.1",
+  "version": "0.0.3",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/index.d.ts",
@@ -26,6 +26,8 @@
     "dist",
     "src/cli/templates",
     "src/built-in",
+    "docs",
+    "AGENTS.md",
     "CONTEXT.md"
   ],
   "scripts": {
@@ -35,7 +37,7 @@
     "build:lib": "tsc && vite build",
     "test": "vitest run",
     "test:watch": "vitest",
-    "build:cli": "vite build --config vite.config.cli.mts && node scripts/copy-templates.mjs",
+    "build:cli": "vite build --config vite.config.cli.mts",
     "preview": "vite preview",
     "test:ui": "vite --config test/vite.config.mts",
     "test:cli-build-app": "npm run build:cli && node test/setup-test-app.mjs",

package/src/cli/templates/bim/CONTEXT.md

@@ -44,9 +44,8 @@ Always use `npm run dev` which runs `thatopen serve` under the hood.
 | `@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.) |
-| `@thatopen/ui-obc` | `CUI` | Pre-built OBC UI tables (used by ModelsPanel) |
 | `three` | `THREE` | 3D rendering engine |
-| `thatopen-services` | `EngineServicesClient` | Platform API client + built-in components |
+| `@thatopen/services` | `EngineServicesClient` | Platform API client + built-in components |
 
 ## Architecture pattern
 
@@ -85,7 +84,7 @@ They are fetched, evaluated, and registered with the OBC component system.
 | **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
+`@thatopen/services` package source (`src/built-in/index.ts`). Read that file for config
 interfaces, method signatures, and code examples.
 
 ### Loading pattern
@@ -93,13 +92,13 @@ interfaces, method signatures, and code examples.
 Use `setup` to create the component system and load built-in components in one call:
 
 ```ts
-import { PlatformClient, AppManager, ViewportsManager } from "thatopen-services";
+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, CUI, THREE, FRAGS },
+  { OBC, OBF, BUI, THREE, FRAGS },
   AppManager, ViewportsManager,
 );
 
@@ -125,7 +124,6 @@ await client.initBuiltInComponent(AppManager, components);
 | ViewportsManager | `{ OBC, BUI, THREE, FRAGS }` | — |
 | LoadModelButton | `{ OBC, BUI }` | — |
 | ModelsDropdown | `{ OBC, BUI }` | — |
-| ModelsPanel | `{ OBC, BUI, CUI }` | `@thatopen/ui-obc` |
 | ViewerToolbar | `{ OBC, OBF, BUI, THREE }` | `@thatopen/components-front` |
 | ColorsPalette | `{ OBC, OBF, BUI }` | `@thatopen/components-front` |
 | ClashesList | `{ OBC, OBF, BUI, THREE }` | `@thatopen/components-front` |
@@ -145,7 +143,6 @@ await client.initBuiltInComponent(AppManager, components);
 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 CUI from "@thatopen/ui-obc";              // needed for ModelsPanel
 import * as THREE from "three";
 import * as FRAGS from "@thatopen/fragments";
 import * as MARKERJS from "@markerjs/markerjs3";      // needed for ScreenshotAnnotator

package/src/cli/templates/bim/package.json

@@ -14,8 +14,7 @@
     "@thatopen/components-front": "~3.4.0",
     "@thatopen/fragments": "~3.4.0",
     "@thatopen/ui": "~3.4.0",
-    "@thatopen/ui-obc": "~3.4.0",
-    "thatopen-services": "file:../../../..",
+    "@thatopen/services": "file:../../../..",
     "three": "^0.182.0"
   },
   "devDependencies": {

package/src/cli/templates/bim/src/app.ts

@@ -1,6 +1,6 @@
 import * as OBC from "@thatopen/components";
 import * as BUI from "@thatopen/ui";
-import { AppManager } from "thatopen-services";
+import { AppManager } from "@thatopen/services";
 import { icons } from "./globals";
 import { AppInfoSectionGridElement, CloudRunnerSectionGridElement } from "./ui-components";
 

package/src/cli/templates/bim/src/bim-components/CloudRunner/index.ts

@@ -1,5 +1,5 @@
 import * as OBC from "@thatopen/components";
-import { AppManager } from "thatopen-services";
+import { AppManager } from "@thatopen/services";
 import { CloudRunnerStatus } from "./src";
 
 export class CloudRunner extends OBC.Component {

package/src/cli/templates/bim/src/main.ts

@@ -3,14 +3,13 @@ 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 CUI from "@thatopen/ui-obc";
 import * as MARKERJS from "@markerjs/markerjs3"
 import {
   PlatformClient,
   AppManager,
   ViewportsManager,
   UIManager,
-} from "thatopen-services";
+} from "@thatopen/services";
 
 import { getAppManager } from "./app";
 import { uiManager, cloudRunner, viewportsManager, getUIManager } from "./setups";
@@ -26,7 +25,7 @@ async function main() {
   // First argument: library globals used by the engine.
   // Subsequent arguments: platform built-in components to initialise.
   const { components } = await client.setup<OBC.Components>(
-    { OBC, OBF, BUI, CUI, THREE, FRAGS, MARKERJS },
+    { OBC, OBF, BUI, THREE, FRAGS, MARKERJS },
     { uuid: ViewportsManager.uuid },
     { uuid: AppManager.uuid },
     { uuid: UIManager.uuid },

package/src/cli/templates/bim/src/setups/ui-manager.ts

@@ -1,6 +1,6 @@
 import * as OBC from "@thatopen/components";
 import * as BUI from "@thatopen/ui";
-import { UIManager } from "thatopen-services";
+import { UIManager } from "@thatopen/services";
 import {
   appInfoSectionTemplate,
   AppInfoSectionState,

package/src/cli/templates/bim/src/setups/viewports-manager.ts

@@ -1,5 +1,5 @@
 import * as OBC from "@thatopen/components";
-import { ViewportsManager } from "thatopen-services";
+import { ViewportsManager } from "@thatopen/services";
 
 export const viewportsManager = async (components: OBC.Components) => {
   const viewports = components.get(ViewportsManager);

package/src/cli/templates/bim-beta/CONTEXT.md

@@ -0,0 +1,241 @@
+# 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-platform/components-beta` | `OBC` | BIM engine — components, fragments, worlds |
+| `@thatopen-platform/components-front-beta` | `OBF` | Front-end BIM components (Highlighter, measurements, etc.) |
+| `@thatopen-platform/fragments-beta` | `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-platform/components-front-beta` |
+| ColorsPalette | `{ OBC, OBF, BUI }` | `@thatopen-platform/components-front-beta` |
+| ClashesList | `{ OBC, OBF, BUI, THREE }` | `@thatopen-platform/components-front-beta` |
+| ClassificationsList | `{ OBC, OBF, BUI }` | `@thatopen-platform/components-front-beta` |
+| ClippingsList | `{ OBC, BUI }` | — |
+| HighlightersList | `{ OBC, OBF, BUI }` | `@thatopen-platform/components-front-beta` |
+| LengthMeasuringsList | `{ OBC, OBF, BUI, THREE }` | `@thatopen-platform/components-front-beta` |
+| AreaMeasuringsList | `{ OBC, OBF, BUI, THREE }` | `@thatopen-platform/components-front-beta` |
+| QtoComparisonList | `{ OBC, OBF, BUI }` | `@thatopen-platform/components-front-beta` |
+| QueriesHierarchy | `{ OBC, OBF, BUI }` | `@thatopen-platform/components-front-beta` |
+| CustomViewLegend | `{ OBC, BUI }` | — |
+| ScreenshotAnnotator | `{ OBC, BUI, MARKERJS }` | `@markerjs/markerjs3` |
+
+### Global abbreviations
+
+```ts
+import * as OBC from "@thatopen-platform/components-beta";
+import * as OBF from "@thatopen-platform/components-front-beta";   // needed for Toolbar, Highlighters, Clashes, etc.
+import * as BUI from "@thatopen/ui";
+import * as THREE from "three";
+import * as FRAGS from "@thatopen-platform/fragments-beta";
+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.

package/src/cli/templates/bim-beta/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "thatopen serve",
+    "build": "vite build",
+    "login": "thatopen login --local",
+    "publish": "thatopen publish"
+  },
+  "dependencies": {
+    "@markerjs/markerjs3": "^3.9.0",
+    "@thatopen-platform/components-beta": "latest",
+    "@thatopen-platform/components-front-beta": "latest",
+    "@thatopen-platform/fragments-beta": "latest",
+    "@thatopen/ui": "~3.4.0",
+    "@thatopen/services": "file:../../../..",
+    "three": "^0.182.0"
+  },
+  "devDependencies": {
+    "@types/three": "^0.182.0",
+    "typescript": "^5.2.0",
+    "vite": "^5.2.0"
+  }
+}

package/src/cli/templates/bim-beta/src/app.ts

@@ -0,0 +1,16 @@
+import * as OBC from "@thatopen-platform/components-beta";
+import * as BUI from "@thatopen/ui";
+import { AppManager } from "@thatopen/services";
+import { icons } from "./globals";
+import { AppInfoSectionGridElement, CloudRunnerSectionGridElement } from "./ui-components";
+
+export type App = {
+  icons: (keyof typeof icons)[];
+  grid: BUI.Grid<
+    ["Viewer", "Split"],
+    ["viewer", AppInfoSectionGridElement, CloudRunnerSectionGridElement]
+  >;
+};
+
+export const getAppManager = (components: OBC.Components) =>
+  components.get(AppManager<App>);