bridgerator 1.0.8 → 1.1.1

package/src/recycle.ps1

@@ -0,0 +1,110 @@
+# Bridgerator: move files / folders to the Recycle Bin (never a permanent delete). Loaded after
+# ask-lib.ps1 (Add-CachedType). Reads a JSON list of absolute paths on stdin, prints one JSON line:
+# [{p, r}] with r = 'recycled' | 'nobin' (this drive has no Recycle Bin / the item is too big for it:
+# nothing was deleted) | 'missing' | 'error:<hresult>'; a recycled item also carries bin = the path of
+# its copy in the Recycle Bin ($R...), so Undo later removes exactly that copy and no other.
+# IFileOperation with FOFX_RECYCLEONDELETE and no UI; a progress sink checks PreDeleteItem: without
+# TSF_DELETE_RECYCLE_IF_POSSIBLE the shell would delete for good, so the item is aborted instead.
+$ErrorActionPreference = 'Stop'
+[Console]::InputEncoding = [Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+Add-CachedType @'
+using System; using System.IO; using System.Runtime.InteropServices;
+[ComImport, Guid("43826d1e-e718-42ee-bc55-a1e261c37bfe"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+public interface IBrShellItem { void BindToHandler(IntPtr pbc, ref Guid bhid, ref Guid riid, out IntPtr ppv); void GetParent(out IBrShellItem ppsi); void GetDisplayName(uint sigdn, out IntPtr name); void GetAttributes(uint mask, out uint attrs); void Compare(IBrShellItem psi, uint hint, out int order); }
+[ComImport, Guid("04b0f1a7-9490-44bc-96e1-4296a31252e2"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+public interface IBrSink {
+  [PreserveSig] int StartOperations();
+  [PreserveSig] int FinishOperations(int hr);
+  [PreserveSig] int PreRenameItem(uint f, IBrShellItem i, [MarshalAs(UnmanagedType.LPWStr)] string n);
+  [PreserveSig] int PostRenameItem(uint f, IBrShellItem i, [MarshalAs(UnmanagedType.LPWStr)] string n, int hr, IBrShellItem c);
+  [PreserveSig] int PreMoveItem(uint f, IBrShellItem i, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n);
+  [PreserveSig] int PostMoveItem(uint f, IBrShellItem i, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n, int hr, IBrShellItem c);
+  [PreserveSig] int PreCopyItem(uint f, IBrShellItem i, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n);
+  [PreserveSig] int PostCopyItem(uint f, IBrShellItem i, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n, int hr, IBrShellItem c);
+  [PreserveSig] int PreDeleteItem(uint f, IBrShellItem i);
+  [PreserveSig] int PostDeleteItem(uint f, IBrShellItem i, int hr, IBrShellItem c);
+  [PreserveSig] int PreNewItem(uint f, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n);
+  [PreserveSig] int PostNewItem(uint f, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n, [MarshalAs(UnmanagedType.LPWStr)] string t, uint a, int hr, IBrShellItem c);
+  [PreserveSig] int UpdateProgress(uint total, uint sofar);
+  [PreserveSig] int ResetTimer();
+  [PreserveSig] int PauseTimer();
+  [PreserveSig] int ResumeTimer();
+}
+[ComImport, Guid("947aab5f-0a5c-4c13-b4d6-4bf7836fc9f8"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+public interface IBrFileOperation {
+  uint Advise(IBrSink s); void Unadvise(uint c); void SetOperationFlags(uint f);
+  void SetProgressMessage([MarshalAs(UnmanagedType.LPWStr)] string m); void SetProgressDialog([MarshalAs(UnmanagedType.IUnknown)] object d);
+  void SetProperties([MarshalAs(UnmanagedType.IUnknown)] object p); void SetOwnerWindow(IntPtr h);
+  void ApplyPropertiesToItem(IBrShellItem i); void ApplyPropertiesToItems([MarshalAs(UnmanagedType.IUnknown)] object i);
+  void RenameItem(IBrShellItem i, [MarshalAs(UnmanagedType.LPWStr)] string n, IBrSink s); void RenameItems([MarshalAs(UnmanagedType.IUnknown)] object i, [MarshalAs(UnmanagedType.LPWStr)] string n);
+  void MoveItem(IBrShellItem i, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n, IBrSink s); void MoveItems([MarshalAs(UnmanagedType.IUnknown)] object i, IBrShellItem d);
+  void CopyItem(IBrShellItem i, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n, IBrSink s); void CopyItems([MarshalAs(UnmanagedType.IUnknown)] object i, IBrShellItem d);
+  void DeleteItem(IBrShellItem i, IBrSink s); void DeleteItems([MarshalAs(UnmanagedType.IUnknown)] object i);
+  void NewItem(IBrShellItem d, uint a, [MarshalAs(UnmanagedType.LPWStr)] string n, [MarshalAs(UnmanagedType.LPWStr)] string t, IBrSink s);
+  void PerformOperations(); [return: MarshalAs(UnmanagedType.Bool)] bool GetAnyOperationsAborted();
+}
+public class BrRecycleSink : IBrSink {
+  public bool Seen, ToBin; public int Hr; public string Bin;
+  public int PreDeleteItem(uint f, IBrShellItem i) { Seen = true; ToBin = (f & 0x80) != 0; return ToBin ? 0 : unchecked((int)0x80004004); }
+  public int PostDeleteItem(uint f, IBrShellItem i, int hr, IBrShellItem c) {
+    Hr = hr;
+    // c = the item now in the Recycle Bin (null when deleted for good): its file-system path (SIGDN_FILESYSPATH).
+    if (c != null) { try { IntPtr n; c.GetDisplayName(0x80058000, out n); Bin = Marshal.PtrToStringUni(n); Marshal.FreeCoTaskMem(n); } catch { Bin = null; } }
+    return 0;
+  }
+  public int StartOperations() { return 0; } public int FinishOperations(int hr) { return 0; }
+  public int PreRenameItem(uint f, IBrShellItem i, string n) { return 0; } public int PostRenameItem(uint f, IBrShellItem i, string n, int hr, IBrShellItem c) { return 0; }
+  public int PreMoveItem(uint f, IBrShellItem i, IBrShellItem d, string n) { return 0; } public int PostMoveItem(uint f, IBrShellItem i, IBrShellItem d, string n, int hr, IBrShellItem c) { return 0; }
+  public int PreCopyItem(uint f, IBrShellItem i, IBrShellItem d, string n) { return 0; } public int PostCopyItem(uint f, IBrShellItem i, IBrShellItem d, string n, int hr, IBrShellItem c) { return 0; }
+  public int PreNewItem(uint f, IBrShellItem d, string n) { return 0; } public int PostNewItem(uint f, IBrShellItem d, string n, string t, uint a, int hr, IBrShellItem c) { return 0; }
+  public int UpdateProgress(uint t, uint s) { return 0; } public int ResetTimer() { return 0; } public int PauseTimer() { return 0; } public int ResumeTimer() { return 0; }
+}
+public static class BrRecycle {
+  [DllImport("shell32.dll", CharSet = CharSet.Unicode, PreserveSig = false)]
+  static extern void SHCreateItemFromParsingName(string path, IntPtr pbc, [MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out IBrShellItem item);
+  // FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR | FOF_ALLOWUNDO | FOFX_RECYCLEONDELETE | FOFX_EARLYFAILURE
+  const uint FLAGS = 0x0004 | 0x0010 | 0x0400 | 0x0200 | 0x0040 | 0x00080000 | 0x00100000;
+  public static string LastBin;
+  public static string One(string path) {
+    LastBin = null;
+    if (!File.Exists(path) && !Directory.Exists(path)) return "missing";
+    try {
+      var root = Path.GetPathRoot(path);
+      if (string.IsNullOrEmpty(root) || root.StartsWith(@"\\")) return "nobin";
+      var dt = new DriveInfo(root).DriveType;
+      if (dt != DriveType.Fixed && dt != DriveType.Removable) return "nobin";
+    } catch { return "nobin"; }
+    var op = (IBrFileOperation)Activator.CreateInstance(Type.GetTypeFromCLSID(new Guid("3ad05575-8857-4850-9277-11b85bdb8e09")));
+    var sink = new BrRecycleSink();
+    try {
+      op.SetOperationFlags(FLAGS);
+      IBrShellItem item; SHCreateItemFromParsingName(path, IntPtr.Zero, typeof(IBrShellItem).GUID, out item);
+      op.DeleteItem(item, sink);
+      try { op.PerformOperations(); } catch (COMException e) { if (sink.Seen && !sink.ToBin) return "nobin"; return "error:" + e.ErrorCode.ToString("x8"); }
+      if (sink.Seen && !sink.ToBin) return "nobin";
+      if (sink.Hr < 0) return "error:" + sink.Hr.ToString("x8");
+      if (!sink.Seen || File.Exists(path) || Directory.Exists(path)) return op.GetAnyOperationsAborted() ? "nobin" : "error:not-deleted";
+      LastBin = sink.Bin;
+      return "recycled";
+    } catch (Exception e) { return "error:" + e.GetType().Name; }
+    finally { Marshal.ReleaseComObject(op); }
+  }
+}
+'@
+$list = [Console]::In.ReadToEnd() | ConvertFrom-Json
+# Each item: a path, or {p, skip}: skip = letters h / s / r - a hidden / system / read-only item is left
+# alone ('skipped'), as the command itself would (a wildcard without -Force / /a / /f).
+function Test-Skip([string]$path, [string]$skip) {
+  if (-not $skip) { return $false }
+  try { $a = [IO.File]::GetAttributes($path) } catch { return $false }
+  return (($skip.Contains('h') -and ($a -band [IO.FileAttributes]::Hidden)) -or ($skip.Contains('s') -and ($a -band [IO.FileAttributes]::System)) -or ($skip.Contains('r') -and ($a -band [IO.FileAttributes]::ReadOnly)))
+}
+$out = @(foreach ($x in @($list)) {
+  if ($x -is [string]) { $p = $x; $skip = '' } else { $p = [string]$x.p; $skip = [string]$x.skip }
+  if (Test-Skip $p $skip) { @{ p = $p; r = 'skipped' } } else {
+    $r = [BrRecycle]::One($p)
+    if ($r -eq 'recycled' -and [BrRecycle]::LastBin) { @{ p = $p; r = $r; bin = [BrRecycle]::LastBin } } else { @{ p = $p; r = $r } }
+  }
+})
+[Console]::Out.WriteLine((ConvertTo-Json -InputObject @($out) -Compress -Depth 3))

package/src/screen-tool.mjs

@@ -0,0 +1,185 @@
+// LOGIC: see critical-logic/bridge.md ("Extra tools", screen). `screen`: the list of open windows, a
+// screenshot of the whole screen / one monitor / one window, and text recognition (Windows' built-in
+// OCR, the languages installed on the PC) of the screen, a window or an image file. Everything runs in
+// screen.ps1 (user32 + System.Drawing + Windows.Media.Ocr); no extra programs, nothing downloaded.
+// Every screenshot shows a notification on the PC ("the AI took a screenshot") unless the person turned
+// that off (screen.notify). Screenshots can be switched off completely (screen.enabled).
+// A locked screen / sign-in screen / UAC prompt can't be captured: an honest error, never a black picture.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { showNotice } from './notice.mjs';
+import { fail, guard, freeName, needAction, str, int, psJson, ToolError } from './tool-lib.mjs';
+
+const PS = fileURLToPath(new URL('./screen.ps1', import.meta.url));
+export const MAX_SIDE = 1600;                 // long side of the picture sent to the AI
+export const MAX_BYTES = 900 * 1024;          // JPEG bytes (base64 ≈ 1.2 MB)
+const MAX_B64 = Math.ceil(MAX_BYTES / 3) * 4 + 4;
+const MAX_TEXT = 60000;
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.bmp', '.gif', '.tif', '.tiff']);
+const ACTIONS = ['windows', 'capture', 'ocr'];
+
+export const defs = [{
+  name: 'screen',
+  title: 'Screen and text recognition',
+  description: 'Screenshots and text recognition on this PC. action "windows": open windows (id, title, program). '
+    + '"capture": a picture of the whole screen, one monitor (monitor) or one window (window = part of its title, or window_id); save_to also keeps a full-size copy. '
+    + '"ocr": the text on the screen, a window or an image file (path), recognized by Windows (languages installed on the PC; language like "en-US"). '
+    + 'The person sees a notification on the PC for each screenshot. A locked screen can\'t be captured.',
+  inputSchema: {
+    type: 'object', additionalProperties: false, required: ['action'],
+    properties: {
+      action: { type: 'string', enum: ACTIONS },
+      window: { type: 'string', maxLength: 200, description: 'Part of the window title (any case)' },
+      window_id: { type: 'integer', minimum: 1, description: 'Window id from action "windows"' },
+      monitor: { type: 'integer', minimum: 1, maximum: 16, description: 'Monitor number; without it: all monitors' },
+      language: { type: 'string', maxLength: 20, description: 'OCR language tag, e.g. "en-US", "ru"' },
+      path: { type: 'string', maxLength: 1000, description: 'Image file for ocr instead of the screen' },
+      save_to: { type: 'string', maxLength: 1000, description: 'Full path of a .png or .jpg for a full-size copy (capture)' },
+    },
+  },
+  annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+}];
+
+export const settings = [
+  { key: 'screen.enabled', default: true, widensWhen: true, label: { en: 'Screenshots and screen text recognition', ru: 'Снимки экрана и распознавание текста' }, hint: { en: 'The AI can take a picture of the screen or a window.', ru: 'ИИ может сделать снимок экрана или окна.' } },
+  { key: 'screen.notify', default: true, widensWhen: false, label: { en: 'Notify me about every screenshot', ru: 'Уведомлять о каждом снимке экрана' }, hint: { en: 'A notification "the AI took a screenshot" appears on the PC.', ru: 'На ПК появляется уведомление «ИИ сделал снимок экрана».' } },
+];
+const DEFAULT = Object.fromEntries(settings.map((s) => [s.key, s.default]));
+function setting(ctx, key) {
+  if (ctx.extra?.value) return ctx.extra.value(ctx.cfg, key);
+  const [g, k] = key.split('.');
+  const v = ctx.cfg?.[g]?.[k];
+  return typeof v === 'boolean' ? v : DEFAULT[key];
+}
+
+const clean = (s, n = 200) => String(s ?? '').replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, ' ').trim().slice(0, n);
+const run = (ctx, env, timeout = 60000) => psJson(ctx, { files: [PS], env, timeout });
+const check = (r) => { if (!r || r.ok !== true) throw new ToolError(r?.code || 'PS_FAILED', MESSAGES[r?.code] || clean(r?.message, 300) || 'Windows could not do it.', HINTS[r?.code] || ''); return r; };
+const MESSAGES = {
+  SCREEN_LOCKED: 'The screen is locked (or the sign-in screen / a Windows security prompt is open), so no screenshot can be taken until the person unlocks the PC.',
+};
+const HINTS = {
+  SCREEN_LOCKED: 'Ask the person to unlock the PC and try again.',
+  NO_WINDOW: 'Call screen with action "windows" to see the open windows.',
+  NO_MONITOR: 'Leave monitor out to capture all monitors.',
+  NO_OCR_LANG: 'The person can add a language with text recognition in Windows Settings → Time & language → Language & region (Add a language).',
+  BAD_LANG: 'Use one of the installed languages, or leave language out.',
+  BAD_IMAGE: 'Use a PNG, JPEG, BMP, GIF or TIFF file.',
+  IMAGE_TOO_LARGE: 'Use a smaller image or capture one window instead of all monitors.',
+  EXISTS: 'Call again: a new free name is chosen.',
+};
+
+/** Part of a title → one window: exact title first, then the topmost window whose title contains it. */
+export function pickWindow(list, query) {
+  const q = clean(query).toLowerCase();
+  if (!q) fail('BAD_ARGS', 'window must name a part of a window title.');
+  const hits = list.filter((w) => String(w.title).toLowerCase().includes(q));
+  if (!hits.length) {
+    const titles = list.slice(0, 15).map((w) => `"${clean(w.title, 80)}"`).join(', ');
+    fail('NO_WINDOW', `No open window has "${clean(query, 80)}" in its title.${titles ? ` Open windows: ${titles}.` : ''}`, HINTS.NO_WINDOW);
+  }
+  const exact = hits.find((w) => String(w.title).toLowerCase() === q);
+  return { win: exact || hits[0], others: hits.length - 1 };
+}
+
+const kb = (n) => `${Math.max(1, Math.round(n / 1024))} KB`;
+
+// The capture runs in a second PowerShell: it checks the id still belongs to the same program.
+const winEnv = (win) => ({ BRX_HWND: String(win.id), ...(Number.isInteger(win.pid) && win.pid > 0 ? { BRX_PID: String(win.pid) } : {}) });
+async function target(ctx, args) {
+  const windowQuery = str(args, 'window', { max: 200 });
+  const windowId = args.window_id === undefined ? undefined : int(args, 'window_id', { min: 1, max: Number.MAX_SAFE_INTEGER });
+  const monitor = int(args, 'monitor', { min: 1, max: 16, def: 0 });
+  if ((windowQuery || windowId) && monitor) fail('BAD_ARGS', 'Use either window / window_id or monitor, not both.');
+  if (windowId || windowQuery) {
+    const r = check(await run(ctx, { BRX_ACTION: 'windows' }));
+    const list = Array.isArray(r.windows) ? r.windows : [];
+    if (windowId) {
+      const win = list.find((w) => w.id === windowId);
+      if (!win) fail('NO_WINDOW', 'That window is not open any more.', HINTS.NO_WINDOW);
+      return { env: winEnv(win), what: 'window', win, others: 0 };
+    }
+    const { win, others } = pickWindow(list, windowQuery);
+    return { env: winEnv(win), what: 'window', win, others };
+  }
+  return { env: monitor ? { BRX_MONITOR: String(monitor) } : {}, what: monitor ? 'monitor' : 'screen', monitor };
+}
+
+function saveTarget(ctx, p) {
+  if (p === undefined) return undefined;
+  const abs = guard(ctx, p, { write: true });
+  if (!['.png', '.jpg', '.jpeg'].includes(path.extname(abs).toLowerCase())) fail('BAD_PATH', 'save_to must end with .png or .jpg.');
+  if (!fs.existsSync(path.dirname(abs))) fail('BAD_PATH', `The folder "${path.dirname(abs)}" does not exist.`, 'Create the folder first or choose another one.');
+  return freeName(abs);
+}
+
+function indicate(ctx, t, ocr) {
+  if (!setting(ctx, 'screen.notify')) return;
+  try {
+    (ctx.notice ?? showNotice)({ kind: 'screenshot', what: t.what, monitor: t.monitor, title: t.win?.title, ocr }, ctx.log || (() => {}));
+  } catch (e) { ctx.log?.(`[bridgerator] screenshot notice failed: ${e?.message || e}`); }
+}
+
+const describeTarget = (t) => (t.what === 'window' ? `window "${clean(t.win.title, 120)}"` : t.what === 'monitor' ? `monitor ${t.monitor}` : 'the whole screen');
+
+function linesText(r) {
+  let s = (Array.isArray(r.lines) ? r.lines : []).map((l) => clean(l, 2000)).join('\n');
+  if (s.length > MAX_TEXT) s = `${s.slice(0, MAX_TEXT)}\n[… cut at ${MAX_TEXT} characters]`;
+  return s;
+}
+
+export async function handle(name, args, ctx) {
+  const action = needAction(args, ACTIONS);
+  const lang = str(args, 'language', { max: 20 });
+  if (lang && !/^[a-z]{2,3}(-[a-z0-9]{2,8})*$/i.test(lang)) fail('BAD_ARGS', 'language must be a tag like "en-US" or "ru".');
+
+  // OCR of an image file is not a screenshot: no screen setting, no notice — the folder rules apply.
+  if (action === 'ocr' && args.path !== undefined) {
+    const file = guard(ctx, str(args, 'path', { required: true, max: 1000 }));
+    if (!IMAGE_EXT.has(path.extname(file).toLowerCase())) fail('BAD_IMAGE', 'This is not an image file.', HINTS.BAD_IMAGE);
+    const st = fs.statSync(file);
+    if (!st.isFile()) fail('BAD_PATH', 'path must be an image file, not a folder.');
+    if (st.size > 50 * 1024 * 1024) fail('IMAGE_TOO_LARGE', 'The image is larger than 50 MB.', HINTS.IMAGE_TOO_LARGE);
+    const r = check(await run(ctx, { BRX_ACTION: 'ocr', BRX_FILE: file, ...(lang ? { BRX_LANG: lang } : {}) }, 120000));
+    const body = linesText(r);
+    return { content: [{ type: 'text', text: `Text recognized in ${path.basename(file)} (${r.width}×${r.height}, language ${clean(r.language, 20)}):\n${body || '[no text found]'}` }] };
+  }
+  if (args.path !== undefined) fail('BAD_ARGS', 'path is only for action "ocr".');
+
+  if (!setting(ctx, 'screen.enabled')) {
+    fail('SCREEN_OFF', 'Screenshots are turned off on this PC.', 'The person can turn them on in the Bridgerator window (Settings), or you can ask with bridgerator_settings (screen.enabled); the person confirms it on the PC.');
+  }
+
+  if (action === 'windows') {
+    const r = check(await run(ctx, { BRX_ACTION: 'windows' }));
+    const windows = (Array.isArray(r.windows) ? r.windows : []).slice(0, 100).map((w) => ({ id: w.id, title: clean(w.title), program: clean(w.process, 60), ...(w.minimized ? { minimized: true } : {}) }));
+    return { content: [{ type: 'text', text: JSON.stringify({ windows }, null, 2) }] };
+  }
+
+  if (action === 'ocr' && args.save_to !== undefined) fail('BAD_ARGS', 'save_to is only for action "capture".');
+  const t = await target(ctx, args);
+  const save = action === 'capture' ? saveTarget(ctx, args.save_to) : undefined;
+  const env = { BRX_ACTION: action, ...t.env, ...(lang ? { BRX_LANG: lang } : {}), ...(save ? { BRX_SAVE: save } : {}),
+    ...(action === 'capture' ? { BRX_IMAGE: '1', BRX_MAXSIDE: String(MAX_SIDE), BRX_MAXBYTES: String(MAX_BYTES) } : {}) };
+  // The person is told about every picture taken (after the capture, so the notice is not in it) — also
+  // when a later step failed (taken) or the run did not answer (it may have taken one).
+  let raw;
+  try { raw = await run(ctx, env, action === 'ocr' ? 120000 : 60000); } catch (e) { indicate(ctx, t, action === 'ocr'); throw e; }
+  if (raw?.ok === true || raw?.taken === true) indicate(ctx, t, action === 'ocr');
+  const r = check(raw);
+  const notes = [
+    ...(t.others ? [`${t.others} other window(s) also match "${clean(args.window, 80)}"; use window_id to pick another one.`] : []),
+    ...(r.minimized ? ['The window is minimized: Windows may give an empty or old picture of it.'] : []),
+  ];
+  if (action === 'ocr') {
+    const body = linesText(r);
+    return { content: [{ type: 'text', text: `Text on ${describeTarget(t)} (${r.width}×${r.height}, language ${clean(r.language, 20)}):\n${body || '[no text found]'}${notes.length ? `\n\n${notes.join(' ')}` : ''}` }] };
+  }
+  if (typeof r.data !== 'string' || !r.data || r.data.length > MAX_B64 || !/^[A-Za-z0-9+/]+=*$/.test(r.data.slice(-64))) {
+    fail('IMAGE_TOO_LARGE', 'The screenshot could not be made small enough to send.', HINTS.IMAGE_TOO_LARGE);
+  }
+  const head = `Screenshot of ${describeTarget(t)}: ${r.width}×${r.height}, sent as ${r.outWidth}×${r.outHeight} JPEG (${kb(r.bytes || r.data.length * 0.75)}).`;
+  const saved = r.saved ? ` Full-size copy saved: ${r.saved}` : '';
+  return { content: [{ type: 'text', text: `${head}${saved}${notes.length ? ` ${notes.join(' ')}` : ''}` }, { type: 'image', data: r.data, mimeType: 'image/jpeg' }] };
+}

package/src/screen.ps1

@@ -0,0 +1,285 @@
+# LOGIC: see critical-logic/bridge.md ("Extra tools", screen). Screenshot / window list / OCR for the
+# `screen` tool (screen-tool.mjs). Windows PowerShell 5.1, no extra programs: user32 + System.Drawing for
+# the picture, the built-in Windows.Media.Ocr engine for text. Input only through BRX_* environment
+# variables; output = ONE JSON line. Never shows a window, never moves or restores the person's windows.
+#   BRX_ACTION  windows | capture | ocr | langs
+#   BRX_HWND    window id (capture / ocr of one window; BRX_PID = its process then, must still match), BRX_MONITOR 1-based monitor (0 = all)
+#   BRX_FILE    image file to recognize (ocr), BRX_LANG OCR language tag (empty = the user's languages)
+#   BRX_IMAGE   1 = return the compressed picture, BRX_MAXSIDE / BRX_MAXBYTES its limits, BRX_SAVE full-size copy path
+
+function Out-Json($o) { [Console]::Out.WriteLine((ConvertTo-Json -InputObject $o -Depth 6 -Compress)) }
+# taken = a picture was already made: the bridge shows the screenshot notice even when a later step fails.
+$script:taken = $false
+function Fail([string]$code, [string]$message, $extra = @{}) { $o = @{ ok = $false; code = $code; message = $message }; if ($script:taken) { $o.taken = $true }; foreach ($k in $extra.Keys) { $o[$k] = $extra[$k] }; Out-Json $o; exit 0 }
+
+# Compiled helpers are cached like the tray helper's (%LOCALAPPDATA%\Bridgerator\cache, br-<hash>.dll).
+function Add-CachedType([string]$code, [string[]]$refs = @()) {
+  try {
+    $dir = Join-Path $env:LOCALAPPDATA 'Bridgerator\cache'
+    $bytes = [Text.Encoding]::UTF8.GetBytes("$code|$($refs -join ',')|$($PSVersionTable.CLRVersion)")
+    $key = -join ([Security.Cryptography.SHA256]::Create().ComputeHash($bytes)[0..11] | ForEach-Object { $_.ToString('x2') })
+    $dll = Join-Path $dir "br-$key.dll"
+    if (-not [IO.File]::Exists($dll)) {
+      [void][IO.Directory]::CreateDirectory($dir)
+      $tmp = Join-Path $dir "br-$key.$PID.dll"
+      Add-Type -TypeDefinition $code -ReferencedAssemblies $refs -OutputAssembly $tmp -OutputType Library
+      try { [IO.File]::Move($tmp, $dll) } catch {
+        # Another run compiled the same helper at the same moment: use its file, drop ours.
+        if ([IO.File]::Exists($dll)) { try { [IO.File]::Delete($tmp) } catch { } } else { $dll = $tmp }
+      }
+    }
+    Add-Type -Path $dll
+  } catch {
+    Add-Type -TypeDefinition $code -ReferencedAssemblies $refs
+  }
+}
+
+Add-CachedType -refs System.Drawing @'
+using System; using System.Text; using System.Collections.Generic; using System.Runtime.InteropServices;
+using System.Drawing; using System.Drawing.Imaging; using System.Drawing.Drawing2D; using System.IO;
+public static class BrShot {
+  delegate bool EnumProc(IntPtr h, IntPtr l);
+  delegate bool MonProc(IntPtr m, IntPtr dc, ref RECT r, IntPtr l);
+  [StructLayout(LayoutKind.Sequential)] public struct RECT { public int L, T, R, B; }
+  [DllImport("user32.dll")] static extern bool EnumWindows(EnumProc f, IntPtr l);
+  [DllImport("user32.dll")] static extern bool EnumDisplayMonitors(IntPtr dc, IntPtr clip, MonProc f, IntPtr l);
+  [DllImport("user32.dll")] static extern bool IsWindowVisible(IntPtr h);
+  [DllImport("user32.dll")] static extern bool IsWindow(IntPtr h);
+  [DllImport("user32.dll")] static extern bool IsIconic(IntPtr h);
+  [DllImport("user32.dll", CharSet = CharSet.Unicode)] static extern int GetWindowText(IntPtr h, StringBuilder s, int n);
+  [DllImport("user32.dll")] static extern int GetWindowTextLength(IntPtr h);
+  [DllImport("user32.dll")] static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
+  [DllImport("user32.dll")] static extern int GetWindowLong(IntPtr h, int idx);
+  [DllImport("user32.dll")] static extern bool GetWindowRect(IntPtr h, out RECT r);
+  [DllImport("user32.dll")] static extern bool PrintWindow(IntPtr h, IntPtr hdc, uint flags);
+  [DllImport("dwmapi.dll")] static extern int DwmGetWindowAttribute(IntPtr h, int a, out int v, int size);
+  [DllImport("dwmapi.dll")] static extern int DwmGetWindowAttribute(IntPtr h, int a, out RECT r, int size);
+  [DllImport("user32.dll")] static extern IntPtr OpenInputDesktop(uint flags, bool inherit, uint access);
+  [DllImport("user32.dll")] static extern bool CloseDesktop(IntPtr h);
+  [DllImport("user32.dll", CharSet = CharSet.Unicode)] static extern bool GetUserObjectInformation(IntPtr h, int idx, StringBuilder buf, int len, out int needed);
+  [DllImport("user32.dll")] static extern IntPtr SetThreadDpiAwarenessContext(IntPtr c);
+  [DllImport("user32.dll")] static extern bool SetProcessDPIAware();
+
+  // Physical pixels on every monitor (per-monitor v2; older Windows: system aware).
+  public static void Dpi() {
+    try { if (SetThreadDpiAwarenessContext(new IntPtr(-4)) != IntPtr.Zero) return; } catch (Exception) { }
+    try { SetProcessDPIAware(); } catch (Exception) { }
+  }
+  // The desktop that gets the keyboard: "Default" when the person is working; locked screen, sign-in
+  // screen and UAC prompts are on the secure desktop (not readable from here) -> null.
+  public static string InputDesktop() {
+    IntPtr d = OpenInputDesktop(0, false, 0x0001);
+    if (d == IntPtr.Zero) return null;
+    try { StringBuilder b = new StringBuilder(256); int n; return GetUserObjectInformation(d, 2, b, b.Capacity * 2, out n) ? b.ToString() : null; }
+    finally { CloseDesktop(d); }
+  }
+  public class Win { public long Id; public string Title; public uint Pid; public bool Minimized; public int W, H; }
+  public static List<Win> Windows() {
+    List<Win> list = new List<Win>();
+    EnumWindows(delegate(IntPtr h, IntPtr l) {
+      if (!IsWindowVisible(h)) return true;
+      int len = GetWindowTextLength(h);
+      if (len <= 0) return true;
+      if ((GetWindowLong(h, -20) & 0x80) != 0) return true;              // WS_EX_TOOLWINDOW
+      int cloaked = 0;
+      if (DwmGetWindowAttribute(h, 14, out cloaked, 4) == 0 && cloaked != 0) return true; // hidden store apps
+      StringBuilder sb = new StringBuilder(len + 1); GetWindowText(h, sb, sb.Capacity);
+      RECT r; GetWindowRect(h, out r);
+      uint pid; GetWindowThreadProcessId(h, out pid);
+      Win w = new Win(); w.Id = h.ToInt64(); w.Title = sb.ToString(); w.Pid = pid; w.Minimized = IsIconic(h); w.W = r.R - r.L; w.H = r.B - r.T;
+      if (!w.Minimized && (w.W <= 1 || w.H <= 1)) return true;
+      list.Add(w);
+      return true;
+    }, IntPtr.Zero);
+    return list;
+  }
+  public static Rectangle[] Monitors() {
+    List<Rectangle> m = new List<Rectangle>();
+    EnumDisplayMonitors(IntPtr.Zero, IntPtr.Zero, delegate(IntPtr hm, IntPtr dc, ref RECT r, IntPtr l) { m.Add(Rectangle.FromLTRB(r.L, r.T, r.R, r.B)); return true; }, IntPtr.Zero);
+    return m.ToArray();
+  }
+  public static Bitmap Screen(int monitor) {
+    Rectangle[] mons = Monitors();
+    Rectangle b;
+    if (monitor > 0) { if (monitor > mons.Length) return null; b = mons[monitor - 1]; }
+    else { b = mons.Length > 0 ? mons[0] : Rectangle.Empty; foreach (Rectangle x in mons) b = Rectangle.Union(b, x); }
+    if (b.Width <= 0 || b.Height <= 0) return null;
+    Bitmap bmp = new Bitmap(b.Width, b.Height, PixelFormat.Format32bppArgb);
+    using (Graphics g = Graphics.FromImage(bmp)) { g.Clear(Color.Black); g.CopyFromScreen(b.Left, b.Top, 0, 0, b.Size, CopyPixelOperation.SourceCopy); }
+    return bmp;
+  }
+  public static bool IsMinimized(long id) { return IsIconic(new IntPtr(id)); }
+  public static uint Owner(long id) { uint pid; GetWindowThreadProcessId(new IntPtr(id), out pid); return pid; }
+  public static bool Exists(long id) { IntPtr h = new IntPtr(id); return IsWindow(h) && IsWindowVisible(h); }
+  // PrintWindow with PW_RENDERFULLCONTENT: the window's own picture, also when other windows cover it.
+  // Cropped to the visible frame (without the invisible resize borders).
+  public static Bitmap Window(long id) {
+    IntPtr h = new IntPtr(id);
+    RECT r; if (!GetWindowRect(h, out r)) return null;
+    int w = r.R - r.L, ht = r.B - r.T;
+    if (w <= 1 || ht <= 1) return null;
+    Bitmap full = new Bitmap(w, ht, PixelFormat.Format32bppArgb);
+    using (Graphics g = Graphics.FromImage(full)) {
+      IntPtr hdc = g.GetHdc();
+      bool ok;
+      try { ok = PrintWindow(h, hdc, 2); } finally { g.ReleaseHdc(hdc); }
+      if (!ok) { full.Dispose(); return null; }
+    }
+    RECT f;
+    if (DwmGetWindowAttribute(h, 9, out f, Marshal.SizeOf(typeof(RECT))) == 0) {
+      Rectangle c = Rectangle.Intersect(new Rectangle(f.L - r.L, f.T - r.T, f.R - f.L, f.B - f.T), new Rectangle(0, 0, w, ht));
+      if (c.Width > 1 && c.Height > 1 && (c.Width < w || c.Height < ht)) { Bitmap crop = full.Clone(c, full.PixelFormat); full.Dispose(); return crop; }
+    }
+    return full;
+  }
+  public static Bitmap Scale(Bitmap src, double k) {
+    int w = Math.Max(1, (int)Math.Round(src.Width * k)), h = Math.Max(1, (int)Math.Round(src.Height * k));
+    Bitmap dst = new Bitmap(w, h, PixelFormat.Format24bppRgb);
+    using (Graphics g = Graphics.FromImage(dst)) { g.InterpolationMode = InterpolationMode.HighQualityBicubic; g.PixelOffsetMode = PixelOffsetMode.HighQuality; g.DrawImage(src, 0, 0, w, h); }
+    return dst;
+  }
+  static ImageCodecInfo Jpeg() { foreach (ImageCodecInfo c in ImageCodecInfo.GetImageEncoders()) if (c.MimeType == "image/jpeg") return c; return null; }
+  public static byte[] ToJpeg(Bitmap b, long quality) {
+    using (MemoryStream ms = new MemoryStream()) {
+      EncoderParameters p = new EncoderParameters(1); p.Param[0] = new EncoderParameter(System.Drawing.Imaging.Encoder.Quality, quality);
+      b.Save(ms, Jpeg(), p); return ms.ToArray();
+    }
+  }
+  // Long side <= maxSide, then lower quality / size until it fits maxBytes.
+  public class Packed { public byte[] Data; public int W, H; public long Quality; }
+  public static Packed Pack(Bitmap src, int maxSide, int maxBytes) {
+    double k = Math.Min(1.0, (double)maxSide / Math.Max(src.Width, src.Height));
+    long[] qs = new long[] { 80, 65, 50 };
+    for (int round = 0; round < 6; round++) {
+      using (Bitmap s = Scale(src, k)) {
+        foreach (long q in qs) {
+          byte[] d = ToJpeg(s, q);
+          if (d.Length <= maxBytes) { Packed p = new Packed(); p.Data = d; p.W = s.Width; p.H = s.Height; p.Quality = q; return p; }
+        }
+      }
+      k *= 0.75;
+    }
+    return null;
+  }
+  // A NEW file only (CreateNew): never overwrites, also when the name was taken a moment ago.
+  public static void Save(Bitmap b, string path) {
+    string ext = Path.GetExtension(path).ToLowerInvariant();
+    byte[] data = ext == ".png" ? ToPng(b) : ToJpeg(b, 90);
+    FileStream f = new FileStream(path, FileMode.CreateNew, FileAccess.Write, FileShare.None);
+    try { f.Write(data, 0, data.Length); f.Dispose(); }
+    catch (Exception) { f.Dispose(); try { File.Delete(path); } catch (Exception) { } throw; }
+  }
+  public static byte[] ToPng(Bitmap b) { using (MemoryStream ms = new MemoryStream()) { b.Save(ms, ImageFormat.Png); return ms.ToArray(); } }
+}
+'@
+
+# --- OCR (Windows.Media.Ocr, WinRT from PowerShell 5.1) ---------------------------------------
+function Get-Await {
+  Add-Type -AssemblyName System.Runtime.WindowsRuntime
+  $script:AsTaskOp = [System.WindowsRuntimeSystemExtensions].GetMethods() | Where-Object { $_.Name -eq 'AsTask' -and $_.GetParameters().Count -eq 1 -and $_.GetParameters()[0].ParameterType.Name -eq 'IAsyncOperation`1' } | Select-Object -First 1
+}
+function Await($op, [Type]$type) {
+  $task = $script:AsTaskOp.MakeGenericMethod($type).Invoke($null, @($op))
+  [void]$task.Wait(-1)
+  $task.Result
+}
+function Get-OcrLanguages {
+  [void][Windows.Media.Ocr.OcrEngine, Windows.Foundation, ContentType = WindowsRuntime]
+  @([Windows.Media.Ocr.OcrEngine]::AvailableRecognizerLanguages | ForEach-Object { $_.LanguageTag })
+}
+function Invoke-Ocr([byte[]]$bytes, [string]$lang) {
+  Get-Await
+  [void][Windows.Media.Ocr.OcrEngine, Windows.Foundation, ContentType = WindowsRuntime]
+  [void][Windows.Graphics.Imaging.BitmapDecoder, Windows.Foundation, ContentType = WindowsRuntime]
+  [void][Windows.Graphics.Imaging.SoftwareBitmap, Windows.Foundation, ContentType = WindowsRuntime]
+  [void][Windows.Storage.Streams.IRandomAccessStream, Windows.Foundation, ContentType = WindowsRuntime]
+  $langs = @(Get-OcrLanguages)                     # @(): one language must stay a list, not a string
+  if (-not $langs.Count) { Fail 'NO_OCR_LANG' 'No text recognition language is installed in Windows.' }
+  if ($lang) {
+    $hit = $langs | Where-Object { $_ -ieq $lang -or $_ -ilike "$lang-*" } | Select-Object -First 1
+    if (-not $hit) { Fail 'BAD_LANG' "Text recognition for ""$lang"" is not installed." @{ languages = $langs } }
+    $engine = [Windows.Media.Ocr.OcrEngine]::TryCreateFromLanguage([Windows.Globalization.Language]::new($hit))
+  } else {
+    $engine = [Windows.Media.Ocr.OcrEngine]::TryCreateFromUserProfileLanguages()
+    if (-not $engine) { $engine = [Windows.Media.Ocr.OcrEngine]::TryCreateFromLanguage([Windows.Globalization.Language]::new($langs[0])) }
+  }
+  if (-not $engine) { Fail 'NO_OCR_LANG' 'Text recognition could not start for the installed languages.' @{ languages = $langs } }
+  $ms = New-Object IO.MemoryStream (, $bytes)
+  $stream = [System.IO.WindowsRuntimeStreamExtensions]::AsRandomAccessStream($ms)
+  try {
+    $decoder = Await ([Windows.Graphics.Imaging.BitmapDecoder]::CreateAsync($stream)) ([Windows.Graphics.Imaging.BitmapDecoder])
+  } catch { Fail 'BAD_IMAGE' 'This file is not an image Windows can read (PNG, JPEG, BMP, GIF or TIFF).' }
+  $max = [Windows.Media.Ocr.OcrEngine]::MaxImageDimension
+  if ($decoder.PixelWidth -gt $max -or $decoder.PixelHeight -gt $max) { Fail 'IMAGE_TOO_LARGE' "The image is larger than $max pixels on a side." }
+  $bitmap = Await ($decoder.GetSoftwareBitmapAsync()) ([Windows.Graphics.Imaging.SoftwareBitmap])
+  $res = Await ($engine.RecognizeAsync($bitmap)) ([Windows.Media.Ocr.OcrResult])
+  @{ language = $engine.RecognizerLanguage.LanguageTag; lines = @($res.Lines | ForEach-Object { $_.Text }); width = [int]$decoder.PixelWidth; height = [int]$decoder.PixelHeight }
+}
+# Text recognition works best on the full-size picture; above the engine's limit it is scaled down.
+function Get-OcrBytes($bmp) {
+  [void][Windows.Media.Ocr.OcrEngine, Windows.Foundation, ContentType = WindowsRuntime]
+  $max = [Windows.Media.Ocr.OcrEngine]::MaxImageDimension
+  $side = [Math]::Max($bmp.Width, $bmp.Height)
+  if ($side -gt $max) { $s = [BrShot]::Scale($bmp, ($max - 1) / $side); try { return , [BrShot]::ToPng($s) } finally { $s.Dispose() } }
+  , [BrShot]::ToPng($bmp)
+}
+
+try {
+  [BrShot]::Dpi()
+  $action = $env:BRX_ACTION
+  if ($action -eq 'langs') { Out-Json @{ ok = $true; languages = @(Get-OcrLanguages) }; exit 0 }
+  if ($action -eq 'ocr' -and $env:BRX_FILE) {
+    $r = Invoke-Ocr ([IO.File]::ReadAllBytes($env:BRX_FILE)) $env:BRX_LANG
+    Out-Json (@{ ok = $true; kind = 'file' } + $r); exit 0
+  }
+  if (([BrShot]::InputDesktop()) -ne 'Default') { Fail 'SCREEN_LOCKED' 'The screen is locked, signed out or showing a Windows security prompt.' }
+  if ($action -eq 'windows') {
+    $wins = @([BrShot]::Windows() | ForEach-Object {
+      $p = ''; try { $p = (Get-Process -Id $_.Pid -ErrorAction Stop).ProcessName } catch { }
+      @{ id = $_.Id; pid = [int64]$_.Pid; title = $_.Title; process = $p; minimized = $_.Minimized; width = $_.W; height = $_.H } })
+    Out-Json @{ ok = $true; windows = $wins }; exit 0
+  }
+  if ($action -ne 'capture' -and $action -ne 'ocr') { Fail 'BAD_ACTION' "Unknown action $action." }
+  $hwnd = [long]('0' + $env:BRX_HWND)
+  $monitor = [int]('0' + $env:BRX_MONITOR)
+  $minimized = $false
+  if ($hwnd) {
+    if (-not [BrShot]::Exists($hwnd)) { Fail 'NO_WINDOW' 'That window is not open any more.' }
+    # The id was looked up in an earlier run: it must still belong to the same program (ids are reused).
+    if ($env:BRX_PID -and [string][BrShot]::Owner($hwnd) -ne $env:BRX_PID) { Fail 'NO_WINDOW' 'That window closed meanwhile.' }
+    $minimized = [BrShot]::IsMinimized($hwnd)
+    $bmp = [BrShot]::Window($hwnd)
+    $kind = 'window'
+  } else {
+    $count = ([BrShot]::Monitors()).Count
+    if ($monitor -gt $count) { Fail 'NO_MONITOR' "There is no monitor $monitor (this PC has $count)." @{ monitors = $count } }
+    try { $bmp = [BrShot]::Screen($monitor) } catch { Fail 'SCREEN_LOCKED' 'Windows gave no picture of the screen (locked, or a remote session without a display).' }
+    $kind = $(if ($monitor) { 'monitor' } else { 'screen' })
+  }
+  if (-not $bmp) { Fail 'CAPTURE_FAILED' 'Windows could not take the picture.' }
+  $script:taken = $true
+  try {
+    $out = @{ ok = $true; kind = $kind; width = $bmp.Width; height = $bmp.Height; minimized = $minimized }
+    if ($action -eq 'ocr') {
+      $r = Invoke-Ocr (Get-OcrBytes $bmp) $env:BRX_LANG
+      $out.language = $r.language; $out.lines = $r.lines
+    }
+    if ($env:BRX_IMAGE -eq '1') {
+      $p = [BrShot]::Pack($bmp, [int]$env:BRX_MAXSIDE, [int]$env:BRX_MAXBYTES)
+      if (-not $p) { Fail 'IMAGE_TOO_LARGE' 'The picture could not be made small enough.' }
+      $out.mime = 'image/jpeg'; $out.data = [Convert]::ToBase64String($p.Data); $out.outWidth = $p.W; $out.outHeight = $p.H; $out.bytes = $p.Data.Length
+    }
+    # The full-size copy last: no file is left on disk when an earlier step failed.
+    if ($env:BRX_SAVE) {
+      try { [BrShot]::Save($bmp, $env:BRX_SAVE) } catch {
+        $h = $_.Exception.HResult; if ($_.Exception.InnerException) { $h = $_.Exception.InnerException.HResult }
+        if ($h -eq -2147024816 -or $h -eq -2147024713) { Fail 'EXISTS' 'A file with this name appeared meanwhile; nothing was overwritten.' }
+        throw
+      }
+      $out.saved = $env:BRX_SAVE
+    }
+    Out-Json $out
+  } finally { $bmp.Dispose() }
+} catch {
+  Out-Json @{ ok = $false; code = 'PS_ERROR'; message = [string]$_.Exception.Message; taken = [bool]$script:taken }
+}