@amalgm/browser 0.1.2-preview.34176754339 → 0.1.2-preview.34320564379

package/PURPOSE.md

@@ -9,15 +9,17 @@ and REST API while selecting the correct underlying browser implementation
 from host context. In the macOS desktop app, browser work can occur in a
 visible Electron surface that the user can watch and control. Everywhere else,
 the same work runs in an isolated headless Chromium session. Browser state
-belongs to Browser, never to Chat, Agents, Engine, or the application renderer.
+belongs to Browser, never to Chat, Agents, Shell, Engine, or the application
+renderer.
 
 Browser serves users browsing visibly in Amalgm, agents using Browser through
 a Toolbox, background automations and sub-agents, standalone SDK and CLI
 consumers, MCP and REST clients, and future browser-driver implementations.
 
-Amalgm Engine is a composition root. It may provide host capabilities,
-execution context, artifact storage, event relay, and UI composition through
+Amalgm Shell is the active composition root. It may provide host capabilities,
+execution context, artifact storage, event relay, and UI coordination through
 public Browser ports. It does not own a second browser implementation.
+Amalgm Engine is historical reference evidence only.
 
 ## Primitives
 
@@ -73,7 +75,7 @@ including the exact two-parent merge commit that becomes managed source.
 Managed releases bind to one exact published Core version and build from the
 locked dependency graph on the supported Node toolchain.
 
-1. Browser owns browser state and never depends on Chat, Agents, Engine,
+1. Browser owns browser state and never depends on Chat, Agents, Shell, Engine,
    Realtime, or an application renderer to define it.
 2. Every state change passes through `BrowserService`; drivers execute actions
    and adapters expose the service without reimplementing its rules.
@@ -82,9 +84,11 @@ locked dependency graph on the supported Node toolchain.
 4. Every page and visible surface belongs to exactly one session. Visible
    identity is stamped and verified; ambiguity or mismatch fails closed before
    an action, and reconnection may only recover the same verified surface.
-5. A fresh compatible desktop host selects Electron, an explicit operator CDP
-   endpoint selects CDP-capable headless execution, and everything else selects
-   headless. A standalone headed window is always explicit.
+5. Requested capability and fresh host evidence select a backend before session
+   creation. Work requiring a visible surface selects a compatible Electron
+   host or fails clearly; background work selects headless; work that merely
+   prefers visibility may fall back to headless. An explicit operator CDP
+   endpoint and a standalone headed window are always deliberate overrides.
 6. One action has one meaning across drivers. Backend differences are explicit
    capabilities or typed unsupported-operation errors.
 7. Cancellation and deadlines reach the underlying CDP call, encoder, fetch,
@@ -120,16 +124,20 @@ locked dependency graph on the supported Node toolchain.
 17. TypeScript under `src/` and `bin/` is the sole implementation source. The
     SDK owns behavior; CLI, MCP, REST, Toolbox, and Electron IPC remain thin
     adapters with parity tests.
-18. Browser installs and operates without Engine or Electron. Behavior on an
-    unseen session follows from these axioms without another special case.
+18. Browser installs and operates without Shell, Engine, or Electron. Behavior
+    on an unseen session follows from these axioms without another special case.
+19. Shell composes exactly one Browser service. Electron supplies a hardened
+    visible host and isolated cookie adapter to that service; it never creates a
+    second Browser registry, session authority, or action implementation.
 
 ## Predictable behavior
 
-Before session creation, the host context selects one capable backend. The
-session keeps that backend until close; a lost visible page either verifies and
-reattaches to its original stamped surface or fails before acting. All public
-surfaces dispatch the same typed action through `BrowserService`. Headless work
-stays headless unless a caller explicitly asks for a headed debug window.
+Before session creation, the requested capability and host context select one
+capable backend. The session keeps that backend until close; a lost visible page
+either verifies and reattaches to its original stamped surface or fails before
+acting. All public surfaces dispatch the same typed action through
+`BrowserService`. Background work stays headless unless visibility is requested
+or an operator explicitly asks for a headed debug window.
 
 The visible Electron partition and every headless profile keep physically
 separate Chromium stores. Their adapters may reconcile individual cookie
@@ -137,9 +145,15 @@ records through Browser's encrypted jar, including tombstoned deletions, but
 they cannot inspect one another. Named auth bundles are separate, explicit
 snapshots. Captures, input coordinates, and recordings all address the same
 verified page, while large artifacts leave the API through the injected store.
-Engine and Realtime can compose and relay Browser without becoming Browser.
+Shell and Realtime can compose and relay Browser without becoming Browser.
 
 The Browser build supplies its Electron CommonJS adapter and companion preload as
 SDK-owned artifacts; a UI copies those bytes without rebuilding Browser behavior.
 Desktop bridge discovery uses one host-selected machine namespace and a validated
 Core binding; neither a shared user root nor an unknown lane selects another host.
+
+Headless source examinations provision Chrome through the locked agent-browser
+launcher and record the actual browser identity and failing operation. Installing
+the npm dependency supplies the launcher, not Chrome; ambient browser discovery
+is not proof that the declared browser prerequisite was provisioned. Process
+and test deadlines retain the same bounds during diagnosis.

package/README.md

@@ -5,17 +5,24 @@ isolated headless automation. Its TypeScript SDK owns behavior; the CLI, MCP
 server, REST API, Toolbox manifest, Electron host integration, and packaged
 skill are projections of the same actions.
 
-Browser is independent of Amalgm Engine, Chat, Agents, Tools, and Realtime.
+Browser is independent of Amalgm Shell, Engine, Chat, Agents, Tools, and
+Realtime. Shell composes Browser through its public ports; it does not define
+Browser behavior.
 Read the [purpose and axioms](./PURPOSE.md) for the product contract.
 
 ## Install
 
-Node.js 20 or newer is required.
+Node.js 24 or newer is required.
 
 ```sh
 npm install @amalgm/browser
+npx --no-install agent-browser install
 ```
 
+The `agent-browser` dependency supplies the launcher. Its `install` command
+downloads Chrome for Testing; an existing Chrome or an explicit CDP endpoint
+can also supply the browser.
+
 Electron is an optional peer dependency. Server consumers can install and
 import the core or headless exports without loading Electron.
 
@@ -36,7 +43,7 @@ const snapshot = await browser.execute(session.id, { type: 'snapshot' });
 await browser.closeSession(session.id);
 ```
 
-Standalone use selects the bundled headless runtime. A desktop composition can
+Standalone use selects the headless runtime. A desktop composition can
 inject `ElectronBrowserDriver`; an explicit `AMALGM_BROWSER_CDP_URL` attaches
 the headless driver to an operator-owned Chromium endpoint. Backend selection
 happens before session creation and never changes during the session.
@@ -102,8 +109,8 @@ uses its local fallback. See [recording](./docs/RECORDING.md).
   `WebContentsView` surfaces, identity, shell policy, cookies, and ad blocking.
 - [Toolbox integration](./docs/TOOLBOX_INTEGRATION.md) covers the single
   `browser` tool, capability grants, and legacy aliases.
-- [Engine integration](./docs/ENGINE_INTEGRATION.md) covers composition and a
-  no-dual-writer cutover. Engine changes are deliberately a later stage.
+- [Shell integration](./docs/SHELL_INTEGRATION.md) covers the one-service
+  composition boundary and the historical Engine cutover rule.
 
 ## Verify
 
@@ -115,7 +122,7 @@ npm run test:electron   # macOS real-Electron harness
 
 Verification covers strict TypeScript, the 220-line source limit, runtime and
 adapter contracts, migration fixtures, package installation, and tarball
-hygiene. The opt-in suites use real bundled Chromium and real Electron.
+hygiene. The opt-in suites use real Chromium and real Electron.
 
 The complete documentation index is [docs/README.md](./docs/README.md).
 

package/docs/AXIOMS.md

@@ -1,6 +1,6 @@
 # Axiom map
 
-[PURPOSE.md](../PURPOSE.md) is the authoritative list of primitives and 18
+[PURPOSE.md](../PURPOSE.md) is the authoritative list of primitives and 19
 product axioms. This document maps them to observable boundaries.
 
 | Axioms | Consequence | Evidence |
@@ -12,7 +12,8 @@ product axioms. This document maps them to observable boundaries.
 | 14 | Capture and recording address the actual page | DPR, target, sampler, and real-runtime tests |
 | 15 | Context enters through ports; events are sanitized | artifact and SSE contracts |
 | 16 | Existing state is imported safely | transactional legacy fixture test |
-| 17–18 | One TypeScript implementation works without Engine/Electron | package install and adapter parity tests |
+| 17–18 | One TypeScript implementation works without Shell, Engine, or Electron | package install and adapter parity tests |
+| 19 | Shell composes one Browser service; Electron is a host adapter | Shell composition and Electron harness tests |
 
 When behavior fails, classify it against this map. If code drifted, restore the
 axiom everywhere it applies. If the axiom is incomplete, update

package/docs/COMPATIBILITY.md

@@ -2,8 +2,9 @@
 
 ## Runtime and package
 
-- Node.js: 20 or newer
-- modules: ESM import only
+- Node.js: 24 or newer
+- modules: ESM core imports; ESM and generated CommonJS for
+  `@amalgm/browser/electron`
 - Electron: optional peer, version 33 or newer
 - Electron surface protocols: writes protocol 6; reads protocols 5 and 6
 - Browser partition: exactly `persist:amalgm-browser`
@@ -21,11 +22,11 @@ Historical aggregate Browser grants, older prefixed IDs, and individual
 `cua_*` names are normalized in the Toolbox compatibility adapter. They are
 not core action aliases and never create doubled Browser prefixes.
 
-## Engine routes and data
+## Historical Engine routes and data
 
-Engine can keep its previous HTTP/IPC route shapes during rolling integration
-by delegating into this SDK. Raw cookie bootstrap and merge must use the
-restricted adapter transport, not public OpenAPI.
+During a bounded historical cutover, Engine routes may delegate into this SDK.
+They must not remain as a parallel production implementation. Raw cookie
+bootstrap and merge use the restricted adapter transport, not public OpenAPI.
 
 Legacy Engine profiles, encrypted auth/cookie-source bundles, cookie
 tombstones, and login sessions are supported by the versioned importer. Paths

package/docs/ELECTRON_INTEGRATION.md

@@ -3,6 +3,12 @@
 Electron is an optional peer dependency and appears only behind
 `@amalgm/browser/electron`. Headless consumers do not load it.
 
+The published Electron entry has both ESM and generated CommonJS conditions.
+Desktop builds may copy `electron.cjs` and `electron-preload.cjs` into their
+own generated output so Electron ships the native adapter without the full
+headless dependency graph. Both files are build products of Browser's
+TypeScript source and must never be edited or reimplemented by a host app.
+
 ## Composition
 
 The package contains both sides of the visible boundary:

package/docs/EVENTS.md

@@ -26,5 +26,5 @@ authorization headers, and captured pixels are forbidden.
 and heartbeat comments. A disconnect removes the listener. A missing history
 cursor safely returns retained history rather than inventing ordering.
 
-Engine or Realtime may relay these events verbatim. That relay does not become
+Shell or Realtime may relay these events verbatim. That relay does not become
 the Browser authority and must not enrich an event with Browser secrets.

package/docs/HEADLESS_RUNTIME.md

@@ -53,6 +53,6 @@ image-only, or hostile custom controls; prefer snapshot references elsewhere.
 
 ## Real verification
 
-`npm run test:real` launches the bundled Chromium runtime and verifies
+`npm run test:real` launches the installed Chromium runtime and verifies
 navigation, snapshot, exact-target CDP capture, DPR normalization, page-scoped
 typing, and real page-only recording.

package/docs/MCP.md

@@ -2,7 +2,7 @@
 
 Run `amalgm-browser-mcp` or `amalgm-browser mcp`. The server speaks
 newline-delimited JSON-RPC over stdio and implements MCP tool listing and tool
-calls without Engine.
+calls without Shell or Engine.
 
 The 22 tools are the canonical action names prefixed with `browser_`:
 

package/docs/README.md

@@ -12,10 +12,12 @@ your integration:
   [recording](./RECORDING.md)
 - [Events](./EVENTS.md) and the [Realtime boundary](./REALTIME_BOUNDARY.md)
 - [Toolbox](./TOOLBOX_INTEGRATION.md) and
-  [Engine](./ENGINE_INTEGRATION.md) composition
+  [Shell](./SHELL_INTEGRATION.md) composition
 - [Migration](./MIGRATION.md) and [compatibility](./COMPATIBILITY.md)
 - [Operations](./OPERATIONS.md), [testing](./TESTING.md), and
   [troubleshooting](./TROUBLESHOOTING.md)
 
-The package is ESM-only, requires Node.js 20+, and exposes deliberate entry
-points rather than internal implementation modules.
+The core package is ESM-only and requires Node.js 24+. The deliberate
+`@amalgm/browser/electron` entry point additionally provides a generated
+CommonJS condition for Electron main processes; no internal implementation
+module is public.

package/docs/SDK.md

@@ -1,6 +1,6 @@
 # TypeScript SDK
 
-The package is ESM-only and supports Node.js 20 or newer.
+The package is ESM-only and supports Node.js 24 or newer.
 
 ```ts
 import { createBrowser, BrowserError } from '@amalgm/browser';

package/docs/SHELL_INTEGRATION.md

@@ -0,0 +1,54 @@
+# Shell integration
+
+Amalgm Shell consumes `@amalgm/browser`; Browser never imports Shell. Shell is
+the active composition root, while the old Engine implementation is historical
+migration evidence only.
+
+## Composition boundary
+
+One Shell runtime constructs exactly one `BrowserProductService` and exposes
+its MCP and HTTP adapters. It may inject caller context, authorization,
+artifacts, events, and an optional visible-host driver. It does not translate
+actions or create another registry, cookie jar, profile store, or session
+authority.
+
+This composition becomes active only in a signed machine service plan that
+declares Browser. Merely installing the SDK must not create Browser databases
+or portable state in a Core-and-Files-only release.
+
+```ts
+import { createBrowser } from '@amalgm/browser';
+import { ElectronBrowserDriver } from '@amalgm/browser/electron';
+
+const browser = createBrowser({
+  root: shellBrowserRoot,
+  electronDriver: visibleHost
+    ? new ElectronBrowserDriver(visibleHost)
+    : undefined,
+  eventSink: browserEventRelay,
+  authorization: shellBrowserAuthorization,
+});
+```
+
+Background work selects the headless driver. Work requiring a visible surface
+selects the compatible Electron host before the session is created and fails
+clearly when that capability is absent. The backend is immutable for the
+session lifetime.
+
+## Electron boundary
+
+Electron owns application lifecycle and supplies Browser's hardened native
+surface host plus the isolated Browser cookie adapter. React supplies visual
+chrome and bounds. Neither is a second Browser service. Application auth stays
+in Electron's `defaultSession`; websites stay in `persist:amalgm-browser`.
+
+The UI and Shell must bind to the same exact published Browser release. A
+desktop build copies Browser's generated native adapter, while Shell installs
+the complete SDK for headless and service execution.
+
+## Historical cutover rule
+
+Legacy Engine data may be imported once through `legacyDatabaseFile`. The
+importer is read-only with respect to the legacy database. Old and new writers
+must never run against the same Browser state; after cutover, Engine Browser
+code is deleted rather than retained as a fallback.

package/docs/TESTING.md

@@ -7,7 +7,8 @@ real browser processes.
 ```sh
 npm run check          # tree hygiene and strict TypeScript
 npm test               # unit and transport contracts
-npm run test:real      # real bundled headless Chromium
+npx --no-install agent-browser install # provision Chrome for Testing
+npm run test:real      # real headless Chromium
 npm run test:electron  # real Electron; macOS
 npm run verify         # check, build, test, package/install
 ```
@@ -32,7 +33,11 @@ npm run verify         # check, build, test, package/install
 
 ## Real boundaries
 
-The headless suite launches bundled Chromium and ffmpeg. The Electron harness
+Source CI provisions Chrome for Testing through the locked `agent-browser`
+dependency before the headless suite, which launches that real browser and ffmpeg.
+The suite records command phases and the live CDP browser identity; it never logs
+page data, process output, or command arguments. Provisioning and browser action
+deadlines are separate, and the action deadlines remain unchanged. The Electron harness
 launches the actual Electron binary with two `WebContentsView` surfaces and
 checks partition identity, isolation, capture, remount, and WebM recording.
 These tests exist because mocks cannot validate CDP target identity or physical

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amalgm/browser",
-  "version": "0.1.2-preview.34176754339",
+  "version": "0.1.2-preview.34320564379",
   "description": "Safe persistent browser automation across headless Chromium and visible Electron surfaces.",
   "repository": {
     "type": "git",
@@ -100,7 +100,7 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@amalgm/core": "0.4.8-preview.34168975242",
+    "@amalgm/core": "0.5.1-preview.34318364556",
     "@ghostery/adblocker": "^2.18.1",
     "agent-browser": "0.26.0",
     "better-sqlite3": "^12.10.1",
@@ -157,11 +157,11 @@
       "package.json"
     ]
   },
-  "gitHead": "f5b42292f912fcdf55bdf121fd553ffb1657b9db",
+  "gitHead": "26f755c33736141e211756f1e5f84f18afcea651",
   "amalgmSource": {
     "repository": "amalgm-inc/amalgm-browser",
     "branch": "preview",
-    "commit": "f5b42292f912fcdf55bdf121fd553ffb1657b9db",
-    "occurrence": "34176754339"
+    "commit": "26f755c33736141e211756f1e5f84f18afcea651",
+    "occurrence": "34320564379"
   }
 }

package/skills/use-amalgm-browser/SKILL.md

@@ -1,42 +1,188 @@
 ---
 name: use-amalgm-browser
-description: Operate web pages through the standalone Amalgm Browser MCP or CLI using persistent sessions, accessibility snapshots, screenshots, browser-scoped computer use, recordings, and human login handoff. Use for web navigation, form interaction, page inspection, visual verification, canvas or image-only controls, authenticated browsing, or browser recordings.
+description: Drive real web pages with Browser (@amalgm/browser) through its MCP server, CLI, or TypeScript SDK — persistent sessions, accessibility snapshots with stable @refs, screenshots, form filling, browser-scoped computer use, WebM recordings, and human login handoff. Use it whenever an agent needs to navigate a site, read or verify page content, fill and submit forms, operate canvas or image-only UIs, browse while authenticated, or record what happened on a page.
 ---
 
-# Use Amalgm Browser
+# Browser
 
-Use Browser as one persistent page session. Let the host select visible Electron
-or headless Chromium; do not ask users to choose a backend during normal work.
+Browser is one safe, persistent, observable way for agents to operate the web. You open a page once into a named session, read it as a structured accessibility snapshot, act on elements through stable references, and only fall back to pixels when pixels are the interface. MCP and the generic CLI action command expose twenty-two product actions. The SDK exposes core browsing through `browser.execute()` and authentication, login handoff, and recording through `browser.auth`, `browser.login`, and `browser.recordings`; REST exposes the same service through action and resource routes.
 
-## Work in this order
+## Installation
 
-1. Call `browser_open` once with the target URL.
-2. Call `browser_snapshot` to read the page and obtain stable `@eN` references.
-3. Prefer `browser_click`, `browser_fill`, `browser_select`, and `browser_press`
-   with snapshot references.
-4. Re-run `browser_snapshot` after navigation or material page changes.
-5. Use `browser_screenshot` only when pixels matter.
-6. Use `browser_cua` for canvas, WebGL, image-only, or hostile custom controls.
-7. Keep the same `session` value throughout one task. Close it when finished.
+Browser requires Node.js 24 or newer.
 
-Use `text=Visible label` or CSS only when a snapshot reference is unavailable.
-Use `browser_cli` only for an operation absent from the canonical actions.
+```bash
+npm install @amalgm/browser
+npx --no-install agent-browser install
+```
 
-## Safety and identity
+The package installs three executables alongside the SDK:
 
-- Treat screenshot and computer-use coordinates as CSS pixels with a 1:1 map.
-- Never try to switch an Electron session onto another visible surface.
-- Let surface verification fail closed; retry once only when Browser reports a
-  genuine surface reconnection.
-- Never request or print raw cookies, tokens, auth payloads, or storage values.
-- Use `browser_auth_link_create` when a human must complete authentication.
-- Use named auth bundles explicitly; do not treat a profile as an auth bundle.
+- `amalgm-browser` — the CLI; prints stable JSON to stdout.
+- `amalgm-browser-mcp` — the MCP server (also reachable as `amalgm-browser mcp`).
+- `amalgm-browser-rest` — the authenticated loopback REST API (also `amalgm-browser serve --token <token>`).
 
-## Specialized operations
+The `agent-browser` dependency supplies the launcher; its `install` command downloads Chrome for Testing. An existing Chrome installation can also supply the standalone headless browser. Setting `AMALGM_BROWSER_CDP_URL` attaches to a Chromium endpoint you already run instead.
 
-- For action inputs and CUA variants, read
-  [references/actions.md](references/actions.md).
-- For recordings, start only after the page is open and stop before closing the
-  session. Report `videoSeconds` and `wallSeconds` by their actual names.
-- For visual verification, use the returned screenshot image rather than
-  inferring appearance from the accessibility snapshot.
+### MCP setup
+
+To register the MCP server with an MCP-capable client (Claude Code, Cursor, or any client that speaks MCP over stdio), point it at the `amalgm-browser-mcp` binary:
+
+```json
+{
+  "mcpServers": {
+    "browser": {
+      "command": "npx",
+      "args": ["-y", "-p", "@amalgm/browser", "amalgm-browser-mcp"]
+    }
+  }
+}
+```
+
+The server speaks newline-delimited JSON-RPC over stdio and exposes the tools listed in [MCP tools](#mcp-tools). Screenshots come back as MCP image content; everything else is bounded, sanitized JSON.
+
+## Quickstart
+
+Open a page, read it, and click something. With the SDK:
+
+```ts
+import { createBrowser } from '@amalgm/browser';
+
+const browser = createBrowser();
+const session = await browser.createSession({ id: 'research' });
+
+await browser.execute(session.id, { type: 'open', url: 'https://example.com' });
+
+// Returns the accessibility tree with stable @refs like @e3.
+const snapshot = await browser.execute(session.id, { type: 'snapshot' });
+
+await browser.execute(session.id, { type: 'click', target: '@e3' });
+
+await browser.closeSession(session.id);
+```
+
+The same flow on the CLI — note that every invocation reuses one `--session` value:
+
+```bash
+amalgm-browser open https://example.com --session research
+amalgm-browser snapshot --session research
+amalgm-browser click @e3 --session research
+amalgm-browser close --session research
+```
+
+Through MCP the identical sequence is `browser_open`, `browser_snapshot`, `browser_click`, `browser_close`, each taking an optional `session` field (defaulting to `default`).
+
+## Core concepts
+
+### Sessions
+
+A session is a persistent page context: one live browser state that survives across commands. Create it once at the start of a task, pass the same session id to every subsequent action, and close it when the task ends. Sessions are cheap to keep open and expensive to churn — reopening a page resets navigation state, cookies-in-flight, and every element reference you have collected.
+
+Backend selection (headless Chromium, an operator-supplied CDP endpoint, or a visible desktop surface when Browser is embedded in a host app) happens once, before session creation, and never changes during a session's lifetime. You do not choose a backend per command and should not ask users to.
+
+### Tabs
+
+A session can hold multiple tabs. `tab` with `action: "list" | "new" | "switch" | "close"` (plus an `id` for switch/close) manages them. Switching tabs changes which page your snapshot refs describe — treat a tab switch like a navigation and take a fresh snapshot afterward.
+
+### Snapshot references (@refs)
+
+`snapshot` returns the page's accessibility tree, with every interactive element tagged with a stable reference such as `@e12`. These refs are the preferred target grammar for `click`, `fill`, and `select`. Two fallbacks exist when a ref is unavailable:
+
+- `text=Sign in` — match by visible label.
+- `#submit` or any CSS selector — structural match.
+
+Refs belong to the latest snapshot of the current tab. Navigation, tab switches, and material page changes invalidate them; re-run `snapshot` after any of these and use the fresh refs.
+
+## Command sequencing
+
+Browser actions are individual commands over one shared session, and the ordering rules matter more than any single call:
+
+1. Call `open` once per page, not once per command. The session holds the page.
+2. Call `snapshot` to get refs, then act with those refs. Do not re-issue `tab` or `open` before each action — that resets the page context and every `@ref` you hold goes stale.
+3. Re-snapshot only when the page has actually changed: after navigation, after a tab switch, after a click that triggered new content.
+4. When a multi-step sequence fails, classify the failure by the specific command that failed, not by the sequence as a whole. Every action returns a typed error with a stable code (see [Error handling](#error-handling)); a `NOT_FOUND` on step four means a stale ref or changed page at step four, not a broken session. Usually the fix is a fresh `snapshot` and a retry of that one step.
+5. Keep one owner per session. Two processes driving the same session id conflict; the second gets a lease conflict rather than silently interleaving.
+
+## Reading pages: snapshots vs screenshots
+
+`snapshot` and `screenshot` answer different questions.
+
+Use `snapshot` to know what is on the page and what you can do to it: it returns text, structure, roles, and actionable refs, and it is what you should reason over for navigation, form state, and content extraction. Use `screenshot` only when pixels are the question — verifying layout, reading a canvas, checking that an image rendered. `screenshot` accepts `fullPage: true` for beyond-the-viewport capture.
+
+When you need visual verification, look at the returned screenshot image itself. Do not infer visual appearance from the accessibility snapshot — the snapshot deliberately abstracts away pixels.
+
+Screenshot and computer-use coordinates are CSS pixels with a 1:1 mapping between the image and the viewport, so a coordinate you read off a screenshot is the coordinate you pass to `cua`.
+
+`console` reads console output and page errors from the session (`clear: true` empties the buffer), and `eval` runs a JavaScript expression in the page when you need a computed answer the snapshot does not surface.
+
+## Forms and input
+
+The core input actions cover ordinary DOM forms:
+
+```bash
+amalgm-browser fill @e7 "jane@example.com" --session research
+amalgm-browser select @e9 "US" --session research
+amalgm-browser press Enter --session research
+```
+
+- `fill` sets a target's text; pass `submit: true` to submit the surrounding form in the same action.
+- `select` picks a native `<option>` by value.
+- `press` sends a key or key combination to the page.
+- `dialog` accepts or dismisses a native page dialog (`action: "accept" | "dismiss"`, with optional `text` for prompts).
+- `wait` blocks on a selector appearing, a URL match, or a duration (`selector`, `url`, `ms`, `timeoutMs`) — use it between an action and the snapshot that reads its result.
+
+For interfaces without usable DOM semantics — canvas editors, WebGL, image-only controls, hostile custom widgets — use `cua`, browser-scoped computer use. It takes one `operation` per call:
+
+```json
+{ "kind": "click", "x": 320, "y": 240, "button": "left" }
+{ "kind": "type", "text": "hello" }
+{ "kind": "drag", "path": [{ "x": 10, "y": 10 }, { "x": 80, "y": 90 }] }
+```
+
+The full operation set is `screenshot`, `click`, `double_click`, `move`, `scroll`, `type`, `keypress`, and `drag`; see [references/actions.md](references/actions.md) for every shape. Reach for `cua` as the fallback, not the default — snapshot refs are more reliable wherever the DOM is honest.
+
+## Authentication and recording
+
+When a task needs a human to log in, let the host provide the login interface. `browser.login.create()` and the authenticated REST login creation route return a TTL-bound login token and a relative `/browser-auth/...` URL; the host must serve that interface and transport. Treat the creation result as a secret. The token authorizes activation and completion until the login is completed, cancelled, or expires. MCP sanitizes the token and URL, so its `browser_auth_link_create` result cannot supply a usable login credential.
+
+`auth_save` stores a session's authenticated state as a named encrypted bundle, and `auth_load` restores a bundle by `bundleId`. Completing a login handoff saves its bundle automatically. `auth_list` shows sanitized bundle and login metadata; ordinary action results do not return raw cookie or storage values.
+
+`record_start` / `record_stop` / `record_list` manage page-only WebM recordings of a session. Start recording only after the page is open, and stop before closing the session. Results report `wallSeconds` (elapsed clock time) and `videoSeconds` (encoded footage) separately.
+
+## MCP tools
+
+The MCP server exposes twenty-two tools — the canonical action names prefixed with `browser_`. Session actions accept an optional `session` string and default to `default`. `browser_record_list` and `browser_auth_list` list service-wide metadata, while `browser_auth_link_create` creates a separate login session; these three tools do not accept `session`.
+
+| Group | Tools |
+| --- | --- |
+| Navigate & read | `browser_open`, `browser_snapshot`, `browser_screenshot`, `browser_console`, `browser_wait` |
+| Act on elements | `browser_click`, `browser_fill`, `browser_press`, `browser_select`, `browser_eval` |
+| Session & page | `browser_tab`, `browser_dialog`, `browser_close`, `browser_cli` |
+| Computer use | `browser_cua` |
+| Recording | `browser_record_start`, `browser_record_stop`, `browser_record_list` |
+| Authentication | `browser_auth_list`, `browser_auth_link_create`, `browser_auth_save`, `browser_auth_load` |
+
+`browser_cli` is the escape hatch: it runs an advanced `agent-browser` argv action for operations outside the canonical set. Prefer the named tools whenever one exists.
+
+The CLI provides direct commands for the fifteen core browsing and computer-use actions, such as `amalgm-browser open` and `amalgm-browser snapshot`. Use `amalgm-browser action <name> --input <json>` for any of the twenty-two product actions, including authentication and recording, or use the resource commands (`sessions`, `profiles`, `auth`, `recordings`, `capabilities`, `doctor`).
+
+## Error handling
+
+Failures are typed `BrowserError` values with stable codes:
+
+| Code | Meaning |
+| --- | --- |
+| `INVALID_INPUT` | Malformed action input; fix the call, do not retry as-is. |
+| `NOT_FOUND` | Target, session, or resource does not exist — often a stale `@ref`; re-snapshot. |
+| `CONFLICT` | Another owner holds the session or resource. |
+| `CAPABILITY_UNSUPPORTED` | The active backend does not implement this action group; nothing is silently approximated. |
+| `AUTHORIZATION_DENIED` | The caller is not permitted to perform the action. |
+| `TIMEOUT` / `ABORTED` | The operation ran out of time or was cancelled. |
+| `PROCESS_FAILED` | The underlying browser process failed. |
+| `SURFACE_IDENTITY_FAILED` | A visible desktop surface no longer matches the session; this fails closed. Retry once only after a genuine reconnection, never against a different surface. |
+
+Check `session.capabilities` before relying on optional groups (computer use, recording, auth, full-page capture) — a backend that lacks a capability refuses it explicitly rather than faking it.
+
+CLI exit codes map the same taxonomy: `0` success, `2` invalid input, `3` authorization denied, `4` not found, `5` timeout or cancellation, `1` any other typed failure. Pass `--timeout <ms>` to bound any blocking CLI operation.
+
+For the complete target grammar, computer-use operation shapes, and tab, dialog, auth, and recording inputs, see [references/actions.md](references/actions.md).

package/skills/use-amalgm-browser/references/actions.md

@@ -1,14 +1,20 @@
-# Browser actions
+# Action reference
+
+MCP (`browser_<action>`) and the generic CLI command (`amalgm-browser action <name> --input <json>`) expose the product action catalog. The CLI also has direct commands for core browsing and computer use. SDK core actions use `browser.execute(sessionId, action)`; authentication, login, and recording use `browser.auth`, `browser.login`, and `browser.recordings`. REST provides action and resource routes over those services. This reference covers the input shapes that need more detail than the main page gives.
 
 ## Targets
 
-- `@e12`: preferred stable reference from the latest snapshot.
-- `text=Sign in`: visible-text fallback.
-- `#submit` or another CSS selector: structural fallback.
+`click`, `fill`, and `select` take a `target` string in one grammar:
+
+- `@e12` — a stable reference from the latest accessibility snapshot. Preferred.
+- `text=Sign in` — visible-text fallback when no ref is available.
+- `#submit` (or any CSS selector) — structural fallback.
+
+Refs are valid only for the latest snapshot of the current tab. After navigation, a tab switch, or a material page change, run `snapshot` again and use the new refs.
 
 ## Computer use
 
-Call `browser_cua` with one `operation`:
+`cua` performs one browser-scoped operation per call. Coordinates are CSS pixels and map 1:1 to viewport screenshots returned by `screenshot`.
 
 ```json
 { "kind": "screenshot" }
@@ -21,20 +27,31 @@ Call `browser_cua` with one `operation`:
 { "kind": "drag", "path": [{ "x": 10, "y": 10 }, { "x": 80, "y": 90 }] }
 ```
 
-Normal DOM work should use snapshot refs. Computer use is the fallback for
-interfaces without usable DOM semantics.
+Use computer use for canvas, WebGL, image-only, or custom controls without DOM semantics. Ordinary DOM work should use snapshot refs — they survive layout shifts that break coordinates.
 
 ## Tabs and dialogs
 
-Use `browser_tab` with `list`, `new`, `switch`, or `close`. Visible Electron
-sessions are bound to one verified surface and may reject switching.
+`tab` takes `action: "list" | "new" | "switch" | "close"`, with `id` identifying the tab for `switch` and `close`. Switching tabs invalidates snapshot refs; re-snapshot after switching. Sessions bound to a visible desktop surface may reject switching to a surface they do not own.
+
+`dialog` takes `action: "accept" | "dismiss"`, with optional `text` supplied only for prompt dialogs.
+
+## Waiting
+
+`wait` blocks on whichever condition you supply: `selector` (element appears), `url` (location matches), or `ms` (fixed delay), bounded by `timeoutMs`. Prefer `selector` or `url` over fixed delays.
+
+## Authentication
+
+- `auth_link_create` — create a TTL-bound human login handoff. Input: `targetUrl` (required), optional `domains`, `ttlMs` (clamped to one minute–one hour), `transport`, `liveUrl`. SDK `browser.login.create()` and authenticated REST creation return a token and relative URL once; the host must serve the login interface. The token remains valid until completion, cancellation, or expiry. MCP redacts it and cannot return a usable credential.
+- `auth_save` — save the session's authenticated state as a named encrypted bundle. Input: `name` (required), optional `domains`.
+- `auth_load` — load a bundle into the session by `bundleId`.
+- `auth_list` — list sanitized profiles, bundles, and login sessions. Never returns raw cookie or token values.
+
+A profile is a browser state directory; an auth bundle is an explicitly saved, named credential snapshot. They are separate — loading a profile does not load a bundle.
 
-Use `browser_dialog` with `accept` or `dismiss`; add `text` only for prompts.
+## Recording
 
-## Authentication and recording
+- `record_start` — begin a page-only WebM recording. Optional `fps` (clamped 1–30) and `name`. The page must be open first.
+- `record_stop` — stop the session's recording; call before `close`.
+- `record_list` — list recordings and active status.
 
-- `browser_auth_link_create`: mint a human login handoff.
-- `browser_auth_save`: explicitly save named encrypted browser state.
-- `browser_auth_load`: explicitly load a named bundle into a session.
-- `browser_record_start`, `browser_record_stop`, `browser_record_list`: manage
-  page-only WebM recordings.
+Results report `wallSeconds` (elapsed clock time) and `videoSeconds` (encoded footage) under those exact names.

package/docs/ENGINE_INTEGRATION.md

@@ -1,73 +0,0 @@
-# Engine integration
-
-Engine consumes `@amalgm/browser`; Browser never imports Engine. The extraction
-repository is complete independently, but the Engine switchover is deliberately
-a later change.
-
-## Composition boundary
-
-At startup Engine constructs one Browser product and injects:
-
-- `ElectronBrowserDriver` and the native Electron host on desktop;
-- caller/owner/client/project context and authorization;
-- Realtime-backed cwd and artifact resolution;
-- an event sink into the existing relay;
-- the existing Browser storage root and optional legacy database path.
-
-```ts
-import { createBrowser } from '@amalgm/browser';
-import { ElectronBrowserDriver } from '@amalgm/browser/electron';
-
-const browser = createBrowser({
-  root: engineBrowserRoot,
-  legacyDatabaseFile: engineDatabaseFile,
-  electronDriver: new ElectronBrowserDriver(visibleHost),
-  eventSink: browserEventRelay,
-  authorization: engineBrowserAuthorization,
-});
-```
-
-Engine registers `browserToolboxManifest`, delegates old REST/IPC handlers to
-the SDK, and starts standalone MCP or REST adapters where needed. It must not
-translate Browser behavior or keep another implementation.
-
-## Cutover order
-
-1. Add the package and compose it behind existing Engine Browser entry points.
-2. Run old compatibility tests and the package contracts without dual writes.
-3. Stop old Browser writers and back up the Engine DB and Browser directory.
-4. Start the package once with `legacyDatabaseFile`; verify the migration
-   result, entity counts, cookie tombstones, encrypted bundles, and modes.
-5. Point Toolbox, MCP, REST, Electron IPC, and event relay at the one package
-   instance.
-6. Verify visible and headless sessions plus rollback readiness.
-7. Remove Engine's Browser action code, registry policy, cookie authority,
-   auth vault, recorder, process wrapper, copied tests, and stale docs in one
-   cleanup change.
-
-Never run old and new writers against the same Browser state. A compatibility
-route may delegate to the new service, but it must not mirror writes.
-
-## Existing data
-
-The package reuses `$AMALGM_DIR/browser`, the exact Electron partition
-`persist:amalgm-browser`, profile directories, recording locations, and native
-ad-block directory. Its built-in read-only legacy import handles Engine
-profiles, encrypted auth/cookie-source rows, cookie revisions and tombstones,
-login rows, and token hashes. See [MIGRATION.md](./MIGRATION.md).
-
-## Rollback
-
-The importer never mutates the legacy Engine database or deletes legacy blob
-files. If verification fails before cutover, stop the package, restore the
-Browser-directory backup if it was shared, and resume the old writer. After
-new traffic begins, rollback requires a deliberate maintenance window and
-restoring the pre-cutover backup; do not let the old implementation consume
-new-format writes opportunistically.
-
-## Post-cutover boundary
-
-Engine may retain only composition, authorization, Realtime/artifact context,
-event relay, UI presentation, and renderer wiring. Native Browser shell policy
-and visible-surface behavior live in the package's Electron export, even though
-Engine owns the Electron application lifecycle.