// @effect-diagnostics nodeBuiltinImport:off -- KDE authorizes a dedicated, installed native executable.
import * as NodeCrypto from "node:crypto";
import * as NodeChildProcess from "node:child_process";
import * as NodeFSP from "node:fs/promises";
import * as NodeOS from "node:os";
import * as NodePath from "node:path";
import * as NodeURL from "node:url";
import * as Schema from "effect/Schema";
import type { DesktopCaptureHelperState } from "@t3tools/contracts";
import { escapeDesktopEntryExecArgument } from "../app/DesktopLinuxUrlHandler.ts";
import type { LinuxWindowSnapshot } from "./LinuxSnapShot.ts";
import { CaptureSetupRequiredError, readPortalPng } from "./linuxCaptureSession.ts";
import { startNativeCaptureFeedback } from "./NativeCaptureFeedback.ts";
export { isKdeCaptureSession } from "./linuxCaptureSession.ts";
export const KDE_CAPTURE_EXECUTABLE = "t3-kde-snap-shot";
const DESKTOP_FILE = "com.t3tools.T3Code.KdeCapture.desktop";
const MARKER = "X-T3Code-Capture-Helper=true";
const decodeCapabilities = Schema.decodeUnknownSync(
Schema.fromJsonString(Schema.Struct({ feedbackAvailable: Schema.optional(Schema.Boolean) })),
);
export type KdeCapturePaths = { readonly bundle: string; readonly dataHome: string };
export function kdeCapturePaths(paths: KdeCapturePaths) {
return {
executable: NodePath.join(paths.dataHome, "t3code", "kde-capture", KDE_CAPTURE_EXECUTABLE),
desktop: NodePath.join(paths.dataHome, "applications", DESKTOP_FILE),
};
}
function kdeCaptureDesktopEntry(executable: string): string {
return [
"[Desktop Entry]",
"Type=Application",
"Name=T3 Code SnapShots",
"NoDisplay=true",
`Exec=${escapeDesktopEntryExecArgument(executable)} check`,
// KService reads this custom property as a KConfig list, not an XDG ';' list.
"X-KDE-DBUS-Restricted-Interfaces=org.kde.KWin.ScreenShot2",
MARKER,
"",
].join("\n");
}
function run(executable: string, args: string[], signal?: AbortSignal): Promise<string> {
return new Promise((resolve, reject) => {
NodeChildProcess.execFile(
executable,
args,
{
timeout: 20_000,
maxBuffer: 128 * 1024,
encoding: "utf8",
...(signal ? { signal } : {}),
},
(error, stdout, stderr) => {
if (!error) return resolve(stdout);
if (executable === "kbuildsycoca6") {
reject(
new Error(
"KDE couldn't register the capture helper. Make sure KDE's service tools (kbuildsycoca6) are installed, then reinstall the helper.",
),
);
return;
}
if (stderr.includes("NoAuthorized")) {
reject(
new Error(
"KDE hasn't granted capture access. Reinstall the capture helper in setup, then try again.",
),
);
} else
reject(
new Error(
stderr.trim() ||
"The KDE capture helper did not respond. Reopen capture setup and check access.",
),
);
},
);
});
}
async function regularFile(path: string): Promise<Buffer | undefined> {
const stat = await NodeFSP.lstat(path).catch((error: NodeJS.ErrnoException) => {
if (error.code !== "ENOENT") throw error;
return undefined;
});
if (!stat) return undefined;
if (!stat.isFile() || stat.isSymbolicLink())
throw new Error(
"Capture helper files must be regular files. Remove the conflicting link before trying again.",
);
return NodeFSP.readFile(path);
}
export class KdeCaptureSetup {
private readonly paths: KdeCapturePaths;
constructor(paths: KdeCapturePaths) {
this.paths = paths;
}
async state(): Promise<DesktopCaptureHelperState> {
try {
const { executable, desktop } = kdeCapturePaths(this.paths);
const [installed, entry] = await Promise.all([regularFile(executable), regularFile(desktop)]);
if (!installed || !entry)
return {
status: "not-installed",
message:
"Install the bundled helper to capture the window you're using without a picker.",
};
const bundle = await regularFile(this.paths.bundle);
if (!bundle)
return {
status: "error",
message: "The capture helper is missing from this build. Update or reinstall T3 Code.",
};
if (!installed.equals(bundle) || entry.toString() !== kdeCaptureDesktopEntry(executable))
return {
status: "update-required",
message: "Update the bundled capture helper to continue.",
};
const capabilities = decodeCapabilities(await run(executable, ["check"]));
return {
status: "ready",
message: "KDE capture access is ready. Next, choose your shortcut.",
feedbackAvailable: capabilities.feedbackAvailable ?? false,
};
} catch (error) {
return {
status: "error",
message: error instanceof Error ? error.message : "Couldn't check KDE capture access.",
};
}
}
async perform(action: "install-kde-helper" | "remove-kde-helper") {
const { executable, desktop } = kdeCapturePaths(this.paths);
const entry = await regularFile(desktop);
if (entry && !entry.toString().split("\n").includes(MARKER))
throw new Error(
"Another desktop entry uses the capture helper's name. Rename it before continuing.",
);
const directory = NodePath.dirname(executable);
const existing = await NodeFSP.lstat(directory).catch((error: NodeJS.ErrnoException) => {
if (error.code !== "ENOENT") throw error;
return undefined;
});
if (existing && (!existing.isDirectory() || existing.isSymbolicLink()))
throw new Error("The capture helper directory is not a regular directory.");
await regularFile(executable);
if (action === "remove-kde-helper") {
if (entry) await NodeFSP.unlink(desktop);
await NodeFSP.unlink(executable).catch((error: NodeJS.ErrnoException) => {
if (error.code !== "ENOENT") throw error;
});
} else {
const bundle = await regularFile(this.paths.bundle);
if (!bundle)
throw new Error(
"The capture helper is missing from this build. Update or reinstall T3 Code.",
);
await NodeFSP.mkdir(directory, { recursive: true });
await NodeFSP.mkdir(NodePath.dirname(desktop), { recursive: true });
const staging = await NodeFSP.mkdtemp(NodePath.join(directory, ".install-"));
const stagedDesktop = `${desktop}.${NodeCrypto.randomUUID()}.tmp`;
try {
const staged = NodePath.join(staging, KDE_CAPTURE_EXECUTABLE);
await NodeFSP.writeFile(staged, bundle, { mode: 0o755 });
await NodeFSP.rename(staged, executable);
await NodeFSP.writeFile(stagedDesktop, kdeCaptureDesktopEntry(executable), {
mode: 0o644,
flag: "wx",
});
await NodeFSP.rename(stagedDesktop, desktop);
} finally {
await NodeFSP.rm(stagedDesktop, { force: true });
await NodeFSP.rm(staging, { recursive: true, force: true });
}
}
// KService must see the new desktop entry before KWin checks the executable.
await run("kbuildsycoca6", ["--noincremental"]);
// AppImage search paths and locale affect KService caches; refresh in Plasma's session environment.
await run("systemd-run", [
"--user",
"--quiet",
"--wait",
"--collect",
"--pipe",
"--service-type=exec",
"kbuildsycoca6",
"--noincremental",
]).catch(() => undefined);
}
}
const Dimension = Schema.Int.check(Schema.isGreaterThan(0));
const Bounds = Schema.Struct({ x: Schema.Int, y: Schema.Int, width: Dimension, height: Dimension });
const Window = Schema.Struct({
title: Schema.String,
appName: Schema.String,
appIdentifier: Schema.String,
processId: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
bounds: Bounds,
clientBounds: Bounds,
});
const decodeCapture = Schema.decodeUnknownSync(
Schema.fromJsonString(Schema.Struct({ window: Schema.NullOr(Window) })),
);
export async function captureKdeWindow(
paths: KdeCapturePaths,
options?: { readonly flash: boolean; readonly animate: boolean },
): Promise<LinuxWindowSnapshot> {
const state = await new KdeCaptureSetup(paths).state();
if (state.status !== "ready") throw new CaptureSetupRequiredError({ state: state.message });
const { executable } = kdeCapturePaths(paths);
const directory = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "t3-kde-capture-"));
let retained = false;
const cleanup = () => NodeFSP.rm(directory, { recursive: true, force: true });
try {
const result = decodeCapture(await run(executable, ["capture", directory]));
const png = await readPortalPng(
NodeURL.pathToFileURL(NodePath.join(directory, "capture.png")).href,
);
const feedback = new AbortController();
const effects =
state.feedbackAvailable && result.window && options && (options.flash || options.animate)
? await startNativeCaptureFeedback(executable, directory, {
bounds: result.window.bounds,
pid: process.pid,
...options,
}).catch(() => undefined)
: undefined;
if (effects) {
retained = true;
void effects.closed.then(cleanup).catch(() => undefined);
}
let targetTitle = "";
const close = () => {
effects?.close();
feedback.abort();
};
return {
png,
...(result.window ? { window: result.window } : {}),
feedback: {
animationStarted: effects?.animationStarted ?? false,
activate: async (title) => {
targetTitle = title;
const activation = await NodeFSP.mkdtemp(
NodePath.join(NodeOS.tmpdir(), "t3-kde-activate-"),
);
try {
await run(
executable,
["activate", activation, String(process.pid), title],
feedback.signal,
);
} finally {
await NodeFSP.rm(activation, { recursive: true, force: true });
}
},
animateTo: async (frame) => {
await effects?.animateTo(targetTitle, frame);
},
complete: async () => {
await effects?.complete();
feedback.abort();
await cleanup();
},
close,
},
};
} finally {
if (!retained) await cleanup();
}
}