@bivy/bivy 0.17.3-staging.29 → 0.17.3-staging.30

package/bin/bivy.mjs

@@ -2434,6 +2434,12 @@ async function cmdApp(args = []) {
        bivy app present [view] [--path /page] [--note "…"] [--session <id>]
        bivy app share [app-id] [--view <view>] [--session <id>]
        bivy app run [--name <name>] [--restart-on-change] [--session <id>] -- <command> [args…]
+       bivy app click <x> <y> [--right|--middle] [--double] [--app <app>]
+       bivy app type <text> [--app <app>]
+       bivy app key <keys> [--app <app>]            e.g. enter, cmd+s, ctrl+shift+t
+       bivy app scroll <x> <y> [--up|--down|--left|--right] [--steps <n>] [--app <app>]
+       bivy app drag <x> <y> <to-x> <to-y> [--app <app>]
+       bivy app move <x> <y> [--app <app>]
 
 Manifest: {"version":1,"name":"My app","views":[
   {"kind":"web","name":"Website","source":{"kind":"service","port":3000}},
@@ -2442,9 +2448,10 @@ Manifest: {"version":1,"name":"My app","views":[
 
 Static web source: {"kind":"static","directory":"./dist"}
 Server Bivy runs: {"kind":"service","port":5173,"start":{"command":"pnpm","args":["dev"]}}
-Desktop GUI app (Linux, needs TigerVNC's Xvnc):
+Desktop GUI app (Linux with TigerVNC's Xvnc, or macOS 13+):
   {"kind":"display","name":"Editor","command":"cargo","args":["run"],"restartOnChange":true}
-  It runs on a private display streamed into the preview, sized to the viewer.
+  It runs on a private display (Linux) or shows its own windows (macOS),
+  streamed into the preview and sized to the viewer.
   "restartOnChange" restarts it after a turn that changed files. Shortcut with
   no manifest: bivy app run -- cargo run
 Publishing does not start commands. Open Apps in the session menu to view or run;
@@ -2455,6 +2462,13 @@ Terminal commands run with the node user's permissions, not in a new sandbox.
 Chrome/Chromium (desktop apps: straight from their display) and prints the PNG paths — look at them before saying the UI is
 done. It is off by default: turn it on in Bivy → Settings → this machine, or
 run: bivy config set sessions.appScreenshots true
+click/type/key/scroll/drag/move use a desktop app like a person would, in the
+pixels of its screenshot (bivy app shot), and print a new screenshot after
+(when screenshots are on) — look at it to see what happened. --app picks the
+app (default: the one opened last). Keys: a character or enter, tab, escape,
+backspace, delete, arrows (up…), home, end, pageup, pagedown, f1–f12, with
+modifiers shift, ctrl, alt/option, cmd. On a Mac, the pointer and keyboard
+focus move to the app while it's used.
 "present" says a change is ready for the user to look at: they get a card in
 the chat with the app at phone width (and before/after), and it opens the live
 preview. Use it when you finish a visible change, or when the user asks to see
@@ -2468,6 +2482,7 @@ who can read it may use the app.
 Web previews require operator setup; see docs/apps.md.`);
     return;
   }
+  if (INPUT_ACTIONS[action]) return appInput(action, rest);
   if (!["publish", "list", "remove", "shot", "run", "present", "share"].includes(action)) throw new Error("Unknown app command. Run bivy app --help.");
   // `run -- <command> [args…]`: publish a one-window desktop app without a manifest file.
   let runManifest;
@@ -2528,10 +2543,14 @@ Web previews require operator setup; see docs/apps.md.`);
     body.manifest = manifest;
   } else if (action === "run") body.manifest = runManifest;
   else if (action === "remove") body.appId = positional[0];
+  await appRequest(action === "run" ? "publish" : action, body);
+}
+
+async function appRequest(action, body) {
   const config = loadConfig();
   if (!(await ensureNodeRunning(config))) throw new Error("Could not reach the Bivy node.");
   const token = await localDeviceToken(config);
-  const response = await fetch(`${url(config)}/api/apps/${action === "run" ? "publish" : action}`, {
+  const response = await fetch(`${url(config)}/api/apps/${action}`, {
     method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify(body),
   });
   const result = await response.json();
@@ -2545,6 +2564,38 @@ Web previews require operator setup; see docs/apps.md.`);
   console.log(JSON.stringify(result, null, 2));
 }
 
+// Computer use in desktop apps: each command's positional arguments, and the
+// flags that shape its action. The node validates the action.
+const INPUT_ACTIONS = {
+  click: { args: ["x", "y"], flags: { "--right": { button: "right" }, "--middle": { button: "middle" }, "--double": { count: 2 } } },
+  move: { args: ["x", "y"], flags: {} },
+  drag: { args: ["x", "y", "toX", "toY"], flags: {} },
+  scroll: { args: ["x", "y"], flags: { "--up": { direction: "up" }, "--down": { direction: "down" }, "--left": { direction: "left" }, "--right": { direction: "right" } }, defaults: { direction: "down" }, values: { "--steps": "steps" } },
+  type: { args: ["text"], flags: {}, text: true },
+  key: { args: ["keys"], flags: {}, text: true },
+};
+async function appInput(kind, rest) {
+  const spec = INPUT_ACTIONS[kind];
+  const action = { kind, ...spec.defaults };
+  const options = {};
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (spec.flags[arg]) Object.assign(action, spec.flags[arg]);
+    else if (arg === "--app" || arg === "--session" || spec.values?.[arg]) {
+      const value = rest[++i];
+      if (value === undefined || value.startsWith("--")) throw new Error(`${arg} requires a value.`);
+      if (spec.values?.[arg]) action[spec.values[arg]] = Number(value); else options[arg] = value;
+    } else if (arg.startsWith("--")) throw new Error(`Unknown option ${arg}. Run bivy app --help.`);
+    else positional.push(arg);
+  }
+  if (positional.length !== spec.args.length) throw new Error(`Usage: bivy app ${kind} ${spec.args.map((name) => `<${name}>`).join(" ")}. Run bivy app --help.`);
+  spec.args.forEach((name, i) => { action[name] = spec.text ? positional[i] : Number(positional[i]); });
+  const sessionId = resolveAttachSessionId({ sessionFlag: options["--session"], env: process.env });
+  if (!sessionId) throw new Error("Set --session <id> or run inside a Bivy agent session.");
+  await appRequest("input", { sessionId, action, ...(options["--app"] ? { target: options["--app"] } : {}) });
+}
+
 // Map a saved session's runtime id to the `bivy run` agent whose native CLI can
 // resume it in a terminal. Only agents with a real native resume qualify; other
 // runtimes (generic-cli, SDK-only) have no terminal resume and open in the web app.

package/dist/apps/display-viewer.js

@@ -3,12 +3,15 @@
 export const DISPLAY_SOCKET_PATH = "/__bivy/display";
 export const DISPLAY_STATS_PATH = "/__bivy/display-stats";
 export const NOVNC_PATH = "/__bivy/novnc/";
+/** The modifier apps paste with, as a keysym and noVNC key code: ⌘ on a Mac. */
+const PASTE_MODIFIER = { darwin: [0xffeb, "MetaLeft"] };
 /** The page a display view serves on its own origin: noVNC's client streaming
  * the app's display. It asks the display to match its size in device pixels
  * (`scale` is what the display was started at), scales down when the display
  * is larger, reconnects while the app starts, carries the clipboard both ways
  * on a tap, gives phones a keyboard, and reports stream latency to Bivy. */
-export function displayViewer(nonce, name, scale) {
+export function displayViewer(nonce, name, scale, platform = process.platform) {
+    const [modifier, modifierCode] = PASTE_MODIFIER[platform] ?? [0xffe3, "ControlLeft"];
     const title = name.replace(/[<>&"]/g, (c) => `&#${c.charCodeAt(0)};`);
     return `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1, interactive-widget=resizes-content"><title>${title}</title>
 <style nonce="${nonce}">:root{color-scheme:light dark;font-family:system-ui,sans-serif}html,body{margin:0;height:100%;overflow:hidden;background:Canvas;color:CanvasText}
@@ -62,8 +65,8 @@ function connect(){
 connect();
 
 $("copy").onclick=async()=>{try{await navigator.clipboard.writeText(remote);$("copy").textContent="Copied";setTimeout(()=>{$("copy").hidden=true;},1500);}catch{$("copy").textContent="Couldn’t copy";}};
-// Paste: hand the text to the app's clipboard, then press Ctrl+V in it.
-const paste=text=>{if(!text)return;rfb.clipboardPasteFrom(text);rfb.sendKey(0xffe3,"ControlLeft",true);rfb.sendKey(0x76,"KeyV");rfb.sendKey(0xffe3,"ControlLeft",false);rfb.focus();};
+// Paste: hand the text to the app's clipboard, then press Ctrl+V (⌘V on a Mac) in it.
+const paste=text=>{if(!text)return;rfb.clipboardPasteFrom(text);rfb.sendKey(${modifier},"${modifierCode}",true);rfb.sendKey(0x76,"KeyV");rfb.sendKey(${modifier},"${modifierCode}",false);rfb.focus();};
 $("paste-open").onclick=async()=>{
   try{const text=await navigator.clipboard.readText();if(text){paste(text);return;}}catch{}
   // No clipboard access here: paste into a field instead.

package/dist/apps/display.js

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawn, execFileSync } from "node:child_process";
 import { FitWindowManager, writeXauthority } from "./x11.js";
+import { MacDisplayHost } from "./macos-display.js";
 /** Environment for programs on a preview display. X11 for every toolkit, so an
  * app never escapes to the machine's own Wayland/X session. */
 const APP_ENV = {
@@ -48,7 +49,7 @@ export class DisplayHost {
     /** Why desktop views can't run here, or undefined when they can. */
     unavailable() {
         if ((this.options.platform ?? process.platform) !== "linux")
-            return "Desktop app views need a Linux machine for now.";
+            return "Desktop app views need a Linux or macOS machine.";
         if (!(this.options.xvnc ?? findXvnc)())
             return "Desktop app views need TigerVNC's X server. Install it (Debian/Ubuntu: sudo apt install tigervnc-standalone-server), or set BIVY_XVNC to its path.";
         return undefined;
@@ -133,3 +134,12 @@ function freeDisplay(x11Dir) {
     }
     throw new Error("No free X display number.");
 }
+/** How each platform gives a desktop app a preview display: a private X
+ * server on Linux, the app's own windows on a Mac. Both serve VNC on a
+ * private socket, so everything downstream is shared. */
+const HOSTS = {
+    darwin: (dataDir) => new MacDisplayHost({ cacheDir: path.join(dataDir, "bin") }),
+};
+export function createDisplayHost(dataDir, platform = process.platform) {
+    return HOSTS[platform]?.(dataDir) ?? new DisplayHost({ platform });
+}

package/dist/apps/gateway.js

@@ -2,7 +2,8 @@
 // Copyright (c) 2026 Petter André Sjulstad
 import http from "node:http";
 import net from "node:net";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
+import { gzipSync } from "node:zlib";
 import path from "node:path";
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
@@ -50,6 +51,47 @@ function allowInspector(policy, url) {
     }
     return directives.join("; ");
 }
+/** Text-like types that shrink well; images and fonts are compressed already. */
+const COMPRESSIBLE = /^(?:text\/|application\/(?:json|javascript|xml|wasm)|image\/svg\+xml)/i;
+/** Snapshot and noVNC buffers never change, so validators and gzip copies are made once. */
+const encodings = new WeakMap();
+function encoded(data, type) {
+    let entry = encodings.get(data);
+    if (!entry) {
+        // Weak: the identity and gzip bodies share it.
+        entry = { etag: `W/"${createHash("sha256").update(data).digest("base64url").slice(0, 27)}"` };
+        if (data.length >= 1024 && COMPRESSIBLE.test(type)) {
+            const gzip = gzipSync(data);
+            if (gzip.length < data.length)
+                entry.gzip = gzip;
+        }
+        encodings.set(data, entry);
+    }
+    return entry;
+}
+/** Serves fixed bytes with a validator (304 on a match) and gzip when the browser takes it. */
+function sendBytes(req, res, status, headers, data) {
+    const file = encoded(data, String(headers["content-type"] ?? ""));
+    headers.etag = file.etag;
+    headers.vary = "Accept-Encoding";
+    if (status === 200 && (req.headers["if-none-match"] ?? "").split(",").some((tag) => tag.trim() === file.etag)) {
+        res.writeHead(304, headers);
+        res.end();
+        return;
+    }
+    const gzip = file.gzip && /\bgzip\b/i.test(req.headers["accept-encoding"] ?? "") ? file.gzip : undefined;
+    if (gzip)
+        headers["content-encoding"] = "gzip";
+    const body = gzip ?? data;
+    res.writeHead(status, { ...headers, "content-length": body.length });
+    res.end(req.method === "HEAD" ? undefined : body);
+}
+/** App content may sit in the browser's own cache, never a shared one, and is
+ * revalidated on every use whatever the app says: a preview must show what the
+ * agent just built. The app's validators still turn unchanged files into 304s. */
+function privateCache(policy) {
+    return /\bno-store\b/i.test(policy ?? "") ? "no-store" : "private, no-cache";
+}
 const HOUR = 60 * 60_000;
 /** A viewer that stops reading doesn't make the node buffer the display. */
 const DISPLAY_BUFFER_BYTES = 4 * 1024 * 1024;
@@ -125,8 +167,8 @@ function responseHeaders(headers, ancestors, inspector) {
             .map((cookie) => cookie.replace(/;\s*domain=[^;]*/ig, ""));
     }
     // Preview data must not become a shared proxy cache entry. Apps cannot frame
-    // Bivy, retain an opener, or cache an offline service-worker copy of the gate.
-    result["cache-control"] = "no-store";
+    // Bivy or retain an opener; service workers are refused (see handle).
+    result["cache-control"] = privateCache(headers["cache-control"]);
     result["referrer-policy"] = "no-referrer";
     result["cross-origin-opener-policy"] = "same-origin";
     result["x-content-type-options"] = "nosniff";
@@ -474,8 +516,7 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
             headers["content-type"] = MIME[path.extname(file).toLowerCase()] || "application/octet-stream";
             if (inspect && path.extname(file).toLowerCase() === ".html" && data.length <= MAX_INJECT_BYTES)
                 data = withInspector(data);
-            res.writeHead(status, { ...headers, "content-length": data.length });
-            res.end(req.method === "HEAD" ? undefined : data);
+            sendBytes(req, res, status, headers, data);
             return;
         }
         if (entry.target.kind !== "service") {
@@ -573,8 +614,7 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
                 res.end();
                 return;
             }
-            res.writeHead(200, { ...responseHeaders({}, this.ancestors(id)), "content-type": "text/javascript; charset=utf-8", "content-length": data.length });
-            res.end(req.method === "HEAD" ? undefined : data);
+            sendBytes(req, res, 200, { ...responseHeaders({}, this.ancestors(id)), "content-type": "text/javascript; charset=utf-8" }, data);
             return;
         }
         if (!isPageLoad(req)) {

package/dist/apps/input.js

@@ -0,0 +1,96 @@
+/** VNC button-mask bits: buttons, then the wheel's four directions. */
+const BUTTONS = { left: 1, middle: 2, right: 4 };
+const WHEEL = { up: 8, down: 16, left: 32, right: 64 };
+/** X keysyms by name. Super is ⌘ on a Mac. */
+const MODIFIERS = {
+    shift: 0xffe1, ctrl: 0xffe3, control: 0xffe3, alt: 0xffe9, option: 0xffe9, opt: 0xffe9,
+    cmd: 0xffeb, command: 0xffeb, super: 0xffeb, meta: 0xffeb, win: 0xffeb,
+};
+const KEYS = {
+    enter: 0xff0d, return: 0xff0d, tab: 0xff09, escape: 0xff1b, esc: 0xff1b, backspace: 0xff08, delete: 0xffff, insert: 0xff63,
+    home: 0xff50, end: 0xff57, pageup: 0xff55, pagedown: 0xff56, left: 0xff51, up: 0xff52, right: 0xff53, down: 0xff54,
+    space: 0x20, plus: 0x2b, ...Object.fromEntries(Array.from({ length: 12 }, (_, i) => [`f${i + 1}`, 0xffbe + i])),
+};
+/** Characters typed as keys rather than as text. */
+const TYPED = { "\n": KEYS.enter, "\t": KEYS.tab };
+const PAUSE = 30;
+const keysym = (char) => { const cp = char.codePointAt(0); return cp <= 0xff ? cp : 0x0100_0000 + cp; };
+const press = (sym) => [{ key: { keysym: sym, down: true } }, { key: { keysym: sym, down: false } }];
+/** "cmd+shift+s", "ctrl+c", "enter": modifiers held around one key. */
+function combo(keys) {
+    const parts = keys.toLowerCase().split("+").map((part) => part.trim());
+    const key = parts.pop();
+    const held = parts.map((part) => {
+        const sym = MODIFIERS[part];
+        if (sym === undefined)
+            throw new Error(`Unknown modifier "${part}". Use ${[...new Set(Object.keys(MODIFIERS))].join(", ")}.`);
+        return sym;
+    });
+    // A letter with Shift is its capital, as a keyboard sends it.
+    const char = [...key].length === 1 ? (held.includes(MODIFIERS.shift) ? key.toUpperCase() : key) : undefined;
+    const sym = KEYS[key] ?? MODIFIERS[key] ?? (char && keysym(char));
+    if (!sym)
+        throw new Error(`Unknown key "${key}". Use a character or ${Object.keys(KEYS).join(", ")}.`);
+    return [...held.map((s) => ({ key: { keysym: s, down: true } })), ...press(sym), ...held.reverse().map((s) => ({ key: { keysym: s, down: false } }))];
+}
+const point = (n) => Number.isInteger(n) && n >= 0 && n < 65536;
+/** Checks an action from the command line or API. */
+export function readAction(input) {
+    const a = (input ?? {});
+    const at = (...keys) => { if (!keys.every((k) => point(a[k])))
+        throw new Error("Coordinates must be whole pixels in the app's screenshot."); };
+    switch (a.kind) {
+        case "click":
+            at("x", "y");
+            if (a.button !== undefined && !(typeof a.button === "string" && a.button in BUTTONS))
+                throw new Error("Button must be left, middle or right.");
+            if (a.count !== undefined && ![1, 2, 3].includes(a.count))
+                throw new Error("Click count must be 1, 2 or 3.");
+            return a;
+        case "move":
+            at("x", "y");
+            return a;
+        case "drag":
+            at("x", "y", "toX", "toY");
+            return a;
+        case "scroll":
+            at("x", "y");
+            if (!(typeof a.direction === "string" && a.direction in WHEEL))
+                throw new Error("Scroll direction must be up, down, left or right.");
+            if (a.steps !== undefined && !(Number.isInteger(a.steps) && a.steps >= 1 && a.steps <= 50))
+                throw new Error("Scroll steps must be 1–50.");
+            return a;
+        case "type":
+            if (typeof a.text !== "string" || !a.text || a.text.length > 2000)
+                throw new Error("Text must be 1–2000 characters.");
+            return a;
+        case "key":
+            if (typeof a.keys !== "string" || !a.keys.trim() || a.keys.length > 100)
+                throw new Error("Keys must name a key, like enter or cmd+s.");
+            combo(a.keys);
+            return a;
+        default: throw new Error("Action must be click, move, drag, scroll, type or key.");
+    }
+}
+/** The pointer and key events that perform an action. */
+export function inputEvents(action) {
+    const at = (x, y, buttons = 0) => ({ pointer: { x, y, buttons } });
+    switch (action.kind) {
+        case "move": return [at(action.x, action.y)];
+        case "click": {
+            const button = BUTTONS[action.button ?? "left"];
+            return [at(action.x, action.y), ...Array.from({ length: action.count ?? 1 }, () => [at(action.x, action.y, button), at(action.x, action.y)]).flat()];
+        }
+        case "drag": {
+            // Through a few points on the way, so apps see a drag, not a jump.
+            const path = Array.from({ length: 8 }, (_, i) => at(Math.round(action.x + (action.toX - action.x) * (i + 1) / 8), Math.round(action.y + (action.toY - action.y) * (i + 1) / 8), 1));
+            return [at(action.x, action.y), at(action.x, action.y, 1), ...path.flatMap((step) => [{ wait: PAUSE }, step]), at(action.toX, action.toY)];
+        }
+        case "scroll": {
+            const bit = WHEEL[action.direction];
+            return [at(action.x, action.y), ...Array.from({ length: action.steps ?? 3 }, () => [at(action.x, action.y, bit), at(action.x, action.y)]).flat()];
+        }
+        case "type": return [...action.text].flatMap((char) => [...press(TYPED[char] ?? keysym(char)), { wait: 5 }]);
+        case "key": return combo(action.keys);
+    }
+}

package/dist/apps/macos-display.js

@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { spawn, execFile, execFileSync } from "node:child_process";
+/** The helper's source ships next to this module; it is compiled on this Mac on first use. */
+const SOURCE = fileURLToPath(new URL("./macos-display.swift", import.meta.url));
+const START_MS = 10_000;
+const BUILD_MS = 5 * 60_000;
+/** Darwin 22 is macOS 13, the first with everything the helper uses. */
+const MIN_DARWIN = 22;
+/** What each missing permission is called in System Settings. */
+const PERMISSIONS = { screenRecording: "Screen Recording", accessibility: "Accessibility" };
+/** Desktop views on macOS. There are no private displays on a Mac, so each
+ * view gets a helper that serves its app's own windows as a VNC display on a
+ * private socket (see macos-display.swift): the same contract as an Xvnc
+ * display, so the viewer, relay, screenshots and input are shared. */
+export class MacDisplayHost {
+    options;
+    displays = new Map();
+    build;
+    checked;
+    prompted = false;
+    constructor(options) {
+        this.options = options;
+    }
+    compiled;
+    get source() { return this.options.source ?? SOURCE; }
+    binary() {
+        this.compiled ??= path.join(this.options.cacheDir, `macos-display-${createHash("sha256").update(fs.readFileSync(this.source)).digest("hex").slice(0, 16)}`);
+        return this.compiled;
+    }
+    /** Why desktop views can't run here, or undefined when they can. */
+    unavailable() {
+        if ((this.options.platform ?? process.platform) !== "darwin")
+            return "This display host runs on macOS only.";
+        if (Number((this.options.release ?? os.release()).split(".")[0]) < MIN_DARWIN)
+            return "Desktop app views need macOS 13 or later.";
+        const binary = this.binary();
+        if (fs.existsSync(binary))
+            return this.missing(binary);
+        if (!(this.options.swiftc ?? hasSwiftc)())
+            return "Desktop app views on macOS need Apple's command line tools to build their helper. Install them with: xcode-select --install";
+        void this.helper().catch(() => { }); // build ahead of the first open
+        return undefined;
+    }
+    /** Permissions the helper lacks, as a message; checked at most every few seconds. */
+    missing(binary) {
+        if (this.checked && Date.now() - this.checked.at < 5_000)
+            return this.checked.missing;
+        let missing;
+        try {
+            const granted = JSON.parse(execFileSync(binary, ["check"], { encoding: "utf8", timeout: 5_000 }));
+            const lacking = Object.keys(PERMISSIONS).filter((key) => !granted[key]).map((key) => PERMISSIONS[key]);
+            if (lacking.length) {
+                missing = `Desktop app views on macOS need ${lacking.join(" and ")} permission. In System Settings → Privacy & Security, allow ${lacking.join(" and ")} for the program that runs Bivy (your terminal app, or ${process.execPath} when Bivy runs in the background), then restart Bivy.`;
+            }
+        }
+        catch {
+            missing = "Couldn't run Bivy's macOS display helper.";
+        }
+        this.checked = { at: Date.now(), missing };
+        return missing;
+    }
+    /** The compiled helper: built once per version of its source, then reused. */
+    helper() {
+        const binary = this.binary();
+        if (fs.existsSync(binary))
+            return Promise.resolve(binary);
+        this.build ??= new Promise((resolve, reject) => {
+            fs.mkdirSync(this.options.cacheDir, { recursive: true, mode: 0o700 });
+            const temp = `${binary}.${process.pid}.tmp`;
+            execFile("xcrun", ["swiftc", "-O", "-swift-version", "5", this.source, "-o", temp], { timeout: BUILD_MS }, (error, _stdout, stderr) => {
+                if (error) {
+                    fs.rmSync(temp, { force: true });
+                    reject(new Error(`Couldn't build Bivy's macOS display helper: ${String(stderr).trim().split("\n").at(-1) ?? error.message}`));
+                    return;
+                }
+                fs.renameSync(temp, binary);
+                for (const old of fs.readdirSync(this.options.cacheDir))
+                    if (old.startsWith("macos-display-") && path.join(this.options.cacheDir, old) !== binary)
+                        fs.rmSync(path.join(this.options.cacheDir, old), { force: true });
+                resolve(binary);
+            });
+        }).finally(() => { this.build = undefined; });
+        return this.build;
+    }
+    running(id) { return this.displays.get(id)?.ready; }
+    /** `scale` (1 or 2) is the pixel density frames are captured at. */
+    ensure(id, _name, scale = 1) {
+        const existing = this.displays.get(id);
+        if (existing)
+            return existing.ready;
+        const state = { dir: fs.mkdtempSync(path.join(os.tmpdir(), "bivy-display-")) };
+        state.ready = this.start(state, scale === 2 ? 2 : 1).then((display) => {
+            state.child.once("exit", () => { if (this.displays.get(id) === state)
+                this.stop(id); });
+            return display;
+        }, (error) => { this.stop(id); throw error; });
+        this.displays.set(id, state);
+        return state.ready;
+    }
+    async start(state, scale) {
+        const reason = this.unavailable();
+        if (reason)
+            throw new Error(reason);
+        const binary = await this.helper();
+        const missing = this.missing(binary);
+        if (missing) {
+            // Once per run, let macOS ask: it lists the program in System Settings.
+            if (!this.prompted) {
+                this.prompted = true;
+                execFile(binary, ["check", "--prompt"], () => { });
+            }
+            throw new Error(missing);
+        }
+        const socket = path.join(state.dir, "vnc.sock");
+        const token = randomBytes(16).toString("hex");
+        const child = spawn(binary, ["serve", socket, token, String(scale)], { stdio: ["ignore", "pipe", "pipe"] });
+        state.child = child;
+        const wm = { count: 0 };
+        let errors = "";
+        child.stderr.on("data", (chunk) => { errors = (errors + chunk).slice(-2000); console.warn(`[apps] macOS display: ${String(chunk).trim()}`); });
+        const up = await new Promise((resolve) => {
+            const timer = setTimeout(() => { child.kill("SIGKILL"); resolve(false); }, START_MS);
+            child.once("exit", () => { clearTimeout(timer); resolve(false); });
+            child.once("error", () => { clearTimeout(timer); resolve(false); });
+            createInterface({ input: child.stdout }).on("line", (line) => {
+                if (line === "ready") {
+                    clearTimeout(timer);
+                    resolve(true);
+                }
+                const windows = /^windows (\d+)$/.exec(line);
+                if (windows)
+                    wm.count = Number(windows[1]);
+            });
+        });
+        if (!up)
+            throw new Error(`Couldn't start a display for this app.${errors ? ` ${errors.trim().split("\n").at(-1)}` : ""}`);
+        return { socket, wm, scale, env: { BIVY_MAC_DISPLAY: token }, launch: [binary, "run", "--"] };
+    }
+    stop(id) {
+        const state = this.displays.get(id);
+        if (!state)
+            return;
+        this.displays.delete(id);
+        state.child?.kill("SIGTERM");
+        fs.rmSync(state.dir, { recursive: true, force: true });
+    }
+    stopAll() { for (const id of [...this.displays.keys()])
+        this.stop(id); }
+}
+let swiftc;
+function hasSwiftc() {
+    if (swiftc === undefined) {
+        try {
+            execFileSync("xcrun", ["--find", "swiftc"], { stdio: "ignore", timeout: 10_000 });
+            swiftc = true;
+        }
+        catch {
+            swiftc = false;
+        }
+    }
+    return swiftc;
+}