@shipvo/sim 0.1.3 → 0.1.4

package/mock-rules.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipvo/sim",
-  "version": "0.1.3",
+  "version": "0.1.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`.",
@@ -14,6 +14,8 @@
   "files": [
     "server.mjs",
     "app-name.mjs",
+    "mock-rules.mjs",
+    "push-notification.mjs",
     "README.md"
   ],
   "peerDependencies": {

package/push-notification.mjs

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

package/server.mjs

@@ -9,6 +9,8 @@ import { readFileSync, existsSync, writeFileSync, appendFileSync, mkdirSync, sta
 import { join, extname, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { withAppName } from "./app-name.mjs";
+import { parseMockRules } from "./mock-rules.mjs";
+import { pushNotification } from "./push-notification.mjs";
 import { createRequire } from "node:module";
 import { execSync } from "node:child_process";
 // Playwright: the app's own install first (its browsers match it), then this package's, then a global one.
@@ -40,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 } };
@@ -49,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();
@@ -114,7 +125,7 @@ async function screen(page) {
 function log(id, action, ok, extra = {}) { appendFileSync(join(DIR, `${id}.json.log`), JSON.stringify({ at: Date.now(), name: action, ok, ...extra }) + "\n"); }
 
 async function act(id, body) {
-  const s = sessions.get(id); if (!s) throw new Error(`no session '${id}': call /session first`);
+  const s = sessions.get(id); if (!s) throw new SimError("no_session", `no session '${id}': call /session first`);
   const { page } = s;
   // A ref is valid only for the page it came from and while its element is unchanged. Re-snapshot first, so a node that
   // was re-rendered with new content has lost its old ref, then fail with a typed error instead of acting on anything else.
@@ -129,9 +140,26 @@ async function act(id, body) {
     if ((await l.count()) !== 1) throw stale();
     return l;
   };
+  // Before acting on an element, say why it cannot receive the action. Nothing has reached the app when this throws.
+  const NOT_DELIVERED = { not_visible: "is not visible", disabled: "is disabled", covered: "is covered by another element" };
+  const ready = async (l) => {
+    const fail = (reason, what) => new SimError(reason, `${what} ${NOT_DELIVERED[reason]}, so nothing was sent to the app.`);
+    if (!(await l.isVisible())) throw fail("not_visible", String(body.ref));
+    // Still off the screen after scrolling it into view (for example a fixed element parked outside the window).
+    await l.scrollIntoViewIfNeeded({ timeout: 1000 }).catch(() => {});
+    const box = await l.boundingBox(); const vp = page.viewportSize();
+    if (!box || (vp && (box.x + box.width <= 0 || box.y + box.height <= 0 || box.x >= vp.width || box.y >= vp.height))) throw fail("not_visible", String(body.ref));
+    if (await l.isDisabled()) throw fail("disabled", String(body.ref));
+    const covered = await l.evaluate((el) => {
+      const r = el.getBoundingClientRect();
+      const top = document.elementFromPoint(r.left + r.width / 2, r.top + r.height / 2);
+      return !!top && top !== el && !el.contains(top) && !top.contains(el);
+    });
+    if (covered) throw fail("covered", String(body.ref));
+  };
   switch (body.action) {
     case "screen": break;
-    case "tap": await (await resolve(body.ref)).click({ timeout: 3000 }); break;
+    case "tap": { const t = await resolve(body.ref); await ready(t); await t.click({ timeout: 3000 }); break; }
     case "type": {
       // A labelled text field may resolve to its wrapper; type into the real input inside it, as a phone focuses the field.
       let t = await resolve(body.ref);
@@ -143,7 +171,9 @@ async function act(id, body) {
         if ((await named.count()) !== 1) throw new Error(`${body.ref} is not a text field. Type into a "textbox" ref.`);
         t = named;
       }
-      await t.fill(String(body.text ?? ""), { timeout: 3000 }); if (body.enter) await t.press("Enter"); break;
+      await ready(t);
+      await t.fill(String(body.text ?? ""), { timeout: 3000 }); if (body.enter) await t.press("Enter");
+      return { delivery: "delivered", value: await t.inputValue().catch(() => null), screen: await screen(page) };
     }
     case "scroll": {
       const target = body.ref ? await resolve(body.ref) : page.locator("body");
@@ -154,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 () => {
@@ -168,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");
@@ -194,6 +250,8 @@ const server = http.createServer(async (req, res) => {
       if (!hit) { const r = await fetch(`${CONTROL}${key}`); if (!r.ok) return send(r.status, { error: "artifact" }); hit = { type: r.headers.get("content-type") ?? "application/octet-stream", body: Buffer.from(await r.arrayBuffer()) }; WCACHE.set(key, hit); }
       return send(200, hit.body, hit.type);
     }
+    // a founder opening the printed link lands on the app
+    if ((req.method === "GET" || req.method === "HEAD") && url.pathname === "/") { res.writeHead(302, { location: "/app/", ...CORS }); return res.end(); }
     if (url.pathname.startsWith("/app/")) {
       let p = join(DIST, url.pathname.slice(5) || "index.html"); if (!existsSync(p) || statSync(p).isDirectory()) p = join(DIST, "index.html");
       if (extname(p) === ".html") return send(200, withAppName(readFileSync(p, "utf8"), APP_NAME), MIME[".html"]);
@@ -224,7 +282,7 @@ const server = http.createServer(async (req, res) => {
     if (url.pathname === "/session") { await newSession(body.session, body); const s = sessions.get(body.session); log(body.session, "start", true, { app: s.app, release: s.release }); return send(200, { ok: true, app: s.app, release: s.release, screen: await screen(s.page) }); }
     if (url.pathname === "/act") {
       try { const r = await act(body.session, body); log(body.session, body.action, true, body.ref ? { ref: body.ref } : {}); return send(200, { ok: true, ...r }); }
-      catch (e) { log(body.session, body.action, false); const s = sessions.get(body.session); return send(200, { ok: false, error: String(e.message).split("\n")[0], ...(e.code ? { code: e.code } : {}), screen: s ? await screen(s.page) : null }); }
+      catch (e) { log(body.session, body.action, false); const s = sessions.get(body.session); return send(200, { ok: false, error: String(e.message).split("\n")[0], ...(e.code ? { code: e.code } : {}), ...(DELIVERY.has(body.action) && REASONS.has(e.code) ? { delivery: "not_delivered", reason: e.code, safe_to_retry: true } : {}), screen: s ? await screen(s.page) : null }); }
     }
     send(404, { error: "not found" });
   } catch (e) { send(500, { error: String(e) }); }
@@ -232,3 +290,4 @@ const server = http.createServer(async (req, res) => {
 // Agents and parity runs pause between actions; keep idle connections open well beyond Node's 5 s default.
 server.keepAliveTimeout = 300_000; server.headersTimeout = 310_000; server.requestTimeout = 0;
 server.listen(PORT, () => console.log(`Shipvo UI simulator on http://localhost:${PORT} (sessions in ${DIR})`));
+launchBrowser();