@omiron33/omi-neuron-web 0.2.17 → 0.2.19

package/README.md

@@ -686,7 +686,7 @@ export interface NeuronWebProps {
 
 Props currently used inside `NeuronWeb` (others are reserved for future use):
 
-- Used: `graphData`, `className`, `style`, `fullHeight`, `isFullScreen`, `isLoading`, `error`, `renderEmptyState`, `renderLoadingState`, `ariaLabel`, `theme`, `layout`, `renderNodeHover`, `renderNodeDetail`, `hoverCard`, `clickCard`, `clickZoom`, `cardsMode`, `onNodeHover`, `onNodeClick`, `onNodeDoubleClick`, `onNodeFocused`, `onBackgroundClick`, `performanceMode`, `focusNodeSlug`, `onFocusConsumed`, `visibleNodeSlugs`.
+- Used: `graphData`, `className`, `style`, `fullHeight`, `isFullScreen`, `isLoading`, `error`, `renderEmptyState`, `renderLoadingState`, `ariaLabel`, `theme`, `layout`, `renderNodeHover`, `renderNodeDetail`, `hoverCard`, `clickCard`, `clickZoom`, `cardsMode`, `onNodeHover`, `onNodeClick`, `onNodeDoubleClick`, `onNodeFocused`, `onBackgroundClick`, `performanceMode`, `focusNodeSlug`, `onFocusConsumed`, `visibleNodeSlugs`, `studyPathRequest`, `onStudyPathComplete`.
 - Used: `cameraFit` (auto-fit bounds to a viewport fraction).
 - Reserved (declared but not used in the component yet): `selectedNode`, `onEdgeClick`, `onCameraChange`, `studyPathRequest`, `onStudyPathComplete`, `domainColors`, `graphData.storyBeats`.
 
@@ -847,6 +847,37 @@ Semantics:
 <NeuronWeb graphData={graphData} visibleNodeSlugs={[]} />;
 ```
 
+### Study path playback (follow the path between nodes)
+
+Use `studyPathRequest` to step through an ordered list of nodes. Each step:
+- selects the node
+- tweens the camera to the node (if `clickZoom.enabled`)
+- highlights the edge between the current and next step
+
+```tsx
+<NeuronWeb
+  graphData={graphData}
+  studyPathRequest={{
+    steps: [
+      { nodeSlug: 'uap', label: 'Start' },
+      { nodeSlug: 'neph', label: 'Next' },
+      { nodeSlug: 'jude6', label: 'Finish' },
+    ],
+    stepDurationMs: 4200,
+  }}
+  onStudyPathComplete={() => console.log('study path done')}
+/>
+```
+
+Fallback form (two-step path):
+
+```tsx
+<NeuronWeb
+  graphData={graphData}
+  studyPathRequest={{ fromNodeId: 'uap', toNodeId: 'neph' }}
+/>
+```
+
 ### Click cards + click zoom
 
 Enable a persistent card on click and optional zoom-to-node behavior:

package/dist/{NeuronWeb-CZgKU1-X.d.ts → NeuronWeb-CnamAVi_.d.ts}

@@ -6,9 +6,30 @@ interface NeuronStoryBeat {
     label: string;
     nodeIds: string[];
 }
+interface StudyPathStep {
+    nodeSlug?: string;
+    nodeId?: string;
+    label?: string;
+    summary?: string;
+}
 interface StudyPathRequest {
-    fromNodeId: string;
-    toNodeId: string;
+    /**
+     * Ordered steps to follow (slugs or ids). When provided, this takes precedence.
+     */
+    steps?: StudyPathStep[];
+    /**
+     * Optional label for the study path (consumer UI usage).
+     */
+    label?: string;
+    /**
+     * Time to hold each step before advancing (ms). Defaults to 4200.
+     */
+    stepDurationMs?: number;
+    /**
+     * Minimal fallback when steps are not provided.
+     */
+    fromNodeId?: string;
+    toNodeId?: string;
 }
 interface NeuronWebTheme {
     colors: {
@@ -137,6 +158,6 @@ interface NeuronWebProps {
     ariaLabel?: string;
 }
 
-declare function NeuronWeb({ graphData, className, style, fullHeight, isFullScreen, isLoading, error, focusNodeSlug, onFocusConsumed, visibleNodeSlugs, renderEmptyState, renderLoadingState, ariaLabel, theme, layout, cameraFit, cardsMode, clickCard, clickZoom, renderNodeHover, renderNodeDetail, hoverCard, onNodeHover, onNodeClick, onNodeDoubleClick, onNodeFocused, onBackgroundClick, performanceMode, }: NeuronWebProps): React__default.ReactElement;
+declare function NeuronWeb({ graphData, className, style, fullHeight, isFullScreen, isLoading, error, focusNodeSlug, onFocusConsumed, visibleNodeSlugs, renderEmptyState, renderLoadingState, ariaLabel, theme, layout, cameraFit, cardsMode, clickCard, clickZoom, studyPathRequest, onStudyPathComplete, renderNodeHover, renderNodeDetail, hoverCard, onNodeHover, onNodeClick, onNodeDoubleClick, onNodeFocused, onBackgroundClick, performanceMode, }: NeuronWebProps): React__default.ReactElement;
 
 export { type CameraFitOptions as C, type HoverCardOptions as H, type NeuronWebTheme as N, type NeuronWebThemeOverride as a, type NeuronLayoutOptions as b, NeuronWeb as c, type NeuronWebProps as d, type NeuronLayoutMode as e, type ClickCardOptions as f, type ClickZoomOptions as g, type CardsMode as h };

package/dist/{NeuronWeb-JVrxQksC.d.cts → NeuronWeb-DkNLfI1I.d.cts}

@@ -6,9 +6,30 @@ interface NeuronStoryBeat {
     label: string;
     nodeIds: string[];
 }
+interface StudyPathStep {
+    nodeSlug?: string;
+    nodeId?: string;
+    label?: string;
+    summary?: string;
+}
 interface StudyPathRequest {
-    fromNodeId: string;
-    toNodeId: string;
+    /**
+     * Ordered steps to follow (slugs or ids). When provided, this takes precedence.
+     */
+    steps?: StudyPathStep[];
+    /**
+     * Optional label for the study path (consumer UI usage).
+     */
+    label?: string;
+    /**
+     * Time to hold each step before advancing (ms). Defaults to 4200.
+     */
+    stepDurationMs?: number;
+    /**
+     * Minimal fallback when steps are not provided.
+     */
+    fromNodeId?: string;
+    toNodeId?: string;
 }
 interface NeuronWebTheme {
     colors: {
@@ -137,6 +158,6 @@ interface NeuronWebProps {
     ariaLabel?: string;
 }
 
-declare function NeuronWeb({ graphData, className, style, fullHeight, isFullScreen, isLoading, error, focusNodeSlug, onFocusConsumed, visibleNodeSlugs, renderEmptyState, renderLoadingState, ariaLabel, theme, layout, cameraFit, cardsMode, clickCard, clickZoom, renderNodeHover, renderNodeDetail, hoverCard, onNodeHover, onNodeClick, onNodeDoubleClick, onNodeFocused, onBackgroundClick, performanceMode, }: NeuronWebProps): React__default.ReactElement;
+declare function NeuronWeb({ graphData, className, style, fullHeight, isFullScreen, isLoading, error, focusNodeSlug, onFocusConsumed, visibleNodeSlugs, renderEmptyState, renderLoadingState, ariaLabel, theme, layout, cameraFit, cardsMode, clickCard, clickZoom, studyPathRequest, onStudyPathComplete, renderNodeHover, renderNodeDetail, hoverCard, onNodeHover, onNodeClick, onNodeDoubleClick, onNodeFocused, onBackgroundClick, performanceMode, }: NeuronWebProps): React__default.ReactElement;
 
 export { type CameraFitOptions as C, type HoverCardOptions as H, type NeuronWebTheme as N, type NeuronWebThemeOverride as a, type NeuronLayoutOptions as b, NeuronWeb as c, type NeuronWebProps as d, type NeuronLayoutMode as e, type ClickCardOptions as f, type ClickZoomOptions as g, type CardsMode as h };

package/dist/{chunk-CKFZJZLN.cjs → chunk-OUO3CKBM.cjs}

@@ -1061,6 +1061,8 @@ function NeuronWeb({
   cardsMode,
   clickCard,
   clickZoom,
+  studyPathRequest,
+  onStudyPathComplete,
   renderNodeHover,
   renderNodeDetail,
   hoverCard,
@@ -1076,9 +1078,12 @@ function NeuronWeb({
   const clickCardRef = react.useRef(null);
   const [hoveredNodeId, setHoveredNodeId] = react.useState(null);
   const [selectedNodeId, setSelectedNodeId] = react.useState(null);
+  const [studyPathPlayer, setStudyPathPlayer] = react.useState(null);
   const fitStateRef = react.useRef({ hasFit: false, signature: "" });
   const firstFilterChangeRef = react.useRef(true);
   const [filterTransitioning, setFilterTransitioning] = react.useState(false);
+  const pathEdgeIdsRef = react.useRef([]);
+  const focusEdgesRef = react.useRef(null);
   const filteredGraphData = react.useMemo(() => {
     if (visibleNodeSlugs === null || visibleNodeSlugs === void 0) {
       return graphData;
@@ -1250,6 +1255,43 @@ function NeuronWeb({
     });
     return map;
   }, [workingGraph.edges]);
+  const applyFocusEdges = react.useCallback(
+    (edgeIds) => {
+      if (!edgeRenderer) return;
+      focusEdgesRef.current = edgeIds;
+      const merged = new Set(edgeIds ?? []);
+      pathEdgeIdsRef.current.forEach((id) => merged.add(id));
+      edgeRenderer.setFocusEdges(merged.size ? Array.from(merged) : null);
+    },
+    [edgeRenderer]
+  );
+  const resolvedStudyPathSteps = react.useMemo(() => {
+    if (!studyPathRequest) return null;
+    if (studyPathRequest.steps && studyPathRequest.steps.length) {
+      return studyPathRequest.steps;
+    }
+    if (studyPathRequest.fromNodeId && studyPathRequest.toNodeId) {
+      return [
+        { nodeId: studyPathRequest.fromNodeId },
+        { nodeId: studyPathRequest.toNodeId }
+      ];
+    }
+    return null;
+  }, [studyPathRequest]);
+  react.useEffect(() => {
+    if (!resolvedStudyPathSteps || resolvedStudyPathSteps.length === 0) {
+      setStudyPathPlayer(null);
+      pathEdgeIdsRef.current = [];
+      applyFocusEdges(focusEdgesRef.current);
+      return;
+    }
+    setStudyPathPlayer({
+      steps: resolvedStudyPathSteps,
+      index: 0,
+      playing: true,
+      stepDurationMs: studyPathRequest?.stepDurationMs ?? 4200
+    });
+  }, [resolvedStudyPathSteps, studyPathRequest?.stepDurationMs, applyFocusEdges]);
   const nodeByIdentifier = react.useMemo(() => {
     const map = /* @__PURE__ */ new Map();
     resolvedNodes.forEach((node) => {
@@ -1266,6 +1308,70 @@ function NeuronWeb({
   const clickCardOffset = clickCard?.offset ?? [24, 24];
   const clickCardWidth = clickCard?.width ?? 320;
   const clickZoomEnabled = clickZoom?.enabled ?? true;
+  react.useEffect(() => {
+    if (!studyPathPlayer) return;
+    const step = studyPathPlayer.steps[studyPathPlayer.index];
+    const stepKey = step?.nodeSlug ?? step?.nodeId ?? null;
+    const node = stepKey ? nodeByIdentifier.get(stepKey) ?? null : null;
+    if (node && nodeRenderer && edgeRenderer) {
+      setSelectedNodeId(node.id);
+      nodeRenderer.setSelectedNode(node.id);
+      nodeRenderer.pulseNode(node.id);
+      if (clickZoomEnabled) {
+        const nodePosition = nodeRenderer.getNodePosition(node.id);
+        if (nodePosition) {
+          animationController?.focusOnNode(nodePosition, () => {
+            if (onNodeFocused) onNodeFocused(node);
+          });
+        }
+      }
+      const slug = node.slug;
+      applyFocusEdges(slug ? edgesBySlug.get(slug) ?? [] : []);
+    }
+    const nextStep = studyPathPlayer.index < studyPathPlayer.steps.length - 1 ? studyPathPlayer.steps[studyPathPlayer.index + 1] : null;
+    const currentSlug = node?.slug ?? (step?.nodeSlug ?? null);
+    const nextKey = nextStep?.nodeSlug ?? nextStep?.nodeId ?? null;
+    const nextNode = nextKey ? nodeByIdentifier.get(nextKey) ?? null : null;
+    const nextSlug = nextNode?.slug ?? (nextStep?.nodeSlug ?? null);
+    if (currentSlug && nextSlug) {
+      pathEdgeIdsRef.current = workingGraph.edges.filter(
+        (edge) => edge.from === currentSlug && edge.to === nextSlug || edge.to === currentSlug && edge.from === nextSlug
+      ).map((edge) => edge.id);
+    } else {
+      pathEdgeIdsRef.current = [];
+    }
+    applyFocusEdges(focusEdgesRef.current);
+  }, [
+    studyPathPlayer,
+    nodeByIdentifier,
+    nodeRenderer,
+    edgeRenderer,
+    edgesBySlug,
+    workingGraph.edges,
+    animationController,
+    clickZoomEnabled,
+    onNodeFocused,
+    applyFocusEdges
+  ]);
+  react.useEffect(() => {
+    if (!studyPathPlayer || !studyPathPlayer.playing) return;
+    const timer = window.setTimeout(() => {
+      setStudyPathPlayer((prev) => {
+        if (!prev) return prev;
+        if (prev.index >= prev.steps.length - 1) {
+          if (onStudyPathComplete) onStudyPathComplete();
+          return { ...prev, playing: false };
+        }
+        return { ...prev, index: prev.index + 1 };
+      });
+    }, studyPathPlayer.stepDurationMs);
+    return () => window.clearTimeout(timer);
+  }, [studyPathPlayer, onStudyPathComplete]);
+  react.useEffect(() => {
+    if (!studyPathPlayer || studyPathPlayer.playing) return;
+    pathEdgeIdsRef.current = [];
+    applyFocusEdges(focusEdgesRef.current);
+  }, [studyPathPlayer, applyFocusEdges]);
   react.useEffect(() => {
     if (!sceneManager || !nodeRenderer || !edgeRenderer) return;
     nodeRenderer.renderNodes(resolvedNodes);
@@ -1442,9 +1548,9 @@ function NeuronWeb({
     if (selectedNodeId && !nodeMap.has(selectedNodeId)) {
       setSelectedNodeId(null);
       nodeRenderer.setSelectedNode(null);
-      edgeRenderer.setFocusEdges(null);
+      applyFocusEdges(null);
     }
-  }, [selectedNodeId, nodeMap, nodeRenderer, edgeRenderer]);
+  }, [selectedNodeId, nodeMap, nodeRenderer, edgeRenderer, applyFocusEdges]);
   react.useEffect(() => {
     if (!focusNodeSlug || !nodeRenderer || !edgeRenderer) return;
     const node = nodeByIdentifier.get(focusNodeSlug);
@@ -1455,7 +1561,7 @@ function NeuronWeb({
     setSelectedNodeId(node.id);
     nodeRenderer.setSelectedNode(node.id);
     nodeRenderer.pulseNode(node.id);
-    edgeRenderer.setFocusEdges(node.slug ? edgesBySlug.get(node.slug) ?? [] : []);
+    applyFocusEdges(node.slug ? edgesBySlug.get(node.slug) ?? [] : []);
     if (clickZoomEnabled) {
       const nodePosition = nodeRenderer.getNodePosition(node.id);
       if (nodePosition) {
@@ -1478,7 +1584,8 @@ function NeuronWeb({
     clickZoomEnabled,
     animationController,
     onNodeFocused,
-    onFocusConsumed
+    onFocusConsumed,
+    applyFocusEdges
   ]);
   react.useEffect(() => {
     if (!interactionManager || !nodeRenderer || !edgeRenderer) return;
@@ -1488,13 +1595,13 @@ function NeuronWeb({
       nodeRenderer.setHoveredNode(nodeId);
       if (nodeId) {
         const slug = nodeSlugById.get(nodeId);
-        edgeRenderer.setFocusEdges(slug ? edgesBySlug.get(slug) ?? [] : []);
+        applyFocusEdges(slug ? edgesBySlug.get(slug) ?? [] : []);
       } else {
         const selectedSlug = selectedNodeId ? nodeSlugById.get(selectedNodeId) : null;
         if (selectedSlug) {
-          edgeRenderer.setFocusEdges(edgesBySlug.get(selectedSlug) ?? []);
+          applyFocusEdges(edgesBySlug.get(selectedSlug) ?? []);
         } else {
-          edgeRenderer.setFocusEdges(null);
+          applyFocusEdges(null);
         }
       }
       if (onNodeHover) {
@@ -1514,7 +1621,7 @@ function NeuronWeb({
         }
       }
       const slug = nodeSlugById.get(node.id);
-      edgeRenderer.setFocusEdges(slug ? edgesBySlug.get(slug) ?? [] : []);
+      applyFocusEdges(slug ? edgesBySlug.get(slug) ?? [] : []);
       if (onNodeClick) {
         onNodeClick(node);
       }
@@ -1534,7 +1641,7 @@ function NeuronWeb({
       setSelectedNodeId(null);
       nodeRenderer.setSelectedNode(null);
       if (!hoveredNodeId) {
-        edgeRenderer.setFocusEdges(null);
+        applyFocusEdges(null);
       }
       if (onBackgroundClick) onBackgroundClick();
     };
@@ -1552,7 +1659,8 @@ function NeuronWeb({
     onNodeClick,
     onNodeDoubleClick,
     onNodeFocused,
-    onBackgroundClick
+    onBackgroundClick,
+    applyFocusEdges
   ]);
   react.useEffect(() => {
     if (!sceneManager || !interactionManager) return;
@@ -1753,5 +1861,5 @@ exports.NeuronWeb = NeuronWeb;
 exports.SceneManager = SceneManager;
 exports.ThemeEngine = ThemeEngine;
 exports.applyFuzzyLayout = applyFuzzyLayout;
-//# sourceMappingURL=chunk-CKFZJZLN.cjs.map
-//# sourceMappingURL=chunk-CKFZJZLN.cjs.map
+//# sourceMappingURL=chunk-OUO3CKBM.cjs.map
+//# sourceMappingURL=chunk-OUO3CKBM.cjs.map