@fieldnotes/sync-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Irakli Iremashvili
+
+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,30 @@
+# @fieldnotes/sync-server
+
+Authoritative WebSocket relay server for [`@fieldnotes/sync`](../sync).
+
+The relay holds the canonical per-room canvas state and fans out element
+operations to every other connection in the room. Clients connect, request a
+snapshot to catch up, then stream `upsert` / `remove` / `clear` ops that the hub
+applies and forwards.
+
+## Pieces
+
+- **`SyncHub`** — transport-agnostic relay. Per-room canonical state lives behind
+  an async `HubBackend`; each room processes messages on its own serial queue so
+  concurrent edits to the same room never race, while different rooms run
+  independently.
+- **`MemoryHubBackend`** — in-memory `HubBackend` (the default). Redis-backed and
+  authenticated backends are planned.
+- **`createSyncServer`** — a runnable `ws` reference server. Connect with
+  `?room=<id>` in the query string; missing room closes the socket.
+
+## Usage
+
+```ts
+import { createSyncServer } from '@fieldnotes/sync-server';
+
+const { close } = createSyncServer({ port: 8080 });
+// ws://localhost:8080?room=my-room
+```
+
+Auth and a Redis `HubBackend` are upcoming.

package/dist/index.cjs

@@ -0,0 +1,162 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MemoryHubBackend: () => MemoryHubBackend,
+  SyncHub: () => SyncHub,
+  createSyncServer: () => createSyncServer
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/sync-hub.ts
+var import_sync2 = require("@fieldnotes/sync");
+
+// src/memory-hub-backend.ts
+var import_sync = require("@fieldnotes/sync");
+var MemoryHubBackend = class {
+  rooms = /* @__PURE__ */ new Map();
+  room(id) {
+    let r = this.rooms.get(id);
+    if (!r) {
+      r = /* @__PURE__ */ new Map();
+      this.rooms.set(id, r);
+    }
+    return r;
+  }
+  async snapshot(room) {
+    return [...this.room(room).values()];
+  }
+  async apply(room, op) {
+    (0, import_sync.applyOpToMap)(this.room(room), op);
+  }
+};
+
+// src/sync-hub.ts
+var HUB_FROM = "hub";
+var SyncHub = class {
+  backend;
+  conns = /* @__PURE__ */ new Map();
+  rooms = /* @__PURE__ */ new Map();
+  // room → connIds
+  roomQueues = /* @__PURE__ */ new Map();
+  // room → serial tail
+  constructor(options = {}) {
+    this.backend = options.backend ?? new MemoryHubBackend();
+  }
+  addConnection(conn) {
+    this.conns.set(conn.id, conn);
+    let set = this.rooms.get(conn.room);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.rooms.set(conn.room, set);
+    }
+    set.add(conn.id);
+  }
+  removeConnection(connId) {
+    const conn = this.conns.get(connId);
+    if (!conn) return;
+    this.conns.delete(connId);
+    const members = this.rooms.get(conn.room);
+    if (members) {
+      members.delete(connId);
+      if (members.size === 0) {
+        this.rooms.delete(conn.room);
+        this.roomQueues.delete(conn.room);
+      }
+    }
+  }
+  roomCount() {
+    return this.rooms.size;
+  }
+  handleMessage(connId, message) {
+    const conn = this.conns.get(connId);
+    if (!conn) return Promise.resolve();
+    const room = conn.room;
+    const prev = this.roomQueues.get(room) ?? Promise.resolve();
+    const next = prev.then(() => this.process(conn, message)).catch(() => {
+    });
+    this.roomQueues.set(room, next);
+    return next;
+  }
+  async process(conn, message) {
+    const env = (0, import_sync2.parseEnvelope)(message);
+    if (!env) return;
+    const op = env.op;
+    if (op.kind === "request-snapshot") {
+      const elements = await this.backend.snapshot(conn.room);
+      conn.send(
+        JSON.stringify({ from: HUB_FROM, op: { kind: "snapshot", to: env.from, elements } })
+      );
+    } else if (op.kind === "upsert" || op.kind === "remove" || op.kind === "clear") {
+      await this.backend.apply(conn.room, op);
+      const members = this.rooms.get(conn.room);
+      if (members) {
+        for (const id of members) {
+          if (id === conn.id) continue;
+          this.conns.get(id)?.send(message);
+        }
+      }
+    }
+  }
+};
+
+// src/create-sync-server.ts
+var import_ws = require("ws");
+function createSyncServer(options = {}) {
+  const hub = new SyncHub({ backend: options.backend });
+  const wss = options.server ? new import_ws.WebSocketServer({ server: options.server }) : new import_ws.WebSocketServer({ port: options.port ?? 0 });
+  let counter = 0;
+  wss.on("connection", (ws, req) => {
+    const url = new URL(req.url ?? "", "http://localhost");
+    const room = url.searchParams.get("room");
+    if (!room) {
+      ws.close(1008, "room required");
+      return;
+    }
+    const connId = `c${++counter}-${Math.random().toString(36).slice(2, 8)}`;
+    hub.addConnection({
+      id: connId,
+      room,
+      send: (m) => {
+        try {
+          ws.send(m);
+        } catch {
+        }
+      }
+    });
+    ws.on("message", (data) => {
+      void hub.handleMessage(connId, String(data)).catch((err) => console.error("[sync-server]", err));
+    });
+    ws.on("close", () => hub.removeConnection(connId));
+  });
+  return {
+    hub,
+    wss,
+    close: () => new Promise((resolve) => wss.close(() => resolve()))
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MemoryHubBackend,
+  SyncHub,
+  createSyncServer
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/sync-hub.ts","../src/memory-hub-backend.ts","../src/create-sync-server.ts"],"sourcesContent":["export { SyncHub } from './sync-hub';\nexport type { SyncHubOptions, Connection } from './sync-hub';\nexport { MemoryHubBackend } from './memory-hub-backend';\nexport type { HubBackend } from './hub-backend';\nexport { createSyncServer } from './create-sync-server';\nexport type { CreateSyncServerOptions } from './create-sync-server';\n","import { parseEnvelope } from '@fieldnotes/sync';\nimport { MemoryHubBackend } from './memory-hub-backend';\nimport type { HubBackend } from './hub-backend';\n\nexport interface Connection {\n  id: string;\n  room: string;\n  send(message: string): void;\n}\n\nexport interface SyncHubOptions {\n  backend?: HubBackend;\n}\n\nconst HUB_FROM = 'hub';\n\nexport class SyncHub {\n  private readonly backend: HubBackend;\n  private readonly conns = new Map<string, Connection>();\n  private readonly rooms = new Map<string, Set<string>>(); // room → connIds\n  private readonly roomQueues = new Map<string, Promise<void>>(); // room → serial tail\n\n  constructor(options: SyncHubOptions = {}) {\n    this.backend = options.backend ?? new MemoryHubBackend();\n  }\n\n  addConnection(conn: Connection): void {\n    this.conns.set(conn.id, conn);\n    let set = this.rooms.get(conn.room);\n    if (!set) {\n      set = new Set();\n      this.rooms.set(conn.room, set);\n    }\n    set.add(conn.id);\n  }\n\n  removeConnection(connId: string): void {\n    const conn = this.conns.get(connId);\n    if (!conn) return;\n    this.conns.delete(connId);\n    const members = this.rooms.get(conn.room);\n    if (members) {\n      members.delete(connId);\n      if (members.size === 0) {\n        this.rooms.delete(conn.room);\n        this.roomQueues.delete(conn.room);\n      }\n    }\n  }\n\n  roomCount(): number {\n    return this.rooms.size;\n  }\n\n  handleMessage(connId: string, message: string): Promise<void> {\n    const conn = this.conns.get(connId);\n    if (!conn) return Promise.resolve();\n    const room = conn.room;\n    const prev = this.roomQueues.get(room) ?? Promise.resolve();\n    const next = prev\n      .then(() => this.process(conn, message))\n      .catch(() => {\n        // swallow so one failed message never wedges the room's serial queue\n      });\n    this.roomQueues.set(room, next);\n    return next;\n  }\n\n  private async process(conn: Connection, message: string): Promise<void> {\n    const env = parseEnvelope(message);\n    if (!env) return;\n    const op = env.op;\n    if (op.kind === 'request-snapshot') {\n      const elements = await this.backend.snapshot(conn.room);\n      conn.send(\n        JSON.stringify({ from: HUB_FROM, op: { kind: 'snapshot', to: env.from, elements } }),\n      );\n    } else if (op.kind === 'upsert' || op.kind === 'remove' || op.kind === 'clear') {\n      await this.backend.apply(conn.room, op);\n      const members = this.rooms.get(conn.room);\n      if (members) {\n        for (const id of members) {\n          if (id === conn.id) continue;\n          this.conns.get(id)?.send(message);\n        }\n      }\n    }\n    // 'snapshot' from a client → ignored\n  }\n}\n","import { applyOpToMap, type SyncOp } from '@fieldnotes/sync';\nimport type { CanvasElement } from '@fieldnotes/core';\nimport type { HubBackend } from './hub-backend';\n\nexport class MemoryHubBackend implements HubBackend {\n  private rooms = new Map<string, Map<string, CanvasElement>>();\n\n  private room(id: string): Map<string, CanvasElement> {\n    let r = this.rooms.get(id);\n    if (!r) {\n      r = new Map();\n      this.rooms.set(id, r);\n    }\n    return r;\n  }\n\n  async snapshot(room: string): Promise<CanvasElement[]> {\n    return [...this.room(room).values()];\n  }\n\n  async apply(room: string, op: SyncOp): Promise<void> {\n    applyOpToMap(this.room(room), op);\n  }\n}\n","import { WebSocketServer } from 'ws';\nimport type { Server } from 'http';\nimport { SyncHub } from './sync-hub';\nimport type { HubBackend } from './hub-backend';\n\nexport interface CreateSyncServerOptions {\n  port?: number;\n  server?: Server;\n  backend?: HubBackend;\n}\n\nexport function createSyncServer(options: CreateSyncServerOptions = {}): {\n  hub: SyncHub;\n  wss: WebSocketServer;\n  close: () => Promise<void>;\n} {\n  const hub = new SyncHub({ backend: options.backend });\n  const wss = options.server\n    ? new WebSocketServer({ server: options.server })\n    : new WebSocketServer({ port: options.port ?? 0 });\n  let counter = 0;\n  wss.on('connection', (ws, req) => {\n    const url = new URL(req.url ?? '', 'http://localhost');\n    const room = url.searchParams.get('room');\n    if (!room) {\n      ws.close(1008, 'room required');\n      return;\n    }\n    const connId = `c${++counter}-${Math.random().toString(36).slice(2, 8)}`;\n    hub.addConnection({\n      id: connId,\n      room,\n      send: (m) => {\n        try {\n          ws.send(m);\n        } catch {\n          /* socket closed mid-send */\n        }\n      },\n    });\n    ws.on('message', (data) => {\n      void hub\n        .handleMessage(connId, String(data))\n        .catch((err) => console.error('[sync-server]', err));\n    });\n    ws.on('close', () => hub.removeConnection(connId));\n  });\n  return {\n    hub,\n    wss,\n    close: () => new Promise<void>((resolve) => wss.close(() => resolve())),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,IAAAA,eAA8B;;;ACA9B,kBAA0C;AAInC,IAAM,mBAAN,MAA6C;AAAA,EAC1C,QAAQ,oBAAI,IAAwC;AAAA,EAEpD,KAAK,IAAwC;AACnD,QAAI,IAAI,KAAK,MAAM,IAAI,EAAE;AACzB,QAAI,CAAC,GAAG;AACN,UAAI,oBAAI,IAAI;AACZ,WAAK,MAAM,IAAI,IAAI,CAAC;AAAA,IACtB;AACA,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,SAAS,MAAwC;AACrD,WAAO,CAAC,GAAG,KAAK,KAAK,IAAI,EAAE,OAAO,CAAC;AAAA,EACrC;AAAA,EAEA,MAAM,MAAM,MAAc,IAA2B;AACnD,kCAAa,KAAK,KAAK,IAAI,GAAG,EAAE;AAAA,EAClC;AACF;;;ADTA,IAAM,WAAW;AAEV,IAAM,UAAN,MAAc;AAAA,EACF;AAAA,EACA,QAAQ,oBAAI,IAAwB;AAAA,EACpC,QAAQ,oBAAI,IAAyB;AAAA;AAAA,EACrC,aAAa,oBAAI,IAA2B;AAAA;AAAA,EAE7D,YAAY,UAA0B,CAAC,GAAG;AACxC,SAAK,UAAU,QAAQ,WAAW,IAAI,iBAAiB;AAAA,EACzD;AAAA,EAEA,cAAc,MAAwB;AACpC,SAAK,MAAM,IAAI,KAAK,IAAI,IAAI;AAC5B,QAAI,MAAM,KAAK,MAAM,IAAI,KAAK,IAAI;AAClC,QAAI,CAAC,KAAK;AACR,YAAM,oBAAI,IAAI;AACd,WAAK,MAAM,IAAI,KAAK,MAAM,GAAG;AAAA,IAC/B;AACA,QAAI,IAAI,KAAK,EAAE;AAAA,EACjB;AAAA,EAEA,iBAAiB,QAAsB;AACrC,UAAM,OAAO,KAAK,MAAM,IAAI,MAAM;AAClC,QAAI,CAAC,KAAM;AACX,SAAK,MAAM,OAAO,MAAM;AACxB,UAAM,UAAU,KAAK,MAAM,IAAI,KAAK,IAAI;AACxC,QAAI,SAAS;AACX,cAAQ,OAAO,MAAM;AACrB,UAAI,QAAQ,SAAS,GAAG;AACtB,aAAK,MAAM,OAAO,KAAK,IAAI;AAC3B,aAAK,WAAW,OAAO,KAAK,IAAI;AAAA,MAClC;AAAA,IACF;AAAA,EACF;AAAA,EAEA,YAAoB;AAClB,WAAO,KAAK,MAAM;AAAA,EACpB;AAAA,EAEA,cAAc,QAAgB,SAAgC;AAC5D,UAAM,OAAO,KAAK,MAAM,IAAI,MAAM;AAClC,QAAI,CAAC,KAAM,QAAO,QAAQ,QAAQ;AAClC,UAAM,OAAO,KAAK;AAClB,UAAM,OAAO,KAAK,WAAW,IAAI,IAAI,KAAK,QAAQ,QAAQ;AAC1D,UAAM,OAAO,KACV,KAAK,MAAM,KAAK,QAAQ,MAAM,OAAO,CAAC,EACtC,MAAM,MAAM;AAAA,IAEb,CAAC;AACH,SAAK,WAAW,IAAI,MAAM,IAAI;AAC9B,WAAO;AAAA,EACT;AAAA,EAEA,MAAc,QAAQ,MAAkB,SAAgC;AACtE,UAAM,UAAM,4BAAc,OAAO;AACjC,QAAI,CAAC,IAAK;AACV,UAAM,KAAK,IAAI;AACf,QAAI,GAAG,SAAS,oBAAoB;AAClC,YAAM,WAAW,MAAM,KAAK,QAAQ,SAAS,KAAK,IAAI;AACtD,WAAK;AAAA,QACH,KAAK,UAAU,EAAE,MAAM,UAAU,IAAI,EAAE,MAAM,YAAY,IAAI,IAAI,MAAM,SAAS,EAAE,CAAC;AAAA,MACrF;AAAA,IACF,WAAW,GAAG,SAAS,YAAY,GAAG,SAAS,YAAY,GAAG,SAAS,SAAS;AAC9E,YAAM,KAAK,QAAQ,MAAM,KAAK,MAAM,EAAE;AACtC,YAAM,UAAU,KAAK,MAAM,IAAI,KAAK,IAAI;AACxC,UAAI,SAAS;AACX,mBAAW,MAAM,SAAS;AACxB,cAAI,OAAO,KAAK,GAAI;AACpB,eAAK,MAAM,IAAI,EAAE,GAAG,KAAK,OAAO;AAAA,QAClC;AAAA,MACF;AAAA,IACF;AAAA,EAEF;AACF;;;AEzFA,gBAAgC;AAWzB,SAAS,iBAAiB,UAAmC,CAAC,GAInE;AACA,QAAM,MAAM,IAAI,QAAQ,EAAE,SAAS,QAAQ,QAAQ,CAAC;AACpD,QAAM,MAAM,QAAQ,SAChB,IAAI,0BAAgB,EAAE,QAAQ,QAAQ,OAAO,CAAC,IAC9C,IAAI,0BAAgB,EAAE,MAAM,QAAQ,QAAQ,EAAE,CAAC;AACnD,MAAI,UAAU;AACd,MAAI,GAAG,cAAc,CAAC,IAAI,QAAQ;AAChC,UAAM,MAAM,IAAI,IAAI,IAAI,OAAO,IAAI,kBAAkB;AACrD,UAAM,OAAO,IAAI,aAAa,IAAI,MAAM;AACxC,QAAI,CAAC,MAAM;AACT,SAAG,MAAM,MAAM,eAAe;AAC9B;AAAA,IACF;AACA,UAAM,SAAS,IAAI,EAAE,OAAO,IAAI,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,GAAG,CAAC,CAAC;AACtE,QAAI,cAAc;AAAA,MAChB,IAAI;AAAA,MACJ;AAAA,MACA,MAAM,CAAC,MAAM;AACX,YAAI;AACF,aAAG,KAAK,CAAC;AAAA,QACX,QAAQ;AAAA,QAER;AAAA,MACF;AAAA,IACF,CAAC;AACD,OAAG,GAAG,WAAW,CAAC,SAAS;AACzB,WAAK,IACF,cAAc,QAAQ,OAAO,IAAI,CAAC,EAClC,MAAM,CAAC,QAAQ,QAAQ,MAAM,iBAAiB,GAAG,CAAC;AAAA,IACvD,CAAC;AACD,OAAG,GAAG,SAAS,MAAM,IAAI,iBAAiB,MAAM,CAAC;AAAA,EACnD,CAAC;AACD,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,OAAO,MAAM,IAAI,QAAc,CAAC,YAAY,IAAI,MAAM,MAAM,QAAQ,CAAC,CAAC;AAAA,EACxE;AACF;","names":["import_sync"]}

package/dist/index.d.cts

@@ -0,0 +1,50 @@
+import { CanvasElement } from '@fieldnotes/core';
+import { SyncOp } from '@fieldnotes/sync';
+import { WebSocketServer } from 'ws';
+import { Server } from 'http';
+
+interface HubBackend {
+    snapshot(room: string): Promise<CanvasElement[]>;
+    apply(room: string, op: SyncOp): Promise<void>;
+}
+
+interface Connection {
+    id: string;
+    room: string;
+    send(message: string): void;
+}
+interface SyncHubOptions {
+    backend?: HubBackend;
+}
+declare class SyncHub {
+    private readonly backend;
+    private readonly conns;
+    private readonly rooms;
+    private readonly roomQueues;
+    constructor(options?: SyncHubOptions);
+    addConnection(conn: Connection): void;
+    removeConnection(connId: string): void;
+    roomCount(): number;
+    handleMessage(connId: string, message: string): Promise<void>;
+    private process;
+}
+
+declare class MemoryHubBackend implements HubBackend {
+    private rooms;
+    private room;
+    snapshot(room: string): Promise<CanvasElement[]>;
+    apply(room: string, op: SyncOp): Promise<void>;
+}
+
+interface CreateSyncServerOptions {
+    port?: number;
+    server?: Server;
+    backend?: HubBackend;
+}
+declare function createSyncServer(options?: CreateSyncServerOptions): {
+    hub: SyncHub;
+    wss: WebSocketServer;
+    close: () => Promise<void>;
+};
+
+export { type Connection, type CreateSyncServerOptions, type HubBackend, MemoryHubBackend, SyncHub, type SyncHubOptions, createSyncServer };

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import { CanvasElement } from '@fieldnotes/core';
+import { SyncOp } from '@fieldnotes/sync';
+import { WebSocketServer } from 'ws';
+import { Server } from 'http';
+
+interface HubBackend {
+    snapshot(room: string): Promise<CanvasElement[]>;
+    apply(room: string, op: SyncOp): Promise<void>;
+}
+
+interface Connection {
+    id: string;
+    room: string;
+    send(message: string): void;
+}
+interface SyncHubOptions {
+    backend?: HubBackend;
+}
+declare class SyncHub {
+    private readonly backend;
+    private readonly conns;
+    private readonly rooms;
+    private readonly roomQueues;
+    constructor(options?: SyncHubOptions);
+    addConnection(conn: Connection): void;
+    removeConnection(connId: string): void;
+    roomCount(): number;
+    handleMessage(connId: string, message: string): Promise<void>;
+    private process;
+}
+
+declare class MemoryHubBackend implements HubBackend {
+    private rooms;
+    private room;
+    snapshot(room: string): Promise<CanvasElement[]>;
+    apply(room: string, op: SyncOp): Promise<void>;
+}
+
+interface CreateSyncServerOptions {
+    port?: number;
+    server?: Server;
+    backend?: HubBackend;
+}
+declare function createSyncServer(options?: CreateSyncServerOptions): {
+    hub: SyncHub;
+    wss: WebSocketServer;
+    close: () => Promise<void>;
+};
+
+export { type Connection, type CreateSyncServerOptions, type HubBackend, MemoryHubBackend, SyncHub, type SyncHubOptions, createSyncServer };

package/dist/index.js

@@ -0,0 +1,133 @@
+// src/sync-hub.ts
+import { parseEnvelope } from "@fieldnotes/sync";
+
+// src/memory-hub-backend.ts
+import { applyOpToMap } from "@fieldnotes/sync";
+var MemoryHubBackend = class {
+  rooms = /* @__PURE__ */ new Map();
+  room(id) {
+    let r = this.rooms.get(id);
+    if (!r) {
+      r = /* @__PURE__ */ new Map();
+      this.rooms.set(id, r);
+    }
+    return r;
+  }
+  async snapshot(room) {
+    return [...this.room(room).values()];
+  }
+  async apply(room, op) {
+    applyOpToMap(this.room(room), op);
+  }
+};
+
+// src/sync-hub.ts
+var HUB_FROM = "hub";
+var SyncHub = class {
+  backend;
+  conns = /* @__PURE__ */ new Map();
+  rooms = /* @__PURE__ */ new Map();
+  // room → connIds
+  roomQueues = /* @__PURE__ */ new Map();
+  // room → serial tail
+  constructor(options = {}) {
+    this.backend = options.backend ?? new MemoryHubBackend();
+  }
+  addConnection(conn) {
+    this.conns.set(conn.id, conn);
+    let set = this.rooms.get(conn.room);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.rooms.set(conn.room, set);
+    }
+    set.add(conn.id);
+  }
+  removeConnection(connId) {
+    const conn = this.conns.get(connId);
+    if (!conn) return;
+    this.conns.delete(connId);
+    const members = this.rooms.get(conn.room);
+    if (members) {
+      members.delete(connId);
+      if (members.size === 0) {
+        this.rooms.delete(conn.room);
+        this.roomQueues.delete(conn.room);
+      }
+    }
+  }
+  roomCount() {
+    return this.rooms.size;
+  }
+  handleMessage(connId, message) {
+    const conn = this.conns.get(connId);
+    if (!conn) return Promise.resolve();
+    const room = conn.room;
+    const prev = this.roomQueues.get(room) ?? Promise.resolve();
+    const next = prev.then(() => this.process(conn, message)).catch(() => {
+    });
+    this.roomQueues.set(room, next);
+    return next;
+  }
+  async process(conn, message) {
+    const env = parseEnvelope(message);
+    if (!env) return;
+    const op = env.op;
+    if (op.kind === "request-snapshot") {
+      const elements = await this.backend.snapshot(conn.room);
+      conn.send(
+        JSON.stringify({ from: HUB_FROM, op: { kind: "snapshot", to: env.from, elements } })
+      );
+    } else if (op.kind === "upsert" || op.kind === "remove" || op.kind === "clear") {
+      await this.backend.apply(conn.room, op);
+      const members = this.rooms.get(conn.room);
+      if (members) {
+        for (const id of members) {
+          if (id === conn.id) continue;
+          this.conns.get(id)?.send(message);
+        }
+      }
+    }
+  }
+};
+
+// src/create-sync-server.ts
+import { WebSocketServer } from "ws";
+function createSyncServer(options = {}) {
+  const hub = new SyncHub({ backend: options.backend });
+  const wss = options.server ? new WebSocketServer({ server: options.server }) : new WebSocketServer({ port: options.port ?? 0 });
+  let counter = 0;
+  wss.on("connection", (ws, req) => {
+    const url = new URL(req.url ?? "", "http://localhost");
+    const room = url.searchParams.get("room");
+    if (!room) {
+      ws.close(1008, "room required");
+      return;
+    }
+    const connId = `c${++counter}-${Math.random().toString(36).slice(2, 8)}`;
+    hub.addConnection({
+      id: connId,
+      room,
+      send: (m) => {
+        try {
+          ws.send(m);
+        } catch {
+        }
+      }
+    });
+    ws.on("message", (data) => {
+      void hub.handleMessage(connId, String(data)).catch((err) => console.error("[sync-server]", err));
+    });
+    ws.on("close", () => hub.removeConnection(connId));
+  });
+  return {
+    hub,
+    wss,
+    close: () => new Promise((resolve) => wss.close(() => resolve()))
+  };
+}
+export {
+  MemoryHubBackend,
+  SyncHub,
+  createSyncServer
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sync-hub.ts","../src/memory-hub-backend.ts","../src/create-sync-server.ts"],"sourcesContent":["import { parseEnvelope } from '@fieldnotes/sync';\nimport { MemoryHubBackend } from './memory-hub-backend';\nimport type { HubBackend } from './hub-backend';\n\nexport interface Connection {\n  id: string;\n  room: string;\n  send(message: string): void;\n}\n\nexport interface SyncHubOptions {\n  backend?: HubBackend;\n}\n\nconst HUB_FROM = 'hub';\n\nexport class SyncHub {\n  private readonly backend: HubBackend;\n  private readonly conns = new Map<string, Connection>();\n  private readonly rooms = new Map<string, Set<string>>(); // room → connIds\n  private readonly roomQueues = new Map<string, Promise<void>>(); // room → serial tail\n\n  constructor(options: SyncHubOptions = {}) {\n    this.backend = options.backend ?? new MemoryHubBackend();\n  }\n\n  addConnection(conn: Connection): void {\n    this.conns.set(conn.id, conn);\n    let set = this.rooms.get(conn.room);\n    if (!set) {\n      set = new Set();\n      this.rooms.set(conn.room, set);\n    }\n    set.add(conn.id);\n  }\n\n  removeConnection(connId: string): void {\n    const conn = this.conns.get(connId);\n    if (!conn) return;\n    this.conns.delete(connId);\n    const members = this.rooms.get(conn.room);\n    if (members) {\n      members.delete(connId);\n      if (members.size === 0) {\n        this.rooms.delete(conn.room);\n        this.roomQueues.delete(conn.room);\n      }\n    }\n  }\n\n  roomCount(): number {\n    return this.rooms.size;\n  }\n\n  handleMessage(connId: string, message: string): Promise<void> {\n    const conn = this.conns.get(connId);\n    if (!conn) return Promise.resolve();\n    const room = conn.room;\n    const prev = this.roomQueues.get(room) ?? Promise.resolve();\n    const next = prev\n      .then(() => this.process(conn, message))\n      .catch(() => {\n        // swallow so one failed message never wedges the room's serial queue\n      });\n    this.roomQueues.set(room, next);\n    return next;\n  }\n\n  private async process(conn: Connection, message: string): Promise<void> {\n    const env = parseEnvelope(message);\n    if (!env) return;\n    const op = env.op;\n    if (op.kind === 'request-snapshot') {\n      const elements = await this.backend.snapshot(conn.room);\n      conn.send(\n        JSON.stringify({ from: HUB_FROM, op: { kind: 'snapshot', to: env.from, elements } }),\n      );\n    } else if (op.kind === 'upsert' || op.kind === 'remove' || op.kind === 'clear') {\n      await this.backend.apply(conn.room, op);\n      const members = this.rooms.get(conn.room);\n      if (members) {\n        for (const id of members) {\n          if (id === conn.id) continue;\n          this.conns.get(id)?.send(message);\n        }\n      }\n    }\n    // 'snapshot' from a client → ignored\n  }\n}\n","import { applyOpToMap, type SyncOp } from '@fieldnotes/sync';\nimport type { CanvasElement } from '@fieldnotes/core';\nimport type { HubBackend } from './hub-backend';\n\nexport class MemoryHubBackend implements HubBackend {\n  private rooms = new Map<string, Map<string, CanvasElement>>();\n\n  private room(id: string): Map<string, CanvasElement> {\n    let r = this.rooms.get(id);\n    if (!r) {\n      r = new Map();\n      this.rooms.set(id, r);\n    }\n    return r;\n  }\n\n  async snapshot(room: string): Promise<CanvasElement[]> {\n    return [...this.room(room).values()];\n  }\n\n  async apply(room: string, op: SyncOp): Promise<void> {\n    applyOpToMap(this.room(room), op);\n  }\n}\n","import { WebSocketServer } from 'ws';\nimport type { Server } from 'http';\nimport { SyncHub } from './sync-hub';\nimport type { HubBackend } from './hub-backend';\n\nexport interface CreateSyncServerOptions {\n  port?: number;\n  server?: Server;\n  backend?: HubBackend;\n}\n\nexport function createSyncServer(options: CreateSyncServerOptions = {}): {\n  hub: SyncHub;\n  wss: WebSocketServer;\n  close: () => Promise<void>;\n} {\n  const hub = new SyncHub({ backend: options.backend });\n  const wss = options.server\n    ? new WebSocketServer({ server: options.server })\n    : new WebSocketServer({ port: options.port ?? 0 });\n  let counter = 0;\n  wss.on('connection', (ws, req) => {\n    const url = new URL(req.url ?? '', 'http://localhost');\n    const room = url.searchParams.get('room');\n    if (!room) {\n      ws.close(1008, 'room required');\n      return;\n    }\n    const connId = `c${++counter}-${Math.random().toString(36).slice(2, 8)}`;\n    hub.addConnection({\n      id: connId,\n      room,\n      send: (m) => {\n        try {\n          ws.send(m);\n        } catch {\n          /* socket closed mid-send */\n        }\n      },\n    });\n    ws.on('message', (data) => {\n      void hub\n        .handleMessage(connId, String(data))\n        .catch((err) => console.error('[sync-server]', err));\n    });\n    ws.on('close', () => hub.removeConnection(connId));\n  });\n  return {\n    hub,\n    wss,\n    close: () => new Promise<void>((resolve) => wss.close(() => resolve())),\n  };\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@fieldnotes/sync-server",
+  "version": "0.1.0",
+  "description": "Authoritative WebSocket relay server for Field Notes real-time sync",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IrakliDevelop/fieldnotes.git",
+    "directory": "packages/sync-server"
+  },
+  "bugs": {
+    "url": "https://github.com/IrakliDevelop/fieldnotes/issues"
+  },
+  "homepage": "https://github.com/IrakliDevelop/fieldnotes/tree/master/packages/sync-server#readme",
+  "keywords": [
+    "realtime",
+    "sync",
+    "websocket",
+    "relay",
+    "collaboration",
+    "fieldnotes"
+  ],
+  "dependencies": {
+    "ws": "^8.18.0",
+    "@fieldnotes/sync": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.12",
+    "@vitest/coverage-v8": "^4.1.0",
+    "tsup": "^8.5.1",
+    "vitest": "^4.1.0",
+    "@fieldnotes/core": "0.46.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}