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
+129
View File
@@ -159,4 +159,133 @@ describe("layoutStore", () => {
expect(save).toHaveBeenCalledTimes(1);
expect(save.mock.calls[0][0]).toBe(s.getState().layout);
});
describe("previewSession (docs/PREVIEW.md)", () => {
it("brings a session's own tab forward, then puts the layout back", () => {
const s = store();
s.getState().openSession("s1");
s.getState().addTab();
s.getState().openSession("s2");
const before = JSON.stringify(s.getState().layout);
s.getState().previewSession("s1");
const tab1 = s.getState().layout.tabs.find((t) => leaves(t.root).some((l) => l.sessionId === "s1"))!;
expect(s.getState().layout.activeTabId).toBe(tab1.id);
expect(s.getState().preview?.sessionId).toBe("s1");
s.getState().previewSession(null);
expect(s.getState().preview).toBeNull();
expect(JSON.stringify(s.getState().layout)).toBe(before);
});
it("shows a session no pane holds in a throwaway tab that leaves no trace", () => {
const s = store();
s.getState().openSession("s1");
const before = JSON.stringify(s.getState().layout);
s.getState().previewSession("s9");
expect(s.getState().layout.tabs).toHaveLength(2);
const tempTab = s.getState().layout.tabs[1];
expect(leaves(tempTab.root).map((l) => l.sessionId)).toEqual(["s9"]);
s.getState().previewSession(null);
expect(s.getState().layout.tabs).toHaveLength(1);
expect(JSON.stringify(s.getState().layout)).toBe(before);
});
it("stepping between previews leaves only the newest one on screen", () => {
const s = store();
s.getState().openSession("s1");
const before = JSON.stringify(s.getState().layout);
s.getState().previewSession("s9");
s.getState().previewSession("s8");
expect(s.getState().layout.tabs).toHaveLength(2);
expect(s.getState().preview?.sessionId).toBe("s8");
s.getState().previewSession(null);
expect(JSON.stringify(s.getState().layout)).toBe(before);
});
it("never persists while up, and saves again once settled back", () => {
const save = vi.fn();
const { scheduler, flush } = fakeScheduler();
const s = store({ save, scheduler });
s.getState().openSession("s1");
flush();
save.mockClear();
s.getState().previewSession("s9");
expect(save).not.toHaveBeenCalled();
s.getState().previewSession(null);
flush();
expect(save).toHaveBeenCalledTimes(1);
});
it("commitPreview keeps the throwaway tab as a real one", () => {
const s = store();
s.getState().openSession("s1");
s.getState().previewSession("s9");
expect(s.getState().commitPreview("s9")).toBe(true);
expect(s.getState().preview).toBeNull();
expect(s.getState().layout.tabs).toHaveLength(2);
expect(leaves(s.getState().layout.tabs[1].root).map((l) => l.sessionId)).toEqual(["s9"]);
});
it("commitPreview discards a non-matching preview and reports false", () => {
const s = store();
s.getState().openSession("s1");
s.getState().previewSession("s9");
expect(s.getState().commitPreview("s1")).toBe(false);
expect(s.getState().preview).toBeNull();
expect(s.getState().layout.tabs).toHaveLength(1);
});
it("openSession settles a matching preview instead of moving it a second time", () => {
const s = store();
s.getState().openSession("s1");
s.getState().previewSession("s9");
s.getState().openSession("s9");
expect(s.getState().preview).toBeNull();
expect(s.getState().layout.tabs).toHaveLength(2);
expect(leaves(s.getState().layout.tabs[0].root).map((l) => l.sessionId)).toEqual(["s1"]);
});
it("any real layout change ends a preview first: splitFocused", () => {
const s = store();
s.getState().openSession("s1");
s.getState().previewSession("s9");
const first = leaves(s.getState().layout.tabs[0].root)[0].id;
s.getState().splitFocused(first, "row");
expect(s.getState().preview).toBeNull();
expect(s.getState().layout.tabs).toHaveLength(1);
expect(leaves(s.getState().layout.tabs[0].root).map((l) => l.sessionId).sort()).toEqual([null, "s1"]);
});
it("any real layout change ends a preview first: addTab/selectTab/closeTab", () => {
const s = store();
s.getState().openSession("s1");
s.getState().previewSession("s9");
s.getState().addTab();
expect(s.getState().preview).toBeNull();
// The throwaway tab was discarded before the real tab was added.
expect(s.getState().layout.tabs).toHaveLength(2);
});
it("closeSession drops the preview before closing the real pane", () => {
const s = store();
s.getState().openSession("s1");
s.getState().previewSession("s9");
s.getState().closeSession("s1");
expect(s.getState().preview).toBeNull();
expect(s.getState().layout.tabs).toHaveLength(1);
expect(s.getState().layout.tabs[0].root).toBeNull();
});
});
});
+116 -1
View File
@@ -11,12 +11,14 @@ import {
emptyLayout,
equalizeRatios,
findLeaf,
freshId,
leaves,
locateSession,
removeLeaf,
splitLeaf,
type Dir,
type Layout,
type Tab,
} from "../layout.js";
import { loadLayout, saveLayout } from "../persistence.js";
import type { Uuid } from "../types.js";
@@ -35,13 +37,29 @@ export interface LayoutStoreOptions {
scheduler?: Scheduler;
}
/** A provisional preview (docs/PREVIEW.md): records exactly what
* `previewSession` moved, so ending it restores the layout byte-for-byte. */
export interface PreviewState {
sessionId: Uuid;
/** Tab that was active before the preview. */
prevActiveTabId: string;
/** Focused leaf to restore, when the preview stole focus in a real tab. */
prevFocus: { tabId: string; leafId: string | null } | null;
/** Throwaway tab built for a session that no pane was showing. */
tempTabId: string | null;
}
export interface LayoutState {
layout: Layout;
/** Session shown provisionally in the content pane, or null. A preview is
* a view, not state: it never reaches `save` (docs/PREVIEW.md). */
preview: PreviewState | null;
}
export interface LayoutActions {
/** Bring `sessionId` into view: focus it if already open, else fill the
* focused pane (VS-Code-style replace), or seed an empty tab. */
* focused pane (VS-Code-style replace), or seed an empty tab. Settles a
* matching preview in place rather than moving it a second time. */
openSession(sessionId: Uuid): void;
/** Same, but never evicts a running pane: reuses an empty leaf or splits
* beside the focused one. `newTab` opens its own tab instead. */
@@ -66,6 +84,15 @@ export interface LayoutActions {
* tab was closed is pruned instead of leaving a pane that can only ever
* show a dead socket. Tabs that were already empty are left alone. */
reconcile(liveIds: ReadonlySet<Uuid>): void;
/** Show `sessionId` in the content pane without committing to it
* (docs/PREVIEW.md): its own tab comes forward, or a throwaway tab
* carries it. `null` puts back whatever was on screen before. Never
* schedules a save while a preview is up. */
previewSession(sessionId: Uuid | null): void;
/** Keep what is being previewed: its throwaway tab becomes a real one, and
* the focus it moved stands. Any other pending preview is simply
* discarded. Returns whether `sessionId` was the one being previewed. */
commitPreview(sessionId: Uuid): boolean;
}
export type LayoutStore = LayoutState & LayoutActions;
@@ -107,10 +134,51 @@ export function createLayoutStore(opts: LayoutStoreOptions = {}) {
commit();
}
// ---- preview (docs/PREVIEW.md): a view, not a layout change — never
// schedules a save while it is up. ----
/** Undo the preview's moves. Mutates only — the caller re-renders /
* persists as it sees fit. Returns whether a preview was active. */
function restorePreview(): boolean {
const p = get().preview;
if (!p) return false;
set({ preview: null });
const layout = get().layout;
if (p.tempTabId) {
const i = layout.tabs.findIndex((t) => t.id === p.tempTabId);
if (i >= 0) layout.tabs.splice(i, 1);
} else if (p.prevFocus) {
const t = layout.tabs.find((x) => x.id === p.prevFocus!.tabId);
if (t) t.focusedLeafId = p.prevFocus.leafId;
}
layout.activeTabId = layout.tabs.some((t) => t.id === p.prevActiveTabId)
? p.prevActiveTabId
: layout.tabs[0].id;
return true;
}
function settlePreview(sessionId: Uuid): boolean {
const p = get().preview;
if (!p) return false;
if (p.sessionId !== sessionId) {
restorePreview();
return false;
}
set({ preview: null });
if (p.tempTabId) {
const layout = get().layout;
const t = layout.tabs.find((x) => x.id === p.tempTabId);
if (t) t.title = `Tab ${layout.tabs.length}`;
}
return true;
}
return {
layout: load() ?? emptyLayout(),
preview: null,
openSession(sessionId) {
if (get().commitPreview(sessionId)) return;
mutate((layout) => {
const loc = locateSession(layout, sessionId);
if (loc) {
@@ -130,6 +198,7 @@ export function createLayoutStore(opts: LayoutStoreOptions = {}) {
},
openSessionBeside(sessionId, placement) {
restorePreview();
mutate((layout) => {
const loc = locateSession(layout, sessionId);
if (loc) {
@@ -158,6 +227,7 @@ export function createLayoutStore(opts: LayoutStoreOptions = {}) {
},
closeSession(sessionId) {
restorePreview();
mutate((layout) => {
const loc = locateSession(layout, sessionId);
if (!loc) return;
@@ -170,6 +240,7 @@ export function createLayoutStore(opts: LayoutStoreOptions = {}) {
},
splitFocused(leafId, dir) {
restorePreview();
mutate((layout) => {
const tab = activeTab(layout);
tab.focusedLeafId = splitLeaf(tab, leafId, null, dir, true);
@@ -178,6 +249,7 @@ export function createLayoutStore(opts: LayoutStoreOptions = {}) {
},
closePane(leafId) {
restorePreview();
mutate((layout) => {
const tab = activeTab(layout);
removeLeaf(tab, leafId);
@@ -196,24 +268,28 @@ export function createLayoutStore(opts: LayoutStoreOptions = {}) {
},
selectTab(tabId) {
restorePreview();
mutate((layout) => {
if (layout.tabs.some((t) => t.id === tabId)) layout.activeTabId = tabId;
});
},
addTab() {
restorePreview();
mutate((layout) => {
addTabToLayout(layout);
});
},
closeTab(tabId) {
restorePreview();
mutate((layout) => {
closeTabInLayout(layout, tabId);
});
},
reorderTab(fromId, toId) {
restorePreview();
mutate((layout) => {
if (fromId === toId) return;
const from = layout.tabs.findIndex((t) => t.id === fromId);
@@ -248,6 +324,45 @@ export function createLayoutStore(opts: LayoutStoreOptions = {}) {
for (const id of emptied) closeTabInLayout(layout, id);
});
},
previewSession(sessionId) {
const current = get().preview;
if (current?.sessionId === sessionId) return;
if (sessionId === null) {
if (restorePreview()) commit();
return;
}
restorePreview();
const layout = get().layout;
const prevActiveTabId = layout.activeTabId;
const loc = locateSession(layout, sessionId);
let preview: PreviewState;
if (loc) {
preview = {
sessionId,
prevActiveTabId,
prevFocus: { tabId: loc.tab.id, leafId: loc.tab.focusedLeafId },
tempTabId: null,
};
layout.activeTabId = loc.tab.id;
loc.tab.focusedLeafId = loc.leaf.id;
} else {
// Not on screen anywhere: a throwaway tab carries it, so no
// existing pane is evicted and nothing the operator arranged moves.
const tab: Tab = { id: freshId("t"), title: "Preview", root: null, focusedLeafId: null };
tab.focusedLeafId = splitLeaf(tab, "", sessionId, "row", true);
layout.tabs.push(tab);
layout.activeTabId = tab.id;
preview = { sessionId, prevActiveTabId, prevFocus: null, tempTabId: tab.id };
}
set({ layout: { ...layout }, preview });
},
commitPreview(sessionId) {
const ok = settlePreview(sessionId);
if (ok) commit();
return ok;
},
};
});
}