fix: recover failed editor frame handoffs

Author: richiemcilroy

apps/desktop/src/routes/editor/Editor.tsx

@@ -412,6 +412,14 @@ function Inner(props: {
 	onMount(() => {
 		const blockPreparingKeys = (event: KeyboardEvent) => {
 			if (editorReady()) return;
+			if (
+				preparingSession?.handoffFailed() &&
+				event.target instanceof Element &&
+				event.target.closest("[data-editor-handoff-error]")
+			) {
+				event.stopImmediatePropagation();
+				return;
+			}
 			if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "w")
 				return;
 			if (event.altKey && event.key === "F4") return;
@@ -877,12 +885,45 @@ function Inner(props: {
 		>
 			<div
 				class="relative flex flex-col flex-1 min-h-0"
-				aria-busy={!editorReady()}
+				aria-busy={!editorReady() && !preparingSession?.handoffFailed()}
 			>
 				<Header
 					registerTitleSave={registerEditorSave}
 					disabled={!editorReady()}
 				/>
+				<Show when={preparingSession?.handoffFailed()}>
+					<div class="absolute inset-0 top-13 max-[900px]:top-[72px] z-30 flex items-center justify-center p-6">
+						<div
+							data-editor-handoff-error
+							role="alertdialog"
+							aria-modal="true"
+							aria-labelledby="editor-handoff-error-title"
+							class="max-w-sm rounded-xl border border-ed-line bg-ed-card p-6 text-center shadow-ed-card"
+						>
+							<h2
+								id="editor-handoff-error-title"
+								class="text-sm font-medium text-ed-text-1"
+							>
+								Couldn’t open the editor
+							</h2>
+							<p class="mt-2 text-xs text-ed-text-2">
+								Try again to finish opening your recording.
+							</p>
+							<button
+								type="button"
+								class="mt-4 rounded-lg bg-ed-accent px-4 py-2 text-xs font-medium text-white"
+								ref={(button) =>
+									queueMicrotask(() => {
+										if (button.isConnected) button.focus();
+									})
+								}
+								onClick={() => void preparingSession?.retryHandoff()}
+							>
+								Try again
+							</button>
+						</div>
+					</div>
+				</Show>
 				<div
 					inert={!editorReady()}
 					class="flex overflow-y-hidden flex-col flex-1 gap-2 w-full min-h-0 leading-5 transition-opacity duration-300 ease-out motion-reduce:transition-none"

apps/desktop/src/routes/editor/EditorErrorScreen.tsx

@@ -195,6 +195,17 @@ export function EditorErrorScreen(props: {
 						<p class="text-sm text-gray-11">{props.error}</p>
 					</div>
 
+					<Show when={!needsRecovery()}>
+						<Button
+							onClick={() => window.location.reload()}
+							variant="primary"
+							class="w-full"
+						>
+							<IconRefreshCw class="size-4 mr-2" />
+							Try again
+						</Button>
+					</Show>
+
 					<Show when={needsRecovery()}>
 						<div class="bg-gray-2 border border-gray-4 rounded-xl p-4 space-y-4">
 							<div class="space-y-2">

apps/desktop/src/routes/editor/preparing-editor-context.test.ts

@@ -0,0 +1,101 @@
+import { createRoot } from "solid-js";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { FrameData } from "~/utils/socket";
+import { createPreparingEditorSession } from "./preparing-editor-context";
+
+const { commitFrame, stopFrame } = vi.hoisted(() => ({
+	commitFrame: vi.fn<() => Promise<boolean>>(),
+	stopFrame: vi.fn(async () => {}),
+}));
+
+vi.mock("~/utils/tauri", () => ({
+	commands: {
+		commitEditorPreparingFrame: commitFrame,
+		stopPreparingEditorFrame: stopFrame,
+	},
+	events: {},
+}));
+
+const frame: FrameData = {
+	width: 1920,
+	height: 1080,
+	renderedFrame: { frameNumber: 0, targetTimeNs: 0n },
+};
+const bounds = { width: 640, height: 360 };
+const cleanups: Array<() => void> = [];
+
+function sessionWithCandidate(retry: () => Promise<unknown>) {
+	return createRoot((dispose) => {
+		cleanups.push(dispose);
+		const session = createPreparingEditorSession();
+		session.beginHandoff(30, 10, {
+			instanceId: "first",
+			fps: 30,
+			progressive: true,
+			retry,
+			requestFrame() {},
+		});
+		return { session, dispose };
+	});
+}
+
+afterEach(() => {
+	for (const dispose of cleanups.splice(0)) dispose();
+	vi.restoreAllMocks();
+	vi.clearAllMocks();
+});
+
+describe("preparing editor handoff recovery", () => {
+	it("surfaces a commit failure and enables editing only after retry is accepted", async () => {
+		vi.spyOn(console, "error").mockImplementation(() => {});
+		commitFrame.mockRejectedValueOnce(new Error("connection lost"));
+		commitFrame.mockResolvedValueOnce(true);
+		const retry = vi.fn(async () => {});
+		const { session } = sessionWithCandidate(retry);
+		session.acknowledgeOrdinaryFrame(frame, bounds);
+		await vi.waitFor(() => expect(session.handoffFailed()).toBe(true));
+		expect(session.ordinaryReady()).toBe(false);
+		await session.retryHandoff();
+		expect(retry).toHaveBeenCalledOnce();
+		expect(session.handoffFailed()).toBe(false);
+		expect(session.ordinaryReady()).toBe(false);
+		session.acknowledgeOrdinaryFrame(frame, bounds);
+		await vi.waitFor(() => expect(session.ordinaryReady()).toBe(true));
+		expect(session.handoffFailed()).toBe(false);
+	});
+
+	it("keeps recovery available when replacing the candidate fails", async () => {
+		vi.spyOn(console, "error").mockImplementation(() => {});
+		commitFrame.mockRejectedValueOnce(
+			"Preparing handoff candidate was superseded",
+		);
+		const retry = vi.fn(async () => {
+			throw new Error("replacement failed");
+		});
+		const { session } = sessionWithCandidate(retry);
+		session.acknowledgeOrdinaryFrame(frame, bounds);
+		await vi.waitFor(() => expect(session.handoffFailed()).toBe(true));
+		expect(retry).toHaveBeenCalledOnce();
+		await session.retryHandoff();
+		expect(retry).toHaveBeenCalledTimes(2);
+		expect(session.handoffFailed()).toBe(true);
+		expect(session.ordinaryReady()).toBe(false);
+	});
+
+	it("ignores a rejected handoff after the editor has closed", async () => {
+		let reject!: (error: Error) => void;
+		commitFrame.mockImplementationOnce(
+			() =>
+				new Promise<boolean>((_, fail) => {
+					reject = fail;
+				}),
+		);
+		const { session, dispose } = sessionWithCandidate(async () => {});
+		session.acknowledgeOrdinaryFrame(frame, bounds);
+		dispose();
+		reject(new Error("late failure"));
+		await new Promise<void>((resolve) => queueMicrotask(resolve));
+		expect(session.handoffFailed()).toBe(false);
+		expect(session.ordinaryReady()).toBe(false);
+	});
+});

apps/desktop/src/routes/editor/preparing-editor-context.tsx

@@ -22,7 +22,7 @@ import { attachPreparingFrameTransport } from "./preparing-frame-transport";
 import { createPreparingHandoff } from "./preparing-handoff";
 import type { createPreparingPlaybackHandoff } from "./preparing-playback-handoff";
 
-function createPreparingEditorSession() {
+export function createPreparingEditorSession() {
 	const model = createPreparingEditorModel();
 	const handoff = createPreparingHandoff();
 	const owner = getOwner();
@@ -55,6 +55,16 @@ function createPreparingEditorSession() {
 	}>();
 	const [retained, setRetained] = createSignal(false);
 	const [ordinaryReady, setOrdinaryReady] = createSignal(false);
+	const [handoffFailed, setHandoffFailed] = createSignal(false);
+	const retryHandoff = async () => {
+		setHandoffFailed(false);
+		try {
+			await retryCandidate();
+		} catch (error) {
+			if (alive && !ordinaryReady()) setHandoffFailed(true);
+			console.error("Failed to replace preparing editor:", error);
+		}
+	};
 	const lease = createPreparingFrameLease({
 		start: async (epoch) => {
 			const url = await commands.createPreparingEditorFrame(epoch);
@@ -144,13 +154,16 @@ function createPreparingEditorSession() {
 		canvases,
 		retained,
 		ordinaryReady,
+		handoffFailed,
+		retryHandoff,
 		acceptSnapshot: subscription.accept,
 		beginHandoff(
 			fps: number,
 			recordingDuration: number,
 			value: NonNullable<typeof candidate>,
 		) {
 			candidate = value;
+			setHandoffFailed(false);
 			const target = handoff.begin(
 				model.playback(),
 				fps,
@@ -222,16 +235,16 @@ function createPreparingEditorSession() {
 						return;
 					}
 					playbackHandoff?.acknowledge(frameNumber, current.progressive);
+					setHandoffFailed(false);
 					setOrdinaryReady(true);
 					lease.close();
 				})
 				.catch((error: unknown) => {
 					if (!alive || candidate !== current) return;
 					if (String(error) === "Preparing handoff candidate was superseded") {
-						void retryCandidate()?.catch((cause: unknown) =>
-							console.error("Failed to replace preparing editor:", cause),
-						);
+						void retryHandoff();
 					} else {
+						setHandoffFailed(true);
 						console.error("Failed to accept preparing editor frame:", error);
 					}
 				});