amalgm 0.1.91 → 0.1.92

package/runtime/scripts/amalgm-mcp/browser/recorder.js

@@ -3,15 +3,18 @@
 /**
  * Session recorder: capture any browser session to a local WebM file.
  *
- * Implementation is a direct CDP Page.startScreencast consumer piped into
- * ffmpeg (ffmpeg-static when bundled, PATH ffmpeg otherwise). This is
- * deliberately NOT agent-browser's `record` command:
+ * Frames come from capture.js (CDP Page.startScreencast on a target that
+ * actually rasters — the page itself headless, the app window cropped to the
+ * webview rectangle when attached) and pipe into ffmpeg. Recordings are
+ * local-only: nothing leaves this computer, and in attached mode the crop
+ * runs inside ffmpeg before any frame reaches disk, so the file only ever
+ * contains the page — not the app around it.
+ *
+ * This is deliberately NOT agent-browser's `record` command:
  *  - `record` needs ffmpeg on the daemon's PATH at daemon-spawn time, and
  *    silently "starts" even when ffmpeg is missing (fails only on stop).
  *  - `record` calls Target.createBrowserContext, which Electron forbids — so
  *    it can never capture the visible in-tab webview.
- * A raw screencast works against every CDP target we care about: launched
- * chromium AND the desktop app's splitscreen webview.
  *
  * Storage: recordings belong to the Amalgm project the work is for —
  * <project>/.amalgm/recordings/ when a project path is known, otherwise
@@ -23,9 +26,13 @@ const path = require('path');
 const { spawn } = require('child_process');
 
 const cli = require('./cli');
-const engine = require('./engine');
+const backend = require('./backend');
+const capture = require('./capture');
+const sessions = require('./sessions');
+
+const active = new Map(); // session -> { cdp, ffmpeg, file, frames, startedAt }
 
-const active = new Map(); // session -> { ws, ffmpeg, file, frames, startedAt }
+const FFMPEG_CLOSE_TIMEOUT_MS = 10_000;
 
 function ffmpegBinary() {
   if (process.env.AMALGM_FFMPEG) return process.env.AMALGM_FFMPEG;
@@ -88,34 +95,8 @@ function recordingFile(args, context, session) {
   return path.join(recordingDir(args, context, session), `${name}-${stamp}.webm`);
 }
 
-/**
- * Page.startScreencast only works on a page-level CDP connection. Launched
- * sessions report a browser-level ws URL, so resolve the active page target
- * through the /json/list endpoint on the same debugger port.
- */
-async function pageWsUrl(wsUrl) {
-  if (!/\/devtools\/browser\//.test(wsUrl)) return wsUrl;
-  const { hostname, port } = new URL(wsUrl);
-  const list = await new Promise((resolve, reject) => {
-    const http = require('http');
-    const req = http.get({ hostname, port, path: '/json/list', timeout: 5_000 }, (res) => {
-      let raw = '';
-      res.on('data', (chunk) => { raw += chunk.toString(); });
-      res.on('end', () => {
-        try { resolve(JSON.parse(raw)); } catch (err) { reject(err); }
-      });
-    });
-    req.on('error', reject);
-    req.on('timeout', () => req.destroy(new Error('Timed out listing CDP targets')));
-  });
-  const page = list.find((t) => t.type === 'webview' && t.webSocketDebuggerUrl)
-    || list.find((t) => t.type === 'page' && t.webSocketDebuggerUrl && !t.url.startsWith('devtools://'));
-  if (!page) throw new Error('No recordable page target found on the CDP endpoint.');
-  return page.webSocketDebuggerUrl;
-}
-
 async function start(args = {}, context = {}) {
-  const session = engine.sessionFor(args, context);
+  const session = sessions.sessionFor(args, context);
   if (active.has(session)) {
     throw new Error(`Recording already active for session "${session}". Call record_stop first.`);
   }
@@ -124,30 +105,29 @@ async function start(args = {}, context = {}) {
   // and a clean refusal beats a half-started recording.
   const binary = ensureFfmpeg();
 
-  const rawUrl = await engine.cdpUrlForSession(session);
-  if (!rawUrl) throw new Error('Could not resolve a CDP endpoint for this browser session.');
-  const wsUrl = await pageWsUrl(rawUrl);
+  // Where frames come from — and, in attached mode, the crop that keeps the
+  // surrounding app UI out of the file. Resolved with hard deadlines.
+  const source = await capture.plan(session, context);
 
-  const WebSocket = require('ws');
   const file = recordingFile(args, context, session);
   const fps = Math.min(Math.max(Number(args.fps) || 10, 1), 30);
+  const filters = [source.crop, 'pad=ceil(iw/2)*2:ceil(ih/2)*2'].filter(Boolean).join(',');
 
   const ffmpeg = spawn(binary, [
     '-y', '-f', 'image2pipe', '-c:v', 'mjpeg', '-framerate', String(fps), '-i', 'pipe:0',
-    '-vf', 'pad=ceil(iw/2)*2:ceil(ih/2)*2', '-c:v', 'libvpx', '-pix_fmt', 'yuv420p', file,
+    '-vf', filters, '-c:v', 'libvpx', '-pix_fmt', 'yuv420p', file,
   ], { stdio: ['pipe', 'ignore', 'pipe'] });
   let ffmpegErr = '';
   ffmpeg.stderr.on('data', (chunk) => { ffmpegErr = (ffmpegErr + chunk.toString()).slice(-2000); });
 
-  const ws = new WebSocket(wsUrl, { perMessageDeflate: false });
-  const recording = { ws, ffmpeg, file, frames: 0, startedAt: Date.now(), ffmpegErr: () => ffmpegErr };
+  const recording = { cdp: null, ffmpeg, file, frames: 0, startedAt: Date.now(), ffmpegErr: () => ffmpegErr };
 
   // Failures after the preflight (binary swapped out, EMFILE, ffmpeg dying
   // mid-recording and EPIPE-ing stdin) end this recording, not the server.
   ffmpeg.on('error', (err) => {
     ffmpegErr = `${err.message}${ffmpegErr ? ` ${ffmpegErr}` : ''}`;
     if (active.get(session) === recording) active.delete(session);
-    try { ws.close(); } catch {}
+    try { recording.cdp?.close(); } catch {}
   });
   ffmpeg.stdin.on('error', () => {
     // Swallow stream errors; stop() reports the failure via exit code + stderr.
@@ -155,54 +135,62 @@ async function start(args = {}, context = {}) {
 
   active.set(session, recording);
 
-  await new Promise((resolve, reject) => {
-    const timer = setTimeout(() => reject(new Error('Timed out connecting to browser CDP endpoint')), 10_000);
-    ws.on('open', () => { clearTimeout(timer); resolve(); });
-    ws.on('error', (err) => { clearTimeout(timer); reject(err); });
-  }).catch((err) => {
+  try {
+    recording.cdp = await capture.connectCdp(source.wsUrl);
+    recording.cdp.on('Page.screencastFrame', (params) => {
+      recording.frames += 1;
+      try { ffmpeg.stdin.write(Buffer.from(params.data, 'base64')); } catch {}
+      recording.cdp.send('Page.screencastFrameAck', { sessionId: params.sessionId });
+    });
+    await recording.cdp.call('Page.enable').catch(() => {});
+    await recording.cdp.call('Page.startScreencast', { format: 'jpeg', quality: 70, everyNthFrame: 1 });
+  } catch (err) {
     active.delete(session);
+    try { recording.cdp?.close(); } catch {}
     try { ffmpeg.kill('SIGKILL'); } catch {}
     throw err;
-  });
-
-  let id = 0;
-  const send = (method, params = {}) => ws.send(JSON.stringify({ id: ++id, method, params }));
-  ws.on('message', (raw) => {
-    let msg;
-    try { msg = JSON.parse(raw); } catch { return; }
-    if (msg.method === 'Page.screencastFrame') {
-      recording.frames += 1;
-      try { ffmpeg.stdin.write(Buffer.from(msg.params.data, 'base64')); } catch {}
-      send('Page.screencastFrameAck', { sessionId: msg.params.sessionId });
-    }
-  });
-  send('Page.enable');
-  send('Page.startScreencast', { format: 'jpeg', quality: 70, everyNthFrame: 1 });
+  }
 
-  return { session, path: file, fps, mimeType: 'video/webm', backend: engine.mode() };
+  return {
+    session,
+    path: file,
+    fps,
+    mimeType: 'video/webm',
+    backend: backend.mode(),
+    cropped: Boolean(source.crop),
+  };
 }
 
 async function stop(args = {}, context = {}) {
-  const session = engine.sessionFor(args, context);
+  const session = sessions.sessionFor(args, context);
   const recording = active.get(session);
   if (!recording) throw new Error(`No active recording for session "${session}".`);
   active.delete(session);
 
-  try {
-    recording.ws.send(JSON.stringify({ id: 9_999, method: 'Page.stopScreencast' }));
-  } catch {}
-  try { recording.ws.close(); } catch {}
+  try { recording.cdp?.send('Page.stopScreencast'); } catch {}
+  try { recording.cdp?.close(); } catch {}
 
+  // ffmpeg gets a bounded window to flush and finalize the container; a
+  // wedged encoder is killed rather than wedging record_stop.
   const exitCode = await new Promise((resolve) => {
-    recording.ffmpeg.on('close', resolve);
-    try { recording.ffmpeg.stdin.end(); } catch { resolve(-1); }
+    const killTimer = setTimeout(() => {
+      try { recording.ffmpeg.kill('SIGKILL'); } catch {}
+    }, FFMPEG_CLOSE_TIMEOUT_MS);
+    recording.ffmpeg.on('close', (code) => {
+      clearTimeout(killTimer);
+      resolve(code);
+    });
+    try { recording.ffmpeg.stdin.end(); } catch {
+      clearTimeout(killTimer);
+      resolve(-1);
+    }
   });
 
   const durationMs = Date.now() - recording.startedAt;
   if (recording.frames === 0 || exitCode !== 0) {
     try { fs.rmSync(recording.file, { force: true }); } catch {}
     throw new Error(recording.frames === 0
-      ? 'No frames captured — the page may not have repainted while recording. (Screencast only emits on visual change.)'
+      ? 'No frames captured — nothing repainted while recording (the screencast only emits on visual change).'
       : `ffmpeg failed (exit ${exitCode}): ${recording.ffmpegErr()}`);
   }
 
@@ -219,7 +207,7 @@ async function stop(args = {}, context = {}) {
 }
 
 function list(args = {}, context = {}) {
-  const session = engine.sessionFor(args, context);
+  const session = sessions.sessionFor(args, context);
   const dir = recordingDir(args, context, session);
   let entries = [];
   try {

package/runtime/scripts/amalgm-mcp/browser/sessions.js

@@ -0,0 +1,64 @@
+'use strict';
+
+/**
+ * Browser session identity and registry.
+ *
+ * A session is 1:1 with a durable profile directory; the default session id
+ * is the caller's chat session, so one conversation keeps one browser across
+ * tool calls without anyone passing ids around. Parallel sessions stay
+ * isolated because each gets its own agent-browser daemon and profile.
+ */
+
+const cli = require('./cli');
+const backend = require('./backend');
+
+/** Sessions that completed the attached-mode handshake (webview selected + focused). */
+const attachedSessions = new Set();
+
+/** Per-session bookkeeping: webviewTabId, lastActiveAt, last url/title. */
+const knownSessions = new Map();
+
+function sessionFor(args = {}, context = {}) {
+  return cli.safeId(
+    args.session
+      || args.profile
+      || args.browserProfileId
+      || args.browserSessionId
+      || args.sessionId
+      || args.tabId
+      || context?.callerSessionId
+      || cli.DEFAULT_SESSION,
+  );
+}
+
+function rememberProfile(session) {
+  try {
+    require('./profiles').touchBrowserProfile({
+      id: session,
+      name: session,
+      source: 'agent-browser',
+      profilePath: cli.profileDir(session),
+    }, { source: 'agent-browser' });
+  } catch {}
+}
+
+function sessionInfo(session, extra = {}) {
+  rememberProfile(session);
+  const info = {
+    session,
+    browserSessionId: session,
+    browserProfileId: session,
+    backend: backend.mode(),
+    ...extra,
+  };
+  knownSessions.set(session, { ...knownSessions.get(session), ...info, lastActiveAt: Date.now() });
+  return info;
+}
+
+module.exports = {
+  attachedSessions,
+  knownSessions,
+  rememberProfile,
+  sessionFor,
+  sessionInfo,
+};

package/runtime/scripts/amalgm-mcp/browser/tools.js

@@ -1,16 +1,20 @@
 'use strict';
 
 /**
- * Browser tools — the thin surface.
+ * Browser core actions — the thin surface.
  *
- * Nine verbs, built on the agent-browser CLI (vercel-labs/agent-browser).
- * The loop is: open → snapshot (refs) → click/fill (@ref) → re-snapshot.
+ * Ten verbs built on the agent-browser CLI (vercel-labs/agent-browser). The
+ * loop is: open → snapshot (@refs) → click/fill (@ref) → re-snapshot.
  * Everything else agent-browser can do (scroll, hover, cookies, network
- * mocking, traces, diffs, React inspection, ...) is reachable through
- * browser_cli without widening this schema.
+ * mocking, traces, diffs, React inspection, ...) is reachable through `cli`
+ * without widening this schema.
  *
- * In the Amalgm desktop app these drive the visible in-tab splitscreen
- * browser; elsewhere they drive a standalone chromium.
+ * Action names are short verbs — the toolbox layer prefixes them, so agents
+ * see toolbox__browser_open, toolbox__browser_snapshot, and so on.
+ *
+ * Visibility is environmental, never an argument: in the Amalgm desktop app
+ * these drive the visible in-tab split-view browser; everywhere else they
+ * drive a headless chromium. Same actions, same results.
  */
 
 const { textResult, errorResult } = require('../lib/tool-result');
@@ -26,7 +30,7 @@ const sessionProperty = {
 const targetProperty = {
   target: {
     type: 'string',
-    description: 'Element target: a snapshot ref like "@e12" (preferred — run browser_snapshot first), a CSS selector, or "text=Visible label".',
+    description: 'Element target: a snapshot ref like "@e12" (preferred — run snapshot first), a CSS selector, or "text=Visible label".',
   },
 };
 
@@ -38,8 +42,8 @@ function line(result, extra = '') {
 
 module.exports = [
   {
-    name: 'browser_open',
-    description: 'Open a URL in the browser. In the Amalgm desktop app this appears in the in-tab splitscreen surface. Follow with browser_snapshot to see interactive elements.',
+    name: 'open',
+    description: 'Open a URL. The browser persists between calls — open once, then interact. Follow with snapshot to see the page as @refs. (In the Amalgm desktop app the user watches this browser in a split view.)',
     inputSchema: {
       type: 'object',
       properties: { url: { type: 'string', description: 'URL to open' }, ...sessionProperty },
@@ -50,15 +54,15 @@ module.exports = [
       try {
         const result = await engine.open(args, ctx);
         return textResult(line(result, `Opened: ${result.title || args.url}`)
-          + '\n\nNext: browser_snapshot lists interactive elements as @refs.');
+          + '\n\nNext: snapshot lists interactive elements as @refs.');
       } catch (err) {
         return errorResult(`Open failed: ${err.message}`);
       }
     },
   },
   {
-    name: 'browser_snapshot',
-    description: 'Accessibility snapshot of the current page with stable @refs for every interactive element. This is how you see the page; use the refs with browser_click and browser_fill.',
+    name: 'snapshot',
+    description: 'Read the page: an accessibility snapshot with a stable @ref for every interactive element. This is how you see the page — pass the refs to click and fill.',
     inputSchema: { type: 'object', properties: sessionProperty },
     async handler(args, ctx) {
       try {
@@ -71,22 +75,22 @@ module.exports = [
     },
   },
   {
-    name: 'browser_screenshot',
-    description: 'Screenshot the current page (PNG). Use browser_snapshot for interaction targets; use this when you need to see pixels.',
+    name: 'screenshot',
+    description: 'Screenshot the page (PNG). Prefer snapshot for driving the page; use this to verify visuals. fullPage captures the whole scroll height when headless; in the desktop app you always get the visible surface.',
     inputSchema: {
       type: 'object',
       properties: {
-        fullPage: { type: 'boolean', description: 'Capture the full scrollable page instead of the viewport' },
+        fullPage: { type: 'boolean', description: 'Capture the full scrollable page instead of the viewport (headless only)' },
         ...sessionProperty,
       },
     },
     async handler(args, ctx) {
       try {
-        const capture = await engine.screenshot(args, ctx);
+        const shot = await engine.screenshot(args, ctx);
         return {
           content: [
-            { type: 'image', data: capture.base64, mimeType: 'image/png' },
-            { type: 'text', text: `Screenshot (${capture.bytes} bytes, ${capture.mode || 'viewport'})` },
+            { type: 'image', data: shot.base64, mimeType: 'image/png' },
+            { type: 'text', text: `Screenshot (${shot.bytes} bytes, ${shot.mode})` },
           ],
         };
       } catch (err) {
@@ -95,7 +99,7 @@ module.exports = [
     },
   },
   {
-    name: 'browser_click',
+    name: 'click',
     description: 'Click an element. Target with a snapshot @ref, CSS selector, or "text=Label".',
     inputSchema: {
       type: 'object',
@@ -106,14 +110,14 @@ module.exports = [
       if (!args.target) return errorResult('target is required (e.g. "@e3", "#submit", "text=Sign in")');
       try {
         const result = await engine.click(args, ctx);
-        return textResult(`Clicked ${args.target}\nSession: ${result.session}\n\nRe-run browser_snapshot if the page changed.`);
+        return textResult(`Clicked ${args.target}\nSession: ${result.session}\n\nRe-run snapshot if the page changed.`);
       } catch (err) {
         return errorResult(`Click failed: ${err.message}`);
       }
     },
   },
   {
-    name: 'browser_fill',
+    name: 'fill',
     description: 'Clear a field and type into it. Optionally press Enter to submit.',
     inputSchema: {
       type: 'object',
@@ -136,7 +140,7 @@ module.exports = [
     },
   },
   {
-    name: 'browser_press',
+    name: 'press',
     description: 'Press a key or combination at the focused element, e.g. "Enter", "Escape", "Tab", "Control+a".',
     inputSchema: {
       type: 'object',
@@ -154,8 +158,8 @@ module.exports = [
     },
   },
   {
-    name: 'browser_eval',
-    description: 'Run JavaScript in the page and return the result. The general-purpose escape hatch for reading or mutating page state.',
+    name: 'eval',
+    description: 'Run JavaScript in the page and return the result — the escape hatch for reading or mutating anything the page knows.',
     inputSchema: {
       type: 'object',
       properties: { script: { type: 'string', description: 'JavaScript to evaluate' }, ...sessionProperty },
@@ -173,7 +177,7 @@ module.exports = [
     },
   },
   {
-    name: 'browser_wait',
+    name: 'wait',
     description: 'Wait for a CSS selector to appear, a URL substring/wildcard to match, or a fixed number of milliseconds.',
     inputSchema: {
       type: 'object',
@@ -195,7 +199,7 @@ module.exports = [
     },
   },
   {
-    name: 'browser_cli',
+    name: 'cli',
     description: 'Run any agent-browser CLI command against this session — the full surface beyond the core verbs: ["scroll","down"], ["hover","@e3"], ["back"], ["tab"], ["get","html","@e1"], ["cookies","get"], ["network","requests"], ["find","role","button","click","--name","Submit"], and more. Run ["--help"] for the command list.',
     inputSchema: {
       type: 'object',
@@ -212,18 +216,18 @@ module.exports = [
         const output = typeof result === 'object' ? JSON.stringify(result, null, 2) : String(result ?? '');
         return textResult(output.slice(0, 15_000) || 'ok');
       } catch (err) {
-        return errorResult(`browser_cli failed: ${err.message}`);
+        return errorResult(`cli failed: ${err.message}`);
       }
     },
   },
   {
-    name: 'browser_close',
-    description: 'Close the browser session. A fresh one launches on the next browser call.',
+    name: 'close',
+    description: 'End the browser session. Headless browsers shut down; the visible desktop surface stays open for the user. A fresh session starts on the next browser call.',
     inputSchema: { type: 'object', properties: sessionProperty },
     async handler(args, ctx) {
       try {
         await engine.close(args, ctx);
-        return textResult('Browser closed.');
+        return textResult('Browser session closed.');
       } catch (err) {
         return errorResult(`Close failed: ${err.message}`);
       }

package/runtime/scripts/amalgm-mcp/server/core-tools.js

@@ -8,10 +8,6 @@
  * circular dependency on the MCP server.
  */
 
-function withCapability(tools, capability) {
-  return tools.map((tool) => ({ ...tool, capability }));
-}
-
 function group(id, name, description, tools, extra = {}) {
   return {
     id,
@@ -64,19 +60,13 @@ const CORE_TOOL_GROUPS = [
   ),
   // Browser is ONE toolbox entry. Users enable/disable it per agent as a
   // single tool; fine-grained control stays available because loadouts can
-  // hold individual action ids (`browser.cua_click`). Each action carries a
-  // `capability` tag so UIs can section the card (core / computer-use /
-  // recording / auth) without splitting the entry.
+  // hold individual action ids (`browser.cua_click`). Action list, capability
+  // sections, and description live with the implementation in ../browser.
   group(
     'browser',
     'Browser',
-    "Drive Amalgm's browser: open pages, snapshot interactive elements as @refs, click, fill, record sessions to project videos, manage durable login profiles, and run any agent-browser CLI command. Visible in the desktop split view; headless on servers.",
-    [
-      ...withCapability(require('../browser/tools'), 'core'),
-      ...withCapability(require('../browser/cua-tools'), 'computer-use'),
-      ...withCapability(require('../browser/recorder-tools'), 'recording'),
-      ...withCapability(require('../browser/auth-tools'), 'auth'),
-    ],
+    require('../browser').DESCRIPTION,
+    require('../browser').ACTIONS,
   ),
 ];
 

package/runtime/scripts/amalgm-mcp/server/mcp.js

@@ -24,6 +24,27 @@ const { buildMcpRequestContext } = require('./mcp-request-context');
 
 const TOOLS = DEFAULT_STATIC_MCP_TOOLS;
 
+/**
+ * One greppable line whenever a session's tool registry changes shape. If a
+ * client ever reports "No such tool available" again, this proves what the
+ * server actually served (the 2026-06-10 partial-registry incident was
+ * unattributable because nothing logged tools/list).
+ */
+const lastToolListHash = new Map();
+function logToolList(ctx, tools) {
+  try {
+    const names = tools.map((tool) => tool.name).sort();
+    const hash = require('crypto').createHash('sha1').update(names.join('\n')).digest('hex').slice(0, 8);
+    const session = ctx?.callerSessionId || 'unknown';
+    if (lastToolListHash.get(session) === hash) return;
+    lastToolListHash.set(session, hash);
+    if (lastToolListHash.size > 500) {
+      lastToolListHash.delete(lastToolListHash.keys().next().value);
+    }
+    console.error(`[amalgm-mcp] tools/list session=${session} count=${tools.length} names-sha1=${hash}`);
+  } catch {}
+}
+
 function createMcpServer(options = {}) {
   const surface = options.surface || createToolboxMcpSurface();
   const buildRequestContext = options.buildRequestContext || buildMcpRequestContext;
@@ -34,7 +55,9 @@ function createMcpServer(options = {}) {
 
   server.setRequestHandler(ListToolsRequestSchema, async (_request, extra) => {
     const ctx = await buildRequestContext(extra);
-    return { tools: await surface.listTools(ctx) };
+    const tools = await surface.listTools(ctx);
+    logToolList(ctx, tools);
+    return { tools };
   });
 
   server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {

package/runtime/scripts/amalgm-mcp/tests/browser-capture.test.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const test = require('node:test');
+const http = require('node:http');
+
+const capture = require('../browser/capture');
+
+test('clipFor turns a webview rect into integer CSS-px clip bounds', () => {
+  const clip = capture.clipFor({ x: 411.5, y: 52.25, width: 868.75, height: 781.5, vw: 1280, vh: 834 });
+  assert.deepEqual(clip, { x: 412, y: 52, width: 869, height: 782, scale: 1 });
+  // Negative origins (mid-animation surfaces) clamp to the viewport.
+  assert.equal(capture.clipFor({ x: -4, y: 0, width: 100, height: 100 }).x, 0);
+  // Retina displays render captures at devicePixelRatio; scale divides it
+  // back out so image pixels map 1:1 onto cua input coordinates.
+  assert.equal(capture.clipFor({ x: 0, y: 0, width: 100, height: 100, dpr: 2 }).scale, 0.5);
+});
+
+test('cropFilterFor crops by viewport fraction so any frame resolution works', () => {
+  const filter = capture.cropFilterFor({ x: 320, y: 0, width: 640, height: 600, vw: 1280, vh: 800 });
+  // width 640/1280=0.5, height 600/800=0.75, x 320/1280=0.25, y 0.
+  assert.equal(filter, 'crop=floor(iw*0.500000/2)*2:floor(ih*0.750000/2)*2:floor(iw*0.250000):floor(ih*0.000000)');
+  // Fractions clamp into [0, 1] even for slightly-out-of-viewport rects.
+  assert.match(capture.cropFilterFor({ x: -10, y: 0, width: 2000, height: 100, vw: 1000, vh: 500 }),
+    /^crop=floor\(iw\*1\.000000\/2\)\*2/);
+});
+
+test('pageTargets keeps only capturable page targets', () => {
+  const targets = [
+    { type: 'page', url: 'devtools://devtools/bundled/devtools_app.html', webSocketDebuggerUrl: 'ws://x/1' },
+    { type: 'webview', url: 'https://example.com/', webSocketDebuggerUrl: 'ws://x/2' },
+    { type: 'page', url: 'http://localhost:3100/', webSocketDebuggerUrl: 'ws://x/3' },
+    { type: 'page', url: 'http://localhost:3100/popup' },
+  ];
+  assert.deepEqual(capture.pageTargets(targets).map((t) => t.webSocketDebuggerUrl), ['ws://x/3']);
+});
+
+test('rectScript matches by marker, then current URL, then the only webview', () => {
+  const script = capture.rectScript('amalgm-bsid-abc', 'https://example.com/');
+  assert.match(script, /amalgm-bsid-abc/);
+  assert.match(script, /https:\/\/example\.com\//);
+  // No current URL → the byUrl branch is disabled, not matching everything.
+  const bare = capture.rectScript('amalgm-bsid-abc', '');
+  assert.match(bare, /"" \? views\.find/);
+});
+
+test('targetListUrl accepts bare ports and ws urls', () => {
+  assert.equal(capture.targetListUrl('9242'), 'http://127.0.0.1:9242/json/list');
+  assert.equal(
+    capture.targetListUrl('ws://127.0.0.1:9242/devtools/browser/abc'),
+    'http://127.0.0.1:9242/json/list',
+  );
+});
+
+test('deadline rejects instead of hanging', async () => {
+  await assert.rejects(
+    () => capture.deadline(new Promise(() => {}), 50, 'Page.captureScreenshot'),
+    /Page\.captureScreenshot timed out after 50ms/,
+  );
+  assert.equal(await capture.deadline(Promise.resolve('ok'), 50, 'fast'), 'ok');
+});
+
+test('a CDP endpoint that accepts but never answers cannot wedge a capture', async () => {
+  // Plain HTTP server: the websocket upgrade never completes, so connectCdp
+  // must give up on its own deadline rather than waiting forever — this is
+  // the daemon-wedge class of failure, now structurally impossible.
+  const server = http.createServer(() => {});
+  server.on('upgrade', () => { /* swallow the upgrade — never respond */ });
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address();
+  const startedAt = Date.now();
+  await assert.rejects(
+    () => capture.connectCdp(`ws://127.0.0.1:${port}/devtools/page/never`),
+    /CDP connect timed out/,
+  );
+  assert.equal(Date.now() - startedAt < 15_000, true);
+  server.close();
+});
+
+test('listTargets rejects cleanly when nothing listens on the port', async () => {
+  // Find a free port, then close it so the request must fail fast.
+  const server = http.createServer(() => {});
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address();
+  await new Promise((resolve) => server.close(resolve));
+  await assert.rejects(() => capture.listTargets(String(port)));
+});