getobsrv 0.4.1 → 0.5.0

package/README.md

@@ -83,8 +83,10 @@ raster density — the PNG comes back as an inline image up to 1.5 MiB),
 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.
+see it (plus `obsrv_drive` to flip URL/preset/profile directly). Agents can
+also scroll, click, pan and highlight while you watch — a drive session works
+as a guided demo. With no app running, everything falls back to the headless
+render automatically.
 
 Build first, then register:
 
@@ -119,7 +121,16 @@ xattr -cr /Applications/Obsrv.app
 
 ## Distribution
 
-Obsrv will publish to npm as **`getobsrv`** (the installed commands remain `obsrv`
+Publish via a packed tarball, never bare `npm publish`: `npm publish` snapshots
+package.json before lifecycle hooks run, which silently skips the prepack
+electron dev→prod dependency swap (this shipped a broken 0.4.0). The flow is:
+
+```bash
+npm run release:pack
+npm publish ./getobsrv-<version>.tgz
+```
+
+Obsrv publishes to npm as **`getobsrv`** (the installed commands remain `obsrv`
 and `obsrv-mcp`; the app's display name remains Obsrv). The bare `obsrv` npm name
 belongs to an unrelated package.
 

package/out/main/index.js

@@ -68,51 +68,11 @@ 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;
+const isRecord$1 = (v) => typeof v === "object" && v !== null;
 function parseRect(raw) {
-  if (!isRecord(raw)) return null;
+  if (!isRecord$1(raw)) return null;
   const { x, y, width, height } = raw;
   if (!isFiniteNumber(x) || !isFiniteNumber(y) || !isFiniteNumber(width) || !isFiniteNumber(height)) return null;
   const r = { x: Math.round(x), y: Math.round(y), width: Math.round(width), height: Math.round(height) };
@@ -134,7 +94,7 @@ function parseModifiers(raw) {
   return raw.filter((m) => typeof m === "string" && MODIFIERS.has(m));
 }
 function parseInputEvent(raw) {
-  if (!isRecord(raw)) return null;
+  if (!isRecord$1(raw)) return null;
   const modifiers = parseModifiers(raw.modifiers);
   switch (raw.type) {
     case "mouseDown":
@@ -167,7 +127,7 @@ function parseDeviceScaleFactor(raw) {
   return raw;
 }
 function parseSettings(raw) {
-  if (!isRecord(raw)) return null;
+  if (!isRecord$1(raw)) return null;
   const { hostDiagonalInches, hostNits } = raw;
   if (!isFiniteNumber(hostDiagonalInches) || hostDiagonalInches <= 0) return null;
   if (!isFiniteNumber(hostNits) || hostNits <= 0) return null;
@@ -180,20 +140,104 @@ function parseMode(raw) {
 }
 const MAX_UI_ID = 64;
 function parseUiState(raw) {
-  if (!isRecord(raw)) return null;
+  if (!isRecord$1(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 };
+  return { presetId, profileId, viewMode, mode, targetBounds: parseRect(raw.targetBounds) };
 }
 function parseScrollPos(raw) {
-  if (!isRecord(raw)) return null;
+  if (!isRecord$1(raw)) return null;
   const { x, y } = raw;
   if (!isFiniteNumber(x) || !isFiniteNumber(y) || x < 0 || y < 0) return null;
   return { x, y };
 }
+const CONTROL_FILE_NAME = "control.json";
+const CONTROL_TOKEN_BYTES = 32;
+const CONTROL_COMMANDS = [
+  "status",
+  "navigate",
+  "setPreset",
+  "setProfile",
+  "setViewMode",
+  "captureVisible",
+  // v0.5 drive controls (spec §14 "Drive controls").
+  "scroll",
+  "panTo",
+  "click",
+  "highlight",
+  "back",
+  "forward",
+  "reload",
+  "setPixelExact",
+  "captureTarget",
+  "focusWindow"
+];
+function isControlCommand(v) {
+  return typeof v === "string" && CONTROL_COMMANDS.includes(v);
+}
+const isRecord = (v) => typeof v === "object" && v !== null;
+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' }`;
+}
+function pixelExactApplyError(v) {
+  return typeof v === "boolean" ? null : "setPixelExact payload must be { on: boolean }";
+}
+function parseClick(raw, viewport) {
+  const shape = "click payload must be { x, y, button? } with finite CSS-pixel coordinates";
+  if (!isRecord(raw)) return shape;
+  const { x, y } = raw;
+  if (typeof x !== "number" || !Number.isFinite(x) || typeof y !== "number" || !Number.isFinite(y)) return shape;
+  if (x < 0 || y < 0 || x >= viewport.width || y >= viewport.height) {
+    return `click (${x}, ${y}) is outside the current CSS viewport ${viewport.width}x${viewport.height}`;
+  }
+  const button = raw.button ?? "left";
+  if (button !== "left" && button !== "middle" && button !== "right") {
+    return "click button must be left, middle or right";
+  }
+  return { x, y, button };
+}
+const HIGHLIGHT_DURATION_DEFAULT_MS = 2e3;
+const HIGHLIGHT_DURATION_MIN_MS = 250;
+const HIGHLIGHT_DURATION_MAX_MS = 1e4;
+function parseHighlight(raw) {
+  const rect = parseRect(raw);
+  if (!rect) return "highlight payload must be { x, y, width, height, durationMs? } with finite, non-negative target-pixel bounds";
+  if (rect.width < 1 || rect.height < 1) return "highlight rect must be at least 1x1 target pixels";
+  const d = raw.durationMs;
+  if (d === void 0) return { ...rect, durationMs: HIGHLIGHT_DURATION_DEFAULT_MS };
+  if (typeof d !== "number" || !Number.isFinite(d)) return "highlight durationMs must be a finite number of milliseconds";
+  return {
+    ...rect,
+    durationMs: Math.min(Math.max(Math.round(d), HIGHLIGHT_DURATION_MIN_MS), HIGHLIGHT_DURATION_MAX_MS)
+  };
+}
 const isPositive = (v) => typeof v === "number" && Number.isFinite(v) && v > 0;
 function loadSettings(file) {
   try {
@@ -325,6 +369,52 @@ class ControlServer {
         const capture = await this.deps.captureVisible();
         return reply(200, { ok: true, ...capture });
       }
+      case "captureTarget": {
+        const capture = await this.deps.captureTarget();
+        return reply(200, { ok: true, ...capture });
+      }
+      case "scroll": {
+        const pos = parseScrollPos(payload);
+        if (!pos) return reply(400, { error: "scroll payload must be { x, y } with finite, non-negative CSS-pixel offsets" });
+        this.deps.scroll(pos);
+        return reply(200, { ok: true });
+      }
+      case "panTo": {
+        const pos = parseScrollPos(payload);
+        if (!pos) return reply(400, { error: "panTo payload must be { x, y } with finite, non-negative target-pixel coordinates" });
+        this.deps.apply({ panTo: pos });
+        return reply(200, { ok: true });
+      }
+      case "click": {
+        const click = parseClick(payload, this.deps.viewport());
+        if (typeof click === "string") return reply(400, { error: click });
+        this.deps.click(click);
+        return reply(200, { ok: true });
+      }
+      case "highlight": {
+        const highlight = parseHighlight(payload);
+        if (typeof highlight === "string") return reply(400, { error: highlight });
+        this.deps.apply({ highlight });
+        return reply(200, { ok: true });
+      }
+      case "back":
+        this.deps.back();
+        return reply(200, { ok: true });
+      case "forward":
+        this.deps.forward();
+        return reply(200, { ok: true });
+      case "reload":
+        this.deps.reload();
+        return reply(200, { ok: true });
+      case "setPixelExact": {
+        const err = pixelExactApplyError(payload.on);
+        if (err) return reply(400, { error: err });
+        this.deps.apply({ pixelExact: payload.on });
+        return reply(200, { ok: true });
+      }
+      case "focusWindow":
+        this.deps.focusWindow();
+        return reply(200, { ok: true });
     }
   }
   /**
@@ -399,18 +489,23 @@ function registerIpc(ctx) {
     assertRenderer(e);
     return navigateBoth(url);
   });
-  electron.ipcMain.on(IPC.reload, (e) => {
-    if (!fromRenderer(e)) return;
+  const reloadBoth = () => {
     native.reload();
     target.reload();
+  };
+  const goBack = () => native.back();
+  const goForward = () => native.forward();
+  electron.ipcMain.on(IPC.reload, (e) => {
+    if (!fromRenderer(e)) return;
+    reloadBoth();
   });
   electron.ipcMain.on(IPC.back, (e) => {
     if (!fromRenderer(e)) return;
-    native.back();
+    goBack();
   });
   electron.ipcMain.on(IPC.forward, (e) => {
     if (!fromRenderer(e)) return;
-    native.forward();
+    goForward();
   });
   electron.ipcMain.handle(IPC.setViewport, (e, width, height, rawDsf) => {
     assertRenderer(e);
@@ -488,6 +583,7 @@ function registerIpc(ctx) {
     if (s.agentControl !== wasEnabled) applyAgentControl(s.agentControl);
   });
   const uiState = { presetId: "1080p-24", profileId: "reference", viewMode: "1:1", mode: "url" };
+  let targetBounds = null;
   const MAX_PENDING_APPLIES = 32;
   let rendererReported = false;
   let warnedPendingOverflow = false;
@@ -496,7 +592,9 @@ function registerIpc(ctx) {
     if (!fromRenderer(e)) return;
     const s = parseUiState(raw);
     if (!s) return;
-    Object.assign(uiState, s);
+    const { targetBounds: bounds, ...state } = s;
+    Object.assign(uiState, state);
+    targetBounds = bounds ?? null;
     if (!rendererReported) {
       rendererReported = true;
       for (const patch of pendingApplies.splice(0)) {
@@ -542,6 +640,42 @@ function registerIpc(ctx) {
       const size = image.getSize();
       return { data: image.toPNG().toString("base64"), width: size.width, height: size.height };
     },
+    captureTarget: async () => {
+      const bounds = targetBounds;
+      const known = bounds !== null && bounds.width >= 1 && bounds.height >= 1;
+      const image = await win.webContents.capturePage(known ? bounds : void 0);
+      const size = image.getSize();
+      return {
+        data: image.toPNG().toString("base64"),
+        width: size.width,
+        height: size.height,
+        warnings: known ? [] : ["the renderer has not reported the target pane bounds yet; captured the full window instead"]
+      };
+    },
+    viewport: () => target.getViewport(),
+    scroll: (pos) => {
+      for (const wc of [native.webContents, target.webContents]) {
+        if (!wc.isDestroyed()) wc.send(IPC.applyScroll, pos);
+      }
+    },
+    click: (c) => {
+      const down = parseInputEvent({ type: "mouseDown", x: c.x, y: c.y, button: c.button, clickCount: 1 });
+      const up = parseInputEvent({ type: "mouseUp", x: c.x, y: c.y, button: c.button, clickCount: 1 });
+      if (!down || !up) return;
+      try {
+        target.sendInput(down);
+        target.sendInput(up);
+      } catch {
+      }
+    },
+    back: goBack,
+    forward: goForward,
+    reload: reloadBoth,
+    focusWindow: () => {
+      if (win.isDestroyed()) return;
+      win.show();
+      win.focus();
+    },
     activity: () => {
       if (!win.isDestroyed()) win.webContents.send(IPC.agentActivity);
     }

package/out/mcp/lib.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.APP_NOT_REACHABLE = exports.urlSchemeError = exports.ALLOWED_URL_SCHEMES = exports.STDERR_TAIL_CHARS = exports.MAX_INLINE_IMAGE_BYTES = exports.UsageError = void 0;
+exports.PANE_CAPTURE_HEADLESS_NOTE = 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;
@@ -105,6 +105,7 @@ Object.defineProperty(exports, "ALLOWED_URL_SCHEMES", { enumerable: true, get: f
 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).';
+exports.PANE_CAPTURE_HEADLESS_NOTE = "capture: 'pane' applies to live mode only; the headless render is the page raster itself, so the option was ignored.";
 /**
  * Decides whether an `obsrv_snap` call drives the visible app or renders
  * headlessly (spec §14 "Live drive"), given whether a control-enabled app
@@ -117,16 +118,19 @@ exports.APP_NOT_REACHABLE = 'The Obsrv app is not reachable. Open the Obsrv desk
  *   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).
+ * - `capture: 'pane'` shapes the live capture only; any headless outcome
+ *   notes that it was ignored.
  * - `mode: 'live'` with no reachable app is an error, never a silent
  *   headless fallback — the caller asked to watch.
  */
 function planSnapPath(input, mode, liveReachable) {
+    const paneNote = input.capture === 'pane' ? [exports.PANE_CAPTURE_HEADLESS_NOTE] : [];
     if (mode === 'headless')
-        return { path: 'headless', notes: [] };
+        return { path: 'headless', notes: paneNote };
     if (!liveReachable) {
         if (mode === 'live')
             return { error: exports.APP_NOT_REACHABLE };
-        return { path: 'headless', notes: [] };
+        return { path: 'headless', notes: paneNote };
     }
     const notes = [];
     const custom = input.width !== undefined ||
@@ -138,7 +142,7 @@ function planSnapPath(input, mode, liveReachable) {
     if (input.fullPage)
         notes.push('fullPage is headless-only; rendered headlessly instead of driving the app.');
     if (notes.length > 0)
-        return { path: 'headless', notes };
+        return { path: 'headless', notes: [...notes, ...paneNote] };
     if (input.waitMs !== undefined)
         notes.push('waitMs is headless-only and was ignored in live mode.');
     return { path: 'live', notes };

package/out/mcp/server.js

@@ -123,6 +123,11 @@ const snapInputShape = {
         .optional()
         .describe('auto (default): drive the visible Obsrv app when it is open with Agent control on, else render headlessly. ' +
         'live: require the app (error if unreachable). headless: never touch the app.'),
+    capture: zod_1.z
+        .enum(['window', 'pane'])
+        .optional()
+        .describe("Live mode only: what the returned PNG shows — 'window' (default) is the whole app window, 'pane' is just " +
+        'the target pane (its footer readout included). Ignored (with a note) when the render is headless.'),
 };
 const snapOutputShape = {
     mode: zod_1.z
@@ -143,8 +148,16 @@ const snapOutputShape = {
     presetId: zod_1.z.string().optional().describe('Live only: the screen preset selected in the app.'),
     profileId: zod_1.z.string().optional().describe('Live only: the panel profile selected in the app.'),
     viewMode: zod_1.z.string().optional().describe("Live only: the app's target-pane view (1:1 or fit)."),
-    width: zod_1.z.number().optional().describe('Live only: captured app-window width in px.'),
-    height: zod_1.z.number().optional().describe('Live only: captured app-window height in px.'),
+    width: zod_1.z
+        .number()
+        .optional()
+        .describe('Live only: captured width in device-independent px (the app window, or the target pane under capture: ' +
+        '"pane"); the PNG raster is this times the display scale.'),
+    height: zod_1.z
+        .number()
+        .optional()
+        .describe('Live only: captured height in device-independent px (the app window, or the target pane under capture: ' +
+        '"pane"); the PNG raster is this times the display scale.'),
 };
 const diffInputShape = {
     url: urlField,
@@ -214,6 +227,34 @@ const driveInputShape = {
     preset: zod_1.z.enum(PRESET_IDS).optional().describe('Apply this screen preset, exactly as clicking the toolbar would.'),
     profile: zod_1.z.enum(PROFILE_IDS).optional().describe('Apply this panel profile in the app.'),
     viewMode: zod_1.z.enum(['1:1', 'fit']).optional().describe("Switch the app's target pane between 1:1 (actual size) and fit."),
+    pixelExact: zod_1.z.boolean().optional().describe("Toggle the toolbar's pixel-exact checkbox (pins the magnification to the host scale)."),
+    focus: zod_1.z.boolean().optional().describe('true: bring the Obsrv window to the front first, so the user sees what follows.'),
+    reload: zod_1.z.boolean().optional().describe('true: reload both panes (the same action as the toolbar reload).'),
+    back: zod_1.z.boolean().optional().describe('true: history back (native pane history; the target mirrors the committed page).'),
+    forward: zod_1.z.boolean().optional().describe('true: history forward (native pane history; the target mirrors it).'),
+    scroll: zod_1.z
+        .object({ x: zod_1.z.number().min(0), y: zod_1.z.number().min(0) })
+        .optional()
+        .describe('Scroll both panes to this absolute page offset in CSS px.'),
+    panTo: zod_1.z
+        .object({ x: zod_1.z.number().min(0), y: zod_1.z.number().min(0) })
+        .optional()
+        .describe("Centre this target-pane pixel (device px of the render) in the pane's 1:1 view; from fit this jumps to 1:1 there."),
+    click: zod_1.z
+        .object({ x: zod_1.z.number().min(0), y: zod_1.z.number().min(0) })
+        .optional()
+        .describe('Left-click the live page at these CSS-viewport coordinates (may navigate; refused outside the viewport).'),
+    highlight: zod_1.z
+        .object({
+        x: zod_1.z.number().min(0),
+        y: zod_1.z.number().min(0),
+        width: zod_1.z.number().min(1),
+        height: zod_1.z.number().min(1),
+        durationMs: zod_1.z.number().optional(),
+    })
+        .optional()
+        .describe('Draw a temporary neutral marker over this target-pixel rect in the pane (durationMs default 2000, clamped ' +
+        '250-10000). A new highlight replaces the previous one.'),
 };
 const driveOutputShape = {
     version: zod_1.z.string().describe('The running app version.'),
@@ -232,6 +273,13 @@ const LIVE_APPLY_TIMEOUT_MS = 5_000;
 const LIVE_CAPTURE_TIMEOUT_MS = 30_000;
 /** How long a live snap waits for `status.url` to reflect the navigation. */
 const LIVE_SETTLE_MS = 5_000;
+/**
+ * How long an `obsrv_drive` click waits for a navigation it may have caused,
+ * so the returned status reflects it. Deliberately short: most clicks do not
+ * navigate, and every non-navigating one pays this in full.
+ */
+const CLICK_SETTLE_MS = 2_000;
+const CLICK_SETTLE_POLL_MS = 250;
 function liveFailure(e) {
     const msg = e instanceof Error ? e.message : String(e);
     return (`${msg}. If the Obsrv app was closed or Agent control was toggled off mid-call, ` +
@@ -287,9 +335,13 @@ async function liveSnap(app, input, notes) {
     // (and any preset resize) a frame or two after the store confirms, and a
     // capture racing that would show a half-applied flip.
     await sleep(300);
+    // `capture: 'pane'` crops to the target pane; the command answers with the
+    // same { data, width, height } shape plus its own warnings (e.g. the
+    // pre-mount full-window fallback), which join the tool's.
     let capture;
     try {
-        capture = await (0, control_2.controlCall)(info, 'captureVisible', {}, LIVE_CAPTURE_TIMEOUT_MS);
+        const command = input.capture === 'pane' ? 'captureTarget' : 'captureVisible';
+        capture = await (0, control_2.controlCall)(info, command, {}, LIVE_CAPTURE_TIMEOUT_MS);
     }
     catch (e) {
         return toolError(liveFailure(e));
@@ -298,6 +350,11 @@ async function liveSnap(app, input, notes) {
     if (typeof data !== 'string' || typeof width !== 'number' || typeof height !== 'number') {
         return toolError('the control server returned a malformed capture');
     }
+    if (Array.isArray(capture['warnings'])) {
+        for (const w of capture['warnings'])
+            if (typeof w === 'string')
+                warnings.push(w);
+    }
     const dir = await (0, promises_1.mkdtemp)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'obsrv-mcp-'));
     const pngPath = (0, node_path_1.join)(dir, 'live.png');
     await (0, promises_1.writeFile)(pngPath, Buffer.from(data, 'base64'));
@@ -336,7 +393,8 @@ server.registerTool('obsrv_snap', {
         `Live drive: when the Obsrv desktop app is open with its "Agent control" toolbar toggle on, \`mode: "auto"\` ` +
         `(the default) drives the *visible* app instead — the user watches the URL load and the preset flip, and the ` +
         `returned PNG is the app window as they see it (\`mode: "live"\` in the result; \`mode: "headless"\` ` +
-        `otherwise). Custom width/height and \`fullPage\` always render headlessly (with a note); \`waitMs\` is ` +
+        `otherwise). \`capture: "pane"\` crops a live capture to just the target pane (headless renders ignore it ` +
+        `with a note). Custom width/height and \`fullPage\` always render headlessly (with a note); \`waitMs\` is ` +
         `ignored in live mode. \`mode: "live"\` errors when the app is not reachable; \`mode: "headless"\` never ` +
         `touches it. Note: although this tool is annotated read-only (it renders and captures), a live snap steers ` +
         `the open app window — navigating it and flipping its preset in front of the user — as its means of ` +
@@ -362,6 +420,9 @@ server.registerTool('obsrv_snap', {
             return liveSnap(live, input, plan.notes);
         liveNotes = plan.notes;
     }
+    else if (input.capture === 'pane') {
+        liveNotes = [lib_1.PANE_CAPTURE_HEADLESS_NOTE];
+    }
     const dir = await (0, promises_1.mkdtemp)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'obsrv-mcp-'));
     const pngPath = (0, node_path_1.join)(dir, 'snap.png');
     let args;
@@ -436,12 +497,20 @@ server.registerTool('obsrv_diff', {
 server.registerTool('obsrv_drive', {
     title: 'Drive the visible Obsrv app',
     description: `Drive the Obsrv desktop app the user is looking at: navigate it to a URL, apply a screen preset, a panel ` +
-        `profile, or the target pane's 1:1/fit view — each applied exactly as clicking the toolbar would, while the ` +
-        `user watches. Applies whichever inputs are given (none = just read the current state) and returns the ` +
-        `resulting status: app version, the URL showing, and the selected preset/profile/view.\n\n` +
+        `profile, the target pane's 1:1/fit view or pixel-exact toggle — each exactly as clicking the toolbar would ` +
+        `— and steer the session like a guided demo: focus the window, step history (back/forward/reload), scroll ` +
+        `both panes, pan the target pane to a pixel, click the live page, and highlight a rect with a temporary ` +
+        `neutral marker, all while the user watches.\n\n` +
+        `Only the supplied inputs run (none = just read the current state), in this fixed order: focus → url → ` +
+        `preset → profile → viewMode → pixelExact → reload → back → forward → scroll → panTo → click → highlight. ` +
+        `The result is the final status: app version, the URL showing, and the selected preset/profile/view. A ` +
+        `click that navigates is reflected in that status — the call waits briefly (up to 2 s) for the commit. ` +
+        `Coordinates: click takes CSS-viewport px of the page (the valid range is 0 up to but not including the ` +
+        `viewport size); panTo and highlight take target-pane pixels (device px of the render — identical to CSS px ` +
+        `on 1x presets); scroll takes page CSS px.\n\n` +
         `Requires the app to be open with its "Agent control" toolbar toggle on; errors otherwise. This tool ` +
-        `mutates visible app state (it changes what the user's window shows) but renders nothing itself — use ` +
-        `obsrv_snap for a capture.`,
+        `mutates visible app state (it changes what the user's window shows, and a click can act on the live page) ` +
+        `but renders nothing itself — use obsrv_snap for a capture.`,
     inputSchema: driveInputShape,
     outputSchema: driveOutputShape,
     // Honest annotation: this changes what the user's window is showing.
@@ -456,6 +525,10 @@ server.registerTool('obsrv_drive', {
     if (!live)
         return toolError(lib_1.APP_NOT_REACHABLE);
     try {
+        // The documented execution order: window attention first, then what is
+        // showing, then how it is shown, then the in-page steering.
+        if (input.focus)
+            await (0, control_2.controlCall)(live.info, 'focusWindow', {}, LIVE_APPLY_TIMEOUT_MS);
         if (input.url !== undefined) {
             await (0, control_2.controlCall)(live.info, 'navigate', { url: input.url.trim() }, args_1.DEFAULT_TIMEOUT_MS + 10_000);
         }
@@ -466,6 +539,38 @@ server.registerTool('obsrv_drive', {
         if (input.viewMode !== undefined) {
             await (0, control_2.controlCall)(live.info, 'setViewMode', { mode: input.viewMode }, LIVE_APPLY_TIMEOUT_MS);
         }
+        if (input.pixelExact !== undefined) {
+            await (0, control_2.controlCall)(live.info, 'setPixelExact', { on: input.pixelExact }, LIVE_APPLY_TIMEOUT_MS);
+        }
+        if (input.reload)
+            await (0, control_2.controlCall)(live.info, 'reload', {}, LIVE_APPLY_TIMEOUT_MS);
+        if (input.back)
+            await (0, control_2.controlCall)(live.info, 'back', {}, LIVE_APPLY_TIMEOUT_MS);
+        if (input.forward)
+            await (0, control_2.controlCall)(live.info, 'forward', {}, LIVE_APPLY_TIMEOUT_MS);
+        if (input.scroll !== undefined)
+            await (0, control_2.controlCall)(live.info, 'scroll', input.scroll, LIVE_APPLY_TIMEOUT_MS);
+        if (input.panTo !== undefined)
+            await (0, control_2.controlCall)(live.info, 'panTo', input.panTo, LIVE_APPLY_TIMEOUT_MS);
+        if (input.click !== undefined) {
+            // A click may navigate. Note the URL first, then wait — bounded and
+            // short, the same settle idea as a live snap — for the status to move
+            // off it, so the returned status reflects what the click did. A click
+            // that navigates nowhere simply rides out the short deadline.
+            const before = (0, control_1.parseControlStatus)(await (0, control_2.controlCall)(live.info, 'status', {}, LIVE_STATUS_TIMEOUT_MS))?.url ?? '';
+            await (0, control_2.controlCall)(live.info, 'click', input.click, LIVE_APPLY_TIMEOUT_MS);
+            const deadline = Date.now() + CLICK_SETTLE_MS;
+            for (;;) {
+                const s = (0, control_1.parseControlStatus)(await (0, control_2.controlCall)(live.info, 'status', {}, LIVE_STATUS_TIMEOUT_MS));
+                if (s && s.url !== before && s.url !== 'about:blank')
+                    break;
+                if (Date.now() >= deadline)
+                    break;
+                await sleep(CLICK_SETTLE_POLL_MS);
+            }
+        }
+        if (input.highlight !== undefined)
+            await (0, control_2.controlCall)(live.info, 'highlight', input.highlight, LIVE_APPLY_TIMEOUT_MS);
         const status = (0, control_1.parseControlStatus)(await (0, control_2.controlCall)(live.info, 'status', {}, LIVE_STATUS_TIMEOUT_MS));
         if (!status)
             return toolError('the control server returned a malformed status');

package/out/renderer/assets/{index-FtoKShe_.css → index-CHF-G97L.css}

@@ -377,6 +377,9 @@ html, body, #root { margin: 0; height: 100%; background: var(--chrome-0); color:
   position: fixed;
   right: 16px;
   bottom: 16px;
+  /* Above the stall notice (2) and the agent highlight (1): these are the
+     app talking to the user and must not sit under an overlay in the pane. */
+  z-index: 3;
   padding: 8px 12px;
   background: var(--chrome-2);
   color: var(--text-0);
@@ -393,12 +396,28 @@ html, body, #root { margin: 0; height: 100%; background: var(--chrome-0); color:
    `left: 0` holds while a wide canvas is scrolled horizontally. The fill is a
    neutral grey: only the rule under it is red, so the one chromatic thing on
    screen is the error itself. */
-.target-wrap { min-width: min-content; }
+/* position: relative anchors the agent highlight to the canvas origin. */
+.target-wrap { min-width: min-content; position: relative; }
+
+/* Agent-control highlight: a temporary neutral marker over the target-pixel
+   rect an agent is pointing at. Style-spec law: no hue — a light outline with
+   a dark dashed inner edge reads on any page without tinting it — and no
+   pointer interception over the pixels under inspection. */
+.agent-highlight {
+  position: absolute;
+  z-index: 1;
+  pointer-events: none;
+  outline: 2px solid var(--text-0);
+  border: 1px dashed var(--chrome-0);
+  box-sizing: border-box;
+}
 .stall {
   position: sticky;
   top: 0;
   left: 0;
-  z-index: 1;
+  /* Above the agent highlight (z-index 1): an error notice outranks a
+     demo marker. */
+  z-index: 2;
   display: flex;
   align-items: center;
   gap: 10px;

package/out/renderer/assets/{index-P496vEhv.js → index-DyCD4ih_.js}

@@ -12777,11 +12777,17 @@ const useStore = create()((set) => ({
   surround: "graphite",
   viewMode: "1:1",
   fitScale: null,
+  agentPan: null,
+  agentHighlight: null,
   // Does not clear `error`: a failed load navigates to Chromium's error page,
   // so clearing here would wipe the toolbar badge the moment it appeared.
-  setUrl: (url) => set({ url }),
-  setPreset: (presetId) => set({ presetId }),
-  setCustom: (c) => set((s) => ({ custom: { ...s.custom, ...c }, presetId: CUSTOM_PRESET_ID })),
+  // Does clear the agent highlight: it marked pixels of the page that was
+  // showing, and a committed navigation (a reload included) replaces them.
+  setUrl: (url) => set({ url, agentHighlight: null }),
+  // A screen change re-rasters the target, so a highlight's target-pixel rect
+  // no longer marks what it marked; the same for the custom fields below.
+  setPreset: (presetId) => set({ presetId, agentHighlight: null }),
+  setCustom: (c) => set((s) => ({ custom: { ...s.custom, ...c }, presetId: CUSTOM_PRESET_ID, agentHighlight: null })),
   setPixelExact: (pixelExact) => set({ pixelExact }),
   // Picking a profile drops any hand-tuned slider values.
   setProfile: (profileId) => set({ profileId, profileOverride: null }),
@@ -12797,9 +12803,15 @@ const useStore = create()((set) => ({
   setSurround: (surround) => set({ surround }),
   setViewMode: (viewMode) => set({ viewMode }),
   setFitScale: (fitScale2) => set({ fitScale: fitScale2 }),
+  requestAgentPan: (p) => set((s) => ({ agentPan: { ...p, seq: (s.agentPan?.seq ?? 0) + 1 } })),
+  clearAgentPan: () => set({ agentPan: null }),
+  showAgentHighlight: (h) => set((s) => ({ agentHighlight: { ...h, seq: (s.agentHighlight?.seq ?? 0) + 1 } })),
+  clearAgentHighlight: (seq) => set((s) => seq === void 0 || s.agentHighlight?.seq === seq ? { agentHighlight: null } : {}),
   // Spec §7: leaving image mode restores the URL that was showing before.
+  // Either direction swaps what the target pane shows, so a highlight over
+  // the old content is dropped with it.
   setMode: (mode) => set(
-    (s) => mode === s.mode ? {} : mode === "image" ? { mode, lastUrl: s.url } : { mode, url: s.lastUrl, image: null }
+    (s) => mode === s.mode ? {} : mode === "image" ? { mode, lastUrl: s.url, agentHighlight: null } : { mode, url: s.lastUrl, image: null, agentHighlight: null }
   )
 }));
 function selectScreen(s) {
@@ -13797,17 +13809,30 @@ function computeFitScale(paneW, paneH, dpr, vpW, vpH, oneToOneScale) {
   if (!usable(paneW, paneH, dpr, vpW, vpH, oneToOneScale)) return 1;
   return Math.min(paneW * dpr / vpW, paneH * dpr / vpH, oneToOneScale);
 }
-function jumpScroll(clickX, clickY, dpr, fitScale2, oneToOneScale, paneW, paneH, vpW, vpH) {
-  if (!usable(dpr, fitScale2, oneToOneScale, paneW, paneH, vpW, vpH) || !Number.isFinite(clickX) || !Number.isFinite(clickY)) {
+function centreScroll(x, y, dpr, oneToOneScale, paneW, paneH, vpW, vpH) {
+  if (!usable(dpr, oneToOneScale, paneW, paneH, vpW, vpH) || !Number.isFinite(x) || !Number.isFinite(y)) {
     return { left: 0, top: 0 };
   }
-  const axis = (click, pane, vp) => {
-    const target = click * dpr / fitScale2;
+  const axis = (target, pane, vp) => {
     const want = target * oneToOneScale / dpr - pane / 2;
     const max = vp * oneToOneScale / dpr - pane;
     return Math.min(Math.max(want, 0), Math.max(max, 0));
   };
-  return { left: axis(clickX, paneW, vpW), top: axis(clickY, paneH, vpH) };
+  return { left: axis(x, paneW, vpW), top: axis(y, paneH, vpH) };
+}
+function jumpScroll(clickX, clickY, dpr, fitScale2, oneToOneScale, paneW, paneH, vpW, vpH) {
+  if (!usable(fitScale2) || !Number.isFinite(clickX) || !Number.isFinite(clickY)) return { left: 0, top: 0 };
+  if (!usable(dpr)) return { left: 0, top: 0 };
+  return centreScroll(
+    clickX * dpr / fitScale2,
+    clickY * dpr / fitScale2,
+    dpr,
+    oneToOneScale,
+    paneW,
+    paneH,
+    vpW,
+    vpH
+  );
 }
 const STALL_MS = 2e3;
 function TargetCanvas({ onFatal, imageFrame }) {
@@ -14075,6 +14100,30 @@ function TargetCanvas({ onFatal, imageFrame }) {
     );
     setViewMode("1:1");
   };
+  const agentPan = useStore((s) => s.agentPan);
+  const clearAgentPan = useStore((s) => s.clearAgentPan);
+  reactExports.useEffect(() => {
+    if (!agentPan) return;
+    clearAgentPan();
+    const jump = centreScroll(agentPan.x, agentPan.y, dpr, oneToOne, pane.width, pane.height, source.width, source.height);
+    if (viewMode === "fit") {
+      pendingJump.current = jump;
+      setViewMode("1:1");
+      return;
+    }
+    const body = paneBody();
+    if (body) {
+      body.scrollLeft = jump.left;
+      body.scrollTop = jump.top;
+    }
+  }, [agentPan]);
+  const agentHighlight = useStore((s) => s.agentHighlight);
+  const clearAgentHighlight = useStore((s) => s.clearAgentHighlight);
+  reactExports.useEffect(() => {
+    if (!agentHighlight) return;
+    const t = window.setTimeout(() => clearAgentHighlight(agentHighlight.seq), agentHighlight.durationMs);
+    return () => window.clearTimeout(t);
+  }, [agentHighlight, clearAgentHighlight]);
   const send = (type) => (e) => {
     if (mode !== "url") return;
     if (viewMode !== "1:1" || panRef.current || e.button === 1) return;
@@ -14103,33 +14152,52 @@ function TargetCanvas({ onFatal, imageFrame }) {
         }
       )
     ] }),
-    /* @__PURE__ */ jsxRuntimeExports.jsx("div", { className: "target-wrap", children: /* @__PURE__ */ jsxRuntimeExports.jsx(
-      "canvas",
-      {
-        ref: canvasRef,
-        className: `target-canvas${fit ? " fit" : panning ? " panning" : altHeld ? " pan-ready" : ""}`,
-        tabIndex: 0,
-        style: { width: `${cssW}px`, height: `${cssH}px` },
-        onClick: jumpTo1x,
-        onPointerDown: startPan,
-        onPointerMove: movePan,
-        onPointerUp: (e) => endPan(e, false),
-        onPointerCancel: (e) => endPan(e, true),
-        onMouseDown: send("mouseDown"),
-        onMouseUp: send("mouseUp"),
-        onMouseMove: send("mouseMove"),
-        onKeyDown: (e) => {
-          if (mode !== "url" || viewMode !== "1:1") return;
-          if (!e.metaKey && !e.ctrlKey) e.preventDefault();
-          for (const ev of keyDownEvents(e)) window.obsrv.sendInput(ev);
-        },
-        onKeyUp: (e) => {
-          if (mode !== "url" || viewMode !== "1:1") return;
-          const ev = keyUpEvent(e);
-          if (ev) window.obsrv.sendInput(ev);
+    /* @__PURE__ */ jsxRuntimeExports.jsxs("div", { className: "target-wrap", children: [
+      /* @__PURE__ */ jsxRuntimeExports.jsx(
+        "canvas",
+        {
+          ref: canvasRef,
+          className: `target-canvas${fit ? " fit" : panning ? " panning" : altHeld ? " pan-ready" : ""}`,
+          tabIndex: 0,
+          style: { width: `${cssW}px`, height: `${cssH}px` },
+          onClick: jumpTo1x,
+          onPointerDown: startPan,
+          onPointerMove: movePan,
+          onPointerUp: (e) => endPan(e, false),
+          onPointerCancel: (e) => endPan(e, true),
+          onMouseDown: send("mouseDown"),
+          onMouseUp: send("mouseUp"),
+          onMouseMove: send("mouseMove"),
+          onKeyDown: (e) => {
+            if (mode !== "url" || viewMode !== "1:1") return;
+            if (!e.metaKey && !e.ctrlKey) e.preventDefault();
+            for (const ev of keyDownEvents(e)) window.obsrv.sendInput(ev);
+          },
+          onKeyUp: (e) => {
+            if (mode !== "url" || viewMode !== "1:1") return;
+            const ev = keyUpEvent(e);
+            if (ev) window.obsrv.sendInput(ev);
+          }
         }
-      }
-    ) })
+      ),
+      agentHighlight && // The agent-control highlight: a target-pixel rect drawn at the
+      // canvas's own scale, absolutely positioned inside the scroll
+      // content so it rides the pane's scroll. Neutral by style-spec law
+      // (no hue) and pointer-events: none, so it never intercepts the
+      // input the canvas forwards.
+      /* @__PURE__ */ jsxRuntimeExports.jsx(
+        "div",
+        {
+          className: "agent-highlight",
+          style: {
+            left: `${agentHighlight.x * scale / dpr}px`,
+            top: `${agentHighlight.y * scale / dpr}px`,
+            width: `${agentHighlight.width * scale / dpr}px`,
+            height: `${agentHighlight.height * scale / dpr}px`
+          }
+        }
+      )
+    ] })
   ] });
 }
 const DISMISS_MS = 4e3;
@@ -14355,6 +14423,8 @@ function App() {
   const [drawer, setDrawer] = reactExports.useState("none");
   const [image, setImage] = reactExports.useState(null);
   const dropToken = reactExports.useRef(0);
+  const targetPaneRef = reactExports.useRef(null);
+  const [targetBounds, setTargetBounds] = reactExports.useState(null);
   const toggle = (which) => () => setDrawer((d) => d === which ? "none" : which);
   const setHost = useStore((s) => s.setHost);
   const setSettings = useStore((s) => s.setSettings);
@@ -14397,14 +14467,29 @@ function App() {
     window.obsrv.setMode(mode);
   }, [mode]);
   reactExports.useEffect(() => {
-    window.obsrv.reportUiState({ presetId, profileId, viewMode, mode });
-  }, [presetId, profileId, viewMode, mode]);
+    const el = targetPaneRef.current;
+    if (!el) return;
+    const measure = () => {
+      const r = el.getBoundingClientRect();
+      setTargetBounds({ x: r.x, y: r.y, width: r.width, height: r.height });
+    };
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    measure();
+    return () => ro.disconnect();
+  }, []);
+  reactExports.useEffect(() => {
+    window.obsrv.reportUiState({ presetId, profileId, viewMode, mode, targetBounds });
+  }, [presetId, profileId, viewMode, mode, targetBounds]);
   reactExports.useEffect(() => {
     return window.obsrv.onAgentApply((patch) => {
       const s = useStore.getState();
       if (patch.presetId !== void 0) s.setPreset(patch.presetId);
       if (patch.profileId !== void 0) s.setProfile(patch.profileId);
       if (patch.viewMode !== void 0) s.setViewMode(patch.viewMode);
+      if (patch.pixelExact !== void 0) s.setPixelExact(patch.pixelExact);
+      if (patch.panTo !== void 0) s.requestAgentPan(patch.panTo);
+      if (patch.highlight !== void 0) s.showAgentHighlight(patch.highlight);
     });
   }, []);
   reactExports.useEffect(() => {
@@ -14476,7 +14561,7 @@ function App() {
             height: image.natural.height
           }
         ) : /* @__PURE__ */ jsxRuntimeExports.jsx(NativeSlot, {}),
-        /* @__PURE__ */ jsxRuntimeExports.jsxs("div", { className: "pane target-pane", children: [
+        /* @__PURE__ */ jsxRuntimeExports.jsxs("div", { className: "pane target-pane", ref: targetPaneRef, children: [
           /* @__PURE__ */ jsxRuntimeExports.jsx("div", { className: "pane-body", children: /* @__PURE__ */ jsxRuntimeExports.jsx(TargetCanvas, { onFatal: setFatal, imageFrame }) }),
           /* @__PURE__ */ jsxRuntimeExports.jsx(TargetFooter, {})
         ] })

package/out/renderer/index.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta http-equiv="Content-Security-Policy" content="default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' blob: data:" />
     <title>Obsrv</title>
-    <script type="module" crossorigin src="./assets/index-P496vEhv.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-FtoKShe_.css">
+    <script type="module" crossorigin src="./assets/index-DyCD4ih_.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-CHF-G97L.css">
   </head>
   <body>
     <div id="root"></div>

package/out/shared/api.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/out/shared/control.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONTROL_COMMANDS = exports.CONTROL_TOKEN_BYTES = exports.CONTROL_FILE_NAME = void 0;
+exports.HIGHLIGHT_DURATION_MAX_MS = exports.HIGHLIGHT_DURATION_MIN_MS = exports.HIGHLIGHT_DURATION_DEFAULT_MS = exports.CONTROL_COMMANDS = exports.CONTROL_TOKEN_BYTES = exports.CONTROL_FILE_NAME = void 0;
 exports.isControlCommand = isControlCommand;
 exports.parseControlFile = parseControlFile;
 exports.controlFileModeOk = controlFileModeOk;
@@ -9,9 +9,13 @@ exports.defaultControlFilePath = defaultControlFilePath;
 exports.presetApplyError = presetApplyError;
 exports.profileApplyError = profileApplyError;
 exports.viewModeApplyError = viewModeApplyError;
+exports.pixelExactApplyError = pixelExactApplyError;
+exports.parseClick = parseClick;
+exports.parseHighlight = parseHighlight;
 exports.parseControlStatus = parseControlStatus;
 const node_crypto_1 = require("node:crypto");
 const node_path_1 = require("node:path");
+const ipcPayloads_1 = require("./ipcPayloads");
 const presets_1 = require("./presets");
 /**
  * The agent-control protocol shared by the main-process control server
@@ -45,6 +49,17 @@ exports.CONTROL_COMMANDS = [
     'setProfile',
     'setViewMode',
     'captureVisible',
+    // v0.5 drive controls (spec §14 "Drive controls").
+    'scroll',
+    'panTo',
+    'click',
+    'highlight',
+    'back',
+    'forward',
+    'reload',
+    'setPixelExact',
+    'captureTarget',
+    'focusWindow',
 ];
 function isControlCommand(v) {
     return typeof v === 'string' && exports.CONTROL_COMMANDS.includes(v);
@@ -136,6 +151,64 @@ function profileApplyError(id) {
 function viewModeApplyError(v) {
     return v === '1:1' || v === 'fit' ? null : `setViewMode payload must be { mode: '1:1' | 'fit' }`;
 }
+function pixelExactApplyError(v) {
+    return typeof v === 'boolean' ? null : 'setPixelExact payload must be { on: boolean }';
+}
+/**
+ * Validates a `click` payload against the target's *current* CSS viewport:
+ * `sendInputEvent` takes CSS coordinates, and a click past the viewport edge
+ * would land on nothing (or, worse, on whatever the page scrolled there),
+ * so it is refused rather than clamped. The coordinate space is
+ * `[0, width) × [0, height)` — pixel row `height` is the first one *outside*
+ * a `height`-pixel viewport. The button defaults to left. Returns the
+ * validated click, or the error message.
+ */
+function parseClick(raw, viewport) {
+    const shape = 'click payload must be { x, y, button? } with finite CSS-pixel coordinates';
+    if (!isRecord(raw))
+        return shape;
+    const { x, y } = raw;
+    if (typeof x !== 'number' || !Number.isFinite(x) || typeof y !== 'number' || !Number.isFinite(y))
+        return shape;
+    if (x < 0 || y < 0 || x >= viewport.width || y >= viewport.height) {
+        return `click (${x}, ${y}) is outside the current CSS viewport ${viewport.width}x${viewport.height}`;
+    }
+    const button = raw.button ?? 'left';
+    if (button !== 'left' && button !== 'middle' && button !== 'right') {
+        return 'click button must be left, middle or right';
+    }
+    return { x, y, button };
+}
+/** How long a highlight overlay stays up when the payload does not say. */
+exports.HIGHLIGHT_DURATION_DEFAULT_MS = 2_000;
+/** Shorter would flash imperceptibly; the payload is clamped, not refused. */
+exports.HIGHLIGHT_DURATION_MIN_MS = 250;
+/** Longer would squat on the pixels under inspection; clamped likewise. */
+exports.HIGHLIGHT_DURATION_MAX_MS = 10_000;
+/**
+ * Validates a `highlight` payload: the rect is checked exactly like a pane
+ * rect (`parseRect` — finite, non-negative, bounded, rounded) and must be at
+ * least 1×1 after rounding (an invisible highlight answering ok would lie).
+ * `durationMs` defaults and clamps rather than erroring — the exact lifetime
+ * is presentation, not correctness — but a non-numeric one is refused, never
+ * guessed. Returns the validated highlight, or the error message.
+ */
+function parseHighlight(raw) {
+    const rect = (0, ipcPayloads_1.parseRect)(raw);
+    if (!rect)
+        return 'highlight payload must be { x, y, width, height, durationMs? } with finite, non-negative target-pixel bounds';
+    if (rect.width < 1 || rect.height < 1)
+        return 'highlight rect must be at least 1x1 target pixels';
+    const d = raw.durationMs;
+    if (d === undefined)
+        return { ...rect, durationMs: exports.HIGHLIGHT_DURATION_DEFAULT_MS };
+    if (typeof d !== 'number' || !Number.isFinite(d))
+        return 'highlight durationMs must be a finite number of milliseconds';
+    return {
+        ...rect,
+        durationMs: Math.min(Math.max(Math.round(d), exports.HIGHLIGHT_DURATION_MIN_MS), exports.HIGHLIGHT_DURATION_MAX_MS),
+    };
+}
 /** Validates a control server `status` response on the client side. */
 function parseControlStatus(raw) {
     if (!isRecord(raw))

package/out/shared/ipcPayloads.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_RECT = void 0;
+exports.parseRect = parseRect;
+exports.parseInputEvent = parseInputEvent;
+exports.parseDeviceScaleFactor = parseDeviceScaleFactor;
+exports.parseSettings = parseSettings;
+exports.parseMode = parseMode;
+exports.parseUiState = parseUiState;
+exports.parseScrollPos = parseScrollPos;
+/**
+ * Parsers for everything the renderer sends main over IPC. Each returns a
+ * fresh, fully-typed value or `null`; nothing from the wire is passed through
+ * by reference, so unknown keys never reach Electron, disk or `getSettings`.
+ * Main must never crash on a renderer message — every handler drops a `null`
+ * silently (or, for request/response channels, rejects the call).
+ */
+/** Largest coordinate or size a pane rect may carry; far beyond any real window. */
+exports.MAX_RECT = 16384;
+const isFiniteNumber = (v) => typeof v === 'number' && Number.isFinite(v);
+const isRecord = (v) => typeof v === 'object' && v !== null;
+function parseRect(raw) {
+    if (!isRecord(raw))
+        return null;
+    const { x, y, width, height } = raw;
+    if (!isFiniteNumber(x) || !isFiniteNumber(y) || !isFiniteNumber(width) || !isFiniteNumber(height))
+        return null;
+    const r = { x: Math.round(x), y: Math.round(y), width: Math.round(width), height: Math.round(height) };
+    for (const v of [r.x, r.y, r.width, r.height])
+        if (v < 0 || v > exports.MAX_RECT)
+            return null;
+    return r;
+}
+const MODIFIERS = new Set([
+    'shift',
+    'control',
+    'alt',
+    'meta',
+    'leftButtonDown',
+    'middleButtonDown',
+    'rightButtonDown',
+]);
+const BUTTONS = new Set(['left', 'middle', 'right']);
+/** Unknown entries are dropped; a missing or non-array list means no modifiers. */
+function parseModifiers(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.filter((m) => typeof m === 'string' && MODIFIERS.has(m));
+}
+function parseInputEvent(raw) {
+    if (!isRecord(raw))
+        return null;
+    const modifiers = parseModifiers(raw.modifiers);
+    switch (raw.type) {
+        case 'mouseDown':
+        case 'mouseUp':
+        case 'mouseMove': {
+            const { x, y, button, clickCount } = raw;
+            if (!isFiniteNumber(x) || !isFiniteNumber(y) || !isFiniteNumber(clickCount))
+                return null;
+            if (typeof button !== 'string' || !BUTTONS.has(button))
+                return null;
+            return { type: raw.type, x, y, button: button, clickCount, modifiers };
+        }
+        case 'mouseWheel': {
+            const { x, y, deltaX, deltaY } = raw;
+            if (!isFiniteNumber(x) || !isFiniteNumber(y) || !isFiniteNumber(deltaX) || !isFiniteNumber(deltaY))
+                return null;
+            return { type: 'mouseWheel', x, y, deltaX, deltaY, modifiers };
+        }
+        case 'keyDown':
+        case 'keyUp':
+        case 'char': {
+            const { keyCode } = raw;
+            if (typeof keyCode !== 'string')
+                return null;
+            return { type: raw.type, keyCode, modifiers };
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * `setViewport`'s device scale factor. Real screens run 1x-3x; 4 leaves
+ * headroom without letting a renderer ask for an absurd raster. A missing
+ * value means 1 (the pre-mobile wire shape); anything else out of range is
+ * refused, never clamped — main must not guess at a malformed payload.
+ */
+function parseDeviceScaleFactor(raw) {
+    if (raw === undefined)
+        return 1;
+    if (!isFiniteNumber(raw) || raw < 1 || raw > 4)
+        return null;
+    return raw;
+}
+/**
+ * Copies exactly the three known keys; the numbers must be finite and
+ * positive. A missing `agentControl` means false (the pre-live-drive wire
+ * shape); any non-boolean value is refused, never coerced.
+ */
+function parseSettings(raw) {
+    if (!isRecord(raw))
+        return null;
+    const { hostDiagonalInches, hostNits } = raw;
+    if (!isFiniteNumber(hostDiagonalInches) || hostDiagonalInches <= 0)
+        return null;
+    if (!isFiniteNumber(hostNits) || hostNits <= 0)
+        return null;
+    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;
+}
+/** Longest preset/profile id the UI-state mirror will store. */
+const MAX_UI_ID = 64;
+/**
+ * The renderer's UI-state report (`IPC.uiState`), mirrored main-side so the
+ * agent-control server can answer `status` without a renderer round-trip.
+ * Ids are copied as opaque strings (bounded — the mirror must not store an
+ * arbitrarily long one) rather than checked against the preset table: the
+ * report *describes* renderer state, and refusing an id main does not know
+ * would leave the mirror lying about it.
+ *
+ * `targetBounds` (the pane rect `captureTarget` crops to) is advisory:
+ * malformed or missing bounds become null — the capture falls back to the
+ * full window — rather than dropping the whole report and starving the
+ * mirror of the state it *is* sure about.
+ */
+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, targetBounds: parseRect(raw.targetBounds) };
+}
+/**
+ * A scroll offset reported by the sync preload in a page webContents. Both
+ * axes must be finite and non-negative; anything else is dropped rather than
+ * relayed to the other pane.
+ */
+function parseScrollPos(raw) {
+    if (!isRecord(raw))
+        return null;
+    const { x, y } = raw;
+    if (!isFiniteNumber(x) || !isFiniteNumber(y) || x < 0 || y < 0)
+        return null;
+    return { x, y };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getobsrv",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "See your site the way 1x screens see it",
   "main": "./out/main/index.js",
   "bin": {
@@ -21,7 +21,8 @@
     "build:mcp": "tsc -p tsconfig.mcp.json",
     "prepublishOnly": "npm run build",
     "prepack": "node scripts/electron-dep.js to-prod",
-    "postpack": "node scripts/electron-dep.js to-dev"
+    "postpack": "node scripts/electron-dep.js to-dev",
+    "release:pack": "npm run build && npm pack"
   },
   "dependencies": {
     "@fontsource/ibm-plex-mono": "^5.3.0",

package/skills/obsrv-screens/SKILL.md

@@ -50,8 +50,9 @@ If the obsrv MCP tools are connected (`obsrv_snap` / `obsrv_diff` /
 `obsrv_presets`), prefer them over shelling out — same pipeline, and the PNG
 comes back inline. If the Obsrv desktop app is open with "Agent control" on
 (toolbar toggle), snaps drive the visible window — the user watches — and
-`obsrv_drive` flips its URL/preset/profile directly; no app means the usual
-headless render.
+`obsrv_drive` flips its URL/preset/profile directly, and can also scroll,
+click, pan and highlight to walk the user through what it found; no app
+means the usual headless render.
 
 ## The loop that catches real regressions