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

package/bin/bivy.mjs

@@ -974,7 +974,7 @@ function looksLikeRemote(value) {
 
 function extractRunFlags(args) {
   const rest = [];
-  let name, model, node, workspace;
+  let name, model, node, workspace, bivySession;
   let chat = false;
   let noOpen = false;
   let noFollow = false;
@@ -993,11 +993,14 @@ function extractRunFlags(args) {
     if (a.startsWith("--node=")) { node = a.slice("--node=".length); continue; }
     if (a === "--workspace" && args[i + 1] !== undefined) { workspace = args[++i]; continue; }
     if (a.startsWith("--workspace=")) { workspace = a.slice("--workspace=".length); continue; }
+    // Internal (set by `bivy resume`): the Bivy session this run continues, so
+    // the node can lock that session's chat while the terminal drives it.
+    if (a === "--bivy-session" && args[i + 1] !== undefined) { bivySession = args[++i]; continue; }
     if (a.startsWith("--clone=")) { clone = a.slice("--clone=".length); continue; }
     if (a === "--clone") { clone = looksLikeRemote(args[i + 1]) ? args[++i] : true; continue; }
     rest.push(a);
   }
-  return { name: name?.trim() || undefined, model: model?.trim() || undefined, node: node?.trim() || undefined, workspace: workspace?.trim() || undefined, chat, noOpen, noFollow, clone, rest };
+  return { name: name?.trim() || undefined, model: model?.trim() || undefined, node: node?.trim() || undefined, workspace: workspace?.trim() || undefined, bivySession: bivySession?.trim() || undefined, chat, noOpen, noFollow, clone, rest };
 }
 
 // A safe-ish workspace dir name from a remote or path (basename minus .git).
@@ -1899,7 +1902,7 @@ function governedChatAgentId(id) {
 
 async function cmdRun(args = []) {
   if (!(await ensureDeps())) process.exit(1);
-  const { name, model, node, workspace, chat, noOpen, noFollow, clone, rest } = extractRunFlags(args);
+  const { name, model, node, workspace, bivySession, chat, noOpen, noFollow, clone, rest } = extractRunFlags(args);
   // Bare `bivy` (empty rest) resolves to the configured default agent; an
   // explicit `bivy run <agent>` keeps that agent verbatim.
   const [agentIdArg, ...extraArgs] = rest;
@@ -1999,7 +2002,8 @@ async function cmdRun(args = []) {
   // Pin a session id at launch when the agent's CLI supports it (and the caller
   // didn't already choose one), so the on-disk session is a known, deterministic
   // resume target — the anchor for later "continue as chat" adoption.
-  const pinnedSessionId = pinRunSessionId(agentId, resolved.spec);
+  const pinnedSessionId = bivySession ? undefined : pinRunSessionId(agentId, resolved.spec);
+  if (bivySession) resolved.spec.sessionId = bivySession;
   if (pinnedSessionId) {
     console.log(c.dim(`session id ${pinnedSessionId} — resume in a terminal with '${agentId} --resume ${pinnedSessionId}'`));
   }
@@ -2426,6 +2430,16 @@ async function cmdApp(args = []) {
     console.log(`Usage: bivy app publish <manifest.json> [--session <id>]
        bivy app list [--session <id>]
        bivy app remove <app-id> [--session <id>]
+       bivy app shot [app-id] [--widths 390,1280] [--themes light,dark] [--path /page] [--session <id>]
+       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}},
@@ -2433,19 +2447,89 @@ Manifest: {"version":1,"name":"My app","views":[
 ]}
 
 Static web source: {"kind":"static","directory":"./dist"}
-Publishing does not start commands. Open Apps in the session menu to view or run.
+Server Bivy runs: {"kind":"service","port":5173,"start":{"command":"pnpm","args":["dev"]}}
+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 (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;
+a server with "start" or a desktop app starts on first open and is restarted if
+it exits.
 Terminal commands run with the node user's permissions, not in a new sandbox.
+"shot" screenshots the session's web views (or one app) with a local headless
+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
+it. [view] is an app or view name or ID (default: the one opened last).
+"share" mints a reusable link to one web view and prints its URL and expiry
+(24 hours, or until Revoke access in Apps, the app is removed or the machine
+restarts). [app-id] is an app ID or name, --view a view ID or name (default: the
+one opened last). Anyone who has the link can use the app, including a live
+server's backend, until it expires or is revoked: only post it where everyone
+who can read it may use the app.
 Web previews require operator setup; see docs/apps.md.`);
     return;
   }
-  if (!["publish", "list", "remove"].includes(action)) throw new Error("Unknown app command. Run bivy app --help.");
+  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;
+  if (action === "run") {
+    const split = rest.indexOf("--");
+    if (split < 0 || !rest[split + 1]) throw new Error("Usage: bivy app run [--name <name>] [--restart-on-change] -- <command> [args…]");
+    const [command, ...commandArgs] = rest.splice(split).slice(1);
+    const nameIndex = rest.indexOf("--name");
+    const name = nameIndex >= 0 ? rest.splice(nameIndex, 2)[1] : path.basename(command);
+    if (!name) throw new Error("--name requires a value.");
+    const restartIndex = rest.indexOf("--restart-on-change");
+    if (restartIndex >= 0) rest.splice(restartIndex, 1);
+    runManifest = { version: 1, name: name.slice(0, 100), views: [{ kind: "display", name: "Window", command, args: commandArgs, ...(restartIndex >= 0 ? { restartOnChange: true } : {}) }] };
+  }
+  const shot = {};
+  if (action === "share") {
+    const i = rest.indexOf("--view");
+    if (i >= 0) {
+      const value = rest[i + 1];
+      if (!value || value.startsWith("--")) throw new Error("--view requires a view ID or name.");
+      shot.view = value;
+      rest.splice(i, 2);
+    }
+  }
+  if (action === "shot" || action === "present") {
+    for (const flag of action === "shot" ? ["--widths", "--themes", "--path"] : ["--path", "--note"]) {
+      const i = rest.indexOf(flag);
+      if (i < 0) continue;
+      const value = rest[i + 1];
+      if (!value || value.startsWith("--")) throw new Error(`${flag} requires a value.`);
+      if (flag === "--widths") shot.widths = value.split(",").map((w) => Number(w.trim()));
+      else if (flag === "--themes") shot.themes = value.split(",").map((t) => t.trim());
+      else if (flag === "--note") shot.note = value;
+      else shot.path = value;
+      rest.splice(i, 2);
+    }
+  }
   const sessionIndex = rest.indexOf("--session");
   if (sessionIndex >= 0 && (!rest[sessionIndex + 1] || rest[sessionIndex + 1].startsWith("--"))) throw new Error("--session requires an id.");
   const sessionId = resolveAttachSessionId({ sessionFlag: sessionIndex >= 0 ? rest[sessionIndex + 1] : undefined, env: process.env });
   if (!sessionId) throw new Error("Set --session <id> or run inside a Bivy agent session.");
   const positional = rest.filter((_, i) => i !== sessionIndex && (sessionIndex < 0 || i !== sessionIndex + 1));
-  if (positional.some((a) => a.startsWith("-")) || positional.length !== (action === "list" ? 0 : 1)) throw new Error("Invalid arguments. Run bivy app --help.");
-  const body = { sessionId };
+  if (positional.some((a) => a.startsWith("-")) || (action === "shot" || action === "present" || action === "share" ? positional.length > 1 : positional.length !== (action === "list" || action === "run" ? 0 : 1))) throw new Error("Invalid arguments. Run bivy app --help.");
+  const body = { sessionId, ...shot };
+  if (action === "shot" && positional[0]) body.appId = positional[0];
+  if (action === "present" && positional[0]) body.target = positional[0];
+  if (action === "share" && positional[0]) body.appId = positional[0];
   if (action === "publish") {
     const file = path.resolve(positional[0]);
     if (fs.statSync(file).size > 64 * 1024) throw new Error("App manifest exceeds 64 KiB.");
@@ -2457,7 +2541,12 @@ Web previews require operator setup; see docs/apps.md.`);
       }
     }
     body.manifest = manifest;
-  } else if (action === "remove") body.appId = positional[0];
+  } 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);
@@ -2466,9 +2555,47 @@ Web previews require operator setup; see docs/apps.md.`);
   });
   const result = await response.json();
   if (!response.ok || result.error) throw new Error(result.error || `App command failed (${response.status}).`);
+  if (action === "share") {
+    const { type: _type, requestId: _requestId, ...link } = result;
+    console.log(JSON.stringify({ ...link, expires: new Date(link.expiresAt).toISOString() }, null, 2));
+    console.error("Anyone with this link can use the app, including its live backend, until it expires or you revoke it (Apps → Revoke access).");
+    return;
+  }
   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.
@@ -2507,6 +2634,7 @@ async function resumeSessionItem(item, config, token) {
   const resumeArgs = agentResumeArgs(agentId, resumeRef);
   const runArgs = [agentId, ...resumeArgs];
   if (item.workspace) runArgs.push("--workspace", item.workspace); // native resume finds the session by its original cwd
+  if (item.id) runArgs.push("--bivy-session", item.id);
   console.log(c.dim(`Resuming ${c.cyan(item.name)} with ${agentId} ${resumeArgs.join(" ")}…`));
   await cmdRun(runArgs);
 }

package/dist/agents/claude-code/runtime.js

@@ -532,6 +532,9 @@ function loadClaudeTranscript(sessionId) {
     // re-drive, or a session the user resumed), so it's noise — we keep only a
     // trailing one, where the session actually ended interrupted. See below.
     const restartNoticeIdx = [];
+    // The latest user prompt, and the index of an API-error reply just kept.
+    let lastPrompt;
+    let lastErrorIdx = -1;
     try {
         for (const line of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
             if (!line.trim())
@@ -567,7 +570,21 @@ function loadClaudeTranscript(sessionId) {
                 continue;
             if (typeof content !== "string" && !Array.isArray(content))
                 continue;
+            // A re-driven prompt: an API-error reply (e.g. a 401 before a credential
+            // refresh) followed — past any restart notice — by the same prompt again.
+            // The turn was recovered, so drop both; otherwise history shows the error and
+            // repeats the prompt at the bottom of the chat.
+            if (role === "user" && lastErrorIdx >= 0 && JSON.stringify(content) === JSON.stringify(lastPrompt)) {
+                messages.splice(lastErrorIdx, 1);
+                restartNoticeIdx.forEach((idx, i) => { if (idx > lastErrorIdx)
+                    restartNoticeIdx[i] = idx - 1; });
+                lastErrorIdx = -1;
+                continue;
+            }
+            if (role === "user" && !(Array.isArray(content) && content.some((block) => block?.type === "tool_result")))
+                lastPrompt = content;
             messages.push({ role, content, timestamp: new Date(entry?.timestamp ?? entry?.createdAt ?? Date.now()).getTime() });
+            lastErrorIdx = entry?.isApiErrorMessage === true ? messages.length - 1 : -1;
         }
     }
     catch {

package/dist/apps/annotate.js

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import { readFileSync } from "node:fs";
+import { decodePng } from "./review.js";
+import { encodePng } from "./rfb.js";
+const MAX_STROKES = 50;
+const MAX_POINTS = 10_000;
+/** Validates strokes from the client (untrusted shape): bounded, finite. */
+export function readStrokes(input) {
+    if (!Array.isArray(input) || !input.length || input.length > MAX_STROKES)
+        throw new Error("Draw at least one mark (at most 50).");
+    let total = 0;
+    return input.map((raw) => {
+        const stroke = raw;
+        if ((stroke?.tool !== "pen" && stroke?.tool !== "box") || !Array.isArray(stroke.points) || !stroke.points.length)
+            throw new Error("Invalid mark.");
+        total += stroke.points.length;
+        if (total > MAX_POINTS)
+            throw new Error("Too many points in the marks.");
+        const points = stroke.points.map((p) => {
+            if (!Array.isArray(p) || p.length !== 2 || !p.every((n) => typeof n === "number" && Number.isFinite(n) && Math.abs(n) < 1e6))
+                throw new Error("Invalid mark point.");
+            return [p[0], p[1]];
+        });
+        return { tool: stroke.tool, points };
+    });
+}
+/** Whether a picture retaken on the machine may not match what the user saw:
+ * the page kept state a fresh browser doesn't have (storage, cookies, typed
+ * input, an open menu or dialog, anything the user did since it loaded), or
+ * the retake couldn't scroll to where they were. A Compare screenshot or a
+ * desktop app's frame is the exact picture, so never approximate. */
+export function approximate(source, signals = {}, scrolledTo = true) {
+    if (source === "exact")
+        return false;
+    return !scrolledTo || Object.values(signals).some(Boolean);
+}
+/** The annotation colours, read from the design tokens (single source). */
+function tokenColor(name, fallback) {
+    let hex = fallback;
+    try {
+        hex = new RegExp(`--${name}:\\s*(#[0-9a-fA-F]{6})`).exec(readFileSync(new URL("./tokens.css", import.meta.url), "utf8"))?.[1] ?? fallback;
+    }
+    catch { /* fallback */ }
+    return [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
+}
+const INK = tokenColor("annotate", "#ff2d78");
+const HALO = tokenColor("annotate-halo", "#ffffff");
+/** Mark width in CSS pixels, and its halo on each side. */
+const WIDTH = 4;
+const HALO_WIDTH = 1.5;
+/** Draws marks onto a PNG. `scale` maps CSS pixels to image pixels;
+ * `offset` (CSS px) is subtracted first — the scroll position the picture
+ * was taken at. Halos go under every mark first, so crossings stay clean. */
+export function composite(png, strokes, map) {
+    const image = decodePng(png);
+    const { width, height, channels } = image;
+    const rgb = Buffer.alloc(width * height * 3);
+    for (let p = 0; p < width * height; p++)
+        image.pixels.copy(rgb, p * 3, p * channels, p * channels + 3);
+    const off = map.offset ?? { x: 0, y: 0 };
+    const toImage = ([x, y]) => [(x - off.x) * map.scale, (y - off.y) * map.scale];
+    const paths = strokes.map((stroke) => {
+        const points = stroke.points.map(toImage);
+        if (stroke.tool === "pen")
+            return points;
+        const [a, b] = [points[0], points[points.length - 1]];
+        return [a, [b[0], a[1]], b, [a[0], b[1]], a];
+    });
+    const disc = (cx, cy, r, color) => {
+        for (let y = Math.max(0, Math.floor(cy - r)); y <= Math.min(height - 1, Math.ceil(cy + r)); y++) {
+            for (let x = Math.max(0, Math.floor(cx - r)); x <= Math.min(width - 1, Math.ceil(cx + r)); x++) {
+                if ((x - cx) ** 2 + (y - cy) ** 2 <= r * r)
+                    rgb.set(color, (y * width + x) * 3);
+            }
+        }
+    };
+    const trace = (path, r, color) => {
+        const step = Math.max(0.5, r / 2);
+        for (let i = 0; i < path.length; i++) {
+            const [x0, y0] = path[i];
+            const [x1, y1] = path[i + 1] ?? path[i];
+            const n = Math.max(1, Math.ceil(Math.hypot(x1 - x0, y1 - y0) / step));
+            for (let k = 0; k <= n; k++)
+                disc(x0 + ((x1 - x0) * k) / n, y0 + ((y1 - y0) * k) / n, r, color);
+        }
+    };
+    const r = (WIDTH / 2) * map.scale;
+    for (const path of paths)
+        trace(path, r + HALO_WIDTH * map.scale, HALO);
+    for (const path of paths)
+        trace(path, r, INK);
+    return encodePng(width, height, rgb);
+}

package/dist/apps/display-viewer.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+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, 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}
+#screen{position:fixed;inset:0}#status{position:fixed;inset:0;display:grid;place-items:center;margin:0;padding:24px;text-align:center;line-height:1.5}[hidden]{display:none!important}
+#tools{position:fixed;left:12px;bottom:72px;display:flex;flex-direction:column;align-items:flex-start;gap:8px}
+button,#paste{font:inherit;font-size:14px;min-height:44px;padding:0 14px;border-radius:22px;border:1px solid GrayText;background:Canvas;color:CanvasText}
+#keys{display:none;min-width:44px;padding:0}@media (pointer:coarse){#keys{display:block}}
+#paste{display:flex;gap:8px;align-items:center;padding:4px 4px 4px 14px}#paste input{font:inherit;min-height:36px;border:0;background:transparent;color:inherit;width:12em}
+#typing{position:fixed;left:0;top:0;width:1px;height:1px;opacity:0;border:0;padding:0}</style>
+<div id="screen"></div><p id="status" role="status">Starting the app…</p>
+<div id="tools"><button id="copy" type="button" hidden>Copy from app</button>
+<form id="paste" hidden><input id="paste-text" aria-label="Text to paste into the app" placeholder="Paste here"><button type="submit">Send</button></form>
+<button id="paste-open" type="button">Paste</button><button id="keys" type="button" aria-label="Show keyboard">⌨</button></div>
+<input id="typing" aria-label="Type into the app" autocapitalize="off" autocomplete="off" autocorrect="off" spellcheck="false">
+<script type="module" nonce="${nonce}">import RFB from "${NOVNC_PATH}core/rfb.js";
+const $=id=>document.getElementById(id),screen=$("screen"),status=$("status"),typing=$("typing"),SCALE=${scale === 2 ? 2 : 1};
+let rfb,wait=500,remote="";
+const say=text=>{status.textContent=text;status.hidden=!text;};
+
+// Latency: time from each input sent to the next frame back, in this browser.
+const lat=[];let pending=0,bytes=0,since=performance.now();
+// (Patched in place: noVNC rejects a WebSocket subclass.)
+const send=WebSocket.prototype.send,probed=new WeakSet();
+WebSocket.prototype.send=function(data){
+  if(!probed.has(this)){probed.add(this);this.addEventListener("message",e=>{bytes+=e.data.byteLength??e.data.size??0;if(pending){lat.push(performance.now()-pending);pending=0;}});}
+  const first=data instanceof ArrayBuffer?new Uint8Array(data)[0]:ArrayBuffer.isView(data)?new Uint8Array(data.buffer,data.byteOffset,1)[0]:-1;
+  if((first===4||first===5)&&!pending)pending=performance.now();
+  return send.call(this,data);
+};
+setInterval(()=>{
+  if(lat.length<5)return;
+  const sorted=lat.splice(0).sort((a,b)=>a-b),at=p=>sorted[Math.min(sorted.length-1,Math.floor(sorted.length*p))];
+  const secs=(performance.now()-since)/1000;since=performance.now();
+  fetch("${DISPLAY_STATS_PATH}",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({latencyMs:{p50:at(.5),p95:at(.95)},kBps:bytes/1024/secs,viewport:{width:innerWidth,height:innerHeight,scale:devicePixelRatio}})}).catch(()=>{});
+  bytes=0;
+},10000);
+
+function connect(){
+  rfb=new RFB(screen,(location.protocol==="https:"?"wss://":"ws://")+location.host+"${DISPLAY_SOCKET_PATH}",{shared:true});
+  // Ask for device pixels, so a display started at 2× stays sharp once scaled
+  // to fit. Only the resize request uses them; scaling still fits CSS pixels.
+  let ask=1;const measure=rfb._screenSize.bind(rfb),request=rfb._requestRemoteResize.bind(rfb);
+  rfb._screenSize=()=>{const s=measure();return{w:Math.round(s.w*ask),h:Math.round(s.h*ask)};};
+  rfb._requestRemoteResize=()=>{ask=SCALE;try{request();}finally{ask=1;}};
+  rfb.resizeSession=true;rfb.scaleViewport=true;rfb.focusOnClick=true;
+  rfb.addEventListener("connect",()=>{wait=500;say("");});
+  rfb.addEventListener("disconnect",()=>{say("Starting the app…");setTimeout(connect,wait);wait=Math.min(wait*2,5000);});
+  // The app copied text: offer it; the browser only lets a tap write the clipboard.
+  rfb.addEventListener("clipboard",e=>{remote=e.detail.text;$("copy").hidden=!remote;$("copy").textContent="Copy from app";});
+}
+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 (⌘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.
+  $("paste").hidden=false;$("paste-text").focus();
+};
+$("paste").onsubmit=e=>{e.preventDefault();paste($("paste-text").value);$("paste-text").value="";$("paste").hidden=true;};
+$("paste-text").addEventListener("keydown",e=>{if(e.key==="Escape"){$("paste").hidden=true;rfb.focus();}});
+
+// Phones: a soft keyboard needs a text field; forward what's typed as keys.
+const SPECIAL={Backspace:0xff08,Enter:0xff0d,Tab:0xff09,Escape:0xff1b,ArrowLeft:0xff51,ArrowUp:0xff52,ArrowRight:0xff53,ArrowDown:0xff54};
+$("keys").onclick=()=>typing.focus();
+typing.addEventListener("keydown",e=>{const key=SPECIAL[e.key];if(key){e.preventDefault();rfb.sendKey(key,null);}});
+typing.addEventListener("input",()=>{for(const ch of typing.value){const cp=ch.codePointAt(0);rfb.sendKey(cp<256?cp:0x01000000+cp,null);}typing.value="";});
+</script></html>`;
+}

package/dist/apps/display.js

@@ -0,0 +1,145 @@
+// 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 { 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 = {
+    WAYLAND_DISPLAY: "",
+    GDK_BACKEND: "x11",
+    QT_QPA_PLATFORM: "xcb",
+    SDL_VIDEODRIVER: "x11",
+    ELECTRON_OZONE_PLATFORM_HINT: "x11",
+    NO_AT_BRIDGE: "1",
+};
+/** How each toolkit is told to draw at 2× for a high-density viewer (Chromium
+ * and Electron read the Xft.dpi the window manager publishes). */
+const SCALE_ENV = {
+    1: {},
+    2: { GDK_SCALE: "2", QT_SCALE_FACTOR: "2", J2D_UISCALE: "2" },
+};
+export const DISPLAY_SCALES = Object.keys(SCALE_ENV).map(Number);
+/** TigerVNC's X server; BIVY_XVNC overrides. */
+const XVNC = ["Xtigervnc", "Xvnc"];
+const START_MS = 10_000;
+export function findXvnc(env = process.env) {
+    if (env.BIVY_XVNC)
+        return fs.existsSync(env.BIVY_XVNC) ? env.BIVY_XVNC : undefined;
+    for (const name of XVNC) {
+        try {
+            return execFileSync("which", [name], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env }).trim() || undefined;
+        }
+        catch { /* next */ }
+    }
+    return undefined;
+}
+/** One private X display per view, started on demand: an Xvnc server that
+ * listens on no TCP port, an authority cookie only its programs get, and a
+ * window manager that fits windows to whatever size the viewer asks for. */
+export class DisplayHost {
+    options;
+    displays = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** 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 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;
+    }
+    running(id) { return this.displays.get(id)?.ready; }
+    /** `scale` (1 or 2) is fixed when the display starts: programs pick it up once. */
+    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, name, SCALE_ENV[scale] ? scale : 1).then((display) => {
+            // If the X server dies, forget it: the next open starts a fresh one.
+            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, name, scale) {
+        const reason = this.unavailable();
+        if (reason)
+            throw new Error(reason);
+        const xvnc = (this.options.xvnc ?? findXvnc)();
+        const x11Dir = this.options.x11Dir ?? "/tmp/.X11-unix";
+        const authority = path.join(state.dir, "Xauthority");
+        const socket = path.join(state.dir, "vnc.sock");
+        const cookie = writeXauthority(authority);
+        // Another X server may take a number between our check and its lock.
+        for (let attempt = 0; attempt < 5; attempt++) {
+            const number = freeDisplay(x11Dir);
+            const child = spawn(xvnc, [`:${number}`, "-auth", authority, "-rfbunixpath", socket, "-rfbunixmode", "0600", "-rfbport", "-1",
+                "-SecurityTypes", "None", "-AlwaysShared=1", "-AcceptSetDesktopSize=1", "-SendPrimary=0", "-nolisten", "tcp", "-geometry", `${1280 * scale}x${800 * scale}`, "-depth", "24", "-dpi", String(96 * scale), "-desktop", name.slice(0, 60)], { stdio: "ignore" });
+            state.child = child;
+            const x = path.join(x11Dir, `X${number}`);
+            const up = await new Promise((resolve) => {
+                const deadline = Date.now() + START_MS;
+                const exited = () => resolve(false);
+                child.once("exit", exited);
+                child.once("error", exited);
+                const poll = () => {
+                    if (child.exitCode !== null)
+                        return;
+                    if (fs.existsSync(socket) && fs.existsSync(x)) {
+                        child.off("exit", exited);
+                        resolve(true);
+                        return;
+                    }
+                    if (Date.now() > deadline) {
+                        child.kill("SIGKILL");
+                        return;
+                    }
+                    setTimeout(poll, 50);
+                };
+                poll();
+            });
+            if (!up)
+                continue;
+            const wm = new FitWindowManager();
+            await wm.start(x, cookie, 96 * scale);
+            return { socket, wm, scale, env: { ...APP_ENV, ...SCALE_ENV[scale], DISPLAY: `:${number}`, XAUTHORITY: authority } };
+        }
+        throw new Error("Couldn't start a display for this app.");
+    }
+    stop(id) {
+        const state = this.displays.get(id);
+        if (!state)
+            return;
+        this.displays.delete(id);
+        void state.ready.then((display) => display.wm.stop(), () => { });
+        state.child?.kill("SIGTERM");
+        fs.rmSync(state.dir, { recursive: true, force: true });
+    }
+    stopAll() { for (const id of [...this.displays.keys()])
+        this.stop(id); }
+}
+function freeDisplay(x11Dir) {
+    for (let n = 100; n < 1000; n++) {
+        if (!fs.existsSync(path.join(x11Dir, `X${n}`)) && !fs.existsSync(`/tmp/.X${n}-lock`))
+            return n;
+    }
+    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 });
+}