@thatopen/services 0.3.10 → 0.3.12

package/dist/cli/commands/revit.d.ts

@@ -0,0 +1,9 @@
+import { Command } from 'commander';
+
+/**
+ * `thatopen revit ...` — Revit collaboration commands. They drive the local
+ * That Open Revit add-in (BT3): publish a shared central, join one, and sync.
+ * Auth comes from `thatopen login` (~/.thatopen/config.json) and is forwarded to
+ * the add-in, so the user never re-enters a token here.
+ */
+export declare const revitCommand: Command;

package/dist/cli/lib/revit-addin.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Talks to the local That Open Revit add-in (BT3). The add-in runs a
+ * 127.0.0.1 command listener and, on startup, writes its port + token to
+ * %APPDATA%\ThatOpen\revit-addin.json so the CLI can discover it. Revit-specific
+ * work (create central, create local, sync) happens inside the add-in; the CLI
+ * only drives it — the same "CLI does everything" model as the rest of `thatopen`.
+ */
+export interface AddinInfo {
+    port: number;
+    token: string;
+    pid: number;
+}
+export declare function discoverAddin(): AddinInfo;
+export declare function callAddin(cmd: string, body?: Record<string, unknown>): Promise<Record<string, unknown>>;
+/**
+ * Push the logged-in user's credentials (API url + token) into the add-in so it
+ * talks to the right account and environment (dev/prod). Idempotent; called
+ * before each command.
+ */
+export declare function configureAddin(apiUrl: string, accessToken: string): Promise<void>;

package/dist/cli.js

@@ -11672,6 +11672,106 @@ const swapCommand = new Command2("swap").description("Toggle between stable publ
     console.error("Failed to install dependencies. Run `npm install` manually.");
   }
 });
+function discoveryFile() {
+  const appData = process.env.APPDATA || require$$2.join(node_os.homedir(), "AppData", "Roaming");
+  return require$$2.join(appData, "ThatOpen", "revit-addin.json");
+}
+function discoverAddin() {
+  const file = discoveryFile();
+  if (!require$$3.existsSync(file)) {
+    console.error("");
+    console.error("  The That Open Revit add-in is not running.");
+    console.error("  Open Revit 2026 (with the add-in installed) and try again.");
+    console.error("  If it is not installed yet, install it and restart Revit.");
+    console.error("");
+    process.exit(1);
+  }
+  try {
+    return JSON.parse(require$$3.readFileSync(file, "utf-8"));
+  } catch {
+    console.error(`Could not read the add-in discovery file at ${file}.`);
+    process.exit(1);
+  }
+}
+async function callAddin(cmd, body = {}) {
+  const info = discoverAddin();
+  let res;
+  try {
+    res = await fetch(`http://127.0.0.1:${info.port}/${cmd}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Bt3-Token": info.token
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(6e5)
+    });
+  } catch {
+    console.error(
+      `Could not reach the Revit add-in on port ${info.port}. Is Revit still open?`
+    );
+    process.exit(1);
+  }
+  const text = await res.text();
+  let json;
+  try {
+    json = text ? JSON.parse(text) : {};
+  } catch {
+    json = { raw: text };
+  }
+  if (!res.ok || json.ok === false || json.error) {
+    const msg = json.error || json.err || res.statusText;
+    console.error(`Revit add-in error: ${msg}`);
+    process.exit(1);
+  }
+  return json;
+}
+async function configureAddin(apiUrl, accessToken) {
+  await callAddin("settings", {
+    base: apiUrl.replace(/\/$/, ""),
+    key: accessToken
+  });
+}
+const revitCommand = new Command2("revit").description(
+  "Revit collaboration — drive the That Open Revit add-in from the CLI"
+);
+async function connect() {
+  const cfg = requireResolvedConfig();
+  await configureAddin(cfg.apiUrl, cfg.accessToken);
+  return cfg;
+}
+revitCommand.command("status").description("Show the add-in status and the current project / central").action(async () => {
+  await connect();
+  const r = await callAddin("status");
+  console.log(JSON.stringify(r, null, 2));
+});
+revitCommand.command("publish-central").description("Turn a .rvt into a shared central and upload it to a project").requiredOption("--project <id>", "Platform project id").requiredOption("--doc <name>", "A short name for this central (e.g. tower-central)").requiredOption("--file <path>", "Absolute path to the source .rvt on this machine").action(async (opts) => {
+  await connect();
+  console.log(`Publishing "${opts.file}" as central "${opts.doc}"...`);
+  console.log("(Revit is enabling worksharing and saving the central — this can take a bit.)");
+  const r = await callAddin("publish-central", {
+    project: opts.project,
+    doc: opts.doc,
+    file: opts.file
+  });
+  console.log(`Published. Central: ${r.central} (version ${r.version}).`);
+  console.log(`Collaborators can now join with:`);
+  console.log(`  thatopen revit join --project ${opts.project} --doc ${opts.doc}`);
+});
+revitCommand.command("join").description("Download a shared central and create + open your local in Revit").requiredOption("--project <id>", "Platform project id").requiredOption("--doc <name>", "The central name to join (from whoever published it)").action(async (opts) => {
+  await connect();
+  console.log(`Joining "${opts.doc}"...`);
+  const r = await callAddin("join", { project: opts.project, doc: opts.doc });
+  console.log(`Joined. Your local was created and opened in Revit:`);
+  console.log(`  ${r.local}`);
+  console.log(`Model as usual, then run "thatopen revit sync" (or the "Sync to team" button).`);
+});
+revitCommand.command("sync").description("Synchronize your local with the team (queued, no divergence)").action(async () => {
+  await connect();
+  console.log("Syncing with the team...");
+  const r = await callAddin("sync");
+  console.log(`Synced.  v${r.verB} → v${r.verA}.`);
+});
 const pkg = JSON.parse(
   require$$3.readFileSync(require$$2.join(__dirname, "..", "package.json"), "utf-8")
 );
@@ -11699,4 +11799,5 @@ program.addCommand(serveCommand);
 program.addCommand(runCommand);
 program.addCommand(localServerCommand);
 program.addCommand(swapCommand);
+program.addCommand(revitCommand);
 program.parse(process.argv);

package/dist/cloud/LasToPotree.d.ts

@@ -0,0 +1,59 @@
+/** Execution params for the PointCloudConverter cloud component. */
+export interface LasToPotreeParams {
+    /** Action (SIMPLE|PLAN|BUILD|MERGE) */
+    action?: string;
+    /** LAS Point Cloud File ID */
+    fileId: string;
+    /** Split level (PLAN) */
+    K?: number;
+    /** Global grid JSON (BUILD/MERGE) */
+    grid?: string;
+    /** Cell name (BUILD) */
+    cell?: string;
+    /** Tile descriptors JSON (MERGE) */
+    tiles?: string;
+    /** Shared entry item id (BUILD/MERGE) */
+    entryId?: string;
+    /** Cell LAS shard hidden-file ids JSON (BUILD cell-file mode) */
+    shards?: string;
+}
+/**
+ * **PointCloudConverter** — Convert a LAS point cloud into a streamable Potree 2.0 octree.
+ *
+ * Reads an uploaded .las and builds a Potree 2.0 octree (metadata.json + hierarchy.bin + chopped octree pieces), published as one visible `.potree` entry whose hidden files hold the streamed chunks. The viewer byte-ranges those chunks, so a cloud opens without downloading it whole.
+ *
+ * The conversion itself lives in @thatopen-platform/components-beta (realityCapture); this component is only the platform I/O around it.
+ *
+ * Notes:
+ * - PLAN/BUILD/MERGE is a MEMORY workaround, not a speed feature — a billion-point cloud cannot fit in one worker. It needs many chained executions, and the platform's file API is whole-file-only (it ignores HTTP Range) at ~7 MB/s, so a 50GB / 2B-point cloud would spend ~9 hours just moving bytes, most of it network. Convert those OFFLINE and upload the .potree directly.
+ * - LAZ is not supported (it is compressed; the LASF signature check rejects it).
+ *
+ * Accepts `.las` → produces `.potree`.
+ *
+ * The execution's `resultMessage` carries the produced file id as
+ * `[potreeFileId=<id>]`; use {@link LasToPotree.parseResult} rather than re-inventing the regex.
+ */
+export declare const LasToPotree: {
+    /** The name the component is PROVISIONED under (what `listComponents({projectId})` returns). */
+    readonly publishedAs: "PointCloudConverter";
+    /** The repo/slug name it is published from. */
+    readonly slug: "las-to-potree";
+    /** Source extensions this converts. */
+    readonly accepts: readonly ["las"];
+    /** The extension it produces. */
+    readonly produces: "potree";
+    /** Valid `action` values. */
+    readonly actions: readonly ["SIMPLE", "PLAN", "BUILD", "MERGE"];
+    /** Hard limits — exceed them and the component FAILS with a message, it does not silently degrade. */
+    readonly limits: {
+        readonly SIMPLE: {
+            readonly maxPoints: 60000000;
+            readonly reason: "The whole cloud is held in one worker (~7-8GB, no disk). Above this the component FAILS with a clear message rather than dying silently.";
+        };
+    };
+    /**
+     * Pull the produced file id out of an execution's `resultMessage`.
+     * Returns null when the message carries none (e.g. the execution failed).
+     */
+    readonly parseResult: (resultMessage: string | undefined | null) => string | null;
+};

package/dist/cloud/SplatToFq.d.ts

@@ -0,0 +1,38 @@
+/** Execution params for the GaussianSplatConverter cloud component. */
+export interface SplatToFqParams {
+    /** Gaussian-Splat PLY File ID */
+    fileId: string;
+    /** Gaussian scale (metric calibration, default 1) */
+    gaussianScale?: string;
+}
+/**
+ * **GaussianSplatConverter** — Convert a 3D Gaussian Splat PLY into a streamable FQ LOD tree.
+ *
+ * Reads an uploaded .ply (plain INRIA 3DGS, or a PlayCanvas compressed.ply) and builds an octree of flat-quant (FQ) LOD nodes, published as one visible `.splat` entry whose hidden files hold the streamed nodes. The viewer fetches only the nodes it needs at the LOD it needs.
+ *
+ * Pure CPU: no GPU, no WebGPU, no WebP, no k-means — which is what lets it run in a cloud worker at all (the splat-transform toolchain it replaces requires WebGPU). The codec and converter live in @thatopen-platform/components-beta (realityCapture); this component is only the platform I/O around it.
+ *
+ * Notes:
+ * - gaussianScale is a METRIC CALIBRATION, not a quality knob: reality-capture splats are non-metric, so this scales them to real-world metres. It is PER-CAPTURE (alcardete calibrates to ~70) — default 1, and recalibrate in the viewer.
+ * - Spherical harmonics (view-dependent colour) are NOT carried: the FQ codec stores a flat RGBA per splat, and the renderer evaluates no SH. A capture therefore renders matte compared to its source. This is a known fidelity gap, not a bug.
+ *
+ * Accepts `.ply` → produces `.splat`.
+ *
+ * The execution's `resultMessage` carries the produced file id as
+ * `[splatFileId=<id>]`; use {@link SplatToFq.parseResult} rather than re-inventing the regex.
+ */
+export declare const SplatToFq: {
+    /** The name the component is PROVISIONED under (what `listComponents({projectId})` returns). */
+    readonly publishedAs: "GaussianSplatConverter";
+    /** The repo/slug name it is published from. */
+    readonly slug: "splat-to-fq";
+    /** Source extensions this converts. */
+    readonly accepts: readonly ["ply"];
+    /** The extension it produces. */
+    readonly produces: "splat";
+    /**
+     * Pull the produced file id out of an execution's `resultMessage`.
+     * Returns null when the message carries none (e.g. the execution failed).
+     */
+    readonly parseResult: (resultMessage: string | undefined | null) => string | null;
+};

package/dist/cloud/index.d.ts

@@ -0,0 +1,2 @@
+export * from './LasToPotree';
+export * from './SplatToFq';

package/docs/builtin/paths.json

@@ -1,86 +1,86 @@
-[
-  {
-    "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/ClashesManager/example.ts",
-    "description": "ClashesManager — Structural engineers and BIM coordinators routinely detect geometric clashes between disciplines — structural steel penetrating ductwork, pipes clashing with slabs — and need to track the status of each issue through resolution without leaving their BIM environment."
-  },
-  {
-    "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."
-  },
-  {
-    "path": "src/built-in/UIManager/src/clashes-panel/example.ts",
-    "description": "clashes-panel — BIM coordinators need a dedicated review environment where they can see all detected clashes, filter by status, navigate to each issue in the 3D viewer, and mark items as resolved — without writing any UI code themselves."
-  },
-  {
-    "path": "src/built-in/UIManager/src/models-list/example.ts",
-    "description": "top-models-list — top-models-list is the project files panel: it lists the project's files, uploads new ones, converts IFC to fragments, and loads `.frag` models into the 3D scene. Its loaders are PLUGGABLE — the panel owns the UI and the orchestration (progress, refresh, association), but the HOST decides how each file format is loaded, so you can teach it new formats without forking the built-in."
-  }
-]
+[
+  {
+    "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/ClashesManager/example.ts",
+    "description": "ClashesManager — Structural engineers and BIM coordinators routinely detect geometric clashes between disciplines — structural steel penetrating ductwork, pipes clashing with slabs — and need to track the status of each issue through resolution without leaving their BIM environment."
+  },
+  {
+    "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."
+  },
+  {
+    "path": "src/built-in/UIManager/src/clashes-panel/example.ts",
+    "description": "clashes-panel — BIM coordinators need a dedicated review environment where they can see all detected clashes, filter by status, navigate to each issue in the 3D viewer, and mark items as resolved — without writing any UI code themselves."
+  },
+  {
+    "path": "src/built-in/UIManager/src/models-list/example.ts",
+    "description": "top-models-list — top-models-list is the project's 3D-viewable-files tree: it mirrors the real storage folder structure, converts IFC to fragments, and loads `.frag`/`.potree`/`.splat` models into the 3D scene. Its loaders are PLUGGABLE — the panel owns the UI and the orchestration (progress, refresh, association), but the HOST decides how each extra file format is loaded, so you can teach it new formats without forking the built-in."
+  }
+]

package/docs/cloud/GaussianSplatConverter.md

@@ -0,0 +1,43 @@
+# GaussianSplatConverter
+
+Convert a 3D Gaussian Splat PLY into a streamable FQ LOD tree.
+
+Reads an uploaded .ply (plain INRIA 3DGS, or a PlayCanvas compressed.ply) and builds an octree of flat-quant (FQ) LOD nodes, published as one visible `.splat` entry whose hidden files hold the streamed nodes. The viewer fetches only the nodes it needs at the LOD it needs.
+
+Pure CPU: no GPU, no WebGPU, no WebP, no k-means — which is what lets it run in a cloud worker at all (the splat-transform toolchain it replaces requires WebGPU). The codec and converter live in @thatopen-platform/components-beta (realityCapture); this component is only the platform I/O around it.
+
+- **Accepts:** `.ply`
+- **Produces:** `.splat`
+- **Result:** the execution's `resultMessage` contains `[splatFileId=<id>]`
+
+## Actions
+
+| action | what it does | params |
+|---|---|---|
+| `default` | Convert the splat in one execution. | `fileId`, `gaussianScale` |
+
+## Params
+
+| id | type | label |
+|---|---|---|
+| `fileId` | string | Gaussian-Splat PLY File ID |
+| `gaussianScale` | string | Gaussian scale (metric calibration, default 1) |
+
+## Notes
+
+- gaussianScale is a METRIC CALIBRATION, not a quality knob: reality-capture splats are non-metric, so this scales them to real-world metres. It is PER-CAPTURE (alcardete calibrates to ~70) — default 1, and recalibrate in the viewer.
+- Spherical harmonics (view-dependent colour) are NOT carried: the FQ codec stores a flat RGBA per splat, and the renderer evaluates no SH. A capture therefore renders matte compared to its source. This is a known fidelity gap, not a bug.
+
+## Usage
+
+```ts
+import { SplatToFq } from "@thatopen/services";
+
+const { executionId } = await client.executeComponent(componentId, {
+  projectId,
+  fileId,
+});
+
+const exec = await client.getExecution(executionId);
+const producedFileId = SplatToFq.parseResult(exec.resultMessage);
+```

package/docs/cloud/PointCloudConverter.md

@@ -0,0 +1,53 @@
+# PointCloudConverter
+
+Convert a LAS point cloud into a streamable Potree 2.0 octree.
+
+Reads an uploaded .las and builds a Potree 2.0 octree (metadata.json + hierarchy.bin + chopped octree pieces), published as one visible `.potree` entry whose hidden files hold the streamed chunks. The viewer byte-ranges those chunks, so a cloud opens without downloading it whole.
+
+The conversion itself lives in @thatopen-platform/components-beta (realityCapture); this component is only the platform I/O around it.
+
+- **Accepts:** `.las`
+- **Produces:** `.potree`
+- **Result:** the execution's `resultMessage` contains `[potreeFileId=<id>]`
+
+## Actions
+
+| action | what it does | params |
+|---|---|---|
+| `SIMPLE` | Build the whole cloud in ONE execution. The default, and what you almost always want. | `fileId` |
+| `PLAN` | For clouds too big for SIMPLE: stream the source once and return an adaptive set of tiles that each fit a worker. | `fileId`, `K` |
+| `BUILD` | Build ONE tile of a PLAN as an aligned subtree of the global octree. Fired once per tile. | `grid`, `cell`, `entryId`, `shards` |
+| `MERGE` | Graft the built tiles into one global octree and publish the `.potree` entry. The tiles' bytes are referenced, never copied. | `grid`, `tiles`, `entryId` |
+
+## Params
+
+| id | type | label |
+|---|---|---|
+| `action` | string | Action (SIMPLE|PLAN|BUILD|MERGE) |
+| `fileId` | string | LAS Point Cloud File ID |
+| `K` | number | Split level (PLAN) |
+| `grid` | string | Global grid JSON (BUILD/MERGE) |
+| `cell` | string | Cell name (BUILD) |
+| `tiles` | string | Tile descriptors JSON (MERGE) |
+| `entryId` | string | Shared entry item id (BUILD/MERGE) |
+| `shards` | string | Cell LAS shard hidden-file ids JSON (BUILD cell-file mode) |
+
+## Notes
+
+- PLAN/BUILD/MERGE is a MEMORY workaround, not a speed feature — a billion-point cloud cannot fit in one worker. It needs many chained executions, and the platform's file API is whole-file-only (it ignores HTTP Range) at ~7 MB/s, so a 50GB / 2B-point cloud would spend ~9 hours just moving bytes, most of it network. Convert those OFFLINE and upload the .potree directly.
+- LAZ is not supported (it is compressed; the LASF signature check rejects it).
+
+## Usage
+
+```ts
+import { LasToPotree } from "@thatopen/services";
+
+const { executionId } = await client.executeComponent(componentId, {
+  projectId,
+  fileId,
+  action: "SIMPLE",
+});
+
+const exec = await client.getExecution(executionId);
+const producedFileId = LasToPotree.parseResult(exec.resultMessage);
+```