@thatopen/services 0.3.0 → 0.3.2

package/src/cli/templates/app/src/setups/right-sidebar.ts

@@ -1,178 +1,178 @@
-import * as BUI from "@thatopen/ui";
-
-/**
- * Mounts several panels as SEPARATE cards stacked vertically on the RIGHT,
- * together spanning the full viewport height. One right-docked `bim-grid
- * floating` holds one row per region (heights split by `grow`); the floating
- * grid's built-in 1rem gap shows between the cards, and its empty "rest" column
- * clicks through to the model. Each region is its own `bim-panel` (own
- * header/border), so they read as distinct cards — not one card with a divider.
- *
- * Each panel element should be `height: 100%` so it fills its row and scrolls
- * internally when its content is tall.
- *
- * @param container the viewport element to overlay
- * @param regions the panels to stack, top to bottom
- * @returns the floating grid element (already appended to the container)
- */
-export interface StackRegion {
-  /** The panel element for this region. */
-  element: HTMLElement;
-  /** Relative height share (CSS grid `fr`). Defaults to 1 (equal split). */
-  grow?: number;
-}
-
-export const rightStack = (container: HTMLElement, regions: StackRegion[]) => {
-  // ── Collapse toggle (mirror of the left files panel's) ─────────
-  // A bare chevron in its own thin grid column in the gutter, just OUTSIDE the
-  // cards (to their left). Collapsing swaps the grid layout to drop the card
-  // columns entirely; the chevron column stays. When collapsed the chevron sits
-  // inset from the right edge (the grid's 1rem padding), so it stays in view.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let gridEl: any = null;
-  let collapsed = false;
-
-  const [toggle, toggleUpdate] = BUI.Component.create<
-    HTMLElement,
-    { collapsed: boolean }
-  >(
-    (s) => BUI.html`
-      <div
-        style="
-          height: 100%; display: flex; align-items: flex-start;
-          pointer-events: none; padding-top: 0.5rem; padding-right: 0.1rem;
-        "
-      >
-        <span
-          role="button"
-          title=${s.collapsed ? "Show panel" : "Hide panel"}
-          @click=${() => setCollapsed(!s.collapsed)}
-          style="
-            pointer-events: auto; cursor: pointer; display: inline-flex;
-            color: var(--bim-ui_bg-contrast-80, #c9c9c9);
-          "
-        ><bim-icon
-          icon=${s.collapsed ? "mdi:chevron-left" : "mdi:chevron-right"}
-          style="font-size: 1.2rem;"
-        ></bim-icon></span>
-      </div>
-    `,
-    { collapsed: false },
-  );
-
-  const setCollapsed = (v: boolean) => {
-    collapsed = v;
-    if (gridEl) gridEl.layout = v ? "collapsed" : "main";
-    toggleUpdate({ collapsed: v });
-  };
-
-  // ── Floating grid: cards docked full-height right, chevron in the gutter ──
-  const grid = BUI.Component.create(() => {
-    const onCreated = (element?: Element) => {
-      if (!element) return;
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const g = element as any;
-      gridEl = g;
-      const names = regions.map((_, i) => `r${i}`);
-      g.elements = {
-        toggle,
-        ...Object.fromEntries(regions.map((r, i) => [names[i], r.element])),
-      };
-      // One row per region; columns: rest (1fr, click-through) | toggle | cards.
-      // The "toggle" area repeats across rows → one full-height gutter column.
-      const rows = regions
-        .map((r, i) => `"rest toggle ${names[i]}" ${r.grow ?? 1}fr`)
-        .join("\n");
-      g.layouts = {
-        main: { template: `${rows}\n/ 1fr auto auto` },
-        // Collapsed: drop the card columns; keep rest + toggle (toggle ends up
-        // near the right edge, inset by the grid's 1rem padding).
-        collapsed: { template: `"rest toggle" 1fr\n/ 1fr auto` },
-      };
-      g.layout = collapsed ? "collapsed" : "main";
-    };
-    return BUI.html`
-      <bim-grid style="padding: 1rem;" ${BUI.ref(onCreated)} floating></bim-grid>
-    `;
-  });
-  container.append(grid);
-
-  return { grid };
-};
-
-/**
- * Mirror of {@link rightStack} for the LEFT side: cards stacked vertically on
- * the left (full height), same 1rem gap + outer margins, with a collapse chevron
- * in the gutter to the RIGHT of the cards (facing the viewport). Used for the
- * Files (top) + helper (bottom) stack.
- */
-export const leftStack = (container: HTMLElement, regions: StackRegion[]) => {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let gridEl: any = null;
-  let collapsed = false;
-
-  const [toggle, toggleUpdate] = BUI.Component.create<
-    HTMLElement,
-    { collapsed: boolean }
-  >(
-    (s) => BUI.html`
-      <div
-        style="
-          height: 100%; display: flex; align-items: flex-start;
-          pointer-events: none; padding-top: 0.5rem; padding-left: 0.1rem;
-        "
-      >
-        <span
-          role="button"
-          title=${s.collapsed ? "Show panel" : "Hide panel"}
-          @click=${() => setCollapsed(!s.collapsed)}
-          style="
-            pointer-events: auto; cursor: pointer; display: inline-flex;
-            color: var(--bim-ui_bg-contrast-80, #c9c9c9);
-          "
-        ><bim-icon
-          icon=${s.collapsed ? "mdi:chevron-right" : "mdi:chevron-left"}
-          style="font-size: 1.2rem;"
-        ></bim-icon></span>
-      </div>
-    `,
-    { collapsed: false },
-  );
-
-  const setCollapsed = (v: boolean) => {
-    collapsed = v;
-    if (gridEl) gridEl.layout = v ? "collapsed" : "main";
-    toggleUpdate({ collapsed: v });
-  };
-
-  const grid = BUI.Component.create(() => {
-    const onCreated = (element?: Element) => {
-      if (!element) return;
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      const g = element as any;
-      gridEl = g;
-      const names = regions.map((_, i) => `r${i}`);
-      g.elements = {
-        toggle,
-        ...Object.fromEntries(regions.map((r, i) => [names[i], r.element])),
-      };
-      // Columns: cards | toggle (gutter, facing viewport) | rest (click-through).
-      const rows = regions
-        .map((r, i) => `"${names[i]} toggle rest" ${r.grow ?? 1}fr`)
-        .join("\n");
-      g.layouts = {
-        main: { template: `${rows}\n/ auto auto 1fr` },
-        // Collapsed: drop the card columns; toggle stays at the left edge (inset
-        // by the grid's 1rem padding).
-        collapsed: { template: `"toggle rest" 1fr\n/ auto 1fr` },
-      };
-      g.layout = collapsed ? "collapsed" : "main";
-    };
-    return BUI.html`
-      <bim-grid style="padding: 1rem;" ${BUI.ref(onCreated)} floating></bim-grid>
-    `;
-  });
-  container.append(grid);
-
-  return { grid };
-};
+import * as BUI from "@thatopen/ui";
+
+/**
+ * Mounts several panels as SEPARATE cards stacked vertically on the RIGHT,
+ * together spanning the full viewport height. One right-docked `bim-grid
+ * floating` holds one row per region (heights split by `grow`); the floating
+ * grid's built-in 1rem gap shows between the cards, and its empty "rest" column
+ * clicks through to the model. Each region is its own `bim-panel` (own
+ * header/border), so they read as distinct cards — not one card with a divider.
+ *
+ * Each panel element should be `height: 100%` so it fills its row and scrolls
+ * internally when its content is tall.
+ *
+ * @param container the viewport element to overlay
+ * @param regions the panels to stack, top to bottom
+ * @returns the floating grid element (already appended to the container)
+ */
+export interface StackRegion {
+  /** The panel element for this region. */
+  element: HTMLElement;
+  /** Relative height share (CSS grid `fr`). Defaults to 1 (equal split). */
+  grow?: number;
+}
+
+export const rightStack = (container: HTMLElement, regions: StackRegion[]) => {
+  // ── Collapse toggle (mirror of the left files panel's) ─────────
+  // A bare chevron in its own thin grid column in the gutter, just OUTSIDE the
+  // cards (to their left). Collapsing swaps the grid layout to drop the card
+  // columns entirely; the chevron column stays. When collapsed the chevron sits
+  // inset from the right edge (the grid's 1rem padding), so it stays in view.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let gridEl: any = null;
+  let collapsed = false;
+
+  const [toggle, toggleUpdate] = BUI.Component.create<
+    HTMLElement,
+    { collapsed: boolean }
+  >(
+    (s) => BUI.html`
+      <div
+        style="
+          height: 100%; display: flex; align-items: flex-start;
+          pointer-events: none; padding-top: 0.5rem; padding-right: 0.1rem;
+        "
+      >
+        <span
+          role="button"
+          title=${s.collapsed ? "Show panel" : "Hide panel"}
+          @click=${() => setCollapsed(!s.collapsed)}
+          style="
+            pointer-events: auto; cursor: pointer; display: inline-flex;
+            color: var(--bim-ui_bg-contrast-80, #c9c9c9);
+          "
+        ><bim-icon
+          icon=${s.collapsed ? "mdi:chevron-left" : "mdi:chevron-right"}
+          style="font-size: 1.2rem;"
+        ></bim-icon></span>
+      </div>
+    `,
+    { collapsed: false },
+  );
+
+  const setCollapsed = (v: boolean) => {
+    collapsed = v;
+    if (gridEl) gridEl.layout = v ? "collapsed" : "main";
+    toggleUpdate({ collapsed: v });
+  };
+
+  // ── Floating grid: cards docked full-height right, chevron in the gutter ──
+  const grid = BUI.Component.create(() => {
+    const onCreated = (element?: Element) => {
+      if (!element) return;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const g = element as any;
+      gridEl = g;
+      const names = regions.map((_, i) => `r${i}`);
+      g.elements = {
+        toggle,
+        ...Object.fromEntries(regions.map((r, i) => [names[i], r.element])),
+      };
+      // One row per region; columns: rest (1fr, click-through) | toggle | cards.
+      // The "toggle" area repeats across rows → one full-height gutter column.
+      const rows = regions
+        .map((r, i) => `"rest toggle ${names[i]}" ${r.grow ?? 1}fr`)
+        .join("\n");
+      g.layouts = {
+        main: { template: `${rows}\n/ 1fr auto auto` },
+        // Collapsed: drop the card columns; keep rest + toggle (toggle ends up
+        // near the right edge, inset by the grid's 1rem padding).
+        collapsed: { template: `"rest toggle" 1fr\n/ 1fr auto` },
+      };
+      g.layout = collapsed ? "collapsed" : "main";
+    };
+    return BUI.html`
+      <bim-grid style="padding: 1rem;" ${BUI.ref(onCreated)} floating></bim-grid>
+    `;
+  });
+  container.append(grid);
+
+  return { grid };
+};
+
+/**
+ * Mirror of {@link rightStack} for the LEFT side: cards stacked vertically on
+ * the left (full height), same 1rem gap + outer margins, with a collapse chevron
+ * in the gutter to the RIGHT of the cards (facing the viewport). Used for the
+ * Files (top) + helper (bottom) stack.
+ */
+export const leftStack = (container: HTMLElement, regions: StackRegion[]) => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let gridEl: any = null;
+  let collapsed = false;
+
+  const [toggle, toggleUpdate] = BUI.Component.create<
+    HTMLElement,
+    { collapsed: boolean }
+  >(
+    (s) => BUI.html`
+      <div
+        style="
+          height: 100%; display: flex; align-items: flex-start;
+          pointer-events: none; padding-top: 0.5rem; padding-left: 0.1rem;
+        "
+      >
+        <span
+          role="button"
+          title=${s.collapsed ? "Show panel" : "Hide panel"}
+          @click=${() => setCollapsed(!s.collapsed)}
+          style="
+            pointer-events: auto; cursor: pointer; display: inline-flex;
+            color: var(--bim-ui_bg-contrast-80, #c9c9c9);
+          "
+        ><bim-icon
+          icon=${s.collapsed ? "mdi:chevron-right" : "mdi:chevron-left"}
+          style="font-size: 1.2rem;"
+        ></bim-icon></span>
+      </div>
+    `,
+    { collapsed: false },
+  );
+
+  const setCollapsed = (v: boolean) => {
+    collapsed = v;
+    if (gridEl) gridEl.layout = v ? "collapsed" : "main";
+    toggleUpdate({ collapsed: v });
+  };
+
+  const grid = BUI.Component.create(() => {
+    const onCreated = (element?: Element) => {
+      if (!element) return;
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const g = element as any;
+      gridEl = g;
+      const names = regions.map((_, i) => `r${i}`);
+      g.elements = {
+        toggle,
+        ...Object.fromEntries(regions.map((r, i) => [names[i], r.element])),
+      };
+      // Columns: cards | toggle (gutter, facing viewport) | rest (click-through).
+      const rows = regions
+        .map((r, i) => `"${names[i]} toggle rest" ${r.grow ?? 1}fr`)
+        .join("\n");
+      g.layouts = {
+        main: { template: `${rows}\n/ auto auto 1fr` },
+        // Collapsed: drop the card columns; toggle stays at the left edge (inset
+        // by the grid's 1rem padding).
+        collapsed: { template: `"toggle rest" 1fr\n/ auto 1fr` },
+      };
+      g.layout = collapsed ? "collapsed" : "main";
+    };
+    return BUI.html`
+      <bim-grid style="padding: 1rem;" ${BUI.ref(onCreated)} floating></bim-grid>
+    `;
+  });
+  container.append(grid);
+
+  return { grid };
+};

package/src/cli/templates/app/src/setups/styles-panel.ts

@@ -1,110 +1,110 @@
-import * as OBC from "@thatopen/components";
-import * as BUI from "@thatopen/ui";
-import { styles, StyleSetting } from "./styles";
-
-/**
- * UI side of the Styles tool. Consumes Worker 1's style DESCRIPTOR
- * (`styles(components, world).settings`) and renders it generically in the
- * bottom-left helper panel: checkbox (bool), slider (number), color picker
- * (color), dropdown (enum) — each wired live to the setting's get/set. Settings
- * are grouped by their `group` field.
- *
- * Returned as a "panel tool" `{ label, icon, render }` for the toolbar; `render`
- * receives a `refresh` callback to re-read all controls after a change (needed
- * because e.g. the preset enum rewrites several other settings).
- */
-const control = (s: StyleSetting, refresh: () => void) => {
-  switch (s.type) {
-    case "bool":
-      return BUI.html`<bim-checkbox
-        label=${s.label}
-        ?checked=${s.get()}
-        @change=${(e: Event) => {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          s.set(!!(e.target as any).value);
-          refresh();
-        }}
-      ></bim-checkbox>`;
-    case "number":
-      return BUI.html`<bim-number-input
-        label=${s.label}
-        slider
-        value=${s.get()}
-        min=${s.min}
-        max=${s.max}
-        step=${s.step}
-        @change=${(e: Event) => {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          s.set(Number((e.target as any).value));
-          refresh();
-        }}
-      ></bim-number-input>`;
-    case "color":
-      return BUI.html`<bim-color-input
-        label=${s.label}
-        color=${s.get()}
-        @input=${(e: Event) => {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          const t = e.target as any;
-          s.set(String(t.color ?? t.value));
-          refresh();
-        }}
-      ></bim-color-input>`;
-    case "enum":
-      return BUI.html`<bim-dropdown
-        label=${s.label}
-        @change=${(e: Event) => {
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          const picked = (e.target as any).value?.[0];
-          const match = s.options.find((o) => o.label === picked);
-          if (match) {
-            s.set(match.value);
-            refresh();
-          }
-        }}
-      >
-        ${s.options.map(
-          (o) => BUI.html`<bim-option label=${o.label} ?checked=${o.value === s.get()}></bim-option>`,
-        )}
-      </bim-dropdown>`;
-  }
-};
-
-export const stylesTool = (components: OBC.Components, world: OBC.World) => ({
-  label: "Styles",
-  icon: "mdi:palette",
-  render: (refresh: () => void) => {
-    const { settings } = styles(components, world);
-    // Group settings by their `group` field, preserving first-seen order.
-    const groups: { name: string; items: StyleSetting[] }[] = [];
-    for (const s of settings) {
-      let g = groups.find((x) => x.name === s.group);
-      if (!g) {
-        g = { name: s.group, items: [] };
-        groups.push(g);
-      }
-      g.items.push(s);
-    }
-    return BUI.html`
-      <div style="display: flex; flex-direction: column; gap: 0.6rem;">
-        ${groups.map(
-          (g) => BUI.html`
-            <div>
-              <div style="
-                font-size: 0.72rem; font-weight: 600; letter-spacing: 0.04em;
-                text-transform: uppercase; opacity: 0.6;
-                color: var(--bim-ui_bg-contrast-100, #e3e3e3);
-                padding: 0.1rem 0 0.3rem; border-bottom: 1px solid var(--bim-ui_bg-contrast-20, rgba(255,255,255,0.1));
-              ">${g.name}</div>
-              <div style="display: flex; flex-direction: column; padding-top: 0.25rem;">
-                ${g.items.map(
-                  (s) => BUI.html`<div style="padding: 0.3rem 0; border-bottom: 1px solid var(--bim-ui_bg-contrast-20, rgba(255, 255, 255, 0.1));">${control(s, refresh)}</div>`,
-                )}
-              </div>
-            </div>
-          `,
-        )}
-      </div>
-    `;
-  },
-});
+import * as OBC from "@thatopen/components";
+import * as BUI from "@thatopen/ui";
+import { styles, StyleSetting } from "./styles";
+
+/**
+ * UI side of the Styles tool. Consumes Worker 1's style DESCRIPTOR
+ * (`styles(components, world).settings`) and renders it generically in the
+ * bottom-left helper panel: checkbox (bool), slider (number), color picker
+ * (color), dropdown (enum) — each wired live to the setting's get/set. Settings
+ * are grouped by their `group` field.
+ *
+ * Returned as a "panel tool" `{ label, icon, render }` for the toolbar; `render`
+ * receives a `refresh` callback to re-read all controls after a change (needed
+ * because e.g. the preset enum rewrites several other settings).
+ */
+const control = (s: StyleSetting, refresh: () => void) => {
+  switch (s.type) {
+    case "bool":
+      return BUI.html`<bim-checkbox
+        label=${s.label}
+        ?checked=${s.get()}
+        @change=${(e: Event) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          s.set(!!(e.target as any).value);
+          refresh();
+        }}
+      ></bim-checkbox>`;
+    case "number":
+      return BUI.html`<bim-number-input
+        label=${s.label}
+        slider
+        value=${s.get()}
+        min=${s.min}
+        max=${s.max}
+        step=${s.step}
+        @change=${(e: Event) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          s.set(Number((e.target as any).value));
+          refresh();
+        }}
+      ></bim-number-input>`;
+    case "color":
+      return BUI.html`<bim-color-input
+        label=${s.label}
+        color=${s.get()}
+        @input=${(e: Event) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const t = e.target as any;
+          s.set(String(t.color ?? t.value));
+          refresh();
+        }}
+      ></bim-color-input>`;
+    case "enum":
+      return BUI.html`<bim-dropdown
+        label=${s.label}
+        @change=${(e: Event) => {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const picked = (e.target as any).value?.[0];
+          const match = s.options.find((o) => o.label === picked);
+          if (match) {
+            s.set(match.value);
+            refresh();
+          }
+        }}
+      >
+        ${s.options.map(
+          (o) => BUI.html`<bim-option label=${o.label} ?checked=${o.value === s.get()}></bim-option>`,
+        )}
+      </bim-dropdown>`;
+  }
+};
+
+export const stylesTool = (components: OBC.Components, world: OBC.World) => ({
+  label: "Styles",
+  icon: "mdi:palette",
+  render: (refresh: () => void) => {
+    const { settings } = styles(components, world);
+    // Group settings by their `group` field, preserving first-seen order.
+    const groups: { name: string; items: StyleSetting[] }[] = [];
+    for (const s of settings) {
+      let g = groups.find((x) => x.name === s.group);
+      if (!g) {
+        g = { name: s.group, items: [] };
+        groups.push(g);
+      }
+      g.items.push(s);
+    }
+    return BUI.html`
+      <div style="display: flex; flex-direction: column; gap: 0.6rem;">
+        ${groups.map(
+          (g) => BUI.html`
+            <div>
+              <div style="
+                font-size: 0.72rem; font-weight: 600; letter-spacing: 0.04em;
+                text-transform: uppercase; opacity: 0.6;
+                color: var(--bim-ui_bg-contrast-100, #e3e3e3);
+                padding: 0.1rem 0 0.3rem; border-bottom: 1px solid var(--bim-ui_bg-contrast-20, rgba(255,255,255,0.1));
+              ">${g.name}</div>
+              <div style="display: flex; flex-direction: column; padding-top: 0.25rem;">
+                ${g.items.map(
+                  (s) => BUI.html`<div style="padding: 0.3rem 0; border-bottom: 1px solid var(--bim-ui_bg-contrast-20, rgba(255, 255, 255, 0.1));">${control(s, refresh)}</div>`,
+                )}
+              </div>
+            </div>
+          `,
+        )}
+      </div>
+    `;
+  },
+});

package/src/cli/templates/app/src/setups/tool-mode-manager.ts

@@ -137,14 +137,20 @@ export class ToolModeManager {
   }
 }
 
-const instances = new WeakMap<OBC.Components, ToolModeManager>();
+// Real OBC.Component wrapper → per-`components` singleton resolved by UUID, so
+// the coordinator is shared across bundle boundaries (toolbar built-in + tools +
+// the app's panels all drive the SAME manager).
+export class ToolModeManagerComponent extends OBC.Component {
+  static readonly uuid = "9b2c7e10-3a4f-4c21-8b6d-1f0a2c3d4e53" as const;
+  enabled = true;
+  readonly manager: ToolModeManager;
+  constructor(components: OBC.Components) {
+    super(components);
+    components.add(ToolModeManagerComponent.uuid, this);
+    this.manager = new ToolModeManager(components);
+  }
+}
 
 /** Per-Components singleton accessor. */
-export const toolModeManager = (components: OBC.Components): ToolModeManager => {
-  let manager = instances.get(components);
-  if (!manager) {
-    manager = new ToolModeManager(components);
-    instances.set(components, manager);
-  }
-  return manager;
-};
+export const toolModeManager = (components: OBC.Components): ToolModeManager =>
+  components.get(ToolModeManagerComponent).manager;

package/src/cli/templates/app/src/setups/tool-mode.ts

@@ -1,23 +1,23 @@
-/**
- * Controller returned by each toolbar mode-tool setup (`clipper`,
- * `lengthMeasurement`, `areaMeasurement`, …). The toolbar — owned by Worker 2 —
- * calls {@link activate} to enter the tool's mode and {@link deactivate} to exit
- * it, and guarantees only one mode is active at a time (mutual exclusion).
- *
- * Contract:
- *  - `activate()`   — enable the tool's pointer/keyboard listeners + cursor.
- *  - `deactivate()` — remove those listeners and drop any transient in-progress
- *                     state. It must NOT discard finished results (e.g. existing
- *                     section planes / measurements persist across mode switches).
- *  Both are idempotent.
- */
-export interface ModeTool {
-  /** Human label, used for the toolbar button tooltip. */
-  label: string;
-  /** Iconify icon name, e.g. "mdi:scissors-cutting". */
-  icon: string;
-  /** Enter the tool's mode. */
-  activate(): void;
-  /** Exit the tool's mode and clean up transient state. */
-  deactivate(): void;
-}
+/**
+ * Controller returned by each toolbar mode-tool setup (`clipper`,
+ * `lengthMeasurement`, `areaMeasurement`, …). The toolbar — owned by Worker 2 —
+ * calls {@link activate} to enter the tool's mode and {@link deactivate} to exit
+ * it, and guarantees only one mode is active at a time (mutual exclusion).
+ *
+ * Contract:
+ *  - `activate()`   — enable the tool's pointer/keyboard listeners + cursor.
+ *  - `deactivate()` — remove those listeners and drop any transient in-progress
+ *                     state. It must NOT discard finished results (e.g. existing
+ *                     section planes / measurements persist across mode switches).
+ *  Both are idempotent.
+ */
+export interface ModeTool {
+  /** Human label, used for the toolbar button tooltip. */
+  label: string;
+  /** Iconify icon name, e.g. "mdi:scissors-cutting". */
+  icon: string;
+  /** Enter the tool's mode. */
+  activate(): void;
+  /** Exit the tool's mode and clean up transient state. */
+  deactivate(): void;
+}