@devries-cameron20 / t3code-1 / commits / 45ff3f5967
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

fix(desktop): bound screencast delivery to slow consumers (#28518)

Co-authored-by: maria-rcks <maria@kuuro.net> Co-authored-by: Julius Marminge <julius0216@outlook.com>

Jack Singer committed Nov 14, 2026 at 10:02 UTC 45ff3f5967943f3e2c503958a0891559a5f70d15
5 files changed +141 -30
apps/desktop/src/preview/CdpRelay.test.ts
+65 -4
@@ -9,6 +9,7 @@ import {
9 const makeTarget = (
10 send: CdpRelayTarget["send"],
11 setDownloadDirectory: CdpRelayTarget["setDownloadDirectory"] = () => {},
12 + ackScreencastFrame: CdpRelayTarget["ackScreencastFrame"] = () => {},
13 ): CdpRelayTarget => ({
14 send,
15 targetId: async () => "GUEST-TARGET",
@@ -17,6 +18,7 @@ const makeTarget = (
18 userAgent: () => "Electron",
19 setDownloadDirectory,
20 receivesScreencast: () => true,
21 + ackScreencastFrame,
22 });
23
24 const makeRelay = (target: CdpRelayTarget, write: (raw: string) => void) =>
@@ -138,9 +140,13 @@ describe("CDP relay", () => {
140
141 describe("CDP relay extra sessions", () => {
142 it("gives a second page session the page's commands and events", async () => {
141 - const send = vi.fn(async () => ({}));
143 + const send = vi.fn<CdpRelayTarget["send"]>(async () => ({}));
144 const written: Array<Record<string, unknown>> = [];
143 - const relay = makeRelay(makeTarget(send), (raw) => written.push(JSON.parse(raw)));
145 + const nativeAcks: Array<number> = [];
146 + const relay = makeRelay(
147 + makeTarget(send, undefined, (frameId) => nativeAcks.push(frameId)),
148 + (raw) => written.push(JSON.parse(raw)),
149 + );
150 relay.receive(JSON.stringify({ id: 1, method: "Target.setAutoAttach", params: {} }));
151 relay.receive(JSON.stringify({ id: 2, method: "Target.attachToBrowserTarget" }));
152 await settle();
@@ -170,8 +176,63 @@ describe("CDP relay extra sessions", () => {
176 await settle();
177 expect(send).toHaveBeenLastCalledWith("Page.startScreencast", {}, undefined, extra);
178 written.length = 0;
173 - relay.event("Page.screencastFrame", { data: "x" }, undefined);
174 - expect(written.map((m) => m["sessionId"])).toEqual(["t3-preview-page", extra]);
179 + const frame = (frameId: number) =>
180 + relay.event("Page.screencastFrame", { data: "x", sessionId: frameId }, undefined);
181 + const ack = (sessionId: string, frameId: number) =>
182 + relay.receive(
183 + JSON.stringify({
184 + id: 6,
185 + method: "Page.screencastFrameAck",
186 + params: { sessionId: frameId },
187 + sessionId,
188 + }),
189 + );
190 + const delivered = () => {
191 + const frames = written
192 + .filter((m) => m["method"])
193 + .map((m) => [m["sessionId"], (m["params"] as { sessionId?: number }).sessionId]);
194 + written.length = 0;
195 + return frames;
196 + };
197 + frame(1);
198 + expect(delivered()).toEqual([
199 + ["t3-preview-page", 1],
200 + [extra, 1],
201 + ]);
202 + // A session that has not acknowledged its frame gets only the newest one, on its ack.
203 + for (let i = 2; i < 100; i++) frame(i);
204 + expect(delivered()).toEqual([]);
205 + // Frames every session is busy for stay unacknowledged, so Chromium pauses at its in-flight limit.
206 + expect(nativeAcks).toEqual([1]);
207 + ack(extra, 1);
208 + await settle();
209 + expect(delivered()).toEqual([[extra, 99]]);
210 + // Each consumer ack lets Chromium send one more frame.
211 + expect(nativeAcks).toEqual([1, 2]);
212 + ack(extra, 99);
213 + await settle();
214 + expect(delivered()).toEqual([]);
215 + expect(nativeAcks).toEqual([1, 2, 3]);
216 + frame(100);
217 + expect(delivered()).toEqual([[extra, 100]]);
218 + ack(extra, 99);
219 + await settle();
220 + frame(101);
221 + expect(delivered()).toEqual([]);
222 + expect(send.mock.calls.some(([method]) => method === "Page.screencastFrameAck")).toBe(false);
223 + // A restart keeps the unacknowledged frame's slot until its own acknowledgement.
224 + relay.receive(JSON.stringify({ id: 7, method: "Page.stopScreencast", sessionId: extra }));
225 + relay.receive(JSON.stringify({ id: 8, method: "Page.startScreencast", sessionId: extra }));
226 + await settle();
227 + delivered();
228 + frame(102);
229 + expect(delivered()).toEqual([]);
230 + ack(extra, 100);
231 + await settle();
232 + expect(delivered()).toEqual([[extra, 102]]);
233 + // Other events still reach a session while its frame is unacknowledged.
234 + relay.event("Page.loadEventFired", { timestamp: 1 }, undefined);
235 + expect(delivered().map(([session]) => session)).toEqual(["t3-preview-page", extra]);
236 });
237 });
238
apps/desktop/src/preview/CdpRelay.ts
+62 -8
@@ -11,6 +11,8 @@ export interface CdpRelayTarget {
11 readonly sessionDetached?: (owner: string) => void;
12 /** Whether a page session, by owner as `send` names it, gets the page's screencast frames. */
13 readonly receivesScreencast: (owner: string | undefined) => boolean;
14 + /** Acknowledges a native screencast frame, letting Chromium send the next one. */
15 + readonly ackScreencastFrame: (frameId: number) => void;
16 /** The page's own CDP target id; Playwright keys the main frame by it. */
17 readonly targetId: () => Promise<string>;
18 readonly url: () => string;
@@ -103,6 +105,20 @@ export function createCdpRelayConnection(
105 let downloadEventsEnabled = false;
106 /** Relay-created page sessions share one real debugger; child frame sessions retain their own ids. */
107 const sessions = new Map<string, "browser" | "page">([[PAGE_SESSION_ID, "page"]]);
108 + // Each page session holds one unacknowledged frame and keeps the newest one skipped meanwhile.
109 + const unackedFrames = new Map<string, number>();
110 + const skippedFrames = new Map<string, Record<string, unknown>>();
111 + // Chromium keeps a few frames in flight and reuses one frame id per run, so pacing it means
112 + // leaving frames every session is busy for unacknowledged and releasing one per consumer ack.
113 + const heldNativeFrames: Array<number> = [];
114 + const releaseHeldFramesWithoutHolders = () => {
115 + if (skippedFrames.size === 0)
116 + for (const frameId of heldNativeFrames.splice(0)) target.ackScreencastFrame(frameId);
117 + };
118 + const sendFrame = (sessionId: string, params: Record<string, unknown>) => {
119 + unackedFrames.set(sessionId, params["sessionId"] as number);
120 + send({ method: "Page.screencastFrame", params, sessionId });
121 + };
122 let sessionSequence = 0;
123 const newSession = (kind: "browser" | "page") => {
124 const sessionId = `t3-preview-${kind}-${++sessionSequence}`;
@@ -170,6 +186,9 @@ export function createCdpRelayConnection(
186 const sessionId = command.params?.["sessionId"];
187 if (typeof sessionId === "string" && sessionId !== PAGE_SESSION_ID) {
188 sessions.delete(sessionId);
189 + unackedFrames.delete(sessionId);
190 + skippedFrames.delete(sessionId);
191 + releaseHeldFramesWithoutHolders();
192 target.sessionDetached?.(sessionId);
193 }
194 return {};
@@ -202,6 +221,27 @@ export function createCdpRelayConnection(
221 }
222 // Playwright asks for this on every page; the host emulates focus only while it is in use.
223 if (command.method === "Emulation.setFocusEmulationEnabled") return Promise.resolve({});
224 + if (command.method === "Page.screencastFrameAck" && child === undefined) {
225 + // A restart keeps the slot too, or restarting would let frames past an unacknowledged one.
226 + const sessionId = command.sessionId!;
227 + if (unackedFrames.get(sessionId) === command.params?.["sessionId"]) {
228 + unackedFrames.delete(sessionId);
229 + const skipped = skippedFrames.get(sessionId);
230 + skippedFrames.delete(sessionId);
231 + if (
232 + skipped !== undefined &&
233 + target.receivesScreencast(sessionId === PAGE_SESSION_ID ? undefined : sessionId)
234 + )
235 + sendFrame(sessionId, skipped);
236 + const released = heldNativeFrames.shift();
237 + if (released !== undefined) target.ackScreencastFrame(released);
238 + }
239 + return Promise.resolve({});
240 + }
241 + if (command.method === "Page.stopScreencast" && child === undefined) {
242 + skippedFrames.delete(command.sessionId!);
243 + releaseHeldFramesWithoutHolders();
244 + }
245 // The shared debugger keeps Runtime enabled after an earlier connection, and a repeated
246 // enable reports no existing contexts; Playwright waits for them, so reset once per connection.
247 if (command.method === "Runtime.enable" && child === undefined) {
@@ -262,15 +302,29 @@ export function createCdpRelayConnection(
302 send({ method, params, sessionId });
303 return;
304 }
265 - for (const [id, kind] of sessions) {
266 - if (kind !== "page") continue;
267 - if (
268 - method === "Page.screencastFrame" &&
269 - !target.receivesScreencast(id === PAGE_SESSION_ID ? undefined : id)
270 - )
271 - continue;
272 - send({ method, params, sessionId: id });
305 + if (method === "Page.screencastFrame") {
306 + const frame = (params ?? {}) as Record<string, unknown>;
307 + const frameId = frame["sessionId"];
308 + if (typeof frameId !== "number") return;
309 + let held = false;
310 + let delivered = false;
311 + for (const [id, kind] of sessions) {
312 + if (kind !== "page") continue;
313 + if (!target.receivesScreencast(id === PAGE_SESSION_ID ? undefined : id)) continue;
314 + if (unackedFrames.has(id)) {
315 + skippedFrames.set(id, frame);
316 + held = true;
317 + } else {
318 + sendFrame(id, frame);
319 + delivered = true;
320 + }
321 + }
322 + if (held && !delivered) heldNativeFrames.push(frameId);
323 + else target.ackScreencastFrame(frameId);
324 + return;
325 }
326 + for (const [id, kind] of sessions)
327 + if (kind === "page") send({ method, params, sessionId: id });
328 },
329 };
330 }
apps/desktop/src/preview/DesktopBrowserHost.test.ts
+7
@@ -1157,6 +1157,13 @@ describe("DesktopBrowserHost", () => {
1157 debuggee.refuse(6);
1158 debuggee.release();
1159 expect([yield* Queue.take(replies), yield* Queue.take(replies)].toSorted()).toEqual([5, 6]);
1160 + yield* raw({
1161 + id: 7,
1162 + method: "Page.screencastFrameAck",
1163 + params: { sessionId: 1 },
1164 + sessionId: "t3-preview-page-1",
1165 + });
1166 + expect(yield* Queue.take(replies)).toBe(7);
1167 yield* settle;
1168 frames.length = 0;
1169 debuggee.emit("Page.screencastFrame", { data: "frame", sessionId: 2 });
apps/desktop/src/preview/DesktopBrowserHost.ts
+4
@@ -421,6 +421,10 @@ export const make = Effect.gen(function* () {
421 dropSessionHolds(tab, owner);
422 },
423 receivesScreencast: (owner) => tab.screencasts.has(owner),
424 + ackScreencastFrame: (frameId) =>
425 + void debuggee
426 + .sendCommand("Page.screencastFrameAck", { sessionId: frameId })
427 + .catch(() => {}),
428 targetId: () =>
429 debuggee
430 .sendCommand("Target.getTargetInfo")
apps/desktop/src/preview/Manager.ts
+3 -18
@@ -1096,28 +1096,13 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
1096 ),
1097 scope,
1098 );
1099 - const handleDebuggerMessage = Effect.fnUntraced(function* (
1100 - method: string,
1101 - params: Record<string, unknown>,
1102 - ) {
1103 - if (method === "Page.screencastFrame") {
1104 - const sessionId = params["sessionId"];
1105 - if (typeof sessionId === "number") {
1106 - yield* attemptPromise(
1107 - {
1108 - operation: "ackScreencastFrame",
1109 - webContentsId: wc.id,
1110 - },
1111 - () => wcDebugger.sendCommand("Page.screencastFrameAck", { sessionId }),
1112 - ).pipe(Effect.ignore);
1113 - }
1114 - }
1099 + const handleDebuggerMessage = Effect.fnUntraced(function* (method: string) {
1100 if (method === "Runtime.consoleAPICalled" || method === "Runtime.exceptionThrown") {
1101 yield* Queue.offer(consoleReleases, undefined);
1102 }
1103 });
1119 - const onMessage: BrowserControlSession["onMessage"] = (_event, method, params) => {
1120 - runFork(handleDebuggerMessage(method, params));
1104 + const onMessage: BrowserControlSession["onMessage"] = (_event, method) => {
1105 + runFork(handleDebuggerMessage(method));
1106 };
1107 const control: BrowserControlSession = {
1108 webContentsId: wc.id,