Skip to content

Commit a99caad

Browse files
feat(studio): coordinate external file changes (#2991)
1 parent b30a234 commit a99caad

2 files changed

Lines changed: 650 additions & 0 deletions

File tree

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
// @vitest-environment happy-dom
2+
import { act } from "react";
3+
import { createRoot } from "react-dom/client";
4+
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
5+
import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
6+
import { markStudioWriteToken, resetStudioWriteTokens } from "../utils/studioFileVersion";
7+
import {
8+
useExternalFileChangeCoordinator,
9+
type ExternalFileChangeCoordinatorHandle,
10+
} from "./useExternalFileChangeCoordinator";
11+
12+
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
13+
14+
type HotHandler = (payload?: unknown) => void;
15+
type CoordinatorOptions = Parameters<typeof useExternalFileChangeCoordinator>[0];
16+
const roots: Array<ReturnType<typeof createRoot>> = [];
17+
let handler: HotHandler | null;
18+
19+
async function mountCoordinator(overrides: Partial<CoordinatorOptions> = {}) {
20+
const captured: { handle: ExternalFileChangeCoordinatorHandle | null } = { handle: null };
21+
const defaults: CoordinatorOptions = {
22+
projectId: "project-a",
23+
activeCompPath: "index.html",
24+
pendingTimelineEditPathRef: { current: new Set() },
25+
drainPendingChanges: vi.fn(async () => ({ status: "clean" as const })),
26+
reloadPreview: vi.fn(),
27+
reloadSdkSession: vi.fn(),
28+
persistConflictSnapshot: vi.fn(async () => undefined),
29+
discardPendingChanges: vi.fn(),
30+
overwriteConflict: vi.fn(async () => undefined),
31+
readProjectFile: vi.fn(async () => "external"),
32+
};
33+
const options = { ...defaults, ...overrides };
34+
const root = createRoot(document.createElement("div"));
35+
roots.push(root);
36+
function Probe() {
37+
captured.handle = useExternalFileChangeCoordinator(options);
38+
return null;
39+
}
40+
await act(async () => root.render(<Probe />));
41+
return { captured, options };
42+
}
43+
44+
describe("external file change coordinator", () => {
45+
beforeEach(() => {
46+
handler = null;
47+
resetStudioWriteTokens();
48+
vi.stubGlobal("__HF_STUDIO_HOT_TEST_ADAPTER__", {
49+
on: (_event: string, next: HotHandler) => {
50+
handler = next;
51+
},
52+
off: () => {
53+
handler = null;
54+
},
55+
});
56+
});
57+
58+
afterEach(async () => {
59+
while (roots.length > 0) await act(async () => roots.pop()?.unmount());
60+
vi.unstubAllGlobals();
61+
});
62+
63+
it("drains before reloading Preview and SDK exactly once", async () => {
64+
const order: string[] = [];
65+
const { captured } = await mountCoordinator({
66+
drainPendingChanges: async () => {
67+
order.push("drain");
68+
return { status: "clean" };
69+
},
70+
reloadPreview: () => order.push("preview"),
71+
reloadSdkSession: () => order.push("sdk"),
72+
});
73+
await act(async () => handler?.({ path: "index.html", content: "external", version: "v2" }));
74+
expect(order).toEqual(["drain", "preview", "sdk"]);
75+
expect(captured.handle?.blocked).toBeNull();
76+
});
77+
78+
it("suppresses an exact Studio write receipt", async () => {
79+
const drainPendingChanges = vi.fn(async () => ({ status: "clean" as const }));
80+
const reloadPreview = vi.fn();
81+
const reloadSdkSession = vi.fn();
82+
await mountCoordinator({ drainPendingChanges, reloadPreview, reloadSdkSession });
83+
markStudioWriteToken("studio-write-1");
84+
await act(async () =>
85+
handler?.({ path: "index.html", content: "studio", writeToken: "studio-write-1" }),
86+
);
87+
expect(drainPendingChanges).not.toHaveBeenCalled();
88+
expect(reloadPreview).not.toHaveBeenCalled();
89+
expect(reloadSdkSession).not.toHaveBeenCalled();
90+
});
91+
92+
it("does not suppress a racing external write by path alone", async () => {
93+
const pendingTimelineEditPathRef = { current: new Set(["index.html"]) };
94+
const drainPendingChanges = vi.fn(async () => ({ status: "clean" as const }));
95+
const reloadPreview = vi.fn();
96+
const reloadSdkSession = vi.fn();
97+
await mountCoordinator({
98+
pendingTimelineEditPathRef,
99+
drainPendingChanges,
100+
reloadPreview,
101+
reloadSdkSession,
102+
});
103+
await act(async () => handler?.({ path: "index.html", content: "agent edit", version: "v2" }));
104+
expect(pendingTimelineEditPathRef.current).not.toContain("index.html");
105+
expect(drainPendingChanges).toHaveBeenCalledOnce();
106+
expect(reloadPreview).toHaveBeenCalledOnce();
107+
expect(reloadSdkSession).toHaveBeenCalledOnce();
108+
});
109+
110+
it("blocks both reloads and retains a complete conflict", async () => {
111+
const conflict = new StudioFileConflictError({
112+
filePath: "index.html",
113+
currentVersion: "v2",
114+
currentContent: "external",
115+
attemptedContent: "studio",
116+
});
117+
const persistConflictSnapshot = vi.fn(async () => undefined);
118+
const { captured, options } = await mountCoordinator({
119+
drainPendingChanges: async () => ({ status: "conflict", error: conflict }),
120+
persistConflictSnapshot,
121+
});
122+
await act(async () => handler?.({ path: "index.html", content: "external", version: "v2" }));
123+
expect(persistConflictSnapshot).toHaveBeenCalledWith("project-a", conflict);
124+
expect(captured.handle?.blocked).toMatchObject({ status: "conflict", error: conflict });
125+
expect(options.reloadPreview).not.toHaveBeenCalled();
126+
expect(options.reloadSdkSession).not.toHaveBeenCalled();
127+
});
128+
129+
it("ignores stale drain completion after a newer generation", async () => {
130+
const drains: Array<(result: { status: "clean" }) => void> = [];
131+
const { options } = await mountCoordinator({
132+
drainPendingChanges: () => new Promise((resolve) => drains.push(resolve)),
133+
});
134+
act(() => {
135+
handler?.({ path: "index.html", content: "first", version: "v2" });
136+
handler?.({ path: "index.html", content: "second", version: "v3" });
137+
});
138+
await act(async () => drains[0]?.({ status: "clean" }));
139+
expect(options.reloadPreview).not.toHaveBeenCalled();
140+
await act(async () => drains[1]?.({ status: "clean" }));
141+
expect(options.reloadPreview).toHaveBeenCalledOnce();
142+
expect(options.reloadSdkSession).toHaveBeenCalledOnce();
143+
});
144+
145+
it("restores a durable unresolved conflict after remount", async () => {
146+
const { captured } = await mountCoordinator({
147+
recoveryFilePath: "index.html",
148+
loadConflictSnapshot: vi.fn(async () => ({
149+
kind: "conflict" as const,
150+
projectId: "project-a",
151+
filePath: "index.html",
152+
externalVersion: "v2",
153+
externalContent: "external",
154+
studioContent: "studio",
155+
createdAt: 100,
156+
})),
157+
});
158+
await vi.waitFor(() => expect(captured.handle?.blocked?.status).toBe("conflict"));
159+
expect(captured.handle?.blocked).toMatchObject({
160+
error: { currentContent: "external", attemptedContent: "studio" },
161+
});
162+
});
163+
164+
it("retains the final local candidate when a drain fails", async () => {
165+
const failure = new Error("network unavailable");
166+
const persistFailureSnapshot = vi.fn(async () => undefined);
167+
const deleteConflictSnapshot = vi.fn(async () => undefined);
168+
const { captured } = await mountCoordinator({
169+
drainPendingChanges: vi
170+
.fn()
171+
.mockResolvedValueOnce({ status: "failed" as const, error: failure })
172+
.mockResolvedValueOnce({ status: "clean" as const }),
173+
getPendingCandidate: () => ({ path: "index.html", content: "final local candidate" }),
174+
persistFailureSnapshot,
175+
deleteConflictSnapshot,
176+
});
177+
await act(async () => handler?.({ path: "index.html" }));
178+
expect(captured.handle?.blocked).toMatchObject({
179+
status: "failed",
180+
error: failure,
181+
studioContent: "final local candidate",
182+
});
183+
expect(persistFailureSnapshot).toHaveBeenCalledWith(
184+
"project-a",
185+
"index.html",
186+
"final local candidate",
187+
null,
188+
null,
189+
failure,
190+
);
191+
await act(async () => captured.handle?.retry());
192+
expect(deleteConflictSnapshot).toHaveBeenCalledWith("project-a", "index.html");
193+
});
194+
195+
it("restores and overwrites from a durable failed draft", async () => {
196+
const overwriteConflict = vi.fn(async () => undefined);
197+
const { captured } = await mountCoordinator({
198+
recoveryFilePath: "index.html",
199+
overwriteConflict,
200+
loadConflictSnapshot: vi.fn(async () => ({
201+
kind: "failed" as const,
202+
projectId: "project-a",
203+
filePath: "index.html",
204+
externalVersion: "v2",
205+
externalContent: "external",
206+
studioContent: "recover me",
207+
failureMessage: "network unavailable",
208+
createdAt: 100,
209+
})),
210+
});
211+
await vi.waitFor(() => expect(captured.handle?.blocked?.status).toBe("failed"));
212+
expect(captured.handle?.blocked).toMatchObject({
213+
studioContent: "recover me",
214+
recovered: true,
215+
});
216+
await act(async () => captured.handle?.keepStudioFile());
217+
expect(overwriteConflict).toHaveBeenCalledWith(
218+
expect.objectContaining({ attemptedContent: "recover me", currentVersion: "v2" }),
219+
);
220+
});
221+
});

0 commit comments

Comments
 (0)