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

package/bin/bivy.mjs

@@ -2426,6 +2426,7 @@ async function cmdApp(args = []) {
     console.log(`Usage: bivy app publish <manifest.json> [--session <id>]
        bivy app list [--session <id>]
        bivy app remove <app-id> [--session <id>]
+       bivy app shot [app-id] [--widths 390,1280] [--themes light,dark] [--path /page] [--session <id>]
 
 Manifest: {"version":1,"name":"My app","views":[
   {"kind":"web","name":"Website","source":{"kind":"service","port":3000}},
@@ -2433,19 +2434,39 @@ Manifest: {"version":1,"name":"My app","views":[
 ]}
 
 Static web source: {"kind":"static","directory":"./dist"}
-Publishing does not start commands. Open Apps in the session menu to view or run.
+Server Bivy runs: {"kind":"service","port":5173,"start":{"command":"pnpm","args":["dev"]}}
+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.
 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
+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"].includes(action)) throw new Error("Unknown app command. Run bivy app --help.");
+  if (!["publish", "list", "remove", "shot"].includes(action)) throw new Error("Unknown app command. Run bivy app --help.");
+  const shot = {};
+  if (action === "shot") {
+    for (const flag of ["--widths", "--themes", "--path"]) {
+      const i = rest.indexOf(flag);
+      if (i < 0) continue;
+      const value = rest[i + 1];
+      if (!value || value.startsWith("--")) throw new Error(`${flag} requires a value.`);
+      if (flag === "--widths") shot.widths = value.split(",").map((w) => Number(w.trim()));
+      else if (flag === "--themes") shot.themes = value.split(",").map((t) => t.trim());
+      else shot.path = value;
+      rest.splice(i, 2);
+    }
+  }
   const sessionIndex = rest.indexOf("--session");
   if (sessionIndex >= 0 && (!rest[sessionIndex + 1] || rest[sessionIndex + 1].startsWith("--"))) throw new Error("--session requires an id.");
   const sessionId = resolveAttachSessionId({ sessionFlag: sessionIndex >= 0 ? rest[sessionIndex + 1] : undefined, env: process.env });
   if (!sessionId) throw new Error("Set --session <id> or run inside a Bivy agent session.");
   const positional = rest.filter((_, i) => i !== sessionIndex && (sessionIndex < 0 || i !== sessionIndex + 1));
-  if (positional.some((a) => a.startsWith("-")) || positional.length !== (action === "list" ? 0 : 1)) throw new Error("Invalid arguments. Run bivy app --help.");
-  const body = { sessionId };
+  if (positional.some((a) => a.startsWith("-")) || (action === "shot" ? positional.length > 1 : positional.length !== (action === "list" ? 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") {
     const file = path.resolve(positional[0]);
     if (fs.statSync(file).size > 64 * 1024) throw new Error("App manifest exceeds 64 KiB.");

package/dist/apps/gateway.js

@@ -5,6 +5,7 @@ import { randomBytes } from "node:crypto";
 import path from "node:path";
 import { readFileSync } from "node:fs";
 import { previewShell } from "./preview-shell.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",
     ".css": "text/css; charset=utf-8", ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png",
@@ -15,7 +16,54 @@ const MIME = {
 const COOKIE = "__Host-bivy-preview";
 const OPEN_PATH = "/__bivy/open";
 const REDEEM_PATH = "/__bivy/redeem";
+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. */
+function withInspector(html) {
+    const text = html.toString("utf8");
+    const tag = `<script src="${INSPECTOR_PATH}"></script>`;
+    const at = /<head\b[^>]*>/i.exec(text) ?? /<html\b[^>]*>/i.exec(text);
+    return Buffer.from(at ? text.slice(0, at.index + at[0].length) + tag + text.slice(at.index + at[0].length) : tag + text);
+}
+/** Let the inspector through an app's CSP by exact URL; other sources are unchanged. */
+function allowInspector(policy, url) {
+    const directives = policy.split(";").map((d) => d.trim()).filter(Boolean);
+    const find = (name) => directives.findIndex((d) => d.toLowerCase().split(/\s+/)[0] === name);
+    const index = [find("script-src-elem"), find("script-src")].find((i) => i >= 0) ?? -1;
+    const add = (directive) => directive.replace(/\s'none'/i, "") + " " + url;
+    if (index >= 0)
+        directives[index] = add(directives[index]);
+    else {
+        const fallback = find("default-src");
+        if (fallback < 0)
+            return policy;
+        directives.push(add(directives[fallback].replace(/^default-src/i, "script-src")));
+    }
+    return directives.join("; ");
+}
 const HOUR = 60 * 60_000;
+/** 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";
+/** A top-level or framed page load. Browsers without Fetch Metadata still ask for HTML. */
+function isPageLoad(req) {
+    const dest = req.headers["sec-fetch-dest"];
+    return req.method === "GET" && (dest ? ["document", "iframe"].includes(dest) : /text\/html/.test(req.headers.accept ?? ""));
+}
+/** Served on the app's origin in place of a blank frame. It reloads itself once
+ * the server answers, and tells a framing shell so it can offer next steps. */
+function upstreamDownPage(nonce, port, shellOrigin) {
+    return `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Waiting for the app server</title>
+<style nonce="${nonce}">:root{color-scheme:light dark;font-family:system-ui,sans-serif}body{margin:0;min-height:100vh;display:grid;place-items:center;padding:24px;box-sizing:border-box;text-align:center}main{max-width:32rem}h1{font-size:1.25rem;margin:0 0 8px}p{margin:0;opacity:.75;line-height:1.5}</style>
+<main><h1>Nothing is answering on port ${port}</h1><p role="status">The app server stopped or hasn’t started yet. This page reloads by itself when it’s back.</p></main>
+<script nonce="${nonce}">const tell=state=>{if(parent!==window)parent.postMessage({type:'bivy:upstream',state,port:${port}},${JSON.stringify(shellOrigin)});};tell('down');
+const poll=async()=>{try{const r=await fetch(location.href,{method:'HEAD',cache:'no-store'});if(!r.headers.has('${UPSTREAM_DOWN}')){tell('up');location.reload();return;}}catch{}setTimeout(poll,2000);};setTimeout(poll,2000);</script></html>`;
+}
 /** Copied links are reusable until revoked, capped so a forgotten one lapses. */
 export const SHARE_TTL = 24 * HOUR;
 const HOP = new Set(["connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "transfer-encoding", "upgrade"]);
@@ -41,7 +89,7 @@ function upstreamHeaders(req, origin) {
     headers["x-forwarded-proto"] = "https";
     return headers;
 }
-function responseHeaders(headers, shellOrigin) {
+function responseHeaders(headers, ancestors, inspector) {
     const result = cleanHeaders(headers);
     if (headers["set-cookie"]) {
         result["set-cookie"] = headers["set-cookie"].filter((cookie) => cookie.split("=", 1)[0].trim() !== COOKIE)
@@ -57,13 +105,16 @@ function responseHeaders(headers, shellOrigin) {
     // CSP directives, but replace framing restrictions with this narrower host.
     delete result["x-frame-options"];
     const csp = result["content-security-policy"];
-    const policies = (Array.isArray(csp) ? csp : csp ? [String(csp)] : []).map((policy) => policy.replace(/(^|[;,])\s*frame-ancestors[^;,]*/gi, "$1"));
-    result["content-security-policy"] = [...policies, `frame-ancestors ${shellOrigin}; worker-src 'none'`].join(", ");
+    const policies = (Array.isArray(csp) ? csp : csp ? [String(csp)] : []).flatMap((policy) => policy.split(","))
+        .map((policy) => policy.replace(/(^|;)\s*frame-ancestors[^;]*/gi, "$1"))
+        .map((policy) => inspector ? allowInspector(policy, inspector) : policy);
+    result["content-security-policy"] = [...policies, `frame-ancestors ${ancestors}; worker-src 'none'`].join(", ");
     return result;
 }
 export class AppGateway {
     registry;
     returnOrigins;
+    signIn;
     server;
     template;
     tickets = new Map();
@@ -71,11 +122,15 @@ export class AppGateway {
         ["/__bivy/tokens.css", readFileSync(new URL("./tokens.css", import.meta.url))],
         ["/__bivy/styles.css", readFileSync(new URL("./styles.css", import.meta.url))],
     ]);
+    /** `reviewer`: the browser session came from a copied (shared) link. */
     sessions = new Map();
     sockets = new Map();
-    constructor(registry, originTemplate, returnOrigins = () => []) {
+    /** `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) {
         this.registry = registry;
         this.returnOrigins = returnOrigins;
+        this.signIn = signIn;
         this.template = previewOriginTemplate(originTemplate);
         this.server = http.createServer((req, res) => { void this.handle(req, res).catch(() => { if (!res.headersSent)
             res.writeHead(502); res.end("Preview request failed."); }); });
@@ -86,6 +141,8 @@ export class AppGateway {
     }
     origin(id) { return this.template.replace("{app}", id); }
     shellOrigin(id) { return this.template.replace("{app}", `view-${id}`); }
+    /** Bivy clients may frame the shell (Peek), so app content allows both. */
+    ancestors(id) { return [this.shellOrigin(id), ...this.returnOrigins()].join(" "); }
     open(id, returnTo) {
         const entry = this.requireWeb(id);
         if (returnTo) {
@@ -100,6 +157,14 @@ export class AppGateway {
         // Fragment never reaches reverse-proxy access logs or the application.
         return `${this.shellOrigin(id)}${OPEN_PATH}#${this.grant({ appId: id, expires: Date.now() + 60_000, returnTo })}`;
     }
+    /** The view's stable address: grants nothing by itself. */
+    address(id) { this.requireWeb(id); return `${this.origin(id)}/`; }
+    /** A one-use link straight to the app origin (no shell), for a signed-in
+     * device returning to a stable address. `~path` resumes the page. */
+    openDirect(id) {
+        this.requireWeb(id);
+        return `${this.origin(id)}${OPEN_PATH}#${this.grant({ appId: id, expires: Date.now() + 60_000 })}`;
+    }
     /** A reusable link straight to the app origin (no shell frame), so it opens
      * in any browser and can be inspected. Valid until revoked or SHARE_TTL. */
     share(id) {
@@ -152,12 +217,13 @@ export class AppGateway {
         const entry = this.registry.getView(id);
         return entry?.view.kind === "web" ? entry : undefined;
     }
-    authorize(req, id) {
+    session(req, id) {
         this.sweep();
         const token = (req.headers.cookie ?? "").split(";").map((part) => part.trim()).find((part) => part.startsWith(`${COOKIE}=`))?.slice(COOKIE.length + 1);
-        const session = token && this.sessions.get(token);
-        return session && session.appId === id ? session.expires : undefined;
+        const session = token ? this.sessions.get(token) : undefined;
+        return session?.appId === id ? session : undefined;
     }
+    authorize(req, id) { return this.session(req, id)?.expires; }
     track(id, socket, expires) {
         let sockets = this.sockets.get(id);
         if (!sockets) {
@@ -176,7 +242,7 @@ export class AppGateway {
         const origin = this.shellOrigin(id);
         const nonce = randomBytes(16).toString("hex");
         res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
-        res.setHeader("Content-Security-Policy", `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'self' 'nonce-${nonce}'; connect-src 'self'; frame-src ${this.origin(id)}; frame-ancestors 'none'; base-uri 'none'; form-action 'none'`);
+        res.setHeader("Content-Security-Policy", `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'self' 'nonce-${nonce}'; connect-src 'self' ${this.origin(id)}; img-src blob:; frame-src ${this.origin(id)}; frame-ancestors ${this.returnOrigins().join(" ") || "'none'"}; base-uri 'none'; form-action 'none'`);
         if (req.method === "GET" && this.styles.has(req.url ?? "")) {
             res.setHeader("Content-Type", "text/css; charset=utf-8");
             res.end(this.styles.get(req.url));
@@ -237,8 +303,13 @@ export class AppGateway {
             const nonce = randomBytes(16).toString("hex");
             res.setHeader("Content-Type", "text/html; charset=utf-8");
             res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
-            res.setHeader("Content-Security-Policy", `default-src 'none'; script-src 'nonce-${nonce}'; connect-src 'self'; frame-ancestors ${this.shellOrigin(id)}; base-uri 'none'`);
-            res.end(`<!doctype html><html lang="en"><meta name="viewport" content="width=device-width"><title>Open Bivy preview</title><p id="status" role="status">Opening preview…</p><script nonce="${nonce}">const ticket=location.hash.slice(1);history.replaceState(null,'',location.pathname);fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body:ticket}).then(r=>{if(!r.ok)throw Error();location.replace('/');}).catch(()=>{document.getElementById('status').textContent='Preview link expired or cookies are blocked. Open a new link from Bivy.';});</script></html>`);
+            res.setHeader("Content-Security-Policy", `default-src 'none'; script-src 'nonce-${nonce}'; connect-src 'self'; frame-ancestors ${this.ancestors(id)}; base-uri 'none'`);
+            // An embedded launch ("e:" prefix) comes from a shell framed inside Bivy.
+            // After redeeming, check the cookie stuck: browsers that refuse framed
+            // cookies are reported to the shell, which falls back to a tab.
+            res.end(`<!doctype html><html lang="en"><meta name="viewport" content="width=device-width"><title>Open Bivy preview</title><p id="status" role="status">Opening preview…</p><script nonce="${nonce}">const [ticket,after='/']=location.hash.slice(1).split('~');history.replaceState(null,'',location.pathname);let next='/';try{next=decodeURIComponent(after);}catch{}if(!next.startsWith('/')||next.startsWith('//'))next='/';
+const fail=blocked=>{if(blocked&&parent!==window)parent.postMessage({type:'bivy:access',state:'blocked'},${JSON.stringify(this.shellOrigin(id))});document.getElementById('status').textContent=blocked?'This browser blocks preview cookies here. Open the preview in a new tab from Bivy.':'Preview link expired or cookies are blocked. Open a new link from Bivy.';};
+fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body:ticket}).then(async r=>{if(!r.ok)return fail(false);const check=await fetch('${REVISION_PATH}?after=-2',{cache:'no-store'});if(!check.ok)return fail(true);location.replace(next);}).catch(()=>fail(false));</script></html>`);
             return;
         }
         if (req.url === REDEEM_PATH && req.method === "POST") {
@@ -257,24 +328,37 @@ export class AppGateway {
                 }
             }
             this.sweep();
-            const grant = this.tickets.get(body);
+            const embedded = body.startsWith("e:");
+            const ticket = embedded ? body.slice(2) : body;
+            const grant = this.tickets.get(ticket);
             if (!grant || grant.appId !== id || this.sessions.size >= 500) {
                 res.writeHead(401);
                 res.end();
                 return;
             }
             if (!grant.reusable)
-                this.tickets.delete(body);
+                this.tickets.delete(ticket);
             // A browser session never outlives the link that created it.
             const expires = Math.min(Date.now() + HOUR, grant.expires);
             const token = randomBytes(32).toString("hex");
-            this.sessions.set(token, { appId: id, expires });
-            res.setHeader("Set-Cookie", `${COOKIE}=${token}; Secure; HttpOnly; SameSite=Lax; Path=/; Max-Age=${Math.max(1, Math.floor((expires - Date.now()) / 1000))}`);
+            this.sessions.set(token, { appId: id, expires, reviewer: grant.reusable === true });
+            // Framed inside Bivy, the cookie is third-party: it must be SameSite=None,
+            // and Partitioned keys it to Bivy's top-level site so no other site can use it.
+            const scope = embedded ? "SameSite=None; Partitioned" : "SameSite=Lax";
+            res.setHeader("Set-Cookie", `${COOKIE}=${token}; Secure; HttpOnly; ${scope}; Path=/; Max-Age=${Math.max(1, Math.floor((expires - Date.now()) / 1000))}`);
             res.writeHead(204);
             res.end();
             return;
         }
         const expires = this.authorize(req, id);
+        // A home-screen visit without access goes through Bivy to sign in, then
+        // comes back to the same page. Framed loads keep the plain message.
+        const signIn = !expires && req.method === "GET" && req.headers["sec-fetch-dest"] === "document" && req.url?.startsWith("/") ? this.signIn?.(entry, req.url) : undefined;
+        if (signIn) {
+            res.writeHead(303, { location: signIn });
+            res.end();
+            return;
+        }
         if (!expires) {
             res.writeHead(401);
             res.end("Preview access expired. Open a new preview link from Bivy.");
@@ -297,6 +381,27 @@ export class AppGateway {
             return;
         }
         this.track(id, req.socket, expires);
+        if (req.url.startsWith(`${REVISION_PATH}?`) && req.method === "GET") {
+            this.revision(req, res, entry);
+            return;
+        }
+        if ((req.url === COMPARE_PATH || req.url.startsWith(`${COMPARE_PATH}/`)) && req.method === "GET") {
+            this.compare(req, res, entry);
+            return;
+        }
+        if (req.url === INSPECTOR_PATH && req.method === "GET") {
+            res.writeHead(200, { "content-type": "text/javascript; charset=utf-8", "cache-control": "no-store" });
+            res.end(inspectorScript(this.shellOrigin(id), this.session(req, id)?.reviewer === true));
+            return;
+        }
+        if (req.url === NOTES_PATH && req.method === "POST") {
+            await this.note(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)
+            entry.lastPath = req.url;
         if (entry.target.kind === "static") {
             if (!["GET", "HEAD"].includes(req.method ?? "")) {
                 res.writeHead(405, { Allow: "GET, HEAD" });
@@ -314,15 +419,27 @@ export class AppGateway {
             }
             if (file.endsWith("/"))
                 file += "index.html";
-            const data = entry.target.files.get(file);
+            let data = entry.target.files.get(file);
+            let status = 200;
+            // Client-side routes: an extensionless page load falls back like common
+            // static hosts do — to 404.html (status 404) when present, else index.html.
+            if (!data && !path.extname(file) && isPageLoad(req)) {
+                const notFound = entry.target.files.get("/404.html");
+                file = notFound ? "/404.html" : "/index.html";
+                data = notFound ?? entry.target.files.get(file);
+                if (notFound)
+                    status = 404;
+            }
             if (!data) {
                 res.writeHead(404);
                 res.end("File not found.");
                 return;
             }
-            const headers = responseHeaders({}, this.shellOrigin(id));
+            const headers = responseHeaders({}, this.ancestors(id));
             headers["content-type"] = MIME[path.extname(file).toLowerCase()] || "application/octet-stream";
-            res.writeHead(200, { ...headers, "content-length": data.length });
+            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);
             return;
         }
@@ -331,17 +448,133 @@ export class AppGateway {
             res.end();
             return;
         }
-        const upstream = http.request({ hostname: "127.0.0.1", port: entry.target.port, path: req.url, method: req.method, headers: upstreamHeaders(req, this.origin(id)) }, (response) => {
-            res.writeHead(response.statusCode ?? 502, responseHeaders(response.headers, this.shellOrigin(id)));
+        const port = entry.target.port;
+        const forward = upstreamHeaders(req, this.origin(id));
+        // Uncompressed HTML so the inspector can be added to page loads.
+        if (inspect)
+            forward["accept-encoding"] = "identity";
+        const upstream = http.request({ hostname: "127.0.0.1", port, path: req.url, method: req.method, headers: forward }, (response) => {
             response.on("error", () => res.destroy());
-            response.pipe(res);
+            const html = inspect && /^text\/html/i.test(response.headers["content-type"] ?? "") && !response.headers["content-encoding"] && Number(response.headers["content-length"] ?? 0) <= MAX_INJECT_BYTES;
+            if (!html) {
+                res.writeHead(response.statusCode ?? 502, responseHeaders(response.headers, this.ancestors(id)));
+                response.pipe(res);
+                return;
+            }
+            const chunks = [];
+            let size = 0;
+            response.on("data", (chunk) => { size += chunk.length; if (size > MAX_INJECT_BYTES) {
+                response.destroy();
+                res.destroy();
+                return;
+            } chunks.push(chunk); });
+            response.on("end", () => {
+                const body = withInspector(Buffer.concat(chunks));
+                const headers = responseHeaders(response.headers, this.ancestors(id), `${this.origin(id)}${INSPECTOR_PATH}`);
+                delete headers["content-length"];
+                res.writeHead(response.statusCode ?? 200, { ...headers, "content-length": body.length });
+                res.end(body);
+            });
         });
         upstream.setTimeout(60_000, () => upstream.destroy(new Error("Preview timed out")));
-        upstream.on("error", () => { if (!res.headersSent)
-            res.writeHead(502, { "content-type": "text/plain" }); res.end("App server unavailable. Start it on the registered port, then reload."); });
+        upstream.on("error", () => {
+            if (res.headersSent) {
+                res.destroy();
+                return;
+            }
+            if (!isPageLoad(req)) {
+                res.writeHead(502, { "content-type": "text/plain", [UPSTREAM_DOWN]: "1" });
+                res.end("App server unavailable. Start it on the registered port, then reload.");
+                return;
+            }
+            const nonce = randomBytes(16).toString("hex");
+            res.writeHead(502, { "content-type": "text/html; charset=utf-8", [UPSTREAM_DOWN]: "1", "content-security-policy": `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; frame-ancestors ${this.ancestors(id)}; base-uri 'none'` });
+            res.end(upstreamDownPage(nonce, port, this.shellOrigin(id)));
+        });
         res.on("close", () => upstream.destroy());
         req.pipe(upstream);
     }
+    /** 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) {
+        let body = "";
+        for await (const chunk of req) {
+            body += chunk.toString();
+            if (body.length > 4096) {
+                res.writeHead(413);
+                res.end();
+                return;
+            }
+        }
+        let input;
+        try {
+            input = JSON.parse(body);
+        }
+        catch {
+            res.writeHead(400);
+            res.end();
+            return;
+        }
+        const text = (value, max) => typeof value === "string" ? value.trim().slice(0, max) : "";
+        const note = text(input.note, 1000);
+        if (!note) {
+            res.writeHead(400);
+            res.end("A note needs some text.");
+            return;
+        }
+        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);
+        res.writeHead(204);
+        res.end();
+    }
+    /** Compare shots for the shell: the list, or one PNG by index. */
+    compare(req, res, entry) {
+        const shots = entry.shots ?? [];
+        const cors = { "access-control-allow-origin": this.shellOrigin(entry.view.id), "access-control-allow-credentials": "true", vary: "Origin" };
+        const index = req.url === COMPARE_PATH ? -1 : Number(req.url.slice(COMPARE_PATH.length + 1));
+        if (index < 0) {
+            res.writeHead(200, { ...cors, "content-type": "application/json" });
+            res.end(JSON.stringify({ shots: shots.map((shot, i) => ({ index: i, revision: shot.revision, at: shot.at })) }));
+            return;
+        }
+        const shot = Number.isInteger(index) ? shots[index] : undefined;
+        if (!shot) {
+            res.writeHead(404, cors);
+            res.end();
+            return;
+        }
+        res.writeHead(200, { ...cors, "content-type": "image/png", "content-length": shot.png.length });
+        res.end(shot.png);
+    }
+    /** Long poll from the trusted shell (same-site, credentialed CORS): answers
+     * when the view's revision differs from `after`, or after 25 seconds. */
+    revision(req, res, entry) {
+        const id = entry.view.id;
+        const after = Number(new URL(req.url, "http://gateway").searchParams.get("after"));
+        let timer;
+        const onRevision = (viewId) => { if (viewId === id)
+            send(); };
+        const cleanup = () => { clearTimeout(timer); this.registry.off("revision", onRevision); };
+        const send = () => {
+            cleanup();
+            if (res.writableEnded || res.destroyed)
+                return;
+            res.writeHead(200, { "content-type": "application/json", "access-control-allow-origin": this.shellOrigin(id), "access-control-allow-credentials": "true", vary: "Origin" });
+            res.end(JSON.stringify({ revision: entry.revision, path: entry.lastPath ?? "/" }));
+        };
+        if (entry.revision !== after) {
+            send();
+            return;
+        }
+        this.registry.on("revision", onRevision);
+        timer = setTimeout(send, 25_000);
+        res.on("close", cleanup);
+    }
     upgrade(req, socket, head) {
         const entry = this.entry(req);
         const expires = entry && this.authorize(req, entry.view.id);
@@ -350,7 +583,8 @@ export class AppGateway {
             return;
         }
         this.track(entry.view.id, socket, expires);
-        const upstream = http.request({ hostname: "127.0.0.1", port: entry.target.port, path: req.url, headers: { ...upstreamHeaders(req, this.origin(entry.view.id)), connection: "Upgrade", upgrade: "websocket" } });
+        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());
         upstream.on("upgrade", (response, peer, upstreamHead) => {
             peer.setTimeout(0);

package/dist/apps/inspector.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+/** Served on the app's own origin and injected into its HTML. It reports only
+ * to the trusted shell that frames it, and everything it reports is untrusted
+ * app data: the shell shows it and turns it into drafts, never into actions.
+ * Agent-neutral: it observes the browser, not the framework or the agent. */
+export function inspectorScript(shellOrigin, reviewer = false) {
+    return `(()=>{
+// Framed by the shell: report to it. Opened from a shared link: offer notes.
+const framed=parent!==window,REVIEWER=${reviewer};
+if(window.__bivyInspector||(!framed&&!REVIEWER))return;window.__bivyInspector=1;
+const SHELL=${JSON.stringify(shellOrigin)};
+const post=m=>{if(!framed)return;try{parent.postMessage(Object.assign({source:'bivy-inspector'},m),SHELL);}catch{}};
+const fmt=v=>{if(v instanceof Error)return v.name+': '+v.message;if(typeof v==='string')return v;try{return JSON.stringify(v);}catch{return String(v);}};
+const log=(level,text)=>post({type:'console',level,text:String(text).slice(0,500),at:Date.now()});
+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});
+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=>{
+  const parts=[];
+  for(let node=el;node&&node.nodeType===1&&node!==document.body&&node!==document.documentElement&&parts.length<4;node=node.parentElement){
+    if(node.id){parts.unshift('#'+CSS.escape(node.id));break;}
+    let part=node.localName;
+    const classes=[...node.classList].filter(c=>!/\\d{3,}|^css-|^_/.test(c)).slice(0,2);
+    if(classes.length)part+='.'+classes.map(c=>CSS.escape(c)).join('.');
+    const same=node.parentElement?[...node.parentElement.children].filter(c=>c.localName===node.localName):[];
+    if(same.length>1)part+=':nth-of-type('+(same.indexOf(node)+1)+')';
+    parts.unshift(part);
+  }
+  return parts.join(' > ')||el.localName;
+};
+let box=null,target=null,onPicked=post,host=null;
+const stop=()=>{box?.remove();box=null;target=null;removeEventListener('pointermove',hover,true);removeEventListener('click',pick,true);removeEventListener('keydown',key,true);};
+const hover=e=>{
+  const el=document.elementFromPoint(e.clientX,e.clientY);
+  if(!el||el===box||el===host)return;target=el;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=>{
+  e.preventDefault();e.stopPropagation();
+  const el=document.elementFromPoint(e.clientX,e.clientY)||target;stop();
+  if(!el||el===host){onPicked({type:'picked',cancelled:true});return;}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});
+};
+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);
+  addEventListener('pointermove',hover,true);addEventListener('click',pick,true);addEventListener('keydown',key,true);
+}
+addEventListener('message',e=>{
+  if(!framed||e.origin!==SHELL||e.source!==parent||e.data?.type!=='bivy:point')return;
+  if(e.data.on)startPointing();else stop();
+});
+if(REVIEWER&&!framed){
+  // A shadow root keeps the app's CSS off these controls (and ours off the app).
+  host=document.createElement('bivy-review');
+  const root=host.attachShadow({mode:'open'});
+  root.innerHTML='<style>:host{all:initial}*{box-sizing:border-box;font:14px/1.4 system-ui,sans-serif}'
+    +'.dock{position:fixed;right:12px;bottom:calc(12px + env(safe-area-inset-bottom));z-index:2147483647;display:flex;flex-direction:column;align-items:flex-end;gap:8px;max-width:calc(100vw - 24px)}'
+    +'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}'
+    +'.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>'
+    +'<div class="row"><button type="button" id="cancel">Cancel</button><button class="primary" id="send">Send note</button></div></form>'
+    +'<button id="leave">Leave a note</button></div>';
+  const $=id=>root.getElementById(id);let picked=null;
+  const say=text=>{$('status').hidden=!text;$('status').textContent=text;};
+  $('leave').onclick=()=>{say('Tap the part of the page your note is about. Escape cancels.');$('leave').hidden=true;startPointing();};
+  onPicked=d=>{
+    $('leave').hidden=false;say('');
+    if(d.cancelled)return;picked=d;
+    $('about').textContent='About: '+(d.text?'“'+d.text.slice(0,80)+'” ':'')+'('+d.selector+')';
+    $('form').hidden=false;$('leave').hidden=true;$('note').focus();
+  };
+  $('cancel').onclick=()=>{$('form').hidden=true;$('leave').hidden=false;};
+  $('form').onsubmit=async e=>{
+    e.preventDefault();
+    const r=await fetch('/__bivy/notes',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify(Object.assign({},picked,{note:$('note').value}))}).catch(()=>null);
+    if(r&&r.ok){$('note').value='';$('form').hidden=true;$('leave').hidden=false;say('Sent. Thanks — the app’s owner will see it.');setTimeout(()=>say(''),4000);}
+    else say('Couldn’t send the note. Your link may have expired.');
+  };
+  (document.body||document.documentElement).append(host);
+}
+})();`;
+}