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

package/PURPOSE.md

@@ -3,43 +3,39 @@
 ## Purpose
 
 Amalgm Browser gives users and software agents one safe, persistent,
-observable way to browse and operate the web across desktop and server
-environments. It presents the same browser actions through an SDK, CLI, MCP,
-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
+observable way to browse and operate the web. It presents the same browser
+actions through an SDK, CLI, MCP, and REST API. Each runtime runs one headless
+Chrome. Every session, usually one per chat, drives its own tabs in that
+Chrome, and every session browses as the runtime's signed-in Amalgm account. A
+viewer can watch and drive any session through its live view. Browser state
 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.
+Browser serves agents using Browser through a Toolbox, background automations
+and sub-agents, standalone SDK and CLI consumers, and MCP and REST clients.
 
-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.
+Amalgm Shell is the active composition root. It supplies the account, caller
+context, artifact storage, event relay, and UI coordination through public
+Browser ports. It does not own a second browser implementation.
 
 ## Primitives
 
 - A **browser service** is the sole mutation boundary for one Browser state
   directory.
-- A **driver** implements browser actions for one backend kind: `electron` or
-  `headless`.
-- A **profile** is a durable or ephemeral browser working identity.
-- A **session** is one live automation lifetime bound to one driver and one
-  profile.
-- A **page** is one web page belonging to one session.
-- A **surface** is one visible Electron-hosted page belonging to one session.
-- An **action** is one typed browser operation with backend-independent
-  meaning.
-- A **capability** states whether a driver supports an operation.
-- A **capture** is a bounded raster result from a session's actual page.
+- An **account** is the Amalgm identity the runtime browses as. Its one
+  durable profile owns every session, auth bundle, and login.
+- The **Chrome host** is the runtime's one headless Chrome, shared by every
+  session.
+- A **driver** runs actions for sessions. The default driver gives each
+  session its own agent-browser daemon attached to the Chrome host.
+- A **session** is one named, durable browsing context with its own tabs.
+- A **page** is one tab belonging to one session.
+- An **action** is one typed browser operation.
+- A **live view** is a session's stream of frames out and input in.
+- A **capture** is a bounded raster result from a session's own page.
 - A **recording** is a bounded capture lifecycle and its stored artifact.
-- A **cookie jar** is Browser's encrypted logical cookie authority.
-- A **cookie adapter** reconciles one driver's physical cookie store with the
-  logical jar.
+- A **cookie jar** is the account's encrypted cookie store of record.
+- A **cookie adapter** syncs one browser's physical cookie store with the jar.
 - An **auth bundle** is an explicit encrypted snapshot of named browser
   authentication state.
 - A **login session** is a TTL-bound handoff for human authentication.
@@ -77,86 +73,112 @@ locked dependency graph on the supported Node toolchain.
 
 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.
-3. Every live session belongs to exactly one backend and one profile, and its
-   backend never changes during that session.
-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. 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,
-   or child process. Process execution uses argv, bounded output, and bounded
-   termination without a shell.
-8. Browser output is bounded or externalized through an artifact store.
+2. Every state change passes through `BrowserService`. The driver executes
+   actions, and adapters expose the service without reimplementing its rules.
+3. Browsing identity is the Amalgm account alone. The registry keeps exactly
+   one durable profile, the account's, and every session, auth bundle, and
+   login belongs to it. A state root binds to that account atomically and
+   cannot be relabeled as another account.
+4. A runtime runs one Chrome, owned by one process at a time. Chrome starts on
+   first use and restarts on the next use after it dies. An OS-held lease
+   protects the profile; a dead owner's Chrome is retired only through the
+   exact browser endpoint that profile published, never by a PID guess.
+5. Every tab belongs to exactly one session. A session sees and controls only
+   its own tabs, every tab it opens lands in the account's browser context,
+   and no session may end or reshape the Chrome that others share.
+   Advanced argv describes page operations only; operation data is separate
+   from process configuration and cannot select another engine or account.
+6. Sessions are durable. A ready session from an earlier process reopens when
+   `createSession` names it again, as every adapter does on each call, and a
+   session keeps working after its Chrome dies and restarts. A session's live
+   view shows and drives only that session.
+7. Capture, computer-use input, and recording address the session's own page.
+   When that page is ambiguous, they fail with `SURFACE_IDENTITY_FAILED`
+   instead of guessing.
+8. Cancellation and deadlines reach the underlying CDP call, encoder, or child
+   process. Process execution uses argv, bounded output, and bounded
+   termination without a shell. Admission precedes asynchronous work; closing
+   stops admission, cancels and drains admitted operations, then releases
+   recordings, the driver and the registry, in that order.
+9. Browser output is bounded or externalized through an artifact store.
    Screenshot and computer-use coordinates share CSS-pixel space.
-9. Application authentication, the Electron `defaultSession`, the isolated
-   `persist:amalgm-browser` partition, and headless profile stores are separate
-   security domains. Browser never reads application authentication state.
-10. Cross-backend cookie portability occurs only through the encrypted Browser
-    jar. Merges are record-level, deletions are tombstoned, partition identity
-    is preserved, protected hosts are rejected, and drivers never reach into
-    one another's stores.
-11. Cookie values, tokens, origin storage, encryption keys, and authorization
-    headers never appear in logs, events, diagnostics, ordinary API results, or
+10. Application authentication and the Electron `defaultSession` are outside
+    Browser. Browser never reads application authentication state, and
+    cookies for protected hosts never enter the account.
+11. The account's encrypted cookie jar is the store of record. Each browser
+    store syncs both ways with the jar and never reads another store
+    directly. Merges are record-level, deletions are tombstoned, and
+    host-only, domain and partition scope are preserved. A reconnect cannot
+    resurrect a tombstoned cookie; only an observed new local edit can do so.
+    An interrupted adapter apply remains an unacknowledged store projection,
+    so its partial echo cannot supersede newer store changes.
+    Native cookie events carry the changed record: save it durably, then deliver
+    the committed change to the other browser stores. Ordinary mutations never
+    scan a store, rewrite the jar, or download a full snapshot. Connection and
+    recovery events alone initialize a store from a snapshot. An idle account
+    performs no cookie work; synchronization has no polling, debounce, or retry
+    timer. An unavailable connection resumes on a host readiness or cookie event.
+    The jar stores one encrypted row per cookie identity, including deletions;
+    a transaction is durable before its value-free revision notification.
+12. Cookie values, tokens, origin storage, encryption keys, and authorization
+    headers never appear in logs, public events, diagnostics, ordinary API results, or
     resource projections. Automatic synchronization moves cookies only.
-12. Profiles, cookie identity, auth bundles, and login sessions remain distinct.
-    Ephemeral profiles are pruned unless live or explicitly referenced; named
-    auth bundles move origin storage only when explicitly requested.
-13. Secret-bearing writes are encrypted, integrity-checked, atomic, and
-    permission-restricted. A missing or corrupt automatic cookie jar degrades
-    ordinary browsing safely instead of exposing secrets or disabling actions.
-14. Capture and recording resolve the session's actual page target without
-    first-target fallbacks. Recording proves capture before encoding, permits
-    one active recording per session, captures page imagery only, and stops an
-    uncooperative encoder within a deadline.
-15. Browser emits sanitized events. Project, cwd, authorization, and artifact
-    destinations enter through explicit context and ports; Browser never
-    invents a workspace or synchronization authority.
-16. Browser migrations are versioned, atomic, idempotent, and restart-safe.
+13. Cookies, auth bundles, and login sessions remain distinct. Named auth
+    bundles move origin storage only when explicitly requested. A login handoff
+    serializes its transitions, repeated activation keeps the same active page,
+    and a terminal login cannot become active again.
+14. Browser-owned secret records are encrypted, integrity-checked, atomic, and
+    permission-restricted; physical browser profiles follow platform storage policy.
+    A missing or corrupt cookie jar degrades ordinary
+    browsing safely instead of exposing secrets or disabling actions.
+15. Recording proves capture before encoding, permits one active recording
+    per session, captures page imagery only, and stops an uncooperative
+    encoder within a deadline.
+16. Browser emits sanitized events. Project, cwd, caller, authorization, and
+    artifact destinations enter through explicit context and ports; Browser
+    never invents a workspace or synchronization authority.
+17. Browser migrations are versioned, atomic, idempotent, and restart-safe.
     Existing Browser data is reused or verified before any destructive change.
-17. TypeScript under `src/` and `bin/` is the sole implementation source. The
+18. 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 Shell, Engine, or Electron. Behavior
+19. 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.
-20. Headless IPC uses a private OS-temporary socket namespace and a digest of
-    the canonical Browser root and session identity; durable path depth and
+20. Shell composes exactly one Browser service per runtime and closes it on
+    shutdown. Electron browses in a separate persistent partition for each
+    Amalgm account and syncs through Browser's private cookie adapter port;
+    it never creates a second registry, session authority, or action implementation.
+    Signing out retires that account's views and cookie adapter.
+21. agent-browser IPC uses a private OS-temporary socket namespace and a digest
+    of the canonical Browser root and session identity; durable path depth and
     session-name length cannot exceed the operating system's socket limit.
 
 ## Predictable behavior
 
-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
-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.
-Shell and Realtime can compose and relay Browser without becoming Browser.
+Every public surface dispatches the same typed action through
+`BrowserService`. The session is an explicit `session` input, else the
+caller's ID from the runtime context, else `default`, so each chat browses in
+its own session without naming one. The first use of a session in a process
+attaches its agent-browser daemon to the runtime's Chrome through the
+session's relay endpoint.
+
+All sessions share the account's browser context. A sign-in in one chat is
+visible in every other chat. Chrome's account profile and Electron's isolated
+account partition emit native cookie changes. Browser persists only those
+records and delivers only changes since each adapter's acknowledged revision.
+Chrome's private extension observes the profile, without attaching to websites
+or inspecting network traffic. The jar initializes each new connection;
+physical browser storage is a projection, never another authority.
+Named auth bundles are separate, explicit snapshots. Captures, input
+coordinates, and recordings address the session's own page, while large
+artifacts leave the API through the injected store. 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.
+
+Browser uses an explicitly configured Chrome, then an installed
+Chromium-family browser, then Chrome for Testing downloaded by agent-browser.
+Installing the npm dependency supplies agent-browser, not Chrome. Source CI
+provisions Chrome for Testing through the locked agent-browser dependency
+before the real-browser suite.

package/README.md

@@ -1,14 +1,15 @@
 # @amalgm/browser
 
-Amalgm Browser is one browser product for visible desktop browsing and
-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.
+Amalgm Browser gives agents and users one persistent, observable browser.
+Each runtime runs one headless Chrome. Every session, usually one per chat,
+drives its own tabs in it, and all sessions browse as the runtime's signed-in
+Amalgm account. Its TypeScript SDK owns behavior; the CLI, MCP server, REST
+API, Toolbox manifest, and packaged skill are projections of the same actions.
 
 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.
+Browser behavior. Read the [purpose and axioms](./PURPOSE.md) for the product
+contract.
 
 ## Install
 
@@ -16,51 +17,46 @@ Node.js 24 or newer is required.
 
 ```sh
 npm install @amalgm/browser
-npx --no-install agent-browser install
+npx --no-install agent-browser install   # only if no Chrome is installed
 ```
 
-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.
+The `agent-browser` dependency drives Chrome. Browser uses
+`AMALGM_BROWSER_EXECUTABLE_PATH` if set, then an installed Chrome, Chromium, or
+Brave, then the Chrome for Testing that `agent-browser install` downloads. See
+[Chrome runtime](./docs/CHROME.md).
 
-Electron is an optional peer dependency. Server consumers can install and
-import the core or headless exports without loading Electron.
+Electron is an optional peer dependency. Server consumers never load it.
 
 ## SDK quick start
 
 ```ts
 import { createBrowser } from '@amalgm/browser';
 
-const browser = createBrowser();
+const browser = createBrowser({ account: { id: 'user-1', name: 'Ada' } });
 const session = await browser.createSession({ id: 'research' });
 
-await browser.execute(session.id, {
-  type: 'open',
-  url: 'https://example.com',
-});
-
+await browser.execute(session.id, { type: 'open', url: 'https://example.com' });
 const snapshot = await browser.execute(session.id, { type: 'snapshot' });
+
 await browser.closeSession(session.id);
+await browser.close(); // stops Chrome
 ```
 
-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.
+Without `account`, the runtime browses as `{ id: 'local', name: 'Local' }`.
 
 ## CLI quick start
 
 ```sh
-amalgm-browser open https://example.com --session research
-amalgm-browser snapshot --session research
-amalgm-browser click @e3 --session research
-amalgm-browser screenshot --session research --full-page
-amalgm-browser close --session research
+amalgm-browser open https://example.com
+amalgm-browser sessions list
+amalgm-browser auth list
 ```
 
-Machine-readable JSON is the normal output. Use `--timeout`, `--cwd`,
-`--headless`, `--headed`, or `--cdp` when the operation needs explicit runtime
-context. See the [CLI reference](./docs/CLI.md).
+Output is JSON. A one-shot command starts Chrome, runs, and stops Chrome. The
+session record and the account's cookies carry over to the next command, but
+the open page does not. For multi-step browsing, keep one process running
+with `amalgm-browser mcp` or `amalgm-browser serve`. See the
+[CLI reference](./docs/CLI.md).
 
 ## MCP and REST
 
@@ -73,56 +69,55 @@ amalgm-browser serve --token 'replace-me'
 ```
 
 MCP uses newline-delimited JSON-RPC over stdio and exposes 22
-`browser_<action>` tools. REST defaults to loopback, authenticates every route
-except health, publishes OpenAPI at `/v1/openapi.json`, and streams sanitized
-events at `/v1/events`.
+`browser_<action>` tools. REST binds loopback, authenticates every route
+except health, publishes OpenAPI at `/v1/openapi.json`, streams sanitized
+events at `/v1/events`, and serves each session's live view as a WebSocket at
+`/v1/sessions/<id>/stream`.
 
 ## State, cookies, and authentication
 
-The default state root is `$AMALGM_BROWSER_DIR` (legacy
-`$AMALGM_BROWSER_ROOT`), then `$AMALGM_DIR/browser`, then
-`~/.amalgm/users/<scope>/browser`. Browser stores SQLite metadata, profile
-directories, encrypted cookie and authentication resources, and fallback
-artifacts there.
+The state root is `$AMALGM_BROWSER_DIR` (or `$AMALGM_BROWSER_ROOT`), then
+`$AMALGM_DIR/browser`, then `~/.amalgm/users/<scope>/browser`. It holds the
+SQLite registry, Chrome's user data, the encrypted cookie jar, auth bundles and
+login secrets, and fallback artifacts.
 
-The visible Electron browser must use `persist:amalgm-browser`; it must never
-use `defaultSession`. Electron and headless Chromium keep separate physical
-stores. Their adapters can reconcile cookie records only through Browser's
-encrypted, tombstone-aware logical jar. Named auth bundles are explicit and
-separate from automatic cookie synchronization. See [cookies](./docs/COOKIES.md)
-and [authentication](./docs/AUTHENTICATION.md).
+The account's encrypted cookie jar is the store of record. Chrome's cookies
+sync both ways with it, so a sign-in survives restarts and a sign-out anywhere
+applies everywhere. Cookies for Amalgm, Supabase, and loopback hosts never
+enter it. Named auth bundles are explicit and separate from this sync. See
+[cookies](./docs/COOKIES.md) and [authentication](./docs/AUTHENTICATION.md).
 
 ## Recording
 
-```sh
-amalgm-browser recordings start --session research --fps 15 --duration-ms 5000
+```ts
+await browser.recordings.start({ sessionId: session.id, fps: 15 });
+const recording = await browser.recordings.stop(session.id);
 ```
 
-Recordings contain the verified page only and are encoded as WebM. Results
+Recordings contain the session's page only and are encoded as WebM. Results
 report `wallSeconds` and `videoSeconds` separately. A host-provided artifact
 destination writes to `<destination>/.amalgm/recordings`; otherwise Browser
-uses its local fallback. See [recording](./docs/RECORDING.md).
+uses its state root. See [recording](./docs/RECORDING.md).
 
-## Desktop and Toolbox integration
+## Host integration
 
-- [Electron integration](./docs/ELECTRON_INTEGRATION.md) covers native
-  `WebContentsView` surfaces, identity, shell policy, cookies, and ad blocking.
+- [Shell integration](./docs/SHELL_INTEGRATION.md) covers creating the one
+  service, mapping chats to sessions, the live view, and shutdown.
+- [Electron integration](./docs/ELECTRON_INTEGRATION.md) covers the desktop
+  app's native browser tabs, policy, and ad blocking.
 - [Toolbox integration](./docs/TOOLBOX_INTEGRATION.md) covers the single
   `browser` tool, capability grants, and legacy aliases.
-- [Shell integration](./docs/SHELL_INTEGRATION.md) covers the one-service
-  composition boundary and the historical Engine cutover rule.
 
 ## Verify
 
 ```sh
 npm run verify
-npm run test:real
-npm run test:electron   # macOS real-Electron harness
+npm run test:real   # real Chrome and a real site
 ```
 
 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 Chromium and real Electron.
+hygiene. The opt-in suite drives real Chrome through agent-browser.
 
 The complete documentation index is [docs/README.md](./docs/README.md).
 

package/SECURITY.md

@@ -6,11 +6,11 @@ recordings.
 
 ## Isolation
 
-Browser separates application authentication, Electron
-`persist:amalgm-browser`, each headless profile, the logical cookie jar, and
-explicit auth bundles. It never queries Electron `defaultSession`. Drivers
-cannot inspect one another's physical stores; portability uses only the
-encrypted Browser adapter contract.
+Browser separates application authentication, the runtime's one Chrome, the
+Electron `persist:amalgm-browser` partition, the signed-in account's cookie
+jar, and explicit auth bundles. It never queries Electron `defaultSession`.
+Chrome and Electron never read each other's physical stores; cookies move
+between them only through the encrypted account jar.
 
 ## Secrets
 
@@ -38,9 +38,11 @@ body parsing where feasible, defaults to loopback, and refuses remote binding
 without explicit authorization. Put TLS and network access control in front of
 any remote deployment. Never expose `/internal/v1/*` to untrusted clients.
 
-Electron bridge advertisements accept only loopback CDP URLs and are private,
-atomic, PID-owned files. Visible actions verify the exact stamped surface and
-fail before input or capture on ambiguity.
+Chrome's debugging port listens on loopback only and is reached through
+Browser's relay. A session's live view is a WebSocket on the REST server under
+the same bearer token; an unauthorized viewer is closed with code 4401. A
+capture that cannot identify the session's own page fails before input or
+capture.
 
 ## User data
 

package/dist/bin/amalgm-browser-mcp.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-import { createBrowser } from '../src/index.js';
-import { createBrowserMcpServer } from '../src/mcp.js';
-await createBrowserMcpServer(createBrowser()).start();
+import { runBrowserCli } from '../src/cli.js';
+process.exitCode = await runBrowserCli(['mcp']);
 //# sourceMappingURL=amalgm-browser-mcp.js.map

package/dist/bin/amalgm-browser-mcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"amalgm-browser-mcp.js","sourceRoot":"","sources":["../../bin/amalgm-browser-mcp.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAEvD,MAAM,sBAAsB,CAAC,aAAa,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"amalgm-browser-mcp.js","sourceRoot":"","sources":["../../bin/amalgm-browser-mcp.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,CAAC,QAAQ,GAAG,MAAM,aAAa,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC"}

package/dist/bin/amalgm-browser-rest.js

@@ -1,20 +1,10 @@
 #!/usr/bin/env node
-import { createBrowser } from '../src/index.js';
-import { createBrowserHttpServer } from '../src/http.js';
-const token = process.env.AMALGM_BROWSER_TOKEN;
-if (!token)
-    throw new Error('AMALGM_BROWSER_TOKEN is required.');
-const host = process.env.AMALGM_BROWSER_HOST || '127.0.0.1';
-const port = Number(process.env.AMALGM_BROWSER_PORT || 0);
-if (!['127.0.0.1', '::1', 'localhost'].includes(host) && process.env.AMALGM_BROWSER_ALLOW_REMOTE !== '1') {
-    throw new Error('Non-loopback bind requires AMALGM_BROWSER_ALLOW_REMOTE=1.');
-}
-const server = createBrowserHttpServer({
-    browser: createBrowser(),
-    token,
-    allowRemote: process.env.AMALGM_BROWSER_ALLOW_REMOTE === '1',
-    ...(process.env.AMALGM_BROWSER_ADAPTER_TOKEN ? { adapterToken: process.env.AMALGM_BROWSER_ADAPTER_TOKEN } : {}),
-});
-const address = await server.listen(port, host);
-process.stderr.write(`amalgm-browser-rest listening on http://${address.address}:${address.port}\n`);
+import { runBrowserCli } from '../src/cli.js';
+// `amalgm-browser serve`, configured from the environment.
+const env = process.env;
+process.exitCode = await runBrowserCli(['serve',
+    ...(env.AMALGM_BROWSER_HOST ? ['--host', env.AMALGM_BROWSER_HOST] : []),
+    ...(env.AMALGM_BROWSER_PORT ? ['--port', env.AMALGM_BROWSER_PORT] : []),
+    ...(env.AMALGM_BROWSER_ALLOW_REMOTE === '1' ? ['--allow-remote'] : []),
+]);
 //# sourceMappingURL=amalgm-browser-rest.js.map

package/dist/bin/amalgm-browser-rest.js.map

@@ -1 +1 @@
-{"version":3,"file":"amalgm-browser-rest.js","sourceRoot":"","sources":["../../bin/amalgm-browser-rest.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAEzD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;AAC/C,IAAI,CAAC,KAAK;IAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;AACjE,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,WAAW,CAAC;AAC5D,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,CAAC,CAAC,CAAC;AAC1D,IAAI,CAAC,CAAC,WAAW,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,2BAA2B,KAAK,GAAG,EAAE,CAAC;IACzG,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;AAC/E,CAAC;AACD,MAAM,MAAM,GAAG,uBAAuB,CAAC;IACrC,OAAO,EAAE,aAAa,EAAE;IACxB,KAAK;IACL,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,2BAA2B,KAAK,GAAG;IAC5D,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,4BAA4B,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;CAChH,CAAC,CAAC;AACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAChD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2CAA2C,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,IAAI,CAAC,CAAC"}
+{"version":3,"file":"amalgm-browser-rest.js","sourceRoot":"","sources":["../../bin/amalgm-browser-rest.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,2DAA2D;AAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;AACxB,OAAO,CAAC,QAAQ,GAAG,MAAM,aAAa,CAAC,CAAC,OAAO;IAC7C,GAAG,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,GAAG,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,GAAG,CAAC,GAAG,CAAC,2BAA2B,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;CACvE,CAAC,CAAC"}

package/dist/src/account.d.ts

@@ -0,0 +1,8 @@
+import type { BrowserRegistry } from './ports.js';
+import type { BrowserProfile } from './types.js';
+export interface BrowserAccount {
+    id: string;
+    name: string;
+}
+export declare const LOCAL_ACCOUNT: BrowserAccount;
+export declare function enrollAccount(registry: BrowserRegistry, account: BrowserAccount, now: string): BrowserProfile;

package/dist/src/account.js

@@ -0,0 +1,42 @@
+import { safeId } from './ids.js';
+import { BrowserError } from './errors.js';
+// The account a runtime browses as until it is told who is signed in.
+export const LOCAL_ACCOUNT = { id: 'local', name: 'Local' };
+// Browsing identity is the amalgm account alone: the registry keeps exactly
+// one durable profile, the account's, and every session, login and auth
+// bundle belongs to it.
+export function enrollAccount(registry, account, now) {
+    return registry.transaction(() => {
+        const owner = registry.getMeta('account-id');
+        if (owner !== undefined && owner !== account.id) {
+            throw new BrowserError('AUTHORIZATION_DENIED', 'This Browser state belongs to another Amalgm account.');
+        }
+        const id = safeId(account.id);
+        const state = registry.snapshot();
+        for (const profile of state.profiles)
+            if (profile.id !== id)
+                registry.deleteProfile(profile.id);
+        for (const session of state.sessions)
+            if (session.profileId !== id)
+                registry.putSession({ ...session, profileId: id });
+        for (const bundle of state.authBundles)
+            if (bundle.profileId !== id)
+                registry.putAuthBundle({ ...bundle, profileId: id });
+        for (const login of state.loginSessions)
+            if (login.profileId !== id)
+                registry.putLoginSession({ ...login, profileId: id });
+        const existing = state.profiles.find((profile) => profile.id === id);
+        const profile = {
+            id,
+            name: account.name.trim() || id,
+            kind: 'durable',
+            createdAt: existing?.createdAt || now,
+            updatedAt: now,
+            lastUsedAt: now,
+        };
+        registry.putProfile(profile);
+        registry.setMeta('account-id', account.id);
+        return profile;
+    });
+}
+//# sourceMappingURL=account.js.map

package/dist/src/account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../../src/account.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAS3C,sEAAsE;AACtE,MAAM,CAAC,MAAM,aAAa,GAAmB,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAE5E,4EAA4E;AAC5E,wEAAwE;AACxE,wBAAwB;AACxB,MAAM,UAAU,aAAa,CAAC,QAAyB,EAAE,OAAuB,EAAE,GAAW;IAC3F,OAAO,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE;QAC/B,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAC7C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,OAAO,CAAC,EAAE,EAAE,CAAC;YAChD,MAAM,IAAI,YAAY,CAAC,sBAAsB,EAAE,uDAAuD,CAAC,CAAC;QAC1G,CAAC;QACD,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC9B,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,EAAE,CAAC;QAClC,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ;YAAE,IAAI,OAAO,CAAC,EAAE,KAAK,EAAE;gBAAE,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAChG,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ;YAAE,IAAI,OAAO,CAAC,SAAS,KAAK,EAAE;gBAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;QACvH,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,WAAW;YAAE,IAAI,MAAM,CAAC,SAAS,KAAK,EAAE;gBAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;QAC1H,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,aAAa;YAAE,IAAI,KAAK,CAAC,SAAS,KAAK,EAAE;gBAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,GAAG,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;QAC3H,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QACrE,MAAM,OAAO,GAAmB;YAC9B,EAAE;YACF,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE;YAC/B,IAAI,EAAE,SAAS;YACf,SAAS,EAAE,QAAQ,EAAE,SAAS,IAAI,GAAG;YACrC,SAAS,EAAE,GAAG;YACd,UAAU,EAAE,GAAG;SAChB,CAAC;QACF,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;QAC7B,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QAC3C,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/action.d.ts

@@ -1,5 +1,4 @@
-import type { BrowserAction, BrowserActionResult, BrowserCapability } from './types.js';
+import type { BrowserAction, BrowserActionResult } from './types.js';
 export declare function validateAction(action: BrowserAction): void;
-export declare function assertActionCapability(action: BrowserAction, capabilities: readonly BrowserCapability[]): void;
 export declare function safeOrigin(value: string): string;
 export declare function boundResult(result: BrowserActionResult): BrowserActionResult;