pixelweaver 0.1.0

package/src/lib/sync/patch-types.ts

@@ -0,0 +1,65 @@
+/**
+ * Data Patch Types -- protocol for server-to-client state synchronization.
+ *
+ * When the server modifies state (via MCP or other operations), it broadcasts
+ * patches describing the pre-computed results. The frontend applies these
+ * directly without re-executing commands.
+ */
+
+/** A patch to pixel data on a specific layer/frame. */
+export interface PixelPatch {
+  type: 'pixel';
+  layerId: string;
+  frameIndex: number;
+  /** Raw RGBA pixel data as base64 string or flat number array (legacy). */
+  data: string | number[];
+  width: number;
+  height: number;
+}
+
+/** A patch to the layer tree structure. */
+export interface LayerPatch {
+  type: 'layer';
+  action: 'add' | 'remove' | 'update';
+  /** Full serialized layer for add/update, just the id for remove. */
+  layer?: unknown;
+  layerId?: string;
+}
+
+/** A patch to canvas dimensions. */
+export interface CanvasPatch {
+  type: 'canvas';
+  width: number;
+  height: number;
+}
+
+/** A patch to frame structure (add/remove/reorder). */
+export interface FramePatch {
+  type: 'frame';
+  action: 'add' | 'remove' | 'reorder' | 'set_duration';
+  frameIndex?: number;
+  /** Full frame data for add (pixel data per layer). */
+  frameData?: unknown;
+  fromIndex?: number;
+  toIndex?: number;
+  durationMs?: number | null;
+}
+
+/** A full state replacement (used for initial sync or large MCP operations). */
+export interface FullStatePatch {
+  type: 'full_state';
+  /** Complete ProjectSnapshot (same format as save/load). */
+  snapshot: unknown;
+}
+
+/** Union of all patch types. */
+export type StatePatch = PixelPatch | LayerPatch | CanvasPatch | FramePatch | FullStatePatch;
+
+/** Wrapper message sent via WebSocket. */
+export interface PatchMessage {
+  type: 'state_patch';
+  projectName: string;
+  patches: StatePatch[];
+  /** ID of the originating command (for correlation). */
+  commandId?: string;
+}

package/src/lib/sync/project-manager.ts

@@ -0,0 +1,108 @@
+/**
+ * Project Manager -- high-level project operations via the REST API.
+ *
+ * Provides typed wrappers around the server's REST endpoints for creating,
+ * listing, inspecting, and deleting projects. The base URL is derived from
+ * the WebSocket URL in sync state (same host/port, HTTP scheme).
+ */
+
+// --- Types ---
+
+export interface CanvasInfo {
+  name: string;
+  width: number;
+  height: number;
+}
+
+export interface ProjectInfo {
+  name: string;
+  width: number;
+  height: number;
+  canvases: CanvasInfo[];
+}
+
+// --- API base URL ---
+
+// Default: same-origin (empty string = relative URLs).
+// Override via VITE_SERVER_URL for dev mode (separate Vite + server ports).
+let apiBase = (import.meta.env.VITE_SERVER_URL as string | undefined) || '';
+
+/** Set the REST API base URL (no trailing slash). */
+export function setApiBase(url: string): void {
+  apiBase = url.replace(/\/+$/, '');
+}
+
+/** Get the current REST API base URL. */
+export function getApiBase(): string {
+  return apiBase;
+}
+
+// --- REST API wrappers ---
+
+/** List all project names on the server. */
+export async function listProjects(): Promise<string[]> {
+  const res = await fetch(`${apiBase}/api/projects`);
+  if (!res.ok) {
+    throw new Error(`Failed to list projects: ${String(res.status)} ${res.statusText}`);
+  }
+  const data = (await res.json()) as { projects: string[] };
+  return data.projects;
+}
+
+/** Create a new project with the given dimensions. */
+export async function createProject(
+  name: string,
+  width: number,
+  height: number,
+): Promise<void> {
+  const res = await fetch(`${apiBase}/api/projects`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name, width, height }),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => res.statusText);
+    throw new Error(`Failed to create project "${name}": ${text}`);
+  }
+}
+
+/** Delete a project by name. */
+export async function deleteProject(name: string): Promise<void> {
+  const res = await fetch(`${apiBase}/api/projects/${encodeURIComponent(name)}`, {
+    method: 'DELETE',
+  });
+  if (!res.ok && res.status !== 204) {
+    const text = await res.text().catch(() => res.statusText);
+    throw new Error(`Failed to delete project "${name}": ${text}`);
+  }
+}
+
+/** Get detailed info about a single project. */
+export async function getProjectInfo(name: string): Promise<ProjectInfo> {
+  const res = await fetch(`${apiBase}/api/projects/${encodeURIComponent(name)}`);
+  if (!res.ok) {
+    throw new Error(`Project "${name}" not found: ${String(res.status)} ${res.statusText}`);
+  }
+
+  // Server returns: { name, width, height, canvases: { [name]: { name, width, height, layers } }, history }
+  const data = (await res.json()) as {
+    name: string;
+    width: number;
+    height: number;
+    canvases?: Record<string, { name: string; width: number; height: number }>;
+  };
+
+  // Transform the server response into our typed ProjectInfo.
+  const canvases: CanvasInfo[] = data.canvases
+    ? Object.values(data.canvases).map(
+        (c) => ({ name: c.name, width: c.width, height: c.height }),
+      )
+    : [];
+
+  return {
+    name: data.name,
+    width: data.width,
+    height: data.height,
+    canvases,
+  };
+}

package/src/lib/sync/sync-init.ts

@@ -0,0 +1,152 @@
+/**
+ * Sync Initialization -- wires the WebSocket client to the app's reactive state.
+ *
+ * This is the glue layer that connects the server-authoritative protocol to
+ * PixelWeaver's Svelte state (canvas, layers, dispatcher). Call initializeSync()
+ * once at app startup; call teardownSync() on app shutdown.
+ *
+ * Current integration level:
+ * - Connection status is reflected in syncState
+ * - State sync messages update canvas dimensions (layer/pixel restoration
+ *   will be extended as the data model matures)
+ * - Command broadcasts are forwarded to registered listeners
+ */
+
+import { WebSocketClient, type StateSnapshot } from './ws-client.js';
+import { syncState } from './sync-state.svelte.js';
+import { canvasState } from '../canvas/canvas-state.svelte.js';
+import { setDispatchHook } from '../core/dispatcher.js';
+import { applyPatches } from './patch-applicator.js';
+import { notificationState } from '../core/notification-state.svelte.js';
+
+// Module-level client instance; null when not initialized.
+let client: WebSocketClient | null = null;
+
+// Unsubscribe functions for event handlers
+let unsubscribers: Array<() => void> = [];
+
+/**
+ * Initialize the sync system: create a WebSocket client, register event
+ * handlers, and connect to the server.
+ *
+ * Safe to call multiple times -- tears down existing connection first.
+ */
+export async function initializeSync(): Promise<void> {
+  // Tear down any previous connection
+  teardownSync();
+
+  client = new WebSocketClient(syncState.serverUrl);
+
+  // --- Wire up event handlers ---
+
+  unsubscribers.push(
+    client.onConnectionChange((connected) => {
+      syncState.connected = connected;
+      syncState.connecting = false;
+      if (connected) {
+        syncState.reconnecting = false;
+        syncState.lastError = null;
+      } else {
+        // If we were connected and lost it, we're now reconnecting
+        // (the client handles reconnect internally)
+        syncState.reconnecting = true;
+      }
+    }),
+  );
+
+  unsubscribers.push(
+    client.onStateSync((state: StateSnapshot) => {
+      applyStateSync(state);
+    }),
+  );
+
+  unsubscribers.push(
+    client.onCommandBroadcast(() => {
+      // For now, command broadcasts from other clients are logged but not
+      // applied locally. Full multi-client command replay is a later phase.
+      // The state_sync mechanism handles full state restoration.
+    }),
+  );
+
+  unsubscribers.push(
+    client.onStatePatch((message) => {
+      applyPatches(message);
+    }),
+  );
+
+  unsubscribers.push(
+    client.onError((error) => {
+      syncState.lastError = error;
+    }),
+  );
+
+  // --- Dispatch hook: forward locally-dispatched commands to the server ---
+
+  setDispatchHook((command) => {
+    if (client && syncState.connected) {
+      client.forwardCommand(command);
+    }
+  });
+
+  // --- Notify the user when the server rejects a forwarded command ---
+
+  client.setOnForwardReject((_commandId, reason) => {
+    notificationState.push({
+      id: 'sync-forward-reject',
+      message: `Server rejected command: ${reason}`,
+      type: 'warning',
+      autoDismissMs: 5000,
+    });
+  });
+
+  // --- Connect ---
+
+  syncState.connecting = true;
+  try {
+    await client.connect();
+  } catch (err) {
+    syncState.connecting = false;
+    syncState.lastError = err instanceof Error ? err.message : String(err);
+    throw err;
+  }
+}
+
+/** Tear down the sync system: disconnect and clean up event handlers. */
+export function teardownSync(): void {
+  setDispatchHook(null);
+  if (client) {
+    client.disconnect();
+    client = null;
+  }
+  for (const unsub of unsubscribers) {
+    unsub();
+  }
+  unsubscribers = [];
+  syncState.connected = false;
+  syncState.connecting = false;
+  syncState.reconnecting = false;
+}
+
+/** Get the active WebSocket client, or null if not initialized. */
+export function getClient(): WebSocketClient | null {
+  return client;
+}
+
+// --- Internal: apply server state to local Svelte state ---
+
+/**
+ * Apply a state_sync snapshot from the server to local state.
+ *
+ * Currently updates canvas dimensions from the project info. As the data
+ * model grows (pixel buffers, full layer trees from server), this function
+ * will be extended to restore those as well.
+ */
+function applyStateSync(state: StateSnapshot): void {
+  if (state.project) {
+    canvasState.canvasWidth = state.project.width;
+    canvasState.canvasHeight = state.project.height;
+  }
+
+  // Layer and pixel data restoration will be implemented as the server's
+  // state model and the client's data structures are aligned in later phases.
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Sync Plugin -- wraps WebSocket sync initialization as a plugin.
+ * Starts the connection in the background (fire-and-forget).
+ */
+
+import type { PluginModule } from '../core/plugin-loader.js';
+import { initializeSync } from './sync-init.js';
+
+export const syncPlugin: PluginModule = {
+  name: 'builtin/sync',
+  version: '1.0.0',
+  description: 'WebSocket sync client for multi-user collaboration',
+
+  register() {
+    // initializeSync is async but register is sync; the connection starts
+    // in the background and errors are handled internally by the sync system.
+    void initializeSync();
+  },
+};

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

@@ -0,0 +1,56 @@
+/**
+ * Sync State -- reactive singleton for connection status and server URL.
+ *
+ * Uses Svelte 5 runes ($state) so that UI components can reactively display
+ * connection status, errors, and configure the server URL.
+ *
+ * Module-level singleton -- one sync state per app instance.
+ */
+
+// --- Reactive state ---
+
+/** Whether the WebSocket is currently connected and open. */
+let connected = $state(false);
+
+/** Whether a connection attempt is in progress (first connect, not reconnect). */
+let connecting = $state(false);
+
+/** Whether the client is attempting to reconnect after a disconnect. */
+let reconnecting = $state(false);
+
+/** The last error message, or null if no error. */
+let lastError = $state<string | null>(null);
+
+/** Derive a same-origin WebSocket URL. */
+function defaultWsUrl(): string {
+  const proto = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+  return `${proto}//${window.location.host}/ws`;
+}
+
+/** The WebSocket server URL. */
+let serverUrl = $state(import.meta.env.VITE_SERVER_URL
+  ? `${(import.meta.env.VITE_SERVER_URL as string).replace(/^http/, 'ws')}/ws`
+  : defaultWsUrl());
+
+// --- Public API ---
+
+export const syncState = {
+  get connected() { return connected; },
+  set connected(v: boolean) { connected = v; },
+
+  get connecting() { return connecting; },
+  set connecting(v: boolean) { connecting = v; },
+
+  get reconnecting() { return reconnecting; },
+  set reconnecting(v: boolean) { reconnecting = v; },
+
+  get lastError() { return lastError; },
+  set lastError(v: string | null) { lastError = v; },
+
+  get serverUrl() { return serverUrl; },
+
+  /** Update the server URL. Does not trigger reconnect on its own. */
+  setServerUrl(url: string): void {
+    serverUrl = url;
+  },
+};