@sponsorcoin/merit-connect 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## Unreleased
+
+- Account states: the caller keeps the remote accounts as CONNECTED or DISCONNECTED (`getDisconnected` / `setDisconnected`, `setAccountConnected`, `listAccounts`). A disconnect made by the caller keeps the account listed; only the remote removes an account (the handshake removes what the remote disconnected, adds what it connected, and lets the caller's own disconnect win). New call `merit_syncAccounts`: the caller sends its connected list and the remote connects exactly those that exist on it. The wallet-level `revoke` now turns every connected account into a kept, disconnected one. 17 tests, 7 mutants.
+- Opening a selection is a SYNC: `eth_requestAccounts` carries the list of accounts the caller wants connected; the remote sets exactly those that exist on it to connected before the selector opens and leaves every other account disconnected. A caller that sends no list changes nothing. 3 tests, 1 more mutant, 1 live check.
+- Connection monitor (`createConnectionMonitor`, `describeConnection`): one subscribable store for the link, with the reason it is not connected (`detached`, `page-silent`, `no-page`, `unknown`) and `waitForConnected`. 15 tests, 6 more mutants.
+
+## 0.0.1 (2026-11-06)
+
+First version, protocol version 1.
+
+- Messages, version check and parsing (`protocol`): one error table including 4901 (version not supported).
+- Requester hub (`createRelay`): one page per request, an answer only from the page and origin asked, once, in time; selection sessions that stay open for pushes; every drop traced with its reason.
+- Responder (`createResponder`): the account selection (starts from what the requester holds, the first change answers, later changes are pushed, a close ends it), revoke, the shared-account check on every signature, one request at a time.
+- Standard calls (`createMeritConnect`): `fetchMeritConnections`, `requestAccounts`, `handshake` (pulled, waits for the link, keeps the stored copy on failure), `revoke`, `onConnectionChange`.
+- Adapters for the Chrome extension and the web page (`createWorkerHub`, `createPanelRequest`, `attachWebPageResponder`), and the in-memory `createLoopback`.
+- One trace channel, `merit-connect:<event>`, with the request id on every line.
+- 74 unit tests, 17 adapter and chain tests, 26 mutants (all caught), and a live end-to-end test (`test/live`).

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @sponsorcoin/merit-connect
+
+The protocol one Merit wallet uses to ask another Merit wallet who is connected, for its accounts, and for signatures. Zero dependencies: no React, no `window`, no `chrome`. The transport (Chrome extension messaging, a web page, the in-memory loopback) is injected.
+
+Design, contract, error codes and the build rows: `docs/design/meritConnectDesign.txt` of the web app repo.
+
+Status (2026-11-06): in use. The Merit Chrome extension and the Merit web app both run on it (the extension's worker relay and side-panel authenticator, the web app's responder). The protocol is version 1; the API below is the one `0.x` will keep stable. See `CHANGELOG.md`.
+
+Build: `npm run build` (tsc, output in `dist/`, which is tracked like the other packages). Test: `npm test` (builds, runs the five test files and the mutation check: every mutant, a deliberately broken rule in a copy of the build, must be caught). Live: `test/live/meritConnect.live.cjs` runs the real extension and the real web app in a real Chromium (its header lists what it needs). Example: `node examples/loopback.mjs`, a complete holder and asker over the in-memory loopback.
+
+## The calls
+
+```ts
+import { createMeritConnect } from '@sponsorcoin/merit-connect';
+
+const connect = createMeritConnect({ WEB_APP: { request, link, subscribeLink, getShared, setShared, newRid, setTimer, clearTimer, now, trace } });
+
+await connect.fetchMeritConnections('WEB_APP'); // { side, connected, loggedOn, detached, shared }
+await connect.requestAccounts('WEB_APP');       // opens the other wallet's account selector
+await connect.handshake('WEB_APP');             // pulls the other wallet's shared list, keeps it
+await connect.revoke('WEB_APP');                // disconnects from that wallet's accounts
+```
+
+`side` is `'EXT'` or `'WEB_APP'`: the wallet being asked. The other wallet is the authority for its own shared list; the copy a wallet keeps is corrected by a pull (`handshake`), never by an unasked push.
+
+## The halves
+
+| Piece | Where it runs | What it does |
+| --- | --- | --- |
+| `createRelay` | the requester's hub (the extension's worker) | sends a request to ONE page, takes an answer only from that page and origin, once, in time; opens a selection session; takes pushes only while it is open |
+| `createResponder` | the wallet that holds the accounts (the web page) | answers reads, runs the account selection, refuses what is not allow-listed, checks that a signing account is shared |
+| `createMeritConnect` | the wallet that asks | the standard calls above, over one `request` function |
+| `createLoopback` | tests | wires a relay to a responder in memory; can drop, duplicate, delay and mislabel messages |
+| `createWorkerHub`, `createPanelRequest`, `attachWebPageResponder` | the Chrome extension and the web page | the adapters (`src/transports.ts`): the worker's relay wired to the tabs, the side panel's request over the worker, the page's responder wired to its provider |
+
+## Writing your own transport
+
+The cores never touch a browser API. A host supplies the channel and says who the SENDER is as its own platform knows it (the browser's tab and origin, never the message's own words):
+
+- the requester's hub needs `targets()` (the pages it can ask), `send(targetId, message)`, timers, an id source and `now()`; it hands every incoming reply to `relay.accept(sender, payload)` and every selection push to `relay.acceptPush(sender, payload)`;
+- the responder needs `reply(reply)` and `push(push)` to send, `handlers` (what the wallet knows and does), and is fed requests with `responder.handle(data)`;
+- the client calls need one `request(method, params, rid)` function that resolves with a reply.
+
+`test/transports.test.mjs` is a complete worked example with plain objects standing in for the Chrome APIs.
+
+## The protocol in short
+
+A message carries `v` (the version, 1) and `rid` (the request id, 1 to 64 letters, digits, `-` and `_`). Methods: `eth_chainId`, `eth_accounts`, `wallet_revokePermissions` (reads, 20 s), `eth_requestAccounts`, `personal_sign`, `eth_signTypedData_v4`, `eth_sendTransaction` (approvals, 5 min). Errors: 4001 rejected, 4100 not authorised, 4200 unsupported, 4900 unavailable, 4901 version not supported, -32602 invalid params, -32005 too many pending. The full contract, the authority and sync rules and the security rules: `docs/design/meritConnectDesign.txt`.
+
+## Account states and the sync call
+
+The caller keeps the remote's accounts as CONNECTED or DISCONNECTED (give `getDisconnected` / `setDisconnected` to keep the disconnected ones). The rules:
+
+- **Connect** (the caller presses it): the caller's connected accounts are sent (`merit_syncAccounts`, or inside `eth_requestAccounts` when a selector is opened); the remote connects exactly those that exist on it and every other account there stays disconnected.
+- **The caller changes an account** (`setAccountConnected`): the account STAYS in the caller's list and only its state changes. `revoke` (the wallet-level Disconnect) turns every connected account into a disconnected one that stays listed.
+- **The remote changes an account**: when it disconnects one, the caller REMOVES it from its list (the remote owns the accounts); when it connects one, the caller ADDS it. Pushes (while a selector is open) and the handshake apply this.
+- The caller's own disconnect wins if the remote was away: the handshake tells the remote.
+
+## The connection monitor
+
+`createConnectionMonitor` is a plain store (`subscribe`, `getSnapshot`; it drops into `useSyncExternalStore`) that says whether the other wallet is connected and, when it is not, WHY in a sentence a person can act on:
+
+| state | meaning | reason shown |
+| --- | --- | --- |
+| `connected` | a page answers and the person has not disconnected it | |
+| `detached` | the person disconnected it on purpose (that choice wins) | "You disconnected ... Press Connect to use it again." |
+| `page-silent` | a page is open but does not answer (a reloaded extension leaves its content script dead) | "... Reload that page (F5) and try again." |
+| `no-page` | no page is open | "... Open it, or press Connect to open it." |
+| `unknown` | the probe itself could not be asked | "... Reload the extension and try again." |
+
+The host supplies one probe, `{ reporting, candidates, loggedOn }` (how many pages answered, how many pages that could be it are open and did NOT, whether the answering one is logged on). `waitForConnected(timeoutMs)` resolves as soon as it connects (asking again every 2 s, so a page the person reloads meanwhile is noticed) or at the limit with the current reason.
+
+## Trace
+
+Every step calls the host's trace function with `merit-connect:<event>` and a detail that carries the request id (`rid`): `request`, `sent`, `received`, `answered`, `failed`, `refused` (with the reason), `selection.open`, `selection.change`, `selection.push`, `selection.close`, `handshake`, `revoke`. A request that was dropped is an id with no later event; a mismatched one is a `refused` event that names the sender.

package/dist/client.d.ts

@@ -0,0 +1,83 @@
+import { type Reply, type Side } from './protocol.js';
+import { type TraceFn } from './trace.js';
+/** How a host asks the other wallet: the relay's `request`, reached however the host reaches it. Always resolves with a reply. */
+export type RequestFn = (method: string, params: unknown, rid: string) => Promise<Reply>;
+export interface LinkState {
+    /** The other wallet answers and the person has not disconnected it. */
+    connected: boolean;
+    loggedOn: boolean;
+    detached: boolean;
+}
+export interface SideConfig {
+    request: RequestFn;
+    /** The link as it reads now. It reads "not connected" until its first answer comes back. */
+    link(): LinkState;
+    /** Called when the link comes up or goes down. Returns the unsubscribe function. */
+    subscribeLink(listener: () => void): () => void;
+    /** The copy of the other wallet's shared accounts that this wallet keeps. */
+    getShared(): Promise<string[]> | string[];
+    setShared(accounts: string[]): Promise<void> | void;
+    /**
+     * 2026-11-06 (owner rule): the accounts of the other wallet that this wallet KEEPS in its list but has disconnected. When the caller changes an account's state the account stays listed and only its state changes; only the OTHER wallet
+     * (by disconnecting it there) removes an account from this list. A host that does not keep such a list leaves these out: a disconnect then removes the account, as before.
+     */
+    getDisconnected?(): Promise<string[]> | string[];
+    setDisconnected?(accounts: string[]): Promise<void> | void;
+    newRid(): string;
+    setTimer(fn: () => void, ms: number): unknown;
+    clearTimer(handle: unknown): void;
+    now(): number;
+    trace?: TraceFn;
+    /** 2026-11-06 (owner): a message for the person when the OTHER wallet took accounts out of this list ("Disconnected by Remote", "Account Does not Exist on ..., Removed from Local"). The host shows it as a notice. */
+    notify?(message: string, addresses: string[]): void;
+}
+export interface Connections {
+    side: Side;
+    connected: boolean;
+    loggedOn: boolean;
+    detached: boolean;
+    shared: string[];
+}
+export interface HandshakeResult {
+    /** The copy was different and was replaced. */
+    changed: boolean;
+    /** The accounts connected here and there after the handshake. */
+    shared: string[];
+    /** Accounts kept in the list but disconnected here (empty when the host keeps no such list). */
+    disconnected?: string[];
+    /** Why no answer was asked for (the stored copy was kept). */
+    skipped?: string;
+}
+/** How long a list that loads while the link still reads "not connected" waits for the link before it shows what it has. */
+export declare const LINK_WAIT_MS = 1500;
+/** How long the handshake waits for the other wallet's answer. */
+export declare const HANDSHAKE_MS = 2500;
+/** A handshake asked this recently is not asked again (the list loads often). */
+export declare const HANDSHAKE_MIN_GAP_MS = 1500;
+/** One account of the other wallet as this wallet lists it: connected or disconnected (kept, not removed). */
+export interface ListedAccount {
+    address: string;
+    connected: boolean;
+}
+/** The standard calls, for the sides this host can reach. A side that was not configured throws 4900. */
+export declare function createMeritConnect(sides: Partial<Record<Side, SideConfig>>): {
+    fetchMeritConnections: (side: Side, options?: {
+        refresh?: boolean;
+    }) => Promise<Connections>;
+    requestAccounts: (side: Side) => Promise<string[]>;
+    /** Connect this wallet to the other: its own Connect page (Cancel / Connect), no accounts. */
+    requestConnection: (side: Side) => Promise<void>;
+    handshake: (side: Side, options?: {
+        force?: boolean;
+    }) => Promise<HandshakeResult>;
+    revoke: (side: Side) => Promise<void>;
+    /** Connect or disconnect ONE account from this wallet (a disconnected account stays in the list). */
+    setAccountConnected: (side: Side, address: string, connected: boolean) => Promise<void>;
+    /** Remove ONE account of the other wallet from this wallet's list (the other wallet is told to disconnect it first and keeps the account). */
+    forgetAccount: (side: Side, address: string) => Promise<void>;
+    /** The accounts as this wallet lists them, each connected or disconnected. */
+    listAccounts: (side: Side) => Promise<ListedAccount[]>;
+    /** The link to that side came up or went down: the host re-runs its list load (which runs the handshake). */
+    onConnectionChange: (side: Side, listener: () => void) => () => void;
+};
+export type MeritConnect = ReturnType<typeof createMeritConnect>;

package/dist/client.js

@@ -0,0 +1,299 @@
+// File: src/client.ts
+//
+// 2026-11-06 (docs/design/meritConnectDesign.txt, rows M6 and section 7): the standard calls a wallet makes to ask another Merit wallet who is connected, for its accounts, and to disconnect. They run over ONE function the
+// host supplies (`request`: in the Chrome extension a message to the worker's relay), so the calls are the same in every app. The side asked is 'EXT' or 'WEB_APP'.
+//
+// The copy of the other wallet's shared list that this wallet keeps is for DISPLAY. The other wallet is the authority (design section 6), so the copy is corrected by a PULL (handshake), never by an unasked push.
+import { ERROR, MeritConnectError, isAddress } from './protocol.js';
+import { createTrace } from './trace.js';
+/** How long a list that loads while the link still reads "not connected" waits for the link before it shows what it has. */
+export const LINK_WAIT_MS = 1500;
+/** How long the handshake waits for the other wallet's answer. */
+export const HANDSHAKE_MS = 2500;
+/** A handshake asked this recently is not asked again (the list loads often). */
+export const HANDSHAKE_MIN_GAP_MS = 1500;
+const sameList = (a, b) => a.length === b.length && a.every((x) => b.some((y) => y.toLowerCase() === x.toLowerCase()));
+const has = (list, address) => list.some((a) => a.toLowerCase() === address.toLowerCase());
+const without = (list, remove) => list.filter((a) => !has(remove, a));
+const union = (a, b) => [...a, ...b.filter((x) => !has(a, x))];
+function createSideClient(side, config) {
+    const trace = createTrace(config.trace);
+    let lastHandshakeAt = Number.NEGATIVE_INFINITY;
+    // 2026-11-06 (owner): this wallet's connected accounts are kept (persisted) while the link is down, and the remote disconnects ALL of its accounts then. So the FIRST handshake after a start, a disconnect or a lost link does not pull: it
+    // RE-SENDS this wallet's connected list (merit_syncAccounts), which re-establishes the connection states. An account the remote does not have is removed here, with a notice.
+    let needsResync = true;
+    // a state change made here is being sent: the list reloads it causes must not pull (the other wallet has not heard of it yet, and would bring the account back)
+    let changing = 0;
+    config.subscribeLink(() => {
+        if (!config.link().connected)
+            needsResync = true;
+    });
+    const appName = side === 'EXT' ? 'Merit (Ext)' : 'Merit (Web App)';
+    const announce = (addresses, why) => {
+        config.notify?.(why === 'missing' ? `Account Does not Exist on ${appName}\nRemoved from Local` : `Disconnected by Remote\n${appName}`, addresses);
+    };
+    /** The link may read "not connected" only because its first answer has not come back: wait for it a moment. */
+    function waitForLink() {
+        if (config.link().connected)
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            let timer;
+            let off = () => undefined;
+            const done = (value) => {
+                off();
+                config.clearTimer(timer);
+                resolve(value);
+            };
+            off = config.subscribeLink(() => {
+                if (config.link().connected)
+                    done(true);
+            });
+            timer = config.setTimer(() => done(false), LINK_WAIT_MS);
+        });
+    }
+    function withTimeout(promise, ms, what) {
+        return new Promise((resolve, reject) => {
+            const timer = config.setTimer(() => reject(new Error(`${what} timed out`)), ms);
+            promise.then((value) => {
+                config.clearTimer(timer);
+                resolve(value);
+            }, (error) => {
+                config.clearTimer(timer);
+                reject(error);
+            });
+        });
+    }
+    const readDisconnected = async () => (config.getDisconnected ? [...(await config.getDisconnected())] : []);
+    const writeDisconnected = async (accounts) => {
+        if (config.setDisconnected)
+            await config.setDisconnected(accounts);
+    };
+    /** Tell the other wallet which accounts are connected (merit_syncAccounts). Resolves with the list it really holds connected now. */
+    async function syncRemote(connected, why) {
+        const rid = config.newRid();
+        trace('request', { side, rid, method: 'merit_syncAccounts', asked: connected.length, why });
+        const reply = await config.request('merit_syncAccounts', [{ connected }], rid);
+        if (!reply.ok)
+            throw new MeritConnectError(reply.error.code, reply.error.message, reply.error.data);
+        return (Array.isArray(reply.result) ? reply.result : []).filter(isAddress);
+    }
+    /**
+     * Make the two lists one. The other wallet owns the accounts, so what it has connected decides the connected accounts here:
+     *   - connected here but no longer connected there: the other wallet DISCONNECTED it, so it is REMOVED from this list;
+     *   - connected there but not known here: the other wallet connected it, so it is ADDED as connected;
+     *   - disconnected HERE (kept in the list) but still connected there: this wallet changed its state, so this wallet's choice wins and the other wallet is told.
+     */
+    async function handshake(options) {
+        const stored = [...(await config.getShared())];
+        const kept = await readDisconnected();
+        const listed = () => (config.getDisconnected ? { disconnected: kept } : {});
+        const unchanged = (skipped) => ({ changed: false, shared: stored, ...listed(), skipped });
+        if (changing) {
+            trace('handshake', { side, skipped: 'a change is being sent', stored: stored.length });
+            return unchanged('a change is being sent');
+        }
+        if (!(await waitForLink())) {
+            trace('handshake', { side, skipped: 'other wallet not connected', stored: stored.length });
+            return unchanged('other wallet not connected');
+        }
+        if (!options?.force && config.now() - lastHandshakeAt < HANDSHAKE_MIN_GAP_MS) {
+            trace('handshake', { side, skipped: 'asked a moment ago', stored: stored.length });
+            return unchanged('asked a moment ago');
+        }
+        lastHandshakeAt = config.now();
+        const rid = config.newRid();
+        try {
+            if (needsResync && stored.length) {
+                const there = await withTimeout(syncRemote(stored, 'reconnect'), HANDSHAKE_MS, 'handshake');
+                needsResync = false;
+                const missing = stored.filter((a) => !has(there, a));
+                trace('handshake', { side, rid, resync: true, sent: stored.length, connected: stored.length - missing.length, missing: missing.length });
+                if (!missing.length)
+                    return { changed: false, shared: stored, ...listed() };
+                const next = without(stored, missing);
+                await writeDisconnected(without(kept, missing));
+                await config.setShared(next);
+                announce(missing, 'missing');
+                return { changed: true, shared: next, ...listed() };
+            }
+            needsResync = false;
+            const reply = await withTimeout(config.request('eth_accounts', undefined, rid), HANDSHAKE_MS, 'handshake');
+            if (!reply.ok)
+                throw new MeritConnectError(reply.error.code, reply.error.message);
+            const remote = (Array.isArray(reply.result) ? reply.result : []).filter(isAddress);
+            const removed = stored.filter((a) => !has(remote, a));
+            const added = remote.filter((a) => !has(stored, a) && !has(kept, a));
+            const mine = remote.filter((a) => has(kept, a));
+            const next = union(without(stored, removed), added);
+            const changed = !sameList(next, stored);
+            trace('handshake', { side, rid, stored: stored.length, shared: next.length, removed: removed.length, added: added.length, mineWins: mine.length, changed });
+            if (changed)
+                await config.setShared(next);
+            if (removed.length)
+                announce(removed, 'disconnected');
+            if (mine.length) {
+                try {
+                    await syncRemote(next, 'a disconnect made here');
+                }
+                catch (error) {
+                    trace('handshake', { side, rid, failed: error instanceof Error ? error.message : String(error), when: 'telling the other wallet about a disconnect' });
+                }
+            }
+            return { changed, shared: next, ...listed() };
+        }
+        catch (error) {
+            // a failed or timed-out handshake KEEPS the stored copy
+            trace('handshake', { side, rid, failed: error instanceof Error ? error.message : String(error), kept: stored.length });
+            return unchanged('failed');
+        }
+    }
+    async function fetchMeritConnections(options) {
+        const link = config.link();
+        const shared = options?.refresh === false || !link.connected ? [...(await config.getShared())] : (await handshake()).shared;
+        return { side, connected: link.connected, loggedOn: link.loggedOn, detached: link.detached, shared };
+    }
+    /** The accounts of the other wallet as this wallet lists them: the connected ones, then the ones kept but disconnected. */
+    async function listAccounts() {
+        const connected = [...(await config.getShared())];
+        const kept = without(await readDisconnected(), connected);
+        return [...connected.map((address) => ({ address, connected: true })), ...kept.map((address) => ({ address, connected: false }))];
+    }
+    /** Open the other wallet's account selector; resolves with the accounts it answers (the first change), which are kept. Later changes arrive as pushes through the relay. */
+    async function requestAccounts() {
+        const rid = config.newRid();
+        const held = [...(await config.getShared())];
+        trace('request', { side, rid, method: 'eth_requestAccounts', held: held.length });
+        const reply = await config.request('eth_requestAccounts', [{ shared: held }], rid);
+        if (!reply.ok) {
+            trace('failed', { side, rid, method: 'eth_requestAccounts', code: reply.error.code });
+            throw new MeritConnectError(reply.error.code, reply.error.message, reply.error.data);
+        }
+        const accounts = (Array.isArray(reply.result) ? reply.result : []).filter(isAddress);
+        // an account the other wallet now has connected is no longer one this wallet holds disconnected (written first: the list reload the shared list causes reads it)
+        await writeDisconnected(without(await readDisconnected(), accounts));
+        await config.setShared(accounts);
+        return accounts;
+    }
+    /** 2026-11-07 (owner: Connect has its own page, like MetaMask): connect THIS wallet to the other. The other wallet shows its own Connect page (Cancel / Connect); no account is chosen or changed here. Rejects when the person cancels there. */
+    async function requestConnection() {
+        const rid = config.newRid();
+        trace('request', { side, rid, method: 'merit_requestConnection' });
+        const reply = await config.request('merit_requestConnection', [], rid);
+        if (!reply.ok) {
+            trace('failed', { side, rid, method: 'merit_requestConnection', code: reply.error.code });
+            throw new MeritConnectError(reply.error.code, reply.error.message, reply.error.data);
+        }
+    }
+    /**
+     * Change one account's state from THIS wallet. Connect: the other wallet is told (it must be reachable) and answers with what really is connected. Disconnect: the account STAYS in this list as disconnected; the other wallet is told when it can
+     * be (when it cannot, the next handshake tells it: this wallet's choice wins).
+     */
+    async function setAccountConnected(address, connected) {
+        changing++;
+        try {
+            await changeAccount(address, connected);
+        }
+        finally {
+            changing--;
+        }
+    }
+    /**
+     * 2026-11-08 (owner, docs/design/removeAccountPlan.txt X3, X4): REMOVE one account of the other wallet from this wallet's list. The other wallet is told to disconnect it first (it must be reachable, else it would bring the account back at the next handshake),
+     * then the account is forgotten here: it is no longer shared, no longer kept disconnected, so it is not listed. It returns only when the other wallet connects it again. The other wallet keeps the account itself.
+     */
+    async function forgetAccount(address) {
+        if (!isAddress(address))
+            throw new MeritConnectError(ERROR.INVALID_PARAMS, 'That is not an account address.');
+        if (!(await waitForLink()))
+            throw new MeritConnectError(ERROR.UNAVAILABLE, 'The other wallet is not connected, so it cannot be told to disconnect this account. Connect it first, then remove the account.');
+        changing++;
+        try {
+            await changeAccount(address, false);
+            await writeDisconnected(without(await readDisconnected(), [address]));
+        }
+        finally {
+            changing--;
+        }
+    }
+    async function changeAccount(address, connected) {
+        if (!isAddress(address))
+            throw new MeritConnectError(ERROR.INVALID_PARAMS, 'That is not an account address.');
+        const current = [...(await config.getShared())];
+        const kept = await readDisconnected();
+        if (connected) {
+            if (!(await waitForLink()))
+                throw new MeritConnectError(ERROR.UNAVAILABLE, 'The other wallet is not connected, so the account cannot be connected there.');
+            const now = await syncRemote(union(current, [address]), 'connect ' + address.slice(0, 8));
+            if (!has(now, address))
+                throw new MeritConnectError(ERROR.UNAUTHORIZED, 'That account is not on the other wallet.');
+            await writeDisconnected(without(kept, now));
+            await config.setShared(now);
+            return;
+        }
+        const next = without(current, [address]);
+        await writeDisconnected(config.setDisconnected ? union(kept, [address]) : kept);
+        await config.setShared(next);
+        if (!config.link().connected) {
+            trace('request', { side, method: 'merit_syncAccounts', skipped: 'other wallet not connected: the next handshake tells it', disconnect: address.slice(0, 8) });
+            return;
+        }
+        try {
+            await syncRemote(next, 'disconnect ' + address.slice(0, 8));
+        }
+        catch (error) {
+            trace('request', { side, method: 'merit_syncAccounts', failed: error instanceof Error ? error.message : String(error), disconnect: address.slice(0, 8) });
+        }
+    }
+    /**
+     * Disconnect from the other wallet (2026-11-06, owner): this wallet's accounts KEEP their connected state (persisted, so the connection can be re-established); the OTHER wallet disconnects all of its accounts. When the link is made again
+     * the first handshake re-sends the connected list.
+     */
+    async function revoke() {
+        needsResync = true;
+        const rid = config.newRid();
+        try {
+            const reply = await config.request('wallet_revokePermissions', undefined, rid);
+            trace('revoke', { side, rid, ok: reply.ok, ...(reply.ok ? {} : { code: reply.error.code }) });
+        }
+        catch (error) {
+            trace('revoke', { side, rid, failed: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    return { handshake, fetchMeritConnections, requestAccounts, requestConnection, revoke, setAccountConnected, forgetAccount, listAccounts };
+}
+/** The standard calls, for the sides this host can reach. A side that was not configured throws 4900. */
+export function createMeritConnect(sides) {
+    const clients = new Map();
+    const client = (side) => {
+        const config = sides[side];
+        if (!config)
+            throw new MeritConnectError(ERROR.UNAVAILABLE, `This host has no connection to ${side}.`);
+        let made = clients.get(side);
+        if (!made) {
+            made = createSideClient(side, config);
+            clients.set(side, made);
+        }
+        return made;
+    };
+    return {
+        fetchMeritConnections: async (side, options) => client(side).fetchMeritConnections(options),
+        requestAccounts: async (side) => client(side).requestAccounts(),
+        /** Connect this wallet to the other: its own Connect page (Cancel / Connect), no accounts. */
+        requestConnection: async (side) => client(side).requestConnection(),
+        handshake: async (side, options) => client(side).handshake(options),
+        revoke: async (side) => client(side).revoke(),
+        /** Connect or disconnect ONE account from this wallet (a disconnected account stays in the list). */
+        setAccountConnected: async (side, address, connected) => client(side).setAccountConnected(address, connected),
+        /** Remove ONE account of the other wallet from this wallet's list (the other wallet is told to disconnect it first and keeps the account). */
+        forgetAccount: async (side, address) => client(side).forgetAccount(address),
+        /** The accounts as this wallet lists them, each connected or disconnected. */
+        listAccounts: async (side) => client(side).listAccounts(),
+        /** The link to that side came up or went down: the host re-runs its list load (which runs the handshake). */
+        onConnectionChange: (side, listener) => {
+            const config = sides[side];
+            if (!config)
+                throw new MeritConnectError(ERROR.UNAVAILABLE, `This host has no connection to ${side}.`);
+            return config.subscribeLink(listener);
+        },
+    };
+}

package/dist/connection.d.ts

@@ -0,0 +1,47 @@
+import { type TraceFn } from './trace.js';
+export type ConnectionState = 'connected' | 'detached' | 'page-silent' | 'no-page' | 'unknown';
+export interface ProbeResult {
+    /** Pages of the other wallet that answered. */
+    reporting: number;
+    /** Open pages that could be the other wallet but did NOT answer. */
+    candidates: number;
+    /** The answering page's wallet is logged on. */
+    loggedOn: boolean;
+}
+export interface ConnectionStatus {
+    state: ConnectionState;
+    /** state === 'connected' */
+    connected: boolean;
+    /** A sentence for the person: what is wrong and what to do (or that all is well). */
+    reason: string;
+    loggedOn: boolean;
+    reporting: number;
+    candidates: number;
+    detached: boolean;
+    /** When this status was worked out. */
+    at: number;
+}
+export interface ConnectionMonitorDeps {
+    /** One round trip. undefined = it could not be asked. */
+    probe(): Promise<ProbeResult | undefined>;
+    /** The person's own choice to disconnect (kept by the host). */
+    isDetached(): boolean;
+    setTimer(fn: () => void, ms: number): unknown;
+    clearTimer(handle: unknown): void;
+    now(): number;
+    /** How the other wallet is called in the sentences (default "Merit web app"). */
+    label?: string;
+    trace?: TraceFn;
+}
+export declare const CONNECT_WAIT_MS = 15000;
+export declare const CONNECT_POLL_MS = 2000;
+export declare function describeConnection(state: ConnectionState, label: string): string;
+export declare function createConnectionMonitor(deps: ConnectionMonitorDeps): {
+    getSnapshot: () => ConnectionStatus;
+    subscribe: (listener: () => void) => () => void;
+    refresh: () => Promise<ConnectionStatus>;
+    /** The host's own state changed (the person disconnected or connected): re-derive without asking. */
+    recompute: () => ConnectionStatus;
+    waitForConnected: (timeoutMs?: number, pollMs?: number) => Promise<ConnectionStatus>;
+};
+export type ConnectionMonitor = ReturnType<typeof createConnectionMonitor>;