@geode/opengeodeweb-front 10.34.0-rc.9 → 10.34.0

package/app/stores/menu.ts

@@ -48,6 +48,17 @@ interface MenuMetaData {
   [key: string]: unknown;
 }
 
+interface OpenMenuOptions {
+  readonly id: string;
+  readonly x: number | undefined;
+  readonly y: number | undefined;
+  readonly width: number;
+  readonly height: number;
+  readonly top: number;
+  readonly left: number;
+  readonly meta_data: MenuMetaData | undefined;
+}
+
 const PointSet_menu = [PointSetPointsOptions];
 
 const EdgedCurve_menu = [EdgedCurvePointsOptions, EdgedCurveEdgesOptions];
@@ -146,10 +157,16 @@ export const useMenuStore = defineStore("menu", () => {
     objectType: string | undefined,
     geodeObject: string | undefined,
   ): MenuItems {
-    if (!objectType || !geodeObject || !menus.value[objectType]) {
+    if (
+      objectType === undefined ||
+      objectType === "" ||
+      geodeObject === undefined ||
+      geodeObject === "" ||
+      !menus.value[objectType]
+    ) {
       return [];
     }
-    return menus.value[objectType]?.[geodeObject] || [];
+    return menus.value[objectType]?.[geodeObject] ?? [];
   }
 
   function closeMenu(): void {
@@ -161,17 +178,9 @@ export const useMenuStore = defineStore("menu", () => {
     display_menu.value = false;
   }
 
-  async function openMenu(
-    id: string,
-    x: number | undefined,
-    y: number | undefined,
-    width: number,
-    height: number,
-    top: number,
-    left: number,
-    meta_data: MenuMetaData | undefined,
-  ): Promise<void> {
-    await closeMenu();
+  function openMenu(options: OpenMenuOptions): void {
+    const { id, x, y, width, height, top, left, meta_data } = options;
+    closeMenu();
 
     if (meta_data) {
       const items = getMenuItems(meta_data.viewer_type, meta_data.geode_object_type);
@@ -181,7 +190,7 @@ export const useMenuStore = defineStore("menu", () => {
     }
 
     current_id.value = id;
-    current_meta_data.value = meta_data || {};
+    current_meta_data.value = meta_data ?? {};
 
     if (x !== undefined && y !== undefined) {
       menuX.value = x;

package/app/stores/treeview.ts

@@ -55,6 +55,22 @@ function defaultOpenedViews(): OpenedView[] {
   return [{ type: "object", id: "main", title: "Objects", scrollTop: 0, opened: [] }];
 }
 
+type ReadonlyOpenedView = Omit<OpenedView, "opened"> & {
+  readonly opened: readonly string[];
+};
+type ReadonlyTreeviewGroup = Omit<TreeviewGroup, "children"> & {
+  readonly children: readonly TreeviewChild[];
+};
+interface ReadonlyTreeviewSnapshot {
+  opened_views?: readonly ReadonlyOpenedView[];
+  panelWidth?: number;
+  additionalPanelWidth?: number;
+  rowHeights?: readonly number[];
+  selectionIds?: readonly string[];
+  selection?: readonly (string | { id: string })[];
+}
+
+// oxlint-disable-next-line max-lines-per-function, max-statements
 export const useTreeviewStore = defineStore("treeview", () => {
   const items = ref<TreeviewGroup[]>([]);
   const selection = ref<string[]>([]);
@@ -66,10 +82,12 @@ export const useTreeviewStore = defineStore("treeview", () => {
   const pendingSelectionIds = ref<string[]>([]);
   const rowHeights = ref<number[]>([]);
 
-  const treeview_config_db = database.treeview_config as unknown as Table<
-    TreeviewConfigRecord,
-    string
-  >;
+  // The database's table map is dynamically assembled at runtime (see internal/database/database.ts), so its exported type is a loose `{}`; cast it to the shape it actually has at runtime rather than widening every call site.
+  type DatabaseTables = Record<string, unknown>;
+  // oxlint-disable-next-line no-unsafe-type-assertion -- database's table map is dynamically typed at runtime; see comment above.
+  const typedDatabase = database as unknown as DatabaseTables;
+  // oxlint-disable-next-line no-unsafe-type-assertion -- database's table map is dynamically typed at runtime; see comment above.
+  const treeview_config_db = typedDatabase.treeview_config as Table<TreeviewConfigRecord, string>;
 
   async function loadConfig(): Promise<void> {
     try {
@@ -77,10 +95,10 @@ export const useTreeviewStore = defineStore("treeview", () => {
       if (config?.opened_views) {
         opened_views.value = config.opened_views;
       }
-      if (config?.panelWidth) {
+      if (config?.panelWidth !== undefined && config.panelWidth !== 0) {
         panelWidth.value = config.panelWidth;
       }
-      if (config?.additionalPanelWidth) {
+      if (config?.additionalPanelWidth !== undefined && config.additionalPanelWidth !== 0) {
         additionalPanelWidth.value = config.additionalPanelWidth;
       }
       if (config?.selectionIds) {
@@ -90,21 +108,24 @@ export const useTreeviewStore = defineStore("treeview", () => {
         rowHeights.value = config.rowHeights;
       }
     } catch (error) {
+      // oxlint-disable-next-line no-console -- surfaces persistence failures during local development.
       console.error("Failed to load treeview config:", error);
     }
   }
+  // oxlint-disable-next-line typescript/no-floating-promises -- loadConfig catches its own errors internally.
   loadConfig();
 
   watch(
     [opened_views, panelWidth, additionalPanelWidth, selection, rowHeights],
     () => {
-      // oxlint-disable-next-line unicorn/prefer-structured-clone
-      const clean_opened_views = JSON.parse(JSON.stringify(opened_views.value));
-      // oxlint-disable-next-line unicorn/prefer-structured-clone
-      const clean_selectionIds = JSON.parse(JSON.stringify(selection.value));
-      // oxlint-disable-next-line unicorn/prefer-structured-clone
-      const clean_rowHeights = JSON.parse(JSON.stringify(rowHeights.value));
-
+      // oxlint-disable-next-line unicorn/prefer-structured-clone, no-unsafe-type-assertion -- JSON round-trip of a known-shape ref; result matches the source type.
+      const clean_opened_views = JSON.parse(JSON.stringify(opened_views.value)) as OpenedView[];
+      // oxlint-disable-next-line unicorn/prefer-structured-clone, no-unsafe-type-assertion -- JSON round-trip of a known-shape ref; result matches the source type.
+      const clean_selectionIds = JSON.parse(JSON.stringify(selection.value)) as string[];
+      // oxlint-disable-next-line unicorn/prefer-structured-clone, no-unsafe-type-assertion -- JSON round-trip of a known-shape ref; result matches the source type.
+      const clean_rowHeights = JSON.parse(JSON.stringify(rowHeights.value)) as number[];
+
+      // oxlint-disable-next-line typescript/no-floating-promises -- best-effort persistence; failures aren't actionable here.
       treeview_config_db.put({
         id: "main",
         opened_views: clean_opened_views,
@@ -118,14 +139,14 @@ export const useTreeviewStore = defineStore("treeview", () => {
   );
 
   function closeView(id: string): void {
-    opened_views.value = opened_views.value.filter((view) => view.id !== id);
+    opened_views.value = opened_views.value.filter((view: ReadonlyOpenedView) => view.id !== id);
   }
 
-  watch(selection, (current, previous) => {
+  watch(selection, (current: readonly string[], previous: readonly string[]) => {
     const { removed } = compareSelections(current, previous);
     for (const id of removed) {
       const index = opened_views.value.findIndex(
-        (view) => view.type === "component" && view.id === id,
+        (view: ReadonlyOpenedView) => view.type === "component" && view.id === id,
       );
       if (index !== -1) {
         closeView(id);
@@ -134,7 +155,7 @@ export const useTreeviewStore = defineStore("treeview", () => {
   });
 
   function toggleView(id: string): void {
-    const index = opened_views.value.findIndex((view) => view.id === id);
+    const index = opened_views.value.findIndex((view: ReadonlyOpenedView) => view.id === id);
     if (index !== -1) {
       closeView(id);
     } else if (id === "main") {
@@ -170,7 +191,7 @@ export const useTreeviewStore = defineStore("treeview", () => {
     if (!found) {
       items.value.push({ id: geodeObjectType, title: geodeObjectType, children: [child] });
       const sort_options = { numeric: true, sensitivity: "base" as const };
-      items.value.sort((groupA, groupB) =>
+      items.value.sort((groupA: ReadonlyTreeviewGroup, groupB: ReadonlyTreeviewGroup) =>
         groupA.title.localeCompare(groupB.title, undefined, sort_options),
       );
     }
@@ -199,12 +220,13 @@ export const useTreeviewStore = defineStore("treeview", () => {
     id: string,
     title: string | undefined,
     geodeObjectType: string,
-    viewType: string = "model_components",
-  ) {
+    viewType = "model_components",
+  ): void {
     const viewId = `${id}_${viewType}`;
-    const index = opened_views.value.findIndex((view) => view.id === viewId);
+    const index = opened_views.value.findIndex((view: ReadonlyOpenedView) => view.id === viewId);
     if (index !== -1) {
-      return closeView(viewId);
+      closeView(viewId);
+      return;
     }
     additionalPanelWidth.value = panelWidth.value;
     opened_views.value.push({
@@ -212,7 +234,7 @@ export const useTreeviewStore = defineStore("treeview", () => {
       id: viewId,
       modelId: id,
       viewType,
-      title: title || id,
+      title: title ?? id,
       geode_object_type: geodeObjectType,
       scrollTop: 0,
       opened: [],
@@ -228,17 +250,19 @@ export const useTreeviewStore = defineStore("treeview", () => {
     }
   }
 
-  function importStores(snapshot: TreeviewSnapshot | undefined): void {
-    opened_views.value = snapshot?.opened_views || defaultOpenedViews();
-    panelWidth.value = snapshot?.panelWidth || PANEL_WIDTH;
-    additionalPanelWidth.value = snapshot?.additionalPanelWidth || PANEL_WIDTH;
-    rowHeights.value = snapshot?.rowHeights || [];
-    pendingSelectionIds.value =
-      snapshot?.selectionIds ||
-      (snapshot?.selection || []).map((selectionItem) =>
-        typeof selectionItem === "string" ? selectionItem : selectionItem.id,
-      ) ||
-      [];
+  function importStores(snapshot: ReadonlyTreeviewSnapshot | undefined): void {
+    opened_views.value = snapshot?.opened_views
+      ? // oxlint-disable-next-line no-unsafe-type-assertion -- narrowing the readonly parameter view back to the mutable working type; these objects aren't actually frozen at runtime.
+        ([...snapshot.opened_views] as OpenedView[])
+      : defaultOpenedViews();
+    panelWidth.value = snapshot?.panelWidth ?? PANEL_WIDTH;
+    additionalPanelWidth.value = snapshot?.additionalPanelWidth ?? PANEL_WIDTH;
+    rowHeights.value = snapshot?.rowHeights ? [...snapshot.rowHeights] : [];
+    pendingSelectionIds.value = snapshot?.selectionIds
+      ? [...snapshot.selectionIds]
+      : (snapshot?.selection ?? []).map((selectionItem: string | { id: string }) =>
+          typeof selectionItem === "string" ? selectionItem : selectionItem.id,
+        );
   }
 
   function finalizeImportSelection(): void {
@@ -278,24 +302,28 @@ export const useTreeviewStore = defineStore("treeview", () => {
   }
 
   function setScrollTop(viewId: string, scrollTop: number): void {
-    const view = opened_views.value.find((openedView) => openedView.id === viewId);
+    const view = opened_views.value.find(
+      (openedView: ReadonlyOpenedView) => openedView.id === viewId,
+    );
     if (view) {
       view.scrollTop = scrollTop;
     }
   }
 
-  function setOpened(viewId: string, opened: string[]): void {
-    const view = opened_views.value.find((openedView) => openedView.id === viewId);
+  function setOpened(viewId: string, opened: readonly string[]): void {
+    const view = opened_views.value.find(
+      (openedView: ReadonlyOpenedView) => openedView.id === viewId,
+    );
     if (view) {
-      view.opened = opened;
+      view.opened = [...opened];
     }
   }
 
-  function setRowHeights(heights: number[]): void {
-    rowHeights.value = heights;
+  function setRowHeights(heights: readonly number[]): void {
+    rowHeights.value = [...heights];
   }
 
-  function exportStores() {
+  function exportStores(): Omit<TreeviewConfigRecord, "id"> {
     return {
       opened_views: opened_views.value,
       panelWidth: panelWidth.value,
@@ -317,7 +345,7 @@ export const useTreeviewStore = defineStore("treeview", () => {
         break;
       }
     }
-    const view = opened_views.value.find((openedView) => openedView.id === id);
+    const view = opened_views.value.find((openedView: ReadonlyOpenedView) => openedView.id === id);
     if (view) {
       view.title = newName;
     }
@@ -351,3 +379,5 @@ export const useTreeviewStore = defineStore("treeview", () => {
     clear,
   };
 });
+
+export type { TreeviewSnapshot };

package/app/stores/viewer.ts

@@ -18,6 +18,7 @@ import { useInfraStore } from "@ogw_front/stores/infra";
 import { viewer_call } from "@ogw_internal/utils/viewer_call";
 
 import type { JsonRpcSchema, RequestHandlers } from "@ogw_shared/utils/types.js";
+// oxlint-disable-next-line import/max-dependencies -- all imports above are required by this store.
 import type { RpcClient } from "@ogw_shared/utils/call_raw.js";
 
 interface PickedPoint {
@@ -35,6 +36,7 @@ export const useViewerStore = defineStore(
   () => {
     const infraStore = useInfraStore();
     const default_local_port = ref("1234");
+    // oxlint-disable-next-line no-unsafe-type-assertion -- placeholder before the real client is set by ws_connect.
     const client = ref<RpcClient>({} as RpcClient);
     const config = ref<unknown>(undefined);
     const picking_mode = ref(false);
@@ -56,21 +58,38 @@ export const useViewerStore = defineStore(
       viewer_url += "/ws";
       return viewer_url;
     });
+    function start_request(): void {
+      request_counter.value += 1;
+    }
+    function stop_request(): void {
+      request_counter.value -= 1;
+    }
     const is_busy = computed(() => request_counter.value > 0);
     function toggle_picking_mode(value: boolean): void {
       picking_mode.value = value;
     }
-    function request(
+    // oxlint-disable-next-line unicorn/consistent-function-scoping
+    async function request(
       {
         schema,
         params = {},
         timeout = request_timeout,
-      }: { schema: JsonRpcSchema; params?: Record<string, unknown>; timeout?: number },
+      }: {
+        schema: JsonRpcSchema;
+        params?: Record<string, unknown>;
+        timeout?: number;
+      },
       callbacks: RequestHandlers = {},
     ): Promise<unknown> {
-      const store = useViewerStore();
-      return viewer_call(
-        store,
+      const microservice = {
+        $id: "viewer",
+        client: client.value,
+        base_url: base_url.value,
+        start_request,
+        stop_request,
+      };
+      const result = await viewer_call(
+        microservice,
         {
           schema,
           params,
@@ -85,6 +104,7 @@ export const useViewerStore = defineStore(
           },
         },
       );
+      return result;
     }
     async function set_picked_point(x: number, y: number): Promise<void> {
       const schema = opengeodeweb_viewer_schemas.opengeodeweb_viewer.viewer.get_point_position;
@@ -100,6 +120,7 @@ export const useViewerStore = defineStore(
         x: world_x,
         y: world_y,
         z: world_z,
+        // oxlint-disable-next-line no-unsafe-type-assertion -- response shape is defined by the get_point_position schema.
       } = response as { x: number; y: number; z: number };
       picked_point.value = {
         x: world_x,
@@ -107,23 +128,24 @@ export const useViewerStore = defineStore(
         z: world_z,
       };
     }
-    function ws_connect() {
+    async function ws_connect(): Promise<void> {
       if (status.value === Status.CONNECTED) {
-        return undefined;
+        return;
       }
-      return navigator.locks.request("viewer.ws_connect", async (lock) => {
+      await navigator.locks.request("viewer.ws_connect", async () => {
         if (status.value === Status.CONNECTED) {
           return;
         }
         try {
-          console.log("VIEWER LOCK GRANTED !", lock);
           status.value = Status.CONNECTING;
           client.value = (await initWebSocketClient(base_url.value, client.value, {
             onConnectionClose: () => {
               status.value = Status.NOT_CONNECTED;
             },
+            // oxlint-disable-next-line no-unsafe-type-assertion -- initWebSocketClient's return is not typed as RpcClient.
           })) as unknown as RpcClient;
           connectImageStream(client.value.getConnection().getSession());
+          // oxlint-disable-next-line no-unsafe-type-assertion -- endBusy is not part of the RpcClient type.
           (client.value as unknown as { endBusy: () => void }).endBusy();
           const schema = opengeodeweb_viewer_schemas.opengeodeweb_viewer.viewer.reset_visualization;
           const timeout = undefined;
@@ -133,22 +155,12 @@ export const useViewerStore = defineStore(
           });
           status.value = Status.CONNECTED;
         } catch (error) {
-          console.error("ws_connect error", error);
           status.value = Status.NOT_CONNECTED;
           throw error;
         }
       });
     }
-    function start_request(): void {
-      request_counter.value += 1;
-    }
-    function stop_request(): void {
-      request_counter.value -= 1;
-    }
-    function launch(args: { projectFolderPath?: string } = {}) {
-      console.log("[VIEWER] Launching viewer microservice...", {
-        args,
-      });
+    async function launch(args: Readonly<{ projectFolderPath?: string }> = {}): Promise<unknown> {
       const appStore = useAppStore();
       const { COMMAND_VIEWER, NUXT_ROOT_PATH } = useRuntimeConfig().public;
       const schema = opengeodeweb_front_schemas.api.local.app.run_viewer;
@@ -157,41 +169,41 @@ export const useViewerStore = defineStore(
         NUXT_ROOT_PATH,
         args,
       };
-      console.log("[VIEWER] params", params);
-      return appStore.request(
+      const result = await appStore.request(
         {
           schema,
           params,
         },
         {
           response_function: (response: unknown) => {
+            // oxlint-disable-next-line no-unsafe-type-assertion -- response shape is defined by the run_viewer schema.
             const { port: viewerPort } = response as { port: string };
-            console.log(`[VIEWER] Viewer launched on port ${viewerPort}`);
             default_local_port.value = viewerPort;
           },
         },
       );
+      return result;
     }
     async function connect(): Promise<void> {
-      console.log("[VIEWER] Connecting to viewer microservice...");
       await ws_connect();
-      console.log("[VIEWER] Viewer connected successfully");
     }
-    function get_version(schema: JsonRpcSchema | undefined) {
+    async function get_version(schema: JsonRpcSchema | undefined): Promise<unknown> {
       if (!schema) {
         return undefined;
       }
-      return request(
+      const result = await request(
         {
           schema,
         },
         {
           response_function: (response: unknown) => {
+            // oxlint-disable-next-line no-unsafe-type-assertion -- response shape is defined by the version schema.
             const { microservice_version } = response as { microservice_version: string };
             version.value = microservice_version;
           },
         },
       );
+      return result;
     }
     return {
       default_local_port,

package/app/utils/attributes.ts

@@ -1,6 +1,6 @@
 interface AttributeRangeSource {
-  min_values?: number[];
-  max_values?: number[];
+  min_values?: readonly number[];
+  max_values?: readonly number[];
   min_value?: number;
   max_value?: number;
 }
@@ -12,7 +12,7 @@ interface AttributeRange {
 
 export function getAttributeRange(
   currentAttribute: AttributeRangeSource | undefined | null,
-  compIndex: number = 0,
+  compIndex = 0,
 ): AttributeRange {
   if (!currentAttribute) {
     return { min: 0, max: 1 };

package/app/utils/clipping_planes.ts

@@ -1,5 +1,6 @@
 import type { Bounds } from "@kitware/vtk.js/types";
 import type vtkActor from "@kitware/vtk.js/Rendering/Core/Actor";
+import type { vtkCamera } from "@kitware/vtk.js/Rendering/Core/Camera";
 
 const AXIS_SCALE = 0.45;
 const SIZE_RATIO = 0.1;
@@ -20,16 +21,15 @@ const DEFAULT_NORMALS = [NORMAL_X, NORMAL_Y, NORMAL_Z];
 const RGB_MAX_VALUE = 255;
 
 function getPlaneCssColor(index: number): string {
-  // Modulo guarantees this index is within bounds of the non-empty PLANE_COLORS array.
-  const rgb = PLANE_COLORS[index % PLANE_COLORS.length]!;
+  const rgb = PLANE_COLORS[index % PLANE_COLORS.length] ?? COLOR_BLUE;
   return `rgb(${rgb.map((channel) => Math.round(channel * RGB_MAX_VALUE)).join(",")})`;
 }
 
 function hasPlaneChanged(
-  origin: number[],
-  normal: number[],
-  currentOrigin: number[] | undefined,
-  currentNormal: number[] | undefined,
+  origin: readonly number[],
+  normal: readonly number[],
+  currentOrigin: readonly number[] | undefined,
+  currentNormal: readonly number[] | undefined,
 ): boolean {
   if (!currentOrigin) {
     return true;
@@ -40,7 +40,27 @@ function hasPlaneChanged(
   );
 }
 
-function getPlaneStyle(rgb: number[]) {
+interface PlaneVisualState {
+  readonly plane: { readonly opacity: number; readonly color: readonly number[] };
+  readonly normal: { readonly opacity: number; readonly color: readonly number[] };
+  readonly origin: { readonly opacity: number; readonly color: readonly number[] };
+}
+
+interface PlaneStyle {
+  readonly active: PlaneVisualState;
+  readonly inactive: PlaneVisualState;
+  readonly static: {
+    readonly display2D: { readonly representation: number };
+    readonly outline: {
+      readonly color: readonly number[];
+      readonly opacity: number;
+      readonly representation: number;
+      readonly interpolation: number;
+    };
+  };
+}
+
+function getPlaneStyle(rgb: readonly number[]): PlaneStyle {
   return {
     active: {
       plane: { opacity: 1, color: rgb },
@@ -59,7 +79,7 @@ function getPlaneStyle(rgb: number[]) {
   };
 }
 
-function computeSceneBounds(actors: vtkActor[]): Bounds {
+function computeSceneBounds(actors: readonly vtkActor[]): Bounds {
   let bounds: Bounds = [Infinity, -Infinity, Infinity, -Infinity, Infinity, -Infinity];
   for (const actor of actors) {
     const boundsOfActor = actor.getBounds();
@@ -76,12 +96,12 @@ function computeSceneBounds(actors: vtkActor[]): Bounds {
 }
 
 interface SceneBoundsInfo {
-  center: number[];
-  cubicBounds: number[];
+  readonly center: readonly number[];
+  readonly cubicBounds: readonly number[];
 }
 
-function computeSceneBoundsInfo(actors: vtkActor[]): SceneBoundsInfo {
-  if (!actors || actors.length === 0) {
+function computeSceneBoundsInfo(actors: readonly vtkActor[]): SceneBoundsInfo {
+  if (actors.length === 0) {
     return { center: [0, 0, 0], cubicBounds: [-1, 1, -1, 1, -1, 1] };
   }
   const [xmin, xmax, ymin, ymax, zmin, zmax] = computeSceneBounds(actors);
@@ -92,13 +112,13 @@ function computeSceneBoundsInfo(actors: vtkActor[]): SceneBoundsInfo {
   ];
 
   const maxActorExtent = Math.max(
-    ...actors.map((actor) => {
+    ...actors.map((actor: vtkActor) => {
       const bounds = actor.getBounds();
       return Math.max(bounds[1] - bounds[0], bounds[3] - bounds[2], bounds[5] - bounds[4]);
     }),
   );
   const halfExtent = maxActorExtent / 2;
-  const [centerX, centerY, centerZ] = center as [number, number, number];
+  const [centerX = 0, centerY = 0, centerZ = 0] = center;
   const cubicBounds = [
     centerX - halfExtent,
     centerX + halfExtent,
@@ -110,6 +130,79 @@ function computeSceneBoundsInfo(actors: vtkActor[]): SceneBoundsInfo {
   return { center, cubicBounds };
 }
 
+interface ActorEntry {
+  readonly actor: vtkActor;
+}
+
+interface MainCameraOptions {
+  readonly focal_point?: readonly number[];
+  readonly position?: readonly number[];
+  readonly view_up?: readonly number[];
+}
+
+function resolveActiveActors(
+  targetAllVisible: boolean,
+  allItems: readonly { readonly id: string }[],
+  selectedDatasetIds: readonly string[],
+  hybridDb: Record<string, ActorEntry | undefined>,
+): vtkActor[] {
+  const targetIds = targetAllVisible
+    ? allItems.map((item: { id: string }) => item.id)
+    : selectedDatasetIds;
+  const targeted = targetIds
+    .map((id) => hybridDb[id]?.actor)
+    .filter((actor: vtkActor | undefined): actor is vtkActor => actor !== undefined);
+  if (targeted.length > 0) {
+    return targeted;
+  }
+  return Object.values(hybridDb)
+    .filter((entry: ActorEntry | undefined): entry is ActorEntry => entry !== undefined)
+    .map((entry: ActorEntry) => entry.actor);
+}
+
+function computeNormalizedViewDirection(
+  focalPoint: readonly number[],
+  position: readonly number[],
+): readonly number[] | undefined {
+  const dir = [
+    (position[0] ?? 0) - (focalPoint[0] ?? 0),
+    (position[1] ?? 0) - (focalPoint[1] ?? 0),
+    (position[2] ?? 0) - (focalPoint[2] ?? 0),
+  ];
+  const dirLen = Math.hypot(...dir);
+  if (dirLen === 0) {
+    return undefined;
+  }
+  return dir.map((component) => component / dirLen);
+}
+
+// Aligns the local clipping-plane preview camera onto the same viewing direction as the
+// Main viewer camera, re-centered on the clipped scene's bounds.
+function alignCameraToMainCamera(
+  camera: vtkCamera,
+  mainCam: MainCameraOptions,
+  center: readonly number[],
+): void {
+  if (!mainCam.focal_point || !mainCam.position) {
+    return;
+  }
+  const normDir = computeNormalizedViewDirection(mainCam.focal_point, mainCam.position);
+  if (!normDir) {
+    return;
+  }
+  const distance = camera.getDistance();
+  camera.setFocalPoint(center[0] ?? 0, center[1] ?? 0, center[2] ?? 0);
+  camera.setPosition(
+    (center[0] ?? 0) + (normDir[0] ?? 0) * distance,
+    (center[1] ?? 0) + (normDir[1] ?? 0) * distance,
+    (center[2] ?? 0) + (normDir[2] ?? 0) * distance,
+  );
+  if (mainCam.view_up) {
+    const [viewUpX = 0, viewUpY = 0, viewUpZ = 0] = mainCam.view_up;
+    camera.setViewUp(viewUpX, viewUpY, viewUpZ);
+  }
+}
+
 export {
   AXIS_SCALE,
   SIZE_RATIO,
@@ -122,4 +215,8 @@ export {
   getPlaneStyle,
   computeSceneBounds,
   computeSceneBoundsInfo,
+  resolveActiveActors,
+  alignCameraToMainCamera,
 };
+
+export type { SceneBoundsInfo, MainCameraOptions };