From 44458690358c05e27a8f8e7abba1b2327e4fcb93 Mon Sep 17 00:00:00 2001
From: Paul Elliott <paul@vizworkshop.com>
Date: Fri, 14 Aug 2026 23:46:44 +0000
Subject: [PATCH 1/2] chore(types): drop the vtk.js ambient shims

src/shims-vtk.d.ts existed because vtk.js shipped no declarations for
these entry points. Upstream now declares all of them, so the file is
removed entirely and the code uses the real types.

Some of the shim was also stale and was quietly hiding drift:
- vtkWidgetManager declared updateSelectionFromXY,
  updateSelectionFromMouseEvent and useSvgLayer, none of which still
  exist upstream
- the reslice cursor state claimed setColor3/setScale1/setOpacity on the
  root state, but those live on the individual handle states; the casts
  in ResliceCursorTool now name the mixin state types they really are
- a non-generic addWidget signature masked that our own vtkPaintWidget
  and vtkCrosshairsWidget declarations extended the factory's value type
  rather than its interface

Preset metadata specific to VolView (OpacityPoints, AbsoluteRange,
EffectiveRange) moves to a local ColorMapPreset type extending vtk.js's
IColorMapPreset, instead of a shim redeclaring the whole module.
---
 src/components/ObliqueSliceViewer.vue      |   9 +-
 src/components/tools/ResliceCursorTool.vue |  30 +-
 src/composables/useVolumeThumbnailing.ts   |   4 +-
 src/shims-vtk.d.ts                         | 310 ---------------------
 src/store/reslice-cursor.ts                |   8 +-
 src/types/color-map-preset.ts              |  26 ++
 src/utils/vtk-helpers.ts                   |  10 +-
 src/vtk/ColorMaps.ts                       |   5 +-
 src/vtk/CrosshairsWidget/index.d.ts        |   4 +-
 src/vtk/PaintWidget/index.d.ts             |   4 +-
 src/vtk/PaintWidget/state.ts               |   6 +-
 11 files changed, 74 insertions(+), 342 deletions(-)
 delete mode 100644 src/shims-vtk.d.ts
 create mode 100644 src/types/color-map-preset.ts

diff --git a/src/components/ObliqueSliceViewer.vue b/src/components/ObliqueSliceViewer.vue
index 60b17faef..492acff73 100644
--- a/src/components/ObliqueSliceViewer.vue
+++ b/src/components/ObliqueSliceViewer.vue
@@ -145,10 +145,15 @@ watchEffect(() => {
 // setup plane origin/normal
 const planeOrigin = vtkFieldRef(resliceCursorState, {
   get: () => resliceCursorState.getCenter(),
-  set: (v) => resliceCursor.setCenter(v),
+  set: (v) => {
+    resliceCursor.setCenter(v);
+    return true;
+  },
 });
 const planes = vtkFieldRef(resliceCursorState, 'planes');
-const planeNormal = computed(() => planes.value[widgetViewType.value].normal);
+// The reslice cursor is created with the default X/Y/Z planes, so the entry
+// for this view's type is always present.
+const planeNormal = computed(() => planes.value[widgetViewType.value]!.normal);
 
 // slicing domain/range
 
diff --git a/src/components/tools/ResliceCursorTool.vue b/src/components/tools/ResliceCursorTool.vue
index eeb4258c4..26cde5722 100644
--- a/src/components/tools/ResliceCursorTool.vue
+++ b/src/components/tools/ResliceCursorTool.vue
@@ -1,9 +1,17 @@
 <script setup lang="ts">
 import { computed, inject, ref, toRefs } from 'vue';
-import {
-  vtkResliceCursorViewWidget,
-  ResliceCursorWidgetState,
-} from '@kitware/vtk.js/Widgets/Widgets3D/ResliceCursorWidget';
+import { vtkResliceCursorWidgetDefaultInstance } from '@kitware/vtk.js/Widgets/Widgets3D/ResliceCursorWidget/behavior';
+import { vtkColor3MixinState } from '@kitware/vtk.js/Widgets/Core/StateBuilder/color3Mixin';
+import { vtkScale1MixinState } from '@kitware/vtk.js/Widgets/Core/StateBuilder/scale1Mixin';
+import { vtkScale3MixinState } from '@kitware/vtk.js/Widgets/Core/StateBuilder/scale3Mixin';
+
+// The reslice cursor builds its sphere handles from the color3/scale1 mixins
+// and its line handles from the color3/scale3 mixins.
+type SphereHandleState = vtkColor3MixinState & vtkScale1MixinState;
+type LineHandleState = vtkColor3MixinState & vtkScale3MixinState;
+// Per-axis label queries mix line handles (scale3) with rotation handles
+// (scale1), so only the color3 mixin is common to every result.
+type ColoredHandleState = vtkColor3MixinState;
 import { OBLIQUE_OUTLINE_COLORS } from '@/src/constants';
 import { getLPSAxisFromDir, getVTKViewTypeFromLPSAxis } from '@/src/utils/lps';
 import { LPSAxisDir } from '@/src/types/lps';
@@ -27,14 +35,14 @@ if (!view) throw new Error('No vtk view');
 const resliceCursorStore = useResliceCursorStore();
 const { resliceCursor, resliceCursorState } = resliceCursorStore;
 
-const widget = ref<vtkResliceCursorViewWidget>();
+const widget = ref<vtkResliceCursorWidgetDefaultInstance>();
 const vtkViewType = computed(() => getVTKViewTypeFromLPSAxis(viewAxis.value));
 
 onViewMounted(view.renderWindowView, () => {
   widget.value = view.widgetManager.addWidget(
     resliceCursor,
     vtkViewType.value
-  ) as vtkResliceCursorViewWidget;
+  ) as vtkResliceCursorWidgetDefaultInstance;
 
   widget.value.setKeepOrthogonality(true);
   // reset mouse cursor styles
@@ -45,13 +53,13 @@ onViewMounted(view.renderWindowView, () => {
   });
 
   resliceCursorState.getStatesWithLabel('sphere').forEach((handle) => {
-    const h = handle as ResliceCursorWidgetState;
+    const h = handle as SphereHandleState;
     h.setScale1(10);
     h.setOpacity(128);
   });
 
   resliceCursorState.getStatesWithLabel('line').forEach((handle) => {
-    const h = handle as ResliceCursorWidgetState;
+    const h = handle as LineHandleState;
     h.setScale3(1, 1, 1);
     h.setOpacity(100);
   });
@@ -61,7 +69,7 @@ onViewMounted(view.renderWindowView, () => {
     ...resliceCursorState.getStatesWithLabel('XinY'),
   ];
   xLines.forEach((handle) => {
-    const h = handle as ResliceCursorWidgetState;
+    const h = handle as ColoredHandleState;
     h.setColor3(OBLIQUE_OUTLINE_COLORS[InitViewIDs.ObliqueSagittal]);
   });
 
@@ -70,7 +78,7 @@ onViewMounted(view.renderWindowView, () => {
     ...resliceCursorState.getStatesWithLabel('YinX'),
   ];
   yLines.forEach((handle) => {
-    const h = handle as ResliceCursorWidgetState;
+    const h = handle as ColoredHandleState;
     h.setColor3(OBLIQUE_OUTLINE_COLORS[InitViewIDs.ObliqueCoronal]);
   });
 
@@ -79,7 +87,7 @@ onViewMounted(view.renderWindowView, () => {
     ...resliceCursorState.getStatesWithLabel('ZinY'),
   ];
   zLines.forEach((handle) => {
-    const h = handle as ResliceCursorWidgetState;
+    const h = handle as ColoredHandleState;
     h.setColor3(OBLIQUE_OUTLINE_COLORS[InitViewIDs.ObliqueAxial]);
   });
 
diff --git a/src/composables/useVolumeThumbnailing.ts b/src/composables/useVolumeThumbnailing.ts
index f3b5ba307..d70a77f8a 100644
--- a/src/composables/useVolumeThumbnailing.ts
+++ b/src/composables/useVolumeThumbnailing.ts
@@ -2,7 +2,7 @@ import { onBeforeUnmount, reactive, ref, watch } from 'vue';
 import { Mode as LookupTableProxyMode } from '@kitware/vtk.js/Proxy/Core/LookupTableProxy';
 import vtkImageData from '@kitware/vtk.js/Common/DataModel/ImageData';
 import vtkPiecewiseFunctionProxy from '@kitware/vtk.js/Proxy/Core/PiecewiseFunctionProxy';
-import vtkColorMaps from '@kitware/vtk.js/Rendering/Core/ColorTransferFunction/ColorMaps';
+import { getPresetByName } from '@/src/types/color-map-preset';
 import type { Vector3 } from '@kitware/vtk.js/types';
 import { createVolumeThumbnailer } from '../core/thumbnailers/volume-thumbnailer';
 import { useCameraOrientation } from './useCameraOrientation';
@@ -22,7 +22,7 @@ function resetOpacityFunction(
   // reset pwf proxy range
   pwfProxy.setDataRange(...dataRange);
 
-  const preset = vtkColorMaps.getPresetByName(presetName);
+  const preset = getPresetByName(presetName);
   if (preset.OpacityPoints) {
     const OpacityPoints = preset.OpacityPoints as number[];
     const points = [];
diff --git a/src/shims-vtk.d.ts b/src/shims-vtk.d.ts
deleted file mode 100644
index 37bed7f20..000000000
--- a/src/shims-vtk.d.ts
+++ /dev/null
@@ -1,310 +0,0 @@
-declare module '@kitware/vtk.js/vtk' {
-  import { vtkObject } from '@kitware/vtk.js/interfaces';
-
-  const vtk = (obj: any): vtkObject => {};
-  vtk.register = (vtkClassName: string, constructor: unknown): void => {};
-
-  export default vtk;
-}
-
-declare module '@kitware/vtk.js/Interaction/Style/InteractorStyleManipulator/Presets' {
-  export default any;
-}
-
-declare module '@kitware/vtk.js/Rendering/Core/ColorTransferFunction/ColorMaps' {
-  export declare const vtkColorMaps: {
-    addPreset(preset: any): void;
-    removePresetByName(name: string): void;
-    getPresetByName(name: string): any;
-    rgbPresetNames: string[];
-  };
-  export default vtkColorMaps;
-}
-
-declare module '@kitware/vtk.js/Widgets/Core/StateBuilder/boundsMixin' {
-  export declare function extend(publicAPI: any, model: any): void;
-}
-declare module '@kitware/vtk.js/Widgets/Core/StateBuilder/visibleMixin' {
-  export declare function extend(
-    publicAPI: any,
-    model: any,
-    initialValue: any
-  ): void;
-}
-declare module '@kitware/vtk.js/Widgets/Core/StateBuilder/scale1Mixin' {
-  export declare function extend(
-    publicAPI: any,
-    model: any,
-    initialValue: any
-  ): void;
-}
-
-declare module '@kitware/vtk.js/Widgets/Core/WidgetManager' {
-  import { vtkObject } from '@kitware/vtk.js/interfaces';
-  import vtkSelectionNode from '@kitware/vtk.js/Common/DataModel/SelectionNode';
-  import vtkRenderer from '@kitware/vtk.js/Rendering/Core/Renderer';
-  import vtkProp from '@kitware/vtk.js/Rendering/Core/Prop';
-  import vtkAbstractWidgetFactory from '@kitware/vtk.js/Widgets/Core/AbstractWidgetFactory';
-  import vtkAbstractWidget from '@kitware/vtk.js/Widgets/Core/AbstractWidget';
-  import vtkWidgetRepresentation from '@kitware/vtk.js/Widgets/Representations/WidgetRepresentation';
-
-  export enum RenderingTypes {
-    PICKING_BUFFER = 0,
-    FRONT_BUFFER = 1,
-  }
-
-  export enum CaptureOn {
-    MOUSE_MOVE = 0,
-    MOUSE_RELEASE = 1,
-  }
-
-  export enum ViewTypes {
-    DEFAULT = 0,
-    GEOMETRY = 1,
-    SLICE = 2,
-    VOLUME = 3,
-    YZ_PLANE = 4, // Sagittal
-    XZ_PLANE = 5, // Coronal
-    XY_PLANE = 6, // Axial
-  }
-
-  export interface SelectedData {
-    requestCount: number;
-    propID: number;
-    compositeID: number;
-    prop: vtkProp;
-    widget: vtkAbstractWidget;
-    representation: vtkWidgetRepresentation;
-    selectedState: vtkWidgetState;
-  }
-
-  export interface vtkWidgetManager extends vtkObject {
-    setCaptureOn(cap: CaptureOn): boolean;
-    getCaptureOn(): CaptureOn;
-    setViewType(type: ViewTypes): boolean;
-    getViewType(): ViewTypes;
-    getSelections(): vtkSelectionNode[];
-    getWidgets(): vtkAbstractWidget[];
-    getViewId(): string;
-    getPickingEnabled(): boolean;
-    /**
-     * @deprecated
-     */
-    getUseSvgLayer(): boolean;
-    /**
-     * @deprecated
-     */
-    setUseSvgLayer(use: boolean): boolean;
-
-    enablePicking(): void;
-    renderWidgets(): void;
-    disablePicking(): void;
-    setRenderer(ren: vtkRenderer): void;
-    addWidget(
-      widget: vtkAbstractWidgetFactory,
-      viewType?: ViewTypes,
-      initialValues?: object
-    ): vtkAbstractWidget | null;
-    removeWidgets(): void;
-    removeWidget(widget: vtkAbstractWidget | vtkAbstractWidgetFactory): void;
-    getSelectedDataForXY(x: number, y: number): Promise<SelectedData>;
-    updateSelectionFromXY(x: number, y: number): void;
-    updateSelectionFromMouseEvent(event: MouseEvent): void;
-    getSelectedData(): SelectedData | {};
-    grabFocus(widget: vtkAbstractWidget | vtkAbstractWidgetFactory): void;
-    releaseFocus(): void;
-  }
-
-  export interface IWidgetManagerInitialValues {
-    captureOn?: CaptureOn;
-    viewType?: ViewTypes;
-    pickingEnabled?: boolean;
-    /**
-     * @deprecated
-     */
-    useSvgLayer?: boolean;
-  }
-
-  export function extend(
-    publicAPI: object,
-    model: object,
-    initialValues?: IWidgetManagerInitialValues
-  ): vtkWidgetManager;
-
-  export function newInstance(
-    initialValues?: IWidgetManagerInitialValues
-  ): vtkWidgetManager;
-
-  export declare const vtkWidgetManager: {
-    newInstance: typeof newInstance;
-    extend: typeof extend;
-  };
-  export default vtkWidgetManager;
-}
-
-declare module '@kitware/vtk.js/Widgets/Core/StateBuilder' {
-  import vtkWidgetState from '@kitware/vtk.js/Widgets/Core/WidgetState';
-
-  export interface StateBuilder {
-    addDynamicMixinState(buildInfo: {
-      labels: string[];
-      mixins: string[];
-      name: string;
-      initialValues?: object;
-    }): StateBuilder;
-    addStateFromMixin(buildInfo: {
-      labels: string[];
-      mixins: string[];
-      name: string;
-      initialValues?: object;
-    }): StateBuilder;
-    addStateFromInstance(stateInfo: {
-      labels: string[];
-      name: string;
-      instance: vtkWidgetState;
-    });
-    addField(field: { name: string; initialValue: any });
-    build(...mixins: string[]): vtkWidgetState;
-  }
-
-  export function createBuilder(): StateBuilder;
-
-  export declare const vtkStateBuilder: {
-    createBuilder: typeof createBuilder;
-  };
-}
-
-declare module '@kitware/vtk.js/IO/XML/XMLImageDataWriter' {
-  export declare const vtkXMLImageDataWriter: {
-    newInstance: typeof newInstance;
-    extend: typeof extend;
-  };
-
-  export default vtkXMLImageDataWriter;
-}
-
-declare module '@kitware/vtk.js/Widgets/Widgets3D/ImageCroppingWidget' {
-  import vtkAbstractWidget from '@kitware/vtk.js/Widgets/Core/AbstractWidget';
-  import vtkAbstractWidgetFactory from '@kitware/vtk.js/Widgets/Core/AbstractWidgetFactory';
-  import vtkPlaneManipulator from '@kitware/vtk.js/Widgets/Manipulators/PlaneManipulator';
-  import vtkLineManipulator from '@kitware/vtk.js/Widgets/Manipulators/LineManipulator';
-  import { mat4, vec3 } from 'gl-matrix';
-  import vtkImageData from '@kitware/vtk.js/Common/DataModel/ImageData';
-  import vtkWidgetState from '@kitware/vtk.js/Widgets/Core/WidgetState';
-  import { Bounds } from '@kitware/vtk.js/types';
-
-  export interface ImageCroppingPlanesState extends vtkWidgetState {
-    getPlanes(): [number, number, number, number, number, number];
-    setPlanes(
-      planes: [number, number, number, number, number, number]
-    ): boolean;
-  }
-
-  export interface ImageCroppingWidgetState extends vtkWidgetState {
-    getIndexToWorldT(): mat4;
-    setIndexToWorldT(transform: mat4): boolean;
-    getWorldToIndexT(): mat4;
-    setWorldToIndexT(transform: mat4): boolean;
-    getCroppingPlanes(): ImageCroppingPlanesState;
-    placeWidget(bounds: Bounds): void;
-  }
-
-  export interface vtkImageCroppingViewWidget extends vtkAbstractWidget {
-    setManipulator(manipulator: vtkPlaneManipulator): boolean;
-    getManipulator(): vtkPlaneManipulator;
-  }
-
-  export interface vtkImageCroppingWidget extends vtkAbstractWidgetFactory {
-    getWidgetState(): ImageCroppingWidgetState;
-    getCornerManipulator(): vtkPlaneManipulator;
-    getEdgeManipulator(): vtkPlaneManipulator;
-    getFaceManipulator(): vtkLineManipulator;
-    setCornerManipulator(manip: vtkPlaneManipulator): boolean;
-    setEdgeManipulator(manip: vtkPlaneManipulator): boolean;
-    setFaceManipulator(manip: vtkLineManipulator): boolean;
-    copyImageDataDescription(image: vtkImageData);
-    setFaceHandlesEnabled(enabled: boolean): void;
-    setCornerHandlesEnabled(enabled: boolean): void;
-    setEdgeHandlesEnabled(enabled: boolean): void;
-  }
-
-  export function newInstance(): vtkImageCroppingWidget;
-
-  export declare const vtkImageCroppingWidget: {
-    newInstance: typeof newInstance;
-  };
-  export default vtkImageCroppingWidget;
-}
-
-declare module '@kitware/vtk.js/Widgets/Core/AbstractWidget/Constants' {
-  export declare const WIDGET_PRIORITY: number;
-}
-
-declare module '@kitware/vtk.js/Widgets/Widgets3D/ResliceCursorWidget' {
-  import vtkAbstractWidget from '@kitware/vtk.js/Widgets/Core/AbstractWidget';
-  import vtkWidgetState from '@kitware/vtk.js/Widgets/Core/WidgetState';
-  import type { Vector3, RGBColor } from '@kitware/vtk.js/types';
-  import vtkResliceCursorWidget from '@kitware/vtk.js/Widgets/Widgets3D/ResliceCursorWidget';
-
-  export interface vtkResliceCursorViewWidget extends vtkAbstractWidget {
-    setManipulator(manipulator: vtkPlaneManipulator): boolean;
-    getManipulator(): vtkPlaneManipulator;
-    setImage(image: vtkImageData): void;
-    setKeepOrthogonality(keepOrthogonality: boolean): void;
-    setScaleInPixels(scaleInPixels: boolean): void;
-    setCursorStyles(styles: {
-      translateCenter: string;
-      rotateLine: string;
-      translateAxis: string;
-    }): boolean;
-  }
-
-  export interface ResliceCursorWidgetState extends vtkWidgetState {
-    placeWidget(bounds: Bounds): void;
-    setColor3(color: RGBColor): boolean;
-    setScale1(scale: number): boolean;
-    setScale3(scaleX: number, scaleY: number, scaleZ: number): boolean;
-    getPlanes(): Record<number, { normal: Vector3; viewUp: Vector3 }>;
-    setPlanes(
-      planes: Record<number, { normal: Vector3; viewUp: Vector3 }>
-    ): void;
-    getCenter(): Vector3;
-    setScrollingMethod(mode: number): boolean;
-    setOpacity(opacity: number): boolean;
-    setImage(image: vtkImageData): boolean;
-    getImage(): vtkImageData;
-  }
-
-  // Just forwarding vtk-js's definition as default export:
-  export default vtkResliceCursorWidget;
-}
-
-declare module '@kitware/vtk.js/Interaction/Widgets/PiecewiseGaussianWidget' {
-  import type { Vector2 } from '@kitware/vtk.js/types';
-  import vtkPiecewiseFunction from '@kitware/vtk.js/Common/DataModel/PiecewiseFunction';
-
-  export interface vtkPiecewiseGaussianWidget {}
-
-  function applyGaussianToPiecewiseFunction(
-    gaussians: any,
-    sampling: number,
-    rangeToUse: Vector2,
-    piecewiseFunction: vtkPiecewiseFunction
-  ): void;
-
-  export declare const vtkPiecewiseGaussianWidget: {
-    applyGaussianToPiecewiseFunction: typeof applyGaussianToPiecewiseFunction;
-  };
-
-  export default vtkPiecewiseWidget;
-}
-
-declare module '@kitware/vtk.js/Filters/Core/Cutter' {
-  export type vtkCutter = any;
-  export declare const vtkCutter: any;
-  export default vtkCutter;
-}
-
-declare module '@kitware/vtk.js/Rendering/Core/AnnotatedCubeActor/Presets' {
-  export default {} as any;
-}
diff --git a/src/store/reslice-cursor.ts b/src/store/reslice-cursor.ts
index 8d92d8536..f471441e6 100644
--- a/src/store/reslice-cursor.ts
+++ b/src/store/reslice-cursor.ts
@@ -3,7 +3,7 @@ import { ImageMetadata } from '@/src/types/image';
 import { LPSAxis } from '@/src/types/lps';
 import { ViewTypes } from '@kitware/vtk.js/Widgets/Core/WidgetManager/Constants';
 import vtkResliceCursorWidget, {
-  ResliceCursorWidgetState,
+  vtkResliceCursorWidgetState,
 } from '@kitware/vtk.js/Widgets/Widgets3D/ResliceCursorWidget';
 import type { Vector3 } from '@kitware/vtk.js/types';
 import { defineStore } from 'pinia';
@@ -23,7 +23,7 @@ export function mapAxisToViewType(axis: LPSAxis) {
 }
 
 function resetReslicePlanes(
-  resliceCursorState: ResliceCursorWidgetState,
+  resliceCursorState: vtkResliceCursorWidgetState,
   imageMetadata: ImageMetadata
 ) {
   const { Inferior, Anterior, Superior, Left } = toRaw(
@@ -49,7 +49,7 @@ function resetReslicePlanes(
 
 function useResliceInit(
   resliceCursor: vtkResliceCursorWidget,
-  resliceCursorState: ResliceCursorWidgetState
+  resliceCursorState: vtkResliceCursorWidgetState
 ) {
   const { currentImageData, currentImageMetadata } = useCurrentImage('global');
 
@@ -69,7 +69,7 @@ const useResliceCursorStore = defineStore('resliceCursor', () => {
   }) as vtkResliceCursorWidget;
 
   const widgetState =
-    resliceCursor.getWidgetState() as ResliceCursorWidgetState;
+    resliceCursor.getWidgetState() as vtkResliceCursorWidgetState;
 
   useResliceInit(resliceCursor, widgetState);
 
diff --git a/src/types/color-map-preset.ts b/src/types/color-map-preset.ts
new file mode 100644
index 000000000..6bf7e15b5
--- /dev/null
+++ b/src/types/color-map-preset.ts
@@ -0,0 +1,26 @@
+import vtkColorMaps, {
+  IColorMapPreset,
+} from '@kitware/vtk.js/Rendering/Core/ColorTransferFunction/ColorMaps';
+
+/**
+ * A vtk.js color map preset carrying the extra opacity/range metadata VolView
+ * attaches to its own medical presets.
+ *
+ * vtk.js stores presets verbatim, so these fields survive a round trip through
+ * `addPreset`/`getPresetByName`; they are just not part of vtk.js's own type.
+ */
+export interface ColorMapPreset extends IColorMapPreset {
+  /** Flattened (x, opacity) pairs. */
+  OpacityPoints?: number[];
+  /** Whether RGBPoints are in absolute scalar units rather than normalized. */
+  AbsoluteRange?: boolean;
+  /** Preferred scalar opacity mapping range. */
+  EffectiveRange?: [number, number];
+}
+
+/**
+ * `vtkColorMaps.getPresetByName` narrowed to VolView's preset shape.
+ */
+export function getPresetByName(name: string): ColorMapPreset {
+  return vtkColorMaps.getPresetByName(name) as ColorMapPreset;
+}
diff --git a/src/utils/vtk-helpers.ts b/src/utils/vtk-helpers.ts
index f0841039a..0f3e18e0e 100644
--- a/src/utils/vtk-helpers.ts
+++ b/src/utils/vtk-helpers.ts
@@ -1,6 +1,6 @@
 import vtkPiecewiseFunctionProxy from '@kitware/vtk.js/Proxy/Core/PiecewiseFunctionProxy';
 import vtkPiecewiseFunction from '@kitware/vtk.js/Common/DataModel/PiecewiseFunction';
-import vtkColorMaps from '@kitware/vtk.js/Rendering/Core/ColorTransferFunction/ColorMaps';
+import { getPresetByName } from '@/src/types/color-map-preset';
 import vtkRenderer from '@kitware/vtk.js/Rendering/Core/Renderer';
 import vtkOpenGLRenderWindow from '@kitware/vtk.js/Rendering/OpenGL/RenderWindow';
 import type { Vector2, Vector3 } from '@kitware/vtk.js/types';
@@ -127,7 +127,7 @@ export function getShiftedOpacityFromPreset(
   shift: number,
   shiftAlpha: number
 ) {
-  const preset = vtkColorMaps.getPresetByName(presetName);
+  const preset = getPresetByName(presetName);
   if (preset.OpacityPoints) {
     const opacityPoints = preset.OpacityPoints as number[];
     const points = [];
@@ -160,7 +160,7 @@ type OpacityFunctionWithoutRange =
 export function getOpacityFunctionFromPreset(
   presetName: string
 ): OpacityFunctionWithoutRange {
-  const preset = vtkColorMaps.getPresetByName(presetName);
+  const preset = getPresetByName(presetName);
 
   if (preset.OpacityPoints) {
     return {
@@ -203,7 +203,7 @@ export function inflateAxisBounds(bounds: number[], delta: number) {
 export function getColorFunctionRangeFromPreset(
   presetName: string
 ): [number, number] | null {
-  const preset = vtkColorMaps.getPresetByName(presetName);
+  const preset = getPresetByName(presetName);
   if (!preset) return null;
 
   const { AbsoluteRange, RGBPoints } = preset;
@@ -228,7 +228,7 @@ export function getColorFunctionRangeFromPreset(
  * @returns
  */
 export function getOpacityRangeFromPreset(presetName: string) {
-  const preset = vtkColorMaps.getPresetByName(presetName);
+  const preset = getPresetByName(presetName);
   if (preset.EffectiveRange) {
     return [...preset.EffectiveRange] as [number, number];
   }
diff --git a/src/vtk/ColorMaps.ts b/src/vtk/ColorMaps.ts
index 0a52d9995..5bb838b21 100644
--- a/src/vtk/ColorMaps.ts
+++ b/src/vtk/ColorMaps.ts
@@ -1,9 +1,10 @@
 import vtkColorMaps from '@kitware/vtk.js/Rendering/Core/ColorTransferFunction/ColorMaps';
+import { ColorMapPreset } from '@/src/types/color-map-preset';
 import MedicalPresets from '@/src/vtk/MedicalColorPresets.json';
 
 function registerPresets(presets: typeof MedicalPresets) {
   for (let i = 0; i < presets.length; i += 1) {
-    vtkColorMaps.addPreset(presets[i]);
+    vtkColorMaps.addPreset(presets[i] as ColorMapPreset);
   }
 }
 
@@ -14,7 +15,7 @@ const twoHotOpaque = {
   Name: '2hot-opaque',
   OpacityPoints: [0, 1],
 };
-vtkColorMaps.addPreset(twoHotOpaque);
+vtkColorMaps.addPreset(twoHotOpaque as ColorMapPreset);
 
 /* prettier-ignore */
 const GroupedPresets = [
diff --git a/src/vtk/CrosshairsWidget/index.d.ts b/src/vtk/CrosshairsWidget/index.d.ts
index 1954378ea..d992cb7e3 100644
--- a/src/vtk/CrosshairsWidget/index.d.ts
+++ b/src/vtk/CrosshairsWidget/index.d.ts
@@ -1,5 +1,5 @@
 import vtkAbstractWidget from '@kitware/vtk.js/Widgets/Core/AbstractWidget';
-import vtkAbstractWidgetFactory from '@kitware/vtk.js/Widgets/Core/AbstractWidgetFactory';
+import { vtkAbstractWidgetFactory } from '@kitware/vtk.js/Widgets/Core/AbstractWidgetFactory';
 import vtkPlaneManipulator from '@kitware/vtk.js/Widgets/Manipulators/PlaneManipulator';
 import { mat4, vec3 } from 'gl-matrix';
 import { CrosshairsWidgetState } from './state';
@@ -9,7 +9,7 @@ export interface vtkCrosshairsViewWidget extends vtkAbstractWidget {
   getManipulator(): vtkPlaneManipulator;
 }
 
-export interface vtkCrosshairsWidget extends vtkAbstractWidgetFactory {
+export interface vtkCrosshairsWidget extends vtkAbstractWidgetFactory<vtkCrosshairsViewWidget> {
   getWidgetState(): CrosshairsWidgetState;
   getManipulator(): vtkPlaneManipulator;
 }
diff --git a/src/vtk/PaintWidget/index.d.ts b/src/vtk/PaintWidget/index.d.ts
index a748ed822..55785f1c2 100644
--- a/src/vtk/PaintWidget/index.d.ts
+++ b/src/vtk/PaintWidget/index.d.ts
@@ -1,5 +1,5 @@
 import vtkAbstractWidget from '@kitware/vtk.js/Widgets/Core/AbstractWidget';
-import vtkAbstractWidgetFactory from '@kitware/vtk.js/Widgets/Core/AbstractWidgetFactory';
+import { vtkAbstractWidgetFactory } from '@kitware/vtk.js/Widgets/Core/AbstractWidgetFactory';
 import vtkPlaneManipulator from '@kitware/vtk.js/Widgets/Manipulators/PlaneManipulator';
 import { mat4, vec3 } from 'gl-matrix';
 import { PaintWidgetState } from './state';
@@ -14,7 +14,7 @@ export interface vtkPaintViewWidget extends vtkAbstractWidget {
   getWorldToIndex(): mat4;
 }
 
-export interface vtkPaintWidget extends vtkAbstractWidgetFactory {
+export interface vtkPaintWidget extends vtkAbstractWidgetFactory<vtkPaintViewWidget> {
   getWidgetState(): PaintWidgetState;
 }
 
diff --git a/src/vtk/PaintWidget/state.ts b/src/vtk/PaintWidget/state.ts
index b74dfeeb2..2ee254760 100644
--- a/src/vtk/PaintWidget/state.ts
+++ b/src/vtk/PaintWidget/state.ts
@@ -1,6 +1,8 @@
 import { IBrushStencil } from '@/src/core/tools/paint/brush';
 import type { Vector3 } from '@kitware/vtk.js/types';
-import vtkStateBuilder from '@kitware/vtk.js/Widgets/Core/StateBuilder';
+import vtkStateBuilder, {
+  vtkRootWidgetState,
+} from '@kitware/vtk.js/Widgets/Core/StateBuilder';
 import vtkWidgetState from '@kitware/vtk.js/Widgets/Core/WidgetState';
 
 export interface PaintPointWidgetState extends vtkWidgetState {
@@ -14,7 +16,7 @@ export interface PaintPointWidgetState extends vtkWidgetState {
   getColor(): number;
 }
 
-export interface PaintWidgetState extends vtkWidgetState {
+export interface PaintWidgetState extends vtkRootWidgetState {
   getBrush(): PaintPointWidgetState;
   getStencil(): IBrushStencil;
   setStencil(stencil: IBrushStencil): boolean;

From fa74ea8504e8b588862bd28fa9fc03e7cb098171 Mon Sep 17 00:00:00 2001
From: Paul Elliott <paul@vizworkshop.com>
Date: Tue, 18 Aug 2026 18:29:11 -0400
Subject: [PATCH 2/2] fix(crop): treat a parallel plane as a miss

intersectMouseEventWithPlane returned whatever vtkPlane.intersectWithLine put
in its `x` field, which is an empty array when the line is parallel to the
plane and no intersection was computed. An empty array is truthy, so the
caller's `if (!coord)` guard never fired and the coordinates read back as
undefined, which propagated as NaN into the crop bounds.

Return null for that case, matching how the function already reports its other
failures, so the existing guard covers it.
---
 src/utils/vtk-helpers.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/utils/vtk-helpers.ts b/src/utils/vtk-helpers.ts
index 0f3e18e0e..82688e9d1 100644
--- a/src/utils/vtk-helpers.ts
+++ b/src/utils/vtk-helpers.ts
@@ -68,7 +68,7 @@ export function intersectMouseEventWithPlane(
   const position = normalizeMouseEventPosition(ev, view);
   if (!position) return null;
 
-  return intersectDisplayWithPlane(
+  const point = intersectDisplayWithPlane(
     position[0],
     position[1],
     origin,
@@ -76,6 +76,9 @@ export function intersectMouseEventWithPlane(
     renderer,
     view
   );
+  // vtkPlane.intersectWithLine yields an empty array when the line is parallel
+  // to the plane, so an empty result is a miss rather than a point at the origin.
+  return point.length === 3 ? point : null;
 }
 
 /**