getobsrv 0.4.1 → 0.6.0

package/README.md

@@ -83,8 +83,19 @@ 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. A `scroll` reports the offset it actually reached
+(`scrolled` / `scroller`), finds the inner scroll container on pages whose
+root cannot scroll, and takes a `scrollSelector` when you need to name the
+container yourself. With no app running, everything falls back to the headless
+render automatically.
+
+A headless `snap` returns `settled: true` when the page went paint-quiet and
+every pixel painted. `settled: false` is still a usable capture, not a
+failure — a page that kept animating, or one whose repaint never completed,
+comes back as-is (exit code 0) with a warning saying what was missing. Only a
+render that painted nothing at all is an error.
 
 Build first, then register:
 
@@ -119,7 +130,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.
 
@@ -129,6 +149,16 @@ belongs to an unrelated package.
   looks different again; a Windows build would show Windows truth natively.
 - Panel simulation is an approximation, not colourimetric.
 - Non-ASCII text input does not type into the target pane (Electron `sendInputEvent`
-  limitation); nested scroll containers aren't mirrored.
+  limitation).
+- Inner-scroller *reporting* is one-way. An agent `scroll` finds the page's real scroll
+  host — the app-shell pattern (`html, body { overflow: hidden }` with an inner
+  `overflow-y: auto` container) is handled, and the result reports the offset actually
+  reached — but scrolling a nested container **by hand** in the native pane is not
+  mirrored to the target: element scroll events don't bubble to `window`, so the report
+  side never sees them. Dragging the page itself still syncs both ways.
+- Scroll targeting stops at the light DOM of the top-level document. A scroller inside a
+  shadow root or an iframe can't be found automatically *or* named with `scrollSelector`
+  (`document.querySelector` doesn't cross either boundary), so a web-component app that
+  hides its scroller in a shadow root has no escape hatch.
 - Frame delivery has no renderer-side backpressure mailbox (see plan header); at 30 fps
   with dirty rects it has not been needed.

package/out/cli/args.js

@@ -44,7 +44,11 @@ diff flags:
 
 Repeated flags: the last occurrence wins.
 Machine output (JSON) goes to stdout; everything human goes to stderr.
-Exit code 0 on success — diff findings are informational, never a failure.`;
+Exit code 0 on success — diff findings are informational, never a failure.
+snap's "settled" is true when the page went paint-quiet and every pixel
+painted. False is a rescued capture, not a failure: a page that kept animating
+(or whose repaint never completed) is written as-is, exit code 0, with a
+warning naming what was missing. Only a render that painted nothing errors.`;
 }
 /** Flags that take no value. */
 const BOOLEAN_FLAGS = new Set(['full-page', 'json']);

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-DkXWE0ha.js");
+const targetSource = require("./targetSource-BKW32VA5.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);
@@ -75,7 +75,11 @@ diff flags:
 
 Repeated flags: the last occurrence wins.
 Machine output (JSON) goes to stdout; everything human goes to stderr.
-Exit code 0 on success — diff findings are informational, never a failure.`;
+Exit code 0 on success — diff findings are informational, never a failure.
+snap's "settled" is true when the page went paint-quiet and every pixel
+painted. False is a rescued capture, not a failure: a page that kept animating
+(or whose repaint never completed) is written as-is, exit code 0, with a
+warning naming what was missing. Only a render that painted nothing errors.`;
 }
 const BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["full-page", "json"]);
 const VALUE_FLAGS = /* @__PURE__ */ new Set(["preset", "profile", "out", "out-dir", "wait", "timeout", "matrix", "width", "height", "dsf", "diagonal"]);
@@ -218,6 +222,37 @@ ${usage()}`);
 }
 const sleep$1 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const DEFAULT_SETTLE_MS = 400;
+function uncoveredBounds(mask, width, height) {
+  const rowHasGap = (y) => {
+    const row = y * width;
+    for (let x = 0; x < width; x++) if (mask[row + x] === 0) return true;
+    return false;
+  };
+  let y0 = -1;
+  for (let y = 0; y < height; y++) {
+    if (rowHasGap(y)) {
+      y0 = y;
+      break;
+    }
+  }
+  if (y0 < 0) return null;
+  let y1 = y0;
+  for (let y = height - 1; y > y0; y--) {
+    if (rowHasGap(y)) {
+      y1 = y;
+      break;
+    }
+  }
+  const columnHasGap = (x) => {
+    for (let y = y0; y <= y1; y++) if (mask[y * width + x] === 0) return true;
+    return false;
+  };
+  let x0 = 0;
+  while (x0 < width && !columnHasGap(x0)) x0++;
+  let x1 = width - 1;
+  while (x1 > x0 && !columnHasGap(x1)) x1--;
+  return { x: x0, y: y0, width: x1 - x0 + 1, height: y1 - y0 + 1 };
+}
 async function captureQuiescent(source, options = {}) {
   const settleMs = options.settleMs ?? DEFAULT_SETTLE_MS;
   const timeoutMs = options.timeoutMs ?? 3e4;
@@ -228,8 +263,10 @@ async function captureQuiescent(source, options = {}) {
   let mask = null;
   let uncovered = 0;
   let lastPaint = Date.now();
+  let frames = 0;
   const onFrame = (m) => {
     lastPaint = Date.now();
+    frames++;
     if (m.frameWidth !== width || m.frameHeight !== height) {
       width = m.frameWidth;
       height = m.frameHeight;
@@ -275,9 +312,19 @@ async function captureQuiescent(source, options = {}) {
       if (failed) throw failed;
       if (covered && Date.now() - lastPaint >= settleMs) break;
       if (Date.now() >= deadline) {
-        if (!covered) throw new Error(`no full frame painted within ${timeoutMs} ms`);
-        options.onWarn?.(`page kept painting for ${timeoutMs} ms (animation?); capturing the current frame`);
         settled = false;
+        if (covered) {
+          options.onWarn?.(`page kept painting for ${timeoutMs} ms (animation?); capturing the current frame`);
+          break;
+        }
+        if (frames === 0 || width === 0 || height === 0) {
+          throw new Error(`no frame painted within ${timeoutMs} ms`);
+        }
+        const total = width * height;
+        const box = mask ? uncoveredBounds(mask, width, height) : null;
+        options.onWarn?.(
+          `warning: ${(uncovered / total * 100).toFixed(1)}% of the ${width}x${height} frame never painted within ${timeoutMs} ms` + (box ? ` (uncovered region ${box.width}x${box.height} at ${box.x},${box.y})` : "") + `; those pixels are transparent, not page content. Returning the frame as captured (settled: false)`
+        );
         break;
       }
       await sleep$1(Math.min(50, settleMs));

package/out/main/index.js

@@ -4,7 +4,7 @@ const node_fs = require("node:fs");
 const promises = require("node:fs/promises");
 const node_path = require("node:path");
 const node_crypto = require("node:crypto");
-const targetSource = require("./targetSource-DkXWE0ha.js");
+const targetSource = require("./targetSource-BKW32VA5.js");
 const node_http = require("node:http");
 const node_url = require("node:url");
 const IPC = {
@@ -28,6 +28,7 @@ const IPC = {
   targetNavigating: "obsrv:target-navigating",
   syncScroll: "obsrv:sync-scroll",
   applyScroll: "obsrv:apply-scroll",
+  scrollResult: "obsrv:scroll-result",
   openImage: "obsrv:open-image",
   focusUrl: "obsrv:focus-url",
   openImagePath: "obsrv:open-image-path",
@@ -68,51 +69,13 @@ 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_SCROLL_SELECTOR = 512;
 const MAX_RECT = 16384;
+const MAX_SCROLL_WARNINGS = 4;
 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 +97,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 +130,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 +143,124 @@ 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 };
 }
+function parseScrollRequest(raw) {
+  const pos = parseScrollPos(raw);
+  if (!pos) return "scroll payload must be { x, y } with finite, non-negative CSS-pixel offsets";
+  const selector = raw.scrollSelector;
+  if (selector === void 0 || selector === null) return pos;
+  if (typeof selector !== "string") return "scrollSelector must be a CSS selector string";
+  const trimmed = selector.trim();
+  if (trimmed === "") return "scrollSelector must not be empty";
+  if (trimmed.length > MAX_SCROLL_SELECTOR) return `scrollSelector must be at most ${MAX_SCROLL_SELECTOR} characters`;
+  return { ...pos, selector: trimmed };
+}
+function parseScrollReport(raw) {
+  if (!isRecord$1(raw)) return null;
+  const { id, x, y, scroller } = raw;
+  if (!isFiniteNumber(id)) return null;
+  if (!isFiniteNumber(x) || !isFiniteNumber(y)) return null;
+  if (scroller !== "root" && scroller !== "element") return null;
+  const warnings = Array.isArray(raw.warnings) ? raw.warnings.filter((w) => typeof w === "string").slice(0, MAX_SCROLL_WARNINGS) : [];
+  return { id, x, y, scroller, warnings };
+}
+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 +392,58 @@ 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 req2 = parseScrollRequest(payload);
+        if (typeof req2 === "string") return reply(400, { error: req2 });
+        const result = await this.deps.scroll(req2);
+        if (!result) return reply(200, { ok: true, scrolled: null, warnings: ["scroll offset could not be confirmed"] });
+        return reply(200, {
+          ok: true,
+          scrolled: { x: result.x, y: result.y },
+          scroller: result.scroller,
+          ...result.warnings.length > 0 ? { warnings: result.warnings } : {}
+        });
+      }
+      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 });
     }
   }
   /**
@@ -365,6 +484,7 @@ class ControlServer {
 }
 const TOOLBAR_H = 44;
 const MAX_IMAGE_FILE_BYTES = 64 * 1024 * 1024;
+const SCROLL_REPLY_TIMEOUT_MS = 1e3;
 function hostInfo(win) {
   try {
     const d = electron.screen.getDisplayMatching(win.getBounds());
@@ -399,18 +519,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);
@@ -456,6 +581,37 @@ function registerIpc(ctx) {
     native.setBounds(rect);
     rendererDrivesLayout = true;
   });
+  let scrollSeq = 0;
+  const scrollWaiters = /* @__PURE__ */ new Map();
+  electron.ipcMain.on(IPC.scrollResult, (e, raw) => {
+    if (e.sender !== target.webContents && e.sender !== native.webContents) return;
+    const report = parseScrollReport(raw);
+    if (!report) return;
+    const waiter = scrollWaiters.get(report.id);
+    if (!waiter) return;
+    scrollWaiters.delete(report.id);
+    waiter(report);
+  });
+  const scrollBoth = async (req) => {
+    const base = { x: req.x, y: req.y };
+    if (req.selector !== void 0) base.selector = req.selector;
+    if (!native.webContents.isDestroyed()) native.webContents.send(IPC.applyScroll, base);
+    const wc = target.webContents;
+    if (wc.isDestroyed()) return null;
+    const id = ++scrollSeq;
+    const answered = new Promise((resolve) => {
+      const timer = setTimeout(() => {
+        scrollWaiters.delete(id);
+        resolve(null);
+      }, SCROLL_REPLY_TIMEOUT_MS);
+      scrollWaiters.set(id, (report) => {
+        clearTimeout(timer);
+        resolve(report);
+      });
+    });
+    wc.send(IPC.applyScroll, { ...base, id });
+    return answered;
+  };
   electron.ipcMain.handle(IPC.getHostInfo, (e) => {
     assertRenderer(e);
     return hostInfo(win);
@@ -488,6 +644,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 +653,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 +701,43 @@ 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(),
+    // An agent scroll drives both panes over the same `applyScroll` channel
+    // the pane-sync mirror uses — each pane's sync preload applies it and
+    // suppresses its own echo, so the two arrive together with no loop.
+    // Relying on the mirror instead would be silent: an applied scroll is
+    // deliberately not re-reported (see preload/sync.ts).
+    scroll: scrollBoth,
+    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/main/{targetSource-DkXWE0ha.js → targetSource-BKW32VA5.js}

@@ -59,6 +59,15 @@ function classifyFileNavigation(from, to) {
   if (IMAGE_EXTENSIONS.test(path)) return "image";
   return from.startsWith("file:") ? "allow" : "block";
 }
+function isFullFrame(dirty, frameWidth, frameHeight, deviceScaleFactor) {
+  if (dirty.x !== 0 || dirty.y !== 0) return false;
+  if (dirty.width === frameWidth && dirty.height === frameHeight) return true;
+  if (!(deviceScaleFactor > 1)) return false;
+  return dirty.width === Math.round(frameWidth / deviceScaleFactor) && dirty.height === Math.round(frameHeight / deviceScaleFactor);
+}
+function fitsFrame(dirty, frameWidth, frameHeight) {
+  return dirty.x >= 0 && dirty.y >= 0 && dirty.width > 0 && dirty.height > 0 && dirty.x + dirty.width <= frameWidth && dirty.y + dirty.height <= frameHeight;
+}
 const SCHEME = /^[a-z][a-z0-9+.-]*:/i;
 const LOOPBACK = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(\/|$)/i;
 function normalizeUrl(input) {
@@ -159,13 +168,14 @@ class TargetSource extends node_events.EventEmitter {
       if (dirty.width <= 0 || dirty.height <= 0) return;
       if (image.isEmpty()) return;
       const full = image.getSize();
-      const isFull = dirty.x === 0 && dirty.y === 0 && dirty.width === full.width && dirty.height === full.height;
+      const isFull = isFullFrame(dirty, full.width, full.height, this.dsf);
+      if (!isFull && !fitsFrame(dirty, full.width, full.height)) return;
       this.emit("frame", {
         frame: {
-          x: dirty.x,
-          y: dirty.y,
-          width: dirty.width,
-          height: dirty.height,
+          x: isFull ? 0 : dirty.x,
+          y: isFull ? 0 : dirty.y,
+          width: isFull ? full.width : dirty.width,
+          height: isFull ? full.height : dirty.height,
           // `toBitmap()` already returns a fresh copy of the pixels (unlike the
           // deprecated `getBitmap()`, typed `void` in Electron 43), and a
           // Buffer is a Uint8Array, so this is the only copy of the slice.

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 };