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

package/dist/apps/gateway.js

@@ -14,6 +14,8 @@ import { pressMenu, readMenuPath, readMenus } from "./menu.js";
 import { inspectorScript } from "./inspector.js";
 import { readStrokes, readElementScrolls } from "./annotate.js";
 import { contentType } from "./mime.js";
+import { loadScenarios, matchRule, planScenario, scenariosFor, summarize } from "./scenarios.js";
+import { simulate } from "./scenario-proxy.js";
 const COOKIE = "__Host-bivy-preview";
 const OPEN_PATH = "/__bivy/open";
 const REDEEM_PATH = "/__bivy/redeem";
@@ -21,6 +23,10 @@ const REVISION_PATH = "/__bivy/revision";
 const INSPECTOR_PATH = "/__bivy/inspector.js";
 const COMPARE_PATH = "/__bivy/compare";
 const NOTES_PATH = "/__bivy/notes";
+const SERVER_ERRORS_PATH = "/__bivy/server-errors";
+const SCENARIOS_PATH = "/__bivy/scenarios";
+const SCENARIO_PATH = "/__bivy/scenario";
+const scenarioKind = (entry) => entry.target.kind === "display" ? "desktop" : "web";
 /** 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. */
@@ -205,9 +211,6 @@ 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.
-     *  `viewOnly`: that link came without the reviewer tools.
-     *  `embedded`: it runs framed inside a Bivy client (a third-party frame). */
     sessions = new Map();
     sockets = new Map();
     /** Connections opened by people with a copied link, so Stop sharing can end
@@ -486,6 +489,11 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
             res.end("Preview access expired. Open a new preview link from Bivy.");
             return;
         }
+        // The shell (its own origin) chooses this browser's scenario; nothing else may.
+        if (req.url === SCENARIO_PATH && req.method === "POST") {
+            await this.enterScenario(req, res, entry, session);
+            return;
+        }
         // Block cross-site mutations even if a client sends the preview cookie.
         if (!["GET", "HEAD"].includes(req.method ?? "") && req.headers.origin !== this.origin(id)) {
             res.writeHead(403);
@@ -511,6 +519,14 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
             this.compare(req, res, entry);
             return;
         }
+        if (req.url.startsWith(SERVER_ERRORS_PATH) && req.method === "GET") {
+            this.serverErrors(req, res, entry, session);
+            return;
+        }
+        if (req.url === SCENARIOS_PATH && req.method === "GET") {
+            this.scenarios(res, entry, session);
+            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), session.reviewer === true && !session.viewOnly, session.embedded === true));
@@ -530,7 +546,19 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
             await this.display(req, res, entry);
             return;
         }
+        const rule = session.scenario && matchRule(session.scenario.network, req.method, req.url);
+        if (rule && await simulate(req, res, rule, responseHeaders({}, this.ancestors(id))))
+            return;
         const inspect = isPageLoad(req);
+        // What the person does in the preview marks the app's logs ("your last
+        // action"): opening a page, or sending something. Assets don't count.
+        const pathOnly = req.url.split("?")[0].slice(0, 200);
+        if (inspect) {
+            entry.loadedAt = Date.now();
+            this.registry.emit("action", id, `Opened ${pathOnly}`);
+        }
+        else if (!["GET", "HEAD", "OPTIONS"].includes(req.method ?? ""))
+            this.registry.emit("action", id, `${req.method} ${pathOnly} from the preview`);
         // 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;
@@ -871,6 +899,96 @@ fetch('${REDEEM_PATH}',{method:'POST',headers:{'Content-Type':'text/plain'},body
         res.writeHead(200, { "content-type": "application/json" });
         res.end(JSON.stringify({ screenshot: Boolean(shot) }));
     }
+    /** Server errors for the shell's Console: since the page loaded ("page"),
+     *  or since the last answer's `now`. The owner's only: a server's log is not
+     *  for people with a shared link. */
+    serverErrors(req, res, entry, session) {
+        const cors = { "access-control-allow-origin": this.shellOrigin(entry.view.id), "access-control-allow-credentials": "true", vary: "Origin" };
+        if (session.reviewer) {
+            res.writeHead(403, cors);
+            res.end();
+            return;
+        }
+        const raw = new URL(req.url, "http://gateway").searchParams.get("since");
+        const since = raw === "page" || raw === null ? (entry.loadedAt ?? Date.now()) - 1 : Number(raw);
+        const found = Number.isFinite(since) ? this.registry.serverErrors?.(entry.view.id, since) : undefined;
+        res.writeHead(200, { ...cors, "content-type": "application/json", "cache-control": "no-store" });
+        res.end(JSON.stringify(found ?? { now: Date.now(), lines: [] }));
+    }
+    /** The view's scenarios for the shell's switcher, and the one it's in: this
+     *  browser's for a web page, the app's for a desktop app. */
+    scenarios(res, entry, session) {
+        const { scenarios, problems } = loadScenarios(entry.workspace);
+        const kind = scenarioKind(entry);
+        const own = scenariosFor(scenarios, entry.app.name, entry.view.name, kind);
+        const active = kind === "desktop" ? entry.scenario : session.scenario;
+        res.writeHead(200, { "access-control-allow-origin": this.shellOrigin(entry.view.id), "access-control-allow-credentials": "true", vary: "Origin", "content-type": "application/json" });
+        res.end(JSON.stringify({ kind, scenarios: summarize(own, problems, entry.app.createdAt, kind), active: active ? { id: active.id, name: active.name, ...(active.simulated ? { simulated: active.simulated } : {}) } : null }));
+    }
+    /** Puts this browser in a scenario (or back in none, for an empty body) and
+     *  returns the plan the shell walks through: pages to open and steps to take.
+     *  A "fresh" scenario also expires the app's cookies this browser sent, so it
+     *  starts as a new visitor. Only the shell's origin may ask. */
+    async enterScenario(req, res, entry, session) {
+        const shell = this.shellOrigin(entry.view.id);
+        const cors = { "access-control-allow-origin": shell, "access-control-allow-credentials": "true", vary: "Origin" };
+        if (req.headers.origin !== shell) {
+            res.writeHead(403);
+            res.end();
+            return;
+        }
+        let body = "";
+        for await (const chunk of req) {
+            body += chunk.toString();
+            if (body.length > 64) {
+                res.writeHead(413, cors);
+                res.end();
+                return;
+            }
+        }
+        const id = body.trim();
+        const json = (status, value) => { res.writeHead(status, { ...cors, "content-type": "application/json" }); res.end(JSON.stringify(value)); };
+        // A desktop app is one program for everyone watching it: its scenario
+        // restarts it, and the steps run in its window before this answers.
+        if (scenarioKind(entry) === "desktop") {
+            if (!this.registry.desktopScenario) {
+                json(400, { error: "Desktop scenarios aren't available on this machine." });
+                return;
+            }
+            try {
+                json(200, await this.registry.desktopScenario(entry.view.id, id));
+            }
+            catch (error) {
+                json(400, { error: error.message });
+            }
+            return;
+        }
+        if (!id) {
+            session.scenario = undefined;
+            res.writeHead(200, { ...cors, "content-type": "application/json" });
+            res.end(JSON.stringify({ plan: null }));
+            return;
+        }
+        let plan;
+        try {
+            const own = scenariosFor(loadScenarios(entry.workspace).scenarios, entry.app.name, entry.view.name, "web");
+            plan = planScenario(own, id, "web");
+        }
+        catch (error) {
+            res.writeHead(400, { ...cors, "content-type": "application/json" });
+            res.end(JSON.stringify({ error: error.message }));
+            return;
+        }
+        session.scenario = plan;
+        const headers = { ...cors, "content-type": "application/json" };
+        if (plan.fresh) {
+            const names = (req.headers.cookie ?? "").split(";").map((part) => part.split("=", 1)[0].trim()).filter((name) => name && name !== COOKIE && /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name));
+            const expire = (name) => `${name}=; Path=/; Max-Age=0`;
+            headers["set-cookie"] = names.map((name) => session.embedded ? partitionCookie(expire(name)) : expire(name));
+        }
+        res.writeHead(200, headers);
+        res.end(JSON.stringify({ plan }));
+    }
     /** Compare shots for the shell: the list, or one PNG by index. */
     compare(req, res, entry) {
         const shots = entry.shots ?? [];

package/dist/apps/inspector.js

@@ -128,10 +128,65 @@ const marked=r=>{
     text:(el.innerText||el.getAttribute('aria-label')||el.getAttribute('alt')||'').trim().replace(/\\s+/g,' ').slice(0,120),
     rect:{x:Math.round(b.left+scrollX),y:Math.round(b.top+scrollY),width:Math.round(b.width),height:Math.round(b.height)}};});
 };
+// Scenarios: the shell walks a scenario's steps here, one at a time, the way a
+// person would (find it, scroll to it, use it), and hears back after each one.
+// A step that leaves the page ends this run; the shell picks up after it on the
+// next page. "load" ties each answer to the page load it came from.
+let leaving=false;
+addEventListener('pagehide',()=>{leaving=true;});addEventListener('beforeunload',()=>{leaving=true;});
+const sleep=ms=>new Promise(r=>setTimeout(r,ms));
+const shown=el=>Boolean(el&&el.getClientRects().length);
+const words=el=>(el.innerText||el.value||el.getAttribute('aria-label')||'').trim().replace(/\\s+/g,' ').toLowerCase();
+const find=q=>{
+  if(typeof q!=='string')return null;
+  if(q.startsWith('text=')){
+    const want=q.slice(5).trim().toLowerCase();
+    const all=[...document.querySelectorAll('a,button,[role=button],[role=link],[role=tab],[role=menuitem],[role=option],label,summary,input[type=submit],input[type=button]')].filter(shown);
+    return all.find(el=>words(el)===want)||all.find(el=>words(el).includes(want))||null;
+  }
+  try{const el=document.querySelector(q);return shown(el)?el:null;}catch{throw Error('“'+q+'” isn’t a valid selector');}
+};
+const waitFor=async q=>{for(let t=0;t<50&&!leaving;t++){const el=find(q);if(el)return el;await sleep(100);}return null;};
+const missing=q=>Error('Couldn’t find “'+q+'” within 5 seconds');
+const STEPS={
+  click:async s=>{const el=await waitFor(s.click);if(!el)throw missing(s.click);el.scrollIntoView({block:'center'});el.click();},
+  fill:async s=>{
+    const el=await waitFor(s.fill);if(!el)throw missing(s.fill);
+    const proto=el.localName==='textarea'?HTMLTextAreaElement.prototype:el.localName==='select'?HTMLSelectElement.prototype:HTMLInputElement.prototype;
+    const set=Object.getOwnPropertyDescriptor(proto,'value')?.set;if(!set)throw Error('“'+s.fill+'” isn’t a field');
+    el.scrollIntoView({block:'center'});el.focus();set.call(el,String(s.with));
+    el.dispatchEvent(new Event('input',{bubbles:true}));el.dispatchEvent(new Event('change',{bubbles:true}));
+  },
+  press:async s=>{
+    const el=document.activeElement||document.body,key=String(s.press),o={key,bubbles:true,cancelable:true};
+    const go=el.dispatchEvent(new KeyboardEvent('keydown',o));el.dispatchEvent(new KeyboardEvent('keyup',o));
+    if(go&&key==='Enter'&&el.form)el.form.requestSubmit();
+  },
+  wait:async s=>{if(typeof s.wait==='number')await sleep(Math.min(10000,Math.max(0,s.wait)));else if(!await waitFor(s.wait))throw missing(s.wait);},
+};
+async function runSteps(d){
+  const steps=Array.isArray(d.steps)?d.steps.slice(0,50):[],run=d.run,load=d.load;
+  for(let i=Math.max(0,Number(d.from)||0);i<steps.length;i++){
+    const step=steps[i]||{},kind=Object.keys(STEPS).find(k=>k in step);
+    try{if(!kind)throw Error('Unknown step');await STEPS[kind](step);}
+    catch(error){if(!leaving)post({type:'step',run,load,i,error:String(error?.message||error).slice(0,300)});return;}
+    post({type:'step',run,load,i,ok:true});
+    await sleep(250);if(leaving)return;
+  }
+  post({type:'steps-done',run,load});
+}
+// A fresh start: what this page keeps in the browser goes (the gateway expires
+// the cookies the server can see).
+const forget=()=>{
+  try{localStorage.clear();sessionStorage.clear();}catch{}
+  for(const c of document.cookie.split(';')){const name=c.split('=')[0].trim();if(name)document.cookie=name+'=; Max-Age=0; Path=/';}
+};
 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:note'&&REVIEWER){
+  if(d.type==='bivy:steps')void runSteps(d);
+  else if(d.type==='bivy:forget'){forget();post({type:'forgot'});}
+  else 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}));

package/dist/apps/preview-shell.js

@@ -89,6 +89,27 @@ nav::-webkit-scrollbar { display:none; }
 #menu kbd { flex:none; padding:0 var(--space-1); border:thin solid var(--line); border-radius:var(--radius-sm); color:var(--muted); font-family:var(--font-mono); font-size:var(--text-xs); }
 /* The name is a label, not a target: one pill, three buttons at most. */
 #name { pointer-events:none; }
+/* With scenarios, the name becomes their switcher: the title says which one
+   you're in, the line under it whether Bivy is simulating anything. */
+#scn { display:flex; align-items:center; gap:var(--space-1); min-width:0; padding-inline:var(--space-2); text-align:start; }
+#scn[data-active] { background:color-mix(in srgb, var(--accent) 14%, var(--surface)); }
+.scn-text { display:flex; flex-direction:column; min-width:0; }
+#scn-title { font-weight:var(--weight-semibold); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; max-width:14em; }
+#scn-sub { font-size:var(--text-xs); font-weight:var(--weight-normal); overflow:hidden; text-overflow:ellipsis; white-space:nowrap; max-width:18em; }
+#scn svg { flex:none; }
+#dock:not([data-edge="top"]) #scn svg { transform:rotate(180deg); }
+.scn-group { margin:var(--space-3) 0 var(--space-1); font-size:var(--text-xs); font-weight:var(--weight-semibold); color:var(--muted); }
+.scn-group:first-of-type { margin-top:0; }
+.scn-list { list-style:none; margin:0; padding:0; display:grid; grid-template-columns:repeat(auto-fill, minmax(200px, 1fr)); gap:var(--space-2); }
+.scn-row { display:flex; align-items:flex-start; gap:var(--space-2); width:100%; height:100%; min-block-size:var(--space-7); box-sizing:border-box; padding:var(--space-2) var(--space-3); border:thin solid var(--line); border-radius:var(--radius-md); background:var(--surface); color:var(--ink); font:inherit; text-align:start; cursor:pointer; }
+.scn-row:hover { background:var(--surface-2); }
+.scn-row:focus-visible { outline:2px solid var(--focus-ring); outline-offset:1px; }
+.scn-row[aria-current="true"] { border-color:var(--accent); box-shadow:0 0 0 1px var(--accent); }
+.scn-row-text { flex:1; min-width:0; display:flex; flex-direction:column; gap:2px; }
+.scn-row-name { font-size:var(--text-sm); font-weight:var(--weight-semibold); overflow-wrap:anywhere; }
+.scn-row-sub { font-size:var(--text-xs); color:var(--muted); overflow-wrap:anywhere; }
+.scn-row .badge { flex:none; }
+#scn-fail-text { font-size:var(--text-sm); margin:0; overflow-wrap:anywhere; }
 #more { position:relative; gap:var(--space-1); }
 #dock:not([data-edge="top"]) #more svg { transform:rotate(180deg); }
 #compare-draw { margin-top:var(--space-2); }
@@ -96,7 +117,7 @@ nav::-webkit-scrollbar { display:none; }
 #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) { .wide-only { display:none; } .label-wide { display:none; } .label-narrow { display:inline; } #title { max-width:9em; } }
+@media (max-width: 699px) { .wide-only { display:none; } .label-wide { display:none; } .label-narrow { display:inline; } #title, #scn-title { max-width:9em; } #scn-sub { max-width:12em; } }
 /* "Made with Bivy": a quiet strip under a shared app, never over it. */
 #made-with { flex-shrink:0; display:flex; align-items:center; justify-content:center; gap:var(--space-1); min-height:var(--space-6); padding:0 var(--space-3) env(safe-area-inset-bottom); box-sizing:border-box; background:var(--surface); border-top:thin solid var(--line); color:var(--muted); font-size:var(--text-xs); text-decoration:none; }
 #made-with:hover, #made-with:focus-visible { color:var(--ink); }
@@ -111,7 +132,7 @@ body.badged #dock:not([data-edge="top"]) { bottom:calc(var(--space-2) + var(--sp
 <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>
-    <p class="muted" id="console-empty">No errors or warnings since this page loaded.</p>
+    <p class="muted" id="console-empty">No errors or warnings since this page loaded, from the page or its server.</p>
     <ul id="entries"></ul>
     <div class="panel-actions"><button class="btn sm" id="send-errors" disabled>Send to agent…</button></div>
   </section>
@@ -121,6 +142,15 @@ body.badged #dock:not([data-edge="top"]) { bottom:calc(var(--space-2) + var(--sp
     <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="scenarios" hidden aria-labelledby="scenarios-title">
+    <h2><span id="scenarios-title">Scenarios</span><button class="btn sm ghost" id="scenarios-close" type="button" aria-label="Close scenarios">✕</button></h2>
+    <div id="scenarios-body"></div>
+  </section>
+  <section class="panel" id="scn-fail" hidden aria-labelledby="scn-fail-title" role="alertdialog">
+    <h2 id="scn-fail-title">Couldn’t finish the scenario</h2>
+    <p id="scn-fail-text"></p>
+    <div class="panel-actions"><button class="btn sm ghost" id="scn-stay" type="button">Stay here</button><button class="btn sm primary" id="scn-fix" type="button">Ask agent to fix</button></div>
+  </section>
   <section class="panel" id="draft" hidden aria-labelledby="draft-title">
     <div id="draft-body">
     <h2 id="draft-title">Note for the agent</h2>
@@ -157,6 +187,8 @@ body.badged #dock:not([data-edge="top"]) { bottom:calc(var(--space-2) + var(--sp
   <nav aria-label="Bivy preview controls">
     <button class="btn sm ghost" id="back" aria-label="Back to chat">‹ <span class="label-wide">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="scn" type="button" hidden aria-haspopup="dialog" aria-expanded="false" aria-controls="scenarios"><span class="scn-text"><span id="scn-title"></span><span id="scn-sub" class="muted" aria-live="polite"></span></span><svg viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6 9l6 6 6-6"/></svg></button>
+    <button class="btn sm ghost" id="scn-reset" type="button" hidden aria-label="Reset scenario" title="Start this scenario over"><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 12a9 9 0 1 0 3-6.7"/><path d="M3 4v5h5"/></svg></button>
     <button class="btn sm primary" id="update" type="button" hidden><span class="label-wide">Show new version</span><span class="label-narrow">New</span></button>
     <button class="btn sm ghost" id="more" type="button" aria-haspopup="menu" aria-expanded="false" aria-label="Preview options"><span class="badge" data-variant="solid" data-tone="danger" id="error-count" hidden></span><svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6 9l6 6 6-6"/></svg></button>
   </nav>
@@ -166,7 +198,9 @@ body.badged #dock:not([data-edge="top"]) { bottom:calc(var(--space-2) + var(--sp
 const $=id=>document.getElementById(id);
 const frame=$('app'),status=$('status'),back=$('back'),reload=$('reload'),stage=$('stage');
 // "#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);
+// "#ticket~page~scenario": a review card's "Try it" opens the preview in a scenario.
+const [ticket,startPage='',startAt='']=location.hash.slice(1).split('~');history.replaceState(null,'',location.pathname);
+let pendingScenario=/^[a-z0-9][a-z0-9-]{0,63}$/.test(startAt)?startAt:'';
 let metadata,currentPath='/';
 // Peek: framed by a Bivy client, which owns closing and the composer.
 const embedded=parent!==window;
@@ -206,10 +240,15 @@ function show(data,launch){
   reviewerTools(false);
   status.textContent='Loading app…';
   frame.onload=()=>{
-    status.hidden=true;void loadCompare();
+    loads++;
+    if(runner&&!runner.desktop)sendSteps();else status.hidden=true;
+    // A desktop app's viewer has no inspector to say it has loaded.
+    if(metadata.inspect===false&&!scenariosLoaded)void loadScenarios();
+    void loadCompare();
     // Put them back where they were before an update they asked for.
     if(restore){const at=restore;restore=null;frame.contentWindow?.postMessage(Object.assign({type:'bivy:restore'},at),metadata.origin);}
     if(!watching){watching=true;latest=-1;shown=null;watch();firstHint();}else if(wake)wake();
+    if(!serverPolling)void pollServer();
   };
   // A Bivy client framing the shell says whether it can take dictation.
   if(embedded&&data.returnTo)toBivy({type:'hello'});
@@ -241,6 +280,8 @@ async function watch(){
     const r=await fetch(metadata.origin+'/__bivy/revision?after='+latest,{credentials:'include',cache:'no-store'});
     if(!r.ok)throw Error();
     const d=await r.json();
+    // A turn may have written or changed scenario files.
+    if(latest!==null&&latest!==-1&&d.revision!==latest)void loadScenarios();
     latest=d.revision;newPath=safePath(d.path);
     // The first poll after a load describes what the frame already has.
     if(shown===null)shown=latest;
@@ -254,6 +295,7 @@ function waiting(on){
   if($('update').hidden===!on)return;
   $('update').hidden=!on;
   $('stamp').textContent=on?'New version ready':'';
+  renderScenarioPill();
 }
 /** Asks the page where it is, so the update can put it back. Without an
  *  inspector (a desktop app) there is nothing to ask. */
@@ -407,20 +449,186 @@ function finishNote(d){
   status.hidden=false;status.textContent=$('stamp').textContent+'. The app’s owner will see it.';
   $('more').focus();
 }
+// Scenarios: named starting points for the live app, from the project's
+// .bivy/scenarios. Opening one tells the gateway (so its simulated responses
+// apply to this browser only), opens its page and walks its steps through the
+// page's inspector, one at a time; a step that loads a new page is picked up
+// after on the next one. Reset does it all again; "Your data" leaves it.
+let scenarios=[],activeScenario=null,runner=null,runSeq=0,loads=0,scenariosLoaded=false;
+const scnBtn=$('scn'),scnReset=$('scn-reset');
+async function loadScenarios(){
+  if(!metadata||metadata.controls===false)return;
+  try{
+    const r=await fetch(metadata.origin+'/__bivy/scenarios',{credentials:'include',cache:'no-store'});if(!r.ok)return;
+    const d=await r.json();
+    scenarios=(Array.isArray(d.scenarios)?d.scenarios:[]).slice(0,100);
+    if(!runner)activeScenario=d.active&&typeof d.active.id==='string'?d.active:null;
+    scenariosLoaded=true;
+    renderScenarioPill();
+    if(!$('scenarios').hidden)renderScenarioList();
+    if(pendingScenario){const id=pendingScenario;pendingScenario='';void enterScenario(id);}
+  }catch{}
+}
+function renderScenarioPill(){
+  if(!metadata)return;
+  const on=scenarios.length>0||Boolean(activeScenario);
+  scnBtn.hidden=!on;$('name').hidden=on;scnReset.hidden=!activeScenario||Boolean(runner);
+  if(!on)return;
+  const sim=activeScenario?.simulated;
+  $('scn-title').textContent=activeScenario?activeScenario.name:metadata.name;
+  $('scn-sub').textContent=runner?'Opening…':activeScenario?(sim?'Simulated: '+sim:metadata.name):$('stamp').textContent||(scenarios.length===1?'1 scenario':scenarios.length+' scenarios');
+  scnBtn.toggleAttribute('data-active',Boolean(activeScenario));
+  scnBtn.setAttribute('aria-label',(activeScenario?'Scenario: '+activeScenario.name+(sim?', simulated':'')+'. ':'')+'Choose a scenario');
+  scnReset.setAttribute('aria-label','Reset '+(activeScenario?.name||'scenario'));
+}
+function scenarioRow(s){
+  const b=document.createElement('button');b.type='button';b.className='scn-row';
+  const current=(activeScenario?.id||'')===s.id;
+  if(current)b.setAttribute('aria-current','true');
+  const text=document.createElement('span');text.className='scn-row-text';
+  const name=document.createElement('span');name.className='scn-row-name';name.textContent=s.name;
+  text.append(name);
+  const lines=s.error?[s.error]:[s.description,s.details??[s.open,s.simulated?'simulates '+s.simulated:'',s.steps?s.steps+' step'+(s.steps===1?'':'s'):'',s.fresh?'as a new visitor':''].filter(Boolean).join(' · ')];
+  for(const line of lines.filter(Boolean)){const sub=document.createElement('span');sub.className='scn-row-sub';sub.textContent=String(line).slice(0,300);text.append(sub);}
+  b.append(text);
+  if(s.error||s.isNew){const tag=document.createElement('span');tag.className='badge';tag.dataset.tone=s.error?'warn':'accent';tag.textContent=s.error?'Needs a fix':'New';b.append(tag);}
+  if(s.error&&(!metadata.returnTo||metadata.reviewer))b.disabled=true;
+  b.onclick=()=>{if(s.error)return toChat(fixRequest(s.name,s.id,s.error));void enterScenario(s.id);};
+  return b;
+}
+function renderScenarioList(){
+  const body=$('scenarios-body'),fresh=scenarios.filter(s=>s.isNew&&!s.error);
+  const group=(label,rows)=>{
+    const h=document.createElement('h3');h.className='scn-group';h.textContent=label;
+    const ul=document.createElement('ul');ul.className='scn-list';
+    for(const row of rows){const li=document.createElement('li');li.append(scenarioRow(row));ul.append(li);}
+    return [h,ul];
+  };
+  const mine={id:'',name:'Your data',details:'The app as it is, no scenario'};
+  body.replaceChildren(...(fresh.length?group('New in this session',fresh):[]),...group(fresh.length?'All':'Start from',[mine,...scenarios.filter(s=>!fresh.includes(s))]));
+}
+scnBtn.onclick=()=>{
+  if(!$('scenarios').hidden)return panels(null);
+  panels('scenarios');renderScenarioList();void loadScenarios();
+  ($('scenarios-body').querySelector('[aria-current="true"]')||$('scenarios-body').querySelector('.scn-row:not(:disabled)'))?.focus();
+};
+$('scenarios-close').onclick=()=>{panels(null);scnBtn.focus();};
+scnReset.onclick=()=>{if(activeScenario)void enterScenario(activeScenario.id);};
+const fixRequest=(name,id,problem)=>'The scenario “'+name+'” (.bivy/scenarios/'+id+'.json) for the app preview "'+metadata.name+'" doesn’t work: '+problem+'\\n\\nPlease fix the scenario, or the app if that’s what broke, and tell me when it opens cleanly.';
+async function enterScenario(id){
+  panels(null);
+  const run=++runSeq;
+  if(runner)clearTimeout(runner.timer);
+  runner=null;
+  // A desktop app: the machine restarts it in the scenario and takes the
+  // steps in its window, then answers. Nothing to walk here.
+  if(metadata.inspect===false)return enterDesktopScenario(id,run);
+  let d={};
+  try{
+    const r=await fetch(metadata.origin+'/__bivy/scenario',{method:'POST',credentials:'include',cache:'no-store',headers:{'content-type':'text/plain'},body:id});
+    d=await r.json().catch(()=>({}));
+    if(!r.ok)throw Error(typeof d.error==='string'?d.error.slice(0,300):'The preview didn’t answer.');
+  }catch(error){if(run===runSeq)failScenario({id,name:scenarios.find(s=>s.id===id)?.name||id},error.message||'The preview didn’t answer.');return;}
+  if(run!==runSeq)return;
+  const plan=d.plan;
+  if(!plan){activeScenario=null;renderScenarioPill();open(currentPath,'Reloading app…');return;}
+  activeScenario={id:plan.id,name:plan.name,...(plan.simulated?{simulated:plan.simulated}:{})};
+  runner={run,plan,stage:0,step:0,timer:0};
+  // As a new visitor: the page forgets what it kept before the first page opens.
+  if(plan.fresh)frame.contentWindow?.postMessage({type:'bivy:forget'},metadata.origin);
+  renderScenarioPill();
+  setTimeout(()=>{if(runner?.run===run)goStage();},plan.fresh?200:0);
+}
+async function enterDesktopScenario(id,run){
+  const name=id?scenarios.find(s=>s.id===id)?.name||id:'';
+  runner={run,desktop:true,timer:0,plan:{id,name}};renderScenarioPill();
+  let d={};
+  try{
+    const r=await fetch(metadata.origin+'/__bivy/scenario',{method:'POST',credentials:'include',cache:'no-store',headers:{'content-type':'text/plain'},body:id});
+    d=await r.json().catch(()=>({}));
+    if(!r.ok)throw Error(typeof d.error==='string'?d.error.slice(0,300):'The app didn’t answer.');
+  }catch(error){if(run===runSeq){runner=null;failScenario({id,name},error.message||'The app didn’t answer.');}return;}
+  if(run!==runSeq)return;
+  activeScenario=d.plan?{id:d.plan.id,name:d.plan.name,...(d.plan.simulated?{simulated:d.plan.simulated}:{})}:null;
+  if(typeof d.error==='string')failScenario(d.plan,d.error.slice(0,400));else finishScenario();
+}
+/** Opens the stage's page (its steps follow when it has loaded), or walks its steps where we are. */
+function goStage(){
+  const st=runner.plan.stages[runner.stage];
+  if(!st)return finishScenario();
+  runner.step=0;
+  if(st.open){shown=latest;waiting(false);open(st.open,'Opening '+runner.plan.name+'…');watchdog();}
+  else sendSteps();
+}
+function sendSteps(){
+  const st=runner.plan.stages[runner.stage];
+  if(!st)return finishScenario();
+  if(runner.step>=st.steps.length){runner.stage++;return goStage();}
+  frame.contentWindow?.postMessage({type:'bivy:steps',run:runner.run,load:loads,steps:st.steps,from:runner.step},metadata.origin);
+  watchdog();
+}
+/** A page that stops answering (no inspector, a hung script) fails the scenario rather than leaving it opening forever. */
+function watchdog(){
+  const at=runner;clearTimeout(at.timer);
+  at.timer=setTimeout(()=>{if(runner===at)failScenario(at.plan,'The page stopped answering at step '+(at.step+1)+' of “'+at.plan.name+'”.');},12000);
+}
+const stepWords=s=>s?('click' in s?'click '+s.click:'fill' in s?'fill '+s.fill:'press' in s?'press '+s.press:'wait' in s?'wait for '+s.wait:'step'):'step';
+function stepReport(d){
+  if(d.type==='steps-done'){runner.stage++;return goStage();}
+  const i=Number(d.i)||0;
+  if(d.ok){runner.step=i+1;return watchdog();}
+  const st=runner.plan.stages[runner.stage],before=runner.plan.stages.slice(0,runner.stage).reduce((n,x)=>n+x.steps.length,0);
+  failScenario(runner.plan,'Step '+(before+i+1)+' ('+stepWords(st.steps[i])+'): '+String(d.error||'it failed').slice(0,300)+'.');
+}
+function finishScenario(){
+  if(runner)clearTimeout(runner.timer);
+  runner=null;status.hidden=true;renderScenarioPill();
+}
+function failScenario(s,message){
+  if(runner)clearTimeout(runner.timer);
+  runner=null;status.hidden=true;renderScenarioPill();
+  panels(null);
+  $('scn-fail-title').textContent='Couldn’t finish “'+s.name+'”';
+  $('scn-fail-text').textContent=message+(metadata.inspect===false?' The app is running with what ran so far.':' You’re on '+currentPath+' with what ran so far.');
+  $('scn-fix').hidden=!metadata.returnTo||Boolean(metadata.reviewer);
+  $('scn-fix').onclick=()=>{$('scn-fail').hidden=true;toChat(fixRequest(s.name,s.id,message));};
+  $('scn-fail').hidden=false;
+  ($('scn-fix').hidden?$('scn-stay'):$('scn-fix')).focus();
+}
+$('scn-stay').onclick=()=>{$('scn-fail').hidden=true;scnBtn.hidden?more.focus():scnBtn.focus();};
 // Console
 let entries=[];
-function resetConsole(){entries=[];renderConsole();}
+function resetConsole(){entries=[];serverSince='page';renderConsole();}
+// The server's errors join the page's: what the app's server logged since this
+// page loaded (Bivy follows the output of servers it runs). The owner's only.
+let serverSince='page',serverPolling=false;
+async function pollServer(){
+  serverPolling=true;
+  if(metadata&&!metadata.reviewer&&metadata.inspect!==false){
+    try{
+      const r=await fetch(metadata.origin+'/__bivy/server-errors?since='+serverSince,{credentials:'include',cache:'no-store'});
+      if(r.ok){
+        const d=await r.json();
+        for(const line of (Array.isArray(d.lines)?d.lines:[]).slice(-20))entries.push({level:'error',source:'server',text:String(line.text).slice(0,500)});
+        if(entries.length>50)entries.splice(0,entries.length-50);
+        if(d.lines?.length)renderConsole();
+        if(Number.isFinite(d.now))serverSince=String(d.now);
+      }
+    }catch{}
+  }
+  setTimeout(()=>void pollServer(),document.hidden?10000:3000);
+}
 function renderConsole(){
   const errors=entries.filter(e=>e.level==='error').length,count=$('error-count');
   count.hidden=!errors;count.textContent=String(errors);
   // The number is shown once, on the pill, so it is visible without opening it.
   $('more').setAttribute('aria-label',errors?'Preview options, '+errors+' error'+(errors===1?'':'s'):'Preview options');
   $('console-empty').hidden=entries.length>0;$('send-errors').disabled=!entries.length;
-  $('entries').replaceChildren(...entries.map(e=>{const li=document.createElement('li');const tag=document.createElement('span');tag.className='badge';tag.dataset.tone=e.level==='error'?'danger':'warn';tag.textContent=e.level;const text=document.createElement('span');text.textContent=e.text;li.append(tag,text);return li;}));
+  $('entries').replaceChildren(...entries.map(e=>{const li=document.createElement('li');const tag=document.createElement('span');tag.className='badge';tag.dataset.tone=e.level==='error'?'danger':'warn';tag.textContent=e.source==='server'?'server':e.level;const text=document.createElement('span');text.textContent=e.text;li.append(tag,text);return li;}));
 }
 $('errors').onclick=()=>panels($('console').hidden?'console':null);
 $('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'));
+$('send-errors').onclick=()=>draft('Console output in the app preview "'+metadata.name+'" (page '+currentPath+'):\\n'+entries.slice(-20).map(e=>'- '+(e.source==='server'?'server error':e.level)+': '+e.text).join('\\n'));
 // Marking: one gesture, two results. Pointing at an element and circling an
 // area were two modes with a button each; they are one mode now, because they
 // are one intention — "this, here".
@@ -666,7 +874,7 @@ 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-checked',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'],['scenarios','scn']]){$(id).hidden=id!==open;$(btn).setAttribute(btn==='scn'?'aria-expanded':'aria-checked',String(id===open));}$('draft').hidden=true;$('scn-fail').hidden=true;}
 compareBtn.onclick=async()=>{
   if(!$('compare').hidden)return panels(null);
   panels('compare');
@@ -736,7 +944,11 @@ addEventListener('message',e=>{
     ask.hidden=!metadata.returnTo;
   }else if(d.source==='bivy-inspector'){
     if(d.type==='note-sent'&&metadata.reviewer)finishNote(d);
-    else if(d.type==='route'){currentPath=safePath(d.path);reviewerTools(true);}
+    else if(d.type==='route'){
+      currentPath=safePath(d.path);reviewerTools(true);
+      if(!scenariosLoaded)void loadScenarios();
+    }
+    else if((d.type==='step'||d.type==='steps-done')&&runner&&d.run===runner.run&&d.load===loads)stepReport(d);
     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==='release'&&heldAt){heldAt=0;stopListening();}
     else if(d.type==='draw-state'){if(draw&&draw.waiting)draw.waiting(d);else if(stateWaiter)stateWaiter(d);}