getobsrv 0.4.1 → 0.6.0

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,208 @@
+"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;
+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
+ * 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;
+/** 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) {
+    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 };
+}
+/**
+ * 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.4.1",
+  "version": "0.6.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