@thatopen/services 0.6.0 → 0.8.0

package/dist/index.es.js

@@ -3,8 +3,8 @@ var we = (n) => {
   throw TypeError(n);
 };
 var Ve = (n, e, t) => e in n ? Me(n, e, { enumerable: !0, configurable: !0, writable: !0, value: t }) : n[e] = t;
-var w = (n, e, t) => Ve(n, typeof e != "symbol" ? e + "" : e, t), J = (n, e, t) => e.has(n) || we("Cannot " + t);
-var Y = (n, e, t) => (J(n, e, "read from private field"), t ? t.call(n) : e.get(n)), K = (n, e, t) => e.has(n) ? we("Cannot add the same private member more than once") : e instanceof WeakSet ? e.add(n) : e.set(n, t), _e = (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 w = (n, e, t) => Ve(n, typeof e != "symbol" ? e + "" : e, t), j = (n, e, t) => e.has(n) || we("Cannot " + t);
+var Y = (n, e, t) => (j(n, e, "read from private field"), t ? t.call(n) : e.get(n)), K = (n, e, t) => e.has(n) ? we("Cannot add the same private member more than once") : e instanceof WeakSet ? e.add(n) : e.set(n, t), _e = (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 v = /* @__PURE__ */ Object.create(null);
 v.open = "0";
 v.close = "1";
@@ -47,7 +47,7 @@ const Ge = (n) => {
   for (s = 0; s < t; s += 4)
     i = P[n.charCodeAt(s)], o = P[n.charCodeAt(s + 1)], h = P[n.charCodeAt(s + 2)], l = P[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", fe = (n, e) => {
+}, Je = typeof ArrayBuffer == "function", fe = (n, e) => {
   if (typeof n != "string")
     return {
       type: "message",
@@ -56,15 +56,15 @@ const Ge = (n) => {
   const t = n.charAt(0);
   return t === "b" ? {
     type: "message",
-    data: Je(n.substring(1), e)
+    data: je(n.substring(1), e)
   } : U[t] ? n.length > 1 ? {
     type: U[t],
     data: n.substring(1)
   } : {
     type: U[t]
   } : te;
-}, Je = (n, e) => {
-  if (je) {
+}, je = (n, e) => {
+  if (Je) {
     const t = Ge(n);
     return $e(t, e);
   } else
@@ -224,7 +224,7 @@ function xe(n, ...e) {
   return e.reduce((t, s) => (n.hasOwnProperty(s) && (t[s] = n[s]), t), {});
 }
 const Ze = _.setTimeout, et = _.clearTimeout;
-function j(n, e) {
+function J(n, e) {
   e.useNativeTimers ? (n.setTimeoutFn = Ze.bind(_), n.clearTimeoutFn = et.bind(_)) : (n.setTimeoutFn = _.setTimeout.bind(_), n.clearTimeoutFn = _.clearTimeout.bind(_));
 }
 const tt = 1.33;
@@ -267,7 +267,7 @@ class pe 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, J(this, e), this.opts = e, this.query = e.query, this.socket = e.socket, this.supportsBinary = !e.forceBase64;
   }
   /**
    * Emits an error.
@@ -474,8 +474,8 @@ class ut extends at {
   /**
    * Sends data.
    *
-   * @param {String} data - data to send.
-   * @param {Function} fn - called upon flush.
+   * @param {String} data to send.
+   * @param {Function} called upon flush.
    * @private
    */
   doWrite(e, t) {
@@ -507,7 +507,7 @@ class T 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, 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();
   }
   /**
    * Creates the XHR object and sends the request.
@@ -807,7 +807,7 @@ class R extends g {
       const s = se(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 = se(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) => {
+    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) => {
       const r = s.prototype.name;
       this.transports.push(r), this._transportsByName[r] = s;
     }), this.opts = Object.assign({
@@ -1008,7 +1008,7 @@ class R extends g {
   /**
    * Sends a packet.
    *
-   * @param {String} type - packet type.
+   * @param {String} type: packet type.
    * @param {String} data.
    * @param {Object} options.
    * @param {Function} fn - callback function.
@@ -1140,8 +1140,8 @@ class Et extends R {
 }
 let Tt = class extends Et {
   constructor(e, t = {}) {
-    const s = typeof e == "object", r = s ? { ...e } : { ...t };
-    (!r.transports || r.transports && typeof r.transports[0] == "string") && (r.transports = (r.transports || ["polling", "websocket", "webtransport"]).map((i) => mt[i]).filter((i) => !!i)), super(s ? r : e, r);
+    const s = typeof e == "object" ? e : t;
+    (!s.transports || s.transports && typeof s.transports[0] == "string") && (s.transports = (s.transports || ["polling", "websocket", "webtransport"]).map((r) => mt[r]).filter((r) => !!r)), super(e, s);
   }
 };
 function vt(n, e = "", t) {
@@ -1274,12 +1274,11 @@ class Bt {
 class ye extends g {
   /**
    * Decoder constructor
+   *
+   * @param {function} reviver - custom reviver to pass down to JSON.stringify
    */
   constructor(e) {
-    super(), this.opts = Object.assign({
-      reviver: void 0,
-      maxAttachments: 10
-    }, typeof e == "function" ? { reviver: e } : e);
+    super(), this.reviver = e;
   }
   /**
    * Decodes an encoded packet string into packet JSON.
@@ -1322,12 +1321,7 @@ class ye extends g {
       const o = e.substring(i, t);
       if (o != Number(o) || e.charAt(t) !== "-")
         throw new Error("Illegal attachments");
-      const h = Number(o);
-      if (!Nt(h) || h < 0)
-        throw new Error("Illegal attachments");
-      if (h > this.opts.maxAttachments)
-        throw new Error("too many attachments");
-      s.attachments = h;
+      s.attachments = Number(o);
     }
     if (e.charAt(t + 1) === "/") {
       const i = t + 1;
@@ -1361,7 +1355,7 @@ class ye extends g {
   }
   tryParse(e) {
     try {
-      return JSON.parse(e, this.opts.reviver);
+      return JSON.parse(e, this.reviver);
     } catch {
       return !1;
     }
@@ -1415,13 +1409,10 @@ class xt {
     this.reconPack = null, this.buffers = [];
   }
 }
-const Nt = Number.isInteger || function(n) {
-  return typeof n == "number" && isFinite(n) && Math.floor(n) === n;
-};
 function ke(n) {
   return Object.prototype.toString.call(n) === "[object Object]";
 }
-const Pt = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+const Nt = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
   __proto__: null,
   Decoder: ye,
   Encoder: Bt,
@@ -1434,7 +1425,7 @@ function b(n, e, t) {
     n.off(e, t);
   };
 }
-const Lt = Object.freeze({
+const Pt = Object.freeze({
   connect: 1,
   connect_error: 1,
   disconnect: 1,
@@ -1559,7 +1550,7 @@ class Ue extends g {
    */
   emit(e, ...t) {
     var s, r, i;
-    if (Lt.hasOwnProperty(e))
+    if (Pt.hasOwnProperty(e))
       throw new Error('"' + e.toString() + '" is a reserved event name');
     if (t.unshift(e), this._opts.retries && !this.flags.fromQueue && !this.flags.volatile)
       return this._addToQueue(t), this;
@@ -2061,12 +2052,12 @@ x.prototype.setJitter = function(n) {
 class oe 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 x({
+    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 x({
       min: this.reconnectionDelay(),
       max: this.reconnectionDelayMax(),
       jitter: this.randomizationFactor()
     }), this.timeout(t.timeout == null ? 2e4 : t.timeout), this._readyState = "closed", this.uri = e;
-    const r = t.parser || Pt;
+    const r = t.parser || Nt;
     this.encoder = new r.Encoder(), this.decoder = new r.Decoder(), this._autoConnect = t.autoConnect !== !1, this._autoConnect && this.open();
   }
   reconnection(e) {
@@ -2309,7 +2300,7 @@ Object.assign(M, {
   io: M,
   connect: M
 });
-function It(n) {
+function Lt(n) {
   try {
     const e = JSON.parse(n);
     if (e && typeof e == "object") {
@@ -2324,9 +2315,9 @@ function It(n) {
   }
   return {};
 }
-class qt extends Error {
+class It extends Error {
   constructor(t, s, r) {
-    const i = It(r);
+    const i = Lt(r);
     super(i.message ?? `${s || "Request failed"} (${t})`);
     w(this, "status");
     w(this, "code");
@@ -2335,7 +2326,7 @@ class qt extends Error {
     this.name = "RequestError", this.status = t, this.code = i.code, this.details = i.details, this.body = r;
   }
 }
-const E = "item/folder", f = "item", S = "processor", Ut = "npm-registry", C = "hidden", Q = "FILE", Z = "TOOL", ee = "APP";
+const E = "item/folder", f = "item", S = "processor", qt = "npm-registry", C = "hidden", Q = "FILE", Z = "TOOL", ee = "APP";
 var a, ce, u, $, V, H, he, ue, De;
 const me = class me {
   /**
@@ -2884,7 +2875,7 @@ return main;`)(...h), d = (y == null ? void 0 : y.componentDefinition) ?? y;
    * @returns The registry, scope, read-only token, and assembled `.npmrc`.
    */
   async getNpmCredentials() {
-    return await c(this, a, u).call(this, "GET", `${Ut}/credentials`);
+    return await c(this, a, u).call(this, "GET", `${qt}/credentials`);
   }
   // ─── Execution ───────────────────────────────────────────────────
   /**
@@ -3198,7 +3189,7 @@ a = new WeakSet(), ce = function(e) {
     );
     if (!A.ok) {
       const O = await A.text().then((Fe) => Fe).catch(() => "");
-      throw new qt(
+      throw new It(
         A.status,
         A.statusText,
         O
@@ -3360,21 +3351,21 @@ const ge = class ge extends ae {
 };
 B = new WeakMap();
 let Ae = ge;
-const Mt = {
+const Ft = {
   MAX_FIELDS: 200,
   MAX_KEY_LENGTH: 50,
   MAX_VALUE_LENGTH: 50
-}, Vt = { uuid: "a3f82c1d-5b74-4e9a-bc30-d7e12f894a61" }, Ht = { uuid: "2c9f4e8d-3a1b-4c5e-9d7f-0a2b6c8e1d3f" }, Gt = { uuid: "b0b5e2a2-0b3a-4a6b-8b1c-0b1c4a6b8b1c" }, jt = { uuid: "3f9c1a7e-6b2d-4e18-9a5c-7d0e2f4b6c81" }, Jt = { uuid: "2c4ae432-fc24-43e9-9783-0c960c674e96" }, Yt = { uuid: "69af63aa-19ba-4fc7-b17b-75647bac1d76" }, Kt = { uuid: "234f1416-528d-452a-9cc9-a16c5239b2eb" };
+}, Mt = { uuid: "a3f82c1d-5b74-4e9a-bc30-d7e12f894a61" }, Vt = { uuid: "2c9f4e8d-3a1b-4c5e-9d7f-0a2b6c8e1d3f" }, Ht = { uuid: "b0b5e2a2-0b3a-4a6b-8b1c-0b1c4a6b8b1c" }, Gt = { uuid: "3f9c1a7e-6b2d-4e18-9a5c-7d0e2f4b6c81" }, Jt = { uuid: "2c4ae432-fc24-43e9-9783-0c960c674e96" }, jt = { uuid: "69af63aa-19ba-4fc7-b17b-75647bac1d76" }, Yt = { uuid: "234f1416-528d-452a-9cc9-a16c5239b2eb" };
 export {
-  Vt as CDEManager,
-  Ht as ClashesManager,
+  Mt as CDEManager,
+  Vt as ClashesManager,
   ae as EngineServicesClient,
-  Gt as FileList,
-  jt as GitHistoryManager,
+  Ht as FileList,
+  Gt as GitHistoryManager,
   Jt as HelloWorld,
-  Mt as METADATA_LIMITS,
+  Ft as METADATA_LIMITS,
   Ae as PlatformClient,
-  qt as RequestError,
-  Yt as TopicsManager,
-  Kt as UIManager
+  It as RequestError,
+  jt as TopicsManager,
+  Yt as UIManager
 };

package/dist/vite-env.d.ts

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

package/docs/ai-quickstart.md

@@ -12,7 +12,7 @@ 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](./revit-collab-quickstart.md)** and follow that instead.
+> **[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
@@ -21,8 +21,8 @@ on the [That Open Platform](https://platform.thatopen.com) from scratch, using
 
 > **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](./flow-plugin-guide.md)** is the
-> byte contract, and **[the architecture notes](./flow-architecture.md)** say why it is shaped that
+> 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.
 >
@@ -69,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
@@ -82,6 +87,16 @@ thatopen create my-app --beta
 cd my-app
 ```
 
+**[app, showing a Revit model's commit history]** If what they asked for is a viewer of the
+revit-flow history, scaffold it directly. Do not build it by hand: the wiring is four additions in
+three places and the ORDER of them is load-bearing (see the boot order section below). This ships
+it already correct, opening on the History layout.
+
+```bash
+thatopen create my-app --beta --history
+cd my-app
+```
+
 **[component]**
 ```bash
 thatopen create my-component -t cloud-component --beta
@@ -105,12 +120,128 @@ 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.
 
+If it does not open by itself, or the user closes the tab, the app you are serving from this
+machine lives at:
+
+```
+https://platform.thatopen.com/dashboard/projects/<PROJECT_ID>/apps/local-app
+```
+
+Substitute the project id. That is the local app running inside the platform's own UI, against
+the project's real data. Send the user there rather than to a bare localhost port, which is the
+app without the platform around it.
+
+> **`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)
 ```
 Runs `main()` in a local emulation of the cloud engine so you can iterate before publishing.
 
+## THE BOOT ORDER. Read this before you write a line of an app.
+
+**This is where apps break, and the error never names the real cause.** An app boots in four
+stages, and a built-in that touches models or the 3D scene must be initialised in the LAST one.
+Call it where it reads naturally, right after `client.setup`, and you get:
+
+```
+Error: FragmentsManager not initialized. Call init() first.
+Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'onHighlight')
+Uncaught (in promise) TypeError: Cannot read properties of undefined (reading 'onClear')
+```
+
+None of which says "you called this too early". The app renders, the panel mounts, and it sits
+there inert.
+
+**Why.** `FragmentsManager` is initialised inside `top-app`'s own `setup` callback, and the 3D
+world does not exist until `<top-app>` has been added to the DOM and `top-viewer` has built it.
+Both of those happen well after `client.setup` returns. Any manager that reads model files or
+colours elements reaches for them the moment it starts.
+
+**The order, and it is not negotiable:**
+
+1. `client.setup(...)` with every built-in you need, then `components.get(UIManager).init()`
+2. `app.setup = ...`, which is where `FragmentsManager.init` goes, and append `<top-app>`
+3. `await firstWorld(...)`, so the world exists
+4. **only now**, `init(client)` on the model-facing managers
+
+Copy this skeleton. It is the boot of an app that works.
+
+```ts
+async function main() {
+  const client = PlatformClient.fromPlatformContext();
+
+  // 1 ── built-ins registered, UI shell up
+  const { components } = await client.setup<OBC.Components>(
+    { OBC, OBF, BUI, THREE, FRAGS, MARKERJS },
+    { uuid: UIManager.uuid },
+    { uuid: GitHistoryManager.uuid },        // and any other built-in you use
+  );
+  components.get(UIManager).init();
+
+  const viewerEl = document.createElement("top-viewer");
+  const app = document.createElement("top-app") as any;
+
+  // 2 ── this callback is what initialises FragmentsManager. Nothing that needs
+  //      fragments may run before it has resolved.
+  app.setup = (waitUntil: (p: Promise<void>, label?: string) => void) => {
+    waitUntil(
+      (async () => {
+        const fragments = components.get(OBC.FragmentsManager);
+        const workerUrl = await FRAGS.FragmentsModels.getWorker();
+        fragments.init(await FRAGS.toClassicWorker(workerUrl), { classicWorker: true });
+      })(),
+      "Fragments Core",
+    );
+    return { components, client };
+  };
+
+  app.elements = { viewer: () => BUI.html`${viewerEl}` };
+  app.layouts = { Main: { template: `"viewer" 1fr / 1fr` } };
+  app.layout = "Main";
+  (document.getElementById("that-open-app") ?? document.body).appendChild(app);
+
+  // 3 ── the world is created asynchronously by top-viewer. Wait for it.
+  await firstWorld(components.get(OBC.Worlds));
+
+  // 4 ── ONLY NOW. Everything above had to have happened first.
+  await components.get(GitHistoryManager).init(client);
+
+  // ...and from here, the real layouts, panels and elements.
+}
+
+/** Resolves with the first world once it exists (top-viewer creates it async). */
+function firstWorld(worlds: any): Promise<any> {
+  const existing = [...worlds.list.values()][0];
+  if (existing) return Promise.resolve(existing);
+  return new Promise((resolve) => {
+    const handler = ({ value }: any) => {
+      worlds.list.onItemSet.remove(handler);
+      resolve(value);
+    };
+    worlds.list.onItemSet.add(handler);
+  });
+}
+```
+
+**Two more traps in the same family:**
+
+- **One stable `top-viewer` node, held in a variable and returned by reference** from every
+  `elements.viewer()` call. Creating a fresh element on each render disposes the world and
+  builds another one, and everything wired to the old one goes quiet.
+- **Registering a built-in is not the same as initialising it.** `client.setup` makes
+  `<top-git-history>` resolvable; `init(client)` is what fills it. A panel that mounts and stays
+  empty is usually the second one missing, not the first.
+
 ## 5. Then build — read the in-project agent guide
 
 The scaffold is real, working code — a complete viewer **[app]** or a runnable `main()`
@@ -148,5 +279,8 @@ component, once added to a project, is then triggered by an app or an automation
 - **Platform token only.** Never introduce, request, or store an npm token.
 - **Never echo or persist the user's token.** It belongs only in `~/.thatopen/config.json` /
   `.npmrc`, both of which the CLI manages and git-ignores.
-- **Propose a short plan and get the user's OK** before changing files.
+- **Do the thing they asked for.** If the request already says what to build, build it. Proposing a
+  four-point plan and waiting for approval to do what was just requested costs the user a whole turn
+  and buys nothing. Stop and ask only when you are about to change files you did not create, when
+  the request can be read two ways that mean different work, or when the next step is destructive.
 - The scaffold already works — **extend it, don't replace it.**

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
+```