@dtour/viewer 0.1.0 → 0.2.0

package/src/DtourViewer.tsx

@@ -4,19 +4,36 @@ import {
   OKABE_ITO,
   computeArcLengths,
   createScatter,
+  createScatterWebGL,
   interpolateAtPosition,
 } from '@dtour/scatter';
 import type { ScatterInstance, ScatterStatus } from '@dtour/scatter';
 import { useAtom, useAtomValue, useSetAtom, useStore } from 'jotai';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { AxisOverlay } from './components/AxisOverlay.tsx';
+import type { AxisOverlayHandle } from './components/AxisOverlay.tsx';
 import { CircularSlider } from './components/CircularSlider.tsx';
+import type { CircularSliderHandle } from './components/CircularSlider.tsx';
 import { Gallery } from './components/Gallery.tsx';
 import { LassoOverlay } from './components/LassoOverlay.tsx';
+import { RevertCameraButton } from './components/RevertCameraButton.tsx';
 import { useAnimatePosition } from './hooks/useAnimatePosition.ts';
 import { useGrandTour } from './hooks/useGrandTour.ts';
+import { usePlayback } from './hooks/usePlayback.ts';
 import { useScatter } from './hooks/useScatter.ts';
 import { computeSelectorSize } from './layout/selector-size.ts';
+import {
+  IDENTITY_QUAT,
+  type Quat,
+  arcballQuat,
+  isIdentityQuat,
+  multiplyQuat,
+  projectToSphere,
+  quatToMat3,
+  slerp,
+} from './lib/arcball.ts';
+import { tourToVisual, visualToTour } from './lib/position-remap.ts';
+import { throttleAndDebounce } from './lib/throttle-debounce.ts';
 import { RadialChart } from './radial-chart/RadialChart.tsx';
 import { parseMetrics } from './radial-chart/parse-metrics.ts';
 import type { RadialTrackConfig } from './radial-chart/types.ts';
@@ -24,16 +41,26 @@ import {
   activeColumnsAtom,
   activeIndicesAtom,
   animationGenAtom,
+  arcLengthsAtom,
   cameraZoomAtom,
   canvasSizeAtom,
   currentBasisAtom,
+  currentKeyframeAtom,
+  embeddedConfigAtom,
+  frameLoadingsAtom,
   guidedSuspendedAtom,
+  hoveredKeyframeAtom,
+  is3dRotatedAtom,
   legendSelectionAtom,
   metadataAtom,
   pointColorAtom,
+  previewCentersAtom,
   previewCountAtom,
   previewScaleAtom,
   resolvedThemeAtom,
+  showAxesAtom,
+  showFrameLoadingsAtom,
+  sliderSpacingAtom,
   tourByAtom,
   tourPlayingAtom,
   tourPositionAtom,
@@ -60,6 +87,9 @@ export type DtourViewerProps = {
   toolbarHeight?: number | undefined;
   /** Called when the scatter instance is created (or null on destroy). */
   onScatterReady?: ((scatter: ScatterInstance | null) => void) | undefined;
+  /** Rendering backend. Read once on mount — changing after mount has no effect.
+   *  Default 'webgpu'. */
+  backend?: 'webgpu' | 'webgl' | undefined;
 };
 
 const PREVIEW_PHYSICAL_SIZE = 300; // Physical pixels per preview canvas
@@ -76,14 +106,17 @@ export const DtourViewer = ({
   onStatus,
   toolbarHeight = 0,
   onScatterReady,
+  backend = 'webgpu',
 }: DtourViewerProps) => {
   const containerRef = useRef<HTMLDivElement>(null);
   const onScatterReadyRef = useRef(onScatterReady);
   onScatterReadyRef.current = onScatterReady;
+  const [scatter, setScatter] = useState<ScatterInstance | null>(null);
   const scatterRef = useRef<ScatterInstance | null>(null);
-  const previewCanvasesRef = useRef<HTMLCanvasElement[]>([]);
+  const [previewCanvases, setPreviewCanvases] = useState<HTMLCanvasElement[]>([]);
   const [position, setPosition] = useAtom(tourPositionAtom);
   const metadata = useAtomValue(metadataAtom);
+  const embeddedConfig = useAtomValue(embeddedConfigAtom);
   const previewCount = useAtomValue(previewCountAtom);
   const previewScale = useAtomValue(previewScaleAtom);
   const viewMode = useAtomValue(viewModeAtom);
@@ -91,15 +124,53 @@ export const DtourViewer = ({
   const setPlaying = useSetAtom(tourPlayingAtom);
   const setCanvasSize = useSetAtom(canvasSizeAtom);
   const store = useStore();
+  const currentKeyframe = useAtomValue(currentKeyframeAtom);
+  const hoveredKeyframe = useAtomValue(hoveredKeyframeAtom);
+  const previewCenters = useAtomValue(previewCentersAtom);
   const [containerSize, setContainerSize] = useState({ width: 0, height: 0 });
   const activeIndices = useAtomValue(activeIndicesAtom);
   const setActiveColumns = useSetAtom(activeColumnsAtom);
   const lastDataRef = useRef<ArrayBuffer | undefined>(undefined);
   const prevDimCountRef = useRef<number | null>(null);
-  const dataRef = useRef(data);
-  dataRef.current = data;
   const onStatusRef = useRef(onStatus);
   onStatusRef.current = onStatus;
+  const sliderRef = useRef<CircularSliderHandle>(null);
+  const axisOverlayRef = useRef<AxisOverlayHandle>(null);
+  const positionRef = useRef(position);
+
+  // Sync positionRef with atom value (overwritten by direct drives within ~33ms)
+  useEffect(() => {
+    positionRef.current = position;
+  }, [position]);
+
+  // Throttle+debounce atom write — fires at most every 100ms during playback
+  // (throttle) AND once more after the last tick (debounce), so Gallery's
+  // currentKeyframe highlight updates during playback (~10fps) while also
+  // guaranteeing the final position is flushed.
+  const positionFlushRef = useRef(throttleAndDebounce((pos: number) => setPosition(pos), 100));
+
+  const schedulePositionFlush = useCallback(() => {
+    positionFlushRef.current(positionRef.current);
+  }, []);
+
+  // Stable ref so the scatter subscribe callback can access the latest flush fn
+  const scheduleFlushRef = useRef(schedulePositionFlush);
+  scheduleFlushRef.current = schedulePositionFlush;
+
+  // Delegate playback rAF to the GPU worker
+  usePlayback(scatter);
+
+  // Flush position to atom immediately when playback stops
+  const playing = useAtomValue(tourPlayingAtom);
+  const prevPlayingRef = useRef(false);
+  useEffect(() => {
+    if (prevPlayingRef.current && !playing) {
+      positionFlushRef.current.cancel();
+      positionFlushRef.current.reset();
+      setPosition(positionRef.current);
+    }
+    prevPlayingRef.current = playing;
+  }, [playing, setPosition]);
 
   const setCurrentBasis = useSetAtom(currentBasisAtom);
   const tourBy = useAtomValue(tourByAtom);
@@ -108,10 +179,22 @@ export const DtourViewer = ({
     numDims: number;
   } | null>(null);
 
+  const showAxes = useAtomValue(showAxesAtom);
+  const spacingMode = useAtomValue(sliderSpacingAtom);
+  const setArcLengthsAtom_ = useSetAtom(arcLengthsAtom);
   const isGuidedMode = viewMode === 'guided';
+  const frameLoadings = useAtomValue(frameLoadingsAtom);
+  const showFrameLoadings = useAtomValue(showFrameLoadingsAtom);
+  const loadingsVisible = showFrameLoadings && frameLoadings !== null && frameLoadings.length > 0;
 
   // Resolve views (from props or auto-generated) and precompute arc lengths
   // so we can track the current tour basis on the main thread.
+  // Embedded tour views from Parquet metadata (only when nDims matches the dataset)
+  const embeddedViews =
+    embeddedConfig?.tour && metadata && embeddedConfig.tour.nDims === metadata.dimCount
+      ? embeddedConfig.tour.views
+      : null;
+
   const { resolvedViews, arcLengths } = useMemo(() => {
     if (!metadata || metadata.dimCount < 2) return { resolvedViews: null, arcLengths: null };
     if (activeIndices.length < 2) return { resolvedViews: null, arcLengths: null };
@@ -121,11 +204,49 @@ export const DtourViewer = ({
       rb = createPCAViews(pcaResult.eigenvectors, dims, pcaResult.numDims, previewCount);
     } else if (views && views.length > 0) {
       rb = views.map((b) => new Float32Array(b));
+    } else if (!views && embeddedViews) {
+      rb = embeddedViews.map((b) => new Float32Array(b));
     } else {
       rb = createDefaultViews(dims, previewCount, activeIndices);
     }
     return { resolvedViews: rb, arcLengths: computeArcLengths(rb, dims) };
-  }, [views, metadata, previewCount, activeIndices, tourBy, pcaResult]);
+  }, [views, embeddedViews, metadata, previewCount, activeIndices, tourBy, pcaResult]);
+
+  // Sync arcLengths atom so Gallery and other components can access it
+  useEffect(() => {
+    setArcLengthsAtom_(arcLengths);
+  }, [arcLengths, setArcLengthsAtom_]);
+
+  // Refs for spacing mode and arcLengths so the scatter subscribe callback
+  // (created once in the init effect) can access the latest values.
+  const spacingModeRef = useRef(spacingMode);
+  spacingModeRef.current = spacingMode;
+  const arcLengthsRef = useRef(arcLengths);
+  arcLengthsRef.current = arcLengths;
+  const resolvedViewsRef = useRef(resolvedViews);
+  resolvedViewsRef.current = resolvedViews;
+  const metadataRef = useRef(metadata);
+  metadataRef.current = metadata;
+  // Pre-allocated scratch buffer for imperative basis interpolation
+  const basisScratchRef = useRef(new Float32Array(0));
+
+  // Imperative axis overlay update — compute the interpolated basis at
+  // a given tour position and push directly to SVG via setBasis.
+  // Called from playbackTick, slider drag, and wheel scrub.
+  const updateAxesImperative = useCallback((tourPos: number) => {
+    const rv = resolvedViewsRef.current;
+    const al = arcLengthsRef.current;
+    const meta = metadataRef.current;
+    if (!rv || !al || !meta || !axisOverlayRef.current) return;
+    const p = meta.dimCount;
+    if (basisScratchRef.current.length !== p * 2) {
+      basisScratchRef.current = new Float32Array(p * 2);
+    }
+    interpolateAtPosition(basisScratchRef.current, rv, al, p, tourPos);
+    axisOverlayRef.current.setBasis(basisScratchRef.current);
+  }, []);
+  const updateAxesRef = useRef(updateAxesImperative);
+  updateAxesRef.current = updateAxesImperative;
 
   // Keep currentBasisAtom in sync with the tour interpolation so other
   // modes (manual, grand) can initialize from the current projection.
@@ -188,20 +309,20 @@ export const DtourViewer = ({
   }, [parsedTracks, legendSelection, pointColor, metadata, resolvedTheme]);
 
   // Bridge Jotai atoms (style, camera) → scatter instance
-  useScatter(scatterRef.current);
+  useScatter(scatter);
 
   const isToolbarVisible = toolbarHeight > 0 && viewMode !== 'grand';
+  const effectiveToolbarHeight = isToolbarVisible ? toolbarHeight : 0;
 
   // Animate camera inset when the toolbar appears/disappears (grand toggle).
   // The shader shifts + scales content to center it below the toolbar.
   // We also track the current pixel offset for positioning overlays.
-  const [overlayOffsetY, setOverlayOffsetY] = useState(isToolbarVisible ? toolbarHeight / 2 : 0);
+  const [overlayOffsetY, setOverlayOffsetY] = useState(isToolbarVisible ? toolbarHeight : 0);
   const overlayOffsetRef = useRef(overlayOffsetY);
   overlayOffsetRef.current = overlayOffsetY;
   const insetAnimRef = useRef<number | null>(null);
 
   useEffect(() => {
-    const scatter = scatterRef.current;
     if (!scatter || containerSize.height === 0) return;
 
     const targetT = viewMode === 'grand' || toolbarHeight === 0 ? 0 : 1;
@@ -209,7 +330,7 @@ export const DtourViewer = ({
     const t = toolbarHeight;
 
     // Current inset factor: derive from current overlayOffsetY via ref
-    const startT = t > 0 ? overlayOffsetRef.current / (t / 2) : 0;
+    const startT = t > 0 ? overlayOffsetRef.current / t : 0;
     if (Math.abs(startT - targetT) < 0.001) {
       // Already at target — just ensure shader is in sync
       const insetOffsetY = (-targetT * t) / h;
@@ -235,7 +356,7 @@ export const DtourViewer = ({
       scatter.setCamera({ insetOffsetY, insetZoom } as Parameters<typeof scatter.setCamera>[0]);
 
       // Overlay pixel offset
-      setOverlayOffsetY((currentT * t) / 2);
+      setOverlayOffsetY(currentT * t);
 
       if (progress < 1) {
         insetAnimRef.current = requestAnimationFrame(tick);
@@ -253,35 +374,43 @@ export const DtourViewer = ({
         insetAnimRef.current = null;
       }
     };
-  }, [viewMode, toolbarHeight, containerSize.height]);
+  }, [scatter, viewMode, toolbarHeight, containerSize.height]);
 
   // Grand mode: Givens-rotation grand tour
-  useGrandTour(scatterRef.current, viewMode, metadata);
+  useGrandTour(scatter, viewMode, metadata);
 
   // Largest selector diameter that doesn't overlap any gallery preview
   const selectorSize = useMemo(
     () =>
       computeSelectorSize(
         containerSize.width,
-        containerSize.height,
+        containerSize.height - effectiveToolbarHeight,
         previewCount,
-        isToolbarVisible,
+        0,
         SELECTOR_PADDING,
         previewScale,
         coloredTracks.length,
+        loadingsVisible,
       ),
     [
       containerSize.width,
       containerSize.height,
       previewCount,
-      isToolbarVisible,
+      effectiveToolbarHeight,
       previewScale,
       coloredTracks.length,
+      loadingsVisible,
     ],
   );
 
-  // Initialize scatter — create main + preview canvases imperatively
-  // (transferControlToOffscreen can only be called once per canvas).
+  // Effect A — Scatter lifecycle: create main canvas + scatter instance.
+  // Runs once on mount, cleans up on unmount. No dependencies — backend is
+  // a static construction prop, store and setCanvasSize are stable singletons.
+  // NOTE: This effect is NOT StrictMode-safe. transferControlToOffscreen()
+  // and ArrayBuffer transfers are one-shot ownership operations that cannot
+  // survive StrictMode's mount→cleanup→remount cycle. Consumers must either
+  // avoid StrictMode or accept a one-time dev-mode data copy.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: intentionally empty — all captured values are stable or refs
   useEffect(() => {
     const container = containerRef.current;
     if (!container) return;
@@ -298,63 +427,101 @@ export const DtourViewer = ({
     mainCanvas.style.display = 'block';
     container.prepend(mainCanvas);
 
-    // Preview canvases — one per tour keyframe view
-    const previews: HTMLCanvasElement[] = [];
-    for (let i = 0; i < previewCount; i++) {
-      const c = document.createElement('canvas');
-      c.width = PREVIEW_PHYSICAL_SIZE;
-      c.height = PREVIEW_PHYSICAL_SIZE;
-      c.style.width = '100%';
-      c.style.height = '100%';
-      c.style.display = 'block';
-      c.style.borderRadius = '2px';
-      previews.push(c);
-    }
-    previewCanvasesRef.current = previews;
-
-    const scatter = createScatter({
-      canvases: [mainCanvas, ...previews],
+    const factory = backend === 'webgl' ? createScatterWebGL : createScatter;
+    const instance = factory({
+      canvas: mainCanvas,
       zoom: store.get(cameraZoomAtom),
     });
-    scatterRef.current = scatter;
-    onScatterReadyRef.current?.(scatter);
+    scatterRef.current = instance;
+    setScatter(instance);
+    onScatterReadyRef.current?.(instance);
+    // Expose scatter instance for dev tools and benchmark automation
+    if (import.meta.env.DEV || (globalThis as Record<string, unknown>).__dtourBenchmarkMode) {
+      (globalThis as Record<string, unknown>).scatter = instance;
+    }
 
-    scatter.subscribe((s: ScatterStatus) => {
+    instance.subscribe((s: ScatterStatus) => {
       onStatusRef.current?.(s);
       if (s.type === 'pcaResult') {
         setPcaResult({ eigenvectors: s.eigenvectors, numDims: s.numDims });
       }
+      if (s.type === 'metadata') {
+        // Data reload: worker resets 3D state, so clear viewer-side refs too
+        if (is3dEnabledRef.current) {
+          is3dEnabledRef.current = false;
+          quatRef.current = IDENTITY_QUAT;
+          residualPCRef.current = null;
+          axisOverlayRef.current?.clearRotation3d();
+          store.set(is3dRotatedAtom, false);
+        }
+      }
+      if (s.type === 'residualPC') {
+        residualPCRef.current = s.residualPC;
+        // If already rotating, immediately update axis overlay so the first
+        // drag frame isn't missed while waiting for the next pointermove.
+        if (!isIdentityQuat(quatRef.current)) {
+          axisOverlayRef.current?.setRotation3d(s.residualPC, quatToMat3(quatRef.current));
+        }
+      }
+      if (s.type === 'playbackTick') {
+        positionRef.current = s.position;
+        const al = arcLengthsRef.current;
+        const visual =
+          spacingModeRef.current === 'equal' && al ? tourToVisual(s.position, al) : s.position;
+        sliderRef.current?.setPosition(visual);
+        scheduleFlushRef.current();
+        updateAxesRef.current(s.position);
+      }
     });
 
     const ro = new ResizeObserver(([entry]) => {
       if (!entry) return;
       const { width, height } = entry.contentRect;
       const curDpr = window.devicePixelRatio || 1;
-      scatter.resize(0, Math.round(width * curDpr), Math.round(height * curDpr), curDpr);
+      instance.resize(0, Math.round(width * curDpr), Math.round(height * curDpr), curDpr);
       setContainerSize({ width, height });
       setCanvasSize({ width, height });
     });
     ro.observe(container);
 
-    // Re-send data to the new scatter instance (e.g. after previewCount change
-    // or HMR where the scatter is recreated but data hasn't changed).
-    if (dataRef.current) {
-      scatter.loadData(dataRef.current.slice(0));
-      lastDataRef.current = dataRef.current;
-    } else {
-      lastDataRef.current = undefined;
-    }
-
     return () => {
       ro.disconnect();
-      scatter.destroy();
+      instance.destroy();
       scatterRef.current = null;
+      setScatter(null);
       onScatterReadyRef.current?.(null);
       mainCanvas.remove();
-      for (const c of previews) c.remove();
-      previewCanvasesRef.current = [];
     };
-  }, [previewCount, setCanvasSize, store]);
+  }, []);
+
+  // Effect B — Preview canvas lifecycle: add/remove preview canvases dynamically.
+  // Runs when scatter instance or previewCount changes.
+  useEffect(() => {
+    if (!scatter) return;
+
+    const previews: HTMLCanvasElement[] = [];
+    for (let i = 0; i < previewCount; i++) {
+      const c = document.createElement('canvas');
+      c.width = PREVIEW_PHYSICAL_SIZE;
+      c.height = PREVIEW_PHYSICAL_SIZE;
+      c.style.width = '100%';
+      c.style.height = '100%';
+      c.style.display = 'block';
+      c.style.borderRadius = '2px';
+      previews.push(c);
+      scatter.addPreviewCanvas(i, c);
+    }
+    setPreviewCanvases(previews);
+    scatter.render();
+
+    return () => {
+      for (let i = 0; i < previews.length; i++) {
+        scatter.removePreviewCanvas(i);
+        previews[i]!.remove();
+      }
+      setPreviewCanvases([]);
+    };
+  }, [scatter, previewCount]);
 
   // Reset active columns and PCA results when a new dataset loads (different dim count)
   useEffect(() => {
@@ -368,20 +535,20 @@ export const DtourViewer = ({
 
   // Send data when it changes
   useEffect(() => {
-    if (!data || !scatterRef.current || data === lastDataRef.current) return;
+    if (!data || !scatter || data === lastDataRef.current) return;
+    if (data.byteLength === 0) return; // already transferred (detached)
     lastDataRef.current = data;
-    scatterRef.current.loadData(data.slice(0));
-  }, [data]);
+    scatter.loadData(data);
+  }, [data, scatter]);
 
   // Trigger PCA computation when tourBy is 'pca' and data is loaded
   useEffect(() => {
-    if (tourBy !== 'pca' || !metadata || metadata.dimCount < 2 || !scatterRef.current) return;
-    scatterRef.current.computePCA();
-  }, [tourBy, metadata]);
+    if (tourBy !== 'pca' || !metadata || metadata.dimCount < 2 || !scatter) return;
+    scatter.computePCA();
+  }, [tourBy, metadata, scatter]);
 
-  // Set views when available (from props, PCA, or auto-generated from metadata)
+  // Set views when available (from props, PCA, embedded, or auto-generated from metadata)
   useEffect(() => {
-    const scatter = scatterRef.current;
     if (!scatter) return;
     if (tourBy === 'pca' && pcaResult && pcaResult.eigenvectors.length >= 2 && metadata) {
       const pcaBases = createPCAViews(
@@ -393,6 +560,8 @@ export const DtourViewer = ({
       scatter.setBases(pcaBases);
     } else if (views && views.length > 0) {
       scatter.setBases(views.map((b) => new Float32Array(b)));
+    } else if (!views && embeddedViews) {
+      scatter.setBases(embeddedViews.map((b) => new Float32Array(b)));
     } else if (metadata && metadata.dimCount >= 2 && activeIndices.length >= 2) {
       const defaultViews = createDefaultViews(metadata.dimCount, previewCount, activeIndices);
       scatter.setBases(defaultViews);
@@ -400,18 +569,21 @@ export const DtourViewer = ({
     // Safety: explicitly request a full re-render after views are set,
     // ensuring all preview canvases get painted even if messages race.
     scatter.render();
-  }, [views, metadata, previewCount, activeIndices, tourBy, pcaResult]);
+  }, [scatter, views, embeddedViews, metadata, previewCount, activeIndices, tourBy, pcaResult]);
 
   const { animateTo, cancelAnimation } = useAnimatePosition();
 
-  // Slider click → animated seek to the clicked position
+  // Slider click → animated seek to the clicked position.
+  // The slider reports a visual position; convert to tour position for the GPU.
   const handlePositionSeek = useCallback(
-    (pos: number) => {
+    (visualPos: number) => {
       setGuidedSuspended(false);
       setPlaying(false);
-      animateTo(pos);
+      const tourPos =
+        spacingMode === 'equal' && arcLengths ? visualToTour(visualPos, arcLengths) : visualPos;
+      animateTo(tourPos);
     },
-    [setGuidedSuspended, setPlaying, animateTo],
+    [setGuidedSuspended, setPlaying, animateTo, spacingMode, arcLengths],
   );
 
   // Slider drag start → cancel animation, switch to immediate updates
@@ -420,13 +592,21 @@ export const DtourViewer = ({
     setGuidedSuspended(false);
   }, [cancelAnimation, setGuidedSuspended]);
 
-  // Slider drag move → immediate position update
+  // Slider drag move → send directly to GPU, update slider imperatively,
+  // debounce atom write to minimize React re-renders during drag.
+  // The slider reports a visual position; convert to tour position for the GPU.
   const handlePositionChange = useCallback(
-    (pos: number) => {
+    (visualPos: number) => {
       setGuidedSuspended(false);
-      setPosition(pos);
+      const tourPos =
+        spacingMode === 'equal' && arcLengths ? visualToTour(visualPos, arcLengths) : visualPos;
+      scatterRef.current?.setTourPosition(tourPos);
+      sliderRef.current?.setPosition(visualPos);
+      positionRef.current = tourPos;
+      updateAxesImperative(tourPos);
+      schedulePositionFlush();
     },
-    [setPosition, setGuidedSuspended],
+    [setGuidedSuspended, schedulePositionFlush, spacingMode, arcLengths, updateAxesImperative],
   );
 
   // Wheel → scrub tour position (guided mode) or zoom (Shift+wheel, all modes).
@@ -452,17 +632,202 @@ export const DtourViewer = ({
       store.set(animationGenAtom, (g) => g + 1);
       store.set(tourPlayingAtom, false);
       store.set(guidedSuspendedAtom, false);
-      store.set(tourPositionAtom, (prev) => {
-        let next = prev + e.deltaY * 0.002;
+      // Send directly to GPU + slider, debounce atom write.
+      // In equal mode, scrub in visual space for perceptual uniformity.
+      const al = arcLengthsRef.current;
+      const mode = spacingModeRef.current;
+      if (mode === 'equal' && al) {
+        const curVisual = tourToVisual(positionRef.current, al);
+        let nextVisual = curVisual + e.deltaY * 0.002;
+        nextVisual = nextVisual - Math.floor(nextVisual);
+        const nextTour = visualToTour(nextVisual, al);
+        positionRef.current = nextTour;
+        scatterRef.current?.setTourPosition(nextTour);
+        sliderRef.current?.setPosition(nextVisual);
+        updateAxesRef.current(nextTour);
+      } else {
+        let next = positionRef.current + e.deltaY * 0.002;
         next = next - Math.floor(next);
-        return next;
-      });
+        positionRef.current = next;
+        scatterRef.current?.setTourPosition(next);
+        sliderRef.current?.setPosition(next);
+        updateAxesRef.current(next);
+      }
+      scheduleFlushRef.current();
     };
     container.addEventListener('wheel', handler, { passive: false });
     return () => container.removeEventListener('wheel', handler);
   }, [store]);
 
-  const tickCount = views?.length ?? previewCount;
+  // ─── 3D camera rotation (manual mode only) ──────────────────────────────
+  const setIs3dRotated = useSetAtom(is3dRotatedAtom);
+  const is3dRotated = useAtomValue(is3dRotatedAtom);
+  const quatRef = useRef<Quat>(IDENTITY_QUAT);
+  const is3dEnabledRef = useRef(false);
+  const revertAnimRef = useRef<number | null>(null);
+  const residualPCRef = useRef<Float32Array | null>(null);
+  const backendRef = useRef(backend);
+  backendRef.current = backend;
+  const effectiveToolbarHeightRef = useRef(effectiveToolbarHeight);
+  effectiveToolbarHeightRef.current = effectiveToolbarHeight;
+
+  // Shift+drag arcball rotation
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    let dragging = false;
+    let lastSphere: [number, number, number] | null = null;
+
+    const toNdc = (e: PointerEvent): [number, number] => {
+      const rect = container.getBoundingClientRect();
+      // Map relative to the visible content area (below toolbar)
+      const t = effectiveToolbarHeightRef.current;
+      const visibleH = rect.height - t;
+      const x = ((e.clientX - rect.left) / rect.width) * 2 - 1;
+      const y = -(((e.clientY - rect.top - t) / visibleH) * 2 - 1);
+      return [x, y];
+    };
+
+    const onDown = (e: PointerEvent) => {
+      if (e.button !== 0) return;
+      // Shift+drag to enter 3D; once active, plain drag also rotates
+      if (!e.shiftKey && !store.get(is3dRotatedAtom)) return;
+      if (store.get(viewModeAtom) !== 'manual') return;
+      if (!store.get(metadataAtom)) return; // data not loaded yet
+      if (backendRef.current !== 'webgpu') return; // 3D requires WebGPU
+      // Let clicks on buttons (revert, toolbar, etc.) pass through
+      if ((e.target as Element).closest('button, a')) return;
+      e.preventDefault();
+      e.stopPropagation();
+      dragging = true;
+      container.setPointerCapture(e.pointerId);
+      const [nx, ny] = toNdc(e);
+      lastSphere = projectToSphere(nx, ny);
+
+      // Enable 3D on first rotation
+      if (!is3dEnabledRef.current) {
+        scatterRef.current?.enable3d();
+        is3dEnabledRef.current = true;
+      }
+    };
+
+    const onMove = (e: PointerEvent) => {
+      if (!dragging || !lastSphere) return;
+      e.preventDefault();
+      const [nx, ny] = toNdc(e);
+      const curSphere = projectToSphere(nx, ny);
+      const delta = arcballQuat(lastSphere, curSphere);
+      quatRef.current = multiplyQuat(delta, quatRef.current);
+      lastSphere = curSphere;
+
+      const mat = quatToMat3(quatRef.current);
+      scatterRef.current?.set3dRotation(mat);
+
+      if (residualPCRef.current) {
+        axisOverlayRef.current?.setRotation3d(residualPCRef.current, mat);
+      }
+
+      if (!store.get(is3dRotatedAtom)) {
+        store.set(is3dRotatedAtom, true);
+      }
+    };
+
+    const endDrag = () => {
+      dragging = false;
+      lastSphere = null;
+    };
+
+    const onUp = (e: PointerEvent) => {
+      if (!dragging) return;
+      endDrag();
+      container.releasePointerCapture(e.pointerId);
+    };
+
+    container.addEventListener('pointerdown', onDown);
+    container.addEventListener('pointermove', onMove);
+    container.addEventListener('pointerup', onUp);
+    container.addEventListener('pointercancel', endDrag);
+    container.addEventListener('lostpointercapture', endDrag);
+    return () => {
+      container.removeEventListener('pointerdown', onDown);
+      container.removeEventListener('pointermove', onMove);
+      container.removeEventListener('pointerup', onUp);
+      container.removeEventListener('pointercancel', endDrag);
+      container.removeEventListener('lostpointercapture', endDrag);
+    };
+  }, [store]);
+
+  // Slerp revert animation
+  const revertCamera = useCallback(() => {
+    if (revertAnimRef.current !== null) cancelAnimationFrame(revertAnimRef.current);
+    const startQuat: Quat = [...quatRef.current];
+    if (isIdentityQuat(startQuat)) {
+      // Already at identity — just disable
+      scatterRef.current?.disable3d();
+      is3dEnabledRef.current = false;
+      quatRef.current = IDENTITY_QUAT;
+      residualPCRef.current = null;
+      axisOverlayRef.current?.clearRotation3d();
+      setIs3dRotated(false);
+      return;
+    }
+    const duration = 300;
+    const startTime = performance.now();
+    const tick = (now: number) => {
+      const elapsed = now - startTime;
+      const progress = Math.min(1, elapsed / duration);
+      // Ease-out cubic
+      const eased = 1 - (1 - progress) ** 3;
+      const q = slerp(startQuat, IDENTITY_QUAT, eased);
+      quatRef.current = q;
+      const mat = quatToMat3(q);
+      scatterRef.current?.set3dRotation(mat);
+      if (residualPCRef.current) {
+        axisOverlayRef.current?.setRotation3d(residualPCRef.current, mat);
+      }
+      if (progress < 1) {
+        revertAnimRef.current = requestAnimationFrame(tick);
+      } else {
+        revertAnimRef.current = null;
+        quatRef.current = IDENTITY_QUAT;
+        scatterRef.current?.disable3d();
+        is3dEnabledRef.current = false;
+        residualPCRef.current = null;
+        axisOverlayRef.current?.clearRotation3d();
+        setIs3dRotated(false);
+      }
+    };
+    revertAnimRef.current = requestAnimationFrame(tick);
+  }, [setIs3dRotated]);
+
+  // Escape key to revert
+  useEffect(() => {
+    if (!is3dRotated) return;
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        revertCamera();
+      }
+    };
+    window.addEventListener('keydown', handler);
+    return () => window.removeEventListener('keydown', handler);
+  }, [is3dRotated, revertCamera]);
+
+  // Reset 3D state when leaving manual mode
+  useEffect(() => {
+    if (viewMode === 'manual') return;
+    if (is3dEnabledRef.current) {
+      scatterRef.current?.disable3d();
+      is3dEnabledRef.current = false;
+      quatRef.current = IDENTITY_QUAT;
+      residualPCRef.current = null;
+      axisOverlayRef.current?.clearRotation3d();
+      setIs3dRotated(false);
+    }
+  }, [viewMode, setIs3dRotated]);
+
+  const tickCount = views?.length ?? embeddedViews?.length ?? previewCount;
   const hasData = !!data && !!metadata;
 
   if (import.meta.env.DEV && views && views.length !== previewCount) {
@@ -471,42 +836,45 @@ export const DtourViewer = ({
     );
   }
 
+  const overlayHeight = containerSize.height - overlayOffsetY;
+
   return (
     <div ref={containerRef} className="w-full h-full relative bg-dtour-bg">
-      {/* Overlay wrapper — translateY matches the shader inset so overlays
-          stay visually centered in the area below the toolbar. */}
-      <div className="absolute inset-0" style={{ transform: `translateY(${overlayOffsetY}px)` }}>
+      {/* Overlay wrapper — positioned below the toolbar so overlays
+          are visually centered in the area below the toolbar. */}
+      <div className="absolute left-0 right-0 bottom-0" style={{ top: `${overlayOffsetY}px` }}>
         {/* Preview gallery — only in guided mode */}
-        {isGuidedMode &&
-          hasData &&
-          containerSize.width > 0 &&
-          previewCanvasesRef.current.length > 0 && (
-            <Gallery
-              previewCanvases={previewCanvasesRef.current}
-              containerWidth={containerSize.width}
-              containerHeight={containerSize.height}
-              isToolbarVisible={isToolbarVisible}
-            />
-          )}
-
-        {/* Lasso selection overlay — available in all modes, below circular selector */}
-        {hasData && containerSize.width > 0 && (
-          <LassoOverlay
-            scatter={scatterRef.current}
-            width={containerSize.width}
-            height={containerSize.height}
+        {isGuidedMode && hasData && containerSize.width > 0 && previewCanvases.length > 0 && (
+          <Gallery
+            previewCanvases={previewCanvases}
+            containerWidth={containerSize.width}
+            containerHeight={overlayHeight}
+            toolbarHeight={0}
           />
         )}
 
-        {/* Manual mode axis overlay — rendered after lasso so handles are on top */}
-        {viewMode === 'manual' && hasData && containerSize.width > 0 && (
-          <AxisOverlay
-            scatter={scatterRef.current}
-            width={containerSize.width}
-            height={containerSize.height}
-          />
+        {/* Lasso selection overlay — available in all modes (disabled during 3D rotation) */}
+        {hasData && containerSize.width > 0 && !is3dRotated && (
+          <LassoOverlay scatter={scatter} width={containerSize.width} height={overlayHeight} />
         )}
 
+        {/* Axis overlay — interactive in manual mode (disabled during 3D rotation),
+            read-only in guided when enabled */}
+        {(viewMode === 'manual' || (isGuidedMode && showAxes)) &&
+          hasData &&
+          containerSize.width > 0 && (
+            <AxisOverlay
+              ref={axisOverlayRef}
+              scatter={scatter}
+              width={containerSize.width}
+              height={overlayHeight}
+              readOnly={isGuidedMode || is3dRotated}
+            />
+          )}
+
+        {/* Revert camera button — shown when 3D camera is rotated in manual mode */}
+        {viewMode === 'manual' && <RevertCameraButton onRevert={revertCamera} />}
+
         {/* Circular selector + radial chart overlay — only in guided mode, above lasso */}
         {isGuidedMode && hasData && (
           <div className="absolute inset-0 flex items-center justify-center pointer-events-none z-10">
@@ -519,18 +887,30 @@ export const DtourViewer = ({
                   position={position}
                   size={selectorSize}
                   innerRadius={selectorSize * 0.4}
+                  arcLengths={arcLengths}
+                  spacingMode={spacingMode}
                 />
               </div>
             )}
             {/* Selector — on top for drag interaction */}
             <div className="pointer-events-none relative z-10">
               <CircularSlider
-                value={position}
+                ref={sliderRef}
+                value={
+                  spacingMode === 'equal' && arcLengths
+                    ? tourToVisual(position, arcLengths)
+                    : position
+                }
                 onChange={handlePositionChange}
                 onSeek={handlePositionSeek}
                 onDragStart={handleDragStart}
                 tickCount={tickCount}
                 size={selectorSize}
+                arcLengths={arcLengths}
+                spacingMode={spacingMode}
+                currentKeyframe={currentKeyframe}
+                hoveredKeyframe={hoveredKeyframe}
+                previewCenters={previewCenters}
               />
             </div>
           </div>