pixelweaver 0.1.0

package/server/src/pixelweaver/mcp_frame_tools.py

@@ -0,0 +1,423 @@
+"""Frame tools for MCP registry.
+
+Provides real server-side state mutations for animation frame operations,
+plus read-only introspection tools. Each mutation handler:
+  1. Validates the active project/canvas
+  2. Mutates CanvasState.frames directly
+  3. Dispatches the command to WebSocket clients (frontend undo stack)
+  4. Broadcasts a full state patch so all clients see the change
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from .mcp_registry import ToolDef
+from .state import FrameState, build_full_state_patch
+
+if TYPE_CHECKING:
+    from .mcp_registry import MCPCommandRegistry
+
+
+def _get_canvas(registry: MCPCommandRegistry) -> Any:
+    """Return the first canvas of the active project, or an error dict."""
+    project = registry.state.get_active_project()
+    if project is None:
+        return {"success": False, "error": "No active project"}
+    canvas = next(iter(project.canvases.values()), None)
+    if canvas is None:
+        return {"success": False, "error": "No canvas in project"}
+    return canvas
+
+
+async def _broadcast_state(registry: MCPCommandRegistry) -> None:
+    """Broadcast a full state patch to all WebSocket clients."""
+    project = registry.state.get_active_project()
+    if project is None:
+        return
+    patch = build_full_state_patch(project)
+    await registry.connections.broadcast({
+        "type": "state_patch",
+        "patches": [patch],
+    })
+
+
+def register_frame_tools(registry: MCPCommandRegistry) -> None:
+    """Register all frame/animation-related MCP tools."""
+
+    # -- add_frame -----------------------------------------------------------
+
+    async def handle_add_frame(args: dict[str, Any]) -> dict[str, Any]:
+        err = registry._require_active_project()
+        if err:
+            return err
+        canvas = _get_canvas(registry)
+        if isinstance(canvas, dict):
+            return canvas
+
+        after_index = args.get("after_index", canvas.current_frame_index)
+        if after_index < -1 or after_index >= canvas.frame_count:
+            return {
+                "success": False,
+                "error": f"after_index {after_index} out of range [-1, {canvas.frame_count - 1}]",
+            }
+
+        new_frame = FrameState(id=str(uuid.uuid4()), pixel_data={})
+        insert_pos = after_index + 1
+        canvas.frames.insert(insert_pos, new_frame)
+
+        await registry._dispatch_command("add_frame", args)
+        await _broadcast_state(registry)
+
+        return {
+            "success": True,
+            "frame_id": new_frame.id,
+            "frame_count": canvas.frame_count,
+        }
+
+    registry._register(
+        ToolDef(
+            "add_frame",
+            "Add a new animation frame",
+            {
+                "type": "object",
+                "properties": {
+                    "after_index": {
+                        "type": "integer",
+                        "description": "Insert after this frame index (default: current frame)",
+                    },
+                },
+            },
+            mutates=True,
+        ),
+        handle_add_frame,
+    )
+
+    # -- remove_frame --------------------------------------------------------
+
+    async def handle_remove_frame(args: dict[str, Any]) -> dict[str, Any]:
+        err = registry._require_active_project()
+        if err:
+            return err
+        canvas = _get_canvas(registry)
+        if isinstance(canvas, dict):
+            return canvas
+
+        frame_index = args["frame_index"]
+        if canvas.frame_count <= 1:
+            return {"success": False, "error": "Cannot remove the last frame"}
+
+        if frame_index < 0 or frame_index >= canvas.frame_count:
+            return {
+                "success": False,
+                "error": f"frame_index {frame_index} out of range [0, {canvas.frame_count - 1}]",
+            }
+
+        canvas.frames.pop(frame_index)
+
+        # Adjust current_frame_index to stay valid
+        if canvas.current_frame_index >= canvas.frame_count:
+            canvas.current_frame_index = canvas.frame_count - 1
+
+        await registry._dispatch_command("remove_frame", args)
+        await _broadcast_state(registry)
+
+        return {"success": True, "frame_count": canvas.frame_count}
+
+    registry._register(
+        ToolDef(
+            "remove_frame",
+            "Remove an animation frame",
+            {
+                "type": "object",
+                "properties": {
+                    "frame_index": {"type": "integer"},
+                },
+                "required": ["frame_index"],
+            },
+            mutates=True,
+        ),
+        handle_remove_frame,
+    )
+
+    # -- duplicate_frame -----------------------------------------------------
+
+    async def handle_duplicate_frame(args: dict[str, Any]) -> dict[str, Any]:
+        err = registry._require_active_project()
+        if err:
+            return err
+        canvas = _get_canvas(registry)
+        if isinstance(canvas, dict):
+            return canvas
+
+        frame_index = args["frame_index"]
+        if frame_index < 0 or frame_index >= canvas.frame_count:
+            return {
+                "success": False,
+                "error": f"frame_index {frame_index} out of range [0, {canvas.frame_count - 1}]",
+            }
+
+        source = canvas.frames[frame_index]
+        # Deep-copy pixel data via bytearray round-trip to guarantee a fresh
+        # object (CPython interns all-zero bytes, so bytes(data) may alias)
+        new_pixel_data = {
+            layer_id: bytes(bytearray(data))
+            for layer_id, data in source.pixel_data.items()
+        }
+        new_frame = FrameState(
+            id=str(uuid.uuid4()),
+            duration_ms=source.duration_ms,
+            pixel_data=new_pixel_data,
+        )
+        canvas.frames.insert(frame_index + 1, new_frame)
+
+        await registry._dispatch_command("duplicate_frame", args)
+        await _broadcast_state(registry)
+
+        return {
+            "success": True,
+            "frame_id": new_frame.id,
+            "source_frame_id": source.id,
+            "frame_count": canvas.frame_count,
+        }
+
+    registry._register(
+        ToolDef(
+            "duplicate_frame",
+            "Duplicate an existing frame",
+            {
+                "type": "object",
+                "properties": {
+                    "frame_index": {"type": "integer"},
+                },
+                "required": ["frame_index"],
+            },
+            mutates=True,
+        ),
+        handle_duplicate_frame,
+    )
+
+    # -- reorder_frame -------------------------------------------------------
+
+    async def handle_reorder_frame(args: dict[str, Any]) -> dict[str, Any]:
+        err = registry._require_active_project()
+        if err:
+            return err
+        canvas = _get_canvas(registry)
+        if isinstance(canvas, dict):
+            return canvas
+
+        from_index = args["from_index"]
+        to_index = args["to_index"]
+
+        if from_index < 0 or from_index >= canvas.frame_count:
+            return {
+                "success": False,
+                "error": f"from_index {from_index} out of range [0, {canvas.frame_count - 1}]",
+            }
+        if to_index < 0 or to_index >= canvas.frame_count:
+            return {
+                "success": False,
+                "error": f"to_index {to_index} out of range [0, {canvas.frame_count - 1}]",
+            }
+
+        # Track the frame that current_frame_index points to
+        current_frame = canvas.frames[canvas.current_frame_index]
+        frame = canvas.frames.pop(from_index)
+        canvas.frames.insert(to_index, frame)
+        # Adjust current_frame_index to track the same frame
+        canvas.current_frame_index = canvas.frames.index(current_frame)
+
+        await registry._dispatch_command("reorder_frame", args)
+        await _broadcast_state(registry)
+
+        return {"success": True, "frame_count": canvas.frame_count}
+
+    registry._register(
+        ToolDef(
+            "reorder_frame",
+            "Move a frame to a new position",
+            {
+                "type": "object",
+                "properties": {
+                    "from_index": {"type": "integer"},
+                    "to_index": {"type": "integer"},
+                },
+                "required": ["from_index", "to_index"],
+            },
+            mutates=True,
+        ),
+        handle_reorder_frame,
+    )
+
+    # -- set_frame_duration --------------------------------------------------
+
+    async def handle_set_frame_duration(args: dict[str, Any]) -> dict[str, Any]:
+        err = registry._require_active_project()
+        if err:
+            return err
+        canvas = _get_canvas(registry)
+        if isinstance(canvas, dict):
+            return canvas
+
+        frame_index = args["frame_index"]
+        if frame_index < 0 or frame_index >= canvas.frame_count:
+            return {
+                "success": False,
+                "error": f"frame_index {frame_index} out of range [0, {canvas.frame_count - 1}]",
+            }
+
+        # duration_ms can be int or null (None = derive from global_fps)
+        duration_ms = args.get("duration_ms")
+        canvas.frames[frame_index].duration_ms = duration_ms
+
+        await registry._dispatch_command("set_frame_duration", args)
+        await _broadcast_state(registry)
+
+        return {"success": True, "frame_index": frame_index, "duration_ms": duration_ms}
+
+    registry._register(
+        ToolDef(
+            "set_frame_duration",
+            "Set duration for a specific frame in milliseconds",
+            {
+                "type": "object",
+                "properties": {
+                    "frame_index": {"type": "integer"},
+                    "duration_ms": {
+                        "type": ["integer", "null"],
+                        "minimum": 1,
+                        "description": "Duration in ms, or null to use global FPS",
+                    },
+                },
+                "required": ["frame_index", "duration_ms"],
+            },
+            mutates=True,
+        ),
+        handle_set_frame_duration,
+    )
+
+    # -- set_global_fps ------------------------------------------------------
+
+    async def handle_set_global_fps(args: dict[str, Any]) -> dict[str, Any]:
+        err = registry._require_active_project()
+        if err:
+            return err
+        canvas = _get_canvas(registry)
+        if isinstance(canvas, dict):
+            return canvas
+
+        fps = args["fps"]
+        canvas.global_fps = max(1.0, min(float(fps), 120.0))
+
+        await registry._dispatch_command("set_global_fps", args)
+        await _broadcast_state(registry)
+
+        return {"success": True, "global_fps": canvas.global_fps}
+
+    registry._register(
+        ToolDef(
+            "set_global_fps",
+            "Set the global frames per second for animation",
+            {
+                "type": "object",
+                "properties": {
+                    "fps": {"type": "number", "minimum": 0.1, "maximum": 120},
+                },
+                "required": ["fps"],
+            },
+            mutates=True,
+        ),
+        handle_set_global_fps,
+    )
+
+    # -- get_frame_count (read-only) -----------------------------------------
+
+    async def handle_get_frame_count(_args: dict[str, Any]) -> dict[str, Any]:
+        canvas = _get_canvas(registry)
+        if isinstance(canvas, dict):
+            return canvas
+        return {
+            "success": True,
+            "count": canvas.frame_count,
+            "current_index": canvas.current_frame_index,
+            "global_fps": canvas.global_fps,
+        }
+
+    registry._register(
+        ToolDef(
+            "get_frame_count",
+            "Get the number of frames, current frame index, and global FPS",
+            {"type": "object", "properties": {}},
+            mutates=False,
+        ),
+        handle_get_frame_count,
+    )
+
+    # -- get_current_frame (read-only) ---------------------------------------
+
+    async def handle_get_current_frame(_args: dict[str, Any]) -> dict[str, Any]:
+        canvas = _get_canvas(registry)
+        if isinstance(canvas, dict):
+            return canvas
+        frame = canvas.current_frame()
+        return {
+            "success": True,
+            "index": canvas.current_frame_index,
+            "id": frame.id,
+            "duration_ms": frame.duration_ms,
+        }
+
+    registry._register(
+        ToolDef(
+            "get_current_frame",
+            "Get info about the currently selected frame",
+            {"type": "object", "properties": {}},
+            mutates=False,
+        ),
+        handle_get_current_frame,
+    )
+
+    # -- set_current_frame ---------------------------------------------------
+
+    async def handle_set_current_frame(args: dict[str, Any]) -> dict[str, Any]:
+        err = registry._require_active_project()
+        if err:
+            return err
+        canvas = _get_canvas(registry)
+        if isinstance(canvas, dict):
+            return canvas
+
+        frame_index = args["frame_index"]
+        if frame_index < 0 or frame_index >= canvas.frame_count:
+            return {
+                "success": False,
+                "error": f"frame_index {frame_index} out of range [0, {canvas.frame_count - 1}]",
+            }
+
+        canvas.current_frame_index = frame_index
+
+        await _broadcast_state(registry)
+
+        return {
+            "success": True,
+            "current_frame_index": canvas.current_frame_index,
+            "frame_id": canvas.current_frame().id,
+        }
+
+    registry._register(
+        ToolDef(
+            "set_current_frame",
+            "Set the currently active frame by index",
+            {
+                "type": "object",
+                "properties": {
+                    "frame_index": {"type": "integer"},
+                },
+                "required": ["frame_index"],
+            },
+            mutates=True,
+        ),
+        handle_set_current_frame,
+    )

package/server/src/pixelweaver/mcp_history_tools.py

@@ -0,0 +1,106 @@
+"""History tools for MCP registry."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .mcp_registry import MCPCommandRegistry
+
+from .mcp_registry import ToolDef
+
+
+def register_history_tools(registry: MCPCommandRegistry) -> None:
+    """Register all history-related MCP tools."""
+
+    # undo
+    async def handle_undo(_args: dict[str, Any]) -> dict[str, Any]:
+        project = registry.state.get_active_project()
+        if project is None:
+            return {"success": False, "error": "No active project"}
+        if not project.command_history:
+            return {"success": False, "error": "Nothing to undo"}
+
+        undone = project.command_history.pop()
+        project.redo_stack.append(undone)
+
+        await registry.connections.broadcast({
+            "type": "command_broadcast",
+            "command": {"type": "undo", "undone": undone},
+            "source": "mcp",
+        })
+
+        return {"success": True, "undone_command": undone.get("type", "unknown")}
+
+    registry._register(
+        ToolDef(
+            "undo",
+            "Undo the last command",
+            {"type": "object", "properties": {}},
+            mutates=True,
+        ),
+        handle_undo,
+    )
+
+    # redo
+    async def handle_redo(_args: dict[str, Any]) -> dict[str, Any]:
+        project = registry.state.get_active_project()
+        if project is None:
+            return {"success": False, "error": "No active project"}
+        if not project.redo_stack:
+            return {"success": False, "error": "Nothing to redo"}
+
+        redone = project.redo_stack.pop()
+        project.command_history.append(redone)
+
+        await registry.connections.broadcast({
+            "type": "command_broadcast",
+            "command": {"type": "redo", "redone": redone},
+            "source": "mcp",
+        })
+
+        return {"success": True, "redone_command": redone.get("type", "unknown")}
+
+    registry._register(
+        ToolDef(
+            "redo",
+            "Redo the last undone command",
+            {"type": "object", "properties": {}},
+            mutates=True,
+        ),
+        handle_redo,
+    )
+
+    # get_action_log
+    async def handle_get_action_log(args: dict[str, Any]) -> dict[str, Any]:
+        project = registry.state.get_active_project()
+        if project is None:
+            return {"success": False, "error": "No active project"}
+
+        limit = args.get("limit", 20)
+        history = project.command_history[-limit:]
+        entries = [
+            {"type": cmd.get("type"), "id": cmd.get("id"), "timestamp": cmd.get("timestamp")}
+            for cmd in history
+        ]
+        return {
+            "success": True,
+            "actions": entries,
+            "total": len(project.command_history),
+            "redo_available": len(project.redo_stack),
+        }
+
+    registry._register(
+        ToolDef(
+            "get_action_log",
+            "Get the recent command history",
+            {
+                "type": "object",
+                "properties": {
+                    "limit": {"type": "integer", "default": 20},
+                },
+            },
+            mutates=False,
+        ),
+        handle_get_action_log,
+    )

package/server/src/pixelweaver/mcp_layer_tools.py

@@ -0,0 +1,64 @@
+"""Layer tools for MCP registry."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .mcp_registry import MCPCommandRegistry
+
+
+def register_layer_tools(registry: MCPCommandRegistry) -> None:
+    """Register all layer-related MCP tools."""
+    layer_tools = [
+        ("add_layer", "Add a new layer to the active canvas", {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Layer name"},
+                "above_layer_id": {"type": "string", "description": "Insert above this layer"},
+            },
+            "required": ["name"],
+        }),
+        ("remove_layer", "Remove a layer by ID", {
+            "type": "object",
+            "properties": {
+                "layer_id": {"type": "string"},
+            },
+            "required": ["layer_id"],
+        }),
+        ("rename_layer", "Rename a layer", {
+            "type": "object",
+            "properties": {
+                "layer_id": {"type": "string"},
+                "name": {"type": "string"},
+            },
+            "required": ["layer_id", "name"],
+        }),
+        ("move_layer", "Move a layer to a new position in the stack", {
+            "type": "object",
+            "properties": {
+                "layer_id": {"type": "string"},
+                "position": {"type": "integer", "description": "New index (0 = bottom)"},
+            },
+            "required": ["layer_id", "position"],
+        }),
+        ("set_layer_visibility", "Show or hide a layer", {
+            "type": "object",
+            "properties": {
+                "layer_id": {"type": "string"},
+                "visible": {"type": "boolean"},
+            },
+            "required": ["layer_id", "visible"],
+        }),
+        ("set_layer_opacity", "Set layer opacity (0.0 - 1.0)", {
+            "type": "object",
+            "properties": {
+                "layer_id": {"type": "string"},
+                "opacity": {"type": "number", "minimum": 0.0, "maximum": 1.0},
+            },
+            "required": ["layer_id", "opacity"],
+        }),
+    ]
+
+    for name, desc, schema in layer_tools:
+        registry._register_drawing_tool(name, desc, schema)

package/server/src/pixelweaver/mcp_lock.py

@@ -0,0 +1,37 @@
+"""Mutex for MCP command execution.
+
+Prevents race conditions between concurrent MCP and UI mutations.
+Use as an async context manager: ``async with mcp_lock: ...``
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+
+class MCPLock:
+    """Async mutex for serializing MCP tool execution."""
+
+    def __init__(self) -> None:
+        self._lock = asyncio.Lock()
+
+    async def acquire(self) -> None:
+        """Acquire the lock (blocks until available)."""
+        await self._lock.acquire()
+
+    def release(self) -> None:
+        """Release the lock."""
+        self._lock.release()
+
+    @property
+    def is_locked(self) -> bool:
+        """Whether the lock is currently held."""
+        return self._lock.locked()
+
+    async def __aenter__(self) -> "MCPLock":
+        await self.acquire()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self.release()