@bastani/atomic 0.9.12 → 0.9.13-alpha.2

package/dist/builtin/workflows/src/shared/store-types.ts

@@ -5,7 +5,7 @@
 
 import type { WorkflowExitStatus, WorkflowInputValues, WorkflowOutputValues } from "./types.js";
 
-export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus | "failed" | "killed";
+export type RunStatus = "pending" | "running" | "paused" | WorkflowExitStatus | "killed";
 export type StageStatus =
 	| "pending"
 	| "running"
@@ -261,8 +261,27 @@ export interface StageSnapshot {
 	pausedAt?: number;
 	/** Timestamp recorded on the most recent resume from a paused state. */
 	resumedAt?: number;
+	/** Who paused this stage. Set only by a deliberate control action. */
+	pauseActor?: WorkflowActor;
+	/** Who resumed this stage. Set only by a deliberate control action. */
+	resumeActor?: WorkflowActor;
 }
 
+/**
+ * Who performed a workflow lifecycle action. A run's `origin` answers "who
+ * launched it"; an actor on a pause, quit, or resume answers "who did this one
+ * thing". They differ routinely — the agent starts a run and the user quits it.
+ */
+export type WorkflowActor = "user" | "agent";
+
+/**
+ * Which code path resumed a run. Only `run_control` is a deliberate control
+ * action; the rest continue work already in progress — answering a
+ * human-in-the-loop prompt, per-stage control, and the acknowledgement pass —
+ * and must never be reported as a lifecycle event of their own.
+ */
+export type RunResumeSource = "run_control" | "prompt_answer" | "stage_control" | "acknowledgement";
+
 export interface RunSnapshot {
 	readonly id: string;
 	readonly name: string;
@@ -286,6 +305,21 @@ export interface RunSnapshot {
 	pausedAt?: number;
 	/** Timestamp when the run entered resumable quit state; display-only expiry marker. */
 	quitAt?: number;
+	/**
+	 * Who paused or quit this run, and who resumed it. A control path records
+	 * these; the engine's own pauses and resumes leave them unset, which is what
+	 * keeps an internal continuation from being reported as a user action.
+	 */
+	pauseActor?: WorkflowActor;
+	resumeActor?: WorkflowActor;
+	/** Which path performed the most recent resume. */
+	resumeSource?: RunResumeSource;
+	/**
+	 * Who launched this run. Set once at dispatch and inherited by a continuation
+	 * from the run it continues. Absent on legacy and restored runs that never
+	 * recorded it, in which case attribution is omitted rather than guessed.
+	 */
+	origin?: WorkflowActor;
 	/** Timestamp recorded on the most recent resume from a paused state. */
 	resumedAt?: number;
 	result?: WorkflowOutputValues;

package/dist/builtin/workflows/src/shared/timing.ts

@@ -19,6 +19,16 @@ interface RunTimerSnapshot {
 function nonNegative(ms: number): number {
 	return Math.max(0, ms);
 }
+/**
+ * Return an occurrence timestamp that remains ordered when a clock tick is
+ * shared by two deliberate control transitions. Lifecycle notice keys use
+ * these timestamps as occurrence identities, so a later transition must not
+ * reuse the prior transition's key.
+ */
+export function nextControlTimestamp(requestedAt: number | undefined, previousAt: number | undefined): number {
+	const candidate = requestedAt ?? Date.now();
+	return previousAt === undefined || candidate > previousAt ? candidate : previousAt + 1;
+}
 
 export function rebasedStageStartedAt(accumulatedDurationMs: number | undefined, resumedAt: number): number {
 	return resumedAt - nonNegative(accumulatedDurationMs ?? 0);

package/dist/builtin/workflows/src/shared/workflow-artifact-env.ts

@@ -0,0 +1,21 @@
+/**
+ * Leaf module: durable workflow-artifact constants with no imports.
+ *
+ * These values are plain data, but their previous home — `workflow-artifacts.ts`
+ * — sits atop roughly fifty modules including `@bastani/atomic` itself. Any
+ * consumer that wanted only a constant paid to transform that whole graph.
+ *
+ * `test/setup-workflow-durability.ts` is such a consumer, and vitest runs it
+ * once per test file, so every unit file transformed ten thousand lines to read
+ * one string. Keeping these constants importable without dependencies is what
+ * lets that setup stay cheap; `workflow-artifacts.ts` re-exports them, so this
+ * split is invisible to every existing caller.
+ *
+ * Keep this module dependency-free.
+ */
+
+/** Maximum age of durable workflow run artifacts before the next workflow write prunes them. */
+export const WORKFLOW_ARTIFACT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Overrides the durable workflow-artifact root, mirroring the agent-directory override convention. */
+export const ENV_WORKFLOW_ARTIFACT_DIR = "ATOMIC_WORKFLOW_ARTIFACT_DIR";

package/dist/builtin/workflows/src/shared/workflow-artifacts.ts

@@ -8,12 +8,9 @@ import { getDurableBackend } from "../durable/factory.js";
 import { type WorkflowRunResumeCandidate, workflowRunHasPausedState } from "../durable/resume-eligibility.js";
 import { store } from "./store.js";
 import type { RunSnapshot } from "./store-types.js";
+import { ENV_WORKFLOW_ARTIFACT_DIR, WORKFLOW_ARTIFACT_RETENTION_MS } from "./workflow-artifact-env.js";
 
-/** Maximum age of durable workflow run artifacts before the next workflow write prunes them. */
-export const WORKFLOW_ARTIFACT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
-
-/** Overrides the durable workflow-artifact root, mirroring the agent-directory override convention. */
-export const ENV_WORKFLOW_ARTIFACT_DIR = "ATOMIC_WORKFLOW_ARTIFACT_DIR";
+export { ENV_WORKFLOW_ARTIFACT_DIR, WORKFLOW_ARTIFACT_RETENTION_MS };
 
 export type WorkflowArtifactRunState = "protected" | "terminal" | "orphan";
 export type WorkflowArtifactRunStateResolver = (runId: string) => WorkflowArtifactRunState | undefined;

package/dist/builtin/workflows/src/tui/chat-surface-message.ts

@@ -27,6 +27,7 @@
 
 import type { ExtensionAPI } from "../extension/index.js";
 import type { RunDetail } from "../runs/background/status.js";
+import type { RunIndicatorStatus } from "../shared/run-indicator-status.js";
 import type { RunSnapshot } from "../shared/store-types.js";
 import type { WorkflowInputValues } from "../shared/types.js";
 import { renderDispatchConfirm } from "./dispatch-confirm.js";
@@ -67,6 +68,15 @@ export interface DispatchPayload {
 export interface StatusPayload {
 	kind: "status";
 	runs: readonly RunSnapshot[];
+	/**
+	 * Emit-time indicator status per visible run id, resolved against the
+	 * complete point-in-time run collection (including hidden nested
+	 * descendants). Persisted with the payload because chat entries are
+	 * re-rendered from `details` after a session restore, where the full
+	 * collection is gone; storing only the derived statuses keeps hidden
+	 * run snapshots out of the serialized message.
+	 */
+	indicatorStatuses?: Readonly<Record<string, RunIndicatorStatus>>;
 }
 
 /** Workflow catalogue after `/workflow list`. */
@@ -164,7 +174,12 @@ export function renderChatSurfacePlainText(
 			return [rendered, `run id: ${payload.runId}`, `inputs: ${formatPlainRecord(payload.inputs)}`].join("\n");
 		}
 		case "status": {
-			const rendered = renderStatusList(payload.runs, { width, now, ...themed });
+			const rendered = renderStatusList(payload.runs, {
+				width,
+				now,
+				...themed,
+				indicatorStatuses: payload.indicatorStatuses,
+			});
 			if (payload.runs.length === 0) return rendered;
 			return [
 				rendered,
@@ -288,7 +303,12 @@ function renderPayload(payload: ChatSurfacePayload, theme: GraphTheme, width: nu
 				width,
 			});
 		case "status":
-			return renderStatusList(payload.runs, { theme, width, now });
+			return renderStatusList(payload.runs, {
+				theme,
+				width,
+				now,
+				indicatorStatuses: payload.indicatorStatuses,
+			});
 		case "list":
 			return renderWorkflowList(payload.entries, { theme, width });
 		case "detail":

package/dist/builtin/workflows/src/tui/dispatch-confirm.ts

@@ -273,11 +273,45 @@ function renderInputsSegment(
 	};
 }
 
+/**
+ * Anything that would break a value out of its single card row.
+ *
+ * Card rows are spliced into a bordered box by `renderRoundedBox`, which pads
+ * each row to the interior width. A value carrying a literal newline emits a
+ * second physical line that no border ever wraps, destroying the box from that
+ * row down. `truncateToWidth` cannot save us: it measures *visible width*, and
+ * a control character has none, so a `\n` survives truncation intact.
+ *
+ * This is reachable from ordinary use — any multi-line workflow input (a
+ * `prompt`, an `acceptance_criteria` block) contains newlines by nature.
+ *
+ * Scoped to `\p{Cc}` (C0/C1 controls, so `\n`, `\r`, `\t`, and a stray ESC that
+ * would otherwise inject styling) plus the two separators `JSON.stringify` does
+ * *not* escape, which some terminals still break lines on. It deliberately does
+ * NOT cover all of `\p{Cf}`: that class includes U+200D ZERO WIDTH JOINER, and
+ * stripping it splits emoji sequences such as a family glyph into their
+ * components. A format character that occupies no cell cannot break a row, so
+ * removing it only corrupts the value the user asked to see.
+ */
+const ROW_BREAKING_RE = /[\p{Cc}\u2028\u2029]+/gu;
+
+/**
+ * Replace runs of row-breaking characters with a single space.
+ *
+ * Only the replaced runs collapse. Pre-existing spacing is left alone and the
+ * result is not trimmed, because a value's own leading, trailing, or repeated
+ * spaces are content: the card renders inside quotes, so `"  alpha   beta  "`
+ * should still read as what was passed rather than as `"alpha beta"`.
+ */
+function toSingleLine(value: string): string {
+	return value.replace(ROW_BREAKING_RE, " ");
+}
+
 function renderInputValue(value: unknown, budget: number): string {
 	if (typeof value === "string") {
 		// Reserve 2 cells for the surrounding quotes; truncate the interior.
 		const interior = Math.max(0, budget - 2);
-		const trimmed = truncateToWidth(value, interior, ELLIPSIS);
+		const trimmed = truncateToWidth(toSingleLine(value), interior, ELLIPSIS);
 		return `"${trimmed}"`;
 	}
 	if (typeof value === "number" || typeof value === "boolean") {
@@ -285,8 +319,9 @@ function renderInputValue(value: unknown, budget: number): string {
 	}
 	if (value === null) return "null";
 	// Objects / arrays — show a compact JSON projection within budget.
+	// JSON.stringify escapes \n as literal backslash-n, but not U+2028/U+2029.
 	const json = JSON.stringify(value);
-	return truncateToWidth(json ?? "", budget, ELLIPSIS);
+	return truncateToWidth(toSingleLine(json ?? ""), budget, ELLIPSIS);
 }
 
 /**

package/dist/builtin/workflows/src/tui/graph-view-constants.ts

@@ -17,20 +17,6 @@ export const COMPACT_HINT_KEYS: Array<{ key: string; label: string }> = [
  */
 export const MODE_PILL_LABEL = "GRAPH";
 
-/**
- * Fixed line count emitted by `_renderOverlay`. pi-tui paints the
- * overlay in the same buffer as the chat, so a *variable* line count
- * causes the chat to scroll every time the focused-stage section grows
- * or shrinks — that's exactly the duplicate-rows bug we hit when
- * navigating with j/k. Padding to a constant height keeps the overlay
- * a stable rectangle that pi-tui can diff cell-by-cell.
- *
- * Mirrors the doom-overlay reference extension, which always emits the
- * same number of lines per frame regardless of game state.
- */
-export const OVERLAY_LINE_COUNT = 32;
-export const OVERLAY_VERTICAL_MARGIN_ROWS = 1;
-
 /**
  * Animation tick period. Overlay re-renders fire on this cadence so
  * duration counters tick from active elapsed time (freezing while paused)
@@ -50,4 +36,3 @@ export const ANIMATION_TICK_MS = 100;
  */
 export const PULSE_PERIOD_MS = 2000;
 export const GRAPH_SCROLL_STEP_COLS = 4;
-export const GRAPH_SCROLL_STEP_ROWS = 4;

package/dist/builtin/workflows/src/tui/graph-view-graph-render.ts

@@ -1,3 +1,4 @@
+import type { RunSnapshot } from "../shared/store-types.js";
 import { hexBg, hexToAnsi, RESET } from "./color-utils.js";
 import { GraphCanvas } from "./graph-canvas.js";
 import { PULSE_PERIOD_MS } from "./graph-view-constants.js";
@@ -11,46 +12,51 @@ interface Placement {
 	line: string;
 }
 
-/** Graph body rendering and vertical/horizontal viewport management. */
+/** Graph body rendering and horizontal canvas management. */
 export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
-	protected _renderGraph(width: number): string[] {
-		const run = this._getCurrentRun();
+	protected _renderGraph(
+		width: number,
+		viewportTop: number,
+		viewportRows: number,
+		renderRun?: RunSnapshot | null,
+	): string[] {
+		const safeRows = Math.max(0, Math.floor(viewportRows));
+		const run = renderRun !== undefined ? renderRun : this._getCurrentRun();
 		if (!run || this.cachedLayout.length === 0) {
 			this.lastGraphViewport = null;
 			this.graphNodeHitRects = [];
-			this.lastGraphTotalRows = 1;
-			const dim = hexToAnsi(this.graphTheme.dim);
-			return [this._centerCanvasContent(`${dim}waiting for stage events…${RESET}`, width)];
+			this.lastGraphTopPad = 0;
+			this.lastGraphVisibleRows = safeRows;
+			const lines = Array.from({ length: safeRows }, () => "");
+			if (safeRows > 0) {
+				const dim = hexToAnsi(this.graphTheme.dim);
+				lines[Math.floor((safeRows - 1) / 2)] = this._centerCanvasContent(
+					`${dim}waiting for stage events…${RESET}`,
+					width,
+				);
+			}
+			return lines;
 		}
 
 		const graphInner = Math.max(1, width - 4);
 		const { canvasWidth, totalRows, bands, edges } = this.cachedRenderGeometry;
-		this.lastGraphTotalRows = totalRows;
 		const leftMargin = Math.max(2, canvasWidth <= graphInner ? Math.floor((graphInner - canvasWidth) / 2) : 2);
 		const viewportWidth = Math.max(1, width - leftMargin);
 		const fullCanvasWidth = Math.max(canvasWidth, viewportWidth);
 		this.lastGraphViewport = { leftMargin, viewportWidth };
-		this._clampGraphHorizontalScroll(fullCanvasWidth, viewportWidth);
-		if (this.pendingEnsureFocusedVisible) {
-			this._scrollFocusedColumnIntoView(viewportWidth, fullCanvasWidth);
-		}
-
-		const bodyRows = this._overlayBodyRows(this._overlayPanelLineCount());
-		if (totalRows > bodyRows) {
-			this._clampGraphScroll(totalRows, bodyRows);
-			if (this.pendingEnsureFocusedVisible) this._scrollFocusedIntoView(width, bodyRows, totalRows);
-			this._clampGraphScroll(totalRows, bodyRows);
-		} else {
-			this.graphScrollOffset = 0;
-		}
 
-		const viewportTop = this.graphScrollOffset;
-		const viewportBottom = Math.min(totalRows, viewportTop + bodyRows);
+		const safeTop = Math.max(0, Math.min(totalRows, Math.floor(viewportTop)));
+		const graphRows = Math.max(0, Math.min(safeRows, totalRows - safeTop));
+		const viewportBottom = safeTop + graphRows;
+		this._clampGraphHorizontalScroll(fullCanvasWidth, viewportWidth);
+		const topPad = safeTop === 0 && totalRows <= safeRows ? Math.min(3, Math.floor((safeRows - totalRows) / 2)) : 0;
+		this.lastGraphTopPad = topPad;
+		this.lastGraphVisibleRows = graphRows;
 		const viewportLeft = this.graphScrollColOffset;
 		const viewportRight = viewportLeft + viewportWidth;
 		const pulsePhase = (Date.now() % PULSE_PERIOD_MS) / PULSE_PERIOD_MS;
 		const edgeCanvas = new GraphCanvas({
-			top: viewportTop,
+			top: safeTop,
 			bottom: viewportBottom,
 			left: viewportLeft,
 			right: viewportRight,
@@ -58,7 +64,7 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
 		const edgeColor = this.graphTheme.borderDim;
 		for (const edge of edges) {
 			if (
-				edge.bottom <= viewportTop ||
+				edge.bottom <= safeTop ||
 				edge.top >= viewportBottom ||
 				edge.right <= viewportLeft ||
 				edge.left >= viewportRight
@@ -69,7 +75,7 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
 		}
 		const edgeLines = edgeCanvas.toLines();
 		const placements = new Map<number, Placement[]>();
-		for (let bandIndex = this._firstVisibleLayoutBand(viewportTop); bandIndex < bands.length; bandIndex++) {
+		for (let bandIndex = this._firstVisibleLayoutBand(safeTop); bandIndex < bands.length; bandIndex++) {
 			const band = bands[bandIndex]!;
 			if (band.top >= viewportBottom) break;
 			for (const ni of band.nodeIndices) {
@@ -88,8 +94,8 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
 				const visibleRight = Math.min(node.x + NODE_W, viewportRight);
 				for (let li = 0; li < cardLines.length; li++) {
 					const globalRow = node.y + li;
-					if (globalRow < viewportTop || globalRow >= viewportBottom) continue;
-					const localRow = globalRow - viewportTop;
+					if (globalRow < safeTop || globalRow >= viewportBottom) continue;
+					const localRow = globalRow - safeTop;
 					let bucket = placements.get(localRow);
 					if (!bucket) {
 						bucket = [];
@@ -106,10 +112,10 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
 
 		const bg = hexBg(this.graphTheme.bg);
 		const leftPad = `${bg}${" ".repeat(leftMargin)}${RESET}`;
-		const composed: string[] = [];
-		for (let localRow = 0; localRow < viewportBottom - viewportTop; localRow++) {
+		const composed = Array.from({ length: safeRows }, () => "");
+		for (let localRow = 0; localRow < graphRows; localRow++) {
 			const line = this._composeRow(edgeLines[localRow] ?? "", placements.get(localRow) ?? [], edgeColor);
-			composed.push(`${leftPad}${this._padCanvas(line, viewportWidth)}`);
+			composed[topPad + localRow] = `${leftPad}${this._padCanvas(line, viewportWidth)}`;
 		}
 		return composed;
 	}
@@ -126,8 +132,8 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
 		const viewportLeft = viewport.leftMargin;
 		const viewportRight = viewport.leftMargin + viewport.viewportWidth;
 		const rects: typeof this.graphNodeHitRects = [];
-		const viewportTop = this.graphScrollOffset;
-		const viewportBottom = viewportTop + visibleRowCount;
+		const viewportTop = this._graphScrollTop();
+		const viewportBottom = Math.min(this.cachedRenderGeometry.totalRows, viewportTop + visibleRowCount);
 		const { bands } = this.cachedRenderGeometry;
 		for (let bandIndex = this._firstVisibleLayoutBand(viewportTop); bandIndex < bands.length; bandIndex++) {
 			const band = bands[bandIndex]!;
@@ -148,19 +154,4 @@ export abstract class GraphViewGraphRenderer extends GraphViewRenderHelpers {
 		}
 		this.graphNodeHitRects = rects;
 	}
-
-	protected _visibleGraphLines(
-		graphLines: string[],
-		_frameWidth: number,
-		bodyRows: number,
-	): { lines: string[]; topPad: number } {
-		this.pendingEnsureFocusedVisible = false;
-		return {
-			lines: graphLines,
-			topPad:
-				this.lastGraphTotalRows <= bodyRows
-					? Math.min(3, Math.max(0, Math.floor((bodyRows - this.lastGraphTotalRows) / 2)))
-					: 0,
-		};
-	}
 }

package/dist/builtin/workflows/src/tui/graph-view-input.ts

@@ -1,4 +1,4 @@
-import { GRAPH_SCROLL_STEP_COLS, GRAPH_SCROLL_STEP_ROWS } from "./graph-view-constants.js";
+import { GRAPH_SCROLL_STEP_COLS } from "./graph-view-constants.js";
 import { GraphViewRenderer } from "./graph-view-render.js";
 import { isKeybindingsLike, type KeybindingsLike } from "./keybindings-adapter.js";
 import { isTerminalLeftMousePress, parseTerminalMouseInput, terminalMouseWheelDirection } from "./mouse-input.js";
@@ -11,6 +11,8 @@ interface MouseWheelDelta {
 	rows: number;
 }
 
+const GRAPH_SCROLL_WHEEL_LINES = 4;
+
 /** Keyboard, mouse, switcher, prompt, and focus navigation handling. */
 export abstract class GraphViewInputController extends GraphViewRenderer {
 	/** Returns true if consumed. */
@@ -19,22 +21,17 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
 			this._returnToMainChat();
 			return true;
 		}
-		if (this.switcherOpen) {
-			return this._handleSwitcherInput(data);
-		}
+		if (this.graphLayout.isScrollbarInput(data)) return this._handleGraphInput(data);
+		if (this.switcherOpen) return this._handleSwitcherInput(data);
+		const wheelDelta = this._mouseWheelDelta(data);
+		if (wheelDelta) return this._handleWheelDelta(wheelDelta);
 		// Stage-local HIL is represented by graph nodes and remains graph-first;
 		// only the legacy run-level prompt card sets `promptState`. Keep that
-		// fallback answerable, but let a narrow set of non-text graph controls
-		// through first so the workflow overlay can still be detached or scrolled
-		// instead of feeling modal while a prompt is visible. Printable keys such
-		// as "/" belong to the prompt card while legacy run-level text/editor
-		// prompts own input.
-		if (this.promptState) {
-			if (this._isNonTextGraphControlBeforePrompt(data)) {
-				return this._handleGraphInput(data);
-			}
-			return this._handlePromptInput(data);
-		}
+		// fallback answerable, but let the scrollbar and wheel controls above
+		// continue to belong to the graph instead of leaking to the transcript.
+		// Printable keys such as "/" belong to the prompt card while legacy
+		// run-level text/editor prompts own input.
+		if (this.promptState) return this._handlePromptInput(data);
 		return this._handleGraphInput(data);
 	}
 
@@ -42,10 +39,6 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
 		return isKeybindingsLike(this.piKeybindings) ? this.piKeybindings : undefined;
 	}
 
-	private _isNonTextGraphControlBeforePrompt(data: string): boolean {
-		return this._mouseWheelDelta(data) !== null;
-	}
-
 	private _isReturnToMainChatInput(data: string): boolean {
 		return matchesKey(data, Key.ctrl("x"));
 	}
@@ -83,12 +76,12 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
 
 	private _handleGraphInput(data: string): boolean {
 		const stageCount = this.cachedLayout.length;
-		const wheelDelta = this._mouseWheelDelta(data);
-		if (wheelDelta) {
-			if (wheelDelta.rows !== 0) this._scrollGraphBy(wheelDelta.rows);
-			if (wheelDelta.cols !== 0) this._scrollGraphHorizontallyBy(wheelDelta.cols);
+		if (this.graphLayout.handleScrollbarInput(data)) {
+			this.pendingEnsureFocusedVisible = false;
 			return true;
 		}
+		const wheelDelta = this._mouseWheelDelta(data);
+		if (wheelDelta) return this._handleWheelDelta(wheelDelta);
 
 		const clickedNodeIndex = this._graphNodeIndexForClick(data);
 		if (clickedNodeIndex !== undefined) {
@@ -168,21 +161,13 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
 			this.switcherOpen = false;
 			return true;
 		}
-		if (matchesKey(data, Key.down)) {
-			const filtered = filterStages(stages, this.switcherState.query);
-			this.switcherState = {
-				...this.switcherState,
-				selectedIndex: Math.min(this.switcherState.selectedIndex + 1, filtered.length - 1),
-			};
-			return true;
-		}
-		if (matchesKey(data, Key.up)) {
-			this.switcherState = {
-				...this.switcherState,
-				selectedIndex: Math.max(this.switcherState.selectedIndex - 1, 0),
-			};
-			return true;
-		}
+		const wheelEvent = parseTerminalMouseInput(data);
+		const wheelDirection = wheelEvent ? terminalMouseWheelDirection(wheelEvent) : null;
+		if (wheelDirection === "down") return this._moveSwitcherSelection(1);
+		if (wheelDirection === "up") return this._moveSwitcherSelection(-1);
+		if (wheelDirection !== null) return true;
+		if (matchesKey(data, Key.down)) return this._moveSwitcherSelection(1);
+		if (matchesKey(data, Key.up)) return this._moveSwitcherSelection(-1);
 		if (matchesKey(data, Key.backspace)) {
 			this.switcherState = {
 				query: this.switcherState.query.slice(0, -1),
@@ -200,6 +185,17 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
 		return false;
 	}
 
+	private _moveSwitcherSelection(step: number): boolean {
+		const stages = this.cachedLayout.map((layoutNode) => layoutNode.stage);
+		const filtered = filterStages(stages, this.switcherState.query);
+		const maxIndex = Math.max(0, filtered.length - 1);
+		this.switcherState = {
+			...this.switcherState,
+			selectedIndex: Math.max(0, Math.min(this.switcherState.selectedIndex + step, maxIndex)),
+		};
+		return true;
+	}
+
 	/**
 	 * Move focus to the nearest node `step` depth-levels away (↑/↓).
 	 * Picks the sibling with the closest `row` to the current node so
@@ -268,10 +264,15 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
 		this.focusedIndex = next;
 		this.pendingEnsureFocusedVisible = true;
 	}
-
-	private _scrollGraphBy(deltaRows: number): void {
+	private _scrollGraphVertically(deltaRows: number): void {
 		this.pendingEnsureFocusedVisible = false;
-		this.graphScrollOffset = Math.max(0, this.graphScrollOffset + deltaRows);
+		this.graphLayout.scrollView.scrollBy(deltaRows);
+	}
+
+	private _handleWheelDelta(delta: MouseWheelDelta): boolean {
+		if (delta.rows !== 0) this._scrollGraphVertically(delta.rows);
+		if (delta.cols !== 0) this._scrollGraphHorizontallyBy(delta.cols);
+		return true;
 	}
 
 	private _scrollGraphHorizontallyBy(deltaCols: number): void {
@@ -292,7 +293,6 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
 		}
 		return null;
 	}
-
 	private _sgrLeftMousePress(data: string): { col: number; row: number } | null {
 		const event = parseTerminalMouseInput(data);
 		if (event?.protocol !== "sgr" || !isTerminalLeftMousePress(event)) return null;
@@ -303,12 +303,15 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
 		const event = parseTerminalMouseInput(data);
 		if (!event) return null;
 		const direction = terminalMouseWheelDirection(event);
-		if (direction === "up") return { cols: 0, rows: -GRAPH_SCROLL_STEP_ROWS };
-		if (direction === "down") return { cols: 0, rows: GRAPH_SCROLL_STEP_ROWS };
+		if (direction === "up") return { cols: 0, rows: -GRAPH_SCROLL_WHEEL_LINES };
+		if (direction === "down") return { cols: 0, rows: GRAPH_SCROLL_WHEEL_LINES };
 		if (direction === "left") return { cols: -GRAPH_SCROLL_STEP_COLS, rows: 0 };
 		if (direction === "right") return { cols: GRAPH_SCROLL_STEP_COLS, rows: 0 };
 		return null;
 	}
+	get _graphScrollbarGeometry() {
+		return this.graphLayout.scrollbarGeometry;
+	}
 
 	// ---- test seams ----
 	get _focusedIndex(): number {
@@ -321,7 +324,7 @@ export abstract class GraphViewInputController extends GraphViewRenderer {
 		return this.switcherState;
 	}
 	get _graphScrollOffset(): number {
-		return this.graphScrollOffset;
+		return this._graphScrollTop();
 	}
 	get _graphScrollColOffset(): number {
 		return this.graphScrollColOffset;