ooxml-core 1.22.0 → 1.24.0

package/dist/automation/live.d.ts

@@ -0,0 +1,89 @@
+import type { AutomationFormat, AutomationTool } from './tools/types.js';
+/**
+ * Runs the headless document tools against editors that are open on screen. A host's own
+ * assistant (or the suite's) registers each mounted editor under an id it chooses, and every call
+ * names the document it acts on: there is no "current document", so a chat that spans several
+ * tabs can never edit the wrong one. The tools are the same definitions the MCP servers use;
+ * this only adds the snapshot and load-back around them.
+ */
+/** What a mounted editor must offer. The editor elements fit it through `liveEditorFromElement`. */
+export interface LiveEditor {
+    readonly format: AutomationFormat;
+    /** The open document as a file, including unsaved edits. */
+    save(): Promise<Uint8Array> | Uint8Array;
+    /** Replaces the open document with `bytes`. */
+    load(bytes: Uint8Array): Promise<void> | void;
+    /** True while the editor refuses edits (a read-only role, a locked document). */
+    readonly readOnly?: boolean;
+}
+/** A tool call: the target document, then the tool's own parameters. */
+export interface LiveToolCall {
+    /** The id the editor was registered under. Required: there is no default document. */
+    target: string;
+    params?: unknown;
+}
+export interface LiveToolResult {
+    target: string;
+    tool: string;
+    /** What the tool returned: a read's view, an edit's report. */
+    result: unknown;
+    /** True when an edit changed the open document. */
+    changed: boolean;
+}
+/** What an edit is about to do, for a host that wants to confirm it first. */
+export interface LiveEditProposal {
+    target: string;
+    tool: string;
+    params: unknown;
+    /** The tool's report for the edit (warnings, results). */
+    result: unknown;
+    /** The file before and after, for a diff. */
+    before: Uint8Array;
+    after: Uint8Array;
+}
+export interface LiveToolHostOptions {
+    /**
+     * Called with each edit before it reaches the editor. Return false to discard it. Leave it out
+     * to apply edits straight away.
+     */
+    review?(proposal: LiveEditProposal): boolean | Promise<boolean>;
+}
+export interface LiveToolDescriptor {
+    name: string;
+    description: string;
+    kind: 'read' | 'edit';
+    format: AutomationFormat;
+    /** JSON Schema of the parameters, with the required `target` added. */
+    inputSchema: Record<string, unknown>;
+}
+export interface LiveToolHost {
+    /** Registers an editor under `id`. Returns a function that removes it. */
+    register(id: string, editor: LiveEditor): () => void;
+    /** The registered documents, so an assistant can offer them to the model. */
+    targets(): {
+        id: string;
+        format: AutomationFormat;
+        readOnly: boolean;
+    }[];
+    /** The read and edit tools that apply to the registered documents, as function-calling specs. */
+    describe(): LiveToolDescriptor[];
+    call(name: string, call: LiveToolCall): Promise<LiveToolResult>;
+}
+/** `tools` is the catalogue to serve: `automationTools.docx`, `pptxTools` and so on, in any mix. */
+export declare function createLiveToolHost(tools: readonly AutomationTool[], options?: LiveToolHostOptions): LiveToolHost;
+/** The members of an editor element that `liveEditorFromElement` uses. */
+export interface LiveEditorElement {
+    saveBytes?(): Promise<Uint8Array> | Uint8Array;
+    exportVsdx?(): Promise<{
+        bytes: Uint8Array;
+    }>;
+    load(bytes: Uint8Array, name?: string): Promise<unknown> | unknown;
+    commitEdit?(): boolean;
+    readOnly?: boolean;
+}
+/**
+ * Adapts a mounted editor element (`<docx-editor>`, `<xlsx-editor>`, `<pptx-editor>`,
+ * `<visio-editor>`) so it can be registered with a host. `name` is the file name the editor shows.
+ */
+export declare function liveEditorFromElement(format: AutomationFormat, element: LiveEditorElement, name?: string): LiveEditor;
+//# sourceMappingURL=live.d.ts.map

package/dist/automation/live.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"live.d.ts","sourceRoot":"","sources":["../../automation/live.ts"],"names":[],"mappings":"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"}

package/dist/collab/embedding.d.ts

@@ -3,6 +3,7 @@ import type { CollaborationRole } from './identity.js';
 import type { ConnectionStatus, ProviderFactory } from './provider.js';
 import { type CollabSession } from './session.js';
 import { type WebrtcOptions } from './webrtc-provider.js';
+import type { CollaborationWriteBackState } from './write-back.js';
 /** Who this window is in the room. */
 export interface CollaborationUser {
     /** Display name; each editor falls back to its own author name. */
@@ -58,6 +59,12 @@ export interface CollaborationState {
     /** The first exchange with the room finished. */
     synced: boolean;
     people: Collaborator[];
+    /**
+     * The owner's write-back (`onWriteBack`), present only in the window that writes back. `saved`
+     * means the host's callback returned (or its promise resolved): the host's acknowledgement and
+     * nothing more.
+     */
+    writeBack?: CollaborationWriteBackState;
 }
 /** The event every editor element dispatches, with a {@link CollaborationState} detail. */
 export declare const COLLABORATION_CHANGE_EVENT = "collaboration-change";

package/dist/collab/embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../collab/embedding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"embedding.d.ts","sourceRoot":"","sources":["../../collab/embedding.ts"],"names":[],"mappings":"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"}

package/dist/collab/index.cjs

@@ -1523,6 +1523,191 @@ function freezeDeep(value) {
   return value;
 }
 
+// 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);
+  };
+}
+
 exports.BROADCAST_THROTTLE_MS = BROADCAST_THROTTLE_MS;
 exports.BoundedMap = BoundedMap;
 exports.COLLABORATION_CHANGE_EVENT = COLLABORATION_CHANGE_EVENT;
@@ -1533,6 +1718,7 @@ exports.CONNECTION_TIMEOUT_MS = CONNECTION_TIMEOUT_MS;
 exports.CURSOR_PALETTE = CURSOR_PALETTE;
 exports.DEFAULT_COLOR = DEFAULT_COLOR;
 exports.DEFAULT_MAX_PACKAGE_BYTES = DEFAULT_MAX_PACKAGE_BYTES;
+exports.DEFAULT_WRITE_BACK_DEBOUNCE_MS = DEFAULT_WRITE_BACK_DEBOUNCE_MS;
 exports.DEPARTURE_CHANNEL = DEPARTURE_CHANNEL;
 exports.Emitter = Emitter;
 exports.INITIAL_SYNC_GRACE_MS = INITIAL_SYNC_GRACE_MS;
@@ -1575,11 +1761,13 @@ exports.createPresencePublisher = createPresencePublisher;
 exports.createSyncGate = createSyncGate;
 exports.createTransportProvider = createTransportProvider;
 exports.createWebSocketTransport = createWebSocketTransport;
+exports.createWriteBackScheduler = createWriteBackScheduler;
 exports.deriveCanvasPresence = deriveCanvasPresence;
 exports.derivePresence = derivePresence;
 exports.encodeDiff = encodeDiff;
 exports.encodeSnapshot = encodeSnapshot;
 exports.encodeStateVector = encodeStateVector2;
+exports.flushWriteBackOnPageClose = flushWriteBackOnPageClose;
 exports.formatCursorLabel = formatCursorLabel;
 exports.freezeDeep = freezeDeep;
 exports.fromBase64 = fromBase64;
@@ -1617,3 +1805,4 @@ exports.validateDisplayName = validateDisplayName;
 exports.validateRoomId = validateRoomId;
 exports.validateUpdate = validateUpdate;
 exports.webrtcProvider = webrtcProvider;
+exports.writeBackStateOf = writeBackStateOf;

package/dist/collab/index.d.ts

@@ -19,4 +19,6 @@ export * from './transport-provider.js';
 export * from './validation.js';
 export * from './webrtc-provider.js';
 export * from './websocket-transport.js';
+export * from './write-back.js';
+export * from './write-back-lifecycle.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/collab/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../collab/index.ts"],"names":[],"mappings":"AAIA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,uBAAuB,CAAC;AACtC,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../collab/index.ts"],"names":[],"mappings":"AAIA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,uBAAuB,CAAC;AACtC,cAAc,SAAS,CAAC;AACxB,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC"}

package/dist/collab/index.mjs

@@ -1499,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, webrtcProvider };
+// 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/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