pixelweaver 0.1.0

package/plugins/builtin/importers/piskel-importer-plugin.ts

@@ -0,0 +1,222 @@
+/**
+ * Piskel Importer Plugin -- imports .piskel files (Piskel's native JSON format).
+ *
+ * Piskel files contain layers, each with chunked base64 PNG sprite sheets.
+ * Each chunk tiles all frames horizontally into a single PNG. This plugin
+ * decodes those PNGs, splits them into per-frame PixelBuffers, and populates
+ * the PixelWeaver layer/frame state.
+ *
+ * Registers:
+ *   - Importer: `piskel` (extensions: ['.piskel'])
+ */
+
+import type { PluginModule } from '../../../src/lib/core/plugin-loader.js';
+import type { PluginAPI } from '../../../src/lib/core/plugin-types.js';
+import type { PixelBuffer } from '../../../src/lib/canvas/pixel-buffer.js';
+import FileImage from '~icons/lucide/file-image';
+
+// --- Piskel file types (subset relevant to import) ---
+//
+// Fields are optional because these shapes describe what JSON.parse()
+// may yield from an untrusted .piskel file. The importer validates and
+// supplies fallbacks for missing values; declaring everything required
+// here would mislead callers into skipping the runtime guards.
+
+interface PiskelChunk {
+  layout?: number[][];
+  base64PNG?: string;
+}
+
+interface PiskelLayer {
+  name: string;
+  opacity?: number;
+  frameCount?: number;
+  chunks?: PiskelChunk[];
+}
+
+interface PiskelFile {
+  modelVersion?: number;
+  piskel?: {
+    name?: string;
+    description?: string;
+    fps?: number;
+    height: number;
+    width: number;
+    layers?: PiskelLayer[];
+    hiddenFrames?: number[];
+  };
+}
+
+/**
+ * Decode a base64 data-URL PNG to ImageData using Image + canvas.
+ * Works in browser environments where Image and canvas are available.
+ */
+async function decodeBase64Png(dataUrl: string): Promise<ImageData> {
+  const img = new Image();
+  img.src = dataUrl;
+  await new Promise<void>((resolve, reject) => {
+    img.onload = () => { resolve(); };
+    img.onerror = () => { reject(new Error('Failed to decode base64 PNG from Piskel chunk')); };
+  });
+
+  // Prefer OffscreenCanvas when available (e.g. in workers)
+  if (typeof OffscreenCanvas !== 'undefined') {
+    const canvas = new OffscreenCanvas(img.width, img.height);
+    const ctx = canvas.getContext('2d');
+    if (!ctx) throw new Error('Failed to get 2d context');
+    ctx.drawImage(img, 0, 0);
+    return ctx.getImageData(0, 0, img.width, img.height);
+  }
+
+  const canvas = document.createElement('canvas');
+  canvas.width = img.width;
+  canvas.height = img.height;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) throw new Error('Failed to get 2d context');
+  ctx.drawImage(img, 0, 0);
+  return ctx.getImageData(0, 0, img.width, img.height);
+}
+
+/**
+ * Extract a single frame's pixels from a horizontally-tiled ImageData.
+ * Frame N occupies columns [N*frameWidth .. (N+1)*frameWidth).
+ */
+function extractFrameBuffer(
+  api: PluginAPI,
+  imageData: ImageData,
+  frameIndex: number,
+  frameWidth: number,
+  frameHeight: number,
+): PixelBuffer {
+  const buf = api.createPixelBuffer(frameWidth, frameHeight);
+  const srcStride = imageData.width * 4;
+  const xOffset = frameIndex * frameWidth;
+
+  for (let y = 0; y < frameHeight; y++) {
+    for (let x = 0; x < frameWidth; x++) {
+      const srcIdx = y * srcStride + (xOffset + x) * 4;
+      buf.setPixel(
+        x,
+        y,
+        imageData.data[srcIdx] ?? 0,
+        imageData.data[srcIdx + 1] ?? 0,
+        imageData.data[srcIdx + 2] ?? 0,
+        imageData.data[srcIdx + 3] ?? 0,
+      );
+    }
+  }
+
+  return buf;
+}
+
+export const piskelImporterPlugin: PluginModule = {
+  name: 'builtin/import-piskel',
+  version: '1.0.0',
+  description: 'Import Piskel .piskel files',
+  register(api) {
+    api.addCommand('import_piskel', {
+      tier: 'project',
+      execute() { /* Will be wired to file picker */ },
+      undo() {},
+      describe() { return 'Import Piskel file'; },
+      label: 'Piskel (.piskel)',
+      category: 'File',
+      icon: FileImage,
+    });
+    api.addMenuItem('menu:file:import:piskel', {
+      commandId: 'import_piskel',
+      menuPath: 'file/import',
+      group: 'import',
+      order: 20,
+      label: 'Piskel (.piskel)',
+    });
+
+    api.addImporter('piskel', {
+      label: 'Piskel File',
+      extensions: ['piskel'],
+
+      async import(data) {
+        const text = data instanceof File ? await data.text() : new TextDecoder().decode(data);
+        // PiskelFile's fields are all declared optional because JSON.parse
+        // yields untrusted data; the structural check below is what
+        // actually proves the minimal shape we need.
+        const json = JSON.parse(text) as PiskelFile;
+        const piskel = json.piskel;
+
+        // Validate minimal structure
+        if (!piskel || typeof piskel.width !== 'number' || typeof piskel.height !== 'number') {
+          throw new Error('Invalid Piskel file: missing piskel object or dimensions.');
+        }
+
+        const width = piskel.width;
+        const height = piskel.height;
+        const fps = Math.max(1, Math.min(120, piskel.fps || 12));
+        const piskelLayers = piskel.layers ?? [];
+
+        // Determine total frame count from the first layer (all layers share the same count)
+        const frameCount = piskelLayers[0]?.frameCount || 1;
+
+        // Handle edge case: no layers at all
+        if (piskelLayers.length === 0) {
+          api.setCanvasSize(width, height);
+          api.setGlobalFps(fps);
+          return;
+        }
+
+        // 1. Set canvas dimensions
+        api.setCanvasSize(width, height);
+
+        // 2. Reset existing layers and frames to a clean slate
+        api.deserializeLayers({ layers: [], activeLayerId: '' });
+        api.deserializeFrames({
+          frames: [],
+          currentFrameIndex: 0,
+          globalFps: fps,
+          originX: 0,
+          originY: 0,
+        });
+
+        // 3. Create the required number of frames
+        for (let i = 0; i < frameCount; i++) {
+          api.addFrame();
+        }
+
+        // 4. Process each Piskel layer
+        let firstLayerId: string | undefined;
+
+        for (const piskelLayer of piskelLayers) {
+          const layerId = api.addLayer(piskelLayer.name);
+          if (!firstLayerId) firstLayerId = layerId;
+
+          const layerFrameCount = piskelLayer.frameCount || 1;
+
+          for (const chunk of piskelLayer.chunks ?? []) {
+            if (!chunk.base64PNG) continue;
+
+            const imageData = await decodeBase64Png(chunk.base64PNG);
+
+            // The layout array maps logical frame indices to chunk tile positions.
+            // Typically layout is [[0],[1],[2],...] meaning frame i is at tile i.
+            // We iterate the layout to support non-trivial mappings.
+            const layout = chunk.layout ?? [];
+            const framesToProcess = layout.length > 0 ? layout.length : layerFrameCount;
+
+            for (let frameIdx = 0; frameIdx < framesToProcess; frameIdx++) {
+              // Determine the tile index within the PNG strip
+              // layout[frameIdx] is an array (usually single-element) pointing to the tile
+              const tileIndex = layout[frameIdx]?.[0] ?? frameIdx;
+
+              // Ensure enough frames exist (in case layers disagree on frame count)
+              while (api.getFrames().length <= frameIdx) {
+                api.addFrame();
+              }
+
+              const buf = extractFrameBuffer(api, imageData, tileIndex, width, height);
+              api.setFramePixelData(frameIdx, layerId, buf);
+            }
+          }
+        }
+      },
+    });
+  },
+};

package/plugins/builtin/importers/sky-spec-plugin.ts

@@ -0,0 +1,409 @@
+/**
+ * Sky Spec Importer Plugin -- imports JSON spec files from the Sky art pipeline.
+ *
+ * Sky specs define sprites as sequences of drawing commands. This plugin
+ * maps each Sky command to a PixelWeaver command and dispatches them through
+ * the command system so they appear in the action log and support undo/redo.
+ *
+ * Handles both single specs and batch specs ({ "batch": [...] }).
+ * For batch specs, imports the first spec and warns about the rest.
+ *
+ * Registers:
+ *   - Importer: `sky-spec` (extensions: ['json'])
+ */
+
+import type { PluginModule } from '../../../src/lib/core/plugin-loader.js';
+import FileJson from '~icons/lucide/file-json';
+import { dispatch } from '../../../src/lib/core/dispatcher.js';
+import type { Command } from '../../../src/lib/core/commands.js';
+import { hexToRgba } from '../drawing-utils.js';
+
+// --- Sky spec types ---
+
+interface SkyCommand {
+  type: string;
+  [key: string]: unknown;
+}
+
+interface SkyLayer {
+  // Optional because the JSON is untrusted: a layer object may omit
+  // `commands` and the importer falls back to `[]` at the use site.
+  commands?: SkyCommand[];
+}
+
+interface SkySpec {
+  name?: string;
+  category?: string;
+  width: number;
+  height: number;
+  background?: string;
+  layers?: SkyLayer[];
+}
+
+interface SkyBatchSpec {
+  batch: SkySpec[];
+}
+
+// --- Command mapping ---
+
+/**
+ * Maps a Sky command type to a PixelWeaver command type and a parameter
+ * transform function. The transform receives the raw Sky command object
+ * plus the spec's canvas dimensions (for commands like `fill` that need them).
+ */
+const COMMAND_MAP: Record<
+  string,
+  { type: string; transform: (cmd: SkyCommand, w: number, h: number) => Record<string, unknown> }
+> = {
+  pixel: {
+    type: 'draw_pixels',
+    transform: (cmd) => ({
+      pixels: [{ x: cmd["x"], y: cmd["y"], ...hexToRgba(cmd["color"] as string) }],
+    }),
+  },
+
+  fill: {
+    type: 'draw_rect',
+    transform: (cmd, w, h) => ({
+      x: 0, y: 0, w, h,
+      filled: true,
+      color: cmd["color"],
+    }),
+  },
+
+  rect: {
+    type: 'draw_rect',
+    transform: (cmd) => ({
+      x: cmd["x"], y: cmd["y"], w: cmd["w"], h: cmd["h"],
+      filled: true,
+      color: cmd["color"],
+    }),
+  },
+
+  rect_outline: {
+    type: 'draw_rect',
+    transform: (cmd) => ({
+      x: cmd["x"], y: cmd["y"], w: cmd["w"], h: cmd["h"],
+      filled: false,
+      color: cmd["color"],
+    }),
+  },
+
+  line: {
+    type: 'draw_line',
+    transform: (cmd) => ({
+      x0: cmd["x1"], y0: cmd["y1"], x1: cmd["x2"], y1: cmd["y2"],
+      color: cmd["color"],
+      algorithm: 'standard',
+    }),
+  },
+
+  hline: {
+    type: 'draw_line',
+    transform: (cmd) => ({
+      x0: cmd["x"], y0: cmd["y"],
+      x1: (cmd["x"] as number) + (cmd["length"] as number) - 1, y1: cmd["y"],
+      color: cmd["color"],
+      algorithm: 'standard',
+    }),
+  },
+
+  vline: {
+    type: 'draw_line',
+    transform: (cmd) => ({
+      x0: cmd["x"], y0: cmd["y"],
+      x1: cmd["x"], y1: (cmd["y"] as number) + (cmd["length"] as number) - 1,
+      color: cmd["color"],
+      algorithm: 'standard',
+    }),
+  },
+
+  diamond_fill: {
+    type: 'draw_diamond',
+    transform: (cmd) => ({
+      cx: cmd["cx"], cy: cmd["cy"],
+      radiusX: cmd["rx"], radiusY: cmd["ry"],
+      filled: true,
+      color: cmd["color"],
+    }),
+  },
+
+  diamond: {
+    type: 'draw_diamond',
+    transform: (cmd) => ({
+      cx: cmd["cx"], cy: cmd["cy"],
+      radiusX: cmd["rx"], radiusY: cmd["ry"],
+      filled: false,
+      color: cmd["color"],
+    }),
+  },
+
+  circle_fill: {
+    type: 'draw_ellipse',
+    transform: (cmd) => ({
+      cx: cmd["cx"], cy: cmd["cy"],
+      rx: cmd["r"], ry: cmd["r"],
+      filled: true,
+      color: cmd["color"],
+    }),
+  },
+
+  circle: {
+    type: 'draw_ellipse',
+    transform: (cmd) => ({
+      cx: cmd["cx"], cy: cmd["cy"],
+      rx: cmd["r"], ry: cmd["r"],
+      filled: false,
+      color: cmd["color"],
+    }),
+  },
+
+  gradient_v: {
+    type: 'draw_gradient',
+    transform: (cmd) => ({
+      x0: (cmd["x"] as number) + (cmd["w"] as number) / 2, y0: cmd["y"],
+      x1: (cmd["x"] as number) + (cmd["w"] as number) / 2, y1: (cmd["y"] as number) + (cmd["h"] as number),
+      color0: cmd["color_top"],
+      color1: cmd["color_bottom"],
+      mode: 'smooth',
+    }),
+  },
+
+  gradient_h: {
+    type: 'draw_gradient',
+    transform: (cmd) => ({
+      x0: cmd["x"], y0: (cmd["y"] as number) + (cmd["h"] as number) / 2,
+      x1: (cmd["x"] as number) + (cmd["w"] as number), y1: (cmd["y"] as number) + (cmd["h"] as number) / 2,
+      color0: cmd["color_left"],
+      color1: cmd["color_right"],
+      mode: 'smooth',
+    }),
+  },
+
+  noise: {
+    type: 'draw_noise',
+    transform: (cmd) => ({
+      x: cmd["x"], y: cmd["y"], w: cmd["w"], h: cmd["h"],
+      colors: cmd["colors"],
+      density: (cmd["density"] ?? 0.3) as number,
+      seed: Math.floor(Math.random() * 0xFFFFFFFF),
+    }),
+  },
+
+  dither: {
+    type: 'draw_dither',
+    transform: (cmd) => ({
+      x: cmd["x"], y: cmd["y"], w: cmd["w"], h: cmd["h"],
+      color0: cmd["color1"],
+      color1: cmd["color2"],
+      matrixSize: 2,
+    }),
+  },
+
+  mirror_h: {
+    type: 'flip',
+    transform: () => ({
+      direction: 'h',
+    }),
+  },
+
+  mirror_v: {
+    type: 'flip',
+    transform: () => ({
+      direction: 'v',
+    }),
+  },
+
+  // Primitives from drawing-primitives-plugin.ts
+  scatter: {
+    type: 'scatter',
+    transform: (cmd) => ({
+      points: cmd["points"],
+      color: cmd["color"],
+    }),
+  },
+
+  copy: {
+    type: 'copy_region',
+    transform: (cmd) => ({
+      srcX: cmd["src_x"], srcY: cmd["src_y"],
+      w: cmd["w"], h: cmd["h"],
+      dstX: cmd["dst_x"], dstY: cmd["dst_y"],
+    }),
+  },
+
+  replace_color: {
+    type: 'replace_color',
+    transform: (cmd) => ({
+      oldColor: cmd["old"],
+      newColor: cmd["new"],
+    }),
+  },
+
+  checkerboard: {
+    type: 'checkerboard',
+    transform: (cmd, w, h) => ({
+      x: (cmd["x"] ?? 0) as number,
+      y: (cmd["y"] ?? 0) as number,
+      w: (cmd["w"] ?? w) as number,
+      h: (cmd["h"] ?? h) as number,
+      color1: cmd["color1"],
+      color2: cmd["color2"],
+      size: (cmd["size"] ?? 1) as number,
+    }),
+  },
+
+  polygon_fill: {
+    type: 'draw_polygon',
+    transform: (cmd) => ({
+      points: cmd["points"],
+      filled: true,
+      color: cmd["color"],
+    }),
+  },
+
+  polygon: {
+    type: 'draw_polygon',
+    transform: (cmd) => ({
+      points: cmd["points"],
+      filled: false,
+      color: cmd["color"],
+    }),
+  },
+
+  iso_outline: {
+    type: 'iso_outline',
+    transform: (cmd) => ({
+      color: cmd["color"],
+    }),
+  },
+};
+
+// --- Dispatch helper ---
+
+const PLUGIN_NAME = 'builtin/sky-spec';
+const PLUGIN_VERSION = '1.0.0';
+
+/**
+ * Build a Command object and dispatch it through the PixelWeaver command system.
+ * This ensures every imported command appears in the action log and supports undo.
+ */
+function dispatchCmd(type: string, params: Record<string, unknown>): void {
+  const command: Command = {
+    type,
+    plugin: PLUGIN_NAME,
+    version: PLUGIN_VERSION,
+    params,
+    id: crypto.randomUUID(),
+    timestamp: Date.now(),
+  };
+  dispatch(command);
+}
+
+// --- Plugin module ---
+
+export const skySpecPlugin: PluginModule = {
+  name: PLUGIN_NAME,
+  version: PLUGIN_VERSION,
+  description: 'Import Sky art pipeline JSON specs',
+  dependencies: ['builtin/layers', 'builtin/canvas-init'],
+
+  register(api) {
+    api.addCommand('import_sky_spec', {
+      tier: 'project',
+      execute() { /* Will be wired to file picker */ },
+      undo() {},
+      describe() { return 'Import Sky Spec file'; },
+      label: 'Sky Spec (.json)',
+      category: 'File',
+      icon: FileJson,
+    });
+    api.addMenuItem('menu:file:import:sky-spec', {
+      commandId: 'import_sky_spec',
+      menuPath: 'file/import',
+      group: 'import',
+      order: 30,
+      label: 'Sky Spec (.json)',
+    });
+
+    api.addImporter('sky-spec', {
+      label: 'Sky Spec File',
+      extensions: ['json'],
+
+      async import(data) {
+        const text = data instanceof File ? await data.text() : new TextDecoder().decode(data);
+        const json = JSON.parse(text) as SkySpec | SkyBatchSpec;
+
+        // Handle batch or single spec
+        const specs: SkySpec[] = 'batch' in json ? json.batch : [json];
+
+        if (specs.length === 0) {
+          throw new Error('Sky spec file contains no specs.');
+        }
+
+        const spec = specs[0];
+        if (!spec) throw new Error('Sky spec file contains no specs.');
+
+        if (specs.length > 1) {
+          console.warn(
+            `[sky-spec] Batch contains ${String(specs.length)} specs; importing only the first ("${spec.name ?? 'unnamed'}"). ` +
+              `Remaining ${String(specs.length - 1)} specs were skipped.`,
+          );
+        }
+
+        // Validate minimal structure
+        if (typeof spec.width !== 'number' || typeof spec.height !== 'number') {
+          throw new Error('Invalid Sky spec: missing width or height.');
+        }
+
+        // 1. Set canvas dimensions
+        api.setCanvasSize(spec.width, spec.height);
+
+        // 2. Clear existing layers and frames
+        api.deserializeLayers({ layers: [], activeLayerId: '' });
+        api.deserializeFrames({
+          frames: [],
+          currentFrameIndex: 0,
+          globalFps: 12,
+          originX: 0,
+          originY: 0,
+        });
+
+        // 3. Create a fresh layer and frame
+        const layerId = api.addLayer(spec.name || 'Layer 1');
+        if (api.getFrames().length === 0) api.addFrame();
+
+        // 4. Ensure the (single, freshly created) frame has a blank buffer
+        //    for the newly added layer. After the deserialize+addFrame above,
+        //    the only frame lives at index 0.
+        api.setFramePixelData(
+          0,
+          layerId,
+          api.createPixelBuffer(spec.width, spec.height),
+        );
+
+        // 5. If background color is set, dispatch a fill command
+        if (spec.background) {
+          dispatchCmd('draw_rect', {
+            x: 0, y: 0, w: spec.width, h: spec.height,
+            filled: true,
+            color: spec.background,
+          });
+        }
+
+        // 6. Iterate layers and commands, map and dispatch each one
+        for (const skyLayer of spec.layers ?? []) {
+          for (const cmd of skyLayer.commands ?? []) {
+            const mapping = COMMAND_MAP[cmd.type];
+            if (!mapping) {
+              console.warn(`[sky-spec] Unknown command type: "${cmd.type}" -- skipped.`);
+              continue;
+            }
+            const params = mapping.transform(cmd, spec.width, spec.height);
+            dispatchCmd(mapping.type, params);
+          }
+        }
+      },
+    });
+  },
+};