@zubra/sync 0.0.0-stage → 5.3.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026, Mikey Nichols
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @zubra/sync
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Local-first state for Zubra components. `'use collection tasks'` at the top of a component's script makes its top-level `let`s the fields of a document in IndexedDB, keyed by the `doc` prop. Writes are signal assignments, so the UI never waits; state survives reloads and works offline; other elements and tabs showing the same document follow.
+
+```html
+<script>
+  'use collection tasks';
+  import { ephemeral } from '@zubra/sync';
+  let completed = false;            // stored
+  let editing = ephemeral(false);   // not stored
+</script>
+<task-item doc="">…</task-item>
+```
+
+`<task-item doc="t42">` is the document `tasks/t42`. To share documents between devices, `connect()` from `@zubra/sync/connect` and serve the log with `createSyncServer()` from `@zubra/sync/server`; components don't change. see [docs/sync.md](https://github.com/journey-to-code-org/zubra/blob/main/docs/sync.md).

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@zubra/sync",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "5.3.0",
+  "description": "Local-first state for Zubra components: 'use collection' keeps a component's state in IndexedDB, across reloads, offline, and in step across tabs.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./connect": {
+      "types": "./src/connect.d.ts",
+      "default": "./src/connect.js"
+    },
+    "./server": {
+      "types": "./src/server.d.ts",
+      "default": "./src/server.js"
+    },
+    "./sqlite": {
+      "types": "./src/sqlite.d.ts",
+      "default": "./src/sqlite.js"
+    }
+  },
+  "scripts": {
+    "test": "node --test --test-force-exit \"test/*.test.js\"",
+    "test:binary": "ZUBRA_SYNC_BACKEND=binary node --test --test-force-exit test/browser.test.js"
+  },
+  "peerDependencies": {
+    "@zubra/runtime": "^5.3.0"
+  },
+  "devDependencies": {
+    "@zubra/compiler": "file:../compiler",
+    "@zubra/runtime": "file:../runtime",
+    "@zubra/server": "file:../server",
+    "playwright": "1.63.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/journey-to-code-org/zubra.git",
+    "directory": "sync"
+  }
+}

package/src/connect.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Share 'use collection' documents through a log at `url` (default `/_zb/sync`), pulling every
+ * `interval` ms (default 2000). Writes stay on the device first and go out when the network allows.
+ */
+export function connect(options?: {
+  url?: string;
+  /** How often to poll while the live stream is closed (ms, default 2000). */
+  interval?: number;
+  /** Open the live event stream (default true). */
+  live?: boolean;
+  /**
+   * Send presence over WebRTC data channels to the peers that can be reached directly; the
+   * server carries introductions, goodbyes, signaling, and presence to anyone else.
+   */
+  webrtc?: boolean | { iceServers?: RTCIceServer[] };
+}): {
+  flush(): Promise<void>;
+  pull(): Promise<void>;
+  /** The peers presence currently goes to directly (webrtc). */
+  direct(): string[];
+  stop(): void;
+};

package/src/connect.js

@@ -0,0 +1,236 @@
+// Tier 1: share 'use collection' documents through a log on a server, so other devices (and
+// other people) converge. The store stays the source of truth on the device: writes land there
+// first, and go out when the network allows; changes from the log come in and are merged.
+//
+//   import { connect } from '@zubra/sync/connect';
+//   connect({ url: '/_zb/sync' });
+//
+// The protocol (plan/sync-design.md), plain HTTP so any server can keep the log:
+//   POST <url>/push  { changes: [Change] }            → { ok: true }
+//   GET  <url>/pull?since=<cursor>                     → { changes: [Change], cursor }
+//   Change = { collection, key, field, value, clock }  (clock: a hybrid logical clock, a string
+//   that sorts by time, then counter, then client id)
+//
+// Merging is last-writer-wins per field, by clock. A device that was offline pushes what it
+// wrote when it's back; whichever write has the later clock wins, on every device alike.
+import { onWrite, receive, currentStore, onPresence, receivePresence, peerId } from './index.js';
+import { mesh } from './webrtc.js';
+
+const CLOCKS = '$clocks';
+const pad = (number, width) => String(number).padStart(width, '0');
+
+function clock(client) {
+  let last = 0;
+  let counter = 0;
+  const tick = (seen = 0) => {
+    const now = Math.max(Date.now(), last, seen);
+    counter = now === last ? counter + 1 : 0;
+    last = now;
+    return `${pad(now, 15)}-${pad(counter, 5)}-${client}`;
+  };
+  return { tick, see: (stamp) => tick(Number(stamp.slice(0, 15))) };
+}
+
+/**
+ * @internal The changes waiting to be pushed. A push takes a snapshot (`take`), and when the
+ * server has it, exactly those changes leave (`done`): by identity, not by count, so a change
+ * added while an earlier push was out is never dropped by it. Two pushes can overlap (the debounce
+ * and the poll loop); this is why that's safe.
+ */
+export function outboxOf(changes = [], persist = () => {}) {
+  let pending = changes;
+  return {
+    get size() {
+      return pending.length;
+    },
+    pending: () => pending.slice(),
+    add(change) {
+      pending.push(change);
+      persist(pending);
+    },
+    take: () => pending.slice(),
+    done(sent) {
+      const gone = new Set(sent);
+      pending = pending.filter((change) => !gone.has(change));
+      persist(pending);
+    },
+  };
+}
+
+const remember = (name, fallback) => {
+  try { return localStorage.getItem(name) ?? fallback(); } catch { return fallback(); }
+};
+const keep = (name, value) => { try { localStorage.setItem(name, value); } catch {} };
+
+/**
+ * Start sharing. `url`: where the log is (`/_zb/sync`). `interval`: how often to pull, in ms
+ * (default 2000). Returns `{ flush, pull, stop }`.
+ */
+export function connect({ url = '/_zb/sync', interval = 2000, live = true, webrtc = false } = {}) {
+  const base = url.replace(/\/$/, '');
+  const client = remember('zubra-sync:client', () => {
+    const id = Math.random().toString(36).slice(2, 10);
+    keep('zubra-sync:client', id);
+    return id;
+  });
+  const clocks = clock(client);
+  let cursor = remember('zubra-sync:cursor', () => '0');
+  const outbox = outboxOf(JSON.parse(remember('zubra-sync:outbox', () => '[]')), (pending) =>
+    keep('zubra-sync:outbox', JSON.stringify(pending)));
+
+  // Local writes: stamp each field, remember the stamp beside the document, queue it.
+  const off = onWrite(async (collection, key, fields) => {
+    const stamped = {};
+    for (const [field, value] of Object.entries(fields)) {
+      const stamp = clocks.tick();
+      stamped[field] = stamp;
+      outbox.add({ collection, key, field, value, clock: stamp });
+    }
+    const doc = (await currentStore().get(collection, key)) ?? {};
+    await currentStore().set(collection, key, { [CLOCKS]: { ...doc[CLOCKS], ...stamped } });
+    schedule();
+  });
+
+  let timer = null;
+  const schedule = () => {
+    clearTimeout(timer);
+    timer = setTimeout(flush, 30);
+  };
+
+  async function flush() {
+    if (!outbox.size) return;
+    const sending = outbox.take();
+    try {
+      const response = await fetch(`${base}/push`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ changes: sending }),
+      });
+      if (!response.ok) return;
+      outbox.done(sending);
+    } catch {
+      // Offline: the outbox stays (in localStorage too), and goes with the next flush.
+    }
+  }
+
+  async function pull() {
+    let body;
+    try {
+      const response = await fetch(`${base}/pull?since=${encodeURIComponent(cursor)}`);
+      if (!response.ok) return;
+      body = await response.json();
+    } catch {
+      return;
+    }
+    await apply(body);
+  }
+
+  // Changes are applied one batch at a time, in the order they arrived.
+  let applying = Promise.resolve();
+  const apply = (body) => (applying = applying.then(() => merge(body)).catch(() => {}));
+
+  async function merge(body) {
+    // By document: apply the fields whose clock beats the one stored here.
+    const byDoc = new Map();
+    for (const change of body.changes) {
+      if (change.clock.endsWith(`-${client}`)) continue;
+      clocks.see(change.clock);
+      const id = JSON.stringify([change.collection, change.key]);
+      if (!byDoc.has(id)) byDoc.set(id, []);
+      byDoc.get(id).push(change);
+    }
+    for (const changes of byDoc.values()) {
+      const { collection, key } = changes[0];
+      const doc = (await currentStore().get(collection, key)) ?? {};
+      const known = { ...doc[CLOCKS] };
+      const fields = {};
+      for (const change of changes) {
+        if (known[change.field] && known[change.field] >= change.clock) continue;
+        known[change.field] = change.clock;
+        fields[change.field] = change.value;
+      }
+      if (Object.keys(fields).length) await receive(collection, key, { ...fields, [CLOCKS]: known });
+    }
+    // Never move the cursor back (a live backlog can arrive after a newer push).
+    const next = String(body.cursor);
+    if (!(/^\d+$/.test(next) && /^\d+$/.test(cursor) && Number(next) < Number(cursor))) cursor = next;
+    keep('zubra-sync:cursor', cursor);
+  }
+
+  // Live: a server-sent event stream brings changes as they're pushed, and other viewers'
+  // presence. While it's open there's nothing to poll; while it isn't, polling carries on.
+  let source = null;
+  let open = false;
+  let retry = null;
+  const listen = () => {
+    if (!live || typeof EventSource === 'undefined' || stopped) return;
+    source = new EventSource(`${base}/live?since=${encodeURIComponent(cursor)}&peer=${encodeURIComponent(peerId())}`);
+    source.addEventListener('open', () => (open = true));
+    source.addEventListener('changes', (event) => apply(JSON.parse(event.data)));
+    source.addEventListener('presence', (event) => {
+      const message = JSON.parse(event.data);
+      rtc?.sawPeer(message.room, message.peer, message.state);
+      receivePresence(message);
+    });
+    source.addEventListener('signal', (event) => rtc?.receiveSignal(JSON.parse(event.data)));
+    source.addEventListener('error', () => {
+      // Reconnect from the current cursor (EventSource would reuse the first one).
+      open = false;
+      source?.close();
+      source = null;
+      clearTimeout(retry);
+      retry = setTimeout(listen, 1000);
+    });
+  };
+
+  // Presence goes straight out, unqueued: an old cursor position is worth nothing later.
+  // With webrtc, presence goes over data channels to the peers that have one; the server carries
+  // it only while someone in the room doesn't (and always carries goodbyes).
+  const rtc =
+    webrtc && typeof RTCPeerConnection !== 'undefined'
+      ? mesh({
+          self: peerId(),
+          iceServers: webrtc.iceServers ?? [],
+          deliver: receivePresence,
+          signal: (room, to, data) =>
+            fetch(`${base}/signal`, {
+              method: 'POST',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({ room, from: peerId(), to, data }),
+            }).catch(() => {}),
+        })
+      : null;
+
+  const offPresence = onPresence((message) => {
+    if (rtc?.send(message) && message.state !== null) return;
+    fetch(`${base}/presence`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(message),
+      keepalive: message.state === null, // a leave on pagehide still gets there
+    }).catch(() => {});
+  });
+  let stopped = false;
+
+  const loop = setInterval(() => flush().then(() => (open ? undefined : pull())), interval);
+  const online = () => flush().then(pull);
+  addEventListener('online', online);
+  flush().then(pull).then(listen);
+  return {
+    flush,
+    pull,
+    /** The peers presence goes to directly (webrtc), by peer id. */
+    direct: () => rtc?.direct() ?? [],
+    stop() {
+      stopped = true;
+      off();
+      offPresence();
+      rtc?.close();
+      source?.close();
+      clearTimeout(retry);
+      clearInterval(loop);
+      clearTimeout(timer);
+      removeEventListener('online', online);
+    },
+  };
+}

package/src/index.d.ts

@@ -0,0 +1,33 @@
+/** `let editing = ephemeral(false)`: state a `'use collection'` component doesn't store. */
+export function ephemeral<T>(value: T): T;
+
+/** `let cursor = presence({ x: 0, y: 0 })`: state shared live with the document's other viewers, never stored. */
+export function presence<T>(value: T): T;
+
+/** `let others = peers()`: the document's other viewers, each `{ peer, ...presence }`. */
+export function peers<T extends object = Record<string, unknown>>(): Array<T & { peer: string }>;
+
+/** Where documents live. `set` merges `fields` into the stored document. */
+export interface Store {
+  get(collection: string, key: string): Promise<Record<string, unknown> | undefined>;
+  set(collection: string, key: string, fields: Record<string, unknown>): Promise<void>;
+}
+
+/** Use another store, before any `'use collection'` element starts. */
+export function configure(options: { store?: Store }): void;
+
+/** The default in browsers: one IndexedDB database (`zubra-sync`), one record per document. */
+export function indexedDBStore(database?: string): Store;
+
+/** A store in memory, for tests and places without IndexedDB. */
+export function memoryStore(): Store;
+
+/** Called by compiled components; not for direct use. */
+export function collection(
+  name: string,
+  keys: string[],
+  props: Record<string, unknown>,
+  fields: Record<string, { get(): unknown; set(value: unknown): void }>,
+  presence?: Record<string, { get(): unknown; set(value: unknown): void }> | null,
+  peers?: { get(): unknown; set(value: unknown): void } | null,
+): void;

package/src/index.js

@@ -0,0 +1,302 @@
+// @zubra/sync: a component's state as a document in a local store.
+//
+//   <script>
+//     'use collection tasks';
+//     import { ephemeral } from '@zubra/sync';
+//     let completed = false;             // stored: a field of the document
+//     let editing = ephemeral(false);    // not stored
+//   </script>
+//   <task-item doc="">…</task-item>      <!-- <task-item doc="t42"> is the document tasks/t42 -->
+//
+// The compiler turns the directive into one call, `collection("tasks", ["doc"], $p, { completed })`,
+// at the end of the component's setup. This module does the rest, with the platform's pieces only:
+//
+// - a write is a signal assignment, so the UI never waits; the store catches up behind it;
+// - the store is IndexedDB (in memory where there's none), so state survives reloads, offline;
+// - other elements showing the same document, in this tab or another (BroadcastChannel), follow.
+//
+// Tier 0 of plan/sync-design.md: one device, no server. Merging is last-writer-wins per field.
+import { effect, onUnmount, Signal } from '@zubra/runtime';
+
+/** `let editing = ephemeral(false)`: state the collection doesn't store. */
+export const ephemeral = (value) => value;
+/**
+ * `let cursor = presence({ x: 0, y: 0 })`: state shared live with the document's other viewers
+ * (other tabs; other devices when connected), never stored. The compiler passes it on.
+ */
+export const presence = (value) => value;
+/** `let others = peers()`: the document's other viewers' presence, `[{ peer, ...state }]`. */
+export const peers = () => [];
+
+let store = null;
+/** Use another store (`{ get(collection, key), set(collection, key, fields) }`), before elements start. */
+export function configure(options = {}) {
+  if (options.store) store = options.store;
+}
+const theStore = () => (store ??= typeof indexedDB === 'undefined' ? memoryStore() : indexedDBStore());
+
+// What a connection (connect.js) listens to: every local save, with the fields it changed.
+const writers = new Set();
+/** @internal Called with `(collection, key, fields)` on each local save. */
+export const onWrite = (fn) => (writers.add(fn), () => writers.delete(fn));
+/** @internal A change from elsewhere: store it, and show it in this tab and the others. */
+export async function receive(collection, key, fields) {
+  await theStore().set(collection, key, fields);
+  deliver(collection, key, fields, null);
+  channel?.postMessage({ collection, key, fields });
+}
+/** @internal The store in use. */
+export const currentStore = () => theStore();
+
+// Every bound element, by document, so a write reaches the others (this tab and, below, others).
+const bound = new Map();
+const docId = (collection, key) => `${collection}\u0000${key}`;
+const channel = typeof BroadcastChannel === 'undefined' ? null : new BroadcastChannel('zubra-sync');
+channel?.addEventListener('message', ({ data }) =>
+  data.kind === 'presence' ? receivePresence(data) : deliver(data.collection, data.key, data.fields, null));
+
+// Presence: each tab is one peer per document ("room"). What it sends goes to the other tabs
+// (BroadcastChannel) and, through a connection, to other devices; nothing is stored.
+const tab = Math.random().toString(36).slice(2, 10);
+const rooms = new Map(); // room → Set of (peer, state) handlers
+const presenceSenders = new Set();
+const joined = new Set(); // rooms this tab has presence in, to leave on pagehide
+/** @internal Called with `{ room, peer, state }` for each presence this tab sends (state null: left). */
+export const onPresence = (fn) => (presenceSenders.add(fn), () => presenceSenders.delete(fn));
+/** @internal This tab's peer id. */
+export const peerId = () => tab;
+/** @internal Presence from elsewhere. */
+export function receivePresence({ room, peer, state }) {
+  if (peer === tab) return;
+  for (const handler of rooms.get(room) ?? []) handler(peer, state);
+}
+function sendPresence(room, state) {
+  const message = { room, peer: tab, state };
+  if (state === null) joined.delete(room);
+  else joined.add(room);
+  channel?.postMessage({ kind: 'presence', ...message });
+  for (const send of presenceSenders) send(message);
+}
+if (typeof addEventListener === 'function') {
+  addEventListener('pagehide', () => {
+    for (const room of [...joined]) sendPresence(room, null);
+  });
+}
+function deliver(collection, key, fields, from) {
+  for (const apply of bound.get(docId(collection, key)) ?? []) if (apply !== from) apply(fields);
+}
+
+/** Plain JSON of a state value; reading it all also subscribes to every nested change. */
+const snapshot = (value) => (value === undefined ? null : JSON.parse(JSON.stringify(value)));
+
+/**
+ * Bind `fields` (the component's state signals, by name) to the document keyed by the `keys`
+ * props in `collection`. Called by compiled components.
+ */
+export function collection(name, keys, props, fields, presenceFields = null, peersSignal = null) {
+  const keyOf = () => {
+    const parts = keys.map((key) => props[key]);
+    return parts.every((part) => part !== undefined && part !== null && part !== '') ? parts.join('/') : null;
+  };
+  const loaded = new Signal.State(null);
+  let current = null;
+  let last = null; // the JSON last loaded or saved, so a load isn't written back
+  let applying = false;
+
+  const apply = (doc) => {
+    if (!doc) return;
+    applying = true;
+    try {
+      for (const [field, signal] of Object.entries(fields)) if (field in doc) signal.set(doc[field]);
+    } finally {
+      applying = false;
+    }
+  };
+  /** Each field's current value, as JSON text. */
+  const values = () => Object.fromEntries(Object.entries(fields).map(([field, signal]) => [field, JSON.stringify(snapshot(signal.get()))]));
+  const onRemote = (doc) => {
+    apply(doc);
+    last = JSON.stringify(Object.fromEntries(Object.keys(fields).map((field) => [field, snapshot(fields[field].get())])));
+  };
+
+  const join = (key) => {
+    const id = docId(name, key);
+    if (!bound.has(id)) bound.set(id, new Set());
+    bound.get(id).add(onRemote);
+  };
+  const leave = (key) => {
+    const id = docId(name, key);
+    bound.get(id)?.delete(onRemote);
+    if (bound.get(id)?.size === 0) bound.delete(id);
+  };
+
+  // Load the document whenever the key changes.
+  effect(() => {
+    const key = keyOf();
+    if (current !== null) leave(current);
+    current = key;
+    if (key === null) return;
+    join(key);
+    let cancelled = false;
+    // What the fields hold as loading starts, to tell what someone changed while it loaded.
+    const before = Signal.subtle.untrack(values);
+    theStore()
+      .get(name, key)
+      .then((doc = {}) => {
+        if (cancelled) return;
+        // An edit made before the document arrived is newer than it: keep the edit (and save
+        // it, below); take the document's values for the rest.
+        const now = values();
+        const edited = new Set(Object.keys(fields).filter((field) => now[field] !== before[field]));
+        apply(Object.fromEntries(Object.entries(doc).filter(([field]) => !edited.has(field))));
+        // `last` is what's stored, so the save effect writes exactly the edits.
+        last = JSON.stringify(Object.fromEntries(Object.keys(fields).map((field) => [field, field in doc ? snapshot(doc[field]) : JSON.parse(before[field])])));
+        loaded.set(key);
+      })
+      .catch((error) => console.error(`@zubra/sync: couldn't load ${name}/${key}`, error));
+    return () => (cancelled = true);
+  });
+
+  // Save on every change, once the document is loaded (so the defaults never overwrite it).
+  effect(() => {
+    const key = keyOf();
+    const doc = Object.fromEntries(Object.entries(fields).map(([field, signal]) => [field, snapshot(signal.get())]));
+    if (key === null || loaded.get() !== key || applying) return;
+    const text = JSON.stringify(doc);
+    if (text === last) return;
+    const before = last === null ? {} : JSON.parse(last);
+    last = text;
+    const changed = Object.fromEntries(Object.entries(doc).filter(([field, value]) => JSON.stringify(value) !== JSON.stringify(before[field])));
+    for (const write of writers) write(name, key, changed);
+    theStore()
+      .set(name, key, doc)
+      .catch((error) => console.error(`@zubra/sync: couldn't save ${name}/${key}`, error));
+    deliver(name, key, doc, onRemote);
+    channel?.postMessage({ collection: name, key, fields: doc });
+  });
+
+  onUnmount(() => current !== null && leave(current));
+  if (presenceFields || peersSignal) live(name, keyOf, presenceFields ?? {}, peersSignal);
+}
+
+const PRUNE = 30_000; // a peer not heard from for this long has gone (a crash, a closed laptop)
+const HEARTBEAT = 10_000;
+
+/** Send this element's presence to its document's room, and keep `peers` up to date. */
+function live(name, keyOf, fields, peersSignal) {
+  const others = new Map(); // peer → { state, seen }
+  const publish = () =>
+    peersSignal?.set([...others.entries()].sort(([a], [b]) => (a < b ? -1 : 1)).map(([peer, { state }]) => ({ ...state, peer })));
+  const sending = Object.keys(fields).length > 0;
+  const mine = () => Object.fromEntries(Object.entries(fields).map(([field, signal]) => [field, snapshot(signal.get())]));
+  let room = null;
+  let latest = null;
+  let queued = false;
+  const flush = () => {
+    queued = false;
+    if (room !== null && latest !== null) sendPresence(room, latest);
+  };
+  const queue = () => {
+    if (queued) return;
+    queued = true;
+    // At most once a frame: a pointer moves far more often than anyone can see.
+    (typeof requestAnimationFrame === 'function' ? requestAnimationFrame : (fn) => setTimeout(fn, 16))(flush);
+  };
+  const onPeer = (peer, state) => {
+    const known = others.has(peer);
+    if (state === null) others.delete(peer);
+    else others.set(peer, { state, seen: Date.now() });
+    publish();
+    // Someone new: tell them where we are, so they don't wait for our next move.
+    if (!known && state !== null && sending) queue();
+  };
+
+  effect(() => {
+    const key = keyOf();
+    const next = key === null ? null : `${name}/${key}`;
+    const state = sending ? mine() : null;
+    if (next !== room) {
+      if (room !== null) {
+        rooms.get(room)?.delete(onPeer);
+        if (sending) sendPresence(room, null);
+        others.clear();
+        publish();
+      }
+      room = next;
+      if (room !== null) {
+        if (!rooms.has(room)) rooms.set(room, new Set());
+        rooms.get(room).add(onPeer);
+      }
+    }
+    if (room !== null && sending) {
+      latest = state;
+      queue();
+    }
+  });
+
+  const timer = setInterval(() => {
+    if (sending && room !== null && latest !== null) sendPresence(room, latest);
+    const now = Date.now();
+    let pruned = false;
+    for (const [peer, { seen }] of others) if (now - seen > PRUNE) pruned = others.delete(peer) || pruned;
+    if (pruned) publish();
+  }, HEARTBEAT);
+
+  onUnmount(() => {
+    clearInterval(timer);
+    if (room !== null) {
+      rooms.get(room)?.delete(onPeer);
+      if (sending) sendPresence(room, null);
+    }
+  });
+}
+
+/** A store in memory: for servers, tests, and browsers without IndexedDB. */
+export function memoryStore() {
+  const docs = new Map();
+  return {
+    async get(collection, key) {
+      const doc = docs.get(docId(collection, key));
+      return doc ? structuredClone(doc) : undefined;
+    },
+    async set(collection, key, fields) {
+      const id = docId(collection, key);
+      docs.set(id, { ...docs.get(id), ...structuredClone(fields) });
+    },
+  };
+}
+
+/** The default store: one IndexedDB database, one record per document, fields merged on write. */
+export function indexedDBStore(database = 'zubra-sync') {
+  let opening = null;
+  const open = () =>
+    (opening ??= new Promise((resolve, reject) => {
+      const request = indexedDB.open(database, 1);
+      request.onupgradeneeded = () => request.result.createObjectStore('docs');
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    }));
+  const run = async (mode, work) => {
+    const db = await open();
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction('docs', mode);
+      const docs = transaction.objectStore('docs');
+      let result;
+      work(docs, (value) => (result = value));
+      transaction.oncomplete = () => resolve(result);
+      transaction.onerror = () => reject(transaction.error);
+    });
+  };
+  return {
+    get: (collection, key) =>
+      run('readonly', (docs, done) => {
+        const request = docs.get([collection, key]);
+        request.onsuccess = () => done(request.result);
+      }),
+    set: (collection, key, fields) =>
+      run('readwrite', (docs) => {
+        const request = docs.get([collection, key]);
+        request.onsuccess = () => docs.put({ ...request.result, ...fields }, [collection, key]);
+      }),
+  };
+}

package/src/server.d.ts

@@ -0,0 +1,31 @@
+export interface Change {
+  collection: string;
+  key: string;
+  field: string;
+  value: unknown;
+  /** A hybrid logical clock: `<15-digit ms>-<5-digit counter>-<client id>`. */
+  clock: string;
+}
+
+export interface Log {
+  append(changes: Change[]): Promise<unknown>;
+  after(cursor: string, limit?: number): Promise<{ changes: Change[]; cursor: number | string }>;
+}
+
+export function memoryLog(): Log;
+
+export function createSyncServer(options?: {
+  log?: Log;
+  /** Default `/_zb/sync`. */
+  mount?: string;
+  /** Refuse a write, or hide a change from a reader, by returning false. */
+  authorize?: (from: { request: Request; collection: string; key: string; write: boolean }) => boolean | Promise<boolean>;
+  /** Other origins allowed to push. */
+  origins?: string[];
+  /** How often the live stream sends a keep-alive comment (ms, default 15000). */
+  heartbeat?: number;
+}): {
+  fetch(request: Request): Promise<Response | null>;
+  /** Node's http: answers sync requests (streaming the live ones) and resolves true, else false. */
+  handle(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse): Promise<boolean>;
+};

package/src/server.js

@@ -0,0 +1,232 @@
+// The log that 'use collection' devices share (tier 1). A fetch handler, so it runs on Node
+// (through `node(req, res)`), Bun, Deno and workers; the log itself is pluggable, and in memory
+// by default. It keeps changes in order and hands them out after a cursor; it doesn't merge:
+// every device applies the same last-writer-wins rule to the same changes, so they converge.
+//
+//   import { createSyncServer } from '@zubra/sync/server';
+//   const sync = createSyncServer();
+//   const response = await sync.fetch(request);   // a Response, or null if not ours
+//
+// `authorize({ request, collection, key, write })` may refuse a change or hide one (return false).
+//
+// Live: `GET <mount>/live?since=<cursor>&peer=<id>` is a server-sent event stream: `changes` as
+// they're pushed, and `presence` from the other viewers (POST <mount>/presence). Subscribers are
+// this process's; several server processes need a shared log and a pub/sub between them.
+//
+// On Node, `handle(req, res)` answers sync requests (streaming the live ones) and returns true.
+const MOUNT = '/_zb/sync';
+
+/** A log in memory: `append(changes)` and `after(cursor)`. */
+export function memoryLog() {
+  const changes = [];
+  return {
+    async append(more) {
+      for (const change of more) changes.push(change);
+      return changes.length;
+    },
+    async after(cursor, limit = 1000) {
+      const from = Number(cursor) || 0;
+      return { changes: changes.slice(from, from + limit), cursor: Math.min(changes.length, from + limit) };
+    },
+  };
+}
+
+const json = (status, value) => new Response(JSON.stringify(value), { status, headers: { 'content-type': 'application/json' } });
+
+const valid = (change) =>
+  change && typeof change.collection === 'string' && typeof change.key === 'string' && typeof change.field === 'string' &&
+  typeof change.clock === 'string' && /^\d{15}-\d{5}-[\w-]+$/.test(change.clock) && change.field !== '$clocks';
+
+export function createSyncServer({ log = memoryLog(), mount = MOUNT, authorize = () => true, origins = [], heartbeat = 15_000 } = {}) {
+  const base = mount.replace(/\/$/, '');
+  // Live subscribers: { peer, request, send(event, data), rooms }.
+  const listeners = new Set();
+  const encoder = new TextEncoder();
+  const roomOf = (room) => {
+    const at = room.indexOf('/');
+    return at > 0 ? { collection: room.slice(0, at), key: room.slice(at + 1) } : null;
+  };
+  async function broadcastChanges(changes, cursor) {
+    for (const listener of listeners) {
+      const visible = [];
+      for (const change of changes) {
+        if (await authorize({ request: listener.request, collection: change.collection, key: change.key, write: false })) visible.push(change);
+      }
+      listener.send('changes', { changes: visible, cursor });
+    }
+  }
+  async function broadcastPresence(message) {
+    const { collection, key } = roomOf(message.room);
+    for (const listener of listeners) {
+      if (listener.peer === message.peer) continue;
+      if (await authorize({ request: listener.request, collection, key, write: false })) listener.send('presence', message);
+    }
+  }
+  const sameOrigin = (request) => {
+    const site = request.headers.get('sec-fetch-site');
+    if (site) return site === 'same-origin' || site === 'none';
+    const origin = request.headers.get('origin');
+    return !origin || origin === new URL(request.url).origin || origins.includes(origin);
+  };
+
+  async function fetch(request) {
+    const url = new URL(request.url);
+    if (url.pathname === `${base}/push` && request.method === 'POST') {
+      if (!sameOrigin(request)) return json(403, { error: 'Cross-site writes are refused' });
+      let body;
+      try {
+        body = await request.json();
+      } catch {
+        return json(400, { error: 'Expected JSON' });
+      }
+      const changes = Array.isArray(body?.changes) ? body.changes : null;
+      if (!changes || !changes.every(valid)) return json(400, { error: 'Expected { changes: [{ collection, key, field, value, clock }] }' });
+      for (const change of changes) {
+        if (!(await authorize({ request, collection: change.collection, key: change.key, write: true }))) return json(403, { error: 'Not yours to change' });
+      }
+      const appended = changes.map(({ collection, key, field, value, clock }) => ({ collection, key, field, value, clock }));
+      const cursor = await log.append(appended);
+      await broadcastChanges(appended, cursor);
+      return json(200, { ok: true });
+    }
+    if (url.pathname === `${base}/presence` && request.method === 'POST') {
+      if (!sameOrigin(request)) return json(403, { error: 'Cross-site writes are refused' });
+      let message;
+      try {
+        message = await request.json();
+      } catch {
+        return json(400, { error: 'Expected JSON' });
+      }
+      const room = typeof message?.room === 'string' ? roomOf(message.room) : null;
+      const okPeer = typeof message?.peer === 'string' && /^[\w-]{1,40}$/.test(message.peer);
+      const okState = message?.state === null || (typeof message?.state === 'object' && !Array.isArray(message.state));
+      if (!room || !okPeer || !okState || JSON.stringify(message.state).length > 4096) {
+        return json(400, { error: 'Expected { room: "<collection>/<key>", peer, state: {…} | null }' });
+      }
+      if (!(await authorize({ request, ...room, write: true }))) return json(403, { error: 'Not yours to join' });
+      const clean = { room: message.room, peer: message.peer, state: message.state };
+      for (const listener of listeners) if (listener.peer === clean.peer) {
+        if (clean.state === null) listener.rooms.delete(clean.room);
+        else listener.rooms.add(clean.room);
+      }
+      await broadcastPresence(clean);
+      return json(200, { ok: true });
+    }
+    if (url.pathname === `${base}/signal` && request.method === 'POST') {
+      // WebRTC signaling: an offer, answer or ICE candidate for one peer in a room, delivered on
+      // that peer's live stream. The server only passes it on.
+      if (!sameOrigin(request)) return json(403, { error: 'Cross-site writes are refused' });
+      let message;
+      try {
+        message = await request.json();
+      } catch {
+        return json(400, { error: 'Expected JSON' });
+      }
+      const room = typeof message?.room === 'string' ? roomOf(message.room) : null;
+      const peerOk = (peer) => typeof peer === 'string' && /^[\w-]{1,40}$/.test(peer);
+      const dataOk = message?.data && typeof message.data === 'object' && !Array.isArray(message.data) && JSON.stringify(message.data).length <= 16384;
+      if (!room || !peerOk(message.from) || !peerOk(message.to) || !dataOk) {
+        return json(400, { error: 'Expected { room, from, to, data: {…} }' });
+      }
+      if (!(await authorize({ request, ...room, write: true }))) return json(403, { error: 'Not yours to join' });
+      const clean = { room: message.room, from: message.from, to: message.to, data: message.data };
+      for (const listener of listeners) if (listener.peer === clean.to) listener.send('signal', clean);
+      return json(200, { ok: true });
+    }
+    if (url.pathname === `${base}/live` && request.method === 'GET') {
+      const peer = url.searchParams.get('peer') ?? '';
+      if (!/^[\w-]{0,40}$/.test(peer)) return json(400, { error: 'Bad peer id' });
+      const since = url.searchParams.get('since') ?? '0';
+      let listener;
+      let timer;
+      const stream = new ReadableStream({
+        start: async (controller) => {
+          const write = (text) => {
+            try {
+              controller.enqueue(encoder.encode(text));
+            } catch {
+              close();
+            }
+          };
+          const close = () => {
+            if (!listeners.delete(listener)) return;
+            clearInterval(timer);
+            // A viewer who disconnects leaves every room they were in.
+            for (const room of listener.rooms) broadcastPresence({ room, peer, state: null });
+            try { controller.close(); } catch {}
+          };
+          listener = { peer, request, rooms: new Set(), send: (event, data) => write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`), close };
+          listeners.add(listener);
+          request.signal?.addEventListener('abort', close);
+          write('retry: 1000\n\n');
+          // Read the backlog after subscribing, so nothing pushed in between is missed (a change
+          // may come twice; applying one twice changes nothing).
+          // Page by page: a log longer than one page is sent whole before anything live.
+          // (One event even when there's nothing, so the client learns the cursor; no empty event
+          // after the last full page.)
+          let from = since;
+          for (let first = true; ; first = false) {
+            const backlog = await log.after(from);
+            if (!backlog.changes.length && !first) break;
+            const visible = [];
+            for (const change of backlog.changes) {
+              if (await authorize({ request, collection: change.collection, key: change.key, write: false })) visible.push(change);
+            }
+            listener.send('changes', { changes: visible, cursor: backlog.cursor });
+            if (!backlog.changes.length || String(backlog.cursor) === String(from)) break;
+            from = backlog.cursor;
+          }
+          timer = setInterval(() => write(': keep-alive\n\n'), heartbeat);
+          timer.unref?.();
+        },
+        cancel: () => listener?.close(),
+      });
+      return new Response(stream, {
+        headers: { 'content-type': 'text/event-stream', 'cache-control': 'no-store', connection: 'keep-alive' },
+      });
+    }
+    if (url.pathname === `${base}/pull` && request.method === 'GET') {
+      const { changes, cursor } = await log.after(url.searchParams.get('since') ?? '0');
+      const visible = [];
+      for (const change of changes) {
+        if (await authorize({ request, collection: change.collection, key: change.key, write: false })) visible.push(change);
+      }
+      return json(200, { changes: visible, cursor });
+    }
+    if (url.pathname.startsWith(`${base}/`)) return json(404, { error: 'Not found' });
+    return null;
+  }
+
+  /** Node's http: answers sync requests (streaming the live ones) and returns true, else false. */
+  async function handle(req, res) {
+    if (!req.url.startsWith(`${base}/`)) return false;
+    const controller = new AbortController();
+    res.on('close', () => controller.abort());
+    const chunks = [];
+    if (req.method !== 'GET' && req.method !== 'HEAD') for await (const chunk of req) chunks.push(chunk);
+    const request = new Request(`http://${req.headers.host ?? 'localhost'}${req.url}`, {
+      method: req.method,
+      headers: Object.entries(req.headers).flatMap(([name, value]) => (Array.isArray(value) ? value.map((each) => [name, each]) : [[name, value]])),
+      body: chunks.length ? Buffer.concat(chunks) : undefined,
+      signal: controller.signal,
+    });
+    const response = await fetch(request);
+    if (!response) return false;
+    res.writeHead(response.status, Object.fromEntries(response.headers));
+    res.flushHeaders?.();
+    if (!response.body) return res.end(), true;
+    const reader = response.body.getReader();
+    controller.signal.addEventListener('abort', () => reader.cancel().catch(() => {}));
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        res.write(value);
+      }
+    } catch {}
+    res.end();
+    return true;
+  }
+
+  return { fetch, handle };
+}

package/src/sqlite.d.ts

@@ -0,0 +1,4 @@
+import type { Log } from './server.js';
+
+/** A sync log in SQLite (`node:sqlite` on Node 22.5+, `bun:sqlite` on Bun). `:memory:` by default. */
+export function sqliteLog(path?: string): Promise<Log & { close(): void }>;

package/src/sqlite.js

@@ -0,0 +1,53 @@
+// A sync log that survives a restart: one SQLite table, through the runtime's own SQLite (Node's
+// `node:sqlite`, Bun's `bun:sqlite`), so there's nothing to install.
+//
+//   import { createSyncServer } from '@zubra/sync/server';
+//   import { sqliteLog } from '@zubra/sync/sqlite';
+//   const sync = createSyncServer({ log: await sqliteLog('sync.db') });
+//
+// The cursor is the row id. Rows are only ever appended.
+export async function sqliteLog(path = ':memory:') {
+  const db = await open(path);
+  db.exec(`CREATE TABLE IF NOT EXISTS changes (
+    seq INTEGER PRIMARY KEY AUTOINCREMENT,
+    collection TEXT NOT NULL,
+    key TEXT NOT NULL,
+    field TEXT NOT NULL,
+    value TEXT,
+    clock TEXT NOT NULL
+  )`);
+  const insert = db.prepare('INSERT INTO changes (collection, key, field, value, clock) VALUES (?, ?, ?, ?, ?)');
+  const select = db.prepare('SELECT seq, collection, key, field, value, clock FROM changes WHERE seq > ? ORDER BY seq LIMIT ?');
+  const last = db.prepare('SELECT COALESCE(MAX(seq), 0) AS seq FROM changes');
+  return {
+    async append(changes) {
+      db.exec('BEGIN');
+      try {
+        for (const { collection, key, field, value, clock } of changes) {
+          insert.run(collection, key, field, JSON.stringify(value ?? null), clock);
+        }
+        db.exec('COMMIT');
+      } catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+      }
+      return Number(last.get().seq);
+    },
+    async after(cursor, limit = 1000) {
+      const rows = select.all(Number(cursor) || 0, limit);
+      const changes = rows.map(({ collection, key, field, value, clock }) => ({ collection, key, field, value: JSON.parse(value), clock }));
+      const cursorNow = rows.length ? Number(rows[rows.length - 1].seq) : Number(cursor) || 0;
+      return { changes, cursor: cursorNow };
+    },
+    close: () => db.close(),
+  };
+}
+
+async function open(path) {
+  if (typeof globalThis.Bun !== 'undefined') {
+    const { Database } = await import('bun:sqlite');
+    return new Database(path);
+  }
+  const { DatabaseSync } = await import('node:sqlite');
+  return new DatabaseSync(path);
+}

package/src/webrtc.js

@@ -0,0 +1,141 @@
+// Presence device to device: once two viewers of a room have found each other through the
+// server, they open a WebRTC data channel and send presence over it directly. On one network the
+// traffic stays there; in any case the server stops carrying every pointer move. It still carries
+// what a channel can't: introductions (a newcomer's first presence), goodbyes, the signaling to
+// open a channel, and presence to anyone without one. Documents never go this way; their changes
+// go through the log, which is what makes them durable.
+//
+// Turned on by connect({ webrtc: true }) or connect({ webrtc: { iceServers } }). Peers on one
+// network need no ICE servers; across networks, give STUN, and TURN for pairs that can't connect
+// directly (the app provides it; see docs/sync.md).
+
+/**
+ * `signal(room, to, data)` sends signaling through the server. Returns the transport's half:
+ * `{ receiveSignal, sawPeer, lostPeer, send(message) → true if every peer in the room got it
+ * directly, close }`. `deliver(message)` gets presence that arrives over a channel.
+ */
+const RETRY = 4000;
+
+export function mesh({ self, signal, deliver, iceServers = [] }) {
+  const peers = new Map(); // peer → { connection, channel, rooms: Set }
+  const rooms = new Map(); // room → Set of peers seen in it
+
+  const open = (peer) => peers.get(peer)?.channel?.readyState === 'open';
+
+  function link(peer, room, fresh = false) {
+    let entry = peers.get(peer);
+    // A channel that hasn't opened in a while won't: a signal went missing (the other side's
+    // stream was reconnecting) or ICE failed. Start again; the next presence through the server
+    // brings us here, on either side.
+    if (entry && fresh && !open(peer) && Date.now() - entry.started > RETRY) {
+      drop(peer);
+      entry = null;
+    }
+    if (entry) {
+      entry.rooms.add(room);
+      return entry;
+    }
+    const connection = new RTCPeerConnection({ iceServers });
+    entry = { connection, channel: null, rooms: new Set([room]), pending: [], started: Date.now() };
+    peers.set(peer, entry);
+    connection.addEventListener('icecandidate', ({ candidate }) => {
+      if (candidate) signal(room, peer, { candidate: candidate.toJSON() });
+    });
+    connection.addEventListener('connectionstatechange', () => {
+      if (['failed', 'closed'].includes(connection.connectionState)) drop(peer);
+    });
+    const attach = (channel) => {
+      entry.channel = channel;
+      channel.addEventListener('message', ({ data }) => {
+        try {
+          const message = JSON.parse(data);
+          // Only presence, only from the peer on this channel.
+          if (message && message.peer === peer && typeof message.room === 'string') deliver(message);
+        } catch {}
+      });
+      channel.addEventListener('close', () => drop(peer));
+    };
+    connection.addEventListener('datachannel', ({ channel }) => attach(channel));
+    // One side starts: the lower id. Both know both ids, so they agree without talking.
+    if (self < peer) {
+      attach(connection.createDataChannel('presence', { ordered: false, maxRetransmits: 0 }));
+      connection
+        .createOffer()
+        .then((offer) => connection.setLocalDescription(offer))
+        .then(() => signal(room, peer, { description: connection.localDescription.toJSON() }))
+        .catch(() => drop(peer));
+    }
+    return entry;
+  }
+
+  function drop(peer) {
+    const entry = peers.get(peer);
+    if (!entry) return;
+    peers.delete(peer);
+    try { entry.connection.close(); } catch {}
+  }
+
+  async function receiveSignal({ room, from, data }) {
+    if (from === self) return;
+    // A new offer means the other side started again: so do we.
+    if (data.description?.type === 'offer' && peers.get(from)?.connection.remoteDescription) drop(from);
+    const entry = link(from, room);
+    const { connection } = entry;
+    try {
+      if (data.description) {
+        await connection.setRemoteDescription(data.description);
+        for (const candidate of entry.pending.splice(0)) await connection.addIceCandidate(candidate);
+        if (data.description.type === 'offer') {
+          await connection.setLocalDescription(await connection.createAnswer());
+          signal(room, from, { description: connection.localDescription.toJSON() });
+        }
+      } else if (data.candidate) {
+        // Candidates can arrive before the description they belong to.
+        if (connection.remoteDescription) await connection.addIceCandidate(data.candidate);
+        else entry.pending.push(data.candidate);
+      }
+    } catch {
+      drop(from);
+    }
+  }
+
+  return {
+    receiveSignal,
+    /** A peer's presence arrived through the server: meet it, if we're both here. */
+    sawPeer(room, peer, state) {
+      if (peer === self) return;
+      if (!rooms.has(room)) rooms.set(room, new Set());
+      if (state === null) {
+        rooms.get(room).delete(peer);
+        const entry = peers.get(peer);
+        entry?.rooms.delete(room);
+        if (entry && entry.rooms.size === 0) drop(peer);
+        return;
+      }
+      rooms.get(room).add(peer);
+      link(peer, room, true);
+    },
+    /** Send presence over the open channels; true if that reached everyone known in the room. */
+    send(message) {
+      const known = rooms.get(message.room);
+      let everyone = Boolean(known && known.size);
+      for (const peer of known ?? []) {
+        if (open(peer)) {
+          try {
+            peers.get(peer).channel.send(JSON.stringify(message));
+          } catch {
+            everyone = false;
+          }
+        } else {
+          everyone = false;
+        }
+      }
+      return everyone;
+    },
+    /** The peers there's an open channel to. */
+    direct: () => [...peers.keys()].filter(open),
+    close() {
+      for (const peer of [...peers.keys()]) drop(peer);
+    },
+  };
+}