@nebutra/collab 0.2.1 → 0.2.3

package/dist/index.js

@@ -41,6 +41,10 @@ var Room = class {
       Y.applyUpdate(this.doc, update, REMOTE_ORIGIN);
     });
   }
+  tenantId;
+  roomId;
+  store;
+  transport;
   doc;
   listeners = /* @__PURE__ */ new Set();
   unsubTransport;
@@ -148,7 +152,8 @@ var Hub = class {
   }
   async doctor() {
     const start = Date.now();
-    let yjs = { ok: false, detail: "" };
+    let yjsOk = false;
+    let yjsDetail = "";
     try {
       const Y2 = await import("yjs");
       const probe = new Y2.Doc();
@@ -158,27 +163,27 @@ var Hub = class {
       const ok = restored.getMap("p").get("k") === 1;
       probe.destroy();
       restored.destroy();
-      yjs = {
-        ok,
-        detail: ok ? "Yjs encode/apply round-trip succeeded." : "Yjs round-trip produced unexpected state."
-      };
+      yjsOk = ok;
+      yjsDetail = ok ? "Yjs encode/apply round-trip succeeded." : "Yjs round-trip produced unexpected state.";
     } catch (e) {
-      yjs = { ok: false, detail: `Yjs unavailable: ${String(e)}` };
+      yjsDetail = `Yjs unavailable: ${String(e)}`;
     }
-    let store = { ok: false, detail: "" };
+    const yjs = { ok: yjsOk, detail: yjsDetail };
+    let storeOk = false;
+    let storeDetail = "";
     try {
       const probe = new Uint8Array([7, 7, 7]);
       await this.store.save("__collab_doctor__", "__probe__", probe);
       const back = await this.store.load("__collab_doctor__", "__probe__");
       const ok = !!back && back.length === probe.length && back[0] === 7;
-      store = {
-        ok,
-        detail: ok ? "SnapshotStore save/load round-trip succeeded." : "SnapshotStore returned unexpected bytes."
-      };
+      storeOk = ok;
+      storeDetail = ok ? "SnapshotStore save/load round-trip succeeded." : "SnapshotStore returned unexpected bytes.";
     } catch (e) {
-      store = { ok: false, detail: `SnapshotStore error: ${String(e)}` };
+      storeDetail = `SnapshotStore error: ${String(e)}`;
     }
-    let transport = { ok: false, detail: "" };
+    const store = { ok: storeOk, detail: storeDetail };
+    let transportOk = false;
+    let transportDetail = "";
     try {
       let received = false;
       const off = this.transport.subscribe("__collab_doctor__", "__probe__", () => {
@@ -186,13 +191,12 @@ var Hub = class {
       });
       await this.transport.broadcast("__collab_doctor__", "__probe__", new Uint8Array([1]));
       off();
-      transport = {
-        ok: received,
-        detail: received ? "Transport broadcast/subscribe round-trip succeeded." : "Transport did not deliver the probe (network adapter may be async)."
-      };
+      transportOk = received;
+      transportDetail = received ? "Transport broadcast/subscribe round-trip succeeded." : "Transport did not deliver the probe (network adapter may be async).";
     } catch (e) {
-      transport = { ok: false, detail: `Transport error: ${String(e)}` };
+      transportDetail = `Transport error: ${String(e)}`;
     }
+    const transport = { ok: transportOk, detail: transportDetail };
     return {
       ok: yjs.ok && store.ok && transport.ok,
       durationMs: Date.now() - start,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/errors.ts","../src/room.ts","../src/hub.ts"],"sourcesContent":["/**\n * Every failure surfaced by this package is a `CollabError`. The contract is\n * deliberately strict: a machine-stable `code` and a human-actionable\n * `suggestion` are MANDATORY, so no code path can throw a bare `Error` that\n * leaves a caller without a remediation hint.\n *\n * Mechanics (code/suggestion/toJSON/empty-suggestion fallback) are inherited\n * from the shared `@nebutra/capability-kit` `CapabilityError`; this subclass\n * only pins collab's error name + its package-specific fallback wording, so\n * the observable contract is unchanged.\n */\n\nimport { CapabilityError } from \"@nebutra/capability-kit\";\n\nexport type CollabErrorCode =\n  | \"COLLAB_INVALID_TENANT\"\n  | \"COLLAB_INVALID_ROOM\"\n  | \"COLLAB_SNAPSHOT_FAILED\"\n  | \"COLLAB_RESTORE_FAILED\"\n  | \"COLLAB_DESTROYED\"\n  | \"COLLAB_TEST\"\n  | (string & {});\n\nexport interface CollabErrorInit {\n  readonly code: CollabErrorCode;\n  /** A non-empty, actionable remediation hint. */\n  readonly suggestion: string;\n  readonly cause?: unknown;\n}\n\nexport class CollabError extends CapabilityError {\n  declare readonly code: CollabErrorCode;\n\n  constructor(message: string, init: CollabErrorInit) {\n    super(message, init, {\n      name: \"CollabError\",\n      emptySuggestionFallback:\n        \"No suggestion was provided. This is a bug in @nebutra/collab — \" +\n        \"report it with the failing operation.\",\n    });\n  }\n}\n","/**\n * A single tenant-scoped CRDT room. One `Y.Doc` per (tenant, room). The hub\n * owns the partitioning; this class assumes its `tenantId`/`roomId` are\n * already the partition it belongs to and never reaches outside them.\n *\n * Snapshot persistence is serialized through `withTenantLock(tenantId,\n * roomId, ...)` borrowed from `@nebutra/tenant-store` rather than a\n * hand-rolled mutex — same primitive used by canvas/reel, so a future swap\n * to a distributed lock changes one place.\n */\n\nimport { withTenantLock } from \"@nebutra/tenant-store\";\nimport * as Y from \"yjs\";\nimport { CollabError } from \"./errors\";\nimport type { CollabRoom, CollabTransport, SnapshotStore, UpdateListener } from \"./types\";\n\n/** Origin tag used when applying remote updates so we don't echo them back. */\nconst REMOTE_ORIGIN = Symbol(\"collab.remote\");\n\nexport class Room implements CollabRoom {\n  readonly doc: Y.Doc;\n  private readonly listeners = new Set<UpdateListener>();\n  private readonly unsubTransport: () => void;\n  private destroyed = false;\n\n  constructor(\n    readonly tenantId: string,\n    readonly roomId: string,\n    private readonly store: SnapshotStore,\n    private readonly transport: CollabTransport,\n  ) {\n    this.doc = new Y.Doc();\n\n    // Fan local updates out to: registered listeners + the transport. The\n    // transport echo is guarded by origin so a remote-applied update is not\n    // re-broadcast into a loop.\n    this.doc.on(\"update\", (update: Uint8Array, origin: unknown) => {\n      for (const cb of [...this.listeners]) cb(update, origin);\n      if (origin !== REMOTE_ORIGIN) {\n        void Promise.resolve(this.transport.broadcast(this.tenantId, this.roomId, update)).catch(\n          () => {\n            // Transport delivery is best-effort; CRDT state stays correct and\n            // converges on the next exchanged update. Swallowing here avoids\n            // an unhandled rejection from a flaky network adapter.\n          },\n        );\n      }\n    });\n\n    // Remote updates for THIS tenant-scoped channel only.\n    this.unsubTransport = this.transport.subscribe(this.tenantId, this.roomId, (update) => {\n      if (this.destroyed) return;\n      Y.applyUpdate(this.doc, update, REMOTE_ORIGIN);\n    });\n  }\n\n  applyUpdate(update: Uint8Array, origin?: unknown): void {\n    this.assertLive();\n    Y.applyUpdate(this.doc, update, origin);\n  }\n\n  encodeState(): Uint8Array {\n    this.assertLive();\n    return Y.encodeStateAsUpdate(this.doc);\n  }\n\n  onUpdate(cb: UpdateListener): () => void {\n    this.assertLive();\n    this.listeners.add(cb);\n    return () => {\n      this.listeners.delete(cb);\n    };\n  }\n\n  async snapshot(): Promise<void> {\n    this.assertLive();\n    const state = this.encodeState();\n    try {\n      // Serialize concurrent snapshots of the SAME room; different rooms (or\n      // the same room under another tenant) persist in parallel.\n      await withTenantLock(this.tenantId, this.roomId, () =>\n        this.store.save(this.tenantId, this.roomId, state),\n      );\n    } catch (cause) {\n      throw new CollabError(`Failed to persist snapshot for room \"${this.roomId}\".`, {\n        code: \"COLLAB_SNAPSHOT_FAILED\",\n        suggestion:\n          \"Verify the configured SnapshotStore is reachable (DB/Redis up, \" +\n          \"credentials valid). The in-memory default never fails; a custom \" +\n          \"adapter likely threw.\",\n        cause,\n      });\n    }\n  }\n\n  /** Hydrate this doc from persisted state, if any. Internal to the hub. */\n  async _restore(): Promise<void> {\n    try {\n      const persisted = await this.store.load(this.tenantId, this.roomId);\n      if (persisted) Y.applyUpdate(this.doc, persisted, REMOTE_ORIGIN);\n    } catch (cause) {\n      throw new CollabError(`Failed to restore room \"${this.roomId}\" from snapshot store.`, {\n        code: \"COLLAB_RESTORE_FAILED\",\n        suggestion:\n          \"Check the SnapshotStore adapter's load() — it should resolve \" +\n          \"null (not throw) when no snapshot exists for the tenant+room.\",\n        cause,\n      });\n    }\n  }\n\n  destroy(): void {\n    if (this.destroyed) return;\n    this.destroyed = true;\n    this.unsubTransport();\n    this.listeners.clear();\n    this.doc.destroy();\n  }\n\n  private assertLive(): void {\n    if (this.destroyed) {\n      throw new CollabError(`Room \"${this.roomId}\" was destroyed and can no longer be used.`, {\n        code: \"COLLAB_DESTROYED\",\n        suggestion:\n          \"Acquire a fresh room via hub.room(tenantId, roomId) instead of \" +\n          \"reusing a destroyed instance.\",\n      });\n    }\n  }\n}\n","/**\n * `CollabHub` — the tenant-partition boundary.\n *\n * TENANT ISOLATION IS STRUCTURAL: rooms are stored in a `Map` keyed by a\n * composite `tenantId\u0000roomId` string with a NUL separator that cannot\n * appear in a normal id. There is no API that takes only a roomId, so a key\n * minted for tenant A is unreachable from tenant B — a room handle is only\n * ever produced by passing an explicit `tenantId`, and the snapshot store +\n * transport are likewise addressed by (tenantId, roomId). The same property\n * a Prisma adapter gets from RLS is enforced here by the composite key, with\n * no trust placed in caller-supplied payload.\n */\n\nimport { CollabError } from \"./errors\";\nimport { Room } from \"./room\";\nimport { InMemorySnapshotStore } from \"./store/memory\";\nimport { LoopbackTransport } from \"./transport/loopback\";\nimport type {\n  CollabConfig,\n  CollabHub,\n  CollabRoom,\n  CollabTransport,\n  DoctorReport,\n  SnapshotStore,\n} from \"./types\";\n\n// NUL separator: it cannot appear in a normal tenant/room id, so the pairs\n// (\"a\",\"bc\") and (\"ab\",\"c\") can never collide into the same room key — the\n// tenant partition is exact, not merely conventional.\nconst KEY_SEP = \"\u0000\";\n\nfunction roomKey(tenantId: string, roomId: string): string {\n  return `${tenantId}${KEY_SEP}${roomId}`;\n}\n\nfunction assertId(value: string, kind: \"tenant\" | \"room\"): void {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new CollabError(`A non-empty ${kind}Id is required.`, {\n      code: kind === \"tenant\" ? \"COLLAB_INVALID_TENANT\" : \"COLLAB_INVALID_ROOM\",\n      suggestion:\n        kind === \"tenant\"\n          ? \"Pass the current tenant id, e.g. from getCurrentTenant().tenantId — \" +\n            \"never call room() without an explicit tenant.\"\n          : \"Pass a stable, non-empty roomId (document/canvas id).\",\n    });\n  }\n}\n\nclass Hub implements CollabHub {\n  private readonly rooms = new Map<string, Room>();\n  private readonly store: SnapshotStore;\n  private readonly transport: CollabTransport;\n\n  constructor(config: CollabConfig = {}) {\n    this.store = config.store ?? new InMemorySnapshotStore();\n    this.transport = config.transport ?? new LoopbackTransport();\n  }\n\n  room(tenantId: string, roomId: string): CollabRoom {\n    assertId(tenantId, \"tenant\");\n    assertId(roomId, \"room\");\n    const key = roomKey(tenantId, roomId);\n    let room = this.rooms.get(key);\n    if (!room) {\n      room = new Room(tenantId, roomId, this.store, this.transport);\n      this.rooms.set(key, room);\n    }\n    return room;\n  }\n\n  async roomRestored(tenantId: string, roomId: string): Promise<CollabRoom> {\n    const key = roomKey(tenantId, roomId);\n    const existed = this.rooms.has(key);\n    const room = this.room(tenantId, roomId) as Room;\n    // Only hydrate a freshly created room; an already-live room is the\n    // authoritative in-memory state.\n    if (!existed) await room._restore();\n    return room;\n  }\n\n  async doctor(): Promise<DoctorReport> {\n    const start = Date.now();\n\n    // 1. Yjs presence + a real round-trip (not just \"is it imported\").\n    let yjs = { ok: false, detail: \"\" };\n    try {\n      const Y = await import(\"yjs\");\n      const probe = new Y.Doc();\n      probe.getMap(\"p\").set(\"k\", 1);\n      const restored = new Y.Doc();\n      Y.applyUpdate(restored, Y.encodeStateAsUpdate(probe));\n      const ok = restored.getMap(\"p\").get(\"k\") === 1;\n      probe.destroy();\n      restored.destroy();\n      yjs = {\n        ok,\n        detail: ok\n          ? \"Yjs encode/apply round-trip succeeded.\"\n          : \"Yjs round-trip produced unexpected state.\",\n      };\n    } catch (e) {\n      yjs = { ok: false, detail: `Yjs unavailable: ${String(e)}` };\n    }\n\n    // 2. Store health — write+read under a reserved diagnostic tenant.\n    let store = { ok: false, detail: \"\" };\n    try {\n      const probe = new Uint8Array([7, 7, 7]);\n      await this.store.save(\"__collab_doctor__\", \"__probe__\", probe);\n      const back = await this.store.load(\"__collab_doctor__\", \"__probe__\");\n      const ok = !!back && back.length === probe.length && back[0] === 7;\n      store = {\n        ok,\n        detail: ok\n          ? \"SnapshotStore save/load round-trip succeeded.\"\n          : \"SnapshotStore returned unexpected bytes.\",\n      };\n    } catch (e) {\n      store = { ok: false, detail: `SnapshotStore error: ${String(e)}` };\n    }\n\n    // 3. Transport health — subscribe, broadcast, observe, unsubscribe.\n    let transport = { ok: false, detail: \"\" };\n    try {\n      let received = false;\n      const off = this.transport.subscribe(\"__collab_doctor__\", \"__probe__\", () => {\n        received = true;\n      });\n      await this.transport.broadcast(\"__collab_doctor__\", \"__probe__\", new Uint8Array([1]));\n      off();\n      transport = {\n        ok: received,\n        detail: received\n          ? \"Transport broadcast/subscribe round-trip succeeded.\"\n          : \"Transport did not deliver the probe (network adapter may be async).\",\n      };\n    } catch (e) {\n      transport = { ok: false, detail: `Transport error: ${String(e)}` };\n    }\n\n    return {\n      ok: yjs.ok && store.ok && transport.ok,\n      durationMs: Date.now() - start,\n      checks: { yjs, store, transport },\n    };\n  }\n\n  destroy(): void {\n    for (const room of this.rooms.values()) room.destroy();\n    this.rooms.clear();\n  }\n}\n\n/** Synchronous factory. */\nexport function createCollab(config?: CollabConfig): CollabHub {\n  return new Hub(config);\n}\n\n/**\n * Async factory mirroring other Sailor integration packages. There is no\n * env/credential negotiation for the zero-config defaults, so this resolves\n * immediately — the async shape is reserved for future credentialed\n * store/transport providers without a breaking signature change.\n */\nexport async function getCollab(config?: CollabConfig): Promise<CollabHub> {\n  return createCollab(config);\n}\n"],"mappings":"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","names":["Y"]}
+{"version":3,"sources":["../src/errors.ts","../src/room.ts","../src/hub.ts"],"sourcesContent":["/**\n * Every failure surfaced by this package is a `CollabError`. The contract is\n * deliberately strict: a machine-stable `code` and a human-actionable\n * `suggestion` are MANDATORY, so no code path can throw a bare `Error` that\n * leaves a caller without a remediation hint.\n *\n * Mechanics (code/suggestion/toJSON/empty-suggestion fallback) are inherited\n * from the shared `@nebutra/capability-kit` `CapabilityError`; this subclass\n * only pins collab's error name + its package-specific fallback wording, so\n * the observable contract is unchanged.\n */\n\nimport { CapabilityError } from \"@nebutra/capability-kit\";\n\nexport type CollabErrorCode =\n  | \"COLLAB_INVALID_TENANT\"\n  | \"COLLAB_INVALID_ROOM\"\n  | \"COLLAB_SNAPSHOT_FAILED\"\n  | \"COLLAB_RESTORE_FAILED\"\n  | \"COLLAB_DESTROYED\"\n  | \"COLLAB_TEST\"\n  | (string & {});\n\nexport interface CollabErrorInit {\n  readonly code: CollabErrorCode;\n  /** A non-empty, actionable remediation hint. */\n  readonly suggestion: string;\n  readonly cause?: unknown;\n}\n\nexport class CollabError extends CapabilityError {\n  declare readonly code: CollabErrorCode;\n\n  constructor(message: string, init: CollabErrorInit) {\n    super(message, init, {\n      name: \"CollabError\",\n      emptySuggestionFallback:\n        \"No suggestion was provided. This is a bug in @nebutra/collab — \" +\n        \"report it with the failing operation.\",\n    });\n  }\n}\n","/**\n * A single tenant-scoped CRDT room. One `Y.Doc` per (tenant, room). The hub\n * owns the partitioning; this class assumes its `tenantId`/`roomId` are\n * already the partition it belongs to and never reaches outside them.\n *\n * Snapshot persistence is serialized through `withTenantLock(tenantId,\n * roomId, ...)` borrowed from `@nebutra/tenant-store` rather than a\n * hand-rolled mutex — same primitive used by canvas/reel, so a future swap\n * to a distributed lock changes one place.\n */\n\nimport { withTenantLock } from \"@nebutra/tenant-store\";\nimport * as Y from \"yjs\";\nimport { CollabError } from \"./errors\";\nimport type { CollabRoom, CollabTransport, SnapshotStore, UpdateListener } from \"./types\";\n\n/** Origin tag used when applying remote updates so we don't echo them back. */\nconst REMOTE_ORIGIN = Symbol(\"collab.remote\");\n\nexport class Room implements CollabRoom {\n  readonly doc: Y.Doc;\n  private readonly listeners = new Set<UpdateListener>();\n  private readonly unsubTransport: () => void;\n  private destroyed = false;\n\n  constructor(\n    readonly tenantId: string,\n    readonly roomId: string,\n    private readonly store: SnapshotStore,\n    private readonly transport: CollabTransport,\n  ) {\n    this.doc = new Y.Doc();\n\n    // Fan local updates out to: registered listeners + the transport. The\n    // transport echo is guarded by origin so a remote-applied update is not\n    // re-broadcast into a loop.\n    this.doc.on(\"update\", (update: Uint8Array, origin: unknown) => {\n      for (const cb of [...this.listeners]) cb(update, origin);\n      if (origin !== REMOTE_ORIGIN) {\n        void Promise.resolve(this.transport.broadcast(this.tenantId, this.roomId, update)).catch(\n          () => {\n            // Transport delivery is best-effort; CRDT state stays correct and\n            // converges on the next exchanged update. Swallowing here avoids\n            // an unhandled rejection from a flaky network adapter.\n          },\n        );\n      }\n    });\n\n    // Remote updates for THIS tenant-scoped channel only.\n    this.unsubTransport = this.transport.subscribe(this.tenantId, this.roomId, (update) => {\n      if (this.destroyed) return;\n      Y.applyUpdate(this.doc, update, REMOTE_ORIGIN);\n    });\n  }\n\n  applyUpdate(update: Uint8Array, origin?: unknown): void {\n    this.assertLive();\n    Y.applyUpdate(this.doc, update, origin);\n  }\n\n  encodeState(): Uint8Array {\n    this.assertLive();\n    return Y.encodeStateAsUpdate(this.doc);\n  }\n\n  onUpdate(cb: UpdateListener): () => void {\n    this.assertLive();\n    this.listeners.add(cb);\n    return () => {\n      this.listeners.delete(cb);\n    };\n  }\n\n  async snapshot(): Promise<void> {\n    this.assertLive();\n    const state = this.encodeState();\n    try {\n      // Serialize concurrent snapshots of the SAME room; different rooms (or\n      // the same room under another tenant) persist in parallel.\n      await withTenantLock(this.tenantId, this.roomId, () =>\n        this.store.save(this.tenantId, this.roomId, state),\n      );\n    } catch (cause) {\n      throw new CollabError(`Failed to persist snapshot for room \"${this.roomId}\".`, {\n        code: \"COLLAB_SNAPSHOT_FAILED\",\n        suggestion:\n          \"Verify the configured SnapshotStore is reachable (DB/Redis up, \" +\n          \"credentials valid). The in-memory default never fails; a custom \" +\n          \"adapter likely threw.\",\n        cause,\n      });\n    }\n  }\n\n  /** Hydrate this doc from persisted state, if any. Internal to the hub. */\n  async _restore(): Promise<void> {\n    try {\n      const persisted = await this.store.load(this.tenantId, this.roomId);\n      if (persisted) Y.applyUpdate(this.doc, persisted, REMOTE_ORIGIN);\n    } catch (cause) {\n      throw new CollabError(`Failed to restore room \"${this.roomId}\" from snapshot store.`, {\n        code: \"COLLAB_RESTORE_FAILED\",\n        suggestion:\n          \"Check the SnapshotStore adapter's load() — it should resolve \" +\n          \"null (not throw) when no snapshot exists for the tenant+room.\",\n        cause,\n      });\n    }\n  }\n\n  destroy(): void {\n    if (this.destroyed) return;\n    this.destroyed = true;\n    this.unsubTransport();\n    this.listeners.clear();\n    this.doc.destroy();\n  }\n\n  private assertLive(): void {\n    if (this.destroyed) {\n      throw new CollabError(`Room \"${this.roomId}\" was destroyed and can no longer be used.`, {\n        code: \"COLLAB_DESTROYED\",\n        suggestion:\n          \"Acquire a fresh room via hub.room(tenantId, roomId) instead of \" +\n          \"reusing a destroyed instance.\",\n      });\n    }\n  }\n}\n","/**\n * `CollabHub` — the tenant-partition boundary.\n *\n * TENANT ISOLATION IS STRUCTURAL: rooms are stored in a `Map` keyed by a\n * composite `tenantId\u0000roomId` string with a NUL separator that cannot\n * appear in a normal id. There is no API that takes only a roomId, so a key\n * minted for tenant A is unreachable from tenant B — a room handle is only\n * ever produced by passing an explicit `tenantId`, and the snapshot store +\n * transport are likewise addressed by (tenantId, roomId). The same property\n * a Prisma adapter gets from RLS is enforced here by the composite key, with\n * no trust placed in caller-supplied payload.\n */\n\nimport { CollabError } from \"./errors\";\nimport { Room } from \"./room\";\nimport { InMemorySnapshotStore } from \"./store/memory\";\nimport { LoopbackTransport } from \"./transport/loopback\";\nimport type {\n  CollabConfig,\n  CollabHub,\n  CollabRoom,\n  CollabTransport,\n  DoctorReport,\n  SnapshotStore,\n} from \"./types\";\n\n// NUL separator: it cannot appear in a normal tenant/room id, so the pairs\n// (\"a\",\"bc\") and (\"ab\",\"c\") can never collide into the same room key — the\n// tenant partition is exact, not merely conventional.\nconst KEY_SEP = \"\u0000\";\n\nfunction roomKey(tenantId: string, roomId: string): string {\n  return `${tenantId}${KEY_SEP}${roomId}`;\n}\n\nfunction assertId(value: string, kind: \"tenant\" | \"room\"): void {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new CollabError(`A non-empty ${kind}Id is required.`, {\n      code: kind === \"tenant\" ? \"COLLAB_INVALID_TENANT\" : \"COLLAB_INVALID_ROOM\",\n      suggestion:\n        kind === \"tenant\"\n          ? \"Pass the current tenant id, e.g. from getCurrentTenant().tenantId — \" +\n            \"never call room() without an explicit tenant.\"\n          : \"Pass a stable, non-empty roomId (document/canvas id).\",\n    });\n  }\n}\n\nclass Hub implements CollabHub {\n  private readonly rooms = new Map<string, Room>();\n  private readonly store: SnapshotStore;\n  private readonly transport: CollabTransport;\n\n  constructor(config: CollabConfig = {}) {\n    this.store = config.store ?? new InMemorySnapshotStore();\n    this.transport = config.transport ?? new LoopbackTransport();\n  }\n\n  room(tenantId: string, roomId: string): CollabRoom {\n    assertId(tenantId, \"tenant\");\n    assertId(roomId, \"room\");\n    const key = roomKey(tenantId, roomId);\n    let room = this.rooms.get(key);\n    if (!room) {\n      room = new Room(tenantId, roomId, this.store, this.transport);\n      this.rooms.set(key, room);\n    }\n    return room;\n  }\n\n  async roomRestored(tenantId: string, roomId: string): Promise<CollabRoom> {\n    const key = roomKey(tenantId, roomId);\n    const existed = this.rooms.has(key);\n    const room = this.room(tenantId, roomId) as Room;\n    // Only hydrate a freshly created room; an already-live room is the\n    // authoritative in-memory state.\n    if (!existed) await room._restore();\n    return room;\n  }\n\n  async doctor(): Promise<DoctorReport> {\n    const start = Date.now();\n\n    // 1. Yjs presence + a real round-trip (not just \"is it imported\").\n    let yjsOk = false;\n    let yjsDetail = \"\";\n    try {\n      const Y = await import(\"yjs\");\n      const probe = new Y.Doc();\n      probe.getMap(\"p\").set(\"k\", 1);\n      const restored = new Y.Doc();\n      Y.applyUpdate(restored, Y.encodeStateAsUpdate(probe));\n      const ok = restored.getMap(\"p\").get(\"k\") === 1;\n      probe.destroy();\n      restored.destroy();\n      yjsOk = ok;\n      yjsDetail = ok\n        ? \"Yjs encode/apply round-trip succeeded.\"\n        : \"Yjs round-trip produced unexpected state.\";\n    } catch (e) {\n      yjsDetail = `Yjs unavailable: ${String(e)}`;\n    }\n    const yjs = { ok: yjsOk, detail: yjsDetail };\n\n    // 2. Store health — write+read under a reserved diagnostic tenant.\n    let storeOk = false;\n    let storeDetail = \"\";\n    try {\n      const probe = new Uint8Array([7, 7, 7]);\n      await this.store.save(\"__collab_doctor__\", \"__probe__\", probe);\n      const back = await this.store.load(\"__collab_doctor__\", \"__probe__\");\n      const ok = !!back && back.length === probe.length && back[0] === 7;\n      storeOk = ok;\n      storeDetail = ok\n        ? \"SnapshotStore save/load round-trip succeeded.\"\n        : \"SnapshotStore returned unexpected bytes.\";\n    } catch (e) {\n      storeDetail = `SnapshotStore error: ${String(e)}`;\n    }\n    const store = { ok: storeOk, detail: storeDetail };\n\n    // 3. Transport health — subscribe, broadcast, observe, unsubscribe.\n    let transportOk = false;\n    let transportDetail = \"\";\n    try {\n      let received = false;\n      const off = this.transport.subscribe(\"__collab_doctor__\", \"__probe__\", () => {\n        received = true;\n      });\n      await this.transport.broadcast(\"__collab_doctor__\", \"__probe__\", new Uint8Array([1]));\n      off();\n      transportOk = received;\n      transportDetail = received\n        ? \"Transport broadcast/subscribe round-trip succeeded.\"\n        : \"Transport did not deliver the probe (network adapter may be async).\";\n    } catch (e) {\n      transportDetail = `Transport error: ${String(e)}`;\n    }\n    const transport = { ok: transportOk, detail: transportDetail };\n\n    return {\n      ok: yjs.ok && store.ok && transport.ok,\n      durationMs: Date.now() - start,\n      checks: { yjs, store, transport },\n    };\n  }\n\n  destroy(): void {\n    for (const room of this.rooms.values()) room.destroy();\n    this.rooms.clear();\n  }\n}\n\n/** Synchronous factory. */\nexport function createCollab(config?: CollabConfig): CollabHub {\n  return new Hub(config);\n}\n\n/**\n * Async factory mirroring other Sailor integration packages. There is no\n * env/credential negotiation for the zero-config defaults, so this resolves\n * immediately — the async shape is reserved for future credentialed\n * store/transport providers without a breaking signature change.\n */\nexport async function getCollab(config?: CollabConfig): Promise<CollabHub> {\n  return createCollab(config);\n}\n"],"mappings":"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","names":["Y"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebutra/collab",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Multi-tenant, transport-agnostic real-time collaborative sync layer: tenant-partitioned CRDT rooms (Yjs) with pluggable snapshot store + transport seams",
   "private": false,
   "license": "MIT",
@@ -10,20 +10,22 @@
     "category": "integrations",
     "summary": "Tenant-partitioned CRDT room manager (Yjs) with pluggable store + transport seams"
   },
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./store/memory": "./src/store/memory.ts",
-    "./transport/loopback": "./src/transport/loopback.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
   },
   "dependencies": {
     "yjs": "^13.6.30",
-    "@nebutra/capability-kit": "0.2.1",
-    "@nebutra/tenant-store": "0.2.1"
+    "@nebutra/tenant-store": "0.2.2",
+    "@nebutra/capability-kit": "0.2.4"
   },
   "devDependencies": {
-    "@types/node": "^22.19.15",
+    "@types/node": "^25.9.1",
     "@vitest/coverage-v8": "^4.0.18",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
@@ -41,6 +43,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "build": "tsup",
     "test": "vitest run",

package/.turbo/turbo-build.log

@@ -1,28 +0,0 @@
-
-> @nebutra/collab@0.2.1 build /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/integrations/collab
-> tsup
-
-CLI Building entry: src/index.ts, src/store/memory.ts, src/transport/loopback.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/integrations/collab/tsup.config.ts
-CLI Target: es2022
-CLI Cleaning output folder
-ESM Build start
-ESM dist/index.js                  6.98 KB
-ESM dist/store/memory.js           134.00 B
-ESM dist/transport/loopback.js     128.00 B
-ESM dist/chunk-6XHNO2RP.js         581.00 B
-ESM dist/chunk-S2HTNEZN.js         817.00 B
-ESM dist/index.js.map              16.53 KB
-ESM dist/store/memory.js.map       71.00 B
-ESM dist/transport/loopback.js.map 71.00 B
-ESM dist/chunk-6XHNO2RP.js.map     2.04 KB
-ESM dist/chunk-S2HTNEZN.js.map     2.46 KB
-ESM ⚡️ Build success in 127ms
-DTS Build start
-DTS ⚡️ Build success in 15811ms
-DTS dist/index.d.ts              2.68 KB
-DTS dist/store/memory.d.ts       1.04 KB
-DTS dist/transport/loopback.d.ts 1005.00 B
-DTS dist/types-68zA3h9k.d.ts     2.27 KB

package/.turbo/turbo-test.log

@@ -1,14 +0,0 @@
-
-> @nebutra/collab@0.2.1 test /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/integrations/collab
-> vitest run
-
-
- RUN  v4.1.4 /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/integrations/collab
-
- ✓ src/__tests__/collab.test.ts (14 tests) 94ms
-
- Test Files  1 passed (1)
-      Tests  14 passed (14)
-   Start at  08:15:01
-   Duration  1.74s (transform 596ms, setup 0ms, import 859ms, tests 94ms, environment 0ms)
-

package/.turbo/turbo-typecheck.log

@@ -1,4 +0,0 @@
-
-> @nebutra/collab@0.2.1 typecheck /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/integrations/collab
-> tsc --noEmit
-

package/examples/snapshot-restore.ts

@@ -1,39 +0,0 @@
-/**
- * Example 3 — snapshot + restore across hub lifetimes.
- *
- * Persist a room via the injected SnapshotStore, then hydrate a brand-new
- * hub from the same store. Demonstrates the persist-then-reload contract
- * used by long-lived documents/canvases.
- *
- * Run: pnpm --filter @nebutra/collab exec tsx examples/snapshot-restore.ts
- */
-
-import { createCollab } from "../src/index";
-import { InMemorySnapshotStore } from "../src/store/memory";
-
-export async function main(): Promise<void> {
-  // A shared store stands in for Prisma/Redis in production.
-  const store = new InMemorySnapshotStore();
-
-  const hub1 = createCollab({ store });
-  const r1 = hub1.room("t1", "doc-1");
-  r1.doc.getText("body").insert(0, "persisted across restarts");
-  await r1.snapshot();
-  hub1.destroy();
-
-  // New process / new hub, same store.
-  const hub2 = createCollab({ store });
-  const r2 = await hub2.roomRestored("t1", "doc-1");
-  const restored = r2.doc.getText("body").toString();
-  if (restored !== "persisted across restarts") {
-    throw new Error(`restore failed, got: "${restored}"`);
-  }
-
-  // eslint-disable-next-line no-console
-  console.warn(`[collab] restored after reload: "${restored}"`);
-  hub2.destroy();
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  void main();
-}

package/examples/tenant-isolation.ts

@@ -1,42 +0,0 @@
-/**
- * Example 2 — tenant isolation (security-critical).
- *
- * Two tenants use the SAME roomId. Their docs, snapshot state and transport
- * channels are hard-partitioned: tenant A's edits are unreachable from
- * tenant B even though the room id string is identical.
- *
- * Run: pnpm --filter @nebutra/collab exec tsx examples/tenant-isolation.ts
- */
-
-import { getCollab } from "../src/index";
-
-export async function main(): Promise<void> {
-  const hub = await getCollab();
-
-  const roomId = "shared-room-id";
-  const a = hub.room("tenantA", roomId);
-  const b = hub.room("tenantB", roomId);
-
-  if (a.doc === b.doc) throw new Error("tenant partition breached: shared doc");
-
-  const leaked: unknown[] = [];
-  b.onUpdate((u) => leaked.push(u));
-
-  a.doc.getMap("m").set("secret", "A-only");
-  await a.snapshot();
-
-  if (b.doc.getMap("m").get("secret") !== undefined) {
-    throw new Error("tenant partition breached: B saw A's value");
-  }
-  if (leaked.length !== 0) {
-    throw new Error("tenant partition breached: B received A's update");
-  }
-
-  // eslint-disable-next-line no-console
-  console.warn("[collab] tenant isolation holds: B never observed A");
-  hub.destroy();
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  void main();
-}

package/examples/zero-config-convergence.ts

@@ -1,43 +0,0 @@
-/**
- * Example 1 — zero-config CRDT convergence.
- *
- * No env, no config, real (non-mock) Yjs behaviour. This file is also the
- * in-package REAL CALLER of the exported `getCollab` factory that keeps
- * `@nebutra/collab` in the `active` tier of the three-tier module lifecycle.
- *
- * Run: pnpm --filter @nebutra/collab exec tsx examples/zero-config-convergence.ts
- */
-
-import * as Y from "yjs";
-import { getCollab } from "../src/index";
-
-export async function main(): Promise<void> {
-  const hub = await getCollab();
-
-  // Two clients on the SAME tenant + room.
-  const a = hub.room("t1", "doc-1");
-  const b = hub.room("t1", "doc-1");
-  if (a !== b) throw new Error("same (tenant,room) must yield same instance");
-
-  // A standalone peer doc simulating a second device.
-  const peer = new Y.Doc();
-  a.doc.getText("body").insert(0, "Hello ");
-  Y.applyUpdate(peer, a.encodeState());
-
-  peer.getText("body").insert(6, "collab");
-  a.applyUpdate(Y.encodeStateAsUpdate(peer));
-  Y.applyUpdate(peer, a.encodeState());
-
-  const converged = a.doc.getText("body").toString();
-  if (converged !== peer.getText("body").toString()) {
-    throw new Error("clients did not converge");
-  }
-
-  // eslint-disable-next-line no-console
-  console.warn(`[collab] converged text: "${converged}"`);
-  hub.destroy();
-}
-
-if (import.meta.url === `file://${process.argv[1]}`) {
-  void main();
-}

package/src/__tests__/collab.test.ts

@@ -1,240 +0,0 @@
-import { _resetTenantLocks } from "@nebutra/tenant-store";
-import { beforeEach, describe, expect, it } from "vitest";
-import * as Y from "yjs";
-import { CollabError, createCollab } from "../index";
-import { InMemorySnapshotStore } from "../store/memory";
-import { LoopbackTransport } from "../transport/loopback";
-
-describe("CRDT convergence", () => {
-  beforeEach(() => _resetTenantLocks());
-
-  it("two clients editing the SAME room converge to identical state", async () => {
-    const hub = createCollab();
-    const a = hub.room("t1", "r1");
-
-    // A separate client doc, simulating a remote peer on the same logical room.
-    const peer = new Y.Doc();
-
-    // Edit on hub side.
-    a.doc.getMap("m").set("from", "a");
-    // Ship A's update to the peer.
-    peer.transact(() => Y.applyUpdate(peer, a.encodeState()));
-
-    // Peer edits concurrently.
-    peer.getMap("m").set("from", "b-peer");
-    peer.getArray("list").push([1, 2, 3]);
-
-    // Exchange peer -> A.
-    a.applyUpdate(Y.encodeStateAsUpdate(peer));
-    // Exchange A -> peer (A may have other state).
-    Y.applyUpdate(peer, a.encodeState());
-
-    // Both sides must converge to identical serialized state.
-    const aState = JSON.stringify(a.doc.getMap("m").toJSON());
-    const peerState = JSON.stringify(peer.getMap("m").toJSON());
-    expect(aState).toBe(peerState);
-    expect(a.doc.getArray("list").toJSON()).toEqual([1, 2, 3]);
-  });
-});
-
-describe("tenant isolation (security-critical)", () => {
-  beforeEach(() => _resetTenantLocks());
-
-  it("room(tenantA) and room(tenantB) with same roomId are independent docs", () => {
-    const hub = createCollab();
-    const a = hub.room("tenantA", "r1");
-    const b = hub.room("tenantB", "r1");
-
-    expect(a.doc).not.toBe(b.doc);
-
-    a.doc.getMap("m").set("secret", "A-only");
-    // B's room must NEVER observe A's update.
-    expect(b.doc.getMap("m").get("secret")).toBeUndefined();
-  });
-
-  it("an update applied to A's room never appears in B's room", () => {
-    const hub = createCollab();
-    const a = hub.room("tenantA", "r1");
-    const b = hub.room("tenantB", "r1");
-
-    const seenByB: Uint8Array[] = [];
-    b.onUpdate((u) => seenByB.push(u));
-
-    a.doc.getMap("m").set("x", 1);
-    a.applyUpdate(Y.encodeStateAsUpdate(a.doc));
-
-    expect(seenByB).toHaveLength(0);
-    expect(b.doc.getMap("m").get("x")).toBeUndefined();
-  });
-
-  it("snapshot store for tenant A never returns tenant B state", async () => {
-    const store = new InMemorySnapshotStore();
-    const hub = createCollab({ store });
-
-    const a = hub.room("tenantA", "shared-room-id");
-    a.doc.getMap("m").set("owner", "A");
-    await a.snapshot();
-
-    // B asks for the SAME roomId — must get nothing from A.
-    const bState = await store.load("tenantB", "shared-room-id");
-    expect(bState).toBeNull();
-
-    const aState = await store.load("tenantA", "shared-room-id");
-    expect(aState).not.toBeNull();
-  });
-
-  it("returns the SAME room instance for repeated (tenant, room) calls", () => {
-    const hub = createCollab();
-    expect(hub.room("t1", "r1")).toBe(hub.room("t1", "r1"));
-    expect(hub.room("t1", "r1")).not.toBe(hub.room("t2", "r1"));
-  });
-});
-
-describe("transport-driven convergence", () => {
-  beforeEach(() => _resetTenantLocks());
-
-  it("separate hubs sharing a transport converge for the same tenant+room", () => {
-    const transport = new LoopbackTransport();
-    const hubA = createCollab({ transport });
-    const hubB = createCollab({ transport });
-    const ra = hubA.room("t1", "r1");
-    const rb = hubB.room("t1", "r1");
-
-    ra.doc.getMap("m").set("k", "v");
-    expect(rb.doc.getMap("m").get("k")).toBe("v");
-
-    // Reverse direction also converges (origin guard prevents a loop).
-    rb.doc.getArray("l").push([42]);
-    expect(ra.doc.getArray("l").toJSON()).toEqual([42]);
-
-    hubA.destroy();
-    hubB.destroy();
-  });
-
-  it("a destroyed room throws CollabError COLLAB_DESTROYED", () => {
-    const hub = createCollab();
-    const r = hub.room("t1", "r1");
-    r.destroy();
-    try {
-      r.encodeState();
-      throw new Error("should have thrown");
-    } catch (e) {
-      expect(e).toBeInstanceOf(CollabError);
-      expect((e as CollabError).code).toBe("COLLAB_DESTROYED");
-      expect((e as CollabError).suggestion.length).toBeGreaterThan(0);
-    }
-  });
-});
-
-describe("restore / snapshot failure surfaces CollabError", () => {
-  beforeEach(() => _resetTenantLocks());
-
-  it("roomRestored wraps a throwing store load", async () => {
-    const store = {
-      load: async () => {
-        throw new Error("db down");
-      },
-      save: async () => {},
-    };
-    const hub = createCollab({ store });
-    try {
-      await hub.roomRestored("t1", "r1");
-      throw new Error("should have thrown");
-    } catch (e) {
-      expect(e).toBeInstanceOf(CollabError);
-      expect((e as CollabError).code).toBe("COLLAB_RESTORE_FAILED");
-      expect((e as CollabError).suggestion.length).toBeGreaterThan(0);
-    }
-  });
-
-  it("snapshot wraps a throwing store save", async () => {
-    const store = {
-      load: async () => null,
-      save: async () => {
-        throw new Error("disk full");
-      },
-    };
-    const hub = createCollab({ store });
-    const r = hub.room("t1", "r1");
-    r.doc.getMap("m").set("a", 1);
-    try {
-      await r.snapshot();
-      throw new Error("should have thrown");
-    } catch (e) {
-      expect(e).toBeInstanceOf(CollabError);
-      expect((e as CollabError).code).toBe("COLLAB_SNAPSHOT_FAILED");
-      expect((e as CollabError).suggestion.length).toBeGreaterThan(0);
-    }
-  });
-});
-
-describe("snapshot + restore", () => {
-  beforeEach(() => _resetTenantLocks());
-
-  it("snapshot() then reload restores doc state", async () => {
-    const store = new InMemorySnapshotStore();
-    const hub1 = createCollab({ store });
-    const r1 = hub1.room("t1", "doc1");
-    r1.doc.getText("body").insert(0, "hello world");
-    await r1.snapshot();
-
-    // Fresh hub, same store — must hydrate from snapshot.
-    const hub2 = createCollab({ store });
-    const r2 = await hub2.roomRestored("t1", "doc1");
-    expect(r2.doc.getText("body").toString()).toBe("hello world");
-  });
-});
-
-describe("onUpdate subscription", () => {
-  beforeEach(() => _resetTenantLocks());
-
-  it("unsubscribe stops further callbacks", () => {
-    const hub = createCollab();
-    const r = hub.room("t1", "r1");
-    const seen: number[] = [];
-    const off = r.onUpdate(() => seen.push(1));
-
-    r.doc.getMap("m").set("a", 1);
-    expect(seen).toHaveLength(1);
-
-    off();
-    r.doc.getMap("m").set("b", 2);
-    expect(seen).toHaveLength(1);
-  });
-});
-
-describe("CollabError", () => {
-  it("carries a non-empty suggestion and a code", () => {
-    const err = new CollabError("something failed", {
-      code: "COLLAB_TEST",
-      suggestion: "do the thing differently",
-    });
-    expect(err).toBeInstanceOf(Error);
-    expect(err.code).toBe("COLLAB_TEST");
-    expect(err.suggestion.length).toBeGreaterThan(0);
-  });
-
-  it("throws CollabError with suggestion on empty tenantId", () => {
-    const hub = createCollab();
-    try {
-      hub.room("", "r1");
-      throw new Error("should have thrown");
-    } catch (e) {
-      expect(e).toBeInstanceOf(CollabError);
-      expect((e as CollabError).suggestion.length).toBeGreaterThan(0);
-    }
-  });
-});
-
-describe("doctor()", () => {
-  it("returns a structured health report in <3s", async () => {
-    const hub = createCollab();
-    const start = Date.now();
-    const report = await hub.doctor();
-    expect(Date.now() - start).toBeLessThan(3000);
-    expect(report.ok).toBe(true);
-    expect(report.checks.yjs.ok).toBe(true);
-    expect(report.checks.store.ok).toBe(true);
-    expect(report.checks.transport.ok).toBe(true);
-  });
-});

package/src/cli.ts

@@ -1,27 +0,0 @@
-/**
- * collab CLI — `doctor` (Yjs/store/transport health) and `debug <roomId>`
- * (open a real zero-config room, apply an update, report convergence state).
- * The doctor/debug argv switch is the shared `@nebutra/capability-kit`
- * runner; only the collab-specific probes live here.
- */
-
-import { runCapabilityCli } from "@nebutra/capability-kit";
-import { getCollab } from "./index";
-
-const hub = await getCollab();
-
-await runCapabilityCli({
-  capability: "collab",
-  doctor: () => hub.doctor(),
-  debug: (roomId?: string) => {
-    const tenantId = "debug-tenant";
-    const id = roomId ?? "debug-room";
-    const room = hub.room(tenantId, id);
-    const before = room.encodeState().length;
-    room.doc.getText("debug").insert(0, "hello canvas");
-    const after = room.encodeState().length;
-    const text = room.doc.getText("debug").toString();
-    room.destroy();
-    return { tenantId, roomId: id, encodedBytes: { before, after }, text };
-  },
-});