@pixerate/editor 0.277.0 → 0.279.0

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>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.277.0",
+  "version": "0.279.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/pixerate-paint-editor/SKILL.md

@@ -11,7 +11,7 @@ seed: its grain is a height map (peaks and valleys) that grain-responsive brushe
 is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y down. See
 `pixerate-agent-tools` for errors, namespacing and batching.
 
-- **Brush colours.** Choosing a brush with a default colour (highlighter yellow, ballpoint blue, chalk light or dark for the colour scheme) makes it the paint colour, unless the colour is locked (`set_color` `locked`). Set the colour after choosing the brush, or lock it first.
+- **Brush colours.** Choosing a brush with a default colour (highlighter yellow, ballpoint blue, chalk light or dark for the colour scheme) makes it the paint colour, unless the colour is locked (`set_color` `locked`). Set the colour after choosing the brush, or lock it first. Strokes painted in a light / dark colour (a brush's pair, or `set_color` `dualColor`) record the pair. Paint them on a stroke layer (`add_layer` type `strokes`) when they should follow the viewer's theme: the document keeps the light side and each viewer sees their own scheme's; a pixel layer keeps the side it was painted in.
 - **Brushes** come from the shared brush library (`pixerate-brushes`: `list_brush_presets`, `create_brush`, `preview_brush`…) and are made of facets: a tip (size, hardness, spacing, angle, roundness, opacity, flow, blend), dynamics (pressure, tilt, velocity, jitter, a **rotation** mode `fixed`, `stroke` or `barrel`), behaviour (paper **grain** response, pick-up, wet or thick surface), marks, light, ferrofluid, motion and colour. `set_brush` chooses one and lays facet changes over it; `get_brush` reads it with the engine it paints with: `dab` (most media), `eraser`, `mixer` (the Mixer Brush: a reservoir of paint plus paint it picks up), `blender` (mixes the colours under and near the tip) or `smudge` (drags paint along the stroke), `wet` (watercolour, gouache, oil and the wet tools, below), `impasto` (thick paint with relief and material, below), `particle` (procedural particle brushes), `bristle` (a tuft of bristles) or `sticker` (sprays editable stickers).
 - **Wet media** (engine `wet`: `behaviour.surface` `wet`, and the wet tools; categories `watercolor` and `wet-tool`): a stroke lays water and pigment on the layer's **wet layer**, a fluid simulation that keeps running after the stroke: the water spreads until its edge is pinned by the paper, carries pigment out to the rim as it dries (edge darkening), drops pigment into the paper's valleys (granulation), pushes pigment back where new water flows in (blooms), bleeds between touching wet colours and runs downhill on a tilted canvas. Paint stays wet until it dries by itself (a few thousand steps) or `dry_paint` dries it; a dried wash is fixed, so the next wash **glazes** over it. A wet brush paints, or is a tool (`tool` `water`, `dryer`, `blow`, `blot`, `wet-blend`, `wet-drag`); `behaviour.wet` `water`, `pigment` (concentration), `body` (0 transparent watercolour .. 1 opaque gouache) and `rewet`, and `behaviour.strength`, set it up. Every result says whether paint is still wet (`wet` / `stillWet`).
 - **Behaviour** (`behaviour.exchange`, dab and mixer brushes) is how a brush treats paint already on the canvas: a **pick-up ratio** (how much paint each dab lifts and carries), a **mix ratio** (how much of the carried paint goes into what it lays down), **dirty** (keep the carried colour into the next stroke) and **multi-colour** (`tip`: several colours side by side across the tip; `dab`: the colour changes along the stroke). A Mixer Brush's `mixer.wet` / `mixer.mix` are the same two ratios. `get_mixer_brush` reads what the brush carries; `clean_mixer_brush` wipes it.
@@ -233,7 +233,7 @@ Listing, saving, sharing and previewing brushes are the brush library's tools (`
 | Tool | Use |
 | --- | --- |
 | `mix_colors` | Predict a mix: `colors` with `weight` parts (and optional tinting `strength`), `model` `pigment` (default, Kubelka-Munk: what pigment blends, the Mixer Brush, pigment blending tools and the pad do) or `rgb` (what normal blending and rgb mixing do). Returns `mixed` by the model plus `pigment` and `rgbLerp` for comparison. Changes nothing. Use it to choose stroke colours. |
-| `set_color` | Set the default paint `color` (and `secondaryColor`); back to one colour after gradient paint or effect paint. `locked: true` keeps it when you choose a brush with a default colour (by default choosing the highlighter makes your colour its yellow). Returns both colours and `locked`. |
+| `set_color` | Set the default paint `color` (and `secondaryColor`); back to one colour after gradient paint or effect paint. `dualColor: { light, dark }` sets a pair for the light and dark schemes instead: strokes record it, and on a stroke layer every viewer sees their own scheme's side. `locked: true` keeps it when you choose a brush with a default colour (by default choosing the highlighter makes your colour its yellow). Returns both colours and `locked` (and `dualColor` when given). |
 | `set_paint` | Set the paint: one colour, or gradient paint (`stops`, `space`, `map`, `softness`; see Gradient paint). Ends effect paint. Errors say what is wrong (unsorted stops, a bad mapping). Returns `paint`, `color`, `secondaryColor`. |
 | `pick_color` | Read the colour at `x`, `y`: of the painting with its paper, or of one layer (with alpha). |
 | `get_mixer_brush` | Read what the brush carries: the Mixer Brush `reservoir` and `amount` left, and `pickup` (paint picked up, kept by dirty brushes). |