@spooky-sync/core 0.0.1-canary.29 → 0.0.1-canary.291

package/dist/sqlite-worker.js

@@ -0,0 +1,439 @@
+import { a as renderOrderSql, d as stableKey, i as projectedDataSql, n as openDb, o as renderWhereSql, r as project, s as reviveRow, u as resolveRelations } from "./sqlite-open.js";
+import sqlite3InitModule from "@sqlite.org/sqlite-wasm";
+
+//#region src/services/database/sqlite-lock-verify.ts
+const LOCK_VERIFY_TIMEOUT_MS = 2e3;
+async function verifyLockStillHeld$1(locks, name, fence, timeoutMs = LOCK_VERIFY_TIMEOUT_MS, warn = () => {}) {
+	if (!locks || !name || typeof locks.query !== "function") return;
+	let timer;
+	try {
+		const state = await Promise.race([locks.query(), new Promise((resolve) => {
+			timer = setTimeout(() => resolve(null), timeoutMs);
+		})]);
+		if (state === null) {
+			warn(`lock verification did not answer within ${timeoutMs}ms; trusting the steal callback`);
+			return;
+		}
+		if (!(state.held ?? []).some((l) => l.name === name)) await fence("lock missing after suspected freeze");
+	} catch {} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+//#endregion
+//#region src/services/database/sqlite-select.ts
+function ensureTable(db, table) {
+	if (db.knownTables.has(table)) return;
+	db.run(`CREATE TABLE IF NOT EXISTS "${table}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)`);
+	db.knownTables.add(table);
+}
+function execRows(db, sql, bind) {
+	return db.exec(sql, bind).map((r) => reviveRow(r.data));
+}
+/** Mirrors the engine's `selectByIds`: fetch by primary id, preserving `ids`
+*  order unless an ORDER BY overrides it. */
+function selectByIds(db, table, ids, opts) {
+	if (ids.length === 0) return [];
+	ensureTable(db, table);
+	const keys = ids.map(stableKey);
+	const placeholders = keys.map(() => "?").join(", ");
+	const bind = [];
+	const dataCol = opts?.select ? projectedDataSql(opts.select, bind) : "data";
+	bind.push(...keys);
+	let sql = `SELECT ${dataCol} FROM "${table}" WHERE id IN (${placeholders})`;
+	if (opts?.orderBy && opts.orderBy.length > 0) sql += renderOrderSql(opts.orderBy);
+	let rows = execRows(db, sql, bind);
+	if (!opts?.orderBy || opts.orderBy.length === 0) {
+		const pos = new Map(keys.map((k, i) => [k, i]));
+		rows = rows.sort((a, b) => (pos.get(stableKey(a.id)) ?? 0) - (pos.get(stableKey(b.id)) ?? 0));
+	}
+	return rows;
+}
+/** Mirrors the engine's `fetchRelation` SQL exactly. */
+function fetchRelation(db, req) {
+	ensureTable(db, req.table);
+	const keys = req.keys.map(stableKey);
+	const placeholders = keys.map(() => "?").join(", ");
+	const bind = [...keys];
+	const lhs = req.matchField === "id" ? "id" : `json_extract(data, '$.${req.matchField}')`;
+	let sql = `SELECT data FROM "${req.table}" WHERE ${lhs} IN (${placeholders})`;
+	if (req.where && req.where.length > 0) sql += ` AND ${renderWhereSql(req.where, bind, {})}`;
+	if (req.orderBy && req.orderBy.length > 0) sql += renderOrderSql(req.orderBy);
+	const rows = execRows(db, sql, bind);
+	return req.select ? rows.map((r) => project(r, req.select)) : rows;
+}
+async function executeSelect(plan, params, db) {
+	const counter = { n: 0 };
+	const fetcher = { fetchRelation: (req) => {
+		counter.n++;
+		return Promise.resolve(fetchRelation(db, req));
+	} };
+	if (plan.ids) {
+		const rows = selectByIds(db, plan.table, plan.ids, {
+			select: plan.select,
+			orderBy: plan.orderBy
+		});
+		await resolveRelations(rows, plan.relations, fetcher);
+		return {
+			rows,
+			relationFetches: counter.n
+		};
+	}
+	ensureTable(db, plan.table);
+	const bind = [];
+	let sql = `SELECT ${plan.select ? projectedDataSql(plan.select, bind) : "data"} FROM "${plan.table}"`;
+	if (plan.where && plan.where.length > 0) sql += ` WHERE ${renderWhereSql(plan.where, bind, params)}`;
+	if (plan.orderBy && plan.orderBy.length > 0) sql += renderOrderSql(plan.orderBy);
+	else sql += ` ORDER BY id`;
+	if (plan.limit !== void 0) sql += ` LIMIT ${Number(plan.limit)}`;
+	if (plan.offset !== void 0) sql += ` OFFSET ${Number(plan.offset)}`;
+	const rows = execRows(db, sql, bind);
+	await resolveRelations(rows, plan.relations, fetcher);
+	return {
+		rows,
+		relationFetches: counter.n
+	};
+}
+
+//#endregion
+//#region src/services/database/sqlite-worker.ts
+/**
+* Dedicated Web Worker that owns the SQLite-WASM handle. All DB access is
+* funnelled through here (the main thread never touches the wasm module), which
+* is also what the OPFS VFS requires — file access must happen off the main
+* thread. Persistence uses the **OPFS SAHPool VFS**: durable, and (unlike the
+* classic OPFS VFS) it does NOT require COOP/COEP cross-origin isolation
+* headers, so host apps embedding the client need no server changes. When OPFS
+* is unavailable it retries, then falls back to an in-memory DB and REPORTS the
+* loss of durability (see `sqlite-open.ts`) instead of degrading silently.
+*
+* Message protocol (request/response keyed by `id`; replies go to the channel
+* the request arrived on):
+*   { id, type: 'open',   payload: { dbName, useOpfs, workerLockName? } }
+*        -> { id, ok, persisted, opfsError? }
+*   { id, type: 'exec',   payload: { sql, bind } }  -> { id, ok, rows }
+*   { id, type: 'run',    payload: { sql, bind } }  -> { id, ok }
+*   { id, type: 'batch',  payload: [{ sql, bind }] } (atomic BEGIN/COMMIT)
+*   { id, type: 'select', payload: { plan, params } } -> { id, ok, rows, relationFetches }
+*   { id, type: 'close' }
+*   { id, type: 'shutdown' }                     (owner only: close + pauseVfs + self.close)
+*   { id, type: 'relock', payload: { workerLockName } }               (owner only)
+*   { id, type: 'add-client', payload: { clientId } } + ev.ports[0]   (owner only)
+*   { id, type: 'remove-client', payload: { clientId } }              (owner only)
+*
+* Multi-client (shared-tabs mode): the OWNER (the leader tab's engine) speaks
+* on the worker's own channel and controls the lifecycle. Follower tabs get a
+* MessagePort each (`add-client`) and may only issue data ops
+* (exec/run/batch/select). Every op, from any channel, runs through ONE op
+* chain so an async `select` from one client can never interleave with another
+* client's `batch` at the VFS layer.
+*
+* Leader fencing (shared-tabs mode): `open` may carry `workerLockName`, a Web
+* Lock this worker acquires BEFORE opening the pool and holds for the DB's
+* lifetime. The name is unique per leadership, so the lock being gone has
+* exactly one meaning: the broker stole it because this tab was presumed dead
+* (usually frozen). When that happens the worker FENCES itself: closes the DB,
+* releases the OPFS sync access handles (pauseVfs), tells the owner, and
+* refuses every further op. A frozen-then-thawed ex-leader therefore can never
+* write the durable file after a new leader took over. The thaw gate below
+* closes the wake-up ordering race where a queued write could run before the
+* lock-loss callback fires.
+*
+* `select` executes a whole QueryPlan — table creation, base select, the full
+* `.related()` tree (shared `resolveRelations`), and JSON row parsing — in ONE
+* round-trip, returning structured-clone row objects. This is the first-load
+* hot path; the per-statement ops remain for the write/shim paths.
+*/
+let db = null;
+let pool = null;
+/** Once fenced, every op is refused and the DB stays closed. Terminal. */
+let fenced = false;
+/** The per-leadership lock currently held (null = no fencing active). A
+*  relock (same-leader re-promotion after a broker restart) briefly holds two
+*  locks: the new one is installed here first, then the old one's own release
+*  is called, so there is no window where neither is held. */
+let currentLock = null;
+function workerLocks() {
+	const nav = globalThis.navigator;
+	return nav?.locks && typeof nav.locks.request === "function" ? nav.locks : null;
+}
+/**
+* Acquire `name` exclusively without waiting. Resolves with a handle when
+* granted, null when someone else holds it. If the request settles while the
+* holder still believes it owns the lock, the broker stole it: fence.
+*/
+function acquireWorkerLock(name) {
+	const locks = workerLocks();
+	if (!locks) return Promise.resolve({
+		name,
+		release() {}
+	});
+	return new Promise((resolve) => {
+		let granted = false;
+		let intentional = false;
+		let releaseGrant = null;
+		locks.request(name, {
+			mode: "exclusive",
+			ifAvailable: true
+		}, (lock) => {
+			if (!lock) {
+				resolve(null);
+				return;
+			}
+			granted = true;
+			resolve({
+				name,
+				release() {
+					intentional = true;
+					releaseGrant?.();
+				}
+			});
+			return new Promise((release) => {
+				releaseGrant = release;
+			});
+		}).then(() => {
+			if (granted && !intentional) fence("worker lock stolen");
+		}, () => {
+			if (granted && !intentional) fence("worker lock request failed");
+		});
+	});
+}
+function releaseHeldLock() {
+	currentLock?.release();
+	currentLock = null;
+}
+/**
+* Terminal teardown after leadership loss. Closing the DB first makes
+* pauseVfs legal (it throws while files are open); pausing releases the sync
+* access handles so the NEW leader's open succeeds without waiting for this
+* worker to be garbage collected.
+*/
+async function fence(reason) {
+	if (fenced) return;
+	fenced = true;
+	console.error(`[sp00ky] sqlite worker fenced (${reason}): leadership was taken over, closing the database and refusing further ops.`);
+	try {
+		db?.close();
+	} catch {}
+	db = null;
+	try {
+		pool?.pauseVfs?.();
+	} catch {}
+	pool = null;
+	try {
+		self.postMessage({
+			type: "lock-lost",
+			reason
+		});
+	} catch {}
+	releaseHeldLock();
+	self.close();
+}
+/**
+* A frozen tab's worker resumes with its message queue intact, and a queued
+* write could run BEFORE the lock-steal callback fires. Both the 1s interval
+* and every op call `noteTick()`; whichever runs first after a long gap kicks
+* off a lock verification, and ops await it before touching the DB. The gap
+* threshold must stay BELOW the broker's pong timeout: a freeze shorter than
+* the threshold cannot have triggered a steal yet, so skipping the check for
+* small gaps is safe.
+*/
+const FREEZE_SUSPECT_MS = 1e4;
+let lastTickAt = performance.now();
+let thawVerification = null;
+function noteTick() {
+	const now = performance.now();
+	const gap = now - lastTickAt;
+	lastTickAt = now;
+	if (gap > FREEZE_SUSPECT_MS && currentLock && !fenced && !thawVerification) thawVerification = verifyLockStillHeld().finally(() => {
+		thawVerification = null;
+	});
+}
+setInterval(noteTick, 1e3);
+function verifyLockStillHeld() {
+	return verifyLockStillHeld$1(workerLocks(), currentLock?.name, (reason) => fence(reason), void 0, (msg) => console.warn(`[sqlite-worker] ${msg}`));
+}
+async function open(dbName, useOpfs, systemTables = [], workerLockName, openOptions) {
+	if (workerLockName) {
+		const handle = await acquireWorkerLock(workerLockName);
+		if (!handle) throw new Error("worker-lock-unavailable");
+		releaseHeldLock();
+		currentLock = handle;
+	}
+	const result = await openDb(await sqlite3InitModule(), dbName, useOpfs, openOptions ?? {});
+	db = result.db;
+	pool = result.pool ?? null;
+	for (const t of systemTables) db.exec({ sql: `CREATE TABLE IF NOT EXISTS "${t}" (id TEXT PRIMARY KEY, data TEXT NOT NULL)` });
+	try {
+		db.exec({ sql: "PRAGMA busy_timeout = 5000; PRAGMA cache_size = -32000;" });
+	} catch {}
+	return {
+		persisted: result.persisted,
+		opfsError: result.opfsError
+	};
+}
+function closeDb() {
+	db?.close();
+	db = null;
+	pool = null;
+	selectDb.knownTables.clear();
+	releaseHeldLock();
+}
+function exec(sql, bind) {
+	if (!db) throw new Error("sqlite: DB not open");
+	return db.exec({
+		sql,
+		bind,
+		rowMode: "object",
+		returnValue: "resultRows"
+	});
+}
+function run(sql, bind) {
+	if (!db) throw new Error("sqlite: DB not open");
+	db.exec({
+		sql,
+		bind
+	});
+}
+function batch(stmts) {
+	if (!db) throw new Error("sqlite: DB not open");
+	db.exec({ sql: "BEGIN" });
+	try {
+		for (const s of stmts) db.exec({
+			sql: s.sql,
+			bind: s.bind
+		});
+		db.exec({ sql: "COMMIT" });
+	} catch (e) {
+		try {
+			db.exec({ sql: "ROLLBACK" });
+		} catch {}
+		throw e;
+	}
+}
+/** DB handle for `executeSelect` (see `sqlite-select.ts`, the unit-testable
+*  plan executor). `knownTables` is cleared on open/close, which covers both
+*  the solo fresh-worker path and the shared-mode same-worker bucket switch. */
+const selectDb = {
+	exec: (sql, bind) => exec(sql, bind),
+	run,
+	knownTables: /* @__PURE__ */ new Set()
+};
+/** Follower client ports, keyed by the clientId the owner assigned. */
+const clients = /* @__PURE__ */ new Map();
+/** Data ops a follower client port may issue; lifecycle stays owner-only. */
+const CLIENT_OPS = new Set([
+	"exec",
+	"run",
+	"batch",
+	"select"
+]);
+/**
+* ONE chain for every op from every channel. The handlers for `open` and
+* `select` are async; without this, a follower's select could interleave with
+* the owner's batch mid-transaction at the VFS layer. (Solo mode kept this
+* invariant on the main thread via the engine's opQueue; with multiple client
+* ports only the worker can.)
+*/
+let opChain = Promise.resolve();
+async function handle(type, payload, source) {
+	if (fenced) throw new Error("sqlite: fenced, leadership was taken over");
+	if (source === "client" && !CLIENT_OPS.has(type)) throw new Error(`sqlite worker: op ${type} is not allowed on a client port`);
+	switch (type) {
+		case "open":
+			selectDb.knownTables.clear();
+			{
+				const result = await open(payload.dbName, payload.useOpfs, payload.systemTables, payload.workerLockName, payload.openOptions);
+				for (const t of payload.systemTables ?? []) selectDb.knownTables.add(t);
+				return result;
+			}
+		case "relock": {
+			const handle = await acquireWorkerLock(payload.workerLockName);
+			if (!handle) throw new Error("worker-lock-unavailable");
+			releaseHeldLock();
+			currentLock = handle;
+			return {};
+		}
+		case "select": return executeSelect(payload.plan, payload.params ?? {}, selectDb);
+		case "exec": return { rows: exec(payload.sql, payload.bind) };
+		case "run":
+			run(payload.sql, payload.bind);
+			return {};
+		case "batch":
+			batch(payload);
+			return {};
+		case "close":
+			closeDb();
+			return {};
+		case "shutdown":
+			try {
+				db?.close();
+			} catch {}
+			db = null;
+			try {
+				pool?.pauseVfs?.();
+			} catch {}
+			pool = null;
+			releaseHeldLock();
+			queueMicrotask(() => self.close());
+			return {};
+		case "remove-client":
+			clients.get(payload.clientId)?.close();
+			clients.delete(payload.clientId);
+			return {};
+		default: throw new Error(`sqlite worker: unknown message ${type}`);
+	}
+}
+function dispatch(target, data, source) {
+	const { id, type, payload } = data ?? {};
+	noteTick();
+	const t0 = performance.now();
+	const runOp = async () => {
+		try {
+			if (thawVerification) await thawVerification;
+			const result = await handle(type, payload, source);
+			target.postMessage({
+				id,
+				ok: true,
+				wt: performance.now() - t0,
+				...result
+			});
+		} catch (err) {
+			target.postMessage({
+				id,
+				ok: false,
+				error: err instanceof Error ? err.message : String(err)
+			});
+		}
+	};
+	opChain = opChain.then(runOp, runOp);
+}
+self.onmessage = (ev) => {
+	const data = ev.data ?? {};
+	if (data.type === "add-client") {
+		const port = ev.ports?.[0];
+		const clientId = data.payload?.clientId;
+		if (!port || !clientId) {
+			self.postMessage({
+				id: data.id,
+				ok: false,
+				error: "sqlite worker: add-client needs a clientId and a transferred port"
+			});
+			return;
+		}
+		clients.get(clientId)?.close();
+		clients.set(clientId, port);
+		port.onmessage = (pe) => dispatch(port, pe.data, "client");
+		port.start?.();
+		self.postMessage({
+			id: data.id,
+			ok: true,
+			wt: 0
+		});
+		return;
+	}
+	dispatch(self, data, "owner");
+};
+
+//#endregion
+export {  };

package/dist/sw.d.ts

@@ -0,0 +1,207 @@
+import { LiveFeed, LiveQuery } from "./live.js";
+import { a as PushNotificationAction, c as PushPayloadKind, d as base64UrlToBytes, f as bytesToBase64Url, i as PushNotification, l as PushUrgency, m as sameBytes, n as BridgeTokenMessage, o as PushOp, p as isPushPayload, r as PUSH_PAYLOAD_VERSION, s as PushPayload, t as BridgeSignOutMessage, u as WebPushClientMessage } from "./worker-types.js";
+
+//#region src/sw/store.d.ts
+
+/**
+ * The service worker's tiny key-value store: IndexedDB database `sp00ky-push`,
+ * object store `kv`. Holds the bridged session (`token`) so a push that wakes
+ * the worker with no page open can still read live data. Falls back to memory
+ * where IndexedDB does not exist (Node, tests).
+ */
+interface KvStore {
+  get<T>(key: string): Promise<T | undefined>;
+  set(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+declare const PUSH_DB_NAME = "sp00ky-push";
+declare const PUSH_STORE_NAME = "kv";
+declare function memoryStore(): KvStore;
+type IdbFactoryLike = {
+  open(name: string, version?: number): IDBOpenDBRequest;
+};
+declare function idbStore(dbName?: string, storeName?: string, factory?: IdbFactoryLike): KvStore;
+/** IndexedDB when it exists, else one process-wide memory store. */
+declare function defaultStore(): KvStore;
+//#endregion
+//#region src/sw/index.d.ts
+interface SwNotification {
+  title: string;
+  tag: string;
+  body?: string;
+  data?: any;
+  close(): void;
+}
+interface SwPushSubscription {
+  endpoint: string;
+  options?: {
+    applicationServerKey?: ArrayBuffer | null;
+  };
+  toJSON(): unknown;
+}
+interface SwRegistration {
+  scope: string;
+  showNotification(title: string, options?: Record<string, unknown>): Promise<void>;
+  getNotifications(filter?: {
+    tag?: string;
+  }): Promise<SwNotification[]>;
+  pushManager?: {
+    getSubscription(): Promise<SwPushSubscription | null>;
+    subscribe(options: {
+      userVisibleOnly: boolean;
+      applicationServerKey: unknown;
+    }): Promise<SwPushSubscription>;
+  };
+}
+interface SwWindowClient {
+  url: string;
+  visibilityState?: string;
+  focused?: boolean;
+  focus(): Promise<unknown>;
+  navigate?(url: string): Promise<unknown>;
+  postMessage(message: unknown): void;
+}
+interface SwClients {
+  matchAll(options?: {
+    type?: string;
+    includeUncontrolled?: boolean;
+  }): Promise<SwWindowClient[]>;
+  openWindow(url: string): Promise<unknown>;
+}
+interface SwScope {
+  registration: SwRegistration;
+  clients: SwClients;
+  location: {
+    origin: string;
+  };
+  navigator?: {
+    userAgent?: string;
+  };
+  addEventListener(type: string, listener: (event: any) => void): void;
+  removeEventListener(type: string, listener: (event: any) => void): void;
+}
+interface SwExtendableEvent {
+  waitUntil(promise: Promise<unknown>): void;
+}
+interface SwPushEvent extends SwExtendableEvent {
+  data: {
+    json(): unknown;
+    text(): string;
+  } | null;
+}
+interface SwNotificationEvent extends SwExtendableEvent {
+  notification: SwNotification;
+  action: string;
+}
+interface SwPushSubscriptionChangeEvent extends SwExtendableEvent {
+  oldSubscription?: SwPushSubscription | null;
+  newSubscription?: SwPushSubscription | null;
+}
+/** What `showNotification` gets: a title plus any notification option. */
+interface NotificationSpec extends PushNotification {
+  title: string;
+}
+/** The session a page bridged over (`db.webPush.bridge()`). Fits `createLiveFeed` as is. */
+interface BridgedToken {
+  token: string;
+  userId: string;
+  endpoint: string;
+  namespace: string;
+  database: string;
+  publicKey?: string;
+  pushEndpoint?: string;
+  /** Epoch ms it was stored. */
+  at: number;
+}
+interface PushHandlerContext {
+  event: SwPushEvent;
+  registration: SwRegistration;
+  /** Show a notification the way the bridge would (tag, url and payload in `data`). */
+  show(spec: NotificationSpec): Promise<void>;
+  showPlaceholder(): Promise<void>;
+  /** Visible windows of this app, right now. */
+  visibleClients(): Promise<SwWindowClient[]>;
+  /** The bridged session, or null (signed out, never bridged, expired). */
+  bridged(): Promise<BridgedToken | null>;
+}
+interface LiveRenderOptions<Row = Record<string, any>> {
+  /** Open a feed for the bridged session: `(t) => createLiveFeed(t)`. */
+  feed(bridged: BridgedToken): LiveFeed | Promise<LiveFeed>;
+  /** What to read for this user (a built query, or `{ surql, params }`). */
+  query(userId: string, payload: PushPayload): LiveQuery;
+  /** Should this row be on screen as a notification? */
+  visible(row: Row): boolean;
+  /** The notification for one row; `tag` identifies it (one notification per row). */
+  render(row: Row): NotificationSpec & {
+    tag: string;
+  };
+  /** Budget for loading the rows, ms. Default 8000 (the push event lives ~30 s). */
+  timeoutMs?: number;
+  /** Quiet period `idle()` waits for, ms. Default 300. */
+  quietMs?: number;
+  /**
+   * A push whose only effect was closing notifications (their rows stopped
+   * being visible, e.g. read on another device) shows nothing. Default true.
+   * `false` shows the placeholder instead, for origins that hit Chrome's
+   * silent-push allowance.
+   */
+  silentClose?: boolean;
+}
+interface InstallPushHandlersOptions<Row = Record<string, any>> {
+  /** Turn a notification url into the one to open. Default: resolved against the worker's scope. */
+  resolveUrl?(url: string, payload: PushPayload | undefined): string;
+  /** Sees every valid push first. Return `true` when you handled it (and showed something). */
+  onPush?(payload: PushPayload, ctx: PushHandlerContext): Promise<boolean | void> | boolean | void;
+  /** Handles content-free nudges (you must show a notification). */
+  onNudge?(payload: PushPayload, ctx: PushHandlerContext): Promise<void> | void;
+  /**
+   * Custom rendering. For a content push, replaces the default mapping of
+   * `payload.notification`; for a nudge, a returned spec is shown instead of
+   * the live renderer. `null`/`undefined` keeps the default.
+   */
+  render?(payload: PushPayload): NotificationSpec | null | undefined;
+  /** Post `{ type: 'sp00ky:push', payload }` to visible windows instead of showing. Default true. */
+  suppressWhenVisible?: boolean;
+  /** Shown when a push cannot be rendered (browsers require a notification per push). */
+  placeholder?: {
+    title: string;
+    body?: string;
+    icon?: string;
+    [key: string]: unknown;
+  };
+  /** Return `true` when you handled the click yourself. */
+  onClick?(event: SwNotificationEvent, payload: PushPayload | undefined, action: string | undefined): Promise<boolean | void> | boolean | void;
+  onClose?(event: SwNotificationEvent, payload: PushPayload | undefined): Promise<void> | void;
+  /**
+   * How a click reaches an already open window: `navigate` (default) loads the
+   * url in it, `message` posts `{ type: 'sp00ky:navigate', url }` for in-app
+   * routing (`db.webPush.onMessage`).
+   */
+  clickMode?: 'navigate' | 'message';
+  /** Render nudges from live data. */
+  live?: LiveRenderOptions<Row>;
+  /** Feed factory for `pushsubscriptionchange` when `live` is not configured. */
+  feed?(bridged: BridgedToken): LiveFeed | Promise<LiveFeed>;
+  /** Re-subscribe on `pushsubscriptionchange`. Default true. */
+  resubscribe?: boolean;
+  /** Defaults to `self`. */
+  scope?: SwScope;
+  /** Defaults to IndexedDB `sp00ky-push` / `kv`. */
+  store?: KvStore;
+}
+declare const DEFAULT_PLACEHOLDER: {
+  title: string;
+  body: string;
+};
+/** The session the page bridged, or null (none, signed out, or its JWT expired). */
+declare function getBridgedToken(store?: KvStore): Promise<BridgedToken | null>;
+/**
+ * `showNotification(title, options)` arguments for a spec: every key passes
+ * through except `title` and `url`; `tag` defaults to the topic; `data` gets
+ * `url`, the payload and per-action urls next to the spec's own data.
+ */
+declare function notificationOptions(spec: NotificationSpec, payload?: PushPayload, extraData?: Record<string, unknown>): [string, Record<string, unknown>];
+/** Wire the push, click, close, message and subscription-change handlers. Returns an uninstall. */
+declare function installPushHandlers<Row = Record<string, any>>(options?: InstallPushHandlersOptions<Row>): () => void;
+//#endregion
+export { BridgeSignOutMessage, BridgeTokenMessage, BridgedToken, DEFAULT_PLACEHOLDER, InstallPushHandlersOptions, type KvStore, LiveRenderOptions, NotificationSpec, PUSH_DB_NAME, PUSH_PAYLOAD_VERSION, PUSH_STORE_NAME, PushHandlerContext, PushNotification, PushNotificationAction, PushOp, PushPayload, PushPayloadKind, PushUrgency, SwClients, SwExtendableEvent, SwNotification, SwNotificationEvent, SwPushEvent, SwPushSubscription, SwPushSubscriptionChangeEvent, SwRegistration, SwScope, SwWindowClient, WebPushClientMessage, base64UrlToBytes, bytesToBase64Url, defaultStore, getBridgedToken, idbStore, installPushHandlers, isPushPayload, memoryStore, notificationOptions, sameBytes };