pixelweaver 0.1.0

package/src/lib/variants/bisection-export.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'vitest';
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import { exportGroupSpritesheet, exportVariantAtlas } from './bisection-export.js';
+import type { Layer } from '../layers/layer-types.js';
+import type { Frame } from '../animation/frame-model.svelte.js';
+import type { VariantPreset } from './variant-state.svelte.js';
+
+/** Build a simple test group with one pixel layer. */
+function makeTestScene() {
+  const layer1: Layer = { id: 'l1', name: 'Body', type: 'pixel', visible: true, opacity: 100, blendMode: 'normal', locked: false };
+  const layer2: Layer = { id: 'l2', name: 'Outside', type: 'pixel', visible: true, opacity: 100, blendMode: 'normal', locked: false };
+  const group: Layer = {
+    id: 'g1', name: 'Character', type: 'group', visible: true, opacity: 100, blendMode: 'normal', locked: false,
+    children: [layer1], expanded: true,
+  };
+
+  // l1 has a red pixel; l2 (outside group) has a green pixel
+  const buf1 = new PixelBuffer(4, 4);
+  buf1.setPixel(1, 1, 255, 0, 0, 255);
+
+  const buf2 = new PixelBuffer(4, 4);
+  buf2.setPixel(2, 2, 0, 255, 0, 255);
+
+  const frame: Frame = {
+    id: 'f1', index: 0, durationMs: null,
+    pixelData: new Map([['l1', buf1], ['l2', buf2]]),
+  };
+
+  return { group, layer2, frame, layerTree: [layer2, group] };
+}
+
+describe('exportGroupSpritesheet', () => {
+  it('should only include pixels from the group\'s layers', () => {
+    const { frame, layerTree } = makeTestScene();
+    const frames = exportGroupSpritesheet('g1', layerTree, [frame], 4, 4);
+
+    expect(frames).toHaveLength(1);
+    const buf = frames[0];
+    if (!buf) throw new Error("missing buffer");
+    // Red pixel from l1 (inside group) should be present
+    expect(buf.getPixel(1, 1)).toEqual([255, 0, 0, 255]);
+    // Green pixel from l2 (outside group) should NOT be present
+    expect(buf.getPixel(2, 2)).toEqual([0, 0, 0, 0]);
+  });
+
+  it('should leave non-group pixels transparent', () => {
+    const { frame, layerTree } = makeTestScene();
+    const frames = exportGroupSpritesheet('g1', layerTree, [frame], 4, 4);
+    const buf = frames[0];
+    if (!buf) throw new Error("missing buffer");
+
+    // Most pixels should be transparent
+    expect(buf.getPixel(0, 0)).toEqual([0, 0, 0, 0]);
+    expect(buf.getPixel(3, 3)).toEqual([0, 0, 0, 0]);
+  });
+
+  it('should apply variant during export', () => {
+    const { frame, layerTree } = makeTestScene();
+    const variant: VariantPreset = {
+      id: 'v1', name: 'Blue',
+      groupOverrides: new Map([
+        ['g1', new Map([['#FF0000', '#0000FF']])], // red -> blue
+      ]),
+    };
+
+    const frames = exportGroupSpritesheet('g1', layerTree, [frame], 4, 4, { variant });
+    const buf = frames[0];
+    if (!buf) throw new Error("missing buffer");
+    // Red pixel should now be blue
+    expect(buf.getPixel(1, 1)).toEqual([0, 0, 255, 255]);
+  });
+
+  it('should throw for non-existent group', () => {
+    expect(() => exportGroupSpritesheet('bad', [], [], 4, 4)).toThrow();
+  });
+});
+
+describe('exportVariantAtlas', () => {
+  it('should create atlas with correct dimensions (rows=variants, cols=frames)', () => {
+    const layer: Layer = { id: 'l1', name: 'L1', type: 'pixel', visible: true, opacity: 100, blendMode: 'normal', locked: false };
+    const group: Layer = {
+      id: 'g1', name: 'Group', type: 'group', visible: true, opacity: 100, blendMode: 'normal', locked: false,
+      children: [layer], expanded: true,
+    };
+
+    const buf = new PixelBuffer(4, 4);
+    buf.setPixel(0, 0, 255, 0, 0, 255);
+
+    const frame1: Frame = { id: 'f1', index: 0, durationMs: null, pixelData: new Map([['l1', buf]]) };
+    const frame2: Frame = { id: 'f2', index: 1, durationMs: null, pixelData: new Map([['l1', buf.clone()]]) };
+
+    const v1: VariantPreset = { id: 'v1', name: 'Original', groupOverrides: new Map() };
+    const v2: VariantPreset = {
+      id: 'v2', name: 'Blue',
+      groupOverrides: new Map([['g1', new Map([['#FF0000', '#0000FF']])]]),
+    };
+
+    const atlas = exportVariantAtlas('g1', [group], [frame1, frame2], [v1, v2], 4, 4);
+    // 2 frames x 4px = 8 wide, 2 variants x 4px = 8 tall
+    expect(atlas.width).toBe(8);
+    expect(atlas.height).toBe(8);
+
+    // Row 0 (v1/Original): frame 1 at (0,0), red pixel at (0,0)
+    expect(atlas.getPixel(0, 0)).toEqual([255, 0, 0, 255]);
+    // Row 0, frame 2 at (4,0), red pixel at (4,0)
+    expect(atlas.getPixel(4, 0)).toEqual([255, 0, 0, 255]);
+
+    // Row 1 (v2/Blue): frame 1 at (0,4), should be blue
+    expect(atlas.getPixel(0, 4)).toEqual([0, 0, 255, 255]);
+    // Row 1, frame 2 at (4,4), should be blue
+    expect(atlas.getPixel(4, 4)).toEqual([0, 0, 255, 255]);
+  });
+});

package/src/lib/variants/bisection-export.ts

@@ -0,0 +1,148 @@
+/**
+ * Bisection Export -- exports individual layer groups as spritesheets or variant atlases.
+ *
+ * "Bisection" refers to isolating a group from the rest of the layer tree,
+ * exporting only its pixels on a transparent background.
+ */
+
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import { composite } from '../layers/compositor.js';
+import type { Layer } from '../layers/layer-types.js';
+import type { Frame } from '../animation/frame-model.svelte.js';
+import { applyPaletteSwap } from './palette-swap.js';
+import type { VariantPreset } from './variant-state.svelte.js';
+
+/**
+ * Find a layer by ID in the tree (depth-first search).
+ */
+function findLayer(id: string, tree: Layer[]): Layer | undefined {
+  for (const layer of tree) {
+    if (layer.id === id) return layer;
+    if (layer.type === 'group' && layer.children) {
+      const found = findLayer(id, layer.children);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Recursively collect IDs of all pixel layers within a layer.
+ */
+function collectPixelLayerIds(layer: Layer): string[] {
+  if (layer.type === 'pixel') return [layer.id];
+  if (layer.children) {
+    return layer.children.flatMap(collectPixelLayerIds);
+  }
+  return [];
+}
+
+/**
+ * Build a minimal layer tree containing only the target group,
+ * preserving its internal structure for correct compositing.
+ */
+function isolateGroupTree(group: Layer): Layer[] {
+  return [group];
+}
+
+/**
+ * Composite a group's layers for a single frame, optionally applying a variant.
+ */
+function compositeGroupFrame(
+  group: Layer,
+  frame: Frame,
+  width: number,
+  height: number,
+  variant?: VariantPreset,
+): PixelBuffer {
+  const pixelLayerIds = collectPixelLayerIds(group);
+  const colorMap = variant?.groupOverrides.get(group.id);
+
+  // Build pixel data map containing only this group's layers
+  const pixelData = new Map<string, PixelBuffer>();
+  for (const layerId of pixelLayerIds) {
+    const buffer = frame.pixelData.get(layerId);
+    if (!buffer) continue;
+    if (colorMap && colorMap.size > 0) {
+      pixelData.set(layerId, applyPaletteSwap(buffer, colorMap));
+    } else {
+      pixelData.set(layerId, buffer);
+    }
+  }
+
+  // Composite using the group's own layer tree (preserves blend modes and opacity)
+  return composite(isolateGroupTree(group), pixelData, width, height);
+}
+
+/**
+ * Export a layer group as a separate spritesheet.
+ * Only includes pixels from layers within the group, on transparent background.
+ *
+ * @param groupId - ID of the group layer to export
+ * @param layerTree - the full layer tree
+ * @param frames - all animation frames
+ * @param width - canvas width in pixels
+ * @param height - canvas height in pixels
+ * @param options - optionally apply a variant preset
+ * @returns one PixelBuffer per frame
+ */
+export function exportGroupSpritesheet(
+  groupId: string,
+  layerTree: Layer[],
+  frames: Frame[],
+  width: number,
+  height: number,
+  options?: { variant?: VariantPreset },
+): PixelBuffer[] {
+  const group = findLayer(groupId, layerTree);
+  if (!group || group.type !== 'group') {
+    throw new Error(`Group "${groupId}" not found or is not a group.`);
+  }
+
+  return frames.map((frame) =>
+    compositeGroupFrame(group, frame, width, height, options?.variant),
+  );
+}
+
+/**
+ * Export all variants of a group as a variant atlas.
+ * Layout: rows = variants, columns = frames.
+ *
+ * @param groupId - ID of the group layer
+ * @param layerTree - the full layer tree
+ * @param frames - all animation frames
+ * @param variants - array of variant presets to render
+ * @param width - per-frame width in pixels
+ * @param height - per-frame height in pixels
+ * @returns a single PixelBuffer atlas image
+ */
+export function exportVariantAtlas(
+  groupId: string,
+  layerTree: Layer[],
+  frames: Frame[],
+  variants: VariantPreset[],
+  width: number,
+  height: number,
+): PixelBuffer {
+  const group = findLayer(groupId, layerTree);
+  if (!group || group.type !== 'group') {
+    throw new Error(`Group "${groupId}" not found or is not a group.`);
+  }
+
+  const atlasWidth = frames.length * width;
+  const atlasHeight = variants.length * height;
+  const atlas = new PixelBuffer(atlasWidth, atlasHeight);
+
+  for (let row = 0; row < variants.length; row++) {
+    const variant = variants[row];
+    if (!variant) continue;
+    for (let col = 0; col < frames.length; col++) {
+      const frame = frames[col];
+      if (!frame) continue;
+      const frameBuffer = compositeGroupFrame(group, frame, width, height, variant);
+      atlas.paste(frameBuffer, col * width, row * height);
+    }
+  }
+
+  return atlas;
+}

package/src/lib/variants/palette-extraction.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import { extractBufferPalette, extractGroupPalette } from './palette-extraction.js';
+import type { Layer } from '../layers/layer-types.js';
+import type { Frame } from '../animation/frame-model.svelte.js';
+
+describe('extractBufferPalette', () => {
+  it('should extract unique colors from a buffer', () => {
+    const buf = new PixelBuffer(3, 1);
+    buf.setPixel(0, 0, 255, 0, 0, 255); // red
+    buf.setPixel(1, 0, 0, 255, 0, 255); // green
+    buf.setPixel(2, 0, 0, 0, 255, 255); // blue
+
+    const palette = extractBufferPalette(buf);
+    expect(palette).toHaveLength(3);
+    expect(palette).toContain('#FF0000');
+    expect(palette).toContain('#00FF00');
+    expect(palette).toContain('#0000FF');
+  });
+
+  it('should deduplicate identical colors', () => {
+    const buf = new PixelBuffer(3, 1);
+    buf.setPixel(0, 0, 255, 0, 0, 255);
+    buf.setPixel(1, 0, 255, 0, 0, 255);
+    buf.setPixel(2, 0, 255, 0, 0, 255);
+
+    const palette = extractBufferPalette(buf);
+    expect(palette).toHaveLength(1);
+    expect(palette[0]).toBe('#FF0000');
+  });
+
+  it('should skip transparent pixels', () => {
+    const buf = new PixelBuffer(2, 1);
+    buf.setPixel(0, 0, 255, 0, 0, 255);
+    // pixel (1,0) is transparent (default)
+
+    const palette = extractBufferPalette(buf);
+    expect(palette).toHaveLength(1);
+    expect(palette[0]).toBe('#FF0000');
+  });
+
+  it('should return empty array for fully transparent buffer', () => {
+    const buf = new PixelBuffer(4, 4);
+    expect(extractBufferPalette(buf)).toEqual([]);
+  });
+
+  it('should include semi-transparent pixels (alpha > 0)', () => {
+    const buf = new PixelBuffer(1, 1);
+    buf.setPixel(0, 0, 128, 64, 32, 1); // alpha=1, nearly transparent but not zero
+
+    const palette = extractBufferPalette(buf);
+    expect(palette).toHaveLength(1);
+  });
+});
+
+describe('extractGroupPalette', () => {
+  it('should extract palette across multiple layers in a group', () => {
+    const layer1: Layer = { id: 'l1', name: 'L1', type: 'pixel', visible: true, opacity: 100, blendMode: 'normal', locked: false };
+    const layer2: Layer = { id: 'l2', name: 'L2', type: 'pixel', visible: true, opacity: 100, blendMode: 'normal', locked: false };
+    const group: Layer = {
+      id: 'g1', name: 'Group', type: 'group', visible: true, opacity: 100, blendMode: 'normal', locked: false,
+      children: [layer1, layer2], expanded: true,
+    };
+
+    const buf1 = new PixelBuffer(2, 1);
+    buf1.setPixel(0, 0, 255, 0, 0, 255);
+    buf1.setPixel(1, 0, 0, 255, 0, 255);
+
+    const buf2 = new PixelBuffer(2, 1);
+    buf2.setPixel(0, 0, 0, 0, 255, 255);
+    buf2.setPixel(1, 0, 255, 0, 0, 255); // duplicate of buf1's red
+
+    const frame: Frame = {
+      id: 'f1', index: 0, durationMs: null,
+      pixelData: new Map([['l1', buf1], ['l2', buf2]]),
+    };
+
+    const palette = extractGroupPalette('g1', [group], [frame]);
+    // Should have 3 unique colors: red, green, blue
+    expect(palette).toHaveLength(3);
+    expect(palette).toContain('#FF0000');
+    expect(palette).toContain('#00FF00');
+    expect(palette).toContain('#0000FF');
+  });
+
+  it('should return empty array for non-existent group', () => {
+    const palette = extractGroupPalette('nonexistent', [], []);
+    expect(palette).toEqual([]);
+  });
+
+  it('should extract across multiple frames', () => {
+    const layer: Layer = { id: 'l1', name: 'L1', type: 'pixel', visible: true, opacity: 100, blendMode: 'normal', locked: false };
+    const group: Layer = {
+      id: 'g1', name: 'Group', type: 'group', visible: true, opacity: 100, blendMode: 'normal', locked: false,
+      children: [layer], expanded: true,
+    };
+
+    const buf1 = new PixelBuffer(1, 1);
+    buf1.setPixel(0, 0, 255, 0, 0, 255);
+    const frame1: Frame = { id: 'f1', index: 0, durationMs: null, pixelData: new Map([['l1', buf1]]) };
+
+    const buf2 = new PixelBuffer(1, 1);
+    buf2.setPixel(0, 0, 0, 0, 255, 255);
+    const frame2: Frame = { id: 'f2', index: 1, durationMs: null, pixelData: new Map([['l1', buf2]]) };
+
+    const palette = extractGroupPalette('g1', [group], [frame1, frame2]);
+    expect(palette).toHaveLength(2);
+    expect(palette).toContain('#FF0000');
+    expect(palette).toContain('#0000FF');
+  });
+});

package/src/lib/variants/palette-extraction.ts

@@ -0,0 +1,84 @@
+/**
+ * Palette Extraction -- extracts unique colors from pixel layers and groups.
+ *
+ * Scans PixelBuffer data to collect all distinct opaque colors as uppercase
+ * 6-digit hex strings. Transparent pixels (alpha === 0) are excluded.
+ */
+
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import { rgbToHex } from '../color/color-utils.js';
+import type { Layer } from '../layers/layer-types.js';
+import type { Frame } from '../animation/frame-model.svelte.js';
+
+/**
+ * Extract unique colors from a single PixelBuffer.
+ * Skips fully transparent pixels (alpha === 0).
+ * Returns uppercase 6-digit hex strings, deduplicated.
+ */
+export function extractBufferPalette(buffer: PixelBuffer): string[] {
+  const colors = new Set<string>();
+  const { data } = buffer;
+
+  for (let i = 0; i < data.length; i += 4) {
+    if (data[i + 3] === 0) continue; // skip transparent pixels
+    colors.add(rgbToHex(data[i] ?? 0, data[i + 1] ?? 0, data[i + 2] ?? 0));
+  }
+
+  return Array.from(colors);
+}
+
+/**
+ * Recursively collect IDs of all pixel layers within a group.
+ */
+function collectPixelLayerIds(layer: Layer): string[] {
+  if (layer.type === 'pixel') return [layer.id];
+  if (layer.children) {
+    return layer.children.flatMap(collectPixelLayerIds);
+  }
+  return [];
+}
+
+/**
+ * Find a layer by ID in the tree (depth-first search).
+ */
+function findLayer(id: string, tree: Layer[]): Layer | undefined {
+  for (const layer of tree) {
+    if (layer.id === id) return layer;
+    if (layer.type === 'group' && layer.children) {
+      const found = findLayer(id, layer.children);
+      if (found) return found;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Extract unique colors from all pixel layers within a layer group,
+ * across all frames.
+ *
+ * Returns uppercase 6-digit hex strings, deduplicated and sorted for
+ * deterministic output.
+ */
+export function extractGroupPalette(
+  groupId: string,
+  layerTree: Layer[],
+  frames: Frame[],
+): string[] {
+  const group = findLayer(groupId, layerTree);
+  if (!group || group.type !== 'group') return [];
+
+  const pixelLayerIds = collectPixelLayerIds(group);
+  const colors = new Set<string>();
+
+  for (const frame of frames) {
+    for (const layerId of pixelLayerIds) {
+      const buffer = frame.pixelData.get(layerId);
+      if (!buffer) continue;
+      for (const hex of extractBufferPalette(buffer)) {
+        colors.add(hex);
+      }
+    }
+  }
+
+  return Array.from(colors).sort();
+}

package/src/lib/variants/palette-interpolation.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'vitest';
+import { interpolatePresets, generateInterpolatedSeries } from './palette-interpolation.js';
+import type { VariantPreset } from './variant-state.svelte.js';
+
+/** Helper to create a preset with a single group's color overrides. */
+function makePreset(
+  name: string,
+  groupId: string,
+  overrides: Record<string, string>,
+): VariantPreset {
+  return {
+    id: `test-${name}`,
+    name,
+    groupOverrides: new Map([[groupId, new Map(Object.entries(overrides))]]),
+  };
+}
+
+describe('interpolatePresets', () => {
+  it('should return preset A colors at t=0', () => {
+    const a = makePreset('A', 'g1', { '#FF0000': '#00FF00' });
+    const b = makePreset('B', 'g1', { '#FF0000': '#0000FF' });
+
+    const result = interpolatePresets(a, b, 0);
+    const color = result.groupOverrides.get('g1')?.get('#FF0000');
+    expect(color).toBe('#00FF00');
+  });
+
+  it('should return preset B colors at t=1', () => {
+    const a = makePreset('A', 'g1', { '#FF0000': '#00FF00' });
+    const b = makePreset('B', 'g1', { '#FF0000': '#0000FF' });
+
+    const result = interpolatePresets(a, b, 1);
+    const color = result.groupOverrides.get('g1')?.get('#FF0000');
+    expect(color).toBe('#0000FF');
+  });
+
+  it('should return an intermediate color at t=0.5', () => {
+    const a = makePreset('A', 'g1', { '#000000': '#000000' });
+    const b = makePreset('B', 'g1', { '#000000': '#FFFFFF' });
+
+    const result = interpolatePresets(a, b, 0.5);
+    const color = result.groupOverrides.get('g1')?.get('#000000');
+    // OKLab midpoint of black and white is a medium gray; exact value depends on OKLab
+    // but it should not be black or white
+    expect(color).not.toBe('#000000');
+    expect(color).not.toBe('#FFFFFF');
+  });
+
+  it('should handle overrides present in only one preset', () => {
+    // Preset A overrides red, preset B does not
+    const a = makePreset('A', 'g1', { '#FF0000': '#00FF00' });
+    const b: VariantPreset = { id: 'b', name: 'B', groupOverrides: new Map() };
+
+    // At t=0, should be fully A's color
+    const r0 = interpolatePresets(a, b, 0);
+    expect(r0.groupOverrides.get('g1')?.get('#FF0000')).toBe('#00FF00');
+
+    // At t=1, B has no override so endpoint is the original color (#FF0000)
+    const r1 = interpolatePresets(a, b, 1);
+    expect(r1.groupOverrides.get('g1')?.get('#FF0000')).toBe('#FF0000');
+  });
+
+  it('should clamp t to [0, 1]', () => {
+    const a = makePreset('A', 'g1', { '#FF0000': '#00FF00' });
+    const b = makePreset('B', 'g1', { '#FF0000': '#0000FF' });
+
+    const rNeg = interpolatePresets(a, b, -0.5);
+    const r0 = interpolatePresets(a, b, 0);
+    expect(rNeg.groupOverrides.get('g1')?.get('#FF0000')).toBe(
+      r0.groupOverrides.get('g1')?.get('#FF0000'),
+    );
+
+    const rOver = interpolatePresets(a, b, 1.5);
+    const r1 = interpolatePresets(a, b, 1);
+    expect(rOver.groupOverrides.get('g1')?.get('#FF0000')).toBe(
+      r1.groupOverrides.get('g1')?.get('#FF0000'),
+    );
+  });
+});
+
+describe('generateInterpolatedSeries', () => {
+  it('should produce the correct number of presets', () => {
+    const a = makePreset('A', 'g1', { '#FF0000': '#000000' });
+    const b = makePreset('B', 'g1', { '#FF0000': '#FFFFFF' });
+
+    expect(generateInterpolatedSeries(a, b, 5)).toHaveLength(5);
+    expect(generateInterpolatedSeries(a, b, 1)).toHaveLength(1);
+    expect(generateInterpolatedSeries(a, b, 0)).toHaveLength(0);
+  });
+
+  it('should have first = A and last = B for series of N >= 2', () => {
+    const a = makePreset('A', 'g1', { '#FF0000': '#000000' });
+    const b = makePreset('B', 'g1', { '#FF0000': '#FFFFFF' });
+
+    const series = generateInterpolatedSeries(a, b, 3);
+    const firstColor = series[0]?.groupOverrides.get('g1')?.get('#FF0000');
+    const lastColor = series[2]?.groupOverrides.get('g1')?.get('#FF0000');
+    expect(firstColor).toBe('#000000');
+    expect(lastColor).toBe('#FFFFFF');
+  });
+
+  it('should produce evenly spaced results', () => {
+    const a = makePreset('A', 'g1', { '#000000': '#000000' });
+    const b = makePreset('B', 'g1', { '#000000': '#FFFFFF' });
+
+    const series = generateInterpolatedSeries(a, b, 3);
+    // Middle value should be the same as interpolation at t=0.5
+    const mid = interpolatePresets(a, b, 0.5);
+    const midColor = mid.groupOverrides.get('g1')?.get('#000000');
+    const seriesMidColor = series[1]?.groupOverrides.get('g1')?.get('#000000');
+    expect(seriesMidColor).toBe(midColor);
+  });
+});

package/src/lib/variants/palette-interpolation.ts

@@ -0,0 +1,87 @@
+/**
+ * Palette Interpolation -- blends between variant presets using OKLab color space.
+ *
+ * Uses lerpColor from color-utils.ts for perceptually uniform interpolation.
+ * Missing overrides in one preset are treated as identity (original color).
+ */
+
+import { lerpColor } from '../color/color-utils.js';
+import type { VariantPreset } from './variant-state.svelte.js';
+
+/**
+ * Interpolate between two variant presets.
+ * Uses OKLab color space (via lerpColor) for perceptual uniformity.
+ *
+ * When a color override exists in only one preset, the other endpoint
+ * is treated as the original color (the key itself), so interpolation
+ * smoothly transitions from/to the unmodified palette.
+ *
+ * @param presetA - first preset (t=0)
+ * @param presetB - second preset (t=1)
+ * @param t - interpolation factor: 0.0 = preset A, 1.0 = preset B
+ * @returns a new preset with interpolated colors
+ */
+export function interpolatePresets(
+  presetA: VariantPreset,
+  presetB: VariantPreset,
+  t: number,
+): VariantPreset {
+  const clampedT = Math.max(0, Math.min(1, t));
+  const groupOverrides = new Map<string, Map<string, string>>();
+
+  // Collect all group IDs from both presets
+  const allGroupIds = new Set<string>();
+  for (const groupId of presetA.groupOverrides.keys()) allGroupIds.add(groupId);
+  for (const groupId of presetB.groupOverrides.keys()) allGroupIds.add(groupId);
+
+  for (const groupId of allGroupIds) {
+    const mapA = presetA.groupOverrides.get(groupId);
+    const mapB = presetB.groupOverrides.get(groupId);
+
+    // Collect all original colors from both maps
+    const allOriginals = new Set<string>();
+    if (mapA) for (const key of mapA.keys()) allOriginals.add(key);
+    if (mapB) for (const key of mapB.keys()) allOriginals.add(key);
+
+    const interpolatedMap = new Map<string, string>();
+
+    for (const originalColor of allOriginals) {
+      // If a preset doesn't override this color, use the original as the endpoint
+      const colorA = mapA?.get(originalColor) ?? originalColor;
+      const colorB = mapB?.get(originalColor) ?? originalColor;
+      interpolatedMap.set(originalColor, lerpColor(colorA, colorB, clampedT));
+    }
+
+    if (interpolatedMap.size > 0) {
+      groupOverrides.set(groupId, interpolatedMap);
+    }
+  }
+
+  return {
+    id: crypto.randomUUID(),
+    name: `Interpolated (t=${clampedT.toFixed(2)})`,
+    groupOverrides,
+  };
+}
+
+/**
+ * Generate N evenly-spaced interpolated presets between A and B.
+ *
+ * For count=3, produces presets at t = 0.0, 0.5, 1.0.
+ * For count=1, produces a preset at t = 0.5.
+ */
+export function generateInterpolatedSeries(
+  presetA: VariantPreset,
+  presetB: VariantPreset,
+  count: number,
+): VariantPreset[] {
+  if (count <= 0) return [];
+  if (count === 1) return [interpolatePresets(presetA, presetB, 0.5)];
+
+  const results: VariantPreset[] = [];
+  for (let i = 0; i < count; i++) {
+    const t = i / (count - 1);
+    results.push(interpolatePresets(presetA, presetB, t));
+  }
+  return results;
+}