@thatopen/services 0.5.0 → 0.7.0

package/docs/ai-quickstart.md

@@ -9,6 +9,28 @@ on the [That Open Platform](https://platform.thatopen.com) from scratch, using
 
 ---
 
+> **Not building anything — here to work in Revit?** If what the user actually wants is to share a
+> Revit model with their team, join one a colleague uploaded, or review a change some other tool
+> proposed to their model, this is the wrong guide and nothing below applies. Go to
+> **[the Revit collaboration quickstart](https://raw.githubusercontent.com/ThatOpen/platform_services/main/docs/revit-collab-quickstart.md)** and follow that instead.
+> It is the same shape as this one: ask first, then drive the CLI.
+>
+> Phrases that mean that guide, not this one: *"I want to collaborate on a Revit project"*, *"share
+> my central"*, *"join my team's model"*, *"someone sent me a change to approve"*, *"work on the
+> same model as my colleague"*.
+
+> **Making another application talk to this one?** If the user wants their own tool — Rhino, Blender,
+> a script, an in-house app — to send changes into somebody's model or to show a model it did not
+> author, that is a third thing again: **[Writing a flow plugin](https://raw.githubusercontent.com/ThatOpen/platform_services/main/docs/flow-plugin-guide.md)** is the
+> byte contract, and **[the architecture notes](https://raw.githubusercontent.com/ThatOpen/platform_services/main/docs/flow-architecture.md)** say why it is shaped that
+> way. Start at its section 0, which sorts the work into three sizes; most integrations are the
+> smallest one and need no ownership, no history and no collaboration layer.
+>
+> Phrases that mean those: *"export my model to the platform"*, *"send my geometry to Revit"*,
+> *"write a plugin for X"*, *"read a .frag in my app"*.
+
+---
+
 ## First — what are you building? (ask if the user hasn't said)
 
 There are two kinds of project. **If the user hasn't told you which they want, ASK them
@@ -47,6 +69,11 @@ Get the token from the platform dashboard — **https://platform.thatopen.com/da
 thatopen login --token <platform-token>
 ```
 
+**[Logging in to That Open Platform](https://raw.githubusercontent.com/ThatOpen/platform_services/main/docs/platform-token.md)** is the short version of everything that
+goes wrong here: production and dev are separate worlds, `login` does not say which one it saved,
+and a machine that is already logged in is somebody's previous session rather than a decision. Read
+it if the user is not on a fresh machine, or if anything comes back `Unauthorized` or `403`.
+
 This validates the token and stores it in `~/.thatopen/config.json`. Login **must** come
 first: the next step's install pulls the private `@thatopen-platform/*-beta` packages, and
 `create` uses your logged-in token to write an authenticated `.npmrc` so that install can
@@ -83,6 +110,16 @@ npm run dev
 Serves the app and opens it inside the platform. **You now have a complete, working viewer** —
 model loading, spatial tree, properties, measurement, sectioning, and more.
 
+> **`npx tsc --noEmit` reports errors in a fresh beta scaffold, and they are not real.** You will see
+> a handful of `Cannot find module '@thatopen/components'` and friends. A beta project aliases those
+> imports to the `@thatopen-platform/*-beta` packages in `vite.config.js`, which bare `tsc` does not
+> read — so it is looking for packages this project deliberately does not install.
+>
+> **In this project, `tsc` is not a signal.** Do not try to fix those errors, do not report them as
+> problems you found, and do not use a clean `tsc` as your definition of done. `npm run dev` and
+> `npm run build` are the ones that tell you anything; to check that something you added really
+> shipped, grep the built bundle for it.
+
 **[component]**
 ```bash
 npm run run        # executes the component locally against the platform (no browser)

package/docs/builtin/paths.json

@@ -83,6 +83,10 @@
     "path": "src/built-in/UIManager/src/clashes-panel/example.ts",
     "description": "clashes-panel — BIM coordinators need a dedicated review environment where they can see all detected clashes, filter by status, navigate to each issue in the 3D viewer, and mark items as resolved — without writing any UI code themselves."
   },
+  {
+    "path": "src/built-in/UIManager/src/git-history-panel/example.ts",
+    "description": "git-history-panel — `top-git-history` is a GitKraken-style commit timeline for the **revit-flow** feature. It lists the commits pushed by the Revit add-in (newest first) and, when you click a commit, drives the shared 3D viewer to color that commit's changed elements — created green, modified blue, deleted red — on the loaded baseline model."
+  },
   {
     "path": "src/built-in/UIManager/src/models-list/example.ts",
     "description": "top-models-list — top-models-list is the project's 3D-viewable-files tree: it mirrors the real storage folder structure, converts IFC to fragments, and loads `.frag`/`.potree`/`.splat` models into the 3D scene. Its loaders are PLUGGABLE — the panel owns the UI and the orchestration (progress, refresh, association), but the HOST decides how each extra file format is loaded, so you can teach it new formats without forking the built-in."

package/docs/cli/create.md

@@ -1,29 +1,29 @@
----
-description: "Scaffold a new app or cloud component project from a template. Covers --template (app for browser BIM apps, cloud-component for server-side components), --beta for switching to private beta engine libraries at scaffold time, and using '.' as the project name to scaffold into the current directory."
----
-
-## thatopen create
-
-Scaffolds a new ThatOpen project and runs `npm install` automatically.
-
-**Usage:**
-```bash
-thatopen create <project-name> [flags]
-thatopen create .             # scaffold into the current directory
-```
-
-**Flags:**
-
-- `--template <template>`, `-t` — Template to use. Default: `app`.
-  - `app` — Browser BIM app running inside the platform iframe.
-  - `cloud-component` — Server-side component executed by the platform's cloud engine and consumed in apps and/or automations.
-- `--beta` — Use private beta engine libraries (`@thatopen-platform/*-beta`) instead of the public ones. Sets `beta: true` in `.thatopen` so `serve`, `local-server`, and `vite build` all resolve to beta packages automatically. Requires beta npm access configured (handled automatically once you `thatopen login`).
-
-> **`--beta` is currently required.** The templates depend on engine APIs that only exist in the beta libraries, so scaffolding without `--beta` errors out for now. Public (non-beta) support is coming with the October release.
-
-**Examples:**
-```bash
-thatopen create my-app --beta
-thatopen create my-app -t cloud-component --beta
-thatopen create . --beta
-```
+---
+description: "Scaffold a new app or cloud component project from a template. Covers --template (app for browser BIM apps, cloud-component for server-side components), --beta for switching to private beta engine libraries at scaffold time, and using '.' as the project name to scaffold into the current directory."
+---
+
+## thatopen create
+
+Scaffolds a new ThatOpen project and runs `npm install` automatically.
+
+**Usage:**
+```bash
+thatopen create <project-name> [flags]
+thatopen create .             # scaffold into the current directory
+```
+
+**Flags:**
+
+- `--template <template>`, `-t` — Template to use. Default: `app`.
+  - `app` — Browser BIM app running inside the platform iframe.
+  - `cloud-component` — Server-side component executed by the platform's cloud engine and consumed in apps and/or automations.
+- `--beta` — Use private beta engine libraries (`@thatopen-platform/*-beta`) instead of the public ones. Sets `beta: true` in `.thatopen` so `serve`, `local-server`, and `vite build` all resolve to beta packages automatically. Requires beta npm access configured (handled automatically once you `thatopen login`).
+
+> **`--beta` is currently required.** The templates depend on engine APIs that only exist in the beta libraries, so scaffolding without `--beta` errors out for now. Public (non-beta) support is coming with the October release.
+
+**Examples:**
+```bash
+thatopen create my-app --beta
+thatopen create my-app -t cloud-component --beta
+thatopen create . --beta
+```

package/docs/cli/local-server.md

@@ -1,38 +1,38 @@
----
-description: "Start a local HTTP + Socket.IO server that replicates the platform's cloud execution API on port 4001, with esbuild watch mode. Connect an app to it via EngineServicesClient's localServerUrl option to execute and monitor a local cloud component without publishing."
----
-
-## thatopen local-server
-
-Starts a local server that mimics the platform's cloud execution API. Runs esbuild in watch mode and rebuilds the component on every save.
-
-Connect an app to it by passing `localServerUrl` to `EngineServicesClient`:
-
-```ts
-const client = new EngineServicesClient(token, apiUrl, {
-  localServerUrl: 'http://localhost:4001'
-});
-```
-
-**Usage:**
-```bash
-thatopen local-server [flags]
-```
-
-**Flags:**
-
-- `--port <port>` — Port to run the server on. Default: `4001`.
-- `--skip-build` — Skip the initial build and use the existing `dist/bundle.js`.
-
-**Endpoints:**
-
-- `POST /api/processor/:componentId/execute`
-- `GET  /api/processor/progress/:executionId`
-- `POST /api/processor/progress/:executionId/abort`
-- `GET  /api/processor/:componentId/progress`
-
-**Example:**
-```bash
-thatopen local-server
-thatopen local-server --port 5000
-```
+---
+description: "Start a local HTTP + Socket.IO server that replicates the platform's cloud execution API on port 4001, with esbuild watch mode. Connect an app to it via EngineServicesClient's localServerUrl option to execute and monitor a local cloud component without publishing."
+---
+
+## thatopen local-server
+
+Starts a local server that mimics the platform's cloud execution API. Runs esbuild in watch mode and rebuilds the component on every save.
+
+Connect an app to it by passing `localServerUrl` to `EngineServicesClient`:
+
+```ts
+const client = new EngineServicesClient(token, apiUrl, {
+  localServerUrl: 'http://localhost:4001'
+});
+```
+
+**Usage:**
+```bash
+thatopen local-server [flags]
+```
+
+**Flags:**
+
+- `--port <port>` — Port to run the server on. Default: `4001`.
+- `--skip-build` — Skip the initial build and use the existing `dist/bundle.js`.
+
+**Endpoints:**
+
+- `POST /api/processor/:componentId/execute`
+- `GET  /api/processor/progress/:executionId`
+- `POST /api/processor/progress/:executionId/abort`
+- `GET  /api/processor/:componentId/progress`
+
+**Example:**
+```bash
+thatopen local-server
+thatopen local-server --port 5000
+```

package/docs/cli/login.md

@@ -1,32 +1,32 @@
----
-description: "Authenticate with the ThatOpen platform by validating an access token against the API. Saves credentials globally (~/.thatopen/config.json) by default, or locally to the project's .thatopen file with --local. Local config takes priority over global."
----
-
-## thatopen login
-
-Validates an access token against the platform API and saves the credentials. Run this once globally before using any other command, or per-project with `--local`.
-
-To get a token:
-1. Go to [https://platform.thatopen.com](https://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
-
-**Usage:**
-```bash
-thatopen login --token <token> [flags]
-```
-
-**Flags:**
-
-- `--token <token>` — Access token from the dashboard. Required.
-- `--api-url <url>` — Platform API URL. Default: `https://platform.thatopen.com` (production). Pass `https://dev.platform.thatopen.com` to target the dev environment.
-- `--local` — Save credentials to `.thatopen` in the current directory instead of the global config. Use this inside a project to override the global token for that project only.
-
-**Examples:**
-```bash
-thatopen login --token my-token
-thatopen login --token my-token --local
-npm run login -- --token my-token    # from inside a scaffolded project
-```
+---
+description: "Authenticate with the ThatOpen platform by validating an access token against the API. Saves credentials globally (~/.thatopen/config.json) by default, or locally to the project's .thatopen file with --local. Local config takes priority over global."
+---
+
+## thatopen login
+
+Validates an access token against the platform API and saves the credentials. Run this once globally before using any other command, or per-project with `--local`.
+
+To get a token:
+1. Go to [https://platform.thatopen.com](https://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
+
+**Usage:**
+```bash
+thatopen login --token <token> [flags]
+```
+
+**Flags:**
+
+- `--token <token>` — Access token from the dashboard. Required.
+- `--api-url <url>` — Platform API URL. Default: `https://platform.thatopen.com` (production). Pass `https://dev.platform.thatopen.com` to target the dev environment.
+- `--local` — Save credentials to `.thatopen` in the current directory instead of the global config. Use this inside a project to override the global token for that project only.
+
+**Examples:**
+```bash
+thatopen login --token my-token
+thatopen login --token my-token --local
+npm run login -- --token my-token    # from inside a scaffolded project
+```

package/docs/cli/publish.md

@@ -1,31 +1,31 @@
----
-description: "Build and upload the project to the platform. Automatically detects app vs cloud component from the local .thatopen config. On first publish, saves the assigned item ID back to .thatopen so subsequent runs update the same item instead of creating a new one."
----
-
-## thatopen publish
-
-Builds the project and uploads it to the platform. Works for both apps and cloud components — the project type is read from `.thatopen` (`itemType: APP | COMPONENT`).
-
-First publish creates the item and auto-saves its ID to `.thatopen`. Subsequent publishes update that same item.
-
-**Usage:**
-```bash
-thatopen publish [flags]
-```
-
-**Flags:**
-
-- `--name <name>` — Item name on the platform. Defaults to `name` in `package.json`.
-- `--version-tag <tag>` — Version tag. Defaults to `version` in `package.json`.
-- `--app-id <id>` — Target an existing app by ID (overrides `.thatopen`).
-- `--component-id <id>` — Target an existing cloud component by ID (overrides `.thatopen`).
-- `--skip-build` — Skip the build step and upload the existing `dist/bundle.js`.
-- `--icon <path>` — Path to an icon file (PNG, WebP, or ICO, max 512 KB). Saved to `.thatopen` for future publishes.
-
-**Examples:**
-```bash
-thatopen publish
-thatopen publish --version-tag 2.0.0
-thatopen publish --skip-build
-thatopen publish --icon assets/icon.png
-```
+---
+description: "Build and upload the project to the platform. Automatically detects app vs cloud component from the local .thatopen config. On first publish, saves the assigned item ID back to .thatopen so subsequent runs update the same item instead of creating a new one."
+---
+
+## thatopen publish
+
+Builds the project and uploads it to the platform. Works for both apps and cloud components — the project type is read from `.thatopen` (`itemType: APP | COMPONENT`).
+
+First publish creates the item and auto-saves its ID to `.thatopen`. Subsequent publishes update that same item.
+
+**Usage:**
+```bash
+thatopen publish [flags]
+```
+
+**Flags:**
+
+- `--name <name>` — Item name on the platform. Defaults to `name` in `package.json`.
+- `--version-tag <tag>` — Version tag. Defaults to `version` in `package.json`.
+- `--app-id <id>` — Target an existing app by ID (overrides `.thatopen`).
+- `--component-id <id>` — Target an existing cloud component by ID (overrides `.thatopen`).
+- `--skip-build` — Skip the build step and upload the existing `dist/bundle.js`.
+- `--icon <path>` — Path to an icon file (PNG, WebP, or ICO, max 512 KB). Saved to `.thatopen` for future publishes.
+
+**Examples:**
+```bash
+thatopen publish
+thatopen publish --version-tag 2.0.0
+thatopen publish --skip-build
+thatopen publish --icon assets/icon.png
+```

package/docs/cli/run.md

@@ -1,26 +1,26 @@
----
-description: "Build and run a cloud component locally as a child process, mirroring the backend execution environment. Accepts execution parameters as JSON via --params, validates them against declarations.json, and streams progress output to the terminal."
----
-
-## thatopen run
-
-Builds and executes a cloud component locally, replicating what the platform's cloud engine does. Useful for testing component logic and parameters before publishing.
-
-Execution output (`MESSAGE`, `PROGRESS`, `SUCCESS`, `FAIL`) is streamed to the terminal with elapsed time.
-
-**Usage:**
-```bash
-thatopen run [flags]
-```
-
-**Flags:**
-
-- `--params <json>` — Execution parameters as a JSON string. Default: `'{}'`. Validated against `declarations.json` if present (warns, does not fail).
-- `--skip-build` — Skip the build step and run the existing `dist/bundle.js`.
-
-**Examples:**
-```bash
-thatopen run
-thatopen run --params '{"fileId": "abc123"}'
-thatopen run --skip-build
-```
+---
+description: "Build and run a cloud component locally as a child process, mirroring the backend execution environment. Accepts execution parameters as JSON via --params, validates them against declarations.json, and streams progress output to the terminal."
+---
+
+## thatopen run
+
+Builds and executes a cloud component locally, replicating what the platform's cloud engine does. Useful for testing component logic and parameters before publishing.
+
+Execution output (`MESSAGE`, `PROGRESS`, `SUCCESS`, `FAIL`) is streamed to the terminal with elapsed time.
+
+**Usage:**
+```bash
+thatopen run [flags]
+```
+
+**Flags:**
+
+- `--params <json>` — Execution parameters as a JSON string. Default: `'{}'`. Validated against `declarations.json` if present (warns, does not fail).
+- `--skip-build` — Skip the build step and run the existing `dist/bundle.js`.
+
+**Examples:**
+```bash
+thatopen run
+thatopen run --params '{"fileId": "abc123"}'
+thatopen run --skip-build
+```

package/docs/cli/serve.md

@@ -1,43 +1,43 @@
----
-description: "Start a local dev server for a browser app. Uses esbuild in watch mode and serves the IIFE bundle on port 4000 with SSE live reload. To connect: open the project on platform.thatopen.com, click the Local App icon, then Get Started."
----
-
-## thatopen serve
-
-Builds the app in watch mode and serves the IIFE bundle locally. On every save, esbuild rebuilds and the platform reloads the bundle automatically via SSE.
-
-Does **not** open a browser tab — the app runs inside the platform iframe. Open your project on the platform, then click the debug button to connect it to the local server.
-
-**Usage:**
-```bash
-thatopen serve [flags]
-```
-
-**Flags:**
-
-- `--port <port>` — Port to serve the bundle on. Default: `4000`.
-
-**Endpoints served:**
-
-- `GET /bundle.js` — The compiled IIFE bundle.
-- `GET /bundle.js.map` — Source map.
-- `GET /events` — SSE stream for live reload.
-
-**Example:**
-```bash
-thatopen serve
-thatopen serve --port 4321
-```
-
-**Connecting the platform to your local server:**
-
-1. Go to [https://platform.thatopen.com](https://platform.thatopen.com) and open a project (create one first if needed).
-2. In the top right corner, click the **Local App** icon.
-3. Click **Get Started**.
-
-The platform loads the bundle from port 4000 and renders the app inside the project context, with full access to its models, data, and users. The dev server must be running before opening this URL — if nothing is served on port 4000, the platform will fail to load the app.
-
-The resulting URL follows this pattern:
-```
-https://platform.thatopen.com/dashboard/projects/{projectId}/apps/local-app
-```
+---
+description: "Start a local dev server for a browser app. Uses esbuild in watch mode and serves the IIFE bundle on port 4000 with SSE live reload. To connect: open the project on platform.thatopen.com, click the Local App icon, then Get Started."
+---
+
+## thatopen serve
+
+Builds the app in watch mode and serves the IIFE bundle locally. On every save, esbuild rebuilds and the platform reloads the bundle automatically via SSE.
+
+Does **not** open a browser tab — the app runs inside the platform iframe. Open your project on the platform, then click the debug button to connect it to the local server.
+
+**Usage:**
+```bash
+thatopen serve [flags]
+```
+
+**Flags:**
+
+- `--port <port>` — Port to serve the bundle on. Default: `4000`.
+
+**Endpoints served:**
+
+- `GET /bundle.js` — The compiled IIFE bundle.
+- `GET /bundle.js.map` — Source map.
+- `GET /events` — SSE stream for live reload.
+
+**Example:**
+```bash
+thatopen serve
+thatopen serve --port 4321
+```
+
+**Connecting the platform to your local server:**
+
+1. Go to [https://platform.thatopen.com](https://platform.thatopen.com) and open a project (create one first if needed).
+2. In the top right corner, click the **Local App** icon.
+3. Click **Get Started**.
+
+The platform loads the bundle from port 4000 and renders the app inside the project context, with full access to its models, data, and users. The dev server must be running before opening this URL — if nothing is served on port 4000, the platform will fail to load the app.
+
+The resulting URL follows this pattern:
+```
+https://platform.thatopen.com/dashboard/projects/{projectId}/apps/local-app
+```

package/docs/cli/swap.md

@@ -1,30 +1,30 @@
----
-description: "Toggle or explicitly set the engine library mode between stable public packages (@thatopen/*) and private beta packages (@thatopen-platform/*-beta). Updates package.json and .thatopen, then runs npm install. Source code never changes — aliases handle resolution."
----
-
-## thatopen swap
-
-Switches the project between stable and beta engine libraries. Without flags, it toggles from the current state. Updates `package.json` dependencies and sets `beta` in `.thatopen` so `thatopen serve`, `thatopen local-server`, and `vite build` all pick up the change automatically.
-
-Source code stays unchanged — `@thatopen/components` imports resolve to the correct package via esbuild/vite aliases based on the `beta` flag in `.thatopen`.
-
-**Usage:**
-```bash
-thatopen swap           # toggle: stable → beta or beta → stable
-thatopen swap --beta    # force beta
-thatopen swap --stable  # force stable
-```
-
-**Flags:**
-
-- `--beta` — Switch to beta libraries (`@thatopen-platform/*-beta`).
-- `--stable` — Switch back to stable public libraries (`@thatopen/*`).
-
-**Examples:**
-```bash
-thatopen swap
-thatopen swap --beta
-thatopen swap --stable
-```
-
-> Beta packages are private and the access must be explicitly granted by That Open Company.
+---
+description: "Toggle or explicitly set the engine library mode between stable public packages (@thatopen/*) and private beta packages (@thatopen-platform/*-beta). Updates package.json and .thatopen, then runs npm install. Source code never changes — aliases handle resolution."
+---
+
+## thatopen swap
+
+Switches the project between stable and beta engine libraries. Without flags, it toggles from the current state. Updates `package.json` dependencies and sets `beta` in `.thatopen` so `thatopen serve`, `thatopen local-server`, and `vite build` all pick up the change automatically.
+
+Source code stays unchanged — `@thatopen/components` imports resolve to the correct package via esbuild/vite aliases based on the `beta` flag in `.thatopen`.
+
+**Usage:**
+```bash
+thatopen swap           # toggle: stable → beta or beta → stable
+thatopen swap --beta    # force beta
+thatopen swap --stable  # force stable
+```
+
+**Flags:**
+
+- `--beta` — Switch to beta libraries (`@thatopen-platform/*-beta`).
+- `--stable` — Switch back to stable public libraries (`@thatopen/*`).
+
+**Examples:**
+```bash
+thatopen swap
+thatopen swap --beta
+thatopen swap --stable
+```
+
+> Beta packages are private and the access must be explicitly granted by That Open Company.