Skip to content

Commit ac89e2d

Browse files
committed
fix(studio): address drain review feedback (#2989)
- prioritize conflicts and clear recovered DOM queue errors - cover delayed blur effects and missing drain branches - document stacked consumers and extend write-token retention
1 parent 1d66603 commit ac89e2d

9 files changed

Lines changed: 195 additions & 26 deletions

‎packages/studio/src/hooks/useEditorSave.test.tsx‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import { act } from "react";
33
import { createRoot } from "react-dom/client";
44
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
55
import { useEditorSave, type EditorSaveHandle } from "./useEditorSave";
6+
import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
67

78
(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
89

@@ -96,4 +97,72 @@ describe("useEditorSave pending work", () => {
9697
expect(writeProjectFile).toHaveBeenCalledOnce();
9798
await act(async () => root.unmount());
9899
});
100+
101+
it("preserves conflict details when flushing a buffered source candidate", async () => {
102+
const conflict = new StudioFileConflictError({
103+
filePath: "index.html",
104+
currentVersion: "external-v2",
105+
currentContent: "external",
106+
attemptedContent: "studio candidate",
107+
});
108+
const captured: { handle: EditorSaveHandle | null } = { handle: null };
109+
110+
function Probe() {
111+
captured.handle = useEditorSave({
112+
editingPathRef: { current: "index.html" },
113+
projectIdRef: { current: "project-a" },
114+
readProjectFile: vi.fn(async () => "before"),
115+
writeProjectFile: vi.fn(async () => {
116+
throw conflict;
117+
}),
118+
recordEdit: vi.fn(async () => undefined),
119+
domEditSaveTimestampRef: { current: 0 },
120+
setRefreshKey: vi.fn(),
121+
showToast: vi.fn(),
122+
});
123+
return null;
124+
}
125+
126+
const root = createRoot(document.createElement("div"));
127+
await act(async () => root.render(<Probe />));
128+
act(() => captured.handle?.handleContentChange("studio candidate"));
129+
130+
await expect(captured.handle?.flushPendingSave()).resolves.toEqual({
131+
status: "conflict",
132+
error: conflict,
133+
});
134+
135+
await act(async () => root.unmount());
136+
});
137+
138+
it("discards an rAF-buffered candidate without persisting it", async () => {
139+
const writeProjectFile = vi.fn(async () => undefined);
140+
const captured: { handle: EditorSaveHandle | null } = { handle: null };
141+
142+
function Probe() {
143+
captured.handle = useEditorSave({
144+
editingPathRef: { current: "index.html" },
145+
projectIdRef: { current: "project-a" },
146+
readProjectFile: vi.fn(async () => "before"),
147+
writeProjectFile,
148+
recordEdit: vi.fn(async () => undefined),
149+
domEditSaveTimestampRef: { current: 0 },
150+
setRefreshKey: vi.fn(),
151+
showToast: vi.fn(),
152+
});
153+
return null;
154+
}
155+
156+
const root = createRoot(document.createElement("div"));
157+
await act(async () => root.render(<Probe />));
158+
act(() => captured.handle?.handleContentChange("discard me"));
159+
act(() => captured.handle?.discardPendingSave());
160+
161+
expect(captured.handle?.getPendingCandidate()).toBeNull();
162+
await expect(captured.handle?.flushPendingSave()).resolves.toEqual({ status: "clean" });
163+
expect(writeProjectFile).not.toHaveBeenCalled();
164+
expect(cancelAnimationFrame).toHaveBeenCalledWith(41);
165+
166+
await act(async () => root.unmount());
167+
});
99168
});

‎packages/studio/src/hooks/useEditorSave.ts‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,10 @@ import { useCallback, useRef } from "react";
22
import { saveProjectFilesWithHistory } from "../utils/studioFileHistory";
33
import type { EditHistoryKind } from "../utils/editHistory";
44
import { trackStudioEvent } from "../utils/studioTelemetry";
5-
import { StudioFileConflictError } from "../utils/studioSaveDiagnostics";
5+
import {
6+
StudioFileConflictError,
7+
type StudioSaveDrainResult,
8+
} from "../utils/studioSaveDiagnostics";
69

710
interface RecordEditInput {
811
label: string;
@@ -28,16 +31,16 @@ export interface EditorSaveCandidate {
2831
content: string;
2932
}
3033

31-
export type EditorSaveDrainResult =
32-
| { status: "clean" }
33-
| { status: "conflict"; error: StudioFileConflictError }
34-
| { status: "failed"; error: unknown };
34+
export type EditorSaveDrainResult = StudioSaveDrainResult;
3535

3636
export interface EditorSaveHandle {
3737
saveRafRef: React.MutableRefObject<number | null>;
3838
handleContentChange: (content: string) => void;
39+
/** Read by the external-reload reconciliation introduced in stack PR #2993. */
3940
getPendingCandidate: () => EditorSaveCandidate | null;
41+
/** Wired into the external-reload drain by stack PR #2993. */
4042
flushPendingSave: () => Promise<EditorSaveDrainResult>;
43+
/** Used by PR #2993 when the external version wins. */
4144
discardPendingSave: () => void;
4245
}
4346

‎packages/studio/src/utils/domEditSaveQueue.test.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,23 @@ describe("dom edit save queue", () => {
115115
queue.destroy();
116116
});
117117

118+
it("clears a stale drain failure after a successful save", async () => {
119+
const failure = new Error("temporary failure");
120+
const queue = createDomEditSaveQueue();
121+
122+
await expect(
123+
queue.enqueue(async () => {
124+
throw failure;
125+
}),
126+
).rejects.toBe(failure);
127+
await expect(queue.waitForIdle()).resolves.toEqual({ status: "failed", error: failure });
128+
129+
await queue.enqueue(async () => undefined);
130+
131+
await expect(queue.waitForIdle()).resolves.toEqual({ status: "clean" });
132+
queue.destroy();
133+
});
134+
118135
it("pauses immediately on a file conflict instead of retrying stale work", async () => {
119136
const onOpen = vi.fn();
120137
const queue = createDomEditSaveQueue({ failureThreshold: 5, onOpen });

‎packages/studio/src/utils/domEditSaveQueue.ts‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import {
22
getStudioSaveErrorMessage,
33
getStudioSaveStatusCode,
44
StudioFileConflictError,
5+
type StudioSaveDrainResult,
56
} from "./studioSaveDiagnostics";
67

78
interface DomEditSaveQueueOpenEvent {
@@ -23,10 +24,7 @@ export interface DomEditSaveQueue {
2324
destroy: () => void;
2425
}
2526

26-
export type DomEditSaveDrainResult =
27-
| { status: "clean" }
28-
| { status: "conflict"; error: StudioFileConflictError }
29-
| { status: "failed"; error: unknown };
27+
export type DomEditSaveDrainResult = StudioSaveDrainResult;
3028

3129
const DEFAULT_FAILURE_THRESHOLD = 5;
3230

@@ -66,7 +64,10 @@ export function createDomEditSaveQueue(options: DomEditSaveQueueOptions = {}): D
6664
const run = async <T>(save: () => Promise<T>): Promise<T> => {
6765
try {
6866
const result = await save();
69-
if (!breakerOpen) consecutiveFailures = 0;
67+
if (!breakerOpen) {
68+
consecutiveFailures = 0;
69+
drainError = null;
70+
}
7071
return result;
7172
} catch (error) {
7273
drainError = error;

‎packages/studio/src/utils/studioFileVersion.test.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,4 +50,14 @@ describe("studio write-token echo identity", () => {
5050
expect(consumeStudioWriteToken("studio-write-1")).toBe(false);
5151
expect(consumeStudioWriteToken(null)).toBe(false);
5252
});
53+
54+
it("keeps a token through a slow write and expires abandoned identity state", () => {
55+
resetStudioWriteTokens();
56+
markStudioWriteToken("slow-studio-write", 1_000);
57+
58+
expect(consumeStudioWriteToken("slow-studio-write", 61_000)).toBe(true);
59+
60+
markStudioWriteToken("abandoned-studio-write", 1_000);
61+
expect(consumeStudioWriteToken("abandoned-studio-write", 301_000)).toBe(false);
62+
});
5363
});

‎packages/studio/src/utils/studioFileVersion.ts‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
const WRITE_TOKEN_TTL_MS = 10_000;
1+
// A token is marked before the request starts, so its lifetime must cover slow writes,
2+
// retries, and the subsequent file-change echo without retaining abandoned tokens forever.
3+
const WRITE_TOKEN_TTL_MS = 5 * 60_000;
24
const studioWriteTokens = new Map<string, number>();
35

46
function pruneStudioWriteTokens(now: number): void {
@@ -7,18 +9,21 @@ function pruneStudioWriteTokens(now: number): void {
79
}
810
}
911

12+
/** Marked by the Studio file writer introduced in external-change stack PR #2990. */
1013
export function markStudioWriteToken(token: string, now: number = Date.now()): void {
1114
pruneStudioWriteTokens(now);
1215
studioWriteTokens.set(token, now);
1316
}
1417

18+
/** Consumed by the external-change coordinator introduced in stack PR #2991. */
1519
export function consumeStudioWriteToken(token: string | null, now: number = Date.now()): boolean {
1620
pruneStudioWriteTokens(now);
1721
if (!token || !studioWriteTokens.has(token)) return false;
1822
studioWriteTokens.delete(token);
1923
return true;
2024
}
2125

26+
/** Resets module-level echo identity between PR #2991 coordinator tests. */
2227
export function resetStudioWriteTokens(): void {
2328
studioWriteTokens.clear();
2429
}

‎packages/studio/src/utils/studioPendingEdits.test.ts‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,33 @@ describe("studio pending edit flush", () => {
3636
input.remove();
3737
});
3838

39+
it("waits for a post-blur effect to register its pending edit listener", async () => {
40+
const input = document.createElement("textarea");
41+
document.body.append(input);
42+
const persist = vi.fn(async () => undefined);
43+
let removeListener: (() => void) | undefined;
44+
let registrationDone: Promise<void> | undefined;
45+
input.addEventListener("blur", () => {
46+
registrationDone = new Promise<void>((resolve) => {
47+
setTimeout(() => {
48+
removeListener = addStudioPendingEditFlushListener(persist);
49+
resolve();
50+
}, 0);
51+
});
52+
});
53+
input.focus();
54+
55+
try {
56+
await expect(flushStudioPendingEdits()).resolves.toEqual({ status: "clean" });
57+
58+
expect(persist).toHaveBeenCalledOnce();
59+
} finally {
60+
await registrationDone;
61+
removeListener?.();
62+
input.remove();
63+
}
64+
});
65+
3966
it("preserves a pending edit failure instead of reporting a clean drain", async () => {
4067
const failure = new Error("field save failed");
4168
const remove = addStudioPendingEditFlushListener(async () => {
@@ -73,6 +100,32 @@ describe("studio pending edit flush", () => {
73100
}
74101
});
75102

103+
it("prioritizes a conflict when pending edits fail with mixed errors", async () => {
104+
const failure = new Error("field save failed");
105+
const conflict = new StudioFileConflictError({
106+
filePath: "index.html",
107+
currentVersion: "v2",
108+
currentContent: "external",
109+
attemptedContent: "studio",
110+
});
111+
const removeFailure = addStudioPendingEditFlushListener(async () => {
112+
throw failure;
113+
});
114+
const removeConflict = addStudioPendingEditFlushListener(async () => {
115+
throw conflict;
116+
});
117+
118+
try {
119+
await expect(flushStudioPendingEdits()).resolves.toEqual({
120+
status: "conflict",
121+
error: conflict,
122+
});
123+
} finally {
124+
removeFailure();
125+
removeConflict();
126+
}
127+
});
128+
76129
it("waits for edits already started by unmounted panels", async () => {
77130
const steps: string[] = [];
78131
let resolvePersist!: () => void;

‎packages/studio/src/utils/studioPendingEdits.ts‎

Lines changed: 21 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,19 @@
1-
import { StudioFileConflictError } from "./studioSaveDiagnostics";
1+
import { StudioFileConflictError, type StudioSaveDrainResult } from "./studioSaveDiagnostics";
22

33
const STUDIO_FLUSH_PENDING_EDITS_EVENT = "hf-studio-flush-pending-edits";
44

55
interface StudioFlushPendingEditsDetail {
66
promises: Array<Promise<unknown>>;
77
}
88

9-
export type StudioPendingEditsDrainResult =
10-
| { status: "clean" }
11-
| { status: "conflict"; error: StudioFileConflictError }
12-
| { status: "failed"; error: unknown };
9+
export type StudioPendingEditsDrainResult = StudioSaveDrainResult;
1310

1411
const pendingEditPromises = new Set<Promise<unknown>>();
1512

13+
function waitForPostBlurEffects(): Promise<void> {
14+
return new Promise((resolve) => setTimeout(resolve, 0));
15+
}
16+
1617
export function trackStudioPendingEdit(
1718
result: Promise<unknown> | unknown,
1819
): Promise<unknown> | undefined {
@@ -33,28 +34,33 @@ export async function flushStudioPendingEdits(): Promise<StudioPendingEditsDrain
3334
active.matches('input, textarea, select, [contenteditable="true"], [role="textbox"]')
3435
) {
3536
active.blur();
36-
// React blur handlers enqueue their save synchronously, while state-driven
37-
// registrations can land in the next microtask.
37+
// ponytail: Preserve synchronous/microtask blur commits, then cross one task boundary
38+
// so React effects triggered by the blur can register their flush listener.
3839
await Promise.resolve();
40+
await waitForPostBlurEffects();
3941
}
4042
const detail: StudioFlushPendingEditsDetail = { promises: [] };
4143
window.dispatchEvent(
4244
new CustomEvent<StudioFlushPendingEditsDetail>(STUDIO_FLUSH_PENDING_EDITS_EVENT, { detail }),
4345
);
46+
let firstFailure: unknown;
47+
let hasFailure = false;
4448
while (detail.promises.length > 0 || pendingEditPromises.size > 0) {
4549
const promises = [...detail.promises, ...pendingEditPromises];
4650
detail.promises = [];
4751
const results = await Promise.allSettled(promises);
48-
const rejected = results.find(
49-
(result): result is PromiseRejectedResult => result.status === "rejected",
50-
);
51-
if (rejected) {
52-
return rejected.reason instanceof StudioFileConflictError
53-
? { status: "conflict", error: rejected.reason }
54-
: { status: "failed", error: rejected.reason };
52+
for (const result of results) {
53+
if (result.status !== "rejected") continue;
54+
if (result.reason instanceof StudioFileConflictError) {
55+
return { status: "conflict", error: result.reason };
56+
}
57+
if (!hasFailure) {
58+
firstFailure = result.reason;
59+
hasFailure = true;
60+
}
5561
}
5662
}
57-
return { status: "clean" };
63+
return hasFailure ? { status: "failed", error: firstFailure } : { status: "clean" };
5864
}
5965

6066
export function addStudioPendingEditFlushListener(

‎packages/studio/src/utils/studioSaveDiagnostics.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,11 @@ export class StudioFileConflictError extends StudioSaveHttpError {
5656
}
5757
}
5858

59+
export type StudioSaveDrainResult<Failure = unknown> =
60+
| { status: "clean" }
61+
| { status: "conflict"; error: StudioFileConflictError }
62+
| { status: "failed"; error: Failure };
63+
5964
function readNumericProperty(value: object, key: string): number | undefined {
6065
const record = value as Record<string, unknown>;
6166
const property = record[key];

0 commit comments

Comments
 (0)