@rocksky/sdk 0.3.0 → 0.5.0

package/src/dedup.ts

@@ -0,0 +1,207 @@
+import { fromUint8Array } from "@atcute/car";
+import { decode as cborDecode, fromBytes, isBytes, isCidLink } from "@atcute/cbor";
+import { toString as cidToString } from "@atcute/cid";
+import { ClassicLevel } from "classic-level";
+
+import { albumHash, artistHash, songHash } from "./hash.js";
+
+const C_ARTIST = "app.rocksky.artist";
+const C_ALBUM = "app.rocksky.album";
+const C_SONG = "app.rocksky.song";
+const C_SCROBBLE = "app.rocksky.scrobble";
+const SEP = "\x00";
+
+/** What an {@link RockskyIndex.indexCar} pass added. */
+export interface IndexStats {
+  artists: number;
+  albums: number;
+  songs: number;
+  scrobbles: number;
+}
+
+export function totalIndexed(s: IndexStats): number {
+  return s.artists + s.albums + s.songs + s.scrobbles;
+}
+
+function identKey(did: string, col: string, hash: string): string {
+  return `${did}${SEP}${col}${SEP}${hash}`;
+}
+function scrobbleKey(did: string, songH: string, secs: number): string {
+  return `${did}${SEP}${C_SCROBBLE}${SEP}${songH}${SEP}${secs}`;
+}
+
+function primaryFor(did: string, col: string, rec: Record<string, unknown>): string | undefined {
+  const s = (k: string) => (typeof rec[k] === "string" ? (rec[k] as string) : "");
+  switch (col) {
+    case C_ARTIST:
+      return s("name") ? identKey(did, C_ARTIST, artistHash(s("name"))) : undefined;
+    case C_ALBUM:
+      return s("title") && s("artist") ? identKey(did, C_ALBUM, albumHash(s("title"), s("artist"))) : undefined;
+    case C_SONG:
+      return s("title") && s("artist") && s("album")
+        ? identKey(did, C_SONG, songHash(s("title"), s("artist"), s("album")))
+        : undefined;
+    case C_SCROBBLE: {
+      if (s("title") && s("artist") && s("album") && s("createdAt")) {
+        const secs = Math.floor(Date.parse(s("createdAt")) / 1000);
+        if (!Number.isNaN(secs)) return scrobbleKey(did, songHash(s("title"), s("artist"), s("album")), secs);
+      }
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Local duplicate-prevention mirror of a user's repo, keyed by Rocksky's
+ * identity hashes, backed by an embedded LevelDB (classic-level). Built from the
+ * repo CAR by {@link Agent.syncRepo} and kept live by {@link Agent.hydrateFromJetstream}.
+ */
+export class RockskyIndex {
+  private db: ClassicLevel<string, string>;
+
+  constructor(path: string) {
+    this.db = new ClassicLevel<string, string>(path, { keyEncoding: "utf8", valueEncoding: "utf8" });
+  }
+
+  /** Open the database (call before use). */
+  open(): Promise<void> {
+    return this.db.open();
+  }
+  /** Close the database. */
+  close(): Promise<void> {
+    return this.db.close();
+  }
+
+  private async get(key: string): Promise<string | undefined> {
+    try {
+      return await this.db.get(key);
+    } catch {
+      return undefined; // NotFound
+    }
+  }
+
+  songUri(did: string, title: string, artist: string, album: string): Promise<string | undefined> {
+    return this.get(identKey(did, C_SONG, songHash(title, artist, album)));
+  }
+  albumUri(did: string, album: string, albumArtist: string): Promise<string | undefined> {
+    return this.get(identKey(did, C_ALBUM, albumHash(album, albumArtist)));
+  }
+  artistUri(did: string, albumArtist: string): Promise<string | undefined> {
+    return this.get(identKey(did, C_ARTIST, artistHash(albumArtist)));
+  }
+  scrobbleUri(did: string, title: string, artist: string, album: string, secs: number): Promise<string | undefined> {
+    return this.get(scrobbleKey(did, songHash(title, artist, album), secs));
+  }
+
+  private async putPrimary(did: string, col: string, primary: string, uri: string): Promise<void> {
+    const rkey = uri.slice(uri.lastIndexOf("/") + 1);
+    await this.db.batch([
+      { type: "put", key: primary, value: uri },
+      { type: "put", key: `${SEP}rk${SEP}${did}${SEP}${col}${SEP}${rkey}`, value: primary },
+    ]);
+  }
+  recordSong(did: string, title: string, artist: string, album: string, uri: string): Promise<void> {
+    return this.putPrimary(did, C_SONG, identKey(did, C_SONG, songHash(title, artist, album)), uri);
+  }
+  recordAlbum(did: string, album: string, albumArtist: string, uri: string): Promise<void> {
+    return this.putPrimary(did, C_ALBUM, identKey(did, C_ALBUM, albumHash(album, albumArtist)), uri);
+  }
+  recordArtist(did: string, albumArtist: string, uri: string): Promise<void> {
+    return this.putPrimary(did, C_ARTIST, identKey(did, C_ARTIST, artistHash(albumArtist)), uri);
+  }
+  recordScrobble(did: string, title: string, artist: string, album: string, secs: number, uri: string): Promise<void> {
+    return this.putPrimary(did, C_SCROBBLE, scrobbleKey(did, songHash(title, artist, album), secs), uri);
+  }
+
+  cursor(did: string): Promise<number> {
+    return this.get(`${SEP}meta${SEP}cursor${SEP}${did}`).then((v) => (v ? Number(v) : 0));
+  }
+  async setCursor(did: string, timeUS: number): Promise<void> {
+    await this.db.put(`${SEP}meta${SEP}cursor${SEP}${did}`, String(timeUS));
+  }
+
+  /** Ingest a full repo CAR for `did`, indexing song/album/artist/scrobble. */
+  async indexCar(did: string, car: Uint8Array): Promise<IndexStats> {
+    const reader = fromUint8Array(car);
+    const blocks = new Map<string, Uint8Array>();
+    for (const entry of reader) blocks.set(cidToString(entry.cid), entry.bytes);
+
+    const root = reader.roots[0];
+    if (!root) throw new Error("CAR has no root");
+    const commit = cborDecode(blocks.get(root.$link)!) as { data: { $link: string }; rev?: string };
+
+    const stats: IndexStats = { artists: 0, albums: 0, songs: 0, scrobbles: 0 };
+    const ops: { type: "put"; key: string; value: string }[] = [];
+
+    for (const [path, valueLink] of walkMst(blocks, commit.data.$link)) {
+      const slash = path.indexOf("/");
+      if (slash < 0) continue;
+      const col = path.slice(0, slash);
+      const rkey = path.slice(slash + 1);
+      if (col !== C_ARTIST && col !== C_ALBUM && col !== C_SONG && col !== C_SCROBBLE) continue;
+      const recBytes = blocks.get(valueLink);
+      if (!recBytes) continue;
+      const rec = cborDecode(recBytes) as Record<string, unknown>;
+      const primary = primaryFor(did, col, rec);
+      if (!primary) continue;
+      const uri = `at://${did}/${col}/${rkey}`;
+      ops.push({ type: "put", key: primary, value: uri });
+      ops.push({ type: "put", key: `${SEP}rk${SEP}${did}${SEP}${col}${SEP}${rkey}`, value: primary });
+      if (col === C_ARTIST) stats.artists++;
+      else if (col === C_ALBUM) stats.albums++;
+      else if (col === C_SONG) stats.songs++;
+      else stats.scrobbles++;
+    }
+    if (commit.rev) ops.push({ type: "put", key: `${SEP}meta${SEP}rev${SEP}${did}`, value: commit.rev });
+    await this.db.batch(ops);
+    return stats;
+  }
+
+  /** Apply a single Jetstream commit event to the index. */
+  async applyCommit(
+    did: string,
+    col: string,
+    operation: string,
+    rkey: string,
+    record: Record<string, unknown> | undefined,
+  ): Promise<void> {
+    if (operation === "create" || operation === "update") {
+      if (!record) return;
+      const primary = primaryFor(did, col, record);
+      if (!primary) return;
+      await this.putPrimary(did, col, primary, `at://${did}/${col}/${rkey}`);
+    } else if (operation === "delete") {
+      const rk = `${SEP}rk${SEP}${did}${SEP}${col}${SEP}${rkey}`;
+      const primary = await this.get(rk);
+      if (primary) {
+        await this.db.batch([
+          { type: "del", key: primary },
+          { type: "del", key: rk },
+        ]);
+      }
+    }
+  }
+}
+
+// In-order MST traversal, reconstructing each leaf's full key. Yields
+// [path, recordCidString]. Skips CIDs absent from `blocks`.
+function* walkMst(blocks: Map<string, Uint8Array>, cid: string): Generator<[string, string]> {
+  const raw = blocks.get(cid);
+  if (!raw) return;
+  const node = cborDecode(raw) as {
+    l?: { $link: string } | null;
+    e: { p: number; k: unknown; v: { $link: string }; t?: { $link: string } | null }[];
+  };
+  if (node.l && isCidLink(node.l)) yield* walkMst(blocks, node.l.$link);
+  let last = new Uint8Array(0);
+  for (const e of node.e) {
+    const suffix = isBytes(e.k) ? fromBytes(e.k) : (e.k as Uint8Array);
+    const key = new Uint8Array(e.p + suffix.length);
+    key.set(last.subarray(0, e.p), 0);
+    key.set(suffix, e.p);
+    yield [new TextDecoder().decode(key), e.v.$link];
+    last = key;
+    if (e.t && isCidLink(e.t)) yield* walkMst(blocks, e.t.$link);
+  }
+}

package/src/errors.ts

@@ -1,47 +1,10 @@
+/** Error thrown when a Rocksky XRPC call returns a non-2xx `{ error, message }`. */
 export class RockskyError extends Error {
-  readonly cause?: unknown;
-  constructor(message: string, options?: { cause?: unknown }) {
-    super(message);
+  readonly kind?: string;
+  constructor(payload: unknown) {
+    const p = payload as { error?: string; message?: string } | undefined;
+    super(p?.message || p?.error || "rocksky request failed");
     this.name = "RockskyError";
-    this.cause = options?.cause;
-  }
-}
-
-export class RockskyHttpError extends RockskyError {
-  readonly status: number;
-  readonly statusText: string;
-  readonly url: string;
-  readonly body: unknown;
-
-  constructor(args: {
-    status: number;
-    statusText: string;
-    url: string;
-    body: unknown;
-    message?: string;
-  }) {
-    const message =
-      args.message ??
-      `Rocksky API ${args.status} ${args.statusText} at ${args.url}`;
-    super(message);
-    this.name = "RockskyHttpError";
-    this.status = args.status;
-    this.statusText = args.statusText;
-    this.url = args.url;
-    this.body = args.body;
-  }
-}
-
-export class RockskyTimeoutError extends RockskyError {
-  constructor(ms: number) {
-    super(`Rocksky request timed out after ${ms}ms`);
-    this.name = "RockskyTimeoutError";
-  }
-}
-
-export class RockskyAuthError extends RockskyError {
-  constructor(message = "Authentication required") {
-    super(message);
-    this.name = "RockskyAuthError";
+    this.kind = p?.error;
   }
 }

package/src/generated/types.ts

@@ -874,6 +874,11 @@ export interface GetArtistTracksParams {
   offset?: number;
 }
 
+export interface GetAudioSettingsParams {
+  /** DID or handle of the user whose settings to fetch. Required for unauthenticated requests. */
+  did?: AtIdentifier;
+}
+
 export interface GetCurrentlyPlayingParams {
   playerId?: string;
   /** Handle or DID of the actor to retrieve the currently playing track for. If not provided, defaults to the current user. */
@@ -1412,6 +1417,17 @@ export interface ProfileRecord {
   createdAt?: DateTime;
 }
 
+export interface PutAudioSettingsInput {
+  /** Crossfade settings to apply. */
+  crossfade?: RockboxCrossfadeSettings;
+  /** Equalizer settings to apply. */
+  equalizer?: RockboxEqualizerSettings;
+  /** Replay gain settings to apply. */
+  replayGain?: RockboxReplayGainSettings;
+  /** Tone control settings to apply. */
+  tone?: RockboxToneSettings;
+}
+
 export interface PutMirrorSourceInput {
   /** One of: lastfm, listenbrainz, tealfm */
   provider: string;
@@ -1506,6 +1522,74 @@ export interface ReportShoutInput {
   reason?: string;
 }
 
+export interface RockboxCrossfadeSettings {
+  /** Crossfade mode: disabled | enabled | shuffle | albumChange | trackChange */
+  mode?: string;
+  /** Fade-in delay in ms */
+  fadeInDelay?: number;
+  /** Fade-in duration in ms */
+  fadeInDuration?: number;
+  /** Fade-out delay in ms */
+  fadeOutDelay?: number;
+  /** Fade-out duration in ms */
+  fadeOutDuration?: number;
+  /** Fade-out mix mode: crossfade | mix */
+  fadeOutMixMode?: string;
+}
+
+export interface RockboxEqualizerBand {
+  /** Center frequency in Hz */
+  frequency: number;
+  /** Band gain in tenths of dB (e.g. 30 = +3.0 dB) */
+  gain: number;
+  /** Q factor × 10 (e.g. 7 = Q 0.7) */
+  q: number;
+}
+
+export interface RockboxEqualizerSettings {
+  /** Whether the equalizer is enabled */
+  enabled?: boolean;
+  /** Pre-amplification cut in tenths of dB applied before EQ bands (e.g. -60 = -6.0 dB) */
+  precut?: number;
+  /** Up to 10 EQ bands */
+  bands?: RockboxEqualizerBand[];
+}
+
+export interface RockboxReplayGainSettings {
+  /** Replay gain mode: disabled | track | album | trackIfShuffling */
+  mode?: string;
+  /** Pre-amplification in tenths of dB (e.g. 15 = +1.5 dB) */
+  preamp?: number;
+  /** Whether to prevent clipping by reducing volume */
+  preventClipping?: boolean;
+}
+
+export interface RockboxSettingsView {
+  /** Crossfade settings */
+  crossfade?: RockboxCrossfadeSettings;
+  /** Equalizer settings */
+  equalizer?: RockboxEqualizerSettings;
+  /** Replay gain settings */
+  replayGain?: RockboxReplayGainSettings;
+  /** Tone control settings (bass, treble, balance, channels) */
+  tone?: RockboxToneSettings;
+  /** When this settings record was first created. */
+  createdAt: DateTime;
+  /** When this settings record was last updated. */
+  updatedAt?: DateTime;
+}
+
+export interface RockboxToneSettings {
+  /** Bass level in dB */
+  bass?: number;
+  /** Treble level in dB */
+  treble?: number;
+  /** Left/right balance. Negative = left, positive = right */
+  balance?: number;
+  /** Channel configuration: stereo | mono | monoLeft | monoRight | karaoke | wide */
+  channels?: string;
+}
+
 export interface ScrobbleFirstScrobbleView {
   /** The handle of the user who first scrobbled this song. */
   handle?: string;
@@ -1573,26 +1657,32 @@ export interface ScrobbleRecord {
 export interface ScrobbleViewBasic {
   /** The unique identifier of the scrobble. */
   id?: string;
-  /** The handle of the user who created the scrobble. */
-  user?: string;
-  /** The display name of the user who created the scrobble. */
-  userDisplayName?: string;
-  /** The avatar URL of the user who created the scrobble. */
-  userAvatar?: Uri;
+  /** The unique identifier of the track this scrobble is of. */
+  trackId?: string;
   /** The title of the scrobble. */
   title?: string;
   /** The artist of the song. */
   artist?: string;
   /** The URI of the artist. */
   artistUri?: AtUri;
+  /** The album artist of the song. */
+  albumArtist?: string;
   /** The album of the song. */
   album?: string;
   /** The URI of the album. */
   albumUri?: AtUri;
   /** The album art URL of the song. */
-  cover?: Uri;
+  albumArt?: Uri;
+  /** The URI of the track (song) this scrobble is of. */
+  trackUri?: AtUri;
+  /** The handle of the user who created the scrobble. */
+  handle?: string;
+  /** The DID of the user who created the scrobble. */
+  did?: AtIdentifier;
+  /** The avatar URL of the user who created the scrobble. */
+  avatar?: Uri;
   /** The timestamp when the scrobble was created. */
-  date?: DateTime;
+  createdAt?: DateTime;
   /** The URI of the scrobble. */
   uri?: Uri;
   /** The SHA256 hash of the scrobble data. */
@@ -1646,6 +1736,21 @@ export interface SeekParams {
   position: number;
 }
 
+export interface SettingsRecord {
+  /** Crossfade settings */
+  crossfade?: RockboxCrossfadeSettings;
+  /** Equalizer settings */
+  equalizer?: RockboxEqualizerSettings;
+  /** Replay gain settings */
+  replayGain?: RockboxReplayGainSettings;
+  /** Tone control settings (bass, treble, balance, channels) */
+  tone?: RockboxToneSettings;
+  /** When this settings record was first created. */
+  createdAt: DateTime;
+  /** When this settings record was last updated. */
+  updatedAt?: DateTime;
+}
+
 export interface ShoutAuthor {
   /** The unique identifier of the author. */
   id?: string;
@@ -2118,6 +2223,8 @@ export interface Endpoints {
   "app.rocksky.playlist.removePlaylist": void;
   "app.rocksky.playlist.removeTrack": void;
   "app.rocksky.playlist.startPlaylist": void;
+  "app.rocksky.rockbox.getAudioSettings": RockboxSettingsView;
+  "app.rocksky.rockbox.putAudioSettings": RockboxSettingsView;
   "app.rocksky.scrobble.createScrobble": ScrobbleViewBasic;
   "app.rocksky.scrobble.getScrobble": ScrobbleViewDetailed;
   "app.rocksky.scrobble.getScrobbles": GetScrobblesOutput;

package/src/hash.ts

@@ -0,0 +1,22 @@
+import { createHash } from "node:crypto";
+
+// Lowercase-hex SHA-256 of s.toLowerCase() — the lowercasing is applied to the
+// whole string (not per field), matching Rocksky's server and every other SDK.
+function sha256Lower(s: string): string {
+  return createHash("sha256").update(s.toLowerCase()).digest("hex");
+}
+
+/** Identity hash of a song: sha256(lower("{title} - {artist} - {album}")). */
+export function songHash(title: string, artist: string, album: string): string {
+  return sha256Lower(`${title} - ${artist} - ${album}`);
+}
+
+/** Identity hash of an album: sha256(lower("{album} - {albumArtist}")). */
+export function albumHash(album: string, albumArtist: string): string {
+  return sha256Lower(`${album} - ${albumArtist}`);
+}
+
+/** Identity hash of an artist: sha256(lower(albumArtist)) — a single field. */
+export function artistHash(albumArtist: string): string {
+  return sha256Lower(albumArtist);
+}

package/src/index.ts

@@ -1,87 +1,18 @@
-export {
-  RockskyClient,
-  RockskyClientBuilder,
-  createClient,
-} from "./client.js";
-export {
-  RockskyError,
-  RockskyHttpError,
-  RockskyTimeoutError,
-  RockskyAuthError,
-} from "./errors.js";
-export {
-  pipe,
-  map,
-  tap,
-  withRetry,
-  withTimeout,
-  withFallback,
-  catchError,
-  type Op,
-} from "./pipe.js";
-export {
-  DEFAULT_BASE_URL,
-  type AuthProvider,
-  type ClientOptions,
-  type FetchLike,
-  type Json,
-  type Pagination,
-  type RequestOptions,
-} from "./types.js";
-export {
-  paginate,
-  type PageOpts,
-  type PageResult,
-  type PaginateArgs,
-} from "./paginate.js";
-export {
-  RealtimeClient,
-  RealtimeClientBuilder,
-  createRealtimeClient,
-  type RealtimeOptions,
-  type RealtimeEvent,
-  type RealtimeEventMap,
-  type ReconnectOptions,
-  type WebSocketCtor,
-  type WebSocketLike,
-} from "./realtime.js";
-
+/**
+ * @rocksky/sdk — the official TypeScript SDK for Rocksky, built on atcute.
+ *
+ * {@link RockskyClient} does unauthenticated AppView reads; {@link Agent} logs
+ * in with an app password and writes app.rocksky.* records to the user's PDS
+ * (scrobble, like, follow, shout, now-playing). With a {@link RockskyIndex}
+ * attached it prevents duplicates, backfilled from the repo CAR
+ * ({@link Agent.syncRepo}) and kept live off the Jetstream firehose
+ * ({@link Agent.hydrateFromJetstream}).
+ */
+export { RockskyClient, DEFAULT_APPVIEW, Interval } from "./client.js";
+export type { DateInterval } from "./client.js";
+export { Agent, type ScrobbleInput, type SongInput, type AlbumInput, type ArtistInput } from "./agent.js";
+export { RockskyIndex, totalIndexed, type IndexStats } from "./dedup.js";
+export { runJetstream, DEFAULT_JETSTREAM_SERVERS, type JetstreamOptions } from "./jetstream.js";
+export { songHash, albumHash, artistHash } from "./hash.js";
+export { RockskyError } from "./errors.js";
 export type * from "./generated/types.js";
-
-export type {
-  GetProfileParams,
-  ActorPagedParams,
-  ActorRangeParams,
-} from "./namespaces/actor.js";
-export type {
-  CreateScrobbleInput,
-  GetScrobblesParams,
-} from "./namespaces/scrobble.js";
-export type {
-  GetSongParams,
-  GetSongsParams,
-  MatchSongParams,
-  CreateSongInput,
-} from "./namespaces/song.js";
-export type { GetAlbumsParams } from "./namespaces/album.js";
-export type {
-  GetArtistsParams,
-  ArtistListenersParams,
-  GetArtistTracksParams,
-} from "./namespaces/artist.js";
-export type {
-  ListApikeysParams,
-  CreateApikeyInput,
-  UpdateApikeyInput,
-} from "./namespaces/apikey.js";
-export type {
-  ScrobblesChartParams,
-  TopChartParams,
-} from "./namespaces/charts.js";
-export type {
-  FollowListParams,
-  KnownFollowersParams,
-} from "./namespaces/graph.js";
-export type { RecommendParams } from "./namespaces/feed.js";
-export type { LikeInput } from "./namespaces/like.js";
-export type { PutMirrorSourceInput } from "./namespaces/mirror.js";

package/src/jetstream.ts

@@ -0,0 +1,122 @@
+import type { RockskyIndex } from "./dedup.js";
+
+/** The four public Bluesky Jetstream servers. */
+export const DEFAULT_JETSTREAM_SERVERS = [
+  "wss://jetstream1.us-east.bsky.network",
+  "wss://jetstream2.us-east.bsky.network",
+  "wss://jetstream1.us-west.bsky.network",
+  "wss://jetstream2.us-west.bsky.network",
+];
+
+const RECONNECT_SLACK_US = 5_000_000;
+
+export interface JetstreamOptions {
+  /** Servers to connect to at once (defaults to {@link DEFAULT_JETSTREAM_SERVERS}). */
+  servers?: string[];
+  /** Cancels the hydration and closes all connections when aborted. */
+  signal?: AbortSignal;
+}
+
+interface JetEvent {
+  did: string;
+  time_us: number;
+  kind: string;
+  commit?: {
+    operation: string;
+    collection: string;
+    rkey: string;
+    record?: Record<string, unknown>;
+  };
+}
+
+// A shared, mutable watermark — the highest time_us processed across sources.
+interface Watermark {
+  v: number;
+}
+
+/**
+ * Hydrate `idx` from the Bluesky Jetstream firehose for `did`, connecting to
+ * every server at once, filtered to app.rocksky.* + this DID. A shared watermark
+ * de-duplicates the overlap between servers and is the reconnect cursor. Resolves
+ * when opts.signal aborts; each source reconnects with backoff.
+ */
+export async function runJetstream(idx: RockskyIndex, did: string, opts: JetstreamOptions = {}): Promise<void> {
+  const servers = opts.servers ?? DEFAULT_JETSTREAM_SERVERS;
+  const wm: Watermark = { v: await idx.cursor(did) };
+  await Promise.all(servers.map((s) => sourceLoop(s, idx, did, wm, opts.signal)));
+}
+
+async function sourceLoop(server: string, idx: RockskyIndex, did: string, wm: Watermark, signal?: AbortSignal) {
+  while (!signal?.aborted) {
+    const cursor = Math.max(0, wm.v - RECONNECT_SLACK_US);
+    try {
+      await connect(subscribeURL(server, did, cursor), idx, did, wm, signal);
+    } catch {
+      // fall through to backoff
+    }
+    await sleep(2000, signal);
+  }
+}
+
+function connect(url: string, idx: RockskyIndex, did: string, wm: Watermark, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const ws = new WebSocket(url);
+    const onAbort = () => {
+      try {
+        ws.close();
+      } catch {
+        /* ignore */
+      }
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    const done = () => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    };
+
+    ws.onmessage = (ev: MessageEvent) => {
+      let event: JetEvent;
+      try {
+        event = JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data));
+      } catch {
+        return;
+      }
+      if (event.kind !== "commit" || event.did !== did || !event.commit) return;
+      // Claim this event for exactly one source (single-threaded: set before await).
+      if (event.time_us <= wm.v) return;
+      wm.v = event.time_us;
+      const c = event.commit;
+      void idx
+        .applyCommit(event.did, c.collection, c.operation, c.rkey, c.record)
+        .then(() => idx.setCursor(did, event.time_us))
+        .catch(() => {});
+    };
+    ws.onclose = done;
+    ws.onerror = () => {
+      try {
+        ws.close();
+      } catch {
+        /* ignore */
+      }
+      done();
+    };
+  });
+}
+
+function subscribeURL(server: string, did: string, cursorUS: number): string {
+  let u = `${server.replace(/\/+$/, "")}/subscribe?wantedCollections=app.rocksky.*&wantedDids=${encodeURIComponent(did)}`;
+  if (cursorUS > 0) u += `&cursor=${cursorUS}`;
+  return u;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) return resolve();
+    const t = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(t);
+      resolve();
+    }, { once: true });
+  });
+}