@shipvo/sim 0.1.4 → 0.1.6

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

@@ -10,14 +10,29 @@ 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 { applyProfile, getProfile } from "./network-profiles.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 { PhoneBrowser, BrowserError, checkUrl } from "./phone-browser.mjs";
+import { acceptWebSocket } from "./ws-lite.mjs";
+import { browserAppPage } from "./browser-app.mjs";
+import { launchErrorMessage } from "./chromium-hint.mjs";
+import { shadeAction, SHADE_ACTIONS } from "./shade-actions.mjs";
+import { settingsAction, syncMedia, SETTINGS_ACTIONS } from "./settings-actions.mjs";
+import { SettingsError } from "./settings.mjs";
+import { AppsError, loadProfile, profilePatch, installApp, uninstallApp, switchApp, describeApps } from "./apps.mjs";
+import { UpdateError, createUpdate, checkForUpdate, applyUpdate, bootDone, updateView, bannerText } from "./update.mjs";
+import { ShadeError } from "./shade.mjs";
+import { createNav, pressHome, openRecents, resume, killApp, assertForeground, setVisibilityInPage, awayScreenHtml, NavError } from "./nav.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;
@@ -26,6 +41,13 @@ const here = dirname(fileURLToPath(import.meta.url));
 const arg = (k, d) => { const i = process.argv.indexOf(`--${k}`); return i > 0 ? process.argv[i + 1] : d; };
 let CFG = {}; try { CFG = JSON.parse(readFileSync(join(process.cwd(), "shipvo.json"), "utf8")); } catch {}
 const PORT = Number(arg("port", 4545)), DIR = arg("dir", "/tmp/pn-ui"), DIST = arg("dist", join(process.cwd(), "sim-dist"));
+// phone.json: only a missing default ./phone.json is ignored. A bad --phone path or a bad file fails sessions with bad_profile.
+let PROFILE = null, PROFILE_ERR = null;
+{ const given = arg("phone", null);
+  try { PROFILE = readFileSync(given ?? join(process.cwd(), "phone.json"), "utf8"); }
+  catch (e) { if (given || e?.code !== "ENOENT") PROFILE_ERR = `cannot read ${given ?? "phone.json"}: ${e?.code ?? e?.message}`; } }
+// Simulated OTA source: a control plane stub that serves <url>/pointer.json (signed) and the bundle. The key is the app's public key.
+const UPDATE = { url: arg("update-url", process.env.PN_UPDATE_URL || ""), key: arg("update-key", process.env.PN_UPDATE_KEY || "") };
 const DEFAULT_APP = arg("app", CFG.appId || "tide"), APP_NAME = CFG.name || "Tide & Tackle";
 // Published releases: open_app("tide@r13") loads the web artifact that `shipvo publish` stored next to the phone bundle.
 const CONTROL = (process.env.PN_CONTROL || process.env.CONTENT_FROM || CFG.controlPlane || "https://api.shipvo.dev").replace(/\/$/, "");
@@ -46,26 +68,79 @@ const MIME = { ".html": "text/html", ".js": "text/javascript", ".json": "applica
 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);
-  const executablePath = arg("chromium", undefined);
-  chromium.launch(executablePath ? { executablePath } : {}).then(resolve, reject).finally(() => clearTimeout(timer));
+  chromium.launch(opts).then(resolve, reject).finally(() => clearTimeout(timer));
 }; });
-browserReady.catch((e) => { console.error(`sim: could not launch Chromium: ${e.message.split("\n")[0]}`); process.exit(1); });
+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 } };
 
+// The phone's Browser app. Chromium starts on the first open. Pages that link to the app's own scheme hand the link to the app.
+// The instance is shared through s.browserP, so two opens at once make one Chromium context.
+function phoneBrowser(s) {
+  s.browserP ??= (async () => {
+    s.peers = s.peers ?? new Set();
+    const b = new PhoneBrowser(await browserReady, { allowPrivate: false, allowHosts: [], device: phone, onDeepLink: (u) => {
+      s.page.evaluate((x) => globalThis.__pnDevice?.openUrl(x), u).catch(() => {});
+      for (const peer of s.peers) peer.send(JSON.stringify({ type: "app", url: u }));   // the phone goes back to the app
+    } });
+    b.onChange = () => pushState(s);
+    s.browser = b;
+    return b;
+  })();
+  s.browserP.catch(() => { s.browserP = undefined; });
+  return s.browserP;
+}
+// One screencast feeds every viewer of the Browser app.
+function ensureCast(s) {
+  const b = s.browser; if (!b?.page || b.screencast || !s.peers?.size) return;
+  b.startScreencast((f) => { const msg = JSON.stringify({ type: "frame", ...f }); for (const p of s.peers) p.send(msg); }).catch(() => {});
+  pushState(s);
+}
+async function pushState(s) {
+  const b = s.browser; if (!b || !s.peers?.size) return;
+  const tabs = await b.tabs().catch(() => []);
+  const msg = JSON.stringify({ type: "state", tabs, url: b.page?.url() ?? "" });
+  for (const peer of s.peers) peer.send(msg);
+}
+/** Opens a web page in the Browser app. Resolves { ok: true }, or { ok: false, code, message } when the page is refused. Viewers get an `error` message too. */
+async function openInBrowserApp(id, url) {
+  const s = sessions.get(id); if (!s) return { ok: false, code: "no_session", message: "no session" };
+  const b = await phoneBrowser(s);
+  for (const peer of s.peers ?? []) peer.send(JSON.stringify({ type: "browser", url }));   // the phone shows the Browser app
+  try { await b.open(url); ensureCast(s); return { ok: true }; } catch (e) {
+    const r = { ok: false, code: e.code ?? "error", message: String(e.message).split("\n")[0] };
+    for (const peer of s.peers ?? []) peer.send(JSON.stringify({ type: "error", code: r.code, message: r.message }));
+    return r;
+  }
+}
+
 async function newSession(id, opts = {}) {
-  if (sessions.has(id)) await sessions.get(id).ctx.close();
+  if (sessions.has(id)) { const old = sessions.get(id); for (const p of old.peers ?? []) p.close(); await (await old.browserP?.catch(() => undefined))?.close(); await old.ctx.close(); }
   const target = await resolveApp(opts.app);
   writeFileSync(join(DIR, `${id}.json`), JSON.stringify({ orders: [] })); writeFileSync(join(DIR, `${id}.json.log`), "");
   const browser = await browserReady;
-  const ctx = await browser.newContext({ ...phone, colorScheme: opts.dark ? "dark" : "light" });
+  // 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" });
+  // The app's Linking.openURL for a web page lands here (see @shipvo/device): it opens in the Browser app, not in the app.
+  await ctx.exposeFunction("__pnOpenBrowser", (url) => openInBrowserApp(id, String(url)));
   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 = [];
+  // phone.json: the apps and settings this phone starts with. The same profile gives the same phone every run.
+  let apps; try { if (PROFILE_ERR && opts.phone === undefined) throw new AppsError("bad_profile", PROFILE_ERR); apps = loadProfile(opts.phone ?? PROFILE ?? {}); } catch (e) { await ctx.close(); throw e instanceof AppsError ? new SimError(e.code, e.message) : e; }
+  const pageErrors = { n: 0 };
+  page.on("pageerror", (e) => { pageErrors.n++; 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() });
+  const patch = profilePatch(apps);
+  if (Object.keys(patch).length) { await page.evaluate((p) => globalThis.__pnDevice?.set?.(p), patch); await syncMedia(page); }
+  sessions.set(id, { pageErrors, update: createUpdate({ release: target.release, url: target.url }), updateSrc: { url: opts.update_url ?? UPDATE.url, key: opts.update_key ?? UPDATE.key }, apps, ctx, page, errors, app: target.app, release: target.release, startedAt: new Date().toISOString(), life: createLifecycle(), shade: { open: "none" }, nav: createNav() });
 }
 
 // Refs are only meaningful for the document that issued them: a full page load restarts Playwright's counter, so an
@@ -77,48 +152,73 @@ async function epochOf(page) {
   if (!d) DOCS.set(page, { id, epoch: 0 }); else if (d.id !== id) { d.id = id; d.epoch++; }
   return DOCS.get(page).epoch;
 }
+// The update banner is a status element in the page, so it is in the accessibility tree. A reload drops it, so boot puts it back.
+async function showBanner(s) {
+  const text = bannerText(s.update);
+  await s.page.evaluate((t) => { document.querySelector("[data-pn-update-banner]")?.remove(); if (!t) return;
+    const d = document.createElement("div"); d.setAttribute("data-pn-update-banner", ""); d.setAttribute("role", "status"); d.setAttribute("aria-label", t); d.textContent = t;
+    d.style.cssText = "position:fixed;left:8px;right:8px;top:8px;z-index:2147483647;padding:8px 12px;border-radius:12px;background:#1d2733;color:#fff;font:600 13px system-ui,sans-serif;pointer-events:none";
+    document.body.appendChild(d); }, text).catch(() => {});
+}
+// One boot of the app. `url` loads that bundle, else the page reloads (a cold start). A page error while loading is a failed boot: three in a row
+// on a new release send the phone back to the release it had.
+async function boot(s, url) {
+  const before = s.pageErrors.n;
+  if (url) await s.page.goto(url, { waitUntil: "networkidle" }); else await s.page.reload({ waitUntil: "networkidle" });
+  await s.page.waitForTimeout(300);
+  const r = bootDone(s.update, s.pageErrors.n > before);
+  if (r.revert) { await s.page.goto(r.url, { waitUntil: "networkidle" }); await s.page.waitForTimeout(300); }
+  await showBanner(s);
+}
+// Fetch layer. Mock rules win; otherwise fetch/XHR run under the session's network profile (default online, untouched).
+async function ensureNetworkRoute(s, page) {
+  if (s.mockRoute) return;
+  s.mockRoute = true;
+  await page.route("**/*", async (route) => {
+    const req = route.request();
+    const type = req.resourceType();
+    if (type !== "fetch" && type !== "xhr") return route.fallback();
+    const rule = (s.mocks ?? []).find((m) => (!m.method || m.method === req.method()) && m.match(req.url()));
+    if (rule) {
+      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.
+      return route.fulfill({ status: rule.status, body: rule.body, headers: { "access-control-allow-origin": "*", ...rule.headers } }).catch(() => {});
+    }
+    if (!s.profiled) return route.fallback();
+    try {
+      const { res } = await s.profiled(req.url(), { method: req.method(), body: req.postDataBuffer() ?? undefined, route });
+      await route.fulfill({ response: res }).catch(() => {});
+    } catch { await route.abort("internetdisconnected").catch(() => {}); }
+  });
+}
+
+// Set the session's network profile. Throws unknown_profile for a bad name. Logged in device_log as simulated.
+async function setNetworkProfile(s, page, name) {
+  let profile; try { profile = getProfile(name); } catch (e) { throw new SimError(e.code, e.message); }
+  const from = s.netProfile ?? "online";
+  s.netProfile = name;
+  s.profiled = name === "online" ? null : applyProfile(async (_url, init) => {
+    // Playwright's APIResponse has headers() as a method. A chunked reply has no content-length, so use the body size.
+    const res = await init.route.fetch(); const headers = res.headers(); const size = String((await res.body()).length);
+    return { res, headers: { get: (n) => { const k = String(n).toLowerCase(); return headers[k] ?? (k === "content-length" ? size : null); } } };
+  }, profile, { clock: { sleep: (ms) => new Promise((r) => setTimeout(r, ms)) } });
+  if (s.profiled) await ensureNetworkRoute(s, page);
+  (s.netLog ??= []).push({ at: Date.now(), name: "network_profile", profile: name, from, source: "simulated" });
+}
+
 class SimError extends Error { constructor(code, message) { super(message); this.code = code; } }
 
 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;
 }
 
@@ -157,9 +257,86 @@ async function act(id, body) {
     });
     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", "tap_xy", "type_keys", "type", "scroll", "back", "open_url", "open_notification", "install_app", "uninstall_app", "switch_app", ...SHADE_ACTIONS, ...SETTINGS_ACTIONS].includes(body.action)) { try { assertUnlocked(s.life); } catch (e) { throw new SimError(e.code, e.message); } }
+  // Home screen or app switcher showing: the app is in the background and takes no input.
+  if (["tap", "tap_xy", "type_keys", "type", "scroll", "back", "open_url", "open_notification", "open_notifications", "open_control_center", "toggle_tile", "dismiss_notification"].includes(body.action)) { try { assertForeground(s.nav); } catch (e) { throw new SimError(e.code, e.message); } }
+  // An open panel covers the app on a phone, so input to the app is refused until it is closed.
+  if (["tap", "tap_xy", "type_keys", "type", "scroll"].includes(body.action) && s.shade.open !== "none") throw new SimError("panel_open", `a panel (${s.shade.open}) is open and covers the app, so nothing was sent to it. Close it first (close_panels).`);
   switch (body.action) {
+    // Home, recents, resume and kill. The app hears them as AppState changes (document.visibilityState). Kill is a cold start.
+    case "press_home": case "open_recents": case "resume_app": case "kill_app": {
+      let ev;
+      try { ev = body.action === "press_home" ? pressHome(s.nav) : body.action === "open_recents" ? openRecents(s.nav) : body.action === "resume_app" ? resume(s.nav) : (killApp(s.nav), null); }
+      catch (e) { if (e instanceof NavError) throw new SimError(e.code, e.message); throw e; }
+      if (ev) await page.evaluate(setVisibilityInPage, ev);
+      if (body.action === "kill_app") { s.life.reloads++; await boot(s); await page.evaluate(setVisibilityInPage, "background"); }
+      const where = s.nav.where;
+      return { where, appState: where === "app" ? "active" : "background", reloads: s.life.reloads, screen: where === "app" ? await screen(page) : where === "home" ? `Home screen\n- button "${APP_NAME}" (the app icon: resume_app opens it)\n${describeApps(s.apps)}` : `App switcher\n- card "${APP_NAME}" (resume_app opens it, kill_app closes it)` };
+    }
+    // Installed apps. Errors are typed: unknown_app, already_installed, not_installed. Logged in device_log as simulated.
+    case "install_app": case "uninstall_app": case "switch_app": {
+      const id = String(body.id ?? "");
+      try {
+        if (body.action === "install_app") installApp(s.apps, id, Array.isArray(body.catalog) ? body.catalog : s.apps.store);
+        else if (body.action === "uninstall_app") uninstallApp(s.apps, id, s.nav);
+        else {
+          const url = s.apps.installed_apps.find((a) => a.id === id)?.url ?? "";
+          // fixture: pages are stand-ins (no navigation). app://<id>[@rN] loads a published release like open_app. Anything else
+          // must pass the same private-host guard as the Browser app, so a profile cannot point Chromium at the local network.
+          let dest = null;
+          const am = /^app:\/\/([a-z0-9-]+(?:@(?:r?\d+|latest))?)$/.exec(url);
+          if (am) dest = (await resolveApp(am[1])).url;
+          else if (/^[a-z][a-z0-9+.-]*:/i.test(url) && !/^fixture:/i.test(url)) {
+            try { dest = (await checkUrl(url, { allowPrivate: false, allowHosts: [] })).href; }
+            catch (e) { if (e instanceof BrowserError) throw new SimError(e.code, e.message); throw e; }
+          }
+          switchApp(s.apps, id, s.nav);
+          if (dest && page.url() !== dest) { await page.goto(dest, { waitUntil: "networkidle" }); await page.waitForTimeout(300); }
+          await page.evaluate(setVisibilityInPage, "active");
+        }
+      } catch (e) { if (e instanceof AppsError) throw new SimError(e.code, e.message); throw e; }
+      if (body.action === "uninstall_app" && s.nav.where === "home") await page.evaluate(setVisibilityInPage, "background");
+      const where = s.nav.where;
+      return { where, current_app: s.apps.current_app, installed_apps: s.apps.installed_apps, screen: where === "app" ? await screen(page) : `Home screen\n${describeApps(s.apps)}` };
+    }
+    // Simulated lock, unlock and restart. Restart reloads the page (a cold start of the app); the browser context keeps storage.
+    case "lock": case "unlock": {
+      if (body.action === "lock") s.shade.open = "none";
+      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) };
+    }
+    // Simulated OTA: check (signed pointer, hash), apply (restart on the new bundle), state. Errors: no_update, not_ready. Every change is in device_log.
+    case "get_update_state": case "check_for_update": case "apply_update": {
+      try {
+        if (body.action === "check_for_update") { await checkForUpdate(s.update, { url: s.updateSrc.url, publicKey: s.updateSrc.key }); await showBanner(s); }
+        else if (body.action === "apply_update") {
+          applyUpdate(s.update, (n) => `http://localhost:${PORT}/u/${body.session}/r${n}/index.html`);
+          s.life.reloads++; s.shade.open = "none"; s.nav.where = "app"; s.life.locked = false;
+          await boot(s, s.update.running.url);
+        }
+      } catch (e) { if (e instanceof UpdateError) throw new SimError(e.code, e.message); throw e; }
+      return { update: updateView(s.update), banner: bannerText(s.update), reloads: s.life.reloads, screen: await screen(page) };
+    }
+    case "restart": {
+      restart(s.life); s.shade.open = "none"; s.nav.where = "app";
+      await boot(s);
+      return { reloads: s.life.reloads, restarts: s.life.restarts, screen: await screen(page) };
+    }
     case "screen": break;
+    // Coordinate input, for the "screenshots and coordinates only" side of scripts/agent-efficiency. Not an MCP tool: agents using
+    // the labelled screen tap by ref. x and y are CSS pixels from the top left of the screenshot.
+    case "tap_xy": { const x = Number(body.x), y = Number(body.y); if (!Number.isFinite(x) || !Number.isFinite(y)) throw new Error("tap_xy needs numbers x and y"); await page.mouse.click(x, y); break; }
+    case "type_keys": await page.keyboard.type(String(body.text ?? ""), { delay: 5 }); if (body.enter) await page.keyboard.press("Enter"); break;
     case "tap": { const t = await resolve(body.ref); await ready(t); await t.click({ timeout: 3000 }); break; }
+    // Where an element is: centre and size as 0..1 of the viewport. Used by the recorder to draw taps. Does not act.
+    case "locate": {
+      let box = null; const vp = page.viewportSize();
+      try { box = await (await resolve(body.ref)).boundingBox({ timeout: 1000 }); } catch {}
+      if (!box || !vp) throw new SimError("not_found", `no element ${body.ref} on this screen.`);
+      const c = (v) => Math.min(1, Math.max(0, v));
+      return { locate: { x: c((box.x + box.width / 2) / vp.width), y: c((box.y + box.height / 2) / vp.height), w: c(box.width / vp.width), h: c(box.height / vp.height) } };
+    }
     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);
@@ -183,10 +360,16 @@ async function act(id, body) {
       break;
     }
     // 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 "set_device": await page.evaluate((d) => globalThis.__pnDevice?.set(d), body.device ?? {}); await syncMedia(page); break;
+    case "open_notifications": case "open_control_center": case "close_panels": case "toggle_tile": case "dismiss_notification": {
+      try { return { ...(await shadeAction(page, s.shade, body)) }; } catch (e) { if (e instanceof ShadeError) throw new SimError(e.code, e.message); throw e; }
+    }
+    case "get_settings": case "set_setting": {
+      try { return { ...(await settingsAction(page, body)) }; } catch (e) { if (e instanceof SettingsError) throw new SimError(e.code, e.message); throw e; }
+    }
     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 "open_notification": { s.shade.open = "none"; 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 "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);
@@ -197,21 +380,31 @@ async function act(id, body) {
     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(() => {});
-        });
-      }
+      await ensureNetworkRoute(s, page);
       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 "set_network_profile": { await setNetworkProfile(s, page, body.profile); break; }
+    // The phone's Chromium (isolated from the app page). Page text is untrusted: results carry source "web".
+    case "browser_open": case "browser_snapshot": case "browser_click": case "browser_type": case "browser_back": case "browser_screenshot": case "browser_tabs": case "browser_close_tab": case "browser_scroll": case "browser_wait_for": {
+      if (body.action === "browser_open" && body.url) { await phoneBrowser(s); if (body.allow_private !== undefined) s.browser.opts.allowPrivate = body.allow_private === true; if (Array.isArray(body.allow_hosts)) s.browser.opts.allowHosts = body.allow_hosts.map(String); }
+      if (!s.browser) { if (body.action === "browser_open") throw new SimError("bad_url", "browser_open needs a url"); throw new SimError("no_page", "no page is open: call browser_open first"); }
+      const b = s.browser;
+      try {
+        switch (body.action) {
+          case "browser_open": { const r = await b.open(String(body.url ?? "")); ensureCast(s); return { ...r }; }
+          case "browser_snapshot": return { ...(await b.snapshot()) };
+          case "browser_click": return { ...(await b.click(body.ref)) };
+          case "browser_type": return { ...(await b.type(body.ref, body.text, body.enter)) };
+          case "browser_back": return { ...(await b.back()) };
+          case "browser_tabs": return { source: "web", untrusted: true, tabs: await b.tabs() };
+          case "browser_close_tab": return { source: "web", untrusted: true, tabs: await b.closeTab(Number(body.index)) };
+          case "browser_scroll": return { ...(await b.scroll(Number.isFinite(body.dy) ? body.dy : 400, Number.isFinite(body.dx) ? body.dx : 0)) };
+          case "browser_wait_for": return { ...(await b.waitFor({ text: body.text, gone: body.gone === true, timeoutMs: body.timeout_ms })) };
+          default: { const p = join(DIR, `${id}-web-${Date.now()}.png`); writeFileSync(p, await b.screenshot()); return { path: p, source: "web", untrusted: true }; }
+        }
+      } catch (e) { throw e.code ? new SimError(e.code, e.message) : e; }
+    }
+    case "device_log": return { log: [...(await page.evaluate(() => globalThis.__pnDevice?.log() ?? [])), ...s.life.log, ...s.apps.log, ...s.update.log, ...(s.netLog ?? []), ...(s.browser?.navigations ?? [])], 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 };
@@ -221,10 +414,30 @@ 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 ready(b.first()); 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, open_url, device_log, device_reset, set_network_mocks`);
+    case "device_reset": await page.evaluate((d) => globalThis.__pnDevice?.reset(d), body.device ?? {}); await syncMedia(page); s.shade.open = "none"; break;
+    // 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) };
+    // Rendered size in CSS px of each ref on the current screen: { sizes: { ref: [width, height] } }. Refs that are gone are left out.
+    case "sizes": {
+      const text = await screen(page); const sizes = {};
+      for (const m of text.matchAll(/\[ref=(\w+)\]/g)) {
+        const raw = m[1].replace(/^p\d+(?=e\d+$)/, "");
+        const box = await page.locator(`aria-ref=${raw}`).first().boundingBox().catch(() => null);
+        if (box) sizes[m[1]] = [Math.round(box.width * 10) / 10, Math.round(box.height * 10) / 10];
+      }
+      return { sizes, screen: text };
+    }
+    case "back": { if (s.shade.open !== "none") { s.shade.open = "none"; break; } 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"}`);
+      // Home screen or switcher showing: draw it over the app for the shot, then take it away. The app stays loaded underneath.
+      const away = s.nav.where !== "app";
+      if (away) await page.evaluate((h) => { const d = document.createElement("div"); d.id = "__pn_away"; d.innerHTML = h; document.body.appendChild(d); }, awayScreenHtml(s.nav.where, APP_NAME));
+      let buf; try { buf = await page.screenshot(jpeg ? { path: p, type: "jpeg", quality: 90 } : { path: p }); } finally { if (away) await page.evaluate(() => document.getElementById("__pn_away")?.remove()); }
+      return { path: p, ...(body.inline ? { data: buf.toString("base64") } : {}), screen: await screen(page) };
+    }
+    default: throw new Error(`unknown action '${body.action}'. Actions: screen, get_update_state, check_for_update, apply_update, install_app, uninstall_app, switch_app, lock, unlock, restart, press_home, open_recents, resume_app, kill_app, open_notifications, open_control_center, close_panels, toggle_tile, dismiss_notification, get_settings, set_setting, tap, locate, type, scroll, back, screenshot, set_device, push_notification, notifications, open_notification, open_url, errors, sizes, device_log, device_reset, set_network_mocks, set_network_profile, browser_open, browser_snapshot, browser_click, browser_type, browser_back, browser_screenshot, browser_tabs, browser_close_tab, browser_scroll, browser_wait_for`);
   }
   return { ...(["tap", "scroll", "back"].includes(body.action) ? { delivery: "delivered" } : {}), screen: await screen(page) };
 }
@@ -250,6 +463,9 @@ 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 bundle this session downloaded and verified: the page that runs is the page that was checked
+    { const um = url.pathname.match(/^\/u\/([\w-]+)\/r(\d+)\/index\.html$/);
+      if (um) { const b = sessions.get(um[1])?.update.bundles.get(Number(um[2])); return b ? send(200, b, MIME[".html"]) : send(404, { error: "no_bundle" }); } }
     // 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/")) {
@@ -274,12 +490,14 @@ const server = http.createServer(async (req, res) => {
       }
       return send(202, { ok: true }); // telemetry etc.
     }
+    // the Browser app, in a phone frame
+    if (req.method === "GET" && url.pathname === "/browser") return send(200, browserAppPage(url.searchParams.get("skin") === "ios" ? "ios" : "android", url.searchParams.get("session") ?? ""), MIME[".html"]);
     // agent API
     if (req.method !== "POST") return send(404, { error: "not found" });
     let raw = ""; for await (const ch of req) raw += ch; const body = raw ? JSON.parse(raw) : {};
     if (url.pathname === "/apps") return send(200, { ok: true, apps: [{ id: DEFAULT_APP, name: APP_NAME }] });
     if (url.pathname === "/sessions") return send(200, { ok: true, sessions: [...sessions.entries()].map(([id, s]) => ({ session: id, app: s.app, release: s.release, started_at: s.startedAt ?? null, url: s.page.url() })) });
-    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 === "/session") { try { await newSession(body.session, body); } catch (e) { if (e instanceof SimError && e.code === "bad_profile") return send(200, { ok: false, code: e.code, error: e.message }); throw e; } 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 } : {}), ...(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 }); }
@@ -287,6 +505,33 @@ const server = http.createServer(async (req, res) => {
     send(404, { error: "not found" });
   } catch (e) { send(500, { error: String(e) }); }
 });
+// The Browser app's live view: frames out, taps, swipes and typing in. Same trust as the HTTP API (loopback), plus an Origin check
+// so another web page open on this machine cannot drive the phone.
+server.on("upgrade", (req, socket) => {
+  const url = new URL(req.url, "http://x");
+  const refuse = (line) => socket.end(`HTTP/1.1 ${line}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+  if (url.pathname !== "/browser/ws") return refuse("404 Not Found");
+  let originHost = null; try { if (req.headers.origin) originHost = new URL(req.headers.origin).host; } catch { originHost = "invalid"; }
+  // A missing Origin is allowed (non-browser clients). The Host comparison does not stop DNS rebinding, since both
+  // values come from the requester; the HTTP API has the same trust level.
+  if (originHost && originHost !== req.headers.host) return refuse("403 Forbidden");
+  const s = sessions.get(url.searchParams.get("session") ?? ""); if (!s) return refuse("404 Not Found");
+  const peer = acceptWebSocket(req, socket, async (text) => {
+    let m; try { m = JSON.parse(text); } catch { return; }
+    const b = s.browser;
+    try {
+      if (m.type === "open") { await openInBrowserApp(url.searchParams.get("session"), String(m.url)); return; }   // a refusal reaches every viewer as an `error` message
+      if (!b) return;
+      if (m.type === "back") await b.back(); else if (m.type === "forward") await b.forward(); else if (m.type === "reload") await b.reload();
+      else if (m.type === "tab") await b.selectTab(Number(m.index)); else if (m.type === "newtab") await b.newTab(); else if (m.type === "closetab") await b.closeTab(Number(m.index));
+      else await b.input(m);
+    } catch (e) { peer.send(JSON.stringify({ type: "error", code: e.code ?? "error", message: String(e.message).split("\n")[0] })); }
+  }, () => { s.peers?.delete(peer); if (!s.peers?.size) s.browser?.stopScreencast(); });
+  if (!peer) return;
+  s.peers = s.peers ?? new Set(); s.peers.add(peer);
+  peer.send(JSON.stringify({ type: "hello", browser: !!s.browser }));
+  ensureCast(s);
+});
 // 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})`));

package/settings-actions.mjs

@@ -0,0 +1,28 @@
+// The server side of the Settings screen: the MCP actions get_settings and set_setting. Errors are SettingsError with a typed `code`.
+import { SettingsError, settingPatch, readSettings, describeSettings } from "./settings.mjs";
+
+const read = async (page) => {
+  const sys = await page.evaluate(() => globalThis.__pnDevice?.system?.() ?? null);
+  if (!sys) throw new SettingsError("no_device", "the app has no simulated device in this session");
+  return sys;
+};
+
+/** Dark mode and reduce motion also reach the app's CSS media queries (prefers-color-scheme, prefers-reduced-motion). */
+export async function syncMedia(page) {
+  const sys = await page.evaluate(() => globalThis.__pnDevice?.system?.() ?? null);
+  if (sys) await page.emulateMedia({ colorScheme: sys.darkMode ? "dark" : "light", reducedMotion: sys.reduceMotion ? "reduce" : "no-preference" });
+}
+
+const view = (sys) => { const settings = readSettings(sys); return { settings, screen: describeSettings(settings) }; };
+
+/** Runs get_settings and set_setting. Returns the result fields. */
+export async function settingsAction(page, body) {
+  if (body.action === "get_settings") return view(await read(page));
+  if (typeof body.key !== "string" || !body.key) throw new SettingsError("unknown_setting", "set_setting needs a key, such as dark_mode or font_size");
+  const patch = settingPatch(body.key, body.value); // unknown key and bad value fail before anything changes
+  await read(page);
+  await page.evaluate((p) => globalThis.__pnDevice.set(p), patch);
+  await syncMedia(page);
+  return view(await read(page));
+}
+export const SETTINGS_ACTIONS = ["get_settings", "set_setting"];