@sobree/collab-providers 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 sobree.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @sobree/collab-providers
+
+Yjs provider helpers for [`@sobree/core`](https://www.npmjs.com/package/@sobree/core).
+
+→ Docs: **[docs.sobree.dev/api/collab-providers](https://docs.sobree.dev/api/collab-providers/)**
+
+Sobree's editor is backed by a `Y.Doc` (the Yjs CRDT) — see
+`editor.ydoc`. This package wraps the canonical Yjs providers in
+narrow, normalized factories so attaching persistence /
+collaboration is a 5-line job.
+
+## Install
+
+```sh
+pnpm add @sobree/core @sobree/collab-providers
+```
+
+Then install **only** the underlying provider you actually use — they're
+optional peer deps:
+
+```sh
+pnpm add y-websocket   # for real-time collaboration
+pnpm add y-indexeddb   # for local persistence
+pnpm add y-webrtc      # for peer-to-peer ad-hoc collab
+```
+
+## Usage
+
+### Real-time collaboration (`y-websocket`)
+
+```ts
+import * as Y from "yjs";
+import { createSobree } from "@sobree/core";
+import { attachWebsocketProvider } from "@sobree/collab-providers";
+
+const ydoc = new Y.Doc();
+const handle = await attachWebsocketProvider(ydoc, {
+  url: "wss://collab.example.com",
+  room: "doc-q2-brief",
+  name: "Alice",
+  color: "#f59e0b",
+});
+
+await handle.synced; // optional — wait for initial state from peers
+
+const editor = createSobree("#editor", { ydoc });
+```
+
+### Local persistence (`y-indexeddb`)
+
+```ts
+import * as Y from "yjs";
+import { createSobree } from "@sobree/core";
+import { attachIndexedDBProvider } from "@sobree/collab-providers";
+
+const ydoc = new Y.Doc();
+const handle = await attachIndexedDBProvider(ydoc, { dbName: "doc-q2-brief" });
+await handle.synced; // load persisted snapshot
+
+const editor = createSobree("#editor", { ydoc });
+```
+
+### Peer-to-peer (`y-webrtc`)
+
+```ts
+import * as Y from "yjs";
+import { attachWebRTCProvider } from "@sobree/collab-providers";
+
+const ydoc = new Y.Doc();
+const handle = await attachWebRTCProvider(ydoc, {
+  room: "doc-q2-brief",
+  password: "shared-secret-please",
+});
+```
+
+Best for small (≤4 peer) ad-hoc collab where you don't want a relay
+server. For more peers / persistence / authoritative state, use
+`attachWebsocketProvider` against `@sobree/collab-server`.
+
+### In-memory loopback (tests / demos)
+
+```ts
+import { loopback } from "@sobree/collab-providers";
+const { a, b, destroy } = loopback();
+// a and b are two Y.Docs that auto-sync. Use a as one editor's ydoc,
+// b as another's; mutations on either propagate.
+```
+
+## CollabHandle
+
+Every factory returns the same shape:
+
+```ts
+interface CollabHandle {
+  readonly provider: unknown;          // peek for advanced provider-specific methods
+  readonly awareness: Awareness | null; // null for y-indexeddb (no presence channel)
+  readonly synced: Promise<void>;      // resolves after initial sync
+  destroy(): void;                     // disconnect + remove listeners
+}
+```
+
+## License
+
+MIT.

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @sobree/collab-providers — thin Yjs provider helpers for @sobree/core.
+ *
+ * Each helper is a one-line factory around the canonical Yjs provider
+ * (`y-websocket`, `y-indexeddb`, `y-webrtc`). They normalize the
+ * different provider APIs to a single `CollabHandle` shape:
+ *
+ *   { provider, awareness, synced, destroy() }
+ *
+ * The underlying provider packages are **optional peer deps** —
+ * install only the ones you need. The factories lazy-import them and
+ * throw a clear error if missing.
+ *
+ * Plus an in-memory `loopback()` for tests / demos that wires two
+ * Y.Docs together with no network.
+ */
+export { attachWebsocketProvider } from './websocket';
+export type { WebsocketProviderOptions } from './websocket';
+export { attachIndexedDBProvider } from './indexeddb';
+export type { IndexedDBProviderOptions } from './indexeddb';
+export { attachWebRTCProvider } from './webrtc';
+export type { WebRTCProviderOptions } from './webrtc';
+export { loopback } from './loopback';
+export type { BasicProvider, CollabHandle, CollabSessionPayload, IdentityOptions, } from './types';

package/dist/index.js

@@ -0,0 +1,127 @@
+import * as i from "yjs";
+async function f(r, e) {
+  const a = await m(), t = e.params ?? {}, n = new a.WebsocketProvider(e.url, e.room, r, {
+    params: t,
+    connect: e.connect ?? !0
+  });
+  (e.name || e.color || e.userId) && n.awareness.setLocalStateField("user", {
+    id: e.userId ?? y(),
+    name: e.name ?? "Anonymous",
+    color: e.color ?? "#888"
+  });
+  const o = new Promise((c) => {
+    if (n.synced) {
+      c();
+      return;
+    }
+    const s = (d) => {
+      d && (n.off("sync", s), c());
+    };
+    n.on("sync", s);
+  });
+  return {
+    provider: n,
+    awareness: n.awareness,
+    synced: o,
+    destroy() {
+      n.disconnect(), n.destroy();
+    }
+  };
+}
+async function m() {
+  try {
+    return await import("y-websocket");
+  } catch (r) {
+    throw new Error(
+      "y-websocket is not installed. Run `pnpm add y-websocket` (or `npm install y-websocket`) and import this module again. See https://github.com/yjs/y-websocket.",
+      { cause: r }
+    );
+  }
+}
+function y() {
+  return Math.random().toString(36).slice(2, 10);
+}
+async function h(r, e) {
+  const a = await l(), t = new a.IndexeddbPersistence(e.dbName, r), n = new Promise((o) => {
+    t.once("synced", () => o());
+  });
+  return {
+    provider: t,
+    awareness: null,
+    synced: n,
+    destroy() {
+      t.destroy();
+    }
+  };
+}
+async function l() {
+  try {
+    return await import("y-indexeddb");
+  } catch (r) {
+    throw new Error(
+      "y-indexeddb is not installed. Run `pnpm add y-indexeddb` (or `npm install y-indexeddb`) and import this module again. See https://github.com/yjs/y-indexeddb.",
+      { cause: r }
+    );
+  }
+}
+async function p(r, e) {
+  const a = await w(), t = {};
+  e.password && (t.password = e.password), e.signaling && (t.signaling = e.signaling);
+  const n = new a.WebrtcProvider(e.room, r, t);
+  (e.name || e.color || e.userId) && n.awareness.setLocalStateField("user", {
+    id: e.userId ?? b(),
+    name: e.name ?? "Anonymous",
+    color: e.color ?? "#888"
+  });
+  const o = new Promise((c) => {
+    let s = !1;
+    const d = () => {
+      s || (s = !0, c());
+    };
+    n.on("peers", ({ added: u }) => {
+      u.length > 0 && d();
+    }), setTimeout(d, 1e3);
+  });
+  return {
+    provider: n,
+    awareness: n.awareness,
+    synced: o,
+    destroy() {
+      n.disconnect(), n.destroy();
+    }
+  };
+}
+async function w() {
+  try {
+    return await import("y-webrtc");
+  } catch (r) {
+    throw new Error(
+      "y-webrtc is not installed. Run `pnpm add y-webrtc` (or `npm install y-webrtc`) and import this module again. See https://github.com/yjs/y-webrtc.",
+      { cause: r }
+    );
+  }
+}
+function b() {
+  return Math.random().toString(36).slice(2, 10);
+}
+function g() {
+  const r = new i.Doc(), e = new i.Doc(), a = (n, o) => {
+    o !== "remote" && i.applyUpdate(e, n, "remote");
+  }, t = (n, o) => {
+    o !== "remote" && i.applyUpdate(r, n, "remote");
+  };
+  return r.on("update", a), e.on("update", t), {
+    a: r,
+    b: e,
+    destroy() {
+      r.off("update", a), e.off("update", t);
+    }
+  };
+}
+export {
+  h as attachIndexedDBProvider,
+  p as attachWebRTCProvider,
+  f as attachWebsocketProvider,
+  g as loopback
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/websocket.ts","../src/indexeddb.ts","../src/webrtc.ts","../src/loopback.ts"],"sourcesContent":["import type { CollabHandle, IdentityOptions } from \"./types\";\nimport type * as Y from \"yjs\";\n\nexport interface WebsocketProviderOptions extends IdentityOptions {\n  /** WebSocket server URL (e.g. `wss://collab.example.com`). The room\n   *  name is appended as a path. */\n  url: string;\n  /** Room name. Each room is one Y.Doc shared across peers. */\n  room: string;\n  /** Auth params appended to the WebSocket URL as query string. */\n  params?: Record<string, string>;\n  /** Connect immediately (default true). Set to false to call\n   *  `provider.connect()` manually. */\n  connect?: boolean;\n}\n\n/**\n * Attach a `y-websocket` provider to a Y.Doc.\n *\n * Requires `y-websocket` as a peer dep — install it explicitly:\n *\n * ```sh\n * pnpm add y-websocket\n * ```\n *\n * Returns a `CollabHandle` with the connected provider, awareness\n * (cursor / presence channel), and a `synced` promise that resolves\n * when the initial sync completes.\n *\n * Usage:\n *\n * ```ts\n * import * as Y from \"yjs\";\n * import { createSobree } from \"@sobree/core\";\n * import { attachWebsocketProvider } from \"@sobree/collab-providers\";\n *\n * const ydoc = new Y.Doc();\n * const handle = await attachWebsocketProvider(ydoc, {\n *   url: \"wss://collab.example.com\",\n *   room: \"doc-q2-brief\",\n *   name: \"Alice\",\n *   color: \"#f59e0b\",\n * });\n * const editor = createSobree(\"#editor\", { ydoc });\n *\n * // Later:\n * editor.destroy();\n * handle.destroy();\n * ydoc.destroy();\n * ```\n */\nexport async function attachWebsocketProvider(\n  ydoc: Y.Doc,\n  opts: WebsocketProviderOptions,\n): Promise<CollabHandle> {\n  const yws = await loadYWebsocket();\n  const params = opts.params ?? {};\n  const provider = new yws.WebsocketProvider(opts.url, opts.room, ydoc, {\n    params,\n    connect: opts.connect ?? true,\n  });\n\n  if (opts.name || opts.color || opts.userId) {\n    provider.awareness.setLocalStateField(\"user\", {\n      id: opts.userId ?? randomId(),\n      name: opts.name ?? \"Anonymous\",\n      color: opts.color ?? \"#888\",\n    });\n  }\n\n  const synced = new Promise<void>((resolve) => {\n    if (provider.synced) {\n      resolve();\n      return;\n    }\n    const handler = (isSynced: boolean) => {\n      if (isSynced) {\n        provider.off(\"sync\", handler);\n        resolve();\n      }\n    };\n    provider.on(\"sync\", handler);\n  });\n\n  return {\n    provider,\n    awareness: provider.awareness,\n    synced,\n    destroy(): void {\n      provider.disconnect();\n      provider.destroy();\n    },\n  };\n}\n\nasync function loadYWebsocket(): Promise<typeof import(\"y-websocket\")> {\n  try {\n    return await import(\"y-websocket\");\n  } catch (err) {\n    throw new Error(\n      \"y-websocket is not installed. Run `pnpm add y-websocket` (or `npm install y-websocket`) \" +\n        \"and import this module again. See https://github.com/yjs/y-websocket.\",\n      { cause: err },\n    );\n  }\n}\n\nfunction randomId(): string {\n  // Sufficient for awareness peer ids; not crypto.\n  return Math.random().toString(36).slice(2, 10);\n}\n","import type { CollabHandle } from \"./types\";\nimport type * as Y from \"yjs\";\n\nexport interface IndexedDBProviderOptions {\n  /** Database name. Each name is a separate IndexedDB store. Use one\n   *  per document if you want isolated persistence. */\n  dbName: string;\n}\n\n/**\n * Attach a `y-indexeddb` provider for local persistence. The Y.Doc's\n * state is stored in the browser's IndexedDB; reloading the page\n * restores the document.\n *\n * Requires `y-indexeddb` as a peer dep — install it explicitly:\n *\n * ```sh\n * pnpm add y-indexeddb\n * ```\n *\n * No awareness — local persistence only. The `synced` promise resolves\n * when the existing snapshot has been loaded into the Y.Doc.\n *\n * Usage:\n *\n * ```ts\n * import * as Y from \"yjs\";\n * import { createSobree } from \"@sobree/core\";\n * import { attachIndexedDBProvider } from \"@sobree/collab-providers\";\n *\n * const ydoc = new Y.Doc();\n * const handle = await attachIndexedDBProvider(ydoc, {\n *   dbName: \"doc-q2-brief\",\n * });\n * await handle.synced; // optional — wait for initial load\n * const editor = createSobree(\"#editor\", { ydoc });\n * ```\n */\nexport async function attachIndexedDBProvider(\n  ydoc: Y.Doc,\n  opts: IndexedDBProviderOptions,\n): Promise<CollabHandle> {\n  const yidb = await loadYIndexedDB();\n  const provider = new yidb.IndexeddbPersistence(opts.dbName, ydoc);\n\n  const synced = new Promise<void>((resolve) => {\n    provider.once(\"synced\", () => resolve());\n  });\n\n  return {\n    provider,\n    awareness: null,\n    synced,\n    destroy(): void {\n      provider.destroy();\n    },\n  };\n}\n\nasync function loadYIndexedDB(): Promise<typeof import(\"y-indexeddb\")> {\n  try {\n    return await import(\"y-indexeddb\");\n  } catch (err) {\n    throw new Error(\n      \"y-indexeddb is not installed. Run `pnpm add y-indexeddb` (or `npm install y-indexeddb`) \" +\n        \"and import this module again. See https://github.com/yjs/y-indexeddb.\",\n      { cause: err },\n    );\n  }\n}\n","import type { CollabHandle, IdentityOptions } from \"./types\";\nimport type * as Y from \"yjs\";\n\nexport interface WebRTCProviderOptions extends IdentityOptions {\n  /** Room name. Each room is one Y.Doc shared across peers. */\n  room: string;\n  /** Pre-shared room password. Optional but recommended for any\n   *  non-public collaboration. */\n  password?: string;\n  /** Custom signaling servers. Defaults to the public servers shipped\n   *  with `y-webrtc`; for production set up your own. */\n  signaling?: string[];\n}\n\n/**\n * Attach a `y-webrtc` provider — peer-to-peer collaboration, with a\n * tiny signaling server (or shared public ones) used only for initial\n * peer discovery.\n *\n * Requires `y-webrtc` as a peer dep — install it explicitly:\n *\n * ```sh\n * pnpm add y-webrtc\n * ```\n *\n * Best for small (≤4 peer) ad-hoc collaboration where you don't want\n * to host a relay server. For more peers / persistence /\n * authoritative state, use `attachWebsocketProvider` against\n * `@sobree/collab-server` (Phase 3).\n */\nexport async function attachWebRTCProvider(\n  ydoc: Y.Doc,\n  opts: WebRTCProviderOptions,\n): Promise<CollabHandle> {\n  const ywebrtc = await loadYWebRTC();\n  const providerOpts: Record<string, unknown> = {};\n  if (opts.password) providerOpts.password = opts.password;\n  if (opts.signaling) providerOpts.signaling = opts.signaling;\n\n  const provider = new ywebrtc.WebrtcProvider(opts.room, ydoc, providerOpts);\n\n  if (opts.name || opts.color || opts.userId) {\n    provider.awareness.setLocalStateField(\"user\", {\n      id: opts.userId ?? randomId(),\n      name: opts.name ?? \"Anonymous\",\n      color: opts.color ?? \"#888\",\n    });\n  }\n\n  // y-webrtc has no canonical 'synced' event (peer-to-peer; no\n  // single source of truth). Resolve once the first peer connects,\n  // or after a short timeout if we're alone in the room.\n  const synced = new Promise<void>((resolve) => {\n    let resolved = false;\n    const finish = () => {\n      if (!resolved) {\n        resolved = true;\n        resolve();\n      }\n    };\n    provider.on(\"peers\", ({ added }: { added: unknown[] }) => {\n      if (added.length > 0) finish();\n    });\n    setTimeout(finish, 1000);\n  });\n\n  return {\n    provider,\n    awareness: provider.awareness,\n    synced,\n    destroy(): void {\n      provider.disconnect();\n      provider.destroy();\n    },\n  };\n}\n\nasync function loadYWebRTC(): Promise<typeof import(\"y-webrtc\")> {\n  try {\n    return await import(\"y-webrtc\");\n  } catch (err) {\n    throw new Error(\n      \"y-webrtc is not installed. Run `pnpm add y-webrtc` (or `npm install y-webrtc`) \" +\n        \"and import this module again. See https://github.com/yjs/y-webrtc.\",\n      { cause: err },\n    );\n  }\n}\n\nfunction randomId(): string {\n  return Math.random().toString(36).slice(2, 10);\n}\n","import * as Y from \"yjs\";\n\n/**\n * Two Y.Docs wired together in-memory — useful for tests and demos.\n *\n * Constructs a pair: `{ a: Y.Doc, b: Y.Doc }`. Updates applied to `a`\n * automatically replicate to `b` and vice versa. No network involved.\n *\n * The returned `destroy()` removes both observers — the Y.Docs survive\n * for the caller to inspect / use. `.destroy()` on the docs themselves\n * still works the usual way.\n */\nexport function loopback(): {\n  a: Y.Doc;\n  b: Y.Doc;\n  destroy(): void;\n} {\n  const a = new Y.Doc();\n  const b = new Y.Doc();\n\n  const ab = (update: Uint8Array, origin: unknown) => {\n    if (origin === \"remote\") return;\n    Y.applyUpdate(b, update, \"remote\");\n  };\n  const ba = (update: Uint8Array, origin: unknown) => {\n    if (origin === \"remote\") return;\n    Y.applyUpdate(a, update, \"remote\");\n  };\n  a.on(\"update\", ab);\n  b.on(\"update\", ba);\n\n  return {\n    a,\n    b,\n    destroy(): void {\n      a.off(\"update\", ab);\n      b.off(\"update\", ba);\n    },\n  };\n}\n"],"names":["attachWebsocketProvider","ydoc","opts","yws","loadYWebsocket","params","provider","randomId","synced","resolve","handler","isSynced","err","attachIndexedDBProvider","yidb","loadYIndexedDB","attachWebRTCProvider","ywebrtc","loadYWebRTC","providerOpts","resolved","finish","added","loopback","a","Y","b","ab","update","origin","ba"],"mappings":";AAmDA,eAAsBA,EACpBC,GACAC,GACuB;AACvB,QAAMC,IAAM,MAAMC,EAAA,GACZC,IAASH,EAAK,UAAU,CAAA,GACxBI,IAAW,IAAIH,EAAI,kBAAkBD,EAAK,KAAKA,EAAK,MAAMD,GAAM;AAAA,IACpE,QAAAI;AAAA,IACA,SAASH,EAAK,WAAW;AAAA,EAAA,CAC1B;AAED,GAAIA,EAAK,QAAQA,EAAK,SAASA,EAAK,WAClCI,EAAS,UAAU,mBAAmB,QAAQ;AAAA,IAC5C,IAAIJ,EAAK,UAAUK,EAAA;AAAA,IACnB,MAAML,EAAK,QAAQ;AAAA,IACnB,OAAOA,EAAK,SAAS;AAAA,EAAA,CACtB;AAGH,QAAMM,IAAS,IAAI,QAAc,CAACC,MAAY;AAC5C,QAAIH,EAAS,QAAQ;AACnB,MAAAG,EAAA;AACA;AAAA,IACF;AACA,UAAMC,IAAU,CAACC,MAAsB;AACrC,MAAIA,MACFL,EAAS,IAAI,QAAQI,CAAO,GAC5BD,EAAA;AAAA,IAEJ;AACA,IAAAH,EAAS,GAAG,QAAQI,CAAO;AAAA,EAC7B,CAAC;AAED,SAAO;AAAA,IACL,UAAAJ;AAAA,IACA,WAAWA,EAAS;AAAA,IACpB,QAAAE;AAAA,IACA,UAAgB;AACd,MAAAF,EAAS,WAAA,GACTA,EAAS,QAAA;AAAA,IACX;AAAA,EAAA;AAEJ;AAEA,eAAeF,IAAwD;AACrE,MAAI;AACF,WAAO,MAAM,OAAO,aAAa;AAAA,EACnC,SAASQ,GAAK;AACZ,UAAM,IAAI;AAAA,MACR;AAAA,MAEA,EAAE,OAAOA,EAAA;AAAA,IAAI;AAAA,EAEjB;AACF;AAEA,SAASL,IAAmB;AAE1B,SAAO,KAAK,SAAS,SAAS,EAAE,EAAE,MAAM,GAAG,EAAE;AAC/C;ACxEA,eAAsBM,EACpBZ,GACAC,GACuB;AACvB,QAAMY,IAAO,MAAMC,EAAA,GACbT,IAAW,IAAIQ,EAAK,qBAAqBZ,EAAK,QAAQD,CAAI,GAE1DO,IAAS,IAAI,QAAc,CAACC,MAAY;AAC5C,IAAAH,EAAS,KAAK,UAAU,MAAMG,EAAA,CAAS;AAAA,EACzC,CAAC;AAED,SAAO;AAAA,IACL,UAAAH;AAAA,IACA,WAAW;AAAA,IACX,QAAAE;AAAA,IACA,UAAgB;AACd,MAAAF,EAAS,QAAA;AAAA,IACX;AAAA,EAAA;AAEJ;AAEA,eAAeS,IAAwD;AACrE,MAAI;AACF,WAAO,MAAM,OAAO,aAAa;AAAA,EACnC,SAASH,GAAK;AACZ,UAAM,IAAI;AAAA,MACR;AAAA,MAEA,EAAE,OAAOA,EAAA;AAAA,IAAI;AAAA,EAEjB;AACF;ACvCA,eAAsBI,EACpBf,GACAC,GACuB;AACvB,QAAMe,IAAU,MAAMC,EAAA,GAChBC,IAAwC,CAAA;AAC9C,EAAIjB,EAAK,aAAUiB,EAAa,WAAWjB,EAAK,WAC5CA,EAAK,cAAWiB,EAAa,YAAYjB,EAAK;AAElD,QAAMI,IAAW,IAAIW,EAAQ,eAAef,EAAK,MAAMD,GAAMkB,CAAY;AAEzE,GAAIjB,EAAK,QAAQA,EAAK,SAASA,EAAK,WAClCI,EAAS,UAAU,mBAAmB,QAAQ;AAAA,IAC5C,IAAIJ,EAAK,UAAUK,EAAA;AAAA,IACnB,MAAML,EAAK,QAAQ;AAAA,IACnB,OAAOA,EAAK,SAAS;AAAA,EAAA,CACtB;AAMH,QAAMM,IAAS,IAAI,QAAc,CAACC,MAAY;AAC5C,QAAIW,IAAW;AACf,UAAMC,IAAS,MAAM;AACnB,MAAKD,MACHA,IAAW,IACXX,EAAA;AAAA,IAEJ;AACA,IAAAH,EAAS,GAAG,SAAS,CAAC,EAAE,OAAAgB,QAAkC;AACxD,MAAIA,EAAM,SAAS,KAAGD,EAAA;AAAA,IACxB,CAAC,GACD,WAAWA,GAAQ,GAAI;AAAA,EACzB,CAAC;AAED,SAAO;AAAA,IACL,UAAAf;AAAA,IACA,WAAWA,EAAS;AAAA,IACpB,QAAAE;AAAA,IACA,UAAgB;AACd,MAAAF,EAAS,WAAA,GACTA,EAAS,QAAA;AAAA,IACX;AAAA,EAAA;AAEJ;AAEA,eAAeY,IAAkD;AAC/D,MAAI;AACF,WAAO,MAAM,OAAO,UAAU;AAAA,EAChC,SAASN,GAAK;AACZ,UAAM,IAAI;AAAA,MACR;AAAA,MAEA,EAAE,OAAOA,EAAA;AAAA,IAAI;AAAA,EAEjB;AACF;AAEA,SAASL,IAAmB;AAC1B,SAAO,KAAK,SAAS,SAAS,EAAE,EAAE,MAAM,GAAG,EAAE;AAC/C;AC/EO,SAASgB,IAId;AACA,QAAMC,IAAI,IAAIC,EAAE,IAAA,GACVC,IAAI,IAAID,EAAE,IAAA,GAEVE,IAAK,CAACC,GAAoBC,MAAoB;AAClD,IAAIA,MAAW,YACfJ,EAAE,YAAYC,GAAGE,GAAQ,QAAQ;AAAA,EACnC,GACME,IAAK,CAACF,GAAoBC,MAAoB;AAClD,IAAIA,MAAW,YACfJ,EAAE,YAAYD,GAAGI,GAAQ,QAAQ;AAAA,EACnC;AACA,SAAAJ,EAAE,GAAG,UAAUG,CAAE,GACjBD,EAAE,GAAG,UAAUI,CAAE,GAEV;AAAA,IACL,GAAAN;AAAA,IACA,GAAAE;AAAA,IACA,UAAgB;AACd,MAAAF,EAAE,IAAI,UAAUG,CAAE,GAClBD,EAAE,IAAI,UAAUI,CAAE;AAAA,IACpB;AAAA,EAAA;AAEJ;"}

package/dist/indexeddb.d.ts

@@ -0,0 +1,37 @@
+import { CollabHandle } from './types';
+import type * as Y from "yjs";
+export interface IndexedDBProviderOptions {
+    /** Database name. Each name is a separate IndexedDB store. Use one
+     *  per document if you want isolated persistence. */
+    dbName: string;
+}
+/**
+ * Attach a `y-indexeddb` provider for local persistence. The Y.Doc's
+ * state is stored in the browser's IndexedDB; reloading the page
+ * restores the document.
+ *
+ * Requires `y-indexeddb` as a peer dep — install it explicitly:
+ *
+ * ```sh
+ * pnpm add y-indexeddb
+ * ```
+ *
+ * No awareness — local persistence only. The `synced` promise resolves
+ * when the existing snapshot has been loaded into the Y.Doc.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import * as Y from "yjs";
+ * import { createSobree } from "@sobree/core";
+ * import { attachIndexedDBProvider } from "@sobree/collab-providers";
+ *
+ * const ydoc = new Y.Doc();
+ * const handle = await attachIndexedDBProvider(ydoc, {
+ *   dbName: "doc-q2-brief",
+ * });
+ * await handle.synced; // optional — wait for initial load
+ * const editor = createSobree("#editor", { ydoc });
+ * ```
+ */
+export declare function attachIndexedDBProvider(ydoc: Y.Doc, opts: IndexedDBProviderOptions): Promise<CollabHandle>;

package/dist/loopback.d.ts

@@ -0,0 +1,16 @@
+import * as Y from "yjs";
+/**
+ * Two Y.Docs wired together in-memory — useful for tests and demos.
+ *
+ * Constructs a pair: `{ a: Y.Doc, b: Y.Doc }`. Updates applied to `a`
+ * automatically replicate to `b` and vice versa. No network involved.
+ *
+ * The returned `destroy()` removes both observers — the Y.Docs survive
+ * for the caller to inspect / use. `.destroy()` on the docs themselves
+ * still works the usual way.
+ */
+export declare function loopback(): {
+    a: Y.Doc;
+    b: Y.Doc;
+    destroy(): void;
+};

package/dist/types.d.ts

@@ -0,0 +1,61 @@
+import type * as Y from "yjs";
+/**
+ * Common shape for every provider helper in this package. The
+ * underlying Yjs providers don't share an interface (each has its own
+ * connect / disconnect / awareness API), so we normalize to this
+ * triple. `provider` is typed as `unknown` deliberately — peek at it
+ * for provider-specific advanced use, but most callers should only
+ * need `awareness` and `destroy`.
+ */
+export interface CollabHandle {
+    /** The underlying Yjs provider instance. Type-cast to its concrete
+     *  type if you need provider-specific events / methods. */
+    readonly provider: unknown;
+    /** Awareness state (cursors, presence). May be `null` for providers
+     *  that don't expose awareness (e.g. `y-indexeddb`). */
+    readonly awareness: import('y-protocols/awareness').Awareness | null;
+    /** Resolves once the provider has finished its initial sync. For
+     *  network providers this means "caught up to the room"; for
+     *  `y-indexeddb` this means "loaded local snapshot". */
+    readonly synced: Promise<void>;
+    /** Tear down: disconnect, remove listeners. Idempotent. */
+    destroy(): void;
+}
+/** Bare-minimum shape Sobree needs from a provider. Useful for custom
+ *  providers (BroadcastChannel, MessagePort, in-memory test loopback). */
+export interface BasicProvider {
+    destroy(): void;
+}
+export interface IdentityOptions {
+    /** Stable id for this peer. Defaults to a random uuid per page load. */
+    userId?: string;
+    /** Display name shown to other peers in awareness. */
+    name?: string;
+    /** CSS color for the user's caret / range highlight. */
+    color?: string;
+}
+/** Optional first-class doc store on a Y.Doc — what `editor.ydoc` is. */
+export type AnyYDoc = Y.Doc;
+/**
+ * Session payload — Sobree-extension session message (type 2) sent
+ * by `@sobree/collab-server` immediately after a peer joins a room.
+ * Mirrors the type in `@sobree/collab-server`'s `protocol.ts`.
+ *
+ * Embedders connecting to a Sobree collab-server can read this via a
+ * custom y-websocket message handler; it tells the client whether
+ * the room was empty (safe to seed `initialDocument`) and whether
+ * they're allowed to mutate the document.
+ *
+ * See the collab-server README "leader election" section for the
+ * wire-level integration pattern.
+ */
+export interface CollabSessionPayload {
+    /** True iff the Y.Doc was empty when this peer joined. Only one
+     *  peer per fresh room sees this set. */
+    isEmpty: boolean;
+    /** Whether the server will accept Y sync-update messages from
+     *  this peer. */
+    isWritable: boolean;
+    /** Other peers currently in the room (excluding this one). */
+    peerCount: number;
+}

package/dist/webrtc.d.ts

@@ -0,0 +1,29 @@
+import { CollabHandle, IdentityOptions } from './types';
+import type * as Y from "yjs";
+export interface WebRTCProviderOptions extends IdentityOptions {
+    /** Room name. Each room is one Y.Doc shared across peers. */
+    room: string;
+    /** Pre-shared room password. Optional but recommended for any
+     *  non-public collaboration. */
+    password?: string;
+    /** Custom signaling servers. Defaults to the public servers shipped
+     *  with `y-webrtc`; for production set up your own. */
+    signaling?: string[];
+}
+/**
+ * Attach a `y-webrtc` provider — peer-to-peer collaboration, with a
+ * tiny signaling server (or shared public ones) used only for initial
+ * peer discovery.
+ *
+ * Requires `y-webrtc` as a peer dep — install it explicitly:
+ *
+ * ```sh
+ * pnpm add y-webrtc
+ * ```
+ *
+ * Best for small (≤4 peer) ad-hoc collaboration where you don't want
+ * to host a relay server. For more peers / persistence /
+ * authoritative state, use `attachWebsocketProvider` against
+ * `@sobree/collab-server` (Phase 3).
+ */
+export declare function attachWebRTCProvider(ydoc: Y.Doc, opts: WebRTCProviderOptions): Promise<CollabHandle>;

package/dist/websocket.d.ts

@@ -0,0 +1,50 @@
+import { CollabHandle, IdentityOptions } from './types';
+import type * as Y from "yjs";
+export interface WebsocketProviderOptions extends IdentityOptions {
+    /** WebSocket server URL (e.g. `wss://collab.example.com`). The room
+     *  name is appended as a path. */
+    url: string;
+    /** Room name. Each room is one Y.Doc shared across peers. */
+    room: string;
+    /** Auth params appended to the WebSocket URL as query string. */
+    params?: Record<string, string>;
+    /** Connect immediately (default true). Set to false to call
+     *  `provider.connect()` manually. */
+    connect?: boolean;
+}
+/**
+ * Attach a `y-websocket` provider to a Y.Doc.
+ *
+ * Requires `y-websocket` as a peer dep — install it explicitly:
+ *
+ * ```sh
+ * pnpm add y-websocket
+ * ```
+ *
+ * Returns a `CollabHandle` with the connected provider, awareness
+ * (cursor / presence channel), and a `synced` promise that resolves
+ * when the initial sync completes.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import * as Y from "yjs";
+ * import { createSobree } from "@sobree/core";
+ * import { attachWebsocketProvider } from "@sobree/collab-providers";
+ *
+ * const ydoc = new Y.Doc();
+ * const handle = await attachWebsocketProvider(ydoc, {
+ *   url: "wss://collab.example.com",
+ *   room: "doc-q2-brief",
+ *   name: "Alice",
+ *   color: "#f59e0b",
+ * });
+ * const editor = createSobree("#editor", { ydoc });
+ *
+ * // Later:
+ * editor.destroy();
+ * handle.destroy();
+ * ydoc.destroy();
+ * ```
+ */
+export declare function attachWebsocketProvider(ydoc: Y.Doc, opts: WebsocketProviderOptions): Promise<CollabHandle>;

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@sobree/collab-providers",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Yjs provider helpers for @sobree/core — y-websocket / y-indexeddb / y-webrtc factories with sane defaults. Optional. Bring your own provider if you prefer.",
+  "keywords": [
+    "sobree",
+    "wysiwyg",
+    "editor",
+    "yjs",
+    "collaboration",
+    "crdt",
+    "y-websocket",
+    "y-indexeddb",
+    "y-webrtc"
+  ],
+  "license": "MIT",
+  "author": "sobree.dev",
+  "homepage": "https://docs.sobree.dev/api/collab-providers/",
+  "bugs": {
+    "url": "https://github.com/khayll/sobree/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/khayll/sobree.git",
+    "directory": "packages/collab-providers"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "yjs": "^13.6.0",
+    "@sobree/core": "0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "y-websocket": {
+      "optional": true
+    },
+    "y-indexeddb": {
+      "optional": true
+    },
+    "y-webrtc": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "y-indexeddb": "^9.0.12",
+    "y-protocols": "^1.0.7",
+    "y-webrtc": "^10.3.0",
+    "y-websocket": "^3.0.0",
+    "@sobree/core": "0.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "build": "vite build",
+    "clean": "rm -rf dist"
+  }
+}