getobsrv 0.7.1 → 0.8.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
@@ -70,7 +102,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
 

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

@@ -660,6 +660,7 @@ function registerIpc(ctx) {
   });
   electron.ipcMain.handle(IPC.setViewport, (e, width, height, rawDsf) => {
     assertRenderer(e);
+    viewportArrived = true;
     const dsf = parseDeviceScaleFactor(rawDsf);
     if (dsf === null) throw new Error("invalid deviceScaleFactor");
     const v = target.setViewport(width, height, dsf);
@@ -714,6 +715,7 @@ function registerIpc(ctx) {
     waiter(report);
   });
   const scrollBoth = async (req) => {
+    await awaitViewportStable();
     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);
@@ -786,6 +788,18 @@ function registerIpc(ctx) {
       }
     }
   });
+  let viewportPending = false;
+  let viewportArrived = false;
+  const VIEWPORT_ARRIVAL_MS = 600;
+  const awaitViewportStable = async () => {
+    if (!viewportPending) return;
+    viewportPending = false;
+    const arrivalDeadline = Date.now() + VIEWPORT_ARRIVAL_MS;
+    while (!viewportArrived && Date.now() < arrivalDeadline) {
+      await new Promise((r) => setTimeout(r, SETTLE_POLL_MS));
+    }
+    await settleTarget();
+  };
   const SETTLE_POLL_MS = 80;
   const SETTLE_STABLE_READS = 2;
   const SETTLE_BUDGET_MS = 4e3;
@@ -880,6 +894,10 @@ function registerIpc(ctx) {
     navigate: navigateBoth,
     apply: (patch) => {
       if (win.isDestroyed()) return;
+      if (patch.presetId !== void 0) {
+        viewportPending = true;
+        viewportArrived = false;
+      }
       if (!rendererReported) {
         if (pendingApplies.length >= MAX_PENDING_APPLIES) {
           if (!warnedPendingOverflow) {
@@ -894,12 +912,14 @@ function registerIpc(ctx) {
       win.webContents.send(IPC.agentApply, patch);
     },
     captureVisible: async () => {
+      await awaitViewportStable();
       await settleTarget();
       const image = await win.webContents.capturePage();
       const size = image.getSize();
       return { data: image.toPNG().toString("base64"), width: size.width, height: size.height };
     },
     captureTarget: async () => {
+      await awaitViewportStable();
       const settled = await settleTarget();
       const bounds = canvasBounds ?? targetBounds;
       const known = bounds !== null && bounds.width >= 1 && bounds.height >= 1;

package/package.json

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