The best way to control Claude Code, Codex and more from any computer or phone
fix(desktop): SnapShots keep working on Hyprland after an app update (#28240)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Ryan McDonough committed
Oct 31, 2026 at 19:47 UTC
77c885e8230ac726ece0ad3de6dc568bd9f6aeb6
6 files changed
+57
-10
apps/desktop/src/snapShot/DesktopSnapShot.test.ts
+17
@@ -427,6 +427,7 @@ import * as DesktopClientSettings from "../settings/DesktopClientSettings.ts";
427
import * as DesktopWindow from "../window/DesktopWindow.ts";
428
import * as DesktopSnapShot from "./DesktopSnapShot.ts";
429
import * as SnapShotAccessibility from "./SnapShotAccessibility.ts";
430
+import { CaptureSetupRequiredError } from "./linuxCaptureSession.ts";
431
432
const accessibilityApp = {
433
byPid: accessibilityByPidMock,
@@ -1875,6 +1876,22 @@ it.effect("capture fails closed while snapshots are disabled", () => {
1876
).pipe(Effect.provide(layerTest("win32")));
1877
});
1878
1879
+it.effect("points capture setup failures at SnapShot settings", () => {
1880
+ vi.stubEnv("XDG_SESSION_TYPE", "wayland");
1881
+ linuxCaptureMock.mockRejectedValueOnce(new CaptureSetupRequiredError("Install the helper."));
1882
+ return Effect.scoped(
1883
+ Effect.gen(function* () {
1884
+ const service = yield* DesktopSnapShot.make;
1885
+ yield* service.configure(enabledSettings());
1886
+ const failure = yield* Effect.flip(service.capture);
1887
+ assert.equal(failure.operation, "setup-required");
1888
+ }),
1889
+ ).pipe(
1890
+ Effect.provide(layerTest("linux", { makeDirectory: () => Effect.void })),
1891
+ Effect.ensuring(Effect.sync(() => vi.unstubAllEnvs())),
1892
+ );
1893
+});
1894
+
1895
it.effect(
1896
"keeps saved preferences but rechecks access and shortcut delivery after changing desktops",
1897
() => {
apps/desktop/src/snapShot/DesktopSnapShot.ts
+7
-3
@@ -50,6 +50,7 @@ import { niriSocketPath } from "./NiriSnapShot.ts";
50
import { CaptureShortcutConfig, niriCaptureConfigPath } from "./CaptureShortcutConfig.ts";
51
import type { PortalCaptureShortcut } from "./PortalCaptureShortcut.ts";
52
import {
53
+ CaptureSetupRequiredError,
54
isGnomeCaptureSession,
55
niriCaptureBinding,
56
portalShortcutTrigger,
@@ -128,6 +129,7 @@ const DesktopSnapShotOperation = Schema.Literals([
129
"disabled",
130
"no-window-selected",
131
"window-unavailable",
132
+ "setup-required",
133
"capture",
134
]);
135
@@ -155,6 +157,8 @@ export class DesktopSnapShotError extends Schema.TaggedError<DesktopSnapShotErro
157
return "No window was selected.";
158
case "window-unavailable":
159
return "The active window is not available for capture.";
160
+ case "setup-required":
161
+ return "Finish SnapShot setup in Settings → SnapShots.";
162
case "capture":
163
return "Could not capture the active window.";
164
}
@@ -164,9 +168,9 @@ export class DesktopSnapShotError extends Schema.TaggedError<DesktopSnapShotErro
168
const isDesktopSnapShotError = Schema.is(DesktopSnapShotError);
169
170
function captureFailure(cause: unknown, captureId?: string): DesktopSnapShotError {
167
- return isDesktopSnapShotError(cause)
168
- ? cause
169
- : new DesktopSnapShotError({ operation: "capture", captureId, cause });
171
+ if (isDesktopSnapShotError(cause)) return cause;
172
+ const operation = cause instanceof CaptureSetupRequiredError ? "setup-required" : "capture";
173
+ return new DesktopSnapShotError({ operation, captureId, cause });
174
}
175
176
export class DesktopSnapShot extends Context.Service<
apps/desktop/src/snapShot/HyprlandSnapShot.test.ts
+15
@@ -18,6 +18,7 @@ import {
18
hyprlandCaptureExecutable,
19
hyprlandCaptureShortcut,
20
} from "./HyprlandSnapShot.ts";
21
+import { CaptureSetupRequiredError } from "./linuxCaptureSession.ts";
22
23
let directory: string;
24
let paths: { bundle: string; dataHome: string };
@@ -86,6 +87,20 @@ it("updates explicitly and removes only its helper", async () => {
87
expect((await setup.state()).status).toBe("not-installed");
88
expect(await NodeFSP.readFile(unrelated, "utf8")).toBe("keep");
89
});
90
+it("updates a helper left stale by an app update before capturing", async () => {
91
+ await setup.perform("install-hyprland-helper");
92
+ await NodeFSP.writeFile(paths.bundle, "update");
93
+ const result = await captureHyprlandWindow(paths);
94
+ expect(result.png).toEqual(png);
95
+ expect(await NodeFSP.readFile(hyprlandCaptureExecutable(paths), "utf8")).toBe("update");
96
+ result.feedback?.close();
97
+});
98
+it("leaves first-time installation to explicit setup", async () => {
99
+ await expect(captureHyprlandWindow(paths)).rejects.toBeInstanceOf(CaptureSetupRequiredError);
100
+ await expect(NodeFSP.stat(hyprlandCaptureExecutable(paths))).rejects.toMatchObject({
101
+ code: "ENOENT",
102
+ });
103
+});
104
it("does not overwrite a linked executable", async () => {
105
const executable = hyprlandCaptureExecutable(paths);
106
await NodeFSP.mkdir(NodePath.dirname(executable), { recursive: true });
apps/desktop/src/snapShot/HyprlandSnapShot.ts
+10
-4
@@ -7,7 +7,7 @@ import * as NodeURL from "node:url";
7
import * as Schema from "effect/Schema";
8
import type { DesktopCaptureHelperState } from "@t3tools/contracts";
9
import type { LinuxWindowSnapshot } from "./LinuxSnapShot.ts";
10
-import { readPortalPng } from "./linuxCaptureSession.ts";
10
+import { CaptureSetupRequiredError, readPortalPng } from "./linuxCaptureSession.ts";
11
import { startNativeCaptureFeedback } from "./NativeCaptureFeedback.ts";
12
import { HYPRLAND_CAPTURE_ACTION } from "./linuxCaptureSession.ts";
13
export { isHyprlandCaptureSession } from "./linuxCaptureSession.ts";
@@ -167,9 +167,15 @@ export async function captureHyprlandWindow(
167
paths: HyprlandCapturePaths,
168
options?: { readonly flash: boolean; readonly animate: boolean },
169
): Promise<LinuxWindowSnapshot> {
170
- const state = await new HyprlandCaptureSetup(paths).state();
171
- if (state.status !== "ready")
172
- throw new Error(`${state.message} Open Settings → SnapShots to continue setup.`);
170
+ const setup = new HyprlandCaptureSetup(paths);
171
+ let state = await setup.state();
172
+ if (state.status === "update-required") {
173
+ await setup.perform("install-hyprland-helper").catch((cause: unknown) => {
174
+ throw new CaptureSetupRequiredError(state.message, { cause });
175
+ });
176
+ state = await setup.state();
177
+ }
178
+ if (state.status !== "ready") throw new CaptureSetupRequiredError(state.message);
179
const executable = hyprlandCaptureExecutable(paths);
180
const directory = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "t3-hyprland-capture-"));
181
const cleanup = () => NodeFSP.rm(directory, { recursive: true, force: true });
apps/desktop/src/snapShot/KdeSnapShot.ts
+2
-3
@@ -10,7 +10,7 @@ import type { DesktopCaptureHelperState } from "@t3tools/contracts";
10
11
import { escapeDesktopEntryExecArgument } from "../app/DesktopLinuxUrlHandler.ts";
12
import type { LinuxWindowSnapshot } from "./LinuxSnapShot.ts";
13
-import { readPortalPng } from "./linuxCaptureSession.ts";
13
+import { CaptureSetupRequiredError, readPortalPng } from "./linuxCaptureSession.ts";
14
import { startNativeCaptureFeedback } from "./NativeCaptureFeedback.ts";
15
export { isKdeCaptureSession } from "./linuxCaptureSession.ts";
16
@@ -215,8 +215,7 @@ export async function captureKdeWindow(
215
options?: { readonly flash: boolean; readonly animate: boolean },
216
): Promise<LinuxWindowSnapshot> {
217
const state = await new KdeCaptureSetup(paths).state();
218
- if (state.status !== "ready")
219
- throw new Error(`${state.message} Open Settings → SnapShots to continue setup.`);
218
+ if (state.status !== "ready") throw new CaptureSetupRequiredError(state.message);
219
const { executable } = kdeCapturePaths(paths);
220
const directory = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "t3-kde-capture-"));
221
let retained = false;
apps/desktop/src/snapShot/linuxCaptureSession.ts
+6
@@ -7,6 +7,12 @@ import { nativeImage } from "electron";
7
// Keep dbus-next out of desktop detection and PNG reads in the main process.
8
9
export const HYPRLAND_CAPTURE_ACTION = "capture-window";
10
+
11
+export class CaptureSetupRequiredError extends Error {
12
+ constructor(state: string, options?: ErrorOptions) {
13
+ super(`${state} Open Settings → SnapShots to continue setup.`, options);
14
+ }
15
+}
16
export const NIRI_CAPTURE_PATH = "/com/t3tools/SnapShot";
17
export const NIRI_CAPTURE_INTERFACE = "com.t3tools.SnapShot";
18