@thatopen/services 0.0.2 → 0.0.4

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

@@ -1,64 +1,64 @@
-# 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.
+# 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 +1,49 @@
-# 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>();
-```
+# 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 +1,56 @@
-# 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();
-}
-```
+# 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 +1,54 @@
-# 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
+# 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 +1,74 @@
-# 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.
+# 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.