feat(maestro): port preview mode to React (#251)

Extends layoutStore with previewSession/commitPreview, mirroring
multiview.ts's preview controller: a throwaway tab for a session no pane
holds, byte-for-byte restore on end, and every real layout-changing action
drops an active preview first. Never schedules a save while a preview is up.

Adds usePreview, wrapping the store actions with previewSchedule.ts's
120ms leading-edge throttle, plus a touch guard and an immediate `end()`
for real changes. MultiView/TabBar render the preview hue on the pane
titlebar, canvas ring/chip, and the throwaway tab (dashed, unclickable).
This commit is contained in:
Miguel Palhas
2026-09-09 01:39:05 +01:00
parent e9e98e0c49
commit ea8c42bfb2
7 changed files with 613 additions and 13 deletions
+174
View File
@@ -0,0 +1,174 @@
// @vitest-environment happy-dom
import { act, cleanup, render } from "@testing-library/react";
import { afterEach, describe, expect, it, vi } from "vitest";
import { leaves } from "../layout.js";
import { createLayoutStore, type LayoutStoreApi } from "../stores/layoutStore.js";
import { usePreview, type UsePreviewResult } from "./usePreview.js";
function fakeScheduler() {
const timers = new Map<number, () => void>();
let id = 0;
return {
scheduler: {
setTimer: (fn: () => void) => {
const h = ++id;
timers.set(h, fn);
return h;
},
clearTimer: (h: number) => {
timers.delete(h);
},
},
flush() {
for (const fn of [...timers.values()]) fn();
timers.clear();
},
};
}
/** Hand-driven clock + timer queue for the preview schedule's own throttle,
* independent of the store's save-debounce scheduler above. */
function fakeClock() {
let now = 1_000;
const timers = new Map<number, { at: number; fn: () => void }>();
let handle = 1;
return {
now: () => now,
setTimer: (fn: () => void, ms: number) => {
const h = handle++;
timers.set(h, { at: now + ms, fn });
return h;
},
clearTimer: (h: number) => {
timers.delete(h);
},
advance(ms: number) {
now += ms;
for (const [h, t] of [...timers]) {
if (t.at <= now) {
timers.delete(h);
act(() => t.fn());
}
}
},
};
}
function newStore(): LayoutStoreApi {
return createLayoutStore({ load: () => null, save: vi.fn(), scheduler: fakeScheduler().scheduler });
}
let controls: UsePreviewResult;
function Probe({ store, clock }: { store: LayoutStoreApi; clock: ReturnType<typeof fakeClock> }) {
controls = usePreview({
store,
scheduleDeps: { now: clock.now, setTimer: clock.setTimer, clearTimer: clock.clearTimer },
});
return <div>{controls.previewedSessionId ?? "none"}</div>;
}
afterEach(cleanup);
describe("usePreview", () => {
it("shows the first preview immediately — no settling delay", () => {
const store = newStore();
store.getState().openSession("s1");
const clock = fakeClock();
const view = render(<Probe store={store} clock={clock} />);
act(() => controls.preview("s9"));
expect(view.container.textContent).toBe("s9");
expect(leaves(store.getState().layout.tabs[1]?.root ?? null).map((l) => l.sessionId)).toEqual(["s9"]);
});
it("throttles a burst to one leading + one trailing pane swap", () => {
const store = newStore();
store.getState().openSession("s1");
const clock = fakeClock();
const view = render(<Probe store={store} clock={clock} />);
act(() => {
controls.preview("s1");
controls.preview("s8");
controls.preview("s9");
});
expect(view.container.textContent).toBe("s1");
clock.advance(120);
expect(view.container.textContent).toBe("s9");
});
it("touch never previews", () => {
const store = newStore();
store.getState().openSession("s1");
const clock = fakeClock();
const view = render(<Probe store={store} clock={clock} />);
act(() => controls.previewFromPointer("s9", "touch"));
expect(view.container.textContent).toBe("none");
expect(store.getState().preview).toBeNull();
});
it("previewFromPointer still previews for mouse/pen", () => {
const store = newStore();
store.getState().openSession("s1");
const clock = fakeClock();
const view = render(<Probe store={store} clock={clock} />);
act(() => controls.previewFromPointer("s9", "mouse"));
expect(view.container.textContent).toBe("s9");
});
it("commit cancels a pending trailing preview and opens for real", () => {
const store = newStore();
store.getState().openSession("s1");
const clock = fakeClock();
const view = render(<Probe store={store} clock={clock} />);
act(() => {
controls.preview("s1"); // leading edge: previews the already-open s1
controls.preview("s9"); // queued, gap not elapsed yet
controls.commit("s9");
});
expect(view.container.textContent).toBe("none"); // committed: no longer a preview
expect(leaves(store.getState().layout.tabs[0].root).map((l) => l.sessionId)).toEqual(["s9"]);
clock.advance(120);
// The cancelled trailing preview never fires.
expect(view.container.textContent).toBe("none");
});
it("end drops a preview immediately, bypassing the throttle", () => {
const store = newStore();
store.getState().openSession("s1");
const clock = fakeClock();
const view = render(<Probe store={store} clock={clock} />);
act(() => controls.preview("s9"));
expect(view.container.textContent).toBe("s9");
act(() => controls.end());
expect(view.container.textContent).toBe("none");
expect(store.getState().layout.tabs).toHaveLength(1);
});
it("cancels its pending trailing preview on unmount", () => {
const store = newStore();
store.getState().openSession("s1");
store.getState().addTab();
store.getState().openSession("s2"); // leading edge below will preview this, already on screen
const clock = fakeClock();
const view = render(<Probe store={store} clock={clock} />);
act(() => {
controls.preview("s2"); // leading edge: fires now
controls.preview("s9"); // queued trailing preview
});
expect(store.getState().preview?.sessionId).toBe("s2");
view.unmount();
clock.advance(120);
// The queued trailing preview must not fire after unmount.
expect(store.getState().preview?.sessionId).toBe("s2");
});
});
+81
View File
@@ -0,0 +1,81 @@
// React port of previewSchedule.ts + multiview.ts's preview controller
// (issue #251). Owns the throttled schedule, hands the layout store the
// throttled result, and exposes the three ways a preview ends for real —
// see docs/PREVIEW.md, the contract this mirrors.
import { useCallback, useEffect, useRef } from "react";
import { useStore } from "zustand";
import { createPreviewSchedule, type PreviewScheduleDeps } from "../previewSchedule.js";
import type { LayoutStore, LayoutStoreApi } from "../stores/layoutStore.js";
import type { Uuid } from "../types.js";
export interface UsePreviewOptions {
store: LayoutStoreApi;
/** Test seam for the schedule's clock/timers. */
scheduleDeps?: PreviewScheduleDeps;
}
export interface UsePreviewResult {
/** The session currently shown as a preview, or null. */
previewedSessionId: Uuid | null;
/** Throttled: show `sessionId` in the content pane, or `null` to put back
* whatever was on screen (a highlight move, or the highlight leaving
* every session). Never delayed on the leading edge. */
preview(sessionId: Uuid | null): void;
/** Pointer-hover entry point: touch has no hover, so a touch pointer never
* previews (docs/PREVIEW.md). */
previewFromPointer(sessionId: Uuid | null, pointerType: string): void;
/** Choosing the previewed session — click/Enter on its row, click into its
* pane, or handing it the keyboard (Tab). Keeps exactly what is on
* screen: a throwaway tab becomes real, a focus move inside an existing
* tab stands. Nothing moves a second time. */
commit(sessionId: Uuid): void;
/** Any other real change — opening the command bar, a dialog, navigating
* away — ends a pending or active preview immediately, bypassing the
* throttle. */
end(): void;
}
/** Preview state management (docs/PREVIEW.md): wraps the layout store's
* `previewSession`/`commitPreview` with the 120ms pane-swap throttle so the
* UI never has to schedule it by hand. */
export function usePreview({ store, scheduleDeps }: UsePreviewOptions): UsePreviewResult {
const previewedSessionId = useStore(store, (s: LayoutStore) => s.preview?.sessionId ?? null);
const scheduleRef = useRef<ReturnType<typeof createPreviewSchedule> | null>(null);
if (!scheduleRef.current) {
scheduleRef.current = createPreviewSchedule((id) => store.getState().previewSession(id), scheduleDeps);
}
useEffect(() => {
const schedule = scheduleRef.current;
return () => schedule?.cancel();
}, []);
const preview = useCallback((sessionId: Uuid | null) => {
scheduleRef.current?.(sessionId);
}, []);
const previewFromPointer = useCallback(
(sessionId: Uuid | null, pointerType: string) => {
if (pointerType === "touch") return;
preview(sessionId);
},
[preview],
);
const commit = useCallback(
(sessionId: Uuid) => {
scheduleRef.current?.cancel();
store.getState().openSession(sessionId);
},
[store],
);
const end = useCallback(() => {
scheduleRef.current?.cancel();
store.getState().previewSession(null);
}, [store]);
return { previewedSessionId, preview, previewFromPointer, commit, end };
}