Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.
JavaScript aianthropiccross-platformgeminigroqlinuxmacosnvidiaopen-sourceopenaiparakeetspeech-to-texttranscribewhisperwindows
const crypto = require("crypto");
const { execFile, spawn } = require("child_process");
const debugLogger = require("./debugLogger");
const { isMarkdownTargetSignature } = require("./markdownTargets");
const SESSION_TTL_MS = 5 * 60 * 1000;
const MAX_SELECTION_EDIT_CODE_POINTS = 6000;
// Ceiling for one synthetic-copy round trip. A no-selection agent command
// pays this in full, and replaceSelectedText spends a second round trip
// re-verifying — the accepted cost of failing closed rather than pasting blind.
const COPY_TIMEOUT_MS = 1200;
const CLIPBOARD_POLL_MS = 20;
const ATSPI_TARGET_TIMEOUT_MS = 2000;
const TARGET_CAPTURE_FRESHNESS_MS = 250;
const ATSPI_COOLDOWN_MS = 2000;
// Editors that copy the whole current line when Ctrl+C (⌘C on macOS) lands with
// an empty selection (VS Code's editor.emptySelectionClipboard, Scintilla,
// JetBrains, Visual Studio), making a bare caret look like a selection to the
// synthetic-copy capture. Matched against exe name and window class on
// Windows/Linux and against the localized app name on macOS, so the JetBrains
// IDEs need both spellings.
const LINE_COPY_EDITOR_SIGNATURES = [
"code", // VS Code and forks (VSCodium, code-oss)
"cursor",
"windsurf",
"notepad++",
"sublime",
"jetbrains",
"idea64",
"intellij", // macOS app name for idea64
"pycharm",
"webstorm",
"phpstorm",
"rider64",
"rider", // macOS app name for rider64
"android studio", // macOS app name for studio64
"clion",
"goland",
"rubymine",
"datagrip",
"dataspell",
"studio64", // Android Studio
"devenv", // Visual Studio
];
function runFile(command, args, options = {}) {
return new Promise((resolve) => {
execFile(
command,
args,
{ timeout: options.timeout || COPY_TIMEOUT_MS },
(error, stdout, stderr) => {
resolve({
success: !error,
stdout: stdout?.toString?.() || "",
stderr: stderr?.toString?.() || error?.message || "",
});
}
);
});
}
function runSpawn(command, args, options = {}) {
return new Promise((resolve) => {
const { timeout = COPY_TIMEOUT_MS, ...spawnOptions } = options;
const child = spawn(command, args, {
stdio: ["ignore", "pipe", "pipe"],
windowsHide: true,
...spawnOptions,
});
let stdout = "";
let stderr = "";
let settled = false;
const finish = (success, timedOut = false) => {
if (settled) return;
settled = true;
clearTimeout(timer);
resolve({ success, timedOut, stdout, stderr });
};
child.stdout?.on("data", (chunk) => (stdout += chunk.toString()));
child.stderr?.on("data", (chunk) => (stderr += chunk.toString()));
child.on("error", (error) => {
stderr += error.message;
finish(false);
});
child.on("close", (code) => finish(code === 0));
const timer = setTimeout(() => {
child.kill("SIGKILL");
finish(false, true);
}, timeout);
});
}
// Keys still held past the modifier wait (#2113) and a Wayland clipboard wl-copy
// didn't write (#2621) get their own code, so the renderer can say so instead of
// blaming permissions or a changed target.
const HELD_BACK_CODES = {
"modifiers-held": "modifiers_held",
"wl-copy-missing": "wl_copy_missing",
"wl-copy-failed": "wl_copy_failed",
};
function heldBackCode(fallback, { code, reason } = {}) {
return code === "modifiers_held" ? code : HELD_BACK_CODES[reason] || fallback;
}
class SelectionManager {
constructor({
clipboardManager,
textEditMonitor,
platform = process.platform,
now = Date.now,
} = {}) {
this.clipboardManager = clipboardManager;
this.textEditMonitor = textEditMonitor;
this.platform = platform;
this.now = now;
this.sessions = new Map();
this.lastTarget = null;
// Window titles sit beside their target, never on it, so a capture
// result handed to the renderer can't carry one.
this._targetTitles = new WeakMap();
this._captureTargetPromise = null;
this._lastTargetCaptureAt = 0;
this._atspiCooldownUntil = 0;
this._atspiProbeGeneration = 0;
}
async captureTarget({ force = false } = {}) {
if (this.platform === "darwin") return;
if (!force) {
if (this._captureTargetPromise) return this._captureTargetPromise;
if (
this.lastTarget !== null &&
this.now() - this._lastTargetCaptureAt < TARGET_CAPTURE_FRESHNESS_MS
) {
return;
}
}
this.lastTarget = null;
const probe = this._probeTarget();
this._captureTargetPromise = probe;
const target = await probe;
// A newer toggle press may have started its own probe while this one ran;
// only the latest probe's result may land in lastTarget.
if (this._captureTargetPromise === probe) {
this.lastTarget = target;
this._lastTargetCaptureAt = this.now();
this._captureTargetPromise = null;
}
}
async _probeTarget() {
if (this.platform === "win32") {
const binary = this.clipboardManager.resolveWindowsFastPasteBinary();
if (!binary) return null;
const result = await runSpawn(binary, ["--detect-only"], { timeout: 700 });
const match = result.stdout.match(/TARGET\s+(\S+)/);
if (!result.success || !match) return null;
const target = {
kind: "win-hwnd",
id: match[1],
windowClass: result.stdout.match(/^WINDOW_CLASS (.+)$/m)?.[1]?.trim() || null,
exeName: result.stdout.match(/^EXE_NAME (.+)$/m)?.[1]?.trim() || null,
isTerminal: /^IS_TERMINAL true$/m.test(result.stdout),
};
const title = result.stdout.match(/^WINDOW_TITLE (.+)$/m)?.[1]?.trim();
if (title) this._targetTitles.set(target, title);
return target;
}
if (this.platform === "linux") {
return this._getLinuxTarget();
}
return null;
}
// The Windows foreground window captured at record start, for the paste path
// to restore before Ctrl+V lands (#859). Waits out an in-flight probe for the
// same reason captureSelectedText does: the stop-press probe can still be
// running when fast transcription reaches the paste. Carries the window's
// identity so the paste can judge whether restoring it makes sense.
async getWinTarget() {
while (this._captureTargetPromise) {
await this._captureTargetPromise;
}
return this.lastTarget?.kind === "win-hwnd" ? this.lastTarget : null;
}
// The dictation target as the Tone & Style classifier reads it: the app's
// identity, its window title and, for a macOS browser page, the URL's host.
// Titles stay in the main process; only the resulting category leaves it.
async getTargetAppContext() {
if (this.platform === "darwin") {
const pid = this.textEditMonitor?.lastTargetPid;
const context = pid ? await this.textEditMonitor.getAppContext(pid) : null;
if (!context) return null;
return {
appSignature: `${context.appName || ""} ${context.bundleId || ""}`.trim(),
windowTitle: context.windowTitle,
urlHost: context.urlHost,
};
}
while (this._captureTargetPromise) {
await this._captureTargetPromise;
}
const target = this.lastTarget;
if (!target) return null;
return {
appSignature:
target.kind === "atspi-pid"
? await this._readTargetNames(target.id)
: this._targetSignature(target),
windowTitle: this._targetTitles.get(target) ?? (await this._readWindowTitle(target)),
};
}
// X11 and KDE titles are read on demand rather than at capture, which also
// runs before every paste.
async _readWindowTitle(target) {
const command = { "x11-window": "xdotool", "kde-window": "kdotool" }[target.kind];
if (!command) return null;
const result = await runFile(command, ["getwindowname", target.id], { timeout: 500 });
return (result.success && result.stdout.trim()) || null;
}
async captureSelectedText(options = {}) {
// The caller knows whether a caret capture could ever be used (auto-paste
// on); without it the probe's binary spawn would be pure waste.
const probeEditable = options.probeEditable === true;
return this.clipboardManager.runClipboardOperation(async () => {
// captureTarget() fires on every toggle press, including stop. Fast
// cloud transcription can get here before the stop-press probe lands
// (~1s on Wayland AT-SPI), when lastTarget is still nulled from the
// probe's start — so wait for the latest probe instead of failing with
// target_unavailable while the answer is in flight.
while (this._captureTargetPromise) {
await this._captureTargetPromise;
}
this._pruneSessions();
const expectedTarget =
this.platform === "darwin" && this.textEditMonitor?.lastTargetPid
? { kind: "mac-pid", pid: this.textEditMonitor.lastTargetPid }
: this.lastTarget;
if (!expectedTarget) {
return { status: "unavailable", code: "target_unavailable" };
}
const capture = await this._readCurrentSelection(expectedTarget, { probeEditable });
if (capture.status === "editable") {
const sessionId = crypto.randomUUID();
// The renderer asks for plain prose and strips markdown only when the
// target is not a markdown-friendly app.
const acceptsMarkdown = await this._targetAcceptsMarkdown(capture.target);
this.sessions.set(sessionId, {
kind: "caret",
target: capture.target,
expiresAt: this.now() + SESSION_TTL_MS,
});
return { status: "editable", sessionId, acceptsMarkdown };
}
if (capture.status !== "selected") return capture;
const characterCount = [...capture.text].length;
if (characterCount > MAX_SELECTION_EDIT_CODE_POINTS) {
return {
status: "too_large",
characterCount,
maxCharacters: MAX_SELECTION_EDIT_CODE_POINTS,
};
}
const sessionId = crypto.randomUUID();
this.sessions.set(sessionId, {
kind: "selection",
text: capture.text,
target: capture.target,
expiresAt: this.now() + SESSION_TTL_MS,
});
return {
status: "selected",
sessionId,
text: capture.text,
characterCount,
};
});
}
async replaceSelectedText(sessionId, replacement, options = {}) {
if (typeof replacement !== "string" || replacement.length === 0) {
return { success: false, code: "invalid_replacement" };
}
return this.clipboardManager.runClipboardOperation(async () => {
this._pruneSessions();
const session = this.sessions.get(sessionId);
this.sessions.delete(sessionId);
if (!session || session.kind !== "selection") {
return { success: false, code: "session_expired" };
}
const current = await this._readCurrentSelection(session.target, { activate: true });
if (current.status === "target_changed") {
return { success: false, code: "target_changed" };
}
if (current.status === "unavailable") {
return { success: false, code: heldBackCode("selection_unavailable", current) };
}
if (current.status !== "selected" || current.text !== session.text) {
return { success: false, code: "selection_changed" };
}
try {
const pasteResult = await this.clipboardManager._pasteText(replacement, {
...options,
restoreClipboard: options.restoreClipboard !== false,
});
await pasteResult?.restoreComplete;
if (pasteResult?.pasted === false) {
return { success: false, code: heldBackCode("paste_failed", pasteResult) };
}
return { success: true };
} catch (error) {
debugLogger.warn(
"Selection replacement paste failed",
{ error: error.message },
"clipboard"
);
return { success: false, code: "paste_failed", error: error.message };
}
});
}
async pasteAtCapturedTarget(sessionId, text, options = {}) {
if (typeof text !== "string" || text.length === 0) {
return this._declineAssistantPaste("invalid_replacement", {
sessionFound: this.sessions.has(sessionId),
});
}
return this.clipboardManager.runClipboardOperation(async () => {
this._pruneSessions();
const session = this.sessions.get(sessionId);
this.sessions.delete(sessionId);
if (!session || session.kind !== "caret") {
return this._declineAssistantPaste("session_expired", {
sessionFound: Boolean(session),
sessionKind: session?.kind ?? null,
});
}
const current = await this._readCurrentSelection(session.target, { probeEditable: true });
if (current.status !== "editable") {
return this._declineAssistantPaste(heldBackCode("target_changed", current), {
sessionFound: true,
sessionKind: "caret",
probeStatus: current.status,
probeCode: current.code ?? null,
});
}
try {
const pasteResult = await this.clipboardManager._pasteText(text, {
...options,
restoreClipboard: options.restoreClipboard !== false,
...(session.target?.kind === "win-hwnd" ? { targetWindow: session.target.id } : {}),
});
await pasteResult?.restoreComplete;
if (pasteResult?.pasted === false) {
return this._declineAssistantPaste(heldBackCode("paste_failed", pasteResult), {
sessionFound: true,
sessionKind: "caret",
probeStatus: "editable",
});
}
return { success: true };
} catch (error) {
debugLogger.warn("Assistant response paste failed", { error: error.message }, "clipboard");
return { success: false, code: "paste_failed", error: error.message };
}
});
}
// One line per refusal. The renderer discards the code it receives, so the
// debug log is the only place a declined assistant paste can be diagnosed.
_declineAssistantPaste(code, details = {}) {
debugLogger.info(
"Assistant response paste declined",
{ code, platform: this.platform, ...details },
"clipboard"
);
return { success: false, code };
}
_pruneSessions() {
const now = this.now();
for (const [id, session] of this.sessions) {
if (session.expiresAt <= now) this.sessions.delete(id);
}
}
async _readCurrentSelection(expectedTarget = null, options = {}) {
if (this.platform === "darwin") {
return this._readMacSelection(expectedTarget, options);
}
if (this.platform === "win32") {
return this._readWindowsSelection(expectedTarget, options);
}
if (this.platform === "linux") {
return this._readLinuxSelection(expectedTarget, options);
}
return { status: "unavailable", code: "unsupported_platform" };
}
async _readMacSelection(expectedTarget, { activate = false, probeEditable = false } = {}) {
const pid = expectedTarget?.pid || this.textEditMonitor?.lastTargetPid;
if (!pid || !this.textEditMonitor?.getSelectedText) {
return { status: "unavailable", code: "target_unavailable" };
}
const frontmostPid = await this.textEditMonitor._readFrontmostPid?.();
if (frontmostPid && frontmostPid !== pid) {
return { status: "target_changed" };
}
if (activate && !(await this.textEditMonitor.activatePid(pid))) {
return { status: "unavailable", code: "activation_failed" };
}
const result = await this.textEditMonitor.getSelectedText(pid);
if (result.state === "selected") {
return { status: "selected", text: result.text, target: { kind: "mac-pid", pid } };
}
if (result.state === "none") {
const editable = probeEditable && result.editable && !(await this._isTerminalPid(pid));
return {
status: editable ? "editable" : "none",
target: { kind: "mac-pid", pid },
};
}
// Chromium browsers (and any app whose accessibility tree stays dormant)
// never resolve a focused element — or resolve only the bare window (the
// native read's "unknown" state) — so the read above cannot tell a
// selection from an empty field. A synthetic copy still can — the same
// route Windows and Linux take by default.
return this._readMacSelectionViaClipboard(pid, expectedTarget, probeEditable);
}
async _readMacSelectionViaClipboard(pid, expectedTarget, probeEditable) {
const binary = this.clipboardManager.resolveFastPasteBinary?.();
if (!binary) return { status: "unavailable", code: "accessibility_unavailable" };
const capture = await this._captureViaClipboard(
async () => {
const result = await this._runCopyHelper(binary, ["--copy"]);
const match = result.stdout.match(/COPY_OK\s+(\d+)\s*(.*)/);
if (!result.success || !match) return { success: false };
return {
success: true,
target: { kind: "mac-pid", pid: Number(match[1]), appName: match[2].trim() || null },
};
},
expectedTarget || { kind: "mac-pid", pid }
);
// A copy that never landed leaves the selection as unknown as the
// accessibility read did, so it gets the same non-fatal treatment.
if (capture.status === "unavailable" && capture.code === "copy_failed") {
return { status: "unavailable", code: "accessibility_unavailable" };
}
// Replacement text typed into a shell executes on its embedded newlines, so
// terminal selections are declined exactly as on Linux. GPU-rendered
// terminals (Ghostty, Alacritty, kitty) have no accessibility tree, so this
// path is the only way they reach selection editing at all.
if (
capture.status === "selected" &&
this.clipboardManager.isTerminalSignature?.(capture.target?.appName)
) {
return { status: "none", target: capture.target };
}
return this._markEditableCaret(capture, capture.target || expectedTarget, probeEditable);
}
_runCopyHelper(binary, args) {
return runSpawn(binary, args, { timeout: COPY_TIMEOUT_MS });
}
async _readWindowsSelection(expectedTarget, { probeEditable = false } = {}) {
const binary = this.clipboardManager.resolveWindowsFastPasteBinary();
if (!binary) return { status: "unavailable", code: "copy_helper_unavailable" };
const capture = await this._captureViaClipboard(async () => {
const result = await runSpawn(binary, ["--copy"], { timeout: COPY_TIMEOUT_MS });
if (!result.success) return { success: false };
const match = result.stdout.match(/COPY_OK\s+(\S+)/);
return { success: !!match, target: match ? { kind: "win-hwnd", id: match[1] } : null };
}, expectedTarget);
// The copy reports only the HWND; a same-window expectedTarget (verified by
// _captureViaClipboard) carries the exe/class identity the terminal and
// line-copy checks need, so keep it on the target a caret session stores.
const target =
capture.target && expectedTarget
? { ...expectedTarget, ...capture.target }
: capture.target || expectedTarget;
return this._markEditableCaret(capture, target, probeEditable);
}
async _readLinuxSelection(expectedTarget, { probeEditable = false } = {}) {
const target = await this._getLinuxTarget();
if (!target) return { status: "unavailable", code: "target_unavailable" };
if (expectedTarget && !this._sameTarget(target, expectedTarget)) {
return { status: "target_changed" };
}
if (this.clipboardManager.isLinuxTerminalWindowClass?.(target.windowClass)) {
return { status: "none", target };
}
const binary = this.clipboardManager.resolveLinuxFastPasteBinary();
if (target.kind === "atspi-pid") {
const capture = await this._readLinuxAtspiSelection(binary, expectedTarget || target);
return this._markEditableCaret(
capture,
capture.target || expectedTarget || target,
probeEditable
);
}
// Capture runs right after the voice assistant hotkey press, so its keys are
// often still down; a Ctrl+C sent into them copies nothing.
const modifiers = await this.clipboardManager._awaitModifierRelease();
if (modifiers.state === "held") {
return { status: "unavailable", code: "modifiers_held" };
}
// The checks above approved the window focused before the wait. If focus
// moved while a key was held, the chord would reach an unchecked window,
// and a plain Ctrl+C in a terminal interrupts whatever is running there.
// `focus_moved` lets a fresh capture run the command on its own; a session
// being revalidated still declines as a changed target.
if (modifiers.waitedMs > 0 && !this._sameTarget(await this._getLinuxTarget(), target)) {
return { status: "target_changed", code: "focus_moved" };
}
const capture = await this._captureViaClipboard(async () => {
if (binary) {
if (target.kind === "x11-window") {
// The binary classifies the window itself via --window and picks
// Ctrl+C or Ctrl+Shift+C accordingly.
const result = await runSpawn(binary, ["--copy", "--window", target.id], {
timeout: COPY_TIMEOUT_MS,
});
return { success: result.success, target };
}
// Without an X11 window id the binary cannot classify the target,
// and a plain Ctrl+C in a terminal with no selection sends SIGINT —
// so only proceed when the compositor reported the window class.
if (!target.windowClass) return { success: false };
const isTerminal = this.clipboardManager.isLinuxTerminalWindowClass(target.windowClass);
if (this.clipboardManager._canAccessUinput?.()) {
const args = ["--copy", "--uinput"];
if (isTerminal) args.push("--terminal");
const result = await runSpawn(binary, args, { timeout: COPY_TIMEOUT_MS });
return { success: result.success, target };
}
if (
this.clipboardManager._runPortalPaste &&
!this.clipboardManager.portalDenied &&
!this.clipboardManager.portalUnavailable &&
!this.clipboardManager.portalFailed
) {
try {
await this.clipboardManager._runPortalPaste(binary, {
copy: true,
terminal: isTerminal,
});
return { success: true, target };
} catch (err) {
// Same session-level memory as the paste path (#1614): a stale
// portal session would otherwise stall every selection capture.
if (err?.message !== "portal-denied" && err?.message !== "portal-dismissed") {
this.clipboardManager.portalFailed = true;
}
return { success: false };
}
}
return { success: false };
}
if (target.kind === "x11-window" && this.clipboardManager.commandExists("xdotool")) {
const chord = this.clipboardManager.isLinuxTerminalWindowClass(target.windowClass)
? "ctrl+shift+c"
: "ctrl+c";
const result = await runFile(
"xdotool",
["windowactivate", "--sync", target.id, "key", chord],
{ timeout: COPY_TIMEOUT_MS }
);
return { success: result.success, target };
}
return { success: false };
}, expectedTarget || target);
return this._markEditableCaret(
capture,
capture.target || expectedTarget || target,
probeEditable
);
}
async _markEditableCaret(capture, target, probeEditable) {
if (!probeEditable || capture.status !== "none" || !target) return capture;
// Generated text pasted into a shell executes on its embedded newlines, so
// a terminal target never becomes a caret destination — the same rule the
// selection paths apply.
if (this._isTerminalTarget(capture.target, target)) return capture;
// AT-SPI targets carry only a pid — nothing for the signature check above
// to match — so resolve the executable name before a Wayland terminal's
// empty prompt can read as a writable caret.
if (target.kind === "atspi-pid" && (await this._isTerminalPid(target.id))) return capture;
// macOS targets normally carry the copier's NSWorkspace app name, already
// matched above; only an unnamed target needs its executable resolved so a
// terminal cannot become a caret destination.
if (
target.kind === "mac-pid" &&
!this._targetSignature(target) &&
(await this._isTerminalPid(target.pid))
) {
return capture;
}
const pid = await this._linuxTargetPid(target);
const verdict = await this.textEditMonitor?.isFocusedEditable?.(
pid ? { ...target, pid } : target
);
debugLogger.debug(
"Editable caret probe",
{ kind: target.kind, pid: target.pid ?? pid, verdict },
"clipboard"
);
if (verdict === "editable") return { status: "editable", target };
// An empty copy cannot distinguish a caret from an integrated terminal or
// a page without an input; it can also hide a selection matching the clipboard.
// Unknown accessibility must keep the panel fallback, including on revalidation.
return capture;
}
// The Linux editable probe answers only for a focused field in this process's
// active window, so a focus left behind in another app can't vouch for the
// target. null for other target kinds, or when the process can't be read.
async _linuxTargetPid(target) {
if (target.kind === "atspi-pid") return target.id;
if (target.kind === "hyprland-window") return target.pid;
if (target.kind === "x11-window") return this._readWindowPid("xdotool", target.id);
if (target.kind === "kde-window") return this._readWindowPid("kdotool", target.id);
return null;
}
async _readWindowPid(tool, windowId) {
const result = await runFile(tool, ["getwindowpid", windowId], { timeout: 500 });
const pid = result.success ? result.stdout.trim() : "";
return /^[1-9]\d*$/.test(pid) ? pid : null;
}
_isTerminalTarget(...targets) {
return targets.some(
(target) =>
target?.isTerminal === true ||
this.clipboardManager.isTerminalSignature?.(this._targetSignature(target))
);
}
// macOS AX and Linux AT-SPI targets carry only a pid; resolve the executable
// so terminal apps can be recognized before their empty prompt reads as a
// writable caret. macOS `ps` reports a full path, Linux the bare comm name —
// the parsing below degrades to the bare name unchanged.
async _isTerminalPid(pid) {
if (!this.clipboardManager.isTerminalSignature) return false;
const names = await this._readTargetNames(pid);
return names ? this.clipboardManager.isTerminalSignature(names) : false;
}
// "<bundle name> <executable name>" for a pid — "Visual Studio Code Code" on
// macOS, the bare comm name on Linux — or "" when the pid cannot be read.
async _readTargetNames(pid) {
const executablePath = await this._readExecutablePath(pid);
if (!executablePath) return "";
// Match the bundle and executable names, not the whole path, so a directory
// name can't read as a terminal signature.
const bundleName = executablePath.match(/\/([^/]+)\.app\//)?.[1] ?? "";
const executableName = executablePath.split("/").pop() ?? "";
return `${bundleName} ${executableName}`.trim();
}
// Windows and Linux X11 targets name their app on the target; macOS AX and
// Linux AT-SPI targets carry only a pid, so resolve the executable exactly
// as the terminal check does. A miss or an error means plain text.
async _targetAcceptsMarkdown(target) {
if (!target) return false;
try {
const parts = [this._targetSignature(target)];
const pid =
target.kind === "mac-pid" ? target.pid : target.kind === "atspi-pid" ? target.id : null;
if (pid) parts.push(await this._readTargetNames(pid));
return isMarkdownTargetSignature(parts.join(" ").trim());
} catch {
return false;
}
}
async _readExecutablePath(pid) {
const result = await runSpawn("ps", ["-p", String(pid), "-o", "comm="], { timeout: 500 });
return result.success ? result.stdout.trim() : "";
}
async _readLinuxAtspiSelection(binary, expectedTarget) {
if (!binary) return { status: "unavailable", code: "copy_helper_unavailable" };
if (this.now() < this._atspiCooldownUntil) {
return { status: "unavailable", code: "accessibility_unavailable" };
}
const generation = ++this._atspiProbeGeneration;
const result = await runSpawn(binary, ["--atspi-selection"], { timeout: COPY_TIMEOUT_MS });
if (result.timedOut && generation === this._atspiProbeGeneration) {
this._atspiCooldownUntil = this.now() + ATSPI_COOLDOWN_MS;
debugLogger.warn("AT-SPI selection probe timed out", { cooldownMs: ATSPI_COOLDOWN_MS });
}
if (!result.success) return { status: "unavailable", code: "accessibility_unavailable" };
const selected = result.stdout.match(/^ATSPI_SELECTED\s+(\d+)\s+([A-Za-z0-9+/=]+)$/m);
const none = result.stdout.match(/^ATSPI_NONE\s+(\d+)$/m);
const pid = selected?.[1] || none?.[1];
if (!pid) return { status: "unavailable", code: "accessibility_unavailable" };
const target = { kind: "atspi-pid", id: pid };
if (expectedTarget && !this._sameTarget(target, expectedTarget)) {
return { status: "target_changed" };
}
if (none) return { status: "none", target };
try {
return {
status: "selected",
text: Buffer.from(selected[2], "base64").toString("utf8"),
target,
};
} catch {
return { status: "unavailable", code: "accessibility_unavailable" };
}
}
async _getLinuxTarget() {
// On native Wayland, xdotool can report a stale XWayland window. Prefer
// AT-SPI when available so the target and selected text come from the
// compositor's actual focused accessibility object.
const isWayland = this.clipboardManager._isWayland?.() === true;
if (isWayland) {
const atspiTarget = await this._getLinuxAtspiTarget();
if (atspiTarget) return atspiTarget;
}
if (this.clipboardManager.commandExists("xdotool") && process.env.DISPLAY) {
const result = await runFile("xdotool", ["getactivewindow"], { timeout: 500 });
const id = result.stdout.trim();
if (result.success && id) {
const classResult = await runFile("xdotool", ["getwindowclassname", id], { timeout: 500 });
return {
kind: "x11-window",
id,
windowClass: classResult.success ? classResult.stdout.trim().toLowerCase() : null,
};
}
}
if (this.clipboardManager.commandExists("kdotool")) {
const result = await runFile("kdotool", ["getactivewindow"], { timeout: 500 });
const id = result.stdout.trim();
if (result.success && id) {
return {
kind: "kde-window",
id,
windowClass: this.clipboardManager._detectKdeWindowClass?.() || null,
};
}
}
if (this.clipboardManager.commandExists("hyprctl")) {
const result = await runFile("hyprctl", ["activewindow", "-j"], { timeout: 500 });
if (result.success) {
try {
const active = JSON.parse(result.stdout);
if (active.address) {
const target = {
kind: "hyprland-window",
id: active.address,
windowClass: typeof active.class === "string" ? active.class.toLowerCase() : null,
pid: Number.isInteger(active.pid) && active.pid > 0 ? active.pid : null,
};
if (typeof active.title === "string") this._targetTitles.set(target, active.title);
return target;
}
} catch {}
}
}
return isWayland ? null : this._getLinuxAtspiTarget();
}
async _getLinuxAtspiTarget() {
if (this.now() < this._atspiCooldownUntil) return null;
const binary = this.clipboardManager.resolveLinuxFastPasteBinary();
if (!binary) return null;
const generation = ++this._atspiProbeGeneration;
const result = await runSpawn(binary, ["--atspi-target"], {
timeout: ATSPI_TARGET_TIMEOUT_MS,
});
if (result.timedOut && generation === this._atspiProbeGeneration) {
this._atspiCooldownUntil = this.now() + ATSPI_COOLDOWN_MS;
debugLogger.warn("AT-SPI target probe timed out", { cooldownMs: ATSPI_COOLDOWN_MS });
}
const match = result.stdout.match(/^TARGET\s+ATSPI\s+(\d+)$/m);
if (!result.success || !match) return null;
const target = { kind: "atspi-pid", id: match[1] };
const title = result.stdout.match(/^WINDOW_TITLE_B64 ([A-Za-z0-9+/=]+)$/m)?.[1];
if (title) this._targetTitles.set(target, Buffer.from(title, "base64").toString("utf8"));
return target;
}
async _captureViaClipboard(sendCopy, expectedTarget) {
const original = this.clipboardManager._saveClipboard();
const beforeWrite = this.clipboardManager._readClipboardTextAll();
const sentinel = `__OPENWHISPR_SELECTION_${crypto.randomUUID()}__`;
this.clipboardManager._writeClipboardTextAll(sentinel);
// A clipboard side the sentinel write didn't reach (KDE desyncs X11 from
// Wayland) still holds pre-copy content; snapshot it so stale text can't
// be mistaken for the copied selection. Known limitation: a clipboard that
// already held exactly the selected text reads as "no selection". The
// editable probe must independently verify an empty writable field before
// caret delivery; a live selection or unknown accessibility keeps the panel.
const baseline = new Set([...beforeWrite, ...this.clipboardManager._readClipboardTextAll()]);
const copyResult = await sendCopy();
if (!copyResult?.success || !copyResult.target) {
this._restoreClipboardIfOurs(original, [sentinel], baseline);
return { status: "unavailable", code: "copy_failed" };
}
if (expectedTarget && !this._sameTarget(copyResult.target, expectedTarget)) {
this._restoreClipboardIfOurs(original, [sentinel], baseline);
return { status: "target_changed" };
}
const deadline = Date.now() + COPY_TIMEOUT_MS;
let copiedText = null;
while (Date.now() < deadline) {
copiedText =
this.clipboardManager
._readClipboardTextAll()
.find((text) => text.length > 0 && text !== sentinel && !baseline.has(text)) ?? null;
if (copiedText !== null) break;
await new Promise((resolve) => setTimeout(resolve, CLIPBOARD_POLL_MS));
}
this._restoreClipboardIfOurs(original, [sentinel, copiedText], baseline);
if (copiedText === null) {
return { status: "none", target: copyResult.target };
}
// A line copy from an empty-selection Ctrl+C is exactly one line with a
// trailing terminator; treat that shape from a known line-copy editor as
// "no selection" so a bare caret never gets its line rewritten. Proper
// fix: a real selection read (UIA TextPattern), like --atspi-selection.
if (
/^[^\n]*\r?\n$/.test(copiedText) &&
this._isLineCopyEditor(expectedTarget, copyResult.target)
) {
return { status: "none", target: copyResult.target };
}
return { status: "selected", text: copiedText, target: copyResult.target };
}
_targetSignature(target) {
return `${target?.exeName || ""} ${target?.windowClass || ""} ${target?.appName || ""}`.trim();
}
// Windows and Linux name the app in the target captured before the copy;
// macOS learns it from the copy helper's own report, so both are checked.
_isLineCopyEditor(...targets) {
const signature = targets
.map((target) => this._targetSignature(target))
.join(" ")
.toLowerCase();
if (!signature.trim()) return false;
return LINE_COPY_EDITOR_SIGNATURES.some((editor) => signature.includes(editor));
}
_restoreClipboardIfOurs(original, writtenTexts, baseline = new Set()) {
const written = writtenTexts.filter((text) => typeof text === "string" && text.length > 0);
try {
const current = this.clipboardManager._readClipboardTextAll();
const userClipboardText = current.find(
(text) => text.length > 0 && !written.includes(text) && !baseline.has(text)
);
if (userClipboardText) {
// The user copied something while capture was in flight. Prefer their
// new clipboard over restoring our snapshot, and clear our sentinel
// from any desynchronised X11/Wayland side.
this.clipboardManager._writeClipboardTextAll(userClipboardText);
return;
}
if (!current.some((text) => written.includes(text))) return;
if (original?.type === "text") {
// Text restores go through the all-sides writer so a desynced side
// isn't left holding the sentinel or the copied selection.
this.clipboardManager._writeClipboardTextAll(original.data);
} else {
this.clipboardManager._restoreClipboard(original);
}
} catch {}
}
_sameTarget(a, b) {
return !!a && !!b && a.kind === b.kind && String(a.id ?? a.pid) === String(b.id ?? b.pid);
}
}
module.exports = SelectionManager;
module.exports.SESSION_TTL_MS = SESSION_TTL_MS;