@shipvo/sim 0.1.4 → 0.1.6

package/guide.mjs

@@ -0,0 +1,44 @@
+// Lumi's first-run guide on the Shipvo Phone: three short steps (home screen, the Store, connecting an assistant).
+// It can be skipped, and once it is finished or skipped it never shows again on this browser. It sits in the phone frame
+// over the bottom of the screen, never in the app's own page, so the simulator's screenshots and screen tree do not see it.
+// It is drawn only when Lumi is drawn and the page asks for it (`guide: true`).
+
+export const GUIDE_KEY = "shipvo.lumi.guide";
+
+export const GUIDE_STEPS = [
+  { title: "Your home screen", text: "Go home to see your apps. Go home at any time to come back." },
+  { title: "The Store", text: "The Store icon on the home screen installs more apps on this phone." },
+  { title: "Connect an assistant", text: "To let an AI assistant drive this phone, run: claude mcp add shipvo -- npx -y @shipvo/mcp" },
+];
+
+/** Markup for the guide. Hidden until the page script finds that this browser has not seen it. */
+export function guideHtml() {
+  const steps = GUIDE_STEPS.map((s, i) => `<div class="sf-guide-step" data-step="${i + 1}"${i ? " hidden" : ""}><b>${s.title}</b><p>${s.text.replace(/&/g, "&amp;").replace(/</g, "&lt;")}</p></div>`).join("");
+  return `<div class="sf-guide" data-part="lumi-guide" role="dialog" aria-live="polite" aria-label="Welcome to Shipvo Phone" hidden>`
+    + `<span class="sf-guide-count" data-part="guide-count">1 of ${GUIDE_STEPS.length}</span>${steps}`
+    + `<div class="sf-guide-actions"><button type="button" data-part="guide-skip">Skip</button><button type="button" data-part="guide-next">Next</button></div></div>`;
+}
+
+export const guideCss = [
+  `.sf-guide{position:absolute;left:12px;right:12px;bottom:40px;z-index:4;box-sizing:border-box;padding:12px 14px;border-radius:16px;background:#10151c;color:#fff;border:1px solid #7fd6f5aa;box-shadow:0 0 14px #7fd6f555,0 6px 20px #0008;font:14px/1.4 system-ui,sans-serif}`,
+  `.sf-guide[hidden],.sf-guide [hidden]{display:none}`,
+  `.sf-guide p{margin:4px 0 0;overflow-wrap:anywhere}.sf-guide-count{float:right;font-size:11px;opacity:.7}`,
+  `.sf-guide-actions{display:flex;justify-content:flex-end;gap:8px;margin-top:10px}`,
+  `.sf-guide button{padding:6px 16px;border:1px solid #fff6;border-radius:999px;background:transparent;color:#fff;font:600 13px system-ui,sans-serif;cursor:pointer}`,
+  `.sf-guide [data-part=guide-next]{background:#7fd6f5;border-color:#7fd6f5;color:#10151c}.sf-guide button:focus-visible{outline:3px solid #4da3ff;outline-offset:2px}`,
+].join("\n");
+
+/** Browser script. Shows the guide on first launch, steps through it, and remembers a finish or a skip in localStorage. */
+export function guideClientScript() {
+  return `(function(){var K=${JSON.stringify(GUIDE_KEY)},g=document.querySelector('[data-part="lumi-guide"]');if(!g)return;
+function seen(){try{return localStorage.getItem(K)==="done"}catch(x){return false}}
+function save(){try{localStorage.setItem(K,"done")}catch(x){}}
+var s=g.querySelectorAll(".sf-guide-step"),i=0,c=g.querySelector('[data-part="guide-count"]'),n=g.querySelector('[data-part="guide-next"]');
+function lumi(st){if(window.shipvoLumi)window.shipvoLumi.set(st)}
+function draw(){for(var j=0;j<s.length;j++)s[j].hidden=j!==i;c.textContent=(i+1)+" of "+s.length;n.textContent=i===s.length-1?"Done":"Next"}
+function close(happy){save();g.hidden=true;lumi(happy?"happy":"idle")}
+g.querySelector('[data-part="guide-skip"]').addEventListener("click",function(){close(false)});
+n.addEventListener("click",function(){if(i>=s.length-1)return close(true);i++;draw()});
+document.addEventListener("keydown",function(e){if(e.key==="Escape"&&!g.hidden)close(false)});
+if(seen())return;draw();g.hidden=false})();`;
+}

package/lifecycle.mjs

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

package/lumi.mjs

@@ -0,0 +1,97 @@
+// Lumi, the glowing orb, drawn in the phone frame beside the camera cutout. Our own artwork.
+// Lumi lives in the frame's status bar, never in the app's screen: it is not inside `.sf-content`, it is hidden from
+// assistive tech and the labelled screen tree, and it takes no pointer input. The simulator's own page (screens, screenshots,
+// recordings for agents) never draws it, so agents and tests see the same app with Lumi on or off.
+
+export const LUMI_STATES = ["idle", "working", "happy", "worried"];
+
+/** True when Lumi is drawn by default. SHIPVO_LUMI=off|0|false|no hides it anywhere; on|1|true|yes shows it. With no setting it is off in CI and on otherwise. */
+export function lumiDefault(env = typeof process !== "undefined" ? process.env : {}) {
+  const v = String(env.SHIPVO_LUMI ?? "").trim().toLowerCase();
+  if (["off", "0", "false", "no"].includes(v)) return false;
+  if (["on", "1", "true", "yes"].includes(v)) return true;
+  const ci = String(env.CI ?? "").trim().toLowerCase();
+  return !(ci && ci !== "0" && ci !== "false");
+}
+
+const FACE = {
+  idle: `<path d="M8.6 15.4q2.4 1.6 4.8 0" fill="none" stroke="#10151c" stroke-width="1.3" stroke-linecap="round"/>`,
+  working: `<ellipse cx="11" cy="15.6" rx="1.3" ry="1.1" fill="#10151c"/>`,
+  happy: `<path d="M8 14.6q3 3.6 6 0z" fill="#10151c"/>`,
+  worried: `<path d="M8.8 16.6q2.2-1.8 4.4 0" fill="none" stroke="#10151c" stroke-width="1.3" stroke-linecap="round"/><path d="M6.6 8.2l3 .8M15.4 8.2l-3 .8" stroke="#10151c" stroke-width="1" stroke-linecap="round"/>`,
+};
+
+/**
+ * What Lumi shows for a result. `event` is { kind, error?, name?, detail? }:
+ * check-passed and flow-done give happy; page-error, crash, action-failed and check-failed give worried.
+ * The reason is one line taken from the real error or result (first line, spaces collapsed, at most 90 characters).
+ * Anything else, or an unusable event, returns null and Lumi stays as it is. Pure and self-contained, so the page can run it.
+ */
+export function lumiReaction(event) {
+  if (!event || typeof event !== "object") return null;
+  const one = (v) => {
+    const t = String(v && v.message ? v.message : v == null ? "" : v).split(/\r?\n/).map((x) => x.replace(/\s+/g, " ").trim()).find(Boolean) || "";
+    return t.length > 90 ? t.slice(0, 89) + "…" : t;
+  };
+  const name = one(event.name), err = one(event.error), detail = one(event.detail);
+  const why = (fallback) => err || detail || fallback;
+  switch (event.kind) {
+    case "check-passed": return { state: "happy", reason: name ? "Check passed: " + name : "Check passed" };
+    case "flow-done": return { state: "happy", reason: name ? "Flow finished: " + name : "Flow finished" };
+    case "page-error": return { state: "worried", reason: "Page error: " + why("the page threw an error") };
+    case "crash": return { state: "worried", reason: "Crash: " + why("the app stopped") };
+    case "action-failed": return { state: "worried", reason: (name ? "Action failed (" + name + "): " : "Action failed: ") + why("no reason given") };
+    case "check-failed": return { state: "worried", reason: (name ? "Check failed (" + name + "): " : "Check failed: ") + why("no reason given") };
+    default: return null;
+  }
+}
+
+/** Markup for Lumi. `state` is one of idle, working, happy, worried. */
+export function lumiHtml(state = "idle") {
+  const st = LUMI_STATES.includes(state) ? state : "idle";
+  const faces = LUMI_STATES.map((s) => `<g data-face="${s}"${s === st ? "" : " hidden"}>${FACE[s]}</g>`).join("");
+  return `<span class="sf-lumi" data-part="lumi" data-state="${st}" aria-hidden="true" inert>`
+    + `<svg viewBox="0 0 22 22" width="22" height="22" focusable="false"><defs><radialGradient id="sf-lumi-g" cx="40%" cy="35%" r="70%"><stop offset="0" stop-color="#e9fbff"/><stop offset=".6" stop-color="#7fd6f5"/><stop offset="1" stop-color="#3b9ad9"/></radialGradient></defs>`
+    + `<circle cx="11" cy="11" r="10" fill="url(#sf-lumi-g)"/>`
+    + `<g class="sf-lumi-eyes"><ellipse cx="7.8" cy="11" rx="1.4" ry="1.9" fill="#10151c"/><ellipse cx="14.2" cy="11" rx="1.4" ry="1.9" fill="#10151c"/></g>${faces}</svg></span>`;
+}
+
+/** The caption pill Lumi shows for the agent's current step. Hidden until a step is shown. Outside the app's screen tree like Lumi. */
+export const lumiCaptionHtml = () => `<span class="sf-lumi-cap" data-part="lumi-caption" aria-hidden="true" inert hidden></span>`;
+
+/** Style for Lumi. `top` and `offset` place it beside the cutout. Motion stops for people who ask for less of it. */
+export const lumiCss = (k) => [
+  // The glow must never paint over the app's screen below the status bar.
+  `.sf-status{overflow:hidden}`,
+  `.sf-lumi{position:absolute;left:50%;top:${Math.round((k.status - 22) / 2)}px;margin-left:${k.part === "dynamic-island" ? 66 : 20}px;width:22px;height:22px;pointer-events:none;z-index:3;animation:sf-lumi-float 3.6s ease-in-out infinite}`,
+  `.sf-lumi svg{display:block;border-radius:50%;box-shadow:0 0 6px 1px #7fd6f5aa;animation:sf-lumi-glow 2.8s ease-in-out infinite}`,
+  `.sf-lumi-eyes{transform-box:fill-box;transform-origin:center;animation:sf-lumi-blink 4.5s infinite}`,
+  `.sf-lumi [hidden]{display:none}`,
+  `.sf-lumi[data-state=working] svg{animation-duration:1.1s}.sf-lumi[data-state=working]{animation-duration:1.6s}`,
+  `.sf-lumi[data-state=happy] svg{box-shadow:0 0 9px 3px #ffe08aaa}.sf-lumi[data-state=worried] svg{box-shadow:0 0 7px 2px #ff9a8aaa}`,
+  `.sf-lumi-cap{position:absolute;left:50%;top:${k.status + 6}px;transform:translateX(-50%);max-width:80%;box-sizing:border-box;padding:4px 12px;border-radius:14px;background:#10151ce6;color:#fff;font:600 12px system-ui,sans-serif;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;pointer-events:none;z-index:4}.sf-lumi-cap[hidden]{display:none}`,
+  `@keyframes sf-lumi-float{0%,100%{transform:translateY(0)}50%{transform:translateY(-2px)}}`,
+  `@keyframes sf-lumi-glow{0%,100%{opacity:.88}50%{opacity:1;filter:brightness(1.12)}}`,
+  `@keyframes sf-lumi-blink{0%,92%,100%{transform:scaleY(1)}95%{transform:scaleY(.1)}}`,
+  `@media (prefers-reduced-motion:reduce){.sf-lumi,.sf-lumi svg,.sf-lumi-eyes{animation:none}}`,
+].join("\n");
+
+/**
+ * Browser script. `window.shipvoLumi.set(state, reason?)` changes Lumi's state; `react(event)` picks the state and reason from a result (see lumiReaction).
+ * A `{ type: "pn:lumi", state, reason? }` or `{ type: "pn:lumi", event }` message does the same. The reason sits in Lumi's `data-reason` and `title`
+ * and is cleared when the state has no reason.
+ * `window.shipvoLumi.say(text, state, holdMs)` (or `{ type: "pn:lumi", state, caption, hold }`) also shows a short caption.
+ * With `holdMs` > 0 the caption goes away and Lumi goes back to idle after that long. Touches only Lumi and its caption.
+ */
+export function lumiClientScript() {
+  return `(function(){var S=${JSON.stringify(LUMI_STATES)},T=0;var lumiReaction=${lumiReaction.toString()};
+function set(state,reason){if(S.indexOf(state)<0)return false;var l=document.querySelector('[data-part="lumi"]');if(!l)return false;l.setAttribute("data-state",state);
+if(typeof reason==="string"&&reason){l.setAttribute("data-reason",reason);l.setAttribute("title",reason)}else{l.removeAttribute("data-reason");l.removeAttribute("title")}
+var g=l.querySelectorAll("[data-face]");for(var i=0;i<g.length;i++)g[i].hidden=g[i].getAttribute("data-face")!==state;return true}
+function react(ev){var r=lumiReaction(ev);if(!r)return null;return set(r.state,r.reason)?r:null}
+function say(text,state,hold){clearTimeout(T);var c=document.querySelector('[data-part="lumi-caption"]');var ok=set(state||"working");
+if(c){var t=String(text==null?"":text).replace(/\\s+/g," ").trim().slice(0,80);c.textContent=t;c.hidden=!t}
+if(hold>0)T=setTimeout(function(){if(c){c.hidden=true;c.textContent=""}set("idle")},hold);return ok}
+if(typeof window==="undefined")return;window.shipvoLumi={set:set,react:react,say:say,states:S};
+window.addEventListener("message",function(e){var d=e.data;if(!d||d.type!=="pn:lumi")return;if(d.event)react(d.event);else if(typeof d.caption==="string")say(d.caption,d.state,Number(d.hold)||0);else set(d.state,d.reason)})})();`;
+}

package/nav.mjs

@@ -0,0 +1,98 @@
+// Navigation and lifecycle for the simulated phone: back, home, recents, kill. Pure state plus markup.
+// The app sees these as AppState changes: react-native-web reads document.visibilityState, so "background" means hidden.
+
+/** Typed error for a navigation action that cannot run now. */
+export class NavError extends Error { constructor(code, message) { super(message); this.code = code; } }
+
+/** Where the phone is: the app in front ("app"), the home screen ("home") or the app switcher ("recents"). */
+export function createNav() {
+  return { where: "app", kills: 0, log: [] };
+}
+
+const note = (st, name) => { st.log.push({ at: Date.now(), name, source: "simulated" }); };
+
+/** Home: app to background. From recents it also goes home. Returns the AppState the app should see ("background"), or null if nothing changes. */
+export function pressHome(st) {
+  const was = st.where; st.where = "home"; note(st, "press_home");
+  return was === "app" ? "background" : null;
+}
+
+/** Recents: the app switcher card. From the app this backgrounds it. */
+export function openRecents(st) {
+  const was = st.where; st.where = "recents"; note(st, "open_recents");
+  return was === "app" ? "background" : null;
+}
+
+/** Tap the app icon or its recents card. Returns "active" when the app comes back. Throws if the app is already in front. */
+export function resume(st) {
+  if (st.where === "app") throw new NavError("app_in_foreground", "the app is already in front");
+  st.where = "app"; note(st, "resume"); return "active";
+}
+
+/** Swipe the recents card away. The app is killed; the next open is a cold start. Throws unless the switcher is open. */
+export function killApp(st) {
+  if (st.where !== "recents") throw new NavError("recents_not_open", "open the app switcher first (open_recents), then kill_app");
+  st.where = "home"; st.kills++; note(st, "kill_app"); return st;
+}
+
+/** Throws app_not_foreground while the home screen or the app switcher is showing, so no input reaches a backgrounded app. */
+export function assertForeground(st) {
+  if (st.where !== "app") throw new NavError("app_not_foreground", `the phone is on the ${st.where === "home" ? "home screen" : "app switcher"}, so nothing was sent to the app. Open the app first (resume_app).`);
+}
+
+/**
+ * Classify a swipe on the bottom bar or the left edge.
+ * s: { skin, fromEdge: "bottom"|"left"|null, dx, dy, ms } (dy negative is up).
+ * Returns "home", "recents", "switch-left", "switch-right", "back" or null.
+ */
+export function classifySwipe({ skin = "android", fromEdge = null, dx = 0, dy = 0, ms = 0 } = {}) {
+  if (fromEdge === "left" && dx > 60 && Math.abs(dy) < 80) return "back";
+  if (fromEdge !== "bottom") return null;
+  if (dy < -60 && Math.abs(dx) < Math.abs(dy)) return ms >= 400 ? "recents" : "home";
+  if (skin === "ios" && Math.abs(dx) > 60 && Math.abs(dy) < 40) return dx > 0 ? "switch-right" : "switch-left";
+  return null;
+}
+
+/** Runs in the app page. Sets what AppState reads and fires the event. */
+export function setVisibilityInPage(state) {
+  const hidden = state === "background";
+  try {
+    Object.defineProperty(document, "visibilityState", { configurable: true, get: () => (hidden ? "hidden" : "visible") });
+    Object.defineProperty(document, "hidden", { configurable: true, get: () => hidden });
+  } catch {}
+  document.dispatchEvent(new Event("visibilitychange"));
+}
+
+/** Home screen markup: the app icon. Hidden until the phone goes home. */
+export function homeScreenHtml(appName = "App") {
+  const n = String(appName).replace(/[<>&"'\\]/g, "").slice(0, 40) || "App";
+  return `<div class="sf-home" data-part="home-screen" role="region" aria-label="Home screen" hidden><button type="button" class="sf-icon" data-part="app-icon" aria-label="${n}"><b>${n.slice(0, 1).toUpperCase()}</b><span>${n}</span></button></div>`;
+}
+
+/** App switcher markup: one card for the app. Click the card to open it, the close button (or swipe it up) to kill the app. */
+export function recentsHtml(appName = "App") {
+  const n = String(appName).replace(/[<>&"'\\]/g, "").slice(0, 40) || "App";
+  return `<div class="sf-recents" data-part="recents" role="region" aria-label="Recent apps" hidden><div class="sf-card" data-part="recents-card"><button type="button" data-part="recents-open" aria-label="Open ${n}">${n}</button><button type="button" data-part="recents-close" aria-label="Close ${n}">Close</button></div></div>`;
+}
+
+/** The three buttons of Android 3-button navigation. */
+export function navButtonsHtml() {
+  return `<div class="sf-navbtns" data-part="nav-buttons" hidden><button type="button" data-part="nav-back" aria-label="Back">◀</button><button type="button" data-part="nav-home" aria-label="Home">●</button><button type="button" data-part="nav-recents" aria-label="Recents">■</button></div>`;
+}
+
+/** CSS for the home screen and the app switcher. Colours follow the theme (data-theme on the phone body, or on any parent). Dark is the default. */
+export function navScreensCss() {
+  return [
+    `.sf-home,.sf-recents{position:absolute;inset:0;z-index:4;background:linear-gradient(160deg,#1d3557,#0b1320);color:#fff;font-family:system-ui,sans-serif}`,
+    `[data-theme="light"] .sf-home{background:linear-gradient(160deg,#dbe7f5,#f4f7fb);color:#111}`,
+    `.sf-icon{position:absolute;left:28px;top:70px;width:76px;padding:0;border:0;background:none;color:inherit;display:flex;flex-direction:column;align-items:center;gap:6px;font:600 12px system-ui,sans-serif;cursor:pointer}.sf-icon b{display:flex;width:60px;height:60px;border-radius:16px;background:#f4a261;color:#102030;align-items:center;justify-content:center;font-size:28px}`,
+    `.sf-recents{display:flex;align-items:center;justify-content:center;background:#10151cee;color:#fff}[data-theme="light"] .sf-recents{background:#eef1f5ee;color:#111}`,
+    `.sf-card{width:230px;height:420px;border-radius:20px;background:#fff;color:#111;border:1px solid #8884;display:flex;flex-direction:column;justify-content:space-between;align-items:center;padding:14px;box-sizing:border-box;transition:transform .2s}[data-theme="dark"] .sf-card{background:#1c232d;color:#fff}.sf-card button{border:0;border-radius:10px;padding:8px 18px;background:#8883;color:inherit;font:600 14px system-ui,sans-serif;cursor:pointer}`,
+  ].join("");
+}
+
+/** The home screen or switcher as plain markup, shown (not hidden), for a screenshot of a headless session. */
+export function awayScreenHtml(where, appName = "App") {
+  const inner = (where === "home" ? homeScreenHtml(appName) : recentsHtml(appName)).replace(" hidden>", ">");
+  return `<style>${navScreensCss()}</style><div data-theme="dark" style="position:fixed;inset:0;z-index:2147483647">${inner}</div>`;
+}

package/network-profiles.mjs

@@ -0,0 +1,84 @@
+// Network profiles for the simulator. Pure functions: no sim wiring.
+//
+// The numbers below are simulation settings, not measurements of any real
+// network. `latencyMs` is a fixed wait per request, `downKbps` is the
+// throughput used to turn bytes into wait time, and `failureRate` is the share
+// of requests that fail with a network error (0 to 1).
+//
+// `low-end-4g` uses the download rate seen on the Android phone in
+// docs/spike-results.md, section "Results so far": a 1.57 MB bundle in 1.4 to
+// 2.0 s over 4G, which is about 6,300 kbps at the slow end. That section does
+// not record a round-trip time, so its latency is a simulation setting.
+
+export const PROFILES = Object.freeze({
+  online: Object.freeze({ latencyMs: 0, downKbps: Infinity, failureRate: 0 }),
+  offline: Object.freeze({ latencyMs: 0, downKbps: 0, failureRate: 1 }),
+  '2g': Object.freeze({ latencyMs: 800, downKbps: 50, failureRate: 0.02 }),
+  '3g': Object.freeze({ latencyMs: 300, downKbps: 750, failureRate: 0.01 }),
+  'slow-4g': Object.freeze({ latencyMs: 150, downKbps: 1600, failureRate: 0 }),
+  spotty: Object.freeze({ latencyMs: 400, downKbps: 500, failureRate: 0.3 }),
+  'low-end-4g': Object.freeze({ latencyMs: 100, downKbps: 6300, failureRate: 0.005 }),
+});
+
+export const PROFILE_NAMES = Object.freeze(Object.keys(PROFILES));
+
+export function getProfile(name) {
+  if (typeof name !== 'string' || !Object.hasOwn(PROFILES, name)) {
+    const err = new Error(
+      `Unknown network profile "${String(name)}". Use one of: ${PROFILE_NAMES.join(', ')}.`,
+    );
+    err.code = 'unknown_profile';
+    throw err;
+  }
+  return PROFILES[name];
+}
+
+// mulberry32: small seeded PRNG, returns numbers in [0, 1).
+function prng(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function bodyBytes(body) {
+  if (body == null) return 0;
+  if (typeof body === 'string') return new TextEncoder().encode(body).length;
+  if (typeof body.byteLength === 'number') return body.byteLength;
+  if (typeof body.size === 'number') return body.size;
+  return 0;
+}
+
+function transferMs(bytes, downKbps) {
+  if (!bytes || !Number.isFinite(downKbps)) return 0;
+  return (bytes * 8) / downKbps;
+}
+
+/**
+ * Wrap `fetchImpl` so requests behave as `profile` describes.
+ * Waits latencyMs + bytes*8/downKbps (request body bytes, then the response's
+ * content-length when present) through `clock.sleep(ms)`. Rejects with a
+ * network TypeError at `failureRate`, drawn from a PRNG seeded by `seed`.
+ */
+export function applyProfile(fetchImpl, profile, { seed = 1, clock } = {}) {
+  if (profile === PROFILES.online) return fetchImpl;
+  const random = prng(seed);
+  const fail = () => new TypeError('fetch failed: network request failed');
+  return async function profiledFetch(input, init) {
+    if (profile.failureRate >= 1) throw fail();
+    // One draw per request keeps the failing set stable for a seed.
+    const failed = random() < profile.failureRate;
+    const reqBytes = bodyBytes(init?.body ?? input?.body);
+    await clock.sleep(profile.latencyMs + transferMs(reqBytes, profile.downKbps));
+    if (failed) throw fail();
+    const res = await fetchImpl(input, init);
+    const len = Number(res?.headers?.get?.('content-length'));
+    const extra = transferMs(Number.isFinite(len) ? len : 0, profile.downKbps);
+    if (extra > 0) await clock.sleep(extra);
+    return res;
+  };
+}

package/package.json

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

package/phone-browser.mjs

@@ -0,0 +1,187 @@
+// A real Chromium page behind the phone: one isolated browser context per phone, a mobile viewport and touch.
+// Pages are untrusted web content. Private hosts are refused unless the caller opts in.
+import { lookup } from "node:dns/promises";
+import { isIP } from "node:net";
+
+export const USER_AGENT_TAG = "ShipvoPhone";
+
+export class BrowserError extends Error {
+  constructor(code, message) { super(message); this.code = code; }
+}
+
+function v4Private(a, b) {
+  return a === 0 || a === 10 || a === 127 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) ||
+    (a === 192 && b === 168) || (a === 100 && b >= 64 && b <= 127);
+}
+
+/** True for loopback, link-local, RFC1918, CGNAT, `.local`, `.internal` and `localhost` names or addresses. */
+export function isPrivateHost(host) {
+  let h = String(host).toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
+  if (h === "localhost" || h.endsWith(".localhost") || h.endsWith(".local") || h.endsWith(".internal")) return true;
+  const kind = isIP(h);
+  if (kind === 4) { const [a, b] = h.split(".").map(Number); return v4Private(a, b); }
+  if (kind === 6) {
+    // IPv4-mapped (::ffff:a.b.c.d or ::ffff:7f00:1)
+    const m = /^::ffff:(?:(\d+)\.(\d+)\.(\d+)\.(\d+)|([0-9a-f]{1,4}):([0-9a-f]{1,4}))$/.exec(h);
+    if (m) {
+      if (m[1]) return v4Private(Number(m[1]), Number(m[2]));
+      const hi = parseInt(m[5], 16); return v4Private(hi >> 8, hi & 255);
+    }
+    if (h === "::" || h === "::1") return true;
+    const first = parseInt(h.split(":")[0] || "0", 16);
+    return (first & 0xfe00) === 0xfc00 || (first & 0xffc0) === 0xfe80;   // fc00::/7 unique local, fe80::/10 link-local
+  }
+  return false;
+}
+
+/**
+ * Decides if a URL may be loaded. Throws BrowserError host_not_allowed. A public name that resolves to a
+ * private address is refused too, so a DNS record cannot reach the local network.
+ */
+export async function checkUrl(raw, { allowPrivate = false, allowHosts = [] } = {}, resolve = (h) => lookup(h, { all: true })) {
+  let u; try { u = new URL(raw); } catch { throw new BrowserError("bad_url", `not a URL: ${raw}`); }
+  if (u.protocol === "about:" || u.protocol === "data:" || u.protocol === "blob:") return u;
+  if (u.protocol !== "http:" && u.protocol !== "https:") throw new BrowserError("bad_url", `only http and https pages can be opened, not ${u.protocol}`);
+  const host = u.hostname.toLowerCase();
+  if (allowPrivate || allowHosts.map((x) => x.toLowerCase()).includes(host)) return u;
+  const refuse = (why) => new BrowserError("host_not_allowed", `${host} is ${why}, so the phone browser did not open it. Pass allow_private: true, or allow_hosts: ["${host}"], to opt in.`);
+  if (isPrivateHost(host)) throw refuse("a private host");
+  if (!isIP(host.replace(/^\[|\]$/g, ""))) {
+    let addrs = []; try { addrs = await resolve(host); } catch {}
+    if (addrs.some((a) => isPrivateHost(a.address))) throw refuse("a name that points to a private address");
+  }
+  return u;
+}
+
+export class PhoneBrowser {
+  /** @param browser a Playwright Browser. @param opts {allowPrivate, allowHosts, device, resolve} */
+  constructor(browser, opts = {}) {
+    this.browser = browser; this.opts = { allowPrivate: !!opts.allowPrivate, allowHosts: opts.allowHosts ?? [] };
+    this.device = opts.device ?? {}; this.resolve = opts.resolve; this.navigations = [];
+    this.ctx = null; this.page = null; this.pages = []; this.refsFrom = null;
+    this.onDeepLink = opts.onDeepLink ?? null;   // called with a link such as myapp://item/3 that a page tried to open
+    this.cdp = null; this.screencast = null; this.onChange = null;
+  }
+  async #start() {
+    if (this.ctx) { if (!this.page) await this.ctx.newPage(); return; }
+    const d = this.device;
+    this.ctx = await this.browser.newContext({ ...d, userAgent: `${d.userAgent ?? "Mozilla/5.0 (Linux; Android 11; Pixel 5)"} ${USER_AGENT_TAG}`, hasTouch: true, isMobile: true, viewport: d.viewport ?? { width: 393, height: 851 } });
+    // Every request, including redirects and sub-resources, goes through the same host check.
+    await this.ctx.route("**/*", async (route) => {
+      try { await checkUrl(route.request().url(), this.opts, this.resolve); } catch (e) {
+        if (route.request().isNavigationRequest()) this.#log(route.request().url(), false, e.code);
+        return route.abort("blockedbyclient");
+      }
+      return route.continue();
+    });
+    // A link to another app's scheme (myapp://...) cannot load in Chromium. Hand it to the phone, which gives it to the app.
+    await this.ctx.exposeFunction("__shipvoDeepLink", (u) => { if (isDeepLink(u)) { this.#log(String(u), true, undefined, "deep_link"); this.onDeepLink?.(String(u)); } });
+    await this.ctx.addInitScript(() => document.addEventListener("click", (e) => {
+      const a = e.target?.closest?.("a[href]"); if (!a) return;
+      const u = a.href; if (/^(https?|about|data|blob|javascript|file|mailto|tel):/i.test(u) || !/^[a-z][a-z0-9+.-]*:/i.test(u)) return;
+      e.preventDefault(); globalThis.__shipvoDeepLink(u);
+    }, true));
+    this.ctx.on("page", (p) => this.#adopt(p));   // a popup or target=_blank link is a new tab
+    await this.ctx.newPage();
+  }
+  #adopt(p) {
+    if (this.pages.includes(p)) return;
+    this.pages.push(p); this.page = p; this.refsFrom = null;
+    p.on("framenavigated", (f) => { if (f === p.mainFrame()) { this.#log(f.url(), true); this.onChange?.(); } });
+    p.on("close", () => { this.pages = this.pages.filter((x) => x !== p); if (this.page === p) { this.page = this.pages.at(-1) ?? null; this.refsFrom = null; if (this.page) this.#cast(); } this.onChange?.(); });
+    if (this.screencast) this.#cast();
+  }
+  #log(url, ok, code, kind = "browser_navigation") { this.navigations.push({ at: Date.now(), kind, detail: { url, allowed: ok, ...(code ? { code } : {}) }, source: "real", simulated: false }); }
+
+  async open(url) {
+    try { await checkUrl(url, this.opts, this.resolve); } catch (e) { this.#log(String(url), false, e.code); throw e; }
+    await this.#start();
+    try { await this.page.goto(url, { waitUntil: "load", timeout: 20000 }); }
+    catch (e) { throw new BrowserError(/blockedbyclient/i.test(e.message) ? "host_not_allowed" : "navigation_failed", String(e.message).split("\n")[0]); }
+    return this.snapshot();
+  }
+  #need() { if (!this.page) throw new BrowserError("no_page", "no page is open: call browser_open first"); return this.page; }
+  async snapshot() {
+    const page = this.#need();
+    await page.waitForTimeout(100);
+    const tree = await page.locator("body").ariaSnapshot({ mode: "ai" });
+    this.refsFrom = page.url();
+    return { source: "web", untrusted: true, url: page.url(), title: await page.title(), tree };
+  }
+  async #target(ref) {
+    const page = this.#need();
+    const stale = new BrowserError("stale_ref", `stale ref ${ref}: take a new browser_snapshot and use a ref from it.`);
+    if (!/^(?:f\d+)?e\d+$/.test(String(ref)) || this.refsFrom !== page.url()) throw stale;
+    const l = page.locator(`aria-ref=${ref}`);
+    if ((await l.count().catch(() => 0)) !== 1) throw stale;
+    return l;
+  }
+  async click(ref) { const l = await this.#target(ref); await l.click({ timeout: 3000 }); await this.page.waitForLoadState("load").catch(() => {}); return this.snapshot(); }
+  async type(ref, text, enter = false) {
+    const l = await this.#target(ref);
+    await l.fill(String(text ?? ""), { timeout: 3000 }); if (enter) await l.press("Enter");
+    await this.page.waitForLoadState("load").catch(() => {});
+    return this.snapshot();
+  }
+  async back() {
+    const page = this.#need();
+    if (!(await page.goBack({ timeout: 5000 }).catch(() => null))) throw new BrowserError("no_history", "there is no earlier page to go back to");
+    return this.snapshot();
+  }
+  async screenshot() { return this.#need().screenshot({ type: "png" }); }
+  async forward() {
+    const page = this.#need();
+    if (!(await page.goForward({ timeout: 5000 }).catch(() => null))) throw new BrowserError("no_history", "there is no later page to go forward to");
+    return this.snapshot();
+  }
+  async reload() { await this.#need().reload({ timeout: 20000 }).catch((e) => { throw new BrowserError("navigation_failed", String(e.message).split("\n")[0]); }); return this.snapshot(); }
+  async scroll(dy = 400, dx = 0) { await this.#need().mouse.wheel(dx, dy); return this.snapshot(); }
+  /** Waits for text to appear in the page (or to be gone, with gone: true). Resolves with a snapshot. */
+  async waitFor({ text, gone = false, timeoutMs = 5000 } = {}) {
+    const page = this.#need();
+    if (typeof text !== "string" || !text) throw new BrowserError("bad_args", "browser_wait_for needs text");
+    try { await page.waitForFunction(([t, g]) => document.body.innerText.includes(t) !== g, [text, gone], { timeout: Math.min(Math.max(timeoutMs, 100), 30000) }); }
+    catch { throw new BrowserError("timeout", `"${text}" ${gone ? "did not go away" : "did not appear"} within ${timeoutMs} ms`); }
+    return this.snapshot();
+  }
+  async tabs() { return Promise.all(this.pages.map(async (p, index) => ({ index, url: p.url(), title: await p.title().catch(() => ""), active: p === this.page }))); }
+  async selectTab(index) { const p = this.pages[index]; if (!p) throw new BrowserError("no_tab", `no tab ${index}`); this.page = p; this.refsFrom = null; await p.bringToFront(); if (this.screencast) await this.#cast(); this.onChange?.(); }
+  async newTab(url = "about:blank") { await this.#start(); await checkUrl(url, this.opts, this.resolve); const p = await this.ctx.newPage(); await p.goto(url).catch(() => {}); return this.tabs(); }
+  async closeTab(index) {
+    const p = this.pages[index]; if (!p) throw new BrowserError("no_tab", `no tab ${index}`);
+    await p.close(); return this.tabs();
+  }
+
+  // Live view. Chromium pushes JPEG frames (CDP Page.startScreencast); each one is acked once it has been handed on.
+  async #cast() {
+    if (!this.page || !this.ctx) return;
+    try {   // a tab that is closing or not yet attached must not take the server down
+      await this.cdp?.send("Page.stopScreencast").catch(() => {}); this.cdp?.detach().catch(() => {});
+      const c = this.cdp = await this.ctx.newCDPSession(this.page);
+      c.on("Page.screencastFrame", (f) => { c.send("Page.screencastFrameAck", { sessionId: f.sessionId }).catch(() => {}); this.screencast?.({ data: f.data, width: f.metadata.deviceWidth, height: f.metadata.deviceHeight }); });
+      await c.send("Page.startScreencast", { format: "jpeg", quality: 60, maxWidth: 400, maxHeight: 860, everyNthFrame: 1 });
+    } catch {}
+  }
+  async startScreencast(onFrame) { await this.#need(); this.screencast = onFrame; await this.#cast(); }
+  async stopScreencast() { this.screencast = null; await this.cdp?.send("Page.stopScreencast").catch(() => {}); }
+  /** Input as a finger and keyboard would give it, in CSS px of the viewport. */
+  async input(m) {
+    this.#need(); const c = this.cdp ?? (this.cdp = await this.ctx.newCDPSession(this.page));
+    const touch = (type, x, y) => c.send("Input.dispatchTouchEvent", { type, touchPoints: type === "touchEnd" ? [] : [{ x, y }] });
+    const num = (...v) => { if (!v.every((n) => Number.isFinite(n))) throw new BrowserError("bad_args", "coordinates must be numbers"); };
+    if (m.type === "tap") { num(m.x, m.y); await touch("touchStart", m.x, m.y); await touch("touchEnd"); }
+    else if (m.type === "swipe") {
+      num(m.x1, m.y1, m.x2, m.y2); await touch("touchStart", m.x1, m.y1);
+      for (let i = 1; i <= 8; i++) await touch("touchMove", m.x1 + ((m.x2 - m.x1) * i) / 8, m.y1 + ((m.y2 - m.y1) * i) / 8);
+      await touch("touchEnd");
+    }
+    else if (m.type === "text") await c.send("Input.insertText", { text: String(m.text ?? "").slice(0, 2000) });
+    else if (m.type === "key") { const key = String(m.key); const code = { Enter: 13, Backspace: 8, Tab: 9 }[key]; if (!code) throw new BrowserError("bad_args", `unsupported key ${key}`);
+      for (const type of ["keyDown", "keyUp"]) await c.send("Input.dispatchKeyEvent", { type, key, windowsVirtualKeyCode: code, ...(key === "Enter" && type === "keyDown" ? { text: "\r" } : {}) }); }
+    else throw new BrowserError("bad_args", `unknown input ${m.type}`);
+  }
+  async close() { this.screencast = null; await this.ctx?.close().catch(() => {}); this.ctx = this.page = this.cdp = null; this.pages = []; }
+}
+
+/** True for a link into another app: a scheme that is not a web page scheme. */
+export function isDeepLink(u) { return /^[a-z][a-z0-9+.-]*:/i.test(String(u)) && !/^(https?|about|data|blob|javascript|file|ftp|view-source|chrome|devtools|mailto|tel):/i.test(String(u)); }