@thatopen/services 0.1.3 → 0.3.0

package/dist/index.es.js

@@ -3,8 +3,8 @@ var ge = (n) => {
   throw TypeError(n);
 };
 var Ve = (n, e, t) => e in n ? Fe(n, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : n[e] = t;
-var _ = (n, e, t) => Ve(n, typeof e != "symbol" ? e + "" : e, t), j = (n, e, t) => e.has(n) || ge("Cannot " + t);
-var G = (n, e, t) => (j(n, e, "read from private field"), t ? t.call(n) : e.get(n)), K = (n, e, t) => e.has(n) ? ge("Cannot add the same private member more than once") : e instanceof WeakSet ? e.add(n) : e.set(n, t), we = (n, e, t, s) => (j(n, e, "write to private field"), s ? s.call(n, t) : e.set(n, t), t), c = (n, e, t) => (j(n, e, "access private method"), t);
+var _ = (n, e, t) => Ve(n, typeof e != "symbol" ? e + "" : e, t), J = (n, e, t) => e.has(n) || ge("Cannot " + t);
+var j = (n, e, t) => (J(n, e, "read from private field"), t ? t.call(n) : e.get(n)), Y = (n, e, t) => e.has(n) ? ge("Cannot add the same private member more than once") : e instanceof WeakSet ? e.add(n) : e.set(n, t), we = (n, e, t, s) => (J(n, e, "write to private field"), s ? s.call(n, t) : e.set(n, t), t), c = (n, e, t) => (J(n, e, "access private method"), t);
 const k = /* @__PURE__ */ Object.create(null);
 k.open = "0";
 k.close = "1";
@@ -27,14 +27,14 @@ const ee = { type: "error", data: "parser error" }, Ae = typeof Blob == "functio
 function be(n) {
   return n instanceof Uint8Array ? n : n instanceof ArrayBuffer ? new Uint8Array(n) : new Uint8Array(n.buffer, n.byteOffset, n.byteLength);
 }
-let Y;
+let K;
 function Me(n, e) {
   if (Ae && n.data instanceof Blob)
     return n.data.arrayBuffer().then(be).then(e);
   if (Oe && (n.data instanceof ArrayBuffer || Se(n.data)))
     return e(be(n.data));
   ue(n, !1, (t) => {
-    Y || (Y = new TextEncoder()), e(Y.encode(t));
+    K || (K = new TextEncoder()), e(K.encode(t));
   });
 }
 const Ee = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/", N = typeof Uint8Array > "u" ? [] : new Uint8Array(256);
@@ -47,7 +47,7 @@ const He = (n) => {
   for (s = 0; s < t; s += 4)
     i = N[n.charCodeAt(s)], o = N[n.charCodeAt(s + 1)], h = N[n.charCodeAt(s + 2)], l = N[n.charCodeAt(s + 3)], d[r++] = i << 2 | o >> 4, d[r++] = (o & 15) << 4 | h >> 2, d[r++] = (h & 3) << 6 | l & 63;
   return y;
-}, Je = typeof ArrayBuffer == "function", le = (n, e) => {
+}, Ge = typeof ArrayBuffer == "function", le = (n, e) => {
   if (typeof n != "string")
     return {
       type: "message",
@@ -56,15 +56,15 @@ const He = (n) => {
   const t = n.charAt(0);
   return t === "b" ? {
     type: "message",
-    data: je(n.substring(1), e)
+    data: Je(n.substring(1), e)
   } : q[t] ? n.length > 1 ? {
     type: q[t],
     data: n.substring(1)
   } : {
     type: q[t]
   } : ee;
-}, je = (n, e) => {
-  if (Je) {
+}, Je = (n, e) => {
+  if (Ge) {
     const t = He(n);
     return Ce(t, e);
   } else
@@ -77,7 +77,7 @@ const He = (n) => {
     default:
       return n instanceof ArrayBuffer ? n : n.buffer;
   }
-}, Re = "", Ge = (n, e) => {
+}, Re = "", je = (n, e) => {
   const t = n.length, s = new Array(t);
   let r = 0;
   n.forEach((i, o) => {
@@ -85,7 +85,7 @@ const He = (n) => {
       s[o] = h, ++r === t && e(s.join(Re));
     });
   });
-}, Ke = (n, e) => {
+}, Ye = (n, e) => {
   const t = n.split(Re), s = [];
   for (let r = 0; r < t.length; r++) {
     const i = le(t[r], e);
@@ -94,7 +94,7 @@ const He = (n) => {
   }
   return s;
 };
-function Ye() {
+function Ke() {
   return new TransformStream({
     transform(n, e) {
       Me(n, (t) => {
@@ -224,7 +224,7 @@ function Be(n, ...e) {
   return e.reduce((t, s) => (n.hasOwnProperty(s) && (t[s] = n[s]), t), {});
 }
 const Qe = b.setTimeout, Ze = b.clearTimeout;
-function J(n, e) {
+function G(n, e) {
   e.useNativeTimers ? (n.setTimeoutFn = Qe.bind(b), n.clearTimeoutFn = Ze.bind(b)) : (n.setTimeoutFn = b.setTimeout.bind(b), n.clearTimeoutFn = b.clearTimeout.bind(b));
 }
 const et = 1.33;
@@ -267,7 +267,7 @@ class fe extends g {
    * @protected
    */
   constructor(e) {
-    super(), this.writable = !1, J(this, e), this.opts = e, this.query = e.query, this.socket = e.socket, this.supportsBinary = !e.forceBase64;
+    super(), this.writable = !1, G(this, e), this.opts = e, this.query = e.query, this.socket = e.socket, this.supportsBinary = !e.forceBase64;
   }
   /**
    * Emits an error.
@@ -413,7 +413,7 @@ class ot extends fe {
         return this.onClose({ description: "transport closed by the server" }), !1;
       this.onPacket(s);
     };
-    Ke(e, this.socket.binaryType).forEach(t), this.readyState !== "closed" && (this._polling = !1, this.emitReserved("pollComplete"), this.readyState === "open" && this._poll());
+    Ye(e, this.socket.binaryType).forEach(t), this.readyState !== "closed" && (this._polling = !1, this.emitReserved("pollComplete"), this.readyState === "open" && this._poll());
   }
   /**
    * For polling, send a close packet.
@@ -433,7 +433,7 @@ class ot extends fe {
    * @protected
    */
   write(e) {
-    this.writable = !1, Ge(e, (t) => {
+    this.writable = !1, je(e, (t) => {
       this.doWrite(t, () => {
         this.writable = !0, this.emitReserved("drain");
       });
@@ -507,7 +507,7 @@ class v extends g {
    * @package
    */
   constructor(e, t, s) {
-    super(), this.createRequest = e, J(this, s), this._opts = s, this._method = s.method || "GET", this._uri = t, this._data = s.data !== void 0 ? s.data : null, this._create();
+    super(), this.createRequest = e, G(this, s), this._opts = s, this._method = s.method || "GET", this._uri = t, this._data = s.data !== void 0 ? s.data : null, this._create();
   }
   /**
    * Creates the XHR object and sends the request.
@@ -721,7 +721,7 @@ class dt extends fe {
       this.onError("webtransport error", e);
     }), this._transport.ready.then(() => {
       this._transport.createBidirectionalStream().then((e) => {
-        const t = We(Number.MAX_SAFE_INTEGER, this.socket.binaryType), s = e.readable.pipeThrough(t).getReader(), r = Ye();
+        const t = We(Number.MAX_SAFE_INTEGER, this.socket.binaryType), s = e.readable.pipeThrough(t).getReader(), r = Ke();
         r.readable.pipeTo(e.writable), this._writer = r.writable.getWriter();
         const i = () => {
           s.read().then(({ done: h, value: l }) => {
@@ -807,7 +807,7 @@ class C extends g {
       const s = te(e);
       t.hostname = s.host, t.secure = s.protocol === "https" || s.protocol === "wss", t.port = s.port, s.query && (t.query = s.query);
     } else t.host && (t.hostname = te(t.host).host);
-    J(this, t), this.secure = t.secure != null ? t.secure : typeof location < "u" && location.protocol === "https:", t.hostname && !t.port && (t.port = this.secure ? "443" : "80"), this.hostname = t.hostname || (typeof location < "u" ? location.hostname : "localhost"), this.port = t.port || (typeof location < "u" && location.port ? location.port : this.secure ? "443" : "80"), this.transports = [], this._transportsByName = {}, t.transports.forEach((s) => {
+    G(this, t), this.secure = t.secure != null ? t.secure : typeof location < "u" && location.protocol === "https:", t.hostname && !t.port && (t.port = this.secure ? "443" : "80"), this.hostname = t.hostname || (typeof location < "u" ? location.hostname : "localhost"), this.port = t.port || (typeof location < "u" && location.port ? location.port : this.secure ? "443" : "80"), this.transports = [], this._transportsByName = {}, t.transports.forEach((s) => {
       const r = s.prototype.name;
       this.transports.push(r), this._transportsByName[r] = s;
     }), this.opts = Object.assign({
@@ -2052,7 +2052,7 @@ B.prototype.setJitter = function(n) {
 class ie extends g {
   constructor(e, t) {
     var s;
-    super(), this.nsps = {}, this.subs = [], e && typeof e == "object" && (t = e, e = void 0), t = t || {}, t.path = t.path || "/socket.io", this.opts = t, J(this, t), this.reconnection(t.reconnection !== !1), this.reconnectionAttempts(t.reconnectionAttempts || 1 / 0), this.reconnectionDelay(t.reconnectionDelay || 1e3), this.reconnectionDelayMax(t.reconnectionDelayMax || 5e3), this.randomizationFactor((s = t.randomizationFactor) !== null && s !== void 0 ? s : 0.5), this.backoff = new B({
+    super(), this.nsps = {}, this.subs = [], e && typeof e == "object" && (t = e, e = void 0), t = t || {}, t.path = t.path || "/socket.io", this.opts = t, G(this, t), this.reconnection(t.reconnection !== !1), this.reconnectionAttempts(t.reconnectionAttempts || 1 / 0), this.reconnectionDelay(t.reconnectionDelay || 1e3), this.reconnectionDelayMax(t.reconnectionDelayMax || 5e3), this.randomizationFactor((s = t.randomizationFactor) !== null && s !== void 0 ? s : 0.5), this.backoff = new B({
       min: this.reconnectionDelay(),
       max: this.reconnectionDelayMax(),
       jitter: this.randomizationFactor()
@@ -2326,7 +2326,7 @@ class Lt extends Error {
     this.name = "RequestError", this.status = t, this.code = i.code, this.details = i.details, this.body = r;
   }
 }
-const T = "item/folder", p = "item", O = "processor", R = "hidden", X = "FILE", Q = "TOOL", Z = "APP";
+const T = "item/folder", p = "item", O = "processor", It = "npm-registry", R = "hidden", X = "FILE", Q = "TOOL", Z = "APP";
 var a, ae, u, S, V, M, ce, he, Ue;
 const ye = class ye {
   /**
@@ -2337,7 +2337,7 @@ const ye = class ye {
    * @param props - Optional configuration (retry count, auth mode, etc.).
    */
   constructor(e, t, s) {
-    K(this, a);
+    Y(this, a);
     _(this, "apiUrl");
     _(this, "accessToken");
     _(this, "wsUrl");
@@ -2865,6 +2865,18 @@ return main;`)(...h), d = (y == null ? void 0 : y.componentDefinition) ?? y;
   async archiveApp(e) {
     return await c(this, a, u).call(this, "DELETE", `${p}/${e}`);
   }
+  // ─── NPM Registry ────────────────────────────────────────────────
+  /**
+   * Fetches read-only npm credentials for the private `@thatopen` Founders
+   * beta packages. Gated server-side on the token owner's membership tier:
+   * FOUNDING members (and admins) get the token; everyone else gets a 403
+   * (`RequestError` with `status === 403`). The returned `npmrc` is a
+   * ready-to-write `.npmrc` body the CLI drops into a scaffolded project.
+   * @returns The registry, scope, read-only token, and assembled `.npmrc`.
+   */
+  async getNpmCredentials() {
+    return await c(this, a, u).call(this, "GET", `${It}/credentials`);
+  }
   // ─── Execution ───────────────────────────────────────────────────
   /**
    * Triggers server-side execution of a cloud component.
@@ -3246,11 +3258,11 @@ const me = class me extends oe {
    */
   constructor(t, s, r) {
     super(typeof t == "string" ? t : "", s, { ...r, useBearer: !0 });
-    K(this, $);
+    Y(this, $);
     typeof t == "function" && we(this, $, t);
   }
   async resolveAccessToken() {
-    return G(this, $) ? await G(this, $).call(this) : super.resolveAccessToken();
+    return j(this, $) ? await j(this, $).call(this) : super.resolveAccessToken();
   }
   /**
    * Creates a client from the platform context injected into
@@ -3307,20 +3319,18 @@ const me = class me extends oe {
 };
 $ = new WeakMap();
 let ke = me;
-const Ut = {
+const Dt = {
   MAX_FIELDS: 200,
   MAX_KEY_LENGTH: 50,
   MAX_VALUE_LENGTH: 50
-}, Dt = { uuid: "2e32d873-02c9-421c-8743-d8a5ca6ad38a" }, Ft = { uuid: "b0b5e2a2-0b3a-4a6b-8b1c-0b1c4a6b8b1c" }, Vt = { uuid: "2c4ae432-fc24-43e9-9783-0c960c674e96" }, Mt = { uuid: "3c2a9f34-8b6c-4d1b-8f7a-1e4a5b2c9f08" }, Ht = { uuid: "234f1416-528d-452a-9cc9-a16c5239b2eb" }, Jt = { uuid: "def81d43-6b44-4f4a-9c08-7649486112a4" };
+}, Ft = { uuid: "a3f82c1d-5b74-4e9a-bc30-d7e12f894a61" }, Vt = { uuid: "b0b5e2a2-0b3a-4a6b-8b1c-0b1c4a6b8b1c" }, Mt = { uuid: "2c4ae432-fc24-43e9-9783-0c960c674e96" }, Ht = { uuid: "234f1416-528d-452a-9cc9-a16c5239b2eb" };
 export {
-  Dt as AppManager,
+  Ft as CDEManager,
   oe as EngineServicesClient,
-  Ft as FileList,
-  Vt as HelloWorld,
-  Ut as METADATA_LIMITS,
+  Vt as FileList,
+  Mt as HelloWorld,
+  Dt as METADATA_LIMITS,
   ke as PlatformClient,
   Lt as RequestError,
-  Mt as TabbedNavigation,
-  Ht as UIManager,
-  Jt as ViewportsManager
+  Ht as UIManager
 };

package/dist/types/npm.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Read-only npm credentials for the private `@thatopen` Founders beta packages.
+ * Returned by `GET /api/npm-registry/credentials` to FOUNDING members only.
+ */
+export interface NpmCredentials {
+    /** Registry the scope is pinned to (e.g. `https://registry.npmjs.org/`). */
+    registry: string;
+    /** Package scope the token grants read access to (e.g. `@thatopen`). */
+    scope: string;
+    /** The read-only npm token. */
+    token: string;
+    /** Ready-to-write `.npmrc` file body (scope pin + auth line). */
+    npmrc: string;
+}

package/dist/vite-env.d.ts

@@ -1 +1 @@
-/// <reference types="vite/client" />
+/// <reference types="vite/client" />

package/docs/builtin/paths.json

@@ -1,70 +1,74 @@
-[
-  {
-    "path": "src/built-in/CDEManager/example.ts",
-    "description": "CDEManager — CDEManager is the central state machine for a Common Data Environment. It holds files, folders, metadata schemas, viewer groups, and user permissions, and exposes a typed state machine that all file operations — selecting, editing, uploading, viewing — route through. It has no DOM or Three.js dependencies and can run in Node, a browser, or a server-side worker wherever `@thatopen/components` is available."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/FileEditing/example.ts",
-    "description": "Bulk file editing — stage, preview, revert, and commit — A project manager preparing a deliverable handoff needs to update discipline tags across fifteen IFC files after a scope change, rename each to match the new naming convention, and archive three superseded models — all before anything is sent to the backend. Doing the changes one file at a time risks leaving the file list in a half-updated state if the session is interrupted, and there is no way to review exactly what will change before committing."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/FileMoves/example.ts",
-    "description": "Drag-and-drop file and folder moves — A coordinator restructures the project after a scope change: structural files move from the root into a dedicated discipline folder, a MEP sub-folder needs to be promoted to the top level, and a few documents need to come back to root to appear in the general view. Drag-and-drop is the natural gesture for all of this, but each drag session has intermediate stages — the file is \"in the air\", hovering over a candidate target — and every panel watching the file table should see the right state without coordinating directly with the drag component."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/FileOperations/example.ts",
-    "description": "File operations — inline edit, rename, view, download, archive — BIM coordinators reviewing a model drop repeat the same small actions throughout their session: correcting a discipline tag that changed after a scope revision, renaming a file to match the agreed convention, opening it alongside the structural model to check for clashes, handing it off to a sub-consultant, or removing a superseded version from the live set. If every panel in the platform handles these separately, two panels looking at the same file at the same time can show contradictory states — one says \"uploading\", another still shows the old name."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/FileTransfers/example.ts",
-    "description": "File uploads, versioning, and the download cache — A site coordinator drops a batch of files onto the CDE every Monday after the weekend review: some are entirely new models, some are revised versions of files already in the project, and sometimes the metadata group they upload into should be stamped automatically onto the new files. If the platform makes the coordinator sort this out manually, it slows the handoff and introduces naming errors. And if an upload fails halfway through a batch, the file table should land in a safe state rather than freeze at a loading spinner."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/FolderManagement/example.ts",
-    "description": "Folder management — create, rename, archive, and commit — A project reaches the construction phase and the coordination team needs to restructure the folder hierarchy: add a \"Facades\" discipline folder, rename \"Structural\" to its official abbreviation, and archive two superseded folders that have been merged. Doing these one at a time through separate API calls means the folder tree flickers between invalid states as each change lands — a freshly created folder appears before its sibling is renamed, and the archived folders briefly disappear before the new one is visible."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/MetadataSchema/example.ts",
-    "description": "Metadata schema — define, stage, and publish field definitions — Every project has its own vocabulary for describing files: discipline codes, revision phases, area zones, review statuses. A metadata schema defines which fields exist, what values they accept, and whether they are mandatory. Without a structured schema, each user invents their own labels and the file list becomes impossible to filter or report on consistently."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/MetadataViews/example.ts",
-    "description": "Metadata views — organize fields into named table layouts — A structural engineer and an MEP coordinator look at the same file list but care about completely different metadata. Showing every field to everyone produces a wide table that is hard to navigate. Metadata views let each role define which fields appear in which order — saving the layout so the table opens correctly next time without requiring a manual setup every session."
-  },
-  {
-    "path": "src/built-in/CDEManager/examples/ProjectConfig/example.ts",
-    "description": "Project configuration — read, write, and reload persistent data — A CDE application needs to store two kinds of configuration: project-wide settings that all team members share (the metadata schema, custom naming rules) and personal settings that belong to one user (which columns are visible, which metadata views are pinned). Both live inside the project's file storage under a reserved system folder, so they travel with the project and don't rely on a separate configuration service."
-  },
-  {
-    "path": "src/built-in/FileList/example.ts",
-    "description": ""
-  },
-  {
-    "path": "src/built-in/TabbedNavigation/example.ts",
-    "description": ""
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/example.ts",
-    "description": "top-app — Front-end developers building BIM web apps need to coordinate several async initialization steps before the UI can be shown — loading the engine, preparing fragment workers, registering loaders — and users need visible feedback on what is happening during that wait, rather than a blank screen."
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/examples/AppState/example.ts",
-    "description": "Shared reactive state with AppState — Developers building interactive BIM panels often need sibling components — a filter selector and a results table, for example — to stay in sync without a shared parent. Lifting state to a common ancestor and threading it down as props works for shallow trees but becomes unwieldy as the component tree grows."
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/examples/Contexts/example.ts",
-    "description": "Consuming platform contexts in child components — Developers building custom BIM panels need access to the 3D engine, the platform API, and the current project's metadata — but threading these objects down through props across multiple component layers forces every intermediate element to know about data it doesn't use, making trees brittle and hard to refactor."
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/examples/FloatingLayout/example.ts",
-    "description": "Floating layout — Developers building BIM coordination tools often want the 3D model to fill the entire window while control panels float above it — but standard grid layouts give every area equal standing, shrinking the viewer into one cell and leaving visible seams between it and the panels."
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/examples/Notifications/example.ts",
-    "description": "Toasts, file drop, and cross-component notifications — Developers building BIM processing UIs need to surface status updates, errors, and file-drop feedback to users from different points in the component tree — but reaching back to the app root to trigger a notification from a deeply nested component requires threading a reference through every layer in between."
-  },
-  {
-    "path": "src/built-in/UIManager/src/app/examples/Sidebar/example.ts",
-    "description": "Sidebar navigation — Product teams building BIM apps often need multiple distinct views — a 3D model viewer, a data browser, a settings screen — but wiring a custom nav bar and managing view transitions from scratch adds complexity before any real feature work begins."
-  }
-]
+[
+  {
+    "path": "src/built-in/CDEManager/example.ts",
+    "description": "CDEManager — CDEManager is the central state machine for a Common Data Environment. It holds files, folders, metadata schemas, viewer groups, and user permissions, and exposes a typed state machine that all file operations — selecting, editing, uploading, viewing — route through. It has no DOM or Three.js dependencies and can run in Node, a browser, or a server-side worker wherever `@thatopen/components` is available."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/FileEditing/example.ts",
+    "description": "Bulk file editing — stage, preview, revert, and commit — A project manager preparing a deliverable handoff needs to update discipline tags across fifteen IFC files after a scope change, rename each to match the new naming convention, and archive three superseded models — all before anything is sent to the backend. Doing the changes one file at a time risks leaving the file list in a half-updated state if the session is interrupted, and there is no way to review exactly what will change before committing."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/FileMoves/example.ts",
+    "description": "Drag-and-drop file and folder moves — A coordinator restructures the project after a scope change: structural files move from the root into a dedicated discipline folder, a MEP sub-folder needs to be promoted to the top level, and a few documents need to come back to root to appear in the general view. Drag-and-drop is the natural gesture for all of this, but each drag session has intermediate stages — the file is \"in the air\", hovering over a candidate target — and every panel watching the file table should see the right state without coordinating directly with the drag component."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/FileOperations/example.ts",
+    "description": "File operations — inline edit, rename, view, download, archive — BIM coordinators reviewing a model drop repeat the same small actions throughout their session: correcting a discipline tag that changed after a scope revision, renaming a file to match the agreed convention, opening it alongside the structural model to check for clashes, handing it off to a sub-consultant, or removing a superseded version from the live set. If every panel in the platform handles these separately, two panels looking at the same file at the same time can show contradictory states — one says \"uploading\", another still shows the old name."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/FileTransfers/example.ts",
+    "description": "File uploads, versioning, and the download cache — A site coordinator drops a batch of files onto the CDE every Monday after the weekend review: some are entirely new models, some are revised versions of files already in the project, and sometimes the metadata group they upload into should be stamped automatically onto the new files. If the platform makes the coordinator sort this out manually, it slows the handoff and introduces naming errors. And if an upload fails halfway through a batch, the file table should land in a safe state rather than freeze at a loading spinner."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/FolderManagement/example.ts",
+    "description": "Folder management — create, rename, archive, and commit — A project reaches the construction phase and the coordination team needs to restructure the folder hierarchy: add a \"Facades\" discipline folder, rename \"Structural\" to its official abbreviation, and archive two superseded folders that have been merged. Doing these one at a time through separate API calls means the folder tree flickers between invalid states as each change lands — a freshly created folder appears before its sibling is renamed, and the archived folders briefly disappear before the new one is visible."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/MetadataSchema/example.ts",
+    "description": "Metadata schema — define, stage, and publish field definitions — Every project has its own vocabulary for describing files: discipline codes, revision phases, area zones, review statuses. A metadata schema defines which fields exist, what values they accept, and whether they are mandatory. Without a structured schema, each user invents their own labels and the file list becomes impossible to filter or report on consistently."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/MetadataViews/example.ts",
+    "description": "Metadata views — organize fields into named table layouts — A structural engineer and an MEP coordinator look at the same file list but care about completely different metadata. Showing every field to everyone produces a wide table that is hard to navigate. Metadata views let each role define which fields appear in which order — saving the layout so the table opens correctly next time without requiring a manual setup every session."
+  },
+  {
+    "path": "src/built-in/CDEManager/examples/ProjectConfig/example.ts",
+    "description": "Project configuration — read, write, and reload persistent data — A CDE application needs to store two kinds of configuration: project-wide settings that all team members share (the metadata schema, custom naming rules) and personal settings that belong to one user (which columns are visible, which metadata views are pinned). Both live inside the project's file storage under a reserved system folder, so they travel with the project and don't rely on a separate configuration service."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/example.ts",
+    "description": "top-app — Front-end developers building BIM web apps need to coordinate several async initialization steps before the UI can be shown — loading the engine, preparing fragment workers, registering loaders — and users need visible feedback on what is happening during that wait, rather than a blank screen."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/AppState/example.ts",
+    "description": "Shared reactive state with AppState — Developers building interactive BIM panels often need sibling components — a filter selector and a results table, for example — to stay in sync without a shared parent. Lifting state to a common ancestor and threading it down as props works for shallow trees but becomes unwieldy as the component tree grows."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Banner/example.ts",
+    "description": "Persistent banners with top:banner — Some application states need a persistent, visible indicator that stays on screen until the state is explicitly cleared — an archived-files mode, a read-only permission warning, a degraded-connectivity notice. A toast auto-dismisses after a few seconds, which is wrong for these cases. A modal blocks interaction entirely, which is too heavy."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Contexts/example.ts",
+    "description": "Consuming platform contexts in child components — Developers building custom BIM panels need access to the 3D engine, the platform API, and the current project's metadata — but threading these objects down through props across multiple component layers forces every intermediate element to know about data it doesn't use, making trees brittle and hard to refactor."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/FileDrop/example.ts",
+    "description": "File drag-and-drop with top:files-dropped — Desktop BIM workflows often rely on dragging files straight from the OS file manager onto the browser window — but wiring a document-level dragenter, dragover, dragleave, and drop handler that correctly tracks nested enter/leave counts, shows a visual overlay, and forwards the files to the right component is tedious boilerplate to repeat for every app."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/FloatingLayout/example.ts",
+    "description": "Floating layout — Developers building BIM coordination tools often want the 3D model to fill the entire window while control panels float above it — but standard grid layouts give every area equal standing, shrinking the viewer into one cell and leaving visible seams between it and the panels."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Modal/example.ts",
+    "description": "Confirmation modals with top:modal — Destructive or irreversible actions — deleting records, overwriting files, leaving unsaved changes — should ask the user to confirm before proceeding. Opening a custom dialog element from a deeply nested component means threading a reference to a controller up through every layer of the tree."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Notifications/example.ts",
+    "description": "Toasts and cross-component notifications — Developers building BIM processing UIs need to surface status updates, errors, and async feedback to users from different points in the component tree — but reaching back to the app root to trigger a notification from a deeply nested component requires threading a reference through every layer in between."
+  },
+  {
+    "path": "src/built-in/UIManager/src/app/examples/Sidebar/example.ts",
+    "description": "Sidebar navigation — Product teams building BIM apps often need multiple distinct views — a 3D model viewer, a data browser, a settings screen — but wiring a custom nav bar and managing view transitions from scratch adds complexity before any real feature work begins."
+  }
+]

package/docs/cli/create.md

@@ -1,28 +1,28 @@
----
-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.
-
-**Examples:**
-```bash
-thatopen create my-app
-thatopen create my-app -t cloud-component
-thatopen create my-app --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.
+
+**Examples:**
+```bash
+thatopen create my-app
+thatopen create my-app -t cloud-component
+thatopen create my-app --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://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
-
-**Usage:**
-```bash
-thatopen login --token <token> [flags]
-```
-
-**Flags:**
-
-- `--token <token>` — Access token from the dashboard. Required.
-- `--api-url <url>` — Platform API URL. Default: `https://dev.platform.thatopen.com`.
-- `--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://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
+
+**Usage:**
+```bash
+thatopen login --token <token> [flags]
+```
+
+**Flags:**
+
+- `--token <token>` — Access token from the dashboard. Required.
+- `--api-url <url>` — Platform API URL. Default: `https://dev.platform.thatopen.com`.
+- `--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
+```