@thatopen/services 0.0.3 → 0.0.5

package/docs/bim-components/library-examples.md

@@ -1,28 +0,0 @@
-# Library Examples
-
-Before writing any implementation that uses That Open Engine — whether you know the component name or are trying to figure out how to achieve something — check whether an official example covers it. Official examples are the best starting point: they show correct initialization sequences, idiomatic API usage, and working patterns from the source authors.
-
-## How to find an example
-
-1. Fetch the `paths.json` for each repo below (you can do all three in parallel). Do not summarize the response — retain the full JSON in context and use the descriptions to reason about which examples are relevant.
-2. Use the descriptions in the JSON to reason about which examples best match the user's intent. Prefer semantic matching over path name matching — a description may cover what the user needs even if the component name doesn't match exactly.
-3. Only proceed to fetch an example if its description confirms that it directly covers the user's intent, or that it can serve as a building block for composing a new custom component. Do not fetch speculatively.
-4. Construct the full URL: `{base_url}{path_entry}` and fetch the example file to use as your implementation reference.
-
-Path names are descriptive — `VisibilityOperations`, `EditElements`, `SteelDetailing` — so matching by intent works well even when the user hasn't named a specific component.
-
----
-
-## Repositories
-
-### engine_components
-Components from `@thatopen/components` (OBC) and `@thatopen/components-front` (OBF).
-
-- **paths.json**: `https://raw.githubusercontent.com/ThatOpen/engine_components/refs/heads/main/examples/paths.json`
-- **Base URL**: `https://raw.githubusercontent.com/ThatOpen/engine_components/refs/heads/main/`
-
-### engine_fragment
-The `@thatopen/fragments` low-level library. There are no named OBC components here — users typically describe what they want to do (e.g., "edit model properties", "modify elements", "work with visibility").
-
-- **paths.json**: `https://raw.githubusercontent.com/ThatOpen/engine_fragment/refs/heads/main/examples/paths.json`
-- **Base URL**: `https://raw.githubusercontent.com/ThatOpen/engine_fragment/refs/heads/main/`

package/docs/bim-components/observable-collections.md

@@ -1,83 +0,0 @@
-# Observable Collections
-
-`FRAGS.DataMap` and `FRAGS.DataSet` are lifecycle-aware extensions of `Map` and `Set`. The only difference from their native counterparts is that they emit events when items are added or removed, making the collection observable.
-
-Use `DataMap` when there is a clear key to identify each item. Use `DataSet` when the item itself is the identifier. `DataMap` is the default choice in most cases.
-
----
-
-## `FRAGS.DataMap<K, V>`
-
-### Declaration
-
-The primary collection of a component is conventionally named `list`:
-
-```ts
-import * as FRAGS from "@thatopen/fragments"
-
-readonly list = new FRAGS.DataMap<string, SpotElevation>();
-```
-
-### Reactive events
-
-```ts
-this.list.onItemSet.add(({ key, value }) => {
-  // called after an item is added
-});
-
-this.list.onBeforeDelete.add(({ key, value }) => {
-  // called before an item is removed — use to clean up resources
-});
-
-this.list.onItemDeleted.add(({ key }) => {
-  // called after an item is removed
-});
-```
-
-### Get-or-create
-
-When inserting into a `DataMap` where the entry may not exist yet, use a get-or-create pattern:
-
-```ts
-let entry = this.list.get(key);
-if (!entry) {
-  entry = new SpotElevation();
-  this.list.set(key, entry);
-}
-entry.doSomething();
-```
-
-### Guard
-
-A guard runs before every `set()` call and can block the insertion by returning `false`:
-
-```ts
-this.list.guard = (key, value) => {
-  return value.isValid;
-};
-```
-
----
-
-## `FRAGS.DataSet<T>`
-
-Same API as `DataMap` but without keys — the item itself is the identifier:
-
-```ts
-readonly list = new FRAGS.DataSet<SpotElevation>();
-
-this.list.onItemSet.add(({ value }) => { ... });
-this.list.onBeforeDelete.add(({ value }) => { ... });
-```
-
----
-
-## Collections of auxiliary class instances
-
-When a component manages instances of its own auxiliary classes, cleanup typically happens in `onBeforeDelete`:
-
-```ts
-this.list.onBeforeDelete.add(({ value: spotElevation }) => {
-  spotElevation.dispose();
-});
-```

package/docs/bim-components/overview.md

@@ -1,160 +0,0 @@
-# BIM Component Creation
-
-Architecture, patterns, and step-by-step guide for creating BIM components with That Open Engine (OBC/OBF) — the domain-logic layer that wraps fragments, IFC data, measurements, selections, or any non-UI behavior.
-
-## Working mode
-
-Before doing anything else, **read [`./library-examples.md`](./library-examples.md) and fetch the `paths.json` for both `engine_components` and `engine_fragment` in parallel.** Review all descriptions to understand what the engine already provides before forming any opinion about what needs to be built.
-
-Only after that, **propose an implementation plan and wait for the user's approval.**
-
-The proposal must describe:
-- Whether the need is covered by an existing engine component (consume via `components.get()`)
-- Whether existing components can be composed to cover it
-- Only if neither applies: which new component(s) will be created, what properties, events, and public methods it will expose, and whether it needs lifecycle, serialization, render loop, or interactive creation interfaces
-
-Only proceed with changes after the user explicitly confirms the plan. If the scope is unclear, ask first — do not assume.
-
----
-
-## What is a BIM Component?
-
-That Open Engine is the collection of packages that power the app: `@thatopen/components`, `@thatopen/components-front`, `@thatopen/fragments`, `@thatopen/ui`, and `@thatopen/ui-obc`. BIM components are built on top of this ecosystem.
-
-A BIM component is a class that extends `OBC.Component` and encapsulates domain logic — IFC queries, calculations, data management, fragment operations, etc. It exposes that logic through a clean, event-driven interface that UI templates and other components can consume.
-
-### The engine works with Fragments
-
-That Open Engine does not work with IFC STEP files directly. It works with **Fragments** — an open binary format (`.frag`) built for performance: a 2 GB IFC file becomes ~80 MB, loads in seconds at 60fps in the browser.
-
-The runtime representation of a loaded model is a `FragmentsModel`. Its data schema usually mirrors the IFC SCHEMA (local IDs map to IFC express IDs, the spatial structure parallels IFC hierarchy, properties follow IFC attributes and relations), but it is not IFC STEP — it is Fragments. Any component that queries elements, reads properties, or operates on geometry works through the `FragmentsModel` API.
-
-For loading models, querying elements, or reading properties, fetch the relevant example from [`./library-examples.md`](./library-examples.md) before writing any implementation code.
-
-### When to create one
-
-Create a BIM component when custom domain logic is needed.
-
-After reviewing the `paths.json` descriptions fetched in the working mode step:
-
-- If an existing component covers the need → consume it via `this.components.get()` and fetch its example. Do not reimplement.
-- If existing components can be composed to cover it → compose them, fetching the relevant examples as building blocks.
-- Only if the need is genuinely not covered → propose creating a custom component.
-
-Custom components can themselves consume built-in components via `this.components.get()`, so examples remain useful even when building something new.
-
----
-
-## Step 1 — Define the component
-
-Names should be short but descriptive. Use PascalCase for both folder and class, matching exactly:
-
-| Artifact | Convention | Example |
-|---|---|---|
-| Folder | PascalCase | `ActivityTracker/` |
-| Class | PascalCase | `ActivityTracker` |
-| Types prefix | PascalCase matching class | `ActivityTrackerConfig`, `ActivityTrackerResult` |
-
-Use the `Manager` suffix when the component creates instances of something or governs a broad concern — consistent with `FragmentsManager`, `Classifier`, etc. For focused, single-responsibility components, omit it.
-
----
-
-## Step 2 — Create the file structure
-
-```
-ActivityTracker/
-  index.ts        → class definition + re-exports ./src
-  src/
-    index.ts      → re-exports types and support files
-    types.ts      → interfaces, type aliases, enums
-    SpotElevation.ts → auxiliary class (if needed)
-```
-
-Only one class per component extends `OBC.Component` — the main one in `index.ts`. Any other classes the component defines or instantiates are plain TypeScript classes that live in `src/` alongside `types.ts`, and never extend `OBC.Component`.
-
----
-
-## Step 3 — Implement the class in `index.ts`
-
-### Skeleton
-
-Every component needs a unique, hardcoded static UUID — a fixed string literal defined once and never changed. The constructor must call `super(components)` and register the instance with `components.add(UUID, this)` so it becomes globally retrievable via `components.get(ActivityTracker)`.
-
-Before writing the implementation, read [`./coding-conventions.md`](./coding-conventions.md) for naming rules, backing fields, and async patterns that apply throughout the class.
-
-```ts
-import * as OBC from "@thatopen/components"
-
-export class ActivityTracker extends OBC.Component {
-  static readonly uuid = "1b43361b-ef43-4207-9c40-dbed37bec0b6" as const;
-
-  enabled = true;
-
-  constructor(components: OBC.Components) {
-    super(components);
-    components.add(ActivityTracker.uuid, this);
-  }
-}
-
-export * from "./src"
-```
-
-### Interfaces
-
-OBC defines capability interfaces that components can implement to stay consistent with each other and with the engine. Pick the resource that matches your need:
-
-| I need... | Resource |
-|---|---|
-| Initialize the component with config, or clean up resources when it's destroyed | [`./setup-and-cleanup.md`](./setup-and-cleanup.md) |
-| Save and restore state across sessions | [`./save-and-restore-state.md`](./save-and-restore-state.md) |
-| Run logic on every frame of the render loop | [`./per-frame-updates.md`](./per-frame-updates.md) |
-| Implement a flow where the user creates objects in the scene step by step | [`./user-driven-object-creation.md`](./user-driven-object-creation.md) |
-| Expose events or react to state changes | [`./expose-events.md`](./expose-events.md) |
-
-### Accessing other components
-
-Resolve dependencies at call time — never store component instances as fields as it may create memory leaks:
-
-```ts
-const fragments = this.components.get(OBC.FragmentsManager);
-const highlighter = this.components.get(OBF.Highlighter);
-```
-
----
-
-## Step 4 — Define types in `src/types.ts`
-
-Types are defined in parallel as the class needs them, not upfront. All typing for the component lives here — domain interfaces, event payloads, serialized types — so there is a single place to look.
-
-See [`./type-conventions.md`](./type-conventions.md) for common patterns (runtime vs serialized types, generics, etc.).
-
----
-
-## Step 5 — Export from the barrel
-
-Re-export the component from the project's barrel index so it's accessible from a single import point:
-
-```ts
-export * from "./ActivityTracker"
-```
-
----
-
-## Wiring up
-
-Instantiating the component and connecting it to engine events is not the component's responsibility — that belongs in external initialization code. The constructor should never call other components. See [`../app-wiring.md`](../app-wiring.md) for how this is done.
-
----
-
-## See also
-
-- [`./library-examples.md`](./library-examples.md) — Find official usage examples and discover what the engine provides
-- [`./element-collections.md`](./element-collections.md) — Represent or combine element collections across components
-- [`./observable-collections.md`](./observable-collections.md) — Store component-internal data with reactive notifications
-- [`./expose-events.md`](./expose-events.md) — Expose events for other components or the UI to react to
-- [`./setup-and-cleanup.md`](./setup-and-cleanup.md) — Initialize the component with config or clean up resources on destroy
-- [`./save-and-restore-state.md`](./save-and-restore-state.md) — Persist and restore state across sessions
-- [`./per-frame-updates.md`](./per-frame-updates.md) — Run logic on every frame of the render loop
-- [`./user-driven-object-creation.md`](./user-driven-object-creation.md) — Let the user create objects in the scene step by step
-- [`./type-conventions.md`](./type-conventions.md) — Define component types (runtime vs serialized, generics)
-- [`./coding-conventions.md`](./coding-conventions.md) — Code conventions (naming, backing fields, async)

package/docs/bim-components/per-frame-updates.md

@@ -1,20 +0,0 @@
-# Per-Frame Updates
-
-## `OBC.Updateable`
-
-Implement when the component needs to execute logic on every frame — animating objects, polling state, updating visual feedback.
-
-```ts
-export class ActivityTracker extends OBC.Component implements OBC.Updateable {
-  readonly onBeforeUpdate = new OBC.Event<undefined>();
-  readonly onAfterUpdate = new OBC.Event<undefined>();
-
-  update(delta?: number) {
-    this.onBeforeUpdate.trigger(undefined);
-    // per-frame logic
-    this.onAfterUpdate.trigger(undefined);
-  }
-}
-```
-
-The component is driven externally — a world or a setup file calls `update()` each frame. The component never drives itself.

package/docs/bim-components/save-and-restore-state.md

@@ -1,21 +0,0 @@
-# Save and Restore State
-
-## `OBC.Serializable<D, S>`
-
-Implement when the component must persist its state — to a file, to the cloud, or across sessions.
-
-`D` is the runtime type, `S` is the serialized (JSON-safe) equivalent. Both are defined in `src/types.ts`. See [`./type-conventions.md`](./type-conventions.md) for the serialization patterns, including the `localId` → GUID conversion that must happen before storing any item references.
-
-```ts
-export class ActivityTracker extends OBC.Component
-  implements OBC.Serializable<ActivityTrackerData, SerializedActivityTrackerData> {
-
-  export(): SerializedActivityTrackerData {
-    // convert runtime state to JSON-safe structure
-  }
-
-  import(data: SerializedActivityTrackerData) {
-    // restore runtime state from serialized structure
-  }
-}
-```

package/docs/bim-components/setup-and-cleanup.md

@@ -1,64 +0,0 @@
-# Setup and Cleanup
-
-Two interfaces govern a component's lifecycle: `OBC.Configurable` for one-time initialization before use, and `OBC.Disposable` for cleanup when the component is destroyed.
-
----
-
-## `OBC.Configurable<TManager, TConfig>`
-
-Implement when the component requires one-time initialization. This separates construction (cheap, no side effects) from setup (resolves dependencies, applies config, registers event listeners).
-
-```ts
-export interface ActivityTrackerConfig {
-  color: THREE.Color;
-  autoColorize: boolean;
-}
-
-export class ActivityTracker extends OBC.Component
-  implements OBC.Configurable<ActivityTrackerConfigManager, ActivityTrackerConfig> {
-
-  isSetup = false;
-  readonly onSetup = new OBC.Event<undefined>();
-
-  protected _defaultConfig: ActivityTrackerConfig = {
-    color: new THREE.Color("#6528d7"),
-    autoColorize: false,
-  };
-
-  setup(config?: Partial<ActivityTrackerConfig>) {
-    if (this.isSetup) return;
-    const fullConfig = { ...this._defaultConfig, ...config };
-    // apply config, resolve dependencies...
-    this.isSetup = true;
-    this.onSetup.trigger(undefined);
-  }
-}
-```
-
-The `if (this.isSetup) return` guard ensures setup only runs once. The constructor must never call other components — that belongs in `setup()`.
-
----
-
-## `OBC.Disposable`
-
-Implement when the component holds resources that must be explicitly released — Three.js geometries and materials, event subscriptions to external components, workers.
-
-```ts
-export class ActivityTracker extends OBC.Component implements OBC.Disposable {
-  readonly onDisposed = new OBC.Event<undefined>();
-
-  dispose() {
-    // 1. Release Three.js resources
-    this._mesh?.geometry.dispose();
-    this._material.dispose();
-
-    // 2. Reset all events (if OBC.Eventable is also implemented)
-    this.events.reset();
-
-    // 3. Signal disposal — always last
-    this.onDisposed.trigger(undefined);
-  }
-}
-```
-
-`onDisposed` must be triggered at the end of `dispose()`, after all cleanup is done.

package/docs/bim-components/type-conventions.md

@@ -1,49 +0,0 @@
-# Type Conventions
-
-All types for a component live in `src/types.ts` — domain interfaces, event payloads, serialized equivalents — so there is a single place to look.
-
----
-
-## Runtime vs serialized
-
-Components that implement `OBC.Serializable` need two versions of their data types: a runtime version that uses rich TypeScript types, and a serialized version that is JSON-safe.
-
-The serialized type is named `Serialized{TypeName}`:
-
-```ts
-// Runtime — uses Map, Set, Date, THREE.Color
-export interface Activity {
-  index: number;
-  name: string;
-  color: THREE.Color;
-  items: OBC.ModelIdMap;
-  dates: Set<string>;
-}
-
-// Serialized — JSON-safe equivalent
-export interface SerializedActivity {
-  index: number;
-  name: string;
-  color: string;             // THREE.Color → hex string
-  items: [string, number[]][]; // ModelIdMap → tuple array
-  dates: string[];           // Set → array
-}
-```
-
-Conversion happens inside `export()` and `import()` (see [`./save-and-restore-state.md`](./save-and-restore-state.md)).
-
----
-
-## Generics that require `type`, not `interface`
-
-Some OBC and FRAGS generics enforce that their type parameter is a `type` alias. Passing an `interface` causes a TypeScript error. When in doubt, prefer `type` for types used as generic parameters:
-
-```ts
-// ✗ Fails — interface not assignable to the generic constraint
-export interface ActivityData { name: string; value: number }
-const list = new FRAGS.DataMap<string, ActivityData>(); // error
-
-// ✓ Correct
-export type ActivityData = { name: string; value: number }
-const list = new FRAGS.DataMap<string, ActivityData>();
-```

package/docs/bim-components/user-driven-object-creation.md

@@ -1,56 +0,0 @@
-# User-Driven Object Creation
-
-## `OBC.Createable`
-
-Implement when the component lets the user create objects in the scene through a multi-step interaction — click to start, click to confirm, Escape to cancel, click existing to delete.
-
-The key characteristic is **statefulness between clicks**: `create()` is called on every user click, but the first click initiates the workflow and the second confirms it by calling `endCreation()` internally.
-
-```ts
-export class ActivityTracker extends OBC.Component implements OBC.Createable {
-  private _temp: { isDragging: boolean; preview?: SomeObject } = {
-    isDragging: false,
-  };
-
-  create = () => {
-    if (!this.enabled) return;
-    if (!this._temp.isDragging) {
-      this._temp.isDragging = true;
-      this._temp.preview = new SomeObject();
-      return;
-    }
-    this.endCreation();
-  };
-
-  endCreation = () => {
-    if (!this._temp.preview) return;
-    this.list.add(this._temp.preview);
-    this._temp.isDragging = false;
-    this._temp.preview = undefined;
-  };
-
-  cancelCreation = () => {
-    this._temp.isDragging = false;
-    this._temp.preview?.dispose();
-    this._temp.preview = undefined;
-  };
-
-  delete = () => {
-    if (!this.world) return;
-    const casters = this.components.get(OBC.Raycasters);
-    const caster = casters.get(this.world);
-    const intersect = caster.castRayToObjects([...this._boundingBoxes]);
-    if (!intersect) return;
-    // identify and remove the hit object from list
-  };
-}
-```
-
-Wire up the Escape key in the component's `enabled` setter so `cancelCreation()` fires automatically when the component is disabled mid-flow:
-
-```ts
-set enabled(value: boolean) {
-  this._enabled = value;
-  if (!value) this.cancelCreation();
-}
-```

package/docs/cli-setup.md

@@ -1,54 +0,0 @@
-# CLI Setup and Authentication
-
-Before you can scaffold or publish a That Open Platform app, two things must be in place: the `@thatopen/services` CLI installed globally, and a valid platform token for authentication.
-
----
-
-## Step 1: Install or update the CLI
-
-Run the following command in the terminal. This installs the CLI if it isn't present, or updates it to the latest version if it already is:
-
-```bash
-npm i @thatopen/services@latest -g
-```
-
-Once done, verify it works:
-
-```bash
-thatopen --version
-```
-
-If this returns a version number, the CLI is ready. If `npm` is not found, install Node.js first — download the LTS version from [https://nodejs.org](https://nodejs.org), then retry.
-
----
-
-## Step 2: Get a platform token
-
-Generate an access token from the platform:
-
-1. Go to [https://dev.platform.thatopen.com](https://dev.platform.thatopen.com)
-2. In the header, click **Data**
-3. Find the **Tokens** card and create a new token
-4. Enable the permissions: **Apps**, **Components** and **Storage**
-5. Copy the token
-
----
-
-## Step 3: Authenticate
-
-Once you have the token, run:
-
-```bash
-npm run login -- --token <TOKEN>
-```
-
-where `<TOKEN>` is the token you copied. This stores credentials globally at `~/.thatopen/config.json` and persists across sessions — you only need to do this once per machine.
-
----
-
-## When to use this guide
-
-Read this guide when:
-- You are starting a new app and haven't confirmed the CLI is installed
-- A `thatopen` command fails with a "command not found" or "not authenticated" error
-- You have never built a platform app before on this machine

package/docs/cloud-components.md

@@ -1,74 +0,0 @@
-# Cloud components & automations
-
-A **cloud component** is a piece of logic that runs **server-side** (Node.js) on the platform,
-on the shared project context, via the API. Use them to automate real operations — clash checks,
-validations, document generation — and to let apps offload heavy work.
-
-## Apps vs cloud components
-
-|  | Apps | Cloud components |
-|---|---|---|
-| **Runs in** | Browser (iframe on the platform) | Server (Node.js child process) |
-| **Item type** | `APP` | `TOOL` |
-| **Entry point** | Side effects in `main.ts` (renders UI) | `export async function main()` |
-| **Build output** | IIFE `dist/bundle.js` (all deps bundled) | IIFE `dist/bundle.js` (only `@thatopen/services` externalized) |
-| **Template** | `bim`, `default`, `test` | `cloud`, `cloud-test` |
-
-## Scaffold
-
-```bash
-thatopen create my-component --template cloud
-cd my-component
-```
-
-The component is an `export async function main()` that runs on the server. The execution engine
-injects these globals (do **not** import them; for `OBC`/`THREE`/`web-ifc` import them so the
-bundler includes them):
-
-| Global | Purpose |
-|--------|---------|
-| `thatOpenServices` | Authenticated `EngineServicesClient` |
-| `executionParams` | Parameters passed by the caller |
-| `executionContext` | `{ projectId?, executionId, toolId, toolVersion }` |
-| `executionReporter` | `{ message(msg), error(msg), progress(pct) }` for live feedback |
-| `OBC` | `@thatopen/components` — BIM engine (import it) |
-| `THREE` | `three` — 3D math/geometry (import it) |
-| `fs` | Node.js filesystem (import it) |
-
-## Run locally
-
-```bash
-npm run run                                 # build + test locally
-npx thatopen run --params '{"inputFile":"model.ifc"}'   # pass parameters
-```
-
-`thatopen local-server` starts an API-compatible local execution server (default `:4001`) so an
-app can call the component before it's deployed (set `client.localServerUrl`).
-
-## Authenticate & publish
-
-```bash
-npm run login -- --token <your-token>
-npm run publish
-```
-
-## Calling a component from an app
-
-```ts
-const { executionId } = await client.executeComponent(componentId, { param: "value" }, versionTag?);
-client.onExecutionProgress(executionId, (data) => {
-  // data.progressUpdate — percentage
-  // data.messageUpdate — status messages
-});
-```
-
-Include `projectId` in the execution params to scope the run to a project (the backend validates
-the component is linked to that project). See [CONTEXT.md](../CONTEXT.md) for the permissions contract.
-
-## Automations (event-triggered components)
-
-An **automation** is a cloud component that runs automatically in response to a platform **event**
-(rather than being invoked by hand) — e.g. "run the clash check whenever a model is updated."
-The component is the same; what differs is the trigger. Add it to a project, choose the event(s)
-that fire it, and the platform executes it on the shared project context, reporting progress and
-logs through `executionReporter`. Build and publish it exactly like any other cloud component above.