@estiva-app/platform 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @estiva-app/platform
 
+## 0.3.1
+
+Subscribers on one interval share one timer (PER-6). No API change.
+
+0.3.0 started a `setInterval` per subscriber, at the moment it subscribed, so
+three views on one page on the same 10 s woke at three unrelated phases — Ship's
+project page read every ~3 s, and never inside the 1 s merge. Now there is one
+timer per distinct `intervalMs`, and every subscriber on it wakes in the same
+tick.
+
+- A subscriber that joined less than half an interval ago sits out a tick: its
+  caller has just done its own first read. Its first scheduled refresh comes
+  between 0.5× and 1.5× the interval after subscribing, then on the shared beat.
+- Different intervals still have separate timers, and separate phases.
+
+## 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:

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/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/refresh.d.ts

@@ -0,0 +1,163 @@
+/**
+ * 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.
+     * Every subscriber on one `intervalMs` shares one timer and wakes in the same
+     * tick; the first scheduled refresh comes 0.5–1.5 intervals after subscribing.
+     * 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,258 @@
+/**
+ * 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();
+    const groups = new Map();
+    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();
+    };
+    /*
+      One timer per interval, not per subscriber (PER-6).
+  
+      0.3.0 gave each subscriber its own `setInterval`, started when it
+      subscribed. Three views on one page, each on the same 10 s, therefore woke
+      at three unrelated phases — a read every three seconds or so, none of them
+      close enough to merge — and a page with a widget per section read "every
+      couple of seconds" at an interval nobody had chosen. Sharing the timer
+      puts every subscriber on an interval into the same wake-up.
+  
+      A subscriber that joined less than half an interval ago sits the tick out:
+      its caller has just done its own first read, and a shared phase would
+      otherwise re-read it moments later. So the first scheduled refresh comes
+      between a half and one and a half intervals after subscribing, and every
+      one after that on the shared beat.
+    */
+    const intervalTick = (group, intervalMs) => {
+        // Checked at fire time rather than started and stopped on every
+        // visibility change: a hidden tab has nothing on screen to be stale.
+        if (!visible())
+            return;
+        const now = clock.now();
+        for (const subscriber of [...group.members]) {
+            if (now - subscriber.joinedAt < intervalMs / 2)
+                continue;
+            tick(subscriber);
+        }
+    };
+    const join = (subscriber, intervalMs) => {
+        let group = groups.get(intervalMs);
+        if (!group) {
+            const created = { members: new Set(), timer: undefined };
+            created.timer = clock.setInterval(() => intervalTick(created, intervalMs), intervalMs);
+            groups.set(intervalMs, created);
+            group = created;
+        }
+        group.members.add(subscriber);
+    };
+    const leave = (subscriber) => {
+        if (subscriber.intervalMs === undefined)
+            return;
+        const group = groups.get(subscriber.intervalMs);
+        if (!group)
+            return;
+        group.members.delete(subscriber);
+        if (group.members.size === 0) {
+            clock.clearInterval(group.timer);
+            groups.delete(subscriber.intervalMs);
+        }
+    };
+    return {
+        subscribe(refresh, { interval = true, intervalMs = defaultIntervalMs } = {}) {
+            const subscriber = {
+                refresh,
+                lastAt: 0,
+                joinedAt: clock.now(),
+                intervalMs: interval ? intervalMs : undefined,
+            };
+            subscribers.add(subscriber);
+            if (interval)
+                join(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;
+                leave(subscriber);
+                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.2.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.1",
+  "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/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/refresh.ts

@@ -0,0 +1,381 @@
+/**
+ * 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.
+   * Every subscriber on one `intervalMs` shares one timer and wakes in the same
+   * tick; the first scheduled refresh comes 0.5–1.5 intervals after subscribing.
+   * 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
+  /** When it subscribed — its caller's own first read, which this never sees. */
+  joinedAt: number
+  /** The interval it ticks on, or `undefined` for focus and visibility only. */
+  intervalMs: number | undefined
+}
+
+/** Every subscriber on one interval, and the one timer they share (PER-6). */
+interface IntervalGroup {
+  members: Set<Subscriber>
+  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>()
+  const groups = new Map<number, IntervalGroup>()
+  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()
+  }
+
+  /*
+    One timer per interval, not per subscriber (PER-6).
+
+    0.3.0 gave each subscriber its own `setInterval`, started when it
+    subscribed. Three views on one page, each on the same 10 s, therefore woke
+    at three unrelated phases — a read every three seconds or so, none of them
+    close enough to merge — and a page with a widget per section read "every
+    couple of seconds" at an interval nobody had chosen. Sharing the timer
+    puts every subscriber on an interval into the same wake-up.
+
+    A subscriber that joined less than half an interval ago sits the tick out:
+    its caller has just done its own first read, and a shared phase would
+    otherwise re-read it moments later. So the first scheduled refresh comes
+    between a half and one and a half intervals after subscribing, and every
+    one after that on the shared beat.
+  */
+  const intervalTick = (group: IntervalGroup, intervalMs: number) => {
+    // Checked at fire time rather than started and stopped on every
+    // visibility change: a hidden tab has nothing on screen to be stale.
+    if (!visible()) return
+    const now = clock.now()
+    for (const subscriber of [...group.members]) {
+      if (now - subscriber.joinedAt < intervalMs / 2) continue
+      tick(subscriber)
+    }
+  }
+  const join = (subscriber: Subscriber, intervalMs: number) => {
+    let group = groups.get(intervalMs)
+    if (!group) {
+      const created: IntervalGroup = { members: new Set(), timer: undefined }
+      created.timer = clock.setInterval(() => intervalTick(created, intervalMs), intervalMs)
+      groups.set(intervalMs, created)
+      group = created
+    }
+    group.members.add(subscriber)
+  }
+  const leave = (subscriber: Subscriber) => {
+    if (subscriber.intervalMs === undefined) return
+    const group = groups.get(subscriber.intervalMs)
+    if (!group) return
+    group.members.delete(subscriber)
+    if (group.members.size === 0) {
+      clock.clearInterval(group.timer)
+      groups.delete(subscriber.intervalMs)
+    }
+  }
+
+  return {
+    subscribe(refresh, { interval = true, intervalMs = defaultIntervalMs } = {}) {
+      const subscriber: Subscriber = {
+        refresh,
+        lastAt: 0,
+        joinedAt: clock.now(),
+        intervalMs: interval ? intervalMs : undefined,
+      }
+      subscribers.add(subscriber)
+      if (interval) join(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
+        leave(subscriber)
+        if (subscribers.size === 0 && attached) {
+          document.removeEventListener('visibilitychange', onVisibility)
+          window.removeEventListener('focus', fanOut)
+          attached = false
+        }
+      }
+    },
+  }
+}