pixelweaver 0.1.0

package/src/lib/sync/ws-client.ts

@@ -0,0 +1,574 @@
+/**
+ * WebSocket Client for the PixelWeaver server-authoritative protocol.
+ *
+ * Handles connection lifecycle, message routing, auto-reconnect with
+ * exponential backoff, and request/response correlation via message IDs.
+ *
+ * Works in both browser and desktop environments (uses globalThis.WebSocket).
+ */
+
+import type { Command } from '../core/commands.js';
+import type { PatchMessage, StatePatch } from './patch-types.js';
+
+// --- Types for the server protocol ---
+
+/** The state snapshot returned by the server on sync_request. */
+export interface StateSnapshot {
+  project: { name: string; width: number; height: number } | null;
+  canvases: Record<string, {
+    name: string;
+    width: number;
+    height: number;
+    layers: Array<Record<string, unknown>>;
+    frames?: Array<{ id: string; duration_ms: number | null }>;
+    current_frame_index?: number;
+    global_fps?: number;
+  }>;
+  layers: Record<string, Array<Record<string, unknown>>>;
+  history: Array<Record<string, unknown>>;
+}
+
+/** A broadcast command from another client. */
+export interface BroadcastedCommand {
+  type: string;
+  [key: string]: unknown;
+}
+
+// --- Callback types ---
+
+type StateSyncCallback = (state: StateSnapshot) => void;
+type CommandBroadcastCallback = (command: BroadcastedCommand) => void;
+type StatePatchCallback = (message: PatchMessage) => void;
+type ConnectionChangeCallback = (connected: boolean) => void;
+type ErrorCallback = (error: string) => void;
+type ForwardRejectCallback = (commandId: string, reason: string) => void;
+
+// --- Pending message tracking ---
+
+interface PendingMessage {
+  resolve: (value: unknown) => void;
+  reject: (reason: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+// --- Constants ---
+
+const PENDING_TIMEOUT_MS = 10_000;
+const MAX_BACKOFF_MS = 30_000;
+const BASE_BACKOFF_MS = 1_000;
+
+// --- Exported helpers (unit-testable) ---
+
+/** Generate a unique message ID using crypto.randomUUID. */
+export function generateMessageId(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Calculate exponential backoff delay in milliseconds.
+ * Formula: min(base * 2^attempt, maxBackoff)
+ */
+export function calculateBackoff(attempt: number): number {
+  return Math.min(BASE_BACKOFF_MS * Math.pow(2, attempt), MAX_BACKOFF_MS);
+}
+
+// --- WebSocket Client ---
+
+export class WebSocketClient {
+  private ws: WebSocket | null = null;
+  private url: string;
+  private reconnectAttempts = 0;
+  private maxReconnectAttempts = 10;
+  private pendingMessages: Map<string, PendingMessage> = new Map();
+  /** Message IDs of fire-and-forget forwarded commands awaiting server ack. */
+  private forwardedIds: Set<string> = new Set();
+  private forwardRejectCallback: ForwardRejectCallback | null = null;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private intentionalDisconnect = false;
+
+  // Event callback arrays
+  private stateSyncCallbacks: StateSyncCallback[] = [];
+  private commandBroadcastCallbacks: CommandBroadcastCallback[] = [];
+  private statePatchCallbacks: StatePatchCallback[] = [];
+  private connectionChangeCallbacks: ConnectionChangeCallback[] = [];
+  private errorCallbacks: ErrorCallback[] = [];
+
+  constructor(url: string) {
+    this.url = url;
+  }
+
+  // --- Connection lifecycle ---
+
+  /** Connect to the WebSocket server. Resolves when the connection is open. */
+  connect(): Promise<void> {
+    this.intentionalDisconnect = false;
+
+    // If an existing socket is open or still connecting, tear it down
+    // cleanly before constructing a new one. Without this, the old
+    // socket's onclose would fire AFTER this.ws is reassigned and
+    // trigger scheduleReconnect() -- a phantom reconnect on top of
+    // the fresh connection.
+    if (
+      this.ws &&
+      (this.ws.readyState === globalThis.WebSocket.OPEN ||
+        this.ws.readyState === globalThis.WebSocket.CONNECTING)
+    ) {
+      this.ws.onopen = null;
+      this.ws.onmessage = null;
+      this.ws.onerror = null;
+      this.ws.onclose = null;
+      this.ws.close();
+      this.ws = null;
+    }
+
+    // Cancel any pending backoff reconnect -- a manual connect()
+    // supersedes the scheduled one so we don't race two connections.
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      // Guards the connect-promise against multi-fire events. onerror can
+      // fire multiple times on the same socket, and both onopen and onerror
+      // race onclose. Without this flag, we would call resolve/reject (and
+      // spam notifyError on rejection) more than once per connect attempt.
+      let settled = false;
+      const settleResolve = () => {
+        if (settled) return;
+        settled = true;
+        resolve();
+      };
+      const settleReject = (err: Error) => {
+        if (settled) return;
+        settled = true;
+        reject(err);
+      };
+
+      try {
+        this.ws = new globalThis.WebSocket(this.url);
+      } catch (err) {
+        // Synchronous constructor throw: no socket exists, so onclose will
+        // never fire. If we're in an auto-reconnecting state, schedule the
+        // next attempt explicitly -- otherwise the retry chain dies silently.
+        if (
+          !this.intentionalDisconnect &&
+          this.reconnectAttempts < this.maxReconnectAttempts
+        ) {
+          this.scheduleReconnect();
+        }
+        settleReject(new Error(`Failed to create WebSocket: ${err instanceof Error ? err.message : String(err)}`));
+        return;
+      }
+
+      this.ws.onopen = () => {
+        this.reconnectAttempts = 0;
+        this.notifyConnectionChange(true);
+        settleResolve();
+      };
+
+      this.ws.onclose = () => {
+        this.notifyConnectionChange(false);
+        this.rejectAllPending('WebSocket connection closed');
+        if (!this.intentionalDisconnect) {
+          this.scheduleReconnect();
+        }
+      };
+
+      this.ws.onerror = (event) => {
+        // onerror can fire multiple times for a single socket in the
+        // pre-settle window, and also post-open as a runtime signal. The
+        // `settled` guard stops us from rejecting repeatedly AND from
+        // re-notifying subscribers for each duplicate error. Post-settle
+        // onerror events are swallowed here; the following onclose still
+        // notifies via connection change, so subscribers still learn the
+        // socket died.
+        if (settled) return;
+        const msg = `WebSocket error${event instanceof ErrorEvent ? `: ${event.message}` : ''}`;
+        this.notifyError(msg);
+        // If we haven't connected yet, reject the promise. settleReject
+        // flips `settled` so duplicate onerror events become no-ops above.
+        if (this.ws?.readyState !== globalThis.WebSocket.OPEN) {
+          settleReject(new Error(msg));
+        }
+      };
+
+      this.ws.onmessage = (event) => {
+        // event.data is typed `any` by lib.dom; narrow it to what we accept.
+        const payload: unknown = event.data;
+        if (typeof payload === 'string' || payload instanceof ArrayBuffer) {
+          this.handleMessage(payload);
+        }
+      };
+    });
+  }
+
+  /** Disconnect from the server. Stops auto-reconnect. */
+  disconnect(): void {
+    this.intentionalDisconnect = true;
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.rejectAllPending('Client disconnected');
+    if (this.ws) {
+      // Null ALL four handlers symmetrically. Nulling only onclose (the
+      // previous behavior) still let the closing socket fire stale
+      // onopen/onmessage/onerror events, which would call handleMessage
+      // or notifyError after the caller has logically disconnected. This
+      // matches the reconnect-path cleanup in connect().
+      this.ws.onopen = null;
+      this.ws.onmessage = null;
+      this.ws.onerror = null;
+      this.ws.onclose = null;
+      this.ws.close();
+      this.ws = null;
+      this.notifyConnectionChange(false);
+    }
+  }
+
+  /** Update the server URL. Does NOT reconnect automatically. */
+  setUrl(url: string): void {
+    this.url = url;
+  }
+
+  // --- Message sending ---
+
+  /**
+   * Send a command to the server and wait for ack/reject.
+   * The caller provides the command without id/timestamp -- those are filled in.
+   */
+  async sendCommand(commandFields: Omit<Command, 'id' | 'timestamp'>): Promise<void> {
+    const command: Command = {
+      ...commandFields,
+      id: generateMessageId(),
+      timestamp: Date.now(),
+    };
+
+    const msgId = generateMessageId();
+    const message = {
+      type: 'command' as const,
+      id: msgId,
+      command,
+    };
+
+    await this.sendAndWait(msgId, message);
+  }
+
+  /**
+   * Forward an already-dispatched command to the server. Unlike sendCommand(),
+   * this preserves the command's existing id and timestamp. Used by the
+   * dispatcher's sync hook to relay locally-executed commands to the server.
+   *
+   * Best-effort: send failures are silently ignored so local dispatch is never
+   * blocked by network issues. However, if the server later rejects the
+   * command, the forwardRejectCallback (if set) is invoked.
+   */
+  forwardCommand(command: Command): void {
+    if (!this.isConnected()) return;
+
+    const msgId = generateMessageId();
+    const message = {
+      type: 'command' as const,
+      id: msgId,
+      command,
+    };
+
+    try {
+      // isConnected() narrowed above -- ws is non-null while connected,
+      // but TS can't follow the guard through a method call.
+      this.ws?.send(JSON.stringify(message));
+      // Track this ID so we can detect server rejection asynchronously.
+      this.forwardedIds.add(msgId);
+    } catch {
+      // Best-effort -- don't block the caller on send failures.
+    }
+  }
+
+  /**
+   * Register a callback invoked when the server rejects a forwarded command.
+   * Pass null to clear. Only one callback is active at a time.
+   */
+  setOnForwardReject(cb: ForwardRejectCallback | null): void {
+    this.forwardRejectCallback = cb;
+  }
+
+  /** Request a full state sync from the server. */
+  async requestSync(): Promise<StateSnapshot> {
+    const msgId = generateMessageId();
+    const message = {
+      type: 'sync_request' as const,
+      id: msgId,
+    };
+
+    const result = await this.sendAndWait(msgId, message);
+    return result as StateSnapshot;
+  }
+
+  /** Send an undo request and wait for ack. */
+  async sendUndo(): Promise<void> {
+    const msgId = generateMessageId();
+    const message = {
+      type: 'undo' as const,
+      id: msgId,
+    };
+
+    await this.sendAndWait(msgId, message);
+  }
+
+  /** Send a redo request and wait for ack. */
+  async sendRedo(): Promise<void> {
+    const msgId = generateMessageId();
+    const message = {
+      type: 'redo' as const,
+      id: msgId,
+    };
+
+    await this.sendAndWait(msgId, message);
+  }
+
+  // --- Event subscription ---
+
+  /** Register a callback for state_sync messages. Returns an unsubscribe function. */
+  onStateSync(callback: StateSyncCallback): () => void {
+    this.stateSyncCallbacks.push(callback);
+    return () => {
+      const idx = this.stateSyncCallbacks.indexOf(callback);
+      if (idx !== -1) this.stateSyncCallbacks.splice(idx, 1);
+    };
+  }
+
+  /** Register a callback for command_broadcast messages. Returns an unsubscribe function. */
+  onCommandBroadcast(callback: CommandBroadcastCallback): () => void {
+    this.commandBroadcastCallbacks.push(callback);
+    return () => {
+      const idx = this.commandBroadcastCallbacks.indexOf(callback);
+      if (idx !== -1) this.commandBroadcastCallbacks.splice(idx, 1);
+    };
+  }
+
+  /** Register a callback for state_patch messages. Returns an unsubscribe function. */
+  onStatePatch(callback: StatePatchCallback): () => void {
+    this.statePatchCallbacks.push(callback);
+    return () => {
+      const idx = this.statePatchCallbacks.indexOf(callback);
+      if (idx !== -1) this.statePatchCallbacks.splice(idx, 1);
+    };
+  }
+
+  /** Register a callback for connection state changes. Returns an unsubscribe function. */
+  onConnectionChange(callback: ConnectionChangeCallback): () => void {
+    this.connectionChangeCallbacks.push(callback);
+    return () => {
+      const idx = this.connectionChangeCallbacks.indexOf(callback);
+      if (idx !== -1) this.connectionChangeCallbacks.splice(idx, 1);
+    };
+  }
+
+  /** Register a callback for error messages. Returns an unsubscribe function. */
+  onError(callback: ErrorCallback): () => void {
+    this.errorCallbacks.push(callback);
+    return () => {
+      const idx = this.errorCallbacks.indexOf(callback);
+      if (idx !== -1) this.errorCallbacks.splice(idx, 1);
+    };
+  }
+
+  // --- Connection state query ---
+
+  /** Whether the WebSocket is currently open. */
+  isConnected(): boolean {
+    return this.ws?.readyState === globalThis.WebSocket.OPEN;
+  }
+
+  // --- Internal: message handling ---
+
+  private handleMessage(raw: string | ArrayBuffer): void {
+    let data: Record<string, unknown>;
+    try {
+      const text = typeof raw === 'string' ? raw : new TextDecoder().decode(raw);
+      data = JSON.parse(text) as Record<string, unknown>;
+    } catch {
+      this.notifyError('Failed to parse server message');
+      return;
+    }
+
+    switch (data["type"]) {
+      case 'command_ack':
+        // Clear forwarded tracking if this ack is for a forwarded command.
+        this.forwardedIds.delete(data["id"] as string);
+        this.resolvePending(data["id"] as string, undefined);
+        break;
+
+      case 'command_reject': {
+        const rejectId = data["id"] as string;
+        const errVal = data["error"];
+        const reason = typeof errVal === 'string' ? errVal : 'unknown reason';
+        if (this.forwardedIds.delete(rejectId)) {
+          // This was a fire-and-forget forward -- notify via callback.
+          this.forwardRejectCallback?.(rejectId, reason);
+        }
+        this.rejectPending(rejectId, new Error(`Command rejected: ${reason}`));
+        break;
+      }
+
+      case 'state_sync':
+        // Resolve pending sync_request if there is one
+        this.resolvePending(data["id"] as string, data["state"] as StateSnapshot);
+        // Also notify subscribers (for reconnect-triggered syncs, etc.)
+        for (const cb of this.stateSyncCallbacks) {
+          cb(data["state"] as StateSnapshot);
+        }
+        break;
+
+      case 'command_broadcast':
+        for (const cb of this.commandBroadcastCallbacks) {
+          cb(data["command"] as BroadcastedCommand);
+        }
+        break;
+
+      case 'state_patch': {
+        // Server sends snake_case keys; map to the camelCase PatchMessage type.
+        // Spread-conditional on commandId: exactOptionalPropertyTypes distinguishes
+        // "missing" from "explicitly undefined", and PatchMessage.commandId is
+        // declared as optional (not `string | undefined`).
+        const commandId = data["command_id"] as string | undefined;
+        const patchMessage: PatchMessage = {
+          type: 'state_patch',
+          projectName: data["project_name"] as string,
+          patches: data["patches"] as StatePatch[],
+          ...(commandId !== undefined && { commandId }),
+        };
+        for (const cb of this.statePatchCallbacks) {
+          cb(patchMessage);
+        }
+        break;
+      }
+
+      case 'error': {
+        // Reject the pending message if there is one
+        const errVal = data["error"];
+        const errStr = typeof errVal === 'string' ? errVal : 'unknown';
+        this.rejectPending(
+          data["id"] as string,
+          new Error(`Server error: ${errStr}`),
+        );
+        this.notifyError(errStr);
+        break;
+      }
+
+      default:
+        this.notifyError(`Unknown message type: ${String(data["type"])}`);
+    }
+  }
+
+  // --- Internal: send-and-wait pattern ---
+
+  /**
+   * Send a JSON message and return a promise that resolves when the server
+   * responds with a matching message ID (ack/state_sync) or rejects on
+   * error/timeout.
+   */
+  private sendAndWait(msgId: string, message: Record<string, unknown>): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      if (!this.isConnected()) {
+        reject(new Error('Not connected to server'));
+        return;
+      }
+
+      const timer = setTimeout(() => {
+        this.pendingMessages.delete(msgId);
+        reject(new Error(`Request timed out after ${String(PENDING_TIMEOUT_MS)}ms`));
+      }, PENDING_TIMEOUT_MS);
+
+      this.pendingMessages.set(msgId, { resolve, reject, timer });
+
+      try {
+        // isConnected() guarded above -- ws is non-null, but TS loses the
+        // narrowing through the method call.
+        this.ws?.send(JSON.stringify(message));
+      } catch (err) {
+        clearTimeout(timer);
+        this.pendingMessages.delete(msgId);
+        reject(new Error(`Failed to send message: ${err instanceof Error ? err.message : String(err)}`));
+      }
+    });
+  }
+
+  private resolvePending(msgId: string, value: unknown): void {
+    const pending = this.pendingMessages.get(msgId);
+    if (pending) {
+      clearTimeout(pending.timer);
+      this.pendingMessages.delete(msgId);
+      pending.resolve(value);
+    }
+  }
+
+  private rejectPending(msgId: string, error: Error): void {
+    const pending = this.pendingMessages.get(msgId);
+    if (pending) {
+      clearTimeout(pending.timer);
+      this.pendingMessages.delete(msgId);
+      pending.reject(error);
+    }
+  }
+
+  private rejectAllPending(reason: string): void {
+    for (const [id, pending] of this.pendingMessages) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error(reason));
+      this.pendingMessages.delete(id);
+    }
+    // Forwarded commands will never receive ack/reject after disconnect.
+    this.forwardedIds.clear();
+  }
+
+  // --- Internal: reconnect logic ---
+
+  private scheduleReconnect(): void {
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+      this.notifyError(
+        `Max reconnect attempts (${String(this.maxReconnectAttempts)}) reached. Giving up.`,
+      );
+      return;
+    }
+
+    const delay = calculateBackoff(this.reconnectAttempts);
+    this.reconnectAttempts++;
+
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      // Fire-and-forget: setTimeout expects () => void, so wrap the async
+      // body in an IIFE and discard the promise.
+      void (async () => {
+        try {
+          await this.connect();
+          // On successful reconnect, request full state sync
+          this.requestSync().catch((err: unknown) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.notifyError(`Sync after reconnect failed: ${msg}`);
+          });
+        } catch {
+          // connect() rejects on failure. If the socket was constructed and
+          // later errored/closed, its onclose will trigger another reconnect.
+          // If the constructor threw synchronously, connect()'s catch branch
+          // already called scheduleReconnect() so the chain survives.
+        }
+      })();
+    }, delay);
+  }
+
+  // --- Internal: notification helpers ---
+
+  private notifyConnectionChange(connected: boolean): void {
+    for (const cb of this.connectionChangeCallbacks) {
+      cb(connected);
+    }
+  }
+
+  private notifyError(error: string): void {
+    for (const cb of this.errorCallbacks) {
+      cb(error);
+    }
+  }
+}

package/src/lib/ui/AboutDialog.svelte

@@ -0,0 +1,113 @@
+<script lang="ts">
+  interface Props {
+    onClose: () => void;
+  }
+  let { onClose }: Props = $props();
+
+  let dialogEl: HTMLDialogElement | undefined = $state();
+
+  // Open the native <dialog> as soon as it's bound. This runs once on mount
+  // because dialogEl transitions from undefined to the element.
+  $effect(() => {
+    if (dialogEl && !dialogEl.open) {
+      dialogEl.showModal();
+    }
+  });
+
+  // Backdrop click: clicks on the <dialog> element itself target the dialog
+  // (not children), so we can use that to detect outside clicks. We call
+  // dialogEl.close() rather than onClose() directly so the `close` event
+  // fires once through a single code path (onclose={onClose}).
+  function handleDialogClick(e: MouseEvent) {
+    if (e.target === dialogEl) {
+      // e.target === dialogEl narrows dialogEl to non-undefined here.
+      dialogEl.close();
+    }
+  }
+
+  function handleOk() {
+    dialogEl?.close();
+  }
+</script>
+
+<!--
+  Native <dialog> gives us focus trap, Escape-to-close (via cancel event),
+  and backdrop rendering for free. onclose fires on both user and programmatic
+  close and is where we forward the parent's onClose callback.
+-->
+<dialog
+  bind:this={dialogEl}
+  class="about-dialog-el"
+  aria-label="About PixelWeaver"
+  onclick={handleDialogClick}
+  onclose={onClose}
+>
+  <div class="about-dialog">
+    <h2>PixelWeaver</h2>
+    <p>Pixel Art Editor</p>
+    <p class="version">Version 1.0.0</p>
+    <button class="close-btn" onclick={handleOk}>OK</button>
+  </div>
+</dialog>
+
+<style>
+  /* Reset UA styles and use flexbox to center the inner content. */
+  .about-dialog-el {
+    margin: 0;
+    padding: 0;
+    border: none;
+    background: transparent;
+    max-width: none;
+    max-height: none;
+    width: 100vw;
+    height: 100vh;
+    color: inherit;
+  }
+
+  .about-dialog-el[open] {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  .about-dialog-el::backdrop {
+    background: rgba(0, 0, 0, 0.5);
+  }
+
+  .about-dialog {
+    background: var(--bg-panel);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-md);
+    padding: var(--space-6) var(--space-8);
+    text-align: center;
+    min-width: 280px;
+    box-shadow: var(--shadow-md);
+  }
+  h2 {
+    margin: 0 0 var(--space-2);
+    font-family: var(--font-ui);
+    font-size: var(--text-xl);
+    color: var(--accent);
+  }
+  p {
+    margin: 0 0 var(--space-2);
+    color: var(--text-secondary);
+    font-size: var(--text-base);
+  }
+  .version {
+    color: var(--text-muted);
+    font-size: var(--text-sm);
+    margin-bottom: var(--space-4);
+  }
+  .close-btn {
+    background: var(--accent);
+    color: var(--text-on-accent, #fff);
+    border: none;
+    border-radius: var(--radius-sm);
+    padding: var(--space-2) var(--space-6);
+    font-size: var(--text-base);
+    cursor: pointer;
+    transition: opacity var(--transition-fast);
+  }
+  .close-btn:hover { opacity: 0.9; }
+</style>