getobsrv 0.4.1 → 0.6.0

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");
 /**
@@ -123,6 +124,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
@@ -136,15 +142,25 @@ 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.'),
     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 +230,49 @@ 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),
+        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. 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()
+        .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.'),
@@ -222,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. */
@@ -232,6 +303,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 +365,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 +380,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 +423,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 +450,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 +527,23 @@ 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. 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` +
         `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 +558,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,12 +572,67 @@ 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);
+        // 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) {
+            // 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');
+        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/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;