pixelweaver 0.1.0

package/src/lib/variants/variant-commands.ts

@@ -0,0 +1,594 @@
+/**
+ * Variant Commands Plugin -- registers variant operations as undoable commands.
+ *
+ * Provides preset-level commands (add/remove, color overrides) as well as
+ * higher-level batch operations dispatched from the VariantPanel:
+ *   - generate_variants: creates N new variants (random or interpolated)
+ *   - apply_variant: toggles the active preset (undoable)
+ *   - extract_palette_from_layer: read-only feedback via notification
+ *   - export_bisection_atlas: triggers a PNG download of the variant atlas
+ *   - export_variants_batch: downloads each variant as a separate PNG file
+ *
+ * Depends on the builtin/layers plugin for layer tree access.
+ */
+
+import type { PluginModule } from '../core/plugin-loader.js';
+import type { Layer } from '../layers/layer-types.js';
+import type { VariantPreset } from './variant-state.svelte.js';
+import * as variantState from './variant-state.svelte.js';
+import { getLayers, getActiveLayer } from '../layers/layer-tree.svelte.js';
+import { getFrames } from '../animation/frame-model.svelte.js';
+import { canvasState } from '../canvas/canvas-state.svelte.js';
+import { notificationState } from '../core/notification-state.svelte.js';
+import { extractGroupPalette } from './palette-extraction.js';
+import { generateRandomVariant } from './variant-randomizer.js';
+import { generateInterpolatedSeries } from './palette-interpolation.js';
+import { exportGroupSpritesheet } from './bisection-export.js';
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import { dialogState } from '../ui/dialog-state.svelte.js';
+import { downloadBatch } from '../export/download.js';
+
+/** Snapshot a preset for undo restore (deep copy of maps to plain objects). */
+function snapshotPreset(preset: VariantPreset): {
+  id: string;
+  name: string;
+  groupOverrides: Record<string, Record<string, string>>;
+} {
+  const groupOverrides: Record<string, Record<string, string>> = {};
+  for (const [groupId, colorMap] of preset.groupOverrides) {
+    groupOverrides[groupId] = Object.fromEntries(colorMap);
+  }
+  return { id: preset.id, name: preset.name, groupOverrides };
+}
+
+/** Restore a preset from a snapshot. */
+function restorePreset(snapshot: {
+  id: string;
+  name: string;
+  groupOverrides: Record<string, Record<string, string>>;
+}): VariantPreset {
+  const groupOverrides = new Map<string, Map<string, string>>();
+  for (const [groupId, overrides] of Object.entries(snapshot.groupOverrides)) {
+    groupOverrides.set(groupId, new Map(Object.entries(overrides)));
+  }
+  return { id: snapshot.id, name: snapshot.name, groupOverrides };
+}
+
+type RemovePresetSnapshot = {
+  preset: ReturnType<typeof snapshotPreset>;
+  wasActive: boolean;
+};
+
+type ColorOverrideSnapshot = {
+  previousColor: string | null;
+};
+
+/** Snapshot of variants created by generate_variants, used for undo. */
+type GenerateVariantsSnapshot = {
+  /** IDs of presets that were created and need to be removed on undo. */
+  createdPresetIds: string[];
+  /** Previous active preset id (restored on undo if we changed it). */
+  previousActiveId: string | null;
+  /** How many variants were actually created (for describe on redo). */
+  count: number;
+};
+
+/** Snapshot of the previously active preset before apply_variant ran. */
+type ApplyVariantSnapshot = {
+  previousActiveId: string | null;
+};
+
+// --- Group targeting helpers ---
+// Variant batch operations target a "group" layer. We resolve the target
+// group by walking up from the active layer; if nothing fits, we fall back
+// to the first group encountered in a top-level scan of the tree.
+
+function findGroupContaining(tree: Layer[], layerId: string): Layer | null {
+  for (const layer of tree) {
+    if (layer.type === 'group' && layer.children) {
+      if (layer.children.some((c) => c.id === layerId)) return layer;
+      const nested = findGroupContaining(layer.children, layerId);
+      if (nested) return nested;
+    }
+  }
+  return null;
+}
+
+function findFirstGroup(tree: Layer[]): Layer | null {
+  for (const layer of tree) {
+    if (layer.type === 'group') return layer;
+  }
+  return null;
+}
+
+/** Resolve the current "target group" for a variant batch operation. */
+function findTargetGroup(): Layer | null {
+  const active = getActiveLayer();
+  const tree = getLayers();
+
+  if (active) {
+    if (active.type === 'group') return active;
+    const containing = findGroupContaining(tree, active.id);
+    if (containing) return containing;
+  }
+  return findFirstGroup(tree);
+}
+
+/** Push a standard-format notification for variant command feedback. */
+function notify(
+  message: string,
+  type: 'info' | 'warning' | 'success' = 'info',
+): void {
+  notificationState.push({
+    id: `variant-cmd-${crypto.randomUUID()}`,
+    message,
+    type,
+    autoDismissMs: 4000,
+  });
+}
+
+/**
+ * Materialize a detached VariantPreset (as returned by the randomizer /
+ * interpolator) into a real preset in the reactive store. Returns the id
+ * of the newly-added preset.
+ *
+ * The input preset's id is discarded; addPreset() assigns a fresh uuid so
+ * that snapshots captured here are guaranteed to match what's in the store.
+ */
+function materializePreset(detached: VariantPreset, name: string): string {
+  const created = variantState.addPreset(name);
+  for (const [groupId, colorMap] of detached.groupOverrides) {
+    for (const [original, replacement] of colorMap) {
+      variantState.setColorOverride(created.id, groupId, original, replacement);
+    }
+  }
+  return created.id;
+}
+
+export const variantCommandsPlugin: PluginModule = {
+  name: 'builtin/variants',
+  version: '1.0.0',
+  description: 'Variant preset management commands',
+  dependencies: ['builtin/layers'],
+
+  register(api) {
+    // --- add_variant_preset ---
+    api.addCommand('add_variant_preset', {
+      tier: 'project',
+      execute(params) {
+        const preset = variantState.addPreset(params["name"]);
+        params["_presetId"] = preset.id;
+      },
+      undo(params) {
+        variantState.removePreset(params["_presetId"]);
+      },
+      describe(params) {
+        return `Added variant preset "${String(params["name"])}"`;
+      },
+    });
+
+    // --- remove_variant_preset ---
+    api.addCommand('remove_variant_preset', {
+      tier: 'project',
+      execute(params) {
+        const preset = variantState.getPreset(params["id"]);
+        if (!preset) return;
+        // Stash the name on params so describe() can use it (describe only gets params)
+        params["_removedName"] = preset.name;
+        const snapshot: RemovePresetSnapshot = {
+          preset: snapshotPreset(preset),
+          wasActive: variantState.getActivePresetId() === preset.id,
+        };
+        variantState.removePreset(params["id"]);
+        return snapshot;
+      },
+      undo(_params, _ctx, snapshot) {
+        const typed = snapshot as RemovePresetSnapshot | undefined;
+        if (!typed) return;
+        // Re-insert the preset via deserialization
+        const currentState = variantState.serialize();
+        const restored = restorePreset(typed.preset);
+        // We need to re-add; since addPreset generates a new ID, we use deserialize
+        currentState.presets.push({
+          id: restored.id,
+          name: restored.name,
+          groupOverrides: typed.preset.groupOverrides,
+        });
+        if (typed.wasActive) {
+          currentState.activePresetId = restored.id;
+        }
+        variantState.deserialize(currentState);
+      },
+      describe(params) {
+        return `Removed variant preset "${String(params["_removedName"] ?? params["id"])}"`;
+      },
+    });
+
+    // --- set_color_override ---
+    api.addCommand('set_color_override', {
+      tier: 'project',
+      execute(params) {
+        const preset = variantState.getPreset(params["presetId"]);
+        if (!preset) return;
+        const groupMap = preset.groupOverrides.get(params["groupId"]);
+        const snapshot: ColorOverrideSnapshot = {
+          previousColor: groupMap?.get(params["originalColor"]) ?? null,
+        };
+        variantState.setColorOverride(
+          params["presetId"],
+          params["groupId"],
+          params["originalColor"],
+          params["newColor"],
+        );
+        return snapshot;
+      },
+      undo(params, _ctx, snapshot) {
+        const typed = snapshot as ColorOverrideSnapshot | undefined;
+        if (!typed) return;
+        if (typed.previousColor === null) {
+          // There was no override before; remove it
+          variantState.removeColorOverride(
+            params["presetId"],
+            params["groupId"],
+            params["originalColor"],
+          );
+        } else {
+          // Restore previous override
+          variantState.setColorOverride(
+            params["presetId"],
+            params["groupId"],
+            params["originalColor"],
+            typed.previousColor,
+          );
+        }
+      },
+      describe(params) {
+        return `Set color override ${String(params["originalColor"])} -> ${String(params["newColor"])}`;
+      },
+    });
+
+    // --- generate_variants ---
+    // Generate N new variant presets for the active layer group. Modes:
+    //   'random'      -- each variant is an HSV-shifted randomization.
+    //   'interpolate' -- evenly-spaced interpolation between the first two
+    //                    existing presets. Requires >=2 presets already.
+    // Undoable: undo removes the created presets and restores the previous
+    // active preset (if generation set it).
+    api.addCommand('generate_variants', {
+      tier: 'project',
+      undoable: true,
+      execute(params) {
+        const count = Math.max(1, params["count"] ?? 1);
+        const mode = (params["mode"] ?? 'random') as
+          | 'random'
+          | 'interpolate';
+
+        const group = findTargetGroup();
+        if (!group) {
+          notify(
+            'No layer group found. Create a group to generate variants.',
+            'warning',
+          );
+          return;
+        }
+
+        const snapshot: GenerateVariantsSnapshot = {
+          createdPresetIds: [],
+          previousActiveId: variantState.getActivePresetId(),
+          count: 0,
+        };
+
+        if (mode === 'interpolate') {
+          const existing = variantState.getPresets();
+          if (existing.length < 2) {
+            notify(
+              'Interpolate mode needs at least two existing variants.',
+              'warning',
+            );
+            return snapshot;
+          }
+          // existing.length >= 2 is guarded above
+          const presetA = existing[0];
+          const presetB = existing[existing.length - 1];
+          if (!presetA || !presetB) return snapshot;
+          const series = generateInterpolatedSeries(presetA, presetB, count);
+          const baseIndex = existing.length;
+          for (let i = 0; i < series.length; i++) {
+            const item = series[i];
+            if (!item) continue;
+            const name = `Variant ${String(baseIndex + i + 1)}`;
+            const id = materializePreset(item, name);
+            snapshot.createdPresetIds.push(id);
+          }
+        } else {
+          // 'random' mode -- each variant gets its own randomization pass so
+          // they explore different hue rotations (generator samples fresh rng).
+          const palette = extractGroupPalette(group.id, getLayers(), getFrames());
+          if (palette.length === 0) {
+            notify(
+              `Group "${group.name}" has no colors to randomize.`,
+              'warning',
+            );
+            return snapshot;
+          }
+          const groupPalettes = new Map<string, string[]>([[group.id, palette]]);
+          const existingCount = variantState.getPresets().length;
+          for (let i = 0; i < count; i++) {
+            const detached = generateRandomVariant(groupPalettes);
+            const name = `Variant ${String(existingCount + i + 1)}`;
+            const id = materializePreset(detached, name);
+            snapshot.createdPresetIds.push(id);
+          }
+        }
+
+        // Auto-activate the first created preset so the user sees the result.
+        const firstCreated = snapshot.createdPresetIds[0];
+        if (firstCreated !== undefined) {
+          variantState.setActivePreset(firstCreated);
+        }
+        snapshot.count = snapshot.createdPresetIds.length;
+        return snapshot;
+      },
+      undo(_params, _ctx, snapshot) {
+        const typed = snapshot as GenerateVariantsSnapshot | undefined;
+        if (!typed) return;
+        // Remove created presets in reverse order (cheaper splice patterns).
+        for (let i = typed.createdPresetIds.length - 1; i >= 0; i--) {
+          const id = typed.createdPresetIds[i];
+          if (id !== undefined) variantState.removePreset(id);
+        }
+        // Restore the previously active preset if it still exists. If the
+        // previous active id was one that we just removed (shouldn't happen
+        // since we only removed newly-created ones), setActivePreset would
+        // throw -- guard against that.
+        if (
+          typed.previousActiveId !== null &&
+          variantState.getPreset(typed.previousActiveId)
+        ) {
+          variantState.setActivePreset(typed.previousActiveId);
+        } else {
+          variantState.setActivePreset(null);
+        }
+      },
+      describe(params) {
+        const count = params["count"] ?? 1;
+        const mode = params["mode"] ?? 'random';
+        return `Generated ${String(count)} ${mode} variant${count === 1 ? '' : 's'}`;
+      },
+      label: 'Generate Variants',
+      category: 'Variants',
+    });
+
+    // --- apply_variant ---
+    // Set the active variant preset. Pass presetId: null to clear.
+    // Undoable: undo restores the previously active preset.
+    api.addCommand('apply_variant', {
+      tier: 'project',
+      undoable: true,
+      execute(params) {
+        const nextId = params["presetId"] ?? null;
+        const snapshot: ApplyVariantSnapshot = {
+          previousActiveId: variantState.getActivePresetId(),
+        };
+        // Guard: setActivePreset throws for unknown ids. Silently ignore so
+        // a stale dispatch (e.g. after a preset was removed) doesn't crash.
+        if (nextId !== null && !variantState.getPreset(nextId)) {
+          return snapshot;
+        }
+        variantState.setActivePreset(nextId);
+        return snapshot;
+      },
+      undo(_params, _ctx, snapshot) {
+        const typed = snapshot as ApplyVariantSnapshot | undefined;
+        if (!typed) return;
+        if (
+          typed.previousActiveId !== null &&
+          !variantState.getPreset(typed.previousActiveId)
+        ) {
+          variantState.setActivePreset(null);
+          return;
+        }
+        variantState.setActivePreset(typed.previousActiveId);
+      },
+      describe(params) {
+        const id = params["presetId"];
+        if (typeof id !== 'string') return 'Cleared active variant';
+        const preset = variantState.getPreset(id);
+        return `Applied variant "${preset?.name ?? id}"`;
+      },
+      label: 'Apply Variant',
+      category: 'Variants',
+    });
+
+    // --- extract_palette_from_layer ---
+    // Read-only: extracts the palette of the active group and reports via
+    // notification. Not undoable (no state mutation).
+    api.addCommand('extract_palette_from_layer', {
+      tier: 'project',
+      execute() {
+        const group = findTargetGroup();
+        if (!group) {
+          notify('No layer group found.', 'warning');
+          return;
+        }
+        const palette = extractGroupPalette(group.id, getLayers(), getFrames());
+        notify(
+          `Extracted ${String(palette.length)} color${palette.length === 1 ? '' : 's'} from "${group.name}".`,
+          'success',
+        );
+      },
+      undo() {
+        // No-op: this command has no persistent side effects.
+      },
+      describe() {
+        return 'Extracted palette from active group';
+      },
+      label: 'Extract Palette from Layer',
+      category: 'Variants',
+    });
+
+    // --- export_bisection_atlas ---
+    // Opens a preview dialog for the variant atlas (rows = variants, cols = frames).
+    // The actual download is triggered from the dialog after user confirmation.
+    // Not undoable (download is a side effect outside app state).
+    api.addCommand('export_bisection_atlas', {
+      tier: 'project',
+      execute() {
+        const group = findTargetGroup();
+        if (!group) {
+          notify('No layer group found to export.', 'warning');
+          return;
+        }
+        const presets = variantState.getPresets();
+        if (presets.length === 0) {
+          notify('No variants to export. Generate at least one first.', 'warning');
+          return;
+        }
+
+        dialogState.openBisectionExport(group.id);
+      },
+      undo() {
+        // No-op: downloads can't be "undone" -- the file is already on disk.
+      },
+      describe() {
+        return 'Exported bisection atlas';
+      },
+      label: 'Export Bisection Atlas',
+      category: 'Variants',
+    });
+
+    // --- export_variants_batch ---
+    // Downloads each variant as a separate PNG file. Multi-frame variants are
+    // arranged as a horizontal strip (one row, N columns). A small delay
+    // between downloads prevents the browser from throttling rapid blob URLs.
+    api.addCommand('export_variants_batch', {
+      tier: 'project',
+      async execute() {
+        const group = findTargetGroup();
+        if (!group) {
+          notify('No layer group found to export.', 'warning');
+          return;
+        }
+        const presets = variantState.getPresets();
+        if (presets.length === 0) {
+          notify('No variants to export. Generate at least one first.', 'warning');
+          return;
+        }
+
+        const layerTree = getLayers();
+        const frames = getFrames();
+        const w = canvasState.canvasWidth;
+        const h = canvasState.canvasHeight;
+
+        try {
+          const entries: Array<{ blob: Blob; filename: string }> = [];
+
+          for (const preset of presets) {
+            const frameBuffers = exportGroupSpritesheet(
+              group.id, layerTree, frames, w, h, { variant: preset },
+            );
+
+            // Single frame: export the buffer directly.
+            // Multiple frames: stitch into a horizontal strip.
+            let result: PixelBuffer;
+            if (frameBuffers.length === 1) {
+              const only = frameBuffers[0];
+              if (!only) continue;
+              result = only;
+            } else {
+              result = new PixelBuffer(w * frameBuffers.length, h);
+              for (let i = 0; i < frameBuffers.length; i++) {
+                const fb = frameBuffers[i];
+                if (fb) result.paste(fb, i * w, 0);
+              }
+            }
+
+            const canvas = document.createElement('canvas');
+            canvas.width = result.width;
+            canvas.height = result.height;
+            const ctx = canvas.getContext('2d');
+            if (!ctx) {
+              notify('Could not create export canvas.', 'warning');
+              return;
+            }
+            ctx.imageSmoothingEnabled = false;
+            ctx.putImageData(result.toImageData(), 0, 0);
+
+            const blob = await new Promise<Blob | null>((resolve) => {
+              canvas.toBlob(resolve, 'image/png');
+            });
+            if (!blob) continue;
+
+            // Sanitize names for safe filenames
+            const safeName = preset.name.replace(/[^a-zA-Z0-9_-]/g, '_');
+            const safeGroup = group.name.replace(/[^a-zA-Z0-9_-]/g, '_');
+            entries.push({ blob, filename: `${safeGroup}-${safeName}.png` });
+          }
+
+          const saved = await downloadBatch(entries);
+          if (saved) {
+            notify(
+              `Exported ${String(entries.length)} variant${entries.length === 1 ? '' : 's'} as individual PNGs.`,
+              'success',
+            );
+          }
+        } catch (err) {
+          notify(
+            `Batch export failed: ${err instanceof Error ? err.message : String(err)}`,
+            'warning',
+          );
+        }
+      },
+      undo() {
+        // No-op: downloads are side effects outside app state.
+      },
+      describe() {
+        return 'Exported variants as individual PNGs';
+      },
+      label: 'Export Variants Individually',
+      category: 'Variants',
+    });
+
+    // --- remove_color_override ---
+    api.addCommand('remove_color_override', {
+      tier: 'project',
+      execute(params) {
+        const preset = variantState.getPreset(params["presetId"]);
+        if (!preset) return;
+        const groupMap = preset.groupOverrides.get(params["groupId"]);
+        const snapshot: ColorOverrideSnapshot = {
+          previousColor: groupMap?.get(params["originalColor"]) ?? null,
+        };
+        variantState.removeColorOverride(
+          params["presetId"],
+          params["groupId"],
+          params["originalColor"],
+        );
+        return snapshot;
+      },
+      undo(params, _ctx, snapshot) {
+        const typed = snapshot as ColorOverrideSnapshot | undefined;
+        if (typed?.previousColor != null) {
+          variantState.setColorOverride(
+            params["presetId"],
+            params["groupId"],
+            params["originalColor"],
+            typed.previousColor,
+          );
+        }
+      },
+      describe(params) {
+        return `Removed color override for ${String(params["originalColor"])}`;
+      },
+    });
+
+    // --- Menu items for variant exports ---
+    api.addMenuItem('menu:file:export:variants-batch', {
+      commandId: 'export_variants_batch',
+      menuPath: 'file/export',
+      group: 'export',
+      order: 20,
+      label: 'Export Variants Individually...',
+    });
+  },
+};

package/src/lib/variants/variant-panel-plugin.ts

@@ -0,0 +1,27 @@
+/**
+ * Variant Panel Plugin -- registers the VariantPanel Svelte component as a
+ * dockable panel in the right sidebar. Discovery happens through the
+ * *-plugin.ts glob in bootstrap.ts; no manual wiring needed.
+ */
+
+import type { PluginModule } from '../core/plugin-loader.js';
+import VariantPanel from './VariantPanel.svelte';
+
+export const variantPanelPlugin: PluginModule = {
+  name: 'ui/variants',
+  version: '1.0.0',
+  description: 'Variant preset grid panel (generate, preview, export)',
+  // Depends on the variant commands plugin so preset state mutations are
+  // guaranteed to be registered before the panel tries to use them.
+  dependencies: ['builtin/variants'],
+
+  register(api) {
+    api.addPanel('variants', {
+      title: 'Variants',
+      component: VariantPanel,
+      position: 'right',
+      minWidth: 180,
+      maxWidth: 320,
+    });
+  },
+};