@dtour/viewer 0.1.0 → 0.2.0

package/src/radial-chart/RadialChart.tsx

@@ -1,7 +1,10 @@
 import { useCallback, useMemo, useState } from 'react';
+import { tourToVisual } from '../lib/position-remap.ts';
 import { arcPath, keyframeAngle, rectBarPath } from './arc-path.ts';
 import type { ParsedTrack } from './types.ts';
 
+const START_DEG = -135;
+
 export type RadialChartProps = {
   tracks: ParsedTrack[];
   keyframeCount: number;
@@ -11,6 +14,10 @@ export type RadialChartProps = {
   size: number;
   /** Inner radius = selector ring radius (selectorSize * 0.4). */
   innerRadius: number;
+  /** Cumulative arc-lengths for geodesic tick positioning. */
+  arcLengths?: Float32Array | null;
+  /** Slider spacing mode. Default 'equal'. */
+  spacingMode?: 'equal' | 'geodesic';
 };
 
 const TRACK_GAP = 2;
@@ -25,6 +32,8 @@ export const RadialChart = ({
   position,
   size,
   innerRadius,
+  arcLengths,
+  spacingMode = 'equal',
 }: RadialChartProps) => {
   const center = size / 2;
   const [hover, setHover] = useState<HoverInfo | null>(null);
@@ -51,8 +60,37 @@ export const RadialChart = ({
     });
   }, [tracks, innerRadius, stacked]);
 
+  // Compute angle for keyframe index, respecting spacing mode.
+  // In geodesic mode, bars sit at arc-length positions; in equal mode, uniform.
+  const getAngle = useCallback(
+    (index: number): number => {
+      if (spacingMode === 'geodesic' && arcLengths && index < arcLengths.length) {
+        return ((arcLengths[index]! * 360 + START_DEG) * Math.PI) / 180;
+      }
+      return keyframeAngle(index, keyframeCount);
+    },
+    [spacingMode, arcLengths, keyframeCount],
+  );
+
+  // Angular span for a segment from keyframe i to i+1
+  const getSegmentSpan = useCallback(
+    (index: number): number => {
+      if (spacingMode === 'geodesic' && arcLengths && arcLengths.length > 1) {
+        const n = arcLengths.length - 1;
+        const start = arcLengths[index]!;
+        const end = arcLengths[(index + 1) % (n + 1)]!;
+        const span = end > start ? end - start : 1 - start + end;
+        return span * 2 * Math.PI;
+      }
+      return (2 * Math.PI) / keyframeCount;
+    },
+    [spacingMode, arcLengths, keyframeCount],
+  );
+
   // Flanking keyframes based on current position
-  const fractionalIndex = position * keyframeCount;
+  const visualPos =
+    spacingMode === 'equal' && arcLengths ? tourToVisual(position, arcLengths) : position;
+  const fractionalIndex = visualPos * keyframeCount;
   const leftKf = Math.floor(fractionalIndex) % keyframeCount;
   const rightKf = (leftKf + 1) % keyframeCount;
 
@@ -85,7 +123,7 @@ export const RadialChart = ({
     const barWidthPx = (tracks[0]?.barWidth as number) ?? 0;
 
     for (let kfIdx = 0; kfIdx < keyframeCount; kfIdx++) {
-      const centerAngle = keyframeAngle(kfIdx, keyframeCount);
+      const centerAngle = getAngle(kfIdx);
 
       let stackBase = baseR;
       for (let trackIdx = 0; trackIdx < tracks.length; trackIdx++) {
@@ -115,7 +153,7 @@ export const RadialChart = ({
       }
     }
     return bars;
-  }, [stacked, tracks, keyframeCount, baseR, center]);
+  }, [stacked, tracks, keyframeCount, baseR, center, getAngle]);
 
   return (
     <div className="relative" style={{ width: size, height: size }}>
@@ -140,9 +178,10 @@ export const RadialChart = ({
                     {track.normalizedValues.map((normVal, kfIdx) => {
                       if (kfIdx >= keyframeCount) return null;
 
-                      const centerAngle = keyframeAngle(kfIdx, keyframeCount);
-                      const angleStart = centerAngle - segmentAngle / 2 + BAR_PAD_RAD;
-                      const angleEnd = centerAngle + segmentAngle / 2 - BAR_PAD_RAD;
+                      const centerAngle = getAngle(kfIdx);
+                      const halfSpan = getSegmentSpan(kfIdx) / 2;
+                      const angleStart = centerAngle - halfSpan + BAR_PAD_RAD;
+                      const angleEnd = centerAngle + halfSpan - BAR_PAD_RAD;
 
                       const barOuter = rInner + normVal * track.height;
                       const rawValue = track.rawValues[kfIdx] as number;

package/src/spec.ts

@@ -22,11 +22,149 @@ export const dtourSpecSchema = z.object({
   cameraZoom: z.number().positive().optional(),
   viewMode: z.enum(['guided', 'manual', 'grand']).optional(),
   showLegend: z.boolean().optional(),
+  showAxes: z.boolean().optional(),
+  showFrameNumbers: z.boolean().optional(),
+  showFrameLoadings: z.boolean().optional(),
+  showTourDescription: z.boolean().optional(),
+  sliderSpacing: z.enum(['equal', 'geodesic']).optional(),
   themeMode: z.enum(['light', 'dark', 'system']).optional(),
 });
 
 export type DtourSpec = z.infer<typeof dtourSpecSchema>;
 
+/** Per-frame top-2 feature correlations: [featureName, pearsonR] pairs. */
+export type FrameLoading = [string, number];
+
+/** Parsed contents of the Parquet "dtour" key_value_metadata entry. */
+export type EmbeddedConfig = {
+  spec: DtourSpec;
+  colorMap?: Record<string, string>;
+  tour?: {
+    nDims: number;
+    nViews: number;
+    views: Float32Array[];
+    tourMode?: 'signed' | 'discriminative' | null;
+    frameLoadings?: FrameLoading[][];
+    /** Human-readable description of the tour (shown in description sub-bar). */
+    tourDescription?: string;
+    /** Template for per-frame tooltip, with {dim1}, {dim2}, {relation} placeholders. */
+    tourFrameDescription?: string;
+  };
+};
+
+const SPEC_SHAPE_KEYS = Object.keys(dtourSpecSchema.shape) as (keyof DtourSpec)[];
+
+/**
+ * Parse the raw JSON "dtour" value from Parquet key_value_metadata.
+ * Returns null if the string is falsy or unparseable.
+ * Invalid spec fields are silently dropped.
+ */
+export function parseEmbeddedConfig(raw: string | undefined): EmbeddedConfig | null {
+  if (!raw) return null;
+
+  let obj: Record<string, unknown>;
+  try {
+    obj = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof obj !== 'object' || obj === null) return null;
+
+  // Validate each spec field individually — invalid fields are dropped
+  // without affecting valid ones.
+  const spec: Record<string, unknown> = {};
+  for (const key of SPEC_SHAPE_KEYS) {
+    if (!(key in obj)) continue;
+    const fieldSchema = dtourSpecSchema.shape[key];
+    const result = fieldSchema.safeParse(obj[key]);
+    if (result.success) spec[key] = result.data;
+  }
+
+  // Extract colorMap (label → hex string)
+  let colorMap: Record<string, string> | undefined;
+  if (obj.colorMap && typeof obj.colorMap === 'object' && !Array.isArray(obj.colorMap)) {
+    const cm = obj.colorMap as Record<string, unknown>;
+    const valid: Record<string, string> = {};
+    let hasEntries = false;
+    for (const [k, v] of Object.entries(cm)) {
+      if (typeof v === 'string') {
+        valid[k] = v;
+        hasEntries = true;
+      }
+    }
+    if (hasEntries) colorMap = valid;
+  }
+
+  // Extract tour views (base64 float32 column-major)
+  let tour: EmbeddedConfig['tour'] | undefined;
+  if (obj.tour && typeof obj.tour === 'object') {
+    const t = obj.tour as Record<string, unknown>;
+    const nDims = typeof t.nDims === 'number' ? t.nDims : 0;
+    const nViews = typeof t.nViews === 'number' ? t.nViews : 0;
+    const viewsB64 = typeof t.views === 'string' ? t.views : '';
+    if (nDims >= 2 && nViews >= 2 && viewsB64) {
+      try {
+        const binary = atob(viewsB64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+          bytes[i] = binary.charCodeAt(i);
+        }
+        const floats = new Float32Array(bytes.buffer);
+        const stride = nDims * 2;
+        if (floats.length === nViews * stride) {
+          const views: Float32Array[] = [];
+          for (let v = 0; v < nViews; v++) {
+            views.push(floats.slice(v * stride, (v + 1) * stride));
+          }
+          tour = { nDims, nViews, views };
+
+          // Parse tourMode
+          if (t.tourMode === 'signed' || t.tourMode === 'discriminative') {
+            tour.tourMode = t.tourMode;
+          }
+
+          // Parse tourDescription and tourFrameDescription
+          if (typeof t.tourDescription === 'string') {
+            tour.tourDescription = t.tourDescription;
+          }
+          if (typeof t.tourFrameDescription === 'string') {
+            tour.tourFrameDescription = t.tourFrameDescription;
+          }
+
+          // Parse frameLoadings: array of [[name, coeff], [name, coeff]] per view
+          if (Array.isArray(t.frameLoadings)) {
+            const fl: FrameLoading[][] = [];
+            let valid = true;
+            for (const frame of t.frameLoadings as unknown[][]) {
+              if (!Array.isArray(frame)) {
+                valid = false;
+                break;
+              }
+              const pairs: FrameLoading[] = [];
+              for (const pair of frame) {
+                if (
+                  Array.isArray(pair) &&
+                  pair.length === 2 &&
+                  typeof pair[0] === 'string' &&
+                  typeof pair[1] === 'number'
+                ) {
+                  pairs.push([pair[0] as string, pair[1] as number]);
+                }
+              }
+              fl.push(pairs);
+            }
+            if (valid && fl.length > 0) tour.frameLoadings = fl;
+          }
+        }
+      } catch {
+        // Invalid base64 — skip tour
+      }
+    }
+  }
+
+  return { spec: spec as DtourSpec, colorMap, tour };
+}
+
 export const DTOUR_DEFAULTS: Required<DtourSpec> = {
   tourBy: 'dimensions',
   tourPosition: 0,
@@ -44,5 +182,10 @@ export const DTOUR_DEFAULTS: Required<DtourSpec> = {
   cameraZoom: 1 / 1.5,
   viewMode: 'guided',
   showLegend: true,
+  showAxes: false,
+  showFrameNumbers: false,
+  showFrameLoadings: true,
+  showTourDescription: false,
+  sliderSpacing: 'equal',
   themeMode: 'dark',
 };

package/src/state/atoms.ts

@@ -1,5 +1,6 @@
 import type { Metadata } from '@dtour/scatter';
 import { atom } from 'jotai';
+import type { EmbeddedConfig, FrameLoading } from '../spec.ts';
 
 // ---------------------------------------------------------------------------
 // Tour state — controls position and playback along the tour path
@@ -13,6 +14,12 @@ export const tourPlayingAtom = atom(false);
 export const tourSpeedAtom = atom(1);
 export const tourDirectionAtom = atom<1 | -1>(1);
 
+/** Slider spacing mode: 'equal' = uniform tick spacing, 'geodesic' = arc-length proportional. */
+export const sliderSpacingAtom = atom<'equal' | 'geodesic'>('equal');
+
+/** Cumulative arc-lengths for the current tour bases. null when no tour is loaded. */
+export const arcLengthsAtom = atom<Float32Array | null>(null);
+
 // ---------------------------------------------------------------------------
 // View state — controls preview layout and keyframe selection
 // ---------------------------------------------------------------------------
@@ -22,6 +29,34 @@ export const previewScaleAtom = atom<1 | 0.75 | 0.5>(1);
 export const previewPaddingAtom = atom(12);
 export const selectedKeyframeAtom = atom<number | null>(null);
 
+/** Which gallery preview is currently hovered (index), or null. */
+export const hoveredKeyframeAtom = atom<number | null>(null);
+
+/** Preview center positions relative to the container center, plus preview size. */
+export const previewCentersAtom = atom<{ x: number; y: number; size: number }[]>([]);
+
+/** Derived: nearest keyframe to the current tour position. */
+export const currentKeyframeAtom = atom((get) => {
+  const position = get(tourPositionAtom);
+  const arcLengths = get(arcLengthsAtom);
+  const previewCount = get(previewCountAtom);
+  if (!arcLengths || arcLengths.length < 2) {
+    return Math.round(position * previewCount) % previewCount;
+  }
+  const n = arcLengths.length - 1;
+  let best = 0;
+  let bestDist = 1;
+  for (let i = 0; i < n; i++) {
+    let dist = Math.abs(position - arcLengths[i]!);
+    dist = Math.min(dist, 1 - dist);
+    if (dist < bestDist) {
+      bestDist = dist;
+      best = i;
+    }
+  }
+  return best;
+});
+
 // ---------------------------------------------------------------------------
 // Point style — visual appearance of scatter points
 // ---------------------------------------------------------------------------
@@ -67,6 +102,9 @@ export const guidedSuspendedAtom = atom(false);
 /** Target mode after grand ease-out completes. null = not exiting. */
 export const grandExitTargetAtom = atom<'guided' | 'manual' | null>(null);
 
+/** True when the 3D camera is rotated away from front-on (manual mode only). */
+export const is3dRotatedAtom = atom(false);
+
 /**
  * Tracks the currently-displayed projection basis (p×2 column-major).
  * Updated by tour interpolation, manual axis dragging, and zen animation.
@@ -99,6 +137,9 @@ export const canvasSizeAtom = atom({ width: 0, height: 0 });
 
 export const metadataAtom = atom<Metadata | null>(null);
 
+/** Parsed embedded config from Parquet key_value_metadata. Reset on each data load. */
+export const embeddedConfigAtom = atom<EmbeddedConfig | null>(null);
+
 // ---------------------------------------------------------------------------
 // Column visibility — which numeric dimensions participate in the tour
 // ---------------------------------------------------------------------------
@@ -129,6 +170,30 @@ export const activeIndicesAtom = atom<number[]>((get) => {
 /** User preference for showing the legend panel. */
 export const showLegendAtom = atom(true);
 
+/** User preference for showing axis biplot in guided mode. */
+export const showAxesAtom = atom(false);
+
+/** User preference for showing frame numbers on preview thumbnails. */
+export const showFrameNumbersAtom = atom(false);
+
+/** User preference for showing feature loading pills on preview thumbnails. */
+export const showFrameLoadingsAtom = atom(true);
+
+/** User preference for showing the tour description sub-bar. */
+export const showTourDescriptionAtom = atom(false);
+
+/** Per-frame top-2 feature correlations from embedded tour config. */
+export const frameLoadingsAtom = atom<FrameLoading[][] | null>(null);
+
+/** Tour mode from embedded config: null (vanilla), "signed", or "discriminative". */
+export const tourModeAtom = atom<'signed' | 'discriminative' | null>(null);
+
+/** Tour description string from embedded config (shown in description sub-bar). */
+export const tourDescriptionAtom = atom<string | null>(null);
+
+/** Per-frame tooltip template from embedded config, with {dim1}, {dim2}, {relation} placeholders. */
+export const tourFrameDescriptionAtom = atom<string | null>(null);
+
 /**
  * Derived: legend is visible only when showLegend is true, metadata is loaded,
  * AND points are colored by a known data column (numeric or categorical).

package/src/state/spec-sync.ts

@@ -12,7 +12,12 @@ import {
   previewCountAtom,
   previewPaddingAtom,
   previewScaleAtom,
+  showAxesAtom,
+  showFrameLoadingsAtom,
+  showFrameNumbersAtom,
   showLegendAtom,
+  showTourDescriptionAtom,
+  sliderSpacingAtom,
   themeModeAtom,
   tourByAtom,
   tourDirectionAtom,
@@ -61,6 +66,11 @@ const SPEC_ATOM_MAP = {
   cameraZoom: entry(cameraZoomAtom),
   viewMode: entry(viewModeAtom),
   showLegend: entry(showLegendAtom),
+  showAxes: entry(showAxesAtom),
+  showFrameNumbers: entry(showFrameNumbersAtom),
+  showFrameLoadings: entry(showFrameLoadingsAtom),
+  showTourDescription: entry(showTourDescriptionAtom),
+  sliderSpacing: entry(sliderSpacingAtom),
   themeMode: entry(themeModeAtom),
 } as const;
 
@@ -105,6 +115,11 @@ export function initStoreFromSpec(
   spec: DtourSpec | undefined,
 ): void {
   if (!spec) return;
+  applySpecToStore(store, spec);
+}
+
+/** Write spec values into the jotai store. Skips undefined fields. */
+export function applySpecToStore(store: ReturnType<typeof useStore>, spec: DtourSpec): void {
   for (const key of SPEC_KEYS) {
     const value = spec[key];
     if (value !== undefined) {

package/src/styles.css

@@ -3,27 +3,27 @@
 @import "tw-animate-css";
 
 @theme {
-  --color-dtour-bg: #000000;
-  --color-dtour-surface: #222222;
-  --color-dtour-border: #333333;
-  --color-dtour-text: #bbbbbb;
-  --color-dtour-text-muted: #888888;
-  --color-dtour-accent: #4080e8;
-  --color-dtour-accent-hover: #5090f0;
-  --color-dtour-highlight: #ffffff;
+  --color-dtour-bg: oklch(0% 0 0);
+  --color-dtour-surface: oklch(18.66% 0 0);
+  --color-dtour-border: oklch(27.06% 0 0);
+  --color-dtour-text: oklch(79.91% 0 0);
+  --color-dtour-text-muted: oklch(61.66% 0 0);
+  --color-dtour-accent: oklch(61.13% 0.1707 259.68);
+  --color-dtour-accent-hover: oklch(65.65% 0.1581 258.37);
+  --color-dtour-highlight: oklch(100% 0 0);
 }
 
 /* --- Light theme overrides --- */
 
 :where(.dtour-light) {
-  --color-dtour-bg: #ffffff;
-  --color-dtour-surface: #f0f0f0;
-  --color-dtour-border: #d0d0d0;
-  --color-dtour-text: #333333;
-  --color-dtour-text-muted: #777777;
-  --color-dtour-accent: #2060c0;
-  --color-dtour-accent-hover: #1850a8;
-  --color-dtour-highlight: #000000;
+  --color-dtour-bg: oklch(100% 0 0);
+  --color-dtour-surface: oklch(95.51% 0 0);
+  --color-dtour-border: oklch(85.76% 0 0);
+  --color-dtour-text: oklch(32.11% 0 0);
+  --color-dtour-text-muted: oklch(56.93% 0 0);
+  --color-dtour-accent: oklch(50.48% 0.164 258.95);
+  --color-dtour-accent-hover: oklch(44.94% 0.1531 259.62);
+  --color-dtour-highlight: oklch(0% 0 0);
 }
 
 /* --- Animation easing utility for tw-animate-css --- */