@estiva-app/platform 0.1.0

package/dist/live-client.js

@@ -0,0 +1,195 @@
+/**
+ * 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 { createChannelSubscriptions, createLiveRelay, } from '@estiva-app/protocol';
+import { createFolderActivity } from './folder-activity.js';
+import { assumeOnline } 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 const MAX_FOLDERS_PER_SUBSCRIPTION = 128;
+/**
+ * Call an app's observer without letting it break the socket.
+ *
+ * These are the app's callbacks — Peek's `freshness.ts` recorders — and they run
+ * on the connect, sign and state paths. One of them throwing used to be able to
+ * skip the `relay.reconnect()` on the line after it, which leaves a socket
+ * reporting `live` and delivering nothing: the exact failure the online source
+ * exists to prevent, reintroduced by the thing observing it.
+ */
+function safely(run) {
+    try {
+        run();
+    }
+    catch {
+        /* an observer's own problem; never the socket's */
+    }
+}
+/** The `h` tag is the Folder — RFC 0.4 §5.2, measured across all production channels. */
+function folderOf(event) {
+    return event.tags.find((tag) => tag[0] === 'h')?.[1];
+}
+function chunk(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+export function createLiveClient(options) {
+    const stateListeners = new Set();
+    const activity = createFolderActivity();
+    const online = options.online ?? assumeOnline();
+    let state = 'connecting';
+    const relay = createLiveRelay({
+        url: options.relayUrl,
+        getCredential: () => {
+            const credential = options.getCredential();
+            if (!credential) {
+                safely(() => options.observe?.onCredentialMissing?.());
+                return null;
+            }
+            return credential;
+        },
+        sign: async (unsigned, token, expectedPubkey) => {
+            try {
+                const signed = await options.sign(unsigned, token, expectedPubkey);
+                safely(() => options.observe?.onSignOk?.());
+                return signed;
+            }
+            catch (error) {
+                // The status is the honest signal, and "expired" versus "this app
+                // cannot verify the token" decides whether sending somebody to sign in
+                // again helps or wastes their time.
+                safely(() => options.observe?.onSignFailure?.(error));
+                throw error;
+            }
+        },
+        onState: (next) => {
+            state = next;
+            safely(() => options.observe?.onState?.(next));
+            for (const listener of [...stateListeners])
+                safely(() => listener(next));
+        },
+        subscriptionPrefix: options.subscriptionPrefix,
+        log: options.log,
+        socketFactory: options.socketFactory,
+        now: options.now,
+        setTimer: options.setTimer,
+        clearTimer: options.clearTimer,
+        backoff: options.backoff,
+    });
+    const subscriptions = createChannelSubscriptions(relay, {
+        onListenerError: (error) => options.log?.('a channel listener threw', { error: String(error) }),
+    });
+    safely(() => options.observe?.onOnline?.(online.online()));
+    const releaseOnline = online.subscribe((isOnline) => {
+        safely(() => options.observe?.onOnline?.(isOnline));
+        // `offline` drops the socket so the reported state becomes honest at once;
+        // `online` retries immediately rather than waiting out a backoff that may
+        // have grown to half a minute while there was no network to reach.
+        relay.reconnect();
+    });
+    return {
+        relay,
+        subscriptions,
+        state: () => state,
+        onState(listener) {
+            stateListeners.add(listener);
+            return () => stateListeners.delete(listener);
+        },
+        onFolderActivity: (folder, listener) => activity.watch(folder, listener),
+        watchFolders(folders, listener, watchOptions) {
+            const unwatch = folders.map((folder) => activity.watch(folder, () => listener(folder)));
+            const subs = chunk([...new Set(folders)], MAX_FOLDERS_PER_SUBSCRIPTION).map((group) => relay.subscribe([{ ...(watchOptions?.kinds ? { kinds: watchOptions.kinds } : {}), '#h': group }], (event) => {
+                const folder = folderOf(event);
+                if (folder)
+                    activity.notify(folder);
+            }, {
+                onClosed: (reason) => options.log?.('folder subscription closed', { reason }),
+            }));
+            let stopped = false;
+            return {
+                stop() {
+                    if (stopped)
+                        return;
+                    stopped = true;
+                    for (const sub of subs)
+                        sub.close();
+                    for (const release of unwatch)
+                        release();
+                },
+            };
+        },
+        close() {
+            releaseOnline();
+            subscriptions.close();
+            relay.close();
+            stateListeners.clear();
+        },
+    };
+}
+/**
+ * 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 function createLiveClientHolder() {
+    let current = null;
+    return {
+        get(options) {
+            if (current && current.relayUrl === options.relayUrl)
+                return current.client;
+            current?.client.close();
+            current = { relayUrl: options.relayUrl, client: createLiveClient(options) };
+            return current.client;
+        },
+        peek: () => current?.client ?? null,
+        reset() {
+            current?.client.close();
+            current = null;
+        },
+    };
+}
+//# sourceMappingURL=live-client.js.map

package/dist/live-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-client.js","sourceRoot":"","sources":["../src/live-client.ts"],"names":[],"mappings":"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"}

package/dist/online.d.ts

@@ -0,0 +1,49 @@
+/**
+ * "Is the network believed reachable?", as an injected dependency.
+ *
+ * A socket cannot notice the network coming back on its own. Reconnection is
+ * driven by `onclose`, and a connection whose peer became unreachable stays
+ * `OPEN` until TCP gives up — which can be minutes, and browser devtools'
+ * offline mode frequently never closes it at all. So the socket sits reporting
+ * `live`, delivering nothing, and never reconnects.
+ *
+ * Peek solved that with `window.addEventListener('offline', …)` inside the
+ * module that owned its relay. That is the second of the four extractability
+ * constraints failed (ADR 0002 §10): an environment touch reached for rather
+ * than received, which makes the module un-instantiable twice and untestable
+ * without a browser.
+ *
+ * Hence an interface. {@link browserOnlineSource} is the browser
+ * implementation, and it takes its window as an argument — so nothing in this
+ * package touches a global at module scope, and a test supplies a fake.
+ */
+/** What this package needs of `window`. Deliberately tiny. */
+export interface OnlineTarget {
+    navigator: {
+        onLine: boolean;
+    };
+    addEventListener(type: 'online' | 'offline', listener: () => void): void;
+    removeEventListener(type: 'online' | 'offline', listener: () => void): void;
+}
+export interface OnlineSource {
+    /** The current belief. */
+    online(): boolean;
+    /** Called on every change. Returns an unsubscribe; calling it twice is harmless. */
+    subscribe(listener: (online: boolean) => void): () => void;
+}
+/**
+ * `navigator.onLine` and the two window events, as a source.
+ *
+ * The events are the one authority here a socket cannot second-guess, which is
+ * why this exists at all rather than a timer.
+ */
+export declare function browserOnlineSource(target: OnlineTarget): OnlineSource;
+/**
+ * Always online, and never changes.
+ *
+ * For a consumer with no `window` — a Node probe, the agent, a server-side
+ * test. Not a stub: "this environment has no opinion" is a real answer, and it
+ * is better than a package that assumes a browser.
+ */
+export declare function assumeOnline(): OnlineSource;
+//# sourceMappingURL=online.d.ts.map

package/dist/online.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"online.d.ts","sourceRoot":"","sources":["../src/online.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAA;IAC9B,gBAAgB,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;IACxE,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;CAC5E;AAED,MAAM,WAAW,YAAY;IAC3B,0BAA0B;IAC1B,MAAM,IAAI,OAAO,CAAA;IACjB,oFAAoF;IACpF,SAAS,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CAC3D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,YAAY,CAwCtE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,YAAY,CAE3C"}

package/dist/online.js

@@ -0,0 +1,76 @@
+/**
+ * "Is the network believed reachable?", as an injected dependency.
+ *
+ * A socket cannot notice the network coming back on its own. Reconnection is
+ * driven by `onclose`, and a connection whose peer became unreachable stays
+ * `OPEN` until TCP gives up — which can be minutes, and browser devtools'
+ * offline mode frequently never closes it at all. So the socket sits reporting
+ * `live`, delivering nothing, and never reconnects.
+ *
+ * Peek solved that with `window.addEventListener('offline', …)` inside the
+ * module that owned its relay. That is the second of the four extractability
+ * constraints failed (ADR 0002 §10): an environment touch reached for rather
+ * than received, which makes the module un-instantiable twice and untestable
+ * without a browser.
+ *
+ * Hence an interface. {@link browserOnlineSource} is the browser
+ * implementation, and it takes its window as an argument — so nothing in this
+ * package touches a global at module scope, and a test supplies a fake.
+ */
+/**
+ * `navigator.onLine` and the two window events, as a source.
+ *
+ * The events are the one authority here a socket cannot second-guess, which is
+ * why this exists at all rather than a timer.
+ */
+export function browserOnlineSource(target) {
+    const listeners = new Set();
+    let attached = false;
+    const announce = (online) => {
+        for (const listener of [...listeners]) {
+            // Isolated, for the same reason `folder-activity` isolates its own: the
+            // most important subscriber here is the one that reconnects the socket,
+            // and one app listener throwing must not be what stops it running.
+            try {
+                listener(online);
+            }
+            catch {
+                /* a listener's own problem */
+            }
+        }
+    };
+    const onOnline = () => announce(true);
+    const onOffline = () => announce(false);
+    return {
+        online: () => target.navigator.onLine,
+        subscribe(listener) {
+            listeners.add(listener);
+            if (!attached) {
+                // Attached on first use and never in module scope, so importing this
+                // package registers nothing.
+                target.addEventListener('online', onOnline);
+                target.addEventListener('offline', onOffline);
+                attached = true;
+            }
+            return () => {
+                listeners.delete(listener);
+                if (listeners.size === 0 && attached) {
+                    target.removeEventListener('online', onOnline);
+                    target.removeEventListener('offline', onOffline);
+                    attached = false;
+                }
+            };
+        },
+    };
+}
+/**
+ * Always online, and never changes.
+ *
+ * For a consumer with no `window` — a Node probe, the agent, a server-side
+ * test. Not a stub: "this environment has no opinion" is a real answer, and it
+ * is better than a package that assumes a browser.
+ */
+export function assumeOnline() {
+    return { online: () => true, subscribe: () => () => { } };
+}
+//# sourceMappingURL=online.js.map

package/dist/online.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"online.js","sourceRoot":"","sources":["../src/online.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAgBH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAoB;IACtD,MAAM,SAAS,GAAG,IAAI,GAAG,EAA6B,CAAA;IACtD,IAAI,QAAQ,GAAG,KAAK,CAAA;IAEpB,MAAM,QAAQ,GAAG,CAAC,MAAe,EAAE,EAAE;QACnC,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,SAAS,CAAC,EAAE,CAAC;YACtC,wEAAwE;YACxE,wEAAwE;YACxE,mEAAmE;YACnE,IAAI,CAAC;gBACH,QAAQ,CAAC,MAAM,CAAC,CAAA;YAClB,CAAC;YAAC,MAAM,CAAC;gBACP,8BAA8B;YAChC,CAAC;QACH,CAAC;IACH,CAAC,CAAA;IACD,MAAM,QAAQ,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IACrC,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IAEvC,OAAO;QACL,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM;QACrC,SAAS,CAAC,QAAQ;YAChB,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YACvB,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,qEAAqE;gBACrE,6BAA6B;gBAC7B,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;gBAC3C,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;gBAC7C,QAAQ,GAAG,IAAI,CAAA;YACjB,CAAC;YACD,OAAO,GAAG,EAAE;gBACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAA;gBAC1B,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,IAAI,QAAQ,EAAE,CAAC;oBACrC,MAAM,CAAC,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;oBAC9C,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAA;oBAChD,QAAQ,GAAG,KAAK,CAAA;gBAClB,CAAC;YACH,CAAC,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY;IAC1B,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC,EAAE,CAAA;AAC1D,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@estiva-app/platform",
+  "version": "0.1.0",
+  "description": "Browser lifecycle two Estiva apps share: the one live relay socket a tab should hold, its credential read per connect, and the network coming back.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/estiva-app/estiva-foundation.git",
+    "directory": "packages/platform"
+  },
+  "keywords": [
+    "nostr",
+    "relay",
+    "websocket",
+    "nip-42",
+    "pwa",
+    "estiva"
+  ],
+  "scripts": {
+    "prebuild": "npm run build --workspace @estiva-app/protocol",
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/*.test.ts",
+    "typecheck": "npm run build && tsc -p tsconfig.test.json",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@estiva-app/protocol": ">=0.15.0"
+  },
+  "devDependencies": {
+    "@estiva-app/protocol": ">=0.15.0",
+    "typescript": "~5.9.3"
+  }
+}

package/src/folder-activity.ts

@@ -0,0 +1,68 @@
+/**
+ * "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 function createFolderActivity(): FolderActivity {
+  const listeners = new Map<string, Set<FolderListener>>()
+  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()],
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * `@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'