@forsion/tangu-computer-use 0.5.8

package/src/vendor/platform/windows/backend.ts

@@ -0,0 +1,142 @@
+import { parseLookResponse, type LookResponse } from "../../outline.ts";
+import { toBoolean, toFiniteNumber, toOptionalString } from "../coerce.ts";
+import type { ComputerUsePlatformBackend, FramePoints, HelperActResult, PlatformActRequest, PlatformApp, PlatformFocusWindowResult, PlatformFrontmostResult, PlatformObserveRequest, PlatformReadTextRequest, PlatformReadTextResponse, PlatformReadyState, PlatformRoot, PlatformRootKind, PlatformRootQuery, PlatformTarget, PlatformWaitForRequest, PlatformWaitForResponse } from "../types.ts";
+import { WINDOWS_HELPER_PROTOCOL_VERSION, windowsHelper } from "./helper.ts";
+import { assertPlatformArchitecture } from "../architecture.ts";
+
+function normalizedProcessName(appName: string): string {
+	return appName.toLowerCase().replace(/\.exe$/i, "");
+}
+
+function classifyBrowser(appName: string): false | "chrome" | "edge" | "brave" | "firefox" | "vivaldi" | "opera" {
+	switch (normalizedProcessName(appName)) {
+		case "chrome":
+		case "chromium":
+			return "chrome";
+		case "msedge":
+		case "edge":
+			return "edge";
+		case "brave":
+		case "brave-browser":
+			return "brave";
+		case "firefox":
+			return "firefox";
+		case "vivaldi":
+			return "vivaldi";
+		case "opera":
+		case "opera_gx":
+			return "opera";
+		default:
+			return false;
+	}
+}
+
+function parseFramePoints(raw: unknown): FramePoints {
+	const frame = (raw as any)?.framePoints ?? (raw as any)?.bounds ?? {};
+	return {
+		x: toFiniteNumber(frame.x, 0),
+		y: toFiniteNumber(frame.y, 0),
+		w: Math.max(1, toFiniteNumber(frame.w ?? frame.width, 1)),
+		h: Math.max(1, toFiniteNumber(frame.h ?? frame.height, 1)),
+	};
+}
+
+function parseRootKind(raw: unknown): PlatformRootKind {
+	return raw === "menu" || raw === "dialog" || raw === "popover" || raw === "window" ? raw : "window";
+}
+
+function parseRoots(result: unknown): PlatformRoot[] {
+	const array = Array.isArray(result) ? result : (result as any)?.roots;
+	if (!Array.isArray(array)) return [];
+	return array.map((raw: any, index): PlatformRoot => {
+		return {
+			kind: parseRootKind(raw?.kind),
+			rootRef: toOptionalString(raw?.rootRef ?? raw?.windowRef ?? raw?.ref),
+			windowRef: toOptionalString(raw?.windowRef ?? raw?.rootRef ?? raw?.ref),
+			windowId: Number.isFinite(raw?.windowId) ? Math.trunc(raw.windowId) : undefined,
+			pid: Number.isFinite(raw?.pid) ? Math.trunc(raw.pid) : undefined,
+			appName: toOptionalString(raw?.appName ?? raw?.processName),
+			bundleId: toOptionalString(raw?.bundleId),
+			title: toOptionalString(raw?.title) ?? "",
+			role: toOptionalString(raw?.role),
+			subrole: toOptionalString(raw?.subrole),
+			zOrder: Math.trunc(toFiniteNumber(raw?.zOrder, index)),
+			framePoints: parseFramePoints(raw),
+			scaleFactor: Math.max(1, toFiniteNumber(raw?.scaleFactor, 1)),
+			isOnscreen: raw?.isOnscreen === undefined ? true : toBoolean(raw?.isOnscreen),
+			isFocused: toBoolean(raw?.isFocused),
+			isMinimized: toBoolean(raw?.isMinimized),
+			isMain: toBoolean(raw?.isMain ?? raw?.isFocused),
+			isModal: toBoolean(raw?.isModal),
+			metadata: raw?.metadata,
+		};
+	});
+}
+
+function appsFromRoots(roots: PlatformRoot[]): PlatformApp[] {
+	const seen = new Set<number>();
+	return roots.flatMap((root) => {
+		if (!root.pid || seen.has(root.pid)) return [];
+		seen.add(root.pid);
+		return [{ appName: root.appName ?? "Unknown", bundleId: root.bundleId, pid: root.pid, isFrontmost: root.isFocused }];
+	});
+}
+
+function helperAction(request: PlatformActRequest): Record<string, unknown> {
+	if (!("focus" in request.target)) return { ...request };
+	return { ...request, target: request.target.focus, params: { ...request.params, preserveFocus: true } };
+}
+
+async function ensureReady(_ctx: unknown, state: PlatformReadyState, signal?: AbortSignal): Promise<PlatformReadyState> {
+	await windowsHelper.ensureInstalled(signal);
+	const diagnostics = await windowsHelper.command<any>("diagnostics", {}, { signal, timeoutMs: 5_000 });
+	if (diagnostics?.protocolVersion !== WINDOWS_HELPER_PROTOCOL_VERSION) {
+		throw new Error(`Windows helper protocol mismatch: expected ${WINDOWS_HELPER_PROTOCOL_VERSION}, got ${diagnostics?.protocolVersion ?? "unknown"}. Restart Tangu to use the installed helper.`);
+	}
+	assertPlatformArchitecture("Windows", diagnostics);
+	return { ...state, lastPermissionCheckAt: Date.now(), helperDiagnostics: diagnostics };
+}
+
+export const windowsBackend: ComputerUsePlatformBackend = {
+	name: "windows",
+	shutdown(): void { windowsHelper.dispose(); },
+	ensureReady,
+	async listApps(signal?: AbortSignal): Promise<PlatformApp[]> {
+		return appsFromRoots(parseRoots(await windowsHelper.command("listRoots", {}, { signal })));
+	},
+	async listRoots(query: PlatformRootQuery, signal?: AbortSignal): Promise<PlatformRoot[]> {
+		const roots = parseRoots(await windowsHelper.command("listRoots", Number.isFinite(query.pid) ? { pid: Math.trunc(query.pid!) } : {}, { signal }));
+		const title = query.title?.trim().toLowerCase();
+		return title ? roots.filter((root) => root.title.trim().toLowerCase().includes(title)) : roots;
+	},
+	async getFrontmost(signal?: AbortSignal): Promise<PlatformFrontmostResult> {
+		const roots = parseRoots(await windowsHelper.command("listRoots", {}, { signal }));
+		const focused = roots.find((root) => root.isFocused) ?? roots[0];
+		if (!focused?.pid) throw new Error("No frontmost window was available.");
+		return { appName: focused.appName ?? "Unknown", bundleId: focused.bundleId, pid: focused.pid, windowTitle: focused.title, windowId: focused.windowId, rootRef: focused.rootRef };
+	},
+	async focusWindow(target: PlatformTarget, signal?: AbortSignal): Promise<PlatformFocusWindowResult> {
+		return await windowsHelper.command<PlatformFocusWindowResult>("focusWindow", { ...target }, { signal });
+	},
+	async observe(request: PlatformObserveRequest, options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<LookResponse> {
+		return parseLookResponse(await windowsHelper.command("look", { ...request.target, baseLookId: request.baseLookId, maxDimension: request.maxDimension, readText: request.readText, scopeRef: request.scopeRef, includeImage: request.includeImage }, options));
+	},
+	async act(request: PlatformActRequest, options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<HelperActResult> {
+		return await windowsHelper.command<HelperActResult>("act", helperAction(request), options);
+	},
+	async actBatch(requests: PlatformActRequest[], options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<HelperActResult> {
+		return await windowsHelper.command<HelperActResult>("actBatch", { actions: requests.map(helperAction) }, options);
+	},
+	async readText(args: PlatformReadTextRequest, options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<PlatformReadTextResponse> {
+		return await windowsHelper.command("uiaReadText", { ...args }, options);
+	},
+	async waitFor(args: PlatformWaitForRequest, options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<PlatformWaitForResponse> {
+		return await windowsHelper.command("uiaWaitFor", { ...args }, options);
+	},
+	isBrowserApp(appName: string): boolean { return classifyBrowser(appName) !== false; },
+	isChromeFamilyApp(appName: string): boolean { return classifyBrowser(appName) === "chrome" || classifyBrowser(appName) === "edge" || classifyBrowser(appName) === "brave"; },
+	async openBrowserLocation(target: { appName: string; bundleId?: string }, url: string, signal?: AbortSignal): Promise<boolean> {
+		await windowsHelper.command("openBrowserLocation", { ...target, url }, { signal, timeoutMs: 10_000 });
+		return true;
+	},
+};

package/src/vendor/platform/windows/helper.ts

@@ -0,0 +1,140 @@
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { access } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+const SETUP_HELPER_SCRIPT = path.join(PACKAGE_ROOT, "scripts", "setup-helper.mjs");
+const HELPER_SETUP_TIMEOUT_MS = 60_000;
+const COMMAND_TIMEOUT_MS = 15_000;
+
+export const WINDOWS_HELPER_PROTOCOL_VERSION = 4;
+export const WINDOWS_HELPER_PATH = process.env.PI_COMPUTER_USE_WINDOWS_HELPER_PATH || path.join(os.homedir(), ".pi", "agent", "helpers", "tangu-computer-use", "windows-bridge.exe");
+
+interface Pending<T> {
+	resolve(value: T): void;
+	reject(error: Error): void;
+	timer: NodeJS.Timeout;
+}
+
+async function isExecutable(filePath: string): Promise<boolean> {
+	try { await access(filePath, fsConstants.X_OK); return true; } catch { return false; }
+}
+
+async function runProcess(command: string, args: string[], timeoutMs: number, signal?: AbortSignal, env?: NodeJS.ProcessEnv): Promise<void> {
+	if (signal?.aborted) throw new Error("Operation aborted.");
+	await new Promise<void>((resolve, reject) => {
+		const child = spawn(command, args, { stdio: ["ignore", "pipe", "pipe"], env });
+		let stdout = "";
+		let stderr = "";
+		const cleanup = () => { clearTimeout(timer); signal?.removeEventListener("abort", onAbort); };
+		const timer = setTimeout(() => { child.kill("SIGTERM"); cleanup(); reject(new Error(`Command timed out after ${timeoutMs}ms: ${command} ${args.join(" ")}`)); }, timeoutMs);
+		const onAbort = () => { child.kill("SIGTERM"); cleanup(); reject(new Error("Operation aborted.")); };
+		child.stdout.on("data", (chunk) => { stdout += String(chunk); });
+		child.stderr.on("data", (chunk) => { stderr += String(chunk); });
+		child.on("error", (error) => { cleanup(); reject(error); });
+		child.on("close", (code) => {
+			cleanup();
+			if (code === 0) return resolve();
+			const output = [stderr.trim(), stdout.trim()].filter(Boolean).join("\n");
+			reject(new Error(`Command failed (${code}): ${command} ${args.join(" ")}\n${output}`.trim()));
+		});
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+export class WindowsHelperClient {
+	private installChecked = false;
+	private child?: ChildProcessWithoutNullStreams;
+	private buffer = "";
+	private pending = new Map<string, Pending<unknown>>();
+
+	dispose(): void {
+		const error = new Error("Windows helper closed because the Tangu session ended.");
+		for (const pending of this.pending.values()) {
+			clearTimeout(pending.timer);
+			pending.reject(error);
+		}
+		this.pending.clear();
+		this.buffer = "";
+
+		const child = this.child;
+		this.child = undefined;
+		if (!child) return;
+		child.stdin.destroy();
+		child.stdout.destroy();
+		child.stderr.destroy();
+		child.kill("SIGTERM");
+		child.unref();
+	}
+
+	async ensureInstalled(signal?: AbortSignal): Promise<void> {
+		if ((await isExecutable(WINDOWS_HELPER_PATH)) && this.installChecked) return;
+		// Re-enter Electron and Bun standalone hosts as their JavaScript runtimes.
+		await runProcess(process.execPath, [SETUP_HELPER_SCRIPT, "--platform", "windows", "--runtime"], HELPER_SETUP_TIMEOUT_MS, signal, { ...process.env, ELECTRON_RUN_AS_NODE: "1", BUN_BE_BUN: "1" });
+		this.installChecked = true;
+		if (!(await isExecutable(WINDOWS_HELPER_PATH))) throw new Error(`Failed to install Windows helper at ${WINDOWS_HELPER_PATH}.`);
+	}
+
+	private async process(signal?: AbortSignal): Promise<ChildProcessWithoutNullStreams> {
+		await this.ensureInstalled(signal);
+		if (this.child && this.child.exitCode === null && !this.child.killed) return this.child;
+		const child = spawn(WINDOWS_HELPER_PATH, [], { stdio: ["pipe", "pipe", "pipe"] });
+		child.stdout.setEncoding("utf8");
+		child.stderr.setEncoding("utf8");
+		child.stdin.setDefaultEncoding("utf8");
+		child.stdout.on("data", (chunk: string) => this.onStdout(chunk));
+		child.on("exit", () => { if (this.child === child) this.child = undefined; });
+		child.on("error", () => { if (this.child === child) this.child = undefined; });
+		this.child = child;
+		this.buffer = "";
+		return child;
+	}
+
+	private onStdout(chunk: string): void {
+		this.buffer += chunk;
+		for (;;) {
+			const newline = this.buffer.indexOf("\n");
+			if (newline < 0) return;
+			const line = this.buffer.slice(0, newline).trim();
+			this.buffer = this.buffer.slice(newline + 1);
+			if (!line) continue;
+			let parsed: any;
+			try { parsed = JSON.parse(line); } catch { continue; }
+			const pending = this.pending.get(parsed.id);
+			if (!pending) continue;
+			this.pending.delete(parsed.id);
+			clearTimeout(pending.timer);
+			if (parsed.protocolVersion !== WINDOWS_HELPER_PROTOCOL_VERSION) {
+				pending.reject(new Error(`Windows helper protocol mismatch: expected ${WINDOWS_HELPER_PROTOCOL_VERSION}, got ${parsed.protocolVersion ?? "unknown"}. Restart Tangu to use the installed helper.`));
+			} else if (parsed.ok === true) {
+				pending.resolve(parsed.result);
+			} else {
+				const error = new Error(parsed.error?.message ?? "Windows helper command failed.") as Error & { code?: string };
+				error.code = parsed.error?.code;
+				pending.reject(error);
+			}
+		}
+	}
+
+	async command<T>(cmd: string, args: Record<string, unknown> = {}, options?: { timeoutMs?: number; signal?: AbortSignal }): Promise<T> {
+		const child = await this.process(options?.signal);
+		const id = randomUUID();
+		const timeoutMs = options?.timeoutMs ?? COMMAND_TIMEOUT_MS;
+		return await new Promise<T>((resolve, reject) => {
+			const timer = setTimeout(() => { this.pending.delete(id); reject(new Error(`Helper command '${cmd}' timed out after ${timeoutMs}ms.`)); }, timeoutMs);
+			this.pending.set(id, { resolve: resolve as (value: unknown) => void, reject, timer });
+			child.stdin.write(`${JSON.stringify({ protocolVersion: WINDOWS_HELPER_PROTOCOL_VERSION, id, cmd, args })}\n`, (error) => {
+				if (!error) return;
+				this.pending.delete(id);
+				clearTimeout(timer);
+				reject(error);
+			});
+		});
+	}
+}
+
+export const windowsHelper = new WindowsHelperClient();

package/src/vendor/root-selection.ts

@@ -0,0 +1,25 @@
+import type { PlatformRoot } from "./platform/types.ts";
+
+type RankedRoot = Pick<PlatformRoot,
+	"windowId" | "windowRef" | "isModal" | "isFocused" | "isMain" | "isMinimized" | "isOnscreen" | "zOrder" | "title"
+>;
+
+export function scoreWindow(window: RankedRoot): number {
+	let score = 0;
+	if (window.isModal) score += 180;
+	if (window.isFocused) score += 100;
+	if (window.isMain) score += 80;
+	if (!window.isMinimized) score += 40;
+	if (window.isOnscreen) score += 20;
+	if (window.windowId && window.windowId > 0) score += 10;
+	if (window.title.trim().length > 0) score += 2;
+	return score;
+}
+
+export function shouldPreferForegroundModalWindow(current: RankedRoot, candidate: RankedRoot): boolean {
+	if (candidate.windowId === current.windowId && candidate.windowRef === current.windowRef) return false;
+	if (!candidate.isOnscreen || candidate.isMinimized || !candidate.isModal) return false;
+	// AXDialog can describe a background main window, so modality alone is insufficient.
+	const candidateIsInFront = candidate.isFocused || candidate.zOrder < current.zOrder;
+	return candidateIsInFront && scoreWindow(candidate) >= scoreWindow(current);
+}

package/src/vendor/runtime.ts

@@ -0,0 +1,129 @@
+import { randomUUID } from "node:crypto";
+
+export interface StoredState<T> {
+	stateId: string;
+	resourceKey: string;
+	epoch: number;
+	value: T;
+}
+
+export class StaleResourceStateError extends Error {
+	constructor(readonly resourceKey: string, readonly expectedEpoch: number, readonly actualEpoch: number) {
+		super(`State is stale for ${resourceKey}: expected epoch ${expectedEpoch}, current epoch ${actualEpoch}.`);
+		this.name = "StaleResourceStateError";
+	}
+}
+
+/** Bounded insertion-ordered store for immutable agent-facing observations. */
+export class StateStore<T> {
+	private readonly records = new Map<string, StoredState<T>>();
+
+	constructor(private readonly limit = 128) {}
+
+	create(resourceKey: string, epoch: number, value: T): StoredState<T> {
+		const record = { stateId: randomUUID(), resourceKey, epoch, value };
+		this.set(record);
+		return record;
+	}
+
+	set(record: StoredState<T>): void {
+		this.records.delete(record.stateId);
+		this.records.set(record.stateId, record);
+		while (this.records.size > this.limit) {
+			const oldest = this.records.keys().next().value as string | undefined;
+			if (!oldest) break;
+			this.records.delete(oldest);
+		}
+	}
+
+	get(stateId: string): StoredState<T> | undefined {
+		return this.records.get(stateId);
+	}
+
+	clear(): void {
+		this.records.clear();
+	}
+
+	get size(): number {
+		return this.records.size;
+	}
+}
+
+interface ResourceRecord {
+	epoch: number;
+	tail: Promise<void>;
+}
+
+/**
+ * Orders live operations per physical resource while allowing unrelated
+ * resources to overlap. Cached state queries bypass this scheduler entirely.
+ */
+export class ResourceScheduler {
+	private readonly resources = new Map<string, ResourceRecord>();
+	private closed = false;
+
+	epoch(resourceKey: string): number {
+		return this.resource(resourceKey).epoch;
+	}
+
+	restoreEpoch(resourceKey: string, epoch: number): void {
+		const record = this.resource(resourceKey);
+		record.epoch = Math.max(record.epoch, Math.max(0, Math.trunc(epoch)));
+	}
+
+	async read<T>(resourceKey: string, work: (epoch: number) => Promise<T>): Promise<{ value: T; epoch: number }> {
+		return await this.enqueue(resourceKey, async (record) => ({ value: await work(record.epoch), epoch: record.epoch }));
+	}
+
+	async readAt<T>(resourceKey: string, expectedEpoch: number, work: (epoch: number) => Promise<T>): Promise<{ value: T; epoch: number }> {
+		return await this.enqueue(resourceKey, async (record) => {
+			if (record.epoch !== expectedEpoch) throw new StaleResourceStateError(resourceKey, expectedEpoch, record.epoch);
+			return { value: await work(record.epoch), epoch: record.epoch };
+		});
+	}
+
+	async write<T>(resourceKey: string, baseEpoch: number, work: (nextEpoch: number) => Promise<T>): Promise<{ value: T; epoch: number }> {
+		return await this.enqueue(resourceKey, async (record) => {
+			if (record.epoch !== baseEpoch) throw new StaleResourceStateError(resourceKey, baseEpoch, record.epoch);
+			const nextEpoch = record.epoch + 1;
+			// Invalidate the base state before dispatch. If native execution becomes
+			// uncertain or throws after a partial effect, later writes still fail safe.
+			record.epoch = nextEpoch;
+			return { value: await work(nextEpoch), epoch: nextEpoch };
+		});
+	}
+
+	async drain(): Promise<void> {
+		await Promise.all([...this.resources.values()].map((record) => record.tail.catch(() => undefined)));
+	}
+
+	async close(): Promise<void> {
+		this.closed = true;
+		await this.drain();
+		this.resources.clear();
+	}
+
+	private resource(resourceKey: string): ResourceRecord {
+		let record = this.resources.get(resourceKey);
+		if (!record) {
+			record = { epoch: 0, tail: Promise.resolve() };
+			this.resources.set(resourceKey, record);
+		}
+		return record;
+	}
+
+	private async enqueue<T>(resourceKey: string, work: (record: ResourceRecord) => Promise<T>): Promise<T> {
+		if (this.closed) throw new Error("Computer-use session is shutting down.");
+		const record = this.resource(resourceKey);
+		const previous = record.tail;
+		let release!: () => void;
+		const next = new Promise<void>((resolve) => { release = resolve; });
+		record.tail = previous.catch(() => undefined).then(() => next);
+		await previous.catch(() => undefined);
+		try {
+			return await work(record);
+		} finally {
+			release();
+		}
+	}
+}

package/src/vendor/state.ts

@@ -0,0 +1,146 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { CdpPageSnapshot } from "./cdp.ts";
+import type { ImageMode } from "./contract.ts";
+import type { WindowNote } from "./note.ts";
+import { restoreOutline, serializeOutline, type LookResponse, type Outline, type SerializedOutline } from "./outline.ts";
+import { StateStore, type StoredState } from "./runtime.ts";
+
+interface StateTargetSnapshot {
+	pid: number;
+	windowId: number;
+	windowRef?: string;
+}
+
+export interface CurrentTarget {
+	appName: string;
+	bundleId?: string;
+	pid: number;
+	windowTitle: string;
+	windowId: number;
+	windowRef?: string;
+	nativeWindowRef?: string;
+}
+
+export interface CurrentCapture {
+	stateId: string;
+	width: number;
+	height: number;
+	scaleFactor: number;
+	timestamp: number;
+}
+
+export interface OperationState {
+	currentTarget?: CurrentTarget;
+	currentCapture?: CurrentCapture;
+	currentStateTarget?: StateTargetSnapshot;
+	currentImageMode?: ImageMode;
+	currentLook?: LookResponse;
+	currentOutline?: Outline;
+	currentNote?: WindowNote;
+	resourceKey?: string;
+	epoch?: number;
+	lastSearchOcrEscalatedLookId?: string;
+	browserSnapshot?: CdpPageSnapshot;
+	contextId?: string;
+}
+
+interface DesktopObservation {
+	kind: "desktop";
+	target: CurrentTarget;
+	capture: CurrentCapture;
+	look: Omit<LookResponse, "parsedOutline" | "outline">;
+	outline: SerializedOutline;
+	note?: WindowNote;
+	imageMode?: ImageMode;
+}
+
+interface BrowserObservation {
+	kind: "browser";
+	snapshot: CdpPageSnapshot;
+	outline: SerializedOutline;
+}
+
+export type UiObservation = DesktopObservation | BrowserObservation;
+
+export class SavedStates {
+	readonly store = new StateStore<UiObservation>(128);
+	readonly operations = new AsyncLocalStorage<OperationState>();
+
+	current(): OperationState {
+		const state = this.operations.getStore();
+		if (!state) throw new Error("Computer-use operation state is unavailable.");
+		return state;
+	}
+
+	get(stateId: string): StoredState<UiObservation> | undefined {
+		return this.store.get(stateId);
+	}
+
+	set(record: StoredState<UiObservation>): void {
+		this.store.set(record);
+	}
+
+	clear(): void {
+		this.store.clear();
+	}
+
+	hydrate(record: StoredState<UiObservation> | undefined): OperationState {
+		if (!record) return {};
+		if (record.value.kind === "browser") {
+			const outline = restoreOutline(record.value.outline);
+			return {
+				currentCapture: { stateId: record.stateId, width: 0, height: 0, scaleFactor: 1, timestamp: record.value.snapshot.capturedAt },
+				currentLook: {
+					lookId: record.value.snapshot.snapshotId,
+					capturedAt: record.value.snapshot.capturedAt / 1000,
+					window: { windowId: 0, framePoints: { x: 0, y: 0, w: 1, h: 1 }, scaleFactor: 1, isModal: false, role: "document", subrole: "" },
+					outline: outline.root,
+					timings: {},
+					parsedOutline: outline,
+				},
+				currentOutline: outline,
+				resourceKey: record.resourceKey,
+				epoch: record.epoch,
+				browserSnapshot: record.value.snapshot,
+				contextId: record.value.snapshot.contextId,
+			};
+		}
+		const outline = restoreOutline(record.value.outline);
+		return {
+			currentTarget: { ...record.value.target },
+			currentCapture: { ...record.value.capture },
+			currentStateTarget: { pid: record.value.target.pid, windowId: record.value.target.windowId, windowRef: record.value.target.windowRef },
+			currentImageMode: record.value.imageMode,
+			currentLook: { ...record.value.look, outline: outline.root, parsedOutline: outline },
+			currentOutline: outline,
+			currentNote: record.value.note ? structuredClone(record.value.note) : undefined,
+			resourceKey: record.resourceKey,
+			epoch: record.epoch,
+		};
+	}
+
+	saveDesktop(state: OperationState, resourceKey: string, epoch: number): void {
+		if (!state.currentTarget || !state.currentCapture || !state.currentLook || !state.currentOutline) return;
+		this.store.set({
+			stateId: state.currentCapture.stateId,
+			resourceKey,
+			epoch,
+			value: {
+				kind: "desktop",
+				target: { ...state.currentTarget },
+				capture: { ...state.currentCapture },
+				look: {
+					lookId: state.currentLook.lookId,
+					capturedAt: state.currentLook.capturedAt,
+					window: structuredClone(state.currentLook.window),
+					image: state.currentLook.image ? { ...state.currentLook.image } : undefined,
+					timings: { ...state.currentLook.timings },
+					readText: state.currentLook.readText ? { ...state.currentLook.readText } : undefined,
+				},
+				outline: serializeOutline(state.currentOutline),
+				note: state.currentNote ? structuredClone(state.currentNote) : undefined,
+				imageMode: state.currentImageMode,
+			},
+		});
+	}
+}