@bivy/bivy 0.18.3 → 0.18.4-staging.10

package/README.md

@@ -4,17 +4,22 @@
 [![license: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-2b6cb0)](LICENSE)
 [![node](https://img.shields.io/badge/node-%E2%89%A520-2b6cb0)](https://nodejs.org)
 
-**Run coding agents on your machines and use them from anywhere — from a phone,
-browser, terminal, GitHub issue, Slack message, schedule, or webhook.**
+**Build, try, and review apps from your phone. Your coding agent and dev
+environment stay on your own machines.**
 
-Bivy is an open-source workspace for coding-agent work. Turn prompts, GitHub
-issues, CI failures, Slack messages, and schedules into live sessions on your
-machines. Choose the agent and model, sync supported API keys and OAuth logins,
-and steer and review the work from your browser, phone, or terminal.
+Bivy is an open-source remote development environment built around coding
+agents. Ask for a change, try the running app, and point to or draw on what
+needs fixing. Send that feedback to the agent and try again—all in the same
+session, without going back to your computer.
+
+Live previews bring your app to your phone or browser without deploying it to
+Render, building a Docker image, or setting up a separate preview server.
+Share a preview link so someone else can try it and leave notes, too.
 
 Keep Claude Code, Codex, Pi, OpenCode, or another supported agent. Keep your
-repos, tools, and development environment. Bivy connects them into a workflow
-that doesn't end when you leave your desk.
+repos, tools, databases, and development environment. Bivy connects them to
+chat, a terminal, app previews, and code review wherever you are. Start work
+yourself, or let an issue, CI failure, message, schedule, or webhook start it.
 
 **[Start free on Bivy Cloud](https://app.bivy.sh)** ·
 **[Quickstart](docs/quickstart.md)** ·
@@ -47,11 +52,41 @@ entire remote-access stack.
 > sandboxing depend on the runtime. See the
 > [runtime support matrix](docs/runtime-support-matrix.md).
 
-## More than remote access
-
-Remote access lets you reach an agent. Bivy also connects **what starts the
-work, where it runs, which agent and credentials it uses, and how you review
-what happened**.
+## Build → preview → mark up → iterate
+
+Remote chat lets you ask an agent for a change. Bivy also lets you **use what
+it built and show it what to fix**, without a separate deployment step.
+
+1. **Ask for a change.** The agent works in your repo with your existing tools
+   and local services.
+2. **Try the app.** Open a live preview from the session. Use the running app,
+   not just a screenshot of what the agent says it finished. Bivy can discover
+   dev servers running in the session workspace; tap **Preview** to open one.
+3. **Mark up what needs work.** Point at an element or circle and draw on the
+   preview. Add a note, then send the draft to the agent with the element and
+   page context. Marked-up screenshots and before/after comparison are available
+   when agent screenshots are enabled.
+4. **Iterate and review.** Try the next version, inspect the diff, review checks,
+   and decide when the work is ready—not just when the agent stops.
+5. **Bring someone else into the review.** Copy a public preview link so they
+   can use the app without a Bivy account and leave notes on specific elements.
+   Bring their notes into the session when you're ready to act on them.
+
+On Bivy Cloud, preview delivery is built in: no per-app domains, certificates,
+public ports, or tunnels to configure. Self-hosters configure preview delivery
+once for their Bivy deployment, not for every app. The app still needs its normal
+build or dev-server setup, and **the machine serving it must stay awake and
+online**. These are development previews, not production hosting.
+
+**Share deliberately:** anyone with a preview link can use that app, including
+its live backend. Links expire after 24 hours and can be revoked sooner.
+Reviewer notes aren't sent to the agent automatically; you send them or explicitly
+allow agent access. Preview traffic uses HTTPS through the preview relay, not
+session end-to-end encryption; the relay operator can see it.
+
+[App previews, visual feedback, and sharing →](docs/apps.md)
+
+## Your agents and machines, one workspace
 
 | Capability | What it means for you |
 |---|---|
@@ -59,8 +94,10 @@ what happened**.
 | **Your machines and environment** | Work beside your existing repos, dev servers, databases, private networks, toolchains, and GPUs. |
 | **Automations and triggers** | Let issues, failed CI, messages, schedules, and webhooks start work instead of copying requests into a chat. |
 | **Encrypted key and OAuth sync** | Reuse Bivy-managed provider credentials across enrolled machines and compatible runtimes, with less repeated setup. |
-| **Live sessions from anywhere** | Start at your desk, answer a question or approve an action from your phone, then return to the terminal. |
-| **Reviewable results** | See changes, declared checks, artifacts, and pull requests—not just an agent's claim that it finished. |
+| **Live sessions from anywhere** | Build and review from your phone, browser, or terminal; answer questions and approve supported actions in the same session. |
+| **Live app previews** | Try the running app without deploying it to a separate hosting service. |
+| **Visual feedback and sharing** | Point, draw, and send specific feedback to the agent; share a preview link for outside review. |
+| **Reviewable results** | Inspect the app, changes, declared checks, artifacts, and pull requests—not just an agent's claim that it finished. |
 | **Hosted convenience or self-hosting** | Use Bivy Cloud for managed remote access, or run the same open-source core yourself. |
 
 ## One workflow, from trigger to review
@@ -77,7 +114,13 @@ Prompt · GitHub issue · CI failure · Linear · Slack · Schedule · Webhook
                      Join · steer · approve · stop
                                  │
                                  ▼
-                    Changes · checks · artifacts · PR
+                  Try app · inspect changes · checks
+                                 │
+                                 ▼
+                  Mark up · send feedback · iterate
+                                 │
+                                 ▼
+                      Share preview · review PR
 ```
 
 A **Machine** is a computer or server you connect. A **Session** is live agent
@@ -206,10 +249,9 @@ answer questions, approve supported tool calls, or stop the agent.
 
 - Send screenshots, images, logs, and other files from your phone.
 - Download reports and artifacts the agent creates.
-- Publish [session apps](docs/apps.md) with web and CLI/TUI views using
-  `bivy app publish bivy.app.json`. Linked machines automatically discover web
-  preview delivery through Bivy's relay—no per-machine domains, certificates or
-  public ports. Terminal views use the existing connection.
+- Open [session apps](docs/apps.md) from chat or the **Apps** menu: live web
+  previews, desktop app views, and CLI/TUI tools. Agents can publish views with
+  `bivy app publish bivy.app.json` and create share links with `bivy app share`.
 - Use voice input and read-aloud where supported; provider-backed voice may
   send audio or text to the selected provider.
 - Keep a native terminal workflow or use structured chat, depending on the agent.
@@ -259,8 +301,13 @@ bivy run claude
 bivy open
 ```
 
-Open that same session on your phone while it runs. Once that works, connect
-another machine or add your first automation.
+Open that same session on your phone while it runs. For a web app, ask the agent
+to start its dev server, then open **Apps → Running in this workspace → Preview**.
+Try a page, point to something you'd change, and send the feedback back to the
+agent. No separate preview deployment needed.
+
+Once that works, share a preview for review, connect another machine, or add
+your first automation.
 
 **Local-only works too.** `bivy run`, `bivy resume`, and `bivy sessions` need no
 account or server. Choose **local only for now** during setup; use `bivy login`
@@ -327,9 +374,14 @@ Your machine                         Hosted or self-hosted
 
 - **Execution stays on your machine.** Bivy Cloud does not run your agents.
   Your model provider still sees whatever the agent sends it.
-- **Interactive traffic is end-to-end encrypted** between the node and paired
-  devices. The relay forwards opaque frames; your node dials out, so no inbound
-  public port is required.
+- **Interactive session traffic is end-to-end encrypted** between the node and
+  paired devices. The relay forwards opaque session frames; your node dials out,
+  so no inbound public port is required.
+- **App previews have a separate security boundary.** Preview traffic uses HTTPS
+  and an outbound tunnel, not session E2E encryption. The preview ingress/relay
+  operator can see it. Public preview links grant anyone holding them access to
+  that view and its live backend until expiry or revocation. See
+  [preview security and sharing](docs/apps.md#runtime-and-security-boundaries).
 - **Ordinary credential sync uploads ciphertext, not plaintext keys.**
   Supported credentials and recovery limits are documented separately.
 - **Encryption is not universal across integrations.** Slack commands and

package/bin/codex-app-server-shim.mjs

@@ -528,7 +528,12 @@ async function onBivyCommand(msg) {
         bivy({ replyTo: id, ok: true });
         asRequest("turn/start", {
           threadId,
-          input: [{ type: "text", text: String(msg.text ?? "") }],
+          input: [
+            { type: "text", text: String(msg.text ?? "") },
+            ...(msg.images ?? []).map((image) => ({
+              type: "image", url: `data:${image.mimeType || "image/png"};base64,${image.data}`,
+            })),
+          ],
           ...(selectedModel ? { model: selectedModel } : {}),
         })
           .catch((error) => bivy({ type: "session.error", error: error instanceof Error ? error.message : String(error) }));

package/dist/apps/gateway.js

@@ -12,6 +12,7 @@ import { previewShell } from "./preview-shell.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";
+import { readStrokes } from "./annotate.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",
@@ -199,6 +200,7 @@ export class AppGateway {
     registry;
     returnOrigins;
     signIn;
+    captureNote;
     server;
     template;
     tickets = new Map();
@@ -210,13 +212,16 @@ export class AppGateway {
      *  `embedded`: it runs framed inside a Bivy client (a third-party frame). */
     sessions = new Map();
     sockets = new Map();
+    captureAfter = 0;
+    capturing = false;
     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) {
+    constructor(registry, originTemplate, returnOrigins = () => [], signIn, captureNote) {
         this.registry = registry;
         this.returnOrigins = returnOrigins;
         this.signIn = signIn;
+        this.captureNote = captureNote;
         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."); }); });
@@ -253,12 +258,12 @@ export class AppGateway {
         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. */
+    /** Public reviewers use the same isolated controls as the owner, but can
+     * only submit notes. Valid until revoked or SHARE_TTL. */
     share(id) {
         this.requireWeb(id);
         const expiresAt = Date.now() + SHARE_TTL;
-        return { url: `${this.origin(id)}${OPEN_PATH}#${this.grant({ appId: id, expires: expiresAt, reusable: true })}`, expiresAt };
+        return { url: `${this.shellOrigin(id)}${OPEN_PATH}#${this.grant({ appId: id, expires: expiresAt, reusable: true })}`, expiresAt };
     }
     revoke(id) {
         for (const map of [this.tickets, this.sessions])
@@ -366,7 +371,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, ...(entry.target.kind === "display" ? { inspect: false } : {}) }));
+            res.end(JSON.stringify({ name: entry.app.name, origin: this.origin(id), returnTo: grant.returnTo, ...(grant.reusable ? { reviewer: true } : {}), ...(entry.target.kind === "display" ? { inspect: false } : {}) }));
             return;
         }
         res.writeHead(404);
@@ -731,7 +736,7 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
         let body = "";
         for await (const chunk of req) {
             body += chunk.toString();
-            if (body.length > 4096) {
+            if (body.length > 256_000) {
                 res.writeHead(413);
                 res.end();
                 return;
@@ -747,6 +752,16 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
             return;
         }
         const text = (value, max) => typeof value === "string" ? value.trim().slice(0, max) : "";
+        if (!input || typeof input !== "object" || Array.isArray(input)) {
+            res.writeHead(400);
+            res.end();
+            return;
+        }
+        if (input.mark === undefined && input.context === undefined && body.length > 4096) {
+            res.writeHead(413);
+            res.end();
+            return;
+        }
         const note = text(input.note, 1000);
         if (!note) {
             res.writeHead(400);
@@ -755,12 +770,71 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
         }
         const viewport = input.viewport;
         const path = text(input.path, 2048);
+        let shot;
+        if (input.mark !== undefined) {
+            // Public input cannot choose a session, app, Compare image, or capture
+            // dimensions beyond a modest viewport. No agent commands are exposed.
+            if (!this.session(req, entry.view.id)?.reviewer) {
+                res.writeHead(403);
+                res.end();
+                return;
+            }
+            let mark;
+            try {
+                const raw = input.mark;
+                const strokes = readStrokes(raw?.strokes);
+                const v = raw.viewport;
+                if (!Number.isFinite(v?.width) || !Number.isFinite(v?.height) || v.width < 40 || v.width > 4000 || v.height < 40 || v.height > 4000 || v.width * v.height > 4_000_000)
+                    throw Error();
+                const scroll = raw.scroll;
+                if (scroll && (![scroll.x, scroll.y].every(n => Number.isFinite(n) && n >= 0 && n <= 100_000)))
+                    throw Error();
+                if (strokes.some(s => s.points.some(([x, y]) => x < 0 || y < 0 || x > 104_000 || y > 104_000)))
+                    throw Error();
+                // Bound raster work as well as JSON size (long off-screen paths can
+                // otherwise consume CPU even though they paint no visible pixels).
+                const distance = strokes.reduce((total, s) => total + s.points.reduce((length, p, i) => i ? length + Math.hypot(p[0] - s.points[i - 1][0], p[1] - s.points[i - 1][1]) : length, 0), 0);
+                if (distance > 50_000)
+                    throw Error();
+                mark = { appId: entry.app.id, viewId: entry.view.id, strokes, viewport: v, path: text(raw.path, 2048), scroll, dpr: 1, theme: raw.theme === "dark" ? "dark" : "light", signals: { unknown: true } };
+            }
+            catch {
+                res.writeHead(400);
+                res.end("Invalid or oversized annotation. Try fewer marks or a narrower preview.");
+                return;
+            }
+            if (this.capturing || Date.now() < this.captureAfter) {
+                res.writeHead(429);
+                res.end("Please wait a moment before sending another picture.");
+                return;
+            }
+            this.capturing = true;
+            this.captureAfter = Date.now() + 10_000;
+            try {
+                shot = await this.captureNote?.(entry, mark);
+            }
+            catch {
+                res.writeHead(502);
+                res.end("Could not take the picture. Your note has not been sent; please retry.");
+                return;
+            }
+            finally {
+                this.capturing = false;
+            }
+            if (!this.session(req, entry.view.id) || this.registry.getView(entry.view.id) !== entry) {
+                res.writeHead(401);
+                res.end();
+                return;
+            }
+        }
         this.registry.addNote(entry.view.id, {
+            ...(shot ? { shot } : {}),
+            ...(input.context ? { context: text(input.context, 8000) } : {}),
             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();
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify({ screenshot: Boolean(shot) }));
     }
     /** Compare shots for the shell: the list, or one PNG by index. */
     compare(req, res, entry) {

package/dist/apps/inspector.js

@@ -51,7 +51,7 @@ 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,hold});
+    viewport:{width:innerWidth,height:innerHeight},scroll:{x:Math.round(scrollX),y:Math.round(scrollY)},theme:matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light',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.
@@ -123,7 +123,12 @@ const marked=r=>{
 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());
+  if(d.type==='bivy:note'&&REVIEWER){
+    void fetch('/__bivy/notes',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify(d.note)})
+      .then(async r=>{if(!r.ok)throw Error(r.status===429?'Please wait a moment before sending another picture.':r.status===400||r.status===502?(await r.text()).slice(0,200):'Could not send. Check that the link is still valid and try again.');return r.json();})
+      .then(result=>post({type:'note-sent',id:d.id,screenshot:result.screenshot===true}),error=>post({type:'note-sent',id:d.id,error:error.message}));
+  }
+  else 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)})});
 });

package/dist/apps/preview-shell.js

@@ -22,7 +22,7 @@ iframe { width:100%; height:100%; border:0; background:var(--bg); }
 #dock > * { pointer-events:auto; }
 /* The hint sits over the app; a tap on it is meant for the app underneath. */
 #dock > #pointing { pointer-events:none; }
-nav, #draw-bar { display:flex; align-items:center; gap:var(--space-1); max-width:100%; padding:var(--space-1); background:var(--surface); border:thin solid var(--line); border-radius:var(--radius-full); box-shadow:var(--shadow-lg); }
+nav, #draw-bar { display:flex; flex-wrap:wrap; justify-content:center; align-items:center; gap:var(--space-1); max-width:100%; padding:var(--space-1); background:var(--surface); border:thin solid var(--line); border-radius:var(--radius-xl); box-shadow:var(--shadow-lg); }
 nav .btn, #draw-bar .btn { flex-shrink:0; border-radius:var(--radius-full); }
 nav .btn[aria-pressed="true"] { background:var(--accent-soft); color:var(--accent); }
 #name { display:flex; flex-direction:column; min-width:0; padding:0 var(--space-2); }
@@ -46,26 +46,34 @@ nav .btn[aria-pressed="true"] { background:var(--accent-soft); color:var(--accen
 #draft-row { display:flex; align-items:flex-start; gap:var(--space-2); }
 #draft-row #draft-text { flex:1; min-width:0; }
 /* Hold to talk: a phone-sized target that never selects text or opens a callout. */
-#mic { flex:none; inline-size:44px; block-size:44px; padding:0; border-radius:var(--radius-full); touch-action:none; user-select:none; -webkit-user-select:none; -webkit-touch-callout:none; }
+#mic { flex:none; inline-size:var(--space-7); block-size:var(--space-7); padding:0; border-radius:var(--radius-full); touch-action:none; user-select:none; -webkit-user-select:none; -webkit-touch-callout:none; }
 #mic[aria-pressed="true"] { background:var(--accent); border-color:var(--accent); color:var(--accent-contrast); }
-#voice-status { font-size:var(--text-xs); margin:var(--space-2) 0 0; }
-#voice-status:empty { display:none; }
-/* The panel scrolls on a phone; its actions stay in reach at the bottom. */
-#draft .panel-actions { position:sticky; bottom:calc(-1 * var(--space-3)); margin:var(--space-2) calc(-1 * var(--space-3)) calc(-1 * var(--space-3)); padding:var(--space-2) var(--space-3) var(--space-3); background:var(--surface); border-top:thin solid var(--line); }
+#voice-status, #note-status { font-size:var(--text-xs); margin:var(--space-2) 0 0; }
+#voice-status:empty, #note-status:empty { display:none; }
+/* The note owns the dock while editing. Only its body scrolls; actions never
+   cover the text field, even when the keyboard leaves little vertical room. */
+#dock { max-height:calc(100% - var(--space-4)); }
+#dock:has(#draft:not([hidden])) nav, #dock:has(#draft:not([hidden])) #pointing { display:none; }
+#draft { display:flex; flex-direction:column; max-height:70dvh; overflow:hidden; padding:0; }
+#draft-body { min-height:0; overflow:auto; padding:var(--space-3); }
+#draft .panel-actions { flex-shrink:0; margin:0; padding:var(--space-2) var(--space-3); border-top:thin solid var(--line); }
+#draft details { margin-top:var(--space-2); }
+#draft summary { color:var(--muted); font-size:var(--text-sm); cursor:pointer; }
 #draft-hint { font-size:var(--text-xs); margin:var(--space-2) 0 var(--space-1); }
 #draft-context { margin:0; padding:var(--space-2); background:var(--surface-2); border-radius:var(--radius-md); font-family:var(--font-mono); font-size:var(--text-xs); white-space:pre-wrap; overflow-wrap:anywhere; color:var(--muted); }
 #show { position:fixed; right:var(--space-3); bottom:calc(var(--space-3) + env(safe-area-inset-bottom)); z-index:var(--z-sticky); border-radius:var(--radius-full); box-shadow:var(--shadow-lg); }
 /* Draw: marks over the frozen app (or Compare's "after" shot). The layer takes
    every touch, so nothing reaches the app; two fingers scroll the page. */
 #ink { position:fixed; z-index:var(--z-sticky); touch-action:none; cursor:crosshair; user-select:none; -webkit-user-select:none; -webkit-touch-callout:none; }
+/* An HTML hit surface owns gestures even where the SVG has no painted marks. */
+#ink svg { display:block; width:100%; height:100%; pointer-events:none; }
 #ink.frozen { pointer-events:none; cursor:default; }
 #ink .halo { fill:none; stroke:var(--annotate-halo); stroke-width:7; stroke-linecap:round; stroke-linejoin:round; }
 #ink .mark { fill:none; stroke:var(--annotate); stroke-width:4; stroke-linecap:round; stroke-linejoin:round; }
 #dock > #drawing { pointer-events:none; }
 /* Hints float over the app, whose page may be any colour: back them solidly. */
 #dock > .banner.inline[data-tone="accent"] { background:color-mix(in srgb, var(--accent) 14%, var(--surface)); box-shadow:var(--shadow-sm); }
-#draw-bar .btn { min-block-size:44px; }
-#draw-bar .seg-btn { min-block-size:36px; min-inline-size:48px; }
+#dock .btn, #dock .seg-btn, #show, #down .btn { min-block-size:var(--space-7); min-inline-size:var(--space-7); font-size:var(--text-sm); }
 #draw-bar .segmented { flex-shrink:0; }
 #compare-draw { margin-top:var(--space-2); }
 /* Marking a Compare shot: make it big enough to draw on with a thumb. */
@@ -78,7 +86,7 @@ nav .btn[aria-pressed="true"] { background:var(--accent-soft); color:var(--accen
 <div class="banner" data-tone="warn" id="down" hidden><span class="banner-text" id="down-text" role="status"></span><span class="banner-actions"><button class="btn sm" id="ask" hidden>Ask agent to fix</button></span></div>
 <p id="status" role="status">Opening app…</p>
 <div id="stage" data-lens="full"><iframe id="app" title="App preview" hidden sandbox="allow-scripts allow-same-origin allow-forms allow-downloads allow-popups" referrerpolicy="no-referrer"></iframe></div>
-<svg id="ink" hidden aria-hidden="true"></svg>
+<div id="ink" hidden aria-hidden="true"><svg id="ink-marks"></svg></div>
 <div id="dock">
   <section class="panel" id="console" hidden aria-labelledby="console-title">
     <h2><span id="console-title">Console</span><button class="btn sm ghost" id="clear">Clear</button></h2>
@@ -93,12 +101,15 @@ nav .btn[aria-pressed="true"] { background:var(--accent-soft); color:var(--accen
     <button class="btn sm" id="compare-draw" type="button" hidden>Draw on “now”</button>
   </section>
   <section class="panel" id="draft" hidden aria-labelledby="draft-title">
-    <h2 id="draft-title">Draft for the agent</h2>
+    <div id="draft-body">
+    <h2 id="draft-title">Note for the agent</h2>
     <div id="draft-row"><textarea class="field" id="draft-text" aria-label="What should change?" placeholder="What should change?"></textarea>
     <button class="btn" id="mic" type="button" hidden aria-pressed="false" aria-label="Speak" title="Hold to speak, or tap to start and stop"><svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 15.5a3 3 0 003-3V6a3 3 0 10-6 0v6.5a3 3 0 003 3z"/><path d="M6 11.5v1a6 6 0 0012 0v-1M12 18.5V21M9 21h6"/></svg></button></div>
     <p class="muted" id="voice-status" role="status"></p>
-    <p class="muted" id="draft-hint">Sent with this context from the preview. Nothing is sent until you send it in the chat.</p>
-    <pre id="draft-context"></pre>
+    <p class="muted" id="draft-hint">Review in chat before sending.</p>
+    <p class="muted" id="note-status" role="status"></p>
+    <details id="draft-details"><summary>Preview context</summary><pre id="draft-context"></pre></details>
+    </div>
     <div class="panel-actions"><button class="btn sm ghost" id="draft-cancel">Cancel</button><button class="btn sm primary" id="draft-add">Add to chat</button></div>
   </section>
   <p class="banner inline" data-tone="accent" id="pointing" role="status" hidden>Tap anything in the app to point at it. <span id="pointing-voice" hidden>Hold to point and speak. </span>Press Escape or Point again to stop.</p>
@@ -136,9 +147,16 @@ const embedded=parent!==window;
 const toBivy=m=>parent.postMessage(Object.assign({source:'bivy-preview'},m),location.ancestorOrigins?.[0]||new URL(metadata.returnTo).origin);
 const storageKey='bivy-preview';
 const safePath=p=>typeof p==='string'&&p.startsWith('/')&&!p.startsWith('//')&&p.length<=2048?p:'/';
-const open=(path,message)=>{status.hidden=false;status.textContent=message;resetConsole();frame.src=metadata.origin+safePath(path);};
+const reviewerTools=ready=>{if(metadata?.reviewer)for(const id of ['point','draw','errors'])$(id).disabled=!ready;};
+const open=(path,message)=>{status.hidden=false;status.textContent=message;resetConsole();reviewerTools(false);frame.src=metadata.origin+safePath(path);};
 function show(data,launch){
   metadata=data;
+  if(data.reviewer){
+    drawOk=data.inspect!==false;$('draw').hidden=!drawOk;back.hidden=true;
+    $('draft-title').textContent='Note for the app’s owner';
+    $('draft-text').maxLength=1000;
+    $('send-errors').textContent='Leave a note…';
+  }
   $('title').textContent=data.name;
   $('title').title=data.name;
   document.title='Bivy · '+data.name;
@@ -151,8 +169,9 @@ function show(data,launch){
   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+(startPage?'~'+startPage:''):'/');
-  back.hidden=embedded&&Boolean(data.returnTo);
+  back.hidden=Boolean(data.reviewer)||(embedded&&Boolean(data.returnTo));
   for(const b of [reload,$('point'),$('errors')])b.disabled=false;
+  reviewerTools(false);
   status.textContent='Loading app…';
   frame.onload=()=>{status.hidden=true;void loadCompare();if(revision===null){revision=-1;watch();}else if(wake)wake();};
   // A Bivy client framing the shell says whether it can take dictation.
@@ -179,17 +198,23 @@ async function watch(){
     revision=d.revision;retry=0;setTimeout(watch,0);
   }catch{retry=Math.min(30000,(retry||1000)*2);const t=setTimeout(watch,retry);wake=()=>{clearTimeout(t);watch();};}
 }
-// Drafts go to the session's composer; nothing is ever sent from here.
+// Owner drafts go to the session's composer. Reviewer drafts use only the
+// bounded notes endpoint, never the owner's command channel.
 function toChat(text){
   if(embedded)return toBivy({type:'draft',text});
   const to=new URL(metadata.returnTo),session=to.pathname.split('/').pop();
   location.assign(to.origin+'/share?session='+encodeURIComponent(session)+'&text='+encodeURIComponent(text));
 }
+let noteMark=null,pendingNote=null,noteSequence=0;
 function draft(context,listen){
-  panels(null);
+  panels(null);noteMark=null;
+  $('draft-add').disabled=false;
+  $('note-status').textContent='';
+  $('draft-hint').textContent=metadata.reviewer?'Feedback only — no agent runs. Pictures are approximate; if screenshots are off, we save text and mark details.':'Review in chat before sending.';
   $('draft').hidden=false;
-  $('draft-add').textContent=metadata.returnTo?'Add to chat':'Copy';
+  $('draft-add').textContent=metadata.reviewer?'Send note':metadata.returnTo?'Add to chat':'Copy';
   $('draft-context').textContent=context;
+  $('draft-details').open=false;
   const box=$('draft-text');box.value='';
   // Speaking right away: don't raise the keyboard over the draft.
   if(listen)startListening();else box.focus();
@@ -226,15 +251,37 @@ function fromBivy(d){
   else if(d.type==='transcript'){setListening(false);if(typeof d.error==='string')sayVoice(d.error.slice(0,200));else addSpoken(d.text);}
   else if(d.type==='listening'&&d.on===false&&listening){setListening(false);if(voiceStatus.textContent.startsWith('Listening'))sayVoice('');}
 }
-$('draft-cancel').onclick=()=>{cancelListening();$('draft').hidden=true;endDraw();};
+$('draft-cancel').onclick=()=>{const target=marks?$('draw'):point;cancelListening();$('draft').hidden=true;endDraw();target.focus();};
 $('draft-add').onclick=async()=>{
   cancelListening();
-  const note=$('draft-text').value.trim(),text=(note?note+'\\n\\n':'')+$('draft-context').textContent;
+  const note=$('draft-text').value.trim();
+  if(metadata.reviewer){
+    if(!note){$('note-status').textContent='Write a note before sending.';$('draft-text').focus();return;}
+    const mark=marks||noteMark,id=++noteSequence;
+    $('draft-add').disabled=true;$('draft-cancel').disabled=true;$('draft-text').disabled=true;
+    $('note-status').textContent='Sending note…';$('draft-add').textContent='Sending…';
+    const timer=setTimeout(()=>finishNote({id,error:'No reply yet. Your note may have arrived; check the connection before retrying.'}),60000);
+    pendingNote={id,timer};
+    frame.contentWindow?.postMessage({type:'bivy:note',id,note:{note,context:$('draft-context').textContent,selector:mark?.selector||'',text:mark?.text||'',path:mark?.path||currentPath,viewport:mark?.viewport||{width:frame.clientWidth,height:frame.clientHeight},...(mark?{mark}:{})}},metadata.origin);
+    return;
+  }
+  const text=(note?note+'\\n\\n':'')+$('draft-context').textContent;
   // Marks go to the Bivy client, which adds a picture made on the machine.
-  if(marks){const mark=marks;endDraw();return toBivy({type:'annotation',text,mark});}
-  if(metadata.returnTo)return toChat(text);
+  if(marks){const mark=marks;$('draft').hidden=true;endDraw();return toBivy({type:'annotation',text,mark});}
+  if(metadata.returnTo){$('draft').hidden=true;return toChat(text);}
   try{await navigator.clipboard.writeText(text);$('draft-add').textContent='Copied';}catch{$('draft-text').select();}
 };
+$('draft-text').addEventListener('input',()=>{if(!pendingNote)$('note-status').textContent='';});
+function finishNote(d){
+  if(!pendingNote||d.id!==pendingNote.id)return;
+  clearTimeout(pendingNote.timer);pendingNote=null;
+  $('draft-cancel').disabled=false;$('draft-add').disabled=false;$('draft-text').disabled=false;$('draft-add').textContent='Send note';
+  if(d.error){$('note-status').textContent=String(d.error).slice(0,200);return;}
+  $('draft').hidden=true;endDraw();noteMark=null;
+  $('stamp').textContent=d.screenshot?'Note and approximate picture sent':'Note sent without a picture';
+  status.hidden=false;status.textContent=$('stamp').textContent+'. The app’s owner will see it.';
+  point.focus();
+}
 // Console
 let entries=[];
 function resetConsole(){entries=[];renderConsole();}
@@ -263,14 +310,16 @@ function picked(d){
   draft('In the app preview "'+metadata.name+'" (page '+safePath(d.path)+', viewport '+v.width+'×'+v.height+'):\\n'
     +'Element: '+String(d.selector).slice(0,300)+(d.text?' ("'+String(d.text).slice(0,200)+'")':'')+', '+r.width+'×'+r.height+' at '+r.x+','+r.y
     +(errors.length?'\\nRecent errors:\\n'+errors.map(e=>'- '+e.text).join('\\n'):''),d.hold===true&&voice);
+  if(metadata.reviewer){const s=pos(d.scroll);noteMark={path:safePath(d.path),viewport:v,scroll:s,theme:d.theme,selector:String(d.selector).slice(0,300),text:String(d.text||'').slice(0,200),strokes:[{tool:'box',points:[[r.x+s.x,r.y+s.y],[r.x+r.width+s.x,r.y+r.height+s.y]]}]};}
 }
 // Draw: freeze the app and mark what's wrong. Marks are kept in page
 // coordinates (so they stay on the content while two fingers scroll), and
 // the app reports what's under each one. On Done they go into the draft box
 // with that context; Add to chat hands them to the Bivy client, which gets a
-// picture from the machine. Nothing about them goes through this origin's
-// network. Compare's "after" shot can be marked the same way.
-const ink=$('ink'),SVG='http://www.w3.org/2000/svg';
+// picture from the machine. Reviewers instead submit marks with their note;
+// pictures stay on the machine for the owner. Compare's "after" shot can be
+// marked the same way by the owner.
+const ink=$('ink'),inkMarks=$('ink-marks'),SVG='http://www.w3.org/2000/svg';
 let draw=null,marks=null,drawOk=false,nextStroke=0;
 const pos=v=>({x:Number(v?.x)||0,y:Number(v?.y)||0});
 function startDraw(target){
@@ -292,6 +341,7 @@ function startDraw(target){
     current.waiting=d=>{current.waiting=null;current.scroll=pos(d.scroll);current.state={viewport:{width:Math.round(Number(d.viewport?.width))||current.state.viewport.width,height:Math.round(Number(d.viewport?.height))||current.state.viewport.height},dpr:Number(d.dpr)||devicePixelRatio,theme:d.theme==='dark'?'dark':'light',path:safePath(d.path),signals:Object.fromEntries(Object.entries(d.signals||{}).map(([k,v])=>[k,v===true]))};renderInk();};
     frame.contentWindow?.postMessage({type:'bivy:draw'},metadata.origin);
   }
+  for(const b of $('draw-bar').querySelectorAll('[data-tool]'))b.setAttribute('aria-checked',String(b.dataset.tool===draw.tool));
   $('draw-bar').querySelector('[aria-checked="true"]').focus();
   updateDrawBar();renderInk();
 }
@@ -299,7 +349,7 @@ function startDraw(target){
 function placeInk(target){
   const r=(target==='compare'?$('compare-after'):frame).getBoundingClientRect();
   Object.assign(ink.style,{left:r.left+'px',top:r.top+'px',width:r.width+'px',height:r.height+'px'});
-  ink.setAttribute('viewBox','0 0 '+r.width+' '+r.height);
+  inkMarks.setAttribute('viewBox','0 0 '+r.width+' '+r.height);
   return {left:r.left,top:r.top,width:r.width,height:r.height};
 }
 // A rotation or a keyboard moves things: keep the layer on them. (Marks on
@@ -308,7 +358,7 @@ addEventListener('resize',()=>{if(draw&&!draw.done)draw.rect=Object.assign(place
 function endDraw(){
   if(!draw)return;
   delete $('compare').dataset.drawing;
-  draw=null;marks=null;ink.toggleAttribute('hidden',true);ink.replaceChildren();
+  draw=null;marks=null;ink.toggleAttribute('hidden',true);inkMarks.replaceChildren();
   $('drawing').hidden=true;$('draw-bar').hidden=true;document.querySelector('nav').hidden=false;
 }
 function updateDrawBar(){const has=Boolean(draw?.strokes.length);for(const id of ['draw-undo','draw-clear','draw-done'])$(id).disabled=!has;}
@@ -321,7 +371,7 @@ function shape(stroke){
 function renderInk(){
   if(!draw)return;
   const all=[...draw.strokes,...(draw.current?[draw.current]:[])];
-  ink.replaceChildren(...all.flatMap(s=>['halo','mark'].map(c=>{const el=shape(s);el.setAttribute('class',c);return el;})));
+  inkMarks.replaceChildren(...all.flatMap(s=>['halo','mark'].map(c=>{const el=shape(s);el.setAttribute('class',c);return el;})));
 }
 function local(e){const x=e.clientX-draw.rect.left,y=e.clientY-draw.rect.top;return draw.target==='frame'?[Math.round(x+draw.scroll.x),Math.round(y+draw.scroll.y)]:[Math.round(x),Math.round(y)];}
 let scrollAsk=null;
@@ -389,6 +439,7 @@ $('draw-done').onclick=()=>{
 // Compare: screenshots around the agent's last change (agent screenshots on).
 const compareBtn=$('compare-btn');let shots=[],urls=[],compareAfter=-1;
 async function loadCompare(){
+  if(metadata.reviewer)return;
   try{const r=await fetch(metadata.origin+'/__bivy/compare',{credentials:'include',cache:'no-store'});if(!r.ok)return;shots=(await r.json()).shots||[];compareBtn.hidden=shots.length<2;}catch{}
 }
 function panels(open){if(listening)cancelListening();if(draw&&!(open==='compare'&&draw.target==='compare'))endDraw();for(const [id,btn] of [['console','errors'],['compare','compare-btn']]){$(id).hidden=id!==open;$(btn).setAttribute('aria-pressed',String(id===open));}$('draft').hidden=true;}
@@ -431,7 +482,8 @@ addEventListener('message',e=>{
     downText.textContent='Nothing is answering on port '+downPort+'.';
     ask.hidden=!metadata.returnTo;
   }else if(d.source==='bivy-inspector'){
-    if(d.type==='route')currentPath=safePath(d.path);
+    if(d.type==='note-sent'&&metadata.reviewer)finishNote(d);
+    else if(d.type==='route'){currentPath=safePath(d.path);reviewerTools(true);}
     else if(d.type==='console'&&(d.level==='error'||d.level==='warn')){entries.push({level:d.level,text:String(d.text).slice(0,500)});if(entries.length>50)entries.shift();renderConsole();}
     else if(d.type==='picked')picked(d);
     else if(d.type==='release'&&heldAt){heldAt=0;stopListening();}
@@ -441,7 +493,7 @@ addEventListener('message',e=>{
   }
 });
 ask.onclick=()=>toChat('The app preview "'+metadata.name+'" isn’t loading: nothing is answering on port '+downPort+'. Please find out why the server stopped, restart it, and tell me when it’s back.');
-addEventListener('keydown',e=>{if(e.key==='Escape'){if(listening)cancelListening();else if(draw&&!draw.done)endDraw();else if(point.getAttribute('aria-pressed')==='true')pointing(false);else panels(null);}});
+addEventListener('keydown',e=>{if(e.key==='Escape'){if(listening)cancelListening();else if(!$('draft').hidden)$('draft-cancel').click();else if(draw&&!draw.done)endDraw();else if(point.getAttribute('aria-pressed')==='true')pointing(false);else panels(null);}});
 back.onclick=()=>{if(metadata?.returnTo){window.close();setTimeout(()=>location.replace(metadata.returnTo),100);}else{window.close();status.hidden=false;status.textContent='You can close this tab to return to Bivy.';}};
 reload.onclick=()=>{if(metadata)open(currentPath,'Reloading app…');};
 (async()=>{