amalgm 0.1.194 → 0.1.195

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.194",
+  "version": "0.1.195",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

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

@@ -4,7 +4,7 @@
  * Attached mode — drive the browser surface the user is watching.
  *
  * The desktop app advertises its chromium over CDP; the UI mounts the in-tab
- * split-view <webview> with a marker URL. This module owns the attach
+ * split-view native page with a marker URL. This module owns the attach
  * handshake and the command transport, built around one rule:
  *
  *   A session's identity is established ONCE at attach and VERIFIED on every
@@ -17,17 +17,17 @@
  * ref". Both verified live. So instead of a per-command `tab` pin, attach:
  *
  *  1. Asks the UI to open the surface (a browser_surfaces state event).
- *  2. Selects the session's webview in the daemon ONCE (refs don't exist yet).
- *  3. Opens a persistent raw-CDP connection to the guest target and stamps it:
+ *  2. Selects the session's native page in the daemon ONCE (refs don't exist yet).
+ *  3. Opens a persistent raw-CDP connection to that target and stamps it:
  *     `window.__amalgmBsid = session` now, plus the same script on every new
  *     document — the stamp survives navigation and dies with the target.
  *  4. Prepends a guard eval to every batch: stamp mismatch throws, the batch
  *     bails before the action runs, and the session re-attaches once. eval
  *     does not reset refs, so @refs stay live across calls.
  *
- * The persistent guest connection doubles as the capture anchor: screenshots
+ * The persistent page connection doubles as the capture anchor: screenshots
  * and recordings connect straight to the verified target instead of hunting
- * the target list per capture (the hunt's "no webviews yet → first page
+ * the target list per capture (the hunt's "no surfaces yet → first page
  * target" fallback is how cua_screenshot once captured the app's own chat UI).
  */
 
@@ -37,16 +37,16 @@ const cdp = require('./cdp');
 const { surfaces, knownSessions, backendFor } = require('./sessions');
 
 const SURFACE_EVENT_RESOURCE = 'browser_surfaces';
-const WEBVIEW_MARKER_PREFIX = 'amalgm-bsid-';
-const WEBVIEW_WAIT_MS = 15_000;
-const WEBVIEW_POLL_MS = 500;
+const SURFACE_MARKER_PREFIX = 'amalgm-bsid-';
+const SURFACE_WAIT_MS = 15_000;
+const SURFACE_POLL_MS = 500;
 const GUARD_ERROR = 'amalgm-surface-guard';
 const SURFACE_HIDDEN_MESSAGE = 'The browser surface is hidden in the desktop app and did not reopen. '
   + 'Retry; if it keeps failing, close this browser session and open again '
   + '(a fresh surface will mount), or force a headless browser with AMALGM_BROWSER_BACKEND=cli.';
 
 function marker(session) {
-  return `${WEBVIEW_MARKER_PREFIX}${session}`;
+  return `${SURFACE_MARKER_PREFIX}${session}`;
 }
 
 function stampScript(session) {
@@ -87,7 +87,7 @@ function requestSurfaceOpen(session, context) {
 }
 
 /**
- * The session's webview rectangle in the app window, or null when the
+ * The session's surface rectangle in the app window, or null when the
  * splitview is hidden (0x0) or gone. Raw CDP, deadline-bounded.
  */
 async function surfaceRect(session, hintUrl) {
@@ -106,13 +106,13 @@ async function surfaceRect(session, hintUrl) {
  * slot; either way it must have real layout geometry. When it does not, ask
  * the UI to mount it and poll until geometry appears.
  */
-async function ensureSurfaceVisible(session, hintUrl, context, waitMs = WEBVIEW_WAIT_MS) {
+async function ensureSurfaceVisible(session, hintUrl, context, waitMs = SURFACE_WAIT_MS) {
   let found = await surfaceRect(session, hintUrl);
   if (found) return found;
   requestSurfaceOpen(session, context);
   const deadlineAt = Date.now() + waitMs;
   while (Date.now() < deadlineAt) {
-    await new Promise((resolve) => setTimeout(resolve, WEBVIEW_POLL_MS));
+    await new Promise((resolve) => setTimeout(resolve, SURFACE_POLL_MS));
     found = await surfaceRect(session, hintUrl);
     if (found) return found;
   }
@@ -120,12 +120,12 @@ async function ensureSurfaceVisible(session, hintUrl, context, waitMs = WEBVIEW_
 }
 
 /**
- * This session's candidate webviews out of a target/tab list. Marker in the
+ * This session's candidate surfaces out of a target/tab list. Marker in the
  * url or title identifies fresh surfaces exactly; the live URL the embedder
  * DOM reports for the session's marked element covers surfaces that
  * navigated away from the marker (e.g. after an MCP restart) — but two
  * sessions can browse the same URL, so URL matches are candidates to be
- * confirmed by stamp, never picked blindly. And never "the only webview":
+ * confirmed by stamp, never picked blindly. And never "the only surface":
  * a displaced session adopting whatever surface remains is how one chat's
  * browser ends up reading another chat's page.
  */
@@ -155,10 +155,21 @@ async function readStamp(wsUrl) {
   }
 }
 
+function candidateHasMarker(candidate, session) {
+  const markerText = marker(session);
+  return String(candidate?.url || '').includes(markerText)
+    || String(candidate?.title || '').includes(markerText);
+}
+
 /** Resolve same-URL ambiguity: the candidate whose page carries this
- * session's stamp wins. A unique candidate stands on its own. */
-async function confirmGuestCandidates(candidates, session) {
-  if (candidates.length <= 1) return candidates[0] || null;
+ * session's stamp wins. A fresh marker target is already unambiguous. */
+async function confirmSurfaceCandidates(candidates, session) {
+  if (
+    candidates.length === 1
+    && (candidateHasMarker(candidates[0], session) || candidates[0].type === 'webview')
+  ) {
+    return candidates[0];
+  }
   for (const candidate of candidates) {
     if (await readStamp(candidate.webSocketDebuggerUrl) === session) return candidate;
   }
@@ -166,13 +177,13 @@ async function confirmGuestCandidates(candidates, session) {
 }
 
 /**
- * Stamp the guest and keep the connection open. The on-new-document script
+ * Stamp the surface and keep the connection open. The on-new-document script
  * lives exactly as long as this CDP session — which is exactly as long as
- * the stamp should live: the connection drops when the target dies (webview
+ * the stamp should live: the connection drops when the target dies (surface
  * remount, app restart), the surface record is dropped with it, and the next
  * command re-attaches against the new reality.
  */
-async function stampGuest(session, wsUrl) {
+async function stampSurface(session, wsUrl) {
   const client = await cdp.connectCdp(wsUrl);
   try {
     await client.call('Page.enable').catch(() => {});
@@ -186,10 +197,8 @@ async function stampGuest(session, wsUrl) {
 }
 
 /**
- * Chromium drops CDP Input events to an Electron <webview> guest until the
- * guest widget has focus (verified live: clicks report success but never
- * land). One focus pass over raw CDP — the embedder focuses the element, the
- * guest focuses its window. Best-effort: reads work unfocused regardless.
+ * Give the marked host and native page one best-effort focus pass before
+ * input. The main process also focuses a visible WebContentsView directly.
  */
 async function focusSurface(session, surface) {
   try {
@@ -198,9 +207,9 @@ async function focusSurface(session, surface) {
       try {
         await embedder.call('Runtime.evaluate', {
           expression: `(() => {
-            const view = [...document.querySelectorAll('webview')]
+            const view = [...document.querySelectorAll('[data-amalgm-surface]')]
               .find((w) => (w.getAttribute('data-amalgm-surface') || '').includes(${JSON.stringify(marker(session))}));
-            if (view) view.focus();
+            if (view) view.focus({ preventScroll: true });
             return Boolean(view);
           })()`,
           returnByValue: true,
@@ -224,7 +233,7 @@ function commandNeedsOwnedFocus(command) {
 
 /**
  * Focus is owned by the browser session, not by the user's currently selected
- * Amalgm tab. Before commands that need native guest focus, reacquire focus on
+ * Amalgm tab. Before commands that need native page focus, reacquire focus on
  * this session's stamped surface. Reads and evals do not disturb the user.
  */
 async function acquireOwnedFocus(session, context, surface, hintUrl = '') {
@@ -238,8 +247,8 @@ async function acquireOwnedFocus(session, context, surface, hintUrl = '') {
 }
 
 /**
- * Connect the session to the advertised chromium on first use: select the
- * in-tab webview in the daemon, stamp the guest over a persistent raw-CDP
+ * Connect the session to the advertised Chromium on first use: select the
+ * in-tab native page in the daemon, stamp it over a persistent raw-CDP
  * connection, focus it. The returned record is the session's one source of
  * identity — commands verify against the stamp, captures connect to the
  * target it names.
@@ -249,11 +258,14 @@ async function ensureReady(session, context) {
   const live = surfaces.get(session);
   if (live) return live;
 
-  // Explicit external CDP endpoints (plain chromium) have page targets, not
-  // webviews — drive whatever the daemon selected; no surface, no stamp.
+  // Explicit external CDP endpoints (plain Chromium) have no marked Amalgm
+  // host element. WebContentsView targets are also type:"page", so target
+  // type alone can no longer distinguish an external browser from Electron.
   if (process.env.AMALGM_BROWSER_CDP_URL) {
     const targets = await cdp.listTargets(backend.cdpEndpoint()).catch(() => []);
-    if (!targets.some((t) => t.type === 'webview')) {
+    const markedTarget = targets.some((target) => candidateHasMarker(target, session));
+    const markedHost = await surfaceRect(session, '');
+    if (!targets.some((target) => target.type === 'webview') && !markedTarget && !markedHost) {
       const external = { external: true, client: null, tabId: null, wsUrl: null };
       surfaces.set(session, external);
       return external;
@@ -264,24 +276,30 @@ async function ensureReady(session, context) {
   // navigated away from the marker URL (data-amalgm-surface survives where
   // target URLs do not).
   const domSrc = async () => (await surfaceRect(session, ''))?.rect?.src || null;
-  const webviewTabs = async () => {
+  const surfaceTabs = async () => {
     const tabs = await cli.runCli(['tab'], cliOptions(session, { timeoutMs: 15_000 }));
-    return (tabs?.data?.tabs || tabs?.tabs || []).filter((tab) => tab.type === 'webview');
+    const targetTypes = new Set(backend.surfaceTargetTypes());
+    return (tabs?.data?.tabs || tabs?.tabs || []).filter((tab) =>
+      targetTypes.has(tab.type)
+    );
   };
 
-  let candidates = identityCandidates(await webviewTabs(), session, await domSrc());
+  let candidates = identityCandidates(await surfaceTabs(), session, await domSrc());
   if (!candidates.length) {
     requestSurfaceOpen(session, context);
-    const deadlineAt = Date.now() + WEBVIEW_WAIT_MS;
+    const deadlineAt = Date.now() + SURFACE_WAIT_MS;
     while (!candidates.length && Date.now() < deadlineAt) {
-      await new Promise((resolve) => setTimeout(resolve, WEBVIEW_POLL_MS));
-      candidates = identityCandidates(await webviewTabs(), session, await domSrc());
+      await new Promise((resolve) => setTimeout(resolve, SURFACE_POLL_MS));
+      candidates = identityCandidates(await surfaceTabs(), session, await domSrc());
     }
   }
 
   // Same-URL candidates are told apart by the stamp their pages carry from a
   // previous attach: pin each in turn and read it back through the daemon.
-  let selected = candidates.length === 1 ? candidates[0] : null;
+  let selected = candidates.length === 1
+    && (candidateHasMarker(candidates[0], session) || candidates[0].type === 'webview')
+    ? candidates[0]
+    : null;
   for (const candidate of candidates) {
     if (selected) break;
     await cli.runCli(['tab', candidate.tabId], cliOptions(session, { timeoutMs: 15_000 }));
@@ -298,43 +316,48 @@ async function ensureReady(session, context) {
     );
   }
 
-  // The webview target existing is not enough — the session surface must be
+  // The native page target existing is not enough — the session surface must be
   // compositor-backed, or input drops and captures have nothing to render.
   // The app window itself may be hidden or minimized; the app keeps attached
   // surfaces compositing while the browser tool owns them.
   const visible = await ensureSurfaceVisible(session, selected.url, context);
   if (!visible) throw new Error(SURFACE_HIDDEN_MESSAGE);
 
-  // Select the session's webview in the daemon — once. Refs don't exist yet,
+  // Select the session's page in the daemon — once. Refs don't exist yet,
   // so this is the one place a `tab` command is allowed.
   await cli.runCli(['tab', selected.tabId], cliOptions(session, { timeoutMs: 15_000 }));
 
-  // The guest's raw-CDP target, by the same identity as the daemon tab —
-  // stamp-confirmed when several webviews share the URL.
-  const guest = await confirmGuestCandidates(identityCandidates(
+  // The surface's raw-CDP target, by the same identity as the daemon tab —
+  // stamp-confirmed when several pages share the URL.
+  const advertisedTargetTypes = new Set(backend.surfaceTargetTypes());
+  const target = await confirmSurfaceCandidates(identityCandidates(
+    // Rev 5 exposes guest targets as `webview`; rev 6 exposes
+    // WebContentsView pages as `page`. The bridge advertisement selects one
+    // contract, so app renderer pages never enter the candidate set.
     (await cdp.listTargets(backend.cdpEndpoint()))
-      .filter((t) => t.type === 'webview' && t.webSocketDebuggerUrl),
+      .filter((t) => advertisedTargetTypes.has(t.type) && t.webSocketDebuggerUrl),
     session,
     visible.rect?.src || null,
   ), session);
-  if (!guest) throw new Error(SURFACE_HIDDEN_MESSAGE);
+  if (!target) throw new Error(SURFACE_HIDDEN_MESSAGE);
 
-  const client = await stampGuest(session, guest.webSocketDebuggerUrl);
+  const client = await stampSurface(session, target.webSocketDebuggerUrl);
   const surface = {
     tabId: selected.tabId,
-    targetId: guest.id,
-    wsUrl: guest.webSocketDebuggerUrl,
+    targetId: target.id,
+    targetType: target.type,
+    wsUrl: target.webSocketDebuggerUrl,
     embedderWsUrl: visible.pageWsUrl || null,
     client,
     external: false,
   };
-  // The connection dropping IS the detach signal: webview remount, app
+  // The connection dropping IS the detach signal: surface remount, app
   // restart, surface close — all of them invalidate this identity at once.
   client.onClose(() => {
     if (surfaces.get(session) === surface) surfaces.delete(session);
   });
   surfaces.set(session, surface);
-  knownSessions.set(session, { ...knownSessions.get(session), webviewTabId: selected.tabId });
+  knownSessions.set(session, { ...knownSessions.get(session), surfaceTabId: selected.tabId });
 
   await focusSurface(session, surface);
   return surface;
@@ -419,7 +442,7 @@ async function execute(session, commands, options = {}, single) {
     return await attempt();
   } catch (err) {
     if (guarded && looksLikeLostConnection(err)) {
-      // The app restarted, the webview remounted, or the daemon drifted off
+      // The app restarted, the surface remounted, or the daemon drifted off
       // this session's page; re-attach once against current reality.
       detach(session);
       const nextSurface = await ensureReady(session, context);
@@ -450,12 +473,12 @@ async function readText(session, commandArgs, timeoutMs) {
 }
 
 /**
- * The CDP websocket url for raster capture — the surface's own guest target,
+ * The CDP websocket url for raster capture — the surface's own page target,
  * established at attach. Requires the surface on screen (the one physical
- * precondition for guest pixels); ensureSurfaceVisible self-heals a
+ * precondition for attached pixels); ensureSurfaceVisible self-heals a
  * backgrounded tab first. Null for external plain-chromium endpoints.
  */
-async function guestWsUrl(session, context) {
+async function surfaceTarget(session, context) {
   let surface = await ensureReady(session, context);
   if (surface?.external) return null;
   const visible = await ensureSurfaceVisible(session, '', context);
@@ -463,12 +486,19 @@ async function guestWsUrl(session, context) {
   // The target may have died between ensureReady and now — the close handler
   // clears the record, so a second look re-attaches against the new target.
   surface = surfaces.get(session) || await ensureReady(session, context);
-  return surface.wsUrl;
+  return {
+    wsUrl: surface.wsUrl,
+    type: surface.targetType || 'webview',
+  };
+}
+
+async function surfaceWsUrl(session, context) {
+  return (await surfaceTarget(session, context))?.wsUrl || null;
 }
 
 /**
  * Tell the UI this session's surface is done — the renderer unmounts the
- * splitview/tab, so ended sessions stop accumulating webviews (each one is
+ * splitview/tab, so ended sessions stop accumulating page renderers (each is
  * a full renderer process).
  */
 function requestSurfaceClose(session) {
@@ -490,13 +520,14 @@ module.exports = {
   GUARD_ERROR,
   SURFACE_EVENT_RESOURCE,
   SURFACE_HIDDEN_MESSAGE,
-  WEBVIEW_MARKER_PREFIX,
+  SURFACE_MARKER_PREFIX,
   cliOptions,
   detach,
   ensureReady,
   ensureSurfaceVisible,
   guardCommand,
-  guestWsUrl,
+  surfaceWsUrl,
+  surfaceTarget,
   looksLikeLostConnection,
   marker,
   identityCandidates,

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

@@ -58,9 +58,29 @@ function readBridgeAdvertisement() {
   for (const file of bridgeFileCandidates()) {
     try {
       const data = JSON.parse(fs.readFileSync(file, 'utf8'));
-      if (typeof data?.cdpUrl !== 'string' || !data.cdpUrl) continue;
+      const cdpUrl = typeof data?.cdp?.url === 'string'
+        ? data.cdp.url
+        : data?.cdpUrl;
+      const cdpPort = Number.isInteger(data?.cdp?.port)
+        ? data.cdp.port
+        : data?.cdpPort;
+      if (typeof cdpUrl !== 'string' || !cdpUrl) continue;
       if (typeof data?.pid === 'number' && !pidIsRunning(data.pid)) continue;
-      return { cdpUrl: data.cdpUrl, cdpPort: data.cdpPort, label: data.label, file };
+      return {
+        cdpUrl,
+        cdpPort,
+        label: data.label,
+        surfaceProtocol: Number.isInteger(data?.browserSurfaceProtocol)
+          ? data.browserSurfaceProtocol
+          : 5,
+        surfaceTargetType: data?.browserSurfaceTargetType === 'page'
+          ? 'page'
+          : 'webview',
+        surfaceTargetTypes: Array.isArray(data?.browserSurfaceTargetTypes)
+          ? data.browserSurfaceTargetTypes.filter((value) => value === 'page' || value === 'webview')
+          : null,
+        file,
+      };
     } catch {}
   }
   return null;
@@ -81,7 +101,7 @@ function cdpFlagValue(input) {
 /**
  * The CDP endpoint for attached mode, as a --cdp flag value. agent-browser's
  * `connect` command launches a managed browser; raw --cdp attach is the mode
- * that discovers Electron <webview> targets, so that is all we use.
+ * that discovers Electron page targets, so that is all we use.
  */
 function cdpEndpoint() {
   if (process.env.AMALGM_BROWSER_CDP_URL) return cdpFlagValue(process.env.AMALGM_BROWSER_CDP_URL);
@@ -91,6 +111,21 @@ function cdpEndpoint() {
   return cdpFlagValue(advertisement.cdpUrl);
 }
 
+/**
+ * Target kinds spoken by the advertised desktop shell. Missing protocol
+ * means the rev-5 webview contract. Explicit operator endpoints are allowed
+ * to be plain Chromium or either Electron generation, so probe both.
+ */
+function surfaceTargetTypes() {
+  if (process.env.AMALGM_BROWSER_CDP_URL) return ['page', 'webview'];
+  const advertisement = readBridgeAdvertisement();
+  if (!advertisement) return [];
+  if (advertisement.surfaceTargetTypes?.length) {
+    return [...new Set(advertisement.surfaceTargetTypes)];
+  }
+  return [advertisement.surfaceTargetType];
+}
+
 /** The debug override, or null when the owner's stamp decides. */
 function forcedMode() {
   const requested = (process.env.AMALGM_BROWSER_BACKEND || '').toLowerCase();
@@ -121,4 +156,5 @@ module.exports = {
   forcedMode,
   modeFor,
   readBridgeAdvertisement,
+  surfaceTargetTypes,
 };

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

@@ -5,18 +5,13 @@
  *
  * Pixels come straight from the session's own page:
  *  - cli (headless) sessions capture their page target;
- *  - attached sessions capture the <webview> guest target whose identity was
- *    established at attach (attach.guestWsUrl) — never a target-list hunt,
+ *  - attached sessions capture the native page target whose identity was
+ *    established at attach (attach.surfaceTarget) — never a target-list hunt,
  *    never a "first page target" fallback (that fallback is how
  *    cua_screenshot once returned the app's own chat UI).
  *
- * The one physical law (verified live in all four states): a guest rasters
- * iff its <webview> is composited on-screen in the app's layout. The app
- * window may be hidden or minimized — the desktop app disables background
- * throttling while a surface is attached, so frames keep flowing. Only a
- * surface in a background tab (display:none) cannot produce pixels, and
- * ensureSurfaceVisible self-heals that by asking the UI to refocus the
- * surface tab before any capture is attempted.
+ * Background automation surfaces remain composited in a private native
+ * parking window, so captures keep working without covering the user's tab.
  *
  * Every exchange carries a hard deadline (cdp.js): a capture may fail, it
  * can never wedge a session.
@@ -48,34 +43,75 @@ async function pageTargetWsUrl(endpoint) {
 
 /**
  * Where to capture from for this session:
- *   { wsUrl, guest } — guest marks an attached <webview> target, whose output
- *   is normalized to CSS pixels so coordinates map 1:1 onto cua_* input.
+ *   { wsUrl, attached, legacyWebview } — attached output is normalized to
+ *   CSS pixels so coordinates map 1:1 onto cua_* input. The legacy flag
+ *   preserves rev-5's transparent-PNG compatibility during rolling updates.
  */
 async function plan(session, context) {
   if (backendFor(session) !== 'attached') {
     const raw = await daemonCdpUrl(session);
     if (!raw) throw new Error('Could not resolve a CDP endpoint for this browser session.');
     const wsUrl = /\/devtools\/browser\//.test(raw) ? await pageTargetWsUrl(raw) : raw;
-    return { wsUrl, guest: false };
+    return { wsUrl, attached: false };
   }
 
-  // Desktop app: the session's own webview guest, identity from attach.
+  // Desktop app: the session's own native page, identity from attach.
   // Null only for explicit external CDP endpoints (plain chromium) — there
   // the driven page is the capture source.
-  const wsUrl = await attach.guestWsUrl(session, context);
-  if (wsUrl) return { wsUrl, guest: true };
-  return { wsUrl: await pageTargetWsUrl(backend.cdpEndpoint()), guest: false };
+  const target = await attach.surfaceTarget(session, context);
+  if (target) {
+    return {
+      wsUrl: target.wsUrl,
+      attached: true,
+      legacyWebview: target.type === 'webview',
+    };
+  }
+  return {
+    wsUrl: await pageTargetWsUrl(backend.cdpEndpoint()),
+    attached: false,
+  };
+}
+
+/**
+ * Rev-5 Electron webview guests can return a transparent PNG base even when
+ * the page looks white. Keep the old white-flatten pass only for an attached
+ * target positively identified as `webview`; native pages and headless
+ * Chromium skip the process entirely.
+ */
+function flattenPng(buffer) {
+  const { spawn } = require('child_process');
+  return cdp.deadline(new Promise((resolve) => {
+    const child = spawn(cli.ffmpegBinary(), [
+      '-y', '-f', 'image2pipe', '-c:v', 'png', '-i', 'pipe:0',
+      '-filter_complex', '[0:v]format=rgba,split[fg1][fg2];[fg1]drawbox=color=white:t=fill[bg];'
+        + '[bg][fg2]overlay=format=auto,format=rgb24',
+      '-frames:v', '1', '-f', 'image2pipe', '-c:v', 'png', 'pipe:1',
+    ], { stdio: ['pipe', 'pipe', 'ignore'] });
+    const chunks = [];
+    child.stdout.on('data', (chunk) => chunks.push(chunk));
+    child.on('error', () => resolve(buffer));
+    child.on('close', (code) => {
+      const output = Buffer.concat(chunks);
+      resolve(code === 0 && output.length ? output : buffer);
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(buffer);
+  }), 10_000, 'screenshot flatten').catch(() => buffer);
 }
 
-/** Why a guest capture starved, in words an agent can act on. */
+function shouldFlattenCapture(source) {
+  return source?.attached === true && source?.legacyWebview === true;
+}
+
+/** Why an attached capture starved, in words an agent can act on. */
 function starvationReason() {
-  return 'the browser surface is not rendering. Its tab in the Amalgm app is hidden '
-    + '(the app refocuses it automatically — retry), or the app is gone. '
+  return 'the browser surface compositor is unavailable while the app is closing '
+    + 'or recreating that surface. Retry once; if the app is gone, reopen it. '
     + 'AMALGM_BROWSER_BACKEND=cli forces a headless browser instead';
 }
 
 /**
- * The guest's viewport as a CSS-pixel clip. Captures render at the device
+ * The attached surface viewport as a CSS-pixel clip. Captures render at the device
  * scale factor; scale divides it back out so the image is CSS-pixel sized
  * and its coordinates map 1:1 onto cua_click/cua_move input.
  */
@@ -95,7 +131,7 @@ async function cssViewportClip(client) {
  * failure — an actionable refusal at start instead of an empty file at stop.
  */
 async function assertCapturable(client, source) {
-  if (!source.guest) return; // headless page targets raster unconditionally
+  if (!source.attached) return; // headless page targets raster unconditionally
   try {
     await client.call('Page.captureScreenshot', {
       format: 'jpeg',
@@ -107,42 +143,13 @@ async function assertCapturable(client, source) {
   }
 }
 
-/**
- * Electron <webview> guests raster over a transparent base, so a page
- * without its own background captures with alpha — which viewers and
- * encoders composite as black. (CDP's background override is a no-op on
- * guests; verified live.) Flatten guest PNGs onto white with the bundled
- * ffmpeg — the pixels are intact under the alpha. Headless page targets
- * raster opaque and skip this entirely.
- */
-function flattenPng(buffer) {
-  const { spawn } = require('child_process');
-  return cdp.deadline(new Promise((resolve) => {
-    const child = spawn(cli.ffmpegBinary(), [
-      '-y', '-f', 'image2pipe', '-c:v', 'png', '-i', 'pipe:0',
-      '-filter_complex', '[0:v]format=rgba,split[fg1][fg2];[fg1]drawbox=color=white:t=fill[bg];'
-        + '[bg][fg2]overlay=format=auto,format=rgb24',
-      '-frames:v', '1', '-f', 'image2pipe', '-c:v', 'png', 'pipe:1',
-    ], { stdio: ['pipe', 'pipe', 'ignore'] });
-    const chunks = [];
-    child.stdout.on('data', (chunk) => chunks.push(chunk));
-    child.on('error', () => resolve(buffer)); // no ffmpeg — alpha beats no image
-    child.on('close', (code) => {
-      const out = Buffer.concat(chunks);
-      resolve(code === 0 && out.length ? out : buffer);
-    });
-    child.stdin.on('error', () => {});
-    child.stdin.end(buffer);
-  }), 10_000, 'screenshot flatten').catch(() => buffer);
-}
-
 async function screenshot(session, args = {}, context) {
   const fullPage = Boolean(args.fullPage);
   const source = await plan(session, context);
   const client = await cdp.connectCdp(source.wsUrl);
   try {
     const params = { format: 'png' };
-    if (source.guest || !fullPage) {
+    if (source.attached || !fullPage) {
       // Every backend normalizes to CSS pixels — a dpr-2 display would
       // otherwise return a 2x image whose coordinates no longer match the
       // cua_* input space.
@@ -165,19 +172,20 @@ async function screenshot(session, args = {}, context) {
     try {
       ({ data } = await client.call('Page.captureScreenshot', params, SCREENSHOT_TIMEOUT_MS));
     } catch (err) {
-      if (source.guest && /timed out/i.test(String(err.message || ''))) {
+      if (source.attached && /timed out/i.test(String(err.message || ''))) {
         throw new Error(`Screenshot starved: ${starvationReason()}.`);
       }
       throw err;
     }
     if (!data) throw new Error('Empty screenshot response');
-    const image = source.guest
-      ? await flattenPng(Buffer.from(data, 'base64'))
-      : Buffer.from(data, 'base64');
+    const rawImage = Buffer.from(data, 'base64');
+    const image = shouldFlattenCapture(source)
+      ? await flattenPng(rawImage)
+      : rawImage;
     return {
       base64: image.toString('base64'),
       bytes: image.length,
-      mode: source.guest ? 'visible surface' : (fullPage ? 'full page' : 'viewport'),
+      mode: source.attached ? 'visible surface' : (fullPage ? 'full page' : 'viewport'),
     };
   } finally {
     client.close();
@@ -195,6 +203,7 @@ module.exports = {
   plan,
   rectScript: cdp.rectScript,
   screenshot,
+  shouldFlattenCapture,
   starvationReason,
   targetListUrl: cdp.targetListUrl,
 };

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

@@ -116,14 +116,14 @@ function pageTargets(targets) {
 }
 
 /**
- * Locate the session's <webview> element inside a candidate app window.
+ * Locate the session's browser-surface marker inside a candidate app window.
  * Identity, strongest first:
  *  - data-amalgm-surface attribute — stamped once at mount, survives
  *    navigation (the src attribute is rewritten on every navigate, so the
  *    marker URL it starts with does not last);
- *  - marker still in the src attribute — fresh, never-navigated surfaces;
+ *  - marker still in the live URL — fresh, never-navigated surfaces;
  *  - exact current URL — old-app fallback, needs a fresh hint.
- * Never "the only webview": adopting an unidentified surface is how one
+ * Never "the only surface": adopting an unidentified surface is how one
  * chat's session ends up driving another chat's page.
  *
  * A session can match several elements — remounts (chat-tab switches) leave
@@ -132,24 +132,25 @@ function pageTargets(targets) {
  * capturable surface used to be reported as "hidden".
  *
  * Returns layout geometry only when a matched element has on-screen size,
- * plus the embedder's visibilityState and the webview's live URL (to re-find
+ * plus the embedder's visibilityState and the surface's live URL (to re-find
  * the daemon-side target after a restart).
  */
 function rectScript(markerText, currentUrl) {
   const urlLiteral = JSON.stringify(String(currentUrl || ''));
   return `(() => {
-    const views = [...document.querySelectorAll('webview')];
+    const views = [...document.querySelectorAll('[data-amalgm-surface]')];
+    const liveUrl = (w) => w.getAttribute('data-amalgm-url') || w.src || w.getAttribute('src') || '';
     const matches = [
       ...views.filter((w) => (w.getAttribute('data-amalgm-surface') || '').includes(${JSON.stringify(markerText)})),
-      ...views.filter((w) => (w.getAttribute('src') || '').includes(${JSON.stringify(markerText)})),
-      ...(${urlLiteral} ? views.filter((w) => (w.src || '') === ${urlLiteral}) : []),
+      ...views.filter((w) => liveUrl(w).includes(${JSON.stringify(markerText)})),
+      ...(${urlLiteral} ? views.filter((w) => liveUrl(w) === ${urlLiteral}) : []),
     ];
     if (!matches.length) return null;
     const sized = matches.map((w) => ({ w, r: w.getBoundingClientRect() }));
     const match = sized.find(({ r }) => r.width && r.height);
     if (!match) return null;
     const { w, r } = match;
-    return JSON.stringify({ x: r.x, y: r.y, width: r.width, height: r.height, vw: window.innerWidth, vh: window.innerHeight, dpr: window.devicePixelRatio || 1, src: w.src || '', embedderVisibility: document.visibilityState });
+    return JSON.stringify({ x: r.x, y: r.y, width: r.width, height: r.height, vw: window.innerWidth, vh: window.innerHeight, dpr: window.devicePixelRatio || 1, src: liveUrl(w), embedderVisibility: document.visibilityState });
   })()`;
 }
 
@@ -164,8 +165,8 @@ async function embedderRect(cdp, markerText, currentUrl) {
 }
 
 /**
- * Find the app window hosting the session's webview and the webview's
- * on-screen rectangle. Null when the surface is hidden (or no webview
+ * Find the app window hosting the session's marker and its on-screen
+ * rectangle. Null when the surface is hidden (or no marker
  * matches) — callers decide whether to reopen or fail.
  */
 async function findSurfaceRect(endpoint, markerText, currentUrl) {

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

@@ -135,7 +135,7 @@ function baseArgs(session, json = true, cdp = null) {
     '--screenshot-dir', screenshotDir(),
   ];
   // Raw CDP attach (drives an existing chromium — e.g. the Amalgm desktop
-  // app's visible webview — instead of launching one). Must be passed on
+  // app's native browser page — instead of launching one). Must be passed on
   // every command: `connect` launches a managed browser, which is not what
   // attached mode wants.
   if (cdp) args.push('--cdp', String(cdp));

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

@@ -463,7 +463,7 @@ async function close(args = {}, context) {
     try { await recorder.stop({ ...args, session }, context); } catch {}
   }
   // Tear down this session's daemon. In attached mode this only disconnects
-  // from the app's chromium (verified live: the app, its webviews, and other
+  // from the app's Chromium (verified live: the app, its native pages, and other
   // sessions' daemons survive). Without this, every attached session leaks a
   // daemon process for the life of the machine.
   try {
@@ -473,7 +473,7 @@ async function close(args = {}, context) {
   }
   // Tell the UI to unmount the splitview/tab. Each surface is a full
   // renderer process; ended sessions must not accumulate them (ten zombie
-  // webviews were live in the app when this was written).
+  // browser surfaces were live in the app when this was written).
   if (sessions.surfaces.has(session) || sessions.knownSessions.has(session)) {
     attach.requestSurfaceClose(session);
   }
@@ -498,6 +498,7 @@ module.exports = {
   cdpEndpoint: backend.cdpEndpoint,
   modeFor: backend.modeFor,
   readBridgeAdvertisement: backend.readBridgeAdvertisement,
+  surfaceTargetTypes: backend.surfaceTargetTypes,
   // Session façade (sessions.js).
   backendFor: sessions.backendFor,
   ensureCookieSourceLoaded,

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

@@ -3,8 +3,9 @@
 /**
  * Recorder actions — session recording as a first-class primitive any agent
  * can use (QA bots especially). Captures the browser session — including the
- * desktop app's visible in-tab webview, cropped so the file shows only the
- * page — to a local WebM stored with the Amalgm project the work belongs to.
+ * desktop app's native in-tab page, cropped so the file shows only the
+ * page directly — to a local WebM stored with the Amalgm project the work
+ * belongs to.
  */
 
 const { textResult, errorResult } = require('../lib/tool-result');

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

@@ -4,7 +4,7 @@
  * Session recorder: capture any browser session to a local WebM file.
  *
  * Frames come from capture.js (CDP Page.startScreencast on the session's own
- * page target — the headless page, or the attached <webview> guest itself)
+ * page target — the headless page or the attached native surface itself)
  * and pipe into ffmpeg. The frames are the page and nothing else, so no
  * cropping is ever needed; recordings are local-only and nothing leaves this
  * computer.
@@ -13,7 +13,7 @@
  *  - `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.
+ *    it can never capture the in-tab native surface.
  *
  * Storage: recordings belong to the Amalgm project the work is for —
  * <project>/.amalgm/recordings/ when a project path is known, otherwise
@@ -171,11 +171,9 @@ async function start(args = {}, context = {}) {
 
   const file = recordingFile(args, context, session);
   const fps = clampFps(args.fps);
-  // Frames arrive as PNG with alpha: Electron <webview> guests raster over a
-  // transparent base, so a page without its own background would encode as
-  // black. Composite every frame onto white before the encoder sees it
-  // (opaque headless frames pass through unchanged), then pad to the even
-  // dimensions VP8 wants.
+  // Composite every frame onto white for legacy transparent sources, then
+  // pad to the even dimensions VP8 wants. Opaque native-page frames pass
+  // through unchanged.
   const filters = '[0:v]format=rgba,split[fg1][fg2];[fg1]drawbox=color=white:t=fill[bg];'
     + '[bg][fg2]overlay=format=auto,pad=ceil(iw/2)*2:ceil(ih/2)*2,format=yuv420p';
 
@@ -246,7 +244,7 @@ async function start(args = {}, context = {}) {
     fps,
     mimeType: 'video/webm',
     backend: sessions.backendFor(session),
-    source: source.guest ? 'visible surface' : 'page',
+    source: source.attached ? 'visible surface' : 'page',
   };
 }
 

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

@@ -15,13 +15,13 @@ const backend = require('./backend');
 
 /**
  * Attached surfaces: session -> { tabId, targetId, wsUrl, embedderWsUrl,
- * client, external }. An entry exists exactly while its guest CDP connection
+ * client, external }. An entry exists exactly while its page CDP connection
  * is open — the connection's close handler removes it, so presence means
  * live. attach.js owns the lifecycle.
  */
 const surfaces = new Map();
 
-/** Per-session bookkeeping: webviewTabId, lastActiveAt, last url/title. */
+/** Per-session bookkeeping: surfaceTabId, lastActiveAt, last url/title. */
 const knownSessions = new Map();
 
 /**

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

@@ -36,7 +36,7 @@ test('rectScript identifies the session surface and never guesses', () => {
   // No current URL → the byUrl branch is disabled, not matching everything.
   const bare = capture.rectScript('amalgm-bsid-abc', '');
   assert.match(bare, /"" \? views\.filter/);
-  // "The only webview" is how one chat's capture reads another chat's page —
+  // "The only surface" is how one chat's capture reads another chat's page —
   // an unidentified surface must resolve to null, never to a guess.
   assert.doesNotMatch(script, /views\.length === 1/);
   // Remounts leave stale 0x0 copies of a session's surface behind; the match
@@ -70,9 +70,9 @@ test('rectScript prefers the on-screen copy over a stale 0x0 duplicate', async (
   assert.equal(rect.src, 'https://example.com/');
 });
 
-test('starvationReason names the real precondition: the surface tab', () => {
+test('starvationReason names the real precondition: the surface compositor', () => {
   const reason = capture.starvationReason();
-  assert.match(reason, /tab in the Amalgm app is hidden/);
+  assert.match(reason, /surface compositor is unavailable/);
   assert.match(reason, /AMALGM_BROWSER_BACKEND=cli/);
   // Window state is irrelevant since the app keeps attached surfaces
   // compositing while hidden — the message must not send users window-hunting.
@@ -83,11 +83,17 @@ test('assertCapturable converts a starved probe into a named refusal', async ()
   const starvedClient = { call: () => new Promise(() => {}) };
   const probe = capture.assertCapturable(
     { call: (m, p, t) => capture.deadline(new Promise(() => {}), 50, m) },
-    { guest: true },
+    { attached: true },
   );
-  await assert.rejects(() => probe, /Cannot capture this surface: .*tab in the Amalgm app is hidden/);
+  await assert.rejects(() => probe, /Cannot capture this surface: .*surface compositor is unavailable/);
   // Headless page targets raster unconditionally — no probe, no rejection.
-  await capture.assertCapturable(starvedClient, { guest: false });
+  await capture.assertCapturable(starvedClient, { attached: false });
+});
+
+test('only a positively identified rev-5 webview uses PNG flattening', () => {
+  assert.equal(capture.shouldFlattenCapture({ attached: true, legacyWebview: true }), true);
+  assert.equal(capture.shouldFlattenCapture({ attached: true, legacyWebview: false }), false);
+  assert.equal(capture.shouldFlattenCapture({ attached: false, legacyWebview: true }), false);
 });
 
 test('targetListUrl accepts bare ports and ws urls', () => {

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

@@ -95,6 +95,42 @@ test('ownership routing: a fresh advertisement attaches desktop-born chats ONLY'
   });
 });
 
+test('bridge compatibility: missing protocol means rev-5 webview, rev-6 means page', () => {
+  const legacyDir = tempDir('bridge-v5');
+  writeAdvertisement(legacyDir, {
+    cdpUrl: 'ws://127.0.0.1:9242/devtools/browser/legacy',
+    cdpPort: 9242,
+    pid: process.pid,
+  });
+  withEnv({ AMALGM_RUNTIME_STATE_DIR: legacyDir }, () => {
+    assert.equal(engine.readBridgeAdvertisement().surfaceProtocol, 5);
+    assert.deepEqual(engine.surfaceTargetTypes(), ['webview']);
+  });
+
+  const nativeDir = tempDir('bridge-v6');
+  writeAdvertisement(nativeDir, {
+    browserSurfaceProtocol: 6,
+    browserSurfaceTargetType: 'page',
+    browserSurfaceTargetTypes: ['page', 'webview'],
+    cdp: {
+      url: 'ws://127.0.0.1:9342/devtools/browser/native',
+      port: 9342,
+    },
+    pid: process.pid,
+  });
+  withEnv({ AMALGM_RUNTIME_STATE_DIR: nativeDir }, () => {
+    assert.equal(engine.readBridgeAdvertisement().surfaceProtocol, 6);
+    assert.deepEqual(engine.surfaceTargetTypes(), ['page', 'webview']);
+    assert.equal(engine.cdpEndpoint(), '9342');
+  });
+});
+
+test('bridge compatibility: explicit CDP probes both Electron generations', () => {
+  withEnv({ AMALGM_BROWSER_CDP_URL: 'ws://127.0.0.1:9442/devtools/browser/operator' }, () => {
+    assert.deepEqual(engine.surfaceTargetTypes(), ['page', 'webview']);
+  });
+});
+
 test('ownership routing: stale advertisement (dead pid) means headless', () => {
   const stateDir = tempDir('stale');
   writeAdvertisement(stateDir, {
@@ -171,17 +207,17 @@ test('entrypoint routing: candidate order is state dir, derived label dir, AMALG
 
 // ---------------------------------------------------------------------------
 // Session → surface routing. The 2026-06-10 stress tests caught two parallel
-// chats reading each other's pages: a displaced session (its webview died on
-// a chat-tab switch) fell back to "the only webview" — someone else's.
+// chats reading each other's pages: a displaced session (its surface died on
+// a chat-tab switch) fell back to "the only surface" — someone else's.
 // ---------------------------------------------------------------------------
 
 test('surface routing: marker first, then the embedder DOM src as candidates', () => {
   const attach = require('../browser/attach');
 
-  const fresh = { tabId: 't2', type: 'webview', url: 'about:blank#amalgm-bsid-s1' };
-  const navigated = { tabId: 't3', type: 'webview', url: 'https://example.com/' };
-  const twin = { tabId: 't5', type: 'webview', url: 'https://example.com/' };
-  const other = { tabId: 't4', type: 'webview', url: 'https://other.test/' };
+  const fresh = { tabId: 't2', type: 'page', url: 'about:blank#amalgm-bsid-s1' };
+  const navigated = { tabId: 't3', type: 'page', url: 'https://example.com/' };
+  const twin = { tabId: 't5', type: 'page', url: 'https://example.com/' };
+  const other = { tabId: 't4', type: 'page', url: 'https://other.test/' };
 
   // Fresh surface: the marker URL identifies it exactly.
   assert.deepEqual(attach.identityCandidates([other, fresh], 's1', null), [fresh]);
@@ -198,11 +234,11 @@ test('surface routing: marker first, then the embedder DOM src as candidates', (
   );
 });
 
-test('surface routing: an unidentified lone webview is never adopted', () => {
+test('surface routing: an unidentified lone page is never adopted', () => {
   const attach = require('../browser/attach');
-  // One webview left and it is not provably ours — that is the cross-chat
+  // One page left and it is not provably ours — that is the cross-chat
   // leak shape. Fail closed; ensureReady reopens a marked surface instead.
-  const stranger = { tabId: 't9', type: 'webview', url: 'https://another-chats-page.test/' };
+  const stranger = { tabId: 't9', type: 'page', url: 'https://another-chats-page.test/' };
   assert.deepEqual(attach.identityCandidates([stranger], 'displaced-session', null), []);
   assert.deepEqual(attach.identityCandidates([], 'displaced-session', null), []);
 });

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

@@ -148,7 +148,7 @@ console.log(JSON.stringify({ success: true, data: cmds.map((c) => ({ command: c,
   process.env.AMALGM_BROWSER_CDP_URL = '9242';
   // A live surface record makes ensureReady a no-op and turns the guard on.
   surfaces.set('guard-test', { tabId: 't7', wsUrl: 'ws://x/guest', client: { close() {} }, external: false });
-  knownSessions.set('guard-test', { webviewTabId: 't7' });
+  knownSessions.set('guard-test', { surfaceTabId: 't7' });
   try {
     const single = await attach.run('guard-test', ['get', 'url'], { timeoutMs: 5000 });
     assert.deepEqual(single.data, { echoed: ['get', 'url'] }, 'single result keeps its unbatched shape');

package/runtime/scripts/amalgm-mcp/tests/workspace-checkpoint.test.js

@@ -169,6 +169,18 @@ test('checkpoint captures are local cache; their operations travel on the one wa
   assert.match(first, /repo-checkpoints-v7/);
 });
 
+test('a materialized peer card is immediately a valid checkpoint base', () => {
+  const oid = 'a'.repeat(40);
+  assert.equal(_test.checkpointBaseReady({
+    head: { branch: 'main', oid },
+  }, {
+    branch: 'main',
+    baseOid: oid,
+    indexDiff: '',
+    worktreeDiff: '',
+  }), true);
+});
+
 test('an uploading checkpoint payload is not published as a transition', () => {
   const pending = {
     revision: 'a'.repeat(64),

package/runtime/scripts/amalgm-mcp/workspace/checkpoint.js

@@ -178,6 +178,16 @@ function readCheckpointValue(baseOid, value) {
   return { state: 'ready', indexDiff, worktreeDiff };
 }
 
+function checkpointBaseReady(card, reduced) {
+  return Boolean(
+    reduced
+    && reduced.baseOid === card.head?.oid
+    && reduced.branch === card.head?.branch
+    && typeof reduced.indexDiff === 'string'
+    && typeof reduced.worktreeDiff === 'string'
+  );
+}
+
 async function publishPass(replicaId = null) {
   const machine = machineId();
   const run = { published: 0, skips: 0, waiting: 0, failures: 0 };
@@ -187,16 +197,8 @@ async function publishPass(replicaId = null) {
     const repoKey = repoKeyOfCard(card);
     if (!repoKey || !card.head?.oid) continue;
     try {
-      const publishedCard = require('./wall').publishedCardFor(card);
       const reduced = require('./reducer').readRepoState(repoKey);
-      if (
-        !publishedCard
-        || !reduced
-        || reduced.baseOid !== card.head.oid
-        || reduced.branch !== card.head.branch
-        || typeof reduced.indexDiff !== 'string'
-        || typeof reduced.worktreeDiff !== 'string'
-      ) {
+      if (!checkpointBaseReady(card, reduced)) {
         run.waiting += 1;
         continue;
       }
@@ -372,6 +374,7 @@ function checkpointStats() {
 
 module.exports = {
   _test: {
+    checkpointBaseReady,
     checkpointForSharedState,
   },
   CHECKPOINT_CONTRACT,