The best way to control Claude Code, Codex and more from any computer or phone
fix(web): switching a file between markdown and the editor no longer saves a draft twice (#25768)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Oct 27, 2026 at 02:13 UTC
4cb29a56f6cf1f4f4ff06daee5323017c858ddf3
7 files changed
+554
-289
apps/web/src/components/files/FilePreviewPanel.tsx
+7
-15
@@ -117,7 +117,7 @@ import {
117
shouldShowFileExplorer,
118
workspaceAssetResource,
119
} from "./filePreviewMode";
120
-import { useFileSaveCoordinator } from "./useFileSaveCoordinator";
120
+import { changeFileSaveSession, useFileSaveSession } from "./fileSaveSessions";
121
import { revisionedQuery } from "~/state/revisionedQuery";
122
import {
123
getOptimisticProjectFileQueryData,
@@ -675,12 +675,8 @@ function EditableFileSurface({
675
};
676
const surfaceRef = useRef<HTMLDivElement>(null);
677
const selectionFrameRef = useRef<number | null>(null);
678
- const saveCoordinator = useFileSaveCoordinator({
679
- environmentId,
680
- cwd,
681
- relativePath,
682
- onPendingChange,
683
- });
678
+ const saveTarget = { environmentId, cwd, relativePath };
679
+ useFileSaveSession(saveTarget, onPendingChange);
680
// Retain file identity for echoed editor changes; only external changes replace the editor's draft.
681
const [externalFile, setExternalFile] = useState(() =>
682
editableFileContents(environmentId, cwd, relativePath, contents),
@@ -709,7 +705,7 @@ function EditableFileSurface({
705
if (file.contents === getProjectFileContents(environmentId, cwd, relativePath)) return;
706
setEditedContents(file.contents);
707
setProjectFileQueryData(environmentId, cwd, relativePath, file.contents);
712
- saveCoordinator.change(file.contents);
708
+ changeFileSaveSession(saveTarget, file.contents);
709
if (!nextLineAnnotations) return;
710
const remapped = remapFileCommentAnnotations(nextLineAnnotations);
711
// The editor hands back the array it was given until an edit moves an annotation.
@@ -926,12 +922,8 @@ function RenderedMarkdownSurface({
922
readOnly: boolean;
923
workspaceMutationId: string | null;
924
}) {
929
- const saveCoordinator = useFileSaveCoordinator({
930
- environmentId,
931
- cwd,
932
- relativePath,
933
- onPendingChange,
934
- });
925
+ const saveTarget = { environmentId, cwd, relativePath };
926
+ useFileSaveSession(saveTarget, onPendingChange);
927
928
return (
929
<ScrollArea className="min-h-0 flex-1">
@@ -951,7 +943,7 @@ function RenderedMarkdownSurface({
943
const nextContents = setMarkdownTaskChecked(currentContents, markerOffset, checked);
944
if (nextContents === currentContents) return;
945
setProjectFileQueryData(environmentId, cwd, relativePath, nextContents);
954
- saveCoordinator.change(nextContents);
946
+ changeFileSaveSession(saveTarget, nextContents);
947
}
948
}
949
/>
apps/web/src/components/files/fileSaveCoordinator.ts
+25
-3
@@ -7,6 +7,8 @@ export interface FileSaveCoordinatorOptions<A, E> {
7
readonly onPendingChange: (pending: boolean) => void;
8
/** Return false when another editor has newer unsaved contents. */
9
readonly onConfirmed: (contents: string) => boolean | void;
10
+ /** Called when a write pass ends with nothing further scheduled. */
11
+ readonly onSettled?: () => void;
12
}
13
14
export class FileSaveCoordinator<A = unknown, E = unknown> {
@@ -17,6 +19,7 @@ export class FileSaveCoordinator<A = unknown, E = unknown> {
19
private lastChangeAt = 0;
20
private saving = false;
21
private disposed = false;
22
+ private flushing = false;
23
24
constructor(private readonly options: FileSaveCoordinatorOptions<A, E>) {}
25
@@ -29,6 +32,18 @@ export class FileSaveCoordinator<A = unknown, E = unknown> {
32
this.schedule(this.options.debounceMs);
33
}
34
35
+ /** The newest contents not yet written, which is the last write this coordinator will make. */
36
+ get unconfirmedContents(): string | null {
37
+ return this.latestRevision === this.confirmedRevision ? null : this.latestContents;
38
+ }
39
+
40
+ /** Writes the newest draft now instead of after the debounce, then any draft queued behind it. */
41
+ flush(): void {
42
+ this.clearTimer();
43
+ this.flushing = true;
44
+ void this.persistLatest();
45
+ }
46
+
47
dispose(): void {
48
this.disposed = true;
49
this.clearTimer();
@@ -50,8 +65,9 @@ export class FileSaveCoordinator<A = unknown, E = unknown> {
65
}
66
67
private async persistLatest(): Promise<void> {
53
- if (this.saving || this.latestRevision === this.confirmedRevision) return;
54
- if (this.options.canPersist?.() === false) {
68
+ if (this.saving) return;
69
+ if (this.latestRevision === this.confirmedRevision || this.options.canPersist?.() === false) {
70
+ this.settle();
71
return;
72
}
73
@@ -69,6 +85,7 @@ export class FileSaveCoordinator<A = unknown, E = unknown> {
85
this.saving = false;
86
if (revision === this.latestRevision) {
87
if (confirmed) this.options.onPendingChange(false);
88
+ this.settle();
89
return;
90
}
91
@@ -76,10 +93,15 @@ export class FileSaveCoordinator<A = unknown, E = unknown> {
93
0,
94
this.options.debounceMs - (Date.now() - this.lastChangeAt),
95
);
79
- if (this.disposed) {
96
+ if (this.disposed || this.flushing) {
97
void this.persistLatest();
98
} else {
99
this.schedule(remainingDebounce);
100
}
101
}
102
+
103
+ private settle(): void {
104
+ this.flushing = false;
105
+ this.options.onSettled?.();
106
+ }
107
}
apps/web/src/components/files/fileSaveSessions.browser.test.tsx
new
+83
@@ -0,0 +1,83 @@
1
+import { render, fakeTimers } from "../../../test/render";
2
+import { EnvironmentId } from "@t3tools/contracts";
3
+import { AsyncResult } from "effect/reactivity";
4
+import { StrictMode } from "react";
5
+import { describe, expect, it, vi } from "vite-plus/test";
6
+
7
+const { runAtomCommand, getUnsavedFile } = vi.hoisted(() => ({
8
+ runAtomCommand: vi.fn(),
9
+ getUnsavedFile: vi.fn(),
10
+}));
11
+vi.mock(import("@t3tools/client-runtime/state/runtime"), async (original) => ({
12
+ ...(await original()),
13
+ runAtomCommand: runAtomCommand as never,
14
+}));
15
+vi.mock(import("~/state/session"), async (original) => ({
16
+ ...(await original()),
17
+ readEnvironmentScope: () => true,
18
+}));
19
+vi.mock(import("./projectFilesQueryState"), async (original) => ({
20
+ ...(await original()),
21
+ confirmProjectFileQueryData: () => true,
22
+ getUnsavedProjectFileQueryData: getUnsavedFile,
23
+}));
24
+
25
+import { changeFileSaveSession, useFileSaveSession } from "./fileSaveSessions";
26
+
27
+const target = {
28
+ environmentId: EnvironmentId.make("file-save-sessions-browser"),
29
+ cwd: "/workspace",
30
+ relativePath: "README.md",
31
+};
32
+const onPendingChange = vi.fn();
33
+
34
+// The editor and rendered-markdown surfaces are different component types, so
35
+// switching between them unmounts one session holder and mounts another.
36
+function EditorSurface() {
37
+ useFileSaveSession({ ...target }, onPendingChange);
38
+ return <div>editor</div>;
39
+}
40
+function MarkdownSurface() {
41
+ useFileSaveSession({ ...target }, onPendingChange);
42
+ return <div>markdown</div>;
43
+}
44
+
45
+describe("file save sessions in React", () => {
46
+ it("writes a pending draft once when the file switches surfaces under StrictMode", async () => {
47
+ let finishWrite = () => {};
48
+ runAtomCommand.mockReset().mockImplementation(
49
+ () =>
50
+ new Promise((resolve) => {
51
+ finishWrite = () => resolve(AsyncResult.success(undefined));
52
+ }),
53
+ );
54
+ getUnsavedFile.mockReset().mockReturnValue(null);
55
+ await using screen = await render(
56
+ <StrictMode>
57
+ <EditorSurface />
58
+ </StrictMode>,
59
+ { router: false }, // no routes involved; the surfaces are bare effect hosts
60
+ );
61
+ using _timers = fakeTimers();
62
+ // An edit lands in the query cache, unconfirmed until its write settles.
63
+ getUnsavedFile.mockReturnValue({ contents: "draft" });
64
+ changeFileSaveSession(target, "draft");
65
+
66
+ await screen.rerender(
67
+ <StrictMode>
68
+ <MarkdownSurface />
69
+ </StrictMode>,
70
+ );
71
+ finishWrite();
72
+ getUnsavedFile.mockReturnValue(null);
73
+ await vi.runAllTimersAsync();
74
+
75
+ expect(runAtomCommand.mock.calls.map(([, , request]) => request)).toEqual([
76
+ {
77
+ environmentId: target.environmentId,
78
+ input: { cwd: "/workspace", relativePath: "README.md", contents: "draft" },
79
+ },
80
+ ]);
81
+ expect(onPendingChange).toHaveBeenLastCalledWith("README.md", false);
82
+ });
83
+});
apps/web/src/components/files/fileSaveSessions.test.ts
new
+261
@@ -0,0 +1,261 @@
1
+import { EnvironmentId } from "@t3tools/contracts";
2
+import { Cause } from "effect";
3
+import { AsyncResult } from "effect/reactivity";
4
+import { describe, expect, it, vi } from "vite-plus/test";
5
+
6
+import {
7
+ createFileSaveSessions,
8
+ type FileSaveSessionDeps,
9
+ type FileSaveTarget,
10
+} from "./fileSaveSessions";
11
+
12
+const target: FileSaveTarget = {
13
+ environmentId: EnvironmentId.make("file-save-sessions"),
14
+ cwd: "/workspace",
15
+ relativePath: "file.txt",
16
+};
17
+
18
+function setup() {
19
+ vi.useFakeTimers();
20
+ const state = {
21
+ writable: true,
22
+ unsaved: null as string | null,
23
+ onWritable: [] as Array<() => void>,
24
+ };
25
+ const persist = vi.fn<FileSaveSessionDeps["persist"]>(async () => AsyncResult.success(undefined));
26
+ const confirm = vi.fn((_target: FileSaveTarget, _contents: string) => true);
27
+ const onPendingChange = vi.fn();
28
+ const sessions = createFileSaveSessions({
29
+ debounceMs: 500,
30
+ canPersist: () => state.writable,
31
+ subscribeWritable: (_target, onWritable) => {
32
+ state.onWritable.push(onWritable);
33
+ return () => {
34
+ state.onWritable = state.onWritable.filter((listener) => listener !== onWritable);
35
+ };
36
+ },
37
+ persist,
38
+ confirm,
39
+ readUnsaved: () => state.unsaved,
40
+ });
41
+ const writes = () => persist.mock.calls.map(([written, contents]) => [written, contents]);
42
+ return {
43
+ state,
44
+ sessions,
45
+ persist,
46
+ confirm,
47
+ onPendingChange,
48
+ writes,
49
+ [Symbol.dispose]: () => vi.useRealTimers(),
50
+ };
51
+}
52
+
53
+describe("file save sessions", () => {
54
+ it("debounces edits and clears the pending marker once confirmed", async () => {
55
+ using h = setup();
56
+ h.sessions.acquire(target, h.onPendingChange);
57
+ h.sessions.change(target, "a");
58
+ h.sessions.change(target, "ab");
59
+ expect(h.onPendingChange).toHaveBeenLastCalledWith("file.txt", true);
60
+ await vi.advanceTimersByTimeAsync(500);
61
+ expect(h.writes()).toEqual([[target, "ab"]]);
62
+ expect(h.onPendingChange).toHaveBeenLastCalledWith("file.txt", false);
63
+ });
64
+
65
+ it("flushes on the last release and drops edits from retired editors", async () => {
66
+ using h = setup();
67
+ const releaseFirst = h.sessions.acquire(target, h.onPendingChange);
68
+ const releaseSecond = h.sessions.acquire(target, h.onPendingChange);
69
+ h.sessions.change(target, "pending edit");
70
+ releaseFirst();
71
+ expect(h.persist).not.toHaveBeenCalled();
72
+ releaseSecond();
73
+ h.sessions.change(target, "stale editor contents");
74
+ await vi.runAllTimersAsync();
75
+ expect(h.writes()).toEqual([[target, "pending edit"]]);
76
+ expect(h.onPendingChange).toHaveBeenLastCalledWith("file.txt", false);
77
+ });
78
+
79
+ it("gives a replaced file a fresh session and flushes the old one", async () => {
80
+ using h = setup();
81
+ const other = { ...target, relativePath: "other.txt" };
82
+ const release = h.sessions.acquire(target, h.onPendingChange);
83
+ h.sessions.change(target, "old file edit");
84
+ release();
85
+ h.sessions.acquire(other, h.onPendingChange);
86
+ h.sessions.change(target, "stale editor contents");
87
+ h.sessions.change(other, "new file edit");
88
+ await vi.runAllTimersAsync();
89
+ expect(h.writes()).toEqual([
90
+ [target, "old file edit"],
91
+ [other, "new file edit"],
92
+ ]);
93
+ });
94
+
95
+ it("resumes an unsaved draft when a session is created", async () => {
96
+ using h = setup();
97
+ h.state.unsaved = "pending draft";
98
+ h.sessions.acquire(target, h.onPendingChange);
99
+ expect(h.onPendingChange).toHaveBeenLastCalledWith("file.txt", true);
100
+ await vi.advanceTimersByTimeAsync(500);
101
+ expect(h.writes()).toEqual([[target, "pending draft"]]);
102
+ });
103
+
104
+ it("does not queue a draft that a retired session is still writing", async () => {
105
+ using h = setup();
106
+ let finishWrite = () => {};
107
+ h.persist.mockImplementationOnce(
108
+ () =>
109
+ new Promise((resolve) => {
110
+ finishWrite = () => resolve(AsyncResult.success(undefined));
111
+ }),
112
+ );
113
+ const release = h.sessions.acquire(target, h.onPendingChange);
114
+ h.sessions.change(target, "draft");
115
+ h.state.unsaved = "draft";
116
+ release();
117
+ // A StrictMode ref replay reacquires while the flush is in flight.
118
+ h.sessions.acquire(target, h.onPendingChange);
119
+ finishWrite();
120
+ await vi.runAllTimersAsync();
121
+ expect(h.writes()).toEqual([[target, "draft"]]);
122
+ });
123
+
124
+ it("writes a rejoining surface's edit last, over the released session's queued draft", async () => {
125
+ using h = setup();
126
+ let finishWrite = () => {};
127
+ h.persist.mockImplementationOnce(
128
+ () =>
129
+ new Promise((resolve) => {
130
+ finishWrite = () => resolve(AsyncResult.success(undefined));
131
+ }),
132
+ );
133
+ const release = h.sessions.acquire(target, h.onPendingChange);
134
+ h.sessions.change(target, "X");
135
+ await vi.advanceTimersByTimeAsync(500);
136
+ h.sessions.change(target, "Y");
137
+ release();
138
+ h.sessions.acquire(target, h.onPendingChange);
139
+ h.sessions.change(target, "Z");
140
+ await vi.advanceTimersByTimeAsync(500);
141
+ finishWrite();
142
+ await vi.runAllTimersAsync();
143
+ expect(h.writes().at(-1)).toEqual([target, "Z"]);
144
+ });
145
+
146
+ it("tells a surface joining a session with an unsaved edit that the file is pending", () => {
147
+ using h = setup();
148
+ h.sessions.acquire(target, h.onPendingChange);
149
+ h.sessions.change(target, "edit");
150
+ const joiningListener = vi.fn();
151
+ h.sessions.acquire(target, joiningListener);
152
+ expect(joiningListener).toHaveBeenCalledWith("file.txt", true);
153
+ });
154
+
155
+ it("lets go of a released session that cannot write and recovers its draft later", async () => {
156
+ using h = setup();
157
+ const release = h.sessions.acquire(target, h.onPendingChange);
158
+ h.state.writable = false;
159
+ h.sessions.change(target, "draft");
160
+ h.state.unsaved = "draft";
161
+ release();
162
+ expect(h.state.onWritable).toEqual([]);
163
+ h.sessions.change(target, "retired editor contents");
164
+ h.state.writable = true;
165
+ h.sessions.acquire(target, h.onPendingChange);
166
+ await vi.runAllTimersAsync();
167
+ expect(h.writes()).toEqual([[target, "draft"]]);
168
+ });
169
+
170
+ it("recovers a draft that a retired session gave up on when write access dropped", async () => {
171
+ using h = setup();
172
+ let finishWrite = () => {};
173
+ h.persist.mockImplementationOnce(
174
+ () =>
175
+ new Promise((resolve) => {
176
+ finishWrite = () => resolve(AsyncResult.success(undefined));
177
+ }),
178
+ );
179
+ const release = h.sessions.acquire(target, h.onPendingChange);
180
+ h.sessions.change(target, "X");
181
+ await vi.advanceTimersByTimeAsync(500);
182
+ h.sessions.change(target, "Y");
183
+ release();
184
+ h.state.writable = false;
185
+ finishWrite();
186
+ await vi.runAllTimersAsync();
187
+ h.state.unsaved = "Y";
188
+ h.sessions.acquire(target, h.onPendingChange);
189
+ h.state.writable = true;
190
+ for (const onWritable of h.state.onWritable) onWritable();
191
+ await vi.runAllTimersAsync();
192
+ expect(h.writes()).toEqual([
193
+ [target, "X"],
194
+ [target, "Y"],
195
+ ]);
196
+ });
197
+
198
+ it("stops notifying a surface's listener once it releases a shared session", async () => {
199
+ using h = setup();
200
+ const retiredListener = vi.fn();
201
+ const release = h.sessions.acquire(target, retiredListener);
202
+ h.sessions.acquire(target, h.onPendingChange);
203
+ release();
204
+ h.sessions.change(target, "edit");
205
+ await vi.runAllTimersAsync();
206
+ expect(retiredListener).not.toHaveBeenCalled();
207
+ expect(h.onPendingChange).toHaveBeenLastCalledWith("file.txt", false);
208
+ });
209
+
210
+ it("requeues a draft whose retired flush failed on the live session", async () => {
211
+ using h = setup();
212
+ let failWrite = () => {};
213
+ h.persist.mockImplementationOnce(
214
+ () =>
215
+ new Promise((resolve) => {
216
+ failWrite = () => resolve(AsyncResult.failure(Cause.fail("offline")));
217
+ }),
218
+ );
219
+ const release = h.sessions.acquire(target, h.onPendingChange);
220
+ h.sessions.change(target, "draft");
221
+ h.state.unsaved = "draft";
222
+ release();
223
+ h.sessions.acquire(target, h.onPendingChange);
224
+ failWrite();
225
+ await vi.runAllTimersAsync();
226
+ expect(h.writes()).toEqual([
227
+ [target, "draft"],
228
+ [target, "draft"],
229
+ ]);
230
+ expect(h.onPendingChange).toHaveBeenLastCalledWith("file.txt", false);
231
+ });
232
+
233
+ it("keeps edits pending while unwritable and resumes them when access returns", async () => {
234
+ using h = setup();
235
+ h.sessions.acquire(target, h.onPendingChange);
236
+ h.state.writable = false;
237
+ h.sessions.change(target, "pending edit");
238
+ h.state.unsaved = "pending edit";
239
+ await vi.runAllTimersAsync();
240
+ expect(h.persist).not.toHaveBeenCalled();
241
+ expect(h.onPendingChange).toHaveBeenLastCalledWith("file.txt", true);
242
+
243
+ h.state.writable = true;
244
+ for (const onWritable of h.state.onWritable) onWritable();
245
+ await vi.advanceTimersByTimeAsync(500);
246
+ expect(h.writes()).toEqual([[target, "pending edit"]]);
247
+ expect(h.onPendingChange).toHaveBeenLastCalledWith("file.txt", false);
248
+ });
249
+
250
+ it("skips recovery while unwritable and stops watching access after release", async () => {
251
+ using h = setup();
252
+ h.state.writable = false;
253
+ h.state.unsaved = "pending draft";
254
+ const release = h.sessions.acquire(target, h.onPendingChange);
255
+ expect(h.onPendingChange).not.toHaveBeenCalled();
256
+ release();
257
+ expect(h.state.onWritable).toEqual([]);
258
+ await vi.runAllTimersAsync();
259
+ expect(h.persist).not.toHaveBeenCalled();
260
+ });
261
+});
apps/web/src/components/files/fileSaveSessions.ts
new
+178
@@ -0,0 +1,178 @@
1
+import { AuthFilesystemWriteScope, type EnvironmentId } from "@t3tools/contracts";
2
+import { type AtomCommandResult, runAtomCommand } from "@t3tools/client-runtime/state/runtime";
3
+import { useEffect } from "react";
4
+
5
+import { appAtomRegistry } from "~/rpc/atomRegistry";
6
+import { projectEnvironment } from "~/state/projects";
7
+import { environmentSession, readEnvironmentScope, sessionHasScope } from "~/state/session";
8
+
9
+import { FileSaveCoordinator } from "./fileSaveCoordinator";
10
+import {
11
+ confirmProjectFileQueryData,
12
+ getUnsavedProjectFileQueryData,
13
+} from "./projectFilesQueryState";
14
+
15
+export interface FileSaveTarget {
16
+ readonly environmentId: EnvironmentId;
17
+ readonly cwd: string;
18
+ readonly relativePath: string;
19
+}
20
+
21
+export type FilePendingListener = (relativePath: string, pending: boolean) => void;
22
+
23
+export interface FileSaveSessionDeps {
24
+ readonly debounceMs: number;
25
+ readonly canPersist: (target: FileSaveTarget) => boolean;
26
+ /** Calls `onWritable` each time the target environment regains write access. */
27
+ readonly subscribeWritable: (target: FileSaveTarget, onWritable: () => void) => () => void;
28
+ readonly persist: (
29
+ target: FileSaveTarget,
30
+ contents: string,
31
+ ) => Promise<AtomCommandResult<unknown, unknown>>;
32
+ readonly confirm: (target: FileSaveTarget, contents: string) => boolean;
33
+ readonly readUnsaved: (target: FileSaveTarget) => string | null;
34
+}
35
+
36
+interface FileSaveSession {
37
+ readonly coordinator: FileSaveCoordinator;
38
+ /** Lease count per listener; surfaces may share one listener. */
39
+ readonly listeners: Map<FilePendingListener, number>;
40
+ readonly unsubscribeWritable: () => void;
41
+ leases: number;
42
+ /** The last release flushed, and the session stays open until that settles. */
43
+ flushingOnRelease: boolean;
44
+}
45
+
46
+/**
47
+ * One save session, so one ordered write queue, per file. A released session
48
+ * stays open until its flush settles, so a surface rejoining meanwhile reuses
49
+ * it instead of racing the flush. A session that cannot write closes at once,
50
+ * and the next one, or regained write access, resumes the unsaved draft.
51
+ */
52
+export function createFileSaveSessions(deps: FileSaveSessionDeps) {
53
+ const sessions = new Map<string, FileSaveSession>();
54
+
55
+ const recover = (target: FileSaveTarget, coordinator: FileSaveCoordinator) => {
56
+ if (!deps.canPersist(target)) return;
57
+ const unsaved = deps.readUnsaved(target);
58
+ if (unsaved !== null) coordinator.change(unsaved);
59
+ };
60
+
61
+ const create = (key: string, target: FileSaveTarget): FileSaveSession => {
62
+ const listeners = new Map<FilePendingListener, number>();
63
+ const coordinator: FileSaveCoordinator = new FileSaveCoordinator({
64
+ debounceMs: deps.debounceMs,
65
+ canPersist: () => deps.canPersist(target),
66
+ // The last surface's listeners outlive it: a flush that settles after
67
+ // the session is released still has to clear the pending marker.
68
+ onPendingChange: (pending) => {
69
+ for (const listener of listeners.keys()) listener(target.relativePath, pending);
70
+ },
71
+ persist: (contents) => deps.persist(target, contents),
72
+ onConfirmed: (contents) => deps.confirm(target, contents),
73
+ onSettled: () => {
74
+ if (!session.flushingOnRelease) return;
75
+ session.flushingOnRelease = false;
76
+ if (session.leases === 0) {
77
+ if (sessions.get(key) === session) sessions.delete(key);
78
+ session.unsubscribeWritable();
79
+ } else if (coordinator.unconfirmedContents !== null) {
80
+ // A surface rejoined while the release flush failed; retry it once.
81
+ recover(target, coordinator);
82
+ }
83
+ },
84
+ });
85
+ const unsubscribeWritable = deps.subscribeWritable(target, () => recover(target, coordinator));
86
+ const session: FileSaveSession = {
87
+ coordinator,
88
+ listeners,
89
+ unsubscribeWritable,
90
+ leases: 0,
91
+ flushingOnRelease: false,
92
+ };
93
+ return session;
94
+ };
95
+
96
+ const acquire = (target: FileSaveTarget, onPendingChange: FilePendingListener): (() => void) => {
97
+ const key = fileSaveKey(target);
98
+ const existing = sessions.get(key);
99
+ const session = existing ?? create(key, target);
100
+ sessions.set(key, session);
101
+ session.leases += 1;
102
+ session.listeners.set(onPendingChange, (session.listeners.get(onPendingChange) ?? 0) + 1);
103
+ if (!existing) recover(target, session.coordinator);
104
+ else if (session.coordinator.unconfirmedContents !== null) {
105
+ onPendingChange(target.relativePath, true);
106
+ }
107
+
108
+ let released = false;
109
+ return () => {
110
+ if (released) return;
111
+ released = true;
112
+ session.leases -= 1;
113
+ if (session.leases > 0) {
114
+ const count = (session.listeners.get(onPendingChange) ?? 1) - 1;
115
+ if (count > 0) session.listeners.set(onPendingChange, count);
116
+ else session.listeners.delete(onPendingChange);
117
+ return;
118
+ }
119
+ session.flushingOnRelease = true;
120
+ session.coordinator.flush();
121
+ };
122
+ };
123
+
124
+ return {
125
+ /** Holds the file's session open until the returned release runs. */
126
+ acquire,
127
+ /** Edits for a file nobody holds open are dropped, so retired editors stay inert. */
128
+ change(target: FileSaveTarget, contents: string): void {
129
+ const session = sessions.get(fileSaveKey(target));
130
+ if (session && session.leases > 0) session.coordinator.change(contents);
131
+ },
132
+ };
133
+}
134
+
135
+function fileSaveKey({ environmentId, cwd, relativePath }: FileSaveTarget): string {
136
+ return `${environmentId}\u0000${cwd}\u0000${relativePath}`;
137
+}
138
+
139
+const fileSaveSessions = createFileSaveSessions({
140
+ debounceMs: 500,
141
+ canPersist: ({ environmentId }) => readEnvironmentScope(environmentId, AuthFilesystemWriteScope),
142
+ subscribeWritable: ({ environmentId }, onWritable) => {
143
+ let writable = readEnvironmentScope(environmentId, AuthFilesystemWriteScope);
144
+ return appAtomRegistry.subscribe(
145
+ environmentSession.sessionStateAtom(environmentId),
146
+ (state) => {
147
+ const next = sessionHasScope(state, AuthFilesystemWriteScope);
148
+ if (next && !writable) onWritable();
149
+ writable = next;
150
+ },
151
+ );
152
+ },
153
+ persist: ({ environmentId, cwd, relativePath }, contents) =>
154
+ runAtomCommand(appAtomRegistry, projectEnvironment.writeFile, {
155
+ environmentId,
156
+ input: { cwd, relativePath, contents },
157
+ }),
158
+ confirm: ({ environmentId, cwd, relativePath }, contents) =>
159
+ confirmProjectFileQueryData(environmentId, cwd, relativePath, contents),
160
+ readUnsaved: ({ environmentId, cwd, relativePath }) =>
161
+ getUnsavedProjectFileQueryData(environmentId, cwd, relativePath)?.contents ?? null,
162
+});
163
+
164
+/** Holds the file's save session while the surface is mounted; the last surface to leave flushes. */
165
+export function useFileSaveSession(
166
+ { environmentId, cwd, relativePath }: FileSaveTarget,
167
+ onPendingChange: FilePendingListener,
168
+): void {
169
+ // oxlint-disable-next-line t3code/react-effect-budget -- the lease is a mount-scoped external resource; React runs every unmount cleanup before mount setups, so a surface switch flushes before the next surface recovers.
170
+ useEffect(
171
+ () => fileSaveSessions.acquire({ environmentId, cwd, relativePath }, onPendingChange),
172
+ [environmentId, cwd, relativePath, onPendingChange],
173
+ );
174
+}
175
+
176
+export function changeFileSaveSession(target: FileSaveTarget, contents: string): void {
177
+ fileSaveSessions.change(target, contents);
178
+}
apps/web/src/components/files/useFileSaveCoordinator.browser.test.tsx
deleted
-170
@@ -1,170 +0,0 @@
1
-import { render, fakeTimers } from "../../../test/render";
2
-import { EnvironmentId } from "@t3tools/contracts";
3
-import { AsyncResult } from "effect/reactivity";
4
-import { StrictMode, useEffect } from "react";
5
-import { describe, expect, it, vi } from "vite-plus/test";
6
-
7
-const { writeFile, confirmFile, readScope, getUnsavedFile } = vi.hoisted(() => ({
8
- writeFile: vi.fn(),
9
- confirmFile: vi.fn(),
10
- readScope: vi.fn(),
11
- getUnsavedFile: vi.fn(),
12
-}));
13
-vi.mock(import("~/state/session"), async (original) => ({
14
- ...(await original()),
15
- readEnvironmentScope: readScope,
16
- useEnvironmentScope: readScope,
17
-}));
18
-vi.mock(import("~/state/use-atom-command"), async (original) => ({
19
- ...(await original()),
20
- useAtomCommand: (() => writeFile) as never,
21
-}));
22
-vi.mock(import("./projectFilesQueryState"), async (original) => ({
23
- ...(await original()),
24
- confirmProjectFileQueryData: confirmFile,
25
- getUnsavedProjectFileQueryData: getUnsavedFile,
26
-}));
27
-
28
-import { useFileSaveCoordinator } from "./useFileSaveCoordinator";
29
-
30
-const environmentId = EnvironmentId.make("save-lifecycle-audit");
31
-const onPendingChange = vi.fn();
32
-const defaultProps = {
33
- environmentId,
34
- cwd: "/workspace",
35
- relativePath: "file.txt",
36
- onPendingChange,
37
-};
38
-function setup() {
39
- writeFile.mockReset().mockResolvedValue(AsyncResult.success(undefined));
40
- confirmFile.mockReset();
41
- readScope.mockReset().mockReturnValue(true);
42
- getUnsavedFile.mockReset().mockReturnValue(null);
43
- onPendingChange.mockReset();
44
-}
45
-
46
-async function mount(props = defaultProps) {
47
- let latestChange: (contents: string) => void = () => {};
48
- function FileSurface(props: Parameters<typeof useFileSaveCoordinator>[0]) {
49
- const coordinator = useFileSaveCoordinator(props);
50
- useEffect(() => {
51
- latestChange = (contents) => coordinator.change(contents);
52
- });
53
- return null;
54
- }
55
- const ui = (props: Parameters<typeof useFileSaveCoordinator>[0]) => (
56
- <StrictMode>
57
- <FileSurface {...props} />
58
- </StrictMode>
59
- );
60
- const screen = await render(ui(props), { router: false });
61
- return {
62
- changeHandler: () => latestChange,
63
- rerender: (props: Parameters<typeof useFileSaveCoordinator>[0]) => screen.rerender(ui(props)),
64
- unmount: screen.unmount,
65
- [Symbol.asyncDispose]: () => screen[Symbol.asyncDispose](),
66
- };
67
-}
68
-
69
-describe("file-save React lifecycle", () => {
70
- it("persists editor model changes after StrictMode setup replay", async () => {
71
- setup();
72
- using _timers = fakeTimers();
73
- await using screen = await mount();
74
- screen.changeHandler()("AUDIT7907NATIVE\n");
75
- expect(onPendingChange).toHaveBeenCalledWith("file.txt", true);
76
- await vi.advanceTimersByTimeAsync(500);
77
- expect(writeFile).toHaveBeenCalledExactlyOnceWith({
78
- environmentId,
79
- input: { cwd: "/workspace", relativePath: "file.txt", contents: "AUDIT7907NATIVE\n" },
80
- });
81
- expect(confirmFile).toHaveBeenCalledExactlyOnceWith(
82
- environmentId,
83
- "/workspace",
84
- "file.txt",
85
- "AUDIT7907NATIVE\n",
86
- );
87
- expect(onPendingChange).toHaveBeenLastCalledWith("file.txt", false);
88
- });
89
-
90
- it("flushes on unmount and ignores a retired editor callback", async () => {
91
- setup();
92
- using _timers = fakeTimers();
93
- await using screen = await mount();
94
- const retiredChange = screen.changeHandler();
95
- retiredChange("pending edit");
96
- await screen.unmount();
97
- retiredChange("stale editor contents");
98
- await vi.runAllTimersAsync();
99
- expect(writeFile).toHaveBeenCalledTimes(1);
100
- expect(writeFile.mock.calls[0]![0].input.contents).toBe("pending edit");
101
- });
102
-
103
- it.each([false, true])(
104
- "keeps edits pending after permission is revoked before a React update (unmount: %s)",
105
- async (unmount) => {
106
- setup();
107
- using _timers = fakeTimers();
108
- await using screen = await mount();
109
- screen.changeHandler()("pending edit");
110
- readScope.mockReturnValue(false);
111
- if (unmount) {
112
- await screen.unmount();
113
- }
114
- await vi.runAllTimersAsync();
115
- expect(writeFile).not.toHaveBeenCalled();
116
- expect(confirmFile).not.toHaveBeenCalled();
117
- expect(onPendingChange).toHaveBeenLastCalledWith("file.txt", true);
118
- },
119
- );
120
-
121
- it("resumes an unsaved draft when write permission returns after effect replay", async () => {
122
- setup();
123
- using _timers = fakeTimers();
124
- readScope.mockReturnValue(false);
125
- getUnsavedFile.mockReturnValue({ contents: "pending draft" });
126
- await using screen = await mount();
127
- await vi.runAllTimersAsync();
128
- expect(writeFile).not.toHaveBeenCalled();
129
-
130
- readScope.mockReturnValue(true);
131
- await screen.rerender(defaultProps);
132
- await vi.advanceTimersByTimeAsync(500);
133
- expect(writeFile).toHaveBeenCalledExactlyOnceWith({
134
- environmentId,
135
- input: { cwd: "/workspace", relativePath: "file.txt", contents: "pending draft" },
136
- });
137
- expect(onPendingChange).toHaveBeenLastCalledWith("file.txt", false);
138
- });
139
-
140
- it.each([
141
- { relativePath: "other.txt" },
142
- { cwd: "/other-workspace" },
143
- { environmentId: EnvironmentId.make("other-environment") },
144
- ])("retires callbacks when the file identity changes: %j", async (change) => {
145
- setup();
146
- using _timers = fakeTimers();
147
- await using screen = await mount();
148
- const retiredChange = screen.changeHandler();
149
- retiredChange("old file edit");
150
- const nextProps = { ...defaultProps, ...change };
151
- await screen.rerender(nextProps);
152
- retiredChange("stale editor contents");
153
- screen.changeHandler()("new file edit");
154
- await vi.runAllTimersAsync();
155
- expect(writeFile.mock.calls.map(([request]) => request)).toEqual([
156
- {
157
- environmentId,
158
- input: { cwd: "/workspace", relativePath: "file.txt", contents: "old file edit" },
159
- },
160
- {
161
- environmentId: nextProps.environmentId,
162
- input: {
163
- cwd: nextProps.cwd,
164
- relativePath: nextProps.relativePath,
165
- contents: "new file edit",
166
- },
167
- },
168
- ]);
169
- });
170
-});
apps/web/src/components/files/useFileSaveCoordinator.ts
deleted
-101
@@ -1,101 +0,0 @@
1
-import { AuthFilesystemWriteScope, type EnvironmentId } from "@t3tools/contracts";
2
-import { createRef, useEffect, useState } from "react";
3
-
4
-import { projectEnvironment } from "~/state/projects";
5
-import { readEnvironmentScope, useEnvironmentScope } from "~/state/session";
6
-import { useAtomCommand } from "~/state/use-atom-command";
7
-
8
-import { FileSaveCoordinator } from "./fileSaveCoordinator";
9
-import {
10
- confirmProjectFileQueryData,
11
- getUnsavedProjectFileQueryData,
12
-} from "./projectFilesQueryState";
13
-
14
-const FILE_SAVE_DEBOUNCE_MS = 500;
15
-
16
-interface FileSaveOptions {
17
- environmentId: EnvironmentId;
18
- cwd: string;
19
- relativePath: string;
20
- onPendingChange: (relativePath: string, pending: boolean) => void;
21
-}
22
-
23
-export function useFileSaveCoordinator({
24
- environmentId,
25
- cwd,
26
- relativePath,
27
- onPendingChange,
28
-}: FileSaveOptions): Pick<FileSaveCoordinator, "change"> {
29
- const canWriteFiles = useEnvironmentScope(environmentId, AuthFilesystemWriteScope);
30
- const writeFile = useProjectFileWriter();
31
- const inputs = { environmentId, cwd, relativePath, onPendingChange, writeFile };
32
- const [current, setCurrent] = useState(() => ({
33
- inputs,
34
- session: createFileSaveSession(inputs),
35
- }));
36
- if (
37
- current.inputs.environmentId !== environmentId ||
38
- current.inputs.cwd !== cwd ||
39
- current.inputs.relativePath !== relativePath ||
40
- current.inputs.onPendingChange !== onPendingChange ||
41
- current.inputs.writeFile !== writeFile
42
- ) {
43
- setCurrent({ inputs, session: createFileSaveSession(inputs) });
44
- }
45
- const session = current.session;
46
-
47
- // StrictMode replay needs a fresh coordinator; retired file sessions stay inert.
48
- useEffect(session.setup, [session]);
49
- useEffect(() => {
50
- if (!canWriteFiles) return;
51
- let cancelled = false;
52
- // Replay must retire the first session before recovery queues a draft to flush.
53
- queueMicrotask(() => {
54
- if (cancelled) return;
55
- const unsaved = getUnsavedProjectFileQueryData(environmentId, cwd, relativePath);
56
- if (unsaved) session.change(unsaved.contents);
57
- });
58
- return () => {
59
- cancelled = true;
60
- };
61
- }, [canWriteFiles, cwd, environmentId, relativePath, session]);
62
- return session;
63
-}
64
-
65
-function useProjectFileWriter() {
66
- return useAtomCommand(projectEnvironment.writeFile);
67
-}
68
-
69
-function createFileSaveSession({
70
- environmentId,
71
- cwd,
72
- relativePath,
73
- onPendingChange,
74
- writeFile,
75
-}: FileSaveOptions & {
76
- writeFile: ReturnType<typeof useProjectFileWriter>;
77
-}) {
78
- const coordinatorRef = createRef<FileSaveCoordinator>();
79
- return {
80
- change: (contents: string) => coordinatorRef.current?.change(contents),
81
- setup: () => {
82
- const coordinator = new FileSaveCoordinator({
83
- debounceMs: FILE_SAVE_DEBOUNCE_MS,
84
- canPersist: () => readEnvironmentScope(environmentId, AuthFilesystemWriteScope),
85
- onPendingChange: (pending) => onPendingChange(relativePath, pending),
86
- persist: (nextContents) =>
87
- writeFile({
88
- environmentId,
89
- input: { cwd, relativePath, contents: nextContents },
90
- }),
91
- onConfirmed: (confirmedContents) =>
92
- confirmProjectFileQueryData(environmentId, cwd, relativePath, confirmedContents),
93
- });
94
- coordinatorRef.current = coordinator;
95
- return () => {
96
- coordinatorRef.current = null;
97
- coordinator.dispose();
98
- };
99
- },
100
- };
101
-}