Add flatten_layers tool

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2025-10-18
+
+### Added
+- **Layer Flattening Tool** (`flatten_layers`)
+  - Flattens all layers in a sprite into a single layer
+  - Uses Aseprite's built-in flatten operation
+  - Integration test and example demonstration included
+
 ## [0.4.0] - 2025-10-18
 
 ### Added

CLAUDE.md

@@ -94,7 +94,7 @@ MCP Client → MCP Server (Go) → Lua Script Generation → Aseprite CLI (--bat
 - `pkg/config/` - Configuration management (file-based only)
 - `pkg/server/` - MCP server implementation
 - `pkg/tools/` - MCP tool implementations organized by category:
-  - `canvas.go` - Sprite/layer/frame management (create_sprite, add_layer, add_frame, delete_layer with protection, delete_frame with protection)
+  - `canvas.go` - Sprite/layer/frame management (create_sprite, add_layer, add_frame, delete_layer with protection, delete_frame with protection, flatten_layers)
   - `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 (frame duration, tags, tag deletion, duplication, linked cels)
@@ -130,7 +130,7 @@ MCP Client → MCP Server (Go) → Lua Script Generation → Aseprite CLI (--bat
 
 Core functionality implemented and tested:
 - Canvas creation and management (RGB, Grayscale, Indexed)
-- Layer and frame operations (add, delete with last-layer/frame protection)
+- Layer and frame operations (add, delete with last-layer/frame protection, flatten)
 - Drawing primitives (pixels, lines, rectangles, circles, fill) with optional palette-aware color snapping
 - Advanced drawing: Contour tool for drawing polylines and closed polygons with points arrays
 - **Selection and Clipboard Tools (8 tools):**

README.md

@@ -108,6 +108,7 @@ Then use natural language to create sprites:
 | `create_canvas` | Create new sprite with specified dimensions and color mode |
 | `add_layer` | Add a new layer to the sprite |
 | `delete_layer` | Delete a layer from the sprite (cannot delete last layer) |
+| `flatten_layers` | Flatten all layers in a sprite into a single layer |
 | `get_sprite_info` | Get sprite metadata (size, layers, frames) |
 
 ### Drawing & Painting

cmd/pixel-mcp/main.go

@@ -9,11 +9,11 @@ import (
 	"syscall"
 	"time"
 
-	"github.com/willibrandon/pixel-mcp/pkg/config"
-	"github.com/willibrandon/pixel-mcp/pkg/server"
 	"github.com/willibrandon/mtlog"
 	"github.com/willibrandon/mtlog/core"
 	"github.com/willibrandon/mtlog/sinks"
+	"github.com/willibrandon/pixel-mcp/pkg/config"
+	"github.com/willibrandon/pixel-mcp/pkg/server"
 )
 
 var (

examples/README.md

@@ -11,6 +11,7 @@ The `client/` directory contains a complete example MCP client that demonstrates
 - Connecting to the Aseprite MCP server via stdio transport
 - Creating a 64x64 RGB sprite
 - Adding and deleting layers and frames
+- Flattening multiple layers into a single layer
 - Drawing animated content (growing circles)
 - Drawing polylines and polygons (zigzag, triangle, star)
 - Filling areas with colors
@@ -137,6 +138,7 @@ Available tools:
   - create_canvas: Create a new Aseprite sprite
   - add_layer: Add a new layer to the sprite
   - delete_layer: Delete a layer from the sprite
+  - flatten_layers: Flatten all layers into a single layer
   - add_frame: Add a new frame to the sprite timeline
   - delete_frame: Delete a frame from the sprite
   - get_sprite_info: Get metadata about a sprite
@@ -251,6 +253,9 @@ Step 17: Demonstrating layer and frame deletion...
   Deleted Layer 2 (2 layers remaining)
   Deleted frame 2 (2 frames remaining)
   Final state: {"width":32,"height":32,"color_mode":"RGB","frame_count":2,"layer_count":2,"layers":["Layer 1","Layer 3"]}
+  Flattening remaining 2 layers into 1...
+  Layers flattened successfully
+  After flattening: {"width":32,"height":32,"color_mode":"RGB","frame_count":2,"layer_count":1,"layers":["Layer 1"]}
 
 Step 18: Demonstrating polylines and polygons...
   Drawing zigzag polyline on frame 1...

examples/client/main.go

@@ -814,6 +814,24 @@ func createAnimatedSprite(ctx context.Context, session *mcp.ClientSession, logge
 	}
 	logger.Information("  Final state: {Info}", finalInfoResp)
 
+	// Demonstrate flatten_layers
+	logger.Information("  Flattening remaining 2 layers into 1...")
+	if _, err := callTool(ctx, session, "flatten_layers", map[string]any{
+		"sprite_path": deleteSprite,
+	}); err != nil {
+		return fmt.Errorf("flatten_layers failed: %w", err)
+	}
+	logger.Information("  Layers flattened successfully")
+
+	// Verify flattened state
+	flattenedInfoResp, err := callTool(ctx, session, "get_sprite_info", map[string]any{
+		"sprite_path": deleteSprite,
+	})
+	if err != nil {
+		return fmt.Errorf("get_sprite_info after flattening failed: %w", err)
+	}
+	logger.Information("  After flattening: {Info}", flattenedInfoResp)
+
 	// Step 18: Demonstrate drawing polylines and polygons
 	logger.Information("")
 	logger.Information("Step 18: Demonstrating polylines and polygons...")

examples/quantization/main.go

@@ -107,18 +107,18 @@ func run(logger core.Logger) error {
 	// Draw horizontal gradient bars (red to yellow to green to cyan to blue)
 	// We'll batch pixels to make this much faster
 	colors := []struct{ r, g, b int }{
-		{255, 0, 0},     // Red
-		{255, 128, 0},   // Orange
-		{255, 255, 0},   // Yellow
-		{128, 255, 0},   // Yellow-Green
-		{0, 255, 0},     // Green
-		{0, 255, 128},   // Green-Cyan
-		{0, 255, 255},   // Cyan
-		{0, 128, 255},   // Cyan-Blue
-		{0, 0, 255},     // Blue
-		{128, 0, 255},   // Blue-Magenta
-		{255, 0, 255},   // Magenta
-		{255, 0, 128},   // Magenta-Red
+		{255, 0, 0},   // Red
+		{255, 128, 0}, // Orange
+		{255, 255, 0}, // Yellow
+		{128, 255, 0}, // Yellow-Green
+		{0, 255, 0},   // Green
+		{0, 255, 128}, // Green-Cyan
+		{0, 255, 255}, // Cyan
+		{0, 128, 255}, // Cyan-Blue
+		{0, 0, 255},   // Blue
+		{128, 0, 255}, // Blue-Magenta
+		{255, 0, 255}, // Magenta
+		{255, 0, 128}, // Magenta-Red
 	}
 
 	barHeight := 128 / len(colors)
@@ -189,10 +189,10 @@ func run(logger core.Logger) error {
 
 	// Step 3: Test each quantization algorithm
 	algorithms := []struct {
-		name        string
+		name         string
 		targetColors int
-		dither      bool
-		description string
+		dither       bool
+		description  string
 	}{
 		{"median_cut", 16, false, "Median Cut (balanced, no dither)"},
 		{"median_cut", 16, true, "Median Cut with Floyd-Steinberg dithering"},
@@ -253,12 +253,12 @@ func run(logger core.Logger) error {
 
 		// Apply quantization
 		quantizeResp, err := callTool(ctx, session, "quantize_palette", map[string]any{
-			"sprite_path":            copyPath,
-			"target_colors":          algo.targetColors,
-			"algorithm":              algo.name,
-			"dither":                 algo.dither,
-			"preserve_transparency":  false,
-			"convert_to_indexed":     true,
+			"sprite_path":           copyPath,
+			"target_colors":         algo.targetColors,
+			"algorithm":             algo.name,
+			"dither":                algo.dither,
+			"preserve_transparency": false,
+			"convert_to_indexed":    true,
 		})
 		if err != nil {
 			return fmt.Errorf("quantize_palette failed: %w", err)

pkg/aseprite/lua_auto_shading.go

@@ -126,13 +126,13 @@ spr:saveAs(spr.filename)
 
 -- Print JSON result
 print(json)`,
-		EscapeString(layerName),   // layer name for finding
-		EscapeString(layerName),   // layer name for error
-		tempImagePath,             // shaded image path
-		frameNumber,               // frame number for cel lookup
-		frameNumber,               // frame number for error message
-		frameNumber,               // frame number for newCel
-		colorList,                 // generated colors
-		len(generatedColors),      // colors_added
-		regionsShadedCount)        // regions_shaded
+		EscapeString(layerName), // layer name for finding
+		EscapeString(layerName), // layer name for error
+		tempImagePath,           // shaded image path
+		frameNumber,             // frame number for cel lookup
+		frameNumber,             // frame number for error message
+		frameNumber,             // frame number for newCel
+		colorList,               // generated colors
+		len(generatedColors),    // colors_added
+		regionsShadedCount)      // regions_shaded
 }

pkg/aseprite/lua_drawing.go

@@ -1039,18 +1039,18 @@ print("Dithering applied successfully")`,
 		frameNumber, frameNumber,
 		c1.R, c1.G, c1.B, c1.A,
 		c2.R, c2.G, c2.B, c2.A,
-		width,    // line 915: error buffer width
-		height,   // line 920: py loop
-		width,    // line 925: clear buffer width
-		width,    // line 930: px loop
-		width,    // line 933: width check for division by zero
-		width,    // line 936: gradient calculation
-		width,    // line 967: right neighbor check
-		height,   // line 972: bottom neighbor check
-		width,    // line 981: bottom-right check
-		width,    // line 1007: right neighbor check (RGB)
-		height,   // line 1012: bottom neighbor check (RGB)
-		width,    // line 1021: bottom-right check (RGB)
-		x,        // line 1031: x coordinate
-		y)        // line 1031: y coordinate
+		width,  // line 915: error buffer width
+		height, // line 920: py loop
+		width,  // line 925: clear buffer width
+		width,  // line 930: px loop
+		width,  // line 933: width check for division by zero
+		width,  // line 936: gradient calculation
+		width,  // line 967: right neighbor check
+		height, // line 972: bottom neighbor check
+		width,  // line 981: bottom-right check
+		width,  // line 1007: right neighbor check (RGB)
+		height, // line 1012: bottom neighbor check (RGB)
+		width,  // line 1021: bottom-right check (RGB)
+		x,      // line 1031: x coordinate
+		y)      // line 1031: y coordinate
 }

pkg/aseprite/lua_quantization.go

@@ -121,11 +121,11 @@ spr:saveAs(spr.filename)
 
 -- Print JSON result
 print(json)`,
-		len(palette),           // palette resize
-		colorList,              // color list
-		conversionCode,         // conversion code
-		originalColors,         // original_colors
-		len(palette),           // quantized_colors
+		len(palette),            // palette resize
+		colorList,               // color list
+		conversionCode,          // conversion code
+		originalColors,          // original_colors
+		len(palette),            // quantized_colors
 		EscapeString(algorithm)) // algorithm_used
 }
 

pkg/aseprite/quantization_test.go

@@ -278,10 +278,10 @@ func TestQuantizePalette(t *testing.T) {
 	}
 
 	tests := []struct {
-		name        string
+		name         string
 		targetColors int
-		algorithm   string
-		wantErr     bool
+		algorithm    string
+		wantErr      bool
 	}{
 		{
 			name:         "median_cut to 4 colors",

pkg/server/server.go

@@ -20,10 +20,10 @@ import (
 	"fmt"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/willibrandon/mtlog/core"
 	"github.com/willibrandon/pixel-mcp/pkg/aseprite"
 	"github.com/willibrandon/pixel-mcp/pkg/config"
 	"github.com/willibrandon/pixel-mcp/pkg/tools"
-	"github.com/willibrandon/mtlog/core"
 )
 
 // Server wraps the MCP server and provides Aseprite tool implementations.

pkg/server/server_test.go

@@ -3,9 +3,9 @@ package server
 import (
 	"testing"
 
-	"github.com/willibrandon/pixel-mcp/internal/testutil"
 	"github.com/willibrandon/mtlog"
 	"github.com/willibrandon/mtlog/sinks"
+	"github.com/willibrandon/pixel-mcp/internal/testutil"
 )
 
 func TestNew(t *testing.T) {

pkg/tools/analysis.go

@@ -10,9 +10,9 @@ import (
 	"os"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/willibrandon/mtlog/core"
 	"github.com/willibrandon/pixel-mcp/pkg/aseprite"
 	"github.com/willibrandon/pixel-mcp/pkg/config"
-	"github.com/willibrandon/mtlog/core"
 )
 
 // AnalyzeReferenceInput defines the input parameters for the analyze_reference tool.

pkg/tools/analysis_test.go

@@ -13,10 +13,10 @@ import (
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"github.com/willibrandon/pixel-mcp/internal/testutil"
-	"github.com/willibrandon/pixel-mcp/pkg/aseprite"
 	"github.com/willibrandon/mtlog"
 	"github.com/willibrandon/mtlog/core"
+	"github.com/willibrandon/pixel-mcp/internal/testutil"
+	"github.com/willibrandon/pixel-mcp/pkg/aseprite"
 )
 
 // createAnalysisTestSession creates an MCP session with analysis tools registered

pkg/tools/animation.go

@@ -6,9 +6,9 @@ import (
 	"strings"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/willibrandon/mtlog/core"
 	"github.com/willibrandon/pixel-mcp/pkg/aseprite"
 	"github.com/willibrandon/pixel-mcp/pkg/config"
-	"github.com/willibrandon/mtlog/core"
 )
 
 // SetFrameDurationInput defines the input parameters for the set_frame_duration tool.

pkg/tools/animation_integration_test.go

@@ -11,10 +11,10 @@ import (
 	"testing"
 	"time"
 
-	"github.com/willibrandon/pixel-mcp/internal/testutil"
-	"github.com/willibrandon/pixel-mcp/pkg/aseprite"
 	"github.com/willibrandon/mtlog"
 	"github.com/willibrandon/mtlog/sinks"
+	"github.com/willibrandon/pixel-mcp/internal/testutil"
+	"github.com/willibrandon/pixel-mcp/pkg/aseprite"
 )
 
 // Integration tests for animation tools with real Aseprite.

pkg/tools/animation_test.go

@@ -9,10 +9,10 @@ import (
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"github.com/willibrandon/pixel-mcp/internal/testutil"
-	"github.com/willibrandon/pixel-mcp/pkg/aseprite"
 	"github.com/willibrandon/mtlog"
 	"github.com/willibrandon/mtlog/core"
+	"github.com/willibrandon/pixel-mcp/internal/testutil"
+	"github.com/willibrandon/pixel-mcp/pkg/aseprite"
 )
 
 func TestSetFrameDurationInput_Validation(t *testing.T) {

pkg/tools/antialiasing.go

@@ -7,9 +7,9 @@ import (
 	"math"
 
 	"github.com/modelcontextprotocol/go-sdk/mcp"
+	"github.com/willibrandon/mtlog/core"
 	"github.com/willibrandon/pixel-mcp/pkg/aseprite"
 	"github.com/willibrandon/pixel-mcp/pkg/config"
-	"github.com/willibrandon/mtlog/core"
 )
 
 // SuggestAntialiasingInput defines the input parameters for antialiasing suggestions.

pkg/tools/antialiasing_mcp_test.go

@@ -9,10 +9,10 @@ import (
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
-	"github.com/willibrandon/pixel-mcp/internal/testutil"
-	"github.com/willibrandon/pixel-mcp/pkg/aseprite"
 	"github.com/willibrandon/mtlog"
 	"github.com/willibrandon/mtlog/core"
+	"github.com/willibrandon/pixel-mcp/internal/testutil"
+	"github.com/willibrandon/pixel-mcp/pkg/aseprite"
 )
 
 // createAntialiasingTestSession creates an MCP session with antialiasing tools registered