getobsrv 0.3.0

package/out/mcp/server.js

@@ -0,0 +1,301 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const zod_1 = require("zod");
+const args_1 = require("../cli/args");
+const presets_1 = require("../shared/presets");
+const lib_1 = require("./lib");
+/**
+ * Obsrv MCP server (stdio, stateless): three read-only tools wrapping the
+ * headless CLI. Rendering stays in `bin/obsrv.js` — it already owns signals,
+ * per-run user-data isolation, temp-dir cleanup and crash fast-fail — the
+ * server only maps tool input to argv, spawns, and shapes the result.
+ * Launched by `bin/obsrv-mcp.js` from the build at `out/mcp/server.js`.
+ */
+const REPO_ROOT = (0, node_path_1.resolve)(__dirname, '..', '..');
+const CLI_BIN = (0, node_path_1.join)(REPO_ROOT, 'bin', 'obsrv.js');
+const VERSION = (() => {
+    try {
+        return JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(REPO_ROOT, 'package.json'), 'utf8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
+/** Grace between SIGTERM and SIGKILL for a run that ignores the former. */
+const SIGKILL_GRACE_MS = 10_000;
+/**
+ * Spawns `node bin/obsrv.js <args>`; SIGTERMs a wedged run after
+ * `killAfterMs`, and SIGKILLs it if it still has not exited after
+ * SIGKILL_GRACE_MS more.
+ */
+function runCli(args, killAfterMs) {
+    return new Promise((done, fail) => {
+        const child = (0, node_child_process_1.spawn)(process.execPath, [CLI_BIN, ...args], { cwd: REPO_ROOT, stdio: ['ignore', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        let killed = false;
+        let killTimer;
+        const timer = setTimeout(() => {
+            killed = true;
+            child.kill('SIGTERM');
+            killTimer = setTimeout(() => child.kill('SIGKILL'), SIGKILL_GRACE_MS);
+        }, killAfterMs);
+        child.stdout.on('data', d => (stdout += String(d)));
+        child.stderr.on('data', d => (stderr += String(d)));
+        child.on('error', err => {
+            clearTimeout(timer);
+            clearTimeout(killTimer);
+            fail(err);
+        });
+        child.on('close', code => {
+            clearTimeout(timer);
+            clearTimeout(killTimer);
+            done({ code, stdout, stderr, killed });
+        });
+    });
+}
+const toolError = (text) => ({ isError: true, content: [{ type: 'text', text }] });
+function cliFailure(command, run, killAfterMs) {
+    if (run.killed) {
+        return toolError(`obsrv ${command} did not exit within ${killAfterMs} ms and was terminated. ` +
+            `Raise timeoutMs, or try a smaller preset / non-full-page snap. ` +
+            (run.stderr.trim() ? `stderr: ${(0, lib_1.stderrTail)(run.stderr)}` : 'No stderr output.'));
+    }
+    return toolError(`obsrv ${command} failed (exit ${run.code ?? 'unknown'}): ${(0, lib_1.stderrTail)(run.stderr)}`);
+}
+/** An inline image block for a PNG within the cap, else a text block saying why not. */
+async function imageOrNote(pngPath, label, suggestion) {
+    const png = await (0, promises_1.readFile)(pngPath);
+    if ((0, lib_1.shouldInlineImage)(png.byteLength)) {
+        return { type: 'image', data: png.toString('base64'), mimeType: 'image/png' };
+    }
+    return {
+        type: 'text',
+        text: `${label} is ${png.byteLength} bytes — over the ${lib_1.MAX_INLINE_IMAGE_BYTES}-byte inline cap, so it is not ` +
+            `inlined. Read the file at ${pngPath} instead${suggestion ? `, or ${suggestion}` : ''}.`,
+    };
+}
+// --- schemas -----------------------------------------------------------------
+const PRESET_IDS = presets_1.SCREEN_PRESETS.map(p => p.id);
+const PROFILE_IDS = presets_1.PANEL_PROFILES.map(p => p.id);
+const urlField = zod_1.z
+    .string()
+    .min(1)
+    .describe('Page to render: an http://, https:// or file:// URL (bare hosts also work). Other schemes are rejected.');
+const profileField = zod_1.z
+    .enum(PROFILE_IDS)
+    .optional()
+    .describe('Panel simulation (contrast floor, gamut, bit depth, brightness). Default: reference (off).');
+const snapInputShape = {
+    url: urlField,
+    preset: zod_1.z
+        .enum(PRESET_IDS)
+        .optional()
+        .describe('Screen preset id (list them with obsrv_presets). Mutually exclusive with width/height. Default: 1080p-24.'),
+    width: zod_1.z.number().int().min(1).optional().describe('Custom CSS viewport width in px. Needs height; mutually exclusive with preset.'),
+    height: zod_1.z.number().int().min(1).optional().describe('Custom CSS viewport height in px. Needs width.'),
+    deviceScaleFactor: zod_1.z
+        .number()
+        .min(1)
+        .optional()
+        .describe('Raster density for custom dims (device px per CSS px, default 1). Device pixels are capped at 4096 per axis.'),
+    diagonalInches: zod_1.z.number().min(0.1).optional().describe('Simulated panel diagonal in inches, for custom dims.'),
+    profile: profileField,
+    fullPage: zod_1.z.boolean().optional().describe('Capture the full page height (device px capped at 4096; a warning reports clamping).'),
+    waitMs: zod_1.z.number().int().min(0).optional().describe('Extra settle time after load, in ms, for late-settling content. Default 0.'),
+    timeoutMs: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe(`Per-render budget for load + paint quiescence, in ms. Default ${args_1.DEFAULT_TIMEOUT_MS}.`),
+};
+const snapOutputShape = {
+    out: zod_1.z.string().describe('PNG path the CLI wrote (same file as pngPath).'),
+    preset: zod_1.z.string().describe('Preset id, or "custom" for width/height runs.'),
+    cssWidth: zod_1.z.number().describe('Applied CSS viewport width.'),
+    cssHeight: zod_1.z.number().describe('Applied CSS viewport height (grown under fullPage).'),
+    deviceScaleFactor: zod_1.z.number(),
+    profile: zod_1.z.string(),
+    settled: zod_1.z.boolean().describe('False: the page never went paint-quiet (e.g. animation) and the capture is best-effort.'),
+    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).'),
+};
+const diffInputShape = {
+    url: urlField,
+    preset: zod_1.z
+        .enum(PRESET_IDS)
+        .optional()
+        .describe('Screen preset id — 1x presets only (e.g. laptop-768, 1080p-24); dense presets are refused. Default: 1080p-24.'),
+    profile: profileField,
+    includeImages: zod_1.z
+        .boolean()
+        .optional()
+        .describe('Also inline target.png and reference.png as images (each subject to the 1.5 MiB cap). Default: paths only.'),
+    waitMs: zod_1.z.number().int().min(0).optional().describe('Extra settle time after load, in ms, applied to both renders. Default 0.'),
+    timeoutMs: zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe(`Per-render budget for load + paint quiescence, in ms. Default ${args_1.DEFAULT_TIMEOUT_MS}.`),
+};
+const diffOutputShape = {
+    url: zod_1.z.string(),
+    preset: zod_1.z.string(),
+    profile: zod_1.z.string(),
+    // Always present: buildDiffArgs unconditionally passes --out-dir, and the
+    // CLI writes both PNGs whenever it is given one.
+    files: zod_1.z
+        .object({ target: zod_1.z.string(), reference: zod_1.z.string() })
+        .describe('PNGs on the same 1x grid, kept in a per-call temp dir.'),
+    inkCoverage: zod_1.z
+        .object({ target: zod_1.z.number(), reference: zod_1.z.number(), delta: zod_1.z.number() })
+        .describe('Fraction of pixels darker than the ink threshold; negative delta = the 1x render is losing ink.'),
+    rows: zod_1.z
+        .object({ target: zod_1.z.number(), reference: zod_1.z.number(), ratio: zod_1.z.number().nullable() })
+        .describe('Ink rows: target on the 1x raster, reference on the raw 2x raster. Ratio ≈0.5 is normal glyph scaling.'),
+    bands: zod_1.z.array(zod_1.z.object({ y0: zod_1.z.number(), y1: zod_1.z.number(), targetInk: zod_1.z.number(), referenceInk: zod_1.z.number(), delta: zod_1.z.number() })),
+    findings: zod_1.z.array(zod_1.z.string()).describe('Humanised per-band findings. Informational — thresholds are the caller\'s job.'),
+};
+const presetsOutputShape = {
+    presets: zod_1.z.array(zod_1.z.object({
+        id: zod_1.z.string(),
+        label: zod_1.z.string(),
+        group: zod_1.z.string(),
+        cssWidth: zod_1.z.number(),
+        cssHeight: zod_1.z.number(),
+        deviceScaleFactor: zod_1.z.number(),
+        diagonalInches: zod_1.z.number(),
+        ppi: zod_1.z.number().describe('Physical pixel density of the simulated panel (device px per inch).'),
+    })),
+    profiles: zod_1.z.array(zod_1.z.object({
+        id: zod_1.z.string(),
+        label: zod_1.z.string(),
+        contrastRatio: zod_1.z.number().nullable(),
+        gamutCoverage: zod_1.z.number(),
+        bits: zod_1.z.number(),
+        frc: zod_1.z.boolean(),
+        nits: zod_1.z.number().nullable(),
+        summary: zod_1.z.string(),
+    })),
+};
+// --- server ------------------------------------------------------------------
+const server = new mcp_js_1.McpServer({ name: 'obsrv-mcp-server', version: VERSION });
+server.registerTool('obsrv_snap', {
+    title: 'Render a URL on a target screen',
+    description: `Render a URL headlessly at a target screen's true raster density — a real 1x raster for laptop/desktop ` +
+        `presets, the device's 2x/3x DPR plus mobile UA and viewport semantics for phone presets — optionally ` +
+        `through a cheap-panel simulation, and return the PNG. Use it to judge how a page actually looks on the ` +
+        `screens users own (1366×768 laptops, 1080p desktops, budget Androids) before declaring frontend work done.\n\n` +
+        `Pass either \`preset\` (list ids with obsrv_presets) or custom \`width\` + \`height\`, never both. ` +
+        `Returns structured metadata (applied viewport, profile, \`settled\`, warnings, and \`pngPath\` — the PNG ` +
+        `kept in a per-call temp dir) plus the PNG as an inline image when it is within the 1.5 MiB cap; larger ` +
+        `captures (typically fullPage) stay on disk with a note.`,
+    inputSchema: snapInputShape,
+    outputSchema: snapOutputShape,
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+}, async (input) => {
+    const badScheme = (0, lib_1.urlSchemeError)(input.url);
+    if (badScheme)
+        return toolError(badScheme);
+    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;
+    try {
+        args = (0, lib_1.buildSnapArgs)({ ...input, url: input.url.trim() }, pngPath);
+    }
+    catch (e) {
+        await (0, promises_1.rm)(dir, { recursive: true, force: true });
+        if (e instanceof lib_1.UsageError)
+            return toolError(e.message);
+        throw e;
+    }
+    const killAfterMs = (0, lib_1.killBudgetMs)(1, input.timeoutMs ?? args_1.DEFAULT_TIMEOUT_MS, input.waitMs ?? 0);
+    const run = await runCli(args, killAfterMs);
+    if (run.killed || run.code !== 0)
+        return cliFailure('snap', run, killAfterMs);
+    const meta = (0, lib_1.extractTrailingJson)(run.stdout);
+    if (!meta)
+        return toolError(`obsrv snap exited 0 but printed unparseable JSON: ${(0, lib_1.stderrTail)(run.stdout)}`);
+    const structured = { ...meta, pngPath };
+    return {
+        content: [
+            { type: 'text', text: JSON.stringify(structured, null, 2) },
+            await imageOrNote(pngPath, 'The captured PNG', 'retry without fullPage / with a smaller preset for an inline image'),
+        ],
+        structuredContent: structured,
+    };
+});
+server.registerTool('obsrv_diff', {
+    title: 'Diff a 1x render against its 2x reference',
+    description: `Numerically compare how a URL renders on a 1x screen against a 2x reference (the same CSS viewport at ` +
+        `dsf 2 — what a HiDPI dev sees — box-downsampled onto the target's 1x grid). Use it to confirm suspected ` +
+        `low-DPI legibility problems: thinning strokes, weakening hairlines, fading grey text.\n\n` +
+        `Returns ink coverage for target and reference (negative delta = the 1x render is losing ink), ink-row ` +
+        `counts and their ratio (≈0.5 is normal glyph scaling; a hairline contributes one row at any density), ` +
+        `8 horizontal band deltas with humanised findings (informational — apply your own thresholds), and the ` +
+        `paths of target.png / reference.png in a per-call temp dir. \`includeImages: true\` also inlines both ` +
+        `PNGs (1.5 MiB cap each).\n\n` +
+        `1x presets only (e.g. laptop-768, 1080p-24): dense presets (phones) and CSS viewports over 2048px are ` +
+        `refused with an explanatory error — use obsrv_snap for those.`,
+    inputSchema: diffInputShape,
+    outputSchema: diffOutputShape,
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+}, async (input) => {
+    const badScheme = (0, lib_1.urlSchemeError)(input.url);
+    if (badScheme)
+        return toolError(badScheme);
+    const dir = await (0, promises_1.mkdtemp)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'obsrv-mcp-'));
+    const args = (0, lib_1.buildDiffArgs)({ url: input.url.trim(), preset: input.preset, profile: input.profile, waitMs: input.waitMs, timeoutMs: input.timeoutMs }, dir);
+    // Two renders per diff: the target and its 2x reference.
+    const killAfterMs = (0, lib_1.killBudgetMs)(2, input.timeoutMs ?? args_1.DEFAULT_TIMEOUT_MS, input.waitMs ?? 0);
+    const run = await runCli(args, killAfterMs);
+    if (run.killed || run.code !== 0)
+        return cliFailure('diff', run, killAfterMs);
+    const metrics = (0, lib_1.extractTrailingJson)(run.stdout);
+    if (!metrics)
+        return toolError(`obsrv diff exited 0 but printed unparseable JSON: ${(0, lib_1.stderrTail)(run.stdout)}`);
+    const content = [{ type: 'text', text: JSON.stringify(metrics, null, 2) }];
+    if (input.includeImages) {
+        const files = metrics['files'];
+        content.push({ type: 'text', text: 'target.png (the 1x render, profile applied):' });
+        content.push(await imageOrNote(files.target, 'target.png', ''));
+        content.push({ type: 'text', text: 'reference.png (the 2x render downsampled onto the 1x grid):' });
+        content.push(await imageOrNote(files.reference, 'reference.png', ''));
+    }
+    return { content, structuredContent: metrics };
+});
+server.registerTool('obsrv_presets', {
+    title: 'List screen presets and panel profiles',
+    description: `List every screen preset (id, label, group, CSS dims, deviceScaleFactor, panel diagonal, derived physical ` +
+        `ppi) and panel profile (id, label, simulation params) accepted by obsrv_snap and obsrv_diff. Read straight ` +
+        `from the app's preset table — nothing is rendered.`,
+    inputSchema: {},
+    outputSchema: presetsOutputShape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+}, async () => {
+    const catalog = (0, lib_1.listCatalog)();
+    return {
+        content: [{ type: 'text', text: JSON.stringify(catalog, null, 2) }],
+        structuredContent: { ...catalog },
+    };
+});
+// --- boot --------------------------------------------------------------------
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    // stdout is the protocol channel; the one boot line goes to stderr.
+    process.stderr.write(`obsrv-mcp-server ${VERSION} running on stdio\n`);
+}
+main().catch((e) => {
+    process.stderr.write(`obsrv-mcp: fatal: ${e instanceof Error ? e.message : String(e)}\n`);
+    process.exit(1);
+});

package/out/preload/app.js

@@ -0,0 +1,87 @@
+"use strict";
+const electron = require("electron");
+const IPC = {
+  navigate: "obsrv:navigate",
+  reload: "obsrv:reload",
+  back: "obsrv:back",
+  forward: "obsrv:forward",
+  setViewport: "obsrv:set-viewport",
+  setNativeBounds: "obsrv:set-native-bounds",
+  setMode: "obsrv:set-mode",
+  sendInput: "obsrv:send-input",
+  getHostInfo: "obsrv:get-host-info",
+  getSettings: "obsrv:get-settings",
+  setSettings: "obsrv:set-settings",
+  frame: "obsrv:frame",
+  frameSubscribe: "obsrv:frame-subscribe",
+  urlChanged: "obsrv:url-changed",
+  loadError: "obsrv:load-error",
+  hostChanged: "obsrv:host-changed",
+  targetLoading: "obsrv:target-loading",
+  targetNavigating: "obsrv:target-navigating",
+  openImage: "obsrv:open-image",
+  focusUrl: "obsrv:focus-url",
+  openImagePath: "obsrv:open-image-path",
+  readImageFile: "obsrv:read-image-file"
+};
+function subscribe(channel, cb) {
+  const listener = (_e, v) => cb(v);
+  electron.ipcRenderer.on(channel, listener);
+  return () => {
+    electron.ipcRenderer.removeListener(channel, listener);
+  };
+}
+let frameSubscribers = 0;
+function subscribeFrames(cb) {
+  const off = subscribe(IPC.frame, cb);
+  if (++frameSubscribers === 1) electron.ipcRenderer.send(IPC.frameSubscribe);
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    frameSubscribers--;
+    off();
+  };
+}
+const api = {
+  navigate: (url) => electron.ipcRenderer.invoke(IPC.navigate, url),
+  reload: () => electron.ipcRenderer.send(IPC.reload),
+  back: () => electron.ipcRenderer.send(IPC.back),
+  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),
+  setMode: (mode) => electron.ipcRenderer.send(IPC.setMode, mode),
+  sendInput: (ev) => electron.ipcRenderer.send(IPC.sendInput, ev),
+  getHostInfo: () => electron.ipcRenderer.invoke(IPC.getHostInfo),
+  getSettings: () => electron.ipcRenderer.invoke(IPC.getSettings),
+  setSettings: (s) => electron.ipcRenderer.invoke(IPC.setSettings, s),
+  onFrame: subscribeFrames,
+  onUrlChanged: (cb) => subscribe(IPC.urlChanged, cb),
+  onLoadError: (cb) => subscribe(IPC.loadError, cb),
+  onHostChanged: (cb) => subscribe(IPC.hostChanged, cb),
+  onTargetLoading: (cb) => subscribe(IPC.targetLoading, cb),
+  onTargetNavigating: (cb) => {
+    const listener = () => cb();
+    electron.ipcRenderer.on(IPC.targetNavigating, listener);
+    return () => {
+      electron.ipcRenderer.removeListener(IPC.targetNavigating, listener);
+    };
+  },
+  onOpenImage: (cb) => {
+    const listener = () => cb();
+    electron.ipcRenderer.on(IPC.openImage, listener);
+    return () => {
+      electron.ipcRenderer.removeListener(IPC.openImage, listener);
+    };
+  },
+  onFocusUrl: (cb) => {
+    const listener = () => cb();
+    electron.ipcRenderer.on(IPC.focusUrl, listener);
+    return () => {
+      electron.ipcRenderer.removeListener(IPC.focusUrl, listener);
+    };
+  },
+  onOpenImagePath: (cb) => subscribe(IPC.openImagePath, cb),
+  readImageFile: (path) => electron.ipcRenderer.invoke(IPC.readImageFile, path)
+};
+electron.contextBridge.exposeInMainWorld("obsrv", api);

package/out/preload/sync.js

@@ -0,0 +1,41 @@
+"use strict";
+const electron = require("electron");
+const SUPPRESS_MS = 120;
+const SYNC_SCROLL = "obsrv:sync-scroll";
+const APPLY_SCROLL = "obsrv:apply-scroll";
+let suppressUntil = 0;
+let lastApplied = null;
+let rafId = 0;
+let deferred = null;
+function report() {
+  rafId = 0;
+  const remaining = suppressUntil - performance.now();
+  if (remaining > 0) {
+    if (deferred === null) {
+      deferred = setTimeout(() => {
+        deferred = null;
+        report();
+      }, remaining);
+    }
+    return;
+  }
+  const x = window.scrollX;
+  const y = window.scrollY;
+  if (lastApplied && lastApplied.x === x && lastApplied.y === y) return;
+  lastApplied = null;
+  electron.ipcRenderer.send(SYNC_SCROLL, { x, y });
+}
+window.addEventListener(
+  "scroll",
+  () => {
+    if (rafId !== 0) return;
+    rafId = requestAnimationFrame(report);
+  },
+  { 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);
+});