pixelweaver 0.1.0

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

@@ -0,0 +1,174 @@
+/**
+ * Aseprite Importer Plugin -- registers an importer for .ase/.aseprite files.
+ *
+ * Converts parsed Aseprite data into PixelWeaver's internal state:
+ * canvas dimensions, layers, frames with pixel data, and palette.
+ */
+
+import type { PluginModule } from '../../../src/lib/core/plugin-loader.js';
+import type { PluginAPI } from '../../../src/lib/core/plugin-types.js';
+import FileImage from '~icons/lucide/file-image';
+import { parseAseprite } from './aseprite-parser.js';
+import type { Palette } from '../../../src/lib/color/palette.js';
+import type { AsepriteLayer } from './aseprite-parser.js';
+import { rgbToHex } from '../../../src/lib/color/color-utils.js';
+
+/**
+ * Build a PixelWeaver layer tree from the flat Aseprite layer list.
+ * Aseprite layers use childLevel to indicate nesting depth; we reconstruct
+ * the parent-child relationships and create PW layers accordingly.
+ *
+ * Returns a map from Aseprite layer index to PixelWeaver layer ID.
+ */
+function createLayerTree(api: PluginAPI, aseLayers: AsepriteLayer[]): Map<number, string> {
+  const indexToId = new Map<number, string>();
+
+  // Track the group stack: each entry is the PW group layer ID at that depth.
+  // childLevel 0 = root, childLevel 1 = inside a depth-0 group, etc.
+  const groupStack: string[] = [];
+
+  for (let i = 0; i < aseLayers.length; i++) {
+    const aseLayer = aseLayers[i];
+    if (!aseLayer) continue;
+
+    // Trim the group stack to match the current child level
+    while (groupStack.length > aseLayer.childLevel) {
+      groupStack.pop();
+    }
+
+    const parentId = groupStack.length > 0 ? groupStack[groupStack.length - 1] : undefined;
+    const isVisible = (aseLayer.flags & 1) !== 0;
+    // Aseprite opacity is 0-255, PixelWeaver uses 0-100
+    const pwOpacity = Math.round((aseLayer.opacity / 255) * 100);
+
+    // Build options object, omitting parentId entirely when undefined
+    // (exactOptionalPropertyTypes disallows passing { parentId: undefined })
+    const layerOptions = parentId !== undefined ? { parentId } : {};
+
+    if (aseLayer.type === 1) {
+      // Group layer
+      const groupId = api.addGroup(aseLayer.name, layerOptions);
+      api.setLayerVisibility(groupId, isVisible);
+      api.setLayerOpacity(groupId, pwOpacity);
+      indexToId.set(i, groupId);
+      groupStack.push(groupId);
+    } else {
+      // Pixel layer (type 0) or tilemap (type 2, treated as pixel)
+      const layerId = api.addLayer(aseLayer.name, layerOptions);
+      api.setLayerVisibility(layerId, isVisible);
+      api.setLayerOpacity(layerId, pwOpacity);
+      indexToId.set(i, layerId);
+    }
+  }
+
+  return indexToId;
+}
+
+export const asepriteImporterPlugin: PluginModule = {
+  name: 'builtin/import-aseprite',
+  version: '1.0.0',
+  description: 'Import Aseprite .ase/.aseprite files',
+
+  register(api) {
+    api.addCommand('import_aseprite', {
+      tier: 'project',
+      execute() { /* Will be wired to file picker */ },
+      undo() {},
+      describe() { return 'Import Aseprite file'; },
+      label: 'Aseprite (.ase/.aseprite)',
+      category: 'File',
+      icon: FileImage,
+    });
+    api.addMenuItem('menu:file:import:aseprite', {
+      commandId: 'import_aseprite',
+      menuPath: 'file/import',
+      group: 'import',
+      order: 10,
+      label: 'Aseprite (.ase/.aseprite)',
+    });
+
+    api.addImporter('aseprite', {
+      label: 'Aseprite File',
+      extensions: ['ase', 'aseprite'],
+
+      async import(data) {
+        const buffer = data instanceof File ? await data.arrayBuffer() : data;
+        const aseFile = await parseAseprite(buffer);
+
+        // 1. Set canvas dimensions
+        api.setCanvasSize(aseFile.width, aseFile.height);
+
+        // 2. Clear existing layers and frames to start fresh
+        api.deserializeLayers({ layers: [], activeLayerId: '' });
+        api.deserializeFrames({
+          frames: [],
+          currentFrameIndex: 0,
+          globalFps: 12,
+          originX: 0,
+          originY: 0,
+        });
+
+        // 3. Create PixelWeaver layers from the Aseprite layer list
+        const layerIndexToId = createLayerTree(api, aseFile.layers);
+
+        // 4. Create frames and populate pixel data
+        for (let f = 0; f < aseFile.frames.length; f++) {
+          const aseFrame = aseFile.frames[f];
+          if (!aseFrame) continue;
+          const frameIndex = api.addFrame({ afterIndex: f - 1 });
+
+          // Set per-frame duration if specified
+          if (aseFrame.duration > 0) {
+            api.setFrameDuration(frameIndex, aseFrame.duration);
+          }
+
+          // Copy cel pixel data into each layer's PixelBuffer for this frame
+          for (const cel of aseFrame.cels) {
+            const layerId = layerIndexToId.get(cel.layerIndex);
+            if (!layerId) continue; // layer not mapped (e.g., unsupported type)
+            if (cel.pixels.length === 0) continue; // empty or unsupported cel
+
+            // Create a full-canvas-sized PixelBuffer and place cel pixels at (cel.x, cel.y)
+            const pixelBuffer = api.createPixelBuffer(aseFile.width, aseFile.height);
+
+            for (let py = 0; py < cel.height; py++) {
+              for (let px = 0; px < cel.width; px++) {
+                const srcIdx = (py * cel.width + px) * 4;
+                const destX = cel.x + px;
+                const destY = cel.y + py;
+                pixelBuffer.setPixel(
+                  destX,
+                  destY,
+                  cel.pixels[srcIdx] ?? 0,
+                  cel.pixels[srcIdx + 1] ?? 0,
+                  cel.pixels[srcIdx + 2] ?? 0,
+                  cel.pixels[srcIdx + 3] ?? 0,
+                );
+              }
+            }
+
+            api.setFramePixelData(frameIndex, layerId, pixelBuffer);
+          }
+        }
+
+        // Select the first frame
+        if (api.getFrames().length > 0) {
+          api.setCurrentFrame(0);
+        }
+
+        // 5. Set the project palette from Aseprite colors
+        if (aseFile.palette.length > 0) {
+          const palette: Palette = {
+            name: 'Imported (Aseprite)',
+            colors: aseFile.palette
+              .filter((c) => c.a > 0) // skip fully transparent entries
+              .map((c) => rgbToHex(c.r, c.g, c.b)),
+          };
+          // Deduplicate colors while preserving order
+          palette.colors = [...new Set(palette.colors)];
+          api.setProjectPalette(palette);
+        }
+      },
+    });
+  },
+};

package/plugins/builtin/importers/aseprite-parser.ts

@@ -0,0 +1,497 @@
+/**
+ * Aseprite (.ase/.aseprite) binary file parser.
+ *
+ * Parses the binary format into a structured AsepriteFile object with layers,
+ * frames, cels, and palette data. All pixel data is normalized to RGBA
+ * regardless of the source color depth (indexed, grayscale, or RGBA).
+ *
+ * Format spec: https://github.com/aseprite/aseprite/blob/main/docs/ase-file-specs.md
+ * All multi-byte integers are little-endian.
+ */
+
+// --- Public types ---
+
+export interface AsepriteFile {
+  width: number;
+  height: number;
+  colorDepth: number; // 8 = indexed, 16 = grayscale, 32 = RGBA
+  transparentIndex: number;
+  frames: AsepriteFrame[];
+  layers: AsepriteLayer[];
+  palette: AsepriteColor[];
+}
+
+export interface AsepriteFrame {
+  duration: number; // milliseconds
+  cels: AsepriteCel[];
+}
+
+export interface AsepriteLayer {
+  name: string;
+  flags: number; // bit 0: visible, bit 1: editable, bit 4: group
+  type: number; // 0 = normal (image), 1 = group, 2 = tilemap
+  opacity: number; // 0-255
+  blendMode: number;
+  childLevel: number; // nesting depth (0 = root)
+}
+
+export interface AsepriteCel {
+  layerIndex: number;
+  x: number;
+  y: number;
+  opacity: number; // 0-255
+  width: number;
+  height: number;
+  pixels: Uint8Array; // always RGBA, 4 bytes per pixel
+  linkedFrame?: number; // if this cel references another frame's cel
+}
+
+export interface AsepriteColor {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+  name?: string;
+}
+
+// --- Constants ---
+
+const FILE_MAGIC = 0xa5e0;
+const FRAME_MAGIC = 0xf1fa;
+
+// Chunk type identifiers
+const CHUNK_LAYER = 0x2004;
+const CHUNK_CEL = 0x2005;
+const CHUNK_PALETTE = 0x2019;
+const CHUNK_OLD_PALETTE_1 = 0x0004; // legacy palette (fallback for indexed files)
+const CHUNK_OLD_PALETTE_2 = 0x0011; // legacy palette variant
+
+// Cel type identifiers
+const CEL_RAW = 0;
+const CEL_LINKED = 1;
+const CEL_COMPRESSED = 2;
+const CEL_COMPRESSED_TILEMAP = 3;
+
+// --- Binary reader helper ---
+
+/**
+ * Wraps a DataView with a position cursor for sequential reads.
+ * All reads are little-endian as per the Aseprite format.
+ */
+class BinaryReader {
+  private view: DataView;
+  pos: number;
+
+  constructor(buffer: ArrayBuffer, offset = 0) {
+    this.view = new DataView(buffer);
+    this.pos = offset;
+  }
+
+  byte(): number {
+    const v = this.view.getUint8(this.pos);
+    this.pos += 1;
+    return v;
+  }
+
+  word(): number {
+    const v = this.view.getUint16(this.pos, true);
+    this.pos += 2;
+    return v;
+  }
+
+  short(): number {
+    const v = this.view.getInt16(this.pos, true);
+    this.pos += 2;
+    return v;
+  }
+
+  dword(): number {
+    const v = this.view.getUint32(this.pos, true);
+    this.pos += 4;
+    return v;
+  }
+
+  /** Read a STRING: WORD length prefix followed by UTF-8 bytes. */
+  string(): string {
+    const len = this.word();
+    const bytes = new Uint8Array(this.view.buffer, this.pos, len);
+    this.pos += len;
+    return new TextDecoder().decode(bytes);
+  }
+
+  /** Read raw bytes without advancing the position cursor. */
+  bytes(length: number): Uint8Array {
+    const result = new Uint8Array(this.view.buffer, this.pos, length);
+    this.pos += length;
+    return result;
+  }
+
+  /** Skip forward by n bytes. */
+  skip(n: number): void {
+    this.pos += n;
+  }
+}
+
+// --- Zlib decompression using browser DecompressionStream ---
+
+async function decompress(data: Uint8Array): Promise<Uint8Array> {
+  // DecompressionStream('deflate') handles raw deflate; Aseprite uses zlib
+  // which is deflate with a zlib header -- 'deflate' mode in the Web API
+  // actually handles the zlib wrapper (RFC 1950), not raw deflate (RFC 1951).
+  const ds = new DecompressionStream('deflate');
+  const writer = ds.writable.getWriter();
+  void writer.write(data as unknown as BufferSource);
+  void writer.close();
+  const reader = ds.readable.getReader();
+  const chunks: Uint8Array[] = [];
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+  }
+  const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+  const result = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return result;
+}
+
+// --- Pixel format conversion ---
+
+/**
+ * Convert indexed pixel data to RGBA using the palette.
+ * Pixels matching transparentIndex become fully transparent.
+ */
+function indexedToRgba(
+  indexed: Uint8Array,
+  palette: AsepriteColor[],
+  transparentIndex: number,
+): Uint8Array {
+  const rgba = new Uint8Array(indexed.length * 4);
+  for (let i = 0; i < indexed.length; i++) {
+    const idx = indexed[i];
+    const out = i * 4;
+    if (idx === undefined || idx === transparentIndex) {
+      // Fully transparent
+      rgba[out] = 0;
+      rgba[out + 1] = 0;
+      rgba[out + 2] = 0;
+      rgba[out + 3] = 0;
+    } else if (idx < palette.length) {
+      const entry = palette[idx];
+      if (entry) {
+        rgba[out] = entry.r;
+        rgba[out + 1] = entry.g;
+        rgba[out + 2] = entry.b;
+        rgba[out + 3] = entry.a;
+      }
+    } else {
+      // Out-of-range index: treat as transparent
+      rgba[out] = 0;
+      rgba[out + 1] = 0;
+      rgba[out + 2] = 0;
+      rgba[out + 3] = 0;
+    }
+  }
+  return rgba;
+}
+
+/**
+ * Convert grayscale pixel data (2 bytes per pixel: gray, alpha) to RGBA.
+ */
+function grayscaleToRgba(gray: Uint8Array): Uint8Array {
+  const pixelCount = gray.length / 2;
+  const rgba = new Uint8Array(pixelCount * 4);
+  for (let i = 0; i < pixelCount; i++) {
+    const g = gray[i * 2] ?? 0;
+    const a = gray[i * 2 + 1] ?? 0;
+    const out = i * 4;
+    rgba[out] = g;
+    rgba[out + 1] = g;
+    rgba[out + 2] = g;
+    rgba[out + 3] = a;
+  }
+  return rgba;
+}
+
+// --- Chunk parsers ---
+
+function parseLayerChunk(reader: BinaryReader): AsepriteLayer {
+  const flags = reader.word();
+  const type = reader.word();
+  const childLevel = reader.word();
+  reader.word(); // default width (ignored)
+  reader.word(); // default height (ignored)
+  const blendMode = reader.word();
+  const opacity = reader.byte();
+  reader.skip(3); // reserved
+  const name = reader.string();
+
+  return { name, flags, type, opacity, blendMode, childLevel };
+}
+
+/**
+ * Parse the cel chunk header and raw/compressed pixel data.
+ * Returns the cel metadata; pixel data for compressed cels is decompressed asynchronously.
+ */
+async function parseCelChunk(
+  reader: BinaryReader,
+  chunkEnd: number,
+  colorDepth: number,
+  palette: AsepriteColor[],
+  transparentIndex: number,
+): Promise<AsepriteCel> {
+  const layerIndex = reader.word();
+  const x = reader.short();
+  const y = reader.short();
+  const opacity = reader.byte();
+  const celType = reader.word();
+  reader.skip(7); // reserved / z-index (not needed)
+
+  if (celType === CEL_LINKED) {
+    // Linked cel: references pixels from another frame
+    const frameIndex = reader.word();
+    return {
+      layerIndex,
+      x,
+      y,
+      opacity,
+      width: 0,
+      height: 0,
+      pixels: new Uint8Array(0),
+      linkedFrame: frameIndex,
+    };
+  }
+
+  if (celType === CEL_COMPRESSED_TILEMAP) {
+    // Tilemap cels are not supported; skip the rest
+    return {
+      layerIndex,
+      x,
+      y,
+      opacity,
+      width: 0,
+      height: 0,
+      pixels: new Uint8Array(0),
+    };
+  }
+
+  const width = reader.word();
+  const height = reader.word();
+
+  let rawPixels: Uint8Array;
+
+  if (celType === CEL_RAW) {
+    // Bytes per pixel depends on color depth: 4 (RGBA), 2 (grayscale), 1 (indexed)
+    const bpp = colorDepth / 8;
+    rawPixels = reader.bytes(width * height * bpp);
+  } else if (celType === CEL_COMPRESSED) {
+    // Remaining bytes in this chunk are zlib-compressed pixel data
+    const compressedSize = chunkEnd - reader.pos;
+    const compressed = reader.bytes(compressedSize);
+    rawPixels = await decompress(compressed);
+  } else {
+    // Unknown cel type; return empty
+    return { layerIndex, x, y, opacity, width, height, pixels: new Uint8Array(0) };
+  }
+
+  // Convert to RGBA based on color depth
+  let rgbaPixels: Uint8Array;
+  if (colorDepth === 32) {
+    rgbaPixels = rawPixels;
+  } else if (colorDepth === 16) {
+    rgbaPixels = grayscaleToRgba(rawPixels);
+  } else {
+    // colorDepth === 8 (indexed)
+    rgbaPixels = indexedToRgba(rawPixels, palette, transparentIndex);
+  }
+
+  return { layerIndex, x, y, opacity, width, height, pixels: rgbaPixels };
+}
+
+function parsePaletteChunk(reader: BinaryReader): AsepriteColor[] {
+  const size = reader.dword();
+  const firstIndex = reader.dword();
+  const lastIndex = reader.dword();
+  reader.skip(8); // reserved
+
+  // Pre-fill with transparent black for indices before firstIndex
+  const colors: AsepriteColor[] = Array.from(
+    { length: size },
+    (): AsepriteColor => ({ r: 0, g: 0, b: 0, a: 255 }),
+  );
+
+  for (let i = firstIndex; i <= lastIndex; i++) {
+    const flags = reader.word();
+    const r = reader.byte();
+    const g = reader.byte();
+    const b = reader.byte();
+    const a = reader.byte();
+    // Omit name when absent (exactOptionalPropertyTypes disallows explicit undefined)
+    const color: AsepriteColor = { r, g, b, a };
+    if (flags & 1) {
+      color.name = reader.string();
+    }
+    colors[i] = color;
+  }
+
+  return colors;
+}
+
+/**
+ * Parse the legacy palette chunk (0x0004).
+ * Used as a fallback when no new-format palette chunk (0x2019) is present.
+ */
+function parseOldPaletteChunk(reader: BinaryReader): AsepriteColor[] {
+  const numPackets = reader.word();
+  const colors: AsepriteColor[] = [];
+
+  for (let p = 0; p < numPackets; p++) {
+    const skipCount = reader.byte(); // entries to skip from current position
+    let count = reader.byte(); // number of colors in this packet
+    if (count === 0) count = 256;
+    // Pad skipped slots with black
+    for (let s = 0; s < skipCount; s++) {
+      colors.push({ r: 0, g: 0, b: 0, a: 255 });
+    }
+    for (let c = 0; c < count; c++) {
+      const r = reader.byte();
+      const g = reader.byte();
+      const b = reader.byte();
+      colors.push({ r, g, b, a: 255 });
+    }
+  }
+
+  return colors;
+}
+
+// --- Main parser ---
+
+/**
+ * Parse an Aseprite file from an ArrayBuffer.
+ * Returns the complete file structure with all layers, frames, cels, and palette.
+ */
+export async function parseAseprite(buffer: ArrayBuffer): Promise<AsepriteFile> {
+  const reader = new BinaryReader(buffer);
+
+  // --- File header (128 bytes) ---
+  reader.dword(); // bytes 0-3: file size (not needed for parsing)
+  const magic = reader.word(); // bytes 4-5
+  if (magic !== FILE_MAGIC) {
+    throw new Error(`Not a valid Aseprite file (magic: 0x${magic.toString(16)}, expected 0x${FILE_MAGIC.toString(16)})`);
+  }
+
+  const frameCount = reader.word(); // bytes 6-7
+  const width = reader.word(); // bytes 8-9
+  const height = reader.word(); // bytes 10-11
+  const colorDepth = reader.word(); // bytes 12-13
+  reader.dword(); // bytes 14-17: flags (unused)
+  reader.skip(10); // bytes 18-27: deprecated speed, reserved
+  const transparentIndex = reader.byte(); // byte 28
+  reader.skip(99); // bytes 29-127: remaining header padding
+
+  const layers: AsepriteLayer[] = [];
+  let palette: AsepriteColor[] = [];
+  let hasNewPalette = false;
+  const frames: AsepriteFrame[] = [];
+
+  // --- Parse frames ---
+  for (let f = 0; f < frameCount; f++) {
+    const frameStart = reader.pos;
+
+    // Frame header (16 bytes)
+    const frameSizeBytes = reader.dword();
+    const frameMagic = reader.word();
+    if (frameMagic !== FRAME_MAGIC) {
+      throw new Error(`Invalid frame magic at frame ${String(f)} (0x${frameMagic.toString(16)})`);
+    }
+
+    const oldChunkCount = reader.word();
+    const duration = reader.word();
+    reader.skip(2); // reserved
+    const newChunkCount = reader.dword();
+
+    // Use new chunk count if available, otherwise fall back to old
+    const chunkCount = newChunkCount !== 0 ? newChunkCount : oldChunkCount;
+
+    const cels: AsepriteCel[] = [];
+
+    // --- Parse chunks within this frame ---
+    for (let c = 0; c < chunkCount; c++) {
+      const chunkStart = reader.pos;
+      const chunkSize = reader.dword();
+      const chunkType = reader.word();
+      const chunkEnd = chunkStart + chunkSize;
+
+      switch (chunkType) {
+        case CHUNK_LAYER:
+          layers.push(parseLayerChunk(reader));
+          break;
+
+        case CHUNK_CEL:
+          cels.push(
+            await parseCelChunk(reader, chunkEnd, colorDepth, palette, transparentIndex),
+          );
+          break;
+
+        case CHUNK_PALETTE:
+          palette = parsePaletteChunk(reader);
+          hasNewPalette = true;
+          break;
+
+        case CHUNK_OLD_PALETTE_1:
+        case CHUNK_OLD_PALETTE_2:
+          // Only use legacy palette if no new-format palette has been seen
+          if (!hasNewPalette) {
+            palette = parseOldPaletteChunk(reader);
+          }
+          break;
+
+        // Other chunk types (tags, slices, user data, etc.) are skipped
+      }
+
+      // Advance to end of chunk regardless of how much was read
+      reader.pos = chunkEnd;
+    }
+
+    frames.push({ duration, cels });
+
+    // Advance to end of frame in case of padding
+    reader.pos = frameStart + frameSizeBytes;
+  }
+
+  // --- Resolve linked cels ---
+  // Linked cels reference the pixels of the same layer in another frame.
+  for (const frame of frames) {
+    for (let i = 0; i < frame.cels.length; i++) {
+      const cel = frame.cels[i];
+      if (!cel) continue;
+      if (cel.linkedFrame !== undefined && cel.pixels.length === 0) {
+        const sourceFrame = frames[cel.linkedFrame];
+        if (sourceFrame) {
+          const sourceCel = sourceFrame.cels.find(
+            (sc) => sc.layerIndex === cel.layerIndex && sc.linkedFrame === undefined,
+          );
+          if (sourceCel) {
+            // Rebuild without linkedFrame so exactOptionalPropertyTypes is happy
+            const rebuilt: AsepriteCel = {
+              width: sourceCel.width,
+              height: sourceCel.height,
+              pixels: sourceCel.pixels,
+              x: sourceCel.x,
+              y: sourceCel.y,
+              layerIndex: cel.layerIndex,
+              opacity: cel.opacity,
+            };
+            frame.cels[i] = rebuilt;
+          }
+        }
+      }
+    }
+  }
+
+  return { width, height, colorDepth, transparentIndex, frames, layers, palette };
+}