@amalgm/browser 0.1.0

package/docs/ELECTRON_INTEGRATION.md

@@ -0,0 +1,87 @@
+# Electron integration
+
+Electron is an optional peer dependency and appears only behind
+`@amalgm/browser/electron`. Headless consumers do not load it.
+
+## Composition
+
+The package contains both sides of the visible boundary:
+
+- `createBrowserShell` owns native page sites, policy, downloads, permissions,
+  context menus, popup conversion, ad blocking, and safe teardown.
+- `createBrowserSurfaceController` owns automation surfaces, bounds,
+  presentation, capture, focus, find, zoom, and surface state.
+- `ElectronBrowserDriver` presents those verified surfaces to the Browser SDK.
+- host advertisement helpers publish a private, atomic loopback CDP bridge.
+
+The application renderer supplies presentation and IPC wiring; it is not a
+browser-state authority.
+
+## Partition isolation
+
+Always obtain the physical Browser session with `getBrowserSession` or
+`isolatedBrowserSession`. Both require the exact partition:
+
+```text
+persist:amalgm-browser
+```
+
+Do not pass Electron `defaultSession` to the shell or cookie adapter. The
+Browser partition owns its cookies, cache, storage, service workers,
+permissions, zoom, and request policy without touching application auth.
+
+## Surface identity
+
+Protocol 6 uses native page targets; protocol 5 remains a rolling-compatibility
+reader for the prior webview bridge. A requested automation surface receives a
+neutral marker URL, surface ID, and session stamp. The driver binds this
+identity and verifies it before every action.
+
+It never selects a target by order, target count, active tab, or URL. Identical
+URLs in two sessions remain distinct. A destroyed target may be reattached
+once only to the same verified identity. Mismatch or ambiguity fails before
+input, capture, or recording.
+
+## Native shell policy
+
+The shell provides:
+
+- safe `http`, `https`, and controlled external-protocol navigation
+- popup-to-tab and child-window disposition
+- page state, favicon, navigation, and load-failure events
+- back, forward, reload, focus, location, find, and zoom commands
+- spellcheck-aware context menus
+- unique basename-only download destinations and lifecycle actions
+- requesting-frame permission origins with fail-closed defaults
+- browser-only shortcuts and renderer ownership checks
+- off-screen parking and fixed automation viewport behavior
+
+The host maps these typed contracts to its visible chrome; the renderer should
+not reproduce their policy.
+
+## Cookies and ad blocking
+
+Construct `ElectronCookieAdapter` with the isolated partition's `Cookies`
+object. Its stable adapter ID is `electron:default-session` for historical jar
+compatibility; the object itself is never Electron `defaultSession`.
+
+`NativeAdBlocker` uses Ghostery-compatible filtering, a compiled cache,
+seven-day refresh, a last-good-cache fallback, cosmetic rules, scriptlets,
+mutation observation, and per-site settings. `AMALGM_BROWSER_ADBLOCK=0`
+disables it explicitly. Filtering is attached only to Browser contents, not the
+application renderer, API, or auth traffic.
+
+## Host advertisement
+
+`writeHostAdvertisement` validates a loopback CDP URL, writes atomically with
+private permissions, and records PID/protocol/target types. The selector
+rejects stale, dead, remote, or incompatible advertisements. Call
+`removeHostAdvertisement` during owner teardown; it only removes an
+advertisement owned by the expected PID.
+
+## Verification
+
+`npm run test:electron` runs a real macOS Electron harness. It checks the exact
+partition, two simultaneous same-URL surfaces, action isolation, failure before
+identity mismatch, one remount, CSS-pixel capture, fixed off-screen viewport,
+and page-only WebM recording.

package/docs/ENGINE_INTEGRATION.md

@@ -0,0 +1,73 @@
+# 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.

package/docs/EVENTS.md

@@ -0,0 +1,30 @@
+# Events
+
+Browser emits version-1 state transitions through an injected
+`BrowserEventSink`. `BrowserEventBus` provides a bounded standalone history and
+subscription implementation; REST exposes it as SSE.
+
+Event families are:
+
+- `session.created`, `session.ready`, `session.closed`, `session.failed`
+- `surface.requested`, `surface.bound`, `surface.updated`, `surface.lost`
+- `page.navigated`, `page.failed`
+- `profile.updated`
+- `recording.started`, `recording.stopped`
+- `login.updated`
+- `cookie-jar.changed`
+- `download.updated`
+- `permission.requested`
+
+Every event has a stable random ID, ISO timestamp, version, and only the
+resource identifiers/metadata required by that transition. Navigation uses a
+sanitized origin rather than a sensitive full URL. Error text is redacted and
+bounded. Cookie values, auth payloads, login tokens, storage contents, keys,
+authorization headers, and captured pixels are forbidden.
+
+`GET /v1/events` sends retained events after `Last-Event-ID`, then live events
+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
+the Browser authority and must not enrich an event with Browser secrets.

package/docs/HEADLESS_RUNTIME.md

@@ -0,0 +1,58 @@
+# Headless runtime
+
+Headless is the default for standalone SDK/CLI use, servers, automations,
+agents, and background jobs. It uses `agent-browser` behind `BrowserDriver`;
+the core service does not know its command-line arguments.
+
+## Process and executable selection
+
+Resolution prefers:
+
+1. `AMALGM_AGENT_BROWSER_BIN`
+2. the platform-native binary shipped by `agent-browser`
+3. the package's JavaScript wrapper
+4. an `agent-browser` executable on PATH
+
+When packaged in Electron, native binaries and ffmpeg are resolved from
+`app.asar.unpacked`. Every process uses an argv array with `shell: false`, a
+safe explicit cwd, bounded stdout/stderr, an operation timeout, cancellation,
+SIGTERM, and bounded SIGKILL escalation.
+
+## Configuration
+
+- `AMALGM_BROWSER_EXECUTABLE_PATH` — explicit Chromium executable
+- `AMALGM_BROWSER_PROVIDER` — external provider understood by agent-browser
+- `AMALGM_BROWSER_CDP_URL` — attach to an operator-owned CDP endpoint
+- `AMALGM_AGENT_BROWSER_BIN` — explicit agent-browser executable
+- `AMALGM_BROWSER_HEADED=1` — explicit standalone headed debug mode
+- `AMALGM_FFMPEG` — encoder override
+
+An explicit CDP endpoint remains a headless-driver session in the domain model;
+it does not opt into Electron surfaces. Ordinary background work never opens a
+headed window or steals focus.
+
+## Profiles and state
+
+Each session uses its assigned Browser profile directory. Durable profiles
+survive explicit reuse; ephemeral profiles are pruned only when not live,
+referenced, or physically Chromium-locked. Backend-local cookies remain in
+that profile. The trusted headless cookie adapter reconciles individual records
+through the encrypted logical jar without inspecting Electron.
+
+## Capture and input
+
+Accessibility snapshots create stable `@eN` references for ordinary DOM
+actions. Direct CDP resolves the session's actual target for screenshot,
+computer use, and recording—never the first or only page. Viewport screenshots
+are normalized to CSS pixels even when device pixel ratio exceeds one;
+full-page capture is height-bounded.
+
+Computer use supports screenshot, click, double click, move, scroll, type,
+keypress, and drag. Native CDP input is page-scoped. Use it for canvas, WebGL,
+image-only, or hostile custom controls; prefer snapshot references elsewhere.
+
+## Real verification
+
+`npm run test:real` launches the bundled Chromium runtime and verifies
+navigation, snapshot, exact-target CDP capture, DPR normalization, page-scoped
+typing, and real page-only recording.

package/docs/MCP.md

@@ -0,0 +1,36 @@
+# MCP server
+
+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.
+
+The 22 tools are the canonical action names prefixed with `browser_`:
+
+```text
+browser_open              browser_snapshot       browser_screenshot
+browser_click             browser_fill           browser_press
+browser_select            browser_eval           browser_wait
+browser_cli               browser_dialog         browser_tab
+browser_console           browser_close          browser_cua
+browser_record_start      browser_record_stop    browser_record_list
+browser_auth_list         browser_auth_link_create
+browser_auth_save         browser_auth_load
+```
+
+Schemas derive from the same action descriptor array used by CLI, REST, and
+Toolbox. The optional `session` field selects the persistent session; otherwise
+the adapter uses `default`.
+
+`notifications/cancelled` aborts the active SDK operation identified by the
+JSON-RPC request ID. Text results are bounded. Captures are emitted as MCP image
+content when the result is an image. Recording and resource results contain
+sanitized metadata.
+
+Raw cookie values, auth payloads, encryption keys, bearer headers, and stored
+login token hashes are not MCP tools or resource output. Login-link creation is
+the deliberate one-time credential-delivery operation; callers must treat its
+returned token-bearing URL as a secret.
+
+Toolbox uses a different compatibility namespace,
+`toolbox__browser_<action>`, documented in
+[TOOLBOX_INTEGRATION.md](./TOOLBOX_INTEGRATION.md).

package/docs/MIGRATION.md

@@ -0,0 +1,64 @@
+# Migration
+
+Browser preserves existing user state through path reuse plus a versioned
+legacy import. Migration is read-only with respect to the legacy Engine DB and
+is recorded as `engine-browser-v1` metadata in the new registry.
+
+## Automatic path
+
+When `createBrowser()` uses its normal `$AMALGM_DIR/browser` root, it checks
+for `$AMALGM_DIR/amalgm.db`. An explicit root does not guess a database;
+provide `legacyDatabaseFile` to opt in, or `false` to disable import.
+
+```ts
+const browser = createBrowser({
+  root: '/state/browser',
+  legacyDatabaseFile: '/state/amalgm.db',
+});
+```
+
+The importer opens the old DB read-only and imports inside one new-registry
+transaction:
+
+- `browser_profiles` into durable/ephemeral profile metadata;
+- ordinary `browser_auth_bundles` after hash and AES-GCM verification;
+- the `browser-cookie-source` bundle into record-level cookies and tombstones;
+- `browser_login_sessions` plus stored token hashes.
+
+The source database path is recorded only after successful completion. A
+second start reports `already-migrated` and makes no changes. A failure rolls
+back SQLite metadata and leaves the source untouched.
+
+## State reused in place
+
+- Electron partition `persist:amalgm-browser`
+- `$AMALGM_DIR/browser` root and headless profile directories
+- existing project `.amalgm/recordings`
+- native Electron `userData/browser/adblock` cache and settings
+- bridge protocol 5 advertisement readers during rolling upgrade
+- legacy key from `AMALGM_BROWSER_AUTH_KEY` or
+  `auth-bundles/keys/local-device.key`
+
+The new registry also imports `registry-v1.json` transactionally once when
+present. It never deletes that source file automatically.
+
+## Verification checklist
+
+1. Stop all legacy Browser writers.
+2. Back up the Engine DB and Browser directory.
+3. Run import against a copy first.
+4. Compare profile, bundle, login, cookie-record, and tombstone counts.
+5. Open a durable headless profile and the isolated Electron partition.
+6. Load a named auth bundle and verify only its declared domains.
+7. Confirm DB/key/encrypted files are private and the source is unchanged.
+8. Re-run and confirm an idempotent no-op.
+
+Representative encrypted legacy fixtures exercise this sequence in the test
+suite.
+
+## Non-destructive rollback
+
+Before cutover, discard the new Browser root and continue from the untouched
+legacy source. After cutover writes occur, restore the complete pre-cutover
+backup rather than mixing formats or replaying selected files. Never copy
+cookies into a different Electron partition merely to normalize names.

package/docs/OPERATIONS.md

@@ -0,0 +1,69 @@
+# Operations
+
+## 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.
+
+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.
+
+## Environment
+
+| Variable | Purpose |
+| --- | --- |
+| `AMALGM_BROWSER_DIR` | standalone state root (`AMALGM_BROWSER_ROOT` legacy alias) |
+| `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_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_AUTH_KEY` | legacy-import key override only |
+| `AMALGM_BROWSER_DEBUG=1` | 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.
+
+## 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.
+
+## 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.
+
+## 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
+remote.

package/docs/README.md

@@ -0,0 +1,21 @@
+# Documentation
+
+Start with [the product purpose](../PURPOSE.md), then use the guide matching
+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
+  [Electron integration](./ELECTRON_INTEGRATION.md)
+- [Cookies](./COOKIES.md), [authentication](./AUTHENTICATION.md), and
+  [recording](./RECORDING.md)
+- [Events](./EVENTS.md) and the [Realtime boundary](./REALTIME_BOUNDARY.md)
+- [Toolbox](./TOOLBOX_INTEGRATION.md) and
+  [Engine](./ENGINE_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.

package/docs/REALTIME_BOUNDARY.md

@@ -0,0 +1,33 @@
+# 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.
+
+Browser receives opaque project/cwd/artifact values through
+`BrowserRuntimeContext` or an injected `BrowserArtifactStore`. It never imports
+Realtime or infers a project from Chat records.
+
+An invisible host-provided cwd flow looks like:
+
+```ts
+await browser.execute(sessionId, action, {
+  projectRef: realtimeProject.id,
+  cwdRef: realtimeProject.cwdRef,
+  artifactDestination: await realtime.resolveArtifactDirectory(realtimeProject),
+  signal,
+});
+```
+
+This is equivalent to a host resolving `amalgm cwd <project>` before the call;
+Browser consumes the result but does not create another project registry.
+
+Browser may persist its own operational metadata and encrypted secrets.
+Realtime may store or transport an encrypted Browser resource only as an
+opaque, authorized blob. Browser remains responsible for its schema,
+encryption, exclusions, merge rules, and decryption.
+
+Realtime may relay sanitized Browser events and place Browser artifacts. It
+does not become the session, cookie, or auth authority. Standalone Browser must
+continue to work without Realtime through explicit local adapters.

package/docs/RECORDING.md

@@ -0,0 +1,55 @@
+# Recording
+
+Recording is a Browser lifecycle, not a screenshot loop in an adapter.
+
+```ts
+const started = await browser.recordings.start({
+  sessionId: session.id,
+  fps: 15,
+  name: 'checkout',
+  context: { artifactDestination: projectRoot, signal },
+});
+
+const stopped = await browser.recordings.stop(session.id);
+```
+
+## Invariants
+
+- 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
+- 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.
+
+## 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`.
+Browser does not maintain a current-project registry. Artifacts are sensitive
+user data and the embedding store owns access control and retention.
+
+## Failure and restart visibility
+
+Missing ffmpeg or spawn failure returns a typed process error without crashing
+MCP or REST. Active rows record their owner PID. Startup marks a dead owner's
+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.

package/docs/REST.md

@@ -0,0 +1,69 @@
+# REST API
+
+Run either:
+
+```sh
+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>`.
+
+## Discovery and streaming
+
+- `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|DELETE /v1/sessions/:sessionId`
+- `POST /v1/sessions/:sessionId/cancel`
+- `POST /v1/sessions/:sessionId/actions/:action`
+
+Every one of the 22 canonical actions has an action route generated from the
+shared descriptor. Resource-specific routes below expose richer lifecycle
+operations.
+
+## Profiles, 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`
+- `POST /v1/auth/bundles/:bundleId/load|export`
+- `GET|POST /v1/auth/login-sessions`
+- `GET /v1/auth/login-sessions/:loginId`
+- `POST /v1/auth/login-sessions/:loginId/activate|input|complete|cancel`
+- `GET|POST /v1/recordings`
+- `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/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.
+
+## 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:
+
+```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.