getobsrv 0.3.1 → 0.4.0

package/out/mcp/server.js

@@ -9,7 +9,9 @@ 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 control_1 = require("../shared/control");
 const presets_1 = require("../shared/presets");
+const control_2 = require("./control");
 const lib_1 = require("./lib");
 /**
  * Obsrv MCP server (stdio, stateless): three read-only tools wrapping the
@@ -116,17 +118,33 @@ const snapInputShape = {
         .min(1)
         .optional()
         .describe(`Per-render budget for load + paint quiescence, in ms. Default ${args_1.DEFAULT_TIMEOUT_MS}.`),
+    mode: zod_1.z
+        .enum(['auto', 'headless', 'live'])
+        .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.'),
 };
 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.'),
+    mode: zod_1.z
+        .enum(['headless', 'live'])
+        .describe('How the snap was produced: a headless render, or a capture of the visible Obsrv app window (live drive).'),
+    out: zod_1.z.string().optional().describe('Headless only: PNG path the CLI wrote (same file as pngPath).'),
+    preset: zod_1.z.string().optional().describe('Headless only: preset id, or "custom" for width/height runs.'),
+    cssWidth: zod_1.z.number().optional().describe('Headless only: applied CSS viewport width.'),
+    cssHeight: zod_1.z.number().optional().describe('Headless only: applied CSS viewport height (grown under fullPage).'),
+    deviceScaleFactor: zod_1.z.number().optional().describe('Headless only.'),
+    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.'),
     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.'),
 };
 const diffInputShape = {
     url: urlField,
@@ -187,6 +205,122 @@ const presetsOutputShape = {
         summary: zod_1.z.string(),
     })),
 };
+const driveInputShape = {
+    url: zod_1.z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Navigate the app (both panes) to this http://, https:// or file:// URL (bare hosts also work).'),
+    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."),
+};
+const driveOutputShape = {
+    version: zod_1.z.string().describe('The running app version.'),
+    url: zod_1.z.string().describe('The URL the target pane reports showing.'),
+    presetId: zod_1.z.string(),
+    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)."),
+};
+// --- live drive --------------------------------------------------------------
+/** Budget for one control `status` round-trip once the app is known live. */
+const LIVE_STATUS_TIMEOUT_MS = 2_000;
+/** Budget for a preset/profile/view-mode apply (the server confirms, bounded). */
+const LIVE_APPLY_TIMEOUT_MS = 5_000;
+/** Budget for `captureVisible` (a full-window PNG over loopback). */
+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;
+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, ` +
+        `re-open the app and re-enable the toolbar toggle — or pass mode: "headless".`);
+}
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+/**
+ * The live `obsrv_snap` path: navigate the visible app (plus preset/profile
+ * when given), wait — bounded — for the app to report the navigation, then
+ * capture the window exactly as the user sees it.
+ */
+async function liveSnap(app, input, notes) {
+    const { info } = app;
+    const warnings = [...notes];
+    const before = app.status.url;
+    let applied = '';
+    try {
+        // The navigate command answers once both panes finished loading, so it
+        // carries the same per-render budget the headless path polices.
+        const nav = await (0, control_2.controlCall)(info, 'navigate', { url: input.url.trim() }, (input.timeoutMs ?? args_1.DEFAULT_TIMEOUT_MS) + 10_000);
+        applied = typeof nav['url'] === 'string' ? nav['url'] : '';
+        if (input.preset !== undefined)
+            await (0, control_2.controlCall)(info, 'setPreset', { id: input.preset }, LIVE_APPLY_TIMEOUT_MS);
+        if (input.profile !== undefined)
+            await (0, control_2.controlCall)(info, 'setProfile', { id: input.profile }, LIVE_APPLY_TIMEOUT_MS);
+    }
+    catch (e) {
+        return toolError(liveFailure(e));
+    }
+    // The app settles when it reports the applied URL — or, after a redirect,
+    // any committed non-blank URL that is no longer the pre-navigation one.
+    let status = app.status;
+    let settled = false;
+    const deadline = Date.now() + LIVE_SETTLE_MS;
+    for (;;) {
+        try {
+            const s = (0, control_1.parseControlStatus)(await (0, control_2.controlCall)(info, 'status', {}, LIVE_STATUS_TIMEOUT_MS));
+            if (s) {
+                status = s;
+                settled = s.url === applied || (applied !== '' && s.url !== before && s.url !== 'about:blank');
+            }
+        }
+        catch (e) {
+            return toolError(liveFailure(e));
+        }
+        if (settled || Date.now() >= deadline)
+            break;
+        await sleep(250);
+    }
+    if (!settled)
+        warnings.push('the app did not confirm the navigation before capture; the PNG may show the previous page.');
+    // One short grace after the state settles: the renderer repaints the pane
+    // (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);
+    let capture;
+    try {
+        capture = await (0, control_2.controlCall)(info, 'captureVisible', {}, LIVE_CAPTURE_TIMEOUT_MS);
+    }
+    catch (e) {
+        return toolError(liveFailure(e));
+    }
+    const { data, width, height } = capture;
+    if (typeof data !== 'string' || typeof width !== 'number' || typeof height !== 'number') {
+        return toolError('the control server returned a malformed capture');
+    }
+    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'));
+    const structured = {
+        mode: 'live',
+        url: status.url,
+        presetId: status.presetId,
+        profileId: status.profileId,
+        viewMode: status.viewMode,
+        width,
+        height,
+        settled,
+        warnings,
+        pngPath,
+    };
+    return {
+        content: [
+            { type: 'text', text: JSON.stringify(structured, null, 2) },
+            await imageOrNote(pngPath, 'The captured app window', 'read the file at pngPath'),
+        ],
+        structuredContent: structured,
+    };
+}
 // --- server ------------------------------------------------------------------
 const server = new mcp_js_1.McpServer({ name: 'obsrv-mcp-server', version: VERSION });
 server.registerTool('obsrv_snap', {
@@ -198,7 +332,15 @@ server.registerTool('obsrv_snap', {
         `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.`,
+        `captures (typically fullPage) stay on disk with a note.\n\n` +
+        `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 ` +
+        `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 ` +
+        `capture; that visible steering is the point of live mode.`,
     inputSchema: snapInputShape,
     outputSchema: snapOutputShape,
     annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
@@ -206,6 +348,20 @@ server.registerTool('obsrv_snap', {
     const badScheme = (0, lib_1.urlSchemeError)(input.url);
     if (badScheme)
         return toolError(badScheme);
+    // The live path first (spec §14 "Live drive"): a reachable control-enabled
+    // app wins under auto, is required under live, and is never probed under
+    // headless. planSnapPath documents the fallback rules.
+    const requestedMode = input.mode ?? 'auto';
+    let liveNotes = [];
+    if (requestedMode !== 'headless') {
+        const live = await (0, control_2.discoverControl)();
+        const plan = (0, lib_1.planSnapPath)(input, requestedMode, live !== null);
+        if ('error' in plan)
+            return toolError(plan.error);
+        if (plan.path === 'live' && live)
+            return liveSnap(live, input, plan.notes);
+        liveNotes = plan.notes;
+    }
     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;
@@ -225,7 +381,8 @@ server.registerTool('obsrv_snap', {
     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 };
+    const cliWarnings = Array.isArray(meta['warnings']) ? meta['warnings'] : [];
+    const structured = { ...meta, mode: 'headless', warnings: [...cliWarnings, ...liveNotes], pngPath };
     return {
         content: [
             { type: 'text', text: JSON.stringify(structured, null, 2) },
@@ -245,7 +402,10 @@ server.registerTool('obsrv_diff', {
         `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.`,
+        `refused with an explanatory error — use obsrv_snap for those.\n\n` +
+        `Headless-only: a diff always performs its own two renders and never drives a running Obsrv app window ` +
+        `(the comparison needs both rasters, which the visible app cannot show) — use obsrv_snap or obsrv_drive ` +
+        `for live drive.`,
     inputSchema: diffInputShape,
     outputSchema: diffOutputShape,
     annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
@@ -273,6 +433,51 @@ server.registerTool('obsrv_diff', {
     }
     return { content, structuredContent: metrics };
 });
+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` +
+        `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.`,
+    inputSchema: driveInputShape,
+    outputSchema: driveOutputShape,
+    // Honest annotation: this changes what the user's window is showing.
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+}, async (input) => {
+    if (input.url !== undefined) {
+        const badScheme = (0, lib_1.urlSchemeError)(input.url);
+        if (badScheme)
+            return toolError(badScheme);
+    }
+    const live = await (0, control_2.discoverControl)();
+    if (!live)
+        return toolError(lib_1.APP_NOT_REACHABLE);
+    try {
+        if (input.url !== undefined) {
+            await (0, control_2.controlCall)(live.info, 'navigate', { url: input.url.trim() }, args_1.DEFAULT_TIMEOUT_MS + 10_000);
+        }
+        if (input.preset !== undefined)
+            await (0, control_2.controlCall)(live.info, 'setPreset', { id: input.preset }, LIVE_APPLY_TIMEOUT_MS);
+        if (input.profile !== undefined)
+            await (0, control_2.controlCall)(live.info, 'setProfile', { id: input.profile }, LIVE_APPLY_TIMEOUT_MS);
+        if (input.viewMode !== undefined) {
+            await (0, control_2.controlCall)(live.info, 'setViewMode', { mode: input.viewMode }, 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');
+        return {
+            content: [{ type: 'text', text: JSON.stringify(status, null, 2) }],
+            structuredContent: { ...status },
+        };
+    }
+    catch (e) {
+        return toolError(liveFailure(e));
+    }
+});
 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 ` +

package/out/preload/app.js

@@ -22,7 +22,10 @@ const IPC = {
   openImage: "obsrv:open-image",
   focusUrl: "obsrv:focus-url",
   openImagePath: "obsrv:open-image-path",
-  readImageFile: "obsrv:read-image-file"
+  readImageFile: "obsrv:read-image-file",
+  uiState: "obsrv:ui-state",
+  agentApply: "obsrv:agent-apply",
+  agentActivity: "obsrv:agent-activity"
 };
 function subscribe(channel, cb) {
   const listener = (_e, v) => cb(v);
@@ -82,6 +85,15 @@ const api = {
     };
   },
   onOpenImagePath: (cb) => subscribe(IPC.openImagePath, cb),
-  readImageFile: (path) => electron.ipcRenderer.invoke(IPC.readImageFile, path)
+  readImageFile: (path) => electron.ipcRenderer.invoke(IPC.readImageFile, path),
+  reportUiState: (s) => electron.ipcRenderer.send(IPC.uiState, s),
+  onAgentApply: (cb) => subscribe(IPC.agentApply, cb),
+  onAgentActivity: (cb) => {
+    const listener = () => cb();
+    electron.ipcRenderer.on(IPC.agentActivity, listener);
+    return () => {
+      electron.ipcRenderer.removeListener(IPC.agentActivity, listener);
+    };
+  }
 };
 electron.contextBridge.exposeInMainWorld("obsrv", api);

package/out/renderer/assets/{index-VleEBVgL.css → index-FtoKShe_.css}

@@ -251,11 +251,25 @@ html, body, #root { margin: 0; height: 100%; background: var(--chrome-0); color:
 .num { font-family: var(--mono); font-variant-numeric: tabular-nums; }
 
 /* An open drawer's button: weight and a 1px border, not hue. */
-.toolbar :is(.toggle-panel, .toggle-settings)[aria-pressed='true'] {
+.toolbar :is(.toggle-panel, .toggle-settings, .agent-toggle)[aria-pressed='true'] {
   border-color: var(--text-0);
   background: var(--chrome-1);
 }
 
+/* Agent control: same neutral chrome as every other toggle; the activity
+   badge is text-weight only — an agent driving the window is a status, not
+   an alert. */
+.toolbar .agent-toggle { width: auto; padding: 0 8px; white-space: nowrap; }
+.agent-activity {
+  color: var(--text-1);
+  border: 1px solid var(--line);
+  border-radius: 4px;
+  padding: 1px 6px;
+  font-size: 11px;
+  letter-spacing: 0.5px;
+  white-space: nowrap;
+}
+
 /* Drawers sit beside the panes, never over them: the native WebContentsView is
    an OS-level overlay and would cover anything painted on top of it. */
 .body { flex: 1 1 auto; display: flex; min-height: 0; }

package/out/renderer/assets/{index-BAEO9_6W.js → index-P496vEhv.js}

@@ -12688,7 +12688,7 @@ const createImpl = (createState) => {
 };
 const create = ((createState) => createImpl);
 const MAX_VIEWPORT = 4096;
-const DEFAULT_SETTINGS = { hostDiagonalInches: 27, hostNits: 500 };
+const DEFAULT_SETTINGS = { hostDiagonalInches: 27, hostNits: 500, agentControl: false };
 const SCREEN_PRESETS = [
   // Laptops — ordered largest to smallest panel, then the denser 1080p outlier.
   { id: "laptop-768", label: '1366×768 15.6"', width: 1366, height: 768, diagonalInches: 15.6, deviceScaleFactor: 1, group: "laptop" },
@@ -14172,8 +14172,29 @@ function Toolbar({ drawer, onTogglePanel, onToggleSettings }) {
   const setSurround = useStore((s) => s.setSurround);
   const viewMode = useStore((s) => s.viewMode);
   const setViewMode = useStore((s) => s.setViewMode);
+  const agentControl = useStore((s) => s.settings.agentControl);
+  const setSettings = useStore((s) => s.setSettings);
   const inputRef = reactExports.useRef(null);
   const [draft, setDraft] = reactExports.useState(barText);
+  const [agentActive, setAgentActive] = reactExports.useState(false);
+  reactExports.useEffect(() => {
+    let timer;
+    const off = window.obsrv.onAgentActivity(() => {
+      setAgentActive(true);
+      clearTimeout(timer);
+      timer = setTimeout(() => setAgentActive(false), 3e3);
+    });
+    return () => {
+      clearTimeout(timer);
+      off();
+    };
+  }, []);
+  const toggleAgent = () => {
+    const current = useStore.getState().settings;
+    const next = { ...current, agentControl: !current.agentControl };
+    setSettings(next);
+    window.obsrv.setSettings(next).catch(() => setSettings(current));
+  };
   const lastMode = reactExports.useRef(mode);
   reactExports.useEffect(() => {
     const modeChanged = lastMode.current !== mode;
@@ -14290,6 +14311,19 @@ function Toolbar({ drawer, onTogglePanel, onToggleSettings }) {
       },
       s.id
     )) }),
+    agentActive && /* @__PURE__ */ jsxRuntimeExports.jsx("span", { className: "agent-activity", children: "AGENT" }),
+    /* @__PURE__ */ jsxRuntimeExports.jsx(
+      "button",
+      {
+        className: "agent-toggle",
+        type: "button",
+        title: "Agent control — let a local agent drive this window",
+        "aria-label": "Agent control",
+        "aria-pressed": agentControl,
+        onClick: toggleAgent,
+        children: "Agent"
+      }
+    ),
     /* @__PURE__ */ jsxRuntimeExports.jsx(
       "button",
       {
@@ -14334,6 +14368,9 @@ function App() {
   const surround = useStore((s) => s.surround);
   const viewport = useStore(useShallow(selectViewport));
   const deviceScaleFactor = useStore(selectDeviceScaleFactor);
+  const presetId = useStore((s) => s.presetId);
+  const profileId = useStore((s) => s.profileId);
+  const viewMode = useStore((s) => s.viewMode);
   reactExports.useEffect(() => {
     window.obsrv.getHostInfo().then(setHost, (e) => console.warn("obsrv: getHostInfo failed", e));
     window.obsrv.getSettings().then(setSettings, (e) => console.warn("obsrv: getSettings failed", e));
@@ -14359,6 +14396,17 @@ function App() {
   reactExports.useEffect(() => {
     window.obsrv.setMode(mode);
   }, [mode]);
+  reactExports.useEffect(() => {
+    window.obsrv.reportUiState({ presetId, profileId, viewMode, mode });
+  }, [presetId, profileId, viewMode, mode]);
+  reactExports.useEffect(() => {
+    return window.obsrv.onAgentApply((patch) => {
+      const s = useStore.getState();
+      if (patch.presetId !== void 0) s.setPreset(patch.presetId);
+      if (patch.profileId !== void 0) s.setProfile(patch.profileId);
+      if (patch.viewMode !== void 0) s.setViewMode(patch.viewMode);
+    });
+  }, []);
   reactExports.useEffect(() => {
     document.documentElement.dataset.surround = surround;
   }, [surround]);

package/out/renderer/index.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta http-equiv="Content-Security-Policy" content="default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' blob: data:" />
     <title>Obsrv</title>
-    <script type="module" crossorigin src="./assets/index-BAEO9_6W.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-VleEBVgL.css">
+    <script type="module" crossorigin src="./assets/index-P496vEhv.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-FtoKShe_.css">
   </head>
   <body>
     <div id="root"></div>

package/out/shared/control.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTROL_COMMANDS = exports.CONTROL_TOKEN_BYTES = exports.CONTROL_FILE_NAME = void 0;
+exports.isControlCommand = isControlCommand;
+exports.parseControlFile = parseControlFile;
+exports.controlFileModeOk = controlFileModeOk;
+exports.tokenEqual = tokenEqual;
+exports.defaultControlFilePath = defaultControlFilePath;
+exports.presetApplyError = presetApplyError;
+exports.profileApplyError = profileApplyError;
+exports.viewModeApplyError = viewModeApplyError;
+exports.parseControlStatus = parseControlStatus;
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const presets_1 = require("./presets");
+/**
+ * The agent-control protocol shared by the main-process control server
+ * (`src/main/controlServer.ts`) and the MCP discovery client
+ * (`src/mcp/control.ts`): discovery-file shape, token comparison, command
+ * names and payload validation. Pure node — no Electron, no I/O — so
+ * everything here runs under plain node and is unit-tested in
+ * tests/unit/control.test.ts.
+ *
+ * Renderer code imports *types* from this module only; the `node:crypto`
+ * import never reaches a browser bundle.
+ *
+ * Security decisions (spec §14 "Live drive"):
+ * - The server binds 127.0.0.1 only, on an ephemeral port.
+ * - Every command — `status` included — carries the bearer token from the
+ *   discovery file. The file is mode 0600 in the app's own userData dir, so
+ *   possession already proves "same user"; a token-free status would only
+ *   leak app state to other local users for no benefit.
+ * - No command accepts file paths, JavaScript, or IPC channel names; every
+ *   payload is validated against the same tables the app itself uses.
+ */
+/** Discovery file the app writes to `app.getPath('userData')` while agent control is on. */
+exports.CONTROL_FILE_NAME = 'control.json';
+/** Bearer-token entropy; hex-encoded in the discovery file (64 chars). */
+exports.CONTROL_TOKEN_BYTES = 32;
+const TOKEN_RE = /^[0-9a-f]{64}$/;
+exports.CONTROL_COMMANDS = [
+    'status',
+    'navigate',
+    'setPreset',
+    'setProfile',
+    'setViewMode',
+    'captureVisible',
+];
+function isControlCommand(v) {
+    return typeof v === 'string' && exports.CONTROL_COMMANDS.includes(v);
+}
+const isRecord = (v) => typeof v === 'object' && v !== null;
+/**
+ * Parses a discovery file's contents. Strict: a malformed file (bad JSON,
+ * out-of-range port, a token that is not 64 hex chars) yields null — the
+ * client must treat the app as not reachable rather than send credentials
+ * derived from a file something else may have written.
+ */
+function parseControlFile(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(parsed))
+        return null;
+    const { port, token } = parsed;
+    if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65535)
+        return null;
+    if (typeof token !== 'string' || !TOKEN_RE.test(token))
+        return null;
+    return { port, token };
+}
+/**
+ * Whether a discovery file's permission bits are acceptable: no group or
+ * other access on POSIX (the app writes it 0600). Windows has no POSIX mode
+ * bits worth reading, so everything passes there.
+ */
+function controlFileModeOk(mode, platform) {
+    if (platform === 'win32')
+        return true;
+    return (mode & 0o077) === 0;
+}
+/**
+ * Constant-time bearer-token comparison. Both sides are hashed first so
+ * `timingSafeEqual` always gets equal-length inputs — a length mismatch must
+ * not throw or short-circuit into a timing signal.
+ */
+function tokenEqual(expected, provided) {
+    if (typeof provided !== 'string')
+        return false;
+    const a = (0, node_crypto_1.createHash)('sha256').update(expected).digest();
+    const b = (0, node_crypto_1.createHash)('sha256').update(provided).digest();
+    return (0, node_crypto_1.timingSafeEqual)(a, b);
+}
+/**
+ * Where the app's discovery file lives for a given platform, derived the way
+ * Electron derives `app.getPath('userData')` for productName "Obsrv" — the
+ * MCP server runs under plain node and cannot ask Electron.
+ */
+function defaultControlFilePath(platform, env, home) {
+    const appDir = platform === 'darwin'
+        ? (0, node_path_1.join)(home, 'Library', 'Application Support', 'Obsrv')
+        : platform === 'win32'
+            ? (0, node_path_1.join)(env['APPDATA'] ?? (0, node_path_1.join)(home, 'AppData', 'Roaming'), 'Obsrv')
+            : (0, node_path_1.join)(env['XDG_CONFIG_HOME'] ?? (0, node_path_1.join)(home, '.config'), 'Obsrv');
+    return (0, node_path_1.join)(appDir, exports.CONTROL_FILE_NAME);
+}
+const idList = (ids) => ids.join(', ');
+/**
+ * Validates a `setPreset` payload id. The custom preset is refused: it is
+ * defined by the renderer's own width/height/diagonal fields, so "apply
+ * custom" from outside would apply whatever happened to be typed there.
+ */
+function presetApplyError(id) {
+    if (typeof id !== 'string')
+        return 'setPreset payload must be { id: string }';
+    if (id === 'custom') {
+        return 'the custom preset cannot be applied remotely — it is defined by the fields in the app; pick a preset id';
+    }
+    if (!presets_1.SCREEN_PRESETS.some(p => p.id === id)) {
+        return `unknown preset "${id}" — valid ids: ${idList(presets_1.SCREEN_PRESETS.map(p => p.id))}`;
+    }
+    return null;
+}
+function profileApplyError(id) {
+    if (typeof id !== 'string')
+        return 'setProfile payload must be { id: string }';
+    if (!presets_1.PANEL_PROFILES.some(p => p.id === id)) {
+        return `unknown profile "${id}" — valid ids: ${idList(presets_1.PANEL_PROFILES.map(p => p.id))}`;
+    }
+    return null;
+}
+function viewModeApplyError(v) {
+    return v === '1:1' || v === 'fit' ? null : `setViewMode payload must be { mode: '1:1' | 'fit' }`;
+}
+/** Validates a control server `status` response on the client side. */
+function parseControlStatus(raw) {
+    if (!isRecord(raw))
+        return null;
+    const { version, url, presetId, profileId, viewMode, mode } = raw;
+    if (typeof version !== 'string' || typeof url !== 'string')
+        return null;
+    if (typeof presetId !== 'string' || typeof profileId !== 'string')
+        return null;
+    if (viewMode !== '1:1' && viewMode !== 'fit')
+        return null;
+    if (mode !== 'url' && mode !== 'image')
+        return null;
+    return { version, url, presetId, profileId, viewMode, mode };
+}

package/out/shared/presets.js

@@ -4,7 +4,7 @@ exports.PANEL_PROFILES = exports.SCREEN_PRESETS = exports.DEFAULT_SETTINGS = exp
 exports.findPreset = findPreset;
 exports.findProfile = findProfile;
 exports.MAX_VIEWPORT = 4096;
-exports.DEFAULT_SETTINGS = { hostDiagonalInches: 27, hostNits: 500 };
+exports.DEFAULT_SETTINGS = { hostDiagonalInches: 27, hostNits: 500, agentControl: false };
 exports.SCREEN_PRESETS = [
     // Laptops — ordered largest to smallest panel, then the denser 1080p outlier.
     { id: 'laptop-768', label: '1366×768 15.6"', width: 1366, height: 768, diagonalInches: 15.6, deviceScaleFactor: 1, group: 'laptop' },

package/out/shared/url.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALLOWED_URL_SCHEMES = void 0;
+exports.normalizeUrl = normalizeUrl;
+exports.urlSchemeError = urlSchemeError;
+/** `scheme:` prefix, e.g. `https:`, `about:`, `file:`. */
+const SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+/** Loopback host with optional port, e.g. `localhost:5173`, `127.0.0.1/a`. */
+const LOOPBACK = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?(\/|$)/i;
+/**
+ * Turn URL-bar input into an absolute, loadable URL.
+ * Loopback is checked before the scheme test because `localhost:5173`
+ * parses as scheme `localhost` otherwise.
+ */
+function normalizeUrl(input) {
+    const s = input.trim();
+    if (s === '')
+        throw new Error('empty url');
+    if (/\s/.test(s))
+        throw new Error('invalid URL');
+    if (s.startsWith('/'))
+        return `file://${s}`;
+    if (LOOPBACK.test(s))
+        return `http://${s}`;
+    if (SCHEME.test(s))
+        return s;
+    return `https://${s}`;
+}
+/** Schemes an agent-facing entry point (MCP tool, control server) may load. */
+exports.ALLOWED_URL_SCHEMES = ['http:', 'https:', 'file:'];
+/**
+ * Rejects URLs whose explicit scheme is outside the allowlist (javascript:,
+ * data:, chrome:, …) with an actionable message, or returns null when the URL
+ * may proceed. Scheme-relative (`//host`), bare-host (`example.com/page`) and
+ * host:port (`localhost:5173`) forms pass — they normalise to http(s)
+ * downstream. Shared by the MCP tools and the agent-control server, so the
+ * app's URL bar stays the only surface that can reach another scheme.
+ */
+function urlSchemeError(url) {
+    const trimmed = url.trim();
+    const match = /^([a-z][a-z0-9+.-]*):/i.exec(trimmed);
+    if (!match)
+        return null; // bare host or scheme-relative
+    const scheme = `${match[1].toLowerCase()}:`;
+    if (exports.ALLOWED_URL_SCHEMES.includes(scheme))
+        return null;
+    // `localhost:5173`-style host:port, not a scheme: the "scheme" is followed
+    // by a bare port number.
+    if (/^[a-z0-9.-]+:\d+(\/|$)/i.test(trimmed))
+        return null;
+    return (`unsupported URL scheme "${scheme}" — obsrv renders ` +
+        `${exports.ALLOWED_URL_SCHEMES.map(s => `${s}//`).join(', ')} URLs only ` +
+        `(bare hosts like example.com also work; they normalise to http(s)).`);
+}