pixelweaver 0.1.0

package/src/lib/recovery/idb-store.ts

@@ -0,0 +1,118 @@
+/**
+ * IndexedDB Storage -- thin wrapper for storing crash-recovery snapshots.
+ *
+ * Stores a single "latest" snapshot that is overwritten on each save.
+ * All operations are async and handle errors gracefully by logging
+ * warnings rather than throwing (IndexedDB failures should not crash the app).
+ */
+
+const DB_NAME = 'pixelweaver-recovery';
+const STORE_NAME = 'snapshots';
+const DB_VERSION = 1;
+
+export interface RecoverySnapshot {
+  /** Always "latest" -- we only keep one snapshot at a time. */
+  id: string;
+  timestamp: number;
+  projectName: string;
+  /** Serialized canvas states keyed by canvas ID. */
+  canvasStates: Record<string, {
+    width: number;
+    height: number;
+    layerTree: unknown;       // serialized LayerTreeState
+    pixelData: Record<string, ArrayBuffer>;  // layer ID -> RGBA bytes
+  }>;
+  /** Commands sent to the server but not yet acknowledged. */
+  pendingCommands: unknown[];
+}
+
+/**
+ * Open (or create) the recovery database.
+ * Creates the object store on first run or version upgrade.
+ */
+export async function openDB(): Promise<IDBDatabase> {
+  return new Promise<IDBDatabase>((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+
+    request.onupgradeneeded = () => {
+      const db = request.result;
+      if (!db.objectStoreNames.contains(STORE_NAME)) {
+        db.createObjectStore(STORE_NAME, { keyPath: 'id' });
+      }
+    };
+
+    request.onsuccess = () => { resolve(request.result); };
+    request.onerror = () => { reject(request.error ?? new Error('IndexedDB open failed')); };
+  });
+}
+
+/** Persist a recovery snapshot (overwrites any existing one). */
+export async function saveSnapshot(snapshot: RecoverySnapshot): Promise<void> {
+  try {
+    const db = await openDB();
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, 'readwrite');
+      const store = tx.objectStore(STORE_NAME);
+      store.put(snapshot);
+      tx.oncomplete = () => { db.close(); resolve(); };
+      tx.onerror = () => { db.close(); reject(tx.error ?? new Error('IndexedDB save transaction failed')); };
+    });
+  } catch (err) {
+    console.warn('[recovery] Failed to save snapshot:', err);
+  }
+}
+
+/** Load the most recent recovery snapshot, or null if none exists. */
+export async function loadSnapshot(): Promise<RecoverySnapshot | null> {
+  try {
+    const db = await openDB();
+    return await new Promise<RecoverySnapshot | null>((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, 'readonly');
+      const store = tx.objectStore(STORE_NAME);
+      const request = store.get('latest');
+      request.onsuccess = () => {
+        db.close();
+        // IDBRequest.result is `any`; narrow to our shape before resolving.
+        resolve((request.result as RecoverySnapshot | undefined) ?? null);
+      };
+      request.onerror = () => { db.close(); reject(request.error ?? new Error('IndexedDB load request failed')); };
+    });
+  } catch (err) {
+    console.warn('[recovery] Failed to load snapshot:', err);
+    return null;
+  }
+}
+
+/** Delete all recovery snapshots. */
+export async function clearSnapshot(): Promise<void> {
+  try {
+    const db = await openDB();
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, 'readwrite');
+      const store = tx.objectStore(STORE_NAME);
+      store.clear();
+      tx.oncomplete = () => { db.close(); resolve(); };
+      tx.onerror = () => { db.close(); reject(tx.error ?? new Error('IndexedDB clear transaction failed')); };
+    });
+  } catch (err) {
+    console.warn('[recovery] Failed to clear snapshot:', err);
+  }
+}
+
+/** Check whether a recovery snapshot exists without loading its data. */
+export async function hasSnapshot(): Promise<boolean> {
+  try {
+    const db = await openDB();
+    return await new Promise<boolean>((resolve, reject) => {
+      const tx = db.transaction(STORE_NAME, 'readonly');
+      const store = tx.objectStore(STORE_NAME);
+      // count with a key range of just "latest" is cheaper than get
+      const request = store.count(IDBKeyRange.only('latest'));
+      request.onsuccess = () => { db.close(); resolve(request.result > 0); };
+      request.onerror = () => { db.close(); reject(request.error ?? new Error('IndexedDB count request failed')); };
+    });
+  } catch (err) {
+    console.warn('[recovery] Failed to check snapshot:', err);
+    return false;
+  }
+}

package/src/lib/recovery/recovery-manager.test.ts

@@ -0,0 +1,321 @@
+/**
+ * Tests for RecoveryManager.
+ *
+ * IndexedDB is not available in jsdom, so we mock the idb-store module
+ * and focus on testing the manager's coordination logic:
+ *   - pending command tracking (add, remove, list)
+ *   - snapshot interval lifecycle (start, stop)
+ *   - snapshot save triggered periodically and on visibility change
+ *   - state gatherer integration
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { RecoveryManager } from './recovery-manager.js';
+import type { RecoverySnapshot } from './idb-store.js';
+
+// --- Mock the IndexedDB store ---
+
+vi.mock('./idb-store.js', () => ({
+  saveSnapshot: vi.fn<(snapshot: RecoverySnapshot) => Promise<void>>().mockResolvedValue(undefined),
+  loadSnapshot: vi.fn<() => Promise<RecoverySnapshot | null>>().mockResolvedValue(null),
+  clearSnapshot: vi.fn<() => Promise<void>>().mockResolvedValue(undefined),
+  hasSnapshot: vi.fn<() => Promise<boolean>>().mockResolvedValue(false),
+}));
+
+// Import after mocking so we get the mocked versions
+import { saveSnapshot, loadSnapshot, clearSnapshot, hasSnapshot } from './idb-store.js';
+
+const mockedSaveSnapshot = vi.mocked(saveSnapshot);
+const mockedLoadSnapshot = vi.mocked(loadSnapshot);
+const mockedClearSnapshot = vi.mocked(clearSnapshot);
+const mockedHasSnapshot = vi.mocked(hasSnapshot);
+
+// --- Helpers ---
+
+function makeGatherer(projectName = 'Test Project') {
+  return () => ({
+    projectName,
+    canvasStates: {
+      main: {
+        width: 32,
+        height: 32,
+        layerTree: { layers: [], activeLayerId: '' },
+        pixelData: {},
+      },
+    },
+  });
+}
+
+// --- Tests ---
+
+describe('RecoveryManager', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  // --- Pending command tracking ---
+
+  describe('pending command tracking', () => {
+    it('should add a pending command', () => {
+      const manager = new RecoveryManager();
+      manager.addPendingCommand({ id: 'cmd-1', type: 'draw_pixel', params: {} });
+
+      const pending = manager.getPendingCommands();
+      expect(pending).toHaveLength(1);
+      expect(pending[0]?.id).toBe('cmd-1');
+    });
+
+    it('should add multiple pending commands', () => {
+      const manager = new RecoveryManager();
+      manager.addPendingCommand({ id: 'cmd-1', type: 'draw' });
+      manager.addPendingCommand({ id: 'cmd-2', type: 'fill' });
+      manager.addPendingCommand({ id: 'cmd-3', type: 'erase' });
+
+      expect(manager.getPendingCommands()).toHaveLength(3);
+    });
+
+    it('should remove a pending command by ID', () => {
+      const manager = new RecoveryManager();
+      manager.addPendingCommand({ id: 'cmd-1', type: 'draw' });
+      manager.addPendingCommand({ id: 'cmd-2', type: 'fill' });
+
+      manager.removePendingCommand('cmd-1');
+
+      const pending = manager.getPendingCommands();
+      expect(pending).toHaveLength(1);
+      expect(pending[0]?.id).toBe('cmd-2');
+    });
+
+    it('should be a no-op when removing a non-existent command', () => {
+      const manager = new RecoveryManager();
+      manager.addPendingCommand({ id: 'cmd-1', type: 'draw' });
+
+      manager.removePendingCommand('cmd-999');
+
+      expect(manager.getPendingCommands()).toHaveLength(1);
+    });
+
+    it('should include pending commands in the snapshot', async () => {
+      const manager = new RecoveryManager();
+      manager.setStateGatherer(makeGatherer());
+      manager.addPendingCommand({ id: 'cmd-1', type: 'draw' });
+      manager.addPendingCommand({ id: 'cmd-2', type: 'fill' });
+
+      await manager.saveSnapshot();
+
+      expect(mockedSaveSnapshot).toHaveBeenCalledOnce();
+      const saved = mockedSaveSnapshot.mock.calls[0]?.[0];
+      expect(saved?.pendingCommands).toHaveLength(2);
+    });
+  });
+
+  // --- Snapshot interval lifecycle ---
+
+  describe('snapshot interval', () => {
+    it('should start periodic saves at the configured interval', async () => {
+      const manager = new RecoveryManager(1000);
+      manager.setStateGatherer(makeGatherer());
+      manager.start();
+
+      // No save yet at t=0
+      expect(mockedSaveSnapshot).not.toHaveBeenCalled();
+
+      // Advance past one interval
+      await vi.advanceTimersByTimeAsync(1000);
+      expect(mockedSaveSnapshot).toHaveBeenCalledTimes(1);
+
+      // Advance past another interval
+      await vi.advanceTimersByTimeAsync(1000);
+      expect(mockedSaveSnapshot).toHaveBeenCalledTimes(2);
+
+      manager.stop();
+    });
+
+    it('should stop periodic saves when stop() is called', async () => {
+      const manager = new RecoveryManager(1000);
+      manager.setStateGatherer(makeGatherer());
+      manager.start();
+
+      await vi.advanceTimersByTimeAsync(1000);
+      expect(mockedSaveSnapshot).toHaveBeenCalledTimes(1);
+
+      manager.stop();
+
+      // Further time advancement should not trigger more saves
+      await vi.advanceTimersByTimeAsync(5000);
+      expect(mockedSaveSnapshot).toHaveBeenCalledTimes(1);
+    });
+
+    it('should not start a second interval if already running', async () => {
+      const manager = new RecoveryManager(1000);
+      manager.setStateGatherer(makeGatherer());
+      manager.start();
+      manager.start(); // should be a no-op
+
+      await vi.advanceTimersByTimeAsync(1000);
+      // If a second interval were started, we'd see 2 calls instead of 1
+      expect(mockedSaveSnapshot).toHaveBeenCalledTimes(1);
+
+      manager.stop();
+    });
+
+    it('should use the default 5000ms interval', async () => {
+      const manager = new RecoveryManager();
+      manager.setStateGatherer(makeGatherer());
+      manager.start();
+
+      // At 4999ms, no save yet
+      await vi.advanceTimersByTimeAsync(4999);
+      expect(mockedSaveSnapshot).not.toHaveBeenCalled();
+
+      // At 5000ms, first save
+      await vi.advanceTimersByTimeAsync(1);
+      expect(mockedSaveSnapshot).toHaveBeenCalledTimes(1);
+
+      manager.stop();
+    });
+  });
+
+  // --- Snapshot save content ---
+
+  describe('saveSnapshot', () => {
+    it('should save a snapshot with correct structure', async () => {
+      const manager = new RecoveryManager();
+      manager.setStateGatherer(makeGatherer('My Project'));
+
+      await manager.saveSnapshot();
+
+      expect(mockedSaveSnapshot).toHaveBeenCalledOnce();
+      const saved = mockedSaveSnapshot.mock.calls[0]?.[0];
+      expect(saved?.id).toBe('latest');
+      expect(saved?.projectName).toBe('My Project');
+      expect(saved?.canvasStates).toHaveProperty('main');
+      expect(saved?.canvasStates["main"]?.width).toBe(32);
+      expect(saved?.pendingCommands).toEqual([]);
+      expect(typeof saved?.timestamp).toBe('number');
+    });
+
+    it('should not save if no state gatherer is set', async () => {
+      const manager = new RecoveryManager();
+
+      await manager.saveSnapshot();
+
+      expect(mockedSaveSnapshot).not.toHaveBeenCalled();
+    });
+  });
+
+  // --- Visibility change ---
+
+  describe('visibility change', () => {
+    it('should save a snapshot when tab becomes hidden', async () => {
+      const manager = new RecoveryManager();
+      manager.setStateGatherer(makeGatherer());
+      manager.start();
+
+      // Simulate the tab being hidden
+      Object.defineProperty(document, 'visibilityState', {
+        value: 'hidden',
+        writable: true,
+        configurable: true,
+      });
+      document.dispatchEvent(new Event('visibilitychange'));
+
+      // saveSnapshot is async; flush microtasks
+      await vi.advanceTimersByTimeAsync(0);
+
+      expect(mockedSaveSnapshot).toHaveBeenCalledTimes(1);
+
+      // Restore
+      Object.defineProperty(document, 'visibilityState', {
+        value: 'visible',
+        writable: true,
+        configurable: true,
+      });
+      manager.stop();
+    });
+
+    it('should not save when tab becomes visible', async () => {
+      const manager = new RecoveryManager();
+      manager.setStateGatherer(makeGatherer());
+      manager.start();
+
+      Object.defineProperty(document, 'visibilityState', {
+        value: 'visible',
+        writable: true,
+        configurable: true,
+      });
+      document.dispatchEvent(new Event('visibilitychange'));
+
+      await vi.advanceTimersByTimeAsync(0);
+
+      expect(mockedSaveSnapshot).not.toHaveBeenCalled();
+
+      manager.stop();
+    });
+
+    it('should stop listening for visibility changes after stop()', async () => {
+      const manager = new RecoveryManager();
+      manager.setStateGatherer(makeGatherer());
+      manager.start();
+      manager.stop();
+
+      Object.defineProperty(document, 'visibilityState', {
+        value: 'hidden',
+        writable: true,
+        configurable: true,
+      });
+      document.dispatchEvent(new Event('visibilitychange'));
+
+      await vi.advanceTimersByTimeAsync(0);
+
+      expect(mockedSaveSnapshot).not.toHaveBeenCalled();
+
+      Object.defineProperty(document, 'visibilityState', {
+        value: 'visible',
+        writable: true,
+        configurable: true,
+      });
+    });
+  });
+
+  // --- Delegated IDB operations ---
+
+  describe('delegated IDB operations', () => {
+    it('should delegate hasRecoveryData to idb-store', async () => {
+      const manager = new RecoveryManager();
+
+      mockedHasSnapshot.mockResolvedValueOnce(true);
+      expect(await manager.hasRecoveryData()).toBe(true);
+      expect(mockedHasSnapshot).toHaveBeenCalledOnce();
+    });
+
+    it('should delegate loadRecoveryData to idb-store', async () => {
+      const manager = new RecoveryManager();
+
+      const fakeSnapshot: RecoverySnapshot = {
+        id: 'latest',
+        timestamp: 1234567890,
+        projectName: 'Recovered',
+        canvasStates: {},
+        pendingCommands: [{ id: 'cmd-1' }],
+      };
+      mockedLoadSnapshot.mockResolvedValueOnce(fakeSnapshot);
+
+      const loaded = await manager.loadRecoveryData();
+      expect(loaded).toBe(fakeSnapshot);
+      expect(mockedLoadSnapshot).toHaveBeenCalledOnce();
+    });
+
+    it('should delegate clearRecoveryData to idb-store', async () => {
+      const manager = new RecoveryManager();
+
+      await manager.clearRecoveryData();
+      expect(mockedClearSnapshot).toHaveBeenCalledOnce();
+    });
+  });
+});

package/src/lib/recovery/recovery-manager.ts

@@ -0,0 +1,115 @@
+/**
+ * Recovery Manager -- coordinates periodic snapshot saves and crash recovery.
+ *
+ * Saves a lightweight state snapshot to IndexedDB every N seconds, and also
+ * on `visibilitychange` (tab-switch / minimize). On next load, the app can
+ * check for recovery data and replay any commands the server never acked.
+ *
+ * Designed as a class so multiple instances can coexist in tests, but the
+ * app typically creates a single global instance.
+ */
+
+import type { RecoverySnapshot } from './idb-store.js';
+import {
+  saveSnapshot as idbSave,
+  loadSnapshot as idbLoad,
+  clearSnapshot as idbClear,
+  hasSnapshot as idbHas,
+} from './idb-store.js';
+
+/** Function that produces the current app state for a snapshot. */
+export type StateGatherer = () => Omit<RecoverySnapshot, 'id' | 'timestamp' | 'pendingCommands'>;
+
+interface PendingCommand {
+  id: string;
+  data: unknown;
+}
+
+export class RecoveryManager {
+  private intervalId: ReturnType<typeof setInterval> | null = null;
+  private readonly saveIntervalMs: number;
+  private pendingCommands: PendingCommand[] = [];
+  private gatherState: StateGatherer | null = null;
+  private readonly handleVisibilityChange: () => void;
+
+  constructor(saveIntervalMs = 5000) {
+    this.saveIntervalMs = saveIntervalMs;
+
+    // Bind once so we can remove the same listener reference later
+    this.handleVisibilityChange = () => {
+      if (document.visibilityState === 'hidden') {
+        // Fire-and-forget -- we do our best to save before the tab goes away
+        void this.saveSnapshot();
+      }
+    };
+  }
+
+  /**
+   * Provide the function that gathers current app state for snapshots.
+   * Must be called before start() so that saveSnapshot knows what to persist.
+   */
+  setStateGatherer(gatherer: StateGatherer): void {
+    this.gatherState = gatherer;
+  }
+
+  /** Start periodic snapshots and listen for visibility changes. */
+  start(): void {
+    if (this.intervalId !== null) return; // already running
+    this.intervalId = setInterval(() => { void this.saveSnapshot(); }, this.saveIntervalMs);
+    document.addEventListener('visibilitychange', this.handleVisibilityChange);
+  }
+
+  /** Stop periodic snapshots and remove the visibility listener. */
+  stop(): void {
+    if (this.intervalId !== null) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+    document.removeEventListener('visibilitychange', this.handleVisibilityChange);
+  }
+
+  /** Save a snapshot now. Called periodically by the interval and on visibility change. */
+  async saveSnapshot(): Promise<void> {
+    if (!this.gatherState) return;
+
+    const state = this.gatherState();
+    const snapshot: RecoverySnapshot = {
+      id: 'latest',
+      timestamp: Date.now(),
+      projectName: state.projectName,
+      canvasStates: state.canvasStates,
+      pendingCommands: this.pendingCommands.map((pc) => pc.data),
+    };
+    await idbSave(snapshot);
+  }
+
+  /** Check whether recovery data exists from a previous session. */
+  async hasRecoveryData(): Promise<boolean> {
+    return idbHas();
+  }
+
+  /** Load recovery data from a previous session. */
+  async loadRecoveryData(): Promise<RecoverySnapshot | null> {
+    return idbLoad();
+  }
+
+  /** Clear recovery data (call after the server confirms all state is synced). */
+  async clearRecoveryData(): Promise<void> {
+    await idbClear();
+  }
+
+  /** Track a command that has been sent to the server but not yet acked. */
+  addPendingCommand(command: { id: string; [key: string]: unknown }): void {
+    this.pendingCommands.push({ id: command.id, data: command });
+  }
+
+  /** Remove a pending command once the server has acknowledged it. */
+  removePendingCommand(commandId: string): void {
+    this.pendingCommands = this.pendingCommands.filter((pc) => pc.id !== commandId);
+  }
+
+  /** Read-only access to the current pending commands list (for testing). */
+  getPendingCommands(): readonly PendingCommand[] {
+    return this.pendingCommands;
+  }
+}

package/src/lib/recovery/recovery-plugin.ts

@@ -0,0 +1,55 @@
+/**
+ * Recovery Plugin -- wraps crash-recovery initialization as a plugin.
+ * Sets up periodic IndexedDB snapshots and checks for prior recovery data.
+ */
+
+import type { PluginModule } from '../core/plugin-loader.js';
+import { RecoveryManager } from './recovery-manager.js';
+import { recoveryState } from './recovery-state.svelte.js';
+import { canvasState } from '../canvas/canvas-state.svelte.js';
+import { serialize as serializeLayerTree } from '../layers/layer-tree.svelte.js';
+import { getCurrentFrame } from '../animation/frame-model.svelte.js';
+
+export const recoveryPlugin: PluginModule = {
+  name: 'builtin/recovery',
+  version: '1.0.0',
+  description: 'Periodic crash-recovery snapshots via IndexedDB',
+
+  register() {
+    const manager = new RecoveryManager();
+
+    manager.setStateGatherer(() => {
+      const frame = getCurrentFrame();
+      // Convert each layer's PixelBuffer to a plain ArrayBuffer copy
+      const pixelData: Record<string, ArrayBuffer> = {};
+      for (const [layerId, buffer] of frame.pixelData) {
+        pixelData[layerId] = buffer.data.buffer.slice(0) as ArrayBuffer;
+      }
+
+      return {
+        projectName: 'default',
+        canvasStates: {
+          default: {
+            width: canvasState.canvasWidth,
+            height: canvasState.canvasHeight,
+            layerTree: serializeLayerTree(),
+            pixelData,
+          },
+        },
+      };
+    });
+
+    manager.start();
+
+    // Check for existing recovery data from a previous session.
+    // Fire-and-forget: the notification is best-effort at startup.
+    void manager.hasRecoveryData().then(async (hasData) => {
+      if (hasData) {
+        const snapshot = await manager.loadRecoveryData();
+        if (snapshot) {
+          recoveryState.setRecoveryAvailable(true, snapshot.timestamp);
+        }
+      }
+    });
+  },
+};

package/src/lib/recovery/recovery-state.svelte.ts

@@ -0,0 +1,21 @@
+/**
+ * Recovery State -- reactive Svelte 5 state indicating whether crash
+ * recovery data is available on startup.
+ *
+ * Components can read `recoveryState.available` and `.timestamp` to
+ * decide whether to show a recovery prompt to the user.
+ */
+
+let available = $state(false);
+let timestamp = $state<number | null>(null);
+
+export const recoveryState = {
+  get available() { return available; },
+  get timestamp() { return timestamp; },
+
+  /** Mark recovery data as available (or not). */
+  setRecoveryAvailable(isAvailable: boolean, ts?: number): void {
+    available = isAvailable;
+    timestamp = ts ?? null;
+  },
+};

package/src/lib/recovery/sw-plugin.ts

@@ -0,0 +1,18 @@
+/**
+ * Service Worker Plugin -- registers the app-shell caching service worker.
+ * Registration is fire-and-forget; failures are logged as warnings.
+ */
+
+import type { PluginModule } from '../core/plugin-loader.js';
+import { registerServiceWorker } from './sw-register.js';
+
+export const serviceWorkerPlugin: PluginModule = {
+  name: 'builtin/service-worker',
+  version: '1.0.0',
+  description: 'Service worker registration for offline caching',
+
+  register() {
+    // Async but fire-and-forget; errors are handled inside registerServiceWorker
+    void registerServiceWorker();
+  },
+};

package/src/lib/recovery/sw-register.ts

@@ -0,0 +1,17 @@
+/**
+ * Service Worker Registration -- registers the app-shell caching service worker.
+ *
+ * Fails silently with a console warning if the browser does not support
+ * service workers or if registration fails for any other reason.
+ */
+
+export async function registerServiceWorker(): Promise<void> {
+  if (!('serviceWorker' in navigator)) return;
+
+  try {
+    const registration = await navigator.serviceWorker.register('/sw.js');
+    console.info('[sw] Service worker registered, scope:', registration.scope);
+  } catch (err) {
+    console.warn('[sw] Service worker registration failed:', err);
+  }
+}