getobsrv 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Opeyemi Ajagbe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# Obsrv
+
+See your site the way 1x screens see it.
+
+Designers and developers work on HiDPI (2x–3x) monitors. A large share of users are on
+1x screens — 1080p desktops, 1366×768 laptops, cheap TN panels. On those screens, thin
+font weights go weak, 0.5px hairlines vanish, low-contrast grey text becomes illegible,
+gradients band and P3 colours clip. Browser dev tools emulate the *viewport* of a 1x
+screen but still rasterise on your monitor's physical pixels, so you never see any of it.
+
+Obsrv shows any URL (or a dropped 2x design export) two ways, side by side:
+
+- **Native** — rendered at your host DPR, the way you normally see it.
+- **Target** — rendered at a true 1x by an offscreen Chromium surface
+  (`deviceScaleFactor: 1`), displayed at the physical size it would have on a chosen
+  target monitor, with optional cheap-panel simulation (contrast floor, sRGB coverage,
+  6-bit + FRC dithering, brightness) applied in a WebGL2 shader.
+
+Both panes stay in lock-step (scroll, navigation) and the 1x pane is fully interactive.
+
+- **Mobile presets** — phone and tablet presets (iPhone 6.1" @3x, budget Android @2x, …)
+  rasterise at the device's *true* 2x/3x DPR, wear a mobile user agent, get real mobile
+  viewport semantics (a page without a viewport meta lays out at 980px and shrinks to
+  fit), and are shown at true physical size — usually a small, dense render on a
+  desktop monitor, exactly like the phone in your hand.
+
+## Use
+
+```bash
+npm install
+npm run dev
+```
+
+Type a URL (localhost is fine), pick a target screen preset (1080p 24", 1366×768
+laptop, iPhone 6.1" @3x, …), pick a panel profile (Reference, Office IPS, Budget TN, Old laptop) or open
+the advanced sliders. Enter your own monitor's diagonal in Settings once so the target
+pane renders at true physical size. Drop a 2x/3x PNG or JPG export to check a design
+before it's built.
+
+The target pane opens at 1:1, which usually overflows the pane: pan with a
+middle-button drag, Option+drag or Option+wheel, or switch the toolbar's
+`1:1 / Fit` control to a fit-to-pane overview (smoothly minified, so not
+pixel-exact — the footer says so) and click anywhere in it to jump back to 1:1
+at that spot.
+
+## Agent & CI use
+
+The same rendering pipeline runs headless — no window, JSON on stdout, humans
+on stderr — so agents (Claude Code) and CI can ask "how does this URL look on
+a 1366×768 laptop / budget Android?" without the GUI. Build first
+(`npm run build`; the CLI runs the built `out/`), then:
+
+```bash
+# One PNG at a preset's true raster density (+ metadata JSON on stdout):
+node bin/obsrv.js snap http://localhost:5173 --preset laptop-768 --out shot.png
+
+# A matrix of screens, cheap-panel simulation, full-page capture:
+node bin/obsrv.js snap http://localhost:5173 --matrix laptop-768,android-65,1080p-24 --out shots/
+node bin/obsrv.js snap http://localhost:5173 --preset laptop-768 --profile budget-tn --out tn.png
+node bin/obsrv.js snap http://localhost:5173 --preset laptop-768 --full-page --out full.png
+
+# Machine-readable 1x-vs-2x comparison (ink coverage, row ratios, band deltas):
+node bin/obsrv.js diff http://localhost:5173 --preset laptop-768 --out-dir diffout
+```
+
+`node bin/obsrv.js --help` 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).
+
+### MCP server
+
+The same CLI is also wrapped as an MCP server (stdio, stateless) so MCP
+clients get the tools natively: `obsrv_snap` (render a URL at a preset's true
+raster density — the PNG comes back as an inline image up to 1.5 MiB),
+`obsrv_diff` (the 1x-vs-2x metrics as structured output) and `obsrv_presets`
+(every preset and panel profile, no render). Build first, then register:
+
+```bash
+claude mcp add --scope user obsrv -- node /Users/opeyemiajagbe/Documents/Projects/Obsrv/bin/obsrv-mcp.js
+```
+
+## Develop
+
+```bash
+npm run typecheck     # tsc, both processes
+npm test              # unit (Vitest, node)
+npm run test:browser  # shader parity vs the TS reference (Vitest browser mode)
+npm run test:e2e      # Playwright driving the real Electron app
+npm run dist          # build a macOS DMG (unsigned without a Developer ID identity)
+```
+
+Architecture, decisions and the full spec live in
+[docs/superpowers/specs/2026-08-22-obsrv-design.md](docs/superpowers/specs/2026-08-22-obsrv-design.md);
+the UI style rationale (why the chrome is strictly neutral) is in
+[docs/superpowers/specs/2026-08-23-obsrv-ui-style.md](docs/superpowers/specs/2026-08-23-obsrv-ui-style.md).
+
+## Distribution
+
+Obsrv will publish to npm as **`getobsrv`** (the installed commands remain `obsrv`
+and `obsrv-mcp`; the app's display name remains Obsrv). The bare `obsrv` npm name
+belongs to an unrelated package.
+
+## Known v1 limits
+
+- Rendering truth is the host OS's 1x rasteriser (macOS today). Windows ClearType at 1x
+  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.
+- Frame delivery has no renderer-side backpressure mailbox (see plan header); at 30 fps
+  with dirty rects it has not been needed.

package/bin/obsrv-mcp.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Plain-Node launcher for the Obsrv MCP server (stdio transport): checks for
+// the compiled entry and runs it in-process so stdin/stdout stay the protocol
+// channel. Register with an MCP client as `node /path/to/bin/obsrv-mcp.js`.
+//
+// Prerequisites: `npm install` and `npm run build` in the Obsrv repo — the
+// launcher runs the *built* out/mcp/server.js, never the TypeScript sources.
+'use strict'
+
+const { existsSync } = require('node:fs')
+const { join } = require('node:path')
+
+const serverEntry = join(__dirname, '..', 'out', 'mcp', 'server.js')
+if (!existsSync(serverEntry)) {
+  console.error('obsrv-mcp: out/mcp/server.js is missing — run `npm run build` in the Obsrv repo first')
+  process.exit(1)
+}
+
+require(serverEntry)

package/bin/obsrv.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+// Plain-Node launcher for the headless Obsrv CLI: resolves the Electron
+// binary and re-runs the built entry inside it, forwarding argv (behind `--`
+// so Chromium never eats our flags), stdio, and the exit code.
+//
+// Prerequisites: `npm install` and `npm run build` in the Obsrv repo — the
+// launcher runs the *built* out/main/cli.js, never the TypeScript sources.
+'use strict'
+
+const { spawn } = require('node:child_process')
+const { existsSync, mkdtempSync, rmSync } = require('node:fs')
+const { tmpdir } = require('node:os')
+const { join } = require('node:path')
+
+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')
+  process.exit(1)
+}
+
+let electron
+try {
+  // Under plain node, require('electron') resolves to the binary's path.
+  electron = require('electron')
+} catch {
+  console.error('obsrv: electron is not installed — run `npm install` in the Obsrv repo first')
+  process.exit(1)
+}
+if (typeof electron !== 'string') {
+  console.error('obsrv: require("electron") did not resolve to a binary path (already inside Electron?)')
+  process.exit(1)
+}
+
+const env = { ...process.env }
+// Must boot the real Electron runtime, not Node-mode.
+delete env.ELECTRON_RUN_AS_NODE
+
+// The launcher owns the throwaway user-data dir: Chromium flushes profile
+// files (Session Storage, Local State) *after* the last main-process JS runs,
+// so the Electron child cannot reliably delete its own profile — the plain
+// Node parent, which outlives Chromium, can.
+const userData = mkdtempSync(join(tmpdir(), 'obsrv-cli-'))
+env.OBSRV_CLI_USER_DATA = userData
+const cleanup = () => {
+  try {
+    rmSync(userData, { recursive: true, force: true })
+  } catch {
+    // Best-effort removal of a tmp dir.
+  }
+}
+
+const child = spawn(electron, [cliEntry, '--', ...process.argv.slice(2)], { stdio: 'inherit', env })
+child.on('error', err => {
+  console.error(`obsrv: failed to launch electron: ${err.message}`)
+  cleanup()
+  process.exit(1)
+})
+child.on('exit', (code, signal) => {
+  cleanup()
+  // A run we forwarded a signal into is not a success, even though Chromium's
+  // native SIGTERM shutdown reports exit code 0.
+  process.exit(signal || signalled ? 1 : code ?? 1)
+})
+
+// Forward termination to the Electron child rather than dying and orphaning
+// it; the child's exit then drives our own (and the cleanup) above.
+let signalled = false
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
+    signalled = true
+    child.kill(signal)
+  })
+}

package/out/cli/args.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TIMEOUT_MS = exports.DEFAULT_PRESET = exports.ArgError = void 0;
+exports.usage = usage;
+exports.parseArgs = parseArgs;
+const calibration_1 = require("../shared/calibration");
+const presets_1 = require("../shared/presets");
+/**
+ * Pure argv parsing for the headless CLI (`bin/obsrv.js` → `out/main/cli.js`).
+ * No Electron imports: everything here is unit-testable under plain node.
+ */
+class ArgError extends Error {
+}
+exports.ArgError = ArgError;
+exports.DEFAULT_PRESET = '1080p-24';
+exports.DEFAULT_TIMEOUT_MS = 30_000;
+function usage() {
+    const presets = presets_1.SCREEN_PRESETS.map(p => `      ${p.id.padEnd(14)} ${p.label}`).join('\n');
+    const profiles = presets_1.PANEL_PROFILES.map(p => p.id).join(' | ');
+    return `obsrv — see your site the way 1x screens see it (headless CLI)
+
+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.
+
+Shared flags:
+  --preset <id>        Screen preset (default ${exports.DEFAULT_PRESET}):
+${presets}
+  --width <px> --height <px> [--dsf <factor>] [--diagonal <inches>]
+                       Custom CSS viewport instead of --preset (dsf defaults to 1).
+  --profile <id>       Panel profile: ${profiles} (default reference).
+  --wait <ms>          Extra settle time after load (default 0).
+  --timeout <ms>       Per-render budget for load + paint quiescence (default ${exports.DEFAULT_TIMEOUT_MS}).
+
+snap flags:
+  --out <file>         Output PNG (default ./obsrv-<preset>.png). Under --matrix: an
+                       output directory, or a pattern containing {preset}.
+  --full-page          Capture the full page height (device pixels capped at 4096).
+  --matrix <id,id,…>   Render each listed preset in one run.
+
+diff flags:
+  --out-dir <dir>      Also write target.png and reference.png.
+  --json               JSON metrics to stdout (already the default; accepted for clarity).
+
+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.`;
+}
+/** Flags that take no value. */
+const BOOLEAN_FLAGS = new Set(['full-page', 'json']);
+/** Flags that consume the next token. */
+const VALUE_FLAGS = new Set(['preset', 'profile', 'out', 'out-dir', 'wait', 'timeout', 'matrix', 'width', 'height', 'dsf', 'diagonal']);
+const SNAP_ONLY = new Set(['out', 'full-page', 'matrix']);
+const DIFF_ONLY = new Set(['out-dir', 'json']);
+function collect(command, argv) {
+    let url = null;
+    const flags = new Map();
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (token.startsWith('--')) {
+            const name = token.slice(2);
+            if (BOOLEAN_FLAGS.has(name)) {
+                flags.set(name, true);
+            }
+            else if (VALUE_FLAGS.has(name)) {
+                const value = argv[++i];
+                if (value === undefined || value.startsWith('--'))
+                    throw new ArgError(`--${name} requires a value`);
+                flags.set(name, value);
+            }
+            else {
+                throw new ArgError(`unknown flag: --${name}\n\n${usage()}`);
+            }
+        }
+        else if (url === null) {
+            url = token;
+        }
+        else {
+            throw new ArgError(`unexpected argument: ${token}`);
+        }
+    }
+    if (url === null)
+        throw new ArgError(`usage: obsrv ${command} <url> [flags] — run \`obsrv --help\` for the flag list`);
+    const wrongCommand = command === 'snap' ? DIFF_ONLY : SNAP_ONLY;
+    for (const name of flags.keys()) {
+        if (wrongCommand.has(name)) {
+            throw new ArgError(`--${name} is a ${command === 'snap' ? 'diff' : 'snap'} flag; \`obsrv ${command}\` does not take it`);
+        }
+    }
+    return { url, flags };
+}
+function integer(flags, name, fallback, min) {
+    const raw = flags.get(name);
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        throw new ArgError(`--${name}: expected a number, got "${String(raw)}"`);
+    if (!Number.isInteger(n))
+        throw new ArgError(`--${name}: expected an integer, got "${String(raw)}"`);
+    if (n < min)
+        throw new ArgError(`--${name}: must be >= ${min}`);
+    return n;
+}
+function float(flags, name, fallback, min) {
+    const raw = flags.get(name);
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < min)
+        throw new ArgError(`--${name}: expected a number >= ${min}, got "${String(raw)}"`);
+    return n;
+}
+function presetSpec(id) {
+    let preset;
+    try {
+        preset = (0, presets_1.findPreset)(id);
+    }
+    catch {
+        throw new ArgError(`unknown preset: ${id} (valid: ${presets_1.SCREEN_PRESETS.map(p => p.id).join(', ')})`);
+    }
+    return {
+        presetId: preset.id,
+        cssWidth: preset.width,
+        cssHeight: preset.height,
+        deviceScaleFactor: preset.deviceScaleFactor,
+        diagonalInches: preset.diagonalInches,
+    };
+}
+function resolveSpecs(flags) {
+    const custom = ['width', 'height', 'dsf', 'diagonal'].some(f => flags.has(f));
+    if (custom && flags.has('preset'))
+        throw new ArgError('--preset and --width/--height are mutually exclusive');
+    if (custom && flags.has('matrix'))
+        throw new ArgError('--matrix lists presets; it cannot be combined with custom --width/--height dims');
+    if (flags.has('matrix') && flags.has('preset'))
+        throw new ArgError('--matrix already lists presets; drop --preset');
+    if (custom) {
+        if (!flags.has('width') || !flags.has('height')) {
+            throw new ArgError('custom dims need both --width and --height (with optional --dsf and --diagonal)');
+        }
+        const cssWidth = integer(flags, 'width', 0, 1);
+        const cssHeight = integer(flags, 'height', 0, 1);
+        const deviceScaleFactor = float(flags, 'dsf', 1, 1);
+        const max = (0, calibration_1.maxCssViewport)(deviceScaleFactor);
+        if (cssWidth > max || cssHeight > max) {
+            throw new ArgError(`viewport exceeds the 4096-device-pixel budget: at dsf ${deviceScaleFactor} the CSS limit is ${max}`);
+        }
+        const diagonal = flags.has('diagonal') ? float(flags, 'diagonal', 0, 0.1) : null;
+        return { specs: [{ presetId: 'custom', cssWidth, cssHeight, deviceScaleFactor, diagonalInches: diagonal }], matrix: false };
+    }
+    const matrixRaw = flags.get('matrix');
+    if (typeof matrixRaw === 'string') {
+        const ids = matrixRaw.split(',').map(s => s.trim()).filter(s => s.length > 0);
+        if (ids.length === 0)
+            throw new ArgError('--matrix: expected a comma-separated list of preset ids');
+        return { specs: ids.map(presetSpec), matrix: true };
+    }
+    const id = typeof flags.get('preset') === 'string' ? flags.get('preset') : exports.DEFAULT_PRESET;
+    return { specs: [presetSpec(id)], matrix: false };
+}
+function resolveProfile(flags) {
+    const raw = flags.get('profile');
+    if (raw === undefined)
+        return 'reference';
+    try {
+        return (0, presets_1.findProfile)(raw).id;
+    }
+    catch {
+        throw new ArgError(`unknown profile: ${String(raw)} (valid: ${presets_1.PANEL_PROFILES.map(p => p.id).join(', ')})`);
+    }
+}
+function parseArgs(argv) {
+    const [command, ...rest] = argv;
+    if (command === undefined || command === 'help' || command === '--help' || command === '-h') {
+        return { command: 'help', text: usage() };
+    }
+    if (command !== 'snap' && command !== 'diff') {
+        throw new ArgError(`unknown command: ${command}\n\n${usage()}`);
+    }
+    const { url, flags } = collect(command, rest);
+    const { specs, matrix } = resolveSpecs(flags);
+    const profileId = resolveProfile(flags);
+    const waitMs = integer(flags, 'wait', 0, 0);
+    const timeoutMs = integer(flags, 'timeout', exports.DEFAULT_TIMEOUT_MS, 1);
+    if (command === 'snap') {
+        const out = typeof flags.get('out') === 'string' ? flags.get('out') : matrix ? '.' : `obsrv-${specs[0].presetId}.png`;
+        return { command, url, specs, profileId, out, matrix, fullPage: flags.has('full-page'), waitMs, timeoutMs };
+    }
+    const spec = specs[0];
+    if (spec.deviceScaleFactor !== 1) {
+        throw new ArgError(`diff compares the target against a 2x reference downsampled onto the target's 1x grid, ` +
+            `so it only supports 1x targets in v1 — "${spec.presetId}" renders at ${spec.deviceScaleFactor}x. ` +
+            `Use a 1x preset (e.g. laptop-768, 1080p-24) or plain \`obsrv snap\` for dense presets.`);
+    }
+    const referenceMax = (0, calibration_1.maxCssViewport)(2);
+    if (spec.cssWidth > referenceMax || spec.cssHeight > referenceMax) {
+        throw new ArgError(`diff renders a 2x reference, so the CSS viewport must fit ${referenceMax}px per axis ` +
+            `(4096 device px at 2x) — "${spec.presetId}" is ${spec.cssWidth}×${spec.cssHeight}. ` +
+            `Use \`obsrv snap\` for this preset instead.`);
+    }
+    const outDir = typeof flags.get('out-dir') === 'string' ? flags.get('out-dir') : null;
+    return { command, url, spec, profileId, outDir, waitMs, timeoutMs };
+}