pixelweaver 0.1.0

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

@@ -0,0 +1,243 @@
+/**
+ * Color conversion utilities for PixelWeaver.
+ *
+ * Thin wrappers around `culori` that normalize to PixelWeaver's conventions:
+ *   - RGB values: 0-255 integers
+ *   - HSV/HSL: H 0-360, S 0-100, V/L 0-100
+ *   - Hex: uppercase 6-digit "#RRGGBB"
+ *   - Perceptual operations use OKLab color space
+ */
+
+import {
+  parse,
+  formatHex,
+  formatHex8,
+  interpolate as culoriInterpolate,
+  differenceEuclidean,
+  converter,
+  type Rgb,
+} from 'culori';
+
+const toRgb = converter('rgb');
+const toHsv = converter('hsv');
+const toHsl = converter('hsl');
+// Pre-built OKLab distance function (reused across calls)
+const oklabDistance = differenceEuclidean('oklab');
+
+// --- Types ---
+
+export interface RgbColor {
+  r: number;
+  g: number;
+  b: number;
+}
+
+export interface RgbaColor extends RgbColor {
+  a: number;
+}
+
+export interface HsvColor {
+  h: number;
+  s: number;
+  v: number;
+}
+
+export interface HslColor {
+  h: number;
+  s: number;
+  l: number;
+}
+
+// --- Helpers ---
+
+/** Clamp a value to [min, max] and round to integer */
+function clampRound(value: number, min: number, max: number): number {
+  return Math.round(Math.min(max, Math.max(min, value)));
+}
+
+// --- Public API ---
+
+/**
+ * Parse any CSS color string to an RGBA object.
+ * Returns null if the input cannot be parsed.
+ */
+export function parseColor(input: string): RgbaColor | null {
+  const parsed = parse(input);
+  if (!parsed) return null;
+
+  // After the parsed check, toRgb returns a non-null Rgb (culori's
+  // converter is only nullable when its input may be undefined).
+  const rgb = toRgb(parsed) as Rgb & { alpha?: number };
+
+  return {
+    r: clampRound(rgb.r * 255, 0, 255),
+    g: clampRound(rgb.g * 255, 0, 255),
+    b: clampRound(rgb.b * 255, 0, 255),
+    a: rgb.alpha !== undefined ? rgb.alpha : 1,
+  };
+}
+
+/**
+ * Convert a hex color string to RGB (0-255).
+ * Assumes valid 6-digit hex input (e.g. "#FF0000").
+ */
+export function hexToRgb(hex: string): RgbColor {
+  const parsed = parse(hex);
+  if (!parsed) throw new Error(`Invalid hex color: ${hex}`);
+
+  const rgb = toRgb(parsed);
+  return {
+    r: clampRound(rgb.r * 255, 0, 255),
+    g: clampRound(rgb.g * 255, 0, 255),
+    b: clampRound(rgb.b * 255, 0, 255),
+  };
+}
+
+/**
+ * Convert RGB (0-255) to uppercase 6-digit hex.
+ */
+export function rgbToHex(r: number, g: number, b: number): string {
+  const hex = formatHex({ mode: 'rgb', r: r / 255, g: g / 255, b: b / 255 });
+  return hex.toUpperCase();
+}
+
+/**
+ * Convert RGBA (0-255) to uppercase 8-digit hex "#RRGGBBAA".
+ */
+export function rgbaToHex(r: number, g: number, b: number, a: number): string {
+  const hex = formatHex8({
+    mode: 'rgb',
+    r: r / 255,
+    g: g / 255,
+    b: b / 255,
+    alpha: a / 255,
+  });
+  return hex.toUpperCase();
+}
+
+/**
+ * Convert a hex color string to RGBA (0-255).
+ * Accepts 3-digit, 6-digit, and 8-digit hex inputs (with or without alpha).
+ * When the input carries no alpha channel, defaults to `a: 255`.
+ */
+export function hexToRgba(hex: string): RgbaColor {
+  const parsed = parse(hex);
+  if (!parsed) throw new Error(`Invalid hex color: ${hex}`);
+
+  const rgb = toRgb(parsed) as Rgb & { alpha?: number };
+  return {
+    r: clampRound(rgb.r * 255, 0, 255),
+    g: clampRound(rgb.g * 255, 0, 255),
+    b: clampRound(rgb.b * 255, 0, 255),
+    // culori omits `alpha` when the source had no alpha channel; default to 255
+    a: rgb.alpha !== undefined ? clampRound(rgb.alpha * 255, 0, 255) : 255,
+  };
+}
+
+/**
+ * Convert RGB (0-255) to HSV (H: 0-360, S: 0-100, V: 0-100).
+ */
+export function rgbToHsv(r: number, g: number, b: number): HsvColor {
+  const hsv = toHsv({ mode: 'rgb', r: r / 255, g: g / 255, b: b / 255 });
+  return {
+    // culori omits h for achromatic colors; default to 0
+    h: clampRound(hsv.h ?? 0, 0, 360),
+    s: clampRound(hsv.s * 100, 0, 100),
+    v: clampRound(hsv.v * 100, 0, 100),
+  };
+}
+
+/**
+ * Convert HSV (H: 0-360, S: 0-100, V: 0-100) to RGB (0-255).
+ */
+export function hsvToRgb(h: number, s: number, v: number): RgbColor {
+  const rgb = toRgb({ mode: 'hsv', h, s: s / 100, v: v / 100 });
+  return {
+    r: clampRound(rgb.r * 255, 0, 255),
+    g: clampRound(rgb.g * 255, 0, 255),
+    b: clampRound(rgb.b * 255, 0, 255),
+  };
+}
+
+/**
+ * Convert RGB (0-255) to HSL (H: 0-360, S: 0-100, L: 0-100).
+ */
+export function rgbToHsl(r: number, g: number, b: number): HslColor {
+  const hsl = toHsl({ mode: 'rgb', r: r / 255, g: g / 255, b: b / 255 });
+  return {
+    // culori omits h for achromatic colors; default to 0
+    h: clampRound(hsl.h ?? 0, 0, 360),
+    s: clampRound(hsl.s * 100, 0, 100),
+    l: clampRound(hsl.l * 100, 0, 100),
+  };
+}
+
+/**
+ * Convert HSL (H: 0-360, S: 0-100, L: 0-100) to RGB (0-255).
+ */
+export function hslToRgb(h: number, s: number, l: number): RgbColor {
+  const rgb = toRgb({ mode: 'hsl', h, s: s / 100, l: l / 100 });
+  return {
+    r: clampRound(rgb.r * 255, 0, 255),
+    g: clampRound(rgb.g * 255, 0, 255),
+    b: clampRound(rgb.b * 255, 0, 255),
+  };
+}
+
+/**
+ * Interpolate between two hex colors in OKLab space.
+ * t=0 returns color1, t=1 returns color2.
+ * Returns uppercase 6-digit hex.
+ */
+export function lerpColor(color1: string, color2: string, t: number): string {
+  const interp = culoriInterpolate([color1, color2], 'oklab');
+  const result = formatHex(interp(t));
+  return result.toUpperCase();
+}
+
+/**
+ * Find the nearest color in a palette to the given hex color.
+ * Uses Euclidean distance in OKLab space for perceptual accuracy.
+ * Returns the closest palette color (or the input if palette is empty).
+ */
+export function nearestPaletteColor(hex: string, palette: string[]): string {
+  if (palette.length === 0) return hex;
+
+  const target = parse(hex);
+  if (!target) return hex;
+
+  // Safe: palette.length === 0 is checked above
+  const first = palette[0];
+  if (first === undefined) return hex;
+  let bestColor = first;
+  let bestDist = Infinity;
+
+  for (const candidate of palette) {
+    const parsed = parse(candidate);
+    if (!parsed) continue;
+
+    const dist = oklabDistance(target, parsed);
+    if (dist < bestDist) {
+      bestDist = dist;
+      bestColor = candidate;
+    }
+  }
+
+  return bestColor;
+}
+
+/**
+ * Compute perceptual color distance between two hex colors.
+ * Uses Euclidean distance in OKLab space, normalized to 0-1 range.
+ * Same color returns 0; maximally different colors approach 1.
+ */
+export function colorDistance(hex1: string, hex2: string): number {
+  const c1 = parse(hex1);
+  const c2 = parse(hex2);
+  if (!c1 || !c2) return 1;
+
+  const raw = oklabDistance(c1, c2);
+  // OKLab Euclidean distance for maximally different colors (black vs white)
+  // is roughly ~1.0. We clamp to [0,1] for a clean API.
+  return Math.min(1, raw);
+}

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

@@ -0,0 +1,127 @@
+/**
+ * Reactive palette state for PixelWeaver.
+ *
+ * Module-level singleton using Svelte 5 $state runes.
+ * Manages project/global palettes, palette lock mode,
+ * and auto-collected colors from the canvas.
+ */
+
+import type { Palette } from './palette.js';
+import { BUILTIN_PALETTES } from './palette.js';
+import { nearestPaletteColor } from './color-utils.js';
+
+// --- Reactive state ---
+
+let projectPalette = $state<Palette | null>(null);
+
+// Global palettes start with built-in presets; user can add more
+let globalPalettes = $state<Palette[]>([...BUILTIN_PALETTES]);
+
+let paletteLocked = $state(false);
+
+// The palette used for locking (project palette or a selected global palette)
+let activePalette = $state<Palette | null>(null);
+
+// All unique colors found in the current project (auto-updated by drawing tools)
+let autoCollectedColors = $state<string[]>([]);
+
+// --- Public API ---
+
+export function getProjectPalette(): Palette | null {
+  return projectPalette;
+}
+
+export function setProjectPalette(palette: Palette | null): void {
+  projectPalette = palette;
+}
+
+export function getGlobalPalettes(): Palette[] {
+  return globalPalettes;
+}
+
+export function addGlobalPalette(palette: Palette): void {
+  globalPalettes = [...globalPalettes, palette];
+}
+
+export function removeGlobalPalette(name: string): void {
+  globalPalettes = globalPalettes.filter((p) => p.name !== name);
+}
+
+export function isPaletteLocked(): boolean {
+  return paletteLocked;
+}
+
+export function setPaletteLocked(locked: boolean): void {
+  paletteLocked = locked;
+}
+
+export function getActivePalette(): Palette | null {
+  return activePalette;
+}
+
+export function setActivePalette(palette: Palette | null): void {
+  activePalette = palette;
+}
+
+export function getAutoCollectedColors(): string[] {
+  return autoCollectedColors;
+}
+
+/**
+ * Register a color as used on the canvas.
+ * Deduplicates automatically.
+ */
+export function addAutoCollectedColor(hex: string): void {
+  if (!autoCollectedColors.includes(hex)) {
+    autoCollectedColors = [...autoCollectedColors, hex];
+  }
+}
+
+/**
+ * Snap a color to the nearest color in the active palette.
+ * Returns the input unchanged if palette lock is off or no active palette is set.
+ */
+export function snapToActivePalette(hex: string): string {
+  if (!paletteLocked || !activePalette || activePalette.colors.length === 0) {
+    return hex;
+  }
+  return nearestPaletteColor(hex, activePalette.colors);
+}
+
+// --- Serialization ---
+
+/** Serialized shape of project-level palette state. */
+export interface PaletteStateSnapshot {
+  projectPalette: Palette | null;
+  paletteLocked: boolean;
+}
+
+/** Export project-level palette state as a plain JSON-safe object. */
+export function serialize(): PaletteStateSnapshot {
+  const pp = getProjectPalette();
+  return {
+    projectPalette: pp ? { name: pp.name, colors: [...pp.colors] } : null,
+    paletteLocked: isPaletteLocked(),
+  };
+}
+
+/** Restore project-level palette state from a serialized snapshot. */
+export function deserialize(data: PaletteStateSnapshot): void {
+  setProjectPalette(
+    data.projectPalette
+      ? { name: data.projectPalette.name, colors: [...data.projectPalette.colors] }
+      : null,
+  );
+  setPaletteLocked(data.paletteLocked);
+}
+
+/**
+ * Reset all palette state to defaults. Intended for tests only.
+ */
+export function _resetForTesting(): void {
+  projectPalette = null;
+  globalPalettes = [...BUILTIN_PALETTES];
+  paletteLocked = false;
+  activePalette = null;
+  autoCollectedColors = [];
+}

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

@@ -0,0 +1,154 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  getProjectPalette,
+  setProjectPalette,
+  getGlobalPalettes,
+  addGlobalPalette,
+  removeGlobalPalette,
+  isPaletteLocked,
+  setPaletteLocked,
+  getActivePalette,
+  setActivePalette,
+  getAutoCollectedColors,
+  addAutoCollectedColor,
+  snapToActivePalette,
+  _resetForTesting,
+} from './palette-state.svelte.js';
+import { BUILTIN_PALETTES } from './palette.js';
+import type { Palette } from './palette.js';
+
+describe('Palette State', () => {
+  beforeEach(() => {
+    _resetForTesting();
+  });
+
+  // --- Built-in palettes ---
+
+  it('should include built-in palettes in global palettes', () => {
+    const globals = getGlobalPalettes();
+    for (const builtin of BUILTIN_PALETTES) {
+      const found = globals.find((p) => p.name === builtin.name);
+      expect(found).toBeDefined();
+      expect(found?.readonly).toBe(true);
+    }
+  });
+
+  it('built-in palettes should have valid hex colors', () => {
+    for (const palette of BUILTIN_PALETTES) {
+      for (const color of palette.colors) {
+        expect(color).toMatch(/^#[0-9A-F]{6}$/);
+      }
+    }
+  });
+
+  // --- Project palette ---
+
+  it('should default project palette to null', () => {
+    expect(getProjectPalette()).toBeNull();
+  });
+
+  it('should set and get project palette', () => {
+    const pal: Palette = { name: 'Test', colors: ['#FF0000'] };
+    setProjectPalette(pal);
+    expect(getProjectPalette()).toStrictEqual(pal);
+  });
+
+  // --- Global palette management ---
+
+  it('should add a global palette', () => {
+    const before = getGlobalPalettes().length;
+    addGlobalPalette({ name: 'Custom', colors: ['#123456'] });
+    expect(getGlobalPalettes()).toHaveLength(before + 1);
+    expect(getGlobalPalettes().find((p) => p.name === 'Custom')).toBeDefined();
+  });
+
+  it('should remove a global palette by name', () => {
+    addGlobalPalette({ name: 'ToRemove', colors: ['#000000'] });
+    removeGlobalPalette('ToRemove');
+    expect(getGlobalPalettes().find((p) => p.name === 'ToRemove')).toBeUndefined();
+  });
+
+  // --- Palette lock ---
+
+  it('should default palette lock to false', () => {
+    expect(isPaletteLocked()).toBe(false);
+  });
+
+  it('should toggle palette lock', () => {
+    setPaletteLocked(true);
+    expect(isPaletteLocked()).toBe(true);
+    setPaletteLocked(false);
+    expect(isPaletteLocked()).toBe(false);
+  });
+
+  // --- Active palette ---
+
+  it('should default active palette to null', () => {
+    expect(getActivePalette()).toBeNull();
+  });
+
+  it('should set active palette', () => {
+    const pal: Palette = { name: 'Active', colors: ['#FF0000', '#00FF00'] };
+    setActivePalette(pal);
+    expect(getActivePalette()).toStrictEqual(pal);
+  });
+
+  // --- snapToActivePalette ---
+
+  it('should return input unchanged when palette is not locked', () => {
+    setActivePalette({ name: 'Test', colors: ['#FF0000'] });
+    setPaletteLocked(false);
+    expect(snapToActivePalette('#00FF00')).toBe('#00FF00');
+  });
+
+  it('should return input unchanged when no active palette is set', () => {
+    setPaletteLocked(true);
+    setActivePalette(null);
+    expect(snapToActivePalette('#00FF00')).toBe('#00FF00');
+  });
+
+  it('should snap to nearest palette color when locked', () => {
+    const palette: Palette = {
+      name: 'RGB',
+      colors: ['#FF0000', '#00FF00', '#0000FF'],
+    };
+    setActivePalette(palette);
+    setPaletteLocked(true);
+
+    // A dark red should snap to red
+    expect(snapToActivePalette('#CC1111')).toBe('#FF0000');
+    // A dark green should snap to green
+    expect(snapToActivePalette('#11CC11')).toBe('#00FF00');
+    // A dark blue should snap to blue
+    expect(snapToActivePalette('#1111CC')).toBe('#0000FF');
+  });
+
+  it('should snap exact palette color to itself', () => {
+    const palette: Palette = {
+      name: 'Test',
+      colors: ['#FF0000', '#00FF00'],
+    };
+    setActivePalette(palette);
+    setPaletteLocked(true);
+
+    expect(snapToActivePalette('#FF0000')).toBe('#FF0000');
+  });
+
+  // --- Auto-collected colors ---
+
+  it('should start with empty auto-collected colors', () => {
+    expect(getAutoCollectedColors()).toEqual([]);
+  });
+
+  it('should add auto-collected colors', () => {
+    addAutoCollectedColor('#FF0000');
+    addAutoCollectedColor('#00FF00');
+    expect(getAutoCollectedColors()).toEqual(['#FF0000', '#00FF00']);
+  });
+
+  it('should deduplicate auto-collected colors', () => {
+    addAutoCollectedColor('#FF0000');
+    addAutoCollectedColor('#FF0000');
+    expect(getAutoCollectedColors()).toEqual(['#FF0000']);
+  });
+});

package/src/lib/color/palette.ts

@@ -0,0 +1,79 @@
+/**
+ * Palette definitions and built-in presets for PixelWeaver.
+ *
+ * All colors are uppercase 6-digit hex strings (#RRGGBB).
+ */
+
+export interface Palette {
+  name: string;
+  colors: string[];
+  readonly?: boolean;
+}
+
+/**
+ * Built-in palette presets. These are marked readonly so users
+ * cannot accidentally modify them (they can duplicate and edit copies).
+ */
+export const BUILTIN_PALETTES: Palette[] = [
+  {
+    name: 'PICO-8',
+    colors: [
+      '#000000', '#1D2B53', '#7E2553', '#008751',
+      '#AB5236', '#5F574F', '#C2C3C7', '#FFF1E8',
+      '#FF004D', '#FFA300', '#FFEC27', '#00E436',
+      '#29ADFF', '#83769C', '#FF77A8', '#FFCCAA',
+    ],
+    readonly: true,
+  },
+  {
+    name: 'GameBoy',
+    colors: ['#0F380F', '#306230', '#8BAC0F', '#9BBC0F'],
+    readonly: true,
+  },
+  {
+    name: 'NES',
+    colors: [
+      '#666666', '#002A88', '#1412A7', '#3B00A4',
+      '#5C007E', '#6E0040', '#6C0600', '#561D00',
+      '#333500', '#0B4800', '#005200', '#004F08',
+      '#00404D', '#000000', '#000000', '#000000',
+      '#ADADAD', '#155FD9', '#4240FF', '#7527FE',
+      '#A01ACC', '#B71E7B', '#B53120', '#994E00',
+      '#6B6D00', '#388700', '#0C9300', '#008F32',
+      '#007C8D', '#000000', '#000000', '#000000',
+      '#FFFEFF', '#64B0FF', '#9290FF', '#C676FF',
+      '#F36AFF', '#FE6ECC', '#FE8170', '#EA9E22',
+      '#BCBE00', '#88D800', '#5CE430', '#45E082',
+      '#48CDDE', '#4F4F4F', '#000000', '#000000',
+      '#FFFEFF', '#C0DFFF', '#D3D2FF', '#E8C8FF',
+      '#FBC2FF', '#FEC4EA', '#FECCC5', '#F7D8A5',
+      '#E4E594', '#CFEF96', '#BDF4AB', '#B3F3CC',
+      '#B5EBF2', '#B8B8B8', '#000000', '#000000',
+    ],
+    readonly: true,
+  },
+  {
+    name: 'Sweetie 16',
+    colors: [
+      '#1A1C2C', '#5D275D', '#B13E53', '#EF7D57',
+      '#FFCD75', '#A7F070', '#38B764', '#257179',
+      '#29366F', '#3B5DC9', '#41A6F6', '#73EFF7',
+      '#F4F4F4', '#94B0C2', '#566C86', '#333C57',
+    ],
+    readonly: true,
+  },
+  {
+    name: 'Endesga 32',
+    colors: [
+      '#BE4A2F', '#D77643', '#EAD4AA', '#E4A672',
+      '#B86F50', '#733E39', '#3E2731', '#A22633',
+      '#E43B44', '#F77622', '#FEAE34', '#FEE761',
+      '#63C74D', '#3E8948', '#265C42', '#193C3E',
+      '#124E89', '#0099DB', '#2CE8F5', '#FFFFFF',
+      '#C0CBDC', '#8B9BB4', '#5A6988', '#3A4466',
+      '#262B44', '#181425', '#FF0044', '#68386C',
+      '#B55088', '#F6757A', '#E8B796', '#C28569',
+    ],
+    readonly: true,
+  },
+];

package/src/lib/core/bootstrap.ts

@@ -0,0 +1,66 @@
+/**
+ * Bootstrap -- discovers all plugin modules via Vite's import.meta.glob
+ * and loads them through the plugin loader in dependency order.
+ *
+ * Must run synchronously before Svelte mounts so that tools, commands,
+ * shortcuts, and panels are available on first render.
+ */
+
+import { loadPlugins } from './plugin-loader.js';
+import type { PluginModule } from './plugin-loader.js';
+
+// Discover all plugin modules via Vite's import.meta.glob.
+// Patterns target three categories:
+//   1. Builtin tools and effects in plugins/builtin/
+//   2. System/UI plugins matching *-plugin.ts in src/lib/
+//   3. Command plugins matching *-commands.ts in src/lib/
+const pluginModules = import.meta.glob(
+  [
+    '/plugins/builtin/**/*.ts',
+    '!/plugins/builtin/**/*.test.ts',
+    '/src/lib/**/*-plugin.ts',
+    '/src/lib/**/*-commands.ts',
+  ],
+  { eager: true }
+);
+
+// Type guard: checks if a value has the shape of a PluginModule
+function isPluginModule(value: unknown): value is PluginModule {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'name' in value &&
+    typeof (value as Record<string, unknown>)["name"] === 'string' &&
+    'version' in value &&
+    typeof (value as Record<string, unknown>)["version"] === 'string' &&
+    'register' in value &&
+    typeof (value as Record<string, unknown>)["register"] === 'function'
+  );
+}
+
+// Extract PluginModule exports from all discovered modules.
+// The type guard filters out non-plugin modules (like drawing-utils.ts)
+// that match the glob patterns but don't export a PluginModule. The seen
+// set prevents duplicate registration if a plugin somehow appears in
+// multiple glob patterns.
+function discoverPlugins(): PluginModule[] {
+  const plugins: PluginModule[] = [];
+  const seen = new Set<string>();
+
+  for (const mod of Object.values(pluginModules)) {
+    const exports = mod as Record<string, unknown>;
+    for (const value of Object.values(exports)) {
+      if (isPluginModule(value) && !seen.has(value.name)) {
+        plugins.push(value);
+        seen.add(value.name);
+      }
+    }
+  }
+
+  return plugins;
+}
+
+export function bootstrap(): void {
+  const plugins = discoverPlugins();
+  loadPlugins(plugins);
+}