pixelweaver 0.1.0

package/src/lib/animation/animation-preview.svelte.ts

@@ -0,0 +1,151 @@
+/**
+ * Animation Preview -- playback controller for frame animation.
+ *
+ * Supports loop, pingpong, and side-by-side modes. The tick() method
+ * should be called from requestAnimationFrame; it advances frames
+ * based on per-frame timing from the frame model.
+ *
+ * Uses Svelte 5 $state runes for reactive playback state.
+ *
+ * Module-level singleton -- one preview state per app instance.
+ */
+
+import * as frameModel from './frame-model.svelte.js';
+
+// --- Types ---
+
+export type PreviewMode = 'loop' | 'pingpong' | 'side-by-side';
+
+// --- Reactive state ---
+
+let playing = $state<boolean>(false);
+let mode = $state<PreviewMode>('loop');
+let speedMultiplier = $state<number>(1.0);
+let previewFrameIndex = $state<number>(0);
+
+// Internal: accumulated time since last frame advance
+let accumulator = 0;
+// Internal: pingpong direction (1 = forward, -1 = backward)
+let pingpongDirection = 1;
+
+// --- Queries ---
+
+export function isPlaying(): boolean {
+  return playing;
+}
+
+export function getMode(): PreviewMode {
+  return mode;
+}
+
+export function getSpeedMultiplier(): number {
+  return speedMultiplier;
+}
+
+export function getPreviewFrameIndex(): number {
+  return previewFrameIndex;
+}
+
+// --- Mutations ---
+
+export function play(): void {
+  playing = true;
+  accumulator = 0;
+}
+
+export function pause(): void {
+  playing = false;
+}
+
+export function stop(): void {
+  playing = false;
+  previewFrameIndex = 0;
+  accumulator = 0;
+  pingpongDirection = 1;
+}
+
+export function step(direction: 1 | -1): void {
+  const totalFrames = frameModel.getFrames().length;
+  if (totalFrames === 0) return;
+
+  let next = previewFrameIndex + direction;
+  // Wrap around
+  if (next < 0) next = totalFrames - 1;
+  if (next >= totalFrames) next = 0;
+
+  previewFrameIndex = next;
+}
+
+export function setMode(newMode: PreviewMode): void {
+  mode = newMode;
+  // Reset pingpong direction when changing modes
+  pingpongDirection = 1;
+}
+
+export function setSpeed(multiplier: number): void {
+  speedMultiplier = Math.max(0.1, Math.min(10, multiplier));
+}
+
+/**
+ * Advance the preview by deltaMs milliseconds.
+ * Call from requestAnimationFrame. Respects per-frame duration and speed.
+ */
+export function tick(deltaMs: number): void {
+  if (!playing) return;
+
+  const totalFrames = frameModel.getFrames().length;
+  if (totalFrames <= 1) return;
+
+  accumulator += deltaMs;
+
+  // Advance as many frames as needed (handles large deltas).
+  // Recompute frameDuration each iteration because advanceFrame()
+  // changes previewFrameIndex and each frame may have a different duration.
+  let frameDuration = frameModel.getFrameDuration(previewFrameIndex) / speedMultiplier;
+  while (accumulator >= frameDuration) {
+    accumulator -= frameDuration;
+    advanceFrame(totalFrames);
+    frameDuration = frameModel.getFrameDuration(previewFrameIndex) / speedMultiplier;
+  }
+}
+
+/** Internal: advance one frame based on the current mode. */
+function advanceFrame(totalFrames: number): void {
+  if (mode === 'loop') {
+    previewFrameIndex = (previewFrameIndex + 1) % totalFrames;
+  } else if (mode === 'pingpong') {
+    const next = previewFrameIndex + pingpongDirection;
+    if (next >= totalFrames) {
+      // Reverse direction, step back one
+      pingpongDirection = -1;
+      previewFrameIndex = totalFrames - 2;
+      // Edge case: only 2 frames
+      if (previewFrameIndex < 0) previewFrameIndex = 0;
+    } else if (next < 0) {
+      // Reverse direction, step forward one
+      pingpongDirection = 1;
+      previewFrameIndex = 1;
+      // Edge case: only 2 frames
+      if (previewFrameIndex >= totalFrames) previewFrameIndex = 0;
+    } else {
+      previewFrameIndex = next;
+    }
+  } else {
+    // mode === 'side-by-side' -- the only remaining case.
+    // All frames shown simultaneously, but we still advance the
+    // "highlight" index for the UI.
+    previewFrameIndex = (previewFrameIndex + 1) % totalFrames;
+  }
+}
+
+/**
+ * Reset all preview state. Intended for tests only.
+ */
+export function _resetForTesting(): void {
+  playing = false;
+  mode = 'loop';
+  speedMultiplier = 1.0;
+  previewFrameIndex = 0;
+  accumulator = 0;
+  pingpongDirection = 1;
+}

package/src/lib/animation/clipboard.ts

@@ -0,0 +1,134 @@
+/**
+ * Clipboard -- internal and system clipboard operations for frames.
+ *
+ * The internal clipboard preserves layer structure (rich paste),
+ * while system clipboard operations flatten to PNG (interop paste).
+ */
+
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import type { Frame } from './frame-model.svelte.js';
+import type { Layer } from '../layers/layer-types.js';
+
+// --- Types ---
+
+export interface InternalClipboardData {
+  type: 'frame' | 'selection';
+  layers: { id: string; name: string; pixelData: ArrayBuffer }[];
+  width: number;
+  height: number;
+}
+
+// --- Internal clipboard state ---
+
+let internalClipboard: InternalClipboardData | null = null;
+
+// --- Internal clipboard operations ---
+
+/**
+ * Copy a frame's pixel data to the internal clipboard, preserving layer info.
+ * Only copies layers that have pixel data in the frame.
+ */
+export function copyFrameToInternal(frame: Frame, layerTree: Layer[]): void {
+  const layers: InternalClipboardData['layers'] = [];
+  let width = 0;
+  let height = 0;
+
+  // Walk all pixel layers in the tree to maintain order
+  function collectLayers(tree: Layer[]): void {
+    for (const layer of tree) {
+      if (layer.type === 'pixel') {
+        const buffer = frame.pixelData.get(layer.id);
+        if (buffer) {
+          // Store a copy of the raw data as ArrayBuffer
+          layers.push({
+            id: layer.id,
+            name: layer.name,
+            pixelData: buffer.data.buffer.slice(0) as ArrayBuffer,
+          });
+          width = buffer.width;
+          height = buffer.height;
+        }
+      } else if (layer.children) {
+        collectLayers(layer.children);
+      }
+    }
+  }
+
+  collectLayers(layerTree);
+
+  internalClipboard = {
+    type: 'frame',
+    layers,
+    width,
+    height,
+  };
+}
+
+/**
+ * Read from the internal clipboard. Returns null if empty.
+ */
+export function pasteFromInternal(): InternalClipboardData | null {
+  return internalClipboard;
+}
+
+/**
+ * Copy a composited (flattened) frame to the system clipboard as PNG.
+ * Uses the Clipboard API (requires secure context / user gesture).
+ */
+export async function copyToSystemClipboard(composited: PixelBuffer): Promise<void> {
+  // Create an offscreen canvas to convert PixelBuffer to PNG blob
+  const canvas = new OffscreenCanvas(composited.width, composited.height);
+  const ctx = canvas.getContext('2d');
+  if (!ctx) throw new Error('Could not get 2d context from OffscreenCanvas.');
+
+  ctx.putImageData(composited.toImageData(), 0, 0);
+  const blob = await canvas.convertToBlob({ type: 'image/png' });
+
+  await navigator.clipboard.write([
+    new ClipboardItem({ 'image/png': blob }),
+  ]);
+}
+
+/**
+ * Paste an image from the system clipboard as a PixelBuffer.
+ * Returns null if no image is available.
+ */
+export async function pasteFromSystemClipboard(): Promise<PixelBuffer | null> {
+  const items = await navigator.clipboard.read();
+
+  for (const item of items) {
+    if (item.types.includes('image/png')) {
+      const blob = await item.getType('image/png');
+      const bitmap = await createImageBitmap(blob);
+
+      const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+      const ctx = canvas.getContext('2d');
+      if (!ctx) continue;
+
+      ctx.drawImage(bitmap, 0, 0);
+      const imageData = ctx.getImageData(0, 0, bitmap.width, bitmap.height);
+
+      return new PixelBuffer(
+        imageData.width,
+        imageData.height,
+        new Uint8ClampedArray(imageData.data),
+      );
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Clear the internal clipboard.
+ */
+export function clearInternal(): void {
+  internalClipboard = null;
+}
+
+/**
+ * Reset clipboard state. Intended for tests only.
+ */
+export function _resetForTesting(): void {
+  internalClipboard = null;
+}

package/src/lib/animation/frame-model.svelte.ts

@@ -0,0 +1,437 @@
+/**
+ * Frame Model -- reactive state for animation frames.
+ *
+ * Each frame holds per-layer pixel data (the layer structure itself is shared
+ * across all frames via layer-tree.svelte.ts). Uses Svelte 5 $state runes.
+ *
+ * Module-level singleton -- one frame model per app instance.
+ */
+
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import { SvelteMap } from 'svelte/reactivity';
+
+// --- Types ---
+
+export interface Frame {
+  id: string;
+  index: number;
+  /** null = use global FPS; number = per-frame override in milliseconds */
+  durationMs: number | null;
+  /** layerId -> pixel data for this frame */
+  pixelData: Map<string, PixelBuffer>;
+}
+
+export interface SerializedFrame {
+  id: string;
+  index: number;
+  durationMs: number | null;
+  pixelData: Record<string, { width: number; height: number; data: number[] }>;
+}
+
+export interface FramesSerialized {
+  frames: SerializedFrame[];
+  currentFrameIndex: number;
+  globalFps: number;
+  originX: number;
+  originY: number;
+}
+
+// --- Reactive state ---
+
+let frames = $state<Frame[]>([]);
+let currentFrameIndex = $state<number>(0);
+let globalFps = $state<number>(12);
+let originX = $state<number>(0);
+let originY = $state<number>(0);
+
+// --- Internal helpers ---
+
+function createFrame(index: number): Frame {
+  return {
+    id: crypto.randomUUID(),
+    index,
+    durationMs: null,
+    pixelData: new Map(),
+  };
+}
+
+/** Re-index all frames so frame.index matches array position. */
+function reindex(): void {
+  for (let i = 0; i < frames.length; i++) {
+    const f = frames[i];
+    if (f) f.index = i;
+  }
+}
+
+// --- Queries ---
+
+export function getFrames(): Frame[] {
+  return frames;
+}
+
+export function getCurrentFrameIndex(): number {
+  return currentFrameIndex;
+}
+
+export function getGlobalFps(): number {
+  return globalFps;
+}
+
+export function getOriginX(): number {
+  return originX;
+}
+
+export function getOriginY(): number {
+  return originY;
+}
+
+export function getCurrentFrame(): Frame {
+  if (frames.length === 0) {
+    throw new Error('No frames exist.');
+  }
+  const frame = frames[currentFrameIndex];
+  if (!frame) throw new Error(`Current frame index ${String(currentFrameIndex)} out of range.`);
+  return frame;
+}
+
+/**
+ * Get the actual duration in ms for a frame.
+ * Uses per-frame override if set, otherwise derives from global FPS.
+ */
+export function getFrameDuration(index: number): number {
+  if (index < 0 || index >= frames.length) {
+    throw new Error(`Frame index ${String(index)} out of range (0..${String(frames.length - 1)}).`);
+  }
+  const frame = frames[index];
+  if (!frame) throw new Error(`Frame index ${String(index)} missing`);
+  if (frame.durationMs !== null) {
+    return frame.durationMs;
+  }
+  // Derive from global FPS: 1000ms / fps
+  return Math.round(1000 / globalFps);
+}
+
+export function getPixelDataForLayer(frameIndex: number, layerId: string): PixelBuffer | undefined {
+  if (frameIndex < 0 || frameIndex >= frames.length) return undefined;
+  return frames[frameIndex]?.pixelData.get(layerId);
+}
+
+// --- Mutations ---
+
+export function addFrame(options?: { afterIndex?: number; duplicate?: boolean }): Frame {
+  const insertAfter = options?.afterIndex ?? frames.length - 1;
+  const insertIndex = Math.max(0, Math.min(insertAfter + 1, frames.length));
+
+  const newFrame = createFrame(insertIndex);
+
+  // If duplicating, copy pixel data from the source frame
+  if (options?.duplicate && frames.length > 0) {
+    const sourceIndex = Math.min(insertAfter, frames.length - 1);
+    const source = frames[sourceIndex >= 0 ? sourceIndex : 0];
+    if (source) {
+      for (const [layerId, buffer] of source.pixelData) {
+        newFrame.pixelData.set(layerId, buffer.clone());
+      }
+    }
+  }
+
+  frames.splice(insertIndex, 0, newFrame);
+  reindex();
+  return newFrame;
+}
+
+export function removeFrame(index: number): void {
+  if (index < 0 || index >= frames.length) {
+    throw new Error(`Frame index ${String(index)} out of range.`);
+  }
+  if (frames.length <= 1) {
+    throw new Error('Cannot remove the last frame.');
+  }
+
+  frames.splice(index, 1);
+  reindex();
+
+  // Adjust current frame index if needed
+  if (currentFrameIndex >= frames.length) {
+    currentFrameIndex = frames.length - 1;
+  }
+}
+
+export function duplicateFrame(index: number): Frame {
+  if (index < 0 || index >= frames.length) {
+    throw new Error(`Frame index ${String(index)} out of range.`);
+  }
+  return addFrame({ afterIndex: index, duplicate: true });
+}
+
+export function reorderFrame(fromIndex: number, toIndex: number): void {
+  if (fromIndex < 0 || fromIndex >= frames.length) {
+    throw new Error(`Source frame index ${String(fromIndex)} out of range.`);
+  }
+  if (toIndex < 0 || toIndex >= frames.length) {
+    throw new Error(`Target frame index ${String(toIndex)} out of range.`);
+  }
+  if (fromIndex === toIndex) return;
+
+  const [moved] = frames.splice(fromIndex, 1) as [Frame];
+  frames.splice(toIndex, 0, moved);
+  reindex();
+
+  // Keep current frame tracking the same frame object
+  if (currentFrameIndex === fromIndex) {
+    currentFrameIndex = toIndex;
+  } else if (fromIndex < currentFrameIndex && toIndex >= currentFrameIndex) {
+    currentFrameIndex--;
+  } else if (fromIndex > currentFrameIndex && toIndex <= currentFrameIndex) {
+    currentFrameIndex++;
+  }
+}
+
+/**
+ * Move a set of frames (preserving their relative order) to a target position.
+ * The target index refers to the position in the original array where the
+ * group should land after extraction and re-insertion.
+ */
+export function reorderFrames(fromIndices: number[], toIndex: number): void {
+  if (fromIndices.length === 0) return;
+
+  // De-dup, validate, and sort ascending
+  // eslint-disable-next-line svelte/prefer-svelte-reactivity -- function-local dedup helper
+  const sorted = [...new Set(fromIndices)]
+    .filter((i) => i >= 0 && i < frames.length)
+    .sort((a, b) => a - b);
+
+  if (sorted.length === 0) return;
+
+  // Extract frames at those indices (in ascending order to preserve relative order)
+  const extracted: Frame[] = sorted.map((i) => frames[i] as Frame);
+
+  // Remove them from the array in reverse order to preserve indices during removal
+  for (let i = sorted.length - 1; i >= 0; i--) {
+    const idx = sorted[i];
+    if (idx !== undefined) frames.splice(idx, 1);
+  }
+
+  // Calculate adjusted target index: account for removed items that were before the target
+  let adjustedTarget = toIndex;
+  for (const idx of sorted) {
+    if (idx < toIndex) {
+      adjustedTarget--;
+    }
+  }
+
+  // Clamp to valid range after removals
+  adjustedTarget = Math.max(0, Math.min(adjustedTarget, frames.length));
+
+  // Insert extracted frames at the adjusted target position
+  frames.splice(adjustedTarget, 0, ...extracted);
+  reindex();
+
+  // Clamp currentFrameIndex to valid range
+  if (currentFrameIndex >= frames.length) {
+    currentFrameIndex = frames.length - 1;
+  }
+}
+
+export function setCurrentFrame(index: number): void {
+  if (index < 0 || index >= frames.length) {
+    throw new Error(`Frame index ${String(index)} out of range.`);
+  }
+  currentFrameIndex = index;
+}
+
+export function setGlobalFps(fps: number): void {
+  if (fps < 1 || fps > 120) {
+    throw new Error(`FPS must be between 1 and 120, got ${String(fps)}.`);
+  }
+  globalFps = fps;
+}
+
+export function setFrameDuration(index: number, durationMs: number | null): void {
+  if (index < 0 || index >= frames.length) {
+    throw new Error(`Frame index ${String(index)} out of range.`);
+  }
+  if (durationMs !== null && durationMs <= 0) {
+    throw new Error('Frame duration must be positive.');
+  }
+  const fr = frames[index];
+  if (fr) fr.durationMs = durationMs;
+}
+
+export function setOrigin(x: number, y: number): void {
+  originX = x;
+  originY = y;
+}
+
+// --- Server state application ---
+
+/**
+ * Replace all animation state from server-native data.
+ * Each frame's pixelData is already a Map<string, PixelBuffer>.
+ * Unlike deserialize(), this avoids the wasteful number-array conversion
+ * since the server sends base64-encoded pixel data decoded upstream.
+ */
+export function applyServerState(
+  serverFrames: Array<{
+    id: string;
+    durationMs: number | null;
+    pixelData: Map<string, PixelBuffer>;
+  }>,
+  newCurrentFrameIndex: number,
+  newGlobalFps: number,
+  newOriginX: number,
+  newOriginY: number,
+): void {
+  frames = serverFrames.map((sf, i) => ({
+    id: sf.id,
+    index: i,
+    durationMs: sf.durationMs,
+    // Ensure reactive Map for Svelte 5
+    pixelData:
+      sf.pixelData instanceof SvelteMap
+        ? sf.pixelData
+        : new SvelteMap(sf.pixelData),
+  }));
+  currentFrameIndex = Math.max(
+    0,
+    Math.min(newCurrentFrameIndex, frames.length - 1),
+  );
+  globalFps = Math.max(1, Math.min(newGlobalFps, 120));
+  originX = newOriginX;
+  originY = newOriginY;
+}
+
+// --- Serialization ---
+
+export function serialize(): FramesSerialized {
+  return {
+    frames: frames.map((frame) => {
+      const pixelData: Record<string, { width: number; height: number; data: number[] }> = {};
+      for (const [layerId, buffer] of frame.pixelData) {
+        pixelData[layerId] = {
+          width: buffer.width,
+          height: buffer.height,
+          data: Array.from(buffer.data),
+        };
+      }
+      return {
+        id: frame.id,
+        index: frame.index,
+        durationMs: frame.durationMs,
+        pixelData,
+      };
+    }),
+    currentFrameIndex,
+    globalFps,
+    originX,
+    originY,
+  };
+}
+
+export function deserialize(data: FramesSerialized): void {
+  frames = data.frames.map((sf) => {
+    const pixelData = new SvelteMap<string, PixelBuffer>();
+    for (const [layerId, bufData] of Object.entries(sf.pixelData)) {
+      pixelData.set(
+        layerId,
+        new PixelBuffer(bufData.width, bufData.height, new Uint8ClampedArray(bufData.data)),
+      );
+    }
+    return {
+      id: sf.id,
+      index: sf.index,
+      durationMs: sf.durationMs,
+      pixelData,
+    };
+  });
+  currentFrameIndex = data.currentFrameIndex;
+  globalFps = data.globalFps;
+  originX = data.originX;
+  originY = data.originY;
+}
+
+/**
+ * Insert a frame object at a specific index (for undo restore).
+ * Does NOT reindex -- caller is responsible for calling reindex if needed.
+ */
+export function _insertFrameAt(index: number, frame: Frame): void {
+  frames.splice(index, 0, frame);
+  reindex();
+}
+
+/**
+ * Remove a frame by index and return it (for undo snapshots).
+ */
+export function _removeFrameAt(index: number): Frame {
+  const [removed] = frames.splice(index, 1) as [Frame];
+  reindex();
+  if (currentFrameIndex >= frames.length) {
+    currentFrameIndex = Math.max(0, frames.length - 1);
+  }
+  return removed;
+}
+
+/**
+ * Remove multiple frames at the given indices.
+ * Indices are de-duped, sorted, and removed in reverse order to avoid index shifting.
+ * Cannot remove ALL frames -- at least one frame is always kept (the lowest-indexed survivor).
+ * Returns the removed Frame objects in their original index order (for undo).
+ */
+export function removeFrames(indices: number[]): Frame[] {
+  if (indices.length === 0) return [];
+
+  // De-dup and sort ascending. Local transient Set -- not reactive state.
+  // eslint-disable-next-line svelte/prefer-svelte-reactivity -- function-local dedup helper
+  const unique = [...new Set(indices)]
+    .filter((i) => i >= 0 && i < frames.length)
+    .sort((a, b) => a - b);
+
+  if (unique.length === 0) return [];
+
+  // If indices cover ALL frames, keep the first one
+  let toRemove = unique;
+  if (toRemove.length >= frames.length) {
+    toRemove = toRemove.slice(1); // drop index 0 so frame 0 survives
+  }
+
+  // Remove in reverse order (highest first) to preserve lower indices
+  const removed: Frame[] = [];
+  for (let i = toRemove.length - 1; i >= 0; i--) {
+    const idx = toRemove[i];
+    if (idx === undefined) continue;
+    const [r] = frames.splice(idx, 1) as [Frame];
+    removed.unshift(r); // prepend so result is in ascending index order
+  }
+
+  reindex();
+
+  // Clamp currentFrameIndex to valid range
+  if (currentFrameIndex >= frames.length) {
+    currentFrameIndex = frames.length - 1;
+  }
+
+  return removed;
+}
+
+/**
+ * Insert multiple frames starting at the given index.
+ * Useful for undo of bulk delete and for paste-multiple.
+ */
+export function insertFramesAt(index: number, framesToInsert: Frame[]): void {
+  if (framesToInsert.length === 0) return;
+
+  const clampedIndex = Math.max(0, Math.min(index, frames.length));
+  frames.splice(clampedIndex, 0, ...framesToInsert);
+  reindex();
+}
+
+/**
+ * Reset all frame state. Intended for tests only.
+ */
+export function _resetForTesting(): void {
+  frames = [];
+  currentFrameIndex = 0;
+  globalFps = 12;
+  originX = 0;
+  originY = 0;
+}