pixelweaver 0.1.0

package/src/lib/color/color-commands.ts

@@ -0,0 +1,87 @@
+/**
+ * Color commands plugin for PixelWeaver.
+ *
+ * Registers undoable commands for color operations:
+ * foreground/background color changes, color swap, and palette lock toggle.
+ */
+
+import type { PluginModule } from '../core/plugin-loader.js';
+import {
+  getForegroundColor,
+  setForegroundColor,
+  getBackgroundColor,
+  setBackgroundColor,
+  swapColors,
+} from './color-state.svelte.js';
+import {
+  isPaletteLocked,
+  setPaletteLocked,
+} from './palette-state.svelte.js';
+
+export const colorCommandsPlugin: PluginModule = {
+  name: 'builtin/colors',
+  version: '1.0.0',
+  description: 'Core color management commands',
+  dependencies: [],
+
+  register(api) {
+    api.addCommand('set_foreground_color', {
+      execute(params) {
+        const hex = params["color"];
+        // Store the previous color for undo (stashed in params by convention)
+        params["_prevColor"] = getForegroundColor();
+        setForegroundColor(hex);
+      },
+      undo(params) {
+        const prev = params["_prevColor"];
+        if (prev) setForegroundColor(prev);
+      },
+      describe(params) {
+        return `Set foreground color to ${String(params["color"])}`;
+      },
+    });
+
+    api.addCommand('set_background_color', {
+      execute(params) {
+        const hex = params["color"];
+        params["_prevColor"] = getBackgroundColor();
+        setBackgroundColor(hex);
+      },
+      undo(params) {
+        const prev = params["_prevColor"];
+        if (prev) setBackgroundColor(prev);
+      },
+      describe(params) {
+        return `Set background color to ${String(params["color"])}`;
+      },
+    });
+
+    api.addCommand('swap_colors', {
+      execute() {
+        swapColors();
+      },
+      undo() {
+        // Swap is its own inverse
+        swapColors();
+      },
+      describe() {
+        return 'Swapped foreground and background colors';
+      },
+    });
+
+    api.addCommand('set_palette_locked', {
+      execute(params) {
+        const locked = params["locked"];
+        params["_prevLocked"] = isPaletteLocked();
+        setPaletteLocked(locked);
+      },
+      undo(params) {
+        const prev = params["_prevLocked"];
+        if (prev !== undefined) setPaletteLocked(prev);
+      },
+      describe(params) {
+        return params["locked"] ? 'Locked palette' : 'Unlocked palette';
+      },
+    });
+  },
+};

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

@@ -0,0 +1,98 @@
+/**
+ * Reactive color state for PixelWeaver.
+ *
+ * Module-level singleton using Svelte 5 $state runes.
+ * Manages foreground/background colors, recent color history,
+ * and the active color space for the picker UI.
+ */
+
+const MAX_RECENT_COLORS = 32;
+
+// --- Reactive state ---
+
+let foregroundColor = $state('#000000');
+let backgroundColor = $state('#FFFFFF');
+let recentColors = $state<string[]>([]);
+let activeColorSpace = $state<'hsv' | 'hsl' | 'rgb' | 'hex'>('hsv');
+
+// --- Public API ---
+
+export function getForegroundColor(): string {
+  return foregroundColor;
+}
+
+export function setForegroundColor(hex: string): void {
+  foregroundColor = hex;
+}
+
+export function getBackgroundColor(): string {
+  return backgroundColor;
+}
+
+export function setBackgroundColor(hex: string): void {
+  backgroundColor = hex;
+}
+
+/** Swap foreground and background colors */
+export function swapColors(): void {
+  const tmp = foregroundColor;
+  foregroundColor = backgroundColor;
+  backgroundColor = tmp;
+}
+
+export function getRecentColors(): string[] {
+  return recentColors;
+}
+
+/**
+ * Add a color to the front of the recent colors list.
+ * Deduplicates (moves to front if already present) and caps at MAX_RECENT_COLORS.
+ */
+export function addRecentColor(hex: string): void {
+  const filtered = recentColors.filter((c) => c !== hex);
+  recentColors = [hex, ...filtered].slice(0, MAX_RECENT_COLORS);
+}
+
+export function getActiveColorSpace(): 'hsv' | 'hsl' | 'rgb' | 'hex' {
+  return activeColorSpace;
+}
+
+export function setActiveColorSpace(space: 'hsv' | 'hsl' | 'rgb' | 'hex'): void {
+  activeColorSpace = space;
+}
+
+// --- Serialization ---
+
+export interface ColorStateData {
+  foregroundColor: string;
+  backgroundColor: string;
+  recentColors: string[];
+}
+
+/** Export color state as a plain JSON-safe object. */
+export function serializeColorState(): ColorStateData {
+  return {
+    foregroundColor: getForegroundColor(),
+    backgroundColor: getBackgroundColor(),
+    recentColors: [...getRecentColors()],
+  };
+}
+
+/** Restore color state from a serialized snapshot. */
+export function deserializeColorState(data: ColorStateData): void {
+  setForegroundColor(data.foregroundColor);
+  setBackgroundColor(data.backgroundColor);
+  // Direct assignment -- no addRecentColor loop because we need to fully
+  // replace the list (not merge with existing) and preserve exact order.
+  recentColors = [...data.recentColors];
+}
+
+/**
+ * Reset all color state to defaults. Intended for tests only.
+ */
+export function _resetForTesting(): void {
+  foregroundColor = '#000000';
+  backgroundColor = '#FFFFFF';
+  recentColors = [];
+  activeColorSpace = 'hsv';
+}

package/src/lib/color/color-state.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  getForegroundColor,
+  setForegroundColor,
+  getBackgroundColor,
+  setBackgroundColor,
+  swapColors,
+  getRecentColors,
+  addRecentColor,
+  getActiveColorSpace,
+  setActiveColorSpace,
+  _resetForTesting,
+} from './color-state.svelte.js';
+
+describe('Color State', () => {
+  beforeEach(() => {
+    _resetForTesting();
+  });
+
+  it('should default foreground to black', () => {
+    expect(getForegroundColor()).toBe('#000000');
+  });
+
+  it('should default background to white', () => {
+    expect(getBackgroundColor()).toBe('#FFFFFF');
+  });
+
+  it('should set foreground color', () => {
+    setForegroundColor('#FF0000');
+    expect(getForegroundColor()).toBe('#FF0000');
+  });
+
+  it('should set background color', () => {
+    setBackgroundColor('#00FF00');
+    expect(getBackgroundColor()).toBe('#00FF00');
+  });
+
+  it('should swap foreground and background colors', () => {
+    setForegroundColor('#FF0000');
+    setBackgroundColor('#0000FF');
+    swapColors();
+    expect(getForegroundColor()).toBe('#0000FF');
+    expect(getBackgroundColor()).toBe('#FF0000');
+  });
+
+  it('should swap colors back to original after two swaps', () => {
+    setForegroundColor('#AABBCC');
+    setBackgroundColor('#112233');
+    swapColors();
+    swapColors();
+    expect(getForegroundColor()).toBe('#AABBCC');
+    expect(getBackgroundColor()).toBe('#112233');
+  });
+
+  it('should start with empty recent colors', () => {
+    expect(getRecentColors()).toEqual([]);
+  });
+
+  it('should add a recent color to the front', () => {
+    addRecentColor('#FF0000');
+    addRecentColor('#00FF00');
+    expect(getRecentColors()[0]).toBe('#00FF00');
+    expect(getRecentColors()[1]).toBe('#FF0000');
+  });
+
+  it('should deduplicate recent colors (move to front)', () => {
+    addRecentColor('#FF0000');
+    addRecentColor('#00FF00');
+    addRecentColor('#FF0000'); // already present, should move to front
+    expect(getRecentColors()).toEqual(['#FF0000', '#00FF00']);
+  });
+
+  it('should cap recent colors at 32', () => {
+    for (let i = 0; i < 40; i++) {
+      const hex = `#${i.toString(16).padStart(6, '0').toUpperCase()}`;
+      addRecentColor(hex);
+    }
+    expect(getRecentColors()).toHaveLength(32);
+    // Most recent should be the last added
+    expect(getRecentColors()[0]).toBe('#000027');
+  });
+
+  it('should default active color space to hsv', () => {
+    expect(getActiveColorSpace()).toBe('hsv');
+  });
+
+  it('should set active color space', () => {
+    setActiveColorSpace('rgb');
+    expect(getActiveColorSpace()).toBe('rgb');
+  });
+});

package/src/lib/color/color-utils.test.ts

@@ -0,0 +1,220 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseColor,
+  hexToRgb,
+  rgbToHex,
+  rgbToHsv,
+  hsvToRgb,
+  rgbToHsl,
+  hslToRgb,
+  lerpColor,
+  nearestPaletteColor,
+  colorDistance,
+} from './color-utils.js';
+
+// --- parseColor ---
+
+describe('parseColor', () => {
+  it('should parse a 6-digit hex string', () => {
+    const c = parseColor('#FF0000');
+    expect(c).toEqual({ r: 255, g: 0, b: 0, a: 1 });
+  });
+
+  it('should parse a 3-digit hex string', () => {
+    const c = parseColor('#F00');
+    expect(c).toEqual({ r: 255, g: 0, b: 0, a: 1 });
+  });
+
+  it('should parse rgb() notation', () => {
+    const c = parseColor('rgb(0, 128, 255)');
+    expect(c).toEqual({ r: 0, g: 128, b: 255, a: 1 });
+  });
+
+  it('should parse named colors', () => {
+    const c = parseColor('red');
+    expect(c).toEqual({ r: 255, g: 0, b: 0, a: 1 });
+  });
+
+  it('should return null for invalid input', () => {
+    expect(parseColor('notacolor')).toBeNull();
+    expect(parseColor('')).toBeNull();
+  });
+});
+
+// --- hexToRgb / rgbToHex roundtrip ---
+
+describe('hexToRgb / rgbToHex', () => {
+  const cases = [
+    { hex: '#FF0000', r: 255, g: 0, b: 0 },
+    { hex: '#00FF00', r: 0, g: 255, b: 0 },
+    { hex: '#0000FF', r: 0, g: 0, b: 255 },
+    { hex: '#000000', r: 0, g: 0, b: 0 },
+    { hex: '#FFFFFF', r: 255, g: 255, b: 255 },
+    { hex: '#808080', r: 128, g: 128, b: 128 },
+  ];
+
+  for (const { hex, r, g, b } of cases) {
+    it(`hexToRgb(${hex}) should return (${String(r)}, ${String(g)}, ${String(b)})`, () => {
+      expect(hexToRgb(hex)).toEqual({ r, g, b });
+    });
+
+    it(`rgbToHex(${String(r)}, ${String(g)}, ${String(b)}) should return ${hex}`, () => {
+      expect(rgbToHex(r, g, b)).toBe(hex);
+    });
+  }
+
+  it('should roundtrip correctly', () => {
+    const original = '#AB12CD';
+    const { r, g, b } = hexToRgb(original);
+    expect(rgbToHex(r, g, b)).toBe(original);
+  });
+});
+
+// --- rgbToHsv / hsvToRgb roundtrip ---
+
+describe('rgbToHsv / hsvToRgb', () => {
+  it('should convert red correctly', () => {
+    const hsv = rgbToHsv(255, 0, 0);
+    expect(hsv).toEqual({ h: 0, s: 100, v: 100 });
+    expect(hsvToRgb(0, 100, 100)).toEqual({ r: 255, g: 0, b: 0 });
+  });
+
+  it('should convert green correctly', () => {
+    const hsv = rgbToHsv(0, 255, 0);
+    expect(hsv).toEqual({ h: 120, s: 100, v: 100 });
+    expect(hsvToRgb(120, 100, 100)).toEqual({ r: 0, g: 255, b: 0 });
+  });
+
+  it('should convert blue correctly', () => {
+    const hsv = rgbToHsv(0, 0, 255);
+    expect(hsv).toEqual({ h: 240, s: 100, v: 100 });
+    expect(hsvToRgb(240, 100, 100)).toEqual({ r: 0, g: 0, b: 255 });
+  });
+
+  it('should convert white correctly', () => {
+    const hsv = rgbToHsv(255, 255, 255);
+    expect(hsv).toEqual({ h: 0, s: 0, v: 100 });
+    expect(hsvToRgb(0, 0, 100)).toEqual({ r: 255, g: 255, b: 255 });
+  });
+
+  it('should convert black correctly', () => {
+    const hsv = rgbToHsv(0, 0, 0);
+    expect(hsv).toEqual({ h: 0, s: 0, v: 0 });
+    expect(hsvToRgb(0, 0, 0)).toEqual({ r: 0, g: 0, b: 0 });
+  });
+
+  it('should roundtrip an arbitrary color within rounding tolerance', () => {
+    const hsv = rgbToHsv(100, 150, 200);
+    const rgb = hsvToRgb(hsv.h, hsv.s, hsv.v);
+    // Double rounding (RGB->HSV integers->RGB integers) can drift by +/-1
+    expect(Math.abs(rgb.r - 100)).toBeLessThanOrEqual(1);
+    expect(Math.abs(rgb.g - 150)).toBeLessThanOrEqual(1);
+    expect(Math.abs(rgb.b - 200)).toBeLessThanOrEqual(1);
+  });
+});
+
+// --- rgbToHsl / hslToRgb roundtrip ---
+
+describe('rgbToHsl / hslToRgb', () => {
+  it('should convert red correctly', () => {
+    const hsl = rgbToHsl(255, 0, 0);
+    expect(hsl).toEqual({ h: 0, s: 100, l: 50 });
+    expect(hslToRgb(0, 100, 50)).toEqual({ r: 255, g: 0, b: 0 });
+  });
+
+  it('should convert white correctly', () => {
+    const hsl = rgbToHsl(255, 255, 255);
+    expect(hsl).toEqual({ h: 0, s: 0, l: 100 });
+  });
+
+  it('should convert black correctly', () => {
+    const hsl = rgbToHsl(0, 0, 0);
+    expect(hsl).toEqual({ h: 0, s: 0, l: 0 });
+  });
+
+  it('should roundtrip an arbitrary color within rounding tolerance', () => {
+    const hsl = rgbToHsl(100, 150, 200);
+    const rgb = hslToRgb(hsl.h, hsl.s, hsl.l);
+    // Double rounding (RGB->HSL integers->RGB integers) can drift by +/-1
+    expect(Math.abs(rgb.r - 100)).toBeLessThanOrEqual(1);
+    expect(Math.abs(rgb.g - 150)).toBeLessThanOrEqual(1);
+    expect(Math.abs(rgb.b - 200)).toBeLessThanOrEqual(1);
+  });
+});
+
+// --- lerpColor ---
+
+describe('lerpColor', () => {
+  it('should return color1 at t=0', () => {
+    expect(lerpColor('#FF0000', '#0000FF', 0)).toBe('#FF0000');
+  });
+
+  it('should return color2 at t=1', () => {
+    expect(lerpColor('#FF0000', '#0000FF', 1)).toBe('#0000FF');
+  });
+
+  it('should return a midpoint at t=0.5', () => {
+    const mid = lerpColor('#FF0000', '#0000FF', 0.5);
+    // The midpoint in OKLab space is roughly a purple/violet; just check it parses
+    expect(mid).toMatch(/^#[0-9A-F]{6}$/);
+    // It should not be either endpoint
+    expect(mid).not.toBe('#FF0000');
+    expect(mid).not.toBe('#0000FF');
+  });
+
+  it('should return the same color when lerping between identical colors', () => {
+    expect(lerpColor('#AABBCC', '#AABBCC', 0.5)).toBe('#AABBCC');
+  });
+});
+
+// --- nearestPaletteColor ---
+
+describe('nearestPaletteColor', () => {
+  const palette = ['#FF0000', '#00FF00', '#0000FF', '#FFFFFF', '#000000'];
+
+  it('should return an exact match', () => {
+    expect(nearestPaletteColor('#FF0000', palette)).toBe('#FF0000');
+  });
+
+  it('should find the closest color', () => {
+    // A dark red should be closer to red than to green or blue
+    expect(nearestPaletteColor('#CC1111', palette)).toBe('#FF0000');
+  });
+
+  it('should return white for a very light color', () => {
+    expect(nearestPaletteColor('#FAFAFA', palette)).toBe('#FFFFFF');
+  });
+
+  it('should return the input when palette is empty', () => {
+    expect(nearestPaletteColor('#123456', [])).toBe('#123456');
+  });
+});
+
+// --- colorDistance ---
+
+describe('colorDistance', () => {
+  it('should return 0 for identical colors', () => {
+    expect(colorDistance('#FF0000', '#FF0000')).toBe(0);
+  });
+
+  it('should return 0 for the same color expressed differently', () => {
+    // Both parse to the same RGB
+    expect(colorDistance('#000000', '#000000')).toBe(0);
+  });
+
+  it('should return a high distance for very different colors', () => {
+    const dist = colorDistance('#000000', '#FFFFFF');
+    expect(dist).toBeGreaterThan(0.5);
+  });
+
+  it('should return a small distance for similar colors', () => {
+    const dist = colorDistance('#FF0000', '#EE1111');
+    expect(dist).toBeLessThan(0.15);
+  });
+
+  it('should be symmetric', () => {
+    const ab = colorDistance('#FF0000', '#0000FF');
+    const ba = colorDistance('#0000FF', '#FF0000');
+    expect(ab).toBeCloseTo(ba, 10);
+  });
+});