feat(export): add advanced export and import tools

- Add export_spritesheet tool with 5 layout options (horizontal/vertical/rows/columns/packed)
- Add optional JSON metadata export for spritesheets with frame data and animation tags
- Add import_image tool to import external images as layers with optional positioning
- Add save_as tool to save sprites to new .aseprite file paths
- Add delete_tag tool to remove animation tags by name
- Implement 4 Lua generators: ExportSpritesheet, ImportImage, SaveAs, DeleteTag
- Add comprehensive unit tests (6 subtests) and integration tests (7 tests)
- Update example client with Step 22 demonstrating all Phase 5 tools
- Update README.md and CLAUDE.md documentation with new tools
- All Phase 5 tests passing with real Aseprite

Author: willibrandon

CLAUDE.md

@@ -87,13 +87,13 @@ MCP Client → MCP Server (Go) → Lua Script Generation → Aseprite CLI (--bat
   - `canvas.go` - Sprite/layer/frame management (create_sprite, add_layer, add_frame, delete_layer with protection, delete_frame with protection)
   - `drawing.go` - Drawing primitives (pixels, lines, rectangles, circles, fill, contours for polylines/polygons)
   - `selection.go` - Selection and clipboard operations (8 tools)
-  - `animation.go` - Animation and timeline operations
+  - `animation.go` - Animation and timeline operations (frame duration, tags, tag deletion, duplication, linked cels)
   - `inspection.go` - Pixel data inspection and reading
   - `analysis.go` - Reference image analysis (palette extraction, edge detection, composition)
   - `dithering.go` - Dithering patterns for gradients and textures (15 patterns)
   - `palette_tools.go` - Palette management (set_palette, apply_shading, analyze_palette_harmonies)
   - `transform.go` - Transform operations (flip, rotate, scale, crop, resize canvas, outline, downsampling)
-  - `export.go` - Export and import operations
+  - `export.go` - Export and import operations (export_sprite, export_spritesheet, import_image, save_as)
 - `internal/testutil/` - Testing utilities (no mocks)
 
 ### Core Workflow
@@ -126,7 +126,7 @@ Core functionality implemented and tested:
   - Select all, deselect, move selection
   - Cut, copy, paste operations
   - **Important limitation**: Selections are transient and do NOT persist in .aseprite files - they only exist in memory during script execution
-- Animation tools (frame duration, tags, duplication, linked cels)
+- Animation tools (frame duration, tags, tag deletion, duplication, linked cels)
 - Inspection tools (pixel data reading with pagination for verification and analysis)
 - **Professional Pixel Art Tools:**
   - Reference image analysis (k-means palette extraction, brightness maps, Sobel edge detection)
@@ -150,7 +150,11 @@ Core functionality implemented and tested:
     - `crop_sprite`: Crop to rectangular region
     - `resize_canvas`: Resize canvas with anchor positioning (5 anchor points)
     - `apply_outline`: Apply outline effect with color and thickness
-- Sprite export (PNG, GIF, JPG, BMP)
+- **Export & Import Tools (4 tools):**
+  - `export_sprite`: Export to PNG/GIF/JPG/BMP formats
+  - `export_spritesheet`: Export animation frames as spritesheet with 5 layout options (horizontal/vertical/rows/columns/packed), configurable padding, and optional JSON metadata
+  - `import_image`: Import external images as layers with optional positioning
+  - `save_as`: Save sprite to new .aseprite file path
 - Metadata retrieval
 - Example client implementation (examples/client/main.go)
 - Integration test suite with real Aseprite

README.md

@@ -148,6 +148,7 @@ Then use natural language to create sprites:
 | `delete_frame` | Delete a frame from the sprite (cannot delete last frame) |
 | `set_frame_duration` | Set the duration of an animation frame in milliseconds |
 | `create_tag` | Create an animation tag with playback direction |
+| `delete_tag` | Delete an animation tag by name |
 | `duplicate_frame` | Duplicate an existing frame with all cels |
 | `link_cel` | Create a linked cel that shares image data |
 
@@ -156,6 +157,9 @@ Then use natural language to create sprites:
 |------|-------------|
 | `get_pixels` | Read pixel data from a rectangular region (paginated, for verification) |
 | `export_sprite` | Export sprite to PNG/GIF/JPG/BMP |
+| `export_spritesheet` | Export animation frames as spritesheet (horizontal/vertical/rows/columns/packed layout, optional JSON metadata) |
+| `import_image` | Import external image file as a layer in the sprite |
+| `save_as` | Save sprite to a new .aseprite file path |
 
 ## Examples
 

examples/README.md

@@ -63,6 +63,10 @@ The example creates:
 - `../sprites/antialiasing-before.png` - Jagged diagonal line (stair-step pattern)
 - `../sprites/antialiasing-after.png` - Smoothed diagonal with intermediate colors applied
 - `../sprites/transform-demo.png` - Transform operations: triangle flipped, rotated, and scaled 2x
+- `../sprites/animation-spritesheet.png` - 4-frame horizontal spritesheet with growing colored circles
+- `../sprites/animation-spritesheet.json` - JSON metadata for spritesheet
+- `../sprites/saved-animation.aseprite` - Sprite saved with save_as tool
+- `../sprites/imported-spritesheet.png` - Result of importing spritesheet as layer
 - `/tmp/selection-demo.png` - Drawing demo showing red squares and blue circle
 
 ## Example Output
@@ -105,6 +109,10 @@ Available tools:
   - crop_sprite: Crop sprite to rectangular region
   - resize_canvas: Resize canvas with anchor positioning
   - apply_outline: Apply outline effect to layer with thickness
+  - export_spritesheet: Export animation frames as spritesheet with layout options
+  - import_image: Import external image file as a layer
+  - save_as: Save sprite to a new .aseprite file path
+  - delete_tag: Delete an animation tag by name
   - select_rectangle: Create rectangular selection with mode (replace/add/subtract/intersect)
   - select_ellipse: Create elliptical selection with mode
   - select_all: Select entire canvas
@@ -232,6 +240,21 @@ Step 21: Demonstrating selection and clipboard operations...
   ✓ Result saved to: /tmp/selection-demo.png
   Note: Selection tools work within single Lua scripts but don't persist across tool calls
 
+Step 22: Demonstrating advanced export tools (spritesheet, import, save_as, delete_tag)...
+  Creating 16x16 animated sprite with 4 frames...
+  Creating animation tags...
+  Exporting as horizontal spritesheet with JSON metadata...
+  ✓ Exported spritesheet: ../sprites/animation-spritesheet.png (4 frames)
+  ✓ JSON metadata: ../sprites/animation-spritesheet.json
+  Deleting temporary tag 'temp_tag'...
+  ✓ Tag deleted successfully
+  Saving sprite to new location...
+  ✓ Sprite saved to: ../sprites/saved-animation.aseprite
+  Creating new sprite to import spritesheet...
+  Importing spritesheet as a layer...
+  ✓ Spritesheet imported as layer
+  ✓ Exported imported result: ../sprites/imported-spritesheet.png
+
 Example completed successfully!
 ```
 

examples/client/main.go

@@ -1186,6 +1186,190 @@ func createAnimatedSprite(ctx context.Context, session *mcp.ClientSession, logge
 	logger.Information("  ✓ Result saved to: {OutputPath}", selectionOutputPath)
 	logger.Information("  Note: Selection tools work within single Lua scripts but don't persist across tool calls")
 
+	// Step 22: Demonstrate advanced export tools
+	logger.Information("")
+	logger.Information("Step 22: Demonstrating advanced export tools (spritesheet, import, save_as, delete_tag)...")
+
+	// Create an animated sprite for spritesheet export
+	logger.Information("  Creating 16x16 animated sprite with 4 frames...")
+	output, err = callTool(ctx, session, "create_canvas", map[string]any{
+		"width":      16,
+		"height":     16,
+		"color_mode": "rgb",
+	})
+	if err != nil {
+		return fmt.Errorf("create_canvas for spritesheet failed: %w", err)
+	}
+
+	var sheetCreateOutput struct {
+		FilePath string `json:"file_path"`
+	}
+	if err := json.Unmarshal([]byte(output), &sheetCreateOutput); err != nil {
+		return fmt.Errorf("failed to parse create_canvas output: %w", err)
+	}
+	sheetSpritePath := sheetCreateOutput.FilePath
+	defer os.Remove(sheetSpritePath)
+
+	// Add 3 more frames (total 4)
+	for i := 0; i < 3; i++ {
+		_, err = callTool(ctx, session, "add_frame", map[string]any{
+			"sprite_path": sheetSpritePath,
+			"duration_ms": 100,
+		})
+		if err != nil {
+			return fmt.Errorf("add_frame failed: %w", err)
+		}
+	}
+
+	// Draw different colored circles on each frame
+	colors2 := []string{"#FF0000", "#00FF00", "#0000FF", "#FFFF00"}
+	for i := 0; i < 4; i++ {
+		_, err = callTool(ctx, session, "draw_circle", map[string]any{
+			"sprite_path":  sheetSpritePath,
+			"layer_name":   "Layer 1",
+			"frame_number": i + 1,
+			"center_x":     8,
+			"center_y":     8,
+			"radius":       4 + i,
+			"color":        colors2[i],
+			"filled":       true,
+		})
+		if err != nil {
+			return fmt.Errorf("draw_circle frame %d failed: %w", i+1, err)
+		}
+	}
+
+	// Create animation tags
+	logger.Information("  Creating animation tags...")
+	_, err = callTool(ctx, session, "create_tag", map[string]any{
+		"sprite_path": sheetSpritePath,
+		"tag_name":    "grow",
+		"from_frame":  1,
+		"to_frame":    4,
+		"direction":   "forward",
+	})
+	if err != nil {
+		return fmt.Errorf("create_tag failed: %w", err)
+	}
+
+	_, err = callTool(ctx, session, "create_tag", map[string]any{
+		"sprite_path": sheetSpritePath,
+		"tag_name":    "temp_tag",
+		"from_frame":  1,
+		"to_frame":    2,
+		"direction":   "pingpong",
+	})
+	if err != nil {
+		return fmt.Errorf("create second tag failed: %w", err)
+	}
+
+	// Export as spritesheet with JSON metadata
+	sheetPath := filepath.Join(outputDir, "animation-spritesheet.png")
+	logger.Information("  Exporting as horizontal spritesheet with JSON metadata...")
+	sheetOutput, err := callTool(ctx, session, "export_spritesheet", map[string]any{
+		"sprite_path":  sheetSpritePath,
+		"output_path":  sheetPath,
+		"layout":       "horizontal",
+		"padding":      2,
+		"include_json": true,
+	})
+	if err != nil {
+		return fmt.Errorf("export_spritesheet failed: %w", err)
+	}
+
+	var sheetResult struct {
+		SpritesheetPath string  `json:"spritesheet_path"`
+		MetadataPath    *string `json:"metadata_path"`
+		FrameCount      int     `json:"frame_count"`
+	}
+	if err := json.Unmarshal([]byte(sheetOutput), &sheetResult); err != nil {
+		return fmt.Errorf("failed to parse export_spritesheet output: %w", err)
+	}
+	logger.Information("  ✓ Exported spritesheet: {Path} ({Count} frames)", sheetResult.SpritesheetPath, sheetResult.FrameCount)
+	if sheetResult.MetadataPath != nil {
+		logger.Information("  ✓ JSON metadata: {Path}", *sheetResult.MetadataPath)
+	}
+
+	// Delete the temporary tag
+	logger.Information("  Deleting temporary tag 'temp_tag'...")
+	_, err = callTool(ctx, session, "delete_tag", map[string]any{
+		"sprite_path": sheetSpritePath,
+		"tag_name":    "temp_tag",
+	})
+	if err != nil {
+		return fmt.Errorf("delete_tag failed: %w", err)
+	}
+	logger.Information("  ✓ Tag deleted successfully")
+
+	// Save the sprite to a new location
+	savedSpritePath := filepath.Join(outputDir, "saved-animation.aseprite")
+	logger.Information("  Saving sprite to new location...")
+	saveOutput, err := callTool(ctx, session, "save_as", map[string]any{
+		"sprite_path": sheetSpritePath,
+		"output_path": savedSpritePath,
+	})
+	if err != nil {
+		return fmt.Errorf("save_as failed: %w", err)
+	}
+
+	var saveResult struct {
+		Success  bool   `json:"success"`
+		FilePath string `json:"file_path"`
+	}
+	if err := json.Unmarshal([]byte(saveOutput), &saveResult); err != nil {
+		return fmt.Errorf("failed to parse save_as output: %w", err)
+	}
+	logger.Information("  ✓ Sprite saved to: {Path}", saveResult.FilePath)
+
+	// Import the spritesheet back into a new sprite
+	logger.Information("  Creating new sprite to import spritesheet...")
+	output, err = callTool(ctx, session, "create_canvas", map[string]any{
+		"width":      64,
+		"height":     32,
+		"color_mode": "rgb",
+	})
+	if err != nil {
+		return fmt.Errorf("create_canvas for import failed: %w", err)
+	}
+
+	var importCreateOutput struct {
+		FilePath string `json:"file_path"`
+	}
+	if err := json.Unmarshal([]byte(output), &importCreateOutput); err != nil {
+		return fmt.Errorf("failed to parse create_canvas output: %w", err)
+	}
+	importSpritePath := importCreateOutput.FilePath
+	defer os.Remove(importSpritePath)
+
+	logger.Information("  Importing spritesheet as a layer...")
+	_, err = callTool(ctx, session, "import_image", map[string]any{
+		"sprite_path":  importSpritePath,
+		"image_path":   sheetPath,
+		"layer_name":   "Spritesheet",
+		"frame_number": 1,
+		"position": map[string]any{
+			"x": 0,
+			"y": 0,
+		},
+	})
+	if err != nil {
+		return fmt.Errorf("import_image failed: %w", err)
+	}
+	logger.Information("  ✓ Spritesheet imported as layer")
+
+	// Export the result
+	importResultPath := filepath.Join(outputDir, "imported-spritesheet.png")
+	_, err = callTool(ctx, session, "export_sprite", map[string]any{
+		"sprite_path":  importSpritePath,
+		"output_path":  importResultPath,
+		"format":       "png",
+		"frame_number": 0,
+	})
+	if err != nil {
+		return fmt.Errorf("export imported sprite failed: %w", err)
+	}
+	logger.Information("  ✓ Exported imported result: {Path}", importResultPath)
+
 	return nil
 }
 

examples/sprites/animation-spritesheet..json

@@ -0,0 +1,52 @@
+{ "frames": {
+   "sprite-1759478144095359000 0.aseprite": {
+    "frame": { "x": 2, "y": 2, "w": 20, "h": 20 },
+    "rotated": false,
+    "trimmed": false,
+    "spriteSourceSize": { "x": 0, "y": 0, "w": 16, "h": 16 },
+    "sourceSize": { "w": 16, "h": 16 },
+    "duration": 100
+   },
+   "sprite-1759478144095359000 1.aseprite": {
+    "frame": { "x": 24, "y": 2, "w": 20, "h": 20 },
+    "rotated": false,
+    "trimmed": false,
+    "spriteSourceSize": { "x": 0, "y": 0, "w": 16, "h": 16 },
+    "sourceSize": { "w": 16, "h": 16 },
+    "duration": 100
+   },
+   "sprite-1759478144095359000 2.aseprite": {
+    "frame": { "x": 46, "y": 2, "w": 20, "h": 20 },
+    "rotated": false,
+    "trimmed": false,
+    "spriteSourceSize": { "x": 0, "y": 0, "w": 16, "h": 16 },
+    "sourceSize": { "w": 16, "h": 16 },
+    "duration": 100
+   },
+   "sprite-1759478144095359000 3.aseprite": {
+    "frame": { "x": 68, "y": 2, "w": 20, "h": 20 },
+    "rotated": false,
+    "trimmed": false,
+    "spriteSourceSize": { "x": 0, "y": 0, "w": 16, "h": 16 },
+    "sourceSize": { "w": 16, "h": 16 },
+    "duration": 100
+   }
+ },
+ "meta": {
+  "app": "https://www.aseprite.org/",
+  "version": "1.x-dev",
+  "image": "animation-spritesheet.png",
+  "format": "RGBA8888",
+  "size": { "w": 90, "h": 24 },
+  "scale": "1",
+  "frameTags": [
+   { "name": "grow", "from": 0, "to": 3, "direction": "forward", "color": "#000000ff" },
+   { "name": "temp_tag", "from": 0, "to": 1, "direction": "pingpong", "color": "#000000ff" }
+  ],
+  "layers": [
+   { "name": "Layer 1", "opacity": 255, "blendMode": "normal" }
+  ],
+  "slices": [
+  ]
+ }
+}