@thatopen/services 0.3.3 → 0.3.4

package/docs/ai-quickstart.md

@@ -1,7 +1,7 @@
-# That Open Platform — AI Quick Start (zero to a running app)
+# That Open Platform — AI Quick Start (zero to a running app or cloud component)
 
-You are an AI assistant. A user pointed you at this URL so you can scaffold and run a
-**BIM app** on the [That Open Platform](https://platform.thatopen.com) from scratch, using
+You are an AI assistant. A user pointed you at this URL so you can scaffold and run something
+on the [That Open Platform](https://platform.thatopen.com) from scratch, using
 `@thatopen/services` (the `thatopen` CLI + client library). Follow the steps below in order.
 
 > The only secret you need is a **platform API token** — **not** an npm token. The CLI
@@ -9,6 +9,22 @@ You are an AI assistant. A user pointed you at this URL so you can scaffold and
 
 ---
 
+## First — what are you building? (ask if the user hasn't said)
+
+There are two kinds of project. **If the user hasn't told you which they want, ASK them
+before scaffolding** — explain it in plain terms and let them pick:
+
+- **App** — something people *open and click around in*, running in the platform's browser
+  UI: a 3D BIM viewer, a dashboard, a form, a custom tool. Choose this when the goal is a
+  visual interface. Template: `app`.
+- **Cloud component** — *server-side logic* with no UI of its own, running in the platform's
+  cloud and triggered by an app or an automation to do work on the project's data — e.g.
+  convert a file (IFC→fragments, point cloud→tiles), generate a report, run a calculation.
+  Choose this when the goal is processing/automation, not a screen. Template: `cloud-component`.
+
+Steps 0–2 are identical for both; they diverge only at `create` (step 3) and how you run them
+(step 4). This guide marks **[app]** / **[component]** where they differ.
+
 ## 0. Prerequisites (check, don't assume)
 
 - **Node.js ≥ 18** and **npm** — verify with `node -v`.
@@ -36,39 +52,57 @@ first: the next step's install pulls the private `@thatopen-platform/*-beta` pac
 `create` uses your logged-in token to write an authenticated `.npmrc` so that install can
 resolve them. No npm account or manual npm token is involved.
 
-## 3. Scaffold a beta app
+## 3. Scaffold a beta project
 
+**[app]**
 ```bash
 thatopen create my-app --beta
 cd my-app
 ```
 
-`--beta` is required for now: the bundled viewer uses engine APIs that currently live only
-in the beta libraries (public engine support lands with the October release). `create`
-configures private beta access from your platform token and runs `npm install` for you.
+**[component]**
+```bash
+thatopen create my-component -t cloud-component --beta
+cd my-component
+```
+
+`--beta` is required for now (the templates use engine APIs that currently live only in the
+beta libraries; public support lands with the October release). `create` configures private
+beta access from your platform token and runs `npm install` for you. The **app** scaffold is
+a complete working viewer; the **cloud-component** scaffold is a `main()` entry point plus a
+`declarations.json` (the parameters the component accepts) — read its `README.md`, which
+explains the exactly-four globals the cloud engine injects (do NOT import them) and how to
+read/write the project's data.
 
 ## 4. Run it
 
+**[app]**
 ```bash
 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.
 
-This 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.
+**[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.
 
 ## 5. Then build — read the in-project agent guide
 
-The scaffold is a real app, not a blank page. **Before changing anything**, open and follow:
+The scaffold is real, working code — a complete viewer **[app]** or a runnable `main()`
+**[component]** — not a blank page. **Before changing anything**, open and follow:
 
 ```
 node_modules/@thatopen/services/resources/AGENTS.md
 ```
 
-(The scaffolded project's own `AGENTS.md` points here too.) It is the canonical guide: it
-indexes every platform built-in, the client API, the CLI, and the engine / UI example sets.
-Load those indexes before writing code. **All UI must be built with Lit + `@thatopen/ui`
-(`BUI`)** — consult the design system before writing any UI. Run the app first, then extend
-it; don't rebuild a viewer from scratch.
+(The scaffolded project's own `AGENTS.md` points here too.) It is the canonical guide for
+**both** project types: it indexes every platform built-in, the client API, the CLI, and the
+engine / UI example sets. Load those indexes before writing code. For an **app**, **all UI
+must be built with Lit + `@thatopen/ui` (`BUI`)** — consult the design system first. Run the
+scaffold first, then extend it; don't rebuild from scratch.
 
 ## 6. Publish (when ready)
 
@@ -76,7 +110,9 @@ it; don't rebuild a viewer from scratch.
 npm run publish
 ```
 
-Builds the app, zips it (`dist/bundle.zip`), and uploads a new version to the platform.
+Builds, zips (`dist/bundle.zip`), and uploads a new version to the platform — for an **app**
+or a **component** (a component also ships its `declarations.json`). Re-run it any time to
+push a new version.
 
 ---
 

package/package.json

@@ -15,7 +15,7 @@
     "access": "public"
   },
   "private": false,
-  "version": "0.3.3",
+  "version": "0.3.4",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",
   "types": "dist/index.d.ts",

package/src/cli/templates/app/src/main.ts

@@ -45,6 +45,14 @@ async function main() {
   // visibility/inspect toolbar (see below), so the platform default would just
   // duplicate it.
   const viewerEl = document.createElement("top-viewer");
+  // Frame the viewport to match the side panels (BUI bim-panel host = 1px border
+  // + 0.75rem radius). top-viewer's host is already overflow:hidden, so the
+  // radius clips the canvas corners; border-box keeps the 1px inside the grid
+  // area. Done here (not in top-viewer) so the CDE's top-file-viewer, which draws
+  // its own frame, never double-borders.
+  viewerEl.style.border = "1px solid var(--bim-ui_bg-contrast-20)";
+  viewerEl.style.borderRadius = "0.75rem";
+  viewerEl.style.boxSizing = "border-box";
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const app = document.createElement("top-app") as any;
@@ -169,8 +177,8 @@ async function main() {
   // Navigation gizmo is now baked into <top-viewer> (setupViewerTools), so the
   // app no longer mounts it. (Cascade: the rest of the overlay tools follow.)
 
-  // Auto-load one model (top-viewer's world wires fragments→scene itself).
-  void autoLoadFirstModel(components, client);
+  // No auto-load: the viewer opens empty. Users add models from the Assets
+  // (files) panel — top-models-list loads the .frag they pick into the world.
 }
 
 /** Resolves with the first world once it exists (top-viewer creates it async). */
@@ -188,36 +196,4 @@ function firstWorld(worlds: any): Promise<any> {
   });
 }
 
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-async function autoLoadFirstModel(components: OBC.Components, client: any) {
-  const fragments = components.get(OBC.FragmentsManager);
-  const projectId: string | undefined = client?.context?.projectId;
-  if (!projectId) {
-    console.warn("[a2] no projectId — skipping auto-load");
-    return;
-  }
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const items = (await client.listFiles({ projectId })) as any[];
-    const frags = items.filter((it) =>
-      (it.name ?? "").toLowerCase().endsWith(".frag"),
-    );
-    const frag =
-      frags.find((it) => (it.name ?? "").toLowerCase().includes("bloxhub")) ??
-      frags[0];
-    if (!frag) {
-      console.warn("[a2] no .frag in project to auto-load");
-      return;
-    }
-    const resp = await client.downloadFile(String(frag._id));
-    const buffer = await resp.arrayBuffer();
-    await fragments.core.load(buffer, { modelId: String(frag._id) });
-    await fragments.core.update(true);
-    console.log("[a2] auto-loaded model:", frag.name);
-  } catch (error) {
-    console.warn("[a2] auto-load failed", error);
-  }
-}
-
 main().catch(console.error);