@ltm-blueverse/alpha-semantic-hub 0.7.0

package/explorer/src/workspaces/GraphWorkspace/SigmaSceneAdapter.tsx

@@ -0,0 +1,55 @@
+import { forwardRef, useImperativeHandle, useRef } from "react";
+
+import { GraphCanvas, type GraphCanvasHandle } from "./GraphCanvas";
+import type { GraphSceneAdapter, GraphSceneHandle, GraphSceneProps, GraphSceneRuntime } from "./scene";
+
+export const SigmaSceneAdapter = forwardRef<GraphSceneHandle, GraphSceneProps>(
+  function SigmaSceneAdapter(
+    {
+      onNodeSelect,
+      onEdgeSelect,
+      onInteractionStateChange,
+      onCameraStateChange,
+      onDiagnosticsChange,
+      onAnalyticsChange,
+      onRuntimeChange,
+      onLayoutRunningChange,
+      ...sceneProps
+    },
+    ref,
+  ) {
+    const canvasRef = useRef<GraphCanvasHandle>(null);
+    const runtimeRef = useRef<GraphSceneRuntime | null>(null);
+
+    useImperativeHandle(ref, () => ({
+      fitView: () => canvasRef.current?.fitView(),
+      focusNode: (nodeId: string) => canvasRef.current?.focusNode(nodeId),
+      zoomIn: () => canvasRef.current?.zoomIn(),
+      zoomOut: () => canvasRef.current?.zoomOut(),
+      getRuntime: () => runtimeRef.current,
+      setLayoutRunning: onLayoutRunningChange
+        ? (running: boolean) => {
+            onLayoutRunningChange(running);
+          }
+        : undefined,
+    }), [onLayoutRunningChange]);
+
+    return (
+      <GraphCanvas
+        ref={canvasRef}
+        onNodeClick={onNodeSelect ?? (() => {})}
+        onEdgeClick={onEdgeSelect}
+        onInteractionStateChange={onInteractionStateChange}
+        onCameraStateChange={onCameraStateChange}
+        onDiagnosticsChange={onDiagnosticsChange}
+        onAnalyticsChange={onAnalyticsChange}
+        onSceneRuntimeChange={(runtime) => {
+          runtimeRef.current = runtime;
+          onRuntimeChange?.(runtime);
+        }}
+        onLayoutRunningChange={onLayoutRunningChange}
+        {...sceneProps}
+      />
+    );
+  },
+) as GraphSceneAdapter;

package/explorer/src/workspaces/GraphWorkspace/TimelinePanel.tsx

@@ -0,0 +1,193 @@
+import { useEffect, useRef, useState, useCallback, useMemo } from "react";
+import { DataSet } from "vis-data";
+import { Timeline } from "vis-timeline";
+import type { TimelineOptions } from "vis-timeline";
+import "vis-timeline/styles/vis-timeline-graph2d.css";
+import { GRAPH_THEME } from "./graphTheme";
+import { DEFAULT_MIN_DATE, resolvePlayStepMs, resolveScrubberBounds } from "./temporalScrubberBounds";
+
+export interface TimelinePanelProps {
+  onTimeChange: (time: Date) => void;
+  minDate?: string;
+  maxDate?: string;
+}
+
+const PLAYHEAD_ID = "playhead";
+const PLAY_INTERVAL_MS = 500;
+const ONE_DAY_MS = 1000 * 60 * 60 * 24;
+
+const VIS_OVERRIDE_CSS = `
+  .sem-timeline-wrap .vis-timeline { border: none !important; background: transparent !important; overflow: visible !important; }
+  .sem-timeline-wrap .vis-panel.vis-background, .sem-timeline-wrap .vis-panel.vis-center { background: transparent !important; }
+  .sem-timeline-wrap .vis-panel { border-color: ${GRAPH_THEME.ui.timeline.border} !important; }
+  .sem-timeline-wrap .vis-time-axis .vis-text {
+    color: ${GRAPH_THEME.ui.timeline.text} !important;
+    font-size: 11px !important;
+    font-family: 'JetBrains Mono', 'Fira Code', monospace !important;
+    padding-top: 3px !important;
+  }
+  .sem-timeline-wrap .vis-time-axis .vis-text.vis-major {
+    color: ${GRAPH_THEME.ui.timeline.textStrong} !important;
+    font-weight: 700 !important;
+    font-size: 12px !important;
+  }
+  .sem-timeline-wrap .vis-time-axis .vis-grid.vis-minor { border-color: ${GRAPH_THEME.ui.timeline.gridMinor} !important; }
+  .sem-timeline-wrap .vis-time-axis .vis-grid.vis-major { border-color: ${GRAPH_THEME.ui.timeline.gridMajor} !important; }
+  .sem-timeline-wrap .vis-custom-time.${PLAYHEAD_ID} {
+    background: ${GRAPH_THEME.ui.timeline.playheadSoft} !important;
+    width: 2px !important;
+    cursor: ew-resize !important;
+    z-index: 5 !important;
+  }
+  .sem-timeline-wrap .vis-custom-time.${PLAYHEAD_ID} > .vis-custom-time-marker {
+    background: ${GRAPH_THEME.ui.timeline.playhead} !important;
+    color: ${GRAPH_THEME.ui.text.inverse} !important;
+    font-size: 10px !important;
+    font-weight: 700 !important;
+    border-radius: 3px !important;
+    padding: 1px 5px !important;
+    white-space: nowrap !important;
+    box-shadow: 0 0 8px rgba(98, 226, 205, 0.45) !important;
+  }
+  .sem-timeline-wrap .vis-current-time { display: none !important; }
+  .sem-timeline-wrap .vis-panel.vis-left { display: none !important; }
+`;
+
+function formatPlayheadLabel(value: Date): string {
+  return `${value.getFullYear()}/${String(value.getMonth() + 1).padStart(2, "0")}`;
+}
+
+export function TimelinePanel({ onTimeChange, minDate, maxDate }: TimelinePanelProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const timelineRef = useRef<Timeline | null>(null);
+  const playheadRef = useRef<Date>(DEFAULT_MIN_DATE);
+  const playIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [displayDate, setDisplayDate] = useState(formatPlayheadLabel(DEFAULT_MIN_DATE));
+
+  // Captured once per mount so re-renders keep the same reference and do not
+  // retrigger the timeline effect below.
+  const now = useMemo(() => new Date(), []);
+  const { minBound, maxBound, defaultTime } = useMemo(
+    () => resolveScrubberBounds({ minDate, maxDate, now }),
+    [maxDate, minDate, now],
+  );
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const timeline = timelineRef.current;
+    if (!timeline) {
+      const items = new DataSet([]);
+      const options: TimelineOptions = {
+        height: "100%",
+        min: minBound,
+        max: maxBound,
+        start: minBound,
+        end: maxBound,
+        showCurrentTime: false,
+        zoomable: true,
+        moveable: true,
+        zoomMin: ONE_DAY_MS,
+        zoomMax: 1000 * 60 * 60 * 24 * 365 * 80,
+        showMajorLabels: true,
+        showMinorLabels: true,
+        orientation: { axis: "bottom" },
+        margin: { item: 0, axis: 0 },
+        selectable: false,
+        stack: false,
+      } as TimelineOptions;
+
+      const nextTimeline = new Timeline(containerRef.current, items, options);
+      timelineRef.current = nextTimeline;
+      playheadRef.current = defaultTime;
+      nextTimeline.addCustomTime(defaultTime, PLAYHEAD_ID);
+      nextTimeline.on("timechange", (props: { id: string; time: Date }) => {
+        if (props.id !== PLAYHEAD_ID) return;
+        playheadRef.current = props.time;
+        nextTimeline.setCustomTime(props.time, PLAYHEAD_ID);
+        onTimeChange(props.time);
+        setDisplayDate(formatPlayheadLabel(props.time));
+      });
+      onTimeChange(defaultTime);
+      setDisplayDate(formatPlayheadLabel(defaultTime));
+      return () => {
+        nextTimeline.destroy();
+        timelineRef.current = null;
+      };
+    }
+
+    timeline.setOptions({ min: minBound, max: maxBound, start: minBound, end: maxBound });
+    playheadRef.current = defaultTime;
+    timeline.setCustomTime(defaultTime, PLAYHEAD_ID);
+    onTimeChange(defaultTime);
+    setDisplayDate(formatPlayheadLabel(defaultTime));
+  }, [defaultTime, maxBound, minBound, onTimeChange]);
+
+  const startPlay = useCallback(() => {
+    if (playIntervalRef.current) return;
+    playIntervalRef.current = setInterval(() => {
+      const timeline = timelineRef.current;
+      if (!timeline) return;
+      const next = new Date(playheadRef.current.getTime() + resolvePlayStepMs(minBound, maxBound));
+      if (next >= maxBound) {
+        next.setTime(minBound.getTime());
+      }
+      playheadRef.current = next;
+      timeline.setCustomTime(next, PLAYHEAD_ID);
+      onTimeChange(next);
+      setDisplayDate(formatPlayheadLabel(next));
+    }, PLAY_INTERVAL_MS);
+  }, [maxBound, minBound, onTimeChange]);
+
+  const stopPlay = useCallback(() => {
+    if (playIntervalRef.current) {
+      clearInterval(playIntervalRef.current);
+      playIntervalRef.current = null;
+    }
+  }, []);
+
+  const togglePlay = useCallback(() => {
+    setIsPlaying((previous) => {
+      if (previous) {
+        stopPlay();
+        return false;
+      }
+      startPlay();
+      return true;
+    });
+  }, [startPlay, stopPlay]);
+
+  useEffect(() => () => stopPlay(), [stopPlay]);
+
+  return (
+    <div style={{ position: "relative", width: "100%", height: "90px", borderTop: `1px solid ${GRAPH_THEME.ui.timeline.border}`, background: GRAPH_THEME.ui.timeline.background, backdropFilter: "blur(16px)", WebkitBackdropFilter: "blur(16px)", display: "flex", alignItems: "stretch", flexShrink: 0 }}>
+      <style>{VIS_OVERRIDE_CSS}</style>
+      <div style={{ display: "flex", flexDirection: "column", alignItems: "center", justifyContent: "center", gap: 4, padding: "0 16px", borderRight: `1px solid ${GRAPH_THEME.ui.timeline.border}`, minWidth: 80, flexShrink: 0 }}>
+        <button
+          id="temporal-play-btn"
+          onClick={togglePlay}
+          title={isPlaying ? "Pause Evolution" : "Play Evolution"}
+          style={{ width: 34, height: 34, borderRadius: "50%", border: `1.5px solid ${isPlaying ? GRAPH_THEME.ui.control.activeBorder : GRAPH_THEME.ui.control.defaultBorder}`, background: isPlaying ? GRAPH_THEME.ui.timeline.playheadSoft : GRAPH_THEME.ui.control.defaultBg, color: GRAPH_THEME.ui.timeline.playhead, cursor: "pointer", display: "flex", alignItems: "center", justifyContent: "center", transition: "all 0.2s", boxShadow: isPlaying ? "0 0 10px rgba(98, 226, 205, 0.32)" : "none" }}
+        >
+          {isPlaying ? (
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor"><rect x="6" y="4" width="4" height="16" /><rect x="14" y="4" width="4" height="16" /></svg>
+          ) : (
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor"><polygon points="5,3 19,12 5,21" /></svg>
+          )}
+        </button>
+        <span style={{ fontSize: 10, color: isPlaying ? GRAPH_THEME.ui.timeline.playhead : GRAPH_THEME.ui.timeline.text, fontFamily: "monospace", letterSpacing: "0.04em", transition: "color 0.2s" }}>
+          {displayDate}
+        </span>
+      </div>
+
+      <div style={{ position: "absolute", top: 5, left: 100, fontSize: 10, fontWeight: 600, letterSpacing: "0.1em", color: GRAPH_THEME.ui.text.subtle, textTransform: "uppercase", pointerEvents: "none", zIndex: 2 }}>
+        Temporal Scrubber · {minBound.getFullYear()}-{maxBound.getFullYear()}
+      </div>
+
+      <div className="sem-timeline-wrap" style={{ flex: 1, overflow: "hidden", position: "relative" }}>
+        <div ref={containerRef} style={{ width: "100%", height: "100%", position: "relative" }} />
+      </div>
+    </div>
+  );
+}

package/explorer/src/workspaces/GraphWorkspace/behaviors/clickSelectionBehavior.ts

@@ -0,0 +1,29 @@
+import type { GraphBehavior } from "./types";
+
+export const clickSelectionBehavior: GraphBehavior = {
+  id: "click-selection",
+  attach: () => {},
+  detach: () => {},
+  onNodeClick: (context, nodeId) => {
+    context.setHoveredNodeId(nodeId);
+    context.onEdgeSelectionChange("");
+    if (context.getInteractionState().selectedNodeId === nodeId) {
+      context.onNodeSelectionChange("");
+    } else {
+      context.onNodeSelectionChange(nodeId);
+    }
+  },
+  onEdgeClick: (context, edgeId) => {
+    context.setHoveredNodeId(null);
+    if (context.getInteractionState().selectedEdgeId === edgeId) {
+      context.onEdgeSelectionChange("");
+    } else {
+      context.onEdgeSelectionChange(edgeId);
+    }
+  },
+  onStageClick: (context) => {
+    context.setHoveredNodeId(null);
+    context.onEdgeSelectionChange("");
+    context.onNodeSelectionChange("");
+  },
+};

package/explorer/src/workspaces/GraphWorkspace/behaviors/fitViewBehavior.ts

@@ -0,0 +1,15 @@
+import type { GraphBehavior } from "./types";
+
+export const fitViewBehavior: GraphBehavior = {
+  id: "fit-view",
+  attach: () => {},
+  detach: () => {},
+  performAction: (context, action) => {
+    if (action.type !== "fitView") {
+      return false;
+    }
+
+    context.fitCurrentView();
+    return true;
+  },
+};

package/explorer/src/workspaces/GraphWorkspace/behaviors/focusCameraBehavior.ts

@@ -0,0 +1,25 @@
+import type { GraphBehavior } from "./types";
+
+export const focusCameraBehavior: GraphBehavior = {
+  id: "focus-camera",
+  attach: () => {},
+  detach: () => {},
+  performAction: (context, action) => {
+    if (action.type === "focusNode") {
+      context.focusNodeInView(action.nodeId);
+      return true;
+    }
+
+    if (action.type === "centerSelection") {
+      context.centerSelectionInView(action.nodeId);
+      return true;
+    }
+
+    if (action.type === "centerGroupedSelection") {
+      context.centerGroupedSelectionInView(action.nodeId);
+      return true;
+    }
+
+    return false;
+  },
+};

package/explorer/src/workspaces/GraphWorkspace/behaviors/hoverActivationBehavior.ts

@@ -0,0 +1,15 @@
+import type { GraphBehavior } from "./types";
+
+export const hoverActivationBehavior: GraphBehavior = {
+  id: "hover-activation",
+  attach: () => {},
+  detach: () => {},
+  onNodeEnter: (context, nodeId) => {
+    context.setHoveredNodeId(nodeId);
+  },
+  onNodeLeave: (context, nodeId) => {
+    if (context.getInteractionState().hoveredNodeId === nodeId) {
+      context.setHoveredNodeId(null);
+    }
+  },
+};

package/explorer/src/workspaces/GraphWorkspace/behaviors/pathHighlightBehavior.ts

@@ -0,0 +1,52 @@
+import type { GraphBehavior } from "./types";
+
+const SWEEP_TICKS = 6;
+const SWEEP_INTERVAL_MS = 60;
+
+export function createPathHighlightBehavior(): GraphBehavior {
+  let lastPathSignature = "";
+  let sweepTimer: ReturnType<typeof setTimeout> | null = null;
+  let sweepGeneration = 0;
+
+  function cancelSweep() {
+    sweepGeneration++;
+    if (sweepTimer !== null) {
+      clearTimeout(sweepTimer);
+      sweepTimer = null;
+    }
+  }
+
+  function scheduleSweep(sigma: { refresh: () => void }, tick: number, gen: number) {
+    if (tick >= SWEEP_TICKS) return;
+    sweepTimer = setTimeout(() => {
+      if (gen !== sweepGeneration) return;
+      sigma.refresh();
+      scheduleSweep(sigma, tick + 1, gen);
+    }, SWEEP_INTERVAL_MS);
+  }
+
+  return {
+    id: "path-highlight",
+    attach: () => {},
+    detach: (context) => {
+      cancelSweep();
+      lastPathSignature = "";
+      context.sigma.refresh();
+    },
+    onStateChange: (context, interactionState) => {
+      const nextPathSignature = interactionState.activePath.join("::");
+      if (nextPathSignature === lastPathSignature) {
+        return;
+      }
+
+      lastPathSignature = nextPathSignature;
+      cancelSweep();
+      context.sigma.refresh();
+
+      // Animate intermediate nodes lighting up sequentially
+      if (interactionState.activePath.length > 2) {
+        scheduleSweep(context.sigma, 0, sweepGeneration);
+      }
+    },
+  };
+}

package/explorer/src/workspaces/GraphWorkspace/behaviors/searchFocusBehavior.ts

@@ -0,0 +1,36 @@
+import type { GraphBehavior } from "./types";
+
+export function createSearchFocusBehavior(): GraphBehavior {
+  let lastSelectedNodeId = "";
+  let lastViewMode = "";
+
+  return {
+    id: "search-focus",
+    attach: () => {},
+    detach: () => {
+      lastSelectedNodeId = "";
+      lastViewMode = "";
+    },
+    onStateChange: (context, interactionState) => {
+      const nextSelectedNodeId = interactionState.selectedNodeId;
+      const nextViewMode = interactionState.viewMode;
+      if (nextViewMode !== lastViewMode) {
+        lastViewMode = nextViewMode;
+        lastSelectedNodeId = nextSelectedNodeId;
+        return;
+      }
+      if (!nextSelectedNodeId || nextSelectedNodeId === lastSelectedNodeId) {
+        lastSelectedNodeId = nextSelectedNodeId;
+        lastViewMode = nextViewMode;
+        return;
+      }
+
+      lastSelectedNodeId = nextSelectedNodeId;
+      lastViewMode = nextViewMode;
+      context.dispatchAction({
+        type: nextViewMode === "grouped" ? "centerGroupedSelection" : "centerSelection",
+        nodeId: nextSelectedNodeId,
+      });
+    },
+  };
+}

package/explorer/src/workspaces/GraphWorkspace/behaviors/types.ts

@@ -0,0 +1,41 @@
+import type Graph from "graphology";
+import type Sigma from "sigma";
+
+import { graph, type EdgeAttributes, type NodeAttributes } from "../../../store/graphStore";
+import type { GraphCameraState, GraphInteractionState } from "../types";
+
+export type GraphBehaviorActionRequest =
+  | { type: "fitView" }
+  | { type: "focusNode"; nodeId: string }
+  | { type: "centerSelection"; nodeId: string }
+  | { type: "centerGroupedSelection"; nodeId: string };
+
+export interface GraphBehaviorContext {
+  sigma: Sigma;
+  graph: typeof graph | Graph<NodeAttributes, EdgeAttributes>;
+  displayGraph: typeof graph | Graph<NodeAttributes, EdgeAttributes>;
+  getInteractionState: () => GraphInteractionState;
+  setHoveredNodeId: (nodeId: string | null) => void;
+  onNodeSelectionChange: (nodeId: string) => void;
+  onEdgeSelectionChange: (edgeId: string) => void;
+  focusNodeInView: (nodeId: string) => void;
+  centerSelectionInView: (nodeId: string) => void;
+  centerGroupedSelectionInView: (nodeId: string) => void;
+  fitCurrentView: () => void;
+  dispatchAction: (action: GraphBehaviorActionRequest) => void;
+}
+
+export interface GraphBehavior {
+  id: string;
+  attach: (context: GraphBehaviorContext) => void;
+  detach: (context: GraphBehaviorContext) => void;
+  onNodeEnter?: (context: GraphBehaviorContext, nodeId: string) => void;
+  onNodeLeave?: (context: GraphBehaviorContext, nodeId: string) => void;
+  onNodeClick?: (context: GraphBehaviorContext, nodeId: string) => void;
+  onEdgeClick?: (context: GraphBehaviorContext, edgeId: string) => void;
+  onStageClick?: (context: GraphBehaviorContext) => void;
+  onCameraChange?: (context: GraphBehaviorContext, cameraState: GraphCameraState) => void;
+  onStateChange?: (context: GraphBehaviorContext, interactionState: GraphInteractionState) => void;
+  apply?: (context: GraphBehaviorContext, interactionState: GraphInteractionState) => void;
+  performAction?: (context: GraphBehaviorContext, action: GraphBehaviorActionRequest) => boolean;
+}

package/explorer/src/workspaces/GraphWorkspace/behaviors/viewModeSwitchBehavior.ts

@@ -0,0 +1,29 @@
+import type { GraphBehavior } from "./types";
+import type { GraphViewMode } from "../types";
+
+export function createViewModeSwitchBehavior(): GraphBehavior {
+  let lastViewMode: GraphViewMode | null = null;
+
+  return {
+    id: "view-mode-switch",
+    attach: () => {},
+    detach: () => {
+      lastViewMode = null;
+    },
+    onStateChange: (context, interactionState) => {
+      if (interactionState.viewMode === lastViewMode) {
+        return;
+      }
+
+      lastViewMode = interactionState.viewMode;
+      const nextFocusedNodeId = interactionState.focusedNodeId;
+
+      if (interactionState.viewMode === "focused" && nextFocusedNodeId) {
+        context.dispatchAction({ type: "focusNode", nodeId: nextFocusedNodeId });
+        return;
+      }
+
+      context.dispatchAction({ type: "fitView" });
+    },
+  };
+}