@thatopen/services 0.3.15 → 0.3.16

package/src/built-in/UIManager/src/clashes-panel/example.ts

@@ -1,160 +1,183 @@
-/* MD
-  ## 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.
-
-  `clashes-panel` is a ready-made web component that delivers exactly that. It
-  connects to `ClashesManager` automatically and manages the entire review
-  workflow: the detection matrix, the clash table with status filters, sphere
-  markers and element highlights in the viewer, run controls with live progress,
-  and a loading skeleton while fresh data reloads after a run completes.
-
-  This tutorial covers the prerequisites before mounting the panel; dropping it
-  into a `top-app` layout alongside a 3D viewer; and a detailed breakdown of
-  everything the panel handles automatically so you know what you do not need to
-  implement yourself.
-
-  By the end, you'll have a fully working clash-review environment running in
-  your application with a single line of markup.
-*/
-
-import { html } from "lit";
-import * as THREE from "three";
-import * as OBC from "@thatopen/components";
-import * as OBF from "@thatopen/components-front";
-import * as FRAGS from "@thatopen/fragments";
-import * as BUI from "@thatopen/ui";
-import { PlatformClient, UIManager, ClashesManager } from "@thatopen/services";
-import type { App } from "../app/index";
-
-
-/* MD
-  ### ✅ Prerequisites
-
-  Two conditions must be met before the panel mounts:
-
-  1. **`UIManager` must be in the setup call.** It registers all platform web
-     components, including `<top-clashes-panel>` itself. Without it the element is
-     unknown to the browser and renders as an empty box.
-
-  2. **`ClashesManager.init(client)` must have resolved.** The panel reads all
-     its initial data from the manager in `connectedCallback`. If `init` has not
-     finished, the panel mounts into an empty state and never catches up because
-     it only subscribes to change events — it does not poll.
-
-  Both conditions are naturally satisfied when you call `init` before appending
-  `top-app` to the document, which is the pattern shown below.
-*/
-
-const client = PlatformClient.fromPlatformContext();
-
-const { components } = (await client.setup(
-  { OBC, OBF, BUI, THREE, FRAGS },
-  { uuid: UIManager.uuid },
-  { uuid: ClashesManager.uuid },
-)) as { components: OBC.Components };
-
-components.get(UIManager).init();
-
-// init must resolve before top-app (and therefore clashes-panel) mounts.
-await components.get(ClashesManager).init(client);
-
-/* MD
-  ### 🖥️ Wiring the panel
-
-  Add `clashes-panel` as a named area in `app.elements` and reference it in your
-  layout template. A side-by-side layout with the 3D viewer is the most natural
-  arrangement — the panel controls markers and highlights directly in the scene.
-*/
-
-const app = document.createElement("top-app") as unknown as App;
-
-app.setup = (waitUntil) => {
-  waitUntil(
-    (async () => {
-      const fragments = components.get(OBC.FragmentsManager);
-      const workerUrl = await FRAGS.FragmentsModels.getWorker();
-      fragments.init(await FRAGS.toClassicWorker(workerUrl), { classicWorker: true });
-    })(),
-    "Fragments Core",
-  );
-
-  waitUntil(
-    (async () => {
-      const loader = components.get(OBC.IfcLoader);
-      await loader.setup();
-    })(),
-    "IFC Loader",
-  );
-
-  return { components, client };
-};
-
-app.elements = {
-  viewer:  () => html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
-  clashes: () => html`<top-clashes-panel></top-clashes-panel>`,
-};
-
-app.layouts = {
-  main: {
-    label:    "Main",
-    icon:     "solar:3d-square-bold",
-    template: `"viewer clashes" 1fr / 1fr 22rem`,
-  },
-};
-
-app.layout = "main";
-
-const container = document.getElementById("that-open-app") ?? document.body;
-container.appendChild(app);
-document.body.style.margin = "0";
-
-/* MD
-  ### 🤖 What the panel manages automatically
-
-  Once mounted, `clashes-panel` takes ownership of the following without any
-  further code from you:
-
-  **Data synchronization** — the panel subscribes to every `ClashesManager`
-  event (`onJobsChanged`, `onRunsChanged`, `onClashesChanged`,
-  `onClashStatusChanged`, `onQueriesChanged`, `onRunningJobsChanged`) and keeps
-  its tables in sync. Changes made programmatically through the manager API are
-  reflected in the panel immediately.
-
-  **Run lifecycle** — a progress callout appears as soon as a run starts
-  (`onRunProgress`), updates its percentage and message in real time, and
-  disappears when the run completes or errors. If a run was already in progress
-  when the page loaded, the panel calls `reconnectIfRunning` automatically when
-  the user opens that job.
-
-  **Post-run reload skeleton** — after a successful run the manager reloads clash
-  data from storage. During that window (`onReloadingChanged = true`) the panel
-  replaces its entire content with an animated skeleton so the user is never left
-  looking at stale results that appear final.
-
-  **Sphere markers** — entering a job view places colored spheres in the 3D scene
-  at each clash location, transformed from IFC world space to viewer space.
-  Selecting a clash in the table zooms the camera, ghosts unrelated elements, and
-  re-focuses the markers on the selection. Leaving the job view removes all
-  markers and restores the full scene.
-
-  **Element highlights** — element A is highlighted green and element B red for
-  every new or active clash in the current job. Selecting a single clash refines
-  the highlight to that pair only. Clearing the selection or changing status
-  restores the full job highlight.
-
-  **Model awareness** — the panel tracks which fragment models are currently
-  loaded in the scene. Markers and highlights are activated only when the relevant
-  models are present, and are cleaned up automatically if a model is disposed
-  while the panel is open.
-
-  **Save indicator** — a subtle indicator appears while auto-save is in progress
-  (`onSaveStart`) and disappears once the write confirms (`onSaveComplete`), so
-  users know their status changes and query edits are persisted.
-
-  **Disconnection cleanup** — when the panel is removed from the DOM it calls
-  `hideMarkers` and `clearClashHighlight` on the manager, leaving the 3D scene
-  clean regardless of what was selected at the time.
-*/
+/* MD
+  ## 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.
+
+  `clashes-panel` is a ready-made web component that delivers exactly that. It
+  connects to `ClashesManager` automatically and manages the entire review
+  workflow: the detection matrix, the clash table with status filters, sphere
+  markers and element highlights in the viewer, run controls with live progress,
+  a loading skeleton while fresh data reloads after a run completes, and
+  turning a cluster of clashes into a tracked BCF topic in one click.
+
+  This tutorial covers the prerequisites before mounting the panel; dropping it
+  into a `top-app` layout alongside a 3D viewer; and a detailed breakdown of
+  everything the panel handles automatically so you know what you do not need to
+  implement yourself.
+
+  By the end, you'll have a fully working clash-review environment running in
+  your application with a single line of markup.
+*/
+
+import { html } from "lit";
+import * as THREE from "three";
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+import * as FRAGS from "@thatopen/fragments";
+import * as BUI from "@thatopen/ui";
+import { PlatformClient, UIManager, ClashesManager, TopicsManager } from "@thatopen/services";
+import type { App } from "../app/index";
+
+
+/* MD
+  ### ✅ Prerequisites
+
+  Three conditions must be met before the panel mounts:
+
+  1. **`UIManager` must be in the setup call.** It registers all platform web
+     components, including `<top-clashes-panel>` itself. Without it the element is
+     unknown to the browser and renders as an empty box.
+
+  2. **`ClashesManager.init(client)` must have resolved.** The panel reads all
+     its initial data from the manager in `connectedCallback`. If `init` has not
+     finished, the panel mounts into an empty state and never catches up because
+     it only subscribes to change events — it does not poll.
+
+  3. **`TopicsManager.init(client)` must have resolved too.** The panel's
+     "Create topic" button (turns a selection of clashes into a tracked BCF
+     topic) needs `Viewpoints.world` set to capture the camera, and `BCFTopics`
+     configured with `version: "3"` for the clash↔topic link to survive a
+     reload — `TopicsManager.init` is what sets both up. Skip it and the button
+     still works, but the topic it creates is subtly broken.
+
+  All three are naturally satisfied when you call both `init`s before appending
+  `top-app` to the document, which is the pattern shown below.
+*/
+
+const client = PlatformClient.fromPlatformContext();
+
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: UIManager.uuid },
+  { uuid: ClashesManager.uuid },
+  { uuid: TopicsManager.uuid },
+)) as { components: OBC.Components };
+
+components.get(UIManager).init();
+
+// Both inits must resolve before top-app (and therefore clashes-panel) mounts.
+// Independent of each other — safe to run in parallel.
+await Promise.all([
+  components.get(ClashesManager).init(client),
+  components.get(TopicsManager).init(client),
+]);
+
+/* MD
+  ### 🖥️ Wiring the panel
+
+  Add `clashes-panel` as a named area in `app.elements` and reference it in your
+  layout template. A side-by-side layout with the 3D viewer is the most natural
+  arrangement — the panel controls markers and highlights directly in the scene.
+*/
+
+const app = document.createElement("top-app") as unknown as App;
+
+app.setup = (waitUntil) => {
+  waitUntil(
+    (async () => {
+      const fragments = components.get(OBC.FragmentsManager);
+      const workerUrl = await FRAGS.FragmentsModels.getWorker();
+      fragments.init(await FRAGS.toClassicWorker(workerUrl), { classicWorker: true });
+    })(),
+    "Fragments Core",
+  );
+
+  waitUntil(
+    (async () => {
+      const loader = components.get(OBC.IfcLoader);
+      await loader.setup();
+    })(),
+    "IFC Loader",
+  );
+
+  return { components, client };
+};
+
+app.elements = {
+  viewer:  () => html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
+  clashes: () => html`<top-clashes-panel></top-clashes-panel>`,
+};
+
+app.layouts = {
+  main: {
+    label:    "Main",
+    icon:     "solar:3d-square-bold",
+    template: `"viewer clashes" 1fr / 1fr 22rem`,
+  },
+};
+
+app.layout = "main";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";
+
+/* MD
+  ### 🤖 What the panel manages automatically
+
+  Once mounted, `clashes-panel` takes ownership of the following without any
+  further code from you:
+
+  **Data synchronization** — the panel subscribes to every `ClashesManager`
+  event (`onJobsChanged`, `onRunsChanged`, `onClashesChanged`,
+  `onClashStatusChanged`, `onQueriesChanged`, `onRunningJobsChanged`) and keeps
+  its tables in sync. Changes made programmatically through the manager API are
+  reflected in the panel immediately.
+
+  **Run lifecycle** — a progress callout appears as soon as a run starts
+  (`onRunProgress`), updates its percentage and message in real time, and
+  disappears when the run completes or errors. If a run was already in progress
+  when the page loaded, the panel calls `reconnectIfRunning` automatically when
+  the user opens that job.
+
+  **Post-run reload skeleton** — after a successful run the manager reloads clash
+  data from storage. During that window (`onReloadingChanged = true`) the panel
+  replaces its entire content with an animated skeleton so the user is never left
+  looking at stale results that appear final.
+
+  **Sphere markers** — entering a job view places colored spheres in the 3D scene
+  at each clash location, transformed from IFC world space to viewer space.
+  Selecting a clash in the table zooms the camera, ghosts unrelated elements, and
+  re-focuses the markers on the selection. Leaving the job view removes all
+  markers and restores the full scene.
+
+  **Element highlights** — element A is highlighted green and element B red for
+  every new or active clash in the current job. Selecting a single clash refines
+  the highlight to that pair only. Clearing the selection or changing status
+  restores the full job highlight.
+
+  **Model awareness** — the panel tracks which fragment models are currently
+  loaded in the scene. Markers and highlights are activated only when the relevant
+  models are present, and are cleaned up automatically if a model is disposed
+  while the panel is open.
+
+  **Create topic from clash** — selecting one or more clashes and clicking
+  "Create topic" builds a BCF topic with an auto-generated title/description
+  summarizing the pair(s) and a viewpoint capturing the same selection and
+  red/green coloring shown in the table. The link back to the source clash(es)
+  is recorded separately so it survives independently of the topic's own BCF
+  fields. The button is disabled while the camera is still flying to a
+  selection or no models are loaded yet, so it can't fire on an empty scene.
+
+  **Save indicator** — every persisted change (clashes, queries, matrices,
+  topics created from a selection) routes through `top-app`'s shared
+  `projectStorageContext`, the same one `topics-panel` uses. A small indicator
+  reflects the real debounce-then-upload cycle: just an icon while a save is
+  pending, the full "Saving..." pill once the upload is actually in flight.
+
+  **Disconnection cleanup** — when the panel is removed from the DOM it calls
+  `hideMarkers` and `clearClashHighlight` on the manager, leaving the 3D scene
+  clean regardless of what was selected at the time.
+*/

package/src/built-in/UIManager/src/models-list/example.ts

@@ -1,122 +1,122 @@
-/* MD
-  ## 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.
-
-  This tutorial covers the two extension points. First, registering a custom loader for a file extension — either imperatively with `registerLoader(ext, fn)` or up front via the `loaders` property; a loader receives `(fileId, ctx)` where `ctx` carries the engine (`components`), the platform `client`, and per-file alignment persistence. Second, overriding the IFC to fragments `converter` — omit it to use the built-in default (which drives the project's IfcFragmenter cloud component, resolved by its stable name — see `adrs/resolve-ifc-fragmenter-by-stable-name.md`), or provide one to run conversion elsewhere.
-
-  A behaviour worth knowing: registering a loader does NOT control whether a file shows up in the tree — the tree always mirrors the project's real storage folders, so an unrecognized file is still listed as long as it's a source (IFC/LAS/PLY) or derivative (`.frag`/`.potree`/`.splat`) extension; the loaders registry only decides whether a file's row gets a load action or none.
-
-  Known gaps (intentionally deferred, not forgotten): file upload and the base-model/auto-coordinate settings aren't ported, so `allow-upload` is currently a no-op. Everything else per-file is here, including editable attach/detach via a picker — MINUS delete, dropped on purpose. See `models-list/legacy-example.ts` + `models-list/impl.ts` for the retired implementation those gaps would be ported from.
-
-  By the end you'll have a files tree that knows how to load a custom format and how to run a custom IFC conversion, with the panel's UI untouched.
-*/
-
-import { html } from "lit";
-import * as THREE from "three";
-import * as OBC from "@thatopen/components";
-import * as OBF from "@thatopen/components-front";
-import * as FRAGS from "@thatopen/fragments";
-import * as BUI from "@thatopen/ui";
-import { PlatformClient, UIManager } from "@thatopen/services";
-import type { App } from "../app/index";
-import type { ModelsListV2 } from "./src/v2/models-list-panel";
-
-
-const client = PlatformClient.fromPlatformContext();
-
-// UIManager registers every platform web component (top-app, top-viewer,
-// top-models-list, …) before the DOM renders.
-const { components } = (await client.setup(
-  { OBC, OBF, BUI, THREE, FRAGS },
-  { uuid: UIManager.uuid },
-)) as { components: OBC.Components };
-
-components.get(UIManager).init();
-
-const app = document.createElement("top-app") as unknown as App;
-
-app.setup = (waitUntil) => {
-  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 };
-};
-
-// One stable <top-models-list>, kept by reference so re-rendering top-app
-// reuses it. The loaders are read LIVE, so registration can happen at any time.
-const modelsList = document.createElement("top-models-list") as ModelsListV2;
-
-// ── Extension point 1: a custom loader, keyed by file extension ──────────────
-// A ModelLoader is `(fileId, ctx) => void | Promise<void>`. The panel calls it
-// when the user loads a file whose extension matches. `ctx` gives you everything
-// you need: { name, ext, components, client, getAlignment, setAlignment }. Do
-// whatever it takes to put the file in the scene — fetch it via the client,
-// parse it, and add geometry to a world from `components`.
-modelsList.registerLoader("xyz", async (fileId, ctx) => {
-  // const buffer = await ctx.client
-  //   .downloadFile(fileId)
-  //   .then((r: Response) => r.arrayBuffer());
-  // ...parse `buffer` and add it to the world here...
-  // Persist/restore a placement matrix across reloads via the panel's app-data:
-  //   const saved = ctx.getAlignment(fileId);
-  //   ctx.setAlignment(fileId, matrix.toArray());
-  console.log(`[xyz loader] would load "${ctx.name}" (${fileId})`, ctx.components);
-});
-
-// Equivalent declarative form — hand the whole registry over at once:
-//   modelsList.loaders = { xyz: async (fileId, ctx) => { ... } };
-//
-// Registering a loader for an extension gives its files a load action here —
-// but doesn't control visibility (see the note above). For a CONVERT-style
-// action — e.g. a PLY that runs a PLY→3D-tiles cloud component then views the
-// result — register a RICH entry so the button reads correctly:
-//   modelsList.registerLoader("ply", {
-//     label: "Generate 3D tiles",
-//     icon: "mdi:cube-scan",
-//     fn: async (fileId, ctx) => {
-//       // const { executionId } = await ctx.client.executeComponent(...);
-//       // ...poll until done, then open the produced tileset...
-//     },
-//   });
-
-// ── Extension point 2: override the IFC → fragments converter ────────────────
-// OMIT this to keep the built-in default (drives the project's IfcFragmenter
-// cloud component via the platform client). Provide it to run conversion
-// elsewhere / differently — the panel keeps the progress bar, reload-survival,
-// association and refresh; your converter just `start`s and is `poll`ed.
-modelsList.converter = {
-  async start(fileId) {
-    // kick off your conversion; return an execution id to poll
-    return `exec-${fileId}`;
-  },
-  async poll(executionId) {
-    // report progress; when done, hand back the produced .frag id
-    return { done: true, ok: true, fragId: "demo-frag", message: "Converted" };
-  },
-};
-
-// Mount the panel into a one-area layout. (In a real app it sits beside a
-// top-viewer so loaded models have a world to render into.)
-app.elements = {
-  files: () => html`${modelsList}`,
-};
-app.layouts = {
-  main: {
-    label: "Files",
-    icon: "mdi:folder-multiple-outline",
-    template: `"files" 1fr / 1fr`,
-  },
-};
-app.layout = "main";
-
-const container = document.getElementById("that-open-app") ?? document.body;
-container.appendChild(app);
-document.body.style.margin = "0";
+/* MD
+  ## 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.
+
+  This tutorial covers the two extension points. First, registering a custom loader for a file extension — either imperatively with `registerLoader(ext, fn)` or up front via the `loaders` property; a loader receives `(fileId, ctx)` where `ctx` carries the engine (`components`), the platform `client`, and per-file alignment persistence. Second, overriding the IFC to fragments `converter` — omit it to use the built-in default (which drives the project's IfcFragmenter cloud component, resolved by its stable name — see `adrs/resolve-ifc-fragmenter-by-stable-name.md`), or provide one to run conversion elsewhere.
+
+  A behaviour worth knowing: registering a loader does NOT control whether a file shows up in the tree — the tree always mirrors the project's real storage folders, so an unrecognized file is still listed as long as it's a source (IFC/LAS/PLY) or derivative (`.frag`/`.potree`/`.splat`) extension; the loaders registry only decides whether a file's row gets a load action or none.
+
+  Known gaps (intentionally deferred, not forgotten): file upload and the base-model/auto-coordinate settings aren't ported, so `allow-upload` is currently a no-op. Everything else per-file is here, including editable attach/detach via a picker — MINUS delete, dropped on purpose. See `models-list/legacy-example.ts` + `models-list/impl.ts` for the retired implementation those gaps would be ported from.
+
+  By the end you'll have a files tree that knows how to load a custom format and how to run a custom IFC conversion, with the panel's UI untouched.
+*/
+
+import { html } from "lit";
+import * as THREE from "three";
+import * as OBC from "@thatopen/components";
+import * as OBF from "@thatopen/components-front";
+import * as FRAGS from "@thatopen/fragments";
+import * as BUI from "@thatopen/ui";
+import { PlatformClient, UIManager } from "@thatopen/services";
+import type { App } from "../app/index";
+import type { ModelsListV2 } from "./src/v2/models-list-panel";
+
+
+const client = PlatformClient.fromPlatformContext();
+
+// UIManager registers every platform web component (top-app, top-viewer,
+// top-models-list, …) before the DOM renders.
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: UIManager.uuid },
+)) as { components: OBC.Components };
+
+components.get(UIManager).init();
+
+const app = document.createElement("top-app") as unknown as App;
+
+app.setup = (waitUntil) => {
+  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 };
+};
+
+// One stable <top-models-list>, kept by reference so re-rendering top-app
+// reuses it. The loaders are read LIVE, so registration can happen at any time.
+const modelsList = document.createElement("top-models-list") as ModelsListV2;
+
+// ── Extension point 1: a custom loader, keyed by file extension ──────────────
+// A ModelLoader is `(fileId, ctx) => void | Promise<void>`. The panel calls it
+// when the user loads a file whose extension matches. `ctx` gives you everything
+// you need: { name, ext, components, client, getAlignment, setAlignment }. Do
+// whatever it takes to put the file in the scene — fetch it via the client,
+// parse it, and add geometry to a world from `components`.
+modelsList.registerLoader("xyz", async (fileId, ctx) => {
+  // const buffer = await ctx.client
+  //   .downloadFile(fileId)
+  //   .then((r: Response) => r.arrayBuffer());
+  // ...parse `buffer` and add it to the world here...
+  // Persist/restore a placement matrix across reloads via the panel's app-data:
+  //   const saved = ctx.getAlignment(fileId);
+  //   ctx.setAlignment(fileId, matrix.toArray());
+  console.log(`[xyz loader] would load "${ctx.name}" (${fileId})`, ctx.components);
+});
+
+// Equivalent declarative form — hand the whole registry over at once:
+//   modelsList.loaders = { xyz: async (fileId, ctx) => { ... } };
+//
+// Registering a loader for an extension gives its files a load action here —
+// but doesn't control visibility (see the note above). For a CONVERT-style
+// action — e.g. a PLY that runs a PLY→3D-tiles cloud component then views the
+// result — register a RICH entry so the button reads correctly:
+//   modelsList.registerLoader("ply", {
+//     label: "Generate 3D tiles",
+//     icon: "mdi:cube-scan",
+//     fn: async (fileId, ctx) => {
+//       // const { executionId } = await ctx.client.executeComponent(...);
+//       // ...poll until done, then open the produced tileset...
+//     },
+//   });
+
+// ── Extension point 2: override the IFC → fragments converter ────────────────
+// OMIT this to keep the built-in default (drives the project's IfcFragmenter
+// cloud component via the platform client). Provide it to run conversion
+// elsewhere / differently — the panel keeps the progress bar, reload-survival,
+// association and refresh; your converter just `start`s and is `poll`ed.
+modelsList.converter = {
+  async start(fileId) {
+    // kick off your conversion; return an execution id to poll
+    return `exec-${fileId}`;
+  },
+  async poll(executionId) {
+    // report progress; when done, hand back the produced .frag id
+    return { done: true, ok: true, fragId: "demo-frag", message: "Converted" };
+  },
+};
+
+// Mount the panel into a one-area layout. (In a real app it sits beside a
+// top-viewer so loaded models have a world to render into.)
+app.elements = {
+  files: () => html`${modelsList}`,
+};
+app.layouts = {
+  main: {
+    label: "Files",
+    icon: "mdi:folder-multiple-outline",
+    template: `"files" 1fr / 1fr`,
+  },
+};
+app.layout = "main";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";