@amalgm/browser 0.1.2-preview.35541635545 → 0.1.2-preview.37254096068

package/docs/OPERATIONS.md

@@ -2,68 +2,76 @@
 
 ## State layout
 
-Root selection follows the `@amalgm/core` product state-dir law:
-`AMALGM_BROWSER_DIR` (or its legacy spelling `AMALGM_BROWSER_ROOT`), then
-`$AMALGM_DIR/browser`, then `~/.amalgm/users/<scope>/browser`. The root contains `browser.db`, WAL files, encrypted
-cookie/login state, `browser.key`, auth bundles, profiles, and fallback
-artifacts. Directories are private and secret/DB files are mode `0600` where
-the platform supports POSIX permissions.
+The root is chosen by the `@amalgm/core` product state-dir law:
+`AMALGM_BROWSER_DIR` (or `AMALGM_BROWSER_ROOT`), then `$AMALGM_DIR/browser`,
+then `~/.amalgm/users/<scope>/browser`. It contains:
 
-Do not put the root inside a source repository. Do not back up a live SQLite
-DB by copying only `browser.db`; stop writers or use a SQLite-safe snapshot.
+| Path | Contents |
+| --- | --- |
+| `chrome/` | Chrome's user data directory |
+| `chrome.lease.sqlite` | OS-held exclusive lease for the process running Chrome |
+| `cookie-adapter.json` | private native-adapter capability published by the host |
+| `browser.db` (+ WAL files) | sessions, auth-bundle metadata, login sessions |
+| `cookie-jar.sqlite` (+ WAL files) | the account's encrypted cookie records and tombstones |
+| `cookie-observer/` | SDK-generated private Chrome cookie extension |
+| `browser.key` | the local encryption key |
+| `auth-bundles/` | encrypted auth-bundle payloads |
+| `login-secrets.enc` | hashed login tokens |
+| `screenshots/`, `temporary/` | agent-browser output and short-lived state files |
+| `.amalgm/recordings/` | recordings when no artifact destination is given |
+
+Directories are private and secret files are mode `0600` where the platform
+supports POSIX permissions. Do not put the root inside a source repository.
+Do not copy a live SQLite database without its committed WAL state; stop the
+runtime or use a SQLite-safe snapshot for both `browser.db` and `cookie-jar.sqlite`.
 
 ## Environment
 
 | Variable | Purpose |
 | --- | --- |
-| `AMALGM_BROWSER_DIR` | standalone state root (`AMALGM_BROWSER_ROOT` legacy alias) |
+| `AMALGM_BROWSER_DIR` | state root (`AMALGM_BROWSER_ROOT` also accepted) |
 | `AMALGM_DIR` | Amalgm state root |
-| `AMALGM_BROWSER_BACKEND` | explicit debug force: headless/electron |
-| `AMALGM_BROWSER_CDP_URL` | operator-owned CDP endpoint |
-| `AMALGM_BROWSER_HEADED` | explicit headed standalone Chromium |
-| `AMALGM_BROWSER_EXECUTABLE_PATH` | Chromium executable |
+| `AMALGM_BROWSER_EXECUTABLE_PATH` | Chrome executable (`AGENT_BROWSER_EXECUTABLE_PATH` also accepted) |
 | `AMALGM_AGENT_BROWSER_BIN` | agent-browser executable |
-| `AMALGM_BROWSER_PROVIDER` | external agent-browser provider |
 | `AMALGM_FFMPEG` | ffmpeg executable |
 | `AMALGM_BROWSER_TOKEN` | REST bearer token |
-| `AMALGM_BROWSER_ADAPTER_TOKEN` | restricted cookie-adapter token |
-| `AMALGM_BROWSER_HOST`, `AMALGM_BROWSER_PORT` | REST listen address |
-| `AMALGM_BROWSER_ALLOW_REMOTE=1` | remote bind opt-in |
-| `AMALGM_BROWSER_NOVNC_PUBLIC_URL` | public login handoff URL |
-| `AMALGM_BROWSER_NOVNC_URL` | internal noVNC fallback URL |
-| `AMALGM_BROWSER_LOGIN_TRANSPORT` | default human-login transport |
-| `AMALGM_BROWSER_ADBLOCK=0` | native ad-block kill switch |
-| `AMALGM_BROWSER_WCV=0` | temporary protocol-5 surface compatibility |
-| `AMALGM_RUNTIME_STATE_DIR` | Electron bridge advertisement directory |
-| `AMALGM_RUNTIME_LABEL`, `AMALGM_BRANCH` | labeled bridge discovery |
+| `AMALGM_BROWSER_ADAPTER_TOKEN` | internal cookie-route token |
+| `AMALGM_BROWSER_HOST`, `AMALGM_BROWSER_PORT` | `amalgm-browser-rest` listen address |
+| `AMALGM_BROWSER_ALLOW_REMOTE=1` | `amalgm-browser-rest` remote bind opt-in |
+| `AMALGM_BROWSER_ADBLOCK=0` | Electron ad-block kill switch |
 | `AMALGM_BROWSER_AUTH_KEY` | legacy-import key override only |
-| `AMALGM_BROWSER_DEBUG=1` | sanitized debug logging |
+| `AMALGM_BROWSER_DEBUG` | sanitized debug logging |
 
 ## Process model
 
-Multiple processes may share SQLite metadata: entity writes do not replace a
-whole registry and cross-process leases prevent concurrent action/close races
-on one session. A live browser process and encoder still have one owner. Run
-one long-lived service for sustained MCP/REST work; use explicit session IDs
-for CLI reuse.
+One process runs a root's Chrome. It holds an exclusive SQLite lease, and
+another process gets `CONFLICT` when it needs Chrome on the same root.
+The OS releases the lease on process death; never remove its file. Recovery
+retires an orphan only through the exact endpoint in `chrome/DevToolsActivePort`.
+Run one long-lived runtime (`mcp`, `serve`, or an embedding host) for
+sustained work. If Chrome dies, the next action starts a new one.
+
+Processes may still share the SQLite metadata: entity writes never replace the
+whole registry, and cross-process leases stop two processes from acting on,
+closing, or creating the same session at once.
 
 ## Health and observability
 
-Use `/v1/health` for process health, `/v1/capabilities` for installed drivers,
-`doctor` for basic CLI diagnostics, resource listing for durable state, and SSE
-for sanitized transitions. Never log request bodies for auth or internal
-cookie routes.
+Use `GET /v1/health` for process health, `doctor` for basic CLI diagnostics,
+resource listings for durable state, and SSE for sanitized transitions. Set
+`AMALGM_BROWSER_DEBUG` for sanitized debug logs. Never log request bodies for
+auth or internal cookie routes.
 
 ## Retention
 
-Prune abandoned sessions and stale ephemeral profiles on an operator-defined
-schedule. Durable, referenced, live, or Chromium-locked profiles are retained.
-Artifacts are sensitive; the injected store or host owns retention and access
-control. Browser does not delete successful recordings automatically.
+`sessions prune` (default 24 hours) deletes closed and failed sessions that
+have not changed within the age limit. Artifacts are sensitive; the injected
+artifact store or host owns their retention and access control. Browser does
+not delete finished recordings.
 
 ## Remote REST
 
 Loopback is the safe default. Remote binding requires explicit opt-in and a
-strong bearer token; use TLS and network access control in front of the local
-server. Keep the adapter-token endpoints private even when ordinary REST is
+strong bearer token; put TLS and network access control in front of the
+server. Keep the internal cookie routes private even when ordinary REST is
 remote.

package/docs/README.md

@@ -6,7 +6,7 @@ your integration:
 - [Architecture](./ARCHITECTURE.md) and [axiom map](./AXIOMS.md)
 - [SDK](./SDK.md), [actions](./ACTIONS.md), [CLI](./CLI.md),
   [MCP](./MCP.md), and [REST](./REST.md)
-- [Headless runtime](./HEADLESS_RUNTIME.md) and
+- [Chrome runtime](./CHROME.md) and
   [Electron integration](./ELECTRON_INTEGRATION.md)
 - [Cookies](./COOKIES.md), [authentication](./AUTHENTICATION.md), and
   [recording](./RECORDING.md)
@@ -17,7 +17,7 @@ your integration:
 - [Operations](./OPERATIONS.md), [testing](./TESTING.md), and
   [troubleshooting](./TROUBLESHOOTING.md)
 
-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.
+The core package is ESM-only and requires Node.js 24+. The
+`@amalgm/browser/electron` entry point also provides a generated CommonJS
+condition for Electron main processes; no internal implementation module is
+public.

package/docs/REALTIME_BOUNDARY.md

@@ -1,9 +1,9 @@
 # Realtime boundary
 
 Realtime owns files, workspace identity, project context, current working
-directory, and general application-state synchronization. Browser owns browser
-sessions, profiles, drivers, cookies, auth resources, recordings, and Browser
-events.
+directory, and general application-state synchronization. Browser owns the
+runtime's Chrome, browser sessions, the account's cookie jar, auth resources,
+recordings, and Browser events.
 
 Browser receives opaque project/cwd/artifact values through
 `BrowserRuntimeContext` or an injected `BrowserArtifactStore`. It never imports

package/docs/RECORDING.md

@@ -18,27 +18,27 @@ const stopped = await browser.recordings.stop(session.id);
 - one active recording per session
 - FPS clamped to 1–30
 - ffmpeg verified before browser capture starts
-- exact verified page target, never application chrome or a first target
-- first capturable frame required before the encoder starts
+- the session's own page, found as for screenshots; an ambiguous page fails
+  with `SURFACE_IDENTITY_FAILED`
+- a first page frame required within five seconds, before the encoder starts
 - one latest-frame slot separates paint frequency from encoding cadence
 - static pages receive honest wall-clock duration
 - animation floods do not create an unbounded queue
 - source stop, encoder flush, and forced termination are bounded
 - zero-frame or failed artifacts are removed
 
-The result reports `wallSeconds`, `videoSeconds`, encoded `frames`, received
-frames, skipped ticks, and sanitized artifact metadata. These fields are
-deliberately distinct; there is no ambiguous generic duration.
+A stopped recording reports `wallSeconds`, `videoSeconds`, `frames`
+(encoded), `framesReceived`, `skippedTicks`, an optional `warning`, and the
+artifact's metadata (`id`, `kind`, `path`, `mimeType`, `bytes`, `createdAt`).
+These fields are deliberately distinct; there is no ambiguous generic
+duration. The video is VP9 WebM.
 
 ## Artifacts
 
-The local artifact adapter resolves in this order:
-
-1. `context.artifactDestination`
-2. the embedding host's injected artifact store/context
-3. the standalone Browser root
-
-Project destinations use `<project>/.amalgm/recordings/<name>-<id>.webm`.
+An embedding host may inject its own `artifactStore`. The default local store
+writes to `context.artifactDestination` when given, otherwise to the Browser
+root, at `<destination>/.amalgm/recordings/<name>-<timestamp>.webm`. The name
+defaults to the session ID.
 Browser does not maintain a current-project registry. Artifacts are sensitive
 user data and the embedding store owns access control and retention.
 
@@ -50,6 +50,7 @@ row failed, while a live foreign owner remains visible and returns a conflict
 to stop/force-stop. `forceStop(sessionId)` aborts a locally owned encoder and
 marks it failed; a service never claims it controlled another process.
 
-Both real headless and real Electron suites encode a page-only WebM. Unit
-contracts cover static pages, frame floods, backpressure, capture viability,
-missing ffmpeg, cancellation, and bounded stop.
+`browser.close()` stops this process's recordings and keeps what was captured.
+
+Unit contracts cover static pages, frame floods, backpressure, capture
+viability, missing ffmpeg, cancellation, and dead-owner recovery.

package/docs/REST.md

@@ -7,34 +7,52 @@ amalgm-browser serve --token replace-me
 AMALGM_BROWSER_TOKEN=replace-me amalgm-browser-rest
 ```
 
-The server binds loopback by default. Remote binding requires explicit
-`allowRemote` in the SDK, `--allow-remote` in the CLI, or
-`AMALGM_BROWSER_ALLOW_REMOTE=1` for the standalone binary. All routes except
-`GET /v1/health` require `Authorization: Bearer <token>`.
+The server binds loopback by default. Remote binding requires `allowRemote`
+in the SDK, `--allow-remote` in the CLI, or `AMALGM_BROWSER_ALLOW_REMOTE=1`
+for `amalgm-browser-rest`, which also reads `AMALGM_BROWSER_HOST` and
+`AMALGM_BROWSER_PORT`. Every route except `GET /v1/health` requires the
+token, sent as `Authorization: Bearer <token>`, as `X-Amalgm-Runtime-Token`,
+or, for WebSocket clients that cannot set headers, as the subprotocol
+`amalgm-runtime-token.<token>`. A missing or wrong token gets `401`.
 
-## Discovery and streaming
+## Discovery and events
 
 - `GET /v1/health`
 - `GET /v1/openapi.json`
-- `GET /v1/capabilities`
 - `GET /v1/events` (SSE; supports `Last-Event-ID`)
 
 ## Sessions and actions
 
-- `GET|POST /v1/sessions`
-- `POST /v1/sessions/prune`
+- `GET|POST /v1/sessions` (`POST` takes an optional `id`)
+- `POST /v1/sessions/prune` (optional `maxAgeMs`)
 - `GET|DELETE /v1/sessions/:sessionId`
 - `POST /v1/sessions/:sessionId/cancel`
 - `POST /v1/sessions/:sessionId/actions/:action`
+- `GET /v1/sessions/:sessionId/stream` (WebSocket)
 
-Every one of the 22 canonical actions has an action route generated from the
-shared descriptor. Resource-specific routes below expose richer lifecycle
-operations.
+Each of the 22 actions has an action route generated from the shared
+descriptor; the path's session ID is the action's session.
 
-## Profiles, auth, and recording
+The stream route upgrades to a WebSocket that relays the session's live view,
+in agent-browser's stream format:
+
+- out: `status`, `tabs` (only this session's tabs), and `frame` (a base64
+  JPEG plus metadata);
+- in: `input_mouse`, `input_keyboard`, and `input_touch`.
+
+Messages pass through unchanged. Send keyboard input as a full key event, not
+just `key` and `code`:
+
+```json
+{"type":"input_keyboard","eventType":"keyDown","key":"Enter","code":"Enter","text":"\r","windowsVirtualKeyCode":13,"modifiers":0}
+```
+
+A browser cannot read a refused handshake, so a missing or wrong token
+completes the handshake and then closes with code `4401`. A missing session or
+a failed upstream closes with `1011` and the reason `<CODE>: <message>`.
+
+## Auth and recording
 
-- `GET|POST /v1/profiles`; `POST /v1/profiles/prune`
-- `GET|PATCH|DELETE /v1/profiles/:profileId`
 - `GET|POST /v1/auth/bundles`
 - `POST /v1/auth/bundles/import`
 - `GET|DELETE /v1/auth/bundles/:bundleId`
@@ -46,24 +64,37 @@ operations.
 - `GET /v1/recordings/:recordingId`
 - `POST /v1/recordings/:recordingId/stop|cancel`
 
-The generated OpenAPI document is the route inventory and excludes internal
-raw-cookie schemas.
-
-## Internal cookie transport
+## Internal cookie routes
 
-`/internal/v1/*` is reserved for trusted physical cookie adapters. It requires
-both the bearer token and `X-Browser-Adapter-Token`, is handled only after
-authorization, sends `Cache-Control: no-store`, and is omitted from public
-OpenAPI. Never expose this transport through an untrusted reverse proxy.
+`/internal/v1/cookies/metadata|bootstrap` (`GET`),
+`/internal/v1/cookies/delta?after=<version>` (`GET`),
+`/internal/v1/cookies/changes` (value-free SSE), and
+`/internal/v1/cookies/install|merge` (`POST`) serve trusted cookie adapters
+in other processes. They require the runtime token and a matching
+`X-Browser-Adapter-Token`, and answer `401` unless the server was given an
+adapter token (`AMALGM_BROWSER_ADAPTER_TOKEN` for the CLI). They are not in
+the OpenAPI document. Never expose them through an untrusted reverse proxy.
 
 ## Limits and errors
 
-Defaults are a 512 KB request body, 2 MB JSON output, and 120-second request
-deadline. Client disconnect aborts unfinished work. Errors use:
+Defaults are a 512 KB request body (larger bodies are `INVALID_INPUT`), 2 MB
+JSON output, and a 120-second request deadline. Client disconnect aborts
+unfinished work. Every JSON response sends `Cache-Control: no-store`. Typed
+errors use:
 
 ```json
 {"error":{"code":"INVALID_INPUT","message":"sanitized explanation"}}
 ```
 
-SSE emits only versioned sanitized Browser events, sends heartbeats, resumes
-from retained history, and removes listeners on disconnect.
+Status codes: `400` invalid input, `403` authorization denied, `404` not
+found, `409` conflict, `413` output too large (`OUTPUT_TOO_LARGE`), `504`
+timeout, `500` anything else. The token check's `401` has its own body:
+`{"error":"Missing or invalid Amalgm runtime token"}`.
+
+Closing the HTTP adapter cancels and drains its admitted requests and closes
+its SSE and live-view connections. The embedding host separately owns closing
+the Browser service.
+
+SSE sends only versioned sanitized events, replays retained history after
+`Last-Event-ID`, sends a heartbeat every 15 seconds, and removes its listener
+on disconnect.

package/docs/SDK.md

@@ -4,63 +4,75 @@ The package is ESM-only and supports Node.js 24 or newer.
 
 ```ts
 import { createBrowser, BrowserError } from '@amalgm/browser';
+
+const browser = createBrowser({ root, account: { id: user.id, name: user.name } });
 ```
 
-`createBrowser(options)` returns `BrowserProductService`. Defaults include a
-SQLite registry, local artifact store, encrypted cookie/auth files, headless
-driver, event bus, system clock, safe logger, and runtime selector. Injected
-ports can replace registry, drivers, selector, event sink, clock, ID generator,
-logger, authorization, profile directories, artifact store, process launcher,
-cookie jar/coordinator, auth vault, login secret store, and ffmpeg. Native
-ad-block construction separately accepts an injected fetch implementation.
+`createBrowser(options)` returns the browser service (`BrowserService`). Every
+option is optional:
+
+- `root`: state root (see [operations](./OPERATIONS.md))
+- `account`: who every session browses as; default `{ id: 'local', name: 'Local' }`
+- `legacyDatabaseFile`: legacy import source, or `false` (see
+  [migration](./MIGRATION.md))
+- injected ports: `registry`, `driver`, `eventSink`, `clock`, `logger`,
+  `authorization`, `id`, `artifactStore`, `processLauncher`, `cookieJar`,
+  `authVault`, `loginSecrets`, and `ffmpegBinary`
+
+By default Browser uses a SQLite registry, the runtime's Chrome driver, an
+event bus, a local artifact store, encrypted cookie rows and auth files under
+the root. Chrome starts on the first action. [`examples/basic.ts`](../examples/basic.ts)
+opens a page, snapshots it, and closes.
+
+## Account
+
+`browser.account` is the account record. There is one browsing identity per
+root: sessions, auth bundles, and logins all belong to it, and a different
+`account` on an existing root takes them over.
 
 ## Sessions and actions
 
-- `createSession({ id?, profileId?, profileKind?, context? })`
+- `createSession({ id?, context? })`: creates the session, or reopens an
+  existing ready one; after a restart, call it before `execute` (the adapters
+  do this on every call). `context.ownerId` is stored as the session's owner.
 - `getSession(id)` / `listSessions()`
-- `execute(sessionId, BrowserAction, context?)`
+- `execute(sessionId, BrowserAction, context?)`: one action at a time per
+  session
+- `streamUrl(sessionId, context?)`: loopback WebSocket URL for the session's
+  live view
 - `cancel(sessionId)`
-- `closeSession(sessionId, context?)`
-- `pruneSessions(maxAgeMs?)`
+- `closeSession(sessionId, context?)`: closes the session's tabs
+- `pruneSessions(maxAgeMs?)`: deletes old closed and failed sessions
+- `close()`: stops recordings, detaches every session, syncs cookies, stops
+  Chrome, and closes the registry
 
 `BrowserAction` is a discriminated union for `open`, `snapshot`, `screenshot`,
 `click`, `fill`, `press`, `select`, `eval`, `wait`, `cli`, `dialog`, `tab`,
 `console`, `cua`, and `close`. See [ACTIONS.md](./ACTIONS.md). Blocking calls
-take `context.signal`; cancellation propagates to the driver, CDP, encoder, or
-child process.
-
-## Profiles
-
-- `createProfile({ id?, name, kind? })`
-- `listProfiles()` / `getProfile(id)` / `inspectProfile(id)`
-- `updateProfile(id, { name?, kind? })`
-- `deleteProfile(id)` / `pruneProfiles(maxAgeMs?)`
-
-Inspection returns `live`, `referenced`, and physical `locked` status. Delete
-and prune refuse live, referenced, or Chromium-locked profiles.
+take `context.signal`; cancellation reaches the driver, CDP, encoder, or child
+process.
 
 ## Authentication and login
 
 - `browser.auth.list()` / `get(id)` / `delete(id)`
-- `browser.auth.save({ sessionId, name, domains?, context? })`
+- `browser.auth.save({ sessionId, name, id?, domains?, context? })`
 - `browser.auth.load({ sessionId, bundleId, context? })`
 - `browser.auth.exportEncrypted(id, portableKey, context?)`
 - `browser.auth.importEncrypted(resource, portableKey, context?)`
-- `browser.login.create(...)` / `list()` / `get(id)`
+- `browser.login.create({ targetUrl, domains?, ttlMs?, transport?, liveUrl?, context? })`
+- `browser.login.list()` / `get(id)`
 - `browser.login.activate(id, token, context?)`
 - `browser.login.input(id, token, cuaOperation, context?)`
-- `browser.login.complete(...)` / `cancel(id, token)`
+- `browser.login.complete({ id, token, bundleName?, context? })` /
+  `cancel(id, token)`
 
-The token and token-bearing URL exist only in the one-time login creation
-result. Stored login resources contain a hash and ordinary list/get projections
-never return the credential.
+The token and handoff URL appear only in the login creation result. See
+[authentication](./AUTHENTICATION.md).
 
 ## Cookies
 
-`browser.cookies` is the encrypted jar. `browser.cookieAdapters` registers and
-reconciles trusted physical-store adapters. This is an embedding API, not an
-ordinary automation API; raw cookie values must not be projected to users.
-See [COOKIES.md](./COOKIES.md).
+`browser.cookies` is the account's encrypted cookie jar. It is an embedding
+API; never show raw cookie values to users. See [COOKIES.md](./COOKIES.md).
 
 ## Recordings
 
@@ -68,34 +80,32 @@ See [COOKIES.md](./COOKIES.md).
 - `stop(sessionId)` / `forceStop(sessionId)`
 - `list()` / `get(recordingId)` / `activeRecordings()`
 
-FPS is clamped to 1–30. Artifact placement uses `context.artifactDestination`
-before the standalone fallback.
+See [RECORDING.md](./RECORDING.md).
 
 ## Runtime context
 
 `BrowserRuntimeContext` accepts opaque `ownerId`, `callerId`, `clientKind`,
-`projectRef`, `cwdRef`, `artifactDestination`, authorization context, and
-`AbortSignal`. Browser does not discover these from Chat or a workspace
-registry.
+`projectRef`, `cwdRef`, `artifactDestination`, `authorization`, and `signal`.
+Browser does not discover these from Chat or a workspace registry. An
+injected `authorization` port is asked before `sessions.create`,
+`sessions.close`, `sessions.stream`, `actions.<type>`, `auth.export`, and
+`auth.import`.
 
-## Errors and capabilities
+## Errors
 
-Failures are `BrowserError` values with stable codes such as `INVALID_INPUT`,
-`NOT_FOUND`, `CONFLICT`, `CAPABILITY_UNSUPPORTED`, `AUTHORIZATION_DENIED`,
-`TIMEOUT`, `ABORTED`, `PROCESS_FAILED`, and `SURFACE_IDENTITY_MISMATCH`.
-Inspect `session.capabilities` before optional behavior. Unsupported behavior
-fails explicitly; it is not silently approximated.
+Failures are `BrowserError` values with one of these codes: `ABORTED`,
+`AUTHORIZATION_DENIED`, `CONFLICT`, `INVALID_INPUT`, `NOT_FOUND`,
+`PROCESS_FAILED`, `SURFACE_IDENTITY_FAILED`, `TIMEOUT`.
 
 ## Entry points
 
-- `@amalgm/browser` — service, ports, types, persistence, migration
-- `@amalgm/browser/headless` — headless driver and executable resolution
-- `@amalgm/browser/electron` — Electron-only host and native shell
-- `@amalgm/browser/cookies` — trusted cookie integration
-- `@amalgm/browser/recording` — recording components
-- `@amalgm/browser/toolbox`, `/mcp`, `/http` — adapters
-- `@amalgm/browser/testing` — deterministic test driver
-
-The [custom driver example](../examples/custom-driver.ts) implements the small
-`BrowserDriver` contract for a remote provider. A provider must advertise only
-capabilities it implements and must honor the runtime cancellation signal.
+- `@amalgm/browser`: service, ports, types, persistence, migration
+- `@amalgm/browser/electron`: the desktop app's in-app browser
+- `@amalgm/browser/cookies`: cookie jar, coordinator, and policy
+- `@amalgm/browser/recording`: recording components
+- `@amalgm/browser/toolbox`, `/mcp`, `/http`: adapters
+- `@amalgm/browser/testing`: `TestBrowserDriver` and `MemoryBrowserRegistry`
+
+A custom `driver` implements the `BrowserDriver` port (`open`, `execute`,
+`close`, `saveState`, `loadState`, `startScreencast`, `streamUrl`, `dispose`)
+and must honor the runtime cancellation signal.

package/docs/SHELL_INTEGRATION.md

@@ -1,54 +1,96 @@
 # 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.
+Amalgm Shell consumes `@amalgm/browser`; Browser never imports Shell. One Shell
+runtime creates exactly one Browser service, mounts its adapters, and closes
+it on shutdown. It never creates another registry, cookie jar, or session
+authority.
 
-## Composition boundary
+This composition is active only in a signed machine service plan that
+declares Browser. Installing the SDK alone must not create Browser databases
+or state.
 
-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.
+## Create the service
 
-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.
+Shell creates the service lazily, as the signed-in Amalgm account:
 
 ```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,
+  root: runtimeBrowserRoot,
+  account: { id: userId, name: userEmail },
+  eventSink: browserEventRelay,             // optional
+  authorization: shellBrowserAuthorization, // optional
 });
 ```
 
-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.
+`account` is who every session browses as. Without it the runtime browses as
+`{ id: 'local', name: 'Local' }`. On an existing root, a different account
+takes over every session, auth bundle, and login, along with the root's
+cookie jar, so give each account its own root. Chrome is not started until
+the first action.
+
+## Map chats to sessions
+
+Mount the MCP adapter at `/mcp/browser` and pass the calling chat, from the
+chat relay's `x-amalgm-session-id` header, as both `callerId` and `ownerId`:
+
+```ts
+import { createBrowserMcpServer } from '@amalgm/browser/mcp';
+
+const mcp = createBrowserMcpServer(browser);
+
+async function onMcpMessage(message, headers) {
+  const chat = headers['x-amalgm-session-id'];
+  return mcp.handle(message, typeof chat === 'string' ? { callerId: chat, ownerId: chat } : {});
+}
+```
+
+A tool call without a `session` argument then runs in the session named after
+the chat, and any session the call creates is owned by that chat. Each chat
+gets its own tabs while all chats share the account's sign-ins. `handle`
+returns the JSON-RPC result or throws; Shell writes the JSON-RPC response.
+`notifications/cancelled` aborts the matching call.
+
+## REST and live view
+
+Shell serves `/browser/*` HTTP requests and WebSocket upgrades by handing them
+in-process to the REST adapter's `server` (from `createBrowserHttpServer`),
+which never listens on a port. It reroots the path onto `/v1/*`. After Shell's
+gateway admits a request, Shell stamps the REST adapter's own random token as
+the `x-amalgm-runtime-token` header. The internal cookie routes are not exposed
+through Shell.
+
+A viewer opens `/browser/sessions/<id>/stream` to watch and drive one
+session's live view (see [REST](./REST.md)). In process,
+`browser.streamUrl(sessionId)` returns the same stream's loopback WebSocket
+URL.
+
+## Shutdown
+
+```ts
+await browser.close();
+```
 
-## Electron boundary
+`close` stops active recordings, detaches every session, syncs cookies one
+last time, stops Chrome, and closes the registry; Shell does not close the
+database itself. Sessions stay in the registry and reopen when next used after
+the runtime restarts. While the runtime runs, it owns the root's Chrome; a
+second process on the same root gets `CONFLICT` when it tries to start Chrome.
 
-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`.
+## Electron
 
-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.
+Electron owns the application lifecycle and hosts the user's in-app browser
+tabs through `@amalgm/browser/electron` (see
+[Electron integration](./ELECTRON_INTEGRATION.md)). Application auth stays in
+Electron's `defaultSession`; websites stay in the account-specific
+`persist:amalgm-browser-<account hash>` partition. Its cookies sync with the
+runtime through Browser's private adapter port. Managed UI and Shell bind to
+the same exact published Browser release.
 
-## Historical cutover rule
+## Legacy import
 
-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.
+Legacy Engine data may be imported once through `legacyDatabaseFile` (see
+[migration](./MIGRATION.md)). The importer never writes to the legacy
+database. Legacy and current writers must never run against the same Browser
+state.