@shipvo/sim 0.1.5 → 0.1.6

package/server.mjs

@@ -10,11 +10,22 @@ 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.
@@ -30,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(/\/$/, "");
@@ -61,21 +79,68 @@ 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;
   // 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 = [];
-  page.on("pageerror", (e) => errors.push(String(e?.message ?? e).split("\n")[0]));
+  // 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, errors, app: target.app, release: target.release, startedAt: new Date().toISOString(), life: createLifecycle() });
+  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
@@ -87,6 +152,60 @@ 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) {
@@ -139,20 +258,85 @@ 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", "type", "scroll", "back", "open_url", "open_notification"].includes(body.action)) { try { assertUnlocked(s.life); } catch (e) { throw new SimError(e.code, e.message); } }
+  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);
-      await page.reload({ waitUntil: "networkidle" }); await page.waitForTimeout(300);
+      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);
@@ -176,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);
@@ -190,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() ?? [])), ...s.life.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 };
@@ -214,17 +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 "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) };
-    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; }
+    // 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"}`);
-      const buf = await page.screenshot(jpeg ? { path: p, type: "jpeg", quality: 90 } : { path: p });
+      // 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, 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`);
+    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"];

package/settings.mjs

@@ -0,0 +1,95 @@
+// The phone's Settings screen: dark mode, font size, bold text, reduce motion, language and RTL.
+// Pure: no DOM, no timers. The frame page draws the screen; the server uses the same rules for the MCP tools get_settings and set_setting.
+// Each setting is a field of the simulated device (@shipvo/device), so the app sees it through Appearance, PixelRatio, AccessibilityInfo, I18nManager and Intl.
+
+/** Typed error for a setting that cannot be read or changed. */
+export class SettingsError extends Error { constructor(code, message) { super(message); this.code = code; } }
+
+export const FONT_SIZES = ["small", "default", "large", "largest"];
+export const LANGUAGES = { en: "English", fr: "Français", ar: "العربية" };
+
+/** Setting key -> label, device field and kind. */
+export const SETTINGS = {
+  dark_mode: { label: "Dark mode", field: "darkMode", kind: "boolean" },
+  font_size: { label: "Font size", field: "fontSize", kind: "choice", values: FONT_SIZES },
+  bold_text: { label: "Bold text", field: "boldText", kind: "boolean" },
+  reduce_motion: { label: "Reduce motion", field: "reduceMotion", kind: "boolean" },
+  language: { label: "Language", field: "language", kind: "choice", values: Object.keys(LANGUAGES) },
+  rtl: { label: "Right-to-left layout", field: "rtl", kind: "boolean" },
+};
+export const SETTING_KEYS = Object.keys(SETTINGS);
+
+/** The settings as an object keyed by setting name, from the device's `system()`. */
+export function readSettings(device = {}) {
+  const defaults = { dark_mode: false, font_size: "default", bold_text: false, reduce_motion: false, language: "en", rtl: false };
+  return Object.fromEntries(SETTING_KEYS.map((k) => [k, device[SETTINGS[k].field] ?? defaults[k]]));
+}
+
+/** The `set_device` patch for one setting. Setting the language to Arabic turns RTL on, and to any other language turns it off. Throws SettingsError. */
+export function settingPatch(key, value) {
+  const s = Object.prototype.hasOwnProperty.call(SETTINGS, key) ? SETTINGS[key] : null;
+  if (!s) throw new SettingsError("unknown_setting", `unknown setting '${key}'. Settings: ${SETTING_KEYS.join(", ")}`);
+  if (s.kind === "boolean") {
+    if (typeof value !== "boolean") throw new SettingsError("bad_value", `'${key}' takes true or false`);
+    return { [s.field]: value };
+  }
+  if (typeof value !== "string" || !s.values.includes(value)) throw new SettingsError("bad_value", `'${key}' takes one of: ${s.values.join(", ")}`);
+  return key === "language" ? { language: value, rtl: value === "ar" } : { [s.field]: value };
+}
+
+/** Plain-text view of the Settings screen for an agent: one row per setting. */
+export function describeSettings(values) {
+  const lines = ["Settings"];
+  for (const k of SETTING_KEYS) { const s = SETTINGS[k], v = values[k]; lines.push(`- ${s.kind === "boolean" ? "switch" : "choice"} ${k} (${s.label}): ${s.kind === "boolean" ? (v ? "on" : "off") : v}`); }
+  return lines.join("\n");
+}
+
+/** Markup for the Settings screen. Hidden until opened. The rows are drawn by the client script. */
+export function settingsHtml() {
+  return `<div class="sf-settings" data-part="settings-screen" role="dialog" aria-label="Settings" tabindex="-1" hidden><h2 class="sf-sh">Settings</h2><div data-part="settings-rows" role="group" aria-label="Settings"></div><button type="button" class="sf-close" data-part="settings-close">Close</button></div>`;
+}
+/** The Settings icon for the home screen. */
+export function settingsIconHtml() {
+  return `<button type="button" class="sf-icon" data-part="settings-icon" aria-label="Settings" style="left:124px"><b>⚙</b><span>Settings</span></button>`;
+}
+/** The gear for the shade panels. */
+export function gearHtml() {
+  return `<button type="button" class="sf-gear" data-part="settings-gear" aria-label="Settings">⚙ Settings</button>`;
+}
+
+export const settingsCss = [
+  `.sf-settings{position:absolute;inset:0;z-index:8;overflow:auto;padding:48px 14px 14px;background:#10151c;color:#fff;font:15px system-ui,sans-serif}.sf-settings[hidden]{display:none}.sf-sh{margin:0 0 12px;font-size:22px}`,
+  `.sf-srow{display:flex;align-items:center;justify-content:space-between;gap:10px;width:100%;box-sizing:border-box;margin:6px 0;padding:12px;border:0;border-radius:14px;background:#2c3036;color:#fff;font:inherit;text-align:start}.sf-srow[role=switch]::after{content:"Off";opacity:.7}.sf-srow[aria-checked=true]::after{content:"On";color:#4da3ff;font-weight:700}`,
+  `.sf-group2{margin:6px 0;padding:8px 12px;border-radius:14px;background:#2c3036}.sf-group2 b{display:block;margin-bottom:6px}.sf-opts{display:flex;flex-wrap:wrap;gap:6px}.sf-opt{padding:8px 12px;border:1px solid #fff6;border-radius:999px;background:transparent;color:#fff;font:inherit}.sf-opt[aria-checked=true]{background:#4da3ff;color:#001;border-color:#4da3ff}`,
+  `.sf-gear{margin:0 8px 8px 0;padding:8px 16px;border:1px solid #fff6;border-radius:999px;background:transparent;color:#fff}`,
+  `.sf-settings :focus-visible,.sf-gear:focus-visible{outline:3px solid #4da3ff;outline-offset:2px}`,
+].join("\n");
+
+/** Browser script for the frame page: opens Settings from the home icon or the shade gear, draws the rows, and writes changes to the app's `__pnDevice`. */
+export function settingsClientScript(iframeId = "app") {
+  return `(function(){
+var SETTINGS=${JSON.stringify(SETTINGS)},SETTING_KEYS=${JSON.stringify(SETTING_KEYS)},LANGS=${JSON.stringify(LANGUAGES)},FONT=${JSON.stringify(FONT_SIZES)},settingPatch=${settingPatch.toString()},readSettings=${readSettings.toString()};
+function SettingsError(c,m){var e=new Error(m);e.code=c;return e}
+var r=document.querySelector('[data-part="phone-body"]');if(!r)return;
+var q=function(p){return r.querySelector('[data-part="'+p+'"]')},sc=q("settings-screen");if(!sc)return;
+function dev(){var f=document.getElementById(${JSON.stringify(iframeId)});var w=f&&f.contentWindow;return w&&w.__pnDevice&&w.__pnDevice.system?w.__pnDevice:null}
+function esc(s){return String(s).replace(/[&<>"]/g,function(c){return{"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;"}[c]})}
+var SIZE={small:"Small",default:"Default",large:"Large",largest:"Largest"};
+function draw(){var d=dev(),rows=q("settings-rows");if(!d||!rows||sc.hidden)return;var v=readSettings(d.system()),h="";
+SETTING_KEYS.forEach(function(k){var s=SETTINGS[k];
+if(s.kind==="boolean")h+='<button type="button" class="sf-srow" role="switch" data-setting="'+k+'" aria-checked="'+(!!v[k])+'">'+esc(s.label)+'</button>';
+else{h+='<div class="sf-group2" role="radiogroup" aria-label="'+esc(s.label)+'"><b>'+esc(s.label)+'</b><div class="sf-opts">'+s.values.map(function(o){return '<button type="button" class="sf-opt" role="radio" data-setting="'+k+'" data-value="'+o+'" aria-checked="'+(v[k]===o)+'">'+esc(k==="language"?LANGS[o]:SIZE[o])+'</button>'}).join("")+'</div></div>'}});
+var keep=document.activeElement&&document.activeElement.getAttribute&&document.activeElement.getAttribute("data-setting"),kv=document.activeElement&&document.activeElement.getAttribute&&document.activeElement.getAttribute("data-value");
+rows.innerHTML=h;if(keep){var again=rows.querySelector('[data-setting="'+keep+'"]'+(kv?'[data-value="'+kv+'"]':''));if(again)again.focus({preventScroll:true})}}
+var back=null;
+function show(on){if(on){back=document.activeElement;sc.hidden=false;draw();sc.focus({preventScroll:true});try{window.parent.postMessage({type:"pn:settings-open",open:true},"*")}catch(x){}}else{sc.hidden=true;if(back&&back.focus)back.focus({preventScroll:true});back=null}}
+r.addEventListener("click",function(e){var t=e.target;if(!t.closest)return;
+if(t.closest('[data-part="settings-icon"],[data-part="settings-gear"]')){show(true);return}
+if(t.closest('[data-part="settings-close"]')){show(false);return}
+var row=t.closest("[data-setting]");if(row){var d=dev();if(!d)return;var k=row.getAttribute("data-setting"),s=SETTINGS[k],val=s.kind==="boolean"?row.getAttribute("aria-checked")!=="true":row.getAttribute("data-value");
+try{d.set(settingPatch(k,val))}catch(x){}draw()}});
+document.addEventListener("keydown",function(e){if(e.key==="Escape"&&!sc.hidden)show(false)});
+var f=document.getElementById(${JSON.stringify(iframeId)});function wire(){var w=f&&f.contentWindow;if(w&&!w.__shipvoSettingsHooked){w.__shipvoSettingsHooked=true;w.addEventListener("pn:system",draw)}}
+if(f){f.addEventListener("load",wire);wire()}
+})();`;
+}

package/shade-actions.mjs

@@ -0,0 +1,52 @@
+// The server side of the notification shade, Notification Center and Control Center: MCP actions that read and change
+// the simulated device in the page. `shade` is per-session state `{ open }`. Errors are ShadeError with a typed `code`.
+import { ShadeError, TILES, tileStates, tilePatch, describePanel } from "./shade.mjs";
+
+const read = async (page) => page.evaluate(() => {
+  const d = globalThis.__pnDevice; if (!d) return null;
+  return { platform: d.state.platform, settings: d.settings(), notifications: d.notifications() };
+});
+const need = (info) => { if (!info) throw new ShadeError("no_device", "the app has no simulated device in this session"); return info; };
+const text = (info, shade) => describePanel(info.platform, shade.open, info.settings, info.notifications);
+const view = (info, shade) => ({ panel: shade.open, tiles: shade.open === "notifications" ? [] : tileStates(info.platform, info.settings, shade.open !== "shade"), notifications: info.notifications, screen: text(info, shade) });
+
+/** Dark mode reaches the app as its colour scheme (prefers-color-scheme). */
+export async function applyScheme(page, dark) { await page.emulateMedia({ colorScheme: dark ? "dark" : "light" }); }
+
+/** Runs open_notifications, open_control_center, toggle_tile, dismiss_notification, close_panels. Returns the result fields. */
+export async function shadeAction(page, shade, body) {
+  const info = need(await read(page));
+  switch (body.action) {
+    case "open_notifications": {
+      // Android: the first pull shows quick-settings tiles and notifications, the second expands all tiles. iPhone: Notification Center.
+      shade.open = info.platform === "ios" ? "notifications" : (shade.open === "shade" || shade.open === "shade-expanded" || body.expand) ? "shade-expanded" : "shade";
+      return view(info, shade);
+    }
+    case "open_control_center": {
+      if (info.platform !== "ios") throw new ShadeError("no_control_center", "an Android phone has no Control Center: its quick-settings tiles are in the notification shade (open_notifications)");
+      shade.open = "control"; return view(info, shade);
+    }
+    case "close_panels": shade.open = "none"; return view(info, shade);
+    case "toggle_tile": {
+      if (typeof body.tile !== "string" || !body.tile) throw new ShadeError("bad_tile", "toggle_tile needs a tile, such as wifi or dark_mode");
+      const patch = tilePatch(info.platform, body.tile, info.settings, body.value); // unknown tile and bad value fail first
+      const visible = shade.open === "none" || shade.open === "notifications" ? [] : tileStates(info.platform, info.settings, shade.open !== "shade").map((t) => t.id);
+      if (!visible.includes(body.tile)) throw new ShadeError("tile_not_visible", info.platform === "ios" ? `open_control_center first: '${body.tile}' is in Control Center` : `open_notifications first (twice to expand all tiles): '${body.tile}' is not showing`);
+      await page.evaluate((p) => globalThis.__pnDevice.set(p), patch);
+      if ("darkMode" in patch) await applyScheme(page, patch.darkMode);
+      const next = need(await read(page)); return view(next, shade);
+    }
+    case "dismiss_notification": {
+      if (shade.open === "none" || shade.open === "control") throw new ShadeError("panel_closed", "open the notification shade first (open_notifications)");
+      if (body.all) { await page.evaluate(() => globalThis.__pnDevice.clearAll()); }
+      else {
+        const id = body.id ?? info.notifications.at(-1)?.id;
+        if (!id || !(await page.evaluate((i) => globalThis.__pnDevice.dismiss(i), id))) throw new ShadeError("no_such_notification", id ? `no notification '${id}' in the shade` : "no notifications to dismiss");
+      }
+      return view(need(await read(page)), shade);
+    }
+  }
+  throw new ShadeError("unknown_action", body.action);
+}
+export const SHADE_ACTIONS = ["open_notifications", "open_control_center", "close_panels", "toggle_tile", "dismiss_notification"];
+export { TILES };