@dtour/viewer 0.1.0

package/src/hooks/useModeCycling.ts

@@ -0,0 +1,64 @@
+import { useAtomValue, useSetAtom } from 'jotai';
+import { useEffect, useRef } from 'react';
+import {
+  grandExitTargetAtom,
+  guidedSuspendedAtom,
+  tourPlayingAtom,
+  viewModeAtom,
+} from '../state/atoms.ts';
+
+const MODES = ['guided', 'manual', 'grand'] as const;
+
+/**
+ * Cycles view modes on Shift+Tab (guided → manual → grand → guided).
+ *
+ * Also manages guided suspension: pauses playback when leaving guided mode,
+ * and sets `guidedSuspended` when returning to guided so the current
+ * projection is preserved until the user interacts with the slider.
+ *
+ * When exiting grand mode, defers the actual mode switch so the grand
+ * tour animation can ease out first.
+ */
+export const useModeCycling = () => {
+  const viewMode = useAtomValue(viewModeAtom);
+  const setViewMode = useSetAtom(viewModeAtom);
+  const setPlaying = useSetAtom(tourPlayingAtom);
+  const setGuidedSuspended = useSetAtom(guidedSuspendedAtom);
+  const setGrandExitTarget = useSetAtom(grandExitTargetAtom);
+
+  // Use ref so the keydown handler always sees the latest viewMode
+  // without needing to re-register the listener on every mode change.
+  const viewModeRef = useRef(viewMode);
+  viewModeRef.current = viewMode;
+
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key !== 'Tab' || !e.shiftKey || e.repeat || e.ctrlKey || e.metaKey || e.altKey) return;
+      e.preventDefault();
+
+      const current = viewModeRef.current;
+      const idx = MODES.indexOf(current);
+      const next = MODES[(idx + 1) % MODES.length]!;
+
+      if (current === 'grand') {
+        // Exiting grand — request ease-out, defer mode switch
+        // next is always 'guided' here (grand → guided in the cycle)
+        setGrandExitTarget(next as 'guided' | 'manual');
+      } else {
+        if (current === 'guided') {
+          setPlaying(false);
+        }
+        if (next === 'guided') {
+          setGuidedSuspended(true);
+        }
+        if (next === 'grand') {
+          setGrandExitTarget(null);
+        }
+        setViewMode(next);
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [setViewMode, setPlaying, setGuidedSuspended, setGrandExitTarget]);
+};

package/src/hooks/usePlayback.ts

@@ -0,0 +1,54 @@
+import { useAtomValue, useSetAtom } from 'jotai';
+import { useEffect, useRef } from 'react';
+import {
+  tourDirectionAtom,
+  tourPlayingAtom,
+  tourPositionAtom,
+  tourSpeedAtom,
+} from '../state/atoms.ts';
+
+/**
+ * rAF loop that advances tour position when playing.
+ *
+ * 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.
+ */
+export const usePlayback = () => {
+  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]);
+};

package/src/hooks/useScatter.ts

@@ -0,0 +1,162 @@
+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 {
+  backgroundColorAtom,
+  cameraPanXAtom,
+  cameraPanYAtom,
+  cameraZoomAtom,
+  colorMapAtom,
+  guidedSuspendedAtom,
+  legendClearGenAtom,
+  legendSelectionAtom,
+  metadataAtom,
+  paletteAtom,
+  pointColorAtom,
+  pointOpacityAtom,
+  pointSizeAtom,
+  resolvedThemeAtom,
+  tourPositionAtom,
+} from '../state/atoms.ts';
+
+/**
+ * Bridge between Jotai atoms and a ScatterInstance.
+ *
+ * Subscribes to atom changes and forwards them as postMessage calls
+ * to the GPU worker. Also subscribes to scatter status events and
+ * writes metadata back into Jotai.
+ */
+export const useScatter = (scatter: ScatterInstance | null) => {
+  const position = useAtomValue(tourPositionAtom);
+  const pointSize = useAtomValue(pointSizeAtom);
+  const opacity = useAtomValue(pointOpacityAtom);
+  const color = useAtomValue(pointColorAtom);
+  const guidedSuspended = useAtomValue(guidedSuspendedAtom);
+  const panX = useAtomValue(cameraPanXAtom);
+  const panY = useAtomValue(cameraPanYAtom);
+  const zoom = useAtomValue(cameraZoomAtom);
+  const backgroundColor = useAtomValue(backgroundColorAtom);
+  const palette = useAtomValue(paletteAtom);
+  const resolvedTheme = useAtomValue(resolvedThemeAtom);
+  const rawColorMap = useAtomValue(colorMapAtom);
+  const metadata = useAtomValue(metadataAtom);
+  const setMetadata = useSetAtom(metadataAtom);
+  const legendSelection = useAtomValue(legendSelectionAtom);
+  const legendClearGen = useAtomValue(legendClearGenAtom);
+  const setLegendSelection = useSetAtom(legendSelectionAtom);
+
+  // Forward background color
+  useEffect(() => {
+    scatter?.setBackgroundColor(backgroundColor);
+  }, [scatter, backgroundColor]);
+
+  // Forward camera — registered first so the worker receives setCamera before
+  // setTourPosition (which triggers a render). Otherwise the first render uses
+  // the client's default zoom=1 instead of the atom value.
+  useEffect(() => {
+    scatter?.setCamera({ pan: [panX, panY], zoom });
+  }, [scatter, panX, panY, zoom]);
+
+  // Forward tour position (skipped when suspended after returning from manual/grand)
+  useEffect(() => {
+    if (guidedSuspended) return;
+    scatter?.setTourPosition(position);
+  }, [scatter, position, guidedSuspended]);
+
+  // Forward point style (size + opacity + uniform color)
+  useEffect(() => {
+    if (!scatter) return;
+
+    if (Array.isArray(color)) {
+      // RGB tuple — uniform color; clear any per-point encoding
+      scatter.clearColor();
+      scatter.setStyle({ pointSize, opacity, color });
+    } else if (isHexColor(color)) {
+      // Hex string — parse to RGB uniform color
+      scatter.clearColor();
+      scatter.setStyle({ pointSize, opacity, color: hexToRgb(color) });
+    } else {
+      // Column name — encode per-point colors via data worker
+      scatter.setStyle({ pointSize, opacity });
+      // Resolve theme-aware colorMap to Record<string, [r,g,b]> for the scatter worker
+      let resolvedColorMap: Record<string, [number, number, number]> | undefined;
+      if (rawColorMap) {
+        resolvedColorMap = {};
+        for (const [label, value] of Object.entries(rawColorMap)) {
+          const hex = typeof value === 'string' ? value : value[resolvedTheme];
+          resolvedColorMap[label] = hexToRgb255(hex);
+        }
+      }
+      scatter.encodeColor(color, palette, resolvedTheme, resolvedColorMap);
+    }
+  }, [scatter, pointSize, opacity, color, palette, resolvedTheme, rawColorMap]);
+
+  // Forward legend selection → scatter.selectByColumn
+  useEffect(() => {
+    if (!scatter || !metadata || legendSelection === null || legendSelection.size === 0) return;
+
+    // Determine the active color column
+    if (typeof color !== 'string' || isHexColor(color)) return;
+    const column = color;
+
+    const isCategorical = metadata.categoricalColumnNames.includes(column);
+
+    if (isCategorical) {
+      scatter.selectByColumn(column, { labelIndices: Array.from(legendSelection) });
+    } else {
+      // Continuous: 13 stops (indices 0–12). Middle stops each cover range/12,
+      // end stops (0 and 12) cover half that (range/24).
+      const colIndex = metadata.columnNames.indexOf(column);
+      if (colIndex === -1) return;
+      const min = metadata.mins[colIndex]!;
+      const max = metadata.maxes[colIndex]!;
+      const range = max - min;
+      const midWidth = range / 12;
+      const endWidth = midWidth / 2;
+
+      const ranges: number[] = [];
+      for (const stopIdx of legendSelection) {
+        const lo = stopIdx === 0 ? min : min + endWidth + (stopIdx - 1) * midWidth;
+        const hi = stopIdx === 12 ? max : min + endWidth + stopIdx * midWidth;
+        ranges.push(lo, hi);
+      }
+
+      scatter.selectByColumn(column, { valueRanges: new Float32Array(ranges) });
+    }
+  }, [scatter, legendSelection, color, metadata]);
+
+  // Clear scatter selection when legend explicitly deselects (gen bumped by ColorLegend)
+  useEffect(() => {
+    if (!scatter || legendClearGen === 0) return;
+    scatter.clearSelection();
+  }, [scatter, legendClearGen]);
+
+  // Reset legend selection and clear GPU selection mask when color column changes
+  const prevColorRef = useRef(color);
+  useEffect(() => {
+    if (prevColorRef.current !== color) {
+      prevColorRef.current = color;
+      setLegendSelection(null);
+      scatter?.clearSelection();
+    }
+  }, [scatter, color, setLegendSelection]);
+
+  // Subscribe to scatter status events and update metadata atom.
+  // Use a ref so the setMetadata closure never goes stale.
+  const setMetadataRef = useRef(setMetadata);
+  setMetadataRef.current = setMetadata;
+
+  const setLegendSelectionRef = useRef(setLegendSelection);
+  setLegendSelectionRef.current = setLegendSelection;
+
+  useEffect(() => {
+    if (!scatter) return;
+    return scatter.subscribe((s: ScatterStatus) => {
+      if (s.type === 'metadata') {
+        setMetadataRef.current(s.metadata);
+        setLegendSelectionRef.current(null);
+      }
+    });
+  }, [scatter]);
+};

package/src/hooks/useSystemTheme.ts

@@ -0,0 +1,19 @@
+import { useSetAtom } from 'jotai';
+import { useEffect } from 'react';
+import { systemThemeAtom } from '../state/atoms.ts';
+
+/**
+ * Subscribes to the OS-level color scheme preference and updates
+ * `systemThemeAtom`. Called once in DtourInner.
+ */
+export const useSystemTheme = () => {
+  const setSystemTheme = useSetAtom(systemThemeAtom);
+
+  useEffect(() => {
+    const mql = window.matchMedia('(prefers-color-scheme: dark)');
+    const update = () => setSystemTheme(mql.matches ? 'dark' : 'light');
+    update();
+    mql.addEventListener('change', update);
+    return () => mql.removeEventListener('change', update);
+  }, [setSystemTheme]);
+};

package/src/index.ts

@@ -0,0 +1,55 @@
+// @dtour/viewer — React UI for dtour: circular selector, preview gallery, tour controls.
+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';
+
+// Portal container — for Shadow DOM isolation (e.g. anywidget/Marimo)
+export { PortalContainerContext } from './portal-container.tsx';
+
+// Advanced composable API — for users who need granular control with their own Provider
+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 { createDefaultViews } from './views.ts';
+
+// Radial chart — quality metrics visualization
+export { RadialChart, parseMetrics } from './radial-chart/index.ts';
+export type { RadialTrackConfig, ParsedTrack, RadialChartProps } from './radial-chart/index.ts';
+
+// Jotai atoms — for advanced users composing with DtourViewer + own Provider
+export {
+  // Tour
+  tourPositionAtom,
+  tourPlayingAtom,
+  tourSpeedAtom,
+  tourDirectionAtom,
+  // Preview
+  previewCountAtom,
+  previewPaddingAtom,
+  selectedKeyframeAtom,
+  // Point style
+  pointSizeAtom,
+  pointOpacityAtom,
+  pointColorAtom,
+  colorMapAtom,
+  // Camera
+  cameraPanXAtom,
+  cameraPanYAtom,
+  cameraZoomAtom,
+  // View mode
+  viewModeAtom,
+  // Legend
+  showLegendAtom,
+  legendVisibleAtom,
+  // Theme
+  themeModeAtom,
+  resolvedThemeAtom,
+  // Read-only
+  metadataAtom,
+} from './state/atoms.ts';

package/src/layout/gallery-positions.ts

@@ -0,0 +1,105 @@
+/** Gap between adjacent previews (CSS px). */
+export const GAP = 32;
+/** Maximum preview size (CSS px). */
+export const MAX_SIZE = 320;
+/**
+ * Per-edge-count ratio arrays.
+ *   k=1 (4 previews)  → [1]             all same
+ *   k=2 (8 previews)  → [1, 0.5]        corners 1, middle 0.5
+ *   k=3 (12 previews) → [1, 0.75]       corners 1, mid 0.75
+ *   k=4 (16 previews) → [1, 0.75, 0.5]  corners 1, near-corner 0.75, middle 0.5
+ */
+const RATIOS_BY_K: Record<number, readonly number[]> = {
+  1: [1],
+  2: [1, 0.5],
+  3: [1, 0.75],
+  4: [1, 0.75, 0.5],
+};
+
+const FALLBACK_RATIOS: readonly number[] = [1, 0.75, 0.5];
+
+/**
+ * Size ratio for position `j` on an edge of `k` emitted points.
+ * distFromCorner = min(j, k - j), then looked up in the per-k ratio table.
+ */
+export function sizeRatio(j: number, k: number): number {
+  const ratios = RATIOS_BY_K[k] ?? FALLBACK_RATIOS;
+  const dist = Math.min(j, k - j);
+  return ratios[Math.min(dist, ratios.length - 1)] ?? 1;
+}
+
+export type GallerySizes = {
+  /** CSS grid-template-columns value (e.g. "320px 256px 320px") */
+  gridTemplateColumns: string;
+  /** CSS grid-template-rows value */
+  gridTemplateRows: string;
+  /** Per-preview pixel size (indexed by preview slot) */
+  sizes: number[];
+  /** Largest preview size in px (for padding/selector math) */
+  previewSize: number;
+  /** Horizontal padding (px) */
+  padX: number;
+  /** Vertical padding (px) */
+  padY: number;
+};
+
+/**
+ * Compute ratio-weighted CSS grid templates and preview sizes.
+ *
+ * Track sizes are pixel values derived from the **shorter** container
+ * dimension so previews stay square and identically sized on both axes.
+ * `space-between` on the grid container distributes extra space on the
+ * longer axis to push tracks to the perimeter edges.
+ *
+ *   k=1 → "Spx Spx"
+ *   k=2 → "Spx 0.8Spx Spx"
+ *   k=3 → "Spx 0.8Spx 0.8Spx Spx"
+ *   k=4 → "Spx 0.8Spx 0.6Spx 0.8Spx Spx"
+ */
+export function computeGallerySizes(
+  containerWidth: number,
+  containerHeight: number,
+  previewCount: number,
+  scale = 1,
+): GallerySizes {
+  const k = Math.max(1, previewCount / 4);
+  const numTracks = k + 1;
+
+  // Build ratio array for the grid tracks
+  const ratios: number[] = [];
+  let ratioSum = 0;
+  for (let j = 0; j <= k; j++) {
+    const r = sizeRatio(j, k);
+    ratios.push(r);
+    ratioSum += r;
+  }
+
+  // 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 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 previewSize = baseSize;
+
+  // Per-preview sizes: each preview's size depends on its edge position.
+  // Preview i sits at edge position j = i % k, sized by sizeRatio(j, k).
+  const sizes: number[] = [];
+  for (let i = 0; i < previewCount; i++) {
+    sizes.push(baseSize * sizeRatio(i % k, k));
+  }
+
+  const padX = previewSize / 2;
+  const padY = previewSize / 2;
+
+  return {
+    gridTemplateColumns: template,
+    gridTemplateRows: template,
+    sizes,
+    previewSize,
+    padX,
+    padY,
+  };
+}

package/src/layout/selector-size.ts

@@ -0,0 +1,135 @@
+import { GAP, MAX_SIZE, sizeRatio } from './gallery-positions.ts';
+
+const MIN_SIZE = 80;
+
+/**
+ * CircularSlider draws its ring at `size * RING_RATIO` from centre.
+ * The selector diameter we return must account for this ratio so
+ * the *ring* (not the SVG bounding-box) respects the padding.
+ */
+const RING_RATIO = 0.4;
+
+/**
+ * Compute the largest selector diameter (px) whose visible ring does
+ * not overlap any preview in the gallery perimeter layout.
+ *
+ * For every preview bounding-box we compute the Euclidean distance from
+ * the container centre to the nearest point on that box.  The container
+ * edges (accounting for overlayOffsetY) are an additional constraint.
+ * The returned diameter satisfies `size * RING_RATIO + padding ≤ minDist`,
+ * i.e. `size = (minDist − padding) / RING_RATIO`, clamped to
+ * {@link MIN_SIZE}.
+ */
+export function computeSelectorSize(
+  containerWidth: number,
+  containerHeight: number,
+  previewCount: number,
+  isToolbarVisible: boolean,
+  padding: number,
+  scale = 1,
+  /** Number of radial metric tracks rendered outside the ring. */
+  metricTrackCount = 0,
+): number {
+  if (previewCount === 0 || containerWidth <= 0 || containerHeight <= 0) {
+    return Math.max(MIN_SIZE, Math.min(containerWidth, containerHeight));
+  }
+
+  const k = Math.max(1, previewCount / 4);
+  const numTracks = k + 1;
+
+  // 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.
+  const gridLeft = 16;
+  const toolbarOffset = isToolbarVisible ? 20 : 0; // toolbarHeight / 2
+  const verticalInset = 16 + toolbarOffset;
+  const gridW = containerWidth - 2 * gridLeft;
+  const gridH = containerHeight - 2 * verticalInset;
+
+  // Track sizes (same logic as computeGallerySizes)
+  const ratios: number[] = [];
+  let ratioSum = 0;
+  for (let j = 0; j <= k; j++) {
+    const r = sizeRatio(j, k);
+    ratios.push(r);
+    ratioSum += r;
+  }
+  const shortSide = Math.min(gridW, gridH);
+  const availableForCells = shortSide - (numTracks - 1) * GAP;
+  const baseSize = Math.min(MAX_SIZE, availableForCells / ratioSum) * scale;
+  const trackSizes = ratios.map((r) => baseSize * r);
+  const trackTotal = trackSizes.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 effGapX = GAP + (numTracks > 1 ? Math.max(0, freeX) / (numTracks - 1) : 0);
+  const effGapY = GAP + (numTracks > 1 ? Math.max(0, freeY) / (numTracks - 1) : 0);
+
+  // Track start positions relative to grid origin
+  const colStarts: number[] = [0];
+  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);
+  }
+
+  // Selector centre in the overlay-wrapper coordinate system
+  const cx = containerWidth / 2;
+  const cy = containerHeight / 2;
+
+  // Container edge constraint: the wrapper is shifted by toolbarOffset,
+  // so the visible bottom edge is closer to centre than the top edge.
+  let minDist = Math.min(containerWidth / 2, containerHeight / 2 - toolbarOffset);
+
+  for (let i = 0; i < previewCount; i++) {
+    // Grid cell — same edge-walk order as Gallery
+    let col: number;
+    let row: number;
+    if (i < k) {
+      row = 0;
+      col = i;
+    } else if (i < 2 * k) {
+      row = i - k;
+      col = k;
+    } else if (i < 3 * k) {
+      row = k;
+      col = 3 * k - i;
+    } else {
+      row = 4 * k - i;
+      col = 0;
+    }
+
+    const cellX = gridLeft + colStarts[col]!;
+    const cellY = verticalInset + rowStarts[row]!;
+    const cellW = trackSizes[col]!;
+    const cellH = trackSizes[row]!;
+    const size = baseSize * sizeRatio(i % k, k);
+
+    // Alignment within cell (matches Gallery flex alignment)
+    let px: number;
+    if (col === 0) px = cellX;
+    else if (col === k) px = cellX + cellW - size;
+    else px = cellX + (cellW - size) / 2;
+
+    let py: number;
+    if (row === 0) py = cellY;
+    else if (row === k) py = cellY + cellH - size;
+    else py = cellY + (cellH - size) / 2;
+
+    // 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));
+    minDist = Math.min(minDist, Math.sqrt(dx * dx + dy * dy));
+  }
+
+  // The visible ring sits at size * RING_RATIO from centre. Metric tracks
+  // extend outward from the ring; each track is ~18px (16px bar + 2px gap).
+  const metricThickness = metricTrackCount * 18;
+
+  // Outermost point = size * RING_RATIO + metricThickness, so:
+  // size * RING_RATIO + metricThickness + padding ≤ minDist
+  // size = (minDist - padding - metricThickness) / RING_RATIO
+  return Math.max(MIN_SIZE, (minDist - padding - metricThickness) / RING_RATIO);
+}

package/src/lib/color-utils.ts

@@ -0,0 +1,22 @@
+/** Check if a string is a hex color (e.g. #ff6600, #f60). */
+export const isHexColor = (s: string): boolean => /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.test(s);
+
+/** Parse a hex color string to [r, g, b] in 0-1 range. */
+export const hexToRgb = (hex: string): [number, number, number] => {
+  let h = hex.slice(1);
+  if (h.length === 3) {
+    h = h[0]! + h[0]! + h[1]! + h[1]! + h[2]! + h[2]!;
+  }
+  const n = Number.parseInt(h, 16);
+  return [(n >> 16) / 255, ((n >> 8) & 0xff) / 255, (n & 0xff) / 255];
+};
+
+/** Parse a hex color string to [r, g, b] in 0-255 range. */
+export const hexToRgb255 = (hex: string): [number, number, number] => {
+  let h = hex.slice(1);
+  if (h.length === 3) {
+    h = h[0]! + h[0]! + h[1]! + h[1]! + h[2]! + h[2]!;
+  }
+  const n = Number.parseInt(h, 16);
+  return [n >> 16, (n >> 8) & 0xff, n & 0xff];
+};

package/src/lib/gram-schmidt.ts

@@ -0,0 +1,41 @@
+/**
+ * In-place Gram-Schmidt orthonormalization for a p×2 column-major basis.
+ * Layout: [x0, x1, ..., xp-1, y0, y1, ..., yp-1]
+ *
+ * Normalizes column 0, orthogonalizes column 1 against column 0,
+ * then normalizes column 1.
+ */
+export const gramSchmidt = (basis: Float32Array, dims: number): void => {
+  // Normalize column 0
+  let norm0 = 0;
+  for (let i = 0; i < dims; i++) {
+    norm0 += basis[i]! * basis[i]!;
+  }
+  norm0 = Math.sqrt(norm0);
+  if (norm0 > 1e-12) {
+    for (let i = 0; i < dims; i++) {
+      basis[i]! /= norm0;
+    }
+  }
+
+  // Orthogonalize column 1 against column 0
+  let dot = 0;
+  for (let i = 0; i < dims; i++) {
+    dot += basis[i]! * basis[dims + i]!;
+  }
+  for (let i = 0; i < dims; i++) {
+    basis[dims + i]! -= dot * basis[i]!;
+  }
+
+  // Normalize column 1
+  let norm1 = 0;
+  for (let i = 0; i < dims; i++) {
+    norm1 += basis[dims + i]! * basis[dims + i]!;
+  }
+  norm1 = Math.sqrt(norm1);
+  if (norm1 > 1e-12) {
+    for (let i = 0; i < dims; i++) {
+      basis[dims + i]! /= norm1;
+    }
+  }
+};

package/src/lib/utils.ts

@@ -0,0 +1,4 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export const cn = (...inputs: ClassValue[]) => twMerge(clsx(inputs));

package/src/portal-container.tsx

@@ -0,0 +1,14 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * Context for overriding where Radix portals render their content.
+ * When provided, dropdown menus, tooltips, etc. portal into the given
+ * element instead of `document.body`.  This is required for Shadow DOM
+ * isolation (e.g. the anywidget/Marimo embed) so that portalled content
+ * stays inside the shadow root and inherits scoped styles.
+ */
+export const PortalContainerContext = createContext<HTMLElement | undefined>(undefined);
+
+export function usePortalContainer(): HTMLElement | undefined {
+  return useContext(PortalContainerContext);
+}