primocode 7.10.1 → 7.12.0

package/lib/desktop.js

@@ -1,9 +1,14 @@
 /**
- * desktop.js — Controle nativo do mouse/teclado do sistema operacional.
+ * desktop.js — Controle nativo do computador: mouse, teclado, janelas e tela.
  * Zero dependências npm. Usa ferramentas nativas do SO:
- *   Linux: xdotool
- *   macOS: cliclick (brew install cliclick) ou osascript
- *   Windows: powershell + System.Windows.Forms
+ *   Linux:   xdotool (mouse/teclado/janelas) + scrot/maim/… (tela)
+ *   macOS:   cliclick (brew install cliclick) e osascript/System Events
+ *   Windows: powershell (user32 + UI Automation) — nada a instalar
+ *
+ * A regra do módulo: o agente NÃO enxerga pixels (os modelos são só-texto),
+ * então ele enxerga por NOMES — as janelas abertas (listWindows), os botões e
+ * ícones de cada janela (uiElements) e o clique pelo nome (clickElement).
+ * Coordenada continua existindo, mas é o último recurso, não o primeiro.
  */
 
 'use strict';
@@ -24,19 +29,52 @@ const TOOLS = {
     nircmd: PLATFORM === 'win32' && (() => { try { execSync('where nircmd', {stdio:'ignore'}); return true; } catch { return false; } })(),
 };
 
-function run(cmd) {
-    try { execSync(cmd, { stdio: 'ignore', timeout: 10000 }); return { ok: true }; }
-    catch (e) { return { ok: false, error: e.message }; }
+function run(cmd, opts = {}) {
+    try {
+        execSync(cmd, {
+            stdio: 'ignore',
+            timeout: opts.timeout || 15000,
+            env: opts.env ? { ...process.env, ...opts.env } : undefined,
+        });
+        return { ok: true };
+    } catch (e) { return { ok: false, error: e.message }; }
 }
 
-// PowerShell sem perfil; escapa aspas duplas para caber em -Command "...".
-function pwsh(script) {
-    return run(`powershell -NoProfile -Command "${script.replace(/"/g, '\\"')}"`);
+// Igual ao run(), mas devolve o stdout — para os comandos que PERGUNTAM algo
+// (listar janelas, ler elementos) em vez de só agir.
+function runOut(cmd, opts = {}) {
+    try {
+        const out = execSync(cmd, {
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: opts.timeout || 15000,
+            env: opts.env ? { ...process.env, ...opts.env } : undefined,
+        });
+        return { ok: true, out: String(out || '') };
+    } catch (e) { return { ok: false, error: e.message, out: String((e && e.stdout) || '') }; }
 }
 
+// Argumento de shell entre aspas simples, à prova de apóstrofo. O truque
+// POSIX é fechar a aspa, escapar o apóstrofo e reabrir: 'don'\''t'.
+function sh1(s) {
+    return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+// PowerShell via -EncodedCommand: o script vai em base64 (UTF-16LE), então
+// aspas, cifrão e acento do texto do usuário NUNCA passam pelo cmd.exe cru.
+// A versão antiga escapava aspas à mão dentro de -Command "..." e quebrava
+// com qualquer texto que tivesse caractere especial — era um dos motivos de
+// "clica mas não digita" no Windows.
+function pwshCmd(script) {
+    const b64 = Buffer.from(script, 'utf16le').toString('base64');
+    return `powershell -NoProfile -NonInteractive -EncodedCommand ${b64}`;
+}
+function pwshRun(script, opts = {}) { return run(pwshCmd(script), opts); }
+function pwshOut(script, opts = {}) { return runOut(pwshCmd(script), opts); }
+
 // Clique/scroll de verdade no Windows precisam de mouse_event (user32).
 // A abordagem antiga só posicionava o cursor — nunca clicava.
-const WIN_USER32 = "Add-Type -Name U -Namespace W -MemberDefinition '[DllImport(\\\"user32.dll\\\")] public static extern bool SetCursorPos(int X,int Y); [DllImport(\\\"user32.dll\\\")] public static extern void mouse_event(uint f,uint dx,uint dy,uint d,int e);';";
+const WIN_USER32 = `Add-Type -Name U -Namespace W -MemberDefinition '[DllImport("user32.dll")] public static extern bool SetCursorPos(int X,int Y); [DllImport("user32.dll")] public static extern void mouse_event(uint f,uint dx,uint dy,uint d,int e);';`;
 
 // Primeira ferramenta cujo comando existe no PATH.
 function firstCmd(list) {
@@ -44,86 +82,574 @@ function firstCmd(list) {
     return null;
 }
 
+// Coordenada tem de ser número. Validar aqui vale para as três plataformas —
+// sem isso um x="abc" virava comando de shell quebrado, não erro legível.
+function coord(v) {
+    const n = Math.round(Number(v));
+    return Number.isFinite(n) ? n : null;
+}
+
+// ── Teclas: um dialeto por SO, uma tradução só ───────────────────────────
+// O modelo fala "ctrl+shift+t", "Enter", "alt+tab" — e cada SO tem a própria
+// gramática. Estas funções são puras (testáveis sem SO nenhum).
+
+/** "ctrl+shift+t" → { mods: ['ctrl','shift'], key: 't' } */
+function parseCombo(name) {
+    const parts = String(name || '').trim().split('+').map((s) => s.trim()).filter(Boolean);
+    const key = parts.pop() || '';
+    const mods = [];
+    for (const p of parts) {
+        const m = p.toLowerCase();
+        if (m === 'ctrl' || m === 'control') mods.push('ctrl');
+        else if (m === 'shift') mods.push('shift');
+        else if (m === 'alt' || m === 'option' || m === 'opt') mods.push('alt');
+        else if (m === 'cmd' || m === 'command' || m === 'win' || m === 'windows' || m === 'super' || m === 'meta') mods.push('super');
+    }
+    return { mods, key };
+}
+
+const F_RE = /^f([1-9]|1[0-2])$/i;
+
+// xdotool: nomes de keysym.
+const XKEYS = {
+    enter: 'Return', return: 'Return', tab: 'Tab', escape: 'Escape', esc: 'Escape',
+    backspace: 'BackSpace', delete: 'Delete', del: 'Delete', space: 'space',
+    arrowup: 'Up', up: 'Up', arrowdown: 'Down', down: 'Down',
+    arrowleft: 'Left', left: 'Left', arrowright: 'Right', right: 'Right',
+    home: 'Home', end: 'End', pageup: 'Prior', pagedown: 'Next',
+    insert: 'Insert', printscreen: 'Print',
+    win: 'Super_L', windows: 'Super_L', super: 'Super_L', cmd: 'Super_L', meta: 'Super_L',
+};
+
+/** "ctrl+shift+ArrowLeft" → "ctrl+shift+Left" (gramática do xdotool). */
+function xdoKey(name) {
+    const { mods, key } = parseCombo(name);
+    const k = key.toLowerCase();
+    const traduzida = XKEYS[k] || (F_RE.test(k) ? k.toUpperCase() : key);
+    return [...mods, traduzida].join('+');
+}
+
+// Windows SendKeys: ^=ctrl +=shift %=alt, especiais entre chaves.
+const WINKEYS = {
+    enter: '{ENTER}', return: '{ENTER}', tab: '{TAB}', escape: '{ESC}', esc: '{ESC}',
+    backspace: '{BACKSPACE}', delete: '{DEL}', del: '{DEL}', space: ' ',
+    arrowup: '{UP}', up: '{UP}', arrowdown: '{DOWN}', down: '{DOWN}',
+    arrowleft: '{LEFT}', left: '{LEFT}', arrowright: '{RIGHT}', right: '{RIGHT}',
+    home: '{HOME}', end: '{END}', pageup: '{PGUP}', pagedown: '{PGDN}',
+    insert: '{INS}', printscreen: '{PRTSC}',
+};
+
+/** Texto literal para SendKeys: +^%~(){}[] têm significado — vão entre chaves. */
+function escapeSendKeys(text) {
+    return String(text).replace(/[+^%~(){}[\]]/g, '{$&}');
+}
+
+/**
+ * "ctrl+shift+t" → "^+t" (SendKeys). Devolve null quando o atalho usa a tecla
+ * Windows, que o SendKeys não alcança — o chamador explica a alternativa.
+ * "win" sozinho vira ^{ESC}, que abre o menu Iniciar desde sempre.
+ */
+function winSendKeys(name) {
+    const { mods, key } = parseCombo(name);
+    const k = key.toLowerCase();
+    if (!mods.length && (k === 'win' || k === 'windows' || k === 'super' || k === 'meta' || k === 'cmd')) return '^{ESC}';
+    if (mods.includes('super')) return null;
+    const prefix = mods.map((m) => (m === 'ctrl' ? '^' : m === 'shift' ? '+' : '%')).join('');
+    let token = WINKEYS[k] || (F_RE.test(k) ? `{${k.toUpperCase()}}` : escapeSendKeys(key.length === 1 ? key.toLowerCase() : key));
+    // Modificador se aplica à PRÓXIMA tecla; um token de várias teclas precisa
+    // de parênteses para o modificador cobrir todas.
+    if (prefix && token.length > 1 && !/^\{[^}]+\}$/.test(token)) token = `(${token})`;
+    return prefix + token;
+}
+
+// macOS: tecla especial é key code NUMÉRICO; letra é keystroke.
+const MACCODES = {
+    enter: 36, return: 36, tab: 48, escape: 53, esc: 53, backspace: 51, delete: 117, del: 117,
+    space: 49, arrowleft: 123, left: 123, arrowright: 124, right: 124,
+    arrowdown: 125, down: 125, arrowup: 126, up: 126,
+    home: 115, end: 119, pageup: 116, pagedown: 121,
+    f1: 122, f2: 120, f3: 99, f4: 118, f5: 96, f6: 97, f7: 98, f8: 100, f9: 101, f10: 109, f11: 103, f12: 111,
+};
+
+/** A linha de System Events para uma tecla/atalho: `key code 36 using {...}`. */
+function macKeyScript(name) {
+    const { mods, key } = parseCombo(name);
+    const using = mods.map((m) => (m === 'ctrl' ? 'control down' : m === 'shift' ? 'shift down' : m === 'alt' ? 'option down' : 'command down')).join(', ');
+    const sufixo = using ? ` using {${using}}` : '';
+    const k = key.toLowerCase();
+    if (MACCODES[k] != null) return `key code ${MACCODES[k]}${sufixo}`;
+    const safe = String(key).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return `keystroke "${safe}"${sufixo}`;
+}
+
+function osascript(linhas, opts = {}) {
+    const script = Array.isArray(linhas) ? linhas.join('\n') : String(linhas);
+    return run(`osascript -e ${sh1(script)}`, opts);
+}
+function osascriptOut(linhas, opts = {}) {
+    const script = Array.isArray(linhas) ? linhas.join('\n') : String(linhas);
+    return runOut(`osascript -e ${sh1(script)}`, opts);
+}
+
 // ── Mouse ─────────────────────────────────────────────
 function click(x, y, button = 'left') {
-    if (TOOLS.xdotool) return run(`xdotool mousemove ${x} ${y} click ${button === 'right' ? 3 : 1}`);
-    if (TOOLS.cliclick) return run(`cliclick c:${x},${y}`);
+    const [xi, yi] = [coord(x), coord(y)];
+    if (xi == null || yi == null) return { ok: false, error: `Coordenada inválida: x=${x}, y=${y}` };
+    if (TOOLS.xdotool) return run(`xdotool mousemove ${xi} ${yi} click ${button === 'right' ? 3 : 1}`);
+    if (TOOLS.cliclick) return run(`cliclick ${button === 'right' ? 'rc' : 'c'}:${xi},${yi}`);
     if (PLATFORM === 'win32') {
         const down = button === 'right' ? '0x0008' : '0x0002';
         const up = button === 'right' ? '0x0010' : '0x0004';
-        return pwsh(`${WIN_USER32} [W.U]::SetCursorPos(${x},${y}); [W.U]::mouse_event(${down},0,0,0,0); [W.U]::mouse_event(${up},0,0,0,0)`);
+        return pwshRun(`${WIN_USER32} [W.U]::SetCursorPos(${xi},${yi}); Start-Sleep -Milliseconds 40; [W.U]::mouse_event(${down},0,0,0,0); [W.U]::mouse_event(${up},0,0,0,0)`);
     }
     return { ok: false, error: 'Nenhuma ferramenta de automação encontrada. Instale xdotool (Linux) ou cliclick (macOS), ou use as tools browser_*.' };
 }
 
+// Clique duplo é o que ABRE as coisas fora do navegador: ícone da área de
+// trabalho, arquivo no Explorer, célula de planilha. Sem ele o agente "clicava
+// mas nada abria".
+function doubleClick(x, y) {
+    const [xi, yi] = [coord(x), coord(y)];
+    if (xi == null || yi == null) return { ok: false, error: `Coordenada inválida: x=${x}, y=${y}` };
+    if (TOOLS.xdotool) return run(`xdotool mousemove ${xi} ${yi} click --repeat 2 --delay 120 1`);
+    if (TOOLS.cliclick) return run(`cliclick dc:${xi},${yi}`);
+    if (PLATFORM === 'win32') {
+        const clique = '[W.U]::mouse_event(0x0002,0,0,0,0); [W.U]::mouse_event(0x0004,0,0,0,0)';
+        return pwshRun(`${WIN_USER32} [W.U]::SetCursorPos(${xi},${yi}); Start-Sleep -Milliseconds 40; ${clique}; Start-Sleep -Milliseconds 90; ${clique}`);
+    }
+    return { ok: false, error: 'Clique duplo não disponível: instale xdotool (Linux) ou cliclick (macOS).' };
+}
+
 function move(x, y) {
-    if (TOOLS.xdotool) return run(`xdotool mousemove ${x} ${y}`);
-    if (TOOLS.cliclick) return run(`cliclick m:${x},${y}`);
+    const [xi, yi] = [coord(x), coord(y)];
+    if (xi == null || yi == null) return { ok: false, error: `Coordenada inválida: x=${x}, y=${y}` };
+    if (TOOLS.xdotool) return run(`xdotool mousemove ${xi} ${yi}`);
+    if (TOOLS.cliclick) return run(`cliclick m:${xi},${yi}`);
     if (PLATFORM === 'win32') {
-        return pwsh(`${WIN_USER32} [W.U]::SetCursorPos(${x},${y})`);
+        return pwshRun(`${WIN_USER32} [W.U]::SetCursorPos(${xi},${yi})`);
     }
     return { ok: false, error: 'Automação não disponível' };
 }
 
 function drag(fromX, fromY, toX, toY) {
+    const [fx, fy, tx, ty] = [coord(fromX), coord(fromY), coord(toX), coord(toY)];
+    if ([fx, fy, tx, ty].some((v) => v == null)) return { ok: false, error: 'Coordenada inválida no drag' };
     if (TOOLS.xdotool) {
-        return run(`xdotool mousemove ${fromX} ${fromY} mousedown 1 mousemove ${toX} ${toY} mouseup 1`);
+        return run(`xdotool mousemove ${fx} ${fy} mousedown 1 mousemove ${tx} ${ty} mouseup 1`);
     }
     if (TOOLS.cliclick) {
-        return run(`cliclick dd:${fromX},${fromY} du:${toX},${toY}`);
+        return run(`cliclick dd:${fx},${fy} du:${tx},${ty}`);
+    }
+    if (PLATFORM === 'win32') {
+        // Arrastar de verdade exige passos intermediários: soltar o botão no
+        // destino sem passar pelo caminho não conta como drag para o Windows.
+        const passos = [];
+        const N = 8;
+        for (let i = 1; i <= N; i++) {
+            const px = Math.round(fx + ((tx - fx) * i) / N);
+            const py = Math.round(fy + ((ty - fy) * i) / N);
+            passos.push(`[W.U]::SetCursorPos(${px},${py}); Start-Sleep -Milliseconds 25`);
+        }
+        return pwshRun(`${WIN_USER32} [W.U]::SetCursorPos(${fx},${fy}); Start-Sleep -Milliseconds 60; [W.U]::mouse_event(0x0002,0,0,0,0); Start-Sleep -Milliseconds 120; ${passos.join('; ')}; [W.U]::mouse_event(0x0004,0,0,0,0)`);
     }
     return { ok: false, error: 'Drag não suportado nesta plataforma sem xdotool/cliclick' };
 }
 
 function scroll(dy) {
-    if (TOOLS.xdotool) return run(`xdotool click --repeat ${Math.max(1, Math.abs(Math.round(dy / 50)))} ${dy > 0 ? 5 : 4}`);
-    if (TOOLS.cliclick) return run(`cliclick scroll:${Math.round(dy / 50)}`);
+    const d = Number(dy);
+    const passo = Number.isFinite(d) ? d : 300;
+    if (TOOLS.xdotool) return run(`xdotool click --repeat ${Math.max(1, Math.abs(Math.round(passo / 50)))} ${passo > 0 ? 5 : 4}`);
+    if (TOOLS.cliclick) return run(`cliclick scroll:${Math.round(passo / 50)}`);
     if (PLATFORM === 'win32') {
         // Roda do mouse: 120 = um "clique". dy>0 rola para baixo (delta negativo).
-        const delta = -Math.round(dy / 50) * 120;
-        return pwsh(`${WIN_USER32} [W.U]::mouse_event(0x0800,0,0,${delta},0)`);
+        const delta = -Math.round(passo / 50) * 120;
+        return pwshRun(`${WIN_USER32} [W.U]::mouse_event(0x0800,0,0,${delta},0)`);
     }
     return { ok: false, error: 'Scroll não suportado nesta plataforma' };
 }
 
 // ── Teclado ───────────────────────────────────────────
 function type(text) {
-    if (TOOLS.xdotool) return run(`xdotool type --delay 10 '${text.replace(/'/g, "'\''")}'`);
-    if (TOOLS.cliclick) {
-        const safe = text.replace(/"/g, '\\"');
-        return run(`osascript -e 'tell application "System Events" to keystroke "${safe}"'`);
+    const t = String(text ?? '');
+    if (!t) return { ok: true, digitado: 0 };
+    if (TOOLS.xdotool) return run(`xdotool type --delay 12 -- ${sh1(t)}`);
+    if (PLATFORM === 'darwin') {
+        // Uma keystroke por linha; entre elas, Return de verdade (key code 36) —
+        // keystroke com "\n" no meio não quebra linha em app nenhum.
+        const linhas = t.split(/\r?\n/);
+        const corpo = [];
+        linhas.forEach((l, i) => {
+            if (i > 0) corpo.push('key code 36');
+            if (l) corpo.push(`keystroke "${l.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`);
+        });
+        return osascript(['tell application "System Events"', ...corpo, 'end tell']);
     }
     if (PLATFORM === 'win32') {
-        const ps = `Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.SendKeys]::SendWait('${text.replace(/'/g, "''")}')`;
-        return run(`powershell -Command "${ps}"`);
+        // SendKeys trata +^%~(){}[] como comando — escapar TUDO, senão digitar
+        // "olá (teste)" dispara atalho em vez de texto. Depois do escape, o Enter
+        // literal vira {ENTER}.
+        const seq = escapeSendKeys(t).replace(/\r?\n/g, '{ENTER}');
+        return pwshRun(`Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.SendKeys]::SendWait($env:PRIMO_KEYS)`, { env: { PRIMO_KEYS: seq } });
     }
     return { ok: false, error: 'Automação de teclado não disponível' };
 }
 
 function key(name) {
-    // xdotool usa nomes; cada SO tem seu dialeto — traduzimos por plataforma.
-    const xmap = {
-        Enter: 'Return', Return: 'Return', Tab: 'Tab', Escape: 'Escape', Esc: 'Escape',
-        Backspace: 'BackSpace', ArrowUp: 'Up', ArrowDown: 'Down', ArrowLeft: 'Left',
-        ArrowRight: 'Right', Space: 'space', Delete: 'Delete',
-    };
-    if (TOOLS.xdotool) return run(`xdotool key ${xmap[name] || name}`);
+    if (!name) return { ok: false, error: 'Diga a tecla: "Enter", "ctrl+c", "alt+tab"…' };
+    if (TOOLS.xdotool) return run(`xdotool key --clearmodifiers ${xdoKey(name)}`);
 
     if (PLATFORM === 'darwin') {
-        // macOS: key code exige NÚMERO. Mapeamos as teclas comuns.
-        const mac = { Enter: 36, Return: 36, Tab: 48, Escape: 53, Esc: 53, Backspace: 51, Delete: 51, Space: 49, ArrowLeft: 123, ArrowRight: 124, ArrowDown: 125, ArrowUp: 126 };
-        if (mac[name] != null) return run(`osascript -e 'tell application "System Events" to key code ${mac[name]}'`);
-        // Atalho com modificadores, ex "cmd+c": usa keystroke.
-        return run(`osascript -e 'tell application "System Events" to keystroke "${String(name).replace(/"/g, '\\"')}"'`);
+        return osascript(`tell application "System Events" to ${macKeyScript(name)}`);
     }
     if (PLATFORM === 'win32') {
-        const win = { Enter: '{ENTER}', Return: '{ENTER}', Tab: '{TAB}', Escape: '{ESC}', Esc: '{ESC}', Backspace: '{BACKSPACE}', Delete: '{DEL}', Space: ' ', ArrowUp: '{UP}', ArrowDown: '{DOWN}', ArrowLeft: '{LEFT}', ArrowRight: '{RIGHT}' };
-        const seq = win[name] || name;
-        return pwsh(`Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.SendKeys]::SendWait('${seq.replace(/'/g, "''")}')`);
+        const seq = winSendKeys(name);
+        if (seq === null) {
+            return { ok: false, error: 'Atalho com a tecla Windows não é alcançável por SendKeys. Alternativas: desktop_key("win") abre o menu Iniciar; desktop_open_app abre programas direto.' };
+        }
+        return pwshRun(`Add-Type -AssemblyName System.Windows.Forms; [System.Windows.Forms.SendKeys]::SendWait($env:PRIMO_KEYS)`, { env: { PRIMO_KEYS: seq } });
     }
     return { ok: false, error: 'Key não suportado nesta plataforma' };
 }
 
+// ── Programas e janelas ───────────────────────────────
+// Abrir app o agente já conseguia pelo shell; o que faltava era o resto da
+// conversa: saber QUAIS janelas existem, trazer uma para a frente e enxergar
+// o que há dentro dela. É isso que transforma "abre mas não interage" em
+// interação de verdade.
+
+// Nomes em português do dia a dia → executável/app real. Pequena de propósito:
+// só o que tem tradução óbvia. O resto passa direto como o usuário falou.
+const APP_ALIASES = {
+    win32: {
+        'bloco de notas': 'notepad', 'notepad': 'notepad', 'calculadora': 'calc',
+        'paint': 'mspaint', 'explorador de arquivos': 'explorer', 'arquivos': 'explorer',
+        'explorer': 'explorer', 'prompt de comando': 'cmd', 'terminal': 'wt',
+        'gerenciador de tarefas': 'taskmgr', 'configuracoes': 'ms-settings:',
+        'painel de controle': 'control', 'edge': 'msedge', 'word': 'winword',
+        'excel': 'excel', 'powerpoint': 'powerpnt',
+    },
+    darwin: {
+        'calculadora': 'Calculator', 'bloco de notas': 'TextEdit', 'notas': 'Notes',
+        'arquivos': 'Finder', 'finder': 'Finder', 'terminal': 'Terminal',
+        'chrome': 'Google Chrome', 'safari': 'Safari', 'musica': 'Music',
+        'fotos': 'Photos', 'configuracoes': 'System Settings', 'ajustes': 'System Settings',
+    },
+    linux: {
+        'calculadora': 'gnome-calculator', 'arquivos': 'nautilus',
+        'bloco de notas': 'gedit', 'editor de texto': 'gedit',
+        'terminal': 'gnome-terminal', 'chrome': 'google-chrome',
+    },
+};
+
+function normaliza(s) {
+    return String(s || '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase().trim();
+}
+
+function aliasDoApp(nome, platform = PLATFORM) {
+    const mapa = APP_ALIASES[platform] || {};
+    return mapa[normaliza(nome)] || String(nome || '').trim();
+}
+
+function openApp(nome) {
+    const pedido = String(nome || '').trim();
+    if (!pedido) return { ok: false, error: 'Diga o nome do programa (ex: "chrome", "bloco de notas").' };
+    const app = aliasDoApp(pedido);
+
+    let r;
+    if (PLATFORM === 'win32') {
+        // Start-Process resolve PATH e App Paths (chrome, winword…); o start do
+        // cmd cobre o resto (URIs tipo ms-settings:, associações).
+        r = pwshOut(`$ErrorActionPreference='Stop'; $a=$env:PRIMO_APP; try { Start-Process $a; Write-Output 'OK' } catch { try { Start-Process -FilePath 'cmd.exe' -ArgumentList @('/c','start','',$a) -WindowStyle Hidden; Write-Output 'OK' } catch { Write-Output ('ERRO ' + $_.Exception.Message) } }`, { env: { PRIMO_APP: app } });
+        if (r.ok && !/^ERRO/m.test(r.out)) r = { ok: true };
+        else r = { ok: false, error: (r.out || r.error || '').trim() || `não consegui abrir "${app}"` };
+    } else if (PLATFORM === 'darwin') {
+        r = run(`open -a ${sh1(app)}`);
+        if (!r.ok && app !== pedido) r = run(`open -a ${sh1(pedido)}`);
+        if (!r.ok) r = { ok: false, error: `Não achei o app "${pedido}". Use o nome exato como aparece em /Applications.` };
+    } else {
+        const bin = app.split(/\s+/)[0];
+        if (hasCmd('gtk-launch') && run(`gtk-launch ${sh1(bin)}`).ok) r = { ok: true };
+        else if (hasCmd(bin)) r = run(`bash -c ${sh1(`setsid ${app} >/dev/null 2>&1 < /dev/null &`)}`);
+        else r = { ok: false, error: `Não achei o programa "${pedido}" no PATH.` };
+    }
+
+    if (!r.ok) return r;
+    return { ok: true, app, dica: 'A janela pode levar 1–2s para abrir. Confirme com desktop_windows e traga para a frente com desktop_focus.' };
+}
+
+function listWindows() {
+    let linhas = [];
+    if (PLATFORM === 'win32') {
+        const r = pwshOut(`Get-Process | Where-Object { $_.MainWindowTitle } | ForEach-Object { $t = $_.MainWindowTitle -replace "[\\r\\n|]", " "; Write-Output ("$($_.ProcessName)|$t") }`, { timeout: 20000 });
+        if (!r.ok && !r.out) return { ok: false, error: r.error || 'não consegui listar as janelas' };
+        linhas = r.out.split('\n');
+    } else if (PLATFORM === 'darwin') {
+        const r = osascriptOut([
+            'set saida to ""',
+            'tell application "System Events"',
+            '  repeat with p in (application processes whose visible is true)',
+            '    repeat with w in windows of p',
+            '      try',
+            '        set saida to saida & (name of p) & "|" & (name of w) & linefeed',
+            '      end try',
+            '    end repeat',
+            '  end repeat',
+            'end tell',
+            'return saida',
+        ], { timeout: 20000 });
+        if (!r.ok) return { ok: false, error: 'Não consegui listar as janelas. Conceda permissão de Acessibilidade ao Terminal em Ajustes → Privacidade e Segurança.' };
+        linhas = r.out.split('\n');
+    } else {
+        if (hasCmd('wmctrl')) {
+            const r = runOut('wmctrl -l');
+            if (r.ok) linhas = r.out.split('\n').map((l) => {
+                const m = l.match(/^\S+\s+-?\d+\s+\S+\s+(.*)$/);
+                return m ? `|${m[1]}` : '';
+            });
+        } else if (TOOLS.xdotool) {
+            const r = runOut(`xdotool search --onlyvisible --name '.*' getwindowname %@ 2>/dev/null`);
+            if (r.ok) linhas = r.out.split('\n').map((t) => (t.trim() ? `|${t.trim()}` : ''));
+        } else {
+            return { ok: false, error: 'Instale wmctrl ou xdotool para listar janelas no Linux.' };
+        }
+    }
+
+    const janelas = [];
+    for (const l of linhas) {
+        const linha = l.replace(/\r/g, '').trim();
+        if (!linha) continue;
+        const sep = linha.indexOf('|');
+        const app = sep >= 0 ? linha.slice(0, sep).trim() : '';
+        const titulo = (sep >= 0 ? linha.slice(sep + 1) : linha).trim();
+        if (titulo) janelas.push({ app, titulo });
+    }
+    return { ok: true, total: janelas.length, janelas: janelas.slice(0, 60) };
+}
+
+function focusWindow(titulo) {
+    const t = String(titulo || '').trim();
+    if (!t) return { ok: false, error: 'Diga o título (ou parte dele) da janela.' };
+
+    if (PLATFORM === 'win32') {
+        const r = pwshOut(
+            `$ErrorActionPreference='SilentlyContinue'
+Add-Type -Name W -Namespace P -MemberDefinition '[DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h); [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr h, int n); [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr h);'
+$t = $env:PRIMO_TITLE
+$p = Get-Process | Where-Object { $_.MainWindowTitle -and ($_.MainWindowTitle -match [regex]::Escape($t) -or $_.ProcessName -match [regex]::Escape($t)) } | Select-Object -First 1
+if (-not $p) { Write-Output 'NOTFOUND'; exit 0 }
+if ([P.W]::IsIconic($p.MainWindowHandle)) { [P.W]::ShowWindow($p.MainWindowHandle, 9) | Out-Null }
+[P.W]::SetForegroundWindow($p.MainWindowHandle) | Out-Null
+Write-Output $p.MainWindowTitle`,
+            { env: { PRIMO_TITLE: t }, timeout: 20000 },
+        );
+        const saida = (r.out || '').trim();
+        if (!r.ok && !saida) return { ok: false, error: r.error || 'falhou ao focar' };
+        if (/^NOTFOUND/m.test(saida)) return naoAchouJanela(t);
+        return { ok: true, janela: saida.split('\n')[0] };
+    }
+
+    if (PLATFORM === 'darwin') {
+        const safe = t.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+        const r = osascript([
+            'tell application "System Events"',
+            `  set alvo to first application process whose visible is true and (name contains "${safe}" or displayed name contains "${safe}")`,
+            '  set frontmost of alvo to true',
+            'end tell',
+        ]);
+        if (!r.ok) return naoAchouJanela(t);
+        return { ok: true, janela: t };
+    }
+
+    if (TOOLS.xdotool) {
+        const busca = runOut(`xdotool search --onlyvisible --name ${sh1(t)} 2>/dev/null`);
+        const id = (busca.out || '').trim().split('\n')[0];
+        if (!id) return naoAchouJanela(t);
+        const r = run(`xdotool windowactivate --sync ${id}`);
+        return r.ok ? { ok: true, janela: t } : r;
+    }
+    return { ok: false, error: 'Focar janela não disponível: instale xdotool (Linux).' };
+}
+
+// Erro que sabe o que EXISTE leva a informação junto — mesma ideia dos
+// "trechosParecidos" do edit_file. Erro seco faz o modelo chutar de novo.
+function naoAchouJanela(titulo) {
+    const w = listWindows();
+    return {
+        ok: false,
+        error: `Nenhuma janela combinou com "${titulo}".`,
+        janelasAbertas: w.ok ? w.janelas.map((j) => j.titulo).slice(0, 30) : undefined,
+        comoCorrigir: 'Use um título de "janelasAbertas", copiado literalmente (ou um pedaço único dele). Se o programa nem abriu, chame desktop_open_app antes.',
+    };
+}
+
+// ── Elementos da janela — os "olhos" do agente ────────────────────────────
+// Os modelos do servidor são só-texto: mandar um PNG não adianta nada. O que
+// funciona é ler a árvore de acessibilidade — a mesma que o leitor de tela usa
+// — e devolver NOME + POSIÇÃO de cada botão, campo e ícone. Aí "clique em
+// Salvar" vira coordenada exata, sem chute.
+
+const MAX_ELEMENTOS = 120;
+
+const PS_ELEMENTOS = `$ErrorActionPreference='SilentlyContinue'
+Add-Type -AssemblyName UIAutomationClient
+Add-Type -AssemblyName UIAutomationTypes
+Add-Type -Name W -Namespace P -MemberDefinition '[DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();'
+$titulo = $env:PRIMO_TITLE
+$root = [System.Windows.Automation.AutomationElement]::RootElement
+$win = $null
+if ($titulo) {
+  foreach ($w in $root.FindAll([System.Windows.Automation.TreeScope]::Children, [System.Windows.Automation.Condition]::TrueCondition)) {
+    if ($w.Current.Name -like ('*' + $titulo + '*')) { $win = $w; break }
+  }
+}
+if (-not $win) {
+  $h = [P.W]::GetForegroundWindow()
+  if ($h -ne [IntPtr]::Zero) { $win = [System.Windows.Automation.AutomationElement]::FromHandle($h) }
+}
+if (-not $win) { Write-Output 'SEMJANELA'; exit 0 }
+Write-Output ('JANELA|' + ($win.Current.Name -replace "[\\r\\n|]", ' '))
+$todos = $win.FindAll([System.Windows.Automation.TreeScope]::Descendants, [System.Windows.Automation.Condition]::TrueCondition)
+$n = 0
+foreach ($e in $todos) {
+  if ($n -ge ${MAX_ELEMENTOS}) { break }
+  $c = $e.Current
+  $nome = $c.Name
+  if (-not $nome) { continue }
+  if ($c.IsOffscreen) { continue }
+  $r = $c.BoundingRectangle
+  if ($r.Width -le 0 -or $r.Height -le 0) { continue }
+  $tipo = $c.ControlType.ProgrammaticName -replace 'ControlType\\.', ''
+  $cx = [int]($r.X + $r.Width / 2); $cy = [int]($r.Y + $r.Height / 2)
+  $nome = $nome -replace "[\\r\\n|]", ' '
+  Write-Output ("$tipo|$cx|$cy|$nome")
+  $n++
+}`;
+
+function uiElements(janela) {
+    const titulo = String(janela || '').trim();
+
+    if (PLATFORM === 'win32') {
+        const r = pwshOut(PS_ELEMENTOS, { env: { PRIMO_TITLE: titulo }, timeout: 45000 });
+        if (!r.ok && !r.out) return { ok: false, error: r.error || 'não consegui ler os elementos' };
+        if (/^SEMJANELA/m.test(r.out)) return { ok: false, error: 'Nenhuma janela em foco. Abra o programa (desktop_open_app) ou foque a janela (desktop_focus) primeiro.' };
+        return parseElementos(r.out);
+    }
+
+    if (PLATFORM === 'darwin') {
+        // `entire contents` lê a janela toda de uma vez; elemento sem nome ou
+        // sem posição só é pulado (o try engole).
+        const r = osascriptOut([
+            'set saida to ""',
+            'set n to 0',
+            'tell application "System Events"',
+            '  set p to first application process whose frontmost is true',
+            '  set saida to "JANELA|" & (name of p) & linefeed',
+            '  try',
+            '    set els to entire contents of front window of p',
+            '    repeat with e in els',
+            `      if n ≥ ${MAX_ELEMENTOS} then exit repeat`,
+            '      try',
+            '        set nm to name of e',
+            '        if nm is not missing value and nm is not "" then',
+            '          set {ex, ey} to position of e',
+            '          set {ew, eh} to size of e',
+            '          set saida to saida & (role of e) & "|" & (ex + ew div 2) & "|" & (ey + eh div 2) & "|" & nm & linefeed',
+            '          set n to n + 1',
+            '        end if',
+            '      end try',
+            '    end repeat',
+            '  end try',
+            'end tell',
+            'return saida',
+        ], { timeout: 45000 });
+        if (!r.ok) return { ok: false, error: 'Não consegui ler a janela. Conceda permissão de Acessibilidade ao Terminal em Ajustes → Privacidade e Segurança → Acessibilidade.' };
+        return parseElementos(r.out);
+    }
+
+    return { ok: false, error: 'Leitura de elementos não disponível no Linux. Caminho alternativo: desktop_screenshot para o usuário ver, e desktop_click com coordenadas (xdotool).' };
+}
+
+function parseElementos(saida) {
+    const elementos = [];
+    let janela = '';
+    const vistos = new Set();
+    for (const linha of String(saida || '').split('\n')) {
+        const l = linha.replace(/\r/g, '').trim();
+        if (!l) continue;
+        if (l.startsWith('JANELA|')) { janela = l.slice(7).trim(); continue; }
+        const partes = l.split('|');
+        if (partes.length < 4) continue;
+        const [tipo, xs, ys] = partes;
+        const nome = partes.slice(3).join('|').trim();
+        const x = Math.round(Number(xs)), y = Math.round(Number(ys));
+        if (!nome || !Number.isFinite(x) || !Number.isFinite(y)) continue;
+        const chave = `${tipo}|${x}|${y}|${nome}`;
+        if (vistos.has(chave)) continue;
+        vistos.add(chave);
+        elementos.push({ tipo: tipo.trim(), x, y, nome: nome.slice(0, 120) });
+        if (elementos.length >= MAX_ELEMENTOS) break;
+    }
+    if (!elementos.length) {
+        return { ok: false, error: 'A janela não expôs elementos nomeados (alguns apps escondem a árvore de acessibilidade). Use desktop_screenshot + desktop_click por coordenada.' , janela };
+    }
+    return { ok: true, janela, total: elementos.length, elementos };
+}
+
+/**
+ * Melhor elemento para um nome pedido — sem acento, sem caixa, aceitando
+ * pedaço ("salvar" acha "Salvar como…"). Pura, para o teste bater sem SO.
+ */
+function escolherElemento(elementos, consulta) {
+    const q = normaliza(consulta);
+    if (!q) return null;
+    let melhor = null;
+    let nota = 0;
+    for (const e of elementos || []) {
+        const n = normaliza(e.nome);
+        if (!n) continue;
+        let s = 0;
+        // O nome que ESTENDE a consulta ("salvar como" → "Salvar como…") vale
+        // mais que a consulta estender o nome: quem pediu a frase maior quis o
+        // elemento maior, não o irmão de nome curto.
+        if (n === q) s = 100;
+        else if (n.startsWith(q)) s = 85;
+        else if (q.startsWith(n)) s = 75;
+        else if (n.includes(q)) s = 65;
+        else if (q.includes(n)) s = 55;
+        else {
+            const termos = q.split(/\s+/).filter((t) => t.length > 1);
+            const acertos = termos.filter((t) => n.includes(t)).length;
+            if (acertos) s = Math.round((40 * acertos) / termos.length);
+        }
+        if (!s) continue;
+        // Empate: nome mais curto costuma ser o botão em si, não a frase que o contém.
+        if (s > nota || (s === nota && melhor && e.nome.length < melhor.nome.length)) { nota = s; melhor = e; }
+    }
+    return nota >= 40 ? melhor : null;
+}
+
+function clickElement(nome, opts = {}) {
+    const pedido = String(nome || '').trim();
+    if (!pedido) return { ok: false, error: 'Diga o nome do elemento (o texto do botão, ícone ou campo).' };
+
+    const lidos = uiElements(opts.window);
+    if (!lidos.ok) return lidos;
+
+    const alvo = escolherElemento(lidos.elementos, pedido);
+    if (!alvo) {
+        return {
+            ok: false,
+            error: `Nenhum elemento parecido com "${pedido}" na janela "${lidos.janela}".`,
+            elementosDisponiveis: lidos.elementos.slice(0, 40).map((e) => e.nome),
+            comoCorrigir: 'Chame de novo com um nome de "elementosDisponiveis", copiado literalmente.',
+        };
+    }
+
+    const r = opts.double ? doubleClick(alvo.x, alvo.y) : click(alvo.x, alvo.y, opts.button || 'left');
+    if (!r.ok) return r;
+    return { ok: true, clicado: alvo.nome, tipo: alvo.tipo, x: alvo.x, y: alvo.y, duplo: !!opts.double };
+}
+
 // ── Screenshot ────────────────────────────────────────
 function screenshot(saveTo) {
     const filename = saveTo || `desktop-${Date.now()}.png`;
@@ -133,8 +659,8 @@ function screenshot(saveTo) {
         return done(run(`screencapture -x "${filename}"`));
     }
     if (PLATFORM === 'win32') {
-        const ps = `Add-Type -AssemblyName System.Drawing; Add-Type -AssemblyName System.Windows.Forms; $b=[System.Windows.Forms.Screen]::PrimaryScreen.Bounds; $bmp=New-Object System.Drawing.Bitmap($b.Width,$b.Height); $g=[System.Drawing.Graphics]::FromImage($bmp); $g.CopyFromScreen($b.Location,[System.Drawing.Point]::Empty,$bmp.Size); $bmp.Save('${filename}'); $g.Dispose(); $bmp.Dispose()`;
-        return done(pwsh(ps));
+        const ps = `Add-Type -AssemblyName System.Drawing; Add-Type -AssemblyName System.Windows.Forms; $b=[System.Windows.Forms.Screen]::PrimaryScreen.Bounds; $bmp=New-Object System.Drawing.Bitmap($b.Width,$b.Height); $g=[System.Drawing.Graphics]::FromImage($bmp); $g.CopyFromScreen($b.Location,[System.Drawing.Point]::Empty,$bmp.Size); $bmp.Save('${filename.replace(/'/g, "''")}'); $g.Dispose(); $bmp.Dispose()`;
+        return done(pwshRun(ps));
     }
     // Linux: tenta as ferramentas comuns, na ordem.
     const scrot = firstCmd(['scrot', 'gnome-screenshot', 'spectacle', 'import', 'maim']);
@@ -182,8 +708,13 @@ function getScreenSize() {
 }
 
 module.exports = {
-    click, move, drag, scroll,
+    click, doubleClick, move, drag, scroll,
     type, key,
+    openApp, listWindows, focusWindow, uiElements, clickElement,
     screenshot, getScreenSize,
     TOOLS,
+    // Puras, exportadas para o test/desktop.test.js provar a tradução de teclas
+    // e a escolha de elemento sem depender do SO da máquina de teste.
+    parseCombo, xdoKey, winSendKeys, macKeyScript, escapeSendKeys,
+    escolherElemento, aliasDoApp,
 };