@thatopen/services 0.0.2 → 0.0.4

package/AGENTS.md

@@ -1,76 +1,86 @@
-# Building on the That Open Platform — Agent Guide
-
-You are an AI assistant helping a user build a **BIM app** or **cloud component** on the
-That Open Platform using **`@thatopen/services`** (the `thatopen` CLI + client library).
-
-**Read this file first.** It states the rules you must follow, then routes you to the one
-detailed doc for whatever you're doing. Open only the doc you need — don't load everything.
-
-> This guide is tool-agnostic: it works with any AI (Claude, Codex, your own). All docs it
-> references ship inside the `@thatopen/services` package under `docs/`.
-
----
-
-## How to work
-
-- **New app or component?** The **first step is always the CLI** (`thatopen create`) — never
-  hand-write the scaffold. See [docs/cli-setup.md](./docs/cli-setup.md) then
-  [docs/scaffolding.md](./docs/scaffolding.md).
-- **Propose a short plan and get the user's OK** before changing files. If scope is unclear, ask.
-- Prefer existing engine functionality over custom code (see rule 2).
-
-## Hard rules (always apply)
-
-1. **All business logic lives in a BIM component** (`src/bim-components/`).
-   `setups/` only wire; `ui-components/` only render; `main.ts` only boots. Logic that doesn't
-   fit an existing component → create a new one. Never put logic in a setup, template, or `main.ts`.
-2. **Check engine components first** — `@thatopen/components` (`OBC`) and
-   `@thatopen/components-front` (`OBF`) — before building anything custom.
-3. **Platform built-ins** (`AppManager`, `ViewportsManager`, `UIManager`, …) come from
-   `@thatopen/services` and are available after `client.setup()`. Don't reinvent them.
-
----
-
-## What are you doing? → open the right doc
-
-### Set up & ship
-| Goal | Doc |
-|---|---|
-| Install the CLI + authenticate | [docs/cli-setup.md](./docs/cli-setup.md) |
-| Scaffold a new app / component | [docs/scaffolding.md](./docs/scaffolding.md) |
-| Preview the app inside the platform | [docs/previewing.md](./docs/previewing.md) |
-| Publish an app or component | [docs/publishing.md](./docs/publishing.md) |
-
-### Structure & wire an app
-| Goal | Doc |
-|---|---|
-| Project structure, architecture rules, component tiers | [docs/app-architecture.md](./docs/app-architecture.md) |
-| Boot / `app.ts` / `main.ts` / `client.setup()` | [docs/app-wiring.md](./docs/app-wiring.md) |
-| Configure layout, add/reorganize grid sections | [docs/app-layout.md](./docs/app-layout.md) |
-| Connect component logic to the UI | [docs/connect-logic-to-ui.md](./docs/connect-logic-to-ui.md) |
-| Update a grid element's state at runtime | [docs/update-grid-elements.md](./docs/update-grid-elements.md) |
-| Access the backend client / project data | [docs/access-backend-data.md](./docs/access-backend-data.md) |
-| Register and use icons | [docs/using-icons.md](./docs/using-icons.md) |
-| Declare and use colors | [docs/using-colors.md](./docs/using-colors.md) |
-
-### Build a custom BIM component
-Start at [docs/bim-components/overview.md](./docs/bim-components/overview.md) — conventions,
-lifecycle (setup/cleanup), exposing events, observable/element collections, per-frame updates,
-saving/restoring state, user-driven object creation.
-
-### Build a UI component
-Start at [docs/ui-components/overview.md](./docs/ui-components/overview.md) — rendering patterns,
-section layout, data tables, inline forms, confirmation dialogs, display text, async actions.
-
-### Cloud components & automations
-[docs/cloud-components.md](./docs/cloud-components.md) — build / run locally / publish a cloud
-component, the execution globals, and event-triggered automations.
-
----
-
-## Reference (also shipped in this package)
-
-- **Library API** — `PlatformClient` vs `EngineServicesClient`, the permissions contract, and the
-  full method surface → [CONTEXT.md](./CONTEXT.md)
-- **Built-in components API** — config interfaces, method signatures, `@example` blocks →
-  `src/built-in/index.ts` (in the installed package, `node_modules/@thatopen/services/`)
+# Building on the That Open Platform — Agent Guide
+
+You are an AI assistant helping a user build a **BIM app** or **cloud component** on the
+That Open Platform using **`@thatopen/services`** (the `thatopen` CLI + client library).
+
+**Read this file first.** It states the rules you must follow, then routes you to the one
+detailed doc for whatever you're doing. Open only the doc you need — don't load everything.
+
+> This guide is tool-agnostic: it works with any AI (Claude, Codex, your own). All docs it
+> references ship inside the `@thatopen/services` package under `docs/`.
+
+---
+
+## How to work
+
+- 🚩 **BEFORE creating anything, ask the user about beta access — this is important.** Ask:
+  *"Do you have That Open beta access? It gives you the latest libraries, features and progress —
+  and it's what the platform currently runs. Do you want to use it?"* **If yes, scaffold with the
+  `bim-beta` template** (`thatopen create <name> -t bim-beta`). Founding members have **permanent** beta
+  access, so for them the answer is almost always yes. Using the matching library line avoids
+  runtime errors against the platform. (Beta packages are private — the user needs their beta
+  access token configured in npm, or `npm install` will fail.) See
+  [docs/scaffolding.md](./docs/scaffolding.md).
+- **New app or component?** The **first step is always the CLI** (`thatopen create`) — never
+  hand-write the scaffold. See [docs/cli-setup.md](./docs/cli-setup.md) then
+  [docs/scaffolding.md](./docs/scaffolding.md).
+- **The scaffold is already a complete, working viewer** (model loading, spatial tree, properties).
+  **Run it first** (`npm run dev`) to see it work, *then* extend it — don't rebuild a viewer from scratch.
+- **Propose a short plan and get the user's OK** before changing files. If scope is unclear, ask.
+- Prefer existing engine functionality over custom code (see rule 2).
+
+## Hard rules (always apply)
+
+1. **All business logic lives in a BIM component** (`src/bim-components/`).
+   `setups/` only wire; `ui-components/` only render; `main.ts` only boots. Logic that doesn't
+   fit an existing component → create a new one. Never put logic in a setup, template, or `main.ts`.
+2. **Check engine components first** — `@thatopen/components` (`OBC`) and
+   `@thatopen/components-front` (`OBF`) — before building anything custom.
+3. **Platform built-ins** (`AppManager`, `ViewportsManager`, `UIManager`, …) come from
+   `@thatopen/services` and are available after `client.setup()`. Don't reinvent them.
+
+---
+
+## What are you doing? → open the right doc
+
+### Set up & ship
+| Goal | Doc |
+|---|---|
+| Install the CLI + authenticate | [docs/cli-setup.md](./docs/cli-setup.md) |
+| Scaffold a new app / component | [docs/scaffolding.md](./docs/scaffolding.md) |
+| Preview the app inside the platform | [docs/previewing.md](./docs/previewing.md) |
+| Publish an app or component | [docs/publishing.md](./docs/publishing.md) |
+
+### Structure & wire an app
+| Goal | Doc |
+|---|---|
+| Project structure, architecture rules, component tiers | [docs/app-architecture.md](./docs/app-architecture.md) |
+| Boot / `app.ts` / `main.ts` / `client.setup()` | [docs/app-wiring.md](./docs/app-wiring.md) |
+| Configure layout, add/reorganize grid sections | [docs/app-layout.md](./docs/app-layout.md) |
+| Connect component logic to the UI | [docs/connect-logic-to-ui.md](./docs/connect-logic-to-ui.md) |
+| Update a grid element's state at runtime | [docs/update-grid-elements.md](./docs/update-grid-elements.md) |
+| Access the backend client / project data | [docs/access-backend-data.md](./docs/access-backend-data.md) |
+| Register and use icons | [docs/using-icons.md](./docs/using-icons.md) |
+| Declare and use colors | [docs/using-colors.md](./docs/using-colors.md) |
+
+### Build a custom BIM component
+Start at [docs/bim-components/overview.md](./docs/bim-components/overview.md) — conventions,
+lifecycle (setup/cleanup), exposing events, observable/element collections, per-frame updates,
+saving/restoring state, user-driven object creation.
+
+### Build a UI component
+Start at [docs/ui-components/overview.md](./docs/ui-components/overview.md) — rendering patterns,
+section layout, data tables, inline forms, confirmation dialogs, display text, async actions.
+
+### Cloud components & automations
+[docs/cloud-components.md](./docs/cloud-components.md) — build / run locally / publish a cloud
+component, the execution globals, and event-triggered automations.
+
+---
+
+## Reference (also shipped in this package)
+
+- **Library API** — `PlatformClient` vs `EngineServicesClient`, the permissions contract, and the
+  full method surface → [CONTEXT.md](./CONTEXT.md)
+- **Built-in components API** — config interfaces, method signatures, `@example` blocks →
+  `src/built-in/index.ts` (in the installed package, `node_modules/@thatopen/services/`)

package/dist/cli.js

@@ -7980,7 +7980,7 @@ const loginCommand = new Command2("login").description("Authenticate with the Th
     );
   }
 });
-const TEMPLATES = ["default", "bim", "cloud", "test", "cloud-test"];
+const TEMPLATES = ["default", "bim", "bim-beta", "cloud", "test", "cloud-test"];
 const libVersion = (() => {
   try {
     const pkg2 = JSON.parse(require$$3.readFileSync(require$$2.join(__dirname, "..", "package.json"), "utf-8"));
@@ -8028,12 +8028,21 @@ const createCommand = new Command2("create").argument("<project-name>", 'Name of
   const pkgPath = require$$2.join(targetDir, "package.json");
   const pkg2 = require$$3.readFileSync(pkgPath, "utf-8").replace(/\{\{PROJECT_NAME\}\}/g, packageName).replace(/\{\{VERSION\}\}/g, libVersion).replace(/"@thatopen\/services": "file:[^"]*"/, `"@thatopen/services": "^${libVersion}"`);
   require$$3.writeFileSync(pkgPath, pkg2);
+  const isBeta = template === "bim-beta";
+  if (isBeta) {
+    console.log("");
+    console.log("This template uses the private BETA engine libraries (@thatopen-platform/*-beta).");
+    console.log("If install fails with a 401/403, configure your beta access token in npm first.");
+  }
   console.log("");
   console.log("Installing dependencies...");
   try {
     require$$1.execSync("npm install", { cwd: targetDir, stdio: "inherit" });
   } catch {
     console.error("Failed to install dependencies. Run `npm install` manually.");
+    if (isBeta) {
+      console.error("Beta packages are private — if this is an auth error, your beta token may not be configured.");
+    }
   }
   console.log("");
   console.log(useCurrentDir ? "  Project ready!" : `  Created ./${projectName}`);

package/docs/access-backend-data.md

@@ -1,19 +1,19 @@
-# Access Backend Data
-
-## Accessing backend data via `AppManager`
-
-After `init()`, `AppManager` exposes:
-
-- **`app.client`** — `EngineServicesClient`: backend client for API calls
-- **`app.projectData`** — `ProjectData`: current user info, role, project metadata
-
-Both are resolved before any setup runs. Always access them through `getAppManager(components)`:
-
-```ts
-const app = getAppManager(components)
-if (app.projectData.currentUser?.role.name === "Project Admin") {
-  // render admin-only controls
-}
-
-const files = await app.client.getProjectFiles(app.projectData.id)
-```
+# Access Backend Data
+
+## Accessing backend data via `AppManager`
+
+After `init()`, `AppManager` exposes:
+
+- **`app.client`** — `EngineServicesClient`: backend client for API calls
+- **`app.projectData`** — `ProjectData`: current user info, role, project metadata
+
+Both are resolved before any setup runs. Always access them through `getAppManager(components)`:
+
+```ts
+const app = getAppManager(components)
+if (app.projectData.currentUser?.role.name === "Project Admin") {
+  // render admin-only controls
+}
+
+const files = await app.client.getProjectFiles(app.projectData.id)
+```

package/docs/app-architecture.md

@@ -1,94 +1,94 @@
-# App Architecture and Composition
-
-## Architecture rule: logic lives only in BIM components
-
-**All business logic in a platform app must live inside a BIM component** (`src/bim-components/`). This is not a convention — it is the architectural constraint of the platform.
-
-| Layer | What belongs here | What does NOT belong here |
-|---|---|---|
-| `bim-components/` | State, events, async operations, data access, coordination logic | — |
-| `setups/` | Event subscriptions, calling component methods, UI sync | Business logic, data processing, state |
-| `ui-components/` | Rendering, layout, reading component state | Logic, API calls, mutations |
-| `main.ts` | Boot sequence only | Any logic whatsoever |
-
-If logic doesn't fit inside an existing BIM component, the answer is always to create a new one or extend an existing one — never to write it in a setup file, a template, or `main.ts`.
-
-```ts
-// ✗ Forbidden — logic in a setup file
-export const mySetup = (components: OBC.Components) => {
-  const fragments = components.get(OBC.FragmentsManager)
-  fragments.list.onItemSet.add(async (model) => {
-    const data = await fetchSomething(model.uuid)  // ← logic here is wrong
-    processData(data)
-  })
-}
-
-// ✓ Correct — setup only wires; logic lives in the component
-export const mySetup = (components: OBC.Components) => {
-  const uis = getUIManager(components)
-  const manager = components.get(MyManager)
-  manager.onDataReady.add(() => uis.custom.get("myPanel").updateInstances())
-}
-```
-
----
-
-## Component tiers in a platform app
-
-Every platform app works with three tiers of components, all accessible via `components.get()`:
-
-- **Engine components** — public, from `@thatopen/components` (OBC) and `@thatopen/components-front` (OBF). Always check these first before building custom logic.
-- **Platform built-in components** — private components from `@thatopen/services` (e.g. `AppManager`, `UIManager`, `ViewportsManager`). Available after `client.setup()`, already wired up.
-- **Custom components** — see the BIM-component and UI-component guides in `docs/`. Live in `src/bim-components/`, self-register in their constructor via `components.add()`.
-
----
-
-## Project Structure
-
-Every app has this shape under `src/`. To configure the app layout or add and reorganize sections in the grid, see [./app-layout.md](./app-layout.md).
-
-```
-src/
-├── bim-components/   → custom OBC domain components
-├── ui-components/    → BUI templates, barrel only
-├── setups/           → initialization and wiring
-├── app.ts            → typed app identity
-├── globals.ts        → global constants (icons, tooltips, colors, etc.)
-└── main.ts           → entry point
-```
-
-### `bim-components/`
-
-Each custom OBC component lives in its own folder, built following the BIM-component guide in `docs/` (see [./bim-components/overview.md](./bim-components/overview.md)). The `index.ts` barrel re-exports every component class, its types, and its static `uuid` — this is the single import point for all custom domain logic throughout the app.
-
-### `ui-components/`
-
-Templates created following the UI-component guide in `docs/` (see [./ui-components/overview.md](./ui-components/overview.md)) are re-exported from the barrel. The `index.ts` is a **pure barrel** — only re-exports, nothing else. Registration of templates in the UIManager happens in `setups/ui-manager.ts`.
-
-### `setups/`
-
-One file per component being initialized. `ui-manager.ts` is always present as fixed boilerplate; all other files are custom wiring. See [./connect-logic-to-ui.md](./connect-logic-to-ui.md) for the full implementation reference. To update the state of a grid element at runtime from a setup or event handler, see [./update-grid-elements.md](./update-grid-elements.md).
-
-### `app.ts` and `main.ts`
-
-`app.ts` defines the app's typed shape and the `getAppManager` accessor. `main.ts` boots the platform — no business logic belongs here. See [./app-wiring.md](./app-wiring.md) for structure, `client.setup()`, and `componentSetups`. To access the backend client or project data (`app.client`, `app.projectData`), see [./access-backend-data.md](./access-backend-data.md).
-
-### `globals.ts`
-
-Contains the icon registry, color registry, and any other global constants. All icons must be declared here and accessed through `AppManager`. Colors are declared here and imported directly where needed. See [./using-icons.md](./using-icons.md) and [./using-colors.md](./using-colors.md) for details.
-
----
-
-## See also
-
-- [Connect logic to the UI](./connect-logic-to-ui.md) — register templates, sync views, etc.
-- [Configure the app layout](./app-layout.md) — add or reorganize sections in the grid.
-- [App wiring](./app-wiring.md) — boot the app, configure `app.ts`, `main.ts`, `client.setup()`, `componentSetups`.
-- [Access backend data](./access-backend-data.md) — the backend client and project data (`app.client`, `app.projectData`).
-- [Using icons](./using-icons.md) — register or use icons in the app.
-- [Using colors](./using-colors.md) — declare or use global colors (highlighter, palette, etc.).
-- [Update grid elements](./update-grid-elements.md) — update the state of a grid element at runtime.
-- [Scaffolding a new app](./scaffolding.md) — scaffold a new app from scratch using the CLI.
-- [Publishing an app](./publishing.md) — publish an app to the platform (login + publish).
-- [CLI setup](./cli-setup.md) — install the CLI and authenticate with a platform token.
-- [Previewing apps](./previewing.md) — preview the app during development inside the platform.
+# App Architecture and Composition
+
+## Architecture rule: logic lives only in BIM components
+
+**All business logic in a platform app must live inside a BIM component** (`src/bim-components/`). This is not a convention — it is the architectural constraint of the platform.
+
+| Layer | What belongs here | What does NOT belong here |
+|---|---|---|
+| `bim-components/` | State, events, async operations, data access, coordination logic | — |
+| `setups/` | Event subscriptions, calling component methods, UI sync | Business logic, data processing, state |
+| `ui-components/` | Rendering, layout, reading component state | Logic, API calls, mutations |
+| `main.ts` | Boot sequence only | Any logic whatsoever |
+
+If logic doesn't fit inside an existing BIM component, the answer is always to create a new one or extend an existing one — never to write it in a setup file, a template, or `main.ts`.
+
+```ts
+// ✗ Forbidden — logic in a setup file
+export const mySetup = (components: OBC.Components) => {
+  const fragments = components.get(OBC.FragmentsManager)
+  fragments.list.onItemSet.add(async (model) => {
+    const data = await fetchSomething(model.uuid)  // ← logic here is wrong
+    processData(data)
+  })
+}
+
+// ✓ Correct — setup only wires; logic lives in the component
+export const mySetup = (components: OBC.Components) => {
+  const uis = getUIManager(components)
+  const manager = components.get(MyManager)
+  manager.onDataReady.add(() => uis.custom.get("myPanel").updateInstances())
+}
+```
+
+---
+
+## Component tiers in a platform app
+
+Every platform app works with three tiers of components, all accessible via `components.get()`:
+
+- **Engine components** — public, from `@thatopen/components` (OBC) and `@thatopen/components-front` (OBF). Always check these first before building custom logic.
+- **Platform built-in components** — private components from `@thatopen/services` (e.g. `AppManager`, `UIManager`, `ViewportsManager`). Available after `client.setup()`, already wired up.
+- **Custom components** — see the BIM-component and UI-component guides in `docs/`. Live in `src/bim-components/`, self-register in their constructor via `components.add()`.
+
+---
+
+## Project Structure
+
+Every app has this shape under `src/`. To configure the app layout or add and reorganize sections in the grid, see [./app-layout.md](./app-layout.md).
+
+```
+src/
+├── bim-components/   → custom OBC domain components
+├── ui-components/    → BUI templates, barrel only
+├── setups/           → initialization and wiring
+├── app.ts            → typed app identity
+├── globals.ts        → global constants (icons, tooltips, colors, etc.)
+└── main.ts           → entry point
+```
+
+### `bim-components/`
+
+Each custom OBC component lives in its own folder, built following the BIM-component guide in `docs/` (see [./bim-components/overview.md](./bim-components/overview.md)). The `index.ts` barrel re-exports every component class, its types, and its static `uuid` — this is the single import point for all custom domain logic throughout the app.
+
+### `ui-components/`
+
+Templates created following the UI-component guide in `docs/` (see [./ui-components/overview.md](./ui-components/overview.md)) are re-exported from the barrel. The `index.ts` is a **pure barrel** — only re-exports, nothing else. Registration of templates in the UIManager happens in `setups/ui-manager.ts`.
+
+### `setups/`
+
+One file per component being initialized. `ui-manager.ts` is always present as fixed boilerplate; all other files are custom wiring. See [./connect-logic-to-ui.md](./connect-logic-to-ui.md) for the full implementation reference. To update the state of a grid element at runtime from a setup or event handler, see [./update-grid-elements.md](./update-grid-elements.md).
+
+### `app.ts` and `main.ts`
+
+`app.ts` defines the app's typed shape and the `getAppManager` accessor. `main.ts` boots the platform — no business logic belongs here. See [./app-wiring.md](./app-wiring.md) for structure, `client.setup()`, and `componentSetups`. To access the backend client or project data (`app.client`, `app.projectData`), see [./access-backend-data.md](./access-backend-data.md).
+
+### `globals.ts`
+
+Contains the icon registry, color registry, and any other global constants. All icons must be declared here and accessed through `AppManager`. Colors are declared here and imported directly where needed. See [./using-icons.md](./using-icons.md) and [./using-colors.md](./using-colors.md) for details.
+
+---
+
+## See also
+
+- [Connect logic to the UI](./connect-logic-to-ui.md) — register templates, sync views, etc.
+- [Configure the app layout](./app-layout.md) — add or reorganize sections in the grid.
+- [App wiring](./app-wiring.md) — boot the app, configure `app.ts`, `main.ts`, `client.setup()`, `componentSetups`.
+- [Access backend data](./access-backend-data.md) — the backend client and project data (`app.client`, `app.projectData`).
+- [Using icons](./using-icons.md) — register or use icons in the app.
+- [Using colors](./using-colors.md) — declare or use global colors (highlighter, palette, etc.).
+- [Update grid elements](./update-grid-elements.md) — update the state of a grid element at runtime.
+- [Scaffolding a new app](./scaffolding.md) — scaffold a new app from scratch using the CLI.
+- [Publishing an app](./publishing.md) — publish an app to the platform (login + publish).
+- [CLI setup](./cli-setup.md) — install the CLI and authenticate with a platform token.
+- [Previewing apps](./previewing.md) — preview the app during development inside the platform.