getobsrv 0.5.0 → 0.6.0

package/README.md

@@ -85,9 +85,18 @@ If the desktop app is open with the toolbar's **Agent control** toggle on,
 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). 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
+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:
 
 ```bash
@@ -140,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,7 +69,9 @@ function attachFrameBus(target, win) {
     }
   };
 }
+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$1 = (v) => typeof v === "object" && v !== null;
 function parseRect(raw) {
@@ -154,6 +157,26 @@ function parseScrollPos(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 = [
@@ -374,10 +397,16 @@ class ControlServer {
         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 });
+        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);
@@ -455,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());
@@ -551,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);
@@ -653,11 +714,12 @@ function registerIpc(ctx) {
       };
     },
     viewport: () => target.getViewport(),
-    scroll: (pos) => {
-      for (const wc of [native.webContents, target.webContents]) {
-        if (!wc.isDestroyed()) wc.send(IPC.applyScroll, pos);
-      }
-    },
+    // 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 });

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/server.js

@@ -11,6 +11,7 @@ const zod_1 = require("zod");
 const args_1 = require("../cli/args");
 const control_1 = require("../shared/control");
 const presets_1 = require("../shared/presets");
+const types_1 = require("../shared/types");
 const control_2 = require("./control");
 const lib_1 = require("./lib");
 /**
@@ -141,7 +142,9 @@ const snapOutputShape = {
     profile: zod_1.z.string().optional().describe('Headless only: applied panel profile id.'),
     settled: zod_1.z
         .boolean()
-        .describe('Headless: the page went paint-quiet. Live: the app confirmed the navigation before the capture.'),
+        .describe('Headless: the page went paint-quiet and every pixel painted. False is still a usable capture — a page that ' +
+        'kept animating, or one whose repaint never completed, is returned as-is with a warning saying what was ' +
+        'missing. Live: the app confirmed the navigation before the capture.'),
     warnings: zod_1.z.array(zod_1.z.string()),
     pngPath: zod_1.z.string().describe('Absolute path of the captured PNG (kept in a per-call temp dir).'),
     url: zod_1.z.string().optional().describe('Live only: the URL the app reports showing.'),
@@ -233,9 +236,24 @@ const driveInputShape = {
     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) })
+        .object({
+        x: zod_1.z.number().min(0),
+        y: zod_1.z.number().min(0),
+        scrollSelector: zod_1.z
+            .string()
+            .min(1)
+            .max(types_1.MAX_SCROLL_SELECTOR)
+            .optional()
+            .describe('Escape hatch: a CSS selector naming the element to scroll, for pages whose scroll host the automatic ' +
+            'detection misjudges (several large scrollers, a virtualised list that translates content). No fallback ' +
+            'if it matches nothing — the result says so. Same reach as the detection: light DOM of the top-level ' +
+            'document only, so a scroller inside a shadow root or an iframe cannot be targeted.'),
+    })
         .optional()
-        .describe('Scroll both panes to this absolute page offset in CSS px.'),
+        .describe('Scroll both panes to this absolute page offset in CSS px. Pages whose root cannot scroll (app shells with ' +
+        '`html, body { overflow: hidden }` and an inner `overflow-y: auto` container) are handled: the largest ' +
+        'visible inner scroller is found and scrolled instead. Check `scrolled` in the result for the offset ' +
+        'actually reached — that is how you tell a real scroll from one that clamped.'),
     panTo: zod_1.z
         .object({ x: zod_1.z.number().min(0), y: zod_1.z.number().min(0) })
         .optional()
@@ -263,6 +281,18 @@ const driveOutputShape = {
     profileId: zod_1.z.string(),
     viewMode: zod_1.z.string(),
     mode: zod_1.z.string().describe("The app's pane mode: 'url' (live page) or 'image' (a dropped design export)."),
+    scrolled: zod_1.z
+        .object({ x: zod_1.z.number(), y: zod_1.z.number() })
+        .nullable()
+        .optional()
+        .describe('Only when `scroll` was requested: the offset the target pane actually reached, read back after the write. ' +
+        'Less than you asked for means the content clamped (short page, or the wrong scroller). Null means the ' +
+        'pane did not confirm in time — the scroll may still have landed.'),
+    scroller: zod_1.z
+        .enum(['root', 'element'])
+        .optional()
+        .describe("Only when `scroll` was requested: 'root' if the document scrolled, 'element' if an inner scroll container did."),
+    warnings: zod_1.z.array(zod_1.z.string()).optional().describe('Anything worth knowing about the commands that ran (e.g. a scrollSelector that matched nothing).'),
 };
 // --- live drive --------------------------------------------------------------
 /** Budget for one control `status` round-trip once the app is known live. */
@@ -504,7 +534,10 @@ server.registerTool('obsrv_drive', {
         `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. ` +
+        `click that navigates is reflected in that status — the call waits briefly (up to 2 s) for the commit. A ` +
+        `scroll adds \`scrolled\` (the offset actually reached) and \`scroller\` ('root' or 'element'): compare ` +
+        `\`scrolled\` with what you asked for rather than trusting the call's success, and use \`scroll.scrollSelector\` ` +
+        `when the automatic scroll-host detection picks the wrong container.\n\n` +
         `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` +
@@ -548,8 +581,25 @@ server.registerTool('obsrv_drive', {
             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);
+        // The scroll answer is the interesting half: it reports the offset the
+        // pane reached, which is the only way to tell a scroll from a clamp.
+        let scrolled;
+        let scroller;
+        const warnings = [];
+        if (input.scroll !== undefined) {
+            const r = await (0, control_2.controlCall)(live.info, 'scroll', input.scroll, LIVE_APPLY_TIMEOUT_MS);
+            const at = r['scrolled'];
+            scrolled =
+                at !== null && typeof at === 'object' && typeof at.x === 'number' && typeof at.y === 'number'
+                    ? { x: at.x, y: at.y }
+                    : null;
+            if (r['scroller'] === 'root' || r['scroller'] === 'element')
+                scroller = r['scroller'];
+            if (Array.isArray(r['warnings']))
+                for (const w of r['warnings'])
+                    if (typeof w === 'string')
+                        warnings.push(w);
+        }
         if (input.panTo !== undefined)
             await (0, control_2.controlCall)(live.info, 'panTo', input.panTo, LIVE_APPLY_TIMEOUT_MS);
         if (input.click !== undefined) {
@@ -574,9 +624,15 @@ server.registerTool('obsrv_drive', {
         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');
+        const structured = {
+            ...status,
+            ...(input.scroll !== undefined ? { scrolled: scrolled ?? null } : {}),
+            ...(scroller !== undefined ? { scroller } : {}),
+            ...(warnings.length > 0 ? { warnings } : {}),
+        };
         return {
-            content: [{ type: 'text', text: JSON.stringify(status, null, 2) }],
-            structuredContent: { ...status },
+            content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
+            structuredContent: structured,
         };
     }
     catch (e) {

package/out/preload/sync.js

@@ -1,8 +1,12 @@
 "use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const electron = require("electron");
 const SUPPRESS_MS = 120;
 const SYNC_SCROLL = "obsrv:sync-scroll";
 const APPLY_SCROLL = "obsrv:apply-scroll";
+const SCROLL_RESULT = "obsrv:scroll-result";
+const MAX_VISITED = 2e3;
+const SCROLL_EPSILON = 1;
 let suppressUntil = 0;
 let lastApplied = null;
 let rafId = 0;
@@ -33,9 +37,102 @@ window.addEventListener(
   },
   { passive: true }
 );
-electron.ipcRenderer.on(APPLY_SCROLL, (_e, pos) => {
-  lastApplied = pos;
-  if (window.scrollX === pos.x && window.scrollY === pos.y) return;
-  suppressUntil = performance.now() + SUPPRESS_MS;
-  window.scrollTo(pos.x, pos.y);
+function rootScrolls() {
+  const el = document.scrollingElement;
+  if (!el) return false;
+  return el.scrollHeight > el.clientHeight + SCROLL_EPSILON || el.scrollWidth > el.clientWidth + SCROLL_EPSILON;
+}
+function canScroll(el) {
+  const overflowsY = el.scrollHeight > el.clientHeight + SCROLL_EPSILON;
+  const overflowsX = el.scrollWidth > el.clientWidth + SCROLL_EPSILON;
+  if (!overflowsY && !overflowsX) return false;
+  const style = window.getComputedStyle(el);
+  const scrollableY = style.overflowY === "auto" || style.overflowY === "scroll";
+  const scrollableX = style.overflowX === "auto" || style.overflowX === "scroll";
+  return overflowsY && scrollableY || overflowsX && scrollableX;
+}
+function isVisible(el) {
+  const check = el.checkVisibility;
+  if (typeof check !== "function") return el.getClientRects().length > 0;
+  return check.call(el, { visibilityProperty: true, opacityProperty: true });
+}
+function findScroller(root = document.body) {
+  if (!root) return null;
+  let best = null;
+  let bestArea = 0;
+  let visited = 0;
+  const stack = [root];
+  while (stack.length > 0) {
+    const el = stack.pop();
+    if (visited++ >= MAX_VISITED) break;
+    const area = el.clientWidth * el.clientHeight;
+    if (area <= 0 && el.getClientRects().length === 0 && window.getComputedStyle(el).display === "none") continue;
+    if (area > bestArea && canScroll(el) && isVisible(el)) {
+      best = el;
+      bestArea = area;
+    }
+    const kids = el.children;
+    for (let i = kids.length - 1; i >= 0; i--) stack.push(kids[i]);
+  }
+  return best;
+}
+let cachedScroller = null;
+function resolveScroller() {
+  if (rootScrolls()) {
+    cachedScroller = null;
+    return null;
+  }
+  if (cachedScroller && cachedScroller.isConnected && canScroll(cachedScroller)) return cachedScroller;
+  cachedScroller = findScroller();
+  return cachedScroller;
+}
+function applyTo(el, pos) {
+  if (el) {
+    el.scrollTo({ left: pos.x, top: pos.y, behavior: "instant" });
+    return { x: el.scrollLeft, y: el.scrollTop };
+  }
+  window.scrollTo({ left: pos.x, top: pos.y, behavior: "instant" });
+  return { x: window.scrollX, y: window.scrollY };
+}
+electron.ipcRenderer.on(APPLY_SCROLL, (_e, req) => {
+  const pos = { x: req.x, y: req.y };
+  const warnings = [];
+  let scroller = "root";
+  let reached;
+  if (typeof req.selector === "string") {
+    let el = null;
+    try {
+      el = document.querySelector(req.selector);
+    } catch {
+      warnings.push(`scrollSelector ${JSON.stringify(req.selector)} is not a valid CSS selector; nothing was scrolled`);
+    }
+    if (el) {
+      scroller = "element";
+      reached = applyTo(el, pos);
+      if (reached.x !== pos.x || reached.y !== pos.y) {
+        warnings.push(
+          `scrollSelector ${JSON.stringify(req.selector)} matched an element that could not reach (${pos.x}, ${pos.y}); it stopped at (${reached.x}, ${reached.y})`
+        );
+      }
+    } else {
+      if (warnings.length === 0) {
+        warnings.push(`scrollSelector ${JSON.stringify(req.selector)} matched no element; nothing was scrolled`);
+      }
+      reached = { x: window.scrollX, y: window.scrollY };
+    }
+  } else {
+    const el = resolveScroller();
+    scroller = el ? "element" : "root";
+    if (!el) {
+      lastApplied = pos;
+      if (window.scrollX !== pos.x || window.scrollY !== pos.y) suppressUntil = performance.now() + SUPPRESS_MS;
+    }
+    reached = applyTo(el, pos);
+  }
+  if (typeof req.id === "number") {
+    electron.ipcRenderer.send(SCROLL_RESULT, { id: req.id, x: reached.x, y: reached.y, scroller, warnings });
+  }
 });
+exports.MAX_VISITED = MAX_VISITED;
+exports.findScroller = findScroller;
+exports.resolveScroller = resolveScroller;

package/out/shared/ipcPayloads.js

@@ -8,6 +8,9 @@ exports.parseSettings = parseSettings;
 exports.parseMode = parseMode;
 exports.parseUiState = parseUiState;
 exports.parseScrollPos = parseScrollPos;
+exports.parseScrollRequest = parseScrollRequest;
+exports.parseScrollReport = parseScrollReport;
+const types_1 = require("./types");
 /**
  * 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
@@ -17,6 +20,8 @@ exports.parseScrollPos = parseScrollPos;
  */
 /** Largest coordinate or size a pane rect may carry; far beyond any real window. */
 exports.MAX_RECT = 16384;
+/** Most warnings a pane's scroll reply may carry; the preload sends at most one. */
+const MAX_SCROLL_WARNINGS = 4;
 const isFiniteNumber = (v) => typeof v === 'number' && Number.isFinite(v);
 const isRecord = (v) => typeof v === 'object' && v !== null;
 function parseRect(raw) {
@@ -156,3 +161,48 @@ function parseScrollPos(raw) {
         return null;
     return { x, y };
 }
+/**
+ * A `scroll` command payload: an offset plus the optional `scrollSelector`
+ * escape hatch. The selector is only ever handed to `document.querySelector`
+ * in the preload's isolated world — never evaluated — but it is still bounded
+ * and type-checked here so a malformed one is refused with an explanation
+ * rather than silently ignored by the page. Returns the parsed request, or the
+ * error message.
+ */
+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 === undefined || 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 > types_1.MAX_SCROLL_SELECTOR)
+        return `scrollSelector must be at most ${types_1.MAX_SCROLL_SELECTOR} characters`;
+    return { ...pos, selector: trimmed };
+}
+/**
+ * A pane's `IPC.scrollResult` reply. Sent by the sync preload, which runs
+ * beside a third-party page, so it is parsed exactly like any renderer
+ * message; anything malformed is dropped and the caller times out rather than
+ * reporting an offset it cannot trust.
+ */
+function parseScrollReport(raw) {
+    if (!isRecord(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 };
+}

package/out/shared/types.js

@@ -1,2 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SCROLL_SELECTOR = void 0;
+/** Longest `scrollSelector` accepted; a CSS selector far beyond any real one. */
+exports.MAX_SCROLL_SELECTOR = 512;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getobsrv",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "See your site the way 1x screens see it",
   "main": "./out/main/index.js",
   "bin": {