@dtour/viewer 0.1.0 → 0.2.0

package/src/hooks/usePlayback.ts

@@ -1,54 +1,28 @@
-import { useAtomValue, useSetAtom } from 'jotai';
-import { useEffect, useRef } from 'react';
-import {
-  tourDirectionAtom,
-  tourPlayingAtom,
-  tourPositionAtom,
-  tourSpeedAtom,
-} from '../state/atoms.ts';
+import type { ScatterInstance } from '@dtour/scatter';
+import { useAtomValue } from 'jotai';
+import { useEffect } from 'react';
+import { tourDirectionAtom, tourPlayingAtom, tourSpeedAtom } from '../state/atoms.ts';
 
 /**
- * rAF loop that advances tour position when playing.
+ * Delegates playback to the GPU worker's rAF loop.
  *
- * Reads playing/speed/direction from atoms, writes position.
- * Automatically pauses when the tab is hidden (rAF stops firing).
- * Wraps at 0/1 for cyclic tour.
+ * When playing, sends startPlayback to the scatter instance which runs
+ * a requestAnimationFrame loop in the GPU worker — rendering directly
+ * without main-thread involvement. Position updates are broadcast back
+ * at ~30fps for UI sync (slider, atom).
  */
-export const usePlayback = () => {
+export const usePlayback = (scatter: ScatterInstance | null) => {
   const playing = useAtomValue(tourPlayingAtom);
   const speed = useAtomValue(tourSpeedAtom);
   const direction = useAtomValue(tourDirectionAtom);
-  const setPosition = useSetAtom(tourPositionAtom);
-
-  // Use refs for values read inside rAF to avoid re-creating the effect
-  const speedRef = useRef(speed);
-  speedRef.current = speed;
-  const directionRef = useRef(direction);
-  directionRef.current = direction;
 
   useEffect(() => {
-    if (!playing) return;
-
-    let prevTime: number | null = null;
-    let rafId: number;
-
-    const tick = (time: number) => {
-      if (prevTime !== null) {
-        const dt = (time - prevTime) / 1000; // seconds
-        // Full tour cycle = 20s at speed=1
-        const delta = (dt * speedRef.current * directionRef.current) / 20;
-        setPosition((prev) => {
-          let next = prev + delta;
-          // Wrap cyclically
-          next = next - Math.floor(next);
-          return next;
-        });
-      }
-      prevTime = time;
-      rafId = requestAnimationFrame(tick);
-    };
-
-    rafId = requestAnimationFrame(tick);
-    return () => cancelAnimationFrame(rafId);
-  }, [playing, setPosition]);
+    if (!scatter) return;
+    if (playing) {
+      scatter.startPlayback(speed, direction);
+    } else {
+      scatter.stopPlayback();
+    }
+    return () => scatter.stopPlayback();
+  }, [scatter, playing, speed, direction]);
 };

package/src/hooks/useScatter.ts

@@ -2,12 +2,14 @@ import type { ScatterInstance, ScatterStatus } from '@dtour/scatter';
 import { useAtomValue, useSetAtom } from 'jotai';
 import { useEffect, useRef } from 'react';
 import { hexToRgb, hexToRgb255, isHexColor } from '../lib/color-utils.ts';
+import { parseEmbeddedConfig } from '../spec.ts';
 import {
   backgroundColorAtom,
   cameraPanXAtom,
   cameraPanYAtom,
   cameraZoomAtom,
   colorMapAtom,
+  embeddedConfigAtom,
   guidedSuspendedAtom,
   legendClearGenAtom,
   legendSelectionAtom,
@@ -17,6 +19,7 @@ import {
   pointOpacityAtom,
   pointSizeAtom,
   resolvedThemeAtom,
+  tourPlayingAtom,
   tourPositionAtom,
 } from '../state/atoms.ts';
 
@@ -33,6 +36,7 @@ export const useScatter = (scatter: ScatterInstance | null) => {
   const opacity = useAtomValue(pointOpacityAtom);
   const color = useAtomValue(pointColorAtom);
   const guidedSuspended = useAtomValue(guidedSuspendedAtom);
+  const playing = useAtomValue(tourPlayingAtom);
   const panX = useAtomValue(cameraPanXAtom);
   const panY = useAtomValue(cameraPanYAtom);
   const zoom = useAtomValue(cameraZoomAtom);
@@ -58,11 +62,12 @@ export const useScatter = (scatter: ScatterInstance | null) => {
     scatter?.setCamera({ pan: [panX, panY], zoom });
   }, [scatter, panX, panY, zoom]);
 
-  // Forward tour position (skipped when suspended after returning from manual/grand)
+  // Forward tour position (skipped during worker-driven playback and when
+  // suspended after returning from manual/grand)
   useEffect(() => {
-    if (guidedSuspended) return;
+    if (guidedSuspended || playing) return;
     scatter?.setTourPosition(position);
-  }, [scatter, position, guidedSuspended]);
+  }, [scatter, position, guidedSuspended, playing]);
 
   // Forward point style (size + opacity + uniform color)
   useEffect(() => {
@@ -77,8 +82,13 @@ export const useScatter = (scatter: ScatterInstance | null) => {
       scatter.clearColor();
       scatter.setStyle({ pointSize, opacity, color: hexToRgb(color) });
     } else {
-      // Column name — encode per-point colors via data worker
+      // Column name — encode per-point colors via data worker.
+      // Skip until metadata is available: the data worker only knows column
+      // names after it has parsed the dataset, so encodeColor sent before
+      // that point would silently no-op.  Including metadata in the deps
+      // ensures we re-send once data is ready.
       scatter.setStyle({ pointSize, opacity });
+      if (!metadata) return;
       // Resolve theme-aware colorMap to Record<string, [r,g,b]> for the scatter worker
       let resolvedColorMap: Record<string, [number, number, number]> | undefined;
       if (rawColorMap) {
@@ -90,7 +100,7 @@ export const useScatter = (scatter: ScatterInstance | null) => {
       }
       scatter.encodeColor(color, palette, resolvedTheme, resolvedColorMap);
     }
-  }, [scatter, pointSize, opacity, color, palette, resolvedTheme, rawColorMap]);
+  }, [scatter, pointSize, opacity, color, palette, resolvedTheme, rawColorMap, metadata]);
 
   // Forward legend selection → scatter.selectByColumn
   useEffect(() => {
@@ -150,12 +160,18 @@ export const useScatter = (scatter: ScatterInstance | null) => {
   const setLegendSelectionRef = useRef(setLegendSelection);
   setLegendSelectionRef.current = setLegendSelection;
 
+  const setEmbeddedConfig = useSetAtom(embeddedConfigAtom);
+  const setEmbeddedConfigRef = useRef(setEmbeddedConfig);
+  setEmbeddedConfigRef.current = setEmbeddedConfig;
+
   useEffect(() => {
     if (!scatter) return;
     return scatter.subscribe((s: ScatterStatus) => {
       if (s.type === 'metadata') {
         setMetadataRef.current(s.metadata);
         setLegendSelectionRef.current(null);
+        // Parse and store embedded config from Parquet metadata
+        setEmbeddedConfigRef.current(parseEmbeddedConfig(s.metadata.embeddedConfig));
       }
     });
   }, [scatter]);

package/src/index.ts

@@ -4,8 +4,8 @@ import './styles.css';
 // Primary API — self-contained component with spec-driven state
 export { Dtour } from './Dtour.tsx';
 export type { DtourProps, DtourHandle } from './Dtour.tsx';
-export type { DtourSpec } from './spec.ts';
-export { dtourSpecSchema, DTOUR_DEFAULTS } from './spec.ts';
+export type { DtourSpec, EmbeddedConfig } from './spec.ts';
+export { dtourSpecSchema, DTOUR_DEFAULTS, parseEmbeddedConfig } from './spec.ts';
 
 // Portal container — for Shadow DOM isolation (e.g. anywidget/Marimo)
 export { PortalContainerContext } from './portal-container.tsx';
@@ -15,7 +15,7 @@ export { DtourViewer } from './DtourViewer.tsx';
 export type { DtourViewerProps } from './DtourViewer.tsx';
 export { DtourToolbar } from './components/DtourToolbar.tsx';
 export { CircularSlider } from './components/CircularSlider.tsx';
-export type { CircularSliderProps } from './components/CircularSlider.tsx';
+export type { CircularSliderProps, CircularSliderHandle } from './components/CircularSlider.tsx';
 export { createDefaultViews } from './views.ts';
 
 // Radial chart — quality metrics visualization
@@ -29,10 +29,14 @@ export {
   tourPlayingAtom,
   tourSpeedAtom,
   tourDirectionAtom,
+  sliderSpacingAtom,
+  arcLengthsAtom,
   // Preview
   previewCountAtom,
   previewPaddingAtom,
   selectedKeyframeAtom,
+  currentKeyframeAtom,
+  hoveredKeyframeAtom,
   // Point style
   pointSizeAtom,
   pointOpacityAtom,
@@ -46,10 +50,19 @@ export {
   viewModeAtom,
   // Legend
   showLegendAtom,
+  // Axes
+  showAxesAtom,
+  // Frame numbers
+  showFrameNumbersAtom,
+  // Frame loadings
+  showFrameLoadingsAtom,
+  frameLoadingsAtom,
+  tourModeAtom,
   legendVisibleAtom,
   // Theme
   themeModeAtom,
   resolvedThemeAtom,
   // Read-only
   metadataAtom,
+  embeddedConfigAtom,
 } from './state/atoms.ts';

package/src/layout/gallery-positions.ts

@@ -2,6 +2,8 @@
 export const GAP = 32;
 /** Maximum preview size (CSS px). */
 export const MAX_SIZE = 320;
+/** Height of the loading bar below/above each preview (CSS px). */
+export const LOADING_BAR_HEIGHT = 24;
 /**
  * Per-edge-count ratio arrays.
  *   k=1 (4 previews)  → [1]             all same
@@ -61,6 +63,7 @@ export function computeGallerySizes(
   containerHeight: number,
   previewCount: number,
   scale = 1,
+  showLoadings = false,
 ): GallerySizes {
   const k = Math.max(1, previewCount / 4);
   const numTracks = k + 1;
@@ -74,14 +77,22 @@ export function computeGallerySizes(
     ratioSum += r;
   }
 
+  // When loading bars are shown, each row track needs extra height.
+  // Subtract the total loading bar height from the available vertical
+  // space before computing the base size so previews stay square.
+  const loadingExtra = showLoadings ? LOADING_BAR_HEIGHT : 0;
+  const totalLoadingHeight = showLoadings ? numTracks * loadingExtra : 0;
+
   // Derive all track sizes from the short side so previews stay square.
   // Available = shortSide - gaps between tracks.
   // baseSize is the unit; corner = 1.0×base, mid-edge = 0.8×base, etc.
-  const shortSide = Math.min(containerWidth, containerHeight);
+  const effectiveHeight = containerHeight - totalLoadingHeight;
+  const shortSide = Math.min(containerWidth, effectiveHeight);
   const availableForCells = shortSide - (numTracks - 1) * GAP;
   const baseSize = Math.min(MAX_SIZE, availableForCells / ratioSum) * scale;
 
-  const template = ratios.map((r) => `${Math.round(baseSize * r)}px`).join(' ');
+  const colTemplate = ratios.map((r) => `${Math.round(baseSize * r)}px`).join(' ');
+  const rowTemplate = ratios.map((r) => `${Math.round(baseSize * r + loadingExtra)}px`).join(' ');
   const previewSize = baseSize;
 
   // Per-preview sizes: each preview's size depends on its edge position.
@@ -95,8 +106,8 @@ export function computeGallerySizes(
   const padY = previewSize / 2;
 
   return {
-    gridTemplateColumns: template,
-    gridTemplateRows: template,
+    gridTemplateColumns: colTemplate,
+    gridTemplateRows: rowTemplate,
     sizes,
     previewSize,
     padX,

package/src/layout/selector-size.ts

@@ -1,4 +1,4 @@
-import { GAP, MAX_SIZE, sizeRatio } from './gallery-positions.ts';
+import { GAP, LOADING_BAR_HEIGHT, MAX_SIZE, sizeRatio } from './gallery-positions.ts';
 
 const MIN_SIZE = 80;
 
@@ -24,11 +24,13 @@ export function computeSelectorSize(
   containerWidth: number,
   containerHeight: number,
   previewCount: number,
-  isToolbarVisible: boolean,
+  toolbarHeight: number,
   padding: number,
   scale = 1,
   /** Number of radial metric tracks rendered outside the ring. */
   metricTrackCount = 0,
+  /** Whether loading bars are shown below/above previews. */
+  showLoadings = false,
 ): number {
   if (previewCount === 0 || containerWidth <= 0 || containerHeight <= 0) {
     return Math.max(MIN_SIZE, Math.min(containerWidth, containerHeight));
@@ -36,12 +38,13 @@ export function computeSelectorSize(
 
   const k = Math.max(1, previewCount / 4);
   const numTracks = k + 1;
+  const loadingExtra = showLoadings ? LOADING_BAR_HEIGHT : 0;
 
   // Must match Gallery CSS: left-4, right-4, top/bottom = verticalInset.
-  // When toolbar is visible overlayOffsetY = toolbarHeight/2 = 20 shifts
-  // the wrapper down, so we bump vertical insets to keep 16px visual gap.
+  // The overlay wrapper shifts down by toolbarHeight/2, so we bump
+  // vertical insets to keep a 16px visual gap below the toolbar.
   const gridLeft = 16;
-  const toolbarOffset = isToolbarVisible ? 20 : 0; // toolbarHeight / 2
+  const toolbarOffset = toolbarHeight / 2;
   const verticalInset = 16 + toolbarOffset;
   const gridW = containerWidth - 2 * gridLeft;
   const gridH = containerHeight - 2 * verticalInset;
@@ -54,16 +57,20 @@ export function computeSelectorSize(
     ratios.push(r);
     ratioSum += r;
   }
-  const shortSide = Math.min(gridW, gridH);
+  const totalLoadingHeight = numTracks * loadingExtra;
+  const effectiveHeight = gridH - totalLoadingHeight;
+  const shortSide = Math.min(gridW, effectiveHeight);
   const availableForCells = shortSide - (numTracks - 1) * GAP;
   const baseSize = Math.min(MAX_SIZE, availableForCells / ratioSum) * scale;
   const trackSizes = ratios.map((r) => baseSize * r);
+  const rowTrackSizes = ratios.map((r) => baseSize * r + loadingExtra);
   const trackTotal = trackSizes.reduce((a, b) => a + b, 0);
+  const rowTrackTotal = rowTrackSizes.reduce((a, b) => a + b, 0);
 
   // Effective gaps: CSS justify-content/align-content: space-between
   // distributes remaining free space equally between inter-track gutters.
   const freeX = gridW - trackTotal - (numTracks - 1) * GAP;
-  const freeY = gridH - trackTotal - (numTracks - 1) * GAP;
+  const freeY = gridH - rowTrackTotal - (numTracks - 1) * GAP;
   const effGapX = GAP + (numTracks > 1 ? Math.max(0, freeX) / (numTracks - 1) : 0);
   const effGapY = GAP + (numTracks > 1 ? Math.max(0, freeY) / (numTracks - 1) : 0);
 
@@ -72,7 +79,7 @@ export function computeSelectorSize(
   const rowStarts: number[] = [0];
   for (let j = 1; j <= k; j++) {
     colStarts.push(colStarts[j - 1]! + trackSizes[j - 1]! + effGapX);
-    rowStarts.push(rowStarts[j - 1]! + trackSizes[j - 1]! + effGapY);
+    rowStarts.push(rowStarts[j - 1]! + rowTrackSizes[j - 1]! + effGapY);
   }
 
   // Selector centre in the overlay-wrapper coordinate system
@@ -104,7 +111,7 @@ export function computeSelectorSize(
     const cellX = gridLeft + colStarts[col]!;
     const cellY = verticalInset + rowStarts[row]!;
     const cellW = trackSizes[col]!;
-    const cellH = trackSizes[row]!;
+    const cellH = rowTrackSizes[row]!;
     const size = baseSize * sizeRatio(i % k, k);
 
     // Alignment within cell (matches Gallery flex alignment)
@@ -113,14 +120,21 @@ export function computeSelectorSize(
     else if (col === k) px = cellX + cellW - size;
     else px = cellX + (cellW - size) / 2;
 
+    // Vertical: the cell now includes loading bar height.
+    // Bottom-edge previews have the bar above (flex-col-reverse),
+    // so the preview canvas sits at the bottom of the cell.
     let py: number;
     if (row === 0) py = cellY;
     else if (row === k) py = cellY + cellH - size;
     else py = cellY + (cellH - size) / 2;
 
+    // Bounding box includes loading bar
+    const boxH = size + loadingExtra;
+    const boxY = row === k ? py - loadingExtra : py;
+
     // Euclidean distance from centre to nearest point on preview rect
     const dx = Math.max(0, px - cx, cx - (px + size));
-    const dy = Math.max(0, py - cy, cy - (py + size));
+    const dy = Math.max(0, boxY - cy, cy - (boxY + boxH));
     minDist = Math.min(minDist, Math.sqrt(dx * dx + dy * dy));
   }
 

package/src/lib/arcball.ts

@@ -0,0 +1,119 @@
+/**
+ * Arcball rotation utilities — Shoemake-style trackball for 3D camera rotation.
+ * All quaternions are [x, y, z, w] format. Rotation matrices are 3×3 column-major.
+ */
+
+export type Quat = [number, number, number, number];
+
+export const IDENTITY_QUAT: Quat = [0, 0, 0, 1];
+
+/** Project a screen point (in [-1,1]² NDC) onto the arcball sphere. */
+export const projectToSphere = (x: number, y: number): [number, number, number] => {
+  const r2 = x * x + y * y;
+  if (r2 <= 1) {
+    // On the sphere
+    return [x, y, Math.sqrt(1 - r2)];
+  }
+  // Outside sphere — project onto edge
+  const s = 1 / Math.sqrt(r2);
+  return [x * s, y * s, 0];
+};
+
+/** Compute rotation quaternion that takes vector `from` to vector `to`. */
+export const arcballQuat = (from: [number, number, number], to: [number, number, number]): Quat => {
+  // Cross product = rotation axis, dot product = cos(angle)
+  const cx = from[1] * to[2] - from[2] * to[1];
+  const cy = from[2] * to[0] - from[0] * to[2];
+  const cz = from[0] * to[1] - from[1] * to[0];
+  const dot = from[0] * to[0] + from[1] * to[1] + from[2] * to[2];
+  // q = (cross, 1 + dot), then normalize — avoids trig
+  const w = 1 + dot;
+  const len = Math.sqrt(cx * cx + cy * cy + cz * cz + w * w);
+  if (len < 1e-12) return IDENTITY_QUAT;
+  return [cx / len, cy / len, cz / len, w / len];
+};
+
+/** Multiply two quaternions: result = a * b. */
+export const multiplyQuat = (a: Quat, b: Quat): Quat => [
+  a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1],
+  a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0],
+  a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3],
+  a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2],
+];
+
+/** Normalize a quaternion in-place and return it. */
+export const normalizeQuat = (q: Quat): Quat => {
+  const len = Math.sqrt(q[0] * q[0] + q[1] * q[1] + q[2] * q[2] + q[3] * q[3]);
+  if (len < 1e-12) return IDENTITY_QUAT;
+  return [q[0] / len, q[1] / len, q[2] / len, q[3] / len];
+};
+
+/** SLERP between two quaternions. t=0 → a, t=1 → b. */
+export const slerp = (a: Quat, b: Quat, t: number): Quat => {
+  // Ensure shortest path
+  let dot = a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3];
+  let bx = b[0];
+  let by = b[1];
+  let bz = b[2];
+  let bw = b[3];
+  if (dot < 0) {
+    dot = -dot;
+    bx = -bx;
+    by = -by;
+    bz = -bz;
+    bw = -bw;
+  }
+
+  if (dot > 0.9995) {
+    // Very close — use linear interpolation to avoid division by zero
+    return normalizeQuat([
+      a[0] + t * (bx - a[0]),
+      a[1] + t * (by - a[1]),
+      a[2] + t * (bz - a[2]),
+      a[3] + t * (bw - a[3]),
+    ]);
+  }
+
+  const theta = Math.acos(dot);
+  const sinTheta = Math.sin(theta);
+  const wa = Math.sin((1 - t) * theta) / sinTheta;
+  const wb = Math.sin(t * theta) / sinTheta;
+  return [wa * a[0] + wb * bx, wa * a[1] + wb * by, wa * a[2] + wb * bz, wa * a[3] + wb * bw];
+};
+
+/** Convert quaternion to 3×3 column-major rotation matrix (9-element Float32Array). */
+export const quatToMat3 = (q: Quat): Float32Array => {
+  const [x, y, z, w] = q;
+  const x2 = x + x;
+  const y2 = y + y;
+  const z2 = z + z;
+  const xx = x * x2;
+  const xy = x * y2;
+  const xz = x * z2;
+  const yy = y * y2;
+  const yz = y * z2;
+  const zz = z * z2;
+  const wx = w * x2;
+  const wy = w * y2;
+  const wz = w * z2;
+
+  // Column-major: col0, col1, col2
+  return new Float32Array([
+    1 - (yy + zz),
+    xy + wz,
+    xz - wy, // col0
+    xy - wz,
+    1 - (xx + zz),
+    yz + wx, // col1
+    xz + wy,
+    yz - wx,
+    1 - (xx + yy), // col2
+  ]);
+};
+
+/** Check if a quaternion is approximately identity (no rotation). */
+export const isIdentityQuat = (q: Quat, epsilon = 1e-4): boolean =>
+  Math.abs(q[0]) < epsilon &&
+  Math.abs(q[1]) < epsilon &&
+  Math.abs(q[2]) < epsilon &&
+  Math.abs(Math.abs(q[3]) - 1) < epsilon;

package/src/lib/position-remap.ts

@@ -0,0 +1,51 @@
+/**
+ * Convert tour position (arc-length parameterized) to visual position (equal spacing).
+ *
+ * In equal mode, keyframe `i` occupies visual range `[i/n, (i+1)/n]`.
+ * We binary-search for the arc-length segment containing `tourPos`, compute
+ * fractional progress within it, and map to the corresponding visual segment.
+ */
+export const tourToVisual = (tourPos: number, arcLengths: Float32Array): number => {
+  const n = arcLengths.length - 1;
+  if (n <= 0) return tourPos;
+  const clamped = Math.max(0, Math.min(1, tourPos));
+
+  // Binary search for the segment containing clamped
+  let lo = 0;
+  let hi = n - 1;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    if (arcLengths[mid + 1]! <= clamped) {
+      lo = mid + 1;
+    } else {
+      hi = mid;
+    }
+  }
+
+  const segStart = arcLengths[lo]!;
+  const segEnd = arcLengths[lo + 1]!;
+  const segLen = segEnd - segStart;
+  const localT = segLen > 1e-10 ? (clamped - segStart) / segLen : 0;
+
+  return (lo + localT) / n;
+};
+
+/**
+ * Convert visual position (equal spacing) to tour position (arc-length).
+ *
+ * Visual position `v` maps to segment `floor(v * n)`, with local fraction
+ * `frac(v * n)` interpolating within that arc-length segment.
+ */
+export const visualToTour = (visualPos: number, arcLengths: Float32Array): number => {
+  const n = arcLengths.length - 1;
+  if (n <= 0) return visualPos;
+  const clamped = Math.max(0, Math.min(1, visualPos));
+
+  const scaled = clamped * n;
+  const segment = Math.min(Math.floor(scaled), n - 1);
+  const localT = scaled - segment;
+
+  const segStart = arcLengths[segment]!;
+  const segEnd = arcLengths[segment + 1]!;
+  return segStart + localT * (segEnd - segStart);
+};

package/src/lib/throttle-debounce.ts

@@ -0,0 +1,79 @@
+/**
+ * Throttle and debounce a function call.
+ *
+ * Throttling ensures the function is called at most every `throttleTime` ms.
+ * Debouncing ensures a final call happens after `debounceTime` ms of silence.
+ * Combined, this gives periodic updates during rapid firing AND a guaranteed
+ * final call with the latest arguments.
+ *
+ * Example with throttleTime=3 and debounceTime=3:
+ *   1. call(args1) => fn(args1) called immediately
+ *   2. call(args2) => ignored (throttled)
+ *   3. call(args3) => ignored (throttled)
+ *   4. call(args4) => fn(args4) called (throttle window expired)
+ *   5. call(args5) => ignored (throttled)
+ *   6. (silence)
+ *   7. fn(args5) called (debounce fires)
+ */
+export type ThrottledAndDebouncedFunction<Input extends unknown[]> = {
+  (...args: Input): void;
+  /** Cancel the pending debounce timer. */
+  cancel: () => void;
+  /** Reset throttle state so the next call fires immediately. */
+  reset: () => void;
+  /** Bypass throttle/debounce and call immediately. */
+  now: (...args: Input) => void;
+};
+
+export const throttleAndDebounce = <Input extends unknown[]>(
+  fn: (...args: Input) => void,
+  throttleTime: number,
+  debounceTime?: number,
+): ThrottledAndDebouncedFunction<Input> => {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  let blockedCalls = 0;
+
+  const finalWait = debounceTime ?? throttleTime;
+
+  const debounced = (...args: Input) => {
+    const later = () => {
+      if (blockedCalls > 0) {
+        fn(...args);
+        blockedCalls = 0;
+      }
+    };
+
+    clearTimeout(timeout);
+    timeout = setTimeout(later, finalWait);
+  };
+
+  let isWaiting = false;
+  const throttledAndDebounced = (...args: Input) => {
+    if (isWaiting) {
+      blockedCalls++;
+      debounced(...args);
+    } else {
+      fn(...args);
+      debounced(...args);
+
+      isWaiting = true;
+      blockedCalls = 0;
+
+      setTimeout(() => {
+        isWaiting = false;
+      }, throttleTime);
+    }
+  };
+
+  throttledAndDebounced.reset = () => {
+    isWaiting = false;
+  };
+
+  throttledAndDebounced.cancel = () => {
+    clearTimeout(timeout);
+  };
+
+  throttledAndDebounced.now = (...args: Input) => fn(...args);
+
+  return throttledAndDebounced;
+};