pixelweaver 0.1.0

package/server/src/pixelweaver/state.py

@@ -0,0 +1,267 @@
+"""In-memory authoritative state for PixelWeaver projects.
+
+The server is the single source of truth. All state mutations flow through
+ServerState, which is then persisted to disk by the auto-saver.
+"""
+
+from __future__ import annotations
+
+import base64
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from pixelweaver.mcp_lock import MCPLock
+
+
+@dataclass
+class FrameState:
+    """Single animation frame within a canvas.
+
+    Each frame holds its own pixel data per layer. The id is a stable UUID
+    that matches the frontend Frame.id. duration_ms=None means "derive
+    from global_fps".
+    """
+
+    id: str
+    duration_ms: int | None = None
+    pixel_data: dict[str, bytes] = field(default_factory=dict)
+
+
+@dataclass
+class CanvasState:
+    """State for a single canvas within a project."""
+
+    name: str
+    width: int
+    height: int
+    layers: list[dict[str, Any]] = field(default_factory=list)
+    # Pixel data lives exclusively in FrameState.pixel_data (per frame,
+    # per layer). Access via canvas.current_frame().pixel_data[layer_id].
+    frames: list[FrameState] = field(default_factory=list)
+    current_frame_index: int = 0
+    global_fps: float = 12.0
+    origin_x: int = 0
+    origin_y: int = 0
+
+    def current_frame(self) -> FrameState:
+        """Return the currently selected frame (bounds-checked)."""
+        if not self.frames:
+            raise ValueError("Canvas has no frames")
+        idx = max(0, min(self.current_frame_index, len(self.frames) - 1))
+        return self.frames[idx]
+
+    def frame_at(self, index: int) -> FrameState:
+        """Return frame at the given index (bounds-checked)."""
+        if index < 0 or index >= len(self.frames):
+            raise IndexError(
+                f"Frame index {index} out of range [0, {len(self.frames)})"
+            )
+        return self.frames[index]
+
+    @property
+    def frame_count(self) -> int:
+        """Number of frames in this canvas."""
+        return len(self.frames)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a JSON-compatible dict (excludes heavy pixel data)."""
+        return {
+            "name": self.name,
+            "width": self.width,
+            "height": self.height,
+            "layers": self.layers,
+            "frames": [
+                {"id": f.id, "duration_ms": f.duration_ms} for f in self.frames
+            ],
+            "current_frame_index": self.current_frame_index,
+            "global_fps": self.global_fps,
+        }
+
+    def to_full_dict(self) -> dict[str, Any]:
+        """Serialize including info about which layers have pixel data."""
+        d = self.to_dict()
+        d["pixel_data_layers"] = list(self.current_frame().pixel_data.keys())
+        return d
+
+
+@dataclass
+class ProjectState:
+    """State for a single project."""
+
+    name: str
+    width: int
+    height: int
+    canvases: dict[str, CanvasState] = field(default_factory=dict)
+    command_history: list[dict[str, Any]] = field(default_factory=list)
+    # Commands that were undone -- available for redo
+    redo_stack: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a JSON-compatible dict for state sync."""
+        return {
+            "name": self.name,
+            "width": self.width,
+            "height": self.height,
+            "canvases": {k: v.to_dict() for k, v in self.canvases.items()},
+            "history": self.command_history,
+        }
+
+
+class ServerState:
+    """In-memory authoritative state for all projects."""
+
+    def __init__(self) -> None:
+        self.projects: dict[str, ProjectState] = {}
+        self.active_project: str | None = None
+        # Shared mutex protecting concurrent state mutations from MCP tool
+        # calls and WebSocket command handlers within the same process.
+        self.mutation_lock = MCPLock()
+
+    # Hard ceiling on canvas dimensions to prevent OOM allocation.
+    # MCP caps at 1024, REST at 4096; this is the last line of defense.
+    MAX_DIMENSION = 4096
+
+    def create_project(self, name: str, width: int, height: int) -> ProjectState:
+        """Create a new project with a default canvas and layer."""
+        if not (1 <= width <= self.MAX_DIMENSION and 1 <= height <= self.MAX_DIMENSION):
+            raise ValueError(
+                f"Dimensions must be 1..{self.MAX_DIMENSION}, got {width}x{height}"
+            )
+        project = ProjectState(name=name, width=width, height=height)
+
+        # Create one default canvas with a single frame and layer
+        default_layer_id = str(uuid.uuid4())
+        pixel_data = {default_layer_id: bytes(width * height * 4)}
+        frame = FrameState(id=str(uuid.uuid4()), pixel_data=pixel_data)
+        canvas = CanvasState(
+            name="canvas-0",
+            width=width,
+            height=height,
+            layers=[
+                {
+                    "id": default_layer_id,
+                    "name": "Layer 0",
+                    "visible": True,
+                    "opacity": 1.0,
+                }
+            ],
+            frames=[frame],
+        )
+
+        project.canvases["canvas-0"] = canvas
+        self.projects[name] = project
+
+        if self.active_project is None:
+            self.active_project = name
+
+        return project
+
+    def get_project(self, name: str) -> ProjectState | None:
+        """Get a project by name."""
+        return self.projects.get(name)
+
+    def get_active_project(self) -> ProjectState | None:
+        """Get the currently active project."""
+        if self.active_project is None:
+            return None
+        return self.projects.get(self.active_project)
+
+    def delete_project(self, name: str) -> bool:
+        """Delete a project. Returns True if it existed."""
+        if name in self.projects:
+            del self.projects[name]
+            if self.active_project == name:
+                # Switch to another project or None
+                self.active_project = next(iter(self.projects), None)
+            return True
+        return False
+
+    def list_projects(self) -> list[str]:
+        """Return names of all projects."""
+        return list(self.projects.keys())
+
+    def get_sync_state(self, project_name: str | None = None) -> dict[str, Any]:
+        """Build a full state snapshot for a sync response.
+
+        If project_name is None, uses the active project.
+        """
+        name = project_name or self.active_project
+        if name is None or name not in self.projects:
+            return {
+                "project": None,
+                "canvases": {},
+                "layers": {},
+                "history": [],
+            }
+
+        project = self.projects[name]
+        return {
+            "project": {
+                "name": project.name,
+                "width": project.width,
+                "height": project.height,
+            },
+            "canvases": {k: v.to_dict() for k, v in project.canvases.items()},
+            "layers": {
+                canvas_name: canvas.layers
+                for canvas_name, canvas in project.canvases.items()
+            },
+            "history": project.command_history,
+        }
+
+
+def build_full_state_patch(project: ProjectState) -> dict[str, Any]:
+    """Build a full-state patch from the current project state.
+
+    Serializes all canvas data including per-frame pixel buffers as base64
+    strings. Used when MCP modifies state and needs to notify WebSocket
+    clients. Keys are camelCase for JS consumers.
+    """
+    canvases: dict[str, Any] = {}
+    for name, canvas in project.canvases.items():
+        # Layer metadata (without pixel data -- that lives in frames now)
+        layers_data = []
+        for layer in canvas.layers:
+            layers_data.append({
+                "id": layer["id"],
+                "name": layer.get("name", ""),
+                "type": layer.get("type", "pixel"),
+                "visible": layer.get("visible", True),
+                "opacity": layer.get("opacity", 1.0),
+                "blendMode": layer.get("blendMode", "normal"),
+                "locked": layer.get("locked", False),
+            })
+
+        # Per-frame pixel data
+        frames_data = []
+        for frame in canvas.frames:
+            frames_data.append({
+                "id": frame.id,
+                "durationMs": frame.duration_ms,
+                "pixelData": {
+                    layer_id: base64.b64encode(raw_bytes).decode("ascii")
+                    for layer_id, raw_bytes in frame.pixel_data.items()
+                },
+            })
+
+        canvases[name] = {
+            "name": canvas.name,
+            "width": canvas.width,
+            "height": canvas.height,
+            "layers": layers_data,
+            "frames": frames_data,
+            "currentFrameIndex": canvas.current_frame_index,
+            "globalFps": canvas.global_fps,
+            "originX": canvas.origin_x,
+            "originY": canvas.origin_y,
+        }
+    return {
+        "type": "full_state",
+        "snapshot": {
+            "name": project.name,
+            "width": project.width,
+            "height": project.height,
+            "canvases": canvases,
+        },
+    }

package/server/src/pixelweaver/storage.py

@@ -0,0 +1,293 @@
+"""Project file I/O for PixelWeaver.
+
+Saves/loads projects as directory structures:
+    <base_dir>/<project_name>/
+        project.json          -- project metadata
+        canvases/<canvas_name>/
+            canvas.json       -- canvas metadata (dimensions, layer tree)
+            frames.json       -- frame manifest (IDs, durations, playback state)
+            frames/<uuid>/
+                layer-<id>.png  -- raw pixel data as PNG per layer
+            history.json      -- command history for this canvas
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import shutil
+from io import BytesIO
+from pathlib import Path
+from typing import Any
+
+from PIL import Image
+
+from pixelweaver.state import CanvasState, FrameState, ProjectState
+
+logger = logging.getLogger(__name__)
+
+
+def _assert_within_base(project_dir: Path, base_dir: Path) -> None:
+    """Raise ValueError if project_dir escapes base_dir (path traversal guard)."""
+    if not project_dir.resolve().is_relative_to(base_dir.resolve()):
+        raise ValueError(
+            f"Path traversal detected: {project_dir} is not inside {base_dir}"
+        )
+
+
+def save_project(project: ProjectState, base_dir: str) -> None:
+    """Save a project to disk as a directory structure."""
+    project_dir = Path(base_dir) / project.name
+    _assert_within_base(project_dir, Path(base_dir))
+    project_dir.mkdir(parents=True, exist_ok=True)
+
+    # project.json -- top-level metadata
+    project_meta: dict[str, Any] = {
+        "name": project.name,
+        "width": project.width,
+        "height": project.height,
+        "canvases": list(project.canvases.keys()),
+    }
+    (project_dir / "project.json").write_text(json.dumps(project_meta, indent=2))
+
+    # Each canvas
+    for canvas_name, canvas in project.canvases.items():
+        _save_canvas(canvas, project_dir / "canvases" / canvas_name)
+
+    # Global command history (all commands across canvases)
+    (project_dir / "history.json").write_text(json.dumps(project.command_history, indent=2))
+
+
+def _save_canvas(canvas: CanvasState, canvas_dir: Path) -> None:
+    """Save a single canvas to its directory."""
+    canvas_dir.mkdir(parents=True, exist_ok=True)
+
+    # canvas.json -- layer metadata (unchanged)
+    canvas_meta: dict[str, Any] = {
+        "name": canvas.name,
+        "width": canvas.width,
+        "height": canvas.height,
+        "layers": canvas.layers,
+    }
+    (canvas_dir / "canvas.json").write_text(json.dumps(canvas_meta, indent=2))
+
+    # frames.json -- frame manifest with playback state
+    frames_manifest: dict[str, Any] = {
+        "frames": [
+            {"id": frame.id, "duration_ms": frame.duration_ms}
+            for frame in canvas.frames
+        ],
+        "current_frame_index": canvas.current_frame_index,
+        "global_fps": canvas.global_fps,
+        "origin_x": canvas.origin_x,
+        "origin_y": canvas.origin_y,
+    }
+    (canvas_dir / "frames.json").write_text(json.dumps(frames_manifest, indent=2))
+
+    # Collect the set of frame IDs that should exist on disk
+    live_frame_ids = {frame.id for frame in canvas.frames}
+
+    # Save each frame's pixel data in frames/<uuid>/
+    frames_dir = canvas_dir / "frames"
+    frames_dir.mkdir(parents=True, exist_ok=True)
+
+    for frame in canvas.frames:
+        frame_dir = frames_dir / frame.id
+        frame_dir.mkdir(parents=True, exist_ok=True)
+        for layer in canvas.layers:
+            layer_id = layer["id"]
+            pixel_bytes = frame.pixel_data.get(layer_id)
+            if pixel_bytes is None:
+                continue
+            png_path = frame_dir / f"layer-{layer_id}.png"
+            _save_layer_png(pixel_bytes, canvas.width, canvas.height, png_path)
+
+    # Cleanup: remove frame directories that are no longer in canvas.frames
+    # (includes old "0" directory from the pre-UUID format)
+    if frames_dir.is_dir():
+        for child in frames_dir.iterdir():
+            if child.is_dir() and child.name not in live_frame_ids:
+                shutil.rmtree(child)
+
+
+def _save_layer_png(pixel_bytes: bytes, width: int, height: int, path: Path) -> None:
+    """Write raw RGBA bytes as a PNG file."""
+    expected_size = width * height * 4
+    if len(pixel_bytes) != expected_size:
+        logger.warning(
+            "Pixel data size mismatch for %s: expected %d, got %d",
+            path,
+            expected_size,
+            len(pixel_bytes),
+        )
+        return
+
+    img = Image.frombytes("RGBA", (width, height), pixel_bytes)
+    img.save(path, format="PNG")
+
+
+def load_project(project_dir: str) -> ProjectState:
+    """Load a project from its directory on disk."""
+    pdir = Path(project_dir)
+
+    project_meta = json.loads((pdir / "project.json").read_text())
+
+    # Defense-in-depth: the name stored in project.json will be used later by
+    # save_project / autosave.  Verify it cannot escape the parent data dir.
+    loaded_name = project_meta["name"]
+    _assert_within_base(pdir.parent / loaded_name, pdir.parent)
+
+    project = ProjectState(
+        name=loaded_name,
+        width=project_meta["width"],
+        height=project_meta["height"],
+    )
+
+    # Load canvases -- verify each canvas name stays inside the project dir
+    canvas_names: list[str] = project_meta.get("canvases", [])
+    for canvas_name in canvas_names:
+        canvas_dir = pdir / "canvases" / canvas_name
+        _assert_within_base(canvas_dir, pdir)
+        if canvas_dir.is_dir():
+            project.canvases[canvas_name] = _load_canvas(canvas_dir)
+
+    # Load global command history
+    history_path = pdir / "history.json"
+    if history_path.exists():
+        project.command_history = json.loads(history_path.read_text())
+
+    return project
+
+
+def _load_canvas(canvas_dir: Path) -> CanvasState:
+    """Load a single canvas from its directory.
+
+    Requires frames.json to exist. Old pre-UUID format (frames/0/) is not
+    supported -- use the migration script (Step 11) to convert old data.
+    """
+    canvas_meta = json.loads((canvas_dir / "canvas.json").read_text())
+    layers = canvas_meta.get("layers", [])
+
+    frames_json_path = canvas_dir / "frames.json"
+    if not frames_json_path.exists():
+        raise FileNotFoundError(
+            f"Missing frames.json in {canvas_dir}. "
+            "Old format (frames/0/) is no longer supported. "
+            "Run the migration script to convert existing projects."
+        )
+
+    manifest = json.loads(frames_json_path.read_text())
+
+    # Reconstruct each FrameState from manifest + layer PNGs on disk
+    frames: list[FrameState] = []
+    for frame_entry in manifest["frames"]:
+        frame_id = frame_entry["id"]
+        duration_ms = frame_entry.get("duration_ms")
+        pixel_data: dict[str, bytes] = {}
+
+        frame_dir = canvas_dir / "frames" / frame_id
+        for layer in layers:
+            layer_id = layer["id"]
+            png_path = frame_dir / f"layer-{layer_id}.png"
+            if png_path.exists():
+                pixel_data[layer_id] = _load_layer_png(png_path)
+            # Missing PNG = transparent layer (empty bytes not stored)
+
+        frames.append(FrameState(id=frame_id, duration_ms=duration_ms, pixel_data=pixel_data))
+
+    canvas = CanvasState(
+        name=canvas_meta["name"],
+        width=canvas_meta["width"],
+        height=canvas_meta["height"],
+        layers=layers,
+        frames=frames,
+        current_frame_index=manifest.get("current_frame_index", 0),
+        global_fps=manifest.get("global_fps", 12.0),
+        origin_x=manifest.get("origin_x", 0),
+        origin_y=manifest.get("origin_y", 0),
+    )
+
+    return canvas
+
+
+def _load_layer_png(path: Path) -> bytes:
+    """Read a PNG file and return raw RGBA bytes."""
+    img = Image.open(path).convert("RGBA")
+    return img.tobytes()
+
+
+def list_projects(base_dir: str) -> list[str]:
+    """List all project directories that contain a project.json."""
+    base = Path(base_dir)
+    if not base.is_dir():
+        return []
+    return sorted(
+        d.name for d in base.iterdir() if d.is_dir() and (d / "project.json").exists()
+    )
+
+
+def export_frame_png(project: ProjectState, canvas_name: str, frame: int = 0) -> bytes:
+    """Composite all visible layers of a canvas frame into a single PNG.
+
+    Returns PNG bytes suitable for an HTTP response.
+
+    The ``frame`` parameter selects which frame to composite by index.
+    ``canvas.frame_at()`` performs bounds checking and raises ``IndexError``
+    for out-of-range indices.
+    """
+    canvas = project.canvases.get(canvas_name)
+    if canvas is None:
+        raise ValueError(f"Canvas {canvas_name!r} not found")
+
+    # frame_at() raises IndexError for out-of-range indices
+    target_frame = canvas.frame_at(frame)
+
+    # Start with a transparent base image
+    composite = Image.new("RGBA", (canvas.width, canvas.height), (0, 0, 0, 0))
+
+    # Composite visible layers bottom-to-top
+    for layer in canvas.layers:
+        if not layer.get("visible", True):
+            continue
+        layer_id = layer["id"]
+        pixel_bytes = target_frame.pixel_data.get(layer_id)
+        if pixel_bytes is None:
+            continue
+        expected_size = canvas.width * canvas.height * 4
+        if len(pixel_bytes) != expected_size:
+            continue
+        layer_img = Image.frombytes("RGBA", (canvas.width, canvas.height), pixel_bytes)
+        opacity = layer.get("opacity", 1.0)
+        if opacity < 1.0:
+            # Reduce alpha channel by opacity factor
+            r, g, b, a = layer_img.split()
+            a = a.point(lambda x: int(x * opacity))
+            layer_img = Image.merge("RGBA", (r, g, b, a))
+        composite = Image.alpha_composite(composite, layer_img)
+
+    buf = BytesIO()
+    composite.save(buf, format="PNG")
+    return buf.getvalue()
+
+
+def make_thumbnail_base64(png_bytes: bytes, max_size: int = 128) -> str:
+    """Return a base64-encoded PNG thumbnail of the given PNG bytes.
+
+    Used by MCP tool handlers to attach a preview of the active canvas to
+    mutation results without sending the full composited image. The image
+    is only downscaled when one of its dimensions exceeds ``max_size``;
+    smaller images pass through untouched. Nearest-neighbor resampling is
+    used to preserve pixel-art edges.
+
+    This helper replaces the previously inlined ``Image.thumbnail`` calls
+    in ``mcp_registry.py`` and supersedes the deleted ``thumbnails.py``
+    module, which worked from raw RGBA data rather than composited PNG
+    bytes.
+    """
+    img = Image.open(BytesIO(png_bytes))
+    if img.width > max_size or img.height > max_size:
+        img.thumbnail((max_size, max_size), Image.NEAREST)
+    buf = BytesIO()
+    img.save(buf, format="PNG")
+    return base64.b64encode(buf.getvalue()).decode("ascii")