feat(v7-h03): undo/redo for spec mutations (Cmd/Ctrl+Z)

Closes V7-H03 (cppmega-mlx-cobb): bounded undo/redo for the canvas
state (nodes + edges + spec triple) with TopBar buttons + keyboard
shortcuts.

New hook vbgui/src/hooks/useHistory.ts:
  - useHistory<T>(capacity=50) → { push, undo, redo, canUndo,
    canRedo, size, clear }.
  - Past stack capped at capacity; oldest entry drops on overflow.
  - Redo stack cleared on push (linear-undo semantics).
  - undo() returns the snapshot BEFORE the popped one; redo()
    returns the snapshot popped by undo.

App.tsx integration:
  - History captures (nodes, edges, spec) on every verify-trigger
    key change (same set of user-meaningful mutations).
  - suppressNextHistoryPushRef avoids the "applying undo registers
    as a new mutation" feedback loop (otherwise redo stack would
    be cleared immediately after undo).
  - Cmd/Ctrl+Z = undo, Shift+Cmd/Ctrl+Z = redo. Skipped inside
    text inputs so typing isn't intercepted.

TopBar:
  - top-bar-undo / top-bar-redo buttons render only when callbacks
    provided (default existing TopBar tests unaffected); disabled
    when !canUndo/!canRedo.

Tests:
  - vbgui vitest useHistory.test.tsx: 7/7 — initial state, push
    grows, undo returns prev + enables redo, redo replays, push
    after undo clears redo, capacity bounds, clear resets.
  - vbgui vitest full suite: 220/220 passing.
  - vbgui e2e 78_undo_redo.spec.ts: 1/1 — preset drop → undo
    reduces canvas brick count → redo restores.
  - vbgui e2e regression (01_canvas_smoke + 55 + 63): 8/8 passing.

Author: apstenku123

vbgui/e2e/scenarios/78_undo_redo.spec.ts

@@ -0,0 +1,41 @@
+// V7-H03: undo/redo through TopBar buttons + canvas state.
+//
+// Drop a preset → verify canvas has bricks → click Undo → assert
+// fewer bricks (or none) → click Redo → assert bricks back.
+
+import { test, expect } from "@playwright/test";
+import { gotoApp, selectPreset } from "../fixtures";
+
+test("V7-H03: Undo after preset drop reduces canvas; Redo restores",
+  async ({ page }) => {
+    test.setTimeout(60_000);
+    await gotoApp(page);
+
+    // Pre-state: canvas empty, both buttons disabled.
+    await expect(page.getByTestId("top-bar-undo")).toBeDisabled();
+    await expect(page.getByTestId("top-bar-redo")).toBeDisabled();
+
+    await selectPreset(page, "llama3_8b");
+    // After preset drop, canvas has bricks.
+    const before = await page.locator(
+      "[data-testid^='brick-node-']").count();
+    expect(before).toBeGreaterThan(0);
+
+    // Undo should now be enabled (we have >=2 history entries:
+    // initial empty + post-preset).
+    await expect.poll(async () =>
+      await page.getByTestId("top-bar-undo").isEnabled(),
+      { timeout: 5_000 }).toBe(true);
+
+    await page.getByTestId("top-bar-undo").click();
+    await expect.poll(async () =>
+      await page.locator("[data-testid^='brick-node-']").count(),
+      { timeout: 5_000 }).toBeLessThan(before);
+
+    // Redo restores the brick count.
+    await expect(page.getByTestId("top-bar-redo")).toBeEnabled();
+    await page.getByTestId("top-bar-redo").click();
+    await expect.poll(async () =>
+      await page.locator("[data-testid^='brick-node-']").count(),
+      { timeout: 5_000 }).toBe(before);
+  });

vbgui/src/App.tsx

@@ -22,6 +22,7 @@ import {
   INITIAL_SPEC, specReducer, type SpecState, type TopologyFactory,
 } from "@/state/spec";
 import { migrate } from "@/state/migrations";
+import { useHistory } from "@/hooks/useHistory";
 import type { ShardingProposalView } from "@/components/sidebar/ShardingTab";
 
 // PRESETS list is now fetched dynamically from the backend via
@@ -90,6 +91,18 @@ export function App(): JSX.Element {
   const [projectName, setProjectName] = useState("untitled");
   const [proposals, setProposals] = useState<ShardingProposalView[]>([]);
   const [spec, dispatch] = useReducer(specReducer, INITIAL_SPEC);
+  // V7-H03: bounded undo/redo. Snapshot is the (nodes, edges, spec)
+  // triple captured on every Verify cycle (cheap proxy for any
+  // user-meaningful mutation that landed). Undo/redo restore the
+  // snapshot triple in one shot.
+  const history = useHistory<{ nodes: Node[]; edges: Edge[];
+                                spec: SpecState }>(50);
+  const lastHistoryKeyRef = useRef<string>("");
+  // V7-H03: when undo/redo applies a snapshot back, the resulting
+  // state-change effect would otherwise push that snapshot AGAIN
+  // and clear the redo stack. This ref lets the apply-path skip
+  // the next push.
+  const suppressNextHistoryPushRef = useRef<boolean>(false);
   const [activeTab, setActiveTab] = useState<AppTab>("canvas");
   const [runReport, setRunReport] = useState<RunReport | null>(null);
   const [runError, setRunError] = useState<string | null>(null);
@@ -211,6 +224,57 @@ export function App(): JSX.Element {
             rewriterKey, sideChannelKey, availableSideChannelKey,
             scheduleVerify]);
 
+  // V7-H03: snapshot the (nodes, edges, spec) triple every time a
+  // structural key changes — that's the same set of user-meaningful
+  // mutations the verify debouncer reacts to.
+  useEffect(() => {
+    const key = `${nodesKey}|${edgesKey}|${lossKey}|${optimKey}|`
+      + `${shardingKey}|${rewriterKey}|${sideChannelKey}`;
+    if (key === lastHistoryKeyRef.current) return;
+    lastHistoryKeyRef.current = key;
+    if (suppressNextHistoryPushRef.current) {
+      suppressNextHistoryPushRef.current = false;
+      return;
+    }
+    history.push({ nodes, edges, spec });
+  }, [nodesKey, edgesKey, lossKey, optimKey, shardingKey,
+      rewriterKey, sideChannelKey, history, nodes, edges, spec]);
+
+  const handleUndo = useCallback(() => {
+    const prev = history.undo();
+    if (prev) {
+      suppressNextHistoryPushRef.current = true;
+      setNodes(prev.nodes);
+      setEdges(prev.edges);
+      dispatch({ type: "spec.replace", spec: prev.spec });
+    }
+  }, [history]);
+  const handleRedo = useCallback(() => {
+    const nxt = history.redo();
+    if (nxt) {
+      suppressNextHistoryPushRef.current = true;
+      setNodes(nxt.nodes);
+      setEdges(nxt.edges);
+      dispatch({ type: "spec.replace", spec: nxt.spec });
+    }
+  }, [history]);
+
+  // V7-H03: Cmd/Ctrl+Z = undo, Shift+Cmd/Ctrl+Z = redo.
+  useEffect(() => {
+    function onKey(ev: KeyboardEvent) {
+      const meta = ev.metaKey || ev.ctrlKey;
+      if (!meta || ev.key.toLowerCase() !== "z") return;
+      // Don't intercept inside text inputs.
+      const tag = (ev.target as HTMLElement | null)?.tagName ?? "";
+      if (tag === "INPUT" || tag === "TEXTAREA") return;
+      ev.preventDefault();
+      if (ev.shiftKey) handleRedo();
+      else handleUndo();
+    }
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [handleUndo, handleRedo]);
+
   // ----- Handlers ----------------------------------------------------------
 
   const handleDropBrick = useCallback(
@@ -459,6 +523,10 @@ export function App(): JSX.Element {
           trainInFlight={trainInFlight}
           trainRunId={trainRunId}
           onCancelTrain={handleCancelTrain}
+          onUndo={handleUndo}
+          onRedo={handleRedo}
+          canUndo={history.canUndo}
+          canRedo={history.canRedo}
           onMixedPrecisionChange={(enabled) => dispatch({ type: "optim.set",
             optim: { ...spec.optim, mixed_precision: enabled } })}
           onFp8EnabledChange={(enabled) => dispatch({ type: "sharding.set",

vbgui/src/components/TopBar.tsx

@@ -23,6 +23,12 @@ export interface TopBarProps {
   /** H02: toggle callbacks. */
   onMixedPrecisionChange?: (enabled: boolean) => void;
   onFp8EnabledChange?: (enabled: boolean) => void;
+  /** V7-H03 undo/redo controls. Buttons render only when callbacks
+   *  provided so unit tests for default TopBar are unaffected. */
+  onUndo?: () => void;
+  onRedo?: () => void;
+  canUndo?: boolean;
+  canRedo?: boolean;
   /** H03: cancel the currently in-flight Train run. */
   trainInFlight?: boolean;
   trainRunId?: string | null;
@@ -110,6 +116,18 @@ export function TopBar(p: TopBarProps): JSX.Element {
         </label>
       )}
 
+      {p.onUndo && (
+        <button data-testid="top-bar-undo"
+                onClick={p.onUndo}
+                disabled={!p.canUndo}
+                title="Undo (Cmd/Ctrl+Z)">↶</button>
+      )}
+      {p.onRedo && (
+        <button data-testid="top-bar-redo"
+                onClick={p.onRedo}
+                disabled={!p.canRedo}
+                title="Redo (Shift+Cmd/Ctrl+Z)">↷</button>
+      )}
       {p.onSaveSpec && (
         <button data-testid="spec-save" onClick={p.onSaveSpec}>Save</button>
       )}

vbgui/src/hooks/useHistory.ts

@@ -0,0 +1,72 @@
+// V7-H03: bounded undo/redo stack for spec mutations.
+//
+// Generic over the snapshot shape. The caller (App) is responsible for
+// pushing a snapshot every time a user-visible mutation lands and for
+// applying the snapshot returned by undo/redo back into its reducers.
+//
+// History capacity defaults to 50 entries. Pushing past the cap drops
+// the oldest snapshot. Redo stack is cleared on every push (the
+// classic linear-undo semantics — once the user branches off, the
+// forward history is gone).
+
+import { useCallback, useRef, useState } from "react";
+
+export interface HistoryAPI<T> {
+  push: (snapshot: T) => void;
+  undo: () => T | null;
+  redo: () => T | null;
+  canUndo: boolean;
+  canRedo: boolean;
+  size: number;
+  clear: () => void;
+}
+
+export function useHistory<T>(capacity = 50): HistoryAPI<T> {
+  const past = useRef<T[]>([]);
+  const future = useRef<T[]>([]);
+  // setVersion bumps to force re-renders when canUndo/canRedo change.
+  const [, setVersion] = useState(0);
+
+  const push = useCallback((snapshot: T) => {
+    past.current.push(snapshot);
+    if (past.current.length > capacity) past.current.shift();
+    future.current = [];
+    setVersion((v) => v + 1);
+  }, [capacity]);
+
+  const undo = useCallback((): T | null => {
+    const top = past.current.pop();
+    if (top === undefined) return null;
+    future.current.push(top);
+    setVersion((v) => v + 1);
+    // Caller should reset to the PREVIOUS snapshot — the one before
+    // the popped state. If we want classic undo (restore previous),
+    // peek the now-top after pop.
+    const prev = past.current[past.current.length - 1];
+    return prev ?? null;
+  }, []);
+
+  const redo = useCallback((): T | null => {
+    const next = future.current.pop();
+    if (next === undefined) return null;
+    past.current.push(next);
+    setVersion((v) => v + 1);
+    return next;
+  }, []);
+
+  const clear = useCallback(() => {
+    past.current = [];
+    future.current = [];
+    setVersion((v) => v + 1);
+  }, []);
+
+  return {
+    push,
+    undo,
+    redo,
+    canUndo: past.current.length > 1,  // need at least 2 entries to undo
+    canRedo: future.current.length > 0,
+    size: past.current.length,
+    clear,
+  };
+}

vbgui/tests/useHistory.test.tsx

@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useHistory } from "@/hooks/useHistory";
+
+describe("V7-H03 useHistory", () => {
+  it("starts with no undo / no redo", () => {
+    const { result } = renderHook(() => useHistory<number>());
+    expect(result.current.canUndo).toBe(false);
+    expect(result.current.canRedo).toBe(false);
+    expect(result.current.size).toBe(0);
+  });
+
+  it("push grows the size and enables undo after >=2 entries", () => {
+    const { result } = renderHook(() => useHistory<number>());
+    act(() => { result.current.push(1); });
+    expect(result.current.canUndo).toBe(false);
+    act(() => { result.current.push(2); });
+    expect(result.current.canUndo).toBe(true);
+    expect(result.current.size).toBe(2);
+  });
+
+  it("undo returns the previous snapshot and enables redo", () => {
+    const { result } = renderHook(() => useHistory<number>());
+    act(() => { result.current.push(10); });
+    act(() => { result.current.push(20); });
+    act(() => { result.current.push(30); });
+    let prev: number | null = null;
+    act(() => { prev = result.current.undo(); });
+    expect(prev).toBe(20);
+    expect(result.current.canRedo).toBe(true);
+  });
+
+  it("redo replays the snapshot popped by undo", () => {
+    const { result } = renderHook(() => useHistory<number>());
+    act(() => { result.current.push(1); });
+    act(() => { result.current.push(2); });
+    act(() => { result.current.push(3); });
+    act(() => { result.current.undo(); });    // pop 3, prev=2
+    let nxt: number | null = null;
+    act(() => { nxt = result.current.redo(); });
+    expect(nxt).toBe(3);
+  });
+
+  it("new push after undo clears redo stack (linear semantics)", () => {
+    const { result } = renderHook(() => useHistory<number>());
+    act(() => { result.current.push(1); });
+    act(() => { result.current.push(2); });
+    act(() => { result.current.undo(); });
+    expect(result.current.canRedo).toBe(true);
+    act(() => { result.current.push(99); });
+    expect(result.current.canRedo).toBe(false);
+  });
+
+  it("capacity bounds the past stack", () => {
+    const { result } = renderHook(() => useHistory<number>(3));
+    act(() => { result.current.push(1); });
+    act(() => { result.current.push(2); });
+    act(() => { result.current.push(3); });
+    act(() => { result.current.push(4); });
+    expect(result.current.size).toBe(3);  // 1 was dropped
+  });
+
+  it("clear resets both stacks", () => {
+    const { result } = renderHook(() => useHistory<number>());
+    act(() => { result.current.push(1); });
+    act(() => { result.current.push(2); });
+    act(() => { result.current.clear(); });
+    expect(result.current.canUndo).toBe(false);
+    expect(result.current.canRedo).toBe(false);
+    expect(result.current.size).toBe(0);
+  });
+});