@shipvo/sim 0.1.2 → 0.1.4

package/app-name.mjs

@@ -0,0 +1,8 @@
+// A page opened straight in a browser (not through a simulator session) has no __PN_SIM__ from the session,
+// so the simulated device would call the app "This app". Put the app's name from shipvo.json in the page.
+// A session's own value wins: the script only fills in what is missing.
+export function withAppName(html, name) {
+  const json = JSON.stringify(String(name)).replace(/</g, "\\u003c");
+  const tag = `<script>globalThis.__PN_SIM__=globalThis.__PN_SIM__||{};globalThis.__PN_SIM__.appName=globalThis.__PN_SIM__.appName||${json};</script>`;
+  return /<head[^>]*>/i.test(html) ? html.replace(/<head[^>]*>/i, (m) => m + tag) : tag + html;
+}

package/mock-rules.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipvo/sim",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "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`.",
@@ -13,6 +13,9 @@
   },
   "files": [
     "server.mjs",
+    "app-name.mjs",
+    "mock-rules.mjs",
+    "push-notification.mjs",
     "README.md"
   ],
   "peerDependencies": {
@@ -42,5 +45,8 @@
   },
   "devDependencies": {
     "playwright": "1.63.0"
+  },
+  "scripts": {
+    "test": "node --test"
   }
 }

package/push-notification.mjs

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

package/server.mjs

@@ -8,6 +8,9 @@ import http from "node:http";
 import { readFileSync, existsSync, writeFileSync, appendFileSync, mkdirSync, statSync } from "node:fs";
 import { join, extname, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { withAppName } from "./app-name.mjs";
+import { parseMockRules } from "./mock-rules.mjs";
+import { pushNotification } from "./push-notification.mjs";
 import { createRequire } from "node:module";
 import { execSync } from "node:child_process";
 // Playwright: the app's own install first (its browsers match it), then this package's, then a global one.
@@ -39,7 +42,15 @@ async function resolveApp(spec) {
 }
 mkdirSync(DIR, { recursive: true });
 const MIME = { ".html": "text/html", ".js": "text/javascript", ".json": "application/json", ".png": "image/png", ".ico": "image/x-icon", ".ttf": "font/ttf", ".css": "text/css" };
-const browser = await chromium.launch();
+// Chromium starts after the server is listening (see the end of this file). Handlers await this shared promise.
+const LAUNCH_TIMEOUT_MS = 60_000;
+let launchBrowser;
+const browserReady = new Promise((resolve, reject) => { launchBrowser = () => {
+  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));
+}; });
+browserReady.catch((e) => { console.error(`sim: could not launch Chromium: ${e.message.split("\n")[0]}`); process.exit(1); });
 const sessions = new Map();
 
 const phone = { ...devices["Pixel 5"], viewport: { width: 393, height: 851 } };
@@ -48,6 +59,7 @@ async function newSession(id, opts = {}) {
   if (sessions.has(id)) await sessions.get(id).ctx.close();
   const target = await resolveApp(opts.app);
   writeFileSync(join(DIR, `${id}.json`), JSON.stringify({ orders: [] })); writeFileSync(join(DIR, `${id}.json.log`), "");
+  const browser = await browserReady;
   const ctx = await browser.newContext({ ...phone, colorScheme: opts.dark ? "dark" : "light" });
   await ctx.addInitScript((cfg) => { globalThis.__PN_SIM__ = cfg; }, { baseUrl: `http://localhost:${PORT}/s/${id}`, appId: target.app, appName: APP_NAME, seed_cart: opts.seed_cart ?? null, device: opts.device ?? null });
   const page = await ctx.newPage();
@@ -56,8 +68,20 @@ async function newSession(id, opts = {}) {
   sessions.set(id, { ctx, page, app: target.app, release: target.release, startedAt: new Date().toISOString() });
 }
 
+// Refs are only meaningful for the document that issued them: a full page load restarts Playwright's counter, so an
+// old "e5" would point at a different element. Each document gets an epoch; refs after the first load are "p<epoch>e5".
+const DOCS = new WeakMap();
+async function epochOf(page) {
+  const id = await page.evaluate(() => (globalThis.__pnDoc ??= Math.random().toString(36).slice(2)));
+  const d = DOCS.get(page);
+  if (!d) DOCS.set(page, { id, epoch: 0 }); else if (d.id !== id) { d.id = id; d.epoch++; }
+  return DOCS.get(page).epoch;
+}
+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(() => {
@@ -94,20 +118,51 @@ async function screen(page) {
     out.push(l);
     if (/^\s*- (button|radio|link|checkbox|switch|tab) "[^"]+"/.test(l) && /:\s*$/.test(l)) hideBelow = indent;
   }
-  return out.join("\n");
+  const text = out.join("\n");
+  return epoch ? text.replace(/\[ref=(e\d+)\]/g, `[ref=p${epoch}$1]`) : text;
 }
 
 function log(id, action, ok, extra = {}) { appendFileSync(join(DIR, `${id}.json.log`), JSON.stringify({ at: Date.now(), name: action, ok, ...extra }) + "\n"); }
 
 async function act(id, body) {
-  const s = sessions.get(id); if (!s) throw new Error(`no session '${id}': call /session first`);
-  const { page } = s; const loc = (ref) => page.locator(`aria-ref=${ref}`);
+  const s = sessions.get(id); if (!s) throw new SimError("no_session", `no session '${id}': call /session first`);
+  const { page } = s;
+  // A ref is valid only for the page it came from and while its element is unchanged. Re-snapshot first, so a node that
+  // was re-rendered with new content has lost its old ref, then fail with a typed error instead of acting on anything else.
+  const loc = (ref) => page.locator(`aria-ref=${ref}`);
+  const resolve = async (ref) => {
+    const m = /^(?:p(\d+))?(e\d+)$/.exec(String(ref));
+    const stale = () => new SimError("stale_ref", `stale ref ${ref}: the screen changed. Take a new snapshot (action "screen") and use a ref from it.`);
+    if (!m) return loc(ref);
+    await screen(page);
+    if (Number(m[1] ?? 0) !== DOCS.get(page).epoch) throw stale();
+    const l = loc(m[2]);
+    if ((await l.count()) !== 1) throw stale();
+    return l;
+  };
+  // Before acting on an element, say why it cannot receive the action. Nothing has reached the app when this throws.
+  const NOT_DELIVERED = { not_visible: "is not visible", disabled: "is disabled", covered: "is covered by another element" };
+  const ready = async (l) => {
+    const fail = (reason, what) => new SimError(reason, `${what} ${NOT_DELIVERED[reason]}, so nothing was sent to the app.`);
+    if (!(await l.isVisible())) throw fail("not_visible", String(body.ref));
+    // Still off the screen after scrolling it into view (for example a fixed element parked outside the window).
+    await l.scrollIntoViewIfNeeded({ timeout: 1000 }).catch(() => {});
+    const box = await l.boundingBox(); const vp = page.viewportSize();
+    if (!box || (vp && (box.x + box.width <= 0 || box.y + box.height <= 0 || box.x >= vp.width || box.y >= vp.height))) throw fail("not_visible", String(body.ref));
+    if (await l.isDisabled()) throw fail("disabled", String(body.ref));
+    const covered = await l.evaluate((el) => {
+      const r = el.getBoundingClientRect();
+      const top = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+      return !!top && top !== el && !el.contains(top) && !top.contains(el);
+    });
+    if (covered) throw fail("covered", String(body.ref));
+  };
   switch (body.action) {
     case "screen": break;
-    case "tap": await loc(body.ref).click({ timeout: 3000 }); break;
+    case "tap": { const t = await resolve(body.ref); await ready(t); await t.click({ timeout: 3000 }); break; }
     case "type": {
       // A labelled text field may resolve to its wrapper; type into the real input inside it, as a phone focuses the field.
-      let t = loc(body.ref);
+      let t = await resolve(body.ref);
       const kind = await t.evaluate((el) => (/^(INPUT|TEXTAREA)$/.test(el.tagName) || el.isContentEditable) ? "field" : el.querySelector("input, textarea") ? "wrapper" : (el.getAttribute("aria-label") || el.textContent || "").trim(), { timeout: 3000 });
       if (kind === "wrapper") t = t.locator("input, textarea").first();
       else if (kind !== "field") {
@@ -116,10 +171,12 @@ async function act(id, body) {
         if ((await named.count()) !== 1) throw new Error(`${body.ref} is not a text field. Type into a "textbox" ref.`);
         t = named;
       }
-      await t.fill(String(body.text ?? ""), { timeout: 3000 }); if (body.enter) await t.press("Enter"); break;
+      await ready(t);
+      await t.fill(String(body.text ?? ""), { timeout: 3000 }); if (body.enter) await t.press("Enter");
+      return { delivery: "delivered", value: await t.inputValue().catch(() => null), screen: await screen(page) };
     }
     case "scroll": {
-      const target = body.ref ? loc(body.ref) : page.locator("body");
+      const target = body.ref ? await resolve(body.ref) : page.locator("body");
       const box = await target.boundingBox().catch(() => null);
       if (box) await page.mouse.move(box.x + box.width / 2, box.y + Math.min(box.height / 2, 400));
       await page.mouse.wheel(body.direction === "right" ? 300 : body.direction === "left" ? -300 : 0, body.direction === "up" ? -600 : body.direction === "down" ? 600 : 0);
@@ -127,9 +184,33 @@ async function act(id, body) {
     }
     // Simulated device: what the phone "has" and what happens to it. See @shipvo/device.
     case "set_device": await page.evaluate((d) => globalThis.__pnDevice?.set(d), body.device ?? {}); break;
-    case "push_notification": await page.evaluate((n) => globalThis.__pnDevice?.push(n), { title: body.title ?? "", body: body.body ?? "", data: body.data ?? {} }); break;
+    case "push_notification": return { ...(await pushNotification(page, body)), screen: await screen(page) };
     case "notifications": return { notifications: await page.evaluate(() => globalThis.__pnDevice?.notifications() ?? []), screen: await screen(page) };
     case "open_notification": { const ok = await page.evaluate((nid) => globalThis.__pnDevice?.openNotification(nid), body.id); if (!ok) throw new Error("no such notification"); await page.waitForTimeout(400); break; }
+    case "open_url": {
+      if (typeof body.url !== "string" || !body.url) throw new SimError("bad_url", "open_url needs a url, such as myapp://item/3");
+      const handled = await page.evaluate((u) => globalThis.__pnDevice?.openUrl(u), body.url);
+      if (!handled) throw new SimError("no_url_listener", `the app has no URL listener, so it did not handle ${body.url}. Register one with onUrl from @shipvo/device.`);
+      await page.waitForTimeout(400); break;
+    }
+    // Stub fetch/XHR on the page. Rules live on the session; unmatched requests continue untouched.
+    case "set_network_mocks": {
+      let rules; try { rules = parseMockRules(body.rules ?? []); } catch (e) { throw new SimError(e.code ?? "mock_invalid", e.message); }
+      s.mocks = rules;
+      if (!s.mockRoute) {
+        s.mockRoute = true;
+        await page.route("**/*", async (route) => {
+          const req = route.request();
+          const type = req.resourceType();
+          const rule = (type === "fetch" || type === "xhr") && (s.mocks ?? []).find((m) => (!m.method || m.method === req.method()) && m.match(req.url()));
+          if (!rule) return route.fallback();
+          if (rule.delayMs) await new Promise((r) => setTimeout(r, rule.delayMs));
+          // The app page may come from another origin, so the stub must pass the browser's CORS check.
+          await route.fulfill({ status: rule.status, body: rule.body, headers: { "access-control-allow-origin": "*", ...rule.headers } }).catch(() => {});
+        });
+      }
+      break;
+    }
     case "device_log": return { log: await page.evaluate(() => globalThis.__pnDevice?.log() ?? []), capabilities: await page.evaluate(() => globalThis.__pnDevice?.capabilities() ?? null), screen: await screen(page) };
     case "diag": {
       const r = await page.evaluate(async () => {
@@ -141,13 +222,15 @@ async function act(id, body) {
       return { diag: r, screen: await screen(page) };
     }
     case "device_reset": await page.evaluate((d) => globalThis.__pnDevice?.reset(d), body.device ?? {}); break;
-    case "back": { const b = page.getByRole("button", { name: "Back", exact: true }); if (await b.count()) await b.first().click(); else throw new Error("no Back button on this screen"); break; }
+    case "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, device_log, device_reset`);
+    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`);
   }
-  return { screen: await screen(page) };
+  return { ...(["tap", "scroll", "back"].includes(body.action) ? { delivery: "delivered" } : {}), screen: await screen(page) };
 }
 
+const DELIVERY = new Set(["tap", "type", "scroll", "back"]);
+const REASONS = new Set(["stale_ref", "not_visible", "disabled", "covered"]);
 const WCACHE = new Map();
 const server = http.createServer(async (req, res) => {
   const url = new URL(req.url, "http://x");
@@ -167,8 +250,11 @@ const server = http.createServer(async (req, res) => {
       if (!hit) { const r = await fetch(`${CONTROL}${key}`); if (!r.ok) return send(r.status, { error: "artifact" }); hit = { type: r.headers.get("content-type") ?? "application/octet-stream", body: Buffer.from(await r.arrayBuffer()) }; WCACHE.set(key, hit); }
       return send(200, hit.body, hit.type);
     }
+    // a founder opening the printed link lands on the app
+    if ((req.method === "GET" || req.method === "HEAD") && url.pathname === "/") { res.writeHead(302, { location: "/app/", ...CORS }); return res.end(); }
     if (url.pathname.startsWith("/app/")) {
       let p = join(DIST, url.pathname.slice(5) || "index.html"); if (!existsSync(p) || statSync(p).isDirectory()) p = join(DIST, "index.html");
+      if (extname(p) === ".html") return send(200, withAppName(readFileSync(p, "utf8"), APP_NAME), MIME[".html"]);
       return send(200, readFileSync(p), MIME[extname(p)] ?? "application/octet-stream");
     }
     // mock control plane per session
@@ -191,11 +277,12 @@ const server = http.createServer(async (req, res) => {
     // 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 === "/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], screen: s ? await screen(s.page) : null }); }
+      catch (e) { log(body.session, body.action, false); const s = sessions.get(body.session); return send(200, { ok: false, error: String(e.message).split("\n")[0], ...(e.code ? { code: e.code } : {}), ...(DELIVERY.has(body.action) && REASONS.has(e.code) ? { delivery: "not_delivered", reason: e.code, safe_to_retry: true } : {}), screen: s ? await screen(s.page) : null }); }
     }
     send(404, { error: "not found" });
   } catch (e) { send(500, { error: String(e) }); }
@@ -203,3 +290,4 @@ const server = http.createServer(async (req, res) => {
 // Agents and parity runs pause between actions; keep idle connections open well beyond Node's 5 s default.
 server.keepAliveTimeout = 300_000; server.headersTimeout = 310_000; server.requestTimeout = 0;
 server.listen(PORT, () => console.log(`Shipvo UI simulator on http://localhost:${PORT} (sessions in ${DIR})`));
+launchBrowser();