@omiron33/omi-neuron-web 0.2.16 → 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:
@@ -859,6 +890,10 @@ Enable a persistent card on click and optional zoom-to-node behavior:
 />
 ```
 
+Orbit pivot behavior:
+- On pointer down, the orbit target shifts to the cursor (or the node under it),
+  so rotating after a focus doesn’t stay locked to the previously focused node.
+
 ### Card mode (global override)
 
 `cardsMode` lets you force card behavior irrespective of `hoverCard.enabled` or `clickCard.enabled`

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-MVSWEBGR.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);
@@ -1280,6 +1386,55 @@ function NeuronWeb({
     if (!sceneManager) return;
     sceneManager.updateBackground(resolvedTheme.colors.background);
   }, [sceneManager, resolvedTheme.colors.background]);
+  react.useEffect(() => {
+    if (!sceneManager || !nodeRenderer) return;
+    const raycaster = new THREE__namespace.Raycaster();
+    const pointer = new THREE__namespace.Vector2();
+    const tempDir = new THREE__namespace.Vector3();
+    const plane = new THREE__namespace.Plane();
+    const intersection = new THREE__namespace.Vector3();
+    const updatePointer = (event) => {
+      const rect = sceneManager.renderer.domElement.getBoundingClientRect();
+      pointer.x = (event.clientX - rect.left) / rect.width * 2 - 1;
+      pointer.y = -((event.clientY - rect.top) / rect.height) * 2 + 1;
+    };
+    const onPointerDown = (event) => {
+      updatePointer(event);
+      raycaster.setFromCamera(pointer, sceneManager.camera);
+      const nodes = nodeRenderer.getNodeObjects();
+      if (nodes.length) {
+        const intersects = raycaster.intersectObjects(nodes, true);
+        if (intersects.length) {
+          const hit = intersects[0].object;
+          const nodeId = hit.userData?.nodeId;
+          if (nodeId) {
+            const nodePosition = nodeRenderer.getNodePosition(nodeId);
+            if (nodePosition) {
+              sceneManager.controls.target.copy(nodePosition);
+              sceneManager.controls.update();
+              return;
+            }
+          }
+          if (intersects[0].point) {
+            sceneManager.controls.target.copy(intersects[0].point);
+            sceneManager.controls.update();
+            return;
+          }
+        }
+      }
+      sceneManager.camera.getWorldDirection(tempDir).normalize();
+      plane.setFromNormalAndCoplanarPoint(tempDir, sceneManager.controls.target.clone());
+      if (raycaster.ray.intersectPlane(plane, intersection)) {
+        sceneManager.controls.target.copy(intersection);
+        sceneManager.controls.update();
+      }
+    };
+    const dom = sceneManager.renderer.domElement;
+    dom.addEventListener("pointerdown", onPointerDown);
+    return () => {
+      dom.removeEventListener("pointerdown", onPointerDown);
+    };
+  }, [sceneManager, nodeRenderer]);
   const cameraFitSuspended = Boolean(selectedNodeId || focusNodeSlug);
   react.useEffect(() => {
     if (!sceneManager || !animationController || !resolvedCameraFit.enabled) return;
@@ -1393,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);
@@ -1406,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) {
@@ -1429,7 +1584,8 @@ function NeuronWeb({
     clickZoomEnabled,
     animationController,
     onNodeFocused,
-    onFocusConsumed
+    onFocusConsumed,
+    applyFocusEdges
   ]);
   react.useEffect(() => {
     if (!interactionManager || !nodeRenderer || !edgeRenderer) return;
@@ -1439,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) {
@@ -1465,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);
       }
@@ -1485,7 +1641,7 @@ function NeuronWeb({
       setSelectedNodeId(null);
       nodeRenderer.setSelectedNode(null);
       if (!hoveredNodeId) {
-        edgeRenderer.setFocusEdges(null);
+        applyFocusEdges(null);
       }
       if (onBackgroundClick) onBackgroundClick();
     };
@@ -1503,7 +1659,8 @@ function NeuronWeb({
     onNodeClick,
     onNodeDoubleClick,
     onNodeFocused,
-    onBackgroundClick
+    onBackgroundClick,
+    applyFocusEdges
   ]);
   react.useEffect(() => {
     if (!sceneManager || !interactionManager) return;
@@ -1704,5 +1861,5 @@ exports.NeuronWeb = NeuronWeb;
 exports.SceneManager = SceneManager;
 exports.ThemeEngine = ThemeEngine;
 exports.applyFuzzyLayout = applyFuzzyLayout;
-//# sourceMappingURL=chunk-MVSWEBGR.cjs.map
-//# sourceMappingURL=chunk-MVSWEBGR.cjs.map
+//# sourceMappingURL=chunk-OUO3CKBM.cjs.map
+//# sourceMappingURL=chunk-OUO3CKBM.cjs.map