@thatopen/services 0.5.0 → 0.7.0

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";

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

@@ -1,170 +1,170 @@
-/* MD
-  ## topics-panel
-  ---
-  Every coordination workflow needs a place to track issues, clashes, and
-  action items against a 3D model — who's responsible, what still needs
-  review, and where in the model it actually is. Building that from scratch
-  means a BCF-compatible data model, a form, comment threads, viewpoint
-  capture/navigation, document links, and a persistence layer — all before a
-  single issue gets tracked.
-
-  `topics-panel` is a ready-made web component that delivers exactly that. It
-  connects to `@thatopen/components`' `BCFTopics` (and `Viewpoints`)
-  automatically and manages the entire workflow: the topic list with search,
-  full CRUD on topics/comments/viewpoints/documents, camera navigation,
-  BCF export/import, and auto-save — without you writing any UI code.
-
-  This tutorial covers the prerequisites before mounting the panel; dropping
-  it into a `top-app` layout alongside a 3D viewer; and a 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 topics/issues 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, TopicsManager } 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-topics-panel>` itself. Without it the
-     element is unknown to the browser and renders as an empty box.
-
-  2. **`TopicsManager.init(client)` must have resolved.** It configures
-     `BCFTopics` (version, author, assignable users — all from real project
-     data) and loads whatever BCF was previously saved for this project. The
-     panel mounts into an empty state and never catches up on its own if you
-     load a BCF after the fact; 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();
-
-// The `{ uuid }` entries tell the platform which built-ins to register for
-// this app — one per built-in beyond the "stable" `@thatopen/components`
-// globals passed as the first argument.
-const { components } = (await client.setup(
-  { OBC, OBF, BUI, THREE, FRAGS },
-  { uuid: UIManager.uuid },
-  { uuid: TopicsManager.uuid },
-)) as { components: OBC.Components };
-
-components.get(UIManager).init();
-
-// init must resolve before top-app (and therefore topics-panel) mounts.
-await components.get(TopicsManager).init(client);
-
-/* MD
-  ### 🖥️ Wiring the panel
-
-  Add `topics-panel` as a named area in `app.elements` and reference it in
-  your layout template, next to the 3D viewer — the panel controls the
-  camera and element selection directly in the scene when you click a
-  viewpoint.
-*/
-
-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 };
-};
-
-app.elements = {
-  viewer: () => html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
-  topics: () => html`<top-topics-panel></top-topics-panel>`,
-};
-
-app.layouts = {
-  main: {
-    label: "Main",
-    icon: "solar:3d-square-bold",
-    template: `"viewer topics" 1fr / 1fr 30rem`,
-  },
-};
-
-app.layout = "main";
-
-const container = document.getElementById("that-open-app") ?? document.body;
-container.appendChild(app);
-document.body.style.margin = "0";
-
-/* MD
-  ### 🤖 What's handled automatically
-
-  **`TopicsManager`** resolves `Viewpoints.world` in the background once
-  `top-viewer` creates it (which only happens after `top-app` finishes
-  mounting), including backfilling it onto viewpoints that were restored
-  from the saved BCF before the world existed — `Viewpoint.go()` would
-  otherwise silently no-op for every one of them. Nothing to wire yourself.
-
-  **`topics-panel`**, once mounted, takes ownership of the following without
-  any further code from you:
-
-  **Full topic CRUD** — create, edit, and delete (behind a confirmation
-  modal) topics with title, type, status, priority, assigned-to, due date,
-  and stage. The list shows a search bar, a type badge next to each title,
-  and switches to an empty state with a "New topic" call-to-action when
-  there's nothing yet.
-
-  **Comments** — add, edit, and delete (with confirmation) threaded comments
-  on a topic, each optionally linked to a specific viewpoint via a clickable
-  tag that jumps the camera there.
-
-  **Viewpoints** — capture the current camera + selection as a new
-  viewpoint, browse them in a snapshot carousel, and click one to fly the
-  camera and re-apply its selection highlight. Navigation is a no-op (not an
-  error) if no models are loaded yet, so a stray click can't fly the camera
-  toward nothing.
-
-  **Documents** — link files from the project's CDE storage (searchable tree
-  picker), unlink from just this topic or hard-delete everywhere it's
-  referenced, and download. Linking is genuinely shared: the same file
-  referenced by two topics reuses one document entry instead of duplicating
-  it.
-
-  **BCF export/import** — export the selected topics (or, with nothing
-  selected, the whole project) to a single `.bcf` file named after the
-  project or the lone topic's title. Import merges a `.bcf` into the current
-  project instead of replacing it; a topic sharing a GUID with an existing
-  one is overwritten (treated as an update from elsewhere, not a conflict).
-
-  **Persistence** — every mutation is auto-saved through `top-app`'s
-  `projectStorageContext`, debounced per file so rapid edits collapse into
-  one upload. A small "Saving..." indicator (shared with any other built-in
-  using the same context, e.g. `clashes-panel`) reflects the real
-  debounce-then-upload cycle: just the icon while pending, the full pill
-  while actually uploading.
-
-  **Author/assignee names** — emails resolve to real names (with an
-  initials avatar) via `top-app`'s `projectDataContext`, which already
-  covers the project owner as well as regular collaborators — no separate
-  lookup needed.
-
-  **Cross-panel awareness** — the list updates live even when a topic is
-  created somewhere else entirely (e.g. `clashes-panel`'s "Create topic from
-  clash"), including the empty-state → list transition if this was the
-  project's first topic.
-*/
+/* MD
+  ## topics-panel
+  ---
+  Every coordination workflow needs a place to track issues, clashes, and
+  action items against a 3D model — who's responsible, what still needs
+  review, and where in the model it actually is. Building that from scratch
+  means a BCF-compatible data model, a form, comment threads, viewpoint
+  capture/navigation, document links, and a persistence layer — all before a
+  single issue gets tracked.
+
+  `topics-panel` is a ready-made web component that delivers exactly that. It
+  connects to `@thatopen/components`' `BCFTopics` (and `Viewpoints`)
+  automatically and manages the entire workflow: the topic list with search,
+  full CRUD on topics/comments/viewpoints/documents, camera navigation,
+  BCF export/import, and auto-save — without you writing any UI code.
+
+  This tutorial covers the prerequisites before mounting the panel; dropping
+  it into a `top-app` layout alongside a 3D viewer; and a 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 topics/issues 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, TopicsManager } 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-topics-panel>` itself. Without it the
+     element is unknown to the browser and renders as an empty box.
+
+  2. **`TopicsManager.init(client)` must have resolved.** It configures
+     `BCFTopics` (version, author, assignable users — all from real project
+     data) and loads whatever BCF was previously saved for this project. The
+     panel mounts into an empty state and never catches up on its own if you
+     load a BCF after the fact; 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();
+
+// The `{ uuid }` entries tell the platform which built-ins to register for
+// this app — one per built-in beyond the "stable" `@thatopen/components`
+// globals passed as the first argument.
+const { components } = (await client.setup(
+  { OBC, OBF, BUI, THREE, FRAGS },
+  { uuid: UIManager.uuid },
+  { uuid: TopicsManager.uuid },
+)) as { components: OBC.Components };
+
+components.get(UIManager).init();
+
+// init must resolve before top-app (and therefore topics-panel) mounts.
+await components.get(TopicsManager).init(client);
+
+/* MD
+  ### 🖥️ Wiring the panel
+
+  Add `topics-panel` as a named area in `app.elements` and reference it in
+  your layout template, next to the 3D viewer — the panel controls the
+  camera and element selection directly in the scene when you click a
+  viewpoint.
+*/
+
+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 };
+};
+
+app.elements = {
+  viewer: () => html`<top-viewer><top-viewer-tools></top-viewer-tools></top-viewer>`,
+  topics: () => html`<top-topics-panel></top-topics-panel>`,
+};
+
+app.layouts = {
+  main: {
+    label: "Main",
+    icon: "solar:3d-square-bold",
+    template: `"viewer topics" 1fr / 1fr 30rem`,
+  },
+};
+
+app.layout = "main";
+
+const container = document.getElementById("that-open-app") ?? document.body;
+container.appendChild(app);
+document.body.style.margin = "0";
+
+/* MD
+  ### 🤖 What's handled automatically
+
+  **`TopicsManager`** resolves `Viewpoints.world` in the background once
+  `top-viewer` creates it (which only happens after `top-app` finishes
+  mounting), including backfilling it onto viewpoints that were restored
+  from the saved BCF before the world existed — `Viewpoint.go()` would
+  otherwise silently no-op for every one of them. Nothing to wire yourself.
+
+  **`topics-panel`**, once mounted, takes ownership of the following without
+  any further code from you:
+
+  **Full topic CRUD** — create, edit, and delete (behind a confirmation
+  modal) topics with title, type, status, priority, assigned-to, due date,
+  and stage. The list shows a search bar, a type badge next to each title,
+  and switches to an empty state with a "New topic" call-to-action when
+  there's nothing yet.
+
+  **Comments** — add, edit, and delete (with confirmation) threaded comments
+  on a topic, each optionally linked to a specific viewpoint via a clickable
+  tag that jumps the camera there.
+
+  **Viewpoints** — capture the current camera + selection as a new
+  viewpoint, browse them in a snapshot carousel, and click one to fly the
+  camera and re-apply its selection highlight. Navigation is a no-op (not an
+  error) if no models are loaded yet, so a stray click can't fly the camera
+  toward nothing.
+
+  **Documents** — link files from the project's CDE storage (searchable tree
+  picker), unlink from just this topic or hard-delete everywhere it's
+  referenced, and download. Linking is genuinely shared: the same file
+  referenced by two topics reuses one document entry instead of duplicating
+  it.
+
+  **BCF export/import** — export the selected topics (or, with nothing
+  selected, the whole project) to a single `.bcf` file named after the
+  project or the lone topic's title. Import merges a `.bcf` into the current
+  project instead of replacing it; a topic sharing a GUID with an existing
+  one is overwritten (treated as an update from elsewhere, not a conflict).
+
+  **Persistence** — every mutation is auto-saved through `top-app`'s
+  `projectStorageContext`, debounced per file so rapid edits collapse into
+  one upload. A small "Saving..." indicator (shared with any other built-in
+  using the same context, e.g. `clashes-panel`) reflects the real
+  debounce-then-upload cycle: just the icon while pending, the full pill
+  while actually uploading.
+
+  **Author/assignee names** — emails resolve to real names (with an
+  initials avatar) via `top-app`'s `projectDataContext`, which already
+  covers the project owner as well as regular collaborators — no separate
+  lookup needed.
+
+  **Cross-panel awareness** — the list updates live even when a topic is
+  created somewhere else entirely (e.g. `clashes-panel`'s "Create topic from
+  clash"), including the empty-state → list transition if this was the
+  project's first topic.
+*/