@condorinst/mobile-bridge 0.21.0 → 0.23.0

package/dist/cli.js

@@ -2,7 +2,15 @@
 
 // src/cli.ts
 import { mkdirSync, writeFileSync } from "fs";
-import { dirname as dirname3, resolve as resolve3 } from "path";
+import { dirname as dirname3, resolve as resolve4 } from "path";
+
+// package.json
+var version = "0.23.0";
+
+// src/canvas-admin/command.ts
+import { createHash as createHash2 } from "crypto";
+import { existsSync, readFileSync as readFileSync2, statSync } from "fs";
+import { extname as extname2, join, resolve as resolve2 } from "path";
 
 // src/cli-core.ts
 import { createHash } from "crypto";
@@ -156,6 +164,11 @@ var BLOCKED_API_RULES = [
     pattern: /window\s*\.\s*open\s*\(/,
     message: "The sandbox has no allow-popups; window.open() returns null."
   },
+  {
+    rule: "crypto-randomuuid",
+    pattern: /crypto\s*\.\s*randomUUID\b/,
+    message: "crypto.randomUUID exists only in a secure context, and the app's sandboxed iframe is probably not one: it can be undefined on the phone while it works in the harness. Use createRequestId() from the SDK, or crypto.getRandomValues."
+  },
   {
     rule: "top-navigation",
     pattern: /window\s*\.\s*top\b/,
@@ -295,6 +308,8 @@ function parseArgs(argv) {
     scenario: "default",
     port: DEFAULT_DEV_PORT,
     nativeVersion: void 0,
+    latencyMs: void 0,
+    panel: true,
     help: false
   };
   for (let i = 0; i < argv.length; i++) {
@@ -337,6 +352,14 @@ function parseArgs(argv) {
       case "--port":
         args.port = Number.parseInt(argv[++i] ?? "", 10) || DEFAULT_DEV_PORT;
         break;
+      case "--latency": {
+        const ms = Number.parseInt(argv[++i] ?? "", 10);
+        args.latencyMs = Number.isFinite(ms) && ms >= 0 ? ms : void 0;
+        break;
+      }
+      case "--no-panel":
+        args.panel = false;
+        break;
       default:
         if (token && !token.startsWith("-") && !args.htmlPath) args.htmlPath = token;
     }
@@ -348,12 +371,16 @@ var USAGE = `condor-mobile-bridge \u2014 tooling for Condor Canvas client bundle
 Usage:
   npx condor-mobile-bridge build    -i <html> [-o <zip>]
   npx condor-mobile-bridge validate -i <zip|html> [--strict]
-  npx condor-mobile-bridge dev      -i <html|zip|dir> [--scenario <name>] [--native-version <v|null>] [--port <n>]
+  npx condor-mobile-bridge canvas   publish|list|revoke ...   (see: canvas --help)
+  npx condor-mobile-bridge dev      -i <html|zip|dir> [--scenario <name|file.json>] [--native-version <v|null>]
+                                    [--port <n>] [--latency <ms>] [--no-panel]
 
 Commands:
   build      Inline a dist/index.html into a self-contained .zip.
   validate   Check a bundle against every rule the Canvas app enforces, plus
              the APIs the sandbox and the CSP block at runtime.
+  canvas     Publish, list and revoke the bundle of your company in the
+             Condor Canvas app (interactive login). See: canvas --help.
   dev        Serve the bundle in a browser harness that behaves like the app:
              same sandbox, shell and policy, and a simulated native side.
              Re-reads the input on every reload. Scenarios: default,
@@ -364,18 +391,488 @@ Options:
   -o, --out <path>     build only: output .zip (default: ${DEFAULT_OUT}).
       --max-bytes <n>  Size limit in bytes (default: ${DEFAULT_MAX_BYTES} = 2 MB).
       --strict         validate only: exit 1 on warnings too, not just errors.
-      --scenario <n>   dev only: device behaviour to simulate (default: default).
+      --scenario <n>   dev only: device behaviour to simulate (default: default),
+                       or a .json file that extends one (see docs/device-testing.md).
       --port <n>       dev only: HTTP port (default: ${DEFAULT_DEV_PORT}).
       --native-version <v|null>
                        dev only: nativeVersion the harness reports (default
-                       0.17.0). 'null' reproduces a shell that could not
+                       0.18.0). 'null' reproduces a shell that could not
                        reach the native side.
+      --latency <ms>   dev only: fixed reply latency (e.g. 0 for fast tests).
+      --no-panel       dev only: hide the floating MOCK panel.
   -h, --help           Show this help.`;
 
+// src/canvas-admin/client.ts
+var CANVAS_ADMIN_API = {
+  prod: "https://api.sleepdiary.condorapps.net",
+  dev: "https://dev.sleepdiary.condorapps.net"
+};
+var CanvasAdminError = class extends Error {
+  constructor(message, status, reason) {
+    super(message);
+    this.status = status;
+    this.reason = reason;
+    this.name = "CanvasAdminError";
+  }
+};
+function tokenFrom(headers) {
+  const values = typeof headers.getSetCookie === "function" ? headers.getSetCookie() : [headers.get("set-cookie") ?? ""];
+  for (const value of values) {
+    const match = /(?:^|[,;\s])token=([^;,\s]*)/.exec(value);
+    if (match?.[1]) return match[1];
+  }
+  return null;
+}
+async function reasonFrom(response) {
+  try {
+    const body = await response.json();
+    for (const key of ["error", "message", "description", "code"]) {
+      const value = body[key];
+      if (typeof value === "string" && value) return value;
+    }
+  } catch {
+  }
+  return null;
+}
+var CanvasAdminClient = class {
+  constructor(opts) {
+    this.token = null;
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.userAgent = opts.userAgent;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.timeoutMs = opts.timeoutMs ?? 6e4;
+  }
+  async request(path, init = {}) {
+    const headers = new Headers(init.headers);
+    headers.set("user-agent", this.userAgent);
+    headers.set("accept", "application/json");
+    if (this.token) headers.set("cookie", `token=${this.token}`);
+    try {
+      return await this.fetchImpl(`${this.baseUrl}${path}`, {
+        ...init,
+        headers,
+        redirect: "manual",
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (err) {
+      throw new CanvasAdminError(
+        `Could not reach ${this.baseUrl}: ${err instanceof Error ? err.message : String(err)}`,
+        0,
+        null
+      );
+    }
+  }
+  async fail(response, what) {
+    const reason = await reasonFrom(response);
+    throw new CanvasAdminError(
+      `${what} failed (HTTP ${response.status})${reason ? `: ${reason}` : ""}`,
+      response.status,
+      reason
+    );
+  }
+  /**
+   * Logs in. Resolves `{ needsCode: true }` when the company requires a
+   * two-factor code (sent by e-mail): call {@link verifyCode} next.
+   */
+  async login(creds) {
+    const response = await this.request("/auth/login", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        company_id: creds.companyId,
+        user_id: creds.userId,
+        password: creds.password
+      })
+    });
+    if (!response.ok) await this.fail(response, "Login");
+    const token = tokenFrom(response.headers);
+    if (!token) throw new CanvasAdminError("Login answered without a session cookie", 200, null);
+    this.token = token;
+    const body = await response.json().catch(() => ({}));
+    return { needsCode: body.completed_auth_flow === false };
+  }
+  /** Sends the two-factor (or recovery) code; the server swaps the session cookie. */
+  async verifyCode(code) {
+    const response = await this.request("/auth/verify_2fa", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ otp_code: code })
+    });
+    if (!response.ok) await this.fail(response, "Two-factor verification");
+    const token = tokenFrom(response.headers);
+    if (token) this.token = token;
+  }
+  /**
+   * Publishes a bundle. **It goes live at once** for every user of the
+   * company: there is no draft. A version can be published only once per
+   * company (HTTP 409).
+   */
+  async publish(input) {
+    const form = new FormData();
+    form.set(
+      "bundle",
+      new Blob([input.zipBytes], { type: "application/zip" }),
+      "bundle.zip"
+    );
+    form.set("version", input.version);
+    if (input.companyId !== void 0) form.set("company_id", String(input.companyId));
+    if (input.minAppVersion) form.set("min_app_version", input.minAppVersion);
+    const response = await this.request("/v2/condor_canvas/bundles", {
+      method: "POST",
+      body: form
+    });
+    if (!response.ok) await this.fail(response, "Publish");
+    const body = await response.json();
+    return body.data;
+  }
+  /** Lists the bundles of a company (a manager always sees their own). */
+  async list(companyId) {
+    const query = companyId === void 0 ? "" : `?company_id=${companyId}`;
+    const response = await this.request(`/v2/condor_canvas/bundles${query}`);
+    if (!response.ok) await this.fail(response, "List");
+    const body = await response.json();
+    return body.data;
+  }
+  /**
+   * Revokes a bundle. Without `fallbackVersion`, revoking the current bundle
+   * leaves the company with none: the app shows its default screen.
+   */
+  async revoke(bundleId, fallbackVersion) {
+    const response = await this.request(`/v2/condor_canvas/bundles/${bundleId}/revoke`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(fallbackVersion ? { fallbackVersion } : {})
+    });
+    if (!response.ok) await this.fail(response, "Revoke");
+    const body = await response.json();
+    return body.data;
+  }
+};
+
+// src/canvas-admin/command.ts
+var CANVAS_USAGE = `condor-mobile-bridge canvas \u2014 publish a bundle to the Condor Canvas app.
+
+Usage:
+  npx condor-mobile-bridge canvas publish <dist/index.html|dir|bundle.zip> --version <v> [options]
+  npx condor-mobile-bridge canvas list    [options]
+  npx condor-mobile-bridge canvas revoke  <bundleId> [--fallback-version <v>] [options]
+
+Publishing goes LIVE AT ONCE for every user of the company \u2014 there is no draft.
+Use a test company, and see docs/device-testing.md.
+
+Options:
+  --company <id>          Company id, as in the Condor web login (or CONDOR_CANVAS_COMPANY).
+  --user <id>             Your user id, as in the Condor web login (or CONDOR_CANVAS_USER).
+                          Both are asked when not given.
+  --version <v>           publish: bundle version, unique per company.
+  --min-app-version <v>   publish: minimum app build that may load it.
+  --fallback-version <v>  revoke: VERSION to serve instead (the version column of
+                          canvas list, e.g. 0.0.8 \u2014 not the id).
+  --env prod|dev          API environment (default: prod). dev is for Condor staff.
+  --base-url <url>        Override the API URL.
+  --yes                   Do not ask for confirmation.
+  --json                  Print results as JSON.
+
+Your password (and the two-factor code, when your company uses one) is asked
+interactively, without echo, and never stored. There is no non-interactive login.`;
+var intOrUndefined = (value) => {
+  if (value === void 0) return void 0;
+  const n = Number(value);
+  return Number.isInteger(n) && n > 0 ? n : Number.NaN;
+};
+function parseCanvasArgs(argv, env = {}) {
+  const [action, ...rest] = argv;
+  if (action !== "publish" && action !== "list" && action !== "revoke") {
+    return { error: `Unknown canvas command "${action ?? ""}". Use publish, list or revoke.` };
+  }
+  const args = {
+    action,
+    env: "prod",
+    yes: false,
+    json: false,
+    companyId: intOrUndefined(env.CONDOR_CANVAS_COMPANY),
+    userId: intOrUndefined(env.CONDOR_CANVAS_USER)
+  };
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i] ?? "";
+    const next = () => rest[++i];
+    switch (token) {
+      case "--env": {
+        const env2 = next();
+        if (env2 !== "prod" && env2 !== "dev") return { error: "--env must be prod or dev." };
+        args.env = env2;
+        break;
+      }
+      case "--base-url":
+        args.baseUrl = next();
+        break;
+      case "--company":
+        args.companyId = intOrUndefined(next());
+        break;
+      case "--user":
+        args.userId = intOrUndefined(next());
+        break;
+      case "--version":
+        args.version = next();
+        break;
+      case "--min-app-version":
+        args.minAppVersion = next();
+        break;
+      case "--fallback-version":
+        args.fallbackVersion = next();
+        break;
+      case "--yes":
+        args.yes = true;
+        break;
+      case "--json":
+        args.json = true;
+        break;
+      case "--password":
+        return {
+          error: "There is no --password flag: the password is only read from the prompt."
+        };
+      default:
+        if (token.startsWith("-")) return { error: `Unknown option ${token}.` };
+        positional.push(token);
+    }
+  }
+  if (Number.isNaN(args.companyId) || Number.isNaN(args.userId)) {
+    return {
+      error: "--company and --user (or CONDOR_CANVAS_COMPANY / CONDOR_CANVAS_USER) take a positive integer id."
+    };
+  }
+  if (action === "publish") {
+    args.input = positional[0];
+    if (!args.input)
+      return { error: "canvas publish needs the bundle: dist/index.html, a dir or a .zip." };
+    if (!args.version) return { error: "canvas publish needs --version." };
+  }
+  if (action === "revoke") {
+    args.bundleId = intOrUndefined(positional[0]);
+    if (!args.bundleId || Number.isNaN(args.bundleId)) {
+      return { error: "canvas revoke needs the bundle id (see canvas list)." };
+    }
+  }
+  return args;
+}
+function loadZip(input) {
+  const path = resolve2(input);
+  if (!existsSync(path)) throw new Error(`${input}: not found.`);
+  let zipBytes;
+  if (extname2(path).toLowerCase() === ".zip") {
+    zipBytes = new Uint8Array(readFileSync2(path));
+  } else {
+    const html = statSync(path).isDirectory() ? join(path, "index.html") : path;
+    zipBytes = buildBundle(html).zipBytes;
+  }
+  return { zipBytes, findings: validateZipBytes(zipBytes).findings };
+}
+async function askId(io, label, value) {
+  if (value !== void 0) return value;
+  const answer = (await io.ask(`${label}: `)).trim();
+  const n = Number(answer);
+  if (!Number.isInteger(n) || n <= 0) throw new Error(`${label} must be a positive integer.`);
+  return n;
+}
+async function confirm(io, args, question2) {
+  if (args.yes) return true;
+  const answer = (await io.ask(`${question2} [y/N] `)).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
+}
+async function logIn(io, client, companyId, userId) {
+  io.print("");
+  io.print("Log in with your Condor web account (typing is hidden; press Enter when done).");
+  let password = "";
+  for (let attempt = 0; attempt < 3 && !password.trim(); attempt++) {
+    if (attempt > 0) io.printError("The password cannot be empty.");
+    password = await io.askSecret("Password: ");
+  }
+  if (!password.trim()) throw new Error("No password given. Nothing was sent.");
+  const { needsCode } = await client.login({ companyId, userId, password });
+  if (!needsCode) return;
+  io.print(
+    "Your company uses two-factor login: a code was sent to your e-mail. Type it below (hidden)."
+  );
+  for (let attempt = 1; attempt <= 2; attempt++) {
+    const code = (await io.askSecret("Code (or a recovery code): ")).trim();
+    try {
+      await client.verifyCode(code);
+      return;
+    } catch (err) {
+      if (attempt === 2 || !(err instanceof CanvasAdminError) || err.status !== 400) throw err;
+      io.printError("That code was not accepted. Try once more.");
+    }
+  }
+}
+function describeError(err) {
+  if (!(err instanceof CanvasAdminError)) return err instanceof Error ? err.message : String(err);
+  if (err.status === 400 && /fallback/i.test(err.reason ?? "")) {
+    return `${err.message}
+--fallback-version takes the VERSION column of \`canvas list\` (e.g. 0.0.8), not the id.`;
+  }
+  switch (err.status) {
+    case 401:
+      return `${err.message}
+Check the company id, user id and password.`;
+    case 403:
+      return `${err.message}
+Your user cannot do this for that company: publishing needs a manager of the company.`;
+    case 409:
+      return `${err.message}
+This version was already published for the company. Use a new --version.`;
+    case 413:
+      return `${err.message}
+The .zip is over 2 MB.`;
+    default:
+      return err.message;
+  }
+}
+function table(rows) {
+  if (rows.length === 0) return ["No bundle published for this company."];
+  return [
+    "id      version        current  revoked  published_at                min_app",
+    ...rows.map(
+      (r) => `${String(r.id).padEnd(8)}${r.version.padEnd(15)}${(r.is_current ? "yes" : "").padEnd(9)}${(r.revoked ? "yes" : "").padEnd(9)}${(r.published_at ?? "").padEnd(28)}${r.min_app_version ?? ""}`
+    )
+  ];
+}
+async function runCanvas(args, io, deps) {
+  const baseUrl = args.baseUrl ?? CANVAS_ADMIN_API[args.env];
+  const envLabel = args.baseUrl ? `custom (${baseUrl})` : `${args.env.toUpperCase()} (${baseUrl})`;
+  try {
+    let zip;
+    if (args.action === "publish") {
+      zip = loadZip(args.input ?? "");
+      const errors = zip.findings.filter((f) => f.severity === "error");
+      for (const f of zip.findings) {
+        (f.severity === "error" ? io.printError : io.print)(
+          `${f.severity.toUpperCase()} [${f.rule}] ${f.message}`
+        );
+      }
+      if (errors.length > 0) {
+        io.printError("The app would reject this bundle. Nothing was sent.");
+        return 1;
+      }
+    }
+    if (!io.interactive) {
+      io.printError(
+        "canvas needs an interactive terminal: the password is only read from a prompt."
+      );
+      return 1;
+    }
+    const companyId = await askId(io, "Company id", args.companyId);
+    const userId = await askId(io, "User id", args.userId);
+    if (args.action === "publish" && zip) {
+      const hash = `sha256-${createHash2("sha256").update(zip.zipBytes).digest("hex")}`;
+      io.print("");
+      io.print(`Environment:  ${envLabel}`);
+      io.print(`Company:      ${companyId}`);
+      io.print(
+        `Version:      ${args.version}${args.minAppVersion ? ` (min app ${args.minAppVersion})` : ""}`
+      );
+      io.print(`Bundle:       ${zip.zipBytes.length} bytes, ${hash}`);
+      io.print("It goes LIVE AT ONCE for every user of this company.");
+      if (!await confirm(io, args, "Publish?")) {
+        io.print("Cancelled. Nothing was sent.");
+        return 1;
+      }
+    }
+    if (args.action === "revoke") {
+      io.print("");
+      io.print(`Environment:  ${envLabel}`);
+      io.print(`Revoke bundle ${args.bundleId} of company ${companyId}.`);
+      io.print(
+        args.fallbackVersion ? `The app switches to version ${args.fallbackVersion} (a version, not an id).` : "Without --fallback-version, revoking the current bundle leaves the company with none: the app shows its default screen."
+      );
+      if (!await confirm(io, args, "Revoke?")) {
+        io.print("Cancelled. Nothing was sent.");
+        return 1;
+      }
+    }
+    const client = new CanvasAdminClient({
+      baseUrl,
+      userAgent: deps.userAgent,
+      fetchImpl: deps.fetchImpl
+    });
+    await logIn(io, client, companyId, userId);
+    if (args.action === "publish" && zip) {
+      const record = await client.publish({
+        zipBytes: zip.zipBytes,
+        version: args.version ?? "",
+        companyId,
+        minAppVersion: args.minAppVersion
+      });
+      if (args.json) io.print(JSON.stringify(record));
+      else {
+        io.print(
+          `Published version ${record.version} (id ${record.id}) \u2014 current: ${record.is_current}.`
+        );
+        io.print(`bundleHash: ${record.bundle_hash}`);
+        io.print("Apps of this company load it the next time they come to the foreground.");
+      }
+      return 0;
+    }
+    if (args.action === "list") {
+      const rows = await client.list(companyId);
+      if (args.json) io.print(JSON.stringify(rows));
+      else for (const line of table(rows)) io.print(line);
+      return 0;
+    }
+    const result = await client.revoke(args.bundleId ?? 0, args.fallbackVersion);
+    io.print(args.json ? JSON.stringify(result) : `Revoked. ${JSON.stringify(result)}`);
+    return 0;
+  } catch (err) {
+    io.printError(describeError(err));
+    return 1;
+  }
+}
+
+// src/canvas-admin/tty.ts
+import { createInterface } from "readline";
+var rl = null;
+var mutedPrompt = null;
+function reader() {
+  if (rl) return rl;
+  rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+  const out = rl;
+  const write = out._writeToOutput.bind(rl);
+  out._writeToOutput = (s) => {
+    if (mutedPrompt === null || s.includes(mutedPrompt)) write(s);
+  };
+  return rl;
+}
+function question(prompt, secret) {
+  const r = reader();
+  return new Promise((resolve5) => {
+    mutedPrompt = secret ? prompt : null;
+    r.question(prompt, (answer) => {
+      if (secret) {
+        mutedPrompt = null;
+        process.stderr.write("\n");
+      }
+      resolve5(answer);
+    });
+  });
+}
+function terminalIo() {
+  return {
+    interactive: Boolean(process.stdin.isTTY),
+    ask: (q) => question(q, false),
+    askSecret: (q) => question(q, true),
+    print: (line) => console.log(line),
+    printError: (line) => console.error(line)
+  };
+}
+function closeTerminalIo() {
+  rl?.close();
+  rl = null;
+}
+
 // src/cli-dev.ts
-import { existsSync, readFileSync as readFileSync2, statSync } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync3, statSync as statSync2 } from "fs";
 import { createServer } from "http";
-import { dirname as dirname2, extname as extname2, join, resolve as resolve2 } from "path";
+import { dirname as dirname2, extname as extname3, join as join2, resolve as resolve3 } from "path";
 import { fileURLToPath } from "url";
 import { strFromU8, unzipSync as unzipSync2 } from "fflate";
 
@@ -482,7 +979,7 @@ function telemetry(spec, now) {
         serialNo: spec.serialNo,
         attemptDate: now - 10 * 6e4,
         message: spec.syncError,
-        messageCode: "SYNC_FAILED"
+        messageCode: "send_data_log_error"
       }
     ] : []
   };
@@ -566,6 +1063,7 @@ function systemStatus(overrides = {}) {
     internet: true,
     permission: true,
     hasDevices: true,
+    hasDevicesKnown: true,
     missingOptionalPermissions: [],
     missingEssentialPermissions: [],
     deviceSyncError: {},
@@ -575,28 +1073,27 @@ function systemStatus(overrides = {}) {
 }
 
 // src/dev/scenarios.ts
-var HARNESS_NATIVE_VERSION = "0.17.0";
+var HARNESS_NATIVE_VERSION = "0.18.0";
 var base = {
-  description: "Two devices, background service already running, realistic latency.",
+  description: "Two devices, background service already running, realistic latency. The first device starts a BLE session 3 s after load; the second stays between sessions.",
   nativeVersion: HARNESS_NATIVE_VERSION,
   latencyMs: [80, 250],
   serviceStartMs: 0,
-  userDeviceSilent: false,
   logPeriodS: 60,
   systemStatus: systemStatus(),
   devices: () => twoDevices()
 };
 var SCENARIOS = {
-  default: base,
+  default: { ...base, firstSessionAfterMs: 3e3 },
   "cold-start": {
     ...base,
-    description: "App launched from cold: the background service takes 4 s to start, and every ping/userDevice sent before that is lost. A bundle that asks once stays on its loading screen forever.",
+    description: "App launched from cold: the background service takes 4 s to start, and every ping/userDevice sent before that is lost. From nativeVersion 0.18.0 the app re-sends the lost userDevice itself; below it, a bundle that asks once stays on its loading screen forever.",
     serviceStartMs: 4e3
   },
   "no-devices": {
     ...base,
-    description: "Account with no linked device: userDevice never answers and systemStatus.hasDevices is false. Your bundle must show an empty state.",
-    userDeviceSilent: true,
+    description: "Account with no linked device: userDevice answers with error NO_DEVICES (below nativeVersion 0.18.0: never answers) and systemStatus.hasDevices is false. Your bundle must show an empty state.",
+    userDeviceError: "NO_DEVICES",
     systemStatus: systemStatus({ hasDevices: false })
   },
   "shared-serial": {
@@ -606,20 +1103,19 @@ var SCENARIOS = {
   },
   offline: {
     ...base,
-    description: "No internet. systemStatus.internet is false and sensorLog fails; userDevice answers from the cache.",
-    sensorLogError: "Connection failed",
-    systemStatus: systemStatus({ internet: false })
+    description: "No internet. systemStatus.internet is false and sensorLog fails; userDevice answers from the cache. The internet comes back when a test calls window.condorDev.setStatus({ internet: true }).",
+    systemStatus: systemStatus({ internet: false, hasDevicesKnown: false })
   }
 };
 
 // src/cli-dev.ts
 function readClientHtml(input) {
-  const path = resolve2(input);
-  if (existsSync(path) && statSync(path).isDirectory()) {
-    return inlineHtml(join(path, "index.html"));
+  const path = resolve3(input);
+  if (existsSync2(path) && statSync2(path).isDirectory()) {
+    return inlineHtml(join2(path, "index.html"));
   }
-  if (extname2(path).toLowerCase() === ".zip") {
-    const files = unzipSync2(new Uint8Array(readFileSync2(path)));
+  if (extname3(path).toLowerCase() === ".zip") {
+    const files = unzipSync2(new Uint8Array(readFileSync3(path)));
     const entry = files["index.html"];
     if (!entry) throw new Error(`${input}: no index.html at the root of the zip.`);
     return strFromU8(entry);
@@ -627,11 +1123,18 @@ function readClientHtml(input) {
   return inlineHtml(path);
 }
 var escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-function harnessPage(scenario, nativeVersion) {
+function harnessPage(scenario, nativeVersion, extra = {}) {
   const options = Object.entries(SCENARIOS).map(
     ([name, s]) => `<option value="${name}" title="${escapeHtml(s.description)}"${name === scenario ? " selected" : ""}>${name}</option>`
   ).join("");
-  const description = escapeHtml(SCENARIOS[scenario]?.description ?? "");
+  const description = escapeHtml(
+    extra.scenarioFile ? `Scenario file ${extra.scenarioFile}` : SCENARIOS[scenario]?.description ?? ""
+  );
+  const defaultsJson = JSON.stringify({
+    latencyMs: extra.latencyMs ?? null,
+    panel: extra.panel !== false,
+    scenarioFile: Boolean(extra.scenarioFile)
+  }).replace(/</g, "\\u003c");
   const scenarioJson = JSON.stringify(scenario).replace(/</g, "\\u003c");
   const nativeJson = JSON.stringify(
     nativeVersion === void 0 ? void 0 : nativeVersion === "null" ? null : nativeVersion
@@ -667,6 +1170,11 @@ function harnessPage(scenario, nativeVersion) {
 <script>
   var scenario = ${scenarioJson};
   var nativeVersion = ${nativeJson};
+  var defaults = ${defaultsJson};
+  var params = new URLSearchParams(location.search);
+  var latency = params.has('latency') ? Number(params.get('latency')) : defaults.latencyMs;
+  var panel = params.has('panel') ? params.get('panel') !== '0' : defaults.panel;
+  var useFile = defaults.scenarioFile && !params.has('scenario');
   var harness = null;
   document.getElementById('scenario').addEventListener('change', function (e) {
     var params = new URLSearchParams(location.search);
@@ -676,14 +1184,55 @@ function harnessPage(scenario, nativeVersion) {
   document.getElementById('back').addEventListener('click', function () {
     if (harness) harness.pressBack();
   });
-  var chosen = CondorDevHarness.SCENARIOS[scenario];
-  if (nativeVersion !== undefined) chosen = Object.assign({}, chosen, { nativeVersion: nativeVersion });
-  fetch('/__condor/client.html')
+  // A scenario file extends a named scenario: its fields replace the base's,
+  // systemStatus is merged, and devices is the userDevice payload to answer.
+  function fromFile(file) {
+    var base = CondorDevHarness.SCENARIOS[file.extends || 'default'];
+    if (!base) throw new Error('scenario file: unknown "extends": ' + file.extends);
+    var out = Object.assign({}, base, file);
+    out.systemStatus = Object.assign({}, base.systemStatus, file.systemStatus || {});
+    if (file.devices) {
+      var devices = JSON.stringify(file.devices);
+      out.devices = function () { return JSON.parse(devices); };
+    } else out.devices = base.devices;
+    return out;
+  }
+  var chosen = null;
+  (useFile ? fetch('/__condor/scenario.json').then(function (r) { return r.json(); }).then(fromFile)
+           : Promise.resolve(CondorDevHarness.SCENARIOS[scenario]))
+    .then(function (s) {
+      chosen = s;
+      if (nativeVersion !== undefined) chosen = Object.assign({}, chosen, { nativeVersion: nativeVersion });
+      if (latency !== null && latency >= 0) chosen = Object.assign({}, chosen, { latencyMs: latency });
+      return fetch('/__condor/client.html');
+    })
     .then(function (r) { if (!r.ok) throw new Error('could not read the bundle: HTTP ' + r.status); return r.text(); })
     .then(function (html) {
-      return CondorDevHarness.createDevHarness({ html: html, scenario: chosen, mount: document.getElementById('device') });
+      return CondorDevHarness.createDevHarness({ html: html, scenario: chosen, mount: document.getElementById('device'), devPanel: panel });
+    })
+    .then(function (h) {
+      harness = h;
+      var confirm = new URLSearchParams(location.search).get('confirm');
+      if (confirm === 'accept' || confirm === 'decline') h.setConfirmations(confirm);
+      // Scripted tests (Puppeteer, Playwright) drive the simulated app here.
+      // See docs/device-testing.md, "Scripted tests".
+      window.condorDev = {
+        scenario: h.scenario,
+        get log() { return h.log.slice(); },
+        // true once the bundle is mounted AND its handshake was answered (or,
+        // with nativeVersion null, left unanswered on purpose).
+        get ready() {
+          return h.log.some(function (e) {
+            return (e.kind === 'reply' && e.key === 'handshake-ack') || /handshake unanswered/.test(e.detail);
+          });
+        },
+        emit: function (key, payload) { h.emit(key, payload); },
+        setStatus: function (patch) { h.setStatus(patch); },
+        setConnected: function (deviceId, connected) { h.setConnected(deviceId, connected); },
+        setConfirmations: function (mode) { h.setConfirmations(mode); },
+        pressBack: function () { h.pressBack(); }
+      };
     })
-    .then(function (h) { harness = h; })
     .catch(function (err) { document.getElementById('device').textContent = String(err); console.error(err); });
 </script>
 </body>
@@ -691,10 +1240,13 @@ function harnessPage(scenario, nativeVersion) {
 }
 function harnessScriptPath() {
   const here = typeof __dirname !== "undefined" ? __dirname : dirname2(fileURLToPath(import.meta.url));
-  return join(here, "dev-harness.global.js");
+  return join2(here, "dev-harness.global.js");
 }
 function startDevServer(opts) {
-  if (!(opts.scenario in SCENARIOS)) {
+  const scenarioFile = opts.scenario.endsWith(".json") ? resolve3(opts.scenario) : void 0;
+  if (scenarioFile) {
+    JSON.parse(readFileSync3(scenarioFile, "utf-8"));
+  } else if (!(opts.scenario in SCENARIOS)) {
     throw new Error(
       `Unknown scenario "${opts.scenario}". Known: ${Object.keys(SCENARIOS).join(", ")}.`
     );
@@ -711,23 +1263,38 @@ function startDevServer(opts) {
         res.end(readClientHtml(opts.input));
         return;
       }
+      if (url.pathname === "/__condor/scenario.json" && scenarioFile) {
+        res.writeHead(200, {
+          "content-type": "application/json; charset=utf-8",
+          "cache-control": "no-store"
+        });
+        res.end(readFileSync3(scenarioFile));
+        return;
+      }
       if (url.pathname === "/__condor/harness.js") {
         res.writeHead(200, {
           "content-type": "text/javascript; charset=utf-8",
           "cache-control": "no-store"
         });
-        res.end(readFileSync2(harnessScriptPath()));
+        res.end(readFileSync3(harnessScriptPath()));
         return;
       }
       if (url.pathname === "/") {
-        const scenario = url.searchParams.get("scenario") ?? opts.scenario;
+        const named = url.searchParams.get("scenario");
+        const scenario = named ?? (scenarioFile ? "default" : opts.scenario);
         res.writeHead(200, {
           "content-type": "text/html; charset=utf-8",
           "content-security-policy": CANVAS_CSP,
           "cache-control": "no-store"
         });
         const nativeVersion = url.searchParams.get("nativeVersion") ?? opts.nativeVersion;
-        res.end(harnessPage(scenario in SCENARIOS ? scenario : opts.scenario, nativeVersion));
+        res.end(
+          harnessPage(scenario in SCENARIOS ? scenario : "default", nativeVersion, {
+            latencyMs: opts.latencyMs,
+            panel: opts.panel,
+            scenarioFile: named ? void 0 : scenarioFile && opts.scenario
+          })
+        );
         return;
       }
       res.writeHead(404).end();
@@ -741,12 +1308,13 @@ function startDevServer(opts) {
 }
 
 // src/cli.ts
-function runDev(input, scenario, port, nativeVersion) {
-  const server = startDevServer({ input, scenario, port, nativeVersion });
+function runDev(opts) {
+  const { input, scenario, port, nativeVersion } = opts;
+  const server = startDevServer(opts);
   server.on("listening", () => {
     const native = nativeVersion === void 0 ? "" : `&nativeVersion=${nativeVersion}`;
     console.log(
-      `Condor Canvas dev harness: http://localhost:${port}/?scenario=${scenario}${native}`
+      `Condor Canvas dev harness: http://localhost:${port}/${scenario.endsWith(".json") ? "" : `?scenario=${scenario}`}${native}`
     );
     console.log(`  bundle:   ${input} (re-read on every reload)`);
     console.log("  sandbox, shell policy and CSP: same as the app");
@@ -761,7 +1329,7 @@ function runDev(input, scenario, port, nativeVersion) {
 }
 function runBuild(htmlPath, outPath, maxBytes) {
   const result = buildBundle(htmlPath, maxBytes);
-  const resolvedOut = resolve3(outPath);
+  const resolvedOut = resolve4(outPath);
   mkdirSync(dirname3(resolvedOut), { recursive: true });
   writeFileSync(resolvedOut, result.zipBytes);
   const kb = (Buffer.byteLength(result.html) / 1024).toFixed(1);
@@ -811,7 +1379,28 @@ ${errors.length} error(s), ${warnings.length} warning(s).` + (result.size === nu
   );
   return 0;
 }
+async function runCanvasCommand(argv) {
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    console.log(CANVAS_USAGE);
+    process.exit(argv.length === 0 ? 1 : 0);
+  }
+  const parsed = parseCanvasArgs(argv, process.env);
+  if ("error" in parsed) {
+    console.error(parsed.error);
+    console.error("Run `condor-mobile-bridge canvas --help`.");
+    process.exit(1);
+  }
+  const code = await runCanvas(parsed, terminalIo(), {
+    userAgent: `condor-mobile-bridge-cli/${version}`
+  });
+  closeTerminalIo();
+  process.exit(code);
+}
 function main() {
+  if (process.argv[2] === "canvas") {
+    void runCanvasCommand(process.argv.slice(3));
+    return;
+  }
   const args = parseArgs(process.argv.slice(2));
   if (args.help || !args.htmlPath) {
     console.log(USAGE);
@@ -819,7 +1408,14 @@ function main() {
   }
   if (args.command === "dev") {
     try {
-      runDev(args.htmlPath, args.scenario, args.port, args.nativeVersion);
+      runDev({
+        input: args.htmlPath,
+        scenario: args.scenario,
+        port: args.port,
+        nativeVersion: args.nativeVersion,
+        latencyMs: args.latencyMs,
+        panel: args.panel
+      });
     } catch (err) {
       console.error(`dev: ${err instanceof Error ? err.message : String(err)}`);
       process.exit(1);