@shipvo/sim 0.1.3 → 0.1.5

package/browser-resolver.mjs

@@ -0,0 +1,52 @@
+// Picks the browser the simulator launches: system Chrome, system Edge, Playwright's cached Chromium,
+// then a one-time `npx playwright install chromium`. Pure: fs and process access are injected.
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+export const INSTALL_COMMAND = "npx playwright install chromium";
+
+/** Where each Playwright channel puts its binary, per platform. */
+export function systemBrowserPaths(channel, platform, env) {
+  if (platform === "win32") {
+    const roots = [env.PROGRAMFILES, env["PROGRAMFILES(X86)"], env.LOCALAPPDATA].filter(Boolean);
+    const rel = channel === "chrome" ? "\\Google\\Chrome\\Application\\chrome.exe" : "\\Microsoft\\Edge\\Application\\msedge.exe";
+    return roots.map((r) => r + rel);
+  }
+  if (platform === "darwin") {
+    return channel === "chrome"
+      ? ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"]
+      : ["/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"];
+  }
+  return channel === "chrome"
+    ? ["/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/opt/google/chrome/chrome"]
+    : ["/usr/bin/microsoft-edge", "/usr/bin/microsoft-edge-stable", "/opt/microsoft/msedge/msedge"];
+}
+
+const defaultRun = (cmd, args) => spawnSync(cmd, args, { stdio: "inherit", shell: process.platform === "win32" });
+
+/**
+ * Returns the options to pass to `chromium.launch`.
+ * Order: system Chrome, system Edge, Playwright cache, one-time install.
+ */
+export function resolveBrowser({ pw, executablePath, env = process.env, fileExists = existsSync, run = defaultRun, platform = process.platform, log = (m) => console.error(m) }) {
+  if (executablePath) return { executablePath };
+  for (const channel of ["chrome", "msedge"]) {
+    if (systemBrowserPaths(channel, platform, env).some((p) => fileExists(p))) return { channel };
+  }
+  let cached;
+  try { cached = pw.chromium.executablePath(); } catch { cached = undefined; }
+  if (cached && fileExists(cached)) return {};
+  if (env.SHIPVO_NO_AUTO_INSTALL === "1") {
+    throw new Error(`no browser found (Chrome, Edge or Playwright Chromium) and SHIPVO_NO_AUTO_INSTALL=1 is set. Run \`${INSTALL_COMMAND}\``);
+  }
+  log(`sim: no Chrome, Edge or Chromium found; running \`${INSTALL_COMMAND}\` once (this downloads a browser)...`);
+  const [cmd, ...args] = INSTALL_COMMAND.split(" ");
+  const res = run(cmd, args);
+  if (!res || res.status !== 0 || res.error) {
+    const why = res && res.error ? `: ${res.error.message}` : "";
+    throw new Error(`\`${INSTALL_COMMAND}\` failed${why}. Run it yourself and check the output`);
+  }
+  let after; try { after = pw.chromium.executablePath(); } catch { after = undefined; }
+  if (!after || !fileExists(after)) throw new Error(`\`${INSTALL_COMMAND}\` failed: it exited 0 but no browser was installed. Run it yourself and check the output`);
+  return {};
+}

package/chromium-hint.mjs

@@ -0,0 +1,19 @@
+// The fix to print when Playwright cannot find the Chromium build it wants.
+export const CHROMIUM_MISSING = /Executable doesn't exist/;
+// Linux: the browser exists but shared libraries are missing.
+export const LIBS_MISSING = /error while loading shared libraries|Host system is missing dependencies/i;
+
+/** The one-line install command for the resolved playwright version, plus the Linux hint. */
+export function chromiumInstallFix(version) {
+  const v = version ? ` (playwright ${version})` : "";
+  return `run \`npx playwright install chromium\` in the app folder${v}. On Linux, if Chromium then fails to start, run \`npx playwright install --with-deps chromium\` or install the system packages it lists.`;
+}
+
+/** The message to print for a launch error. Returns the first line, plus the fix when the browser is not installed. */
+export function launchErrorMessage(message, version) {
+  const first = String(message).split("\n")[0];
+  const base = `could not launch Chromium: ${first}`;
+  if (CHROMIUM_MISSING.test(message)) return `${base}\nFix: ${chromiumInstallFix(version)}`;
+  if (LIBS_MISSING.test(message)) return `${base}\nFix: system libraries are missing. Run \`npx playwright install-deps chromium\``;
+  return base;
+}

package/frame.d.mts

@@ -0,0 +1,37 @@
+export type FrameSkin = "android" | "ios";
+export type FrameStatus = {
+  /** Text shown on the left, for example "9:41". */
+  time?: string;
+  /** Bars filled, 0 to 4. Default 4. */
+  signal?: number;
+  /** Default true. */
+  wifi?: boolean;
+  /** Shows an airplane icon and hides signal and wifi. */
+  airplane?: boolean;
+  /** Level 0 to 100, or an object. Default 100. */
+  battery?: number | { level?: number; charging?: boolean };
+};
+export type FrameOptions = { skin?: FrameSkin; dark?: boolean; status?: FrameStatus; /** HTML for the screen area. */ screen?: string };
+export type Frame = {
+  skin: FrameSkin;
+  /** Screen size in CSS pixels. */
+  width: number;
+  height: number;
+  /** Size of the whole body, bezel included. */
+  outerWidth: number;
+  outerHeight: number;
+  html: string;
+  css: string;
+};
+export const SKINS: Record<FrameSkin, { label: string; width: number; height: number; radius: number }>;
+export function normalizeStatus(status?: FrameStatus): { time: string; signal: number; wifi: boolean; airplane: boolean; battery: { level: number; charging: boolean } };
+export function renderFrame(options?: FrameOptions): Frame;
+export type DeviceStatusInput = { online?: boolean; airplane?: boolean; battery?: number | { level?: number; charging?: boolean } };
+/** Maps the simulated device state and a clock to a status object. */
+export function statusFromDevice(device?: DeviceStatusInput, now?: Date): FrameStatus;
+/** True when a CSS colour is dark, so the status text should be light. */
+export function isDarkBackground(color: string): boolean;
+/** The clock text and icons markup, for redrawing the status bar. */
+export function statusParts(status?: FrameStatus): { time: string; icons: string };
+/** Browser script that keeps the status bar live from the app's `pn:status` events. */
+export function statusClientScript(iframeId?: string, skin?: FrameSkin): string;

package/frame.mjs

@@ -0,0 +1,184 @@
+// The phone body: bezel, cutout, status bar and a slot for the screen. Pure: no DOM, no timers, no dependencies.
+// Our own artwork. It does not copy any vendor's icons, fonts or exact device outlines.
+// Scaling to fit the window is done by the page with a CSS transform on the element this markup sits in.
+
+import { lockScreenHtml, bootScreenHtml, offScreenHtml } from "./lifecycle.mjs";
+
+export const SKINS = {
+  android: { label: "Android", width: 412, height: 915, radius: 36, bezel: 10, status: 36, bar: 24, pad: 22, indicator: 108, part: "punch-hole", bottom: "gesture-bar" },
+  ios: { label: "iPhone", width: 393, height: 852, radius: 55, bezel: 12, status: 54, bar: 34, pad: 36, indicator: 134, part: "dynamic-island", bottom: "home-indicator" },
+};
+
+const FOOT = 14; // extra bezel under the screen, holds the "Simulated" label
+const clean = (s) => String(s).replace(/[<>&"'\\]/g, "").slice(0, 12);
+const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+
+/** Fills in anything missing from a status object. Never throws on odd input. */
+export function normalizeStatus(status = {}) {
+  const s = status && typeof status === "object" ? status : {};
+  const bat = typeof s.battery === "number" ? { level: s.battery } : (s.battery && typeof s.battery === "object" ? s.battery : {});
+  const num = (v, d) => (Number.isFinite(Number(v)) && v !== null && v !== "" ? Number(v) : d);
+  return {
+    time: s.time == null ? "9:41" : clean(s.time),
+    signal: Math.round(clamp(num(s.signal, 4), 0, 4)),
+    wifi: s.wifi !== false,
+    airplane: s.airplane === true,
+    battery: { level: Math.round(clamp(num(bat.level, 100), 0, 100)), charging: bat.charging === true },
+  };
+}
+
+/** Maps the simulated device ({ online, airplane, battery } from @shipvo/device) and a clock to a status object. Network off shows no signal and no wifi. */
+export function statusFromDevice(device = {}, now = new Date()) {
+  const d = device && typeof device === "object" ? device : {};
+  const online = d.online !== false && d.airplane !== true;
+  const h = now.getHours() % 12 || 12, m = String(now.getMinutes()).padStart(2, "0");
+  return { time: `${h}:${m}`, signal: online ? 4 : 0, wifi: online, airplane: d.airplane === true, battery: d.battery };
+}
+
+/** True when a CSS colour (#rgb, #rrggbb, rgb(), rgba()) is dark, so the status text should be light. Unknown or transparent colours count as light. */
+export function isDarkBackground(color) {
+  const c = String(color ?? "").trim().toLowerCase();
+  let r, g, b, a = 1, m;
+  if ((m = /^#([0-9a-f]{3})$/.exec(c))) [r, g, b] = [...m[1]].map((x) => parseInt(x + x, 16));
+  else if ((m = /^#([0-9a-f]{6})/.exec(c))) [r, g, b] = [0, 2, 4].map((i) => parseInt(m[1].slice(i, i + 2), 16));
+  else if ((m = /^rgba?\(\s*([\d.]+)[ ,]+([\d.]+)[ ,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?/.exec(c))) { [r, g, b] = [+m[1], +m[2], +m[3]]; if (m[4] != null) a = m[4].endsWith("%") ? parseFloat(m[4]) / 100 : +m[4]; }
+  else return false;
+  return a >= 0.5 && 0.2126 * r + 0.7152 * g + 0.0722 * b < 128;
+}
+
+/** The parts of the status bar that change: the clock text and the icons markup. */
+export function statusParts(status) {
+  const st = normalizeStatus(status);
+  return { time: st.time, icons: icons(st) };
+}
+
+/**
+ * Browser script for the page (online is shown as 4 bars; the simulated device has no signal strength) that holds the frame. It watches the app's "pn:status" events (sent by @shipvo/device when network,
+ * airplane or battery change), redraws the status bar, ticks the clock each minute and flips the text colour from the app's top background.
+ * `iframeId` is the app iframe. It expects the markup from renderFrame and the functions below inlined by this script.
+ */
+export function statusClientScript(iframeId = "app", skin = "android") {
+  return `(function(){
+var statusParts=${statusParts.toString()},normalizeStatus=${normalizeStatus.toString()},icons=${icons.toString()},battery=${battery.toString()},svg=${svg.toString()},isDarkBackground=${isDarkBackground.toString()},statusFromDevice=${statusFromDevice.toString()};
+var clean=${clean.toString()},clamp=${clamp.toString()};
+var dev={online:true,airplane:false,battery:{level:100,charging:false}};
+function root(){return document.querySelector('[data-part="phone-body"]')}
+function draw(){var r=root();if(!r)return;var p=statusParts(statusFromDevice(dev,new Date()));
+r.querySelector('[data-part="time"]').textContent=p.time;var lt=r.querySelector('[data-part="lock-time"]');if(lt)lt.textContent=p.time;r.querySelector(".sf-icons").innerHTML=p.icons}
+function topColor(w){try{var d=w.document,e=d.elementFromPoint(Math.floor(w.innerWidth/2),1);
+while(e){var c=w.getComputedStyle(e).backgroundColor;if(c&&c!=="transparent"&&!/rgba\\(.*,\\s*0\\)$/.test(c))return c;e=e.parentElement}var b=d.body&&w.getComputedStyle(d.body).backgroundColor;if(b&&!/rgba\\(.*,\\s*0\\)$/.test(b)&&b!=="transparent")return b}catch(x){}return"#fff"}
+function theme(w){var r=root();if(!r)return;var c=topColor(w),dark=isDarkBackground(c);
+r.setAttribute("data-theme",dark?"dark":"light");r.style.setProperty("--sf-status-fg",dark?"#fff":"#111");r.style.setProperty("--sf-status-bg",c)}
+function hook(){var f=document.getElementById(${JSON.stringify(iframeId)});var w=f&&f.contentWindow;if(!w)return;
+if(w.__pnDevice&&w.__pnDevice.status)dev=w.__pnDevice.status();draw();theme(w);
+if(!w.__shipvoStatusHooked){w.__shipvoStatusHooked=true;w.addEventListener("pn:status",function(e){dev=e.detail;draw();theme(w)})}}
+var f=document.getElementById(${JSON.stringify(iframeId)});if(f){f.addEventListener("load",hook);hook()}
+(function buttons(){var r=root();if(!r)return;var q=function(p){return r.querySelector('[data-part="'+p+'"]')},vol=50,hold,volT,bootT;
+if(!q("power-button")||!q("lock-screen")||!q("power-menu"))return;
+function show(el,on){if(el)el.hidden=!on}
+function shown(p){var e=q(p);return !!e&&!e.hidden}
+function lockNow(){show(q("power-menu"),false);show(q("lock-screen"),true);var u=q("unlock-button");if(u)u.focus()}
+function unlockNow(){show(q("lock-screen"),false);var p=q("power-button");if(p)p.focus()}
+function closeMenu(){if(shown("power-menu")){show(q("power-menu"),false);q("power-button").focus()}}
+function powerOn(){show(q("off-screen"),false);show(q("boot-screen"),true);clearTimeout(bootT);bootT=setTimeout(function(){show(q("boot-screen"),false)},1200)}
+function openMenu(){show(q("power-menu"),true);var b=q("power-menu").querySelector("button");if(b)b.focus()}
+var sy=null,ls=q("lock-screen");
+ls.addEventListener("pointerdown",function(e){sy=e.clientY});
+ls.addEventListener("pointerup",function(e){if(sy!=null&&sy-e.clientY>60)unlockNow();sy=null});
+ls.addEventListener("keydown",function(e){if(e.key==="ArrowUp"||e.key==="Enter"){e.preventDefault();unlockNow()}});
+if(q("unlock-button"))q("unlock-button").addEventListener("click",unlockNow);
+var pw=q("power-button");
+function stopHold(){if(hold){clearTimeout(hold);hold=null}}
+pw.addEventListener("pointerdown",function(){stopHold();hold=setTimeout(function(){hold=null;if(shown("off-screen"))return;openMenu();pw.setAttribute("data-held","1")},700)});
+pw.addEventListener("pointerleave",stopHold);pw.addEventListener("pointercancel",stopHold);
+pw.addEventListener("pointerup",stopHold);
+pw.addEventListener("click",function(e){
+if(pw.getAttribute("data-held")){pw.removeAttribute("data-held");return}
+if(shown("off-screen")){powerOn();return}
+if(e.detail===0&&e.shiftKey){shown("power-menu")?closeMenu():openMenu();return}
+if(shown("power-menu")){closeMenu();return}
+if(shown("lock-screen")){return}
+lockNow()});
+function bump(d){vol=Math.max(0,Math.min(100,vol+d));q("volume-level").textContent=vol;show(q("volume-overlay"),true);clearTimeout(volT);volT=setTimeout(function(){show(q("volume-overlay"),false)},1500)}
+q("volume-up-button").addEventListener("click",function(){bump(10)});q("volume-down-button").addEventListener("click",function(){bump(-10)});
+q("off-screen").addEventListener("click",powerOn);q("off-screen").addEventListener("keydown",function(e){if(e.key==="Enter"||e.key===" "){e.preventDefault();powerOn()}});
+r.addEventListener("keydown",function(e){if(e.key==="Escape")closeMenu()});
+document.addEventListener("pointerdown",function(e){if(shown("power-menu")&&!q("power-menu").contains(e.target)&&e.target!==pw)closeMenu()});
+q("power-menu").addEventListener("click",function(e){var a=e.target.getAttribute&&e.target.getAttribute("data-act");if(!a)return;show(q("power-menu"),false);
+if(a==="cancel"){pw.focus();return}
+if(a==="restart"){show(q("boot-screen"),true);var f=document.getElementById(${JSON.stringify(iframeId)});if(f&&f.contentWindow)f.contentWindow.location.reload();clearTimeout(bootT);bootT=setTimeout(function(){show(q("boot-screen"),false)},1200)}
+else{show(q("lock-screen"),false);show(q("off-screen"),true);pw.focus()}})})();
+(function tick(){draw();var n=new Date();setTimeout(tick,(60-n.getSeconds())*1000-n.getMilliseconds()+50)})();
+// The app can change its top colour (a theme switch) without any event we can hear, so look again every 2 seconds. Skipped while the page is hidden.
+setInterval(function(){if(document.hidden)return;var f=document.getElementById(${JSON.stringify(iframeId)});if(f&&f.contentWindow)theme(f.contentWindow)},2000);
+})();`;
+}
+
+const svg = (w, h, body, extra = "") => `<svg class="sf-ico" ${extra} width="${w}" height="${h}" viewBox="0 0 ${w} ${h}" aria-hidden="true">${body}</svg>`;
+
+function icons(st) {
+  if (st.airplane) {
+    return svg(16, 16, `<path d="M8 1.5 9.4 6.5 15 9.5v1.4l-5.6-1.5-.4 3 1.6 1.2v1L8 14.7 5.4 15.6v-1L7 13.4l-.4-3L1 10.9V9.5l5.6-3z" fill="currentColor"/>`, 'data-part="airplane"');
+  }
+  let bars = "";
+  for (let i = 0; i < 4; i++) bars += `<rect x="${i * 4}" y="${10 - i * 3}" width="3" height="${3 + i * 3}" rx="1" fill="currentColor"${i < st.signal ? "" : ' opacity=".3"'}/>`;
+  const signal = svg(15, 12, bars, `data-part="signal" data-level="${st.signal}"`);
+  const wifi = st.wifi
+    ? svg(16, 12, `<path d="M1 4.5a10 10 0 0 1 14 0M3.5 7.2a6.4 6.4 0 0 1 9 0" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/><circle cx="8" cy="10" r="1.4" fill="currentColor"/>`, 'data-part="wifi"')
+    : "";
+  return signal + wifi + battery(st.battery);
+}
+
+function battery(b) {
+  const w = Math.round((b.level / 100) * 15);
+  const bolt = b.charging ? `<path d="M12 2 7.5 7.5h3L9 11l4.5-5.5h-3z" fill="#000" opacity=".75"/>` : "";
+  return svg(25, 12, `<rect x=".75" y=".75" width="21.5" height="10.5" rx="3" fill="none" stroke="currentColor" stroke-width="1.5" opacity=".6"/><rect x="3.5" y="3.5" width="${w}" height="5" rx="1.5" fill="currentColor"/><rect x="23" y="4" width="2" height="4" rx="1" fill="currentColor" opacity=".6"/>${bolt}`, `data-part="battery" data-level="${b.level}"${b.charging ? ' data-charging="true"' : ""}`);
+}
+
+/**
+ * Renders the phone body.
+ * - skin: "android" (412x915, punch-hole camera) or "ios" (393x852, island cutout).
+ * - dark: true gives light status text on a dark bar, false gives dark text on a light bar.
+ * - status: { time, signal 0-4, wifi, airplane, battery (0-100, or { level, charging }) }.
+ * - screen: optional HTML placed in the screen area (the page puts its iframe there).
+ * Returns { skin, width, height, outerWidth, outerHeight, html, css }. width and height are the screen size.
+ */
+export function renderFrame({ skin = "android", dark = false, status, screen = "" } = {}) {
+  const k = SKINS[skin];
+  if (!k) throw new Error(`Unknown skin "${skin}". Use "android" or "ios".`);
+  const st = normalizeStatus(status);
+  const outerWidth = k.width + k.bezel * 2, outerHeight = k.height + k.bezel + k.bezel + FOOT;
+  const shape = skin === "ios"
+    ? `<span class="sf-cut sf-island" data-part="dynamic-island"></span>`
+    : `<span class="sf-cut sf-hole" data-part="punch-hole"></span>`;
+  const html = `<div class="sf-body" data-skin="${skin}" data-theme="${dark ? "dark" : "light"}" data-part="phone-body">`
+    + `<div class="sf-screen"><div class="sf-status" data-part="status-bar"><span class="sf-time" data-part="time">${st.time}</span>${shape}<span class="sf-icons">${icons(st)}</span></div>`
+    + `<div class="sf-content">${screen}</div>`
+    + lockScreenHtml(st.time) + bootScreenHtml() + offScreenHtml()
+    + `<div class="sf-vol" data-part="volume-overlay" role="status" aria-live="polite" hidden><span data-part="volume-level">50</span></div><div class="sf-menu" data-part="power-menu" role="menu" aria-label="Power menu" hidden><button role="menuitem" data-act="restart">Restart</button><button role="menuitem" data-act="poweroff">Power off</button><button role="menuitem" data-act="cancel">Cancel</button></div>`
+    + `<div class="sf-bar" data-part="${k.bottom}"><i></i></div></div>`
+    + `<button class="sf-btn sf-power" data-part="power-button" aria-label="Power"></button><button class="sf-btn sf-volup" data-part="volume-up-button" aria-label="Volume up"></button><button class="sf-btn sf-voldown" data-part="volume-down-button" aria-label="Volume down"></button>`
+    + `<span class="sf-label" data-part="simulated-label">Simulated</span></div>`;
+  const css = [
+    `.sf-body{--sf-bg:${dark ? "#000" : "#fff"};--sf-fg:${dark ? "#fff" : "#111"};position:relative;box-sizing:border-box;width:${outerWidth}px;height:${outerHeight}px;padding:${k.bezel}px ${k.bezel}px ${k.bezel + FOOT}px;`
+      + `border-radius:${k.radius + k.bezel}px;background:linear-gradient(145deg,#3a3d42,#15171a);box-shadow:0 0 0 1px #000,0 10px 34px #0007;touch-action:manipulation;user-select:none;-webkit-user-select:none}`,
+    `.sf-screen{width:${k.width}px;height:${k.height}px;border-radius:${k.radius}px;background:var(--sf-bg);color:var(--sf-fg);overflow:hidden;display:flex;flex-direction:column;position:relative}`,
+    `.sf-status{flex:none;height:${k.status}px;display:flex;justify-content:space-between;align-items:center;padding:0 ${k.pad}px;font:600 14px system-ui,sans-serif;position:relative;z-index:2;color:var(--sf-status-fg,var(--sf-fg));background:var(--sf-status-bg,transparent)}`,
+    `.sf-icons{display:flex;align-items:center;gap:5px}.sf-ico{display:block}`,
+    `.sf-cut{position:absolute;left:50%;background:#000}`,
+    `.sf-hole{top:10px;width:14px;height:14px;margin-left:-7px;border-radius:50%;box-shadow:0 0 0 2px #1c1e21}`,
+    `.sf-island{top:11px;width:122px;height:34px;margin-left:-61px;border-radius:20px}`,
+    `.sf-content{flex:1;min-height:0;position:relative;background:#fff}`,
+    `.sf-content iframe{border:0;background:#fff;width:100%;height:100%;display:block}`,
+    `.sf-bar{flex:none;height:${k.bar}px;display:flex;justify-content:center;align-items:center;background:var(--sf-bg)}`,
+    `.sf-bar i{display:block;width:${k.indicator}px;height:5px;border-radius:3px;background:var(--sf-fg);opacity:.85}`,
+    `.sf-btn{position:absolute;right:-5px;width:5px;padding:0;border:0;border-radius:0 2px 2px 0;background:#5b6068;box-shadow:0 0 0 1px #000;cursor:pointer}.sf-btn::before{content:"";position:absolute;top:-6px;bottom:-6px;left:-4px;right:-10px}.sf-btn:focus-visible,.sf-lock button:focus-visible,.sf-menu button:focus-visible{outline:3px solid #4da3ff;outline-offset:2px}.sf-power{top:200px;height:80px}.sf-volup{top:310px;height:56px}.sf-voldown{top:376px;height:56px}`,
+    `.sf-lock,.sf-boot,.sf-off,.sf-menu,.sf-vol{position:absolute;z-index:5}.sf-lock[hidden],.sf-boot[hidden],.sf-off[hidden],.sf-menu[hidden],.sf-vol[hidden]{display:none}.sf-off{inset:0;z-index:7;background:#000;cursor:pointer}`,
+    `.sf-lock{inset:0;background:#10151c;color:#fff;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:14px;font-family:system-ui,sans-serif}.sf-lock-time{font-size:64px;font-weight:300}.sf-lock-hint{font-size:14px;opacity:.7}.sf-lock button{margin-top:8px;padding:10px 28px;border:1px solid #fff6;border-radius:999px;background:transparent;color:#fff;font:600 15px system-ui,sans-serif;cursor:pointer}`,
+    `.sf-boot{inset:0;z-index:6;background:#000;color:#fff;display:flex;align-items:center;justify-content:center;font:700 34px system-ui,sans-serif;letter-spacing:.04em}`,
+    `.sf-vol{top:80px;right:12px;padding:8px 14px;border-radius:14px;background:#222d;color:#fff;font:600 14px system-ui,sans-serif}`,
+    `.sf-menu{left:50%;top:50%;transform:translate(-50%,-50%);display:flex;flex-direction:column;gap:8px;padding:14px;border-radius:16px;background:#222;box-shadow:0 8px 30px #0008}.sf-menu button{padding:10px 24px;border:0;border-radius:10px;background:#3a3d42;color:#fff;font:600 15px system-ui,sans-serif}`,
+    `.sf-label{position:absolute;left:0;right:0;bottom:3px;text-align:center;font:600 9px system-ui,sans-serif;letter-spacing:.08em;text-transform:uppercase;color:#9aa0a6}`,
+  ].join("\n");
+  return { skin, width: k.width, height: k.height, outerWidth, outerHeight, html, css };
+}

package/lifecycle.mjs

@@ -0,0 +1,50 @@
+// Lock, unlock and restart for the simulated phone. Pure state: no DOM, no timers.
+// The server keeps one of these per session and logs each step; the frame page draws the lock screen and boot screen.
+
+/** Typed error for a lifecycle action that cannot run now. */
+export class LifecycleError extends Error { constructor(code, message) { super(message); this.code = code; } }
+
+/** A new phone state: unlocked, never restarted. `reloads` counts cold starts of the app (the first load is 1). */
+export function createLifecycle() {
+  return { locked: false, reloads: 1, restarts: 0, log: [] };
+}
+
+const note = (st, name, extra = {}) => { st.log.push({ at: Date.now(), name, source: "simulated", ...extra }); };
+
+/** Power press. Locks an unlocked phone. Throws already_locked if it is locked. */
+export function lock(st) {
+  if (st.locked) throw new LifecycleError("already_locked", "the phone is already locked: call unlock first");
+  st.locked = true; note(st, "lock"); return st;
+}
+
+/** Swipe up on the lock screen. Throws not_locked if the phone is unlocked. The app and its screen are untouched. */
+export function unlock(st) {
+  if (!st.locked) throw new LifecycleError("not_locked", "the phone is not locked");
+  st.locked = false; note(st, "unlock"); return st;
+}
+
+/** Restart from the power menu: the app cold-starts (the caller reloads it), storage is kept, the phone ends unlocked. */
+export function restart(st) {
+  st.locked = false; st.restarts++; st.reloads++; note(st, "restart", { reloads: st.reloads }); return st;
+}
+
+/** Throws a typed error when the phone is locked, so no input reaches the app behind the lock screen. */
+export function assertUnlocked(st) {
+  if (st.locked) throw new LifecycleError("phone_locked", "the phone is locked, so nothing was sent to the app. Call unlock first.");
+}
+
+/** Lock screen markup (time and a swipe hint). `time` is plain text such as "9:41". */
+export function lockScreenHtml(time = "9:41") {
+  const t = String(time).replace(/[<>&"'\\]/g, "").slice(0, 12);
+  return `<div class="sf-lock" data-part="lock-screen" role="dialog" aria-label="Lock screen" tabindex="-1" hidden><div class="sf-lock-time" data-part="lock-time">${t}</div><div class="sf-lock-hint">Swipe up to unlock</div><button type="button" data-part="unlock-button">Unlock</button></div>`;
+}
+
+/** Boot screen markup: the Shipvo name on black. Shown for a moment during restart. */
+export function bootScreenHtml() {
+  return `<div class="sf-boot" data-part="boot-screen" hidden><div class="sf-boot-logo">Shipvo</div></div>`;
+}
+
+/** Screen shown after "Power off": black. A click on it, or the power button, turns the phone on again. */
+export function offScreenHtml() {
+  return `<div class="sf-off" data-part="off-screen" role="button" tabindex="0" aria-label="Phone is off. Press to power on" hidden></div>`;
+}

package/mock-rules.mjs

@@ -0,0 +1,28 @@
+// Network mock rules sent by a test (`phone.mockNetwork` in @shipvo/test).
+// The wire format here and the encoder in packages/test/src/phone.ts (encodeMockRules) must stay in sync.
+// Wire rule: { url: string } or { urlRegex: { source, flags } }, optional method,
+// and response: { status, body (string), headers (object of strings), delayMs }.
+export class MockRuleError extends Error { constructor(message) { super(message); this.code = "mock_invalid"; } }
+
+export function parseMockRules(raw) {
+  if (!Array.isArray(raw)) throw new MockRuleError("mock rules must be an array");
+  return raw.map((r, i) => {
+    const bad = (why) => new MockRuleError(`mock rule ${i}: ${why}`);
+    if (!r || typeof r !== "object") throw bad("must be an object");
+    let match;
+    if (typeof r.url === "string" && r.url) { const exact = r.url; match = (u) => u === exact; }
+    else if (r.urlRegex && typeof r.urlRegex.source === "string") {
+      let re; try { re = new RegExp(r.urlRegex.source, String(r.urlRegex.flags ?? "").replace(/[gy]/g, "")); } catch { throw bad("url is not a valid pattern"); }
+      match = (u) => re.test(u);
+    } else throw bad("url must be a non-empty string or a RegExp");
+    if (r.method !== undefined && (typeof r.method !== "string" || !r.method)) throw bad("method must be a non-empty string");
+    const resp = r.response;
+    if (!resp || typeof resp !== "object") throw bad("response is required");
+    if (!Number.isInteger(resp.status) || resp.status < 100 || resp.status > 599) throw bad("status must be an integer from 100 to 599");
+    if (typeof resp.body !== "string") throw bad("body must be a string");
+    if (resp.delayMs !== undefined && (typeof resp.delayMs !== "number" || !(resp.delayMs >= 0) || resp.delayMs > 60000)) throw bad("delayMs must be a number from 0 to 60000");
+    const headers = resp.headers ?? {};
+    if (typeof headers !== "object" || Array.isArray(headers) || Object.values(headers).some((v) => typeof v !== "string")) throw bad("headers must be an object of strings");
+    return { match, method: r.method?.toUpperCase(), status: resp.status, body: resp.body, headers, delayMs: resp.delayMs ?? 0 };
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipvo/sim",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "license": "Apache-2.0",
   "description": "The Shipvo simulator: runs a Shipvo app's web build in a phone-sized headless browser and exposes it to agents (accessibility tree, tap/type/scroll, simulated device, mock backend). Used by @shipvo/mcp and `shipvo sim`.",
@@ -9,11 +9,24 @@
   },
   "exports": {
     "./server.mjs": "./server.mjs",
+    "./screen-rules.mjs": "./screen-rules.mjs",
+    "./frame.mjs": {
+      "types": "./frame.d.mts",
+      "default": "./frame.mjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "server.mjs",
+    "chromium-hint.mjs",
+    "browser-resolver.mjs",
     "app-name.mjs",
+    "frame.mjs",
+    "lifecycle.mjs",
+    "frame.d.mts",
+    "mock-rules.mjs",
+    "screen-rules.mjs",
+    "push-notification.mjs",
     "README.md"
   ],
   "peerDependencies": {

package/push-notification.mjs

@@ -0,0 +1,7 @@
+// The `push_notification` action: hand a push to the device layer in the page and report whether the app got it.
+// `__pnDevice.push` returns the notification id, or nothing when permission blocks it.
+export async function pushNotification(page, body) {
+  const nid = await page.evaluate((n) => globalThis.__pnDevice?.push(n), { title: body.title ?? "", body: body.body ?? "", data: body.data ?? {} });
+  await page.waitForTimeout(200);
+  return { delivered: !!nid, id: nid ?? undefined };
+}

package/screen-rules.mjs

@@ -0,0 +1,45 @@
+// The rules that decide what is "on screen" for an agent. Plain ES module, no imports, so the simulator
+// (`server.mjs`) and the `shipvo run` frame page share one copy. The DOM functions are self-contained:
+// they call no other function, so they can be serialised and run inside a page with `(${fn})(document)`.
+
+/** Remove the markers that `applyScreenRules` set. */
+export function clearScreenRules(document) {
+  for (const el of document.querySelectorAll("[data-pn-offscreen]")) { el.removeAttribute("aria-hidden"); el.removeAttribute("data-pn-offscreen"); }
+}
+
+/** Call `clearScreenRules` first. Hide what a phone would not expose: content behind a modal sheet and off-screen items of a horizontal list. */
+export function applyScreenRules(document) {
+  const win = document.defaultView;
+  // A modal sheet (accessibilityViewIsModal / aria-modal) hides everything behind it from assistive tech on phones.
+  const modal = [...document.querySelectorAll('[aria-modal="true"]')].pop();
+  if (modal) for (let node = modal; node && node !== document.body; node = node.parentElement)
+    for (const sib of node.parentElement?.children ?? []) if (sib !== node && !sib.hasAttribute("aria-hidden")) { sib.setAttribute("aria-hidden", "true"); sib.setAttribute("data-pn-offscreen", "1"); }
+  // Phones only expose the items of a horizontal list that are on screen.
+  for (const sc of document.querySelectorAll("div")) {
+    const cs = win.getComputedStyle(sc);
+    if (!/(auto|scroll)/.test(cs.overflowX) || sc.scrollWidth <= sc.clientWidth + 1) continue;
+    const box = sc.getBoundingClientRect();
+    const row = sc.firstElementChild; if (!row) continue;
+    for (const item of row.children) {
+      const r = item.getBoundingClientRect();
+      if (r.right <= box.left + 1 || r.left >= box.right - 1) { item.setAttribute("aria-hidden", "true"); item.setAttribute("data-pn-offscreen", "1"); }
+    }
+  }
+}
+
+/** Post-process an accessibility snapshot: drop empty generic lines, `aria-hidden` subtrees and the inner text of labelled controls. */
+export function filterTree(tree) {
+  const lines = tree.split("\n").filter((l) => !/^\s*- generic \[ref=e\d+\]:?\s*$/.test(l));
+  // A screen reader announces a control's label, not the words inside it (Android and iOS group a pressable's
+  // children into one element). Drop the inner text lines of labelled controls, as the phones do.
+  const out = []; let hideBelow = -1;
+  for (const l of lines) {
+    const indent = l.search(/\S/);
+    if (hideBelow >= 0 && indent > hideBelow) continue;
+    hideBelow = -1;
+    if (/\[aria-hidden\]/.test(l)) { hideBelow = indent; continue; }   // hidden from assistive tech: not on screen
+    out.push(l);
+    if (/^\s*- (button|radio|link|checkbox|switch|tab) "[^"]+"/.test(l) && /:\s*$/.test(l)) hideBelow = indent;
+  }
+  return out.join("\n");
+}

package/server.mjs

@@ -9,13 +9,19 @@ import { readFileSync, existsSync, writeFileSync, appendFileSync, mkdirSync, sta
 import { join, extname, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { withAppName } from "./app-name.mjs";
+import { parseMockRules } from "./mock-rules.mjs";
+import { pushNotification } from "./push-notification.mjs";
 import { createRequire } from "node:module";
 import { execSync } from "node:child_process";
+import { resolveBrowser } from "./browser-resolver.mjs";
+import { launchErrorMessage } from "./chromium-hint.mjs";
+import { createLifecycle, lock, unlock, restart, assertUnlocked, LifecycleError } from "./lifecycle.mjs";
+import { applyScreenRules, clearScreenRules, filterTree } from "./screen-rules.mjs";
 // Playwright: the app's own install first (its browsers match it), then this package's, then a global one.
 const require_ = createRequire(import.meta.url);
-let pw;
-for (const get of [() => createRequire(join(process.cwd(), "package.json"))("playwright"), () => require_("playwright"), () => require_(join(execSync("npm root -g").toString().trim(), "playwright"))]) {
-  try { pw = get(); break; } catch {}
+let pw, pwVersion;
+for (const from of [() => createRequire(join(process.cwd(), "package.json")), () => require_, () => { const root = execSync("npm root -g").toString().trim(); return (id) => require_(join(root, id)); }]) {
+  try { const r = from(); pw = r("playwright"); try { pwVersion = r("playwright/package.json").version; } catch {} break; } catch {}
 }
 if (!pw) { console.error("playwright is not installed: npm i -D playwright && npx playwright install chromium"); process.exit(2); }
 const { chromium, devices } = pw;
@@ -40,7 +46,17 @@ async function resolveApp(spec) {
 }
 mkdirSync(DIR, { recursive: true });
 const MIME = { ".html": "text/html", ".js": "text/javascript", ".json": "application/json", ".png": "image/png", ".ico": "image/x-icon", ".ttf": "font/ttf", ".css": "text/css" };
-const browser = await chromium.launch();
+// Chromium starts after the server is listening (see the end of this file). Handlers await this shared promise.
+const LAUNCH_TIMEOUT_MS = 60_000;
+let launchBrowser;
+const browserReady = new Promise((resolve, reject) => { launchBrowser = () => {
+  // Resolve first (it may download a browser, which can take longer than the launch timeout), then time the launch only.
+  let opts;
+  try { opts = resolveBrowser({ pw, executablePath: arg("chromium", undefined) }); } catch (e) { reject(e); return; }
+  const timer = setTimeout(() => reject(new Error(`Chromium did not start within ${LAUNCH_TIMEOUT_MS / 1000} s`)), LAUNCH_TIMEOUT_MS);
+  chromium.launch(opts).then(resolve, reject).finally(() => clearTimeout(timer));
+}; });
+browserReady.catch((e) => { console.error(`sim: ${launchErrorMessage(e.message, pwVersion)}`); process.exit(1); });
 const sessions = new Map();
 
 const phone = { ...devices["Pixel 5"], viewport: { width: 393, height: 851 } };
@@ -49,12 +65,17 @@ async function newSession(id, opts = {}) {
   if (sessions.has(id)) await sessions.get(id).ctx.close();
   const target = await resolveApp(opts.app);
   writeFileSync(join(DIR, `${id}.json`), JSON.stringify({ orders: [] })); writeFileSync(join(DIR, `${id}.json.log`), "");
-  const ctx = await browser.newContext({ ...phone, colorScheme: opts.dark ? "dark" : "light" });
+  const browser = await browserReady;
+  // Optional width, height (output pixels) and scale (device pixel ratio) make a session render at a store screenshot size.
+  const size = Number.isInteger(opts.width) && Number.isInteger(opts.height) && opts.width > 0 && opts.height > 0 ? { viewport: { width: Math.round(opts.width / (opts.scale || 1)), height: Math.round(opts.height / (opts.scale || 1)) }, deviceScaleFactor: opts.scale || 1 } : {};
+  const ctx = await browser.newContext({ ...phone, ...size, colorScheme: opts.dark ? "dark" : "light" });
   await ctx.addInitScript((cfg) => { globalThis.__PN_SIM__ = cfg; }, { baseUrl: `http://localhost:${PORT}/s/${id}`, appId: target.app, appName: APP_NAME, seed_cart: opts.seed_cart ?? null, device: opts.device ?? null });
   const page = await ctx.newPage();
+  const errors = [];
+  page.on("pageerror", (e) => errors.push(String(e?.message ?? e).split("\n")[0]));
   await page.goto(target.url, { waitUntil: "networkidle" });
   await page.waitForTimeout(300);
-  sessions.set(id, { ctx, page, app: target.app, release: target.release, startedAt: new Date().toISOString() });
+  sessions.set(id, { ctx, page, errors, app: target.app, release: target.release, startedAt: new Date().toISOString(), life: createLifecycle() });
 }
 
 // Refs are only meaningful for the document that issued them: a full page load restarts Playwright's counter, so an
@@ -71,50 +92,21 @@ class SimError extends Error { constructor(code, message) { super(message); this
 async function screen(page) {
   await page.waitForTimeout(150);
   const epoch = await epochOf(page);
-  // Phones only expose the items of a horizontal list that are on screen; hide the rest, as a phone would,
-  // so an agent learns to swipe the rail ("scroll right <ref>") exactly as it must on a device.
-  await page.evaluate(() => {
-    for (const el of document.querySelectorAll("[data-pn-offscreen]")) { el.removeAttribute("aria-hidden"); el.removeAttribute("data-pn-offscreen"); }
-    // A modal sheet (accessibilityViewIsModal / aria-modal) hides everything behind it from assistive tech on phones.
-    const modal = [...document.querySelectorAll('[aria-modal="true"]')].pop();
-    if (modal) for (let node = modal; node && node !== document.body; node = node.parentElement)
-      for (const sib of node.parentElement?.children ?? []) if (sib !== node && !sib.hasAttribute("aria-hidden")) { sib.setAttribute("aria-hidden", "true"); sib.setAttribute("data-pn-offscreen", "1"); }
-    for (const sc of document.querySelectorAll("div")) {
-      const cs = getComputedStyle(sc);
-      if (!/(auto|scroll)/.test(cs.overflowX) || sc.scrollWidth <= sc.clientWidth + 1) continue;
-      const box = sc.getBoundingClientRect();
-      const row = sc.firstElementChild; if (!row) continue;
-      for (const item of row.children) {
-        const r = item.getBoundingClientRect();
-        if (r.right <= box.left + 1 || r.left >= box.right - 1) { item.setAttribute("aria-hidden", "true"); item.setAttribute("data-pn-offscreen", "1"); }
-      }
-    }
-  });
+  // Hide what a phone would not expose, so an agent learns to swipe a rail exactly as it must on a device.
+  await page.evaluate(`(${clearScreenRules})(document); (${applyScreenRules})(document)`);
   // What is hidden from assistive tech must not appear at all: this Playwright keeps aria-hidden nodes but strips
   // their names. `inert` removes them from the accessibility tree; it is set only for the snapshot and removed after.
   await page.evaluate(() => { for (const el of document.querySelectorAll('[aria-hidden="true"]')) { el.setAttribute("data-pn-prev-display", el.style.display || ""); el.style.setProperty("display", "none", "important"); } });
   const tree = await page.locator("body").ariaSnapshot({ mode: "ai" });
   await page.evaluate(() => { for (const el of document.querySelectorAll("[data-pn-prev-display]")) { const prev = el.getAttribute("data-pn-prev-display"); if (prev) el.style.display = prev; else el.style.removeProperty("display"); el.removeAttribute("data-pn-prev-display"); } });
-  const lines = tree.split("\n").filter((l) => !/^\s*- generic \[ref=e\d+\]:?\s*$/.test(l));
-  // A screen reader announces a control's label, not the words inside it (Android and iOS group a pressable's
-  // children into one element). Drop the inner text lines of labelled controls, as the phones do.
-  const out = []; let hideBelow = -1;
-  for (const l of lines) {
-    const indent = l.search(/\S/);
-    if (hideBelow >= 0 && indent > hideBelow) continue;
-    hideBelow = -1;
-    if (/\[aria-hidden\]/.test(l)) { hideBelow = indent; continue; }   // hidden from assistive tech: not on screen
-    out.push(l);
-    if (/^\s*- (button|radio|link|checkbox|switch|tab) "[^"]+"/.test(l) && /:\s*$/.test(l)) hideBelow = indent;
-  }
-  const text = out.join("\n");
+  const text = filterTree(tree);
   return epoch ? text.replace(/\[ref=(e\d+)\]/g, `[ref=p${epoch}$1]`) : text;
 }
 
 function log(id, action, ok, extra = {}) { appendFileSync(join(DIR, `${id}.json.log`), JSON.stringify({ at: Date.now(), name: action, ok, ...extra }) + "\n"); }
 
 async function act(id, body) {
-  const s = sessions.get(id); if (!s) throw new Error(`no session '${id}': call /session first`);
+  const s = sessions.get(id); if (!s) throw new SimError("no_session", `no session '${id}': call /session first`);
   const { page } = s;
   // A ref is valid only for the page it came from and while its element is unchanged. Re-snapshot first, so a node that
   // was re-rendered with new content has lost its old ref, then fail with a typed error instead of acting on anything else.
@@ -129,9 +121,38 @@ async function act(id, body) {
     if ((await l.count()) !== 1) throw stale();
     return l;
   };
+  // Before acting on an element, say why it cannot receive the action. Nothing has reached the app when this throws.
+  const NOT_DELIVERED = { not_visible: "is not visible", disabled: "is disabled", covered: "is covered by another element" };
+  const ready = async (l) => {
+    const fail = (reason, what) => new SimError(reason, `${what} ${NOT_DELIVERED[reason]}, so nothing was sent to the app.`);
+    if (!(await l.isVisible())) throw fail("not_visible", String(body.ref));
+    // Still off the screen after scrolling it into view (for example a fixed element parked outside the window).
+    await l.scrollIntoViewIfNeeded({ timeout: 1000 }).catch(() => {});
+    const box = await l.boundingBox(); const vp = page.viewportSize();
+    if (!box || (vp && (box.x + box.width <= 0 || box.y + box.height <= 0 || box.x >= vp.width || box.y >= vp.height))) throw fail("not_visible", String(body.ref));
+    if (await l.isDisabled()) throw fail("disabled", String(body.ref));
+    const covered = await l.evaluate((el) => {
+      const r = el.getBoundingClientRect();
+      const top = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+      return !!top && top !== el && !el.contains(top) && !top.contains(el);
+    });
+    if (covered) throw fail("covered", String(body.ref));
+  };
+  // A locked phone takes no input: say so with a typed error before anything reaches the app.
+  if (["tap", "type", "scroll", "back", "open_url", "open_notification"].includes(body.action)) { try { assertUnlocked(s.life); } catch (e) { throw new SimError(e.code, e.message); } }
   switch (body.action) {
+    // Simulated lock, unlock and restart. Restart reloads the page (a cold start of the app); the browser context keeps storage.
+    case "lock": case "unlock": {
+      try { (body.action === "lock" ? lock : unlock)(s.life); } catch (e) { if (e instanceof LifecycleError) throw new SimError(e.code, e.message); throw e; }
+      return { locked: s.life.locked, screen: s.life.locked ? "Lock screen" : await screen(page) };
+    }
+    case "restart": {
+      restart(s.life);
+      await page.reload({ waitUntil: "networkidle" }); await page.waitForTimeout(300);
+      return { reloads: s.life.reloads, restarts: s.life.restarts, screen: await screen(page) };
+    }
     case "screen": break;
-    case "tap": await (await resolve(body.ref)).click({ timeout: 3000 }); break;
+    case "tap": { const t = await resolve(body.ref); await ready(t); await t.click({ timeout: 3000 }); break; }
     case "type": {
       // A labelled text field may resolve to its wrapper; type into the real input inside it, as a phone focuses the field.
       let t = await resolve(body.ref);
@@ -143,7 +164,9 @@ async function act(id, body) {
         if ((await named.count()) !== 1) throw new Error(`${body.ref} is not a text field. Type into a "textbox" ref.`);
         t = named;
       }
-      await t.fill(String(body.text ?? ""), { timeout: 3000 }); if (body.enter) await t.press("Enter"); break;
+      await ready(t);
+      await t.fill(String(body.text ?? ""), { timeout: 3000 }); if (body.enter) await t.press("Enter");
+      return { delivery: "delivered", value: await t.inputValue().catch(() => null), screen: await screen(page) };
     }
     case "scroll": {
       const target = body.ref ? await resolve(body.ref) : page.locator("body");
@@ -154,10 +177,34 @@ async function act(id, body) {
     }
     // Simulated device: what the phone "has" and what happens to it. See @shipvo/device.
     case "set_device": await page.evaluate((d) => globalThis.__pnDevice?.set(d), body.device ?? {}); break;
-    case "push_notification": await page.evaluate((n) => globalThis.__pnDevice?.push(n), { title: body.title ?? "", body: body.body ?? "", data: body.data ?? {} }); break;
+    case "push_notification": return { ...(await pushNotification(page, body)), screen: await screen(page) };
     case "notifications": return { notifications: await page.evaluate(() => globalThis.__pnDevice?.notifications() ?? []), screen: await screen(page) };
     case "open_notification": { const ok = await page.evaluate((nid) => globalThis.__pnDevice?.openNotification(nid), body.id); if (!ok) throw new Error("no such notification"); await page.waitForTimeout(400); break; }
-    case "device_log": return { log: await page.evaluate(() => globalThis.__pnDevice?.log() ?? []), capabilities: await page.evaluate(() => globalThis.__pnDevice?.capabilities() ?? null), screen: await screen(page) };
+    case "open_url": {
+      if (typeof body.url !== "string" || !body.url) throw new SimError("bad_url", "open_url needs a url, such as myapp://item/3");
+      const handled = await page.evaluate((u) => globalThis.__pnDevice?.openUrl(u), body.url);
+      if (!handled) throw new SimError("no_url_listener", `the app has no URL listener, so it did not handle ${body.url}. Register one with onUrl from @shipvo/device.`);
+      await page.waitForTimeout(400); break;
+    }
+    // Stub fetch/XHR on the page. Rules live on the session; unmatched requests continue untouched.
+    case "set_network_mocks": {
+      let rules; try { rules = parseMockRules(body.rules ?? []); } catch (e) { throw new SimError(e.code ?? "mock_invalid", e.message); }
+      s.mocks = rules;
+      if (!s.mockRoute) {
+        s.mockRoute = true;
+        await page.route("**/*", async (route) => {
+          const req = route.request();
+          const type = req.resourceType();
+          const rule = (type === "fetch" || type === "xhr") && (s.mocks ?? []).find((m) => (!m.method || m.method === req.method()) && m.match(req.url()));
+          if (!rule) return route.fallback();
+          if (rule.delayMs) await new Promise((r) => setTimeout(r, rule.delayMs));
+          // The app page may come from another origin, so the stub must pass the browser's CORS check.
+          await route.fulfill({ status: rule.status, body: rule.body, headers: { "access-control-allow-origin": "*", ...rule.headers } }).catch(() => {});
+        });
+      }
+      break;
+    }
+    case "device_log": return { log: [...(await page.evaluate(() => globalThis.__pnDevice?.log() ?? [])), ...s.life.log], capabilities: await page.evaluate(() => globalThis.__pnDevice?.capabilities() ?? null), screen: await screen(page) };
     case "diag": {
       const r = await page.evaluate(async () => {
         const cfg = globalThis.__PN_SIM__ ?? {}; const out = { baseUrl: cfg.baseUrl, origin: location.origin };
@@ -168,13 +215,22 @@ async function act(id, body) {
       return { diag: r, screen: await screen(page) };
     }
     case "device_reset": await page.evaluate((d) => globalThis.__pnDevice?.reset(d), body.device ?? {}); break;
-    case "back": { const b = page.getByRole("button", { name: "Back", exact: true }); if (await b.count()) await b.first().click(); else throw new Error("no Back button on this screen"); break; }
-    case "screenshot": { const p = join(DIR, `${id}-${Date.now()}.png`); await page.screenshot({ path: p }); return { path: p, screen: await screen(page) }; }
-    default: throw new Error(`unknown action '${body.action}'. Actions: screen, tap, type, scroll, back, screenshot, set_device, push_notification, notifications, open_notification, device_log, device_reset`);
+    // Uncaught page errors since the last call to this action. Reading them clears the list.
+    case "errors": return { errors: s.errors.splice(0), screen: await screen(page) };
+    case "back": { const b = page.getByRole("button", { name: "Back", exact: true }); if (await b.count()) { await ready(b.first()); await b.first().click(); } else throw new Error("no Back button on this screen"); break; }
+    case "screenshot": {
+      // format "jpeg" has no alpha channel, which the stores require. inline: true also returns the bytes as base64 for clients on another machine.
+      const jpeg = body.format === "jpeg"; const p = join(DIR, `${id}-${Date.now()}.${jpeg ? "jpg" : "png"}`);
+      const buf = await page.screenshot(jpeg ? { path: p, type: "jpeg", quality: 90 } : { path: p });
+      return { path: p, ...(body.inline ? { data: buf.toString("base64") } : {}), screen: await screen(page) };
+    }
+    default: throw new Error(`unknown action '${body.action}'. Actions: screen, lock, unlock, restart, tap, type, scroll, back, screenshot, set_device, push_notification, notifications, open_notification, open_url, errors, device_log, device_reset, set_network_mocks`);
   }
-  return { screen: await screen(page) };
+  return { ...(["tap", "scroll", "back"].includes(body.action) ? { delivery: "delivered" } : {}), screen: await screen(page) };
 }
 
+const DELIVERY = new Set(["tap", "type", "scroll", "back"]);
+const REASONS = new Set(["stale_ref", "not_visible", "disabled", "covered"]);
 const WCACHE = new Map();
 const server = http.createServer(async (req, res) => {
   const url = new URL(req.url, "http://x");
@@ -194,6 +250,8 @@ const server = http.createServer(async (req, res) => {
       if (!hit) { const r = await fetch(`${CONTROL}${key}`); if (!r.ok) return send(r.status, { error: "artifact" }); hit = { type: r.headers.get("content-type") ?? "application/octet-stream", body: Buffer.from(await r.arrayBuffer()) }; WCACHE.set(key, hit); }
       return send(200, hit.body, hit.type);
     }
+    // a founder opening the printed link lands on the app
+    if ((req.method === "GET" || req.method === "HEAD") && url.pathname === "/") { res.writeHead(302, { location: "/app/", ...CORS }); return res.end(); }
     if (url.pathname.startsWith("/app/")) {
       let p = join(DIST, url.pathname.slice(5) || "index.html"); if (!existsSync(p) || statSync(p).isDirectory()) p = join(DIST, "index.html");
       if (extname(p) === ".html") return send(200, withAppName(readFileSync(p, "utf8"), APP_NAME), MIME[".html"]);
@@ -224,7 +282,7 @@ const server = http.createServer(async (req, res) => {
     if (url.pathname === "/session") { await newSession(body.session, body); const s = sessions.get(body.session); log(body.session, "start", true, { app: s.app, release: s.release }); return send(200, { ok: true, app: s.app, release: s.release, screen: await screen(s.page) }); }
     if (url.pathname === "/act") {
       try { const r = await act(body.session, body); log(body.session, body.action, true, body.ref ? { ref: body.ref } : {}); return send(200, { ok: true, ...r }); }
-      catch (e) { log(body.session, body.action, false); const s = sessions.get(body.session); return send(200, { ok: false, error: String(e.message).split("\n")[0], ...(e.code ? { code: e.code } : {}), screen: s ? await screen(s.page) : null }); }
+      catch (e) { log(body.session, body.action, false); const s = sessions.get(body.session); return send(200, { ok: false, error: String(e.message).split("\n")[0], ...(e.code ? { code: e.code } : {}), ...(DELIVERY.has(body.action) && REASONS.has(e.code) ? { delivery: "not_delivered", reason: e.code, safe_to_retry: true } : {}), screen: s ? await screen(s.page) : null }); }
     }
     send(404, { error: "not found" });
   } catch (e) { send(500, { error: String(e) }); }
@@ -232,3 +290,4 @@ const server = http.createServer(async (req, res) => {
 // Agents and parity runs pause between actions; keep idle connections open well beyond Node's 5 s default.
 server.keepAliveTimeout = 300_000; server.headersTimeout = 310_000; server.requestTimeout = 0;
 server.listen(PORT, () => console.log(`Shipvo UI simulator on http://localhost:${PORT} (sessions in ${DIR})`));
+launchBrowser();