@pixerate/editor 0.278.0 → 0.279.1

package/dist/paint-editor/index.js

@@ -42,7 +42,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-FNIWHSLI.js";
+} from "../chunk-NJDEKU5D.js";
 import "../chunk-ADMRNWR7.js";
 import "../chunk-WJ4WQJCC.js";
 import {
@@ -125,7 +125,7 @@ import {
   wetPaperInput,
   wetPigmentOf,
   withStrokePath
-} from "../chunk-HHX7ST6Z.js";
+} from "../chunk-YOM76H2V.js";
 import {
   BRUSH_ID,
   BRUSH_PRESETS,
@@ -250,7 +250,7 @@ import {
   normalizeWetParams,
   pigmentOf,
   wetSupport
-} from "../chunk-CTHWXW5M.js";
+} from "../chunk-V6LQND7D.js";
 import "../chunk-J23JOHPR.js";
 import {
   CoverageMap,

package/dist/persistence/autosave.d.cts

@@ -21,6 +21,8 @@ export interface RecoveryMeta {
     time?: number;
     /** Document name, for the "Restore unsaved changes from …?" prompt. */
     name?: string;
+    /** The server / host version the edits in the snapshot were made on (`baseVersion` option). */
+    baseVersion?: number;
 }
 export interface AutosaveRecovery<T = unknown> {
     /** The parsed snapshot (`undefined` when `deserialize` threw; see `error`). */
@@ -65,6 +67,18 @@ export interface AutosaveControllerOptions<T> {
     clearTimeout?: (handle: any) => void;
     /** Start hydrated, i.e. as if `ready()` was already called (default `false`). */
     ready?: boolean;
+    /**
+     * The server / host version of the document that is loaded now. It is stored in each
+     * snapshot's meta, and `checkRecovery` retires (deletes and does not return) a snapshot whose
+     * edits were made on an older version, so it never overwrites newer server state. A snapshot
+     * without a stored version counts as version 0.
+     */
+    baseVersion?: number | (() => number | undefined);
+}
+/** Options for `AutosaveController.checkRecovery`. */
+export interface CheckRecoveryOptions {
+    /** Retire snapshots made on a version older than this (default the `baseVersion` option). */
+    minimumBaseVersion?: number;
 }
 export interface AutosaveController<T = unknown> {
     /** Current status. */
@@ -91,7 +105,7 @@ export interface AutosaveController<T = unknown> {
      * A dirty snapshot left by an earlier session, or `null`. Returns `null` once
      * this session has written its own snapshot.
      */
-    checkRecovery(): Promise<AutosaveRecovery<T> | null>;
+    checkRecovery(options?: CheckRecoveryOptions): Promise<AutosaveRecovery<T> | null>;
     /** Deletes an earlier session's snapshot. No-op once this session wrote its own. */
     discardRecovery(): Promise<boolean>;
     /** Runs one scheduling step now (normally driven by `notify` and timers). */

package/dist/persistence/autosave.d.ts

@@ -21,6 +21,8 @@ export interface RecoveryMeta {
     time?: number;
     /** Document name, for the "Restore unsaved changes from …?" prompt. */
     name?: string;
+    /** The server / host version the edits in the snapshot were made on (`baseVersion` option). */
+    baseVersion?: number;
 }
 export interface AutosaveRecovery<T = unknown> {
     /** The parsed snapshot (`undefined` when `deserialize` threw; see `error`). */
@@ -65,6 +67,18 @@ export interface AutosaveControllerOptions<T> {
     clearTimeout?: (handle: any) => void;
     /** Start hydrated, i.e. as if `ready()` was already called (default `false`). */
     ready?: boolean;
+    /**
+     * The server / host version of the document that is loaded now. It is stored in each
+     * snapshot's meta, and `checkRecovery` retires (deletes and does not return) a snapshot whose
+     * edits were made on an older version, so it never overwrites newer server state. A snapshot
+     * without a stored version counts as version 0.
+     */
+    baseVersion?: number | (() => number | undefined);
+}
+/** Options for `AutosaveController.checkRecovery`. */
+export interface CheckRecoveryOptions {
+    /** Retire snapshots made on a version older than this (default the `baseVersion` option). */
+    minimumBaseVersion?: number;
 }
 export interface AutosaveController<T = unknown> {
     /** Current status. */
@@ -91,7 +105,7 @@ export interface AutosaveController<T = unknown> {
      * A dirty snapshot left by an earlier session, or `null`. Returns `null` once
      * this session has written its own snapshot.
      */
-    checkRecovery(): Promise<AutosaveRecovery<T> | null>;
+    checkRecovery(options?: CheckRecoveryOptions): Promise<AutosaveRecovery<T> | null>;
     /** Deletes an earlier session's snapshot. No-op once this session wrote its own. */
     discardRecovery(): Promise<boolean>;
     /** Runs one scheduling step now (normally driven by `notify` and timers). */

package/dist/persistence/editorAutosave.d.cts

@@ -11,6 +11,12 @@ export interface EditorAutosaveOptions extends Omit<AutosaveControllerOptions<Ed
      * saved state needs no snapshot. Without it, every change counts until `markClean()`.
      */
     dirty?: DirtyFlagSource;
+    /**
+     * The server / host version of the loaded document, stored with each snapshot.
+     * `checkRecovery` / `recoverIfNewer` retire snapshots made on an older version instead of
+     * offering them (see `AutosaveControllerOptions.baseVersion`).
+     */
+    baseVersion?: number | (() => number | undefined);
     /**
      * For documents with `assets`: after `markClean` or `discard` retire a snapshot, delete the
      * stored assets nothing refers to any more (`collectEditorAssetGarbage`, best effort, keeping
@@ -21,8 +27,13 @@ export interface EditorAutosaveOptions extends Omit<AutosaveControllerOptions<Ed
 export interface EditorAutosave {
     readonly controller: AutosaveController<EditorDocumentFile>;
     readonly revisions: RevisionTracker;
-    /** An earlier session's unsaved snapshot of this document, or `null`. */
+    /** An earlier session's unsaved snapshot of this document, or `null` (snapshots made on a version older than `baseVersion` are retired). */
     checkRecovery(): Promise<AutosaveRecovery<EditorDocumentFile> | null>;
+    /**
+     * Checks for an earlier session's unsaved snapshot, restoring it into `doc` if it is valid and
+     * at least as new as `baseVersion`, or retiring it and starting autosave cleanly if stale/invalid.
+     */
+    recoverIfNewer(minimumBaseVersion?: number): Promise<LoadReport | null>;
     /** Loads a recovered snapshot into the document and starts autosaving. */
     restore(recovery: AutosaveRecovery<EditorDocumentFile>): LoadReport;
     /** Deletes the earlier session's snapshot and starts autosaving. */

package/dist/persistence/editorAutosave.d.ts

@@ -11,6 +11,12 @@ export interface EditorAutosaveOptions extends Omit<AutosaveControllerOptions<Ed
      * saved state needs no snapshot. Without it, every change counts until `markClean()`.
      */
     dirty?: DirtyFlagSource;
+    /**
+     * The server / host version of the loaded document, stored with each snapshot.
+     * `checkRecovery` / `recoverIfNewer` retire snapshots made on an older version instead of
+     * offering them (see `AutosaveControllerOptions.baseVersion`).
+     */
+    baseVersion?: number | (() => number | undefined);
     /**
      * For documents with `assets`: after `markClean` or `discard` retire a snapshot, delete the
      * stored assets nothing refers to any more (`collectEditorAssetGarbage`, best effort, keeping
@@ -21,8 +27,13 @@ export interface EditorAutosaveOptions extends Omit<AutosaveControllerOptions<Ed
 export interface EditorAutosave {
     readonly controller: AutosaveController<EditorDocumentFile>;
     readonly revisions: RevisionTracker;
-    /** An earlier session's unsaved snapshot of this document, or `null`. */
+    /** An earlier session's unsaved snapshot of this document, or `null` (snapshots made on a version older than `baseVersion` are retired). */
     checkRecovery(): Promise<AutosaveRecovery<EditorDocumentFile> | null>;
+    /**
+     * Checks for an earlier session's unsaved snapshot, restoring it into `doc` if it is valid and
+     * at least as new as `baseVersion`, or retiring it and starting autosave cleanly if stale/invalid.
+     */
+    recoverIfNewer(minimumBaseVersion?: number): Promise<LoadReport | null>;
     /** Loads a recovered snapshot into the document and starts autosaving. */
     restore(recovery: AutosaveRecovery<EditorDocumentFile>): LoadReport;
     /** Deletes the earlier session's snapshot and starts autosaving. */

package/dist/persistence/index.cjs

@@ -19,7 +19,9 @@
 
 
 
-var _chunkT2HUQBRCcjs = require('../chunk-T2HUQBRC.cjs');
+
+
+var _chunkDK33HLA2cjs = require('../chunk-DK33HLA2.cjs');
 
 
 
@@ -92,4 +94,6 @@ require('../chunk-2BSBFBOA.cjs');
 
 
 
-exports.EDITOR_ASSET_PREFIX = _chunkSJ2CPTQCcjs.EDITOR_ASSET_PREFIX; exports.EDITOR_DOCUMENT_FORMAT = _chunkSJ2CPTQCcjs.EDITOR_DOCUMENT_FORMAT; exports.EditorDocumentLoadError = _chunkSJ2CPTQCcjs.EditorDocumentLoadError; exports.InjectedStorageError = _chunkT2HUQBRCcjs.InjectedStorageError; exports.StorageUnavailableError = _chunkT2HUQBRCcjs.StorageUnavailableError; exports.collectAssetRefs = _chunkSJ2CPTQCcjs.collectAssetRefs; exports.collectEditorAssetGarbage = _chunkSJ2CPTQCcjs.collectEditorAssetGarbage; exports.collectRetiredEditorAssets = _chunkSJ2CPTQCcjs.collectRetiredEditorAssets; exports.createAutosaveController = _chunkT2HUQBRCcjs.createAutosaveController; exports.createDocumentToolProvider = _chunkT2HUQBRCcjs.createDocumentToolProvider; exports.createEditorAssetRegistry = _chunkSJ2CPTQCcjs.createEditorAssetRegistry; exports.createEditorAutosave = _chunkT2HUQBRCcjs.createEditorAutosave; exports.createEditorDocumentStore = _chunkT2HUQBRCcjs.createEditorDocumentStore; exports.createIndexedDbAdapter = _chunkT2HUQBRCcjs.createIndexedDbAdapter; exports.createLoadReport = _chunkSJ2CPTQCcjs.createLoadReport; exports.createLocalStorageAdapter = _chunkT2HUQBRCcjs.createLocalStorageAdapter; exports.createMemoryStorage = _chunkT2HUQBRCcjs.createMemoryStorage; exports.createOpfsAdapter = _chunkT2HUQBRCcjs.createOpfsAdapter; exports.createRecoveryPolicy = _chunkT2HUQBRCcjs.createRecoveryPolicy; exports.createRevisionTracker = _chunkT2HUQBRCcjs.createRevisionTracker; exports.defineEditorDocument = _chunkSJ2CPTQCcjs.defineEditorDocument; exports.exponentialBackoff = _chunkT2HUQBRCcjs.exponentialBackoff; exports.externalizeAssets = _chunkSJ2CPTQCcjs.externalizeAssets; exports.formatRecoveryMessage = _chunkT2HUQBRCcjs.formatRecoveryMessage; exports.hasLoadProblems = _chunkSJ2CPTQCcjs.hasLoadProblems; exports.internalizeAssets = _chunkSJ2CPTQCcjs.internalizeAssets; exports.isEditorDocumentFile = _chunkSJ2CPTQCcjs.isEditorDocumentFile; exports.isIndexedDbAvailable = _chunkT2HUQBRCcjs.isIndexedDbAvailable; exports.isInlineAsset = _chunkSJ2CPTQCcjs.isInlineAsset; exports.isLocalStorageAvailable = _chunkT2HUQBRCcjs.isLocalStorageAvailable; exports.isOpfsAvailable = _chunkT2HUQBRCcjs.isOpfsAvailable; exports.loadDocument = _chunkSJ2CPTQCcjs.loadDocument; exports.loadSections = _chunkSJ2CPTQCcjs.loadSections; exports.migrateDocument = _chunkSJ2CPTQCcjs.migrateDocument; exports.parseEditorDocument = _chunkSJ2CPTQCcjs.parseEditorDocument; exports.persistEditorAssets = _chunkSJ2CPTQCcjs.persistEditorAssets; exports.preloadEditorAssets = _chunkSJ2CPTQCcjs.preloadEditorAssets; exports.recoveryMetaKey = _chunkT2HUQBRCcjs.recoveryMetaKey; exports.serializeEditorDocument = _chunkSJ2CPTQCcjs.serializeEditorDocument; exports.slugifyDocumentName = _chunkT2HUQBRCcjs.slugifyDocumentName; exports.toEditorDocumentFile = _chunkSJ2CPTQCcjs.toEditorDocumentFile; exports.tryCollectEditorAssetGarbage = _chunkSJ2CPTQCcjs.tryCollectEditorAssetGarbage; exports.withEditorAssets = _chunkSJ2CPTQCcjs.withEditorAssets; exports.withStorageFailures = _chunkT2HUQBRCcjs.withStorageFailures;
+
+
+exports.EDITOR_ASSET_PREFIX = _chunkSJ2CPTQCcjs.EDITOR_ASSET_PREFIX; exports.EDITOR_DOCUMENT_FORMAT = _chunkSJ2CPTQCcjs.EDITOR_DOCUMENT_FORMAT; exports.EditorDocumentLoadError = _chunkSJ2CPTQCcjs.EditorDocumentLoadError; exports.EditorRemoteConflictError = _chunkDK33HLA2cjs.EditorRemoteConflictError; exports.InjectedStorageError = _chunkDK33HLA2cjs.InjectedStorageError; exports.StorageUnavailableError = _chunkDK33HLA2cjs.StorageUnavailableError; exports.collectAssetRefs = _chunkSJ2CPTQCcjs.collectAssetRefs; exports.collectEditorAssetGarbage = _chunkSJ2CPTQCcjs.collectEditorAssetGarbage; exports.collectRetiredEditorAssets = _chunkSJ2CPTQCcjs.collectRetiredEditorAssets; exports.createAutosaveController = _chunkDK33HLA2cjs.createAutosaveController; exports.createDocumentToolProvider = _chunkDK33HLA2cjs.createDocumentToolProvider; exports.createEditorAssetRegistry = _chunkSJ2CPTQCcjs.createEditorAssetRegistry; exports.createEditorAutosave = _chunkDK33HLA2cjs.createEditorAutosave; exports.createEditorDocumentStore = _chunkDK33HLA2cjs.createEditorDocumentStore; exports.createEditorRemoteSync = _chunkDK33HLA2cjs.createEditorRemoteSync; exports.createIndexedDbAdapter = _chunkDK33HLA2cjs.createIndexedDbAdapter; exports.createLoadReport = _chunkSJ2CPTQCcjs.createLoadReport; exports.createLocalStorageAdapter = _chunkDK33HLA2cjs.createLocalStorageAdapter; exports.createMemoryStorage = _chunkDK33HLA2cjs.createMemoryStorage; exports.createOpfsAdapter = _chunkDK33HLA2cjs.createOpfsAdapter; exports.createRecoveryPolicy = _chunkDK33HLA2cjs.createRecoveryPolicy; exports.createRevisionTracker = _chunkDK33HLA2cjs.createRevisionTracker; exports.defineEditorDocument = _chunkSJ2CPTQCcjs.defineEditorDocument; exports.exponentialBackoff = _chunkDK33HLA2cjs.exponentialBackoff; exports.externalizeAssets = _chunkSJ2CPTQCcjs.externalizeAssets; exports.formatRecoveryMessage = _chunkDK33HLA2cjs.formatRecoveryMessage; exports.hasLoadProblems = _chunkSJ2CPTQCcjs.hasLoadProblems; exports.internalizeAssets = _chunkSJ2CPTQCcjs.internalizeAssets; exports.isEditorDocumentFile = _chunkSJ2CPTQCcjs.isEditorDocumentFile; exports.isIndexedDbAvailable = _chunkDK33HLA2cjs.isIndexedDbAvailable; exports.isInlineAsset = _chunkSJ2CPTQCcjs.isInlineAsset; exports.isLocalStorageAvailable = _chunkDK33HLA2cjs.isLocalStorageAvailable; exports.isOpfsAvailable = _chunkDK33HLA2cjs.isOpfsAvailable; exports.loadDocument = _chunkSJ2CPTQCcjs.loadDocument; exports.loadSections = _chunkSJ2CPTQCcjs.loadSections; exports.migrateDocument = _chunkSJ2CPTQCcjs.migrateDocument; exports.parseEditorDocument = _chunkSJ2CPTQCcjs.parseEditorDocument; exports.persistEditorAssets = _chunkSJ2CPTQCcjs.persistEditorAssets; exports.preloadEditorAssets = _chunkSJ2CPTQCcjs.preloadEditorAssets; exports.recoveryMetaKey = _chunkDK33HLA2cjs.recoveryMetaKey; exports.serializeEditorDocument = _chunkSJ2CPTQCcjs.serializeEditorDocument; exports.slugifyDocumentName = _chunkDK33HLA2cjs.slugifyDocumentName; exports.toEditorDocumentFile = _chunkSJ2CPTQCcjs.toEditorDocumentFile; exports.tryCollectEditorAssetGarbage = _chunkSJ2CPTQCcjs.tryCollectEditorAssetGarbage; exports.withEditorAssets = _chunkSJ2CPTQCcjs.withEditorAssets; exports.withStorageFailures = _chunkDK33HLA2cjs.withStorageFailures;

package/dist/persistence/index.d.cts

@@ -5,6 +5,7 @@ export * from "./migrate.cjs";
 export * from "./revisions.cjs";
 export * from "./editorDocument.cjs";
 export * from "./editorAutosave.cjs";
+export * from "./remoteSync.cjs";
 export * from "./documentStore.cjs";
 export * from "./documentTools.cjs";
 export * from "./assets.cjs";

package/dist/persistence/index.d.ts

@@ -5,6 +5,7 @@ export * from "./migrate.js";
 export * from "./revisions.js";
 export * from "./editorDocument.js";
 export * from "./editorAutosave.js";
+export * from "./remoteSync.js";
 export * from "./documentStore.js";
 export * from "./documentTools.js";
 export * from "./assets.js";

package/dist/persistence/index.js

@@ -1,10 +1,12 @@
 import {
+  EditorRemoteConflictError,
   InjectedStorageError,
   StorageUnavailableError,
   createAutosaveController,
   createDocumentToolProvider,
   createEditorAutosave,
   createEditorDocumentStore,
+  createEditorRemoteSync,
   createIndexedDbAdapter,
   createLocalStorageAdapter,
   createMemoryStorage,
@@ -19,7 +21,7 @@ import {
   recoveryMetaKey,
   slugifyDocumentName,
   withStorageFailures
-} from "../chunk-JV7DKLMX.js";
+} from "../chunk-KBH6CM3U.js";
 import {
   EDITOR_ASSET_PREFIX,
   EDITOR_DOCUMENT_FORMAT,
@@ -51,6 +53,7 @@ export {
   EDITOR_ASSET_PREFIX,
   EDITOR_DOCUMENT_FORMAT,
   EditorDocumentLoadError,
+  EditorRemoteConflictError,
   InjectedStorageError,
   StorageUnavailableError,
   collectAssetRefs,
@@ -61,6 +64,7 @@ export {
   createEditorAssetRegistry,
   createEditorAutosave,
   createEditorDocumentStore,
+  createEditorRemoteSync,
   createIndexedDbAdapter,
   createLoadReport,
   createLocalStorageAdapter,

package/dist/persistence/remoteSync.d.cts

@@ -0,0 +1,152 @@
+import type { EditorDocument } from "./editorDocument.cjs";
+import type { EditorAutosave } from "./editorAutosave.cjs";
+export type EditorRemoteSyncState = "idle" | "pending" | "saving" | "saved" | "error";
+export interface EditorRemoteSyncStatus {
+    status: EditorRemoteSyncState;
+    version: number;
+    savedVersion: number;
+    dirty: boolean;
+    lastSavedAt: number | null;
+    error?: unknown;
+}
+export interface EditorRemoteSaveContext<TDocument = unknown, TDiff = unknown> {
+    document: TDocument;
+    /** The version to write. */
+    version: number;
+    /**
+     * The server version this save builds on (the last one confirmed). For a compare-and-set
+     * write, update only where the stored version still equals it, and return `{ conflict: true }`
+     * when nothing was updated.
+     */
+    baseVersion: number;
+    /** Changes since the last saved snapshot (with the `diff` option). */
+    diff?: TDiff;
+}
+export interface EditorRemoteSaveResult {
+    version?: number;
+    /**
+     * The server holds a newer version than `baseVersion`, so nothing was written. The controller
+     * calls `onConflict` (or reports an `EditorRemoteConflictError` without it) and keeps the edits.
+     */
+    conflict?: boolean;
+}
+export interface EditorRemoteConflictContext<TDocument = unknown> {
+    /** What this session tried to save. */
+    document: TDocument;
+    /** The last snapshot the server confirmed: the common base for a three-way merge. */
+    base: TDocument;
+    /** The server version reported with the conflict, when `save` returned one. */
+    serverVersion?: number;
+    /**
+     * Runs `fn` (e.g. loading the merged document into the editor) without it counting as a local
+     * change, so it is not broadcast as one; the retry save picks the result up.
+     */
+    apply<TResult>(fn: () => TResult): TResult;
+}
+export interface EditorRemoteConflictResolution<TDocument = unknown> {
+    /** The server's version the merge was made on; the retry save builds on it. */
+    serverVersion: number;
+    /** The server's document, used as the base for the retry's `diff` (default: the old base). */
+    serverDocument?: TDocument;
+}
+/** Reported through `onError` / `status().error` when a save conflicts and is not resolved. */
+export declare class EditorRemoteConflictError extends Error {
+    readonly serverVersion?: number | undefined;
+    constructor(serverVersion?: number | undefined);
+}
+export interface EditorRemoteLocalChangeEvent<TDocument = unknown, TDiff = unknown> {
+    document: TDocument;
+    baseline: TDocument;
+    diff?: TDiff;
+    version: number;
+}
+export interface EditorRemoteSyncOptions<TDocument = unknown, TDiff = unknown> {
+    /**
+     * Persists the latest document snapshot and version to the remote backend.
+     * May return `{ version }` or a numeric `version` if the server advanced the version higher.
+     */
+    save: (context: EditorRemoteSaveContext<TDocument, TDiff>) => Promise<EditorRemoteSaveResult | number | void>;
+    /** Initial known server version of the document (default `0`). */
+    initialVersion?: number;
+    /** Debounce delay in milliseconds after a local edit before calling `save` (default `500`). */
+    debounceMs?: number;
+    /**
+     * Optional diff calculator. `onLocalChange` receives the diff from the previous local snapshot
+     * (the one edit); `save` receives the diff from the last saved snapshot (every edit it covers).
+     */
+    diff?: (current: TDocument, baseline: TDocument) => TDiff;
+    /**
+     * Optional predicate returning `true` when `diff` represents no meaningful change.
+     * When omitted, compares `JSON.stringify(current) === JSON.stringify(baseline)`.
+     */
+    isEmptyDiff?: (diff: TDiff, current: TDocument, baseline: TDocument) => boolean;
+    /**
+     * Invoked immediately whenever a local document change is detected (before `save` debounce),
+     * e.g. for broadcasting incremental diffs to realtime collaborators.
+     */
+    onLocalChange?: (event: EditorRemoteLocalChangeEvent<TDocument, TDiff>) => void;
+    /** Invoked when a remote `save` completes. */
+    onSaved?: (event: {
+        document: TDocument;
+        version: number;
+    }) => void;
+    /** Invoked when a remote `save` throws. */
+    onError?: (error: unknown) => void;
+    /**
+     * Resolves a conflicting save (`save` returned `{ conflict: true }`): fetch the server's
+     * document, merge this session's edits into it (`base` → `document`), load the result with
+     * `apply`, and return the server's version. The controller then saves again on top of it.
+     */
+    onConflict?: (context: EditorRemoteConflictContext<TDocument>) => Promise<EditorRemoteConflictResolution<TDocument>> | EditorRemoteConflictResolution<TDocument>;
+    /** Conflicts resolved in a row before the controller gives up with an error (default `3`). */
+    maxConflictRetries?: number;
+    /**
+     * Optional crash-recovery autosave instance. When a remote save succeeds and no newer
+     * local edits occurred while it was in flight, `autosave.markClean()` is called automatically.
+     */
+    autosave?: Pick<EditorAutosave, "markClean">;
+    /** Wall clock (default `Date.now`). */
+    now?: () => number;
+}
+export interface EditorRemoteSync<TDocument = unknown, TDiff = unknown> {
+    /** Current local version number. */
+    version(): number;
+    /** Last version confirmed saved by the remote server. */
+    savedVersion(): number;
+    /** Whether local changes are waiting to be saved or currently saving. */
+    dirty(): boolean;
+    /** Current sync status snapshot. */
+    status(): EditorRemoteSyncStatus;
+    /** Last committed local baseline snapshot. */
+    baseline(): TDocument;
+    /** Checks the document for changes against `baseline()` (called automatically via `doc.subscribe`). */
+    notify(): boolean;
+    /**
+     * Runs `fn` while suppressing local change detection (so incoming collaborator diffs or
+     * server loads do not echo back a save), then updates `baseline` and advances `version` /
+     * `savedVersion` to `Math.max(version, remoteVersion)`.
+     */
+    applyRemote<TResult>(fn: () => TResult, remoteVersion?: number): TResult;
+    /** Resets the baseline to `doc.getDocument()` and updates `version` / `savedVersion`. */
+    resetBaseline(remoteVersion?: number): void;
+    /** Cancels any debounce timer and immediately saves pending changes. */
+    flush(): Promise<boolean>;
+    /** Resolves when any pending or in-flight save has settled. */
+    whenIdle(): Promise<void>;
+    /** Subscribes to status changes. */
+    subscribe(listener: (status: EditorRemoteSyncStatus) => void): () => void;
+    /** Cancels timers and unsubscribes from `doc`, without discarding in-flight work. */
+    destroy(): void;
+}
+/**
+ * Reactive, version-safe remote persistence controller for an `EditorDocument`.
+ *
+ * - Subscribes to `doc` so every edit (history steps, undo/redo, node drags/resizes, inline
+ *   node data updates, and companion `extras` changes) automatically diffs against the last
+ *   baseline, emits `onLocalChange` for realtime collaboration, and schedules a debounced save.
+ * - Serializes remote `save` calls so two saves never overlap on the wire; edits made while a
+ *   save is in flight are coalesced into a single follow-up save.
+ * - Advances versions monotonically (`Math.max(localVersion, remoteVersion) + 1`), preventing
+ *   version-mismatch wedging when collaborators or server triggers advance the remote version.
+ */
+export declare function createEditorRemoteSync<TDocument = unknown, TDiff = unknown>(doc: EditorDocument<TDocument>, options: EditorRemoteSyncOptions<TDocument, TDiff>): EditorRemoteSync<TDocument, TDiff>;

package/dist/persistence/remoteSync.d.ts

@@ -0,0 +1,152 @@
+import type { EditorDocument } from "./editorDocument.js";
+import type { EditorAutosave } from "./editorAutosave.js";
+export type EditorRemoteSyncState = "idle" | "pending" | "saving" | "saved" | "error";
+export interface EditorRemoteSyncStatus {
+    status: EditorRemoteSyncState;
+    version: number;
+    savedVersion: number;
+    dirty: boolean;
+    lastSavedAt: number | null;
+    error?: unknown;
+}
+export interface EditorRemoteSaveContext<TDocument = unknown, TDiff = unknown> {
+    document: TDocument;
+    /** The version to write. */
+    version: number;
+    /**
+     * The server version this save builds on (the last one confirmed). For a compare-and-set
+     * write, update only where the stored version still equals it, and return `{ conflict: true }`
+     * when nothing was updated.
+     */
+    baseVersion: number;
+    /** Changes since the last saved snapshot (with the `diff` option). */
+    diff?: TDiff;
+}
+export interface EditorRemoteSaveResult {
+    version?: number;
+    /**
+     * The server holds a newer version than `baseVersion`, so nothing was written. The controller
+     * calls `onConflict` (or reports an `EditorRemoteConflictError` without it) and keeps the edits.
+     */
+    conflict?: boolean;
+}
+export interface EditorRemoteConflictContext<TDocument = unknown> {
+    /** What this session tried to save. */
+    document: TDocument;
+    /** The last snapshot the server confirmed: the common base for a three-way merge. */
+    base: TDocument;
+    /** The server version reported with the conflict, when `save` returned one. */
+    serverVersion?: number;
+    /**
+     * Runs `fn` (e.g. loading the merged document into the editor) without it counting as a local
+     * change, so it is not broadcast as one; the retry save picks the result up.
+     */
+    apply<TResult>(fn: () => TResult): TResult;
+}
+export interface EditorRemoteConflictResolution<TDocument = unknown> {
+    /** The server's version the merge was made on; the retry save builds on it. */
+    serverVersion: number;
+    /** The server's document, used as the base for the retry's `diff` (default: the old base). */
+    serverDocument?: TDocument;
+}
+/** Reported through `onError` / `status().error` when a save conflicts and is not resolved. */
+export declare class EditorRemoteConflictError extends Error {
+    readonly serverVersion?: number | undefined;
+    constructor(serverVersion?: number | undefined);
+}
+export interface EditorRemoteLocalChangeEvent<TDocument = unknown, TDiff = unknown> {
+    document: TDocument;
+    baseline: TDocument;
+    diff?: TDiff;
+    version: number;
+}
+export interface EditorRemoteSyncOptions<TDocument = unknown, TDiff = unknown> {
+    /**
+     * Persists the latest document snapshot and version to the remote backend.
+     * May return `{ version }` or a numeric `version` if the server advanced the version higher.
+     */
+    save: (context: EditorRemoteSaveContext<TDocument, TDiff>) => Promise<EditorRemoteSaveResult | number | void>;
+    /** Initial known server version of the document (default `0`). */
+    initialVersion?: number;
+    /** Debounce delay in milliseconds after a local edit before calling `save` (default `500`). */
+    debounceMs?: number;
+    /**
+     * Optional diff calculator. `onLocalChange` receives the diff from the previous local snapshot
+     * (the one edit); `save` receives the diff from the last saved snapshot (every edit it covers).
+     */
+    diff?: (current: TDocument, baseline: TDocument) => TDiff;
+    /**
+     * Optional predicate returning `true` when `diff` represents no meaningful change.
+     * When omitted, compares `JSON.stringify(current) === JSON.stringify(baseline)`.
+     */
+    isEmptyDiff?: (diff: TDiff, current: TDocument, baseline: TDocument) => boolean;
+    /**
+     * Invoked immediately whenever a local document change is detected (before `save` debounce),
+     * e.g. for broadcasting incremental diffs to realtime collaborators.
+     */
+    onLocalChange?: (event: EditorRemoteLocalChangeEvent<TDocument, TDiff>) => void;
+    /** Invoked when a remote `save` completes. */
+    onSaved?: (event: {
+        document: TDocument;
+        version: number;
+    }) => void;
+    /** Invoked when a remote `save` throws. */
+    onError?: (error: unknown) => void;
+    /**
+     * Resolves a conflicting save (`save` returned `{ conflict: true }`): fetch the server's
+     * document, merge this session's edits into it (`base` → `document`), load the result with
+     * `apply`, and return the server's version. The controller then saves again on top of it.
+     */
+    onConflict?: (context: EditorRemoteConflictContext<TDocument>) => Promise<EditorRemoteConflictResolution<TDocument>> | EditorRemoteConflictResolution<TDocument>;
+    /** Conflicts resolved in a row before the controller gives up with an error (default `3`). */
+    maxConflictRetries?: number;
+    /**
+     * Optional crash-recovery autosave instance. When a remote save succeeds and no newer
+     * local edits occurred while it was in flight, `autosave.markClean()` is called automatically.
+     */
+    autosave?: Pick<EditorAutosave, "markClean">;
+    /** Wall clock (default `Date.now`). */
+    now?: () => number;
+}
+export interface EditorRemoteSync<TDocument = unknown, TDiff = unknown> {
+    /** Current local version number. */
+    version(): number;
+    /** Last version confirmed saved by the remote server. */
+    savedVersion(): number;
+    /** Whether local changes are waiting to be saved or currently saving. */
+    dirty(): boolean;
+    /** Current sync status snapshot. */
+    status(): EditorRemoteSyncStatus;
+    /** Last committed local baseline snapshot. */
+    baseline(): TDocument;
+    /** Checks the document for changes against `baseline()` (called automatically via `doc.subscribe`). */
+    notify(): boolean;
+    /**
+     * Runs `fn` while suppressing local change detection (so incoming collaborator diffs or
+     * server loads do not echo back a save), then updates `baseline` and advances `version` /
+     * `savedVersion` to `Math.max(version, remoteVersion)`.
+     */
+    applyRemote<TResult>(fn: () => TResult, remoteVersion?: number): TResult;
+    /** Resets the baseline to `doc.getDocument()` and updates `version` / `savedVersion`. */
+    resetBaseline(remoteVersion?: number): void;
+    /** Cancels any debounce timer and immediately saves pending changes. */
+    flush(): Promise<boolean>;
+    /** Resolves when any pending or in-flight save has settled. */
+    whenIdle(): Promise<void>;
+    /** Subscribes to status changes. */
+    subscribe(listener: (status: EditorRemoteSyncStatus) => void): () => void;
+    /** Cancels timers and unsubscribes from `doc`, without discarding in-flight work. */
+    destroy(): void;
+}
+/**
+ * Reactive, version-safe remote persistence controller for an `EditorDocument`.
+ *
+ * - Subscribes to `doc` so every edit (history steps, undo/redo, node drags/resizes, inline
+ *   node data updates, and companion `extras` changes) automatically diffs against the last
+ *   baseline, emits `onLocalChange` for realtime collaboration, and schedules a debounced save.
+ * - Serializes remote `save` calls so two saves never overlap on the wire; edits made while a
+ *   save is in flight are coalesced into a single follow-up save.
+ * - Advances versions monotonically (`Math.max(localVersion, remoteVersion) + 1`), preventing
+ *   version-mismatch wedging when collaborators or server triggers advance the remote version.
+ */
+export declare function createEditorRemoteSync<TDocument = unknown, TDiff = unknown>(doc: EditorDocument<TDocument>, options: EditorRemoteSyncOptions<TDocument, TDiff>): EditorRemoteSync<TDocument, TDiff>;