@bivy/bivy 0.17.3-staging.9 → 0.18.0

package/dist/apps/menu.js

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import net from "node:net";
+const MAX_ITEMS = 3000;
+const MAX_DEPTH = 4;
+const TIMEOUT_MS = 5_000;
+/** A path of titles, top menu first: "File > Export…" or ["File", "Export…"]. */
+export function readMenuPath(input) {
+    const path = typeof input === "string" ? input.split(">").map((part) => part.trim()) : input;
+    if (!Array.isArray(path) || !path.length || path.length > 8 || path.some((part) => typeof part !== "string" || !part || part.length > 200)) {
+        throw new Error("A menu item is a path of titles, like \"File > Save\".");
+    }
+    return path;
+}
+/** Keeps what the display says to known fields and bounded sizes: the menu
+ * comes from the app, so it is data to show, never markup. */
+function clean(items, depth, budget) {
+    if (!Array.isArray(items))
+        return [];
+    const out = [];
+    for (const raw of items) {
+        if (budget.left-- <= 0)
+            break;
+        const item = raw;
+        if (item?.separator === true) {
+            out.push({ separator: true });
+            continue;
+        }
+        if (typeof item?.title !== "string" || !item.title)
+            continue;
+        const entry = { title: item.title.slice(0, 200), enabled: item.enabled === true };
+        if (typeof item.shortcut === "string" && item.shortcut.length <= 20)
+            entry.shortcut = item.shortcut;
+        if (item.checked === true)
+            entry.checked = true;
+        const children = depth < MAX_DEPTH ? clean(item.items, depth + 1, budget) : [];
+        if (children.length)
+            entry.items = children;
+        out.push(entry);
+    }
+    return out;
+}
+/** One request to a display's control socket, one JSON answer. */
+function ask(control, request) {
+    return new Promise((resolve, reject) => {
+        const socket = net.connect(control);
+        let data = "";
+        socket.setTimeout(TIMEOUT_MS, () => socket.destroy(new Error("The app didn't answer in time.")));
+        socket.on("data", (chunk) => { data += chunk; if (data.length > 4 * 1024 * 1024)
+            socket.destroy(new Error("The app's menu is too large.")); });
+        socket.on("error", (error) => reject(error.code ? new Error("The app isn't running.") : error));
+        socket.on("end", () => {
+            try {
+                const answer = JSON.parse(data);
+                if (typeof answer.error === "string")
+                    reject(new Error(answer.error.slice(0, 300)));
+                else
+                    resolve(answer);
+            }
+            catch {
+                reject(new Error("The app's display gave an unreadable answer."));
+            }
+        });
+        socket.end(`${JSON.stringify(request)}\n`);
+    });
+}
+/** The app's menu bar, read now, so enabled and checked states are current. */
+export async function readMenus(control) {
+    const answer = await ask(control, { menu: true });
+    const budget = { left: MAX_ITEMS };
+    return (Array.isArray(answer.menus) ? answer.menus : []).flatMap((menu) => typeof menu?.title === "string" && menu.title ? [{ title: menu.title.slice(0, 200), items: clean(menu.items, 1, budget) }] : []);
+}
+/** Chooses the menu item at `path`, as if picked from the menu bar. */
+export async function pressMenu(control, path) {
+    await ask(control, { press: path });
+}

package/dist/apps/preview-shell.js

@@ -20,8 +20,10 @@ iframe { width:100%; height:100%; border:0; background:var(--bg); }
 /* The pill floats above the app instead of taking a header row from it. */
 #dock { position:fixed; left:var(--space-2); right:var(--space-2); bottom:calc(var(--space-2) + env(safe-area-inset-bottom)); z-index:var(--z-sticky); display:flex; flex-direction:column; align-items:center; gap:var(--space-2); pointer-events:none; }
 #dock > * { pointer-events:auto; }
-nav { 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 .btn { flex-shrink:0; border-radius:var(--radius-full); }
+/* 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 .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); }
 #title { font-size:var(--text-sm); font-weight:var(--weight-semibold); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; max-width:14em; }
@@ -39,10 +41,36 @@ nav .btn[aria-pressed="true"] { background:var(--accent-soft); color:var(--accen
 #compare-hint { font-size:var(--text-xs); margin:var(--space-1) 0 0; }
 #entries { list-style:none; margin:0; padding:0; font-family:var(--font-mono); font-size:var(--text-xs); }
 #entries li { display:flex; gap:var(--space-2); align-items:baseline; padding:var(--space-1) 0; border-top:thin solid var(--line); overflow-wrap:anywhere; }
-#draft-text { width:100%; min-height:5em; box-sizing:border-box; font:inherit; font-size:var(--text-sm); resize:vertical; }
+/* Keeps .field's 16px: smaller, and iOS zooms the shell on focus and stays zoomed. */
+#draft-text { width:100%; min-height:5em; box-sizing:border-box; resize:vertical; }
+#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[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); }
 #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; }
+#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; }
+#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. */
+#compare[data-drawing] #compare-stage img { max-height:min(60vh, 560px); }
+#compare[data-drawing] #compare-slider, #compare[data-drawing] #compare-hint, #compare[data-drawing] #compare-draw { display:none; }
 .label-narrow { display:none; }
 @media (max-width: 699px) { #lens { display:none; } #name { display:none; } .label-wide { display:none; } .label-narrow { display:inline; } }
 [hidden] { display:none !important; }
@@ -50,6 +78,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="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>
@@ -61,31 +90,44 @@ nav .btn[aria-pressed="true"] { background:var(--accent-soft); color:var(--accen
     <h2 id="compare-title">Before and after the agent’s last change</h2>
     <div id="compare-stage"><img id="compare-after" alt="After the agent’s last change"><img id="compare-before" alt="Before the agent’s last change"><input type="range" id="compare-slider" min="0" max="100" value="50" aria-label="Show more of before or after"></div>
     <p class="muted" id="compare-hint">Left of the handle: before. Right: now. Screenshots at phone width.</p>
+    <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>
-    <textarea class="field" id="draft-text" aria-label="What should change?" placeholder="What should change?"></textarea>
+    <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>
     <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. Press Escape or Point again to stop.</p>
+  <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>
+  <p class="banner inline" data-tone="accent" id="drawing" role="status" hidden>Circle or box what’s wrong, then Done. Two fingers scroll the page.</p>
+  <div id="draw-bar" role="toolbar" aria-label="Drawing tools" hidden>
+    <div class="segmented" role="radiogroup" aria-label="Mark with"><button class="seg-btn" type="button" role="radio" aria-checked="true" data-tool="pen">Pen</button><button class="seg-btn" type="button" role="radio" aria-checked="false" data-tool="box">Box</button></div>
+    <button class="btn sm ghost" id="draw-undo" type="button" disabled>Undo</button>
+    <button class="btn sm ghost" id="draw-clear" type="button" disabled>Clear</button>
+    <button class="btn sm ghost" id="draw-cancel" type="button" aria-label="Stop drawing">✕</button>
+    <button class="btn sm primary" id="draw-done" type="button" disabled>Done</button>
+  </div>
   <nav aria-label="Bivy preview controls">
     <button class="btn sm ghost" id="back" aria-label="Back to chat">‹ <span class="label-wide">Back to chat</span><span class="label-narrow">Chat</span></button>
     <span id="name"><span id="title">App preview</span><span id="stamp" class="muted" role="status"></span></span>
     <button class="btn sm ghost" id="hide" aria-label="Hide Bivy controls" title="Hide controls">⌄</button>
     <button class="btn sm ghost" id="point" aria-pressed="false" disabled>Point</button>
+    <button class="btn sm ghost" id="draw" type="button" hidden>Draw</button>
     <button class="btn sm ghost" id="compare-btn" aria-pressed="false" hidden>Compare</button>
     <button class="btn sm ghost" id="errors" aria-pressed="false" aria-label="Console" disabled>Console <span class="badge" data-variant="solid" data-tone="danger" id="error-count" hidden></span></button>
     <div class="segmented" id="lens" role="radiogroup" aria-label="Preview width"><button class="seg-btn" role="radio" aria-selected="true" data-lens="full">Full</button><button class="seg-btn" role="radio" aria-selected="false" data-lens="tablet">Tablet</button><button class="seg-btn" role="radio" aria-selected="false" data-lens="phone">Phone</button></div>
-    <button class="btn sm ghost" id="reload" disabled>Reload</button>
+    <button class="btn sm ghost" id="reload" aria-label="Reload" disabled><span class="label-wide">Reload</span><span class="label-narrow" aria-hidden="true">↻</span></button>
   </nav>
 </div>
 <button class="btn sm" id="show" hidden aria-label="Show Bivy controls">Bivy</button>
 <script nonce="${nonce}">
 const $=id=>document.getElementById(id);
 const frame=$('app'),status=$('status'),back=$('back'),reload=$('reload'),stage=$('stage');
-const ticket=location.hash.slice(1);history.replaceState(null,'',location.pathname);
+// "#ticket~page": a review card opens the preview on the page it shows.
+const [ticket,startPage='']=location.hash.slice(1).split('~');history.replaceState(null,'',location.pathname);
 let metadata,currentPath='/';
 // Peek: framed by a Bivy client, which owns closing and the composer.
 const embedded=parent!==window;
@@ -106,11 +148,13 @@ function show(data,launch){
   // (Set before navigating: the policy is fixed when the frame loads.)
   for(const b of [$('point'),$('errors')])b.hidden=data.inspect===false;
   if(data.inspect===false)frame.allow='clipboard-read; clipboard-write';
-  frame.src=data.origin+(launch?'/__bivy/open#'+(embedded?'e:':'')+launch:'/');
+  frame.src=data.origin+(launch?'/__bivy/open#'+(embedded?'e:':'')+launch+(startPage?'~'+startPage:''):'/');
   back.hidden=embedded&&Boolean(data.returnTo);
   for(const b of [reload,$('point'),$('errors')])b.disabled=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.
+  if(embedded&&data.returnTo)toBivy({type:'hello'});
   // Store navigation metadata only, never tickets or cookies.
   try{sessionStorage.setItem(storageKey,JSON.stringify(data));}catch{}
 }
@@ -139,16 +183,53 @@ function toChat(text){
   const to=new URL(metadata.returnTo),session=to.pathname.split('/').pop();
   location.assign(to.origin+'/share?session='+encodeURIComponent(session)+'&text='+encodeURIComponent(text));
 }
-function draft(context){
+function draft(context,listen){
   panels(null);
   $('draft').hidden=false;
   $('draft-add').textContent=metadata.returnTo?'Add to chat':'Copy';
   $('draft-context').textContent=context;
-  const box=$('draft-text');box.value='';box.focus();
+  const box=$('draft-text');box.value='';
+  // Speaking right away: don't raise the keyboard over the draft.
+  if(listen)startListening();else box.focus();
 }
-$('draft-cancel').onclick=()=>{$('draft').hidden=true;};
+// Point and speak. The Bivy client framing this shell does the listening:
+// audio never reaches this origin, and only the transcript comes back, into
+// the draft box, where it stays editable. Hold to talk, or tap to start and
+// tap again to stop.
+const mic=$('mic'),voiceStatus=$('voice-status');
+let voice=false,listening=false,heldAt=0;
+const sayVoice=text=>{voiceStatus.textContent=text;};
+function setListening(on){listening=on;mic.setAttribute('aria-pressed',String(on));mic.setAttribute('aria-label',on?'Stop and add what you said':'Speak');}
+function startListening(){if(!voice||listening)return;setListening(true);sayVoice('Listening… let go, or tap the mic again, to add what you said.');toBivy({type:'listen',state:'start'});}
+function stopListening(){if(!listening)return;sayVoice('Turning speech into text…');toBivy({type:'listen',state:'stop'});}
+function cancelListening(){if(listening)toBivy({type:'listen',state:'cancel'});setListening(false);sayVoice('');}
+function addSpoken(text){
+  const box=$('draft-text'),said=String(text||'').trim().slice(0,4000);
+  if(!said)return;
+  box.value=box.value.trim()?box.value.trimEnd()+' '+said:said;
+  sayVoice('Added what you said. Edit it, or Add to chat.');
+}
+mic.onpointerdown=e=>{
+  e.preventDefault();
+  if(listening){stopListening();heldAt=0;return;}
+  heldAt=Date.now();try{mic.setPointerCapture(e.pointerId);}catch{}
+  startListening();
+};
+// A short tap keeps listening until the next tap; a hold stops on release.
+mic.onpointerup=mic.onpointercancel=()=>{if(heldAt&&Date.now()-heldAt>400)stopListening();heldAt=0;};
+mic.onclick=e=>{if(e.detail===0){if(listening)stopListening();else startListening();}};
+function fromBivy(d){
+  if(d.type==='draw'){drawOk=d.available===true;$('draw').hidden=!drawOk;$('compare-draw').hidden=!drawOk;}
+  else if(d.type==='voice'){voice=d.available===true;mic.hidden=!voice;$('pointing-voice').hidden=!voice;if(!voice)cancelListening();}
+  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-add').onclick=async()=>{
+  cancelListening();
   const note=$('draft-text').value.trim(),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);
   try{await navigator.clipboard.writeText(text);$('draft-add').textContent='Copied';}catch{$('draft-text').select();}
 };
@@ -167,31 +248,160 @@ $('clear').onclick=resetConsole;
 $('send-errors').onclick=()=>draft('Console output in the app preview "'+metadata.name+'" (page '+currentPath+'):\\n'+entries.slice(-20).map(e=>'- '+e.level+': '+e.text).join('\\n'));
 // Point and tell
 const point=$('point');
-function pointing(on){point.setAttribute('aria-pressed',String(on));$('pointing').hidden=!on;frame.contentWindow?.postMessage({type:'bivy:point',on},metadata.origin);}
+// Pointing again starts a new draft: panels over the app step aside.
+function pointing(on){if(on)panels(null);point.setAttribute('aria-pressed',String(on));$('pointing').hidden=!on;frame.contentWindow?.postMessage({type:'bivy:point',on},metadata.origin);}
 point.onclick=()=>pointing(point.getAttribute('aria-pressed')!=='true');
 function picked(d){
   pointing(false);
   if(d.cancelled)return;
+  // A long press: the draft opens listening, and letting go stops.
+  if(d.hold&&voice)heldAt=Date.now();
   const r=d.rect||{},v=d.viewport||{};
   const errors=entries.filter(e=>e.level==='error').slice(-5);
   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'):''));
+    +(errors.length?'\\nRecent errors:\\n'+errors.map(e=>'- '+e.text).join('\\n'):''),d.hold===true&&voice);
+}
+// 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';
+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){
+  endDraw();if(point.getAttribute('aria-pressed')==='true')pointing(false);
+  if(target==='frame')panels(null);
+  if(target==='compare'){$('compare-slider').value='0';split();$('compare').dataset.drawing='';}
+  // Tools first: they change the layout the marks are measured against.
+  $('drawing').hidden=false;$('draw-bar').hidden=false;document.querySelector('nav').hidden=true;
+  const r=placeInk(target);
+  draw={target,rect:r,scroll:{x:0,y:0},strokes:[],elements:{},tool:'pen',current:null,pointers:new Map(),pan:null,done:false,
+    state:{viewport:{width:Math.round(r.width),height:Math.round(r.height)},dpr:devicePixelRatio,path:currentPath,signals:{}}};
+  ink.style.zIndex=target==='compare'?'calc(var(--z-sticky) + 1)':'';
+  ink.classList.remove('frozen');ink.toggleAttribute('hidden',false);
+  // Where the page is and what state it holds. Without an inspector (a
+  // desktop app, or a page whose policy kept it out) state is unknown.
+  if(target==='frame'&&metadata.inspect!==false){
+    const current=draw;
+    current.state.signals={unknown:true};
+    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);
+  }
+  $('draw-bar').querySelector('[aria-checked="true"]').focus();
+  updateDrawBar();renderInk();
+}
+/** Lays the marking layer over what's marked; returns where that is. */
+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);
+  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
+// the frame are in page pixels, so they follow; the size in use is kept.)
+addEventListener('resize',()=>{if(draw&&!draw.done)draw.rect=Object.assign(placeInk(draw.target),{});});
+function endDraw(){
+  if(!draw)return;
+  delete $('compare').dataset.drawing;
+  draw=null;marks=null;ink.toggleAttribute('hidden',true);ink.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;}
+const onScreen=([x,y])=>draw.target==='frame'?[x-draw.scroll.x,y-draw.scroll.y]:[x,y];
+function shape(stroke){
+  const pts=stroke.points.map(onScreen);
+  if(stroke.tool==='box'){const [a,b]=[pts[0],pts[pts.length-1]];const el=document.createElementNS(SVG,'rect');el.setAttribute('x',Math.min(a[0],b[0]));el.setAttribute('y',Math.min(a[1],b[1]));el.setAttribute('width',Math.abs(b[0]-a[0]));el.setAttribute('height',Math.abs(b[1]-a[1]));el.setAttribute('rx','3');return el;}
+  const el=document.createElementNS(SVG,'polyline');el.setAttribute('points',pts.map(p=>p.join(',')).join(' '));return el;
 }
+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;})));
+}
+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;
+function scrollPage(dx,dy){
+  if(draw?.target!=='frame'||metadata.inspect===false)return;
+  scrollAsk=scrollAsk?{dx:scrollAsk.dx+dx,dy:scrollAsk.dy+dy}:{dx,dy};
+  requestAnimationFrame(()=>{if(!scrollAsk)return;frame.contentWindow?.postMessage(Object.assign({type:'bivy:scroll'},scrollAsk),metadata.origin);scrollAsk=null;});
+}
+const middle=()=>{const p=[...draw.pointers.values()];return {x:(p[0].x+p[1].x)/2,y:(p[0].y+p[1].y)/2};};
+ink.onpointerdown=e=>{
+  if(!draw||draw.done)return;e.preventDefault();try{ink.setPointerCapture(e.pointerId);}catch{}
+  draw.pointers.set(e.pointerId,{x:e.clientX,y:e.clientY});
+  // A second finger scrolls instead: the stroke it interrupted is dropped.
+  if(draw.pointers.size>=2){draw.current=null;draw.pan=middle();renderInk();return;}
+  draw.current={id:nextStroke++,tool:draw.tool,points:[local(e)]};renderInk();
+};
+ink.onpointermove=e=>{
+  if(!draw||!draw.pointers.has(e.pointerId))return;
+  draw.pointers.set(e.pointerId,{x:e.clientX,y:e.clientY});
+  if(draw.pan&&draw.pointers.size>=2){const m=middle();scrollPage(draw.pan.x-m.x,draw.pan.y-m.y);draw.pan=m;return;}
+  const s=draw.current;if(!s)return;const p=local(e);
+  if(s.tool==='box')s.points=[s.points[0],p];
+  else{const last=s.points[s.points.length-1];if(Math.hypot(p[0]-last[0],p[1]-last[1])<2||s.points.length>=2000)return;s.points.push(p);}
+  renderInk();
+};
+ink.onpointerup=ink.onpointercancel=e=>{
+  if(!draw)return;draw.pointers.delete(e.pointerId);if(draw.pointers.size<2)draw.pan=null;
+  const s=draw.current;draw.current=null;
+  if(s&&e.type==='pointerup'){
+    const xs=s.points.map(p=>p[0]),ys=s.points.map(p=>p[1]),w=Math.max(...xs)-Math.min(...xs),h=Math.max(...ys)-Math.min(...ys);
+    if(w>=4||h>=4){
+      draw.strokes.push(s);
+      // Ask what's under it while it's on screen (viewport coordinates).
+      if(draw.target==='frame'&&metadata.inspect!==false){const [x,y]=onScreen([Math.min(...xs),Math.min(...ys)]);frame.contentWindow?.postMessage({type:'bivy:marks',id:s.id,rect:{x,y,width:w,height:h}},metadata.origin);}
+    }
+  }
+  updateDrawBar();renderInk();
+};
+ink.onwheel=e=>{if(!draw||draw.done)return;e.preventDefault();scrollPage(e.deltaX,e.deltaY);};
+for(const b of $('draw-bar').querySelectorAll('[data-tool]'))b.onclick=()=>{if(!draw)return;draw.tool=b.dataset.tool;for(const o of $('draw-bar').querySelectorAll('[data-tool]'))o.setAttribute('aria-checked',String(o===b));};
+$('draw-undo').onclick=()=>{if(!draw)return;const s=draw.strokes.pop();if(s)delete draw.elements[s.id];updateDrawBar();renderInk();};
+$('draw-clear').onclick=()=>{if(!draw)return;draw.strokes=[];draw.elements={};updateDrawBar();renderInk();};
+$('draw-cancel').onclick=()=>endDraw();
+$('draw').onclick=()=>startDraw('frame');
+$('compare-draw').onclick=()=>startDraw('compare');
+$('draw-done').onclick=()=>{
+  if(!draw||!draw.strokes.length)return;
+  const d=draw,st=d.state,seen=new Set(),els=[];
+  for(const s of d.strokes)for(const el of d.elements[s.id]||[]){const key=String(el.selector);if(!seen.has(key)){seen.add(key);els.push(el);}}
+  const bounds=s=>{const xs=s.points.map(p=>p[0]),ys=s.points.map(p=>p[1]);return s.tool+' '+Math.min(...xs)+','+Math.min(...ys)+'–'+Math.max(...xs)+','+Math.max(...ys);};
+  const where=d.target==='compare'?'On the Compare screenshot after the agent’s last change in "'+metadata.name+'"':metadata.inspect===false?'On the desktop app "'+metadata.name+'"':'In the app preview "'+metadata.name+'"';
+  const scrolled=d.target==='frame'&&(d.scroll.x||d.scroll.y)?', scrolled to '+d.scroll.x+','+d.scroll.y:'';
+  const context=where+' (page '+st.path+', viewport '+st.viewport.width+'×'+st.viewport.height+scrolled+'), marked:\\n'
+    +(els.length?els.map(el=>'- '+String(el.selector).slice(0,300)+(el.text?' ("'+String(el.text).slice(0,120)+'")':'')).join('\\n')+'\\n':'')
+    +'Marks ('+(d.target==='compare'?'screenshot':'page')+' px): '+d.strokes.map(bounds).join('; ');
+  const mark=Object.assign({path:st.path,viewport:st.viewport,dpr:st.dpr,strokes:d.strokes.map(s=>({tool:s.tool,points:s.points})),signals:st.signals},
+    d.target==='frame'?{scroll:d.scroll,theme:st.theme}:{compare:compareAfter});
+  // The marks stay on screen, frozen, while you add your words.
+  d.done=true;draw=null;
+  draft(context,false);
+  draw=d;marks=mark;ink.classList.add('frozen');
+  // Compare closed for the draft box: its marks go with it (they're in the context).
+  if(d.target==='compare')ink.toggleAttribute('hidden',true);$('drawing').hidden=true;$('draw-bar').hidden=true;document.querySelector('nav').hidden=false;
+};
 // Compare: screenshots around the agent's last change (agent screenshots on).
-const compareBtn=$('compare-btn');let shots=[],urls=[];
+const compareBtn=$('compare-btn');let shots=[],urls=[],compareAfter=-1;
 async function loadCompare(){
   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){for(const [id,btn] of [['console','errors'],['compare','compare-btn']]){$(id).hidden=id!==open;$(btn).setAttribute('aria-pressed',String(id===open));}$('draft').hidden=true;}
+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;}
 compareBtn.onclick=async()=>{
   if(!$('compare').hidden)return panels(null);
   panels('compare');
   for(const u of urls)URL.revokeObjectURL(u);
   const pick=[shots[shots.length-2],shots[shots.length-1]];
+  compareAfter=pick[1].index;
   urls=await Promise.all(pick.map(async s=>URL.createObjectURL(await (await fetch(metadata.origin+'/__bivy/compare/'+s.index,{credentials:'include'})).blob())));
   const before=$('compare-before'),after=$('compare-after');
   before.src=urls[0];after.src=urls[1];
+  // Drawing on "now" measures the picture, so wait until it's there.
+  $('compare-draw').disabled=true;
+  void Promise.all([before.decode(),after.decode()]).catch(()=>{}).then(()=>{$('compare-draw').disabled=false;});
   split();
 };
 const split=()=>{$('compare-before').style.clipPath='inset(0 '+(100-Number($('compare-slider').value))+'% 0 0)';};
@@ -208,6 +418,8 @@ for(const b of $('lens').querySelectorAll('button'))b.onclick=()=>{
 const down=$('down'),downText=$('down-text'),ask=$('ask');
 let downPort=0;
 addEventListener('message',e=>{
+  // The Bivy client framing this shell (Peek): voice only.
+  if(embedded&&metadata?.returnTo&&e.source===parent&&e.origin===new URL(metadata.returnTo).origin){if(e.data?.source==='bivy')fromBivy(e.data);return;}
   if(!metadata||e.origin!==metadata.origin||e.source!==frame.contentWindow)return;
   const d=e.data||{};
   if(d.type==='bivy:access'&&d.state==='blocked'&&embedded&&metadata.returnTo)toBivy({type:'blocked'});
@@ -220,10 +432,14 @@ addEventListener('message',e=>{
     if(d.type==='route')currentPath=safePath(d.path);
     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();}
+    else if(d.type==='draw-state'&&draw&&draw.waiting){draw.waiting(d);}
+    else if(d.type==='scrolled'&&draw&&draw.target==='frame'){draw.scroll=pos(d.scroll);renderInk();}
+    else if(d.type==='marked'&&draw){draw.elements[Number(d.id)]=Array.isArray(d.elements)?d.elements.slice(0,8):[];}
   }
 });
 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(point.getAttribute('aria-pressed')==='true')pointing(false);else panels(null);}});
+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);}});
 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()=>{

package/dist/apps/preview-stream.js

@@ -5,20 +5,29 @@ import { createWebSocketStream } from "ws";
 /** A bounded HTTP-compatible socket over an outbound WebSocket. Each write is
  * split into small frames; backpressure propagates in both directions. */
 export class PreviewStream extends Duplex {
+    bytes;
     wire;
     timeoutMs = 0;
     timer;
-    constructor(ws) {
+    constructor(ws, bytes) {
         super({ highWaterMark: 64 * 1024 });
+        this.bytes = bytes;
         this.wire = createWebSocketStream(ws, { highWaterMark: 64 * 1024 });
-        this.wire.on("data", (chunk) => { this.touch(); if (!this.push(chunk))
-            this.wire.pause(); });
+        this.wire.on("data", (chunk) => {
+            this.touch();
+            if (this.bytes)
+                this.bytes.fromNode += chunk.length;
+            if (!this.push(chunk))
+                this.wire.pause();
+        });
         this.wire.once("end", () => this.push(null));
         this.wire.once("error", (error) => this.destroy(error));
         this.wire.once("close", () => this.destroy());
     }
     _read() { this.wire.resume(); }
     _write(chunk, encoding, callback) {
+        if (this.bytes)
+            this.bytes.toNode += chunk.length;
         let offset = 0;
         const next = (error) => {
             if (error || offset >= chunk.length) {
@@ -39,6 +48,8 @@ export class PreviewStream extends Duplex {
         this.wire.destroy();
         callback(error);
     }
+    /** Read by http.Agent when it parks a kept-alive socket. */
+    get timeout() { return this.timeoutMs; }
     setTimeout(ms, callback) {
         this.timeoutMs = ms;
         this.touch();
@@ -48,6 +59,9 @@ export class PreviewStream extends Duplex {
     }
     setNoDelay() { return this; }
     setKeepAlive() { return this; }
+    // http.Agent refs a pooled socket while in use; timers here are already unref'd.
+    ref() { return this; }
+    unref() { return this; }
     touch() {
         clearTimeout(this.timer);
         if (this.timeoutMs) {

package/dist/apps/registry.js

@@ -4,9 +4,19 @@ import fs from "node:fs";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
 import { EventEmitter } from "node:events";
+import { REVIEW_CARD_MODES } from "./types.js";
 const MAX_BYTES = 25 * 1024 * 1024;
+/** Reviewer notes kept per view; the oldest drop first. */
+export const MAX_NOTES = 50;
 const MAX_TOTAL_BYTES = 100 * 1024 * 1024;
 const MAX_FILES = 2000;
+/** Stored notes are re-read from disk: keep only well-formed ones, bounded as when they arrived. */
+const isNote = (value) => {
+    const note = value;
+    return !!note && typeof note.id === "string" && typeof note.at === "number" && typeof note.note === "string" && note.note.length <= 1000
+        && typeof note.selector === "string" && typeof note.text === "string" && typeof note.path === "string"
+        && typeof note.viewport?.width === "number" && typeof note.viewport?.height === "number";
+};
 const sameFiles = (a, b) => a.size === b.size && [...a].every(([key, data]) => b.get(key)?.equals(data));
 /** Snapshot, not a live filesystem server: symlinks and hidden files are never published. */
 function snapshot(workspace, directory) {
@@ -116,7 +126,7 @@ export class AppRegistry extends EventEmitter {
                 continue;
             // A workspace that moved or a build that vanished drops that app, not the rest.
             try {
-                this.publish(record.sessionId, record.workspace, { ...record.manifest, views: keep.map((k) => k.spec) }, { id: record.id, viewIds: keep.map((k) => k.id), createdAt: record.createdAt });
+                this.publish(record.sessionId, record.workspace, { ...record.manifest, views: keep.map((k) => k.spec) }, { id: record.id, viewIds: keep.map((k) => k.id), createdAt: record.createdAt, reviewMode: record.reviewMode, agentNotes: record.agentNotes, notes: record.notes });
             }
             catch { /* skipped */ }
         }
@@ -148,7 +158,7 @@ export class AppRegistry extends EventEmitter {
         if (this.apps.size >= 50)
             throw new Error("Remove an app before publishing more (limit: 50).");
         const id = (i) => (i === undefined ? restore?.id : restore?.viewIds[i]) ?? randomBytes(16).toString("hex");
-        const app = { id: id(), sessionId, name: name(input.name), views: [], createdAt: restore?.createdAt ?? Date.now() };
+        const app = { id: id(), sessionId, name: name(input.name), views: [], createdAt: restore?.createdAt ?? Date.now(), ...(restore?.reviewMode && REVIEW_CARD_MODES.includes(restore.reviewMode) ? { reviewMode: restore.reviewMode } : {}), ...(restore?.agentNotes === true ? { agentNotes: true } : {}) };
         const entries = [];
         let total = [...this.views.values()].reduce((sum, item) => sum + (item.target.kind === "static" ? item.target.bytes : 0), 0);
         for (const [index, spec] of input.views.entries()) {
@@ -186,19 +196,22 @@ export class AppRegistry extends EventEmitter {
             else
                 throw new Error("Unsupported app view. Supported views: web, terminal and display.");
             app.views.push(view);
-            entries.push({ app, view, target, revision: 0, source });
+            const stored = restore?.notes?.[view.id];
+            const notes = view.kind === "web" && Array.isArray(stored) ? stored.filter(isNote).slice(-MAX_NOTES) : [];
+            entries.push({ app, view, target, revision: 0, source, ...(notes.length ? { notes } : {}) });
         }
         // Commit all views together: a bad later view cannot leave a partial app.
         this.apps.set(app.id, app);
         for (const entry of entries)
             this.views.set(entry.view.id, entry);
-        this.persisted.set(app.id, { sessionId, workspace, manifest: structuredClone(input), id: app.id, viewIds: app.views.map((v) => v.id), createdAt: app.createdAt });
+        this.persisted.set(app.id, { sessionId, workspace, manifest: structuredClone(input), id: app.id, viewIds: app.views.map((v) => v.id), createdAt: app.createdAt, ...(app.reviewMode ? { reviewMode: app.reviewMode } : {}), ...(app.agentNotes ? { agentNotes: true } : {}) });
+        this.persistNotes(app.id);
         if (!restore)
             this.save();
         return structuredClone(app);
     }
     list(sessionId) {
-        return structuredClone([...this.apps.values()].filter((app) => app.sessionId === sessionId));
+        return structuredClone([...this.apps.values()].filter((app) => sessionId === undefined || app.sessionId === sessionId));
     }
     getView(id) { return this.views.get(id); }
     /** An agent turn changed files: re-take changed static snapshots and bump
@@ -253,6 +266,64 @@ export class AppRegistry extends EventEmitter {
             throw new Error("View not found in this app.");
         return view;
     }
+    /** Review cards for this app: remembered across sessions' restarts. */
+    setReviewMode(sessionId, id, mode) {
+        if (!REVIEW_CARD_MODES.includes(mode))
+            throw new Error("Preview cards are ready, every or off.");
+        const app = this.require(sessionId, id);
+        app.reviewMode = mode;
+        const record = this.persisted.get(id);
+        if (record)
+            record.reviewMode = mode;
+        this.save();
+    }
+    reviewMode(id) { return this.apps.get(id)?.reviewMode ?? "ready"; }
+    /** Whether agents may read this app's reviewer notes. Only the owner's app sets it. */
+    setAgentNotes(sessionId, id, enabled) {
+        const app = this.require(sessionId, id);
+        if (enabled)
+            app.agentNotes = true;
+        else
+            delete app.agentNotes;
+        const record = this.persisted.get(id);
+        if (record) {
+            if (enabled)
+                record.agentNotes = true;
+            else
+                delete record.agentNotes;
+        }
+        this.save();
+    }
+    agentNotes(id) { return this.apps.get(id)?.agentNotes === true; }
+    /** A reviewer's note: kept bounded, saved with the app, announced (`notes`). */
+    addNote(viewId, note) {
+        const entry = this.views.get(viewId);
+        if (!entry || entry.view.kind !== "web")
+            return;
+        entry.notes = [...(entry.notes ?? []), note].slice(-MAX_NOTES);
+        this.persistNotes(entry.app.id);
+        this.save();
+        this.emit("notes", viewId);
+    }
+    clearNotes(viewId) {
+        const entry = this.views.get(viewId);
+        if (!entry?.notes)
+            return;
+        delete entry.notes;
+        this.persistNotes(entry.app.id);
+        this.save();
+    }
+    persistNotes(appId) {
+        const record = this.persisted.get(appId);
+        const app = this.apps.get(appId);
+        if (!record || !app)
+            return;
+        const notes = Object.fromEntries(app.views.map((view) => [view.id, this.views.get(view.id)?.notes]).filter(([, list]) => Array.isArray(list) && list.length));
+        if (Object.keys(notes).length)
+            record.notes = notes;
+        else
+            delete record.notes;
+    }
     remove(sessionId, id) {
         const app = this.require(sessionId, id);
         for (const view of app.views)