@thatopen/services 0.3.1 → 0.3.3

package/README.md

@@ -2,6 +2,9 @@
 
 Client library and CLI for building BIM apps and cloud components on [That Open Platform](https://platform.thatopen.com). Apps run inside the platform's browser environment; cloud components run server-side and can be triggered from any app.
 
+> **Using an AI assistant?** Point it at this single file and it can take you from nothing to a running app:
+> → [`docs/ai-quickstart.md`](https://raw.githubusercontent.com/ThatOpen/engine_services/main/docs/ai-quickstart.md)
+
 ## Quick Start
 
 ### 1. Install the CLI

package/dist/built-in/index.d.ts

@@ -80,8 +80,6 @@ export type CDEMachineState = {
     kind: "idle";
 } | {
     kind: "loading";
-} | {
-    kind: "uploading";
 } | {
     kind: "preparing";
     files: CDEFile[];
@@ -356,6 +354,22 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
         files?: CDEFile[];
         folder?: ItemFolder;
     }>;
+    readonly onUploadStarted: OBC.Event<{
+        count: number;
+    }>;
+    readonly onIfcConversionStarted: OBC.Event<{
+        file: CDEFile;
+    }>;
+    readonly onIfcConversionProgress: OBC.Event<{
+        file: CDEFile;
+        progress: number;
+    }>;
+    readonly onIfcConversionCompleted: OBC.Event<{
+        file: CDEFile;
+        success: boolean;
+        error?: string;
+    }>;
+    readonly conversionProgress: Map<string, number>;
     enabled: boolean;
     projectName: string;
     missingMetadataPlaceholder: string;
@@ -363,6 +377,7 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
     visibleColumns: Set<string>;
     ctx?: CDEContext;
     private _machineState;
+    private _activeUploads;
     private _showArchived;
     private _preArchivedViewMode;
     private _archivedFiles;
@@ -465,6 +480,20 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
         file: CDEFile;
         existing: CDEFile;
     }[];
+    resolveViewFile(file: CDEFile): CDEFile;
+    private _saveConversionIndex;
+    private _loadConversionIndex;
+    private _resumePendingConversions;
+    /** Cached id of the IfcFragmenter component, resolved by name for this session. */
+    private _ifcFragmenterId?;
+    /**
+     * Resolves the platform IFC→FRAG cloud component's id by its stable name
+     * (`IfcFragmenter`) within the current project, so it works across dev/prod
+     * without a hardcoded id. Cached for the session. Returns `undefined` if no
+     * such component is available in the project.
+     */
+    private _resolveIfcFragmenterId;
+    private _triggerIfcConversions;
     uploadFiles(files: File[], folderId?: string | null, options?: {
         forceNew?: boolean;
     }): Promise<void>;

package/dist/cli.js

@@ -8028,8 +8028,8 @@ async function configureBetaNpmrc(dir) {
 }
 const loginCommand = new Command2("login").description("Authenticate with the ThatOpen platform").option("--token <token>", "Access token from the dashboard").option(
   "--api-url <url>",
-  "API URL",
-  "https://dev.platform.thatopen.com"
+  "API URL (defaults to production; pass https://dev.platform.thatopen.com for the dev environment)",
+  "https://platform.thatopen.com"
 ).option(
   "--local",
   "Save credentials to local .thatopen file instead of global config"
@@ -8099,13 +8099,13 @@ const createCommand = new Command2("create").argument("<project-name>", 'Name of
     console.error(`Unknown template "${opts.template}". Available: ${TEMPLATES.join(", ")}`);
     process.exit(1);
   }
-  if (template === "app" && !opts.beta) {
+  if (!opts.beta) {
     console.error(
-      `The "app" template currently requires the beta engine libraries.
+      `Non-beta projects are not available yet.
 
   thatopen create ${projectName} --beta
 
-Public (non-beta) engine support is coming with the October release.`
+The templates currently require the beta engine libraries. Public (non-beta) engine support is coming with the October release.`
     );
     process.exit(1);
   }

package/docs/ai-quickstart.md

@@ -0,0 +1,89 @@
+# That Open Platform — AI Quick Start (zero to a running app)
+
+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
+`@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
+> derives private beta-registry access from the platform token automatically.
+
+---
+
+## 0. Prerequisites (check, don't assume)
+
+- **Node.js ≥ 18** and **npm** — verify with `node -v`.
+- A **That Open Platform API token**. The user creates it themselves:
+  → **https://platform.thatopen.com/dashboard/data → API Tokens → create → copy.**
+  Ask the user to paste it. **Never print it back, never write it into a file, never commit it.**
+
+## 1. Install the CLI
+
+```bash
+npm install -g @thatopen/services@latest
+```
+
+## 2. Log in (do this BEFORE creating the project)
+
+Get the token from the platform dashboard — **https://platform.thatopen.com/dashboard/data**
+→ **API Tokens** → create → copy. Ask the user to paste it, then run:
+
+```bash
+thatopen login --token <platform-token>
+```
+
+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
+resolve them. No npm account or manual npm token is involved.
+
+## 3. Scaffold a beta 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.
+
+## 4. Run it
+
+```bash
+npm run dev
+```
+
+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.
+
+## 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:
+
+```
+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.
+
+## 6. Publish (when ready)
+
+```bash
+npm run publish
+```
+
+Builds the app, zips it (`dist/bundle.zip`), and uploads a new version to the platform.
+
+---
+
+## Rules for you, the assistant
+
+- **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.
+- The scaffold already works — **extend it, don't replace it.**

package/docs/cli/create.md

@@ -17,12 +17,13 @@ thatopen create .             # scaffold into the current directory
 - `--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.
+- `--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
-thatopen create my-app -t cloud-component
 thatopen create my-app --beta
+thatopen create my-app -t cloud-component --beta
 thatopen create . --beta
 ```

package/docs/cli/login.md

@@ -7,7 +7,7 @@ description: "Authenticate with the ThatOpen platform by validating an access to
 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)
+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**
@@ -21,7 +21,7 @@ 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`.
+- `--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:**

package/docs/cli/paths.json

@@ -21,7 +21,7 @@
   },
   {
     "path": "docs/cli/serve.md",
-    "description": "Start a local dev server for a browser app. Uses esbuild in watch mode and serves the IIFE bundle on port 4000 with SSE live reload. To connect: open the project on dev.platform.thatopen.com, click the Local App icon, then Get Started."
+    "description": "Start a local dev server for a browser app. Uses esbuild in watch mode and serves the IIFE bundle on port 4000 with SSE live reload. To connect: open the project on platform.thatopen.com, click the Local App icon, then Get Started."
   },
   {
     "path": "docs/cli/swap.md",

package/docs/cli/serve.md

@@ -1,5 +1,5 @@
 ---
-description: "Start a local dev server for a browser app. Uses esbuild in watch mode and serves the IIFE bundle on port 4000 with SSE live reload. To connect: open the project on dev.platform.thatopen.com, click the Local App icon, then Get Started."
+description: "Start a local dev server for a browser app. Uses esbuild in watch mode and serves the IIFE bundle on port 4000 with SSE live reload. To connect: open the project on platform.thatopen.com, click the Local App icon, then Get Started."
 ---
 
 ## thatopen serve
@@ -31,7 +31,7 @@ thatopen serve --port 4321
 
 **Connecting the platform to your local server:**
 
-1. Go to [https://dev.platform.thatopen.com](https://dev.platform.thatopen.com) and open a project (create one first if needed).
+1. Go to [https://platform.thatopen.com](https://platform.thatopen.com) and open a project (create one first if needed).
 2. In the top right corner, click the **Local App** icon.
 3. Click **Get Started**.
 
@@ -39,5 +39,5 @@ The platform loads the bundle from port 4000 and renders the app inside the proj
 
 The resulting URL follows this pattern:
 ```
-https://dev.platform.thatopen.com/dashboard/projects/{projectId}/apps/local-app
+https://platform.thatopen.com/dashboard/projects/{projectId}/apps/local-app
 ```

package/package.json

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

package/src/built-in/index.ts

@@ -83,8 +83,6 @@ export type CDEMachineState = {
     kind: "idle";
 } | {
     kind: "loading";
-} | {
-    kind: "uploading";
 } | {
     kind: "preparing";
     files: CDEFile[];
@@ -360,6 +358,22 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
         files?: CDEFile[];
         folder?: ItemFolder;
     }>;
+    readonly onUploadStarted: OBC.Event<{
+        count: number;
+    }>;
+    readonly onIfcConversionStarted: OBC.Event<{
+        file: CDEFile;
+    }>;
+    readonly onIfcConversionProgress: OBC.Event<{
+        file: CDEFile;
+        progress: number;
+    }>;
+    readonly onIfcConversionCompleted: OBC.Event<{
+        file: CDEFile;
+        success: boolean;
+        error?: string;
+    }>;
+    readonly conversionProgress: Map<string, number>;
     enabled: boolean;
     projectName: string;
     missingMetadataPlaceholder: string;
@@ -367,6 +381,7 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
     visibleColumns: Set<string>;
     ctx?: CDEContext;
     private _machineState;
+    private _activeUploads;
     private _showArchived;
     private _preArchivedViewMode;
     private _archivedFiles;
@@ -469,6 +484,20 @@ declare class _CDEManager extends OBC.Component implements OBC.Transitionable<CD
         file: CDEFile;
         existing: CDEFile;
     }[];
+    resolveViewFile(file: CDEFile): CDEFile;
+    private _saveConversionIndex;
+    private _loadConversionIndex;
+    private _resumePendingConversions;
+    /** Cached id of the IfcFragmenter component, resolved by name for this session. */
+    private _ifcFragmenterId?;
+    /**
+     * Resolves the platform IFC→FRAG cloud component's id by its stable name
+     * (`IfcFragmenter`) within the current project, so it works across dev/prod
+     * without a hardcoded id. Cached for the session. Returns `undefined` if no
+     * such component is available in the project.
+     */
+    private _resolveIfcFragmenterId;
+    private _triggerIfcConversions;
     uploadFiles(files: File[], folderId?: string | null, options?: {
         forceNew?: boolean;
     }): Promise<void>;

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

@@ -1,37 +1,37 @@
-import { PlatformClient, ProjectData } from "@thatopen/services";
-
-// ─── A2 migration shim ───────────────────────────────────────────────────────
-// Pre-A2 the platform `AppManager` built-in held the platform `client` +
-// `projectData`, reached via `components.get(AppManager)`. Juan removed
-// AppManager (consolidated into UIManager / top-app). top-app now owns that
-// state and exposes it via lit contexts — but a few non-lit call sites
-// (CloudRunner, data-table-panel, app-info-section) just need `.client` /
-// `.projectData` synchronously. This tiny module holds them, set once from
-// main.ts, and keeps `getAppManager(...)` returning the same `{ client,
-// projectData }` shape those call sites expect.
-
-let _client: PlatformClient | undefined;
-let _projectData: ProjectData | undefined;
-
-/** Called once from main.ts after the platform client (and projectData) exist. */
-export const setAppContext = (
-  client: PlatformClient,
-  projectData?: ProjectData,
-) => {
-  _client = client;
-  _projectData = projectData;
-};
-
-/**
- * Back-compat accessor mirroring the old `components.get(AppManager)` surface
- * the remaining call sites use (`.client` / `.projectData`). The `components`
- * arg is ignored — kept only for signature compatibility with existing callers.
- */
-export const getAppManager = (_components?: unknown) => ({
-  get client() {
-    return _client;
-  },
-  get projectData() {
-    return _projectData;
-  },
-});
+import { PlatformClient, ProjectData } from "@thatopen/services";
+
+// ─── A2 migration shim ───────────────────────────────────────────────────────
+// Pre-A2 the platform `AppManager` built-in held the platform `client` +
+// `projectData`, reached via `components.get(AppManager)`. Juan removed
+// AppManager (consolidated into UIManager / top-app). top-app now owns that
+// state and exposes it via lit contexts — but a few non-lit call sites
+// (CloudRunner, data-table-panel, app-info-section) just need `.client` /
+// `.projectData` synchronously. This tiny module holds them, set once from
+// main.ts, and keeps `getAppManager(...)` returning the same `{ client,
+// projectData }` shape those call sites expect.
+
+let _client: PlatformClient | undefined;
+let _projectData: ProjectData | undefined;
+
+/** Called once from main.ts after the platform client (and projectData) exist. */
+export const setAppContext = (
+  client: PlatformClient,
+  projectData?: ProjectData,
+) => {
+  _client = client;
+  _projectData = projectData;
+};
+
+/**
+ * Back-compat accessor mirroring the old `components.get(AppManager)` surface
+ * the remaining call sites use (`.client` / `.projectData`). The `components`
+ * arg is ignored — kept only for signature compatibility with existing callers.
+ */
+export const getAppManager = (_components?: unknown) => ({
+  get client() {
+    return _client;
+  },
+  get projectData() {
+    return _projectData;
+  },
+});

package/src/cli/templates/app/src/assets/tool-placeholder.ts

@@ -1,50 +1,50 @@
-/**
- * Empty-state illustration for the helper panel (from
- * "Frame 691314571.svg" — a translucent stacked-cards glyph with a check badge).
- * Stored as a string and served as a data URI so it needs no import/build
- * config. Theme-safe: all fills are translucent white/#F8F8F8 over transparent,
- * so it reads correctly on the dark bg-base card.
- */
-export const toolPlaceholderSvg = `<svg width="157" height="156" viewBox="0 0 157 156" fill="none" xmlns="http://www.w3.org/2000/svg">
-<g clip-path="url(#clip0_12378_11440)">
-<mask id="mask0_12378_11440" style="mask-type:alpha" maskUnits="userSpaceOnUse" x="0" y="0" width="157" height="156">
-<ellipse cx="78.5" cy="78" rx="78.5" ry="78" fill="url(#paint0_radial_12378_11440)"/>
-</mask>
-<g mask="url(#mask0_12378_11440)">
-<path d="M2.33321 94.9001H34.2999C38.7803 94.9001 41.0205 94.9001 42.7318 94.0281C44.2371 93.2611 45.4609 92.0373 46.2279 90.532C47.0999 88.8207 47.0999 86.5805 47.0999 82.1V50.4353C47.0999 48.1467 47.0999 47.0024 46.8058 45.948C46.5453 45.0139 46.1172 44.135 45.5423 43.3541C44.8933 42.4726 43.9922 41.7672 42.1902 40.3565L28.9883 30.0212C27.6995 29.0123 27.0551 28.5078 26.3403 28.1493C25.7061 27.8311 25.0324 27.5988 24.3369 27.4583C23.5531 27.3 22.7347 27.3 21.098 27.3H2.33321C-2.14722 27.3 -4.38743 27.3 -6.09872 28.172C-7.60402 28.939 -8.82786 30.1628 -9.59485 31.6681C-10.4668 33.3794 -10.4668 35.6196 -10.4668 40.1V82.1001C-10.4668 86.5805 -10.4668 88.8207 -9.59485 90.532C-8.82786 92.0373 -7.60402 93.2611 -6.09872 94.0281C-4.38743 94.9001 -2.14722 94.9001 2.33321 94.9001Z" fill="#F8F8F8" fill-opacity="0.08" style="mix-blend-mode:luminosity"/>
-<path d="M2.33321 94.9001H34.2999C38.7803 94.9001 41.0205 94.9001 42.7318 94.0281C44.2371 93.2611 45.4609 92.0373 46.2279 90.532C47.0999 88.8207 47.0999 86.5805 47.0999 82.1V50.4353C47.0999 48.1467 47.0999 47.0024 46.8058 45.948C46.5453 45.0139 46.1172 44.135 45.5423 43.3541C44.8933 42.4726 43.9922 41.7672 42.1902 40.3565L28.9883 30.0212C27.6995 29.0123 27.0551 28.5078 26.3403 28.1493C25.7061 27.8311 25.0324 27.5988 24.3369 27.4583C23.5531 27.3 22.7347 27.3 21.098 27.3H2.33321C-2.14722 27.3 -4.38743 27.3 -6.09872 28.172C-7.60402 28.939 -8.82786 30.1628 -9.59485 31.6681C-10.4668 33.3794 -10.4668 35.6196 -10.4668 40.1V82.1001C-10.4668 86.5805 -10.4668 88.8207 -9.59485 90.532C-8.82786 92.0373 -7.60402 93.2611 -6.09872 94.0281C-4.38743 94.9001 -2.14722 94.9001 2.33321 94.9001Z" stroke="white" stroke-opacity="0.15" stroke-width="1.5"/>
-<path d="M154.667 61.0999H122.7C118.22 61.0999 115.98 61.0999 114.268 61.9719C112.763 62.7389 111.539 63.9627 110.772 65.468C109.9 67.1793 109.9 69.4195 109.9 73.9V105.565C109.9 107.853 109.9 108.998 110.194 110.052C110.455 110.986 110.883 111.865 111.458 112.646C112.107 113.527 113.008 114.233 114.81 115.644L128.012 125.979C129.3 126.988 129.945 127.492 130.66 127.851C131.294 128.169 131.968 128.401 132.663 128.542C133.447 128.7 134.265 128.7 135.902 128.7H154.667C159.147 128.7 161.387 128.7 163.099 127.828C164.604 127.061 165.828 125.837 166.595 124.332C167.467 122.621 167.467 120.38 167.467 115.9V73.8999C167.467 69.4195 167.467 67.1793 166.595 65.468C165.828 63.9627 164.604 62.7389 163.099 61.9719C161.387 61.0999 159.147 61.0999 154.667 61.0999Z" fill="#F8F8F8" fill-opacity="0.08" style="mix-blend-mode:luminosity"/>
-<path d="M84.758 182H116.725C121.205 182 123.445 182 125.157 181.128C126.662 180.361 127.886 179.137 128.653 177.632C129.525 175.921 129.525 173.68 129.525 169.2V137.535C129.525 135.247 129.525 134.102 129.231 133.048C128.97 132.114 128.542 131.235 127.967 130.454C127.318 129.573 126.417 128.867 124.615 127.456L111.413 117.121C110.124 116.112 109.48 115.608 108.765 115.249C108.131 114.931 107.457 114.699 106.762 114.558C105.978 114.4 105.16 114.4 103.523 114.4H84.758C80.2776 114.4 78.0374 114.4 76.3261 115.272C74.8208 116.039 73.5969 117.263 72.83 118.768C71.958 120.479 71.958 122.72 71.958 127.2V169.2C71.958 173.68 71.958 175.921 72.83 177.632C73.5969 179.137 74.8208 180.361 76.3261 181.128C78.0374 182 80.2776 182 84.758 182Z" fill="#F8F8F8" fill-opacity="0.08" style="mix-blend-mode:luminosity"/>
-</g>
-<path d="M63.2502 111.583H93.7502C98.2306 111.583 100.471 111.583 102.182 110.711C103.687 109.944 104.911 108.721 105.678 107.215C106.55 105.504 106.55 103.264 106.55 98.7833V67.3691C106.55 65.1068 106.55 63.9756 106.262 62.9315C106.007 62.0065 105.588 61.1349 105.024 60.3584C104.387 59.482 103.503 58.7763 101.735 57.3651L89.0157 47.2126C87.7173 46.1763 87.0681 45.6581 86.3455 45.2897C85.7044 44.9628 85.0221 44.7239 84.3172 44.5794C83.5226 44.4166 82.6919 44.4166 81.0307 44.4166H63.2502C58.7698 44.4166 56.5296 44.4166 54.8183 45.2886C53.313 46.0556 52.0891 47.2794 51.3221 48.7847C50.4502 50.496 50.4502 52.7362 50.4502 57.2166V98.7833C50.4502 103.264 50.4502 105.504 51.3221 107.215C52.0891 108.721 53.313 109.944 54.8183 110.711C56.5296 111.583 58.7698 111.583 63.2502 111.583Z" fill="#F8F8F8" fill-opacity="0.05" style="mix-blend-mode:luminosity"/>
-<g filter="url(#filter0_d_12378_11440)">
-<path d="M62.6 109H94.4C97.7603 109 99.4405 109 100.724 108.346C101.853 107.771 102.771 106.853 103.346 105.724C104 104.44 104 102.76 104 99.4V67.0766C104 65.3954 104 64.5548 103.788 63.7778C103.599 63.0894 103.29 62.4402 102.873 61.8605C102.404 61.2062 101.751 60.677 100.445 59.6184L87.5178 49.1419C86.5385 48.3482 86.0489 47.9514 85.5023 47.6691C85.0175 47.4187 84.5007 47.2355 83.9664 47.1248C83.364 47 82.7338 47 81.4733 47H62.6C59.2397 47 57.5595 47 56.2761 47.654C55.1471 48.2292 54.2292 49.1471 53.654 50.2761C53 51.5595 53 53.2397 53 56.6V99.4C53 102.76 53 104.44 53.654 105.724C54.2292 106.853 55.1471 107.771 56.2761 108.346C57.5595 109 59.2397 109 62.6 109Z" fill="#F8F8F8" fill-opacity="0.08" style="mix-blend-mode:luminosity"/>
-<path d="M62.6 109H94.4C97.7603 109 99.4405 109 100.724 108.346C101.853 107.771 102.771 106.853 103.346 105.724C104 104.44 104 102.76 104 99.4V67.0766C104 65.3954 104 64.5548 103.788 63.7778C103.599 63.0894 103.29 62.4402 102.873 61.8605C102.404 61.2062 101.751 60.677 100.445 59.6184L87.5178 49.1419C86.5385 48.3482 86.0489 47.9514 85.5023 47.6691C85.0175 47.4187 84.5007 47.2355 83.9664 47.1248C83.364 47 82.7338 47 81.4733 47H62.6C59.2397 47 57.5595 47 56.2761 47.654C55.1471 48.2292 54.2292 49.1471 53.654 50.2761C53 51.5595 53 53.2397 53 56.6V99.4C53 102.76 53 104.44 53.654 105.724C54.2292 106.853 55.1471 107.771 56.2761 108.346C57.5595 109 59.2397 109 62.6 109Z" stroke="white" stroke-opacity="0.18" stroke-width="1.5"/>
-</g>
-<path d="M75.9031 85.0833C74.6481 85.0833 73.5803 84.6373 72.6998 83.7452C71.8192 82.8531 71.3789 81.7713 71.3789 80.5V75.5C71.3789 74.2286 71.8192 73.1468 72.6998 72.2548C73.5803 71.3627 74.6481 70.9166 75.9031 70.9166H80.8386C82.0936 70.9166 83.1613 71.3627 84.0419 72.2548C84.9225 73.1468 85.3628 74.2286 85.3628 75.5V80.5C85.3628 81.7713 84.9225 82.8531 84.0419 83.7452C83.1613 84.6373 82.0936 85.0833 80.8386 85.0833H75.9031ZM77.5483 79.2885L76.1721 77.8941C76.0582 77.7788 75.915 77.7198 75.7425 77.717C75.5702 77.7144 75.4244 77.7734 75.3051 77.8941C75.1859 78.015 75.1264 78.1613 75.1264 78.3333C75.1264 78.5052 75.1859 78.6516 75.3051 78.7725L77.0278 80.5177C77.1765 80.6682 77.35 80.7435 77.5483 80.7435C77.7465 80.7435 77.92 80.6682 78.0688 80.5177L81.7656 76.7725C81.8794 76.657 81.9377 76.512 81.9404 76.3373C81.943 76.1627 81.8848 76.015 81.7656 75.8941C81.6464 75.7734 81.5019 75.7131 81.3321 75.7131C81.1624 75.7131 81.0179 75.7734 80.8986 75.8941L77.5483 79.2885Z" fill="#F8F8F8" fill-opacity="0.85"/>
-</g>
-<defs>
-<filter id="filter0_d_12378_11440" x="20.25" y="14.25" width="116.5" height="143.5" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
-<feFlood flood-opacity="0" result="BackgroundImageFix"/>
-<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
-<feOffset dy="24"/>
-<feGaussianBlur stdDeviation="12"/>
-<feComposite in2="hardAlpha" operator="out"/>
-<feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.5 0"/>
-<feBlend mode="multiply" in2="BackgroundImageFix" result="effect1_dropShadow_12378_11440"/>
-<feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow_12378_11440" result="shape"/>
-</filter>
-<radialGradient id="paint0_radial_12378_11440" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(78.5 78) rotate(90) scale(78 78.5)">
-<stop stop-color="#D9D9D9"/>
-<stop offset="1" stop-color="#737373" stop-opacity="0"/>
-</radialGradient>
-<clipPath id="clip0_12378_11440">
-<rect width="157" height="156" fill="white"/>
-</clipPath>
-</defs>
-</svg>`;
-
-/** The illustration as a data URI, ready for an `<img src>`. */
-export const toolPlaceholderUri = `data:image/svg+xml;utf8,${encodeURIComponent(
-  toolPlaceholderSvg,
-)}`;
+/**
+ * Empty-state illustration for the helper panel (from
+ * "Frame 691314571.svg" — a translucent stacked-cards glyph with a check badge).
+ * Stored as a string and served as a data URI so it needs no import/build
+ * config. Theme-safe: all fills are translucent white/#F8F8F8 over transparent,
+ * so it reads correctly on the dark bg-base card.
+ */
+export const toolPlaceholderSvg = `<svg width="157" height="156" viewBox="0 0 157 156" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_12378_11440)">
+<mask id="mask0_12378_11440" style="mask-type:alpha" maskUnits="userSpaceOnUse" x="0" y="0" width="157" height="156">
+<ellipse cx="78.5" cy="78" rx="78.5" ry="78" fill="url(#paint0_radial_12378_11440)"/>
+</mask>
+<g mask="url(#mask0_12378_11440)">
+<path d="M2.33321 94.9001H34.2999C38.7803 94.9001 41.0205 94.9001 42.7318 94.0281C44.2371 93.2611 45.4609 92.0373 46.2279 90.532C47.0999 88.8207 47.0999 86.5805 47.0999 82.1V50.4353C47.0999 48.1467 47.0999 47.0024 46.8058 45.948C46.5453 45.0139 46.1172 44.135 45.5423 43.3541C44.8933 42.4726 43.9922 41.7672 42.1902 40.3565L28.9883 30.0212C27.6995 29.0123 27.0551 28.5078 26.3403 28.1493C25.7061 27.8311 25.0324 27.5988 24.3369 27.4583C23.5531 27.3 22.7347 27.3 21.098 27.3H2.33321C-2.14722 27.3 -4.38743 27.3 -6.09872 28.172C-7.60402 28.939 -8.82786 30.1628 -9.59485 31.6681C-10.4668 33.3794 -10.4668 35.6196 -10.4668 40.1V82.1001C-10.4668 86.5805 -10.4668 88.8207 -9.59485 90.532C-8.82786 92.0373 -7.60402 93.2611 -6.09872 94.0281C-4.38743 94.9001 -2.14722 94.9001 2.33321 94.9001Z" fill="#F8F8F8" fill-opacity="0.08" style="mix-blend-mode:luminosity"/>
+<path d="M2.33321 94.9001H34.2999C38.7803 94.9001 41.0205 94.9001 42.7318 94.0281C44.2371 93.2611 45.4609 92.0373 46.2279 90.532C47.0999 88.8207 47.0999 86.5805 47.0999 82.1V50.4353C47.0999 48.1467 47.0999 47.0024 46.8058 45.948C46.5453 45.0139 46.1172 44.135 45.5423 43.3541C44.8933 42.4726 43.9922 41.7672 42.1902 40.3565L28.9883 30.0212C27.6995 29.0123 27.0551 28.5078 26.3403 28.1493C25.7061 27.8311 25.0324 27.5988 24.3369 27.4583C23.5531 27.3 22.7347 27.3 21.098 27.3H2.33321C-2.14722 27.3 -4.38743 27.3 -6.09872 28.172C-7.60402 28.939 -8.82786 30.1628 -9.59485 31.6681C-10.4668 33.3794 -10.4668 35.6196 -10.4668 40.1V82.1001C-10.4668 86.5805 -10.4668 88.8207 -9.59485 90.532C-8.82786 92.0373 -7.60402 93.2611 -6.09872 94.0281C-4.38743 94.9001 -2.14722 94.9001 2.33321 94.9001Z" stroke="white" stroke-opacity="0.15" stroke-width="1.5"/>
+<path d="M154.667 61.0999H122.7C118.22 61.0999 115.98 61.0999 114.268 61.9719C112.763 62.7389 111.539 63.9627 110.772 65.468C109.9 67.1793 109.9 69.4195 109.9 73.9V105.565C109.9 107.853 109.9 108.998 110.194 110.052C110.455 110.986 110.883 111.865 111.458 112.646C112.107 113.527 113.008 114.233 114.81 115.644L128.012 125.979C129.3 126.988 129.945 127.492 130.66 127.851C131.294 128.169 131.968 128.401 132.663 128.542C133.447 128.7 134.265 128.7 135.902 128.7H154.667C159.147 128.7 161.387 128.7 163.099 127.828C164.604 127.061 165.828 125.837 166.595 124.332C167.467 122.621 167.467 120.38 167.467 115.9V73.8999C167.467 69.4195 167.467 67.1793 166.595 65.468C165.828 63.9627 164.604 62.7389 163.099 61.9719C161.387 61.0999 159.147 61.0999 154.667 61.0999Z" fill="#F8F8F8" fill-opacity="0.08" style="mix-blend-mode:luminosity"/>
+<path d="M84.758 182H116.725C121.205 182 123.445 182 125.157 181.128C126.662 180.361 127.886 179.137 128.653 177.632C129.525 175.921 129.525 173.68 129.525 169.2V137.535C129.525 135.247 129.525 134.102 129.231 133.048C128.97 132.114 128.542 131.235 127.967 130.454C127.318 129.573 126.417 128.867 124.615 127.456L111.413 117.121C110.124 116.112 109.48 115.608 108.765 115.249C108.131 114.931 107.457 114.699 106.762 114.558C105.978 114.4 105.16 114.4 103.523 114.4H84.758C80.2776 114.4 78.0374 114.4 76.3261 115.272C74.8208 116.039 73.5969 117.263 72.83 118.768C71.958 120.479 71.958 122.72 71.958 127.2V169.2C71.958 173.68 71.958 175.921 72.83 177.632C73.5969 179.137 74.8208 180.361 76.3261 181.128C78.0374 182 80.2776 182 84.758 182Z" fill="#F8F8F8" fill-opacity="0.08" style="mix-blend-mode:luminosity"/>
+</g>
+<path d="M63.2502 111.583H93.7502C98.2306 111.583 100.471 111.583 102.182 110.711C103.687 109.944 104.911 108.721 105.678 107.215C106.55 105.504 106.55 103.264 106.55 98.7833V67.3691C106.55 65.1068 106.55 63.9756 106.262 62.9315C106.007 62.0065 105.588 61.1349 105.024 60.3584C104.387 59.482 103.503 58.7763 101.735 57.3651L89.0157 47.2126C87.7173 46.1763 87.0681 45.6581 86.3455 45.2897C85.7044 44.9628 85.0221 44.7239 84.3172 44.5794C83.5226 44.4166 82.6919 44.4166 81.0307 44.4166H63.2502C58.7698 44.4166 56.5296 44.4166 54.8183 45.2886C53.313 46.0556 52.0891 47.2794 51.3221 48.7847C50.4502 50.496 50.4502 52.7362 50.4502 57.2166V98.7833C50.4502 103.264 50.4502 105.504 51.3221 107.215C52.0891 108.721 53.313 109.944 54.8183 110.711C56.5296 111.583 58.7698 111.583 63.2502 111.583Z" fill="#F8F8F8" fill-opacity="0.05" style="mix-blend-mode:luminosity"/>
+<g filter="url(#filter0_d_12378_11440)">
+<path d="M62.6 109H94.4C97.7603 109 99.4405 109 100.724 108.346C101.853 107.771 102.771 106.853 103.346 105.724C104 104.44 104 102.76 104 99.4V67.0766C104 65.3954 104 64.5548 103.788 63.7778C103.599 63.0894 103.29 62.4402 102.873 61.8605C102.404 61.2062 101.751 60.677 100.445 59.6184L87.5178 49.1419C86.5385 48.3482 86.0489 47.9514 85.5023 47.6691C85.0175 47.4187 84.5007 47.2355 83.9664 47.1248C83.364 47 82.7338 47 81.4733 47H62.6C59.2397 47 57.5595 47 56.2761 47.654C55.1471 48.2292 54.2292 49.1471 53.654 50.2761C53 51.5595 53 53.2397 53 56.6V99.4C53 102.76 53 104.44 53.654 105.724C54.2292 106.853 55.1471 107.771 56.2761 108.346C57.5595 109 59.2397 109 62.6 109Z" fill="#F8F8F8" fill-opacity="0.08" style="mix-blend-mode:luminosity"/>
+<path d="M62.6 109H94.4C97.7603 109 99.4405 109 100.724 108.346C101.853 107.771 102.771 106.853 103.346 105.724C104 104.44 104 102.76 104 99.4V67.0766C104 65.3954 104 64.5548 103.788 63.7778C103.599 63.0894 103.29 62.4402 102.873 61.8605C102.404 61.2062 101.751 60.677 100.445 59.6184L87.5178 49.1419C86.5385 48.3482 86.0489 47.9514 85.5023 47.6691C85.0175 47.4187 84.5007 47.2355 83.9664 47.1248C83.364 47 82.7338 47 81.4733 47H62.6C59.2397 47 57.5595 47 56.2761 47.654C55.1471 48.2292 54.2292 49.1471 53.654 50.2761C53 51.5595 53 53.2397 53 56.6V99.4C53 102.76 53 104.44 53.654 105.724C54.2292 106.853 55.1471 107.771 56.2761 108.346C57.5595 109 59.2397 109 62.6 109Z" stroke="white" stroke-opacity="0.18" stroke-width="1.5"/>
+</g>
+<path d="M75.9031 85.0833C74.6481 85.0833 73.5803 84.6373 72.6998 83.7452C71.8192 82.8531 71.3789 81.7713 71.3789 80.5V75.5C71.3789 74.2286 71.8192 73.1468 72.6998 72.2548C73.5803 71.3627 74.6481 70.9166 75.9031 70.9166H80.8386C82.0936 70.9166 83.1613 71.3627 84.0419 72.2548C84.9225 73.1468 85.3628 74.2286 85.3628 75.5V80.5C85.3628 81.7713 84.9225 82.8531 84.0419 83.7452C83.1613 84.6373 82.0936 85.0833 80.8386 85.0833H75.9031ZM77.5483 79.2885L76.1721 77.8941C76.0582 77.7788 75.915 77.7198 75.7425 77.717C75.5702 77.7144 75.4244 77.7734 75.3051 77.8941C75.1859 78.015 75.1264 78.1613 75.1264 78.3333C75.1264 78.5052 75.1859 78.6516 75.3051 78.7725L77.0278 80.5177C77.1765 80.6682 77.35 80.7435 77.5483 80.7435C77.7465 80.7435 77.92 80.6682 78.0688 80.5177L81.7656 76.7725C81.8794 76.657 81.9377 76.512 81.9404 76.3373C81.943 76.1627 81.8848 76.015 81.7656 75.8941C81.6464 75.7734 81.5019 75.7131 81.3321 75.7131C81.1624 75.7131 81.0179 75.7734 80.8986 75.8941L77.5483 79.2885Z" fill="#F8F8F8" fill-opacity="0.85"/>
+</g>
+<defs>
+<filter id="filter0_d_12378_11440" x="20.25" y="14.25" width="116.5" height="143.5" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix"/>
+<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+<feOffset dy="24"/>
+<feGaussianBlur stdDeviation="12"/>
+<feComposite in2="hardAlpha" operator="out"/>
+<feColorMatrix type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.5 0"/>
+<feBlend mode="multiply" in2="BackgroundImageFix" result="effect1_dropShadow_12378_11440"/>
+<feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow_12378_11440" result="shape"/>
+</filter>
+<radialGradient id="paint0_radial_12378_11440" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(78.5 78) rotate(90) scale(78 78.5)">
+<stop stop-color="#D9D9D9"/>
+<stop offset="1" stop-color="#737373" stop-opacity="0"/>
+</radialGradient>
+<clipPath id="clip0_12378_11440">
+<rect width="157" height="156" fill="white"/>
+</clipPath>
+</defs>
+</svg>`;
+
+/** The illustration as a data URI, ready for an `<img src>`. */
+export const toolPlaceholderUri = `data:image/svg+xml;utf8,${encodeURIComponent(
+  toolPlaceholderSvg,
+)}`;