@bivy/bivy 0.17.3-staging.4 → 0.17.3-staging.6

package/bin/bivy.mjs

@@ -2427,6 +2427,7 @@ async function cmdApp(args = []) {
        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 run [--name <name>] [--restart-on-change] [--session <id>] -- <command> [args…]
 
 Manifest: {"version":1,"name":"My app","views":[
   {"kind":"web","name":"Website","source":{"kind":"service","port":3000}},
@@ -2435,17 +2436,36 @@ 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):
+  {"kind":"display","name":"Editor","command":"cargo","args":["run"],"restartOnChange":true}
+  It runs on a private display streamed into the preview, 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" starts on first open and is restarted if it exits.
+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 and prints the PNG paths — look at them before saying the UI is
+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
 Web previews require operator setup; see docs/apps.md.`);
     return;
   }
-  if (!["publish", "list", "remove", "shot"].includes(action)) throw new Error("Unknown app command. Run bivy app --help.");
+  if (!["publish", "list", "remove", "shot", "run"].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 === "shot") {
     for (const flag of ["--widths", "--themes", "--path"]) {
@@ -2464,7 +2484,7 @@ Web previews require operator setup; see docs/apps.md.`);
   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("-")) || (action === "shot" ? positional.length > 1 : positional.length !== (action === "list" ? 0 : 1))) throw new Error("Invalid arguments. Run bivy app --help.");
+  if (positional.some((a) => a.startsWith("-")) || (action === "shot" ? 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 === "publish") {
@@ -2478,11 +2498,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];
   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}`, {
+  const response = await fetch(`${url(config)}/api/apps/${action === "run" ? "publish" : action}`, {
     method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, body: JSON.stringify(body),
   });
   const result = await response.json();

package/dist/apps/display-viewer.js

@@ -0,0 +1,81 @@
+// 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 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) {
+    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 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-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,135 @@
+// 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";
+/** 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 machine for now.";
+        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.");
+}

package/dist/apps/gateway.js

@@ -1,10 +1,14 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // Copyright (c) 2026 Petter André Sjulstad
 import http from "node:http";
+import net from "node:net";
 import { randomBytes } from "node:crypto";
 import path from "node:path";
 import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { WebSocketServer } from "ws";
 import { previewShell } from "./preview-shell.js";
+import { displayViewer, DISPLAY_SOCKET_PATH, DISPLAY_STATS_PATH, NOVNC_PATH } from "./display-viewer.js";
 import { inspectorScript } from "./inspector.js";
 const MIME = {
     ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".mjs": "text/javascript; charset=utf-8",
@@ -47,6 +51,31 @@ function allowInspector(policy, url) {
     return directives.join("; ");
 }
 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;
+/** noVNC's browser modules (core/ and its vendored zlib), served as-is. */
+const novncRoot = (() => { try {
+    return path.dirname(path.dirname(createRequire(import.meta.url).resolve("@novnc/novnc")));
+}
+catch {
+    return undefined;
+} })();
+const novncFiles = new Map();
+function novncFile(relative) {
+    if (!novncRoot || !/^(?:core|vendor)(?:\/[A-Za-z0-9_-]+)+\.js$/.test(relative))
+        return undefined;
+    let data = novncFiles.get(relative);
+    if (!data) {
+        try {
+            data = readFileSync(path.join(novncRoot, relative));
+            novncFiles.set(relative, data);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return data;
+}
 /** Marks gateway-generated "server not answering" responses, so recovery
  * polling can tell them apart from an app's own 502s. */
 const UPSTREAM_DOWN = "x-bivy-upstream-down";
@@ -125,6 +154,7 @@ export class AppGateway {
     /** `reviewer`: the browser session came from a copied (shared) link. */
     sessions = new Map();
     sockets = new Map();
+    displays = new WebSocketServer({ noServer: true, maxPayload: 1024 * 1024, perMessageDeflate: false });
     /** `signIn` sends a signed-out visit to a view's stable address back
      * through Bivy, which re-opens it for a signed-in device. */
     constructor(registry, originTemplate, returnOrigins = () => [], signIn) {
@@ -186,6 +216,7 @@ export class AppGateway {
             this.revoke(id);
         this.tickets.clear();
         this.sessions.clear();
+        this.displays.close();
         this.server.close();
         this.server.closeAllConnections();
     }
@@ -277,7 +308,7 @@ export class AppGateway {
                 return;
             }
             res.setHeader("Content-Type", "application/json");
-            res.end(JSON.stringify({ name: entry.app.name, origin: this.origin(id), returnTo: grant.returnTo }));
+            res.end(JSON.stringify({ name: entry.app.name, origin: this.origin(id), returnTo: grant.returnTo, ...(entry.target.kind === "display" ? { inspect: false } : {}) }));
             return;
         }
         res.writeHead(404);
@@ -398,6 +429,10 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
             await this.note(req, res, entry);
             return;
         }
+        if (entry.target.kind === "display") {
+            await this.display(req, res, entry);
+            return;
+        }
         const inspect = isPageLoad(req);
         // Remember the framed page so a turn reload lands where the user was.
         if (req.method === "GET" && req.headers["sec-fetch-dest"] === "iframe" && req.url.length <= 2048)
@@ -494,6 +529,93 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
         res.on("close", () => upstream.destroy());
         req.pipe(upstream);
     }
+    /** A display view's origin serves only its viewer and noVNC's modules; the
+     * pixels come over the WebSocket (see upgrade). */
+    async display(req, res, entry) {
+        const id = entry.view.id;
+        // The viewer's measurements (same-origin POST, checked above). Numbers only.
+        if (req.url === DISPLAY_STATS_PATH && req.method === "POST") {
+            let body = "";
+            for await (const chunk of req) {
+                body += chunk.toString();
+                if (body.length > 1024) {
+                    res.writeHead(413);
+                    res.end();
+                    return;
+                }
+            }
+            let input;
+            try {
+                input = JSON.parse(body);
+            }
+            catch {
+                res.writeHead(400);
+                res.end();
+                return;
+            }
+            const num = (value, max) => { const n = Number(value); return Number.isFinite(n) ? Math.min(Math.max(0, Math.round(n * 10) / 10), max) : 0; };
+            entry.stats = { at: Date.now(), latencyMs: { p50: num(input.latencyMs?.p50, 60_000), p95: num(input.latencyMs?.p95, 60_000) }, kBps: num(input.kBps, 1e6),
+                viewport: { width: num(input.viewport?.width, 10_000), height: num(input.viewport?.height, 10_000), scale: num(input.viewport?.scale, 8) } };
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (!["GET", "HEAD"].includes(req.method ?? "")) {
+            res.writeHead(405, { Allow: "GET, HEAD" });
+            res.end();
+            return;
+        }
+        const url = req.url.split("?")[0];
+        if (url.startsWith(NOVNC_PATH)) {
+            const data = novncFile(url.slice(NOVNC_PATH.length));
+            if (!data) {
+                res.writeHead(404);
+                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);
+            return;
+        }
+        if (!isPageLoad(req)) {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        const nonce = randomBytes(16).toString("hex");
+        const body = Buffer.from(displayViewer(nonce, entry.app.name, entry.displayScale ?? 1));
+        const headers = responseHeaders({}, this.ancestors(id));
+        headers["content-security-policy"] = `default-src 'none'; script-src 'self' 'nonce-${nonce}'; style-src 'nonce-${nonce}'; img-src data: blob:; connect-src 'self' ${this.origin(id).replace(/^https:/, "wss:")}; frame-ancestors ${this.ancestors(id)}; worker-src 'none'; base-uri 'none'; form-action 'none'`;
+        res.writeHead(200, { ...headers, "content-type": "text/html; charset=utf-8", "content-length": body.length });
+        res.end(req.method === "HEAD" ? undefined : body);
+    }
+    /** Relays a viewer's WebSocket to the display's private VNC socket. */
+    displaySocket(req, socket, head, entry) {
+        this.displays.handleUpgrade(req, socket, head, (ws) => {
+            // Not running yet (or any more): the viewer retries while the app starts.
+            if (!entry.display) {
+                ws.close(1013, "The display isn't running.");
+                return;
+            }
+            const peer = net.connect(entry.display);
+            const close = () => { peer.destroy(); ws.terminate(); };
+            peer.on("data", (data) => {
+                ws.send(data);
+                if (ws.bufferedAmount > DISPLAY_BUFFER_BYTES) {
+                    peer.pause();
+                    const resume = setInterval(() => { if (ws.bufferedAmount < DISPLAY_BUFFER_BYTES / 2 || ws.readyState !== ws.OPEN) {
+                        clearInterval(resume);
+                        peer.resume();
+                    } }, 20);
+                }
+            });
+            ws.on("message", (data) => peer.write(data));
+            peer.on("error", close);
+            peer.on("close", close);
+            ws.on("error", close);
+            ws.on("close", close);
+        });
+    }
     /** A reviewer's note. Untrusted text: stored bounded, shown as text, and only
      * ever turned into a draft by the owner. Same-origin POSTs only (checked above). */
     async note(req, res, entry) {
@@ -578,11 +700,18 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
     upgrade(req, socket, head) {
         const entry = this.entry(req);
         const expires = entry && this.authorize(req, entry.view.id);
-        if (!entry || !expires || entry.target.kind !== "service" || req.headers.origin !== this.origin(entry.view.id) || req.headers.upgrade?.toLowerCase() !== "websocket" || !req.url?.startsWith("/") || req.url.startsWith("//")) {
+        const display = entry?.target.kind === "display";
+        if (!entry || !expires || (entry.target.kind !== "service" && !(display && req.url === DISPLAY_SOCKET_PATH)) || req.headers.origin !== this.origin(entry.view.id) || req.headers.upgrade?.toLowerCase() !== "websocket" || !req.url?.startsWith("/") || req.url.startsWith("//")) {
             socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
             return;
         }
         this.track(entry.view.id, socket, expires);
+        if (display) {
+            this.displaySocket(req, socket, head, entry);
+            return;
+        }
+        if (entry.target.kind !== "service")
+            return;
         const port = entry.target.port;
         const upstream = http.request({ hostname: "127.0.0.1", port, path: req.url, headers: { ...upstreamHeaders(req, this.origin(entry.view.id)), connection: "Upgrade", upgrade: "websocket" } });
         upstream.setTimeout(10_000, () => upstream.destroy());

package/dist/apps/preview-shell.js

@@ -101,6 +101,11 @@ function show(data,launch){
   back.title=data.returnTo?'Return to '+new URL(data.returnTo).host:'Close preview';
   frame.title=data.name;
   frame.hidden=false;
+  // Desktop apps have no page to inspect: no Point or Console. Their viewer
+  // (Bivy's own code) may use the clipboard; generated web apps may not.
+  // (Set before navigating: the policy is fixed when the frame loads.)
+  for(const b of [$('point'),$('errors')])b.hidden=data.inspect===false;
+  if(data.inspect===false)frame.allow='clipboard-read; clipboard-write';
   frame.src=data.origin+(launch?'/__bivy/open#'+(embedded?'e:':'')+launch:'/');
   back.hidden=embedded&&Boolean(data.returnTo);
   for(const b of [reload,$('point'),$('errors')])b.disabled=false;

package/dist/apps/registry.js

@@ -178,8 +178,13 @@ export class AppRegistry extends EventEmitter {
                 target = { kind: "terminal", ...command(spec, workspace, "Terminal view") };
                 view = { ...base, kind: "terminal", command: target.command, args: target.args };
             }
+            else if (spec.kind === "display") {
+                // Shown through the web preview: Bivy's viewer streams the display.
+                target = { kind: "display", ...command(spec, workspace, "Display view"), restartOnChange: spec.restartOnChange === true };
+                view = { ...base, kind: "web", source: "display", managed: true };
+            }
             else
-                throw new Error("Unsupported app view. This machine supports web and terminal views.");
+                throw new Error("Unsupported app view. Supported views: web, terminal and display.");
             app.views.push(view);
             entries.push({ app, view, target, revision: 0, source });
         }
@@ -202,7 +207,8 @@ export class AppRegistry extends EventEmitter {
         const bumped = [];
         let total = [...this.views.values()].reduce((sum, item) => sum + (item.target.kind === "static" ? item.target.bytes : 0), 0);
         for (const entry of this.views.values()) {
-            if (entry.app.sessionId !== sessionId || entry.view.kind !== "web")
+            // A display streams live pixels: only one that restarts on changes has a new revision.
+            if (entry.app.sessionId !== sessionId || entry.view.kind !== "web" || (entry.target.kind === "display" && !entry.target.restartOnChange))
                 continue;
             if (entry.target.kind === "static") {
                 if (!entry.source)

package/dist/apps/rfb.js

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import net from "node:net";
+import { deflateSync } from "node:zlib";
+/** Reads exact byte counts from a stream. */
+class Reader {
+    buffer = Buffer.alloc(0);
+    waiting;
+    failure;
+    reject;
+    constructor(socket) {
+        socket.on("data", (chunk) => { this.buffer = Buffer.concat([this.buffer, chunk]); this.pump(); });
+        const fail = (error) => { this.failure = error; this.reject?.(error); };
+        socket.on("error", fail);
+        socket.on("close", () => fail(new Error("The display closed the connection.")));
+    }
+    read(n) {
+        return new Promise((resolve, reject) => {
+            if (this.failure && this.buffer.length < n) {
+                reject(this.failure);
+                return;
+            }
+            this.waiting = { n, resolve };
+            this.reject = reject;
+            this.pump();
+        });
+    }
+    pump() {
+        if (!this.waiting || this.buffer.length < this.waiting.n)
+            return;
+        const { n, resolve } = this.waiting;
+        this.waiting = undefined;
+        const out = this.buffer.subarray(0, n);
+        this.buffer = this.buffer.subarray(n);
+        resolve(out);
+    }
+}
+/** One full frame from a VNC server (security type None), as packed RGB. Joins
+ * as a shared client, so open viewers stay connected. */
+export async function captureFrame(socketPath, timeoutMs = 10_000) {
+    const socket = net.connect(socketPath);
+    const timer = setTimeout(() => socket.destroy(new Error("The display didn't answer in time.")), timeoutMs);
+    try {
+        const reader = new Reader(socket);
+        const version = (await reader.read(12)).toString("latin1");
+        if (!/^RFB 003\.\d{3}\n$/.test(version))
+            throw new Error("Not a VNC display.");
+        socket.write("RFB 003.008\n");
+        const types = await reader.read((await reader.read(1))[0]);
+        if (!types.includes(1))
+            throw new Error("The display requires a password.");
+        socket.write(Buffer.from([1]));
+        if ((await reader.read(4)).readUInt32BE(0) !== 0)
+            throw new Error("The display refused the connection.");
+        socket.write(Buffer.from([1]));
+        const init = await reader.read(24);
+        const width = init.readUInt16BE(0), height = init.readUInt16BE(2);
+        await reader.read(init.readUInt32BE(20)); // desktop name
+        // 32 bpp true colour, little-endian, red at bit 16: bytes arrive B, G, R, X.
+        const format = Buffer.from([0, 0, 0, 0, 32, 24, 0, 1, 0, 255, 0, 255, 0, 255, 16, 8, 0, 0, 0, 0]);
+        const encodings = Buffer.from([2, 0, 0, 1, 0, 0, 0, 0]); // Raw only
+        const request = Buffer.alloc(10);
+        request[0] = 3;
+        request.writeUInt16BE(width, 6);
+        request.writeUInt16BE(height, 8);
+        socket.write(Buffer.concat([format, encodings, request]));
+        const rgb = Buffer.alloc(width * height * 3);
+        for (;;) {
+            const type = (await reader.read(1))[0];
+            if (type === 2)
+                continue; // bell
+            if (type === 3) {
+                const head = await reader.read(7);
+                await reader.read(head.readUInt32BE(3));
+                continue;
+            } // clipboard
+            if (type !== 0)
+                throw new Error("Unexpected message from the display.");
+            const rects = (await reader.read(3)).readUInt16BE(1);
+            for (let r = 0; r < rects; r++) {
+                const head = await reader.read(12);
+                const x = head.readUInt16BE(0), y = head.readUInt16BE(2), w = head.readUInt16BE(4), h = head.readUInt16BE(6);
+                if (head.readInt32BE(8) !== 0)
+                    throw new Error("Unexpected encoding from the display.");
+                const pixels = await reader.read(w * h * 4);
+                for (let row = 0; row < h; row++)
+                    for (let col = 0; col < w; col++) {
+                        if (x + col >= width || y + row >= height)
+                            continue;
+                        const from = (row * w + col) * 4, to = ((y + row) * width + x + col) * 3;
+                        rgb[to] = pixels[from + 2];
+                        rgb[to + 1] = pixels[from + 1];
+                        rgb[to + 2] = pixels[from];
+                    }
+            }
+            return { width, height, rgb };
+        }
+    }
+    finally {
+        clearTimeout(timer);
+        socket.destroy();
+    }
+}
+const CRC = Array.from({ length: 256 }, (_, n) => { let c = n; for (let k = 0; k < 8; k++)
+    c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; return c >>> 0; });
+function crc32(data) { let c = 0xffffffff; for (const byte of data)
+    c = CRC[(c ^ byte) & 0xff] ^ (c >>> 8); return (c ^ 0xffffffff) >>> 0; }
+function chunk(type, data) {
+    const head = Buffer.alloc(8);
+    head.writeUInt32BE(data.length, 0);
+    head.write(type, 4, "latin1");
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), data])));
+    return Buffer.concat([head, data, crc]);
+}
+export function encodePng(width, height, rgb) {
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(width, 0);
+    header.writeUInt32BE(height, 4);
+    header[8] = 8;
+    header[9] = 2; // 8-bit RGB
+    const rows = Buffer.alloc((width * 3 + 1) * height);
+    for (let y = 0; y < height; y++)
+        rgb.copy(rows, y * (width * 3 + 1) + 1, y * width * 3, (y + 1) * width * 3);
+    return Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), chunk("IHDR", header), chunk("IDAT", deflateSync(rows)), chunk("IEND", Buffer.alloc(0))]);
+}

package/dist/apps/screenshot.js

@@ -7,6 +7,7 @@ import http from "node:http";
 import { once } from "node:events";
 import { spawn, execFileSync } from "node:child_process";
 import { WebSocket } from "ws";
+import { captureFrame, encodePng } from "./rfb.js";
 /** Browsers tried in order; BIVY_CHROME overrides. Any Chromium works. */
 const CANDIDATES = [
     "google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge",
@@ -95,11 +96,24 @@ class Cdp {
 }
 /** Screenshots web views with one headless browser, one shot at a time, so
  * small machines cope. Service views are loaded straight from loopback;
- * static views from a throwaway loopback server. Files are PNGs in `outDir`. */
+ * static views from a throwaway loopback server. Desktop apps are read from
+ * their display, at its current size, without a browser. Files are PNGs in `outDir`. */
 export async function takeShots(views, request, outDir, chrome = findChrome()) {
+    fs.mkdirSync(outDir, { recursive: true });
+    const shots = [];
+    for (const entry of views) {
+        if (entry.target.kind !== "display" || !entry.display)
+            continue;
+        const frame = await captureFrame(entry.display);
+        const file = path.join(outDir, `${entry.view.id.slice(0, 8)}-${frame.width}-native.png`);
+        fs.writeFileSync(file, encodePng(frame.width, frame.height, frame.rgb));
+        shots.push({ viewId: entry.view.id, view: entry.view.name, width: frame.width, theme: "native", file });
+    }
+    views = views.filter((entry) => entry.target.kind === "service" || entry.target.kind === "static");
+    if (!views.length)
+        return shots;
     if (!chrome)
         throw new Error("No Chrome or Chromium found on this machine. Install one, or set BIVY_CHROME to its path.");
-    fs.mkdirSync(outDir, { recursive: true });
     const profile = fs.mkdtempSync(path.join(os.tmpdir(), "bivy-shot-"));
     const servers = [];
     let ws;
@@ -132,7 +146,6 @@ export async function takeShots(views, request, outDir, chrome = findChrome()) {
         const { targetId } = await cdp.send("Target.createTarget", { url: "about:blank" });
         const { sessionId } = await cdp.send("Target.attachToTarget", { targetId, flatten: true });
         await cdp.send("Page.enable", {}, sessionId);
-        const shots = [];
         for (const entry of views) {
             let origin;
             if (entry.target.kind === "service")

package/dist/apps/service.js

@@ -3,6 +3,9 @@ import os from "node:os";
 import path from "node:path";
 import { scanListeners } from "./listeners.js";
 import { takeShots } from "./screenshot.js";
+const NO_DISPLAYS = { unavailable: () => "Desktop app views aren't available on this machine.", ensure: () => Promise.reject(new Error("Desktop app views aren't available on this machine.")), stop: () => { } };
+/** How long a screenshot waits for a desktop app's first window. */
+const WINDOW_WAIT_MS = 15_000;
 /** Composes view providers; registry never spawns processes and the gateway
  * never knows about terminals. New providers can extend open/remove here. */
 /** A managed server that keeps exiting is left down after this many restarts
@@ -21,6 +24,7 @@ export class AppService {
     scan;
     serverWatchMs;
     screenshots;
+    displays;
     shooting = Promise.resolve();
     constructor(registry, gateway, terminals, options = {}) {
         this.registry = registry;
@@ -29,6 +33,7 @@ export class AppService {
         this.scan = options.scan ?? scanListeners;
         this.serverWatchMs = options.serverWatchMs ?? 5_000;
         this.screenshots = { enabled: options.screenshots?.enabled ?? (() => false), take: options.screenshots?.take ?? takeShots };
+        this.displays = options.displays ?? NO_DISPLAYS;
     }
     list(sessionId) {
         const available = Boolean(this.gateway) && this.gateway?.available !== false;
@@ -39,17 +44,35 @@ export class AppService {
                     continue;
                 if (available)
                     view.address = this.gateway?.address?.(view.id);
-                const notes = this.registry.getView(view.id)?.notes;
-                if (notes?.length)
-                    view.notes = structuredClone(notes);
+                const entry = this.registry.getView(view.id);
+                if (entry?.notes?.length)
+                    view.notes = structuredClone(entry.notes);
+                if (entry?.stats)
+                    view.stats = structuredClone(entry.stats);
             }
         return { apps, previewAvailable: available };
     }
-    publish(sessionId, workspace, manifest) { return this.registry.publish(sessionId, workspace, manifest); }
+    publish(sessionId, workspace, manifest) {
+        // Tell the agent now, not on first open, when this machine can't show it.
+        const unavailable = manifest?.views?.some?.((view) => view?.kind === "display") && this.displays.unavailable();
+        if (unavailable)
+            throw new Error(unavailable);
+        return this.registry.publish(sessionId, workspace, manifest);
+    }
     /** An agent turn changed files in this session's workspace. With agent
      * screenshots on, Compare gets an "after" shot once servers have rebuilt. */
     turnChanged(sessionId) {
         const bumped = this.registry.touch(sessionId);
+        // Desktop apps that asked for it are restarted, so they run the new code.
+        for (const id of bumped) {
+            const entry = this.registry.getView(id);
+            const server = this.servers.get(id);
+            if (entry?.target.kind !== "display" || !server?.termId)
+                continue;
+            this.terminals.close(server.termId);
+            server.termId = undefined;
+            void this.ensureServer(entry).catch(() => { });
+        }
         if (bumped.length && this.screenshots.enabled())
             setTimeout(() => void this.capture(bumped), COMPARE_SETTLE_MS).unref?.();
         return bumped;
@@ -60,6 +83,7 @@ export class AppService {
             const entry = this.registry.getView(id);
             if (!entry || entry.view.kind !== "web")
                 continue;
+            await this.windowShown(entry).catch(() => { });
             const outDir = path.join(os.tmpdir(), "bivy-shots", "compare", id);
             const run = this.shooting.catch(() => { }).then(() => this.screenshots.take([entry], { widths: [390], themes: ["light"], path: entry.lastPath ?? "/" }, outDir));
             this.shooting = run;
@@ -88,8 +112,11 @@ export class AppService {
     }
     /** `direct` opens the app origin itself (no shell): a signed-in device
      * returning to a view's stable address. */
-    async open(sessionId, appId, viewId, returnTo, direct = false) {
+    /** `scale`: the opening device's pixel density, used if this starts a display. */
+    async open(sessionId, appId, viewId, returnTo, direct = false, scale) {
         const entry = this.registry.requireView(sessionId, appId, viewId);
+        if (entry.target.kind === "display" && !entry.display)
+            entry.displayScale = scale === 2 ? 2 : 1;
         if (entry.view.kind === "web") {
             if (!this.gateway)
                 throw new Error("Bivy's preview service is unavailable on this connection.");
@@ -153,6 +180,7 @@ export class AppService {
         const views = apps.flatMap((app) => app.views).filter((view) => view.kind === "web").map((view) => this.registry.getView(view.id)).filter(Boolean);
         if (!views.length)
             throw new Error("This session has no web views to screenshot. Publish one with bivy app publish, or preview a detected server.");
+        await Promise.all(views.map((entry) => this.windowShown(entry)));
         const outDir = path.join(os.tmpdir(), "bivy-shots", sessionId.replace(/[^A-Za-z0-9_-]/g, "_"), String(Date.now()));
         const run = this.shooting.catch(() => { }).then(() => this.screenshots.take(views, { widths, themes: [...new Set(themes)], path: page }, outDir));
         this.shooting = run;
@@ -166,10 +194,39 @@ export class AppService {
             throw new Error("Only views with a start command have server logs.");
         return { kind: "terminal", termId };
     }
+    /** A desktop app's display is up and showing a window (or gave up waiting),
+     * so a screenshot shows the app rather than an empty screen. */
+    async windowShown(entry) {
+        if (entry.target.kind !== "display")
+            return;
+        await this.ensureServer(entry);
+        const display = await this.displays.ensure(entry.view.id, entry.app.name, entry.displayScale);
+        for (const until = Date.now() + WINDOW_WAIT_MS; !display.wm.count && Date.now() < until;)
+            await new Promise((r) => setTimeout(r, 100));
+        await new Promise((r) => setTimeout(r, 800)); // first paint
+    }
+    /** The program Bivy runs for a view: a service's start command, or a desktop
+     * app on its display (started first). */
+    program(entry) {
+        const target = entry.target;
+        if (target.kind === "service" && target.start)
+            return { ...target.start, name: `${entry.app.name} · ${entry.view.name} server` };
+        if (target.kind !== "display")
+            throw new Error("This view has no program.");
+        return this.displays.ensure(entry.view.id, entry.app.name, entry.displayScale).then((display) => {
+            entry.display = display.socket;
+            return { command: target.command, args: target.args, workspace: target.workspace, env: display.env, name: `${entry.app.name} · ${entry.view.name}` };
+        });
+    }
+    /** Services start synchronously; a desktop app waits for its display. */
+    startProgram(entry) {
+        const program = this.program(entry);
+        return program instanceof Promise ? program.then((spec) => this.terminals.start(spec)) : this.terminals.start(program);
+    }
     ensureServer(entry) {
-        if (entry.target.kind !== "service" || !entry.target.start)
+        if (!(entry.target.kind === "service" && entry.target.start) && entry.target.kind !== "display")
             return Promise.resolve(undefined);
-        const id = entry.view.id, start = entry.target.start;
+        const id = entry.view.id;
         let state = this.servers.get(id);
         if (!state) {
             state = { restarts: [] };
@@ -178,7 +235,7 @@ export class AppService {
         const server = state;
         if (server.termId && this.terminals.has(server.termId))
             return Promise.resolve(server.termId);
-        server.pending ??= this.terminals.start({ ...start, name: `${entry.app.name} · ${entry.view.name} server` })
+        server.pending ??= this.startProgram(entry)
             .then((termId) => {
             if (!this.registry.getView(id)) {
                 this.terminals.close(termId);
@@ -209,6 +266,12 @@ export class AppService {
         return server.pending;
     }
     stopServer(id) {
+        this.displays.stop(id);
+        const entry = this.registry.getView(id);
+        if (entry) {
+            entry.display = undefined;
+            entry.displayScale = undefined;
+        }
         const server = this.servers.get(id);
         if (!server)
             return;

package/dist/apps/x11.js

@@ -0,0 +1,273 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import net from "node:net";
+import fs from "node:fs";
+import { randomBytes } from "node:crypto";
+/** An X authority file with one MIT-MAGIC-COOKIE-1 for any display number, so
+ * only processes Bivy hands the file to can connect. */
+export function writeXauthority(file, cookie = randomBytes(16)) {
+    const field = (data) => { const len = Buffer.alloc(2); len.writeUInt16BE(data.length); return Buffer.concat([len, data]); };
+    const family = Buffer.from([0xff, 0xff]); // FamilyWild
+    fs.writeFileSync(file, Buffer.concat([family, field(Buffer.alloc(0)), field(Buffer.alloc(0)), field(Buffer.from("MIT-MAGIC-COOKIE-1")), field(cookie)]), { mode: 0o600 });
+    return cookie;
+}
+const pad = (n) => (4 - (n % 4)) % 4;
+// Core protocol numbers used below (X11 protocol, little-endian client).
+const OP = { ChangeWindowAttributes: 2, MapWindow: 8, ConfigureWindow: 12, GetGeometry: 14, ChangeProperty: 18, GetProperty: 20, SendEvent: 25, SetInputFocus: 42, QueryExtension: 98 };
+/** RandR minor opcodes. */
+const RR = { QueryVersion: 0, SetScreenSize: 7 };
+const EV = { DestroyNotify: 17, UnmapNotify: 18, MapRequest: 20, ConfigureNotify: 22, ConfigureRequest: 23 };
+const MASK = { StructureNotify: 1 << 17, SubstructureNotify: 1 << 19, SubstructureRedirect: 1 << 20 };
+const CFG = { x: 1, y: 2, width: 4, height: 8, border: 16 };
+const ATOM = { STRING: 31, RESOURCE_MANAGER: 23, WM_NORMAL_HINTS: 40, WM_SIZE_HINTS: 41, WINDOW: 33, WM_TRANSIENT_FOR: 68 };
+/** WM_SIZE_HINTS flag: the program set a minimum size. */
+const P_MIN_SIZE = 1 << 4;
+/** A window manager with one rule, sized for previews: every top-level window
+ * fills the screen, dialogs are centered at their own size, and everything is
+ * refit when the viewer resizes the display. A window that can't shrink to the
+ * viewer's size grows the screen instead, and the viewer scales it down, so
+ * nothing is cut off. Pure protocol, no dependencies. */
+export class FitWindowManager {
+    socket;
+    buffer = Buffer.alloc(0);
+    seq = 0;
+    root = 0;
+    width = 0;
+    height = 0;
+    ready = false;
+    /** Pending replies by sequence number: the raw reply, or undefined on error. */
+    replies = new Map();
+    /** Mapped windows we manage; `size` is what the app asked for (dialogs keep
+     * it), `min` the smallest it can draw. */
+    windows = new Map();
+    /** The size the viewer asked for, and the size we last set ourselves. */
+    viewer = [0, 0];
+    own;
+    randr = 0;
+    /** Resolves once the WM owns the root window; rejects if another WM does. */
+    /** `dpi` is published as Xft.dpi, which Chromium/Electron and others scale by. */
+    start(socketPath, cookie, dpi = 96) {
+        return new Promise((resolve, reject) => {
+            const socket = net.connect(socketPath);
+            this.socket = socket;
+            socket.on("error", (error) => { if (!this.ready)
+                reject(error); });
+            socket.on("close", () => { if (!this.ready)
+                reject(new Error("The display closed the window manager's connection.")); });
+            const name = Buffer.from("MIT-MAGIC-COOKIE-1");
+            const setup = Buffer.alloc(12);
+            setup.write("l", 0);
+            setup.writeUInt16LE(11, 2);
+            setup.writeUInt16LE(0, 4);
+            setup.writeUInt16LE(name.length, 6);
+            setup.writeUInt16LE(cookie.length, 8);
+            socket.write(Buffer.concat([setup, name, Buffer.alloc(pad(name.length)), cookie, Buffer.alloc(pad(cookie.length))]));
+            socket.on("data", (chunk) => {
+                this.buffer = Buffer.concat([this.buffer, chunk]);
+                try {
+                    if (!this.ready) {
+                        if (this.buffer.length < 8)
+                            return;
+                        const total = 8 + this.buffer.readUInt16LE(6) * 4;
+                        if (this.buffer.length < total)
+                            return;
+                        const reply = this.buffer.subarray(0, total);
+                        this.buffer = this.buffer.subarray(total);
+                        if (reply[0] !== 1) {
+                            reject(new Error(`The display refused the window manager: ${reply.subarray(8, 8 + reply[1]).toString()}`));
+                            socket.destroy();
+                            return;
+                        }
+                        this.parseSetup(reply);
+                        this.ready = true;
+                        this.viewer = [this.width, this.height];
+                        const resources = Buffer.from(`Xft.dpi:\t${dpi}\n`);
+                        this.request(OP.ChangeProperty, 0, Buffer.concat([u32(this.root, ATOM.RESOURCE_MANAGER, ATOM.STRING, 8, resources.length), resources, Buffer.alloc(pad(resources.length))]));
+                        const name = Buffer.from("RANDR");
+                        this.query(OP.QueryExtension, Buffer.concat([u16pair(name.length, 0), name, Buffer.alloc(pad(name.length))]), (reply) => {
+                            if (!reply?.[8])
+                                return;
+                            this.randr = reply[9];
+                            this.request(this.randr, RR.QueryVersion, u32(1, 5));
+                        });
+                        // Redirecting the root's substructure is what makes us the WM.
+                        const seq = this.request(OP.ChangeWindowAttributes, 0, u32(this.root, 0x800, MASK.SubstructureRedirect | MASK.SubstructureNotify | MASK.StructureNotify));
+                        this.replies.set(seq, () => reject(new Error("Another window manager already runs on this display.")));
+                        // A no-reply request can't be confirmed directly; a reply to the next
+                        // request arrives in order, so it means the first one passed.
+                        this.query(OP.GetGeometry, u32(this.root), () => { this.replies.delete(seq); resolve(); });
+                    }
+                    this.drain();
+                }
+                catch {
+                    socket.destroy();
+                }
+            });
+        });
+    }
+    stop() { this.socket?.destroy(); this.socket = undefined; }
+    get size() { return [this.width, this.height]; }
+    /** Top-level windows currently shown. */
+    get count() { return this.windows.size; }
+    parseSetup(reply) {
+        const vendorLength = reply.readUInt16LE(24);
+        const formats = reply[29];
+        const screen = 40 + vendorLength + pad(vendorLength) + formats * 8;
+        this.root = reply.readUInt32LE(screen);
+        this.width = reply.readUInt16LE(screen + 20);
+        this.height = reply.readUInt16LE(screen + 22);
+    }
+    request(opcode, data, body) {
+        const header = Buffer.alloc(4);
+        header[0] = opcode;
+        header[1] = data;
+        header.writeUInt16LE(1 + body.length / 4, 2);
+        this.socket?.write(Buffer.concat([header, body]));
+        this.seq = (this.seq + 1) & 0xffff;
+        return this.seq;
+    }
+    query(opcode, body, done) {
+        this.replies.set(this.request(opcode, 0, body), done);
+    }
+    drain() {
+        while (this.buffer.length >= 32) {
+            const kind = this.buffer[0];
+            const length = kind === 1 ? 32 + this.buffer.readUInt32LE(4) * 4 : 32;
+            if (this.buffer.length < length)
+                return;
+            const packet = this.buffer.subarray(0, length);
+            this.buffer = this.buffer.subarray(length);
+            const seq = packet.readUInt16LE(2);
+            if (kind === 0 || kind === 1) {
+                const done = this.replies.get(seq);
+                this.replies.delete(seq);
+                done?.(kind === 1 ? packet : undefined);
+                continue;
+            }
+            this.event(kind & 0x7f, packet);
+        }
+    }
+    event(code, e) {
+        if (code === EV.MapRequest) {
+            const window = e.readUInt32LE(8);
+            // The size it was created (or last configured) with, and whether it's a
+            // dialog: dialogs name their parent and keep their size, centered.
+            let size = [0, 0], min = [0, 0];
+            this.query(OP.GetGeometry, u32(window), (reply) => { if (reply)
+                size = [reply.readUInt16LE(16), reply.readUInt16LE(18)]; });
+            this.query(OP.GetProperty, u32(window, ATOM.WM_NORMAL_HINTS, ATOM.WM_SIZE_HINTS, 0, 18), (reply) => {
+                if (reply && reply.readUInt32LE(16) >= 7 && reply.readUInt32LE(32) & P_MIN_SIZE)
+                    min = [reply.readInt32LE(32 + 20), reply.readInt32LE(32 + 24)];
+            });
+            this.query(OP.GetProperty, u32(window, ATOM.WM_TRANSIENT_FOR, ATOM.WINDOW, 0, 1), (reply) => {
+                if (!reply)
+                    return; // gone already
+                const dialog = reply.readUInt32LE(16) > 0 && reply.readUInt32LE(32) > 0;
+                this.windows.set(window, { dialog, size, min: min.map((v) => Math.max(0, Math.min(v, 8192))) });
+                if (!this.resize())
+                    this.fit(window);
+                this.request(OP.MapWindow, 0, u32(window));
+                this.request(OP.SetInputFocus, 2, u32(window, 0));
+            });
+        }
+        else if (code === EV.ConfigureRequest) {
+            const window = e.readUInt32LE(8);
+            const size = [e.readUInt16LE(20), e.readUInt16LE(22)];
+            const managed = this.windows.get(window);
+            if (managed) {
+                managed.size = size;
+                this.fit(window);
+                return;
+            }
+            // Not shown yet: honour it; the map request decides the final geometry.
+            this.configure(window, e.readInt16LE(16), e.readInt16LE(18), size[0], size[1]);
+        }
+        else if (code === EV.DestroyNotify || code === EV.UnmapNotify) {
+            const window = e.readUInt32LE(8);
+            if (e.readUInt32LE(4) === this.root && this.windows.delete(window))
+                this.resize();
+        }
+        else if (code === EV.ConfigureNotify && e.readUInt32LE(8) === this.root) {
+            // The display changed size: refit everything to the new screen. If the
+            // viewer did it (not us), remember what it asked for.
+            this.width = e.readUInt16LE(20);
+            this.height = e.readUInt16LE(22);
+            if (!this.own || this.own[0] !== this.width || this.own[1] !== this.height) {
+                this.viewer = [this.width, this.height];
+                this.own = undefined;
+            }
+            if (this.resize())
+                return;
+            for (const window of this.windows.keys())
+                this.fit(window);
+        }
+    }
+    /** Grow the screen past the viewer's size when a window can't shrink that
+     * far; back to the viewer's size when it can. True if a resize was sent (the
+     * refit follows when the display reports its new size). */
+    resize() {
+        if (!this.randr)
+            return false;
+        let [w, h] = this.viewer;
+        for (const { dialog, min } of this.windows.values())
+            if (!dialog) {
+                w = Math.max(w, min[0]);
+                h = Math.max(h, min[1]);
+            }
+        if (w === this.width && h === this.height)
+            return false;
+        this.own = [w, h];
+        const body = Buffer.alloc(16);
+        body.writeUInt32LE(this.root, 0);
+        body.writeUInt16LE(w, 4);
+        body.writeUInt16LE(h, 6);
+        body.writeUInt32LE(Math.round(w * 25.4 / 96), 8);
+        body.writeUInt32LE(Math.round(h * 25.4 / 96), 12);
+        const seq = this.request(this.randr, RR.SetScreenSize, body);
+        // Refused (e.g. too large): stop resizing and fit to the screen we have.
+        // A later reply means it was accepted, so drop the error handler.
+        this.replies.set(seq, () => { this.randr = 0; this.own = undefined; for (const window of this.windows.keys())
+            this.fit(window); });
+        this.query(OP.GetGeometry, u32(this.root), () => this.replies.delete(seq));
+        return true;
+    }
+    fit(window) {
+        const managed = this.windows.get(window);
+        if (!managed)
+            return;
+        if (!managed.dialog) {
+            this.configure(window, 0, 0, this.width, this.height);
+            return;
+        }
+        const w = Math.min(Math.max(managed.size[0], 1), this.width), h = Math.min(Math.max(managed.size[1], 1), this.height);
+        this.configure(window, Math.floor((this.width - w) / 2), Math.floor((this.height - h) / 2), w, h);
+    }
+    configure(window, x, y, width, height) {
+        const body = Buffer.alloc(28);
+        body.writeUInt32LE(window, 0);
+        body.writeUInt16LE(CFG.x | CFG.y | CFG.width | CFG.height | CFG.border, 4);
+        body.writeInt32LE(x, 8);
+        body.writeInt32LE(y, 12);
+        body.writeUInt32LE(Math.max(1, width), 16);
+        body.writeUInt32LE(Math.max(1, height), 20);
+        body.writeUInt32LE(0, 24);
+        this.request(OP.ConfigureWindow, 0, body);
+        // ICCCM: tell the client its geometry even when nothing changed, or
+        // toolkits that asked for another size wait for an answer and never paint.
+        const event = Buffer.alloc(32);
+        event[0] = EV.ConfigureNotify;
+        event.writeUInt32LE(window, 4);
+        event.writeUInt32LE(window, 8);
+        event.writeInt16LE(x, 16);
+        event.writeInt16LE(y, 18);
+        event.writeUInt16LE(Math.max(1, width), 20);
+        event.writeUInt16LE(Math.max(1, height), 22);
+        this.request(OP.SendEvent, 0, Buffer.concat([u32(window, MASK.StructureNotify), event]));
+    }
+}
+function u16pair(a, b) { const out = Buffer.alloc(4); out.writeUInt16LE(a, 0); out.writeUInt16LE(b, 2); return out; }
+function u32(...values) {
+    const out = Buffer.alloc(values.length * 4);
+    values.forEach((value, i) => out.writeUInt32LE(value >>> 0, i * 4));
+    return out;
+}

package/dist/controllers/app-commands.js

@@ -20,7 +20,7 @@ export function createAppCommands(service, workspaceFor, published = () => { })
             published(app);
             return { app };
         },
-        "apps.open": (msg) => service.open(String(msg.sessionId), String(msg.appId), String(msg.viewId), typeof msg.returnTo === "string" ? msg.returnTo : undefined, msg.direct === true),
+        "apps.open": (msg) => service.open(String(msg.sessionId), String(msg.appId), String(msg.viewId), typeof msg.returnTo === "string" ? msg.returnTo : undefined, msg.direct === true, typeof msg.scale === "number" ? msg.scale : undefined),
         "apps.shot": (msg) => service.shot(String(msg.sessionId), typeof msg.appId === "string" ? msg.appId : undefined, { widths: msg.widths, themes: msg.themes, path: typeof msg.path === "string" ? msg.path : undefined }),
         "apps.clearNotes": (msg) => service.clearNotes(String(msg.sessionId), String(msg.appId), String(msg.viewId)),
         "apps.logs": (msg) => service.logs(String(msg.sessionId), String(msg.appId), String(msg.viewId)),

package/dist/protocol/client-command-schemas.js

@@ -12,7 +12,7 @@ export const CLIENT_COMMAND_SCHEMAS = {
     "apps.publish": Type.Object({ ...request, ...session, manifest: Type.Unknown() }),
     "apps.offers": Type.Object({ ...request, ...session }),
     "apps.adopt": Type.Object({ ...request, ...session, port: Type.Integer({ minimum: 1024, maximum: 65535 }) }),
-    "apps.open": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String(), returnTo: Type.Optional(Type.String({ maxLength: 2048 })), direct: Type.Optional(Type.Boolean()) }),
+    "apps.open": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String(), returnTo: Type.Optional(Type.String({ maxLength: 2048 })), direct: Type.Optional(Type.Boolean()), scale: Type.Optional(Type.Integer({ minimum: 1, maximum: 2 })) }),
     "apps.shot": Type.Object({ ...request, ...session, appId: Type.Optional(Type.String()), widths: Type.Optional(Type.Array(Type.Integer(), { maxItems: 4 })), themes: Type.Optional(Type.Array(Type.Union([Type.Literal("light"), Type.Literal("dark")]), { maxItems: 2 })), path: Type.Optional(Type.String({ maxLength: 2048 })) }),
     "apps.clearNotes": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String() }),
     "apps.logs": Type.Object({ ...request, ...session, appId: Type.String(), viewId: Type.String() }),

package/dist/server.js

@@ -31,6 +31,7 @@ import { AppRegistry } from "./apps/registry.js";
 import { AppGateway } from "./apps/gateway.js";
 import { RemotePreview } from "./apps/remote-preview.js";
 import { AppService } from "./apps/service.js";
+import { DisplayHost } from "./apps/display.js";
 import { createAppCommands } from "./controllers/app-commands.js";
 import { bindClientCommandRoutes } from "./http/client-command-routes.js";
 import { collectDiscoveredSessions, planNativeAdoption } from "./runtime/native-session-discovery.js";
@@ -1939,6 +1940,8 @@ const appSignIn = (view, pagePath) => {
 };
 const appGateway = process.env.BIVY_APPS_ORIGIN ? new AppGateway(appRegistry, process.env.BIVY_APPS_ORIGIN, appReturnOrigins, appSignIn) : undefined;
 const remotePreview = new RemotePreview(appRegistry, appReturnOrigins, appSignIn);
+// Desktop app views: one private display per view, started on first open.
+const appDisplays = new DisplayHost();
 const appService = new AppService(appRegistry, appGateway ?? remotePreview, {
     start: async (spec) => {
         let failure = "Could not start the app terminal.";
@@ -1953,7 +1956,7 @@ const appService = new AppService(appRegistry, appGateway ?? remotePreview, {
     },
     has: (id) => terminals.has(id),
     close: (id) => { terminals.close(id); },
-}, { screenshots: { enabled: appScreenshotsEnabled } });
+}, { screenshots: { enabled: appScreenshotsEnabled }, displays: appDisplays });
 const RELAY_COMMANDS = {
     ...createAppCommands(appService, (id) => { const record = resolveSession(id); return record ? harnessDirFor(record) : undefined; }, (app) => {
         const record = resolveSession(app.sessionId);
@@ -11468,6 +11471,7 @@ function shutdown(signal) {
     }
     catch { }
     terminals.disposeAll();
+    appDisplays.stopAll();
     // Drop persistent client/relay sockets so server.close() can actually drain;
     // otherwise a lingering WebSocket keeps the process alive until the supervisor
     // SIGKILLs it, orphaning children.

package/dist/session/run-terminal.js

@@ -238,7 +238,7 @@ export function createRunTerminals(deps) {
                 workspace,
                 command: spec.command,
                 args: spec.args,
-                env: credentialEnv,
+                env: { ...credentialEnv, ...spec.env },
                 cols: spec.cols,
                 rows: spec.rows,
                 clientId: spec.clientId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.17.3-staging.4",
+  "version": "0.17.3-staging.6",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",
@@ -39,6 +39,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
+    "@novnc/novnc": "1.7.0",
     "brace-expansion": "5.0.12",
     "express": "^5.2.1",
     "express-rate-limit": "^8.7.0",