@principal-ai/subsystems-react 0.28.1 → 0.28.2

package/src/subsystem/WalkthroughsPanel.tsx

@@ -0,0 +1,569 @@
+/**
+ * WalkthroughsPanel — the sidebar's flows panel: the ordered list of a
+ * subsystem's walkthroughs, each rendered as a collapsible `WalkthroughFlow`
+ * row. Extracted from `SubsystemComponentGraph`'s `Inner` so the panel (and the
+ * drag-to-reorder controller it hosts) is a component boundary of its own.
+ *
+ * Ordering is authored order: the list renders `walkthroughs` in array order.
+ * When `onReorder` is supplied, each row grows a grip in its header and dropping
+ * a row onto another emits the reordered array (see `reorderWalkthroughs`); the
+ * host owns persistence.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { DragEvent as ReactDragEvent } from 'react';
+import { useTheme } from '@principal-ade/industry-theme';
+import { GripVertical, Pause, Play, X } from 'lucide-react';
+import {
+  reorderTargetIndex,
+  reorderWalkthroughs,
+  walkthroughStepGraphEdgeId,
+  type SubsystemWalkthrough,
+} from './model';
+
+/** Pause (ms) between steps when a walkthrough autoplays. */
+export const WALKTHROUGH_PLAY_PAUSE_MS = 2500;
+
+/** Drag state handed to a row's grip while a reorder is in flight. */
+interface WalkthroughReorderHandle {
+  index: number;
+  isDragging: boolean;
+  onDragStart: (index: number, e: ReactDragEvent) => void;
+  onDragEnd: () => void;
+}
+
+/** One collapsible walkthrough in the sidebar's flows panel. Clicking the
+ *  title: closed → open + select; open and unselected → select; open and
+ *  selected → close + clear focus. The right-aligned close button collapses
+ *  without selecting. A step row focuses that step's edge. */
+function WalkthroughFlow({
+  walkthrough,
+  collapsed,
+  active,
+  onToggleCollapsed,
+  onFocusFlow,
+  onClearFocus,
+  onFocusStep,
+  onHoverStep,
+  onHoverFlow,
+  onLeaveStep,
+  reorder,
+  dragActive,
+  isHoverSuppressed,
+}: {
+  walkthrough: SubsystemWalkthrough;
+  collapsed: boolean;
+  /** `{ stepIndex: null }` = whole flow focused; `{ stepIndex }` = one step. */
+  active: { stepIndex: number | null } | null;
+  onToggleCollapsed: (tlId: string) => void;
+  onFocusFlow: (tl: SubsystemWalkthrough) => void;
+  onClearFocus: () => void;
+  onFocusStep: (tl: SubsystemWalkthrough, stepIndex: number) => void;
+  onHoverStep: (tl: SubsystemWalkthrough, stepIndex: number) => void;
+  /** Preview the whole flow on the canvas (used while the row is collapsed). */
+  onHoverFlow: (tl: SubsystemWalkthrough) => void;
+  onLeaveStep: () => void;
+  /** When set, renders a grip in the header that starts a reorder drag. */
+  reorder?: WalkthroughReorderHandle;
+  /** True while any row is mid-drag; used to reset stale hover styling. */
+  dragActive?: boolean;
+  /** True just after a drop; ignores the browser's synthetic hover until the pointer moves. */
+  isHoverSuppressed?: () => boolean;
+}) {
+  const { theme } = useTheme();
+  const muted = theme.colors.textMuted ?? theme.colors.textSecondary;
+  const hoverBg = theme.colors.background;
+  const wholeFlowActive = active !== null && active.stepIndex === null;
+  const [headerHover, setHeaderHover] = useState(false);
+  const [closeHover, setCloseHover] = useState(false);
+  const [playHover, setPlayHover] = useState(false);
+  const [gripHover, setGripHover] = useState(false);
+  const [hoveredStep, setHoveredStep] = useState<number | null>(null);
+  const stepButtonRefs = useRef<(HTMLButtonElement | null)[]>([]);
+  // Autoplay: stepping through the flow's steps with a pause between each.
+  const [playing, setPlaying] = useState(false);
+  const playTimerRef = useRef<number | null>(null);
+
+  const stopPlaying = useCallback(() => {
+    if (playTimerRef.current != null) {
+      window.clearTimeout(playTimerRef.current);
+      playTimerRef.current = null;
+    }
+    setPlaying(false);
+  }, []);
+
+  // Clear any pending timer on unmount.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useEffect(() => () => stopPlaying(), []);
+
+  // Native HTML5 drag suppresses mouse events, so a row hovered when the drag
+  // began never gets its mouseleave — its hover styling would stick after the
+  // drop. Reset every row's hover whenever a drag starts or ends.
+  useEffect(() => {
+    setHeaderHover(false);
+    setCloseHover(false);
+    setPlayHover(false);
+    setGripHover(false);
+    setHoveredStep(null);
+  }, [dragActive]);
+
+  const startPlaying = useCallback(() => {
+    if (collapsed) onToggleCollapsed(walkthrough.id);
+    if (active === null || active.stepIndex !== null) onFocusFlow(walkthrough);
+    const stepCount = walkthrough.steps.length;
+    if (stepCount === 0) return;
+    setPlaying(true);
+    let i = 0;
+    const tick = () => {
+      if (i >= stepCount) {
+        playTimerRef.current = null;
+        setPlaying(false);
+        return;
+      }
+      onFocusStep(walkthrough, i);
+      i += 1;
+      playTimerRef.current = window.setTimeout(tick, WALKTHROUGH_PLAY_PAUSE_MS);
+    };
+    tick();
+  }, [collapsed, active, onToggleCollapsed, onFocusFlow, walkthrough, onFocusStep]);
+
+  const togglePlay = useCallback(() => {
+    if (playing) {
+      stopPlaying();
+    } else {
+      startPlaying();
+    }
+  }, [playing, stopPlaying, startPlaying]);
+
+  // Keep DOM focus on the active step so the browser focus ring (and
+  // subsequent arrow keys) follow arrow navigation, not the originally
+  // clicked button.
+  useEffect(() => {
+    if (active?.stepIndex == null) return;
+    stepButtonRefs.current[active.stepIndex]?.focus({ preventScroll: true });
+  }, [active?.stepIndex]);
+
+  return (
+    <div>
+      <div
+        onMouseEnter={() => {
+          if (isHoverSuppressed?.()) return;
+          setHeaderHover(true);
+          if (collapsed) onHoverFlow(walkthrough);
+        }}
+        onMouseLeave={() => {
+          setHeaderHover(false);
+          if (collapsed) onLeaveStep();
+        }}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 4,
+          padding: '0 16px',
+          background: wholeFlowActive || headerHover ? hoverBg : 'transparent',
+          transition: 'background 120ms ease',
+        }}
+      >
+        <button
+          type="button"
+          onClick={() => {
+            if (collapsed) {
+              onToggleCollapsed(walkthrough.id);
+              onFocusFlow(walkthrough);
+            } else if (active === null) {
+              onFocusFlow(walkthrough);
+            } else {
+              onToggleCollapsed(walkthrough.id);
+              onClearFocus();
+            }
+          }}
+          style={{
+            flex: 1,
+            display: 'flex',
+            alignItems: 'center',
+            minWidth: 0,
+            padding: '10px 0',
+            border: 'none',
+            background: 'transparent',
+            textAlign: 'left',
+            cursor: 'pointer',
+          }}
+        >
+          <span
+            style={{
+              overflow: 'hidden',
+              textOverflow: 'ellipsis',
+              whiteSpace: 'nowrap',
+              fontSize: theme.fontSizes[1],
+              fontFamily: theme.fonts.monospace,
+              fontWeight: 600,
+              color: theme.colors.text,
+            }}
+          >
+            {walkthrough.title}
+          </span>
+        </button>
+        {!collapsed && (
+          <>
+          <button
+            type="button"
+            aria-label={playing ? `Pause ${walkthrough.title} autoplay` : `Play ${walkthrough.title}`}
+            title={playing ? 'Pause' : 'Play through steps'}
+            onMouseEnter={() => setPlayHover(true)}
+            onMouseLeave={() => setPlayHover(false)}
+            onClick={(e) => {
+              e.stopPropagation();
+              togglePlay();
+            }}
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              flexShrink: 0,
+              width: 22,
+              height: 22,
+              padding: 0,
+              border: 'none',
+              borderRadius: 4,
+              background: playing || playHover ? theme.colors.border : 'transparent',
+              color: playing || playHover ? theme.colors.text : muted,
+              cursor: 'pointer',
+              transition: 'background 120ms ease, color 120ms ease',
+            }}
+          >
+            {playing ? <Pause size={12} strokeWidth={2} /> : <Play size={12} strokeWidth={2} />}
+          </button>
+          <button
+            type="button"
+            aria-label={`Close ${walkthrough.title}`}
+            onMouseEnter={() => setCloseHover(true)}
+            onMouseLeave={() => setCloseHover(false)}
+            onClick={(e) => {
+              e.stopPropagation();
+              onToggleCollapsed(walkthrough.id);
+              if (active !== null) onClearFocus();
+            }}
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              flexShrink: 0,
+              width: 22,
+              height: 22,
+              padding: 0,
+              border: 'none',
+              borderRadius: 4,
+              background: closeHover ? theme.colors.border : 'transparent',
+              color: closeHover ? theme.colors.text : muted,
+              cursor: 'pointer',
+              transition: 'background 120ms ease, color 120ms ease',
+            }}
+          >
+            <X size={12} strokeWidth={2} />
+          </button>
+          </>
+        )}
+        {reorder && (
+          <span
+            role="button"
+            tabIndex={-1}
+            draggable
+            aria-label={`Reorder ${walkthrough.title}`}
+            title="Drag to reorder"
+            onMouseEnter={() => {
+              if (!isHoverSuppressed?.()) setGripHover(true);
+            }}
+            onMouseLeave={() => setGripHover(false)}
+            onDragStart={(e) => reorder.onDragStart(reorder.index, e)}
+            onDragEnd={reorder.onDragEnd}
+            onClick={(e) => e.stopPropagation()}
+            style={{
+              display: 'inline-flex',
+              alignItems: 'center',
+              flexShrink: 0,
+              marginRight: -8,
+              padding: '2px 0',
+              color: gripHover || reorder.isDragging ? theme.colors.text : muted,
+              cursor: reorder.isDragging ? 'grabbing' : 'grab',
+              transition: 'color 120ms ease',
+            }}
+          >
+            <GripVertical size={14} strokeWidth={2} />
+          </span>
+        )}
+      </div>
+      {!collapsed && (
+        <div
+          style={{ display: 'flex', flexDirection: 'column' }}
+          onMouseLeave={() => {
+            setHoveredStep(null);
+            onLeaveStep();
+          }}
+        >
+          {walkthrough.steps.map((step, i) => {
+            const stepActive = active !== null && active.stepIndex === i;
+            return (
+              <button
+                key={`${walkthroughStepGraphEdgeId(step)}-${i}`}
+                ref={(el) => {
+                  stepButtonRefs.current[i] = el;
+                }}
+                type="button"
+                onMouseEnter={() => {
+                  setHoveredStep(i);
+                  onHoverStep(walkthrough, i);
+                }}
+                onClick={() => onFocusStep(walkthrough, i)}
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 8,
+                  minWidth: 0,
+                  padding: '8px 8px 8px 12px',
+                  textAlign: 'left',
+                  borderRadius: 6,
+                  border: 'none',
+                  outline: 'none',
+                  background: stepActive || hoveredStep === i ? hoverBg : 'transparent',
+                  cursor: 'pointer',
+                  transition: 'background 120ms ease',
+                }}
+              >
+                <span
+                  style={{
+                    flexShrink: 0,
+                    width: 14,
+                    fontSize: theme.fontSizes[0],
+                    fontFamily: theme.fonts.monospace,
+                    color: stepActive ? theme.colors.text : muted,
+                  }}
+                >
+                  {i + 1}
+                </span>
+                <span
+                  style={{
+                    flex: 1,
+                    minWidth: 0,
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    whiteSpace: 'nowrap',
+                    fontSize: theme.fontSizes[1],
+                    fontFamily: theme.fonts.monospace,
+                    color: theme.colors.text,
+                  }}
+                >
+                  {step.symbol}
+                </span>
+              </button>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export interface WalkthroughsPanelProps {
+  /** Ordered walkthroughs — the list renders them in array order. */
+  walkthroughs: SubsystemWalkthrough[];
+  /** Ids of the rows whose step lists are expanded. */
+  expandedWalkthroughs: Set<string>;
+  focusedWalkthroughId: string | null;
+  focusedStepIndex: number | null;
+  hoveredWalkthroughStep: {
+    walkthroughId: string;
+    stepIndex: number | null;
+  } | null;
+  onToggleCollapsed: (tlId: string) => void;
+  onFocusFlow: (tl: SubsystemWalkthrough) => void;
+  onClearFocus: () => void;
+  onFocusStep: (tl: SubsystemWalkthrough, stepIndex: number) => void;
+  onHoverStep: (tl: SubsystemWalkthrough, stepIndex: number) => void;
+  onHoverFlow: (tl: SubsystemWalkthrough) => void;
+  onLeaveStep: () => void;
+  /**
+   * When set, rows grow a drag grip (and become drop targets) so a drop emits
+   * the reordered array. Grips show only while every row is collapsed. Omit
+   * for a read-only panel.
+   */
+  onReorder?: (next: SubsystemWalkthrough[]) => void;
+}
+
+/**
+ * The flows panel: a scroll container of `WalkthroughFlow` rows, optionally
+ * drag-reorderable. The host owns the array; a drop calls `onReorder` with the
+ * next order and the host re-renders with it.
+ */
+export function WalkthroughsPanel({
+  walkthroughs,
+  expandedWalkthroughs,
+  focusedWalkthroughId,
+  focusedStepIndex,
+  hoveredWalkthroughStep,
+  onToggleCollapsed,
+  onFocusFlow,
+  onClearFocus,
+  onFocusStep,
+  onHoverStep,
+  onHoverFlow,
+  onLeaveStep,
+  onReorder,
+}: WalkthroughsPanelProps) {
+  const { theme } = useTheme();
+  // Reordering is offered only while every row is collapsed: the compact list
+  // is what you drag, and expanded step lists would make drop targets tall and
+  // the landing boundary ambiguous.
+  const allCollapsed = walkthroughs.every((w) => !expandedWalkthroughs.has(w.id));
+  const reorderable = onReorder != null && allCollapsed;
+  // Row being dragged, and the gap the pointer is over (boundaries 0..n
+  // between rows). The boundary is where the dragged row will be inserted.
+  const [dragIndex, setDragIndex] = useState<number | null>(null);
+  const [dropBoundary, setDropBoundary] = useState<number | null>(null);
+  // After a native drag ends the browser fires a mouseenter on whatever sits
+  // under the cursor, which would light up a row the user never moved onto.
+  // Ignore hover until the pointer actually moves. A ref (not state) so the
+  // guard is synchronous — the synthetic event can beat a re-render.
+  const suppressHoverRef = useRef(false);
+  const hoverClearRef = useRef<(() => void) | null>(null);
+
+  const suppressHoverUntilMove = useCallback(() => {
+    suppressHoverRef.current = true;
+    if (hoverClearRef.current) return;
+    const clear = () => {
+      suppressHoverRef.current = false;
+      window.removeEventListener('mousemove', clear);
+      hoverClearRef.current = null;
+    };
+    hoverClearRef.current = clear;
+    window.addEventListener('mousemove', clear);
+  }, []);
+
+  useEffect(
+    () => () => {
+      if (hoverClearRef.current) {
+        window.removeEventListener('mousemove', hoverClearRef.current);
+        hoverClearRef.current = null;
+      }
+    },
+    [],
+  );
+
+  const resetDrag = useCallback(() => {
+    setDragIndex(null);
+    setDropBoundary(null);
+    suppressHoverUntilMove();
+  }, [suppressHoverUntilMove]);
+
+  const handleDragStart = useCallback((index: number, e: ReactDragEvent) => {
+    suppressHoverRef.current = false;
+    setDragIndex(index);
+    e.dataTransfer.effectAllowed = 'move';
+    // Firefox requires data to be set for a drag to begin.
+    e.dataTransfer.setData('text/plain', String(index));
+  }, []);
+
+  // Pick the boundary nearest the pointer: above the row when over its top
+  // half, below it when over the bottom half. The line marks that gap, and the
+  // drop inserts there — so the indicator always matches the result.
+  const handleDragOver = useCallback(
+    (e: ReactDragEvent, index: number) => {
+      if (dragIndex == null) return;
+      e.preventDefault();
+      e.dataTransfer.dropEffect = 'move';
+      const rect = e.currentTarget.getBoundingClientRect();
+      const below = e.clientY - rect.top > rect.height / 2;
+      setDropBoundary(index + (below ? 1 : 0));
+    },
+    [dragIndex],
+  );
+
+  const handleDrop = useCallback(
+    (e: ReactDragEvent) => {
+      e.preventDefault();
+      const boundary = dropBoundary;
+      const from = dragIndex ?? Number(e.dataTransfer.getData('text/plain'));
+      resetDrag();
+      if (!onReorder || boundary == null || !Number.isInteger(from)) return;
+      // Removing the dragged row shifts every boundary after it down one.
+      const target = reorderTargetIndex(boundary, from);
+      if (target === from) return;
+      onReorder(reorderWalkthroughs(walkthroughs, from, target));
+    },
+    [dragIndex, dropBoundary, onReorder, resetDrag, walkthroughs],
+  );
+
+  const accent = theme.colors.accent ?? theme.colors.primary ?? theme.colors.text;
+  const isHoverSuppressed = useCallback(() => suppressHoverRef.current, []);
+
+  return (
+    <div
+      style={{
+        flex: 1,
+        minHeight: 0,
+        overflowY: 'auto',
+        padding: '0 0 12px',
+      }}
+      onDragEnd={reorderable ? resetDrag : undefined}
+    >
+      {walkthroughs.map((tl, i) => {
+        const isDragging = dragIndex === i;
+        // One indicator per boundary: a row's top edge for boundaries above it,
+        // the last row's bottom edge for the boundary at the very end.
+        const showTop = reorderable && dropBoundary === i;
+        const showBottom =
+          reorderable &&
+          i === walkthroughs.length - 1 &&
+          dropBoundary === walkthroughs.length;
+        return (
+          <div
+            key={tl.id}
+            data-walkthrough-row={tl.id}
+            data-reorder-index={i}
+            onDragOver={reorderable ? (e) => handleDragOver(e, i) : undefined}
+            onDrop={reorderable ? handleDrop : undefined}
+            style={{
+              opacity: isDragging ? 0.45 : 1,
+              boxShadow: showTop
+                ? `inset 0 2px 0 ${accent}`
+                : showBottom
+                  ? `inset 0 -2px 0 ${accent}`
+                  : undefined,
+              transition: 'opacity 120ms ease, box-shadow 120ms ease',
+            }}
+          >
+            <WalkthroughFlow
+              walkthrough={tl}
+              collapsed={!expandedWalkthroughs.has(tl.id)}
+              active={
+                focusedWalkthroughId === tl.id
+                  ? { stepIndex: focusedStepIndex }
+                  : hoveredWalkthroughStep?.walkthroughId === tl.id
+                    ? { stepIndex: hoveredWalkthroughStep.stepIndex }
+                    : null
+              }
+              onToggleCollapsed={onToggleCollapsed}
+              onFocusFlow={onFocusFlow}
+              onClearFocus={onClearFocus}
+              onFocusStep={onFocusStep}
+              onHoverStep={onHoverStep}
+              onHoverFlow={onHoverFlow}
+              onLeaveStep={onLeaveStep}
+              reorder={
+                reorderable
+                  ? {
+                      index: i,
+                      isDragging,
+                      onDragStart: handleDragStart,
+                      onDragEnd: resetDrag,
+                    }
+                  : undefined
+              }
+              dragActive={dragIndex != null}
+              isHoverSuppressed={isHoverSuppressed}
+            />
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/subsystem/model.test.ts

@@ -29,8 +29,10 @@ import {
   packageColor,
   subsystemGraphLayoutKey,
   describeConstructBreakdown,
+  reorderWalkthroughs,
+  reorderTargetIndex,
 } from './model';
-import type { SubsystemComponent, SubsystemComponentEdge } from './model';
+import type { SubsystemComponent, SubsystemComponentEdge, SubsystemWalkthrough } from './model';
 
 const comps: SubsystemComponent[] = [
   { alias: 'reader', name: 'SessionReader', construct: 'class', file: 'SessionReader.ts', purl: 'pkg:github/principal-ai/agent-monitoring' },
@@ -793,3 +795,76 @@ describe('module badge labels', () => {
     expect(moduleBadgeWidth('src/…/nodes.tsx')).toBeLessThan(moduleBadgeWidth('packages/…/nodes.tsx'));
   });
 });
+
+describe('reorderWalkthroughs', () => {
+  const wts: SubsystemWalkthrough[] = [
+    { id: 'a', title: 'A', steps: [] },
+    { id: 'b', title: 'B', steps: [] },
+    { id: 'c', title: 'C', steps: [] },
+  ];
+  const ids = (list: SubsystemWalkthrough[]) => list.map((w) => w.id);
+
+  test('moves an item forward to the target index', () => {
+    expect(ids(reorderWalkthroughs(wts, 0, 2))).toEqual(['b', 'c', 'a']);
+  });
+
+  test('moves an item backward to the target index', () => {
+    expect(ids(reorderWalkthroughs(wts, 2, 0))).toEqual(['c', 'a', 'b']);
+  });
+
+  test('returns a new array and leaves the input untouched', () => {
+    const next = reorderWalkthroughs(wts, 1, 2);
+    expect(next).not.toBe(wts);
+    expect(ids(wts)).toEqual(['a', 'b', 'c']);
+    expect(ids(next)).toEqual(['a', 'c', 'b']);
+  });
+
+  test('no-op when source and target match', () => {
+    expect(ids(reorderWalkthroughs(wts, 1, 1))).toEqual(['a', 'b', 'c']);
+  });
+
+  test('out-of-range source returns a shallow copy unchanged', () => {
+    const next = reorderWalkthroughs(wts, 5, 0);
+    expect(next).not.toBe(wts);
+    expect(ids(next)).toEqual(['a', 'b', 'c']);
+  });
+
+  test('clamps a target beyond the end to the last slot', () => {
+    expect(ids(reorderWalkthroughs(wts, 0, 99))).toEqual(['b', 'c', 'a']);
+  });
+});
+
+describe('reorderTargetIndex', () => {
+  // Boundaries are the n+1 gaps between rows: 0 is above row 0, n is below
+  // the last row. Dragging row `from` to boundary `b` lands it at b, minus one
+  // when b is past from (removing the row shifts later gaps down).
+  test('dragging down past a row lands after it', () => {
+    expect(reorderTargetIndex(2, 0)).toBe(1);
+    expect(reorderTargetIndex(3, 0)).toBe(2);
+  });
+
+  test('dragging up lands at the boundary', () => {
+    expect(reorderTargetIndex(0, 2)).toBe(0);
+    expect(reorderTargetIndex(1, 2)).toBe(1);
+  });
+
+  test('the boundaries around the dragged row are no-ops', () => {
+    expect(reorderTargetIndex(1, 1)).toBe(1);
+    expect(reorderTargetIndex(2, 1)).toBe(1);
+  });
+
+  test('dropping the first row above itself is a no-op', () => {
+    expect(reorderTargetIndex(0, 0)).toBe(0);
+  });
+
+  test('composes with reorderWalkthroughs to match the indicator', () => {
+    const wts: SubsystemWalkthrough[] = [
+      { id: 'a', title: 'A', steps: [] },
+      { id: 'b', title: 'B', steps: [] },
+      { id: 'c', title: 'C', steps: [] },
+    ];
+    // Drag A onto the gap below B (boundary 2) → A lands between B and C.
+    const target = reorderTargetIndex(2, 0);
+    expect(reorderWalkthroughs(wts, 0, target).map((w) => w.id)).toEqual(['b', 'a', 'c']);
+  });
+});

package/src/subsystem/model.ts

@@ -349,6 +349,37 @@ export function walkthroughStepGraphEdgeId(
   return derivedGraphEdgeId(step.from, step.to, step.mechanism);
 }
 
+/**
+ * Move one walkthrough from `from` to `to`, returning a new array. Used by the
+ * flows panel's drag-to-reorder: the array order is the walkthroughs' display
+ * order, so a reorder is just an array splice. Out-of-range `from` returns a
+ * shallow copy unchanged; `to` is clamped into range.
+ */
+export function reorderWalkthroughs(
+  walkthroughs: readonly SubsystemWalkthrough[],
+  from: number,
+  to: number,
+): SubsystemWalkthrough[] {
+  const next = [...walkthroughs];
+  if (!Number.isInteger(from) || from < 0 || from >= next.length) return next;
+  const target = Math.max(0, Math.min(to, next.length - 1));
+  if (target === from) return next;
+  const [moved] = next.splice(from, 1);
+  if (moved) next.splice(target, 0, moved);
+  return next;
+}
+
+/**
+ * Final index for a drag-reorder given the insertion `boundary` (one of the
+ * `n + 1` gaps between rows) and the dragged row's `from` index. Removing the
+ * dragged row shifts every boundary after it down one, so a boundary past
+ * `from` maps to `boundary - 1`. Feed the result to `reorderWalkthroughs` as
+ * `to`; a result equal to `from` is a no-op.
+ */
+export function reorderTargetIndex(boundary: number, from: number): number {
+  return boundary - (boundary > from ? 1 : 0);
+}
+
 export function deriveGraphEdges(doc: {
   relations?: readonly SubsystemRelation[];
   walkthroughs?: readonly SubsystemWalkthrough[];