ooxml-core 1.21.0 → 1.23.0

package/dist/collab/index.mjs

@@ -1024,6 +1024,118 @@ function createTransportProvider({ doc, awareness }, { transport, maxMessageByte
   };
 }
 
+// collab/external-provider.ts
+function adaptYjsProvider(provider) {
+  const events = new Emitter();
+  let destroyed = false;
+  let status = provider.wsconnected || provider.connected ? "connected" : provider.wsconnecting ? "connecting" : "disconnected";
+  let synced = Boolean(provider.synced);
+  const subscriptions = [];
+  const listen = (name, handler) => {
+    const wrapped = handler;
+    provider.on(name, wrapped);
+    subscriptions.push([name, wrapped]);
+  };
+  const setStatus = (next) => {
+    if (destroyed || next === status) return;
+    status = next;
+    events.emit("status", next);
+  };
+  const setSynced = (next) => {
+    if (destroyed || next === synced) return;
+    synced = next;
+    events.emit("synced", next);
+  };
+  listen("status", (payload) => {
+    if (typeof payload.connected === "boolean") {
+      if (!payload.connected) setSynced(false);
+      return setStatus(payload.connected ? "connected" : "disconnected");
+    }
+    if (payload.status === "connected" || payload.status === "connecting")
+      setStatus(payload.status);
+    else if (payload.status === "disconnected") {
+      setSynced(false);
+      setStatus("disconnected");
+    }
+  });
+  const onSync = (value) => setSynced(typeof value === "boolean" ? value : value.synced === true);
+  listen("sync", onSync);
+  listen("synced", onSync);
+  listen("connection-error", (cause) => {
+    if (destroyed) return;
+    setStatus("error");
+    events.emit("error", cause instanceof Error ? cause : new Error("Provider connection error"));
+  });
+  return {
+    get status() {
+      return status;
+    },
+    get synced() {
+      return synced;
+    },
+    connect: () => {
+      if (destroyed || status === "connected" || status === "connecting") return;
+      setStatus("connecting");
+      provider.connect?.();
+    },
+    disconnect: () => {
+      if (destroyed) return;
+      provider.disconnect?.();
+      setSynced(false);
+      setStatus("disconnected");
+    },
+    destroy: () => {
+      if (destroyed) return;
+      setSynced(false);
+      setStatus("disconnected");
+      destroyed = true;
+      for (const [name, handler] of subscriptions) provider.off?.(name, handler);
+      subscriptions.length = 0;
+      events.clear();
+      provider.destroy?.();
+    },
+    on: (event, listener) => events.on(event, listener)
+  };
+}
+function observeExternalSession(session, onSnapshot) {
+  let active = true;
+  let subscribing = true;
+  let previous;
+  let unsubscribe;
+  const notify = () => {
+    if (!active || subscribing) return;
+    const snapshot = session.getSnapshot();
+    if (previous?.status === snapshot.status && previous.synced === snapshot.synced) return;
+    previous = { status: snapshot.status, synced: snapshot.synced };
+    onSnapshot(previous);
+  };
+  const dispose = () => {
+    if (!active) return;
+    active = false;
+    unsubscribe?.();
+  };
+  try {
+    unsubscribe = session.subscribe(notify);
+    subscribing = false;
+    notify();
+  } catch (error) {
+    dispose();
+    throw error;
+  }
+  return dispose;
+}
+
+// collab/webrtc-provider.ts
+function webrtcProvider(options) {
+  return ({ doc, awareness, roomId }) => adaptYjsProvider(
+    new options.WebrtcProvider(roomId, doc, {
+      awareness,
+      ...options.signaling ? { signaling: options.signaling } : {},
+      ...options.password ? { password: options.password } : {}
+    })
+  );
+}
+
 // collab/websocket-transport.ts
 var OPEN = 1;
 function roomUrl(server, roomId) {
@@ -1120,9 +1232,15 @@ function openCollaborationSession(options, defaults) {
   const roomId = options.roomId ?? "";
   if (!isValidRoomId(roomId)) throw new Error(INVALID_ROOM_MESSAGE);
   let provider = options.provider;
+  if (!provider && options.webrtc) {
+    const password = options.webrtc.password ?? options.authToken;
+    provider = webrtcProvider({ ...options.webrtc, ...password ? { password } : {} });
+  }
   if (!provider && options.serverUrl)
     provider = transportProvider({
-      transport: createWebSocketTransport({ url: roomUrl(options.serverUrl, roomId) })
+      transport: createWebSocketTransport({
+        url: withToken(roomUrl(options.serverUrl, roomId), options.authToken)
+      })
     });
   if (!provider) {
     if (!canBroadcast()) throw new Error(NO_BROADCAST_MESSAGE);
@@ -1146,6 +1264,10 @@ function openCollaborationSession(options, defaults) {
   });
   return { session, owned: true };
 }
+function withToken(url, token) {
+  if (!token) return url;
+  return `${url}${url.includes("?") ? "&" : "?"}token=${encodeURIComponent(token)}`;
+}
 function collaborationStateOf(session) {
   return {
     active: true,
@@ -1202,107 +1324,6 @@ function toExternalSession(session) {
   };
 }
 
-// collab/external-provider.ts
-function adaptYjsProvider(provider) {
-  const events = new Emitter();
-  let destroyed = false;
-  let status = provider.wsconnected || provider.connected ? "connected" : provider.wsconnecting ? "connecting" : "disconnected";
-  let synced = Boolean(provider.synced);
-  const subscriptions = [];
-  const listen = (name, handler) => {
-    const wrapped = handler;
-    provider.on(name, wrapped);
-    subscriptions.push([name, wrapped]);
-  };
-  const setStatus = (next) => {
-    if (destroyed || next === status) return;
-    status = next;
-    events.emit("status", next);
-  };
-  const setSynced = (next) => {
-    if (destroyed || next === synced) return;
-    synced = next;
-    events.emit("synced", next);
-  };
-  listen("status", (payload) => {
-    if (typeof payload.connected === "boolean") {
-      if (!payload.connected) setSynced(false);
-      return setStatus(payload.connected ? "connected" : "disconnected");
-    }
-    if (payload.status === "connected" || payload.status === "connecting")
-      setStatus(payload.status);
-    else if (payload.status === "disconnected") {
-      setSynced(false);
-      setStatus("disconnected");
-    }
-  });
-  const onSync = (value) => setSynced(typeof value === "boolean" ? value : value.synced === true);
-  listen("sync", onSync);
-  listen("synced", onSync);
-  listen("connection-error", (cause) => {
-    if (destroyed) return;
-    setStatus("error");
-    events.emit("error", cause instanceof Error ? cause : new Error("Provider connection error"));
-  });
-  return {
-    get status() {
-      return status;
-    },
-    get synced() {
-      return synced;
-    },
-    connect: () => {
-      if (destroyed || status === "connected" || status === "connecting") return;
-      setStatus("connecting");
-      provider.connect?.();
-    },
-    disconnect: () => {
-      if (destroyed) return;
-      provider.disconnect?.();
-      setSynced(false);
-      setStatus("disconnected");
-    },
-    destroy: () => {
-      if (destroyed) return;
-      setSynced(false);
-      setStatus("disconnected");
-      destroyed = true;
-      for (const [name, handler] of subscriptions) provider.off?.(name, handler);
-      subscriptions.length = 0;
-      events.clear();
-      provider.destroy?.();
-    },
-    on: (event, listener) => events.on(event, listener)
-  };
-}
-function observeExternalSession(session, onSnapshot) {
-  let active = true;
-  let subscribing = true;
-  let previous;
-  let unsubscribe;
-  const notify = () => {
-    if (!active || subscribing) return;
-    const snapshot = session.getSnapshot();
-    if (previous?.status === snapshot.status && previous.synced === snapshot.synced) return;
-    previous = { status: snapshot.status, synced: snapshot.synced };
-    onSnapshot(previous);
-  };
-  const dispose = () => {
-    if (!active) return;
-    active = false;
-    unsubscribe?.();
-  };
-  try {
-    unsubscribe = session.subscribe(notify);
-    subscribing = false;
-    notify();
-  } catch (error) {
-    dispose();
-    throw error;
-  }
-  return dispose;
-}
-
 // collab/memory-transport.ts
 function createMemoryHub(options = {}) {
   const rooms = /* @__PURE__ */ new Map();
@@ -1478,4 +1499,189 @@ function freezeDeep(value) {
   return value;
 }
 
-export { BROADCAST_THROTTLE_MS, BoundedMap, COLLABORATION_CHANGE_EVENT, COLLABORATION_OFF_STATE, COLLABORATION_ROLES, COLLAB_LEAVE_MESSAGE, CONNECTION_TIMEOUT_MS, CURSOR_PALETTE, DEFAULT_COLOR, DEFAULT_MAX_PACKAGE_BYTES, DEPARTURE_CHANNEL, Emitter, INITIAL_SYNC_GRACE_MS, INVALID_ROOM_MESSAGE, IdempotencyCache, LEGACY_PPTX_DEPARTURE_CHANNEL, LEGACY_PPTX_LEAVE_MESSAGE, LOCAL_ORIGIN, MAX_LABEL_CHARS, MAX_UPDATE_BYTES, MESSAGE_AWARENESS, MESSAGE_QUERY_AWARENESS, MESSAGE_SYNC, NO_BROADCAST_MESSAGE, PRESENCE_FIELD, PRESENCE_HEARTBEAT_MS, STALE_PRESENCE_MS, SequenceTracker, adaptYjsProvider, applyUpdateSafe, asSelectionIds, assignUserColor, bindDocument, borrowAwareness, buildRoster, canBroadcast, canWrite, clampCoordinate, classifyVersion, clearLocalAwareness, collaborationStateOf, createAssetSync, createBroadcastTransport, createClientId, createCollabSession, createDepartureChannel, createIdGenerator, createMemoryHub, createPresencePublisher, createSyncGate, createTransportProvider, createWebSocketTransport, deriveCanvasPresence, derivePresence, encodeDiff, encodeSnapshot, encodeStateVector2 as encodeStateVector, formatCursorLabel, freezeDeep, fromBase64, getUserInitials, isMixedContentBlocked, isNonNegativeSafeInteger, isPresenceFresh, isValidId, isValidRoomId, mergeUpdates2 as mergeUpdates, observeExternalSession, onCollaborationStateChange, openCollaborationSession, packageAdapter, presenceToCursors, randomToken, registerTeardown, removeAwarenessStatesLocally, restoreSnapshot, roomUrl, sanitizeAvatarUrl, sanitizeCanvasPayload, sanitizeColor, sanitizeIdentity, sanitizeIndex, sanitizeRole, sanitizeUserName, shouldAutoFollowBroadcaster, shouldRoomReplaceLoad, stripHtmlTags, toBase64, toExternalSession, transportProvider, validateDisplayName, validateRoomId, validateUpdate };
+// collab/write-back.ts
+var DEFAULT_WRITE_BACK_DEBOUNCE_MS = 5e3;
+var DEFAULT_RETRY_BASE_MS = 1e3;
+var DEFAULT_RETRY_MAX_MS = 3e4;
+var globalTimers = {
+  setTimeout: (callback, ms) => globalThis.setTimeout(callback, ms),
+  clearTimeout: (handle) => globalThis.clearTimeout(handle)
+};
+var isThenable = (value) => typeof value === "object" && value !== null && typeof value.then === "function";
+function writeBackStateOf(state) {
+  const out = { status: state.status };
+  if (state.lastSavedAt !== void 0) out.lastSavedAt = state.lastSavedAt;
+  if (state.status === "failed" && state.lastError !== void 0) {
+    out.error = state.lastError instanceof Error ? state.lastError.message : String(state.lastError);
+  }
+  return out;
+}
+function createWriteBackScheduler(options) {
+  const timers = options.timers ?? globalTimers;
+  const now = options.now ?? Date.now;
+  const configured = options.debounceMs;
+  const debounceMs = configured !== void 0 && Number.isFinite(configured) && configured >= 0 ? configured : DEFAULT_WRITE_BACK_DEBOUNCE_MS;
+  const attempts = Math.max(1, Math.floor(options.retry?.attempts ?? 1) || 1);
+  const baseDelay = Math.max(0, options.retry?.baseDelayMs ?? DEFAULT_RETRY_BASE_MS);
+  const maxDelay = Math.max(baseDelay, options.retry?.maxDelayMs ?? DEFAULT_RETRY_MAX_MS);
+  let state = { status: "idle" };
+  let generation = 0;
+  let disposed = false;
+  let dirty = false;
+  let timer = null;
+  let running = null;
+  let wake = null;
+  let ended = false;
+  let rushing = 0;
+  const patch = (status, extra = {}) => {
+    const next = { status };
+    const saved = extra.lastSavedAt ?? state.lastSavedAt;
+    if (saved !== void 0) next.lastSavedAt = saved;
+    if (extra.lastError !== void 0) next.lastError = extra.lastError;
+    state = next;
+    options.onStatus?.(state);
+  };
+  const clearTimer = () => {
+    if (timer !== null) timers.clearTimeout(timer);
+    timer = null;
+  };
+  const arm = () => {
+    clearTimer();
+    timer = timers.setTimeout(() => {
+      timer = null;
+      void start();
+    }, debounceMs);
+    if (state.status !== "pending") patch("pending");
+  };
+  const sleep = (ms) => new Promise((resolve) => {
+    if (rushing > 0) return resolve();
+    const handle = timers.setTimeout(done, ms);
+    function done() {
+      timers.clearTimeout(handle);
+      wake = null;
+      resolve();
+    }
+    wake = done;
+  });
+  const settledStatus = () => state.lastSavedAt === void 0 ? "idle" : "saved";
+  async function run() {
+    const gen = generation;
+    const isCurrent = () => gen === generation;
+    patch("saving");
+    try {
+      for (let attempt = 1; ; attempt++) {
+        dirty = false;
+        try {
+          let bytes = options.serialize({ isCurrent });
+          if (isThenable(bytes)) bytes = await bytes;
+          if (!isCurrent()) return;
+          if (bytes === null || bytes === void 0) {
+            if (dirty) arm();
+            else patch(settledStatus());
+            return;
+          }
+          const acknowledged = options.write(bytes);
+          if (isThenable(acknowledged)) await acknowledged;
+          if (!isCurrent()) return;
+          const lastSavedAt = now();
+          if (dirty) {
+            patch("pending", { lastSavedAt });
+            arm();
+          } else {
+            patch("saved", { lastSavedAt });
+          }
+          return;
+        } catch (error) {
+          if (!isCurrent()) return;
+          if (attempt >= attempts) {
+            dirty = true;
+            patch("failed", { lastError: error });
+            return;
+          }
+          await sleep(Math.min(maxDelay, baseDelay * 2 ** (attempt - 1)));
+          if (!isCurrent()) return;
+        }
+      }
+    } finally {
+      ended = true;
+      running = null;
+      if (dirty && timer === null && !disposed && state.status !== "failed") arm();
+    }
+  }
+  function start() {
+    if (running) return running;
+    ended = false;
+    const promise = run();
+    if (!ended) running = promise;
+    return promise;
+  }
+  function cancel() {
+    generation++;
+    clearTimer();
+    dirty = false;
+    const waiting = wake;
+    wake = null;
+    waiting?.();
+    if (state.status === "pending" || state.status === "saving") patch(settledStatus());
+  }
+  return {
+    schedule() {
+      if (disposed) return;
+      dirty = true;
+      if (running) return;
+      arm();
+    },
+    async flush() {
+      if (disposed) return;
+      clearTimer();
+      rushing++;
+      try {
+        wake?.();
+        for (; ; ) {
+          if (running) await running;
+          else if (dirty) await start();
+          else return;
+          if (disposed) return;
+          if (state.status === "failed") throw state.lastError;
+          clearTimer();
+        }
+      } finally {
+        rushing--;
+      }
+    },
+    cancel,
+    dispose() {
+      if (disposed) return;
+      cancel();
+      disposed = true;
+    },
+    get state() {
+      return state;
+    },
+    get dirty() {
+      return dirty;
+    }
+  };
+}
+
+// collab/write-back-lifecycle.ts
+function flushWriteBackOnPageClose(scheduler, options = {}) {
+  const globals = globalThis;
+  const win = options.window === void 0 ? typeof globals.addEventListener === "function" ? globalThis : null : options.window;
+  const doc = options.document === void 0 ? globals.document ?? null : options.document;
+  const flush = () => {
+    if (!scheduler.dirty) return;
+    scheduler.flush().catch((error) => options.onError?.(error));
+  };
+  const hidden = () => {
+    if (doc?.visibilityState === "hidden") flush();
+  };
+  win?.addEventListener("pagehide", flush);
+  doc?.addEventListener("visibilitychange", hidden);
+  return () => {
+    win?.removeEventListener("pagehide", flush);
+    doc?.removeEventListener("visibilitychange", hidden);
+  };
+}
+
+export { BROADCAST_THROTTLE_MS, BoundedMap, COLLABORATION_CHANGE_EVENT, COLLABORATION_OFF_STATE, COLLABORATION_ROLES, COLLAB_LEAVE_MESSAGE, CONNECTION_TIMEOUT_MS, CURSOR_PALETTE, DEFAULT_COLOR, DEFAULT_MAX_PACKAGE_BYTES, DEFAULT_WRITE_BACK_DEBOUNCE_MS, DEPARTURE_CHANNEL, Emitter, INITIAL_SYNC_GRACE_MS, INVALID_ROOM_MESSAGE, IdempotencyCache, LEGACY_PPTX_DEPARTURE_CHANNEL, LEGACY_PPTX_LEAVE_MESSAGE, LOCAL_ORIGIN, MAX_LABEL_CHARS, MAX_UPDATE_BYTES, MESSAGE_AWARENESS, MESSAGE_QUERY_AWARENESS, MESSAGE_SYNC, NO_BROADCAST_MESSAGE, PRESENCE_FIELD, PRESENCE_HEARTBEAT_MS, STALE_PRESENCE_MS, SequenceTracker, adaptYjsProvider, applyUpdateSafe, asSelectionIds, assignUserColor, bindDocument, borrowAwareness, buildRoster, canBroadcast, canWrite, clampCoordinate, classifyVersion, clearLocalAwareness, collaborationStateOf, createAssetSync, createBroadcastTransport, createClientId, createCollabSession, createDepartureChannel, createIdGenerator, createMemoryHub, createPresencePublisher, createSyncGate, createTransportProvider, createWebSocketTransport, createWriteBackScheduler, deriveCanvasPresence, derivePresence, encodeDiff, encodeSnapshot, encodeStateVector2 as encodeStateVector, flushWriteBackOnPageClose, formatCursorLabel, freezeDeep, fromBase64, getUserInitials, isMixedContentBlocked, isNonNegativeSafeInteger, isPresenceFresh, isValidId, isValidRoomId, mergeUpdates2 as mergeUpdates, observeExternalSession, onCollaborationStateChange, openCollaborationSession, packageAdapter, presenceToCursors, randomToken, registerTeardown, removeAwarenessStatesLocally, restoreSnapshot, roomUrl, sanitizeAvatarUrl, sanitizeCanvasPayload, sanitizeColor, sanitizeIdentity, sanitizeIndex, sanitizeRole, sanitizeUserName, shouldAutoFollowBroadcaster, shouldRoomReplaceLoad, stripHtmlTags, toBase64, toExternalSession, transportProvider, validateDisplayName, validateRoomId, validateUpdate, webrtcProvider, writeBackStateOf };

package/dist/collab/webrtc-provider.d.ts

@@ -0,0 +1,21 @@
+import type { Awareness } from 'y-protocols/awareness';
+import type * as Y from 'yjs';
+import { type YjsProviderLike } from './external-provider.js';
+import type { ProviderFactory } from './provider.js';
+/** The y-webrtc `WebrtcProvider` constructor, structurally. */
+export type WebrtcProviderConstructor = new (roomId: string, doc: Y.Doc, options: {
+    signaling?: string[];
+    password?: string;
+    awareness?: Awareness;
+}) => YjsProviderLike;
+export interface WebrtcOptions {
+    /** `WebrtcProvider` from the host's own `y-webrtc` install. */
+    WebrtcProvider: WebrtcProviderConstructor;
+    /** Signaling server URLs; y-webrtc's defaults when omitted. */
+    signaling?: string[];
+    /** Room password: peers without it cannot read the room. */
+    password?: string;
+}
+/** A provider factory that joins the session's room over y-webrtc, sharing its awareness. */
+export declare function webrtcProvider(options: WebrtcOptions): ProviderFactory;
+//# sourceMappingURL=webrtc-provider.d.ts.map

package/dist/collab/webrtc-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webrtc-provider.d.ts","sourceRoot":"","sources":["../../collab/webrtc-provider.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,KAAK,CAAC,MAAM,KAAK,CAAC;AAC9B,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,+DAA+D;AAC/D,MAAM,MAAM,yBAAyB,GAAG,KACvC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,CAAC,CAAC,GAAG,EACV,OAAO,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,CAAA;CAAE,KACvE,eAAe,CAAC;AAErB,MAAM,WAAW,aAAa;IAC7B,+DAA+D;IAC/D,cAAc,EAAE,yBAAyB,CAAC;IAC1C,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,6FAA6F;AAC7F,wBAAgB,cAAc,CAAC,OAAO,EAAE,aAAa,GAAG,eAAe,CAStE"}

package/dist/collab/write-back-lifecycle.d.ts

@@ -0,0 +1,33 @@
+import type { WriteBackScheduler } from './write-back.js';
+/** The part of `window` used: `pagehide` is listened on it. */
+export interface PageHideTarget {
+    addEventListener(type: 'pagehide', listener: () => void): void;
+    removeEventListener(type: 'pagehide', listener: () => void): void;
+}
+/** The part of `document` used: `visibilitychange` is listened on it. */
+export interface VisibilityTarget {
+    readonly visibilityState?: string;
+    addEventListener(type: 'visibilitychange', listener: () => void): void;
+    removeEventListener(type: 'visibilitychange', listener: () => void): void;
+}
+export interface FlushOnPageCloseOptions {
+    /** Default `globalThis` when it can listen (a browser window), otherwise no `pagehide` hook. */
+    window?: PageHideTarget | null;
+    /** Default `globalThis.document` when present. */
+    document?: VisibilityTarget | null;
+    /** Receives a flush that failed (it never throws). Default ignores it. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Flushes `scheduler` on `pagehide` and when the page turns hidden, and returns the function that
+ * removes the listeners. Only unsaved work is written.
+ *
+ * Browsers do not wait for asynchronous work when a page unloads: the flush starts the write, but
+ * a write that needs a network round trip can still be lost on close. A host that must survive a
+ * close should send the bytes with `navigator.sendBeacon(url, bytes)` or
+ * `fetch(url, { method: 'PUT', body: bytes, keepalive: true })` (the browser caps keepalive bodies
+ * at about 64 KiB, so a large document may still not make it), which the browser completes after
+ * the page is gone.
+ */
+export declare function flushWriteBackOnPageClose(scheduler: Pick<WriteBackScheduler, 'flush' | 'dirty'>, options?: FlushOnPageCloseOptions): () => void;
+//# sourceMappingURL=write-back-lifecycle.d.ts.map

package/dist/collab/write-back-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-back-lifecycle.d.ts","sourceRoot":"","sources":["../../collab/write-back-lifecycle.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC9B,gBAAgB,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC/D,mBAAmB,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAClE;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,gBAAgB,CAAC,IAAI,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACvE,mBAAmB,CAAC,IAAI,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CAC1E;AAED,MAAM,WAAW,uBAAuB;IACvC,gGAAgG;IAChG,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACnC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACxC,SAAS,EAAE,IAAI,CAAC,kBAAkB,EAAE,OAAO,GAAG,OAAO,CAAC,EACtD,OAAO,GAAE,uBAA4B,GACnC,MAAM,IAAI,CAyBZ"}

package/dist/collab/write-back.d.ts

@@ -0,0 +1,75 @@
+/** Where a write-back stands: `idle` until the first change, then `pending`, `saving`, `saved` or `failed`. */
+export type WriteBackStatus = 'idle' | 'pending' | 'saving' | 'saved' | 'failed';
+/** What {@link WriteBackScheduler.state} and `onStatus` report. */
+export interface WriteBackState {
+    status: WriteBackStatus;
+    /** `now()` when the host last acknowledged a write. */
+    lastSavedAt?: number;
+    /** The error of the last failed write, once its retries are spent. */
+    lastError?: unknown;
+}
+/** The write-back status as an editor reports it in its collaboration state (JSON friendly). */
+export interface CollaborationWriteBackState {
+    status: WriteBackStatus;
+    lastSavedAt?: number;
+    /** The message of the last failure, while `status` is `failed`. */
+    error?: string;
+}
+export interface WriteBackRetry {
+    /** Total tries per write, the first included. 1 (the default) never retries. */
+    attempts: number;
+    /** Wait before the first retry; doubles on each further retry. Default 1000. */
+    baseDelayMs?: number;
+    /** Upper bound of the wait. Default 30000. */
+    maxDelayMs?: number;
+}
+export interface WriteBackTimers {
+    setTimeout(callback: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface WriteBackOptions {
+    /**
+     * The bytes to store now. Resolve `null` when there is nothing to save yet (the change is not
+     * lost: call `schedule()` again when it is). `isCurrent` turns false once the scheduler was
+     * cancelled or disposed, so a long serialisation can stop early.
+     */
+    serialize: (context: {
+        isCurrent: () => boolean;
+    }) => Uint8Array | null | Promise<Uint8Array | null>;
+    /**
+     * Stores the bytes. A returned promise is the acknowledgement: resolving means stored, rejecting
+     * counts as a failed try. A plain return (void) is treated as acknowledged at once.
+     */
+    write: (bytes: Uint8Array) => void | Promise<void>;
+    /** Quiet time after the last change. Default 5000; invalid values fall back to it. */
+    debounceMs?: number;
+    retry?: WriteBackRetry;
+    onStatus?: (state: WriteBackState) => void;
+    /** Clock for `lastSavedAt`. Default `Date.now`. */
+    now?: () => number;
+    /** Timers, injectable for tests. Default the global ones, looked up at call time. */
+    timers?: WriteBackTimers;
+}
+export interface WriteBackScheduler {
+    /** Notes a change: (re)starts the quiet time, or queues one follow-up write during a write. */
+    schedule(): void;
+    /**
+     * Writes now and resolves once the host acknowledged it (and anything changed meanwhile).
+     * Resolves at once when nothing is unsaved; rejects with the last error when the write failed
+     * after its retries. When `serialize` and `write` return synchronously, the write has been
+     * handed over before `flush` returns.
+     */
+    flush(): Promise<void>;
+    /** Drops pending work and ignores the result of a write in flight; the scheduler stays usable. */
+    cancel(): void;
+    /** Cancels and stops for good: later calls do nothing. */
+    dispose(): void;
+    readonly state: WriteBackState;
+    /** True while a change waits for its quiet time or a write (or its retry) is under way. */
+    readonly dirty: boolean;
+}
+export declare const DEFAULT_WRITE_BACK_DEBOUNCE_MS = 5000;
+/** The status of `state` for a collaboration state; the error becomes its message. */
+export declare function writeBackStateOf(state: WriteBackState): CollaborationWriteBackState;
+export declare function createWriteBackScheduler(options: WriteBackOptions): WriteBackScheduler;
+//# sourceMappingURL=write-back.d.ts.map

package/dist/collab/write-back.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-back.d.ts","sourceRoot":"","sources":["../../collab/write-back.ts"],"names":[],"mappings":"AAKA,+GAA+G;AAC/G,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEjF,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,eAAe,CAAC;IACxB,uDAAuD;IACvD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,gGAAgG;AAChG,MAAM,WAAW,2BAA2B;IAC3C,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC9B,gFAAgF;IAChF,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC/B,UAAU,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACtD,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAChC;;;;OAIG;IACH,SAAS,EAAE,CAAC,OAAO,EAAE;QACpB,SAAS,EAAE,MAAM,OAAO,CAAC;KACzB,KAAK,UAAU,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACrD;;;OAGG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;IAC3C,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,qFAAqF;IACrF,MAAM,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IAClC,+FAA+F;IAC/F,QAAQ,IAAI,IAAI,CAAC;IACjB;;;;;OAKG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,kGAAkG;IAClG,MAAM,IAAI,IAAI,CAAC;IACf,0DAA0D;IAC1D,OAAO,IAAI,IAAI,CAAC;IAChB,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACxB;AAED,eAAO,MAAM,8BAA8B,OAAQ,CAAC;AAcpD,sFAAsF;AACtF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,2BAA2B,CAQnF;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,gBAAgB,GAAG,kBAAkB,CAkKtF"}