@estiva-app/platform 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# @estiva-app/platform
+
+## 0.1.0
+
+First release. The plumbing a second consumer of the live socket needs, taken
+out of `peek-app/src/nostr/liveTopics.ts` and refactored to take its
+environment injected rather than relocated — ADR 0002 §10 scores that file ❌
+on constraint 1 and ❌ on constraint 2, so a `git mv` was never available.
+
+- `createLiveClient` / `createLiveClientHolder` — one socket per tab, the
+  credential read per connect, and the network coming back. The holder is a
+  mechanism; the single module binding stays in the app.
+- `watchFolders` — a whole workspace in one REQ per 128 Folders, reporting
+  which Folder changed rather than what changed. This is the capability the
+  second consumer forced: `createChannelSubscriptions` is one REQ per channel,
+  which a 34-Folder workspace pays on every connect and reconnect against a
+  budget that refuses the 51st unpaced REQ.
+- `createFolderActivity` — from Peek's `foreignActivity.ts`, which was already
+  written as a factory for this reason and came over unchanged in substance.
+  Renamed because "foreign" was Peek's framing: a workspace reader watching its
+  own Folders is in the same position mechanically.
+- `browserOnlineSource` / `assumeOnline` — `navigator.onLine` and the two window
+  events as an injected source, so nothing here touches a global at module
+  scope and the suite runs with no DOM.
+
+`liveProjection.ts` and `freshness.ts` stayed in Peek on purpose: the first is
+Convex-shaped, the second is product voice.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Estiva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @estiva-app/platform
+
+The browser lifecycle two Estiva apps share.
+
+`@estiva-app/protocol` owns the wire — event construction, ids, signatures, and
+the two relay clients — and deliberately contains no fold. This package sits
+above it and holds the things that are about **running in a tab**: the one
+socket a tab should have, its credential read on every connect, and the network
+coming back.
+
+```bash
+npm install @estiva-app/platform
+```
+
+`@estiva-app/protocol` is a peer dependency.
+
+## Why it exists
+
+`createLiveRelay` and `createChannelSubscriptions` were extracted into
+`protocol` with a single caller, and the plumbing a *second* app needs never
+moved with them. It stayed in `peek-app/src/nostr/liveTopics.ts`, which
+[ADR 0002](https://github.com/estiva-app/estiva-docs/blob/main/decisions/0002-foundation-packages.md)
+§10 scores ❌ on constraint 1 (imports) and ❌ on constraint 2
+(environment injected), and calls "the bill SHA-7 is paying".
+
+Three behaviours, each of which fails as a healthy-looking socket that delivers
+nothing:
+
+- **One instance per tab.** `max_subscriptions` is per connection and the relay
+  authenticates a connection once, so a connection per component mount is wrong
+  rather than merely wasteful. React StrictMode makes it concrete: anything
+  owned by an effect is built twice.
+- **The credential read per connect, never captured.** A token captured at
+  module load survives a silent renewal as a dead credential, and a reconnect
+  then signs its `22242` with it.
+- **The network coming back.** Reconnection is driven by `onclose`, and a
+  socket whose peer became unreachable stays `OPEN` until TCP gives up. Without
+  an `online`/`offline` signal it reports `live`, delivers nothing, and never
+  retries.
+
+## Usage
+
+```ts
+import {
+  browserOnlineSource,
+  createLiveClientHolder,
+} from '@estiva-app/platform'
+
+// The app holds the one module-scope binding. This package holds none — that
+// is the constraint-2 failure it exists to stop repeating.
+const holder = createLiveClientHolder()
+
+export function liveClient() {
+  return holder.get({
+    relayUrl: RELAY_URL,
+    // Read fresh on every connect attempt.
+    getCredential: () => {
+      const token = validToken()
+      return token && { accessToken: token.accessToken, pubkey: token.pubkey }
+    },
+    sign: signViaEstivaId,
+    online: browserOnlineSource(window),
+    subscriptionPrefix: 'my-app-',
+    // Told what happened, never asked what to do — your freshness model stays
+    // yours.
+    observe: { onState: recordRelayState, onOnline: recordOnline },
+  })
+}
+```
+
+### Watching one channel, or a whole workspace
+
+Two paths, and the difference is a cost rather than a preference.
+
+```ts
+// Per channel, refcounted: one REQ each, every consumer sees every event.
+// What a message projection wants.
+client.subscriptions.subscribe(channelUuid, (event) => project(event))
+
+// A whole workspace in one REQ per 128 Folders. You are told which Folder
+// changed, never what changed.
+client.watchFolders(folderIds, (folder) => refresh(folder), { kinds: [9, 1111] })
+```
+
+`REQ` is a client→server frame, so it is metered on the relay's
+`LimitType::WsEvents`. Measured against production: **50 unpaced REQs are
+accepted and the 51st is refused** `rate-limited: quota exceeded`. So a
+34-Folder workspace on the per-channel path spends 34 frames on every connect
+*and every reconnect*; `watchFolders` spends one.
+
+Holding subscriptions, by contrast, costs nothing measurable — the probe round
+trip was 44.2 ms whether 1, 34 or 100 were open.
+
+### One thing to know before relying on `watchFolders`
+
+The wide filter is measured, not assumed: one filter carrying 34 `#h` delivered
+34 of 34 live against `wss://estiva.estiva.app`.
+
+It is also a property of the **deployed relay branch**. `nfb-demo-kinds` carries
+a plural `extract_channel_ids_from_filters` that returns the whole channel set;
+on `origin/main`'s singular version the same filter registers as a *global*
+subscription, and `fan_out_scoped` branches on the event's `channel_id` and
+never consults it for anything carrying an `h`. That build delivers **0 of 34,
+with no error at all** — EOSE, `live`, silence.
+
+So anything depending on this should be able to answer *"did an event I did not
+publish actually arrive?"*, because nothing else distinguishes the two cases.
+Pass `kinds` while you are at it: a kindless wide filter was refused outright on
+that other build with `restricted: p-gated events require #p matching your
+pubkey`.
+
+## What this deliberately does not know
+
+Where anything is stored. Peek's version took a `LiveProjectionApi`, and
+extracting that as-is would have baked a Convex assumption into a package two
+apps depend on. This delivers frames and connection state and nothing else, so
+it bets on neither outcome of "do we need Convex": if Convex stays nothing here
+changes, and if it goes this is already right.
+
+Your freshness states and their copy are product voice and stay in your app.
+`observe` is how they get what they need.
+
+## License
+
+MIT

package/dist/folder-activity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * "Something changed in this Folder" — a notification, not an event.
+ *
+ * Arrived in Peek as `foreignActivity.ts`, whose header already anticipated
+ * this move: *"A module-level emitter is what `liveTopics.ts` did, and SHA-7 is
+ * the bill for it. This exports a factory; the app instantiates one and passes
+ * it in, and a test makes its own."* It came over unchanged in substance.
+ *
+ * ## Why it carries no event
+ *
+ * Peek does not store other apps' records and should not start — Convex holds
+ * Peek's things, the relay holds the shared ones (ADR 0001). The panel reads
+ * those records off the relay directly, so the useful signal is *"re-read
+ * now"*, not the bytes.
+ *
+ * That also keeps it correct for kinds nobody has invented yet. A fourth app
+ * publishing its own records into a shared Folder gets a live panel without any
+ * reader learning what those records are.
+ *
+ * ## The rename
+ *
+ * "Foreign" was Peek's framing: the records belonged to another app. A workspace
+ * reader watching its own Folders is in the same position mechanically and the
+ * word stops fitting, so the shared name is about the Folder rather than about
+ * whose records are in it.
+ */
+export type FolderListener = () => void;
+export interface FolderActivity {
+    /** Say that something changed in `folder`. Safe for a folder nobody watches. */
+    notify(folder: string): void;
+    /** Watch one folder. Returns an unsubscribe; calling it twice is harmless. */
+    watch(folder: string, listener: FolderListener): () => void;
+    /** Folders with at least one listener. Test and diagnostic seam. */
+    watched(): string[];
+}
+export declare function createFolderActivity(): FolderActivity;
+//# sourceMappingURL=folder-activity.d.ts.map

package/dist/folder-activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-activity.d.ts","sourceRoot":"","sources":["../src/folder-activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,IAAI,CAAA;AAEvC,MAAM,WAAW,cAAc;IAC7B,gFAAgF;IAChF,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,8EAA8E;IAC9E,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,MAAM,IAAI,CAAA;IAC3D,oEAAoE;IACpE,OAAO,IAAI,MAAM,EAAE,CAAA;CACpB;AAED,wBAAgB,oBAAoB,IAAI,cAAc,CA8BrD"}

package/dist/folder-activity.js

@@ -0,0 +1,35 @@
+export function createFolderActivity() {
+    const listeners = new Map();
+    return {
+        notify(folder) {
+            for (const listener of listeners.get(folder) ?? []) {
+                // One bad listener must not stop the others, and must not surface
+                // somewhere unrelated as a relay error.
+                try {
+                    listener();
+                }
+                catch {
+                    /* a listener's own problem */
+                }
+            }
+        },
+        watch(folder, listener) {
+            let forFolder = listeners.get(folder);
+            if (!forFolder) {
+                forFolder = new Set();
+                listeners.set(folder, forFolder);
+            }
+            forFolder.add(listener);
+            return () => {
+                const current = listeners.get(folder);
+                if (!current)
+                    return;
+                current.delete(listener);
+                if (current.size === 0)
+                    listeners.delete(folder);
+            };
+        },
+        watched: () => [...listeners.keys()],
+    };
+}
+//# sourceMappingURL=folder-activity.js.map

package/dist/folder-activity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folder-activity.js","sourceRoot":"","sources":["../src/folder-activity.ts"],"names":[],"mappings":"AAqCA,MAAM,UAAU,oBAAoB;IAClC,MAAM,SAAS,GAAG,IAAI,GAAG,EAA+B,CAAA;IACxD,OAAO;QACL,MAAM,CAAC,MAAM;YACX,KAAK,MAAM,QAAQ,IAAI,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;gBACnD,kEAAkE;gBAClE,wCAAwC;gBACxC,IAAI,CAAC;oBACH,QAAQ,EAAE,CAAA;gBACZ,CAAC;gBAAC,MAAM,CAAC;oBACP,8BAA8B;gBAChC,CAAC;YACH,CAAC;QACH,CAAC;QACD,KAAK,CAAC,MAAM,EAAE,QAAQ;YACpB,IAAI,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;YACrC,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,SAAS,GAAG,IAAI,GAAG,EAAE,CAAA;gBACrB,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;YAClC,CAAC;YACD,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACvB,OAAO,GAAG,EAAE;gBACV,MAAM,OAAO,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;gBACrC,IAAI,CAAC,OAAO;oBAAE,OAAM;gBACpB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;gBACxB,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;oBAAE,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;YAClD,CAAC,CAAA;QACH,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;KACrC,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@estiva-app/platform` — the browser lifecycle two Estiva apps share.
+ *
+ * Not the wire: `@estiva-app/protocol` owns event construction, ids, signatures
+ * and the two relay clients, and deliberately contains no fold. This package
+ * sits above it and holds the things that are about *running in a tab* — the
+ * one socket a tab should have, the credential read per connect, the network
+ * coming back, and (SHA-2) the PWA's manifest, service worker and update flow.
+ *
+ * ## The rule this package is here to keep
+ *
+ * ADR 0002 §10's four constraints, and the two that `liveTopics.ts` failed:
+ * nothing here imports an app's data layer, store or config, and every
+ * environment touch is an injected parameter rather than a module-level global.
+ * That is why {@link browserOnlineSource} takes its window and
+ * {@link createLiveClientHolder} hands the app a holder instead of keeping one.
+ *
+ * A module-level singleton is usually holding something it reached for rather
+ * than received, and the two failures arrive together.
+ */
+export { MAX_FOLDERS_PER_SUBSCRIPTION, createLiveClient, createLiveClientHolder, type FolderWatch, type LiveClient, type LiveClientHolder, type LiveClientObservers, type LiveClientOptions, } from './live-client.js';
+export { createFolderActivity, type FolderActivity, type FolderListener, } from './folder-activity.js';
+export { assumeOnline, browserOnlineSource, type OnlineSource, type OnlineTarget } from './online.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * `@estiva-app/platform` — the browser lifecycle two Estiva apps share.
+ *
+ * Not the wire: `@estiva-app/protocol` owns event construction, ids, signatures
+ * and the two relay clients, and deliberately contains no fold. This package
+ * sits above it and holds the things that are about *running in a tab* — the
+ * one socket a tab should have, the credential read per connect, the network
+ * coming back, and (SHA-2) the PWA's manifest, service worker and update flow.
+ *
+ * ## The rule this package is here to keep
+ *
+ * ADR 0002 §10's four constraints, and the two that `liveTopics.ts` failed:
+ * nothing here imports an app's data layer, store or config, and every
+ * environment touch is an injected parameter rather than a module-level global.
+ * That is why {@link browserOnlineSource} takes its window and
+ * {@link createLiveClientHolder} hands the app a holder instead of keeping one.
+ *
+ * A module-level singleton is usually holding something it reached for rather
+ * than received, and the two failures arrive together.
+ */
+export { MAX_FOLDERS_PER_SUBSCRIPTION, createLiveClient, createLiveClientHolder, } from './live-client.js';
+export { createFolderActivity, } from './folder-activity.js';
+export { assumeOnline, browserOnlineSource } from './online.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,sBAAsB,GAMvB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,oBAAoB,GAGrB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAwC,MAAM,aAAa,CAAA"}

package/dist/live-client.d.ts

@@ -0,0 +1,168 @@
+/**
+ * One live relay socket per tab, with its environment injected.
+ *
+ * `@estiva-app/protocol` owns the wire: {@link createLiveRelay} is the socket
+ * and NIP-42 AUTH, {@link createChannelSubscriptions} is per-channel
+ * refcounting. Neither of them ever left Peek's building, because the *plumbing*
+ * around them did not move — `peek-app/src/nostr/liveTopics.ts` held a
+ * module-level singleton, imported the app's credential provider, and reached
+ * for `window`. ADR 0002 §10 scores that file ❌ on constraint 1 and ❌ on
+ * constraint 2, and calls it "the bill SHA-7 is paying".
+ *
+ * This is that bill paid. The three behaviours are here; none of them reaches
+ * for anything.
+ *
+ * 1. **One instance per tab.** `max_subscriptions` is per connection and the
+ *    relay authenticates a connection once, so a connection per component mount
+ *    is wrong rather than merely wasteful — and React StrictMode makes it
+ *    concrete, mounting everything twice. The mechanism is
+ *    {@link createLiveClientHolder}; the single module binding stays in the app,
+ *    because a module-level global *here* is the constraint-2 failure this
+ *    package exists to stop repeating.
+ * 2. **The credential is read per connect, never captured.** A token captured
+ *    at module load survives a silent renewal as a dead credential, and a
+ *    reconnect then signs its `22242` with it. `getCredential` is called on
+ *    every connect attempt — that is `createLiveRelay`'s contract, and this
+ *    passes it straight through rather than wrapping it.
+ * 3. **Network return drives a reconnect.** See {@link OnlineSource}.
+ *
+ * ## What this deliberately does not know
+ *
+ * Where anything is stored. Peek's `liveTopics.ts` took a `LiveProjectionApi`,
+ * and extracting that as-is would have baked a Convex assumption into a package
+ * two apps depend on — the "package shaped like one app" failure. So this
+ * delivers frames and connection state and nothing else, and the Convex-shaped
+ * projection stays in Peek. It also bets on neither outcome of "do we need
+ * Convex": if Convex stays nothing here changes, and if it goes this is already
+ * right.
+ */
+import { type ChannelSubscriptions, type LiveRelay, type LiveRelayOptions, type RelayCredential, type RelayState, type SignedEvent, type UnsignedEvent } from '@estiva-app/protocol';
+import { type FolderListener } from './folder-activity.js';
+import { type OnlineSource } from './online.js';
+/**
+ * The relay's aggregate `#h` budget for one REQ, COUNT, `/query` or `/count`.
+ *
+ * `MAX_EXPLICIT_CHANNEL_VALUES` in `buzz-relay/src/handlers/req.rs`: "Explicit
+ * channels may each require an uncached membership lookup and, for a live WS
+ * subscription, a registry entry plus Redis topic retain." Exceeding it is
+ * refused, so {@link LiveClient.watchFolders} chunks rather than hoping.
+ */
+export declare const MAX_FOLDERS_PER_SUBSCRIPTION = 128;
+/**
+ * Told what happened, never asked what to do.
+ *
+ * Peek's freshness model — four states and the copy that goes with them — is
+ * product voice and stays in Peek. These are the observations it needs, so the
+ * app can derive its own states without this package holding any of them.
+ */
+export interface LiveClientObservers {
+    onState?(state: RelayState): void;
+    onOnline?(online: boolean): void;
+    /** No credential at all. Not yet "signed out" — a silent renewal passes through here. */
+    onCredentialMissing?(): void;
+    onSignOk?(): void;
+    onSignFailure?(error: unknown): void;
+}
+export interface LiveClientOptions {
+    /** `https://…` or `wss://…`. Where it comes from is the app's decision. */
+    relayUrl: string;
+    /** Read fresh on every connect attempt, so a reconnect picks up a renewal. */
+    getCredential(): RelayCredential | null;
+    /**
+     * Injected so nothing here fetches. Peek passes `signViaEstivaId`; a keyed
+     * client passes a `signEvent` wrapper, and must set `unsigned.pubkey` itself
+     * because `createLiveRelay` leaves it empty for a remote `/sign` to fill.
+     */
+    sign(unsigned: UnsignedEvent, token: string, expectedPubkey: string): Promise<SignedEvent>;
+    /** Defaults to {@link assumeOnline} — a package that assumed a browser would be wrong. */
+    online?: OnlineSource;
+    observe?: LiveClientObservers;
+    /** Appears in the relay operator's logs and nowhere else. Name your app. */
+    subscriptionPrefix?: string;
+    /** Never receives event bodies or credentials. */
+    log?(message: string, detail?: Record<string, unknown>): void;
+    /** Test seams, passed through untouched. */
+    socketFactory?: LiveRelayOptions['socketFactory'];
+    now?: LiveRelayOptions['now'];
+    setTimer?: LiveRelayOptions['setTimer'];
+    clearTimer?: LiveRelayOptions['clearTimer'];
+    backoff?: LiveRelayOptions['backoff'];
+}
+export interface FolderWatch {
+    /** Idempotent. Closes the REQs and forgets the listeners. */
+    stop(): void;
+}
+export interface LiveClient {
+    /** The socket. Exposed because an app with one subscription needs no more than this. */
+    readonly relay: LiveRelay;
+    /**
+     * Per-channel and refcounted: one REQ per channel, every consumer sees every
+     * event. What a message projection wants, and what Peek uses.
+     */
+    readonly subscriptions: ChannelSubscriptions;
+    state(): RelayState;
+    onState(listener: (state: RelayState) => void): () => void;
+    /**
+     * Watch a whole workspace with **one REQ per 128 Folders**, and be told which
+     * Folder changed rather than what changed.
+     *
+     * This is the capability a second consumer forced, and it is worth saying why
+     * {@link subscriptions} is not it: that path is one REQ per channel, so a
+     * 34-Folder workspace spends 34 client→server frames on every connect and
+     * every reconnect. `REQ` is metered on `LimitType::WsEvents`, and 50 unpaced
+     * REQs are accepted before the 51st is refused `rate-limited: quota
+     * exceeded` — measured against production, LIV-1. A wide filter spends one.
+     *
+     * The wide filter is measured, not assumed: one filter carrying 34 `#h`
+     * delivered 34 of 34 live against `wss://estiva.estiva.app`. It is also a
+     * property of the *deployed relay branch* — `nfb-demo-kinds` carries the
+     * plural `extract_channel_ids_from_filters`, and on `origin/main`'s singular
+     * version the same filter files as a global subscription and `fan_out_scoped`
+     * never consults it for an event carrying an `h`. That build delivers 0 of 34
+     * with no error at all: EOSE, `live`, silence. Anything relying on this should
+     * be able to answer "did an event I did not publish arrive", because nothing
+     * else distinguishes the two.
+     *
+     * `kinds` is strongly recommended rather than optional-by-taste: a kindless
+     * wide filter was refused outright on that other build with `restricted:
+     * p-gated events require #p matching your pubkey`.
+     */
+    watchFolders(folders: string[], listener: (folder: string) => void, options?: {
+        kinds?: number[];
+    }): FolderWatch;
+    /** Watch one Folder by name. The refcounted half of {@link watchFolders}. */
+    onFolderActivity(folder: string, listener: FolderListener): () => void;
+    /** Release everything and stop reconnecting. */
+    close(): void;
+}
+export declare function createLiveClient(options: LiveClientOptions): LiveClient;
+export interface LiveClientHolder {
+    /**
+     * The tab's client, built on first use.
+     *
+     * A changed relay origin means a different deployment, so the old client is
+     * torn down rather than left pointed at it. Not expected in a page's lifetime.
+     */
+    get(options: LiveClientOptions): LiveClient;
+    /**
+     * The client if one exists, without building it.
+     *
+     * A consumer that only wants to listen has no business holding whatever the
+     * builder needed — in Peek's case the Convex actions, which would otherwise
+     * appear in the dependency list of a component that reads the relay directly.
+     * `null` before anything has connected is a real state, not an error: the
+     * caller falls back to its timer.
+     */
+    peek(): LiveClient | null;
+    /** Drops the instance so the next `get` builds a new one. Test seam. */
+    reset(): void;
+}
+/**
+ * Somewhere to keep the one client, without this package keeping it.
+ *
+ * The app holds the single module-scope binding — `const holder =
+ * createLiveClientHolder()` — which is the one place a per-tab singleton can
+ * live without making the package un-instantiable twice.
+ */
+export declare function createLiveClientHolder(): LiveClientHolder;
+//# sourceMappingURL=live-client.d.ts.map

package/dist/live-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-client.d.ts","sourceRoot":"","sources":["../src/live-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAA6C,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrG,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAE7D;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,MAAM,CAAA;AAE/C;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAA;IAChC,yFAAyF;IACzF,mBAAmB,CAAC,IAAI,IAAI,CAAA;IAC5B,QAAQ,CAAC,IAAI,IAAI,CAAA;IACjB,aAAa,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAA;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAA;IAChB,8EAA8E;IAC9E,aAAa,IAAI,eAAe,GAAG,IAAI,CAAA;IACvC;;;;OAIG;IACH,IAAI,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC1F,0FAA0F;IAC1F,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,OAAO,CAAC,EAAE,mBAAmB,CAAA;IAC7B,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,MAAM,CAAA;IAC3B,kDAAkD;IAClD,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAA;IAC7D,4CAA4C;IAC5C,aAAa,CAAC,EAAE,gBAAgB,CAAC,eAAe,CAAC,CAAA;IACjD,GAAG,CAAC,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAA;IAC7B,QAAQ,CAAC,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAA;IACvC,UAAU,CAAC,EAAE,gBAAgB,CAAC,YAAY,CAAC,CAAA;IAC3C,OAAO,CAAC,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAA;CACtC;AAED,MAAM,WAAW,WAAW;IAC1B,6DAA6D;IAC7D,IAAI,IAAI,IAAI,CAAA;CACb;AAED,MAAM,WAAW,UAAU;IACzB,wFAAwF;IACxF,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,oBAAoB,CAAA;IAC5C,KAAK,IAAI,UAAU,CAAA;IACnB,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAC1D;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,YAAY,CACV,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,EAClC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC7B,WAAW,CAAA;IACd,6EAA6E;IAC7E,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,MAAM,IAAI,CAAA;IACtE,gDAAgD;IAChD,KAAK,IAAI,IAAI,CAAA;CACd;AA8BD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAgGvE;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,GAAG,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAAA;IAC3C;;;;;;;;OAQG;IACH,IAAI,IAAI,UAAU,GAAG,IAAI,CAAA;IACzB,wEAAwE;IACxE,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,gBAAgB,CAezD"}