@estiva-app/platform 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @estiva-app/platform
 
+## 0.3.0
+
+When a tab re-reads, and when the relay has asked it to wait (PER-13). Additive.
+
+Ship's `useRefresh` + `relayBudget` taken out of the app, so Peek can stop
+firing every read twice per tab switch and stop retrying refused reads in a
+herd. On 2026-09-23 one person's key reached 306 requests in a minute across
+two Peek tabs and a Ship tab, against buzz's 300-per-pubkey window.
+
+- `createRefreshScheduler({ document, window, budget })` — one `focus` and one
+  `visibilitychange` listener per tab, fanned out to every subscriber. Two
+  triggers inside `mergeMs` (default 1 s) are one read, per subscriber. The
+  interval never runs in a hidden tab. Nothing runs while the budget is paused,
+  and nothing is queued for when it ends.
+- `createRelayBudget({ channel? })` — the pause the relay's `retry in N s`
+  names. Extends, never shortens. `whenClear()` resolves once it has passed.
+  Given a `BroadcastChannel`, a pause one tab learns holds in the app's others.
+- `isRateLimited`, `retryHintMs`, `DEFAULT_BACKOFF_MS`, `MIN_BACKOFF_MS`,
+  `DEFAULT_MERGE_MS`.
+
+## 0.2.0
+
+A Folder notification may carry the event that caused it (PER-8). Additive:
+every existing listener keeps compiling and behaving as before.
+
+- `watchFolders`' listener is called `(folder, event)`. The wide filter always
+  had the event in hand and dropped it, so a reader that keeps what it has read
+  — Peek's sidebar, which re-read 90 days of every Folder to learn about the one
+  message the socket had just delivered — had nothing to apply and could only
+  re-read, against a relay quota metered per HTTP request.
+- `watchFolders` takes `since`, bounding what the REQ replays on subscribe and
+  on every reconnect. Without it the relay replays up to its default limit,
+  shared across every Folder in the filter.
+- `FolderListener` is `(event?) => void` and `FolderActivity.notify` takes the
+  event. A notification with nothing to carry — another app's record moved —
+  still sends none, so a missing event means "re-read", never "nothing".
+
 ## 0.1.0
 
 First release. The plumbing a second consumer of the live socket needs, taken

package/README.md

@@ -109,6 +109,37 @@ 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`.
 
+### Refreshing, and waiting when the relay says so
+
+Buzz meters `POST /query` at 300 a minute **per pubkey**, so every tab and app
+signed in as one person shares one allowance. Build one budget and one
+scheduler per tab:
+
+```ts
+import { createRefreshScheduler, createRelayBudget } from '@estiva-app/platform'
+
+// The transport writes it; the cadence reads it.
+export const relayBudget = createRelayBudget({
+  // Optional: the app's other tabs learn a pause from this one.
+  channel: new BroadcastChannel('my-app-relay-budget'),
+})
+export const refreshScheduler = createRefreshScheduler({ document, window, budget: relayBudget })
+
+// In the transport, on every answer:
+if (status === 429 || isRateLimited(body)) relayBudget.noteRateLimited(body)
+
+// In a hook: focus, becoming visible, and every 30 s while visible. A tab
+// switch raises two events and costs one read; nothing runs while paused.
+useEffect(() => refreshScheduler.subscribe(reload, { interval: !live }), [live])
+
+// Before retrying a refused read: every waiter goes after the longest pause
+// anybody learned, not its own shorter one.
+await relayBudget.whenClear()
+```
+
+Nothing here gates a read. A read somebody asked for by clicking still goes out
+at once; only the cadence backs off.
+
 ## What this deliberately does not know
 
 Where anything is stored. Peek's version took a `LiveProjectionApi`, and

package/dist/folder-activity.d.ts

@@ -23,11 +23,26 @@
  * 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.
+ *
+ * ## …unless it has one to give (PER-8)
+ *
+ * "Re-read now" was the right signal while nobody held what they had read. Once
+ * a reader keeps the events it already has — Peek's sidebar re-read 90 days of
+ * every Folder to learn about the one message the socket had just delivered, and
+ * spent the relay's per-request HTTP quota doing it — the event is the whole
+ * point. So a notification *may* carry the event that caused it. A listener
+ * that ignores the argument is exactly the listener it was before, and a
+ * notification with nothing to carry (another app's record moved) still sends
+ * none, so a reader must treat a missing event as "re-read", not as "nothing".
  */
-export type FolderListener = () => void;
+import type { SignedEvent } from '@estiva-app/protocol';
+export type FolderListener = (event?: SignedEvent) => void;
 export interface FolderActivity {
-    /** Say that something changed in `folder`. Safe for a folder nobody watches. */
-    notify(folder: string): void;
+    /**
+     * Say that something changed in `folder`, and hand over the event when there
+     * is one. Safe for a folder nobody watches.
+     */
+    notify(folder: string, event?: SignedEvent): 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. */

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

@@ -1 +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"}
+{"version":3,"file":"folder-activity.d.ts","sourceRoot":"","sources":["../src/folder-activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAEvD,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,CAAC,EAAE,WAAW,KAAK,IAAI,CAAA;AAE1D,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CAAA;IACjD,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

@@ -1,12 +1,12 @@
 export function createFolderActivity() {
     const listeners = new Map();
     return {
-        notify(folder) {
+        notify(folder, event) {
             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();
+                    listener(event);
                 }
                 catch {
                     /* a listener's own problem */

package/dist/folder-activity.js.map

@@ -1 +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"}
+{"version":3,"file":"folder-activity.js","sourceRoot":"","sources":["../src/folder-activity.ts"],"names":[],"mappings":"AAqDA,MAAM,UAAU,oBAAoB;IAClC,MAAM,SAAS,GAAG,IAAI,GAAG,EAA+B,CAAA;IACxD,OAAO;QACL,MAAM,CAAC,MAAM,EAAE,KAAK;YAClB,KAAK,MAAM,QAAQ,IAAI,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;gBACnD,kEAAkE;gBAClE,wCAAwC;gBACxC,IAAI,CAAC;oBACH,QAAQ,CAAC,KAAK,CAAC,CAAA;gBACjB,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

@@ -5,7 +5,8 @@
  * 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.
+ * coming back, when a tab re-reads and when the relay has asked it to wait
+ * (PER-13), and (SHA-2) the PWA's manifest, service worker and update flow.
  *
  * ## The rule this package is here to keep
  *
@@ -21,4 +22,5 @@
 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';
+export { DEFAULT_BACKOFF_MS, DEFAULT_MERGE_MS, MIN_BACKOFF_MS, createRefreshScheduler, createRelayBudget, isRateLimited, retryHintMs, type BudgetChannel, type FocusTarget, type RefreshScheduler, type RefreshSchedulerOptions, type RefreshSubscription, type RelayBudget, type RelayBudgetOptions, type SchedulerClock, type VisibilityTarget, } from './refresh.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;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;AACrG,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -5,7 +5,8 @@
  * 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.
+ * coming back, when a tab re-reads and when the relay has asked it to wait
+ * (PER-13), and (SHA-2) the PWA's manifest, service worker and update flow.
  *
  * ## The rule this package is here to keep
  *
@@ -21,4 +22,5 @@
 export { MAX_FOLDERS_PER_SUBSCRIPTION, createLiveClient, createLiveClientHolder, } from './live-client.js';
 export { createFolderActivity, } from './folder-activity.js';
 export { assumeOnline, browserOnlineSource } from './online.js';
+export { DEFAULT_BACKOFF_MS, DEFAULT_MERGE_MS, MIN_BACKOFF_MS, createRefreshScheduler, createRelayBudget, isRateLimited, retryHintMs, } from './refresh.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;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;AACrG,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,aAAa,EACb,WAAW,GAUZ,MAAM,cAAc,CAAA"}

package/dist/live-client.d.ts

@@ -126,9 +126,18 @@ export interface LiveClient {
      * `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`.
+     *
+     * **The listener is handed the event** (PER-8). A reader that keeps what it
+     * has read applies it instead of re-reading the Folder; one that only wants
+     * the signal ignores the second argument. Stored events arrive as well as
+     * live ones — the REQ's replay on subscribe and on every reconnect — so a
+     * reader must be idempotent by event id. `since` bounds that replay: without
+     * it the relay replays whatever its default limit allows, shared across every
+     * Folder in the filter, which a keeping reader then has to dedupe.
      */
-    watchFolders(folders: string[], listener: (folder: string) => void, options?: {
+    watchFolders(folders: string[], listener: (folder: string, event?: SignedEvent) => void, options?: {
         kinds?: number[];
+        since?: number;
     }): FolderWatch;
     /** Watch one Folder by name. The refcounted half of {@link watchFolders}. */
     onFolderActivity(folder: string, listener: FolderListener): () => void;

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

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

package/dist/live-client.js

@@ -139,11 +139,17 @@ export function createLiveClient(options) {
         },
         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 unwatch = folders.map((folder) => activity.watch(folder, (event) => listener(folder, event)));
+            const subs = chunk([...new Set(folders)], MAX_FOLDERS_PER_SUBSCRIPTION).map((group) => relay.subscribe([
+                {
+                    ...(watchOptions?.kinds ? { kinds: watchOptions.kinds } : {}),
+                    '#h': group,
+                    ...(watchOptions?.since !== undefined ? { since: watchOptions.since } : {}),
+                },
+            ], (event) => {
                 const folder = folderOf(event);
                 if (folder)
-                    activity.notify(folder);
+                    activity.notify(folder, event);
             }, {
                 onClosed: (reason) => options.log?.('folder subscription closed', { reason }),
             }));

package/dist/live-client.js.map

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

package/dist/refresh.d.ts

@@ -0,0 +1,161 @@
+/**
+ * When a tab re-reads, and when it must not (PER-13).
+ *
+ * Buzz meters `POST /query` at **300 a minute per pubkey** — a fixed 60-second
+ * window, `human_api_calls_per_min`, applied once per HTTP call before the
+ * filters are parsed (`enforce_http_admission`, `api/bridge.rs`). Not per app
+ * and not per tab: two Peek tabs and a Ship tab signed in as one person share
+ * one allowance, and the relay is the only participant that can see all three.
+ *
+ * Ship and Peek each grew half of the answer. Ship's `useRefresh` merged the two
+ * events a tab switch raises and held off after a 429; Peek's
+ * `useRefreshTriggers` did neither, so a tab switch fired every read twice, and
+ * each refused read waited out its own hint and then retried at the same
+ * instant as every other one. Measured on production on 2026-09-23: Miky's key
+ * at 306 requests in one minute, single seconds of 40–58, and 33 refusals in
+ * one second when a whole fan-out was sent into a pause already in force.
+ *
+ * ## Two objects, both handed to the app
+ *
+ * - {@link createRelayBudget} — how long the relay has asked this tab to wait.
+ *   **The transport writes it** (it sees every 429) and everything that decides
+ *   whether to read consults it. No reader has to know about quotas.
+ * - {@link createRefreshScheduler} — one `visibilitychange` and one `focus`
+ *   listener for the whole tab, fanning out to every subscriber, each of which
+ *   still gets Ship's merge: two triggers inside `mergeMs` are one read.
+ *
+ * Neither is a module-level singleton (ADR 0002 §10 constraint 2): the app
+ * builds one of each and keeps the binding, as it does the live-client holder.
+ *
+ * ## A person's own action is not paused
+ *
+ * Nothing here gates a read. The budget is advice the *cadence* honours —
+ * scheduled refreshes skip while it is in force, and a retry waits it out — so
+ * a read somebody asked for by clicking still goes out at once. Backing off a
+ * poll costs freshness nobody asked for; backing off a click costs the thing
+ * they just did.
+ */
+/** The relay's quota refusal, as opposed to any other failure. */
+export declare function isRateLimited(text: string): boolean;
+/**
+ * The relay's own wait, in ms, or `undefined` if it did not state one.
+ *
+ * Buzz writes `rate-limited: quota exceeded; retry in 8s` (`api/bridge.rs`,
+ * `connection.rs`). Parsed rather than assumed because the number is what is
+ * left of the relay's *window*, not a fixed penalty — it shrinks as the minute
+ * rolls on, so a flat wait either spends early or idles long.
+ */
+export declare function retryHintMs(reason: string): number | undefined;
+/** How long to wait when the relay refuses without saying for how long. */
+export declare const DEFAULT_BACKOFF_MS = 30000;
+/**
+ * The floor under a stated wait. `retry in 0s` means the window has just rolled
+ * over; the read that would go out now is the one that was refused, so it still
+ * waits a moment rather than none.
+ */
+export declare const MIN_BACKOFF_MS = 1000;
+/** What the budget needs of a `BroadcastChannel`. Declared here, see `online.ts`. */
+export interface BudgetChannel {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+}
+export interface RelayBudgetOptions {
+    /** Default {@link DEFAULT_BACKOFF_MS}. */
+    defaultBackoffMs?: number;
+    /**
+     * Share pauses with the app's other tabs.
+     *
+     * Tabs of one origin signed in as one person spend one allowance, so a pause
+     * one of them learns holds for all of them. Pass a `BroadcastChannel` — the
+     * app names it — or leave it out. A tab of another app on another origin
+     * cannot be reached this way and learns its own pause from its own refusal.
+     */
+    channel?: BudgetChannel;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface RelayBudget {
+    /**
+     * Record a refusal from the relay's own words. Returns the pause in force
+     * afterwards, in ms.
+     *
+     * Extends a pause but never shortens one: two reads refused in the same
+     * second carry different remaining windows, and the second answer must not
+     * cancel the first.
+     */
+    noteRateLimited(reason: string): number;
+    /** Milliseconds left to wait, or 0. */
+    pausedForMs(): number;
+    /**
+     * Resolves once no pause is in force — immediately if none is.
+     *
+     * Loops rather than sleeping once: a pause can be extended while somebody is
+     * waiting on it, by this tab or another.
+     */
+    whenClear(): Promise<void>;
+    /** Test seam. Nothing in an app clears a pause early. */
+    reset(): void;
+    /** Detach from the channel, if one was given. */
+    close(): void;
+}
+export declare function createRelayBudget(options?: RelayBudgetOptions): RelayBudget;
+/** What the scheduler needs of `document`. */
+export interface VisibilityTarget {
+    readonly visibilityState: string;
+    addEventListener(type: 'visibilitychange', listener: () => void): void;
+    removeEventListener(type: 'visibilitychange', listener: () => void): void;
+}
+/** What the scheduler needs of `window`. */
+export interface FocusTarget {
+    addEventListener(type: 'focus', listener: () => void): void;
+    removeEventListener(type: 'focus', listener: () => void): void;
+}
+/** Timers, injected so a test can drive them. Handles are opaque. */
+export interface SchedulerClock {
+    now(): number;
+    setInterval(run: () => void, ms: number): unknown;
+    clearInterval(handle: unknown): void;
+}
+/**
+ * Two triggers inside this many ms are one read. Switching to a tab raises both
+ * `visibilitychange` and `focus`, and one read is enough for it.
+ */
+export declare const DEFAULT_MERGE_MS = 1000;
+export interface RefreshSchedulerOptions {
+    document: VisibilityTarget;
+    window: FocusTarget;
+    /** Scheduled refreshes skip while this is paused. */
+    budget?: Pick<RelayBudget, 'pausedForMs'>;
+    /** Default {@link DEFAULT_MERGE_MS}. */
+    mergeMs?: number;
+    /** A subscriber's interval when it names none. Default 30 s. */
+    intervalMs?: number;
+    clock?: SchedulerClock;
+}
+export interface RefreshSubscription {
+    /**
+     * Whether the periodic refresh runs. Default `true`.
+     *
+     * A caller with live delivery turns it off while its socket is live and keeps
+     * the focus and visibility triggers: a tab hidden for ten minutes may have had
+     * its socket dropped by the browser, and a reconnect's backfill is not
+     * instant, so re-reading when somebody looks is right either way.
+     */
+    interval?: boolean;
+    intervalMs?: number;
+}
+export interface RefreshScheduler {
+    /**
+     * Re-run `refresh` on focus, on becoming visible, and every `intervalMs`
+     * while visible. Never on subscribe — the caller owns its first read.
+     * Returns an unsubscribe; calling it twice is harmless.
+     */
+    subscribe(refresh: () => void | Promise<void>, options?: RefreshSubscription): () => void;
+}
+export declare function createRefreshScheduler(options: RefreshSchedulerOptions): RefreshScheduler;
+//# sourceMappingURL=refresh.d.ts.map

package/dist/refresh.d.ts.map

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

package/dist/refresh.js

@@ -0,0 +1,209 @@
+/**
+ * When a tab re-reads, and when it must not (PER-13).
+ *
+ * Buzz meters `POST /query` at **300 a minute per pubkey** — a fixed 60-second
+ * window, `human_api_calls_per_min`, applied once per HTTP call before the
+ * filters are parsed (`enforce_http_admission`, `api/bridge.rs`). Not per app
+ * and not per tab: two Peek tabs and a Ship tab signed in as one person share
+ * one allowance, and the relay is the only participant that can see all three.
+ *
+ * Ship and Peek each grew half of the answer. Ship's `useRefresh` merged the two
+ * events a tab switch raises and held off after a 429; Peek's
+ * `useRefreshTriggers` did neither, so a tab switch fired every read twice, and
+ * each refused read waited out its own hint and then retried at the same
+ * instant as every other one. Measured on production on 2026-09-23: Miky's key
+ * at 306 requests in one minute, single seconds of 40–58, and 33 refusals in
+ * one second when a whole fan-out was sent into a pause already in force.
+ *
+ * ## Two objects, both handed to the app
+ *
+ * - {@link createRelayBudget} — how long the relay has asked this tab to wait.
+ *   **The transport writes it** (it sees every 429) and everything that decides
+ *   whether to read consults it. No reader has to know about quotas.
+ * - {@link createRefreshScheduler} — one `visibilitychange` and one `focus`
+ *   listener for the whole tab, fanning out to every subscriber, each of which
+ *   still gets Ship's merge: two triggers inside `mergeMs` are one read.
+ *
+ * Neither is a module-level singleton (ADR 0002 §10 constraint 2): the app
+ * builds one of each and keeps the binding, as it does the live-client holder.
+ *
+ * ## A person's own action is not paused
+ *
+ * Nothing here gates a read. The budget is advice the *cadence* honours —
+ * scheduled refreshes skip while it is in force, and a retry waits it out — so
+ * a read somebody asked for by clicking still goes out at once. Backing off a
+ * poll costs freshness nobody asked for; backing off a click costs the thing
+ * they just did.
+ */
+/**
+ * The host's timers, declared here because this package compiles with neither
+ * the DOM nor the Node lib. Looked up on every call, so a test's fake timers
+ * apply to the defaults.
+ */
+const host = globalThis;
+/** The relay's quota refusal, as opposed to any other failure. */
+export function isRateLimited(text) {
+    const lower = text.toLowerCase();
+    return lower.includes('rate-limited') || lower.includes('quota exceeded');
+}
+/**
+ * The relay's own wait, in ms, or `undefined` if it did not state one.
+ *
+ * Buzz writes `rate-limited: quota exceeded; retry in 8s` (`api/bridge.rs`,
+ * `connection.rs`). Parsed rather than assumed because the number is what is
+ * left of the relay's *window*, not a fixed penalty — it shrinks as the minute
+ * rolls on, so a flat wait either spends early or idles long.
+ */
+export function retryHintMs(reason) {
+    const found = /retry in (\d+)\s*s/i.exec(reason);
+    if (!found)
+        return undefined;
+    return Number(found[1]) * 1000;
+}
+/** How long to wait when the relay refuses without saying for how long. */
+export const DEFAULT_BACKOFF_MS = 30_000;
+/**
+ * The floor under a stated wait. `retry in 0s` means the window has just rolled
+ * over; the read that would go out now is the one that was refused, so it still
+ * waits a moment rather than none.
+ */
+export const MIN_BACKOFF_MS = 1_000;
+const CHANNEL_MESSAGE = 'estiva-relay-budget';
+/** Whether a message on the shared channel is one of ours, and until when. */
+function pausedUntilOf(data) {
+    if (typeof data !== 'object' || data === null)
+        return undefined;
+    const message = data;
+    if (message.type !== CHANNEL_MESSAGE || typeof message.until !== 'number')
+        return undefined;
+    return Number.isFinite(message.until) ? message.until : undefined;
+}
+export function createRelayBudget(options = {}) {
+    const now = options.now ?? (() => Date.now());
+    const sleep = options.sleep ?? ((ms) => new Promise((done) => void host.setTimeout(done, ms)));
+    const defaultBackoffMs = options.defaultBackoffMs ?? DEFAULT_BACKOFF_MS;
+    const channel = options.channel;
+    let pausedUntil = 0;
+    const extend = (until) => {
+        if (until <= pausedUntil)
+            return false;
+        pausedUntil = until;
+        return true;
+    };
+    const onMessage = (event) => {
+        const until = pausedUntilOf(event.data);
+        // Epoch ms, so another tab's clock is this tab's clock. Only extends: a
+        // peer's shorter pause must not cancel a longer one learned here.
+        if (until !== undefined)
+            extend(until);
+    };
+    channel?.addEventListener('message', onMessage);
+    const pausedForMs = () => Math.max(0, pausedUntil - now());
+    return {
+        noteRateLimited(reason) {
+            const wait = Math.max(MIN_BACKOFF_MS, retryHintMs(reason) ?? defaultBackoffMs);
+            const until = now() + wait;
+            if (extend(until)) {
+                try {
+                    channel?.postMessage({ type: CHANNEL_MESSAGE, until });
+                }
+                catch {
+                    /* a closed channel only means the other tabs learn it themselves */
+                }
+            }
+            return pausedForMs();
+        },
+        pausedForMs,
+        async whenClear() {
+            for (let wait = pausedForMs(); wait > 0; wait = pausedForMs())
+                await sleep(wait);
+        },
+        reset() {
+            pausedUntil = 0;
+        },
+        close() {
+            channel?.removeEventListener('message', onMessage);
+        },
+    };
+}
+/**
+ * Two triggers inside this many ms are one read. Switching to a tab raises both
+ * `visibilitychange` and `focus`, and one read is enough for it.
+ */
+export const DEFAULT_MERGE_MS = 1_000;
+const DEFAULT_INTERVAL_MS = 30_000;
+export function createRefreshScheduler(options) {
+    const { document, window, budget } = options;
+    const mergeMs = options.mergeMs ?? DEFAULT_MERGE_MS;
+    const defaultIntervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    const clock = options.clock ?? {
+        // Read through at call time, not captured, so a test's fake timers apply.
+        now: () => Date.now(),
+        setInterval: (run, ms) => host.setInterval(run, ms),
+        clearInterval: (handle) => host.clearInterval(handle),
+    };
+    const subscribers = new Set();
+    let attached = false;
+    const visible = () => document.visibilityState === 'visible';
+    const tick = (subscriber) => {
+        const now = clock.now();
+        if (now - subscriber.lastAt < mergeMs)
+            return;
+        // The relay has refused on quota and said how long to wait. Skipping is the
+        // whole backoff: `lastAt` is left alone, so the first trigger after the
+        // pause runs at once rather than waiting out another interval — and nothing
+        // is queued, so the pause does not end in a burst of everything it skipped.
+        if (budget && budget.pausedForMs() > 0)
+            return;
+        subscriber.lastAt = now;
+        try {
+            // A rejected refresh is the caller's to report; it must not become an
+            // unhandled rejection, and one caller throwing must not skip the rest.
+            void Promise.resolve(subscriber.refresh()).catch(() => { });
+        }
+        catch {
+            /* a subscriber's own problem */
+        }
+    };
+    const fanOut = () => {
+        for (const subscriber of [...subscribers])
+            tick(subscriber);
+    };
+    const onVisibility = () => {
+        if (visible())
+            fanOut();
+    };
+    return {
+        subscribe(refresh, { interval = true, intervalMs = defaultIntervalMs } = {}) {
+            const subscriber = { refresh, lastAt: 0, timer: undefined };
+            subscribers.add(subscriber);
+            if (interval) {
+                // Checked at fire time rather than started and stopped on every
+                // visibility change: a hidden tab has nothing on screen to be stale.
+                subscriber.timer = clock.setInterval(() => {
+                    if (visible())
+                        tick(subscriber);
+                }, intervalMs);
+            }
+            if (!attached) {
+                // On first use and never at module scope, so importing registers
+                // nothing — and one pair of listeners however many subscribe.
+                document.addEventListener('visibilitychange', onVisibility);
+                window.addEventListener('focus', fanOut);
+                attached = true;
+            }
+            return () => {
+                if (!subscribers.delete(subscriber))
+                    return;
+                if (subscriber.timer !== undefined)
+                    clock.clearInterval(subscriber.timer);
+                if (subscribers.size === 0 && attached) {
+                    document.removeEventListener('visibilitychange', onVisibility);
+                    window.removeEventListener('focus', fanOut);
+                    attached = false;
+                }
+            };
+        },
+    };
+}
+//# sourceMappingURL=refresh.js.map

package/dist/refresh.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.3.0",
+  "description": "Browser lifecycle two Estiva apps share: the one live relay socket a tab should hold, its credential read per connect, the network coming back, and when a tab re-reads.",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/folder-activity.ts

@@ -23,12 +23,28 @@
  * 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.
+ *
+ * ## …unless it has one to give (PER-8)
+ *
+ * "Re-read now" was the right signal while nobody held what they had read. Once
+ * a reader keeps the events it already has — Peek's sidebar re-read 90 days of
+ * every Folder to learn about the one message the socket had just delivered, and
+ * spent the relay's per-request HTTP quota doing it — the event is the whole
+ * point. So a notification *may* carry the event that caused it. A listener
+ * that ignores the argument is exactly the listener it was before, and a
+ * notification with nothing to carry (another app's record moved) still sends
+ * none, so a reader must treat a missing event as "re-read", not as "nothing".
  */
-export type FolderListener = () => void
+import type { SignedEvent } from '@estiva-app/protocol'
+
+export type FolderListener = (event?: SignedEvent) => void
 
 export interface FolderActivity {
-  /** Say that something changed in `folder`. Safe for a folder nobody watches. */
-  notify(folder: string): void
+  /**
+   * Say that something changed in `folder`, and hand over the event when there
+   * is one. Safe for a folder nobody watches.
+   */
+  notify(folder: string, event?: SignedEvent): 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. */
@@ -38,12 +54,12 @@ export interface FolderActivity {
 export function createFolderActivity(): FolderActivity {
   const listeners = new Map<string, Set<FolderListener>>()
   return {
-    notify(folder) {
+    notify(folder, event) {
       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()
+          listener(event)
         } catch {
           /* a listener's own problem */
         }

package/src/index.ts

@@ -5,7 +5,8 @@
  * 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.
+ * coming back, when a tab re-reads and when the relay has asked it to wait
+ * (PER-13), and (SHA-2) the PWA's manifest, service worker and update flow.
  *
  * ## The rule this package is here to keep
  *
@@ -34,3 +35,21 @@ export {
   type FolderListener,
 } from './folder-activity.js'
 export { assumeOnline, browserOnlineSource, type OnlineSource, type OnlineTarget } from './online.js'
+export {
+  DEFAULT_BACKOFF_MS,
+  DEFAULT_MERGE_MS,
+  MIN_BACKOFF_MS,
+  createRefreshScheduler,
+  createRelayBudget,
+  isRateLimited,
+  retryHintMs,
+  type BudgetChannel,
+  type FocusTarget,
+  type RefreshScheduler,
+  type RefreshSchedulerOptions,
+  type RefreshSubscription,
+  type RelayBudget,
+  type RelayBudgetOptions,
+  type SchedulerClock,
+  type VisibilityTarget,
+} from './refresh.js'

package/src/live-client.ts

@@ -141,11 +141,19 @@ export interface LiveClient {
    * `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`.
+   *
+   * **The listener is handed the event** (PER-8). A reader that keeps what it
+   * has read applies it instead of re-reading the Folder; one that only wants
+   * the signal ignores the second argument. Stored events arrive as well as
+   * live ones — the REQ's replay on subscribe and on every reconnect — so a
+   * reader must be idempotent by event id. `since` bounds that replay: without
+   * it the relay replays whatever its default limit allows, shared across every
+   * Folder in the filter, which a keeping reader then has to dedupe.
    */
   watchFolders(
     folders: string[],
-    listener: (folder: string) => void,
-    options?: { kinds?: number[] },
+    listener: (folder: string, event?: SignedEvent) => void,
+    options?: { kinds?: number[]; since?: number },
   ): FolderWatch
   /** Watch one Folder by name. The refcounted half of {@link watchFolders}. */
   onFolderActivity(folder: string, listener: FolderListener): () => void
@@ -247,13 +255,19 @@ export function createLiveClient(options: LiveClientOptions): LiveClient {
     },
     onFolderActivity: (folder, listener) => activity.watch(folder, listener),
     watchFolders(folders, listener, watchOptions) {
-      const unwatch = folders.map((folder) => activity.watch(folder, () => listener(folder)))
+      const unwatch = folders.map((folder) => activity.watch(folder, (event) => listener(folder, event)))
       const subs = chunk([...new Set(folders)], MAX_FOLDERS_PER_SUBSCRIPTION).map((group) =>
         relay.subscribe(
-          [{ ...(watchOptions?.kinds ? { kinds: watchOptions.kinds } : {}), '#h': group }],
+          [
+            {
+              ...(watchOptions?.kinds ? { kinds: watchOptions.kinds } : {}),
+              '#h': group,
+              ...(watchOptions?.since !== undefined ? { since: watchOptions.since } : {}),
+            },
+          ],
           (event) => {
             const folder = folderOf(event)
-            if (folder) activity.notify(folder)
+            if (folder) activity.notify(folder, event)
           },
           {
             onClosed: (reason) => options.log?.('folder subscription closed', { reason }),

package/src/refresh.ts

@@ -0,0 +1,323 @@
+/**
+ * When a tab re-reads, and when it must not (PER-13).
+ *
+ * Buzz meters `POST /query` at **300 a minute per pubkey** — a fixed 60-second
+ * window, `human_api_calls_per_min`, applied once per HTTP call before the
+ * filters are parsed (`enforce_http_admission`, `api/bridge.rs`). Not per app
+ * and not per tab: two Peek tabs and a Ship tab signed in as one person share
+ * one allowance, and the relay is the only participant that can see all three.
+ *
+ * Ship and Peek each grew half of the answer. Ship's `useRefresh` merged the two
+ * events a tab switch raises and held off after a 429; Peek's
+ * `useRefreshTriggers` did neither, so a tab switch fired every read twice, and
+ * each refused read waited out its own hint and then retried at the same
+ * instant as every other one. Measured on production on 2026-09-23: Miky's key
+ * at 306 requests in one minute, single seconds of 40–58, and 33 refusals in
+ * one second when a whole fan-out was sent into a pause already in force.
+ *
+ * ## Two objects, both handed to the app
+ *
+ * - {@link createRelayBudget} — how long the relay has asked this tab to wait.
+ *   **The transport writes it** (it sees every 429) and everything that decides
+ *   whether to read consults it. No reader has to know about quotas.
+ * - {@link createRefreshScheduler} — one `visibilitychange` and one `focus`
+ *   listener for the whole tab, fanning out to every subscriber, each of which
+ *   still gets Ship's merge: two triggers inside `mergeMs` are one read.
+ *
+ * Neither is a module-level singleton (ADR 0002 §10 constraint 2): the app
+ * builds one of each and keeps the binding, as it does the live-client holder.
+ *
+ * ## A person's own action is not paused
+ *
+ * Nothing here gates a read. The budget is advice the *cadence* honours —
+ * scheduled refreshes skip while it is in force, and a retry waits it out — so
+ * a read somebody asked for by clicking still goes out at once. Backing off a
+ * poll costs freshness nobody asked for; backing off a click costs the thing
+ * they just did.
+ */
+
+/**
+ * The host's timers, declared here because this package compiles with neither
+ * the DOM nor the Node lib. Looked up on every call, so a test's fake timers
+ * apply to the defaults.
+ */
+const host = globalThis as unknown as {
+  setTimeout(run: () => void, ms: number): unknown
+  setInterval(run: () => void, ms: number): unknown
+  clearInterval(handle: unknown): void
+}
+
+/** The relay's quota refusal, as opposed to any other failure. */
+export function isRateLimited(text: string): boolean {
+  const lower = text.toLowerCase()
+  return lower.includes('rate-limited') || lower.includes('quota exceeded')
+}
+
+/**
+ * The relay's own wait, in ms, or `undefined` if it did not state one.
+ *
+ * Buzz writes `rate-limited: quota exceeded; retry in 8s` (`api/bridge.rs`,
+ * `connection.rs`). Parsed rather than assumed because the number is what is
+ * left of the relay's *window*, not a fixed penalty — it shrinks as the minute
+ * rolls on, so a flat wait either spends early or idles long.
+ */
+export function retryHintMs(reason: string): number | undefined {
+  const found = /retry in (\d+)\s*s/i.exec(reason)
+  if (!found) return undefined
+  return Number(found[1]) * 1000
+}
+
+/** How long to wait when the relay refuses without saying for how long. */
+export const DEFAULT_BACKOFF_MS = 30_000
+
+/**
+ * The floor under a stated wait. `retry in 0s` means the window has just rolled
+ * over; the read that would go out now is the one that was refused, so it still
+ * waits a moment rather than none.
+ */
+export const MIN_BACKOFF_MS = 1_000
+
+/** What the budget needs of a `BroadcastChannel`. Declared here, see `online.ts`. */
+export interface BudgetChannel {
+  postMessage(message: unknown): void
+  addEventListener(type: 'message', listener: (event: { data: unknown }) => void): void
+  removeEventListener(type: 'message', listener: (event: { data: unknown }) => void): void
+}
+
+export interface RelayBudgetOptions {
+  /** Default {@link DEFAULT_BACKOFF_MS}. */
+  defaultBackoffMs?: number
+  /**
+   * Share pauses with the app's other tabs.
+   *
+   * Tabs of one origin signed in as one person spend one allowance, so a pause
+   * one of them learns holds for all of them. Pass a `BroadcastChannel` — the
+   * app names it — or leave it out. A tab of another app on another origin
+   * cannot be reached this way and learns its own pause from its own refusal.
+   */
+  channel?: BudgetChannel
+  now?: () => number
+  sleep?: (ms: number) => Promise<void>
+}
+
+export interface RelayBudget {
+  /**
+   * Record a refusal from the relay's own words. Returns the pause in force
+   * afterwards, in ms.
+   *
+   * Extends a pause but never shortens one: two reads refused in the same
+   * second carry different remaining windows, and the second answer must not
+   * cancel the first.
+   */
+  noteRateLimited(reason: string): number
+  /** Milliseconds left to wait, or 0. */
+  pausedForMs(): number
+  /**
+   * Resolves once no pause is in force — immediately if none is.
+   *
+   * Loops rather than sleeping once: a pause can be extended while somebody is
+   * waiting on it, by this tab or another.
+   */
+  whenClear(): Promise<void>
+  /** Test seam. Nothing in an app clears a pause early. */
+  reset(): void
+  /** Detach from the channel, if one was given. */
+  close(): void
+}
+
+const CHANNEL_MESSAGE = 'estiva-relay-budget'
+
+/** Whether a message on the shared channel is one of ours, and until when. */
+function pausedUntilOf(data: unknown): number | undefined {
+  if (typeof data !== 'object' || data === null) return undefined
+  const message = data as { type?: unknown; until?: unknown }
+  if (message.type !== CHANNEL_MESSAGE || typeof message.until !== 'number') return undefined
+  return Number.isFinite(message.until) ? message.until : undefined
+}
+
+export function createRelayBudget(options: RelayBudgetOptions = {}): RelayBudget {
+  const now = options.now ?? (() => Date.now())
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((done) => void host.setTimeout(done, ms)))
+  const defaultBackoffMs = options.defaultBackoffMs ?? DEFAULT_BACKOFF_MS
+  const channel = options.channel
+  let pausedUntil = 0
+
+  const extend = (until: number): boolean => {
+    if (until <= pausedUntil) return false
+    pausedUntil = until
+    return true
+  }
+  const onMessage = (event: { data: unknown }) => {
+    const until = pausedUntilOf(event.data)
+    // Epoch ms, so another tab's clock is this tab's clock. Only extends: a
+    // peer's shorter pause must not cancel a longer one learned here.
+    if (until !== undefined) extend(until)
+  }
+  channel?.addEventListener('message', onMessage)
+
+  const pausedForMs = () => Math.max(0, pausedUntil - now())
+
+  return {
+    noteRateLimited(reason) {
+      const wait = Math.max(MIN_BACKOFF_MS, retryHintMs(reason) ?? defaultBackoffMs)
+      const until = now() + wait
+      if (extend(until)) {
+        try {
+          channel?.postMessage({ type: CHANNEL_MESSAGE, until })
+        } catch {
+          /* a closed channel only means the other tabs learn it themselves */
+        }
+      }
+      return pausedForMs()
+    },
+    pausedForMs,
+    async whenClear() {
+      for (let wait = pausedForMs(); wait > 0; wait = pausedForMs()) await sleep(wait)
+    },
+    reset() {
+      pausedUntil = 0
+    },
+    close() {
+      channel?.removeEventListener('message', onMessage)
+    },
+  }
+}
+
+/** What the scheduler needs of `document`. */
+export interface VisibilityTarget {
+  readonly visibilityState: string
+  addEventListener(type: 'visibilitychange', listener: () => void): void
+  removeEventListener(type: 'visibilitychange', listener: () => void): void
+}
+
+/** What the scheduler needs of `window`. */
+export interface FocusTarget {
+  addEventListener(type: 'focus', listener: () => void): void
+  removeEventListener(type: 'focus', listener: () => void): void
+}
+
+/** Timers, injected so a test can drive them. Handles are opaque. */
+export interface SchedulerClock {
+  now(): number
+  setInterval(run: () => void, ms: number): unknown
+  clearInterval(handle: unknown): void
+}
+
+/**
+ * Two triggers inside this many ms are one read. Switching to a tab raises both
+ * `visibilitychange` and `focus`, and one read is enough for it.
+ */
+export const DEFAULT_MERGE_MS = 1_000
+
+export interface RefreshSchedulerOptions {
+  document: VisibilityTarget
+  window: FocusTarget
+  /** Scheduled refreshes skip while this is paused. */
+  budget?: Pick<RelayBudget, 'pausedForMs'>
+  /** Default {@link DEFAULT_MERGE_MS}. */
+  mergeMs?: number
+  /** A subscriber's interval when it names none. Default 30 s. */
+  intervalMs?: number
+  clock?: SchedulerClock
+}
+
+export interface RefreshSubscription {
+  /**
+   * Whether the periodic refresh runs. Default `true`.
+   *
+   * A caller with live delivery turns it off while its socket is live and keeps
+   * the focus and visibility triggers: a tab hidden for ten minutes may have had
+   * its socket dropped by the browser, and a reconnect's backfill is not
+   * instant, so re-reading when somebody looks is right either way.
+   */
+  interval?: boolean
+  intervalMs?: number
+}
+
+export interface RefreshScheduler {
+  /**
+   * Re-run `refresh` on focus, on becoming visible, and every `intervalMs`
+   * while visible. Never on subscribe — the caller owns its first read.
+   * Returns an unsubscribe; calling it twice is harmless.
+   */
+  subscribe(refresh: () => void | Promise<void>, options?: RefreshSubscription): () => void
+}
+
+const DEFAULT_INTERVAL_MS = 30_000
+
+interface Subscriber {
+  refresh: () => void | Promise<void>
+  /** When this subscriber last ran. Merge and pause are judged per subscriber. */
+  lastAt: number
+  timer: unknown
+}
+
+export function createRefreshScheduler(options: RefreshSchedulerOptions): RefreshScheduler {
+  const { document, window, budget } = options
+  const mergeMs = options.mergeMs ?? DEFAULT_MERGE_MS
+  const defaultIntervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS
+  const clock: SchedulerClock = options.clock ?? {
+    // Read through at call time, not captured, so a test's fake timers apply.
+    now: () => Date.now(),
+    setInterval: (run, ms) => host.setInterval(run, ms),
+    clearInterval: (handle) => host.clearInterval(handle),
+  }
+  const subscribers = new Set<Subscriber>()
+  let attached = false
+
+  const visible = () => document.visibilityState === 'visible'
+
+  const tick = (subscriber: Subscriber) => {
+    const now = clock.now()
+    if (now - subscriber.lastAt < mergeMs) return
+    // The relay has refused on quota and said how long to wait. Skipping is the
+    // whole backoff: `lastAt` is left alone, so the first trigger after the
+    // pause runs at once rather than waiting out another interval — and nothing
+    // is queued, so the pause does not end in a burst of everything it skipped.
+    if (budget && budget.pausedForMs() > 0) return
+    subscriber.lastAt = now
+    try {
+      // A rejected refresh is the caller's to report; it must not become an
+      // unhandled rejection, and one caller throwing must not skip the rest.
+      void Promise.resolve(subscriber.refresh()).catch(() => {})
+    } catch {
+      /* a subscriber's own problem */
+    }
+  }
+  const fanOut = () => {
+    for (const subscriber of [...subscribers]) tick(subscriber)
+  }
+  const onVisibility = () => {
+    if (visible()) fanOut()
+  }
+
+  return {
+    subscribe(refresh, { interval = true, intervalMs = defaultIntervalMs } = {}) {
+      const subscriber: Subscriber = { refresh, lastAt: 0, timer: undefined }
+      subscribers.add(subscriber)
+      if (interval) {
+        // Checked at fire time rather than started and stopped on every
+        // visibility change: a hidden tab has nothing on screen to be stale.
+        subscriber.timer = clock.setInterval(() => {
+          if (visible()) tick(subscriber)
+        }, intervalMs)
+      }
+      if (!attached) {
+        // On first use and never at module scope, so importing registers
+        // nothing — and one pair of listeners however many subscribe.
+        document.addEventListener('visibilitychange', onVisibility)
+        window.addEventListener('focus', fanOut)
+        attached = true
+      }
+      return () => {
+        if (!subscribers.delete(subscriber)) return
+        if (subscriber.timer !== undefined) clock.clearInterval(subscriber.timer)
+        if (subscribers.size === 0 && attached) {
+          document.removeEventListener('visibilitychange', onVisibility)
+          window.removeEventListener('focus', fanOut)
+          attached = false
+        }
+      }
+    },
+  }
+}