@spooky-sync/core 0.0.1-canary.38 → 0.0.1-canary.381

package/src/mutation/write.saga.ts

@@ -0,0 +1,384 @@
+import { RecordId } from 'surrealdb';
+import type { MutationEventType, UpdateOptions } from '../types';
+import type { Saga } from '../kernel/saga';
+import { fx } from '../kernel/effects';
+import type { ClientState, PeerWrite, PendingWrite } from '../state/client-state';
+import * as R from '../state/reducers';
+import { parseParams } from '../utils/parser';
+import { extractTablePart, parseRecordIdString } from '../utils/index';
+import type { SagaEnv } from '../query/env';
+import { columnsFor } from '../query/env';
+import { PENDING_WRITE_ORPHAN_MS } from '../kernel/constants';
+import {
+  loadPendingWriteRows,
+  parsePendingWriteRow,
+  pendingWriteId,
+  planCreateTx,
+  planDeferredOutboxRowTx,
+  planDeleteTx,
+  planLocalOnlyUpdateTx,
+  planPeerCreateTx,
+  planPeerUndoTx,
+  planUpdateTx,
+  type LocalTx,
+  type PendingWriteRow,
+} from './rows';
+
+export interface WriteInput {
+  kind: MutationEventType;
+  recordId: string;
+  data?: Record<string, unknown>;
+  options?: UpdateOptions;
+}
+
+export interface WriteResult {
+  mutationId: string;
+  record: Record<string, unknown> | null;
+}
+
+const debounceKey = (input: WriteInput): string | null => {
+  const d = input.options?.debounced;
+  if (!d) return null;
+  const opts = d === true ? {} : d;
+  const keyMode = opts.key ?? 'recordId_x_fields';
+  return keyMode === 'recordId'
+    ? input.recordId
+    : `${input.recordId}::${Object.keys(input.data ?? {}).sort().join(',')}`;
+};
+const debounceDelay = (input: WriteInput): number => {
+  const d = input.options?.debounced;
+  return d && d !== true && typeof d.delay === 'number' ? d.delay : 300;
+};
+const flushOnHide = (input: WriteInput): boolean => {
+  const d = input.options?.debounced;
+  return !(d && d !== true && d.flushOnHide === false);
+};
+
+/**
+ * One optimistic write: read the previous row (update/delete), run the local
+ * transaction that writes the row AND its outbox entry, publish the outbox
+ * item (which puts the id into the overlay and dirties the table's queries),
+ * feed the circuit, and start a drain. A debounced update applies locally at
+ * once but accumulates into one outbox row written on flush.
+ */
+export function* write(env: SagaEnv, input: WriteInput): Saga<WriteResult> {
+  const table = extractTablePart(input.recordId);
+  const columns = columnsFor(env, table);
+  if (!columns) throw new Error(`Table ${table} not found`);
+  const rid = parseRecordIdString(input.recordId);
+  const params = input.data ? parseParams(columns as never, input.data) : undefined;
+  const key = input.kind === 'update' ? debounceKey(input) : null;
+  if (key !== null) return yield* debouncedUpdate(input, key, rid, table, params ?? {});
+  const mutationId = (yield fx.id('mutation')) as string;
+  const now = (yield fx.now()) as number;
+  let before: Record<string, unknown> | null = null;
+  if (input.kind !== 'create') before = yield* readBefore(rid);
+  const tx = planTx(input.kind, { recordId: rid, mutationId: parseRecordIdString(mutationId), table, data: params, before, now });
+  return yield* commitWrite(input.kind, tx, { mutationId, recordId: input.recordId, table, before, now });
+}
+
+function planTx(kind: MutationEventType, planInput: Parameters<typeof planCreateTx>[0]): LocalTx {
+  if (kind === 'create') return planCreateTx(planInput);
+  if (kind === 'update') return planUpdateTx(planInput);
+  return planDeleteTx(planInput);
+}
+
+function* readBefore(rid: RecordId<string>): Saga<Record<string, unknown> | null> {
+  const res = (yield fx.local.query('SELECT * FROM ONLY $id', { id: rid })) as unknown[];
+  const row = Array.isArray(res) ? res[0] : null;
+  return row && typeof row === 'object' && !Array.isArray(row) ? (row as Record<string, unknown>) : null;
+}
+
+interface CommitCtx {
+  mutationId: string;
+  recordId: string;
+  table: string;
+  before: Record<string, unknown> | null;
+  now: number;
+}
+
+function* commitWrite(kind: MutationEventType, tx: LocalTx, ctx: CommitCtx): Saga<WriteResult> {
+  const result = (yield fx.local.execute(tx.query, tx.vars)) as unknown;
+  const target = kind === 'update' ? (result as { target?: unknown } | undefined)?.target : result;
+  const record = kind === 'delete' || !target || typeof target !== 'object' ? null : (target as Record<string, unknown>);
+  yield fx.state.update(
+    R.outboxPush({ id: ctx.mutationId, type: kind, recordId: ctx.recordId, table: ctx.table, status: 'pending', ackedAt: null, attempts: 0 })
+  );
+  const version = kind === 'create' ? 1 : typeof record?._00_rv === 'number' ? (record._00_rv as number) : ((ctx.before?._00_rv as number) ?? 0) + 1;
+  const circuitRecord = kind === 'delete' ? (ctx.before ?? {}) : { ...record, _00_rv: version };
+  const circuitTuple = { table: ctx.table, op: kind.toUpperCase() as 'CREATE' | 'UPDATE' | 'DELETE', id: ctx.recordId, record: circuitRecord };
+  try {
+    yield fx.ssp.ingest([circuitTuple]);
+    if (kind === 'delete') yield fx.state.update(R.deleteVersions([ctx.recordId]));
+    else yield fx.state.update(R.setVersions([[ctx.recordId, version]]));
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'error', message: 'circuit ingest failed after a local write', data: { recordId: ctx.recordId, error } });
+  }
+  yield fx.emit({
+    type: 'mutation:event',
+    event: { type: kind, mutation_id: parseRecordIdString(ctx.mutationId), record_id: parseRecordIdString(ctx.recordId), data: tx.vars.data, record, beforeRecord: ctx.before ?? undefined, tableName: ctx.table },
+  });
+  const role = (yield fx.state.read((s) => s.tabRole)) as ClientState['tabRole'];
+  if (role !== 'solo') yield fx.emit({ type: 'tabs:broadcast', message: { type: 'ingest', records: [circuitTuple] } });
+  if (role === 'follower') yield fx.emit({ type: 'tabs:broadcast', message: { type: 'outbox-changed', mutationId: ctx.mutationId } });
+  else yield fx.dispatch({ type: 'Drain' });
+  return { mutationId: ctx.mutationId, record };
+}
+
+/**
+ * Apply locally now, remember the merged patch, write the outbox row on flush.
+ * With `flushOnHide` (the default) the merged patch is also mirrored to
+ * `_00_pending_writes` in the same transaction, so a reload or a closed tab
+ * inside the delay cannot lose it.
+ */
+function* debouncedUpdate(
+  input: WriteInput,
+  key: string,
+  rid: RecordId<string>,
+  table: string,
+  params: Record<string, unknown>
+): Saga<WriteResult> {
+  const existing = (yield fx.state.read((s) => s.pendingWrites.get(key))) as PendingWrite | undefined;
+  const now = (yield fx.now()) as number;
+  const before = existing ? existing.before : yield* readBefore(rid);
+  const mirrorId = existing?.mirrorId ?? (flushOnHide(input) ? pendingWriteId((yield fx.id('mutation')) as string) : null);
+  const delay = debounceDelay(input);
+  const mirror = mirrorId
+    ? { id: parseRecordIdString(mirrorId), row: { recordId: rid, tableName: table, data: { ...existing?.data, ...params }, beforeRecord: before, flushBy: now + delay } }
+    : undefined;
+  const local = planLocalOnlyUpdateTx({ recordId: rid, data: params, mirror });
+  const res = (yield fx.local.execute(local.query, local.vars)) as { target?: Record<string, unknown> } | undefined;
+  const record = res?.target ?? null;
+  yield fx.state.update(R.mergePendingWrite({ key, table, recordId: input.recordId, data: params, before, firstAt: existing?.firstAt ?? now, mirrorId }));
+  yield fx.state.update(R.markTableDirty(table));
+  const version = typeof record?._00_rv === 'number' ? (record._00_rv as number) : 0;
+  const tuple = { table, op: 'UPDATE' as const, id: input.recordId, record: { ...record, _00_rv: version } };
+  try {
+    yield fx.ssp.ingest([tuple]);
+    yield fx.state.update(R.setVersions([[input.recordId, version]]));
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'error', message: 'circuit ingest failed after a local write', data: { recordId: input.recordId, error } });
+  }
+  const role = (yield fx.state.read((s) => s.tabRole)) as ClientState['tabRole'];
+  if (role !== 'solo') yield fx.emit({ type: 'tabs:broadcast', message: { type: 'ingest', records: [tuple] } });
+  yield fx.timer.set(`debounce:${key}`, delay, { type: 'FlushWrite', key });
+  return { mutationId: '', record };
+}
+
+/** Timer target: turn the accumulated patch into one outbox row and drain. */
+export function* flushWrite(env: SagaEnv, key: string): Saga<void> {
+  const pending = (yield fx.state.read((s) => s.pendingWrites.get(key))) as PendingWrite | undefined;
+  if (!pending) return;
+  yield fx.state.update(R.clearPendingWrite(key));
+  const mutationId = (yield fx.id('mutation')) as string;
+  const now = (yield fx.now()) as number;
+  const rid = parseRecordIdString(pending.recordId);
+  const insert = planDeferredOutboxRowTx({
+    recordId: rid,
+    mutationId: parseRecordIdString(mutationId),
+    table: pending.table,
+    data: { ...pending.data },
+    before: pending.before,
+    now,
+    mirrorId: pending.mirrorId ? parseRecordIdString(pending.mirrorId) : undefined,
+  });
+  try {
+    yield fx.local.execute(insert.query, insert.vars);
+  } catch (error) {
+    // The patch is no longer in memory; a mirrored one is still in the store.
+    if (pending.mirrorId) yield fx.timer.set('adopt-writes', PENDING_WRITE_ORPHAN_MS, { type: 'AdoptPendingWrites' });
+    throw error;
+  }
+  yield fx.state.update(R.outboxPush({ id: mutationId, type: 'update', recordId: pending.recordId, table: pending.table, status: 'pending', ackedAt: null, attempts: 0 }));
+  yield fx.emit({
+    type: 'mutation:event',
+    event: { type: 'update', mutation_id: parseRecordIdString(mutationId), record_id: rid, data: { ...pending.data }, beforeRecord: pending.before ?? undefined, tableName: pending.table },
+  });
+  const role = (yield fx.state.read((s) => s.tabRole)) as ClientState['tabRole'];
+  if (role === 'follower') yield fx.emit({ type: 'tabs:broadcast', message: { type: 'outbox-changed', mutationId } });
+  else yield fx.dispatch({ type: 'Drain' });
+}
+
+/**
+ * The page is being hidden (tab switch, reload, close, backgrounded): flush
+ * every mirrored pending write now rather than when its timer fires. On a
+ * reload or close this races the teardown; whatever does not make it stays
+ * in `_00_pending_writes` for the next boot.
+ */
+export function* flushPendingWrites(): Saga<void> {
+  const keys = (yield fx.state.read((s) => [...s.pendingWrites.values()].filter((w) => w.mirrorId !== null).map((w) => w.key))) as string[];
+  for (const key of keys) {
+    yield fx.timer.clear(`debounce:${key}`);
+    yield fx.dispatch({ type: 'FlushWrite', key });
+  }
+}
+
+/**
+ * Move abandoned `_00_pending_writes` rows into the outbox: rows no pending
+ * write of this tab holds, `PENDING_WRITE_ORPHAN_MS` past their due flush. That
+ * is a tab that reloaded or closed inside the delay, or a flush of ours that
+ * failed. A row not yet overdue may still be live in another tab and is looked
+ * at again once it would be. A follower only nudges the leader, so a single
+ * tab adopts and a patch is never queued twice.
+ */
+export function* adoptPendingWrites(): Saga<void> {
+  const state = (yield fx.state.read((s) => s)) as ClientState;
+  let raw: unknown[] = [];
+  try {
+    const res = (yield fx.local.query(loadPendingWriteRows())) as unknown[];
+    raw = Array.isArray(res?.[0]) ? (res[0] as unknown[]) : [];
+  } catch {
+    return; // An older store may not have the table yet: nothing to adopt.
+  }
+  const held = new Set([...state.pendingWrites.values()].map((w) => w.mirrorId));
+  const rows = raw.map(parsePendingWriteRow).filter((r): r is PendingWriteRow => r !== null && !held.has(r.id));
+  if (rows.length === 0) return;
+  if (state.tabRole === 'follower') {
+    yield fx.emit({ type: 'tabs:broadcast', message: { type: 'outbox-changed', mutationId: '' } });
+    return;
+  }
+  const now = (yield fx.now()) as number;
+  let recheckAt = Infinity;
+  let adopted = 0;
+  for (const row of rows) {
+    const due = row.flushBy + PENDING_WRITE_ORPHAN_MS;
+    if (now < due) {
+      recheckAt = Math.min(recheckAt, due);
+      continue;
+    }
+    const mutationId = (yield fx.id('mutation')) as string;
+    const move = planDeferredOutboxRowTx({
+      recordId: parseRecordIdString(row.recordId),
+      mutationId: parseRecordIdString(mutationId),
+      table: row.tableName,
+      data: row.data,
+      before: row.beforeRecord,
+      now,
+      mirrorId: parseRecordIdString(row.id),
+    });
+    try {
+      yield fx.local.execute(move.query, move.vars);
+    } catch (error) {
+      yield fx.emit({ type: 'log', level: 'warn', message: 'could not move an abandoned debounced write into the outbox', data: { id: row.id, error } });
+      continue;
+    }
+    yield fx.state.update(R.outboxPush({ id: mutationId, type: 'update', recordId: row.recordId, table: row.tableName, status: 'pending', ackedAt: null, attempts: 0 }));
+    adopted += 1;
+  }
+  if (adopted > 0) yield fx.dispatch({ type: 'Drain' });
+  if (recheckAt !== Infinity) yield fx.timer.set('adopt-writes', recheckAt - now, { type: 'AdoptPendingWrites' });
+}
+
+// ---- channel peers' creates and deletes ------------------------------------------
+
+/** The row as the local store holds it, or null: what a channel checks its filter against. */
+export function* readRow(recordId: string): Saga<Record<string, unknown> | null> {
+  return yield* readBefore(parseRecordIdString(recordId));
+}
+
+export interface PeerWriteInput {
+  recordId: string;
+  /** The row's fields, for a create. */
+  data?: Record<string, unknown>;
+  /** How long it shows without the server confirming it. */
+  ttlMs: number;
+}
+
+/**
+ * A channel peer created a row: put it in the store and the circuit like an
+ * own optimistic create, minus the outbox entry (the peer pushes it), and
+ * show it through the overlay. `_00_rv` stays unset on purpose: the server's
+ * body (with its computed fields) still downloads and replaces this one.
+ * Refuses an id this client already holds a confirmed row or an own pending
+ * write for, so a peer can never overwrite real data. Returns whether it applied.
+ */
+export function* peerCreate(env: SagaEnv, input: PeerWriteInput): Saga<boolean> {
+  const table = extractTablePart(input.recordId);
+  const columns = columnsFor(env, table);
+  if (!columns) return false;
+  const [confirmed, ownPending, peerPending] = (yield fx.state.read((s) => [
+    s.versions.has(input.recordId),
+    s.outbox.some((i) => i.recordId === input.recordId),
+    s.peerWrites.has(input.recordId),
+  ])) as [boolean, boolean, boolean];
+  if (confirmed || ownPending || peerPending) return false;
+  const rid = parseRecordIdString(input.recordId);
+  const existing = yield* readBefore(rid);
+  let record = existing;
+  if (!existing) {
+    const params = parseParams(columns as never, input.data ?? {});
+    const tx = planPeerCreateTx({ recordId: rid, data: params });
+    try {
+      const res = (yield fx.local.execute(tx.query, tx.vars)) as unknown;
+      record = res && typeof res === 'object' && !Array.isArray(res) ? (res as Record<string, unknown>) : null;
+    } catch (error) {
+      yield fx.emit({ type: 'log', level: 'debug', message: 'peer create refused by the local store', data: { recordId: input.recordId, error } });
+      return false;
+    }
+  }
+  // An existing unconfirmed row is another tab's copy of the same peer create.
+  if (!record) return false;
+  try {
+    yield fx.ssp.ingest([{ table, op: 'CREATE', id: input.recordId, record: { ...record, _00_rv: 0 } }]);
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'error', message: 'circuit ingest failed after a peer create', data: { recordId: input.recordId, error } });
+  }
+  const now = (yield fx.now()) as number;
+  yield fx.state.update(R.setPeerWrite(input.recordId, { kind: 'create', table, expiresAt: now + input.ttlMs }));
+  yield fx.timer.set(`peer:${input.recordId}`, input.ttlMs, { type: 'PeerWriteExpired', id: input.recordId });
+  return true;
+}
+
+/**
+ * A channel peer deleted a row: hide it through the overlay, keep it in the
+ * store. Undoing is then just forgetting the entry; a confirmed delete has
+ * taken the row out of the server's membership by the time it expires.
+ */
+export function* peerDelete(env: SagaEnv, input: PeerWriteInput): Saga<boolean> {
+  const table = extractTablePart(input.recordId);
+  if (!columnsFor(env, table)) return false;
+  const [known, confirmed] = (yield fx.state.read((s) => [s.peerWrites.get(input.recordId), s.versions.has(input.recordId)])) as [
+    PeerWrite | undefined,
+    boolean,
+  ];
+  if (known?.kind === 'create' && !confirmed) {
+    // Deleting a row the same peer created and nobody confirmed: just undo it.
+    yield fx.timer.clear(`peer:${input.recordId}`);
+    yield* undoPeerCreate(table, input.recordId);
+    return true;
+  }
+  const exists = (yield* readBefore(parseRecordIdString(input.recordId))) !== null;
+  if (!exists) return false;
+  const now = (yield fx.now()) as number;
+  yield fx.state.update(R.setPeerWrite(input.recordId, { kind: 'delete', table, expiresAt: now + input.ttlMs }));
+  yield fx.timer.set(`peer:${input.recordId}`, input.ttlMs, { type: 'PeerWriteExpired', id: input.recordId });
+  return true;
+}
+
+/** Timer target: a peer's write stops showing as unconfirmed. */
+export function* peerWriteExpired(id: string): Saga<void> {
+  const [write, confirmed, ownPending] = (yield fx.state.read((s) => [
+    s.peerWrites.get(id),
+    s.versions.has(id),
+    s.outbox.some((i) => i.recordId === id),
+  ])) as [PeerWrite | undefined, boolean, boolean];
+  if (!write) return;
+  if (write.kind === 'create' && !confirmed && !ownPending) {
+    yield* undoPeerCreate(write.table, id);
+    return;
+  }
+  yield fx.state.update(R.clearPeerWrite(id));
+}
+
+function* undoPeerCreate(table: string, id: string): Saga<void> {
+  const rid = parseRecordIdString(id);
+  const before = yield* readBefore(rid);
+  try {
+    const tx = planPeerUndoTx(rid);
+    yield fx.local.execute(tx.query, tx.vars);
+    if (before) yield fx.ssp.ingest([{ table, op: 'DELETE', id, record: before }]);
+  } catch (error) {
+    yield fx.emit({ type: 'log', level: 'warn', message: 'could not undo an unconfirmed peer create', data: { recordId: id, error } });
+  }
+  yield fx.state.update(R.clearPeerWrite(id));
+}

package/src/pure.ts

@@ -0,0 +1,66 @@
+/**
+ * `@spooky-sync/core/pure`: the side-effect-free builders of the sync protocol.
+ *
+ * Everything here is plain functions and constants over `surrealdb` value
+ * types: no wasm, no logger, no `window`/`document`/`localStorage`. Safe to
+ * import from a service worker, a dedicated worker or Node. The full client
+ * imports the same modules, so what this entry builds is byte for byte what
+ * `Sp00kyClient` sends.
+ */
+import { queryHashInput, type QueryKeyInput } from './query/hash';
+import { sha256Hex } from './utils/sha256';
+
+// Statement builders: register + snapshot, heartbeat, bodies, views.
+export * from './query/sql';
+// Query keys.
+export { queryHashInput, viewKeyInput, type QueryKeyInput } from './query/hash';
+// `_00_list_ref` table naming and user-id sanitizing (mirrors ssp-protocol).
+export {
+  ANON_LIST_REF_TABLE,
+  ANON_USER_ID,
+  DEFAULT_REF_MODE,
+  bucketIdForUser,
+  listRefTableFor,
+  sanitizeUserId,
+  type RefMode,
+} from './modules/ref-tables';
+// Membership snapshot parsing (the answer to the register read-back).
+export {
+  FAILED,
+  dedupeRecordVersions,
+  metaFromRow,
+  snapshotFromSingle,
+  type Answer,
+  type ListRefSnapshot,
+  type QueryMetaRow,
+} from './query/membership';
+// LIVE edge decoding.
+export { hashOfEdge, rowOfEdge } from './utils/edges';
+// SurrealQL string helpers.
+export {
+  surql,
+  type SealOptions,
+  type SealedQuery,
+  type SurqlHelper,
+  type TxQuery,
+} from './utils/surql';
+// Param typing the full client applies before registering.
+export { parseQueryParams } from './utils/parser';
+export { encodeRecordId, parseRecordIdString, parseDuration } from './utils/index';
+// Unverified JWT claim reading (user id, access method, impersonation).
+export {
+  decodeTokenClaims,
+  IMPERSONATION_ACCESS,
+  type TokenClaims,
+} from './modules/auth/impersonation';
+export { sha256Hex } from './utils/sha256';
+// Web Push wire types.
+export * from './push/types';
+
+/**
+ * The remote `_00_query` key of a query for one session salt: what the full
+ * client names its view (`_00_query:<key>`).
+ */
+export function queryKey(input: QueryKeyInput, sessionId: string | null): Promise<string> {
+  return sha256Hex(queryHashInput(input, sessionId));
+}

package/src/push/types.ts

@@ -0,0 +1,174 @@
+/**
+ * Web Push wire types shared by the page (`db.webPush`), the service worker
+ * bridge (`@spooky-sync/core/sw`) and the live feed. Pure: types plus a few
+ * dependency-free helpers, safe in any context.
+ *
+ * `PushPayload` mirrors `packages/push-core/src/config.rs` (`PushPayload`,
+ * `PayloadKind`, `Op`, `NotificationTemplate`). Keep the two in step.
+ */
+
+/** Payload format version this build understands. */
+export const PUSH_PAYLOAD_VERSION = 1;
+
+export type PushPayloadKind = 'rule' | 'message';
+export type PushOp = 'create' | 'update' | 'delete';
+export type PushUrgency = 'very-low' | 'low' | 'normal' | 'high';
+
+/** One button on a notification (`NotificationAction` plus a per-action `url`). */
+export interface PushNotificationAction {
+  action: string;
+  title: string;
+  icon?: string;
+  /** Opened instead of the notification's `url` when this action is clicked. */
+  url?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * What a content push shows. Every key other than `title` and `url` is passed
+ * to `showNotification` as is, unknown ones included (`vibrate`, `timestamp`,
+ * whatever a browser adds later).
+ */
+export interface PushNotification {
+  title?: string;
+  body?: string;
+  icon?: string;
+  badge?: string;
+  image?: string;
+  lang?: string;
+  dir?: string;
+  /** Defaults to the push's `topic`. */
+  tag?: string;
+  /** Opened (or focused) on click. */
+  url?: string;
+  requireInteraction?: boolean;
+  renotify?: boolean;
+  silent?: boolean;
+  actions?: PushNotificationAction[];
+  /** Merged into the notification's `data` next to the bridge's own keys. */
+  data?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+/**
+ * The JSON every push carries (then RFC 8291 encrypted). `notification`
+ * present: a content push the service worker shows as is. Absent: a
+ * content-free nudge, the app renders from its own data.
+ */
+export interface PushPayload {
+  v: number;
+  kind: PushPayloadKind;
+  /** Rule name (`kind: 'rule'`). */
+  rule?: string;
+  /** `_00_push_message` id (`kind: 'message'`). */
+  message?: string;
+  /** The row that fired the rule. */
+  table?: string;
+  id?: string;
+  op?: PushOp;
+  topic?: string;
+  notification?: PushNotification;
+  data?: Record<string, unknown>;
+  /** Epoch ms when the engine built it. */
+  ts: number;
+}
+
+/** Page -> service worker: the session to use for live rendering. */
+export interface BridgeTokenMessage {
+  type: 'sp00ky:token';
+  token: string;
+  userId: string;
+  /** The SurrealDB endpoint (`wss://host/rpc`), not the push endpoint. */
+  endpoint: string;
+  namespace: string;
+  database: string;
+  /** VAPID public key (base64url) the page subscribed with, for `pushsubscriptionchange`. */
+  publicKey?: string;
+  /** This browser's push endpoint, when subscribed. */
+  pushEndpoint?: string;
+}
+
+/** Page -> service worker: forget the session and close every notification. */
+export interface BridgeSignOutMessage {
+  type: 'sp00ky:signout';
+}
+
+/** Service worker -> page messages. */
+export type WebPushClientMessage =
+  /** A push arrived while this page was visible, so nothing was shown. */
+  | { type: 'sp00ky:push'; payload: PushPayload }
+  /** A notification was clicked and the bridge was told to route in-app. */
+  | { type: 'sp00ky:navigate'; url: string; payload?: PushPayload; action?: string }
+  /** The browser rotated the push subscription; the page should `sync()`. */
+  | { type: 'sp00ky:subscriptionchange'; endpoint?: string };
+
+/** `urlBase64ToUint8Array`: the VAPID key as `applicationServerKey` wants it. */
+export function base64UrlToBytes(value: string): Uint8Array {
+  const padded =
+    value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (value.length % 4)) % 4);
+  const raw = typeof atob === 'function' ? atob(padded) : decodeBase64Fallback(padded);
+  const out = new Uint8Array(raw.length);
+  for (let i = 0; i < raw.length; i++) out[i] = raw.charCodeAt(i);
+  return out;
+}
+
+export function bytesToBase64Url(bytes: ArrayBuffer | Uint8Array): string {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let raw = '';
+  for (let i = 0; i < view.length; i++) raw += String.fromCharCode(view[i]);
+  const b64 = typeof btoa === 'function' ? btoa(raw) : encodeBase64Fallback(raw);
+  return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export function sameBytes(
+  a: ArrayBuffer | Uint8Array | null | undefined,
+  b: ArrayBuffer | Uint8Array | null | undefined
+): boolean {
+  if (!a || !b) return false;
+  const x = a instanceof Uint8Array ? a : new Uint8Array(a);
+  const y = b instanceof Uint8Array ? b : new Uint8Array(b);
+  if (x.length !== y.length) return false;
+  for (let i = 0; i < x.length; i++) if (x[i] !== y[i]) return false;
+  return true;
+}
+
+/** A payload this build can act on (`v` known, `kind` set). */
+export function isPushPayload(value: unknown): value is PushPayload {
+  if (!value || typeof value !== 'object') return false;
+  const v = value as { v?: unknown; kind?: unknown };
+  return v.v === PUSH_PAYLOAD_VERSION && (v.kind === 'rule' || v.kind === 'message');
+}
+
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+function decodeBase64Fallback(input: string): string {
+  const clean = input.replace(/=+$/, '');
+  let out = '';
+  let buffer = 0;
+  let bits = 0;
+  for (const ch of clean) {
+    const idx = B64.indexOf(ch);
+    if (idx < 0) continue;
+    buffer = (buffer << 6) | idx;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out += String.fromCharCode((buffer >> bits) & 0xff);
+    }
+  }
+  return out;
+}
+
+function encodeBase64Fallback(raw: string): string {
+  let out = '';
+  for (let i = 0; i < raw.length; i += 3) {
+    const a = raw.charCodeAt(i);
+    const b = i + 1 < raw.length ? raw.charCodeAt(i + 1) : 0;
+    const c = i + 2 < raw.length ? raw.charCodeAt(i + 2) : 0;
+    const n = (a << 16) | (b << 8) | c;
+    out += B64[(n >> 18) & 63] + B64[(n >> 12) & 63];
+    out += i + 1 < raw.length ? B64[(n >> 6) & 63] : '=';
+    out += i + 2 < raw.length ? B64[n & 63] : '=';
+  }
+  return out;
+}