getobsrv 0.7.2 → 0.9.0

package/README.md

@@ -28,6 +28,38 @@ Both panes stay in lock-step (scroll, navigation) and the 1x pane is fully inter
   fit), and are shown at true physical size — usually a small, dense render on a
   desktop monitor, exactly like the phone in your hand.
 
+## Quickstart
+
+**The desktop app** — download the DMG for your chip from
+[Releases](https://github.com/vibesyemmy/obsrv/releases), drag Obsrv.app to
+Applications, then clear the quarantine flag once (the build is not yet
+notarised, so macOS falsely reports it as "damaged"):
+
+```bash
+xattr -cr /Applications/Obsrv.app
+```
+
+Open it and set your monitor's diagonal in Settings — that one number is what
+makes the target pane render at true physical size.
+
+**The CLI, and Claude Code / MCP clients:**
+
+```bash
+npm i -g getobsrv                                          # or use npx -y getobsrv
+obsrv install-skill                                        # teach Claude Code when to use it
+claude mcp add --scope user obsrv -- npx -y getobsrv mcp   # give it the tools
+```
+
+`install-skill` copies the [obsrv-screens skill](skills/obsrv-screens/SKILL.md)
+into `~/.claude/skills/` (`--dest` for elsewhere, `--print` to pipe it into
+another agent framework). The skill is what makes an agent reach for Obsrv on
+its own when frontend work needs checking; the MCP registration is what gives
+it the tools to do so. New sessions pick both up.
+
+**Both together** — install the app *and* the tools, then flip **Agent control**
+on in the app's toolbar: agent testing now drives the window you are watching
+instead of rendering invisibly.
+
 ## Use
 
 ```bash
@@ -47,6 +79,12 @@ middle-button drag, Option+drag or Option+wheel, or switch the toolbar's
 pixel-exact — the footer says so) and click anywhere in it to jump back to 1:1
 at that spot.
 
+The `Both / Target` control beside it hides the native pane so the target render
+takes the whole window — useful for a small mobile preset that would otherwise
+sit in half a window, and for agent captures. The native pane stays loaded while
+hidden, so the URL bar, back/forward and link clicks keep working exactly as
+they do side by side.
+
 ## Agent & CI use
 
 The same rendering pipeline runs headless — no window, JSON on stdout, humans
@@ -70,7 +108,8 @@ npx -y getobsrv diff http://localhost:5173 --preset laptop-768 --out-dir diffout
 `npx -y getobsrv --help` (or `node bin/obsrv.js --help` in a checkout) lists every preset, profile and flag. Diff findings
 are informational (exit 0); CI thresholds are the caller's job. A ready-made
 Claude Code skill that wraps the loop (snap matrix → read the PNGs → diff →
-fix → re-snap) lives at [skills/obsrv-screens/SKILL.md](skills/obsrv-screens/SKILL.md).
+fix → re-snap) lives at [skills/obsrv-screens/SKILL.md](skills/obsrv-screens/SKILL.md);
+`obsrv install-skill` copies it into `~/.claude/skills/` so agents find it.
 
 ### MCP server
 
@@ -83,7 +122,9 @@ 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). Agents can
+see it (plus `obsrv_drive` to flip URL/preset/profile/panes directly — `panes:
+'target'` gives the target render the whole window, which is usually what you
+want before a capture). 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

package/bin/install-skill.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// `obsrv install-skill` — copy the packaged Claude Code skill into the user's
+// skills directory, so an agent picks up the snap → look → diff → fix loop
+// without being told about it. Plain Node: no Electron, no build needed.
+'use strict'
+
+const { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync } = require('node:fs')
+const { homedir } = require('node:os')
+const { join, resolve } = require('node:path')
+
+const SKILL_NAME = 'obsrv-screens'
+const source = join(__dirname, '..', 'skills', SKILL_NAME)
+
+function usage() {
+  return `obsrv install-skill — install the ${SKILL_NAME} skill for Claude Code
+
+Usage:
+  obsrv install-skill [flags]
+
+Flags:
+  --dest <dir>   Skills directory to install into (default ~/.claude/skills).
+  --force        Overwrite an existing, different copy.
+  --print        Write SKILL.md to stdout instead of installing.
+  --help         Show this message.
+
+Installs to <dest>/${SKILL_NAME}/. New Claude Code sessions pick the skill up;
+sessions already running need a restart.`
+}
+
+/** Copies a directory tree. Shallow enough for a skill (SKILL.md + optional references). */
+function copyTree(from, to) {
+  mkdirSync(to, { recursive: true })
+  for (const entry of readdirSync(from)) {
+    const src = join(from, entry)
+    const dst = join(to, entry)
+    if (statSync(src).isDirectory()) copyTree(src, dst)
+    else copyFileSync(src, dst)
+  }
+}
+
+/** True when every file in `from` exists in `to` with identical bytes. */
+function sameTree(from, to) {
+  for (const entry of readdirSync(from)) {
+    const src = join(from, entry)
+    const dst = join(to, entry)
+    if (!existsSync(dst)) return false
+    if (statSync(src).isDirectory()) {
+      if (!statSync(dst).isDirectory() || !sameTree(src, dst)) return false
+    } else if (!readFileSync(src).equals(readFileSync(dst))) return false
+  }
+  return true
+}
+
+function main(argv) {
+  let dest = join(homedir(), '.claude', 'skills')
+  let force = false
+
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i]
+    if (flag === '--help' || flag === '-h') {
+      console.log(usage())
+      return 0
+    }
+    if (flag === '--print') {
+      process.stdout.write(readFileSync(join(source, 'SKILL.md'), 'utf8'))
+      return 0
+    }
+    if (flag === '--force') {
+      force = true
+      continue
+    }
+    if (flag === '--dest') {
+      const value = argv[++i]
+      if (!value) {
+        console.error('obsrv install-skill: --dest needs a directory')
+        return 2
+      }
+      dest = resolve(value)
+      continue
+    }
+    console.error(`obsrv install-skill: unknown flag: ${flag}\n\n${usage()}`)
+    return 2
+  }
+
+  if (!existsSync(source)) {
+    console.error(`obsrv install-skill: the packaged skill is missing (looked in ${source})`)
+    return 1
+  }
+
+  const target = join(dest, SKILL_NAME)
+  if (existsSync(target)) {
+    if (sameTree(source, target)) {
+      console.error(`obsrv install-skill: already up to date at ${target}`)
+      return 0
+    }
+    if (!force) {
+      console.error(
+        `obsrv install-skill: ${target} exists and differs — pass --force to overwrite it, ` +
+          'or --dest to install elsewhere',
+      )
+      return 1
+    }
+  }
+
+  copyTree(source, target)
+  console.error(
+    `obsrv install-skill: installed to ${target}\n` +
+      'New Claude Code sessions will pick it up; restart any session already running.',
+  )
+  return 0
+}
+
+process.exit(main(process.argv.slice(2)))

package/bin/obsrv.js

@@ -20,6 +20,14 @@ if (process.argv[2] === 'mcp') {
   return
 }
 
+// `obsrv install-skill` copies the packaged Claude Code skill into the user's
+// skills directory. Also plain node — it never renders anything.
+if (process.argv[2] === 'install-skill') {
+  process.argv.splice(2, 1)
+  require('./install-skill.js')
+  return
+}
+
 const cliEntry = join(__dirname, '..', 'out', 'main', 'cli.js')
 if (!existsSync(cliEntry)) {
   console.error('obsrv: out/main/cli.js is missing — run `npm run build` in the Obsrv repo first')

package/out/cli/args.js

@@ -22,6 +22,8 @@ function usage() {
 Usage:
   obsrv snap <url> [flags]   Render <url> on a target screen; write a PNG, print JSON.
   obsrv diff <url> [flags]   Render <url> at 1x and against a 2x reference; print JSON metrics.
+  obsrv mcp                  Serve the MCP server on stdio (for Claude Code and other clients).
+  obsrv install-skill        Install the obsrv-screens skill for Claude Code (--help for flags).
 
 Shared flags:
   --preset <id>        Screen preset (default ${exports.DEFAULT_PRESET}):

package/out/main/cli.js

@@ -53,6 +53,8 @@ function usage() {
 Usage:
   obsrv snap <url> [flags]   Render <url> on a target screen; write a PNG, print JSON.
   obsrv diff <url> [flags]   Render <url> at 1x and against a 2x reference; print JSON metrics.
+  obsrv mcp                  Serve the MCP server on stdio (for Claude Code and other clients).
+  obsrv install-skill        Install the obsrv-screens skill for Claude Code (--help for flags).
 
 Shared flags:
   --preset <id>        Screen preset (default ${DEFAULT_PRESET}):

package/out/main/index.js

@@ -14,6 +14,7 @@ const IPC = {
   forward: "obsrv:forward",
   setViewport: "obsrv:set-viewport",
   setNativeBounds: "obsrv:set-native-bounds",
+  setNativeVisible: "obsrv:set-native-visible",
   setMode: "obsrv:set-mode",
   sendInput: "obsrv:send-input",
   getHostInfo: "obsrv:get-host-info",
@@ -26,6 +27,7 @@ const IPC = {
   hostChanged: "obsrv:host-changed",
   targetLoading: "obsrv:target-loading",
   targetNavigating: "obsrv:target-navigating",
+  nativeFocused: "obsrv:native-focused",
   syncScroll: "obsrv:sync-scroll",
   applyScroll: "obsrv:apply-scroll",
   scrollResult: "obsrv:scroll-result",
@@ -157,10 +159,13 @@ function parseUiState(raw) {
   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;
+  const panes = raw.panes ?? "both";
+  if (panes !== "both" && panes !== "target") return null;
   return {
     presetId,
     profileId,
     viewMode,
+    panes,
     mode,
     targetBounds: parseRect(raw.targetBounds),
     canvasBounds: parseRect(raw.canvasBounds)
@@ -200,6 +205,7 @@ const CONTROL_COMMANDS = [
   "setPreset",
   "setProfile",
   "setViewMode",
+  "setPanes",
   "captureVisible",
   // v0.5 drive controls (spec §14 "Drive controls").
   "scroll",
@@ -244,6 +250,9 @@ function profileApplyError(id) {
 function viewModeApplyError(v) {
   return v === "1:1" || v === "fit" ? null : `setViewMode payload must be { mode: '1:1' | 'fit' }`;
 }
+function panesApplyError(v) {
+  return v === "both" || v === "target" ? null : `setPanes payload must be { panes: 'both' | 'target' }`;
+}
 function pixelExactApplyError(v) {
   return typeof v === "boolean" ? null : "setPixelExact payload must be { on: boolean }";
 }
@@ -466,6 +475,12 @@ class ControlServer {
         const mode = payload.mode;
         return this.applyAndConfirm({ viewMode: mode }, (s) => s.viewMode === mode);
       }
+      case "setPanes": {
+        const err = panesApplyError(payload.panes);
+        if (err) return reply(400, { error: err });
+        const panes = payload.panes;
+        return this.applyAndConfirm({ panes }, (s) => s.panes === panes);
+      }
       case "captureVisible": {
         const capture = await this.deps.captureVisible();
         return reply(200, { ok: true, ...capture });
@@ -603,7 +618,7 @@ async function checkForUpdate(current, now) {
     request.end();
   });
 }
-const TOOLBAR_H = 44;
+const TOOLBAR_H = 82;
 const MAX_IMAGE_FILE_BYTES = 64 * 1024 * 1024;
 const SCROLL_REPLY_TIMEOUT_MS = 1e3;
 function hostInfo(win) {
@@ -675,13 +690,24 @@ function registerIpc(ctx) {
     } catch {
     }
   });
+  let modeIsLive = true;
+  let panesShowNative = true;
+  const applyNativeVisibility = () => {
+    native.setVisible(modeIsLive && panesShowNative);
+  };
   electron.ipcMain.on(IPC.setMode, (e, raw) => {
     if (!fromRenderer(e)) return;
     const mode = parseMode(raw);
     if (!mode) return;
-    const live = mode === "url";
-    native.setVisible(live);
-    bus.setEnabled(live);
+    modeIsLive = mode === "url";
+    applyNativeVisibility();
+    bus.setEnabled(modeIsLive);
+  });
+  electron.ipcMain.on(IPC.setNativeVisible, (e, raw) => {
+    if (!fromRenderer(e)) return;
+    if (typeof raw !== "boolean") return;
+    panesShowNative = raw;
+    applyNativeVisibility();
   });
   let rendererDrivesLayout = false;
   const fallbackLayout = () => {
@@ -766,7 +792,7 @@ function registerIpc(ctx) {
     settings = s;
     if (s.agentControl !== wasEnabled) applyAgentControl(s.agentControl);
   });
-  const uiState = { presetId: "1080p-24", profileId: "reference", viewMode: "1:1", mode: "url" };
+  const uiState = { presetId: "1080p-24", profileId: "reference", viewMode: "1:1", panes: "both", mode: "url" };
   let targetBounds = null;
   let canvasBounds = null;
   const MAX_PENDING_APPLIES = 32;
@@ -1213,6 +1239,9 @@ function boot() {
       if (!win.isDestroyed()) win.webContents.send(IPC.openImagePath, path);
     }
   });
+  native.webContents.on("focus", () => {
+    if (!win.isDestroyed()) win.webContents.send(IPC.nativeFocused);
+  });
   const target = new targetSource.TargetSource();
   target.on("load-error", (err) => {
     if (!win.isDestroyed()) win.webContents.send(IPC.loadError, err);
@@ -1227,7 +1256,7 @@ function boot() {
   const sync = attachSyncBus(native, target, (url) => {
     if (!win.isDestroyed()) win.webContents.send(IPC.urlChanged, url);
   });
-  const ctx = { win, native, target, bus, sync };
+  const ctx = { win, native, target, bus, sync, toolbarH: TOOLBAR_H };
   registerIpc(ctx);
   installMenu(ctx);
   win.on("close", () => {

package/out/mcp/server.js

@@ -160,6 +160,7 @@ const snapOutputShape = {
     presetId: zod_1.z.string().optional().describe('Live only: the screen preset selected in the app.'),
     profileId: zod_1.z.string().optional().describe('Live only: the panel profile selected in the app.'),
     viewMode: zod_1.z.string().optional().describe("Live only: the app's target-pane view (1:1 or fit)."),
+    panes: zod_1.z.string().optional().describe("Live only: 'both' (native pane beside the target) or 'target' (the target render has the whole window)."),
     width: zod_1.z
         .number()
         .optional()
@@ -245,6 +246,10 @@ 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."),
+    panes: zod_1.z
+        .enum(['both', 'target'])
+        .optional()
+        .describe("Show both panes, or give the target render the whole window ('target'). Solo target is usually what you want before a capture."),
     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).'),
@@ -303,6 +308,7 @@ const driveOutputShape = {
     presetId: zod_1.z.string(),
     profileId: zod_1.z.string(),
     viewMode: zod_1.z.string(),
+    panes: 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() })
@@ -475,6 +481,7 @@ async function liveSnap(app, input, notes) {
         presetId: status.presetId,
         profileId: status.profileId,
         viewMode: status.viewMode,
+        panes: status.panes,
         width,
         height,
         settled,
@@ -620,7 +627,7 @@ server.registerTool('obsrv_drive', {
         `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 → ` +
+        `preset → profile → viewMode → panes → pixelExact → reload → back → forward → scroll → panTo → click → highlight → ` +
         `capture. ` +
         `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 ` +
@@ -664,6 +671,9 @@ 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.panes !== undefined) {
+            await (0, control_2.controlCall)(live.info, 'setPanes', { panes: input.panes }, LIVE_APPLY_TIMEOUT_MS);
+        }
         if (input.pixelExact !== undefined) {
             await (0, control_2.controlCall)(live.info, 'setPixelExact', { on: input.pixelExact }, LIVE_APPLY_TIMEOUT_MS);
         }

package/out/preload/app.js

@@ -7,6 +7,7 @@ const IPC = {
   forward: "obsrv:forward",
   setViewport: "obsrv:set-viewport",
   setNativeBounds: "obsrv:set-native-bounds",
+  setNativeVisible: "obsrv:set-native-visible",
   setMode: "obsrv:set-mode",
   sendInput: "obsrv:send-input",
   getHostInfo: "obsrv:get-host-info",
@@ -19,6 +20,7 @@ const IPC = {
   hostChanged: "obsrv:host-changed",
   targetLoading: "obsrv:target-loading",
   targetNavigating: "obsrv:target-navigating",
+  nativeFocused: "obsrv:native-focused",
   openImage: "obsrv:open-image",
   focusUrl: "obsrv:focus-url",
   openImagePath: "obsrv:open-image-path",
@@ -57,6 +59,7 @@ const api = {
   forward: () => electron.ipcRenderer.send(IPC.forward),
   setViewport: (width, height, deviceScaleFactor) => electron.ipcRenderer.invoke(IPC.setViewport, width, height, deviceScaleFactor),
   setNativeBounds: (rect) => electron.ipcRenderer.send(IPC.setNativeBounds, rect),
+  setNativeVisible: (visible) => electron.ipcRenderer.send(IPC.setNativeVisible, visible),
   setMode: (mode) => electron.ipcRenderer.send(IPC.setMode, mode),
   sendInput: (ev) => electron.ipcRenderer.send(IPC.sendInput, ev),
   getHostInfo: () => electron.ipcRenderer.invoke(IPC.getHostInfo),
@@ -67,6 +70,13 @@ const api = {
   onLoadError: (cb) => subscribe(IPC.loadError, cb),
   onHostChanged: (cb) => subscribe(IPC.hostChanged, cb),
   onTargetLoading: (cb) => subscribe(IPC.targetLoading, cb),
+  onNativeFocused: (cb) => {
+    const listener = () => cb();
+    electron.ipcRenderer.on(IPC.nativeFocused, listener);
+    return () => {
+      electron.ipcRenderer.removeListener(IPC.nativeFocused, listener);
+    };
+  },
   onTargetNavigating: (cb) => {
     const listener = () => cb();
     electron.ipcRenderer.on(IPC.targetNavigating, listener);