Skip to content

Commit 0f815f4

Browse files
fix(studio): hand-off intent before dispatch, steady film under the board, stills outside the board folder
- openInDesktop writes desktop-cta.json before sending the folder, so a running app reads the storyboard ask on arrival; a plain or header open drops an earlier storyboard ask; a failed open puts the earlier record back. - PreviewStage keeps the film at one place in the tree with or without a board, so a board appearing never remounts it; the automatic switch goes through the same pause as a click, and a play while the board is up is paused. - The board reloads when a still it draws changes, including a root board's stills/ and a boards/ page's ../assets. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01HebQXPiLcYKQfvPWB3Fgxy
1 parent e73b0e2 commit 0f815f4

8 files changed

Lines changed: 308 additions & 58 deletions

File tree

‎packages/cli/src/utils/desktopApp.test.ts‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,6 +124,68 @@ describe("openInDesktop", () => {
124124
}
125125
});
126126

127+
it("has the storyboard ask in place when the app is handed the folder, not after", () => {
128+
const dir = mkdtempSync(join(tmpdir(), "hf-cta-order-"));
129+
const record = join(dir, ".hyperframes", "desktop-cta.json");
130+
try {
131+
writeFileSync(join(dir, "index.html"), "<html></html>");
132+
let seen: unknown = null;
133+
openInDesktop(dir, {
134+
...LIVE,
135+
cta: "page-1",
136+
doc: "storyboard",
137+
open: () => {
138+
seen = JSON.parse(readFileSync(record, "utf8"));
139+
return true;
140+
},
141+
});
142+
expect(seen).toMatchObject({ cta: "page-1", doc: "storyboard" });
143+
} finally {
144+
rmSync(dir, { recursive: true, force: true });
145+
}
146+
});
147+
148+
it("doesn't reuse an earlier storyboard ask on a later header or plain open", () => {
149+
const dir = mkdtempSync(join(tmpdir(), "hf-cta-later-"));
150+
const record = join(dir, ".hyperframes", "desktop-cta.json");
151+
const read = () => JSON.parse(readFileSync(record, "utf8"));
152+
try {
153+
writeFileSync(join(dir, "index.html"), "<html></html>");
154+
openInDesktop(dir, { ...LIVE, cta: "page-1", doc: "storyboard", open: () => true });
155+
let seen: unknown = null;
156+
openInDesktop(dir, { ...LIVE, cta: "page-2", open: () => ((seen = read()), true) });
157+
expect(seen).toMatchObject({ cta: "page-2" });
158+
expect(seen).not.toHaveProperty("doc");
159+
160+
openInDesktop(dir, { ...LIVE, cta: "page-1", doc: "storyboard", open: () => true });
161+
openInDesktop(dir, { ...LIVE, open: () => ((seen = read()), true) });
162+
expect(seen).toMatchObject({ cta: "page-1" });
163+
expect(seen).not.toHaveProperty("doc");
164+
} finally {
165+
rmSync(dir, { recursive: true, force: true });
166+
}
167+
});
168+
169+
it("puts the earlier record back when the app didn't take the folder", () => {
170+
const dir = mkdtempSync(join(tmpdir(), "hf-cta-undo-"));
171+
const record = join(dir, ".hyperframes", "desktop-cta.json");
172+
try {
173+
writeFileSync(join(dir, "index.html"), "<html></html>");
174+
openInDesktop(dir, { ...LIVE, cta: "page-1", open: () => true });
175+
const earlier = readFileSync(record, "utf8");
176+
openInDesktop(dir, {
177+
...LIVE,
178+
cta: "page-2",
179+
doc: "storyboard",
180+
open: () => false,
181+
installed: () => true,
182+
});
183+
expect(readFileSync(record, "utf8")).toBe(earlier);
184+
} finally {
185+
rmSync(dir, { recursive: true, force: true });
186+
}
187+
});
188+
127189
it("leaves a project's own marker file alone", () => {
128190
const dir = mkdtempSync(join(tmpdir(), "hf-marked-"));
129191
try {

‎packages/cli/src/utils/desktopApp.ts‎

Lines changed: 42 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import { addCatchUpNote, markSeen, readSeen, seenPath } from "./appHistory.js";
77
import { createProjectConfig } from "./projectConfig.js";
88
import { isCI } from "./attendedTerminal.js";
99
import { isAgentDriven } from "../telemetry/agent_runtime.js";
10-
import { writeRecord } from "./projectRecords.js";
10+
import { readRecord, removeRecord, writeRecord } from "./projectRecords.js";
1111

1212
// The HyperFrames desktop app, then builds named in HYPERFRAMES_DESKTOP_BUNDLE_IDS / _APP_NAMES (comma-separated).
1313
const list = (name: string): string[] =>
@@ -200,27 +200,50 @@ export function openInDesktop(
200200
reason,
201201
downloadUrl: desktopDownloadUrl(platform, src) ?? STUDIO_PAGE,
202202
});
203-
const opened = (app: string): DesktopOpenResult => {
204-
if (cta || doc)
205-
writeRecord(dir, DESKTOP_CTA_RECORD, JSON.stringify({ cta, at: Date.now(), doc }));
206-
return {
207-
opened: true,
208-
app,
209-
handedOver: leaveHandoff(dir, agentSession(env)),
210-
};
203+
const opened = (app: string): DesktopOpenResult => ({
204+
opened: true,
205+
app,
206+
handedOver: leaveHandoff(dir, agentSession(env)),
207+
});
208+
const dispatch = (): DesktopOpenResult => {
209+
if (platform === "darwin") {
210+
const bundleId = bundleIds().find((id) => open(id, dir));
211+
if (!bundleId) return notOpened(installed() ? "open-failed" : "not-installed");
212+
return opened(bundleId === bundleIds()[0] ? DEFAULT_APP : bundleId);
213+
}
214+
const apps = desktopApps({ platform, env, ...where });
215+
if (!apps) return notOpened("unsupported-platform");
216+
if (!apps.length) return notOpened("not-installed");
217+
const app = apps.find(({ executable }) => launch(executable, dir));
218+
return app ? opened(app.name) : notOpened("open-failed");
211219
};
212220
if (!ready) return notOpened("handoff-unavailable");
213221
markBareIndexAsProject(dir);
214-
if (platform === "darwin") {
215-
const bundleId = bundleIds().find((id) => open(id, dir));
216-
if (!bundleId) return notOpened(installed() ? "open-failed" : "not-installed");
217-
return opened(bundleId === bundleIds()[0] ? DEFAULT_APP : bundleId);
218-
}
219-
const apps = desktopApps({ platform, env, ...where });
220-
if (!apps) return notOpened("unsupported-platform");
221-
if (!apps.length) return notOpened("not-installed");
222-
const app = apps.find(({ executable }) => launch(executable, dir));
223-
return app ? opened(app.name) : notOpened("open-failed");
222+
const undoIntent = leaveIntent(dir, cta, doc);
223+
const result = dispatch();
224+
if (!result.opened) undoIntent();
225+
return result;
226+
}
227+
228+
/** Written before the folder is sent, since a running app reads it on arrival; the undo puts back what was there. */
229+
function leaveIntent(dir: string, cta?: string, doc?: "storyboard"): () => void {
230+
const before = readRecord(dir, DESKTOP_CTA_RECORD, 4096);
231+
const earlier = ((): { doc?: unknown } | null => {
232+
try {
233+
return JSON.parse(before);
234+
} catch {
235+
return null;
236+
}
237+
})();
238+
if (cta || doc)
239+
writeRecord(dir, DESKTOP_CTA_RECORD, JSON.stringify({ cta, at: Date.now(), doc }));
240+
else if (earlier?.doc !== undefined)
241+
writeRecord(dir, DESKTOP_CTA_RECORD, JSON.stringify({ ...earlier, doc: undefined }));
242+
else return () => {};
243+
return () => {
244+
if (!before) removeRecord(dir, DESKTOP_CTA_RECORD);
245+
else writeRecord(dir, DESKTOP_CTA_RECORD, before);
246+
};
224247
}
225248

226249
/** The `hyperframes open` line for a project, relative to where the person is. */

‎packages/cli/src/utils/projectRecords.ts‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,13 @@
1-
import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSync } from "node:fs";
1+
import {
2+
closeSync,
3+
constants,
4+
fstatSync,
5+
lstatSync,
6+
mkdirSync,
7+
openSync,
8+
readSync,
9+
unlinkSync,
10+
} from "node:fs";
211
import { join } from "node:path";
312
import { replaceFileAtomically } from "@hyperframes/core/atomic-file";
413

@@ -81,3 +90,15 @@ export function writeRecord(projectDir: string, name: string, data: string): boo
8190
const dir = recordsDir(projectDir, true);
8291
return dir !== null && replaceFile(join(dir, name), data, 0o600);
8392
}
93+
94+
/** Removes a record that is a plain file; false when nothing was removed. */
95+
export function removeRecord(projectDir: string, name: string): boolean {
96+
const dir = recordsDir(projectDir);
97+
try {
98+
if (!dir || !lstatSync(join(dir, name)).isFile()) return false;
99+
unlinkSync(join(dir, name));
100+
return true;
101+
} catch {
102+
return false;
103+
}
104+
}
Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
// @vitest-environment happy-dom
2+
import React, { act, useEffect } from "react";
3+
import { createRoot, type Root } from "react-dom/client";
4+
import { create } from "zustand";
5+
import { afterEach, beforeEach, expect, it, vi } from "vitest";
6+
import type { StoryboardBoard } from "./useStoryboardBoard";
7+
8+
(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
9+
10+
const pauses = vi.fn();
11+
const player = create<{
12+
isPlaying: boolean;
13+
setIsPlaying: (playing: boolean) => void;
14+
requestPlayback: (playing: boolean) => void;
15+
requestSeek: (seconds: number) => void;
16+
}>((set) => ({
17+
isPlaying: false,
18+
setIsPlaying: (isPlaying) => set({ isPlaying }),
19+
requestPlayback: (playing) => {
20+
if (!playing) pauses();
21+
},
22+
requestSeek: () => {},
23+
}));
24+
vi.mock("../../player", () => ({ usePlayerStore: player }));
25+
vi.mock("../../utils/studioTelemetry", () => ({ trackStudioEvent: vi.fn() }));
26+
vi.mock("./StoryboardBoardView", () => ({
27+
StoryboardBoardView: () => <div data-testid="board-view" />,
28+
}));
29+
let board: StoryboardBoard;
30+
vi.mock("./useStoryboardBoard", () => ({ useStoryboardBoard: () => board }));
31+
32+
const { PreviewStage } = await import("./PreviewStage");
33+
34+
const noBoard: StoryboardBoard = {
35+
path: null,
36+
revision: 0,
37+
read: { state: "loading" },
38+
appeared: false,
39+
};
40+
const written: StoryboardBoard = { ...noBoard, path: "boards/storyboard.html", appeared: true };
41+
42+
let mounts = 0;
43+
function Film() {
44+
useEffect(() => {
45+
mounts += 1;
46+
}, []);
47+
return <div data-testid="film" />;
48+
}
49+
50+
let root: Root;
51+
const render = () =>
52+
act(async () =>
53+
root.render(
54+
<PreviewStage projectId="p1">
55+
<Film />
56+
</PreviewStage>,
57+
),
58+
);
59+
const boardShown = () => document.querySelector('[data-testid="board-view"]') !== null;
60+
61+
beforeEach(() => {
62+
mounts = 0;
63+
board = noBoard;
64+
player.setState({ isPlaying: false });
65+
const host = document.createElement("div");
66+
document.body.append(host);
67+
root = createRoot(host);
68+
});
69+
70+
afterEach(async () => {
71+
await act(async () => root.unmount());
72+
document.body.innerHTML = "";
73+
vi.clearAllMocks();
74+
});
75+
76+
it("keeps the film mounted and pauses it when the agent's board first appears", async () => {
77+
player.setState({ isPlaying: true });
78+
await render();
79+
board = written;
80+
await render();
81+
expect(boardShown()).toBe(true);
82+
expect(mounts).toBe(1);
83+
expect(pauses).toHaveBeenCalled();
84+
});
85+
86+
it("keeps the film mounted when the board goes and comes back", async () => {
87+
board = written;
88+
await render();
89+
board = noBoard;
90+
await render();
91+
expect(boardShown()).toBe(false);
92+
board = written;
93+
await render();
94+
expect(mounts).toBe(1);
95+
});
96+
97+
it("pauses a play started while the board covers the film, as a shortcut would", async () => {
98+
await render();
99+
board = written;
100+
await render();
101+
pauses.mockClear();
102+
await act(async () => player.getState().setIsPlaying(true));
103+
expect(pauses).toHaveBeenCalledTimes(1);
104+
});

‎packages/studio/src/components/storyboard/PreviewStage.tsx‎

Lines changed: 45 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
import { useEffect, useRef, useState, type ReactNode } from "react";
1+
import { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
22
import { usePlayerStore } from "../../player";
33
import { trackStudioEvent } from "../../utils/studioTelemetry";
44
import { Tab, Tabs, TabsList, cn } from "../ui";
@@ -9,20 +9,38 @@ type StageTab = "preview" | "storyboard";
99

1010
/**
1111
* The preview panel's stage: the film, and beside it the storyboard once the project has one. With no board there
12-
* is no strip at all. The film stays mounted under the board so going back keeps its place.
12+
* is no strip at all. The film keeps one place in the tree whether or not a board exists, so a board appearing or
13+
* going never remounts it, and it stays paused under the board so going back keeps its place.
1314
*/
1415
export function PreviewStage({ projectId, children }: { projectId: string; children: ReactNode }) {
1516
const board = useStoryboardBoard(projectId);
1617
const [tab, setTab] = useState<StageTab>("preview");
1718
const [dotted, setDotted] = useState(false);
1819
const shownRevision = useRef(board.revision);
20+
const tabRef = useRef(tab);
21+
tabRef.current = tab;
22+
23+
const show = useCallback((next: StageTab, action?: string) => {
24+
if (next === tabRef.current) return;
25+
if (next === "storyboard") usePlayerStore.getState().requestPlayback(false);
26+
trackStudioEvent("storyboard_tab", {
27+
action: action ?? (next === "storyboard" ? "open" : "close"),
28+
});
29+
setTab(next);
30+
}, []);
1931

2032
// A board that appears while Studio is open is the agent's stop: show it, as Desktop does.
2133
useEffect(() => {
22-
if (!board.appeared) return;
23-
setTab("storyboard");
24-
trackStudioEvent("storyboard_tab", { action: "shown_on_write" });
25-
}, [board.appeared]);
34+
if (board.appeared) show("storyboard", "shown_on_write");
35+
}, [board.appeared, show]);
36+
37+
// The film is hidden under the board, so a play from anywhere (a shortcut, a stray request) is undone there.
38+
useEffect(() => {
39+
if (tab !== "storyboard") return;
40+
return usePlayerStore.subscribe((state, prev) => {
41+
if (state.isPlaying && !prev.isPlaying) state.requestPlayback(false);
42+
});
43+
}, [tab]);
2644

2745
useEffect(() => {
2846
if (tab === "storyboard") {
@@ -35,35 +53,30 @@ export function PreviewStage({ projectId, children }: { projectId: string; child
3553
if (!board.path) setTab("preview");
3654
}, [board.path]);
3755

38-
const show = (next: StageTab) => {
39-
if (next === tab) return;
40-
if (next === "storyboard") usePlayerStore.getState().requestPlayback(false);
41-
trackStudioEvent("storyboard_tab", { action: next === "storyboard" ? "open" : "close" });
42-
setTab(next);
43-
};
44-
45-
if (!board.path) return <>{children}</>;
4656
const path = board.path;
57+
const onBoard = path !== null && tab === "storyboard";
4758
return (
4859
<div className="flex h-full w-full min-w-0 flex-col">
49-
<Tabs value={tab} onValueChange={(value) => show(value as StageTab)}>
50-
<div className="flex h-9 shrink-0 items-center border-b border-border-strong bg-surface px-2">
51-
<TabsList aria-label="Preview pages" className="bg-transparent p-0">
52-
<Tab value="preview">Preview</Tab>
53-
<Tab value="storyboard" data-testid="stage-tab-storyboard">
54-
Storyboard
55-
{dotted && (
56-
<span
57-
className="ml-1.5 inline-block h-1.5 w-1.5 rounded-full bg-accent"
58-
aria-label=", updated"
59-
/>
60-
)}
61-
</Tab>
62-
</TabsList>
63-
</div>
64-
</Tabs>
65-
<div className={cn("relative min-h-0 flex-1", tab !== "preview" && "hidden")}>{children}</div>
66-
{tab === "storyboard" && (
60+
{path !== null && (
61+
<Tabs value={tab} onValueChange={(value) => show(value as StageTab)}>
62+
<div className="flex h-9 shrink-0 items-center border-b border-border-strong bg-surface px-2">
63+
<TabsList aria-label="Preview pages" className="bg-transparent p-0">
64+
<Tab value="preview">Preview</Tab>
65+
<Tab value="storyboard" data-testid="stage-tab-storyboard">
66+
Storyboard
67+
{dotted && (
68+
<span
69+
className="ml-1.5 inline-block h-1.5 w-1.5 rounded-full bg-accent"
70+
aria-label=", updated"
71+
/>
72+
)}
73+
</Tab>
74+
</TabsList>
75+
</div>
76+
</Tabs>
77+
)}
78+
<div className={cn("relative min-h-0 flex-1", onBoard && "hidden")}>{children}</div>
79+
{onBoard && (
6780
<div className="min-h-0 flex-1">
6881
<StoryboardBoardView
6982
projectId={projectId}

0 commit comments

Comments
 (0)