getobsrv 0.3.1 → 0.4.0

package/README.md

@@ -1,5 +1,9 @@
 # Obsrv
 
+[![CI](https://github.com/vibesyemmy/obsrv/actions/workflows/ci.yml/badge.svg)](https://github.com/vibesyemmy/obsrv/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/getobsrv)](https://www.npmjs.com/package/getobsrv)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 See your site the way 1x screens see it.
 
 Designers and developers work on HiDPI (2x–3x) monitors. A large share of users are on
@@ -74,7 +78,15 @@ The same CLI is also wrapped as an MCP server (stdio, stateless) so MCP
 clients get the tools natively: `obsrv_snap` (render a URL at a preset's true
 raster density — the PNG comes back as an inline image up to 1.5 MiB),
 `obsrv_diff` (the 1x-vs-2x metrics as structured output) and `obsrv_presets`
-(every preset and panel profile, no render). Build first, then register:
+(every preset and panel profile, no render).
+
+If the desktop app is open with the toolbar's **Agent control** toggle on,
+`obsrv_snap` drives the *visible* window instead: you watch the URL load and
+the preset flip, and the agent gets back a capture of the app exactly as you
+see it (plus `obsrv_drive` to flip URL/preset/profile directly). With no app
+running, everything falls back to the headless render automatically.
+
+Build first, then register:
 
 ```bash
 claude mcp add --scope user obsrv -- npx -y getobsrv mcp
@@ -95,6 +107,16 @@ Architecture, decisions and the full spec live in
 the UI style rationale (why the chrome is strictly neutral) is in
 [docs/superpowers/specs/2026-08-23-obsrv-ui-style.md](docs/superpowers/specs/2026-08-23-obsrv-ui-style.md).
 
+## Install (desktop app)
+
+Grab the DMG for your chip from [Releases](https://github.com/vibesyemmy/obsrv/releases),
+drag Obsrv.app to Applications, then clear the quarantine flag once (the build is not
+yet notarised, so macOS falsely reports it as "damaged"):
+
+```bash
+xattr -cr /Applications/Obsrv.app
+```
+
 ## Distribution
 
 Obsrv will publish to npm as **`getobsrv`** (the installed commands remain `obsrv`

package/out/main/cli.js

@@ -3,7 +3,7 @@ const electron = require("electron");
 const node_fs = require("node:fs");
 const node_os = require("node:os");
 const node_path = require("node:path");
-const targetSource = require("./targetSource-w_vWw7zd.js");
+const targetSource = require("./targetSource-DkXWE0ha.js");
 function boxDownsample(src, factor) {
   if (!Number.isInteger(factor) || factor < 1) throw new RangeError("factor must be an integer >= 1");
   const width = Math.floor(src.width / factor);

package/out/main/index.js

@@ -1,9 +1,11 @@
 "use strict";
 const electron = require("electron");
+const node_fs = require("node:fs");
 const promises = require("node:fs/promises");
 const node_path = require("node:path");
-const targetSource = require("./targetSource-w_vWw7zd.js");
-const node_fs = require("node:fs");
+const node_crypto = require("node:crypto");
+const targetSource = require("./targetSource-DkXWE0ha.js");
+const node_http = require("node:http");
 const node_url = require("node:url");
 const IPC = {
   navigate: "obsrv:navigate",
@@ -29,7 +31,10 @@ const IPC = {
   openImage: "obsrv:open-image",
   focusUrl: "obsrv:focus-url",
   openImagePath: "obsrv:open-image-path",
-  readImageFile: "obsrv:read-image-file"
+  readImageFile: "obsrv:read-image-file",
+  uiState: "obsrv:ui-state",
+  agentApply: "obsrv:agent-apply",
+  agentActivity: "obsrv:agent-activity"
 };
 function attachFrameBus(target, win) {
   let ready = false;
@@ -63,6 +68,46 @@ function attachFrameBus(target, win) {
     }
   };
 }
+const CONTROL_FILE_NAME = "control.json";
+const CONTROL_TOKEN_BYTES = 32;
+const CONTROL_COMMANDS = [
+  "status",
+  "navigate",
+  "setPreset",
+  "setProfile",
+  "setViewMode",
+  "captureVisible"
+];
+function isControlCommand(v) {
+  return typeof v === "string" && CONTROL_COMMANDS.includes(v);
+}
+function tokenEqual(expected, provided) {
+  if (typeof provided !== "string") return false;
+  const a = node_crypto.createHash("sha256").update(expected).digest();
+  const b = node_crypto.createHash("sha256").update(provided).digest();
+  return node_crypto.timingSafeEqual(a, b);
+}
+const idList = (ids) => ids.join(", ");
+function presetApplyError(id) {
+  if (typeof id !== "string") return "setPreset payload must be { id: string }";
+  if (id === "custom") {
+    return "the custom preset cannot be applied remotely — it is defined by the fields in the app; pick a preset id";
+  }
+  if (!targetSource.SCREEN_PRESETS.some((p) => p.id === id)) {
+    return `unknown preset "${id}" — valid ids: ${idList(targetSource.SCREEN_PRESETS.map((p) => p.id))}`;
+  }
+  return null;
+}
+function profileApplyError(id) {
+  if (typeof id !== "string") return "setProfile payload must be { id: string }";
+  if (!targetSource.PANEL_PROFILES.some((p) => p.id === id)) {
+    return `unknown profile "${id}" — valid ids: ${idList(targetSource.PANEL_PROFILES.map((p) => p.id))}`;
+  }
+  return null;
+}
+function viewModeApplyError(v) {
+  return v === "1:1" || v === "fit" ? null : `setViewMode payload must be { mode: '1:1' | 'fit' }`;
+}
 const MAX_RECT = 16384;
 const isFiniteNumber = (v) => typeof v === "number" && Number.isFinite(v);
 const isRecord = (v) => typeof v === "object" && v !== null;
@@ -126,11 +171,23 @@ function parseSettings(raw) {
   const { hostDiagonalInches, hostNits } = raw;
   if (!isFiniteNumber(hostDiagonalInches) || hostDiagonalInches <= 0) return null;
   if (!isFiniteNumber(hostNits) || hostNits <= 0) return null;
-  return { hostDiagonalInches, hostNits };
+  const agentControl = raw.agentControl ?? false;
+  if (typeof agentControl !== "boolean") return null;
+  return { hostDiagonalInches, hostNits, agentControl };
 }
 function parseMode(raw) {
   return raw === "url" || raw === "image" ? raw : null;
 }
+const MAX_UI_ID = 64;
+function parseUiState(raw) {
+  if (!isRecord(raw)) return null;
+  const { presetId, profileId, viewMode, mode } = raw;
+  if (typeof presetId !== "string" || presetId.length === 0 || presetId.length > MAX_UI_ID) return null;
+  if (typeof profileId !== "string" || profileId.length === 0 || profileId.length > MAX_UI_ID) return null;
+  if (viewMode !== "1:1" && viewMode !== "fit") return null;
+  if (mode !== "url" && mode !== "image") return null;
+  return { presetId, profileId, viewMode, mode };
+}
 function parseScrollPos(raw) {
   if (!isRecord(raw)) return null;
   const { x, y } = raw;
@@ -143,7 +200,10 @@ function loadSettings(file) {
     const raw = JSON.parse(node_fs.readFileSync(file, "utf8"));
     return {
       hostDiagonalInches: isPositive(raw.hostDiagonalInches) ? raw.hostDiagonalInches : targetSource.DEFAULT_SETTINGS.hostDiagonalInches,
-      hostNits: isPositive(raw.hostNits) ? raw.hostNits : targetSource.DEFAULT_SETTINGS.hostNits
+      hostNits: isPositive(raw.hostNits) ? raw.hostNits : targetSource.DEFAULT_SETTINGS.hostNits,
+      // Anything but a literal true (older files have no key at all) means off:
+      // a network-facing capability must never be enabled by a malformed file.
+      agentControl: raw.agentControl === true
     };
   } catch {
     return { ...targetSource.DEFAULT_SETTINGS };
@@ -151,9 +211,158 @@ function loadSettings(file) {
 }
 function saveSettings(file, s) {
   if (!isPositive(s.hostDiagonalInches) || !isPositive(s.hostNits)) throw new RangeError("settings values must be finite and > 0");
+  if (typeof s.agentControl !== "boolean") throw new RangeError("agentControl must be a boolean");
   node_fs.mkdirSync(node_path.dirname(file), { recursive: true });
   node_fs.writeFileSync(file, JSON.stringify(s, null, 2));
 }
+const MAX_BODY_BYTES = 64 * 1024;
+const APPLY_WAIT_MS = 2e3;
+const APPLY_POLL_MS = 25;
+const reply = (code, body) => ({ code, body });
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+class ControlServer {
+  constructor(file, deps) {
+    this.file = file;
+    this.deps = deps;
+  }
+  server = null;
+  token = "";
+  get running() {
+    return this.server !== null;
+  }
+  /** Starts the server on an ephemeral loopback port and writes the discovery file. */
+  async start() {
+    if (this.server) return;
+    this.token = node_crypto.randomBytes(CONTROL_TOKEN_BYTES).toString("hex");
+    const server = node_http.createServer((req, res) => void this.handle(req, res));
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", resolve);
+    });
+    this.server = server;
+    const { port } = server.address();
+    node_fs.rmSync(this.file, { force: true });
+    node_fs.writeFileSync(this.file, JSON.stringify({ port, token: this.token }), { mode: 384 });
+  }
+  /**
+   * Stops the server and removes the discovery file. Synchronous on purpose:
+   * the quit path must not race the process teardown, and the file — the
+   * part that outlives the process — goes first.
+   */
+  stop() {
+    const server = this.server;
+    this.server = null;
+    this.token = "";
+    node_fs.rmSync(this.file, { force: true });
+    if (server) {
+      server.closeAllConnections();
+      server.close();
+    }
+  }
+  async handle(req, res) {
+    let out;
+    try {
+      out = await this.route(req);
+    } catch (e) {
+      out = reply(500, { error: e instanceof Error ? e.message : "internal error" });
+    }
+    const payload = JSON.stringify(out.body);
+    res.writeHead(out.code, { "content-type": "application/json", "content-length": Buffer.byteLength(payload) });
+    res.end(payload);
+  }
+  async route(req) {
+    if (req.method !== "POST" || req.url !== "/") return reply(404, { error: "POST / only" });
+    if (req.headers.origin !== void 0) return reply(403, { error: "cross-origin requests are refused" });
+    const contentType = req.headers["content-type"] ?? "";
+    if (!/^application\/json\b/i.test(contentType)) {
+      return reply(415, { error: "content-type must be application/json" });
+    }
+    const raw = await this.readBody(req);
+    if (raw === null) return reply(413, { error: `body over ${MAX_BODY_BYTES} bytes` });
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return reply(400, { error: "body must be JSON" });
+    }
+    if (typeof parsed !== "object" || parsed === null) return reply(400, { error: "body must be a JSON object" });
+    const body = parsed;
+    if (!tokenEqual(this.token, body.token)) return reply(403, { error: "forbidden" });
+    const command = body.command;
+    if (!isControlCommand(command)) {
+      return reply(400, { error: `unknown command — allowed: ${CONTROL_COMMANDS.join(", ")}` });
+    }
+    this.deps.activity();
+    const payload = typeof body.payload === "object" && body.payload !== null ? body.payload : {};
+    switch (command) {
+      case "status":
+        return reply(200, { ok: true, ...this.deps.status() });
+      case "navigate": {
+        const url = payload.url;
+        if (typeof url !== "string" || url.trim() === "") return reply(400, { error: "navigate payload must be { url: string }" });
+        const bad = targetSource.urlSchemeError(url);
+        if (bad) return reply(400, { error: bad });
+        const applied = await this.deps.navigate(url.trim());
+        return reply(200, { ok: true, url: applied });
+      }
+      case "setPreset": {
+        const err = presetApplyError(payload.id);
+        if (err) return reply(400, { error: err });
+        return this.applyAndConfirm({ presetId: payload.id }, (s) => s.presetId === payload.id);
+      }
+      case "setProfile": {
+        const err = profileApplyError(payload.id);
+        if (err) return reply(400, { error: err });
+        return this.applyAndConfirm({ profileId: payload.id }, (s) => s.profileId === payload.id);
+      }
+      case "setViewMode": {
+        const err = viewModeApplyError(payload.mode);
+        if (err) return reply(400, { error: err });
+        const mode = payload.mode;
+        return this.applyAndConfirm({ viewMode: mode }, (s) => s.viewMode === mode);
+      }
+      case "captureVisible": {
+        const capture = await this.deps.captureVisible();
+        return reply(200, { ok: true, ...capture });
+      }
+    }
+  }
+  /**
+   * Forwards a patch to the renderer and waits (bounded) for the UI mirror to
+   * reflect it, so a 200 means "applied", not "sent". `applied: false` after
+   * the wait is not an error — the renderer may be busy — the caller can poll
+   * `status`.
+   */
+  async applyAndConfirm(patch, confirmed) {
+    this.deps.apply(patch);
+    const deadline = Date.now() + APPLY_WAIT_MS;
+    let applied = confirmed(this.deps.status());
+    while (!applied && Date.now() < deadline) {
+      await sleep(APPLY_POLL_MS);
+      applied = confirmed(this.deps.status());
+    }
+    return reply(200, { ok: true, applied, ...this.deps.status() });
+  }
+  /** The request body, or null when it exceeds the cap. */
+  readBody(req) {
+    return new Promise((resolve, rejectOnError) => {
+      const chunks = [];
+      let size = 0;
+      req.on("data", (chunk) => {
+        size += chunk.byteLength;
+        if (size > MAX_BODY_BYTES) {
+          req.removeAllListeners("data");
+          req.removeAllListeners("end");
+          resolve(null);
+          return;
+        }
+        chunks.push(chunk);
+      });
+      req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+      req.on("error", rejectOnError);
+    });
+  }
+}
 const TOOLBAR_H = 44;
 const MAX_IMAGE_FILE_BYTES = 64 * 1024 * 1024;
 function hostInfo(win) {
@@ -176,8 +385,7 @@ function registerIpc(ctx) {
   const assertRenderer = (e) => {
     if (!fromRenderer(e)) throw new Error("ipc: unexpected sender");
   };
-  electron.ipcMain.handle(IPC.navigate, async (e, url) => {
-    assertRenderer(e);
+  const navigateBoth = async (url) => {
     let wanted = url;
     try {
       wanted = targetSource.normalizeUrl(url);
@@ -186,6 +394,10 @@ function registerIpc(ctx) {
     }
     const [applied] = await Promise.all([native.load(wanted), target.load(wanted)]);
     return applied;
+  };
+  electron.ipcMain.handle(IPC.navigate, (e, url) => {
+    assertRenderer(e);
+    return navigateBoth(url);
   });
   electron.ipcMain.on(IPC.reload, (e) => {
     if (!fromRenderer(e)) return;
@@ -271,8 +483,81 @@ function registerIpc(ctx) {
     const s = parseSettings(raw);
     if (!s) throw new Error("invalid settings");
     saveSettings(settingsFile, s);
+    const wasEnabled = settings.agentControl;
     settings = s;
+    if (s.agentControl !== wasEnabled) applyAgentControl(s.agentControl);
+  });
+  const uiState = { presetId: "1080p-24", profileId: "reference", viewMode: "1:1", mode: "url" };
+  const MAX_PENDING_APPLIES = 32;
+  let rendererReported = false;
+  let warnedPendingOverflow = false;
+  const pendingApplies = [];
+  electron.ipcMain.on(IPC.uiState, (e, raw) => {
+    if (!fromRenderer(e)) return;
+    const s = parseUiState(raw);
+    if (!s) return;
+    Object.assign(uiState, s);
+    if (!rendererReported) {
+      rendererReported = true;
+      for (const patch of pendingApplies.splice(0)) {
+        if (!win.isDestroyed()) win.webContents.send(IPC.agentApply, patch);
+      }
+    }
   });
+  const appVersion = (() => {
+    try {
+      const pkg = JSON.parse(node_fs.readFileSync(node_path.join(__dirname, "..", "..", "package.json"), "utf8"));
+      return pkg.version ?? electron.app.getVersion();
+    } catch {
+      return electron.app.getVersion();
+    }
+  })();
+  const control = new ControlServer(node_path.join(electron.app.getPath("userData"), CONTROL_FILE_NAME), {
+    status: () => {
+      let url = "";
+      try {
+        url = target.webContents.getURL();
+      } catch {
+      }
+      return { version: appVersion, url, ...uiState };
+    },
+    navigate: navigateBoth,
+    apply: (patch) => {
+      if (win.isDestroyed()) return;
+      if (!rendererReported) {
+        if (pendingApplies.length >= MAX_PENDING_APPLIES) {
+          if (!warnedPendingOverflow) {
+            warnedPendingOverflow = true;
+            console.warn("obsrv: agent-apply queue full before the renderer mounted; dropping oldest entries");
+          }
+          pendingApplies.shift();
+        }
+        pendingApplies.push(patch);
+        return;
+      }
+      win.webContents.send(IPC.agentApply, patch);
+    },
+    captureVisible: async () => {
+      const image = await win.webContents.capturePage();
+      const size = image.getSize();
+      return { data: image.toPNG().toString("base64"), width: size.width, height: size.height };
+    },
+    activity: () => {
+      if (!win.isDestroyed()) win.webContents.send(IPC.agentActivity);
+    }
+  });
+  const applyAgentControl = (enabled) => {
+    if (enabled) {
+      control.start().catch((e) => {
+        console.error("obsrv: agent-control server failed to start", e);
+      });
+    } else {
+      control.stop();
+    }
+  };
+  if (process.env.OBSRV_AGENT_CONTROL === "1") settings = { ...settings, agentControl: true };
+  if (settings.agentControl) applyAgentControl(true);
+  electron.app.on("will-quit", () => control.stop());
   electron.ipcMain.handle(IPC.readImageFile, async (e, raw) => {
     assertRenderer(e);
     if (typeof raw !== "string" || !targetSource.IMAGE_EXTENSIONS.test(raw)) throw new Error("Unsupported file type");

package/out/main/{targetSource-w_vWw7zd.js → targetSource-DkXWE0ha.js}

@@ -3,7 +3,7 @@ const electron = require("electron");
 const node_events = require("node:events");
 const node_path = require("node:path");
 const MAX_VIEWPORT = 4096;
-const DEFAULT_SETTINGS = { hostDiagonalInches: 27, hostNits: 500 };
+const DEFAULT_SETTINGS = { hostDiagonalInches: 27, hostNits: 500, agentControl: false };
 const SCREEN_PRESETS = [
   // Laptops — ordered largest to smallest panel, then the denser 1080p outlier.
   { id: "laptop-768", label: '1366×768 15.6"', width: 1366, height: 768, diagonalInches: 15.6, deviceScaleFactor: 1, group: "laptop" },
@@ -70,6 +70,16 @@ function normalizeUrl(input) {
   if (SCHEME.test(s)) return s;
   return `https://${s}`;
 }
+const ALLOWED_URL_SCHEMES = ["http:", "https:", "file:"];
+function urlSchemeError(url) {
+  const trimmed = url.trim();
+  const match = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed);
+  if (!match) return null;
+  const scheme = `${match[1].toLowerCase()}:`;
+  if (ALLOWED_URL_SCHEMES.includes(scheme)) return null;
+  if (/^[a-z0-9.-]+:\d+(\/|$)/i.test(trimmed)) return null;
+  return `unsupported URL scheme "${scheme}" — obsrv renders ${ALLOWED_URL_SCHEMES.map((s) => `${s}//`).join(", ")} URLs only (bare hosts like example.com also work; they normalise to http(s)).`;
+}
 const ERR_ABORTED = -3;
 const DEFAULT_FPS = 30;
 const DEFAULT_VIEWPORT = { width: 1920, height: 1080 };
@@ -349,3 +359,4 @@ exports.findPreset = findPreset;
 exports.findProfile = findProfile;
 exports.maxCssViewport = maxCssViewport;
 exports.normalizeUrl = normalizeUrl;
+exports.urlSchemeError = urlSchemeError;

package/out/mcp/control.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ControlCallError = exports.CONTROL_FILE_ENV = void 0;
+exports.controlFilePath = controlFilePath;
+exports.controlCall = controlCall;
+exports.discoverControl = discoverControl;
+const promises_1 = require("node:fs/promises");
+const node_http_1 = require("node:http");
+const node_os_1 = require("node:os");
+const control_1 = require("../shared/control");
+/**
+ * MCP-side client for the app's agent-control server (spec §14 "Live
+ * drive"): discovery-file lookup, liveness check, and the one-shot POST the
+ * protocol speaks. Runs under plain node — the userData path is derived
+ * per-platform in shared/control.ts, never asked of Electron.
+ */
+/**
+ * Overrides where the discovery file is looked for. The e2e harness sets it
+ * (its app runs with an isolated --user-data-dir, so its control.json is not
+ * at the standard path); it also keeps those tests hermetic against a real
+ * Obsrv the developer may have open.
+ */
+exports.CONTROL_FILE_ENV = 'OBSRV_CONTROL_FILE';
+function controlFilePath() {
+    return process.env[exports.CONTROL_FILE_ENV] ?? (0, control_1.defaultControlFilePath)(process.platform, process.env, (0, node_os_1.homedir)());
+}
+/** A non-2xx answer from the control server, carrying its error message. */
+class ControlCallError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+}
+exports.ControlCallError = ControlCallError;
+/**
+ * One control-protocol command. Rejects on transport failure, timeout, or a
+ * non-200 answer (with the server's error message when it sent one).
+ */
+function controlCall(info, command, payload = {}, timeoutMs = 10_000) {
+    return new Promise((resolve, reject) => {
+        const body = JSON.stringify({ token: info.token, command, payload });
+        const req = (0, node_http_1.request)({
+            host: '127.0.0.1',
+            port: info.port,
+            method: 'POST',
+            path: '/',
+            headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) },
+            timeout: timeoutMs,
+        }, res => {
+            let text = '';
+            res.on('data', d => (text += String(d)));
+            res.on('end', () => {
+                let parsed = null;
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    // Handled by the shape check below.
+                }
+                const rec = typeof parsed === 'object' && parsed !== null ? parsed : {};
+                if (res.statusCode === 200) {
+                    resolve(rec);
+                }
+                else {
+                    const detail = typeof rec['error'] === 'string' ? rec['error'] : `control server answered ${res.statusCode ?? '?'}`;
+                    reject(new ControlCallError(`obsrv control ${command}: ${detail}`, res.statusCode));
+                }
+            });
+        });
+        req.on('timeout', () => req.destroy(new Error(`obsrv control ${command} timed out after ${timeoutMs} ms`)));
+        req.on('error', reject);
+        req.end(body);
+    });
+}
+/**
+ * Finds a running, control-enabled Obsrv app: discovery file present, sanely
+ * permissioned (no group/other access on POSIX — the app writes it 0600) and
+ * well-formed, and a tokened `status` answered within `timeoutMs`. Null on
+ * any failure — every path where the app cannot be *proven* live is "not
+ * reachable", so auto mode falls back to headless instead of erroring.
+ */
+async function discoverControl(timeoutMs = 500) {
+    const file = controlFilePath();
+    let raw;
+    try {
+        const s = await (0, promises_1.stat)(file);
+        if (!(0, control_1.controlFileModeOk)(s.mode, process.platform))
+            return null;
+        raw = await (0, promises_1.readFile)(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const info = (0, control_1.parseControlFile)(raw);
+    if (!info)
+        return null;
+    try {
+        const status = (0, control_1.parseControlStatus)(await controlCall(info, 'status', {}, timeoutMs));
+        return status ? { info, status } : null;
+    }
+    catch {
+        return null;
+    }
+}

package/out/mcp/lib.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ALLOWED_URL_SCHEMES = exports.STDERR_TAIL_CHARS = exports.MAX_INLINE_IMAGE_BYTES = exports.UsageError = void 0;
+exports.APP_NOT_REACHABLE = exports.urlSchemeError = exports.ALLOWED_URL_SCHEMES = exports.STDERR_TAIL_CHARS = exports.MAX_INLINE_IMAGE_BYTES = exports.UsageError = void 0;
 exports.buildSnapArgs = buildSnapArgs;
 exports.buildDiffArgs = buildDiffArgs;
 exports.shouldInlineImage = shouldInlineImage;
 exports.killBudgetMs = killBudgetMs;
 exports.stderrTail = stderrTail;
-exports.urlSchemeError = urlSchemeError;
+exports.planSnapPath = planSnapPath;
 exports.extractTrailingJson = extractTrailingJson;
 exports.listCatalog = listCatalog;
 const presets_1 = require("../shared/presets");
@@ -97,30 +97,51 @@ function stderrTail(stderr, max = exports.STDERR_TAIL_CHARS) {
     const trimmed = stderr.trim();
     return trimmed.length <= max ? trimmed : `…${trimmed.slice(-max)}`;
 }
-/** Schemes a tool call may hand to the CLI. */
-exports.ALLOWED_URL_SCHEMES = ['http:', 'https:', 'file:'];
+// The scheme allowlist lives in shared/url.ts so the agent-control server
+// applies the identical check; re-exported so existing importers (and their
+// unit tests) keep their path.
+var url_1 = require("../shared/url");
+Object.defineProperty(exports, "ALLOWED_URL_SCHEMES", { enumerable: true, get: function () { return url_1.ALLOWED_URL_SCHEMES; } });
+Object.defineProperty(exports, "urlSchemeError", { enumerable: true, get: function () { return url_1.urlSchemeError; } });
+exports.APP_NOT_REACHABLE = 'The Obsrv app is not reachable. Open the Obsrv desktop app and enable "Agent control" in the toolbar ' +
+    '(or pass mode: "headless" to render without it).';
 /**
- * Rejects URLs whose explicit scheme is outside the allowlist (javascript:,
- * data:, chrome:, …) with an actionable message, or returns null when the URL
- * may proceed. Scheme-relative (`//host`), bare-host (`example.com/page`) and
- * host:port (`localhost:5173`) forms pass — they normalise to http(s)
- * downstream.
+ * Decides whether an `obsrv_snap` call drives the visible app or renders
+ * headlessly (spec §14 "Live drive"), given whether a control-enabled app
+ * answered discovery. Documented calls, exercised in tests/unit/mcpLib.test.ts:
+ *
+ * - custom dims (width/height/dsf/diagonal) always render headlessly — the
+ *   live path drives the app's preset table only — with a note, even under
+ *   an explicit `mode: 'live'`.
+ * - `fullPage` always renders headlessly (the visible window cannot show a
+ *   full page), with a note.
+ * - `waitMs` is honoured headlessly; on the live path it is ignored with a
+ *   note (the live capture settles on the app's own committed navigation).
+ * - `mode: 'live'` with no reachable app is an error, never a silent
+ *   headless fallback — the caller asked to watch.
  */
-function urlSchemeError(url) {
-    const trimmed = url.trim();
-    const match = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed);
-    if (!match)
-        return null; // bare host or scheme-relative
-    const scheme = `${match[1].toLowerCase()}:`;
-    if (exports.ALLOWED_URL_SCHEMES.includes(scheme))
-        return null;
-    // `localhost:5173`-style host:port, not a scheme: the "scheme" is followed
-    // by a bare port number.
-    if (/^[a-z0-9.-]+:\d+(\/|$)/i.test(trimmed))
-        return null;
-    return (`unsupported URL scheme "${scheme}" — obsrv renders ` +
-        `${exports.ALLOWED_URL_SCHEMES.map(s => `${s}//`).join(', ')} URLs only ` +
-        `(bare hosts like example.com also work; they normalise to http(s)).`);
+function planSnapPath(input, mode, liveReachable) {
+    if (mode === 'headless')
+        return { path: 'headless', notes: [] };
+    if (!liveReachable) {
+        if (mode === 'live')
+            return { error: exports.APP_NOT_REACHABLE };
+        return { path: 'headless', notes: [] };
+    }
+    const notes = [];
+    const custom = input.width !== undefined ||
+        input.height !== undefined ||
+        input.deviceScaleFactor !== undefined ||
+        input.diagonalInches !== undefined;
+    if (custom)
+        notes.push('custom dimensions are headless-only (live mode drives the preset table); rendered headlessly.');
+    if (input.fullPage)
+        notes.push('fullPage is headless-only; rendered headlessly instead of driving the app.');
+    if (notes.length > 0)
+        return { path: 'headless', notes };
+    if (input.waitMs !== undefined)
+        notes.push('waitMs is headless-only and was ignored in live mode.');
+    return { path: 'live', notes };
 }
 /**
  * Parses the CLI's machine output: the trailing JSON object on stdout.