@bivy/bivy 0.17.3-staging.9 → 0.18.0

package/dist/apps/gateway.js

@@ -2,13 +2,15 @@
 // Copyright (c) 2026 Petter André Sjulstad
 import http from "node:http";
 import net from "node:net";
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
+import { gzipSync } from "node:zlib";
 import path from "node:path";
 import { readFileSync } from "node:fs";
 import { createRequire } from "node:module";
 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 { displayViewer, DISPLAY_MENU_PATH, DISPLAY_SOCKET_PATH, DISPLAY_STATS_PATH, NOVNC_PATH } from "./display-viewer.js";
+import { pressMenu, readMenuPath, readMenus } from "./menu.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",
@@ -24,7 +26,6 @@ const REVISION_PATH = "/__bivy/revision";
 const INSPECTOR_PATH = "/__bivy/inspector.js";
 const COMPARE_PATH = "/__bivy/compare";
 const NOTES_PATH = "/__bivy/notes";
-const MAX_NOTES = 50;
 /** Larger HTML documents pass through without the inspector. */
 const MAX_INJECT_BYTES = 5 * 1024 * 1024;
 /** Put the inspector first in <head>, so it sees errors from the app's own scripts. */
@@ -50,6 +51,47 @@ function allowInspector(policy, url) {
     }
     return directives.join("; ");
 }
+/** Text-like types that shrink well; images and fonts are compressed already. */
+const COMPRESSIBLE = /^(?:text\/|application\/(?:json|javascript|xml|wasm)|image\/svg\+xml)/i;
+/** Snapshot and noVNC buffers never change, so validators and gzip copies are made once. */
+const encodings = new WeakMap();
+function encoded(data, type) {
+    let entry = encodings.get(data);
+    if (!entry) {
+        // Weak: the identity and gzip bodies share it.
+        entry = { etag: `W/"${createHash("sha256").update(data).digest("base64url").slice(0, 27)}"` };
+        if (data.length >= 1024 && COMPRESSIBLE.test(type)) {
+            const gzip = gzipSync(data);
+            if (gzip.length < data.length)
+                entry.gzip = gzip;
+        }
+        encodings.set(data, entry);
+    }
+    return entry;
+}
+/** Serves fixed bytes with a validator (304 on a match) and gzip when the browser takes it. */
+function sendBytes(req, res, status, headers, data) {
+    const file = encoded(data, String(headers["content-type"] ?? ""));
+    headers.etag = file.etag;
+    headers.vary = "Accept-Encoding";
+    if (status === 200 && (req.headers["if-none-match"] ?? "").split(",").some((tag) => tag.trim() === file.etag)) {
+        res.writeHead(304, headers);
+        res.end();
+        return;
+    }
+    const gzip = file.gzip && /\bgzip\b/i.test(req.headers["accept-encoding"] ?? "") ? file.gzip : undefined;
+    if (gzip)
+        headers["content-encoding"] = "gzip";
+    const body = gzip ?? data;
+    res.writeHead(status, { ...headers, "content-length": body.length });
+    res.end(req.method === "HEAD" ? undefined : body);
+}
+/** App content may sit in the browser's own cache, never a shared one, and is
+ * revalidated on every use whatever the app says: a preview must show what the
+ * agent just built. The app's validators still turn unchanged files into 304s. */
+function privateCache(policy) {
+    return /\bno-store\b/i.test(policy ?? "") ? "no-store" : "private, no-cache";
+}
 const HOUR = 60 * 60_000;
 /** A viewer that stops reading doesn't make the node buffer the display. */
 const DISPLAY_BUFFER_BYTES = 4 * 1024 * 1024;
@@ -125,8 +167,8 @@ function responseHeaders(headers, ancestors, inspector) {
             .map((cookie) => cookie.replace(/;\s*domain=[^;]*/ig, ""));
     }
     // Preview data must not become a shared proxy cache entry. Apps cannot frame
-    // Bivy, retain an opener, or cache an offline service-worker copy of the gate.
-    result["cache-control"] = "no-store";
+    // Bivy or retain an opener; service workers are refused (see handle).
+    result["cache-control"] = privateCache(headers["cache-control"]);
     result["referrer-policy"] = "no-referrer";
     result["cross-origin-opener-policy"] = "same-origin";
     result["x-content-type-options"] = "nosniff";
@@ -474,8 +516,7 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
             headers["content-type"] = MIME[path.extname(file).toLowerCase()] || "application/octet-stream";
             if (inspect && path.extname(file).toLowerCase() === ".html" && data.length <= MAX_INJECT_BYTES)
                 data = withInspector(data);
-            res.writeHead(status, { ...headers, "content-length": data.length });
-            res.end(req.method === "HEAD" ? undefined : data);
+            sendBytes(req, res, status, headers, data);
             return;
         }
         if (entry.target.kind !== "service") {
@@ -560,6 +601,10 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
             res.end();
             return;
         }
+        if (req.url === DISPLAY_MENU_PATH) {
+            await this.displayMenu(req, res, entry);
+            return;
+        }
         if (!["GET", "HEAD"].includes(req.method ?? "")) {
             res.writeHead(405, { Allow: "GET, HEAD" });
             res.end();
@@ -573,8 +618,7 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
                 res.end();
                 return;
             }
-            res.writeHead(200, { ...responseHeaders({}, this.ancestors(id)), "content-type": "text/javascript; charset=utf-8", "content-length": data.length });
-            res.end(req.method === "HEAD" ? undefined : data);
+            sendBytes(req, res, 200, { ...responseHeaders({}, this.ancestors(id)), "content-type": "text/javascript; charset=utf-8" }, data);
             return;
         }
         if (!isPageLoad(req)) {
@@ -589,6 +633,55 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
         res.writeHead(200, { ...headers, "content-type": "text/html; charset=utf-8", "content-length": body.length });
         res.end(req.method === "HEAD" ? undefined : body);
     }
+    /** The app's menu bar for the viewer: HEAD says whether it has one, GET
+     * reads it, POST {path} chooses an item (same-origin, checked above). */
+    async displayMenu(req, res, entry) {
+        const control = entry.displayControl;
+        const json = (status, body) => { res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store" }); res.end(JSON.stringify(body)); };
+        if (req.method === "HEAD") {
+            res.writeHead(control ? 204 : 404);
+            res.end();
+            return;
+        }
+        if (!control) {
+            json(404, { error: "This app's menus aren't available." });
+            return;
+        }
+        try {
+            if (req.method === "GET") {
+                json(200, { menus: await readMenus(control) });
+                return;
+            }
+            if (req.method !== "POST") {
+                res.writeHead(405, { Allow: "GET, HEAD, POST" });
+                res.end();
+                return;
+            }
+            let body = "";
+            for await (const chunk of req) {
+                body += chunk.toString();
+                if (body.length > 4096) {
+                    res.writeHead(413);
+                    res.end();
+                    return;
+                }
+            }
+            let path;
+            try {
+                path = readMenuPath(JSON.parse(body).path);
+            }
+            catch (error) {
+                json(400, { error: error.message });
+                return;
+            }
+            await pressMenu(control, path);
+            res.writeHead(204);
+            res.end();
+        }
+        catch (error) {
+            json(409, { error: error.message });
+        }
+    }
     /** Relays a viewer's WebSocket to the display's private VNC socket. */
     displaySocket(req, socket, head, entry) {
         this.displays.handleUpgrade(req, socket, head, (ws) => {
@@ -646,11 +739,10 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
         }
         const viewport = input.viewport;
         const path = text(input.path, 2048);
-        entry.notes = [...(entry.notes ?? []), {
-                id: randomBytes(8).toString("hex"), at: Date.now(), note, selector: text(input.selector, 300), text: text(input.text, 200),
-                path: path.startsWith("/") ? path : "/", viewport: { width: Number(viewport?.width) || 0, height: Number(viewport?.height) || 0 },
-            }].slice(-MAX_NOTES);
-        this.registry.emit("notes", entry.view.id);
+        this.registry.addNote(entry.view.id, {
+            id: randomBytes(8).toString("hex"), at: Date.now(), note, selector: text(input.selector, 300), text: text(input.text, 200),
+            path: path.startsWith("/") ? path : "/", viewport: { width: Number(viewport?.width) || 0, height: Number(viewport?.height) || 0 },
+        });
         res.writeHead(204);
         res.end();
     }

package/dist/apps/input.js

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

package/dist/apps/inspector.js

@@ -16,7 +16,9 @@ const log=(level,text)=>post({type:'console',level,text:String(text).slice(0,500
 for(const level of ['error','warn']){const original=console[level];console[level]=function(...args){log(level,args.map(fmt).join(' '));return original.apply(this,args);};}
 addEventListener('error',e=>{if(e.message)log('error',e.message+(e.filename?' ('+e.filename.split('/').pop()+':'+e.lineno+')':''));},true);
 addEventListener('unhandledrejection',e=>log('error','Unhandled rejection: '+fmt(e.reason)));
-const route=()=>post({type:'route',path:location.pathname+location.search+location.hash});
+// Taps and keys since this page (or route) loaded: state a retaken picture may lack.
+let interacted=false;
+const route=()=>{interacted=false;post({type:'route',path:location.pathname+location.search+location.hash});};
 for(const name of ['pushState','replaceState']){const original=history[name];history[name]=function(...args){const result=original.apply(this,args);route();return result;};}
 addEventListener('popstate',route);addEventListener('hashchange',route);route();
 const selector=el=>{
@@ -32,48 +34,100 @@ const selector=el=>{
   }
   return parts.join(' > ')||el.localName;
 };
-let box=null,target=null,onPicked=post,host=null;
-// Picks on pointerup: iOS never fires click for a tap on a non-clickable
-// element when only window listens, so click would miss most of the page.
-// While pointing, the app sees none of the gesture, including the click after.
-const SWALLOW=['pointerdown','mousedown','mouseup','touchend','click','dblclick','contextmenu'];
-const swallow=e=>{e.preventDefault();e.stopPropagation();};
-// A second listener, so stopping (which the shell does right after a pick)
-// doesn't also drop the guard on the rest of the tap. The tap's click ends it.
-const aftermath=e=>{swallow(e);if(e.type==='click')listen(false,aftermath);};
-const listen=(on,handler=swallow)=>{
-  const method=on?addEventListener:removeEventListener;
-  if(handler===swallow){method('pointermove',hover,true);method('pointerup',pick,true);method('keydown',key,true);}
-  for(const type of SWALLOW)method(type,handler,true);
-};
-const stop=()=>{box?.remove();box=null;target=null;listen(false);};
+let box=null,layer=null,onPicked=post,host=null;
+// While pointing, a clear layer over the page takes every tap itself, so the
+// app never sees one and no browser's event order matters (iOS sends no click
+// to a window listener for most taps). The element is looked up beneath it.
+const stop=()=>{box?.remove();layer?.remove();box=layer=null;removeEventListener('keydown',key,true);};
+const under=e=>document.elementsFromPoint(e.clientX,e.clientY).find(el=>el!==layer&&el!==box&&el!==host);
 const hover=e=>{
-  const el=document.elementFromPoint(e.clientX,e.clientY);
-  if(!el||el===box||el===host)return;target=el;const r=el.getBoundingClientRect();
+  const el=under(e);if(!el)return;const r=el.getBoundingClientRect();
   Object.assign(box.style,{left:r.left+'px',top:r.top+'px',width:r.width+'px',height:r.height+'px'});
 };
-const pick=e=>{
-  swallow(e);
-  const el=document.elementFromPoint(e.clientX,e.clientY)||target;stop();
-  // Keep eating the click (and iOS's delayed mouse events) this tap still fires.
-  listen(true,aftermath);setTimeout(()=>listen(false,aftermath),500);
-  if(!el||el===host){onPicked({type:'picked',cancelled:true});return;}const r=el.getBoundingClientRect();
+const report=(el,hold)=>{
+  const r=el.getBoundingClientRect();
   onPicked({type:'picked',selector:selector(el),tag:el.localName,text:(el.innerText||el.getAttribute('aria-label')||el.getAttribute('alt')||'').trim().replace(/\\s+/g,' ').slice(0,200),
     rect:{x:Math.round(r.left),y:Math.round(r.top),width:Math.round(r.width),height:Math.round(r.height)},
-    viewport:{width:innerWidth,height:innerHeight},path:location.pathname+location.search+location.hash});
+    viewport:{width:innerWidth,height:innerHeight},path:location.pathname+location.search+location.hash,hold});
+};
+// A long press picks at once and says so (the shell starts listening); the
+// layer stays until the finger lifts, so the release never reaches the app.
+let press=null,held=false;
+const pick=e=>{
+  e.preventDefault();
+  if(held){held=false;stop();return;}
+  const el=under(e);if(!el)return;stop();report(el,false);
+};
+const down=e=>{
+  hover(e);clearTimeout(press?.timer);held=false;
+  const x=e.clientX,y=e.clientY;
+  press={x,y,timer:setTimeout(()=>{const el=under({clientX:x,clientY:y});if(!el)return;held=true;box?.remove();report(el,true);},450)};
 };
+const move=e=>{hover(e);if(press&&Math.hypot(e.clientX-press.x,e.clientY-press.y)>10)clearTimeout(press.timer);};
+const up=()=>{clearTimeout(press?.timer);press=null;if(held){post({type:'release'});setTimeout(()=>{if(held){held=false;stop();}},0);}};
 const key=e=>{if(e.key==='Escape'){stop();onPicked({type:'picked',cancelled:true});}};
 function startPointing(){
   stop();
   box=document.createElement('div');
   box.setAttribute('aria-hidden','true');
   Object.assign(box.style,{position:'fixed',zIndex:2147483647,pointerEvents:'none',outline:'2px solid Highlight',outlineOffset:'2px',borderRadius:'4px',transition:'all 60ms ease-out'});
-  document.documentElement.append(box);
-  listen(true);
+  // One below the reviewer dock, so its controls stay usable while pointing.
+  layer=document.createElement('div');
+  layer.setAttribute('aria-hidden','true');
+  Object.assign(layer.style,{position:'fixed',inset:0,zIndex:2147483646,cursor:'crosshair',background:'transparent',touchAction:'manipulation',userSelect:'none',webkitUserSelect:'none',webkitTouchCallout:'none'});
+  layer.addEventListener('pointermove',move);layer.addEventListener('pointerdown',down);layer.addEventListener('pointerup',up);layer.addEventListener('pointercancel',up);layer.addEventListener('click',pick);
+  layer.addEventListener('contextmenu',e=>e.preventDefault());
+  document.documentElement.append(layer,box);
+  addEventListener('keydown',key,true);
 }
+for(const type of ['pointerdown','keydown'])addEventListener(type,e=>{if(!layer&&!(host&&e.composedPath?.().includes(host)))interacted=true;},true);
+// Draw (in the shell, over this page): where the page is, what state it holds
+// that a fresh browser on the machine wouldn't, and what's under each mark.
+const signals=()=>{
+  let storage=false;try{storage=localStorage.length+sessionStorage.length>0;}catch{}
+  const edited=[...document.querySelectorAll('input,textarea,select')].some(el=>el.type==='checkbox'||el.type==='radio'?el.checked!==el.defaultChecked:el.localName==='select'?[...el.options].some(o=>o.selected!==o.defaultSelected):el.type!=='hidden'&&el.value!==el.defaultValue);
+  const open=Boolean(document.querySelector('dialog[open],details[open],[aria-expanded="true"],[aria-modal="true"]'));
+  return {storage,cookies:Boolean(document.cookie),interacted,open,edited};
+};
+const drawState=()=>({type:'draw-state',scroll:{x:Math.round(scrollX),y:Math.round(scrollY)},viewport:{width:innerWidth,height:innerHeight},dpr:devicePixelRatio,
+  theme:matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light',path:location.pathname+location.search+location.hash,signals:signals()});
+/** Elements inside a mark (viewport rect): a grid sample, then the largest
+ * element under each hit that sits mostly inside the mark — circling a
+ * button names the button, not the bar it's in. A line through something
+ * falls back to what it crossed. Outermost first, at most eight. */
+const marked=r=>{
+  const hits=new Set();
+  for(let i=0;i<8;i++)for(let j=0;j<8;j++){
+    const x=Math.min(innerWidth-1,Math.max(0,r.x+r.width*(i+0.5)/8)),y=Math.min(innerHeight-1,Math.max(0,r.y+r.height*(j+0.5)/8));
+    const el=document.elementsFromPoint(x,y).find(n=>n!==layer&&n!==box&&n!==host);if(el)hits.add(el);
+  }
+  const big=innerWidth*innerHeight*0.6,page=n=>n===document.body||n===document.documentElement;
+  // Where an element's content is: a full-width block around "Total $102"
+  // is judged by its text, which is what a circle goes around.
+  const range=document.createRange();
+  const rectOf=n=>{const b=n.getBoundingClientRect();if(!n.firstChild||/^(img|svg|video|canvas|input|select|textarea|button)$/.test(n.localName))return b;range.selectNodeContents(n);const c=range.getBoundingClientRect();return c.width&&c.height?c:b;};
+  const inside=n=>{const b=rectOf(n),a=b.width*b.height;if(!a)return 0;const w=Math.max(0,Math.min(b.right,r.x+r.width)-Math.max(b.left,r.x)),h=Math.max(0,Math.min(b.bottom,r.y+r.height)-Math.max(b.top,r.y));return w*h/a;};
+  const area=n=>{const b=rectOf(n);return b.width*b.height;};
+  const picked=new Set();
+  for(const hit of hits){let best=null;for(let n=hit;n&&n.nodeType===1&&!page(n);n=n.parentElement){if(inside(n)>=0.6&&area(n)<big)best=n;else if(best)break;}if(best)picked.add(best);}
+  if(!picked.size)for(const hit of hits)if(!page(hit)&&area(hit)<big&&(hit.innerText||'').trim())picked.add(hit);
+  const list=[...picked].filter(n=>![...picked].some(o=>o!==n&&o.contains(n)))
+    .sort((a,b)=>{const p=a.getBoundingClientRect(),q=b.getBoundingClientRect();return p.top-q.top||p.left-q.left;});
+  return list.slice(0,8).map(el=>{const b=el.getBoundingClientRect();return {selector:selector(el).slice(0,300),tag:el.localName,
+    text:(el.innerText||el.getAttribute('aria-label')||el.getAttribute('alt')||'').trim().replace(/\\s+/g,' ').slice(0,120),
+    rect:{x:Math.round(b.left+scrollX),y:Math.round(b.top+scrollY),width:Math.round(b.width),height:Math.round(b.height)}};});
+};
+addEventListener('message',e=>{
+  if(!framed||e.origin!==SHELL||e.source!==parent)return;
+  const d=e.data||{},n=v=>Number.isFinite(+v)?+v:0;
+  if(d.type==='bivy:draw')post(drawState());
+  else if(d.type==='bivy:scroll'){scrollBy({left:n(d.dx),top:n(d.dy),behavior:'instant'});post({type:'scrolled',scroll:{x:Math.round(scrollX),y:Math.round(scrollY)}});}
+  else if(d.type==='bivy:marks'&&d.rect)post({type:'marked',id:n(d.id),elements:marked({x:n(d.rect.x),y:n(d.rect.y),width:n(d.rect.width),height:n(d.rect.height)})});
+});
 addEventListener('message',e=>{
   if(!framed||e.origin!==SHELL||e.source!==parent||e.data?.type!=='bivy:point')return;
-  if(e.data.on)startPointing();else stop();
+  // Held: the layer goes when the finger lifts (see up).
+  if(e.data.on)startPointing();else if(!held)stop();
 });
 if(REVIEWER&&!framed){
   // A shadow root keeps the app's CSS off these controls (and ours off the app).
@@ -84,7 +138,8 @@ if(REVIEWER&&!framed){
     +'button{border:1px solid ButtonBorder;background:ButtonFace;color:ButtonText;border-radius:999px;padding:10px 14px;font-weight:600;cursor:pointer;min-height:44px}'
     +'.primary{background:CanvasText;color:Canvas;border-color:CanvasText}'
     +'form{width:min(340px,calc(100vw - 24px));background:Canvas;color:CanvasText;border:1px solid GrayText;border-radius:14px;padding:12px;box-shadow:0 8px 30px rgb(0 0 0/.25)}'
-    +'textarea{width:100%;min-height:5em;margin:8px 0;border:1px solid GrayText;border-radius:8px;padding:8px;background:Canvas;color:CanvasText;resize:vertical}'
+    // 16px: smaller, and iOS zooms the page in when the note box is focused.
+    +'textarea{width:100%;min-height:5em;margin:8px 0;border:1px solid GrayText;border-radius:8px;padding:8px;background:Canvas;color:CanvasText;resize:vertical;font-size:16px}'
     +'.row{display:flex;justify-content:flex-end;gap:8px}.muted{color:GrayText;font-size:12px;overflow-wrap:anywhere}[hidden]{display:none!important}</style>'
     +'<div class="dock"><p class="muted" role="status" id="status" hidden></p>'
     +'<form id="form" hidden><label for="note">Your note</label><div class="muted" id="about"></div><textarea id="note" required maxlength="1000"></textarea>'

package/dist/apps/macos-display.js

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