pixelweaver 0.1.0

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

@@ -0,0 +1,314 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import * as fm from './frame-model.svelte.js';
+
+beforeEach(() => {
+  fm._resetForTesting();
+});
+
+describe('addFrame', () => {
+  it('should add a frame to an empty list', () => {
+    fm.addFrame();
+    expect(fm.getFrames()).toHaveLength(1);
+    expect(fm.getFrames()[0]?.index).toBe(0);
+  });
+
+  it('should insert after a specific index', () => {
+    fm.addFrame();
+    fm.addFrame();
+    fm.addFrame({ afterIndex: 0 });
+    expect(fm.getFrames()).toHaveLength(3);
+    // The new frame should be at index 1
+    expect(fm.getFrames()[1]?.id).not.toBe(fm.getFrames()[0]?.id);
+  });
+
+  it('should duplicate pixel data when duplicate option is set', () => {
+    const frame = fm.addFrame();
+    const buf = new PixelBuffer(2, 2);
+    buf.setPixel(0, 0, 255, 0, 0, 255);
+    frame.pixelData.set('layer1', buf);
+
+    fm.addFrame({ afterIndex: 0, duplicate: true });
+    const duped = fm.getFrames()[1];
+    if (!duped) throw new Error('expected duplicated frame');
+    const dupedBuf = duped.pixelData.get('layer1');
+    expect(dupedBuf).toBeDefined();
+    expect(dupedBuf?.getPixel(0, 0)).toEqual([255, 0, 0, 255]);
+    // Verify it's a copy, not a reference
+    buf.setPixel(0, 0, 0, 255, 0, 255);
+    expect(dupedBuf?.getPixel(0, 0)).toEqual([255, 0, 0, 255]);
+  });
+});
+
+describe('removeFrame', () => {
+  it('should remove a frame by index', () => {
+    fm.addFrame();
+    fm.addFrame();
+    fm.removeFrame(0);
+    expect(fm.getFrames()).toHaveLength(1);
+    expect(fm.getFrames()[0]?.index).toBe(0);
+  });
+
+  it('should throw when removing the last frame', () => {
+    fm.addFrame();
+    expect(() => { fm.removeFrame(0); }).toThrow('Cannot remove the last frame');
+  });
+
+  it('should adjust currentFrameIndex if needed', () => {
+    fm.addFrame();
+    fm.addFrame();
+    fm.setCurrentFrame(1);
+    fm.removeFrame(1);
+    expect(fm.getCurrentFrameIndex()).toBe(0);
+  });
+});
+
+describe('duplicateFrame', () => {
+  it('should create a copy after the source frame', () => {
+    const f0 = fm.addFrame();
+    const buf = new PixelBuffer(4, 4);
+    buf.fill(128, 128, 128, 255);
+    f0.pixelData.set('bg', buf);
+
+    fm.duplicateFrame(0);
+    expect(fm.getFrames()).toHaveLength(2);
+    const copy = fm.getFrames()[1];
+    if (!copy) throw new Error('expected duplicated copy');
+    const copyBuf = copy.pixelData.get('bg');
+    expect(copyBuf).toBeDefined();
+    expect(copyBuf?.getPixel(0, 0)).toEqual([128, 128, 128, 255]);
+  });
+});
+
+describe('reorderFrame', () => {
+  it('should swap frame positions', () => {
+    const f0 = fm.addFrame();
+    const f1 = fm.addFrame();
+    const id0 = f0.id;
+    const id1 = f1.id;
+
+    fm.reorderFrame(0, 1);
+    expect(fm.getFrames()[0]?.id).toBe(id1);
+    expect(fm.getFrames()[1]?.id).toBe(id0);
+    // Indices should be reindexed
+    expect(fm.getFrames()[0]?.index).toBe(0);
+    expect(fm.getFrames()[1]?.index).toBe(1);
+  });
+
+  it('should track current frame through reorder', () => {
+    fm.addFrame();
+    fm.addFrame();
+    fm.addFrame();
+    fm.setCurrentFrame(0);
+    fm.reorderFrame(0, 2);
+    expect(fm.getCurrentFrameIndex()).toBe(2);
+  });
+});
+
+describe('reorderFrames', () => {
+  it('should move 2 adjacent frames forward', () => {
+    // Setup: 5 frames [A, B, C, D, E]
+    const fA = fm.addFrame();
+    const fB = fm.addFrame();
+    const fC = fm.addFrame();
+    const fD = fm.addFrame();
+    const fE = fm.addFrame();
+    const idA = fA.id, idB = fB.id, idC = fC.id, idD = fD.id, idE = fE.id;
+
+    // Move frames [0,1] (A,B) to position 4
+    // After extraction: [C, D, E], adjusted target = 4 - 2 = 2 (end)
+    // Result: [C, D, E, A, B]  -- wait, let's recalculate:
+    // sorted=[0,1], extracted=[A,B], remaining=[C,D,E]
+    // adjustedTarget = 4 - 2 (both 0 and 1 < 4) = 2
+    // splice(2, 0, A, B) into [C,D,E] => [C,D,A,B,E]
+    fm.reorderFrames([0, 1], 4);
+    const ids = fm.getFrames().map((f) => f.id);
+    expect(ids).toEqual([idC, idD, idA, idB, idE]);
+    // Verify reindexing
+    fm.getFrames().forEach((f, i) => {
+      expect(f.index).toBe(i);
+    });
+  });
+
+  it('should move 2 adjacent frames backward', () => {
+    // Setup: 5 frames [A, B, C, D, E]
+    const fA = fm.addFrame();
+    const fB = fm.addFrame();
+    const fC = fm.addFrame();
+    const fD = fm.addFrame();
+    const fE = fm.addFrame();
+    const idA = fA.id, idB = fB.id, idC = fC.id, idD = fD.id, idE = fE.id;
+
+    // Move frames [3,4] (D,E) to position 1
+    // sorted=[3,4], extracted=[D,E], remaining=[A,B,C]
+    // adjustedTarget = 1 - 0 (neither 3 nor 4 < 1) = 1
+    // splice(1, 0, D, E) into [A,B,C] => [A,D,E,B,C]
+    fm.reorderFrames([3, 4], 1);
+    const ids = fm.getFrames().map((f) => f.id);
+    expect(ids).toEqual([idA, idD, idE, idB, idC]);
+  });
+
+  it('should move non-contiguous frames', () => {
+    // Setup: 5 frames [A, B, C, D, E]
+    const fA = fm.addFrame();
+    const fB = fm.addFrame();
+    const fC = fm.addFrame();
+    const fD = fm.addFrame();
+    const fE = fm.addFrame();
+    const idA = fA.id, idB = fB.id, idC = fC.id, idD = fD.id, idE = fE.id;
+
+    // Move frames [0, 2] (A, C) to position 4
+    // sorted=[0,2], extracted=[A,C], remaining=[B,D,E]
+    // adjustedTarget = 4 - 2 (both 0 and 2 < 4) = 2
+    // splice(2, 0, A, C) into [B,D,E] => [B,D,A,C,E]
+    fm.reorderFrames([0, 2], 4);
+    const ids = fm.getFrames().map((f) => f.id);
+    expect(ids).toEqual([idB, idD, idA, idC, idE]);
+  });
+
+  it('should be a no-op when moving all frames to position 0', () => {
+    const fA = fm.addFrame();
+    const fB = fm.addFrame();
+    const fC = fm.addFrame();
+    const idA = fA.id, idB = fB.id, idC = fC.id;
+
+    // Move all frames [0,1,2] to position 0
+    // sorted=[0,1,2], extracted=[A,B,C], remaining=[]
+    // adjustedTarget = 0 - 0 = 0
+    // splice(0, 0, A, B, C) into [] => [A, B, C]
+    fm.reorderFrames([0, 1, 2], 0);
+    const ids = fm.getFrames().map((f) => f.id);
+    expect(ids).toEqual([idA, idB, idC]);
+  });
+
+  it('should work like reorderFrame for single-frame input', () => {
+    const fA = fm.addFrame();
+    const fB = fm.addFrame();
+    const fC = fm.addFrame();
+    const idA = fA.id, idB = fB.id, idC = fC.id;
+
+    // Move frame [0] (A) to position 2
+    // sorted=[0], extracted=[A], remaining=[B,C]
+    // adjustedTarget = 2 - 1 (0 < 2) = 1
+    // splice(1, 0, A) into [B,C] => [B,A,C]
+    fm.reorderFrames([0], 2);
+    const ids = fm.getFrames().map((f) => f.id);
+    expect(ids).toEqual([idB, idA, idC]);
+  });
+
+  it('should handle target within the selected range', () => {
+    // Setup: 5 frames [A, B, C, D, E]
+    const fA = fm.addFrame();
+    const fB = fm.addFrame();
+    const fC = fm.addFrame();
+    const fD = fm.addFrame();
+    const fE = fm.addFrame();
+    const idA = fA.id, idB = fB.id, idC = fC.id, idD = fD.id, idE = fE.id;
+
+    // Move frames [1,2,3] (B,C,D) to position 2 (within the range)
+    // sorted=[1,2,3], extracted=[B,C,D], remaining=[A,E]
+    // adjustedTarget = 2 - 1 (only 1 < 2) = 1
+    // splice(1, 0, B, C, D) into [A,E] => [A,B,C,D,E]
+    fm.reorderFrames([1, 2, 3], 2);
+    const ids = fm.getFrames().map((f) => f.id);
+    expect(ids).toEqual([idA, idB, idC, idD, idE]);
+  });
+});
+
+describe('frame duration', () => {
+  it('should derive duration from global FPS when no override', () => {
+    fm.addFrame();
+    fm.setGlobalFps(10);
+    expect(fm.getFrameDuration(0)).toBe(100); // 1000 / 10
+  });
+
+  it('should use per-frame override when set', () => {
+    fm.addFrame();
+    fm.setFrameDuration(0, 200);
+    expect(fm.getFrameDuration(0)).toBe(200);
+  });
+
+  it('should reset to global FPS when override cleared', () => {
+    fm.addFrame();
+    fm.setGlobalFps(12);
+    fm.setFrameDuration(0, 200);
+    fm.setFrameDuration(0, null);
+    expect(fm.getFrameDuration(0)).toBe(Math.round(1000 / 12));
+  });
+});
+
+describe('current frame', () => {
+  it('should start at index 0', () => {
+    fm.addFrame();
+    expect(fm.getCurrentFrameIndex()).toBe(0);
+  });
+
+  it('should change via setCurrentFrame', () => {
+    fm.addFrame();
+    fm.addFrame();
+    fm.setCurrentFrame(1);
+    expect(fm.getCurrentFrameIndex()).toBe(1);
+    expect(fm.getCurrentFrame().index).toBe(1);
+  });
+
+  it('should throw for out-of-range index', () => {
+    fm.addFrame();
+    expect(() => { fm.setCurrentFrame(5); }).toThrow();
+  });
+});
+
+describe('origin', () => {
+  it('should default to (0, 0)', () => {
+    expect(fm.getOriginX()).toBe(0);
+    expect(fm.getOriginY()).toBe(0);
+  });
+
+  it('should update via setOrigin', () => {
+    fm.setOrigin(16, 32);
+    expect(fm.getOriginX()).toBe(16);
+    expect(fm.getOriginY()).toBe(32);
+  });
+});
+
+describe('getPixelDataForLayer', () => {
+  it('should return pixel data for a valid frame and layer', () => {
+    const frame = fm.addFrame();
+    const buf = new PixelBuffer(8, 8);
+    frame.pixelData.set('myLayer', buf);
+    expect(fm.getPixelDataForLayer(0, 'myLayer')).toBe(buf);
+  });
+
+  it('should return undefined for missing layer', () => {
+    fm.addFrame();
+    expect(fm.getPixelDataForLayer(0, 'nonexistent')).toBeUndefined();
+  });
+});
+
+describe('serialize / deserialize', () => {
+  it('should roundtrip frame state', () => {
+    const f0 = fm.addFrame();
+    const buf = new PixelBuffer(4, 4);
+    buf.setPixel(1, 1, 42, 43, 44, 255);
+    f0.pixelData.set('layer1', buf);
+    fm.addFrame();
+    fm.setCurrentFrame(1);
+    fm.setGlobalFps(24);
+    fm.setOrigin(8, 16);
+    fm.setFrameDuration(0, 150);
+
+    const serialized = fm.serialize();
+    fm._resetForTesting();
+    fm.deserialize(serialized);
+
+    expect(fm.getFrames()).toHaveLength(2);
+    expect(fm.getCurrentFrameIndex()).toBe(1);
+    expect(fm.getGlobalFps()).toBe(24);
+    expect(fm.getOriginX()).toBe(8);
+    expect(fm.getOriginY()).toBe(16);
+    expect(fm.getFrames()[0]?.durationMs).toBe(150);
+
+    const restored = fm.getPixelDataForLayer(0, 'layer1');
+    expect(restored).toBeDefined();
+    expect(restored?.getPixel(1, 1)).toEqual([42, 43, 44, 255]);
+  });
+});

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

@@ -0,0 +1,77 @@
+/**
+ * Frame Selection State -- tracks which frames are selected for bulk operations.
+ *
+ * Supports three selection modes:
+ * - Click: single select (clear others, set anchor)
+ * - Ctrl+Click: toggle individual frame in/out of selection
+ * - Shift+Click: extend range from anchor to clicked frame
+ *
+ * The "anchor" is the last frame clicked without Shift, used as the
+ * range start for Shift+Click.
+ */
+
+// Use SvelteSet for reactivity
+import { SvelteSet } from 'svelte/reactivity';
+
+const selected = new SvelteSet<number>();
+let anchor = $state(0);
+
+export const frameSelection = {
+  /** The set of selected frame indices. */
+  get selected(): ReadonlySet<number> { return selected; },
+
+  /** The anchor index (start of shift-click range). */
+  get anchor() { return anchor; },
+
+  /** Whether a specific frame index is selected. */
+  isSelected(index: number): boolean { return selected.has(index); },
+
+  /** Whether multiple frames are selected. */
+  get hasMultiple(): boolean { return selected.size > 1; },
+
+  /** Number of selected frames. */
+  get count(): number { return selected.size; },
+
+  /** Get selected indices sorted ascending. */
+  get sortedIndices(): number[] { return [...selected].sort((a, b) => a - b); },
+
+  /** Single click: clear selection, select one, set anchor. */
+  selectOne(index: number): void {
+    selected.clear();
+    selected.add(index);
+    anchor = index;
+  },
+
+  /** Ctrl+Click: toggle one frame without affecting others. Update anchor. */
+  toggle(index: number): void {
+    if (selected.has(index)) {
+      selected.delete(index);
+    } else {
+      selected.add(index);
+    }
+    anchor = index;
+  },
+
+  /** Shift+Click: select range from anchor to index (inclusive). */
+  extendTo(index: number): void {
+    selected.clear();
+    const from = Math.min(anchor, index);
+    const to = Math.max(anchor, index);
+    for (let i = from; i <= to; i++) {
+      selected.add(i);
+    }
+    // Don't update anchor -- shift-click preserves the anchor
+  },
+
+  /** Clear all selection. */
+  clear(): void {
+    selected.clear();
+  },
+
+  /** Adjust indices after frames are added/removed. Call after any frame mutation. */
+  // For simplicity, just clear selection on structural changes
+  reset(): void {
+    selected.clear();
+    anchor = 0;
+  },
+};

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

@@ -0,0 +1,238 @@
+/**
+ * Frame Tags -- named ranges of frames for organizing animations.
+ *
+ * Tags can be nested (parentId) to represent sub-animations within
+ * larger sequences. Uses Svelte 5 $state runes.
+ *
+ * Module-level singleton -- one tag state per app instance.
+ */
+
+// --- Types ---
+
+export interface FrameTag {
+  id: string;
+  name: string;
+  color: string;
+  startFrame: number; // inclusive
+  endFrame: number;   // inclusive
+  parentId: string | null;
+  children: FrameTag[];
+}
+
+interface SerializedTag {
+  id: string;
+  name: string;
+  color: string;
+  startFrame: number;
+  endFrame: number;
+  parentId: string | null;
+  children: SerializedTag[];
+}
+
+// --- Reactive state ---
+
+let tags = $state<FrameTag[]>([]);
+
+// --- Internal helpers ---
+
+/** Default tag colors, cycled through on creation. */
+const TAG_COLORS = [
+  '#4A90D9', '#D94A4A', '#4AD96B', '#D9C74A',
+  '#9B59B6', '#E67E22', '#1ABC9C', '#E74C3C',
+];
+let colorIndex = 0;
+
+function nextColor(): string {
+  // TAG_COLORS is non-empty so the modulo lookup is always defined.
+  const color = TAG_COLORS[colorIndex % TAG_COLORS.length] ?? '#4A90D9';
+  colorIndex++;
+  return color;
+}
+
+/** Find a tag by ID in the entire tree. */
+function findTag(id: string, searchIn: FrameTag[] = tags): FrameTag | undefined {
+  for (const tag of searchIn) {
+    if (tag.id === id) return tag;
+    const found = findTag(id, tag.children);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+/** Find a tag and its parent array by ID. */
+function findTagContext(
+  id: string,
+  searchIn: FrameTag[] = tags,
+): { tag: FrameTag; siblings: FrameTag[]; index: number } | undefined {
+  for (let i = 0; i < searchIn.length; i++) {
+    const current = searchIn[i];
+    if (!current) continue;
+    if (current.id === id) {
+      return { tag: current, siblings: searchIn, index: i };
+    }
+    const found = findTagContext(id, current.children);
+    if (found) return found;
+  }
+  return undefined;
+}
+
+// --- Queries ---
+
+export function getTags(): FrameTag[] {
+  return tags;
+}
+
+export function getTag(id: string): FrameTag | undefined {
+  return findTag(id);
+}
+
+/** Get all tags that span a given frame index. */
+export function getTagsForFrame(frameIndex: number): FrameTag[] {
+  const result: FrameTag[] = [];
+
+  function walk(searchIn: FrameTag[]): void {
+    for (const tag of searchIn) {
+      if (frameIndex >= tag.startFrame && frameIndex <= tag.endFrame) {
+        result.push(tag);
+      }
+      walk(tag.children);
+    }
+  }
+
+  walk(tags);
+  return result;
+}
+
+/**
+ * Get the full frame range for a tag, including its nested children.
+ * Returns the min start and max end across the tag and all descendants.
+ */
+export function getFrameRange(tagId: string): { start: number; end: number } {
+  const tag = findTag(tagId);
+  if (!tag) {
+    throw new Error(`Tag "${tagId}" not found.`);
+  }
+
+  let start = tag.startFrame;
+  let end = tag.endFrame;
+
+  function expandRange(t: FrameTag): void {
+    start = Math.min(start, t.startFrame);
+    end = Math.max(end, t.endFrame);
+    for (const child of t.children) {
+      expandRange(child);
+    }
+  }
+
+  expandRange(tag);
+  return { start, end };
+}
+
+// --- Mutations ---
+
+export function addTag(
+  name: string,
+  startFrame: number,
+  endFrame: number,
+  options?: { color?: string; parentId?: string },
+): FrameTag {
+  if (startFrame > endFrame) {
+    throw new Error(`startFrame (${String(startFrame)}) must be <= endFrame (${String(endFrame)}).`);
+  }
+
+  const tag: FrameTag = {
+    id: crypto.randomUUID(),
+    name,
+    color: options?.color ?? nextColor(),
+    startFrame,
+    endFrame,
+    parentId: options?.parentId ?? null,
+    children: [],
+  };
+
+  if (options?.parentId) {
+    const parent = findTag(options.parentId);
+    if (!parent) {
+      throw new Error(`Parent tag "${options.parentId}" not found.`);
+    }
+    tag.parentId = parent.id;
+    parent.children.push(tag);
+  } else {
+    tags.push(tag);
+  }
+
+  // Return the proxy version from the tree (just inserted above).
+  const inserted = findTag(tag.id);
+  if (!inserted) throw new Error(`addTag: inserted tag "${tag.id}" not found`);
+  return inserted;
+}
+
+export function removeTag(id: string): void {
+  const ctx = findTagContext(id);
+  if (!ctx) {
+    throw new Error(`Tag "${id}" not found.`);
+  }
+  ctx.siblings.splice(ctx.index, 1);
+}
+
+export function updateTag(
+  id: string,
+  updates: Partial<{ name: string; color: string; startFrame: number; endFrame: number }>,
+): void {
+  const tag = findTag(id);
+  if (!tag) {
+    throw new Error(`Tag "${id}" not found.`);
+  }
+
+  if (updates.name !== undefined) tag.name = updates.name;
+  if (updates.color !== undefined) tag.color = updates.color;
+  if (updates.startFrame !== undefined) tag.startFrame = updates.startFrame;
+  if (updates.endFrame !== undefined) tag.endFrame = updates.endFrame;
+
+  // Validate after update
+  if (tag.startFrame > tag.endFrame) {
+    throw new Error(`startFrame (${String(tag.startFrame)}) must be <= endFrame (${String(tag.endFrame)}).`);
+  }
+}
+
+// --- Serialization ---
+
+function serializeTag(tag: FrameTag): SerializedTag {
+  return {
+    id: tag.id,
+    name: tag.name,
+    color: tag.color,
+    startFrame: tag.startFrame,
+    endFrame: tag.endFrame,
+    parentId: tag.parentId,
+    children: tag.children.map(serializeTag),
+  };
+}
+
+function deserializeTag(data: SerializedTag): FrameTag {
+  return {
+    id: data.id,
+    name: data.name,
+    color: data.color,
+    startFrame: data.startFrame,
+    endFrame: data.endFrame,
+    parentId: data.parentId,
+    children: data.children.map(deserializeTag),
+  };
+}
+
+export function serialize(): { tags: SerializedTag[] } {
+  return { tags: tags.map(serializeTag) };
+}
+
+export function deserialize(data: { tags: SerializedTag[] }): void {
+  tags = data.tags.map(deserializeTag);
+}
+
+/**
+ * Reset all tag state. Intended for tests only.
+ */
+export function _resetForTesting(): void {
+  tags = [];
+  colorIndex = 0;
+}