From f6ea49ff901ec8c0ca1e44d64956d1781517ab02 Mon Sep 17 00:00:00 2001
From: Peter Todd <ptr.tdd@gmail.com>
Date: Mon, 29 Jun 2026 23:41:13 +0100
Subject: [PATCH 1/9] SpatialCanvas picking perf + Rules-of-React cleanup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Tooltip/picking performance:
- Default `aggregateHoverTooltips` to false. Aggregation ran extra
  `pickMultipleObjects` GPU passes per pointer move on top of deck's own
  hover/highlight pick — very costly over large pickable geometry. Single-pick
  hover reuses the existing pick; aggregation is now opt-in.
- Disable shape picking + autoHighlight during pan/zoom via a debounced
  interaction gate (`useViewInteractionGate` -> `pickingEnabled` on the shapes
  layer), so deck doesn't re-render shape geometry into the picking buffer
  mid-gesture.
- Throttle hover tooltip resolution to one run per animation frame, skip
  redundant same-pixel picks, suppress picking while a pointer button is held,
  and batch the per-missing-layer supplemental pick into a single pass.

Rules-of-React (eslint-plugin-react-hooks): clear the 19-finding backlog and
make the `react-lint` CI job required. Replace ref-during-render and
setState-in-effect patterns with derived state across `@spatialdata/react`
useSpatialData and the vis Transforms/Table/Shapes/ImageView/SpatialCanvas
components; document the one intentional external-store ref read in
useLayerData's isBlocking memo.

Adds tests for the batched supplemental pick and the drag-suppression helper.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ...lcanvas-picking-perf-and-rules-of-react.md |  29 ++++
 .github/workflows/test.yml                    |  11 +-
 packages/layers/src/shapesLayer.ts            |  14 +-
 packages/react/src/hooks/useSpatialData.ts    |  52 ++++--
 packages/vis/src/ImageView/index.tsx          |  27 ++-
 packages/vis/src/Shapes/index.tsx             |  57 +++---
 .../src/SpatialCanvas/SpatialCanvasViewer.tsx | 164 +++++++++++-------
 .../src/SpatialCanvas/featureTooltipHover.ts  |  21 ++-
 packages/vis/src/SpatialCanvas/index.tsx      | 107 ++++++++----
 .../SpatialCanvas/renderers/shapesRenderer.ts |   8 +
 .../vis/src/SpatialCanvas/useLayerData.ts     |  47 ++++-
 .../SpatialCanvas/useThrottledHoverTooltip.ts |  91 ++++++++++
 .../SpatialCanvas/useViewInteractionGate.ts   |  61 +++++++
 packages/vis/src/Table/index.tsx              |  20 ++-
 packages/vis/src/Transforms/index.tsx         |  48 +++--
 .../vis/tests/featureTooltipHover.spec.ts     |  44 ++++-
 .../vis/tests/throttledHoverTooltip.spec.ts   |  18 ++
 17 files changed, 597 insertions(+), 222 deletions(-)
 create mode 100644 .changeset/spatialcanvas-picking-perf-and-rules-of-react.md
 create mode 100644 packages/vis/src/SpatialCanvas/useThrottledHoverTooltip.ts
 create mode 100644 packages/vis/src/SpatialCanvas/useViewInteractionGate.ts
 create mode 100644 packages/vis/tests/throttledHoverTooltip.spec.ts

diff --git a/.changeset/spatialcanvas-picking-perf-and-rules-of-react.md b/.changeset/spatialcanvas-picking-perf-and-rules-of-react.md
new file mode 100644
index 00000000..3bf22b90
--- /dev/null
+++ b/.changeset/spatialcanvas-picking-perf-and-rules-of-react.md
@@ -0,0 +1,29 @@
+---
+"@spatialdata/vis": minor
+"@spatialdata/layers": patch
+"@spatialdata/react": patch
+---
+
+SpatialCanvas hover/picking performance and Rules-of-React cleanup.
+
+Picking/tooltip performance:
+
+- `aggregateHoverTooltips` now defaults to `false`. Aggregation issued extra
+  `pickMultipleObjects` GPU passes on every pointer move (on top of the pick
+  deck.gl already does for hover/highlight), which is very expensive over large
+  pickable geometry. Single-pick hover uses the existing pick; enable
+  aggregation explicitly when stacked-layer tooltips are needed.
+- Shape layers are made non-pickable (and `autoHighlight` disabled) while the
+  camera is being panned/zoomed, so deck.gl does not re-render the shape
+  geometry into the picking buffer during gestures. New `pickingEnabled` option
+  on the shapes layer (`@spatialdata/layers`) drives this.
+- Hover tooltip resolution is throttled to one run per animation frame, skips
+  redundant same-pixel work, is suppressed while a pointer button is held
+  (drag), and collapses the per-missing-layer supplemental pick storm into a
+  single batched pick.
+
+Rules-of-React fixes (eslint-plugin-react-hooks, `pnpm lint:react` now clean and
+the `react-lint` CI job is required): removed ref reads/writes during render and
+replaced setState-in-effect patterns with derived state in `@spatialdata/react`
+`useSpatialData` and the vis `Transforms`, `Table`, `Shapes`, `ImageView`, and
+`SpatialCanvas` components.
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index d9b109da..0f6358a4 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -17,9 +17,9 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-    # Surfaces React Hooks / React Compiler (Rules-of-React) findings for the
-    # React-shipping packages via eslint-plugin-react-hooks. Informational for
-    # now: there is an existing backlog of findings, so this must not gate merges.
+    # Enforces React Hooks / React Compiler (Rules-of-React) compliance for the
+    # React-shipping packages via eslint-plugin-react-hooks. The backlog has been
+    # cleared, so this is a required gate: any new finding fails the check.
     steps:
       - uses: actions/checkout@v4
         with:
@@ -39,11 +39,6 @@ jobs:
         run: pnpm install --frozen-lockfile
 
       - name: Lint React packages (react-hooks / react-compiler rules)
-        # continue-on-error (at the step, not the job) keeps this check green
-        # while the backlog exists, so it does not read as a failing/required
-        # check; findings still show in this step's log. Remove this line once
-        # `pnpm lint:react` is clean to turn it into a required gate.
-        continue-on-error: true
         run: pnpm lint:react
 
   test:
diff --git a/packages/layers/src/shapesLayer.ts b/packages/layers/src/shapesLayer.ts
index 08cd5c48..dfb4791d 100644
--- a/packages/layers/src/shapesLayer.ts
+++ b/packages/layers/src/shapesLayer.ts
@@ -237,6 +237,12 @@ export interface CreateShapesDeckLayerOptions {
   spatialCoordinateSystem?: string | null;
   onShapeHover?: (event: ShapesLayerPickEvent) => void;
   onShapeClick?: (event: ShapesLayerPickEvent) => void;
+  /**
+   * When false, the layer is rendered non-pickable with autoHighlight disabled.
+   * Used to suppress deck.gl's per-pointer-move picking-buffer render over large
+   * shape geometry while the camera is being panned/zoomed. Defaults to true.
+   */
+  pickingEnabled?: boolean;
 }
 
 function multiplyAlpha(
@@ -603,8 +609,8 @@ function createPolygonDeckLayer(
     stroked: true,
     opacity: options.opacity ?? 1,
     modelMatrix: options.modelMatrix,
-    pickable: true,
-    autoHighlight: true,
+    pickable: options.pickingEnabled ?? true,
+    autoHighlight: options.pickingEnabled ?? true,
     highlightColor: [255, 255, 0, 128],
     onHover: createPickHandler(
       options.id,
@@ -648,8 +654,8 @@ function createCircleDeckLayer(
     },
     opacity: options.opacity ?? 1,
     modelMatrix: options.modelMatrix,
-    pickable: true,
-    autoHighlight: true,
+    pickable: options.pickingEnabled ?? true,
+    autoHighlight: options.pickingEnabled ?? true,
     highlightColor: [255, 255, 0, 128],
     onHover: createPickHandler(
       options.id,
diff --git a/packages/react/src/hooks/useSpatialData.ts b/packages/react/src/hooks/useSpatialData.ts
index 484350bf..aae94ad9 100644
--- a/packages/react/src/hooks/useSpatialData.ts
+++ b/packages/react/src/hooks/useSpatialData.ts
@@ -1,36 +1,54 @@
-import { useEffect, useState } from 'react';
 import type { SpatialData } from '@spatialdata/core';
+import { useEffect, useState } from 'react';
 import { useSpatialDataContext } from '../provider/SpatialDataProvider';
 
+type ResolvedSpatialData = {
+  /** The promise this result was produced from, used to detect stale results. */
+  promise: Promise<SpatialData> | null;
+  spatialData: SpatialData | null;
+  error: Error | null;
+};
+
 export function useSpatialData() {
   const { spatialDataPromise } = useSpatialDataContext();
-  const [spatialData, setSpatialData] = useState<SpatialData | null>(null);
-  const [error, setError] = useState<Error | null>(null);
-  const [loading, setLoading] = useState<boolean>(true);
+  // Track which promise each settled result came from so loading/reset can be
+  // derived during render rather than synchronised with a setState-in-effect.
+  const [resolved, setResolved] = useState<ResolvedSpatialData>({
+    promise: null,
+    spatialData: null,
+    error: null,
+  });
 
   useEffect(() => {
+    if (!spatialDataPromise) return;
     let cancelled = false;
-    setLoading(true);
-    setError(null);
-    setSpatialData(null);
-    if (!spatialDataPromise) {
-      setLoading(false);
-      return;
-    }
     spatialDataPromise
       .then((s) => {
-        if (!cancelled) setSpatialData(s);
+        if (!cancelled) setResolved({ promise: spatialDataPromise, spatialData: s, error: null });
       })
       .catch((e: unknown) => {
-        if (!cancelled) setError(e instanceof Error ? e : new Error(String(e)));
-      })
-      .finally(() => {
-        if (!cancelled) setLoading(false);
+        if (!cancelled) {
+          setResolved({
+            promise: spatialDataPromise,
+            spatialData: null,
+            error: e instanceof Error ? e : new Error(String(e)),
+          });
+        }
       });
     return () => {
       cancelled = true;
     };
   }, [spatialDataPromise]);
 
-  return { spatialData, loading, error } as const;
+  // When the current promise hasn't settled into `resolved` yet, we're loading
+  // (or idle, if there is no promise). Deriving this avoids resetting state in
+  // an effect every time `spatialDataPromise` changes.
+  const settled = resolved.promise === spatialDataPromise;
+  const loading = Boolean(spatialDataPromise) && !settled;
+
+  return {
+    spatialData: settled ? resolved.spatialData : null,
+    loading,
+    error: settled ? resolved.error : null,
+  } as const;
 }
diff --git a/packages/vis/src/ImageView/index.tsx b/packages/vis/src/ImageView/index.tsx
index 4010e16d..ddbfc202 100644
--- a/packages/vis/src/ImageView/index.tsx
+++ b/packages/vis/src/ImageView/index.tsx
@@ -148,31 +148,24 @@ export default function ImageView() {
   const [selectedImage, setSelectedImage] = useState<string>('');
   const [ref, { width, height }] = useMeasure();
 
-  useEffect(() => {
-    if (!spatialData?.images) return;
-    if (selectedImage === '' || !spatialData.images[selectedImage]) {
-      setSelectedImage(Object.keys(spatialData.images)[0]);
-    }
-  }, [spatialData?.images, selectedImage]);
+  const imageKeys = useMemo(() => Object.keys(spatialData?.images ?? {}), [spatialData?.images]);
+  // Default to the first available image, derived during render.
+  const effectiveImage =
+    selectedImage && imageKeys.includes(selectedImage) ? selectedImage : (imageKeys[0] ?? '');
 
   const vivStores = useMemo(() => {
     return createVivStores();
   }, []);
   const image = useMemo(() => {
-    return spatialData?.images?.[selectedImage];
-  }, [selectedImage, spatialData?.images]);
-  const [imageUrl, setImageUrl] = useState<string | URL>();
-  useEffect(() => {
-    if (image) {
-      setImageUrl(image.url ?? '');
-    } else {
-      setImageUrl('');
-    }
-  }, [image]);
+    return spatialData?.images?.[effectiveImage];
+  }, [effectiveImage, spatialData?.images]);
+  // The url is synchronously available on the image, so derive it rather than
+  // syncing through state in an effect.
+  const imageUrl = useMemo<string | URL>(() => image?.url ?? '', [image]);
   return (
     <div ref={ref} style={containerStyle}>
       {spatialData?.images && (
-        <select value={selectedImage || ''} onChange={(e) => setSelectedImage(e.target.value)}>
+        <select value={effectiveImage} onChange={(e) => setSelectedImage(e.target.value)}>
           {Object.keys(spatialData.images).map((key) => (
             <option key={key} value={key}>
               {key}
diff --git a/packages/vis/src/Shapes/index.tsx b/packages/vis/src/Shapes/index.tsx
index 43bc61c9..a0a39404 100644
--- a/packages/vis/src/Shapes/index.tsx
+++ b/packages/vis/src/Shapes/index.tsx
@@ -1,7 +1,7 @@
 import { useSpatialData } from '@spatialdata/react';
 import JsonView from '@uiw/react-json-view';
 import { darkTheme } from '@uiw/react-json-view/dark';
-import { useEffect, useMemo, useState } from 'react';
+import { useMemo, useState } from 'react';
 // import type { Table } from "@spatialdata/core";
 
 export default function ShapesComponent() {
@@ -9,44 +9,39 @@ export default function ShapesComponent() {
   const [selectedShapes, setSelectedShapes] = useState<string>('');
   const shapeKeys = useMemo(() => Object.keys(spatialData?.shapes ?? {}), [spatialData?.shapes]);
 
-  // Default to first available shape
-  useEffect(() => {
-    if (shapeKeys.length > 0 && (!selectedShapes || !shapeKeys.includes(selectedShapes))) {
-      setSelectedShapes(shapeKeys[0]);
-    }
-  }, [shapeKeys, selectedShapes]);
+  // Default to the first available shape, derived during render.
+  const effectiveShapes =
+    selectedShapes && shapeKeys.includes(selectedShapes) ? selectedShapes : (shapeKeys[0] ?? '');
 
   const shapes = useMemo(() => {
-    return spatialData?.shapes?.[selectedShapes];
-  }, [selectedShapes, spatialData?.shapes]);
-  const [shapesData, setShapesData] = useState<any>(undefined);
-  useEffect(() => {
-    if (shapes) {
-      const result = shapes.getTransformation();
-      if (result.ok) {
-        const t = result.value;
-        setShapesData({
-          type: t.type,
-          input: t.input,
-          output: t.output,
-          matrix: t.toArray(),
-        });
-      } else {
-        // Show the error info
-        setShapesData({
-          error: result.error.message,
-          availableCoordinateSystems: result.error.availableCoordinateSystems,
-        });
-      }
-    } else {
-      setShapesData(undefined);
+    return spatialData?.shapes?.[effectiveShapes];
+  }, [effectiveShapes, spatialData?.shapes]);
+
+  // getTransformation() is synchronous, so the displayed data is pure derived
+  // state rather than something to sync into an effect.
+  const shapesData = useMemo(() => {
+    if (!shapes) return undefined;
+    const result = shapes.getTransformation();
+    if (result.ok) {
+      const t = result.value;
+      return {
+        type: t.type,
+        input: t.input,
+        output: t.output,
+        matrix: t.toArray(),
+      };
     }
+    // Show the error info
+    return {
+      error: result.error.message,
+      availableCoordinateSystems: result.error.availableCoordinateSystems,
+    };
   }, [shapes]);
   return (
     <div>
       <h3>Shapes component:</h3>
       {spatialData?.shapes && (
-        <select value={selectedShapes || ''} onChange={(e) => setSelectedShapes(e.target.value)}>
+        <select value={effectiveShapes} onChange={(e) => setSelectedShapes(e.target.value)}>
           {Object.keys(spatialData.shapes).map((key) => (
             <option key={key} value={key}>
               {key}
diff --git a/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx b/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
index 76d6c26d..d78a9fd1 100644
--- a/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
+++ b/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
@@ -12,6 +12,8 @@ import {
   useState,
 } from 'react';
 import { createPortal } from 'react-dom';
+import { ensureCodecWorkers } from '../codecWorkers';
+import { ImageLayerContextProvider } from './ImageLayerContext';
 import {
   type SpatialCanvasTooltipRenderProps,
   SpatialFeatureTooltip,
@@ -21,15 +23,14 @@ import { SpatialViewer } from './SpatialViewer';
 import { VivLoaderRegistryProvider } from './VivLoaderRegistry';
 import { getDeckFromDeckGlRef, resolveHoverFeatureTooltip } from './featureTooltipHover';
 import {
+  type RenderStackHostLayerResolver,
+  type RenderStackLayerInputs,
+  type UnknownRenderStackHostLayerHandler,
   renderStackOrder,
   renderStackToLayerInputs,
   resolveRenderStackHostLayers,
   sortLayersByRenderStackOrder,
-  type RenderStackHostLayerResolver,
-  type RenderStackLayerInputs,
-  type UnknownRenderStackHostLayerHandler,
 } from './renderStackAdapters';
-import { ImageLayerContextProvider } from './ImageLayerContext';
 import type { ElementsByType, LayerConfig, ShapesLayerPickEvent, ViewState } from './types';
 import {
   type LabelFeaturePickEventData,
@@ -37,12 +38,17 @@ import {
   useLayerData,
 } from './useLayerData';
 import {
-  type VivImageExtensionResolver,
-  type VivImagePassthroughOptions,
-  type VivImagePropsResolver,
-} from './vivImagePassthrough';
-import { ensureCodecWorkers } from '../codecWorkers';
+  type HoverPointerEvent,
+  isHoverDuringDrag,
+  useThrottledHoverTooltip,
+} from './useThrottledHoverTooltip';
+import { useViewInteractionGate } from './useViewInteractionGate';
 import { getAvailableElements } from './utils';
+import type {
+  VivImageExtensionResolver,
+  VivImagePassthroughOptions,
+  VivImagePropsResolver,
+} from './vivImagePassthrough';
 
 export type {
   VivImageExtensionResolver,
@@ -95,7 +101,11 @@ export interface SpatialCanvasViewerProps {
   autoFit?: boolean;
   style?: CSSProperties;
   /**
-   * When true (default), hover tooltips aggregate picks from all layers under the cursor.
+   * When true, hover tooltips aggregate picks from all layers under the cursor.
+   * This issues extra `pickMultipleObjects` GPU passes per pointer move on top of
+   * the pick deck already does for hover/highlight, which is expensive over large
+   * pickable geometry — so it defaults to false (single top pick from the hover
+   * info). Enable it only when stacked-layer tooltips are needed.
    */
   aggregateHoverTooltips?: boolean;
   /** Global fallback Viv LayerExtension instances for image layers. */
@@ -184,6 +194,11 @@ interface UseSpatialCanvasRendererFromLayerInputsOptions {
   sortDeckLayers?: boolean;
   autoFit?: boolean;
   vivPassthrough?: VivImagePassthroughOptions;
+  /**
+   * When true, the camera is being panned/zoomed and shape picking is disabled
+   * to avoid per-move picking-buffer renders over large geometry.
+   */
+  interacting?: boolean;
 }
 
 export function useSpatialCanvasRendererFromLayerInputs({
@@ -200,6 +215,7 @@ export function useSpatialCanvasRendererFromLayerInputs({
   sortDeckLayers,
   autoFit = true,
   vivPassthrough,
+  interacting = false,
 }: UseSpatialCanvasRendererFromLayerInputsOptions) {
   ensureCodecWorkers();
 
@@ -221,7 +237,7 @@ export function useSpatialCanvasRendererFromLayerInputs({
     vivPassthrough
   );
 
-  const generatedDeckLayers = layerData.getLayers();
+  const generatedDeckLayers = layerData.getLayers({ pickingEnabled: !interacting });
   const deckLayers = useMemo(() => {
     const composed = composeSpatialDeckLayers(generatedDeckLayers, [
       ...(hostDeckLayers ?? []),
@@ -397,7 +413,7 @@ function SpatialCanvasViewerInner({
   showLoadingOverlay = true,
   autoFit = true,
   style,
-  aggregateHoverTooltips = true,
+  aggregateHoverTooltips = false,
   vivImageExtensions,
   vivImageExtensionResolver,
   vivImagePropsResolver,
@@ -405,8 +421,9 @@ function SpatialCanvasViewerInner({
   const [measureRef, { width, height }] = useMeasure();
   const viewerContainerRef = useRef<HTMLDivElement | null>(null);
   const deckRef = useRef<DeckGLRef | null>(null);
+  const { interacting, onInteractionStateChange } = useViewInteractionGate();
   const [hoverTooltip, setHoverTooltip] = useState<
-    (SpatialFeatureTooltipData & { x: number; y: number }) | null
+    (SpatialFeatureTooltipData & { x: number; y: number; clientX: number; clientY: number }) | null
   >(null);
 
   const vw = width ?? 0;
@@ -447,63 +464,96 @@ function SpatialCanvasViewerInner({
     sortDeckLayers: Boolean(renderStack),
     autoFit,
     vivPassthrough,
+    interacting,
   });
   const hoverPickLayerIds = useMemo(
     () => Array.from(renderer.enabledLayerIds),
     [renderer.enabledLayerIds]
   );
+  // Feed deck's interaction state into the gate (via deckProps so the existing
+  // spread reaches both DeckGL branches) without disturbing caller deckProps.
+  const mergedDeckProps = useMemo(
+    () => ({ ...deckProps, onInteractionStateChange }),
+    [deckProps, onInteractionStateChange]
+  );
 
-  const handleHover = useCallback(
+  // The expensive part of hovering: aggregate-pick the feature(s) under the
+  // cursor and position the tooltip. Throttled to one run per animation frame.
+  const resolveTooltip = useCallback(
     (info: PickingInfo) => {
-      onHover?.(info);
-      if (!info.picked || typeof info.x !== 'number' || typeof info.y !== 'number') {
+      if (!shouldRenderInternalTooltip(renderTooltip)) {
+        return;
+      }
+      const tooltip =
+        info.picked && typeof info.x === 'number' && typeof info.y === 'number'
+          ? resolveHoverFeatureTooltip(info, renderer.getFeatureTooltip, {
+              aggregate: aggregateHoverTooltips,
+              deck: getDeckFromDeckGlRef(deckRef),
+              pickLayerIds: hoverPickLayerIds,
+            })
+          : null;
+      // Resolve viewport coordinates here (in the event handler) rather than
+      // reading the container ref during render.
+      if (!tooltip) {
         setHoverTooltip(null);
         return;
       }
-      const rawLayerId = typeof info.layer?.id === 'string' ? info.layer.id : '';
-      const normalizedLayerId = rawLayerId.replace(/-#.*#$/, '');
-      const featurePickEvent = renderer.getFeaturePickEvent(normalizedLayerId, {
-        index: info.index,
-        object: info.object,
+      const rect = viewerContainerRef.current?.getBoundingClientRect();
+      setHoverTooltip({
+        ...tooltip,
+        clientX: (rect?.left ?? 0) + tooltip.x,
+        clientY: (rect?.top ?? 0) + tooltip.y,
       });
-      if (featurePickEvent) {
-        onFeatureHover?.({
-          ...featurePickEvent,
-          coordinateSystem,
-          spatialData,
-          pickInfo: info,
-        });
+    },
+    [aggregateHoverTooltips, hoverPickLayerIds, renderTooltip, renderer.getFeatureTooltip]
+  );
+  const scheduleTooltip = useThrottledHoverTooltip(resolveTooltip);
+
+  const handleHover = useCallback(
+    (info: PickingInfo, event?: HoverPointerEvent) => {
+      onHover?.(info);
+      // While panning/dragging, deck keeps firing hover events; the gesture is
+      // changing the view, not inspecting features, so suppress tooltip work.
+      if (isHoverDuringDrag(event)) {
+        setHoverTooltip(null);
+        return;
       }
-      const shapePickEvent = renderer.getShapePickEvent(normalizedLayerId, {
-        index: info.index,
-        object: info.object,
-      });
-      if (shapePickEvent) {
-        onShapeHover?.({
-          ...shapePickEvent,
-          coordinateSystem,
-          pickInfo: info,
+      if (info.picked && typeof info.x === 'number' && typeof info.y === 'number') {
+        const rawLayerId = typeof info.layer?.id === 'string' ? info.layer.id : '';
+        const normalizedLayerId = rawLayerId.replace(/-#.*#$/, '');
+        const featurePickEvent = renderer.getFeaturePickEvent(normalizedLayerId, {
+          index: info.index,
+          object: info.object,
         });
+        if (featurePickEvent) {
+          onFeatureHover?.({
+            ...featurePickEvent,
+            coordinateSystem,
+            spatialData,
+            pickInfo: info,
+          });
+        }
+        const shapePickEvent = renderer.getShapePickEvent(normalizedLayerId, {
+          index: info.index,
+          object: info.object,
+        });
+        if (shapePickEvent) {
+          onShapeHover?.({
+            ...shapePickEvent,
+            coordinateSystem,
+            pickInfo: info,
+          });
+        }
       }
-      if (!shouldRenderInternalTooltip(renderTooltip)) {
-        return;
-      }
-      const tooltip = resolveHoverFeatureTooltip(info, renderer.getFeatureTooltip, {
-        aggregate: aggregateHoverTooltips,
-        deck: getDeckFromDeckGlRef(deckRef),
-        pickLayerIds: hoverPickLayerIds,
-      });
-      setHoverTooltip(tooltip);
+      scheduleTooltip(info);
     },
     [
-      aggregateHoverTooltips,
       coordinateSystem,
-      hoverPickLayerIds,
       onFeatureHover,
       onHover,
       onShapeHover,
-      renderTooltip,
       renderer,
+      scheduleTooltip,
       spatialData,
     ]
   );
@@ -551,17 +601,11 @@ function SpatialCanvasViewerInner({
     [measureRef]
   );
 
-  const viewerRect = viewerContainerRef.current?.getBoundingClientRect();
-  const tooltipClientPosition =
-    hoverTooltip && viewerRect
-      ? {
-          x: viewerRect.left + hoverTooltip.x,
-          y: viewerRect.top + hoverTooltip.y,
-        }
-      : null;
+  const tooltipClientPosition = hoverTooltip
+    ? { x: hoverTooltip.clientX, y: hoverTooltip.clientY }
+    : null;
 
-  const tooltipPayload: SpatialFeatureTooltipData | null =
-    hoverTooltip && tooltipClientPosition ? hoverTooltip : null;
+  const tooltipPayload: SpatialFeatureTooltipData | null = hoverTooltip;
 
   const portalTarget = typeof document !== 'undefined' ? (tooltipContainer ?? document.body) : null;
   const tooltipPortal =
@@ -628,7 +672,7 @@ function SpatialCanvasViewerInner({
               vivLayerProps={renderer.vivLayerProps.length > 0 ? renderer.vivLayerProps : undefined}
               onHover={handleHover}
               onClick={handleClick}
-              deckProps={deckProps}
+              deckProps={mergedDeckProps}
               deckRef={deckRef}
             />
             {showLoadingOverlay && renderer.isBlocking && (
diff --git a/packages/vis/src/SpatialCanvas/featureTooltipHover.ts b/packages/vis/src/SpatialCanvas/featureTooltipHover.ts
index 91719899..23beb8b8 100644
--- a/packages/vis/src/SpatialCanvas/featureTooltipHover.ts
+++ b/packages/vis/src/SpatialCanvas/featureTooltipHover.ts
@@ -181,15 +181,18 @@ function collectPicks(
       return picks;
     }
 
-    const supplementalPicks = missingLayerIds.flatMap((layerId) =>
-      deck.pickMultipleObjects({
-        x: info.x,
-        y: info.y,
-        radius: pickRadius,
-        depth: 1,
-        layerIds: resolveDeckPickLayerIds(deck, [layerId]),
-      })
-    );
+    // Most "missing" layers simply have no geometry under the cursor, so picking
+    // each one individually performs a wasted `readPixels` GPU round-trip per
+    // layer on every pointer move. Issue a single supplemental pick across all
+    // missing layers instead (depth covers one hit per layer) to recover the
+    // genuinely occluded ones without the per-layer readPixels storm.
+    const supplementalPicks = deck.pickMultipleObjects({
+      x: info.x,
+      y: info.y,
+      radius: pickRadius,
+      depth: missingLayerIds.length,
+      layerIds: resolveDeckPickLayerIds(deck, missingLayerIds),
+    });
     return supplementalPicks.length > 0 ? [...picks, ...supplementalPicks] : picks;
   }
   return [info];
diff --git a/packages/vis/src/SpatialCanvas/index.tsx b/packages/vis/src/SpatialCanvas/index.tsx
index c2545b8e..abef6a6a 100644
--- a/packages/vis/src/SpatialCanvas/index.tsx
+++ b/packages/vis/src/SpatialCanvas/index.tsx
@@ -39,10 +39,16 @@ import { TooltipFieldsPanel } from './TooltipFieldsPanel';
 import { VivLoaderRegistryProvider } from './VivLoaderRegistry';
 import { SpatialCanvasProvider, useSpatialCanvasActions, useSpatialCanvasStore } from './context';
 import { getDeckFromDeckGlRef, resolveHoverFeatureTooltip } from './featureTooltipHover';
-import type { SpatialCanvasStoreApi } from './stores';
 import { layerConfig } from './layerConfig';
+import type { SpatialCanvasStoreApi } from './stores';
 import type { AvailableElement, ElementsByType, ViewState } from './types';
 import type { ImageLayerConfig } from './useLayerData';
+import {
+  type HoverPointerEvent,
+  isHoverDuringDrag,
+  useThrottledHoverTooltip,
+} from './useThrottledHoverTooltip';
+import { type ViewInteractionState, useViewInteractionGate } from './useViewInteractionGate';
 import { generateLayerId, getAllCoordinateSystems } from './utils';
 
 // ============================================
@@ -218,6 +224,7 @@ interface ViewerSectionProps {
   vw: number;
   vh: number;
   onHover: (info: PickingInfo) => void;
+  onInteractionStateChange: (state: ViewInteractionState) => void;
   coordinateSystem: string | null;
   deckRef: React.RefObject<DeckGLRef | null>;
 }
@@ -234,9 +241,11 @@ function ViewerSection({
   vw,
   vh,
   onHover,
+  onInteractionStateChange,
   coordinateSystem,
   deckRef,
 }: ViewerSectionProps) {
+  const deckProps = useMemo(() => ({ onInteractionStateChange }), [onInteractionStateChange]);
   const viewState = useSpatialCanvasStore((s) => s.viewState);
   const actions = useSpatialCanvasActions();
 
@@ -300,6 +309,7 @@ function ViewerSection({
         layerOrder={layerOrder}
         vivLayerProps={vivLayerProps.length > 0 ? vivLayerProps : undefined}
         onHover={onHover}
+        deckProps={deckProps}
         deckRef={deckRef}
       />
       {isBlocking && (
@@ -362,7 +372,9 @@ interface SpatialCanvasInnerProps {
   /** Override default tooltip UI; receives pick position in viewport coordinates. */
   renderTooltip?: (props: SpatialCanvasTooltipRenderProps) => ReactNode;
   /**
-   * When true (default), hover tooltips include picks from all layers under the cursor.
+   * When true, hover tooltips include picks from all layers under the cursor.
+   * Defaults to false because aggregation issues extra per-move GPU pick passes
+   * over large geometry; enable only when stacked-layer tooltips are needed.
    */
   aggregateHoverTooltips?: boolean;
 }
@@ -370,7 +382,7 @@ interface SpatialCanvasInnerProps {
 function SpatialCanvasInner({
   tooltipContainer,
   renderTooltip,
-  aggregateHoverTooltips = true,
+  aggregateHoverTooltips = false,
 }: SpatialCanvasInnerProps) {
   const { spatialData, loading: sdLoading } = useSpatialData();
   const [measureRef, { width, height }] = useMeasure();
@@ -378,12 +390,15 @@ function SpatialCanvasInner({
   const viewerContainerRef = useRef<HTMLDivElement | null>(null);
   const deckRef = useRef<DeckGLRef | null>(null);
   const [fullscreen, setFullscreen] = useState(false);
-  const [pendingFullscreenRefitSize, setPendingFullscreenRefitSize] = useState<{
+  // A one-shot request to refit the view after a fullscreen toggle changes the
+  // container size. Stored in a ref (not state) so consuming it in the resize
+  // effect doesn't require a setState-in-effect.
+  const pendingFullscreenRefitSizeRef = useRef<{
     width: number;
     height: number;
   } | null>(null);
   const [hoverTooltip, setHoverTooltip] = useState<
-    (SpatialFeatureTooltipData & { x: number; y: number }) | null
+    (SpatialFeatureTooltipData & { x: number; y: number; clientX: number; clientY: number }) | null
   >(null);
 
   const coordinateSystem = useSpatialCanvasStore((s) => s.coordinateSystem);
@@ -402,6 +417,10 @@ function SpatialCanvasInner({
 
   const vw = width ?? 0;
   const vh = height ?? 0;
+  // Disable shape picking while the camera is being panned/zoomed. `interacting`
+  // flips at most twice per gesture (start/settle), so this hook re-runs to
+  // rebuild layers with toggled pickability — not on every pan frame.
+  const { interacting, onInteractionStateChange } = useViewInteractionGate();
   const {
     availableElements,
     deckLayers,
@@ -426,17 +445,19 @@ function SpatialCanvasInner({
     // are managed entirely by ViewerSection so this hook never re-runs on pan.
     width: vw,
     height: vh,
+    interacting,
   });
   const hoverPickLayerIds = useMemo(() => Array.from(enabledLayerIds), [enabledLayerIds]);
 
   useEffect(() => {
+    const pending = pendingFullscreenRefitSizeRef.current;
     if (
-      !pendingFullscreenRefitSize ||
+      !pending ||
       !hasEnabledLayers ||
       vw <= 0 ||
       vh <= 0 ||
       isBlocking ||
-      (vw === pendingFullscreenRefitSize.width && vh === pendingFullscreenRefitSize.height)
+      (vw === pending.width && vh === pending.height)
     ) {
       return;
     }
@@ -446,16 +467,8 @@ function SpatialCanvasInner({
       ? viewStateFromBounds(bounds, vw, vh)
       : { target: [0, 0] as [number, number], zoom: 0 };
     actions.setViewState(next);
-    setPendingFullscreenRefitSize(null);
-  }, [
-    actions,
-    getWorldBoundsForVisibleLayers,
-    hasEnabledLayers,
-    isBlocking,
-    pendingFullscreenRefitSize,
-    vh,
-    vw,
-  ]);
+    pendingFullscreenRefitSizeRef.current = null;
+  }, [actions, getWorldBoundsForVisibleLayers, hasEnabledLayers, isBlocking, vh, vw]);
 
   useEffect(() => {
     actions.reset();
@@ -528,17 +541,47 @@ function SpatialCanvasInner({
       return columnName !== tableKeys.instanceKey && columnName !== tableKeys.regionKey;
     }) ?? [];
 
-  const handleHover = useCallback(
+  // The expensive part of hovering: aggregate-pick the feature(s) under the
+  // cursor and position the tooltip. Throttled to one run per animation frame.
+  const resolveTooltip = useCallback(
     (info: PickingInfo) => {
-      const tooltip = resolveHoverFeatureTooltip(info, getFeatureTooltip, {
-        aggregate: aggregateHoverTooltips,
-        deck: getDeckFromDeckGlRef(deckRef),
-        pickLayerIds: hoverPickLayerIds,
+      const tooltip =
+        info.picked && typeof info.x === 'number' && typeof info.y === 'number'
+          ? resolveHoverFeatureTooltip(info, getFeatureTooltip, {
+              aggregate: aggregateHoverTooltips,
+              deck: getDeckFromDeckGlRef(deckRef),
+              pickLayerIds: hoverPickLayerIds,
+            })
+          : null;
+      // Resolve viewport coordinates here (in the event handler) rather than
+      // reading the container ref during render.
+      if (!tooltip) {
+        setHoverTooltip(null);
+        return;
+      }
+      const rect = viewerContainerRef.current?.getBoundingClientRect();
+      setHoverTooltip({
+        ...tooltip,
+        clientX: (rect?.left ?? 0) + tooltip.x,
+        clientY: (rect?.top ?? 0) + tooltip.y,
       });
-      setHoverTooltip(tooltip);
     },
     [aggregateHoverTooltips, getFeatureTooltip, hoverPickLayerIds]
   );
+  const scheduleTooltip = useThrottledHoverTooltip(resolveTooltip);
+
+  const handleHover = useCallback(
+    (info: PickingInfo, event?: HoverPointerEvent) => {
+      // While panning/dragging, deck keeps firing hover events; the gesture is
+      // changing the view, not inspecting features, so suppress tooltip work.
+      if (isHoverDuringDrag(event)) {
+        setHoverTooltip(null);
+        return;
+      }
+      scheduleTooltip(info);
+    },
+    [scheduleTooltip]
+  );
 
   const handleViewerRef = useCallback(
     (node: HTMLDivElement | null) => {
@@ -574,15 +617,10 @@ function SpatialCanvasInner({
   }
 
   const hasElements = Object.values(availableElements).some((arr) => arr.length > 0);
-  const viewerRect = viewerContainerRef.current?.getBoundingClientRect();
   /** Viewport coordinates of the deck.gl pick (for portaled `position: fixed` tooltip). */
-  const tooltipClientPosition =
-    hoverTooltip && viewerRect
-      ? {
-          x: viewerRect.left + hoverTooltip.x,
-          y: viewerRect.top + hoverTooltip.y,
-        }
-      : null;
+  const tooltipClientPosition = hoverTooltip
+    ? { x: hoverTooltip.clientX, y: hoverTooltip.clientY }
+    : null;
 
   const shellStyle: CSSProperties = fullscreen
     ? { ...containerStyle, ...fullscreenOverlayStyle, position: 'fixed' }
@@ -633,7 +671,7 @@ function SpatialCanvasInner({
               type="button"
               style={{ ...selectStyle, marginLeft: 'auto', cursor: 'pointer' }}
               onClick={() => {
-                setPendingFullscreenRefitSize({ width: vw, height: vh });
+                pendingFullscreenRefitSizeRef.current = { width: vw, height: vh };
                 setFullscreen((f) => !f);
               }}
             >
@@ -683,6 +721,7 @@ function SpatialCanvasInner({
               vw={vw}
               vh={vh}
               onHover={handleHover}
+              onInteractionStateChange={onInteractionStateChange}
               coordinateSystem={coordinateSystem}
               deckRef={deckRef}
             />
@@ -866,7 +905,9 @@ export interface SpatialCanvasProps {
    */
   renderTooltip?: (props: SpatialCanvasTooltipRenderProps) => ReactNode;
   /**
-   * When true (default), hover tooltips aggregate picks from all layers under the cursor.
+   * When true, hover tooltips aggregate picks from all layers under the cursor.
+   * Defaults to false because aggregation issues extra per-move GPU pick passes
+   * over large geometry; enable only when stacked-layer tooltips are needed.
    */
   aggregateHoverTooltips?: boolean;
 }
diff --git a/packages/vis/src/SpatialCanvas/renderers/shapesRenderer.ts b/packages/vis/src/SpatialCanvas/renderers/shapesRenderer.ts
index 370fb64e..82ab495c 100644
--- a/packages/vis/src/SpatialCanvas/renderers/shapesRenderer.ts
+++ b/packages/vis/src/SpatialCanvas/renderers/shapesRenderer.ts
@@ -64,6 +64,12 @@ export interface ShapesLayerRenderConfig {
    * layer assembly skips Record→Map conversion on every `getLayers()` call.
    */
   featureStateRuntime?: ShapeFeatureStateRuntime;
+  /**
+   * When false, render the layer non-pickable (autoHighlight + hover picking
+   * off). Used to disable shape picking while the camera is moving. Defaults to
+   * true.
+   */
+  pickingEnabled?: boolean;
 }
 
 /**
@@ -88,6 +94,7 @@ export function renderShapesLayer(config: ShapesLayerRenderConfig): Layer | null
     featureStateRuntime,
     renderData,
     prebuilt,
+    pickingEnabled,
   } = config;
 
   if (!visible) return null;
@@ -114,6 +121,7 @@ export function renderShapesLayer(config: ShapesLayerRenderConfig): Layer | null
       visible,
       opacity,
       modelMatrix,
+      pickingEnabled,
     },
     prebuilt
   );
diff --git a/packages/vis/src/SpatialCanvas/useLayerData.ts b/packages/vis/src/SpatialCanvas/useLayerData.ts
index 01976df3..e66c8830 100644
--- a/packages/vis/src/SpatialCanvas/useLayerData.ts
+++ b/packages/vis/src/SpatialCanvas/useLayerData.ts
@@ -65,10 +65,16 @@ import { createImageLoader } from './renderers/imageRenderer';
 import { renderLabelsLayer } from './renderers/labelsRenderer';
 import { type PointData, renderPointsLayer } from './renderers/pointsRenderer';
 import { loadShapesData, renderShapesLayer } from './renderers/shapesRenderer';
-import type { AvailableElement, ChannelConfig, ElementsByType, LayerConfig, ShapesLayerConfig } from './types';
+import type {
+  AvailableElement,
+  ChannelConfig,
+  ElementsByType,
+  LayerConfig,
+  ShapesLayerConfig,
+} from './types';
 import {
-  mergeVivImagePassthroughProps,
   type VivImagePassthroughOptions,
+  mergeVivImagePassthroughProps,
 } from './vivImagePassthrough';
 
 export interface ImageLoaderData {
@@ -191,7 +197,7 @@ export type SpatialFeaturePickEventData = ShapeFeaturePickEventData | LabelFeatu
 
 interface UseLayerDataResult {
   /** Get deck.gl layers ready for rendering (shapes, points, etc.) */
-  getLayers: () => Layer[];
+  getLayers: (options?: { pickingEnabled?: boolean }) => Layer[];
   /** Get Viv layer props for image layers */
   getVivLayerProps: () => ImageLayerConfig[];
   /** Raw loaded image pipeline data (defaults) for the properties UI */
@@ -480,8 +486,15 @@ export function useLayerData(
     Map<string, { signature: string; runtime: ShapeFeatureStateRuntime }>
   >(new Map());
 
+  // Mirror the latest `layers` into a ref so async loaders (which run well after
+  // commit) can read the current config without a stale closure. Written in an
+  // effect rather than during render to satisfy the Rules of React; the only
+  // render-time reader (element resolution in `hasRenderableLayerData`) is
+  // unaffected by a one-commit lag because element type/key are stable per id.
   const layersRef = useRef(layers);
-  layersRef.current = layers;
+  useEffect(() => {
+    layersRef.current = layers;
+  }, [layers]);
 
   const [layerLoadStates, setLayerLoadStates] = useState<Record<string, LayerLoadState>>({});
   const [, setLoadedDataRevision] = useState(0);
@@ -1213,7 +1226,11 @@ export function useLayerData(
     return unionBoundsList(list);
   }, [layerOrder, layers, getWorldBoundsForLayer]);
 
-  const getLayers = useCallback((): Layer[] => {
+  const getLayers = useCallback((options?: { pickingEnabled?: boolean }): Layer[] => {
+    // When the camera is moving we disable shape picking (autoHighlight + hover)
+    // to avoid deck re-rendering the full shape geometry into the picking buffer
+    // on every pointer move. Defaults to enabled.
+    const pickingEnabled = options?.pickingEnabled ?? true;
     const deckLayers: Layer[] = [];
     const loaded = loadedDataRef.current;
 
@@ -1247,6 +1264,7 @@ export function useLayerData(
             ),
             renderData: shapeData.renderData,
             prebuilt: loaded.shapePrebuiltData.get(layerId)?.prebuilt,
+            pickingEnabled,
           });
           if (layer) deckLayers.push(layer);
         }
@@ -1321,9 +1339,12 @@ export function useLayerData(
     return loadedDataRef.current.images.get(elem.key);
   }, []);
 
-  const getImageLoadedDataByElementKey = useCallback((elementKey: string): ImageLoaderData | undefined => {
-    return loadedDataRef.current.images.get(elementKey);
-  }, []);
+  const getImageLoadedDataByElementKey = useCallback(
+    (elementKey: string): ImageLoaderData | undefined => {
+      return loadedDataRef.current.images.get(elementKey);
+    },
+    []
+  );
 
   const getLabelsLayerLoadedData = useCallback((layerId: string): LabelsLoaderData | undefined => {
     const elem = resolveLayerElement(layerId, layersRef.current[layerId], elementMap.current);
@@ -1613,6 +1634,16 @@ export function useLayerData(
 
   const isBlocking = useMemo(
     () =>
+      // `hasRenderableLayerData` consults `loadedDataRef`, an imperatively
+      // maintained cache of already-loaded layer data. Reading it during render
+      // is intentional here: the blocking overlay must distinguish a layer that
+      // is loading for the first time (block) from one that is refreshing but
+      // already has data to show (don't block), and that distinction only lives
+      // in the cache. Freshness is guaranteed because `layerLoadStates` (a real
+      // state value in this memo's deps) changes in lockstep with every load,
+      // forcing this memo to recompute. Lifting the cache to state/useSyncExternalStore
+      // would satisfy the rule but defeats the performance reason the ref exists.
+      // eslint-disable-next-line react-hooks/refs -- intentional external-store read, see comment above
       layerOrder.some((layerId) => {
         const config = layers[layerId];
         if (!config?.visible) return false;
diff --git a/packages/vis/src/SpatialCanvas/useThrottledHoverTooltip.ts b/packages/vis/src/SpatialCanvas/useThrottledHoverTooltip.ts
new file mode 100644
index 00000000..fff4337f
--- /dev/null
+++ b/packages/vis/src/SpatialCanvas/useThrottledHoverTooltip.ts
@@ -0,0 +1,91 @@
+import type { PickingInfo } from 'deck.gl';
+import { useCallback, useEffect, useRef } from 'react';
+
+/**
+ * Minimal shape of the deck.gl hover event (a mjolnir pointer event). `srcEvent`
+ * is the underlying DOM pointer event; its `buttons` bitmask is non-zero while a
+ * pointer button is held, which is how we detect an in-progress pan/drag.
+ */
+export type HoverPointerEvent = { srcEvent?: { buttons?: number } | null };
+
+/** True when the hover event was produced while a pointer button is held (pan/drag). */
+export function isHoverDuringDrag(event?: HoverPointerEvent | null): boolean {
+  return (event?.srcEvent?.buttons ?? 0) !== 0;
+}
+
+/**
+ * Wraps an expensive hover-tooltip resolver so it runs at most once per animation
+ * frame using the most recent pointer position, and skips re-running while the
+ * pointer sits on the same pixel.
+ *
+ * deck.gl fires `onHover` on every pointer move, and resolving an aggregated
+ * tooltip performs one or more `pickMultipleObjects` GPU reads (each a
+ * synchronous `readPixels` stall). Coalescing to a frame and de-duplicating
+ * stationary positions keeps pointer movement smooth without changing pick
+ * semantics. Cheaper hover work (single-pick feature/shape callbacks) should run
+ * directly from the handler and not go through here.
+ */
+export function useThrottledHoverTooltip(
+  resolve: (info: PickingInfo) => void
+): (info: PickingInfo) => void {
+  // Keep the latest resolver without re-subscribing the scheduler; written in an
+  // effect (not during render) per the Rules of React.
+  const resolveRef = useRef(resolve);
+  useEffect(() => {
+    resolveRef.current = resolve;
+  }, [resolve]);
+
+  const rafRef = useRef<number | null>(null);
+  const latestRef = useRef<PickingInfo | null>(null);
+  const lastPosRef = useRef<{ x: number; y: number } | null>(null);
+
+  const flush = useCallback(() => {
+    rafRef.current = null;
+    const info = latestRef.current;
+    latestRef.current = null;
+    if (!info) return;
+
+    const { x, y, picked } = info;
+    // While the pointer hovers the same pixel over a feature, the pick result is
+    // unchanged, so skip the redundant GPU read. Always run when nothing is
+    // picked so moving off a feature reliably clears the tooltip.
+    if (
+      picked &&
+      typeof x === 'number' &&
+      typeof y === 'number' &&
+      lastPosRef.current &&
+      lastPosRef.current.x === x &&
+      lastPosRef.current.y === y
+    ) {
+      return;
+    }
+    lastPosRef.current = typeof x === 'number' && typeof y === 'number' ? { x, y } : null;
+    resolveRef.current(info);
+  }, []);
+
+  const schedule = useCallback(
+    (info: PickingInfo) => {
+      latestRef.current = info;
+      if (rafRef.current !== null) return;
+      if (typeof requestAnimationFrame === 'function') {
+        rafRef.current = requestAnimationFrame(flush);
+      } else {
+        // Non-browser environments (e.g. SSR/tests): resolve synchronously.
+        flush();
+      }
+    },
+    [flush]
+  );
+
+  useEffect(
+    () => () => {
+      if (rafRef.current !== null && typeof cancelAnimationFrame === 'function') {
+        cancelAnimationFrame(rafRef.current);
+        rafRef.current = null;
+      }
+    },
+    []
+  );
+
+  return schedule;
+}
diff --git a/packages/vis/src/SpatialCanvas/useViewInteractionGate.ts b/packages/vis/src/SpatialCanvas/useViewInteractionGate.ts
new file mode 100644
index 00000000..b30d767c
--- /dev/null
+++ b/packages/vis/src/SpatialCanvas/useViewInteractionGate.ts
@@ -0,0 +1,61 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+/** Minimal shape of deck.gl's interaction state (a subset of `InteractionState`). */
+export interface ViewInteractionState {
+  isDragging?: boolean;
+  isPanning?: boolean;
+  isZooming?: boolean;
+  inTransition?: boolean;
+}
+
+export interface ViewInteractionGate {
+  /** True while the camera is being panned/zoomed (or settling within the idle delay). */
+  interacting: boolean;
+  /** Wire to deck.gl's `onInteractionStateChange` (e.g. via `deckProps`). */
+  onInteractionStateChange: (state: ViewInteractionState) => void;
+}
+
+/**
+ * Tracks whether the deck.gl view is being actively manipulated, with the
+ * transition back to idle debounced by `idleDelayMs`.
+ *
+ * Picking large shape layers is expensive: deck re-renders the full geometry
+ * into the picking framebuffer on every pointer move to service hover /
+ * autoHighlight. Disabling shape picking while `interacting` is true removes that
+ * per-move cost during pan/zoom; the debounce avoids re-enabling (and paying a
+ * picking pass) in the gaps between rapid drag steps.
+ */
+export function useViewInteractionGate(idleDelayMs = 150): ViewInteractionGate {
+  const [interacting, setInteracting] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const onInteractionStateChange = useCallback(
+    (state: ViewInteractionState) => {
+      const active = Boolean(
+        state && (state.isDragging || state.isPanning || state.isZooming || state.inTransition)
+      );
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+      if (active) {
+        setInteracting(true);
+      } else {
+        timerRef.current = setTimeout(() => {
+          timerRef.current = null;
+          setInteracting(false);
+        }, idleDelayMs);
+      }
+    },
+    [idleDelayMs]
+  );
+
+  useEffect(
+    () => () => {
+      if (timerRef.current !== null) clearTimeout(timerRef.current);
+    },
+    []
+  );
+
+  return { interacting, onInteractionStateChange };
+}
diff --git a/packages/vis/src/Table/index.tsx b/packages/vis/src/Table/index.tsx
index 4cc58869..db530355 100644
--- a/packages/vis/src/Table/index.tsx
+++ b/packages/vis/src/Table/index.tsx
@@ -10,14 +10,20 @@ export default function TableComponent() {
   const table = useMemo(() => {
     return spatialData?.tables?.[selectedTable];
   }, [selectedTable, spatialData?.tables]);
-  const [tableData, setTableData] = useState<any>(undefined);
+  // Keep the resolved data tagged with the table it came from so stale data is
+  // hidden by deriving during render rather than clearing via setState-in-effect.
+  const [tableData, setTableData] = useState<{ table: unknown; data: any } | undefined>(undefined);
   useEffect(() => {
-    if (table) {
-      table.getAnnDataJS().then((t) => setTableData(t));
-    } else {
-      setTableData(undefined);
-    }
+    if (!table) return;
+    let cancelled = false;
+    table.getAnnDataJS().then((t) => {
+      if (!cancelled) setTableData({ table, data: t });
+    });
+    return () => {
+      cancelled = true;
+    };
   }, [table]);
+  const currentData = tableData && tableData.table === table ? tableData.data : undefined;
   return (
     <div>
       {spatialData?.tables && (
@@ -29,7 +35,7 @@ export default function TableComponent() {
           ))}
         </select>
       )}
-      {tableData && <JsonView value={tableData} style={darkTheme} />}
+      {currentData && <JsonView value={currentData} style={darkTheme} />}
     </div>
   );
 }
diff --git a/packages/vis/src/Transforms/index.tsx b/packages/vis/src/Transforms/index.tsx
index 961ebed8..6734696b 100644
--- a/packages/vis/src/Transforms/index.tsx
+++ b/packages/vis/src/Transforms/index.tsx
@@ -1,8 +1,8 @@
+import type { SpatialElement } from '@spatialdata/core';
 import { useSpatialData } from '@spatialdata/react';
 import JsonView from '@uiw/react-json-view';
 import { darkTheme } from '@uiw/react-json-view/dark';
-import { useEffect, useMemo, useState } from 'react';
-import type { SpatialElement } from '@spatialdata/core';
+import { useMemo, useState } from 'react';
 
 const SPATIAL_ELEMENT_TYPES = ['images', 'labels', 'shapes', 'points'] as const;
 type SpatialElementType = (typeof SPATIAL_ELEMENT_TYPES)[number];
@@ -40,10 +40,19 @@ export default function TransformsComponent() {
     return entries;
   }, [spatialData]);
 
+  // Default to the first element when the user hasn't picked one (or their pick
+  // is no longer available). Derived during render instead of synced via effect.
+  const effectiveElementId = useMemo(() => {
+    if (selectedElementId && allElements.some((e) => getElementId(e) === selectedElementId)) {
+      return selectedElementId;
+    }
+    return allElements[0] ? getElementId(allElements[0]) : '';
+  }, [allElements, selectedElementId]);
+
   // Find currently selected element
   const selectedEntry = useMemo(() => {
-    return allElements.find((e) => getElementId(e) === selectedElementId);
-  }, [allElements, selectedElementId]);
+    return allElements.find((e) => getElementId(e) === effectiveElementId);
+  }, [allElements, effectiveElementId]);
 
   // Get coordinate systems for selected element
   const coordinateSystems = useMemo(() => {
@@ -51,30 +60,17 @@ export default function TransformsComponent() {
     return selectedEntry.element.coordinateSystems;
   }, [selectedEntry]);
 
-  // Default to first element when data loads or changes
-  useEffect(() => {
-    if (
-      allElements.length > 0 &&
-      (!selectedElementId || !allElements.find((e) => getElementId(e) === selectedElementId))
-    ) {
-      setSelectedElementId(getElementId(allElements[0]));
-    }
-  }, [allElements, selectedElementId]);
-
-  // Default to first coordinate system when element changes
-  useEffect(() => {
-    if (coordinateSystems.length > 0 && (!selectedCS || !coordinateSystems.includes(selectedCS))) {
-      setSelectedCS(coordinateSystems[0]);
-    } else if (coordinateSystems.length === 0) {
-      setSelectedCS('');
-    }
+  // Default to the first coordinate system, derived the same way.
+  const effectiveCS = useMemo(() => {
+    if (selectedCS && coordinateSystems.includes(selectedCS)) return selectedCS;
+    return coordinateSystems[0] ?? '';
   }, [coordinateSystems, selectedCS]);
 
   // Get transformation result
   const transformData = useMemo(() => {
-    if (!selectedEntry || !selectedCS) return null;
+    if (!selectedEntry || !effectiveCS) return null;
 
-    const result = selectedEntry.element.getTransformation(selectedCS);
+    const result = selectedEntry.element.getTransformation(effectiveCS);
     if (result.ok) {
       const t = result.value;
       return {
@@ -90,7 +86,7 @@ export default function TransformsComponent() {
       error: result.error.message,
       availableCoordinateSystems: result.error.availableCoordinateSystems,
     };
-  }, [selectedEntry, selectedCS]);
+  }, [selectedEntry, effectiveCS]);
 
   if (loading) return <div>Loading...</div>;
   if (error) return <div>Error: {error.message}</div>;
@@ -104,7 +100,7 @@ export default function TransformsComponent() {
         <label style={{ display: 'flex', flexDirection: 'column', gap: '0.25rem' }}>
           <span>Element:</span>
           <select
-            value={selectedElementId}
+            value={effectiveElementId}
             onChange={(e) => setSelectedElementId(e.target.value)}
             style={{ minWidth: '200px' }}
           >
@@ -123,7 +119,7 @@ export default function TransformsComponent() {
         <label style={{ display: 'flex', flexDirection: 'column', gap: '0.25rem' }}>
           <span>Coordinate System:</span>
           <select
-            value={selectedCS}
+            value={effectiveCS}
             onChange={(e) => setSelectedCS(e.target.value)}
             disabled={coordinateSystems.length === 0}
             style={{ minWidth: '150px' }}
diff --git a/packages/vis/tests/featureTooltipHover.spec.ts b/packages/vis/tests/featureTooltipHover.spec.ts
index e892c256..0ed4deec 100644
--- a/packages/vis/tests/featureTooltipHover.spec.ts
+++ b/packages/vis/tests/featureTooltipHover.spec.ts
@@ -6,8 +6,7 @@ import {
   resolveHoverFeatureTooltip,
 } from '../src/SpatialCanvas/featureTooltipHover.js';
 
-const LABELS_BITMASK_LAYER_ID =
-  'sub-layer-0-0-0-0,512,512,0-labels:mask-#spatial-view#-labels';
+const LABELS_BITMASK_LAYER_ID = 'sub-layer-0-0-0-0,512,512,0-labels:mask-#spatial-view#-labels';
 
 describe('featureTooltipHover', () => {
   it('normalizes viv-suffixed deck layer ids', () => {
@@ -347,6 +346,47 @@ describe('featureTooltipHover', () => {
     );
   });
 
+  it('recovers multiple occluded layers with a single batched supplemental pick', () => {
+    const getFeatureTooltip = vi.fn((layerId: string) => ({
+      elementKey: layerId,
+      elementType: 'shapes' as const,
+      layerId,
+      items: [{ label: 'element', value: layerId }],
+    }));
+    // First (aggregate) pass sees only shapes:a; shapes:b and shapes:c are
+    // "missing" and must be recovered without one readPixels per missing layer.
+    const pickMultipleObjects = vi.fn(({ layerIds }: { layerIds?: string[] }) => {
+      if (layerIds && layerIds.length === 3) {
+        return [{ picked: true, x: 10, y: 20, layer: { id: 'shapes:a' }, index: 0, object: {} }];
+      }
+      return [
+        { picked: true, x: 10, y: 20, layer: { id: 'shapes:b' }, index: 0, object: {} },
+        { picked: true, x: 10, y: 20, layer: { id: 'shapes:c' }, index: 0, object: {} },
+      ];
+    });
+
+    const result = resolveHoverFeatureTooltip(
+      { picked: true, x: 10, y: 20, layer: { id: 'shapes:a' }, index: 0, object: {} },
+      getFeatureTooltip,
+      {
+        deck: { pickMultipleObjects },
+        pickLayerIds: ['shapes:a', 'shapes:b', 'shapes:c'],
+      }
+    );
+
+    // One aggregate pass + one batched supplemental pass = 2 total (not 1 per
+    // missing layer).
+    expect(pickMultipleObjects).toHaveBeenCalledTimes(2);
+    expect(pickMultipleObjects).toHaveBeenLastCalledWith({
+      x: 10,
+      y: 20,
+      radius: 4,
+      depth: 2,
+      layerIds: ['shapes:b', 'shapes:c'],
+    });
+    expect(result?.sections).toHaveLength(3);
+  });
+
   it('falls back to the original hover pick when filtered aggregation returns no picks', () => {
     const getFeatureTooltip = vi.fn(() => ({
       elementKey: 'cells',
diff --git a/packages/vis/tests/throttledHoverTooltip.spec.ts b/packages/vis/tests/throttledHoverTooltip.spec.ts
new file mode 100644
index 00000000..fa334505
--- /dev/null
+++ b/packages/vis/tests/throttledHoverTooltip.spec.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { isHoverDuringDrag } from '../src/SpatialCanvas/useThrottledHoverTooltip.js';
+
+describe('isHoverDuringDrag', () => {
+  it('treats a hover with no held button as a normal hover', () => {
+    expect(isHoverDuringDrag(undefined)).toBe(false);
+    expect(isHoverDuringDrag(null)).toBe(false);
+    expect(isHoverDuringDrag({})).toBe(false);
+    expect(isHoverDuringDrag({ srcEvent: null })).toBe(false);
+    expect(isHoverDuringDrag({ srcEvent: { buttons: 0 } })).toBe(false);
+  });
+
+  it('treats a hover with a held pointer button as an in-progress drag/pan', () => {
+    expect(isHoverDuringDrag({ srcEvent: { buttons: 1 } })).toBe(true);
+    expect(isHoverDuringDrag({ srcEvent: { buttons: 2 } })).toBe(true);
+    expect(isHoverDuringDrag({ srcEvent: { buttons: 4 } })).toBe(true);
+  });
+});

From ac2e2daba700f5cd5d3963adc977ece77e30ed8d Mon Sep 17 00:00:00 2001
From: Peter Todd <ptr.tdd@gmail.com>
Date: Tue, 30 Jun 2026 07:01:02 +0100
Subject: [PATCH 2/9] Fix "Center on layer" stuck disabled (regression from
 refs cleanup)

The Rules-of-React cleanup moved `layersRef.current = layers` from render into
a commit-phase effect. But that ref is read synchronously during render by
`hasRenderableLayerData` (and the loaded-data getters consumed via context),
which drives the "Center on layer" button's enablement and the image/labels
panels. Deferring the write let those readers observe a stale layer config on
the render where a layer first appears, so the button could stay disabled
indefinitely with no follow-up render to correct it.

Restore the synchronous mirror (it must be written during render because it is
consumed during render) with a documented eslint-disable. `pnpm lint:react`
stays clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/vis/src/SpatialCanvas/useLayerData.ts | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/packages/vis/src/SpatialCanvas/useLayerData.ts b/packages/vis/src/SpatialCanvas/useLayerData.ts
index e66c8830..dbc86a41 100644
--- a/packages/vis/src/SpatialCanvas/useLayerData.ts
+++ b/packages/vis/src/SpatialCanvas/useLayerData.ts
@@ -486,15 +486,17 @@ export function useLayerData(
     Map<string, { signature: string; runtime: ShapeFeatureStateRuntime }>
   >(new Map());
 
-  // Mirror the latest `layers` into a ref so async loaders (which run well after
-  // commit) can read the current config without a stale closure. Written in an
-  // effect rather than during render to satisfy the Rules of React; the only
-  // render-time reader (element resolution in `hasRenderableLayerData`) is
-  // unaffected by a one-commit lag because element type/key are stable per id.
+  // Mirror the latest `layers` into a ref. This is read both by async loaders
+  // (which run well after commit) AND synchronously during render by
+  // `hasRenderableLayerData` / the loaded-data getters consumed via context
+  // (e.g. the "Center on layer" button's enablement, image/labels panels). It
+  // must therefore be written during render, not in an effect: deferring it to a
+  // commit-phase effect lets those render-time readers observe a stale config on
+  // the render where a layer first appears, leaving derived UI (the Center
+  // button) wrongly disabled with no follow-up render to correct it.
   const layersRef = useRef(layers);
-  useEffect(() => {
-    layersRef.current = layers;
-  }, [layers]);
+  // eslint-disable-next-line react-hooks/refs -- intentional latest-`layers` mirror consumed during render, see comment above
+  layersRef.current = layers;
 
   const [layerLoadStates, setLayerLoadStates] = useState<Record<string, LayerLoadState>>({});
   const [, setLoadedDataRevision] = useState(0);

From db52fa49a8f5bff4bdbc6ce3ea5c1aa10e5b3cdf Mon Sep 17 00:00:00 2001
From: Peter Todd <ptr.tdd@gmail.com>
Date: Thu, 2 Jul 2026 07:42:30 +0100
Subject: [PATCH 3/9] demo: auto-select a free port for the vis demo dev server

`dev:demo` was pinned to 127.0.0.1:5173 with `--strictPort`, so it failed hard
when 5173 was already taken (e.g. another project's dev server). Prefer 5173 but
fall back to the next free port, and honour the PORT env var when a launcher
pins one.

- vite.config.demo.ts: port = Number(process.env.PORT) || 5173, strictPort: false.
- package.json: drop the hardcoded `--host 127.0.0.1 --port 5173 --strictPort`
  from `dev:demo` (host/port now come from the config).
- .claude/launch.json: run `dev:demo` with autoPort: true so the preview server
  assigns a free port via PORT.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .claude/launch.json              | 3 ++-
 packages/vis/package.json        | 2 +-
 packages/vis/vite.config.demo.ts | 7 +++++--
 3 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/.claude/launch.json b/.claude/launch.json
index aef62964..c5c3fb99 100644
--- a/.claude/launch.json
+++ b/.claude/launch.json
@@ -5,7 +5,8 @@
       "name": "vis-demo",
       "runtimeExecutable": "pnpm",
       "runtimeArgs": ["--filter", "@spatialdata/vis", "dev:demo"],
-      "port": 5173
+      "port": 5173,
+      "autoPort": true
     }
   ]
 }
diff --git a/packages/vis/package.json b/packages/vis/package.json
index 4ae88ed5..49493ed7 100644
--- a/packages/vis/package.json
+++ b/packages/vis/package.json
@@ -21,7 +21,7 @@
     "build": "vite build && tsc --noEmit",
     "dev": "node scripts/dev.mjs",
     "dev:stop": "node ../../scripts/dev-stop.mjs",
-    "dev:demo": "vite --config vite.config.demo.ts --host 127.0.0.1 --port 5173 --strictPort",
+    "dev:demo": "vite --config vite.config.demo.ts",
     "watch": "vite build --watch",
     "test": "vitest run",
     "test:watch": "vitest",
diff --git a/packages/vis/vite.config.demo.ts b/packages/vis/vite.config.demo.ts
index 77894c06..34c9e04a 100644
--- a/packages/vis/vite.config.demo.ts
+++ b/packages/vis/vite.config.demo.ts
@@ -29,8 +29,11 @@ export default defineConfig({
   assetsInclude: ['**/*.wasm'],
   server: {
     host: '127.0.0.1',
-    port: 5173,
-    strictPort: true,
+    // Prefer 5173 but fall back to the next free port when it's taken (e.g. another
+    // dev server is already running). Honours the PORT env var when set, so a
+    // launcher can pin the port. `strictPort` stays off so the fallback can happen.
+    port: Number(process.env.PORT) || 5173,
+    strictPort: false,
     open: false,
     proxy: {
       '/test-fixtures': {

From 264cdcf1bf77bb3d2a0eb87d0f00339e52e6288e Mon Sep 17 00:00:00 2001
From: Peter Todd <ptr.tdd@gmail.com>
Date: Thu, 2 Jul 2026 07:56:54 +0100
Subject: [PATCH 4/9] Harden elementMap against render-time staleness
 (Center-button bug class)

`elementMap` (layerId/element lookup) was a useRef populated in a
useEffect([availableElements]), yet it's read *during render* by
`hasRenderableLayerData` (which gates the "Center on layer" button) and by
`loadData`. An effect-deferred write means a render/effect that runs before the
write observes a commit-stale map -> element resolution returns undefined ->
button stuck disabled, with no follow-up render to correct it. This is the same
hazard class as the earlier `layersRef` regression.

Fix by computing the map with useMemo (rebuilds only when availableElements
changes) and mirroring it into a stable ref written synchronously during render.
That keeps render-time reads current, preserves stable identity (no dependency-
array churn across the many consuming callbacks / the isBlocking memo / loadData),
and needs a single documented eslint-disable for the intentional latest-value
mirror. `pnpm lint:react` stays clean (no new warnings).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/vis/src/SpatialCanvas/useLayerData.ts | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/packages/vis/src/SpatialCanvas/useLayerData.ts b/packages/vis/src/SpatialCanvas/useLayerData.ts
index dbc86a41..74703186 100644
--- a/packages/vis/src/SpatialCanvas/useLayerData.ts
+++ b/packages/vis/src/SpatialCanvas/useLayerData.ts
@@ -505,18 +505,25 @@ export function useLayerData(
     setLoadedDataRevision((revision) => revision + 1);
   }, []);
 
-  // Build a map of element key -> AvailableElement for quick lookup
-  const elementMap = useRef<Map<string, AvailableElement>>(new Map());
-
-  useEffect(() => {
+  // Build a map of element key -> AvailableElement for quick lookup. Memoised so it
+  // only rebuilds when `availableElements` changes...
+  const elementMapValue = useMemo(() => {
     const map = new Map<string, AvailableElement>();
     for (const type of ['images', 'shapes', 'points', 'labels'] as const) {
       for (const elem of availableElements[type]) {
         map.set(`${elem.type}:${elem.key}`, elem);
       }
     }
-    elementMap.current = map;
+    return map;
   }, [availableElements]);
+  // ...and mirrored into a stable ref so render-time consumers (e.g. the "Center on
+  // layer" enablement via `hasRenderableLayerData`) and async loaders read the
+  // current map without adding it — and its identity churn — to every dependency
+  // array. Written during render, NOT in an effect: an effect-deferred write let
+  // render-time readers observe a commit-stale map, which left the button disabled.
+  const elementMap = useRef(elementMapValue);
+  // eslint-disable-next-line react-hooks/refs -- intentional synchronous latest-value mirror consumed during render, see comment above
+  elementMap.current = elementMapValue;
 
   const setLayerResourceStatus = useCallback(
     (layerId: string, resource: keyof LayerLoadState, status: ResourceLoadStatus) => {

From 1e492cf7e039dd2b82d360d4750a2fc93959df08 Mon Sep 17 00:00:00 2001
From: Peter Todd <ptr.tdd@gmail.com>
Date: Thu, 2 Jul 2026 08:35:55 +0100
Subject: [PATCH 5/9] Add hoverTooltipMode (off / simple / aggregate) with UI
 selector
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the boolean `aggregateHoverTooltips` with a tri-state `hoverTooltipMode`
on `SpatialCanvas` and the headless `SpatialCanvasViewer`:

- 'simple' (default): tooltip from the single top-most pick deck already does
  for hover/highlight — no extra GPU passes.
- 'aggregate': adds `pickMultipleObjects` passes to include every layer under
  the cursor (more expensive; for stacked-layer tooltips).
- 'off': shape layers are built non-pickable (autoHighlight off, no picking-
  buffer render) and no tooltip is resolved — the cheapest mode.

`SpatialCanvas` exposes a "Tooltips" selector in the controls bar (initial value
from the prop). The renderer hook now takes `pickingEnabled` (mode !== 'off' &&
!interacting) instead of `interacting`. Export `HoverTooltipMode` from the
package root.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ...lcanvas-picking-perf-and-rules-of-react.md | 13 +++--
 .../src/SpatialCanvas/SpatialCanvasViewer.tsx | 44 ++++++++++-------
 packages/vis/src/SpatialCanvas/index.tsx      | 47 +++++++++++++------
 packages/vis/src/SpatialCanvas/public.ts      |  1 +
 packages/vis/src/index.ts                     |  1 +
 5 files changed, 71 insertions(+), 35 deletions(-)

diff --git a/.changeset/spatialcanvas-picking-perf-and-rules-of-react.md b/.changeset/spatialcanvas-picking-perf-and-rules-of-react.md
index 3bf22b90..67be14cf 100644
--- a/.changeset/spatialcanvas-picking-perf-and-rules-of-react.md
+++ b/.changeset/spatialcanvas-picking-perf-and-rules-of-react.md
@@ -8,11 +8,14 @@ SpatialCanvas hover/picking performance and Rules-of-React cleanup.
 
 Picking/tooltip performance:
 
-- `aggregateHoverTooltips` now defaults to `false`. Aggregation issued extra
-  `pickMultipleObjects` GPU passes on every pointer move (on top of the pick
-  deck.gl already does for hover/highlight), which is very expensive over large
-  pickable geometry. Single-pick hover uses the existing pick; enable
-  aggregation explicitly when stacked-layer tooltips are needed.
+- New `hoverTooltipMode` prop (`'off' | 'simple' | 'aggregate'`, default
+  `'simple'`) on `SpatialCanvas` and `SpatialCanvasViewer`, with a matching
+  selector in the `SpatialCanvas` UI. `'simple'` resolves the tooltip from the
+  single top-most pick deck.gl already does for hover/highlight; `'aggregate'`
+  adds `pickMultipleObjects` GPU passes to include every layer under the cursor
+  (more expensive); `'off'` makes shape layers non-pickable entirely (no
+  autoHighlight, no picking-buffer render) — the cheapest mode. Replaces the
+  earlier boolean `aggregateHoverTooltips`.
 - Shape layers are made non-pickable (and `autoHighlight` disabled) while the
   camera is being panned/zoomed, so deck.gl does not re-render the shape
   geometry into the picking buffer during gestures. New `pickingEnabled` option
diff --git a/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx b/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
index d78a9fd1..e5d953c0 100644
--- a/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
+++ b/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
@@ -60,6 +60,16 @@ export type SpatialCanvasViewerRenderTooltip =
   | false
   | ((props: SpatialCanvasTooltipRenderProps) => ReactNode);
 
+/**
+ * Hover tooltip / picking behaviour:
+ * - `'off'`: no hover tooltip, and shape layers are made non-pickable (no
+ *   autoHighlight, no picking buffer render) — the cheapest mode.
+ * - `'simple'` (default): tooltip from the single top-most pick under the cursor.
+ * - `'aggregate'`: tooltip aggregated across all layers under the cursor, which
+ *   issues extra `pickMultipleObjects` GPU passes per pointer move.
+ */
+export type HoverTooltipMode = 'off' | 'simple' | 'aggregate';
+
 type SpatialFeaturePickEventRuntimeFields = {
   coordinateSystem: string | null;
   spatialData?: SpatialData | null;
@@ -101,13 +111,11 @@ export interface SpatialCanvasViewerProps {
   autoFit?: boolean;
   style?: CSSProperties;
   /**
-   * When true, hover tooltips aggregate picks from all layers under the cursor.
-   * This issues extra `pickMultipleObjects` GPU passes per pointer move on top of
-   * the pick deck already does for hover/highlight, which is expensive over large
-   * pickable geometry — so it defaults to false (single top pick from the hover
-   * info). Enable it only when stacked-layer tooltips are needed.
+   * Hover tooltip / picking behaviour: `'off'` | `'simple'` (default) |
+   * `'aggregate'`. See {@link HoverTooltipMode}. `'aggregate'` is more expensive
+   * (extra GPU pick passes per move); `'off'` disables shape picking entirely.
    */
-  aggregateHoverTooltips?: boolean;
+  hoverTooltipMode?: HoverTooltipMode;
   /** Global fallback Viv LayerExtension instances for image layers. */
   vivImageExtensions?: unknown[];
   /** Per-image LayerExtension factory (runtime attachment). */
@@ -195,10 +203,11 @@ interface UseSpatialCanvasRendererFromLayerInputsOptions {
   autoFit?: boolean;
   vivPassthrough?: VivImagePassthroughOptions;
   /**
-   * When true, the camera is being panned/zoomed and shape picking is disabled
-   * to avoid per-move picking-buffer renders over large geometry.
+   * When false, shape layers are built non-pickable (autoHighlight off), so deck
+   * does not render their geometry into the picking buffer. Used both for the
+   * "off" tooltip mode and to suppress picking during pan/zoom. Defaults to true.
    */
-  interacting?: boolean;
+  pickingEnabled?: boolean;
 }
 
 export function useSpatialCanvasRendererFromLayerInputs({
@@ -215,7 +224,7 @@ export function useSpatialCanvasRendererFromLayerInputs({
   sortDeckLayers,
   autoFit = true,
   vivPassthrough,
-  interacting = false,
+  pickingEnabled = true,
 }: UseSpatialCanvasRendererFromLayerInputsOptions) {
   ensureCodecWorkers();
 
@@ -237,7 +246,7 @@ export function useSpatialCanvasRendererFromLayerInputs({
     vivPassthrough
   );
 
-  const generatedDeckLayers = layerData.getLayers({ pickingEnabled: !interacting });
+  const generatedDeckLayers = layerData.getLayers({ pickingEnabled });
   const deckLayers = useMemo(() => {
     const composed = composeSpatialDeckLayers(generatedDeckLayers, [
       ...(hostDeckLayers ?? []),
@@ -413,7 +422,7 @@ function SpatialCanvasViewerInner({
   showLoadingOverlay = true,
   autoFit = true,
   style,
-  aggregateHoverTooltips = false,
+  hoverTooltipMode = 'simple',
   vivImageExtensions,
   vivImageExtensionResolver,
   vivImagePropsResolver,
@@ -422,6 +431,8 @@ function SpatialCanvasViewerInner({
   const viewerContainerRef = useRef<HTMLDivElement | null>(null);
   const deckRef = useRef<DeckGLRef | null>(null);
   const { interacting, onInteractionStateChange } = useViewInteractionGate();
+  // Shapes are pickable unless tooltips are off or the camera is being moved.
+  const pickingEnabled = hoverTooltipMode !== 'off' && !interacting;
   const [hoverTooltip, setHoverTooltip] = useState<
     (SpatialFeatureTooltipData & { x: number; y: number; clientX: number; clientY: number }) | null
   >(null);
@@ -464,7 +475,7 @@ function SpatialCanvasViewerInner({
     sortDeckLayers: Boolean(renderStack),
     autoFit,
     vivPassthrough,
-    interacting,
+    pickingEnabled,
   });
   const hoverPickLayerIds = useMemo(
     () => Array.from(renderer.enabledLayerIds),
@@ -481,13 +492,14 @@ function SpatialCanvasViewerInner({
   // cursor and position the tooltip. Throttled to one run per animation frame.
   const resolveTooltip = useCallback(
     (info: PickingInfo) => {
-      if (!shouldRenderInternalTooltip(renderTooltip)) {
+      if (hoverTooltipMode === 'off' || !shouldRenderInternalTooltip(renderTooltip)) {
+        setHoverTooltip(null);
         return;
       }
       const tooltip =
         info.picked && typeof info.x === 'number' && typeof info.y === 'number'
           ? resolveHoverFeatureTooltip(info, renderer.getFeatureTooltip, {
-              aggregate: aggregateHoverTooltips,
+              aggregate: hoverTooltipMode === 'aggregate',
               deck: getDeckFromDeckGlRef(deckRef),
               pickLayerIds: hoverPickLayerIds,
             })
@@ -505,7 +517,7 @@ function SpatialCanvasViewerInner({
         clientY: (rect?.top ?? 0) + tooltip.y,
       });
     },
-    [aggregateHoverTooltips, hoverPickLayerIds, renderTooltip, renderer.getFeatureTooltip]
+    [hoverTooltipMode, hoverPickLayerIds, renderTooltip, renderer.getFeatureTooltip]
   );
   const scheduleTooltip = useThrottledHoverTooltip(resolveTooltip);
 
diff --git a/packages/vis/src/SpatialCanvas/index.tsx b/packages/vis/src/SpatialCanvas/index.tsx
index abef6a6a..ba37787f 100644
--- a/packages/vis/src/SpatialCanvas/index.tsx
+++ b/packages/vis/src/SpatialCanvas/index.tsx
@@ -26,6 +26,7 @@ import { LabelsChannelPanel } from './LabelsChannelPanel';
 import { LayerOrderList } from './LayerOrderList';
 import { ShapeFillColorPanel } from './ShapeFillColorPanel';
 import {
+  type HoverTooltipMode,
   shouldAutoFitSpatialView,
   useSpatialCanvasRendererFromLayerInputs,
 } from './SpatialCanvasViewer';
@@ -372,19 +373,19 @@ interface SpatialCanvasInnerProps {
   /** Override default tooltip UI; receives pick position in viewport coordinates. */
   renderTooltip?: (props: SpatialCanvasTooltipRenderProps) => ReactNode;
   /**
-   * When true, hover tooltips include picks from all layers under the cursor.
-   * Defaults to false because aggregation issues extra per-move GPU pick passes
-   * over large geometry; enable only when stacked-layer tooltips are needed.
+   * Initial hover tooltip mode (`'off'` | `'simple'` | `'aggregate'`). The UI
+   * exposes a selector to change it live; this sets the starting value.
    */
-  aggregateHoverTooltips?: boolean;
+  hoverTooltipMode?: HoverTooltipMode;
 }
 
 function SpatialCanvasInner({
   tooltipContainer,
   renderTooltip,
-  aggregateHoverTooltips = false,
+  hoverTooltipMode = 'simple',
 }: SpatialCanvasInnerProps) {
   const { spatialData, loading: sdLoading } = useSpatialData();
+  const [tooltipMode, setTooltipMode] = useState<HoverTooltipMode>(hoverTooltipMode);
   const [measureRef, { width, height }] = useMeasure();
   const shellRef = useRef<HTMLDivElement | null>(null);
   const viewerContainerRef = useRef<HTMLDivElement | null>(null);
@@ -421,6 +422,8 @@ function SpatialCanvasInner({
   // flips at most twice per gesture (start/settle), so this hook re-runs to
   // rebuild layers with toggled pickability — not on every pan frame.
   const { interacting, onInteractionStateChange } = useViewInteractionGate();
+  // Shapes are pickable unless tooltips are off or the camera is being moved.
+  const pickingEnabled = tooltipMode !== 'off' && !interacting;
   const {
     availableElements,
     deckLayers,
@@ -445,7 +448,7 @@ function SpatialCanvasInner({
     // are managed entirely by ViewerSection so this hook never re-runs on pan.
     width: vw,
     height: vh,
-    interacting,
+    pickingEnabled,
   });
   const hoverPickLayerIds = useMemo(() => Array.from(enabledLayerIds), [enabledLayerIds]);
 
@@ -545,10 +548,14 @@ function SpatialCanvasInner({
   // cursor and position the tooltip. Throttled to one run per animation frame.
   const resolveTooltip = useCallback(
     (info: PickingInfo) => {
+      if (tooltipMode === 'off') {
+        setHoverTooltip(null);
+        return;
+      }
       const tooltip =
         info.picked && typeof info.x === 'number' && typeof info.y === 'number'
           ? resolveHoverFeatureTooltip(info, getFeatureTooltip, {
-              aggregate: aggregateHoverTooltips,
+              aggregate: tooltipMode === 'aggregate',
               deck: getDeckFromDeckGlRef(deckRef),
               pickLayerIds: hoverPickLayerIds,
             })
@@ -566,7 +573,7 @@ function SpatialCanvasInner({
         clientY: (rect?.top ?? 0) + tooltip.y,
       });
     },
-    [aggregateHoverTooltips, getFeatureTooltip, hoverPickLayerIds]
+    [tooltipMode, getFeatureTooltip, hoverPickLayerIds]
   );
   const scheduleTooltip = useThrottledHoverTooltip(resolveTooltip);
 
@@ -667,6 +674,19 @@ function SpatialCanvasInner({
                 </option>
               ))}
             </select>
+            <label style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+              <span style={{ color: '#999', fontSize: '12px' }}>Tooltips:</span>
+              <select
+                style={selectStyle}
+                value={tooltipMode}
+                onChange={(e) => setTooltipMode(e.target.value as HoverTooltipMode)}
+                title="Off disables shape picking entirely (fastest); Aggregate picks all layers under the cursor (slowest)."
+              >
+                <option value="off">Off</option>
+                <option value="simple">Simple</option>
+                <option value="aggregate">Aggregate</option>
+              </select>
+            </label>
             <button
               type="button"
               style={{ ...selectStyle, marginLeft: 'auto', cursor: 'pointer' }}
@@ -905,11 +925,10 @@ export interface SpatialCanvasProps {
    */
   renderTooltip?: (props: SpatialCanvasTooltipRenderProps) => ReactNode;
   /**
-   * When true, hover tooltips aggregate picks from all layers under the cursor.
-   * Defaults to false because aggregation issues extra per-move GPU pick passes
-   * over large geometry; enable only when stacked-layer tooltips are needed.
+   * Initial hover tooltip mode: `'off'` | `'simple'` (default) | `'aggregate'`.
+   * The canvas UI exposes a selector to change it live. See {@link HoverTooltipMode}.
    */
-  aggregateHoverTooltips?: boolean;
+  hoverTooltipMode?: HoverTooltipMode;
 }
 
 /**
@@ -964,7 +983,7 @@ export default function SpatialCanvas({
   store,
   tooltipContainer,
   renderTooltip,
-  aggregateHoverTooltips,
+  hoverTooltipMode,
 }: SpatialCanvasProps) {
   return (
     <VivLoaderRegistryProvider>
@@ -972,7 +991,7 @@ export default function SpatialCanvas({
         <SpatialCanvasInner
           tooltipContainer={tooltipContainer}
           renderTooltip={renderTooltip}
-          aggregateHoverTooltips={aggregateHoverTooltips}
+          hoverTooltipMode={hoverTooltipMode}
         />
       </SpatialCanvasProvider>
     </VivLoaderRegistryProvider>
diff --git a/packages/vis/src/SpatialCanvas/public.ts b/packages/vis/src/SpatialCanvas/public.ts
index eb53cd37..fc2fd24b 100644
--- a/packages/vis/src/SpatialCanvas/public.ts
+++ b/packages/vis/src/SpatialCanvas/public.ts
@@ -29,6 +29,7 @@ export {
   useSpatialCanvasRendererFromLayerInputs,
 } from './SpatialCanvasViewer';
 export type {
+  HoverTooltipMode,
   VivImageExtensionResolver,
   VivImageLayerContext,
   VivImagePropsResolver,
diff --git a/packages/vis/src/index.ts b/packages/vis/src/index.ts
index a572d0c8..b0552858 100644
--- a/packages/vis/src/index.ts
+++ b/packages/vis/src/index.ts
@@ -74,6 +74,7 @@ export type {
   SpatialViewerProps,
   SpatialCanvasViewerProps,
   SpatialCanvasViewerRenderTooltip,
+  HoverTooltipMode,
   LabelsSpatialFeaturePickEvent,
   ShapesSpatialFeaturePickEvent,
   SpatialFeaturePickEvent,

From 27add34e5c11c85d19ea28428fd98e62eb28bb92 Mon Sep 17 00:00:00 2001
From: Peter Todd <ptr.tdd@gmail.com>
Date: Thu, 2 Jul 2026 08:48:27 +0100
Subject: [PATCH 6/9] Don't wire deck onHover in tooltips 'off' mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Profiling showed the residual readPixels stall in 'off' mode came from deck's own
`DeckPicker.pickObject` (stack: readPixels <- _drawAndSample <- _pickClosestObject
<- pickObject), triggered purely because an `onHover` handler was still passed to
deck. deck runs a pick (a readPixels/glFinish that flushes the in-flight
image+shape render) on pointer events before invoking onHover, even when nothing
is pickable — so 'off' still stalled during pan.

In 'off' mode the shapes are already non-pickable; also leave deck's `onHover`
unset so deck has no reason to pick at all → no pickObject, no readPixels. Makes
'off' the genuinely cheap mode.

(Simple/aggregate still pay deck's per-move pickObject during drag; suppressing
that for the live-hover modes needs the manual-picking follow-up.)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx | 2 +-
 packages/vis/src/SpatialCanvas/index.tsx               | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx b/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
index e5d953c0..277d669c 100644
--- a/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
+++ b/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
@@ -682,7 +682,7 @@ function SpatialCanvasViewerInner({
               layers={renderer.deckLayers}
               layerOrder={renderer.layerOrder}
               vivLayerProps={renderer.vivLayerProps.length > 0 ? renderer.vivLayerProps : undefined}
-              onHover={handleHover}
+              onHover={hoverTooltipMode === 'off' ? undefined : handleHover}
               onClick={handleClick}
               deckProps={mergedDeckProps}
               deckRef={deckRef}
diff --git a/packages/vis/src/SpatialCanvas/index.tsx b/packages/vis/src/SpatialCanvas/index.tsx
index ba37787f..de80af9e 100644
--- a/packages/vis/src/SpatialCanvas/index.tsx
+++ b/packages/vis/src/SpatialCanvas/index.tsx
@@ -224,7 +224,7 @@ interface ViewerSectionProps {
   getWorldBoundsForVisibleLayers: () => import('@spatialdata/core').AxisAlignedBounds | null;
   vw: number;
   vh: number;
-  onHover: (info: PickingInfo) => void;
+  onHover?: (info: PickingInfo) => void;
   onInteractionStateChange: (state: ViewInteractionState) => void;
   coordinateSystem: string | null;
   deckRef: React.RefObject<DeckGLRef | null>;
@@ -740,7 +740,7 @@ function SpatialCanvasInner({
               getWorldBoundsForVisibleLayers={getWorldBoundsForVisibleLayers}
               vw={vw}
               vh={vh}
-              onHover={handleHover}
+              onHover={tooltipMode === 'off' ? undefined : handleHover}
               onInteractionStateChange={onInteractionStateChange}
               coordinateSystem={coordinateSystem}
               deckRef={deckRef}

From 1ff43046e62b10ca0d1e2a28c9dc91b142fd4e87 Mon Sep 17 00:00:00 2001
From: Peter Todd <ptr.tdd@gmail.com>
Date: Thu, 2 Jul 2026 10:14:02 +0100
Subject: [PATCH 7/9] Remove useThrottledHoverTooltip; call resolveTooltip
 directly
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The rAF throttle + same-pixel-skip in useThrottledHoverTooltip didn't earn its
keep: deck already coalesces hover picking to one pass per animation frame, and
in the default 'simple' mode tooltip resolution just reuses deck's existing pick
(no extra work to throttle). The hook only added a frame of latency and
indirection.

Drop the hook and call `resolveTooltip` straight from the hover handlers. Keep
the one durable piece — the `isHoverDuringDrag` pointer-button drag-gate — moved
into `featureTooltipHover` (its natural home) alongside the other hover helpers,
with its test folded into featureTooltipHover.spec.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ...lcanvas-picking-perf-and-rules-of-react.md |  5 +-
 .../src/SpatialCanvas/SpatialCanvasViewer.tsx | 25 ++---
 .../src/SpatialCanvas/featureTooltipHover.ts  | 12 +++
 packages/vis/src/SpatialCanvas/index.tsx      | 17 ++--
 .../SpatialCanvas/useThrottledHoverTooltip.ts | 91 -------------------
 .../vis/tests/featureTooltipHover.spec.ts     | 17 ++++
 .../vis/tests/throttledHoverTooltip.spec.ts   | 18 ----
 7 files changed, 47 insertions(+), 138 deletions(-)
 delete mode 100644 packages/vis/src/SpatialCanvas/useThrottledHoverTooltip.ts
 delete mode 100644 packages/vis/tests/throttledHoverTooltip.spec.ts

diff --git a/.changeset/spatialcanvas-picking-perf-and-rules-of-react.md b/.changeset/spatialcanvas-picking-perf-and-rules-of-react.md
index 67be14cf..535c3001 100644
--- a/.changeset/spatialcanvas-picking-perf-and-rules-of-react.md
+++ b/.changeset/spatialcanvas-picking-perf-and-rules-of-react.md
@@ -20,9 +20,8 @@ Picking/tooltip performance:
   camera is being panned/zoomed, so deck.gl does not re-render the shape
   geometry into the picking buffer during gestures. New `pickingEnabled` option
   on the shapes layer (`@spatialdata/layers`) drives this.
-- Hover tooltip resolution is throttled to one run per animation frame, skips
-  redundant same-pixel work, is suppressed while a pointer button is held
-  (drag), and collapses the per-missing-layer supplemental pick storm into a
+- Hover tooltip resolution is suppressed while a pointer button is held (drag),
+  and the per-missing-layer supplemental aggregation pick is collapsed into a
   single batched pick.
 
 Rules-of-React fixes (eslint-plugin-react-hooks, `pnpm lint:react` now clean and
diff --git a/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx b/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
index 277d669c..2b84b87b 100644
--- a/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
+++ b/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
@@ -21,7 +21,12 @@ import {
 } from './SpatialFeatureTooltip';
 import { SpatialViewer } from './SpatialViewer';
 import { VivLoaderRegistryProvider } from './VivLoaderRegistry';
-import { getDeckFromDeckGlRef, resolveHoverFeatureTooltip } from './featureTooltipHover';
+import {
+  type HoverPointerEvent,
+  getDeckFromDeckGlRef,
+  isHoverDuringDrag,
+  resolveHoverFeatureTooltip,
+} from './featureTooltipHover';
 import {
   type RenderStackHostLayerResolver,
   type RenderStackLayerInputs,
@@ -37,11 +42,6 @@ import {
   type ShapeFeaturePickEventData,
   useLayerData,
 } from './useLayerData';
-import {
-  type HoverPointerEvent,
-  isHoverDuringDrag,
-  useThrottledHoverTooltip,
-} from './useThrottledHoverTooltip';
 import { useViewInteractionGate } from './useViewInteractionGate';
 import { getAvailableElements } from './utils';
 import type {
@@ -519,7 +519,6 @@ function SpatialCanvasViewerInner({
     },
     [hoverTooltipMode, hoverPickLayerIds, renderTooltip, renderer.getFeatureTooltip]
   );
-  const scheduleTooltip = useThrottledHoverTooltip(resolveTooltip);
 
   const handleHover = useCallback(
     (info: PickingInfo, event?: HoverPointerEvent) => {
@@ -557,17 +556,9 @@ function SpatialCanvasViewerInner({
           });
         }
       }
-      scheduleTooltip(info);
+      resolveTooltip(info);
     },
-    [
-      coordinateSystem,
-      onFeatureHover,
-      onHover,
-      onShapeHover,
-      renderer,
-      scheduleTooltip,
-      spatialData,
-    ]
+    [coordinateSystem, onFeatureHover, onHover, onShapeHover, renderer, resolveTooltip, spatialData]
   );
 
   const handleClick = useCallback(
diff --git a/packages/vis/src/SpatialCanvas/featureTooltipHover.ts b/packages/vis/src/SpatialCanvas/featureTooltipHover.ts
index 23beb8b8..4283f6e7 100644
--- a/packages/vis/src/SpatialCanvas/featureTooltipHover.ts
+++ b/packages/vis/src/SpatialCanvas/featureTooltipHover.ts
@@ -5,6 +5,18 @@ import type { DeckGLRef, PickingInfo } from 'deck.gl';
 const DEFAULT_PICK_RADIUS = 4;
 const DEFAULT_PICK_DEPTH = 12;
 
+/**
+ * Minimal shape of the deck.gl hover event (a mjolnir pointer event). `srcEvent`
+ * is the underlying DOM pointer event; its `buttons` bitmask is non-zero while a
+ * pointer button is held, which is how we detect an in-progress pan/drag.
+ */
+export type HoverPointerEvent = { srcEvent?: { buttons?: number } | null };
+
+/** True when the hover event fired while a pointer button is held (pan/drag). */
+export function isHoverDuringDrag(event?: HoverPointerEvent | null): boolean {
+  return (event?.srcEvent?.buttons ?? 0) !== 0;
+}
+
 export interface PickMultipleObjectsCapable {
   props?: {
     layers?: unknown;
diff --git a/packages/vis/src/SpatialCanvas/index.tsx b/packages/vis/src/SpatialCanvas/index.tsx
index de80af9e..b79fc78c 100644
--- a/packages/vis/src/SpatialCanvas/index.tsx
+++ b/packages/vis/src/SpatialCanvas/index.tsx
@@ -39,16 +39,16 @@ import { SpatialViewer } from './SpatialViewer';
 import { TooltipFieldsPanel } from './TooltipFieldsPanel';
 import { VivLoaderRegistryProvider } from './VivLoaderRegistry';
 import { SpatialCanvasProvider, useSpatialCanvasActions, useSpatialCanvasStore } from './context';
-import { getDeckFromDeckGlRef, resolveHoverFeatureTooltip } from './featureTooltipHover';
+import {
+  type HoverPointerEvent,
+  getDeckFromDeckGlRef,
+  isHoverDuringDrag,
+  resolveHoverFeatureTooltip,
+} from './featureTooltipHover';
 import { layerConfig } from './layerConfig';
 import type { SpatialCanvasStoreApi } from './stores';
 import type { AvailableElement, ElementsByType, ViewState } from './types';
 import type { ImageLayerConfig } from './useLayerData';
-import {
-  type HoverPointerEvent,
-  isHoverDuringDrag,
-  useThrottledHoverTooltip,
-} from './useThrottledHoverTooltip';
 import { type ViewInteractionState, useViewInteractionGate } from './useViewInteractionGate';
 import { generateLayerId, getAllCoordinateSystems } from './utils';
 
@@ -575,7 +575,6 @@ function SpatialCanvasInner({
     },
     [tooltipMode, getFeatureTooltip, hoverPickLayerIds]
   );
-  const scheduleTooltip = useThrottledHoverTooltip(resolveTooltip);
 
   const handleHover = useCallback(
     (info: PickingInfo, event?: HoverPointerEvent) => {
@@ -585,9 +584,9 @@ function SpatialCanvasInner({
         setHoverTooltip(null);
         return;
       }
-      scheduleTooltip(info);
+      resolveTooltip(info);
     },
-    [scheduleTooltip]
+    [resolveTooltip]
   );
 
   const handleViewerRef = useCallback(
diff --git a/packages/vis/src/SpatialCanvas/useThrottledHoverTooltip.ts b/packages/vis/src/SpatialCanvas/useThrottledHoverTooltip.ts
deleted file mode 100644
index fff4337f..00000000
--- a/packages/vis/src/SpatialCanvas/useThrottledHoverTooltip.ts
+++ /dev/null
@@ -1,91 +0,0 @@
-import type { PickingInfo } from 'deck.gl';
-import { useCallback, useEffect, useRef } from 'react';
-
-/**
- * Minimal shape of the deck.gl hover event (a mjolnir pointer event). `srcEvent`
- * is the underlying DOM pointer event; its `buttons` bitmask is non-zero while a
- * pointer button is held, which is how we detect an in-progress pan/drag.
- */
-export type HoverPointerEvent = { srcEvent?: { buttons?: number } | null };
-
-/** True when the hover event was produced while a pointer button is held (pan/drag). */
-export function isHoverDuringDrag(event?: HoverPointerEvent | null): boolean {
-  return (event?.srcEvent?.buttons ?? 0) !== 0;
-}
-
-/**
- * Wraps an expensive hover-tooltip resolver so it runs at most once per animation
- * frame using the most recent pointer position, and skips re-running while the
- * pointer sits on the same pixel.
- *
- * deck.gl fires `onHover` on every pointer move, and resolving an aggregated
- * tooltip performs one or more `pickMultipleObjects` GPU reads (each a
- * synchronous `readPixels` stall). Coalescing to a frame and de-duplicating
- * stationary positions keeps pointer movement smooth without changing pick
- * semantics. Cheaper hover work (single-pick feature/shape callbacks) should run
- * directly from the handler and not go through here.
- */
-export function useThrottledHoverTooltip(
-  resolve: (info: PickingInfo) => void
-): (info: PickingInfo) => void {
-  // Keep the latest resolver without re-subscribing the scheduler; written in an
-  // effect (not during render) per the Rules of React.
-  const resolveRef = useRef(resolve);
-  useEffect(() => {
-    resolveRef.current = resolve;
-  }, [resolve]);
-
-  const rafRef = useRef<number | null>(null);
-  const latestRef = useRef<PickingInfo | null>(null);
-  const lastPosRef = useRef<{ x: number; y: number } | null>(null);
-
-  const flush = useCallback(() => {
-    rafRef.current = null;
-    const info = latestRef.current;
-    latestRef.current = null;
-    if (!info) return;
-
-    const { x, y, picked } = info;
-    // While the pointer hovers the same pixel over a feature, the pick result is
-    // unchanged, so skip the redundant GPU read. Always run when nothing is
-    // picked so moving off a feature reliably clears the tooltip.
-    if (
-      picked &&
-      typeof x === 'number' &&
-      typeof y === 'number' &&
-      lastPosRef.current &&
-      lastPosRef.current.x === x &&
-      lastPosRef.current.y === y
-    ) {
-      return;
-    }
-    lastPosRef.current = typeof x === 'number' && typeof y === 'number' ? { x, y } : null;
-    resolveRef.current(info);
-  }, []);
-
-  const schedule = useCallback(
-    (info: PickingInfo) => {
-      latestRef.current = info;
-      if (rafRef.current !== null) return;
-      if (typeof requestAnimationFrame === 'function') {
-        rafRef.current = requestAnimationFrame(flush);
-      } else {
-        // Non-browser environments (e.g. SSR/tests): resolve synchronously.
-        flush();
-      }
-    },
-    [flush]
-  );
-
-  useEffect(
-    () => () => {
-      if (rafRef.current !== null && typeof cancelAnimationFrame === 'function') {
-        cancelAnimationFrame(rafRef.current);
-        rafRef.current = null;
-      }
-    },
-    []
-  );
-
-  return schedule;
-}
diff --git a/packages/vis/tests/featureTooltipHover.spec.ts b/packages/vis/tests/featureTooltipHover.spec.ts
index 0ed4deec..83f271e5 100644
--- a/packages/vis/tests/featureTooltipHover.spec.ts
+++ b/packages/vis/tests/featureTooltipHover.spec.ts
@@ -1,11 +1,28 @@
 import { describe, expect, it, vi } from 'vitest';
 import {
   getAggregateHoverPickDepth,
+  isHoverDuringDrag,
   normalizeDeckLayerId,
   resolveDeckPickLayerIds,
   resolveHoverFeatureTooltip,
 } from '../src/SpatialCanvas/featureTooltipHover.js';
 
+describe('isHoverDuringDrag', () => {
+  it('treats a hover with no held button as a normal hover', () => {
+    expect(isHoverDuringDrag(undefined)).toBe(false);
+    expect(isHoverDuringDrag(null)).toBe(false);
+    expect(isHoverDuringDrag({})).toBe(false);
+    expect(isHoverDuringDrag({ srcEvent: null })).toBe(false);
+    expect(isHoverDuringDrag({ srcEvent: { buttons: 0 } })).toBe(false);
+  });
+
+  it('treats a hover with a held pointer button as an in-progress drag/pan', () => {
+    expect(isHoverDuringDrag({ srcEvent: { buttons: 1 } })).toBe(true);
+    expect(isHoverDuringDrag({ srcEvent: { buttons: 2 } })).toBe(true);
+    expect(isHoverDuringDrag({ srcEvent: { buttons: 4 } })).toBe(true);
+  });
+});
+
 const LABELS_BITMASK_LAYER_ID = 'sub-layer-0-0-0-0,512,512,0-labels:mask-#spatial-view#-labels';
 
 describe('featureTooltipHover', () => {
diff --git a/packages/vis/tests/throttledHoverTooltip.spec.ts b/packages/vis/tests/throttledHoverTooltip.spec.ts
deleted file mode 100644
index fa334505..00000000
--- a/packages/vis/tests/throttledHoverTooltip.spec.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { isHoverDuringDrag } from '../src/SpatialCanvas/useThrottledHoverTooltip.js';
-
-describe('isHoverDuringDrag', () => {
-  it('treats a hover with no held button as a normal hover', () => {
-    expect(isHoverDuringDrag(undefined)).toBe(false);
-    expect(isHoverDuringDrag(null)).toBe(false);
-    expect(isHoverDuringDrag({})).toBe(false);
-    expect(isHoverDuringDrag({ srcEvent: null })).toBe(false);
-    expect(isHoverDuringDrag({ srcEvent: { buttons: 0 } })).toBe(false);
-  });
-
-  it('treats a hover with a held pointer button as an in-progress drag/pan', () => {
-    expect(isHoverDuringDrag({ srcEvent: { buttons: 1 } })).toBe(true);
-    expect(isHoverDuringDrag({ srcEvent: { buttons: 2 } })).toBe(true);
-    expect(isHoverDuringDrag({ srcEvent: { buttons: 4 } })).toBe(true);
-  });
-});

From 13b3d30181b3ffc6ade1770812916f5fa5a9743b Mon Sep 17 00:00:00 2001
From: Peter Todd <ptr.tdd@gmail.com>
Date: Thu, 2 Jul 2026 11:16:48 +0100
Subject: [PATCH 8/9] Address PR review: clear stale tooltip on 'off', compose
 deckProps, cast-free mode guard

- SpatialCanvas/SpatialCanvasViewer: gate the tooltip portal/payload on
  hoverTooltipMode !== 'off' so switching to 'off' (which unwires onHover)
  clears the last tooltip immediately, via derived render rather than an effect.
- SpatialCanvasViewer.mergedDeckProps: compose the caller's
  onInteractionStateChange with the local interaction gate instead of
  overwriting it.
- scripts/dev.mjs: stop passing hardcoded --port 5173 --strictPort and let
  vite.config.demo.ts own port selection (free-port fallback / PORT env); a busy
  demo port is now a heads-up rather than a fatal preflight exit.
- Add cast-free isHoverTooltipMode type guard; use it in the tooltip-mode
  <select> onChange instead of `as HoverTooltipMode`.
- Widen ViewerSection.onHover type to (info, event?) to match handleHover.
- Type Table's resolved data via Awaited<ReturnType<...getAnnDataJS>> not `any`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 packages/vis/scripts/dev.mjs                  | 27 +++++++------------
 .../src/SpatialCanvas/SpatialCanvasViewer.tsx | 25 +++++++++++++----
 packages/vis/src/SpatialCanvas/index.tsx      |  9 ++++---
 packages/vis/src/Table/index.tsx              |  5 +++-
 4 files changed, 40 insertions(+), 26 deletions(-)

diff --git a/packages/vis/scripts/dev.mjs b/packages/vis/scripts/dev.mjs
index 45a3090e..871a5a43 100644
--- a/packages/vis/scripts/dev.mjs
+++ b/packages/vis/scripts/dev.mjs
@@ -33,18 +33,18 @@ async function fixtureServerIsOurs(port) {
 }
 
 /**
- * Check the ports we need before spawning anything, so a leftover dev server
- * (often from another checkout) produces a clear message instead of a cryptic
- * strict-port crash. Returns whether we still need to start the fixture server.
+ * Check the ports we need before spawning anything: a busy demo port just gets a
+ * heads-up (Vite falls back to a free one), while a foreign process on the fixed
+ * fixture port is fatal. Returns whether we still need to start the fixture server.
  */
 async function preflight() {
   if (await isPortInUse(DEMO_PORT)) {
     const holder = describePortHolder(DEMO_PORT);
-    console.error(
-      `\n[dev] Demo port ${DEMO_PORT} is already in use${holder ? `:\n  ${holder}` : '.'}`
+    console.log(
+      `[dev] Demo port ${DEMO_PORT} is already in use${
+        holder ? ` (${holder})` : ''
+      }; Vite will fall back to the next free port.`
     );
-    console.error('[dev] Run `pnpm dev:stop` to clear SpatialData dev processes, then retry.\n');
-    process.exit(1);
   }
 
   if (await isPortInUse(FIXTURE_SERVER_PORT)) {
@@ -126,13 +126,6 @@ if (startFixtures) {
 }
 console.log(`Starting ${startedParts.join(', ')}...`);
 start('watch', ['vite', 'build', '--watch']);
-start('demo', [
-  'vite',
-  '--config',
-  'vite.config.demo.ts',
-  '--host',
-  '127.0.0.1',
-  '--port',
-  String(DEMO_PORT),
-  '--strictPort',
-]);
+// Host/port (and the free-port fallback) are owned by vite.config.demo.ts so
+// the port selection stays in one place; honour PORT if the caller pins it.
+start('demo', ['vite', '--config', 'vite.config.demo.ts']);
diff --git a/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx b/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
index 2b84b87b..20d17dc6 100644
--- a/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
+++ b/packages/vis/src/SpatialCanvas/SpatialCanvasViewer.tsx
@@ -70,6 +70,11 @@ export type SpatialCanvasViewerRenderTooltip =
  */
 export type HoverTooltipMode = 'off' | 'simple' | 'aggregate';
 
+/** Runtime narrowing for arbitrary strings (e.g. a `<select>` value) to a mode. */
+export function isHoverTooltipMode(value: string): value is HoverTooltipMode {
+  return value === 'off' || value === 'simple' || value === 'aggregate';
+}
+
 type SpatialFeaturePickEventRuntimeFields = {
   coordinateSystem: string | null;
   spatialData?: SpatialData | null;
@@ -482,11 +487,20 @@ function SpatialCanvasViewerInner({
     [renderer.enabledLayerIds]
   );
   // Feed deck's interaction state into the gate (via deckProps so the existing
-  // spread reaches both DeckGL branches) without disturbing caller deckProps.
-  const mergedDeckProps = useMemo(
-    () => ({ ...deckProps, onInteractionStateChange }),
-    [deckProps, onInteractionStateChange]
-  );
+  // spread reaches both DeckGL branches) while still invoking any caller-supplied
+  // onInteractionStateChange handler.
+  const mergedDeckProps = useMemo(() => {
+    const callerOnInteractionStateChange = deckProps?.onInteractionStateChange;
+    return {
+      ...deckProps,
+      onInteractionStateChange: (
+        state: Parameters<NonNullable<DeckGLProps['onInteractionStateChange']>>[0]
+      ) => {
+        callerOnInteractionStateChange?.(state);
+        onInteractionStateChange(state);
+      },
+    };
+  }, [deckProps, onInteractionStateChange]);
 
   // The expensive part of hovering: aggregate-pick the feature(s) under the
   // cursor and position the tooltip. Throttled to one run per animation frame.
@@ -612,6 +626,7 @@ function SpatialCanvasViewerInner({
 
   const portalTarget = typeof document !== 'undefined' ? (tooltipContainer ?? document.body) : null;
   const tooltipPortal =
+    hoverTooltipMode !== 'off' &&
     shouldRenderInternalTooltip(renderTooltip) &&
     tooltipPayload &&
     tooltipClientPosition &&
diff --git a/packages/vis/src/SpatialCanvas/index.tsx b/packages/vis/src/SpatialCanvas/index.tsx
index b79fc78c..0306ec99 100644
--- a/packages/vis/src/SpatialCanvas/index.tsx
+++ b/packages/vis/src/SpatialCanvas/index.tsx
@@ -27,6 +27,7 @@ import { LayerOrderList } from './LayerOrderList';
 import { ShapeFillColorPanel } from './ShapeFillColorPanel';
 import {
   type HoverTooltipMode,
+  isHoverTooltipMode,
   shouldAutoFitSpatialView,
   useSpatialCanvasRendererFromLayerInputs,
 } from './SpatialCanvasViewer';
@@ -224,7 +225,7 @@ interface ViewerSectionProps {
   getWorldBoundsForVisibleLayers: () => import('@spatialdata/core').AxisAlignedBounds | null;
   vw: number;
   vh: number;
-  onHover?: (info: PickingInfo) => void;
+  onHover?: (info: PickingInfo, event?: HoverPointerEvent) => void;
   onInteractionStateChange: (state: ViewInteractionState) => void;
   coordinateSystem: string | null;
   deckRef: React.RefObject<DeckGLRef | null>;
@@ -633,7 +634,7 @@ function SpatialCanvasInner({
     : { ...containerStyle, position: 'relative' };
 
   const tooltipPayload: SpatialFeatureTooltipData | null =
-    hoverTooltip && tooltipClientPosition ? hoverTooltip : null;
+    tooltipMode !== 'off' && hoverTooltip && tooltipClientPosition ? hoverTooltip : null;
 
   const portalTarget = typeof document !== 'undefined' ? (tooltipContainer ?? document.body) : null;
 
@@ -678,7 +679,9 @@ function SpatialCanvasInner({
               <select
                 style={selectStyle}
                 value={tooltipMode}
-                onChange={(e) => setTooltipMode(e.target.value as HoverTooltipMode)}
+                onChange={(e) => {
+                  if (isHoverTooltipMode(e.target.value)) setTooltipMode(e.target.value);
+                }}
                 title="Off disables shape picking entirely (fastest); Aggregate picks all layers under the cursor (slowest)."
               >
                 <option value="off">Off</option>
diff --git a/packages/vis/src/Table/index.tsx b/packages/vis/src/Table/index.tsx
index db530355..681e0ffe 100644
--- a/packages/vis/src/Table/index.tsx
+++ b/packages/vis/src/Table/index.tsx
@@ -12,7 +12,10 @@ export default function TableComponent() {
   }, [selectedTable, spatialData?.tables]);
   // Keep the resolved data tagged with the table it came from so stale data is
   // hidden by deriving during render rather than clearing via setState-in-effect.
-  const [tableData, setTableData] = useState<{ table: unknown; data: any } | undefined>(undefined);
+  type AnnDataResult = Awaited<ReturnType<NonNullable<typeof table>['getAnnDataJS']>>;
+  const [tableData, setTableData] = useState<
+    { table: unknown; data: AnnDataResult } | undefined
+  >(undefined);
   useEffect(() => {
     if (!table) return;
     let cancelled = false;

From 3c1ce50e807a6ea6108ab2ce21af03c2b08ee921 Mon Sep 17 00:00:00 2001
From: Peter Todd <xinaesthete@users.noreply.github.com>
Date: Thu, 2 Jul 2026 11:30:18 +0100
Subject: [PATCH 9/9] fix launch.json syntax broken after merge

---
 .claude/launch.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.claude/launch.json b/.claude/launch.json
index 1d1b6a82..cf42fafc 100644
--- a/.claude/launch.json
+++ b/.claude/launch.json
@@ -5,7 +5,7 @@
       "name": "vis-demo",
       "runtimeExecutable": "pnpm",
       "runtimeArgs": ["--filter", "@spatialdata/vis", "dev:demo"],
-      "autoPort": true
+      "autoPort": true,
       "port": 5173
     },
     {