@pixerate/editor 0.277.0 → 0.279.0

package/dist/{chunk-JV7DKLMX.js → chunk-KBH6CM3U.js}

@@ -473,6 +473,10 @@ function createAutosaveController(options) {
     return rev;
   };
   const docName = () => typeof options.name === "function" ? options.name() : options.name;
+  const readBaseVersion = () => {
+    const v = typeof options.baseVersion === "function" ? options.baseVersion() : options.baseVersion;
+    return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+  };
   const run = (action, rev) => {
     if (action.type === "writeSnapshot") {
       setInfo({ status: "saving", nextAttemptAt: null });
@@ -482,11 +486,13 @@ function createAutosaveController(options) {
         try {
           const text = serialize(getSnapshot());
           await storage.set(key, text);
+          const baseVersion = readBaseVersion();
           const meta = {
             dirty: true,
             revision: action.revision,
             time: wallClock(),
-            name: docName()
+            name: docName(),
+            ...baseVersion !== void 0 ? { baseVersion } : {}
           };
           await storage.set(metaKey, JSON.stringify(meta));
           ok = true;
@@ -607,7 +613,7 @@ function createAutosaveController(options) {
       tick();
       await whenIdle();
     },
-    async checkRecovery() {
+    async checkRecovery(checkOptions) {
       if (policy.ownsSnapshot) return null;
       let meta;
       try {
@@ -618,6 +624,12 @@ function createAutosaveController(options) {
         return null;
       }
       if (!meta || meta.dirty !== true) return null;
+      const required = checkOptions?.minimumBaseVersion ?? readBaseVersion();
+      if (required !== void 0 && (typeof meta.baseVersion === "number" ? meta.baseVersion : 0) < required) {
+        await storage.remove(metaKey).catch(() => void 0);
+        await storage.remove(key).catch(() => void 0);
+        return null;
+      }
       const text = await storage.get(key).catch(() => null);
       if (text === null) return null;
       try {
@@ -726,10 +738,36 @@ function createEditorAutosave(doc, options) {
     savedRevision: revisions.savedRevision
   });
   const unsubscribe = revisions.subscribe(() => controller.notify());
+  const retireRecovery = async () => {
+    await controller.discardRecovery();
+    controller.ready();
+    await collect();
+  };
   return {
     controller,
     revisions,
     checkRecovery: () => controller.checkRecovery(),
+    async recoverIfNewer(minimumBaseVersion) {
+      const recovery = await controller.checkRecovery(
+        minimumBaseVersion !== void 0 ? { minimumBaseVersion } : void 0
+      );
+      if (!recovery) {
+        controller.ready();
+        return null;
+      }
+      if (!recovery.snapshot) {
+        await retireRecovery();
+        return null;
+      }
+      try {
+        const report = doc.loadDocument(recovery.snapshot, { history: "reset" });
+        controller.ready();
+        return report;
+      } catch {
+        await retireRecovery();
+        return null;
+      }
+    },
     restore(recovery) {
       if (!recovery.snapshot) throw recovery.error ?? new Error("The recovered snapshot could not be read.");
       const report = doc.loadDocument(recovery.snapshot, { history: "reset" });
@@ -737,9 +775,7 @@ function createEditorAutosave(doc, options) {
       return report;
     },
     async discard() {
-      await controller.discardRecovery();
-      controller.ready();
-      await collect();
+      await retireRecovery();
     },
     async markClean() {
       revisions.markSaved();
@@ -754,6 +790,289 @@ function createEditorAutosave(doc, options) {
   };
 }
 
+// src/persistence/remoteSync.ts
+var EditorRemoteConflictError = class extends Error {
+  constructor(serverVersion) {
+    super(
+      serverVersion === void 0 ? "The document changed on the server since it was loaded; local edits were not saved." : `The document is at version ${serverVersion} on the server; local edits were not saved.`
+    );
+    this.serverVersion = serverVersion;
+    this.name = "EditorRemoteConflictError";
+  }
+  serverVersion;
+};
+var cloneSnapshot = (value) => {
+  try {
+    return JSON.parse(JSON.stringify(value));
+  } catch {
+    return value;
+  }
+};
+function createEditorRemoteSync(doc, options) {
+  const debounceMs = options.debounceMs ?? 500;
+  const now = options.now ?? Date.now;
+  let localVersion = options.initialVersion ?? 0;
+  let confirmedVersion = localVersion;
+  let localSequence = 0;
+  let savedSequence = 0;
+  let baselineSnapshot = cloneSnapshot(doc.getDocument());
+  let savedSnapshot = baselineSnapshot;
+  let state = "idle";
+  let lastSavedAt = null;
+  let lastError = void 0;
+  let isApplyingRemote = false;
+  let conflictRetries = 0;
+  let destroyed = false;
+  let debounceTimer = null;
+  let inFlightPromise = null;
+  const listeners = /* @__PURE__ */ new Set();
+  const getStatus = () => ({
+    status: state,
+    version: localVersion,
+    savedVersion: confirmedVersion,
+    dirty: localSequence > savedSequence,
+    lastSavedAt,
+    ...lastError !== void 0 ? { error: lastError } : {}
+  });
+  const emit = () => {
+    const currentStatus = getStatus();
+    listeners.forEach((listener) => {
+      try {
+        listener(currentStatus);
+      } catch (error) {
+        console.error("[remoteSync] Error in status listener:", error);
+      }
+    });
+  };
+  const clearTimer = () => {
+    if (debounceTimer !== null) {
+      clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+  };
+  const hasChanged = (current, baseline) => {
+    if (options.diff) {
+      const diff = options.diff(current, baseline);
+      const empty = options.isEmptyDiff ? options.isEmptyDiff(diff, current, baseline) : JSON.stringify(current) === JSON.stringify(baseline);
+      return { changed: !empty, diff };
+    }
+    return { changed: JSON.stringify(current) !== JSON.stringify(baseline) };
+  };
+  const suppressed = (fn) => {
+    const wasApplying = isApplyingRemote;
+    isApplyingRemote = true;
+    try {
+      return fn();
+    } finally {
+      isApplyingRemote = wasApplying;
+    }
+  };
+  const executeSave = async () => {
+    if (inFlightPromise) {
+      await inFlightPromise;
+      if (localSequence > savedSequence) {
+        return executeSave();
+      }
+      return true;
+    }
+    if (localSequence <= savedSequence) {
+      return true;
+    }
+    clearTimer();
+    const targetSequence = localSequence;
+    const snapshotToSave = cloneSnapshot(baselineSnapshot);
+    const diffToSave = options.diff ? options.diff(snapshotToSave, savedSnapshot) : void 0;
+    const versionToSave = Math.max(localVersion, confirmedVersion + 1);
+    localVersion = versionToSave;
+    state = "saving";
+    lastError = void 0;
+    emit();
+    const run = (async () => {
+      try {
+        const result = await options.save({
+          document: snapshotToSave,
+          version: versionToSave,
+          baseVersion: confirmedVersion,
+          diff: diffToSave
+        });
+        if (result && typeof result === "object" && result.conflict) {
+          const serverVersion = typeof result.version === "number" ? result.version : void 0;
+          if (!options.onConflict || conflictRetries >= (options.maxConflictRetries ?? 3)) {
+            conflictRetries = 0;
+            throw new EditorRemoteConflictError(serverVersion);
+          }
+          conflictRetries++;
+          const resolution = await options.onConflict({
+            document: snapshotToSave,
+            base: savedSnapshot,
+            serverVersion,
+            apply: (fn) => suppressed(fn)
+          });
+          confirmedVersion = resolution.serverVersion;
+          localVersion = Math.max(localVersion, confirmedVersion);
+          if (resolution.serverDocument !== void 0) savedSnapshot = cloneSnapshot(resolution.serverDocument);
+          baselineSnapshot = cloneSnapshot(doc.getDocument());
+          localSequence++;
+          state = "pending";
+          emit();
+          return true;
+        }
+        conflictRetries = 0;
+        const returnedVersion = typeof result === "number" ? result : result && typeof result === "object" && typeof result.version === "number" ? result.version : versionToSave;
+        confirmedVersion = Math.max(confirmedVersion, versionToSave, returnedVersion);
+        if (returnedVersion > localVersion) {
+          localVersion = returnedVersion;
+        }
+        savedSequence = Math.max(savedSequence, targetSequence);
+        savedSnapshot = snapshotToSave;
+        lastSavedAt = now();
+        lastError = void 0;
+        if (localSequence <= savedSequence) {
+          state = "saved";
+          try {
+            await options.autosave?.markClean();
+          } catch (error) {
+            console.error("[remoteSync] autosave.markClean failed:", error);
+          }
+        } else {
+          state = "pending";
+        }
+        options.onSaved?.({ document: snapshotToSave, version: confirmedVersion });
+        emit();
+        return true;
+      } catch (error) {
+        lastError = error;
+        state = "error";
+        options.onError?.(error);
+        emit();
+        return false;
+      }
+    })();
+    inFlightPromise = run;
+    let ok;
+    try {
+      ok = await run;
+    } finally {
+      if (inFlightPromise === run) inFlightPromise = null;
+    }
+    if (ok && localSequence > savedSequence && debounceTimer === null) {
+      return executeSave();
+    }
+    return ok;
+  };
+  const scheduleSave = () => {
+    clearTimer();
+    if (debounceMs <= 0) {
+      void executeSave();
+      return;
+    }
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      if (!destroyed) {
+        void executeSave();
+      }
+    }, debounceMs);
+  };
+  const notify = () => {
+    if (isApplyingRemote || destroyed) return false;
+    const current = cloneSnapshot(doc.getDocument());
+    const { changed, diff } = hasChanged(current, baselineSnapshot);
+    if (!changed) return false;
+    const previousBaseline = baselineSnapshot;
+    baselineSnapshot = current;
+    localSequence++;
+    localVersion = Math.max(localVersion, confirmedVersion) + 1;
+    if (state !== "saving") {
+      state = "pending";
+    }
+    emit();
+    options.onLocalChange?.({
+      document: current,
+      baseline: previousBaseline,
+      diff,
+      version: localVersion
+    });
+    scheduleSave();
+    return true;
+  };
+  const flush = async () => {
+    clearTimer();
+    notify();
+    if (localSequence <= savedSequence && !inFlightPromise) {
+      return true;
+    }
+    return executeSave();
+  };
+  const unsubscribeDoc = doc.subscribe(() => {
+    notify();
+  });
+  return {
+    version: () => localVersion,
+    savedVersion: () => confirmedVersion,
+    dirty: () => localSequence > savedSequence,
+    status: getStatus,
+    baseline: () => baselineSnapshot,
+    notify,
+    applyRemote(fn, remoteVersion) {
+      const wasApplying = isApplyingRemote;
+      const wasDirty = localSequence > savedSequence;
+      isApplyingRemote = true;
+      try {
+        const result = fn();
+        baselineSnapshot = cloneSnapshot(doc.getDocument());
+        if (typeof remoteVersion === "number" && Number.isFinite(remoteVersion)) {
+          confirmedVersion = Math.max(confirmedVersion, remoteVersion);
+          localVersion = Math.max(localVersion, remoteVersion);
+        }
+        if (!wasDirty) {
+          savedSequence = localSequence;
+          savedSnapshot = baselineSnapshot;
+        }
+        emit();
+        return result;
+      } finally {
+        isApplyingRemote = wasApplying;
+      }
+    },
+    resetBaseline(remoteVersion) {
+      clearTimer();
+      baselineSnapshot = cloneSnapshot(doc.getDocument());
+      savedSnapshot = baselineSnapshot;
+      if (typeof remoteVersion === "number" && Number.isFinite(remoteVersion)) {
+        localVersion = remoteVersion;
+        confirmedVersion = remoteVersion;
+      }
+      savedSequence = localSequence;
+      lastError = void 0;
+      state = "idle";
+      emit();
+    },
+    flush,
+    async whenIdle() {
+      while (debounceTimer !== null || inFlightPromise) {
+        if (debounceTimer !== null) {
+          await flush();
+        } else if (inFlightPromise) {
+          await inFlightPromise.catch(() => false);
+        }
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      listener(getStatus());
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    destroy() {
+      destroyed = true;
+      clearTimer();
+      unsubscribeDoc();
+      listeners.clear();
+    }
+  };
+}
+
 // src/persistence/documentStore.ts
 function slugifyDocumentName(name) {
   const slug = name.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
@@ -1067,6 +1386,8 @@ export {
   createAutosaveController,
   createRevisionTracker,
   createEditorAutosave,
+  EditorRemoteConflictError,
+  createEditorRemoteSync,
   slugifyDocumentName,
   createEditorDocumentStore,
   createDocumentToolProvider

package/dist/paint-editor/controller.d.cts

@@ -23,7 +23,7 @@ import { type PaintBrushInput, type PaintBrush } from './brushes.cjs';
 import { type BrushLibrary, type BrushLibraryFile } from '../brushes/library.cjs';
 import { type BrushPatch, type UnsettableBrushFacet } from '../brushes/patch.cjs';
 import type { Brush } from '../brushes/types.cjs';
-import type { ColorScheme } from '../color/dual.cjs';
+import { type ColorScheme, type ColorValue } from '../color/dual.cjs';
 import { type PaintCanvas, type PaintDocumentState, type PaintLayer } from './document.cjs';
 import { type ImageEncoder, type ImageFormat } from './encode.cjs';
 import type { PenPoint } from './engine.cjs';
@@ -206,8 +206,8 @@ export interface LiveStrokeUpdate {
     brushId?: string;
     /** Brush settings to change (as `setBrush` takes), on top of `brushId` or the stroke's brush. */
     brush?: Omit<PaintBrushInput, 'id'>;
-    /** A new colour #rrggbb (replaces gradient or effect paint). */
-    color?: string;
+    /** A new colour #rrggbb, or a light / dark pair (replaces gradient or effect paint). */
+    color?: ColorValue;
     /** Paint: a colour, gradient paint or effect paint; `null` back to the plain colour. */
     paint?: unknown;
     /** Another jitter seed (particles, scatter and texture fall differently). */
@@ -275,8 +275,12 @@ export interface PaintPreviewPlacement {
 export interface PaintStrokeInit {
     /** Default the active layer. */
     layerId?: string;
-    /** Default the editor colour. */
-    color?: string;
+    /**
+     * Default the editor colour. A light / dark pair (`DualColor`) is recorded with the stroke
+     * (`RecordedStroke.dualColor`): on a stroke layer the document draws its light side and the view
+     * the viewer's (`setColorScheme`); on a pixel layer it paints the scheme's side.
+     */
+    color?: ColorValue;
     /**
      * What this stroke paints with, instead of the editor's paint: a colour, gradient paint
      * (`@pixerate/editor/paint` `PaintSource`), or effect paint (render it first with
@@ -1062,9 +1066,29 @@ export declare class PaintEditorController {
     private brushColour;
     /**
      * The host's colour scheme: a paint colour that came from a brush's light / dark default
-     * resolves to the new side. Editor state, not an undo step.
+     * resolves to the new side, and stroke layers show their dual-colour strokes in it. Only the
+     * view changes: the document, history and change listeners don't hear of it.
      */
     setColorScheme(scheme: ColorScheme): void;
+    /**
+     * Stroke layers in the colour scheme: the document keeps every stroke layer drawn with each
+     * stroke's `color` (a dual-colour stroke's light side), so saved and shared documents never
+     * depend on who is looking. The view (display, image exports, the base a pointer stroke paints
+     * on) draws dual-colour strokes in the scheme's side instead. One cached surface per layer,
+     * brought up to date from the strokes that changed since it was drawn.
+     */
+    private schemeViews;
+    private schemeCopies;
+    /** Set while a stroke is painted for the document rather than the view (`runStroke` on a stroke layer): dual colours take this side. */
+    private paintScheme;
+    /** A stroke as the scheme shows it: itself, or (a dual-colour stroke) a copy in the scheme's side. */
+    private schemeStroke;
+    /** A stroke layer's surface in the scheme, or `null` when the document's pixels already show it. */
+    private schemeSurface;
+    /** `layers` with each stroke layer that holds dual-colour strokes shown in the scheme. */
+    private schemeLayers;
+    /** The paint colour's light / dark pair for a stroke with `brushId`, when the colour came from one (a brush's own or default colour, or `setColor`). */
+    private dualPaint;
     /** Locks the paint colour: choosing a brush with a default colour keeps it. Editor state, not an undo step. */
     setColorLocked(locked: boolean): void;
     /**
@@ -1075,8 +1099,12 @@ export declare class PaintEditorController {
     private takeBrushColour;
     /** A brush that always paints its own colour (`colour.own`): that colour, resolved for the scheme now; else `null`. */
     private ownColour;
-    /** Sets the paint colour (and goes back to one colour from gradient paint). */
-    setColor(color: string): string;
+    /**
+     * Sets the paint colour (and goes back to one colour from gradient paint). A light / dark pair
+     * paints the colour scheme's side, follows `setColorScheme`, and is recorded with each stroke
+     * painted in it. Returns the colour as #rrggbb.
+     */
+    setColor(color: ColorValue): string;
     /**
      * Sets what strokes paint with: one colour (`{ type: 'color', color }` or `#rrggbb`), or gradient
      * paint (`{ type: 'gradient', stops, space?, map?, softness? }`, see `@pixerate/editor/paint`),
@@ -1775,6 +1803,10 @@ export declare class PaintEditorController {
     liveStrokeArea(id: string): RasterRect | null;
     /** Commits a layer's new stroke list with its redrawn pixels, recorded for replays (one undo step). */
     private commitLiveStrokes;
+    /**
+     * The document with a layer's strokes set and its pixels redrawn. With `record` false (the same
+     * strokes drawn for the colour scheme) the pixel lock doesn't apply and no event is recorded for replays.
+     */
     private withLiveStrokes;
     /** Where a stroke painted (document pixels): as learnt when it was painted or drawn, else an estimate from its points and brush. */
     private strokeArea;

package/dist/paint-editor/controller.d.ts

@@ -23,7 +23,7 @@ import { type PaintBrushInput, type PaintBrush } from './brushes.js';
 import { type BrushLibrary, type BrushLibraryFile } from '../brushes/library.js';
 import { type BrushPatch, type UnsettableBrushFacet } from '../brushes/patch.js';
 import type { Brush } from '../brushes/types.js';
-import type { ColorScheme } from '../color/dual.js';
+import { type ColorScheme, type ColorValue } from '../color/dual.js';
 import { type PaintCanvas, type PaintDocumentState, type PaintLayer } from './document.js';
 import { type ImageEncoder, type ImageFormat } from './encode.js';
 import type { PenPoint } from './engine.js';
@@ -206,8 +206,8 @@ export interface LiveStrokeUpdate {
     brushId?: string;
     /** Brush settings to change (as `setBrush` takes), on top of `brushId` or the stroke's brush. */
     brush?: Omit<PaintBrushInput, 'id'>;
-    /** A new colour #rrggbb (replaces gradient or effect paint). */
-    color?: string;
+    /** A new colour #rrggbb, or a light / dark pair (replaces gradient or effect paint). */
+    color?: ColorValue;
     /** Paint: a colour, gradient paint or effect paint; `null` back to the plain colour. */
     paint?: unknown;
     /** Another jitter seed (particles, scatter and texture fall differently). */
@@ -275,8 +275,12 @@ export interface PaintPreviewPlacement {
 export interface PaintStrokeInit {
     /** Default the active layer. */
     layerId?: string;
-    /** Default the editor colour. */
-    color?: string;
+    /**
+     * Default the editor colour. A light / dark pair (`DualColor`) is recorded with the stroke
+     * (`RecordedStroke.dualColor`): on a stroke layer the document draws its light side and the view
+     * the viewer's (`setColorScheme`); on a pixel layer it paints the scheme's side.
+     */
+    color?: ColorValue;
     /**
      * What this stroke paints with, instead of the editor's paint: a colour, gradient paint
      * (`@pixerate/editor/paint` `PaintSource`), or effect paint (render it first with
@@ -1062,9 +1066,29 @@ export declare class PaintEditorController {
     private brushColour;
     /**
      * The host's colour scheme: a paint colour that came from a brush's light / dark default
-     * resolves to the new side. Editor state, not an undo step.
+     * resolves to the new side, and stroke layers show their dual-colour strokes in it. Only the
+     * view changes: the document, history and change listeners don't hear of it.
      */
     setColorScheme(scheme: ColorScheme): void;
+    /**
+     * Stroke layers in the colour scheme: the document keeps every stroke layer drawn with each
+     * stroke's `color` (a dual-colour stroke's light side), so saved and shared documents never
+     * depend on who is looking. The view (display, image exports, the base a pointer stroke paints
+     * on) draws dual-colour strokes in the scheme's side instead. One cached surface per layer,
+     * brought up to date from the strokes that changed since it was drawn.
+     */
+    private schemeViews;
+    private schemeCopies;
+    /** Set while a stroke is painted for the document rather than the view (`runStroke` on a stroke layer): dual colours take this side. */
+    private paintScheme;
+    /** A stroke as the scheme shows it: itself, or (a dual-colour stroke) a copy in the scheme's side. */
+    private schemeStroke;
+    /** A stroke layer's surface in the scheme, or `null` when the document's pixels already show it. */
+    private schemeSurface;
+    /** `layers` with each stroke layer that holds dual-colour strokes shown in the scheme. */
+    private schemeLayers;
+    /** The paint colour's light / dark pair for a stroke with `brushId`, when the colour came from one (a brush's own or default colour, or `setColor`). */
+    private dualPaint;
     /** Locks the paint colour: choosing a brush with a default colour keeps it. Editor state, not an undo step. */
     setColorLocked(locked: boolean): void;
     /**
@@ -1075,8 +1099,12 @@ export declare class PaintEditorController {
     private takeBrushColour;
     /** A brush that always paints its own colour (`colour.own`): that colour, resolved for the scheme now; else `null`. */
     private ownColour;
-    /** Sets the paint colour (and goes back to one colour from gradient paint). */
-    setColor(color: string): string;
+    /**
+     * Sets the paint colour (and goes back to one colour from gradient paint). A light / dark pair
+     * paints the colour scheme's side, follows `setColorScheme`, and is recorded with each stroke
+     * painted in it. Returns the colour as #rrggbb.
+     */
+    setColor(color: ColorValue): string;
     /**
      * Sets what strokes paint with: one colour (`{ type: 'color', color }` or `#rrggbb`), or gradient
      * paint (`{ type: 'gradient', stops, space?, map?, softness? }`, see `@pixerate/editor/paint`),
@@ -1775,6 +1803,10 @@ export declare class PaintEditorController {
     liveStrokeArea(id: string): RasterRect | null;
     /** Commits a layer's new stroke list with its redrawn pixels, recorded for replays (one undo step). */
     private commitLiveStrokes;
+    /**
+     * The document with a layer's strokes set and its pixels redrawn. With `record` false (the same
+     * strokes drawn for the colour scheme) the pixel lock doesn't apply and no event is recorded for replays.
+     */
     private withLiveStrokes;
     /** Where a stroke painted (document pixels): as learnt when it was painted or drawn, else an estimate from its points and brush. */
     private strokeArea;