pixelweaver 0.1.0

package/server/src/pixelweaver/websocket.py

@@ -0,0 +1,282 @@
+"""WebSocket message handler for PixelWeaver.
+
+Routes incoming messages to the appropriate handler based on type, validates
+them through the protocol models, and coordinates responses/broadcasts.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from collections.abc import Callable
+from typing import Any
+
+from wesktop import WebSocket
+
+from pixelweaver.connections import ConnectionManager
+from pixelweaver.protocol import (
+    CommandMessage,
+    RedoMessage,
+    UndoMessage,
+    parse_client_message,
+)
+from pixelweaver.state import ServerState, build_full_state_patch
+
+logger = logging.getLogger(__name__)
+
+# Callback type for notifying the auto-saver that state changed
+DirtyCallback = Callable[[], None] | None
+
+
+async def handle_message(
+    websocket: WebSocket,
+    raw: dict[str, Any],
+    state: ServerState,
+    manager: ConnectionManager,
+    on_dirty: DirtyCallback = None,
+) -> None:
+    """Dispatch a parsed JSON message from a client.
+
+    Never raises -- all errors are sent back to the client as error messages.
+    """
+    try:
+        msg = parse_client_message(raw)
+    except (ValueError, Exception) as exc:
+        # Malformed message -- send error back
+        msg_id = raw.get("id", str(uuid.uuid4()))
+        await manager.send(
+            websocket,
+            {"type": "error", "id": msg_id, "error": f"Invalid message: {exc}"},
+        )
+        return
+
+    match msg:
+        case CommandMessage():
+            await _handle_command(websocket, msg, state, manager, on_dirty)
+        case _ if msg.type == "sync_request":
+            await _handle_sync_request(websocket, msg, state, manager)
+        case UndoMessage():
+            await _handle_undo(websocket, msg, state, manager, on_dirty)
+        case RedoMessage():
+            await _handle_redo(websocket, msg, state, manager, on_dirty)
+
+
+async def _handle_command(
+    websocket: WebSocket,
+    msg: CommandMessage,
+    state: ServerState,
+    manager: ConnectionManager,
+    on_dirty: DirtyCallback = None,
+) -> None:
+    """Validate command, store in history, ack sender, broadcast to others."""
+    project = state.get_active_project()
+    if project is None:
+        await manager.send(
+            websocket,
+            {
+                "type": "command_reject",
+                "id": msg.id,
+                "command_id": msg.command.id,
+                "error": "No active project",
+            },
+        )
+        return
+
+    # Store command in history (as a plain dict for JSON serialization).
+    # Hold the shared lock so we don't interleave with an in-flight MCP
+    # mutation -- both paths must see a consistent history/redo stack.
+    cmd_dict = msg.command.model_dump()
+    async with state.mutation_lock:
+        project.command_history.append(cmd_dict)
+        # Any new command clears the redo stack
+        project.redo_stack.clear()
+
+    # Ack the sender
+    await manager.send(
+        websocket,
+        {
+            "type": "command_ack",
+            "id": msg.id,
+            "command_id": msg.command.id,
+            "success": True,
+        },
+    )
+
+    # Broadcast to other clients
+    await manager.broadcast(
+        {"type": "command_broadcast", "command": cmd_dict, "source": "client"},
+        exclude=websocket,
+    )
+
+    if on_dirty:
+        on_dirty()
+
+
+async def _handle_sync_request(
+    websocket: WebSocket,
+    msg: Any,
+    state: ServerState,
+    manager: ConnectionManager,
+) -> None:
+    """Send full state snapshot to the requesting client."""
+    sync_state = state.get_sync_state()
+    await manager.send(
+        websocket,
+        {
+            "type": "state_sync",
+            "id": msg.id,
+            "state": sync_state,
+        },
+    )
+
+
+async def _handle_undo(
+    websocket: WebSocket,
+    msg: UndoMessage,
+    state: ServerState,
+    manager: ConnectionManager,
+    on_dirty: DirtyCallback = None,
+) -> None:
+    """Pop last command from history onto redo stack."""
+    # Lock around the check + pop so a concurrent MCP/WS mutation can't race
+    # the empty-history guard. The lock is released before any I/O.
+    undone: dict[str, Any] | None = None
+    error: str | None = None
+    async with state.mutation_lock:
+        project = state.get_active_project()
+        if project is None:
+            error = "No active project"
+        elif not project.command_history:
+            error = "Nothing to undo"
+        else:
+            undone = project.command_history.pop()
+            project.redo_stack.append(undone)
+
+    if undone is None:
+        await manager.send(
+            websocket,
+            {"type": "error", "id": msg.id, "error": error},
+        )
+        return
+
+    await manager.send(
+        websocket,
+        {
+            "type": "command_ack",
+            "id": msg.id,
+            "command_id": undone["id"],
+            "success": True,
+        },
+    )
+
+    # Broadcast undo to other clients
+    undo_broadcast = {
+        "type": "command_broadcast",
+        "command": {"type": "undo", "undone": undone},
+        "source": "client",
+    }
+    await manager.broadcast(undo_broadcast, exclude=websocket)
+
+    if on_dirty:
+        on_dirty()
+
+
+async def _handle_redo(
+    websocket: WebSocket,
+    msg: RedoMessage,
+    state: ServerState,
+    manager: ConnectionManager,
+    on_dirty: DirtyCallback = None,
+) -> None:
+    """Pop last undone command from redo stack back into history."""
+    redone: dict[str, Any] | None = None
+    error: str | None = None
+    async with state.mutation_lock:
+        project = state.get_active_project()
+        if project is None:
+            error = "No active project"
+        elif not project.redo_stack:
+            error = "Nothing to redo"
+        else:
+            redone = project.redo_stack.pop()
+            project.command_history.append(redone)
+
+    if redone is None:
+        await manager.send(
+            websocket,
+            {"type": "error", "id": msg.id, "error": error},
+        )
+        return
+
+    await manager.send(
+        websocket,
+        {
+            "type": "command_ack",
+            "id": msg.id,
+            "command_id": redone["id"],
+            "success": True,
+        },
+    )
+
+    # Broadcast redo to other clients
+    redo_broadcast = {
+        "type": "command_broadcast",
+        "command": {"type": "redo", "redone": redone},
+        "source": "client",
+    }
+    await manager.broadcast(redo_broadcast, exclude=websocket)
+
+    if on_dirty:
+        on_dirty()
+
+
+# ---------------------------------------------------------------------------
+# Patch broadcasting -- used by MCP when it mutates server state
+# ---------------------------------------------------------------------------
+
+
+async def broadcast_patches(
+    connections: ConnectionManager,
+    project_name: str,
+    patches: list[dict[str, Any]],
+    command_id: str | None = None,
+    exclude_ws: WebSocket | None = None,
+) -> None:
+    """Broadcast data patches to all connected WebSocket clients.
+
+    After MCP modifies server state, call this with the resulting patches
+    so every frontend can apply the changes.  *exclude_ws* allows skipping
+    the originating client (e.g. the one that sent a frontend command --
+    it already applied the mutation locally).
+    """
+    message = {
+        "type": "state_patch",
+        "project_name": project_name,
+        "patches": patches,
+        "command_id": command_id,
+    }
+    await connections.broadcast(message, exclude=exclude_ws)
+
+
+async def broadcast_full_state(
+    state: ServerState,
+    connections: ConnectionManager,
+    project_name: str | None = None,
+    command_id: str | None = None,
+    exclude_ws: WebSocket | None = None,
+) -> None:
+    """Build a full-state patch from the active project and broadcast it.
+
+    Convenience wrapper combining build_full_state_patch + broadcast_patches.
+    Used by MCP tools after they mutate pixel data / layers / canvas.
+    """
+    name = project_name or state.active_project
+    if name is None:
+        return
+    project = state.get_project(name)
+    if project is None:
+        return
+    patch = build_full_state_patch(project)
+    await broadcast_patches(
+        connections, name, [patch], command_id=command_id, exclude_ws=exclude_ws,
+    )

package/server/tests/conftest.py

@@ -0,0 +1,17 @@
+import pytest
+from wesktop.testing import TestClient
+from pixelweaver.main import app, state
+
+
+@pytest.fixture
+def client():
+    return TestClient(app)
+
+
+@pytest.fixture(autouse=True)
+def _reset_state():
+    state.projects.clear()
+    state.active_project = None
+    yield
+    state.projects.clear()
+    state.active_project = None

package/server/tests/test_api.py

@@ -0,0 +1,96 @@
+"""Tests for the REST API endpoints."""
+
+from pixelweaver.main import state
+
+
+class TestCreateProject:
+    def test_create_returns_201(self, client, tmp_path):
+        """Creating a project should return 201 with project metadata."""
+        from pixelweaver.config import set_data_dir
+        set_data_dir(str(tmp_path))
+
+        response = client.post("/api/projects", json={
+            "name": "my-sprite",
+            "width": 32,
+            "height": 32,
+        })
+        assert response.status_code == 201
+        data = response.json()
+        assert data["name"] == "my-sprite"
+        assert data["width"] == 32
+
+    def test_create_duplicate_returns_409(self, client, tmp_path):
+        from pixelweaver.config import set_data_dir
+        set_data_dir(str(tmp_path))
+
+        body = {"name": "dup", "width": 16, "height": 16}
+        client.post("/api/projects", json=body)
+        response = client.post("/api/projects", json=body)
+        assert response.status_code == 409
+
+
+class TestListProjects:
+    def test_list_empty(self, client):
+        response = client.get("/api/projects")
+        assert response.status_code == 200
+        assert response.json() == {"projects": []}
+
+    def test_list_includes_created(self, client, tmp_path):
+        from pixelweaver.config import set_data_dir
+        set_data_dir(str(tmp_path))
+
+        client.post("/api/projects", json={"name": "proj-a", "width": 8, "height": 8})
+        response = client.get("/api/projects")
+        assert "proj-a" in response.json()["projects"]
+
+
+class TestGetProject:
+    def test_get_existing(self, client, tmp_path):
+        from pixelweaver.config import set_data_dir
+        set_data_dir(str(tmp_path))
+
+        client.post("/api/projects", json={"name": "proj-b", "width": 16, "height": 16})
+        response = client.get("/api/projects/proj-b")
+        assert response.status_code == 200
+        data = response.json()
+        assert data["name"] == "proj-b"
+        assert "canvases" in data
+
+    def test_get_nonexistent_returns_404(self, client):
+        response = client.get("/api/projects/no-such-project")
+        assert response.status_code == 404
+
+
+class TestDeleteProject:
+    def test_delete_existing_returns_204(self, client, tmp_path):
+        from pixelweaver.config import set_data_dir
+        set_data_dir(str(tmp_path))
+
+        client.post("/api/projects", json={"name": "to-delete", "width": 8, "height": 8})
+        response = client.delete("/api/projects/to-delete")
+        assert response.status_code == 204
+
+        # Verify it's gone
+        response = client.get("/api/projects/to-delete")
+        assert response.status_code == 404
+
+    def test_delete_nonexistent_returns_404(self, client):
+        response = client.delete("/api/projects/no-such-project")
+        assert response.status_code == 404
+
+
+class TestExportPng:
+    def test_export_returns_png(self, client, tmp_path):
+        from pixelweaver.config import set_data_dir
+        set_data_dir(str(tmp_path))
+
+        client.post("/api/projects", json={"name": "export-test", "width": 8, "height": 8})
+        response = client.get("/api/projects/export-test/export/png/canvas-0/0")
+        assert response.status_code == 200
+        assert response.headers["content-type"] == "image/png"
+        # PNG magic bytes
+        assert response.content[:8] == b"\x89PNG\r\n\x1a\n"
+
+    def test_export_nonexistent_project_returns_404(self, client):
+        response = client.get("/api/projects/nope/export/png/canvas-0/0")
+        assert response.status_code == 404

package/server/tests/test_bridge.py

@@ -0,0 +1,161 @@
+"""Tests for DesktopBridge (pywebview file I/O bridge)."""
+
+import base64
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from pixelweaver.bridge import DesktopBridge
+
+
+@pytest.fixture()
+def mock_webview():
+    """Inject a mock webview module into sys.modules for late imports."""
+    mock = MagicMock()
+    mock.SAVE_DIALOG = 20
+    mock.OPEN_DIALOG = 10
+    mock.FOLDER_DIALOG = 30
+    with patch.dict(sys.modules, {"webview": mock}):
+        yield mock
+
+
+def test_save_file_writes_data(mock_webview, tmp_path):
+    """save_file decodes base64 data and writes it to the chosen path."""
+    mock_window = MagicMock()
+    mock_webview.windows = [mock_window]
+
+    out_path = str(tmp_path / "test.pwv")
+    mock_window.create_file_dialog.return_value = (out_path,)
+
+    bridge = DesktopBridge()
+    data = b"hello world"
+    result = bridge.save_file(
+        base64.b64encode(data).decode(), "test.pwv", "PixelWeaver", ["pwv"]
+    )
+
+    assert result == out_path
+    assert Path(out_path).read_bytes() == data
+    mock_window.create_file_dialog.assert_called_once_with(
+        20,
+        save_filename="test.pwv",
+        file_types=("PixelWeaver (*.pwv)",),
+    )
+
+
+def test_save_file_cancelled(mock_webview, tmp_path):
+    """save_file returns None when the user cancels the dialog."""
+    mock_window = MagicMock()
+    mock_webview.windows = [mock_window]
+    mock_window.create_file_dialog.return_value = None
+
+    bridge = DesktopBridge()
+    result = bridge.save_file(
+        base64.b64encode(b"data").decode(), "test.pwv", "PixelWeaver", ["pwv"]
+    )
+
+    assert result is None
+    # Nothing should have been written
+    assert not list(tmp_path.iterdir())
+
+
+def test_open_file_reads_data(mock_webview, tmp_path):
+    """open_file reads the selected file and returns path + base64 data."""
+    mock_window = MagicMock()
+    mock_webview.windows = [mock_window]
+
+    test_file = tmp_path / "image.png"
+    content = b"\x89PNG\r\n\x1a\nfake png data"
+    test_file.write_bytes(content)
+
+    mock_window.create_file_dialog.return_value = (str(test_file),)
+
+    bridge = DesktopBridge()
+    result = bridge.open_file("Images", ["png", "jpg"])
+
+    assert result is not None
+    assert result["path"] == str(test_file)
+    assert base64.b64decode(result["data"]) == content
+    mock_window.create_file_dialog.assert_called_once_with(
+        10,
+        file_types=("Images (*.png *.jpg)",),
+    )
+
+
+def test_open_file_cancelled(mock_webview):
+    """open_file returns None when the user cancels the dialog."""
+    mock_window = MagicMock()
+    mock_webview.windows = [mock_window]
+    mock_window.create_file_dialog.return_value = None
+
+    bridge = DesktopBridge()
+    result = bridge.open_file("Images", ["png"])
+
+    assert result is None
+
+
+def test_write_file_success(tmp_path):
+    """write_file decodes and writes data to the given path."""
+    out_path = str(tmp_path / "output.bin")
+    data = b"\x00\x01\x02\x03"
+
+    bridge = DesktopBridge()
+    result = bridge.write_file(out_path, base64.b64encode(data).decode())
+
+    assert result is True
+    assert Path(out_path).read_bytes() == data
+
+
+def test_write_file_creates_parent_dirs(tmp_path):
+    """write_file creates intermediate directories as needed."""
+    out_path = str(tmp_path / "deep" / "nested" / "dir" / "file.dat")
+    data = b"nested file content"
+
+    bridge = DesktopBridge()
+    result = bridge.write_file(out_path, base64.b64encode(data).decode())
+
+    assert result is True
+    assert Path(out_path).read_bytes() == data
+
+
+def test_pick_directory_returns_path(mock_webview):
+    """pick_directory returns the selected directory path."""
+    mock_window = MagicMock()
+    mock_webview.windows = [mock_window]
+    mock_window.create_file_dialog.return_value = ("/home/user/exports",)
+
+    bridge = DesktopBridge()
+    result = bridge.pick_directory()
+
+    assert result == "/home/user/exports"
+    mock_window.create_file_dialog.assert_called_once_with(30)
+
+
+def test_pick_directory_cancelled(mock_webview):
+    """pick_directory returns None when the user cancels."""
+    mock_window = MagicMock()
+    mock_webview.windows = [mock_window]
+    mock_window.create_file_dialog.return_value = None
+
+    bridge = DesktopBridge()
+    result = bridge.pick_directory()
+
+    assert result is None
+
+
+def test_write_files_to_directory(tmp_path):
+    """write_files_to_directory writes all files to the target directory."""
+    files = [
+        {"name": "frame_0.png", "data": base64.b64encode(b"png0").decode()},
+        {"name": "frame_1.png", "data": base64.b64encode(b"png1").decode()},
+        {"name": "sub/frame_2.png", "data": base64.b64encode(b"png2").decode()},
+    ]
+
+    bridge = DesktopBridge()
+    result = bridge.write_files_to_directory(str(tmp_path / "output"), files)
+
+    assert result is True
+    assert (tmp_path / "output" / "frame_0.png").read_bytes() == b"png0"
+    assert (tmp_path / "output" / "frame_1.png").read_bytes() == b"png1"
+    assert (tmp_path / "output" / "sub" / "frame_2.png").read_bytes() == b"png2"

package/server/tests/test_health.py

@@ -0,0 +1,9 @@
+"""Test the health check endpoint."""
+
+
+def test_health_returns_ok(client):
+    """Health endpoint should return 200 with status ok."""
+    response = client.get("/health")
+
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}

package/server/tests/test_integration.py

@@ -0,0 +1,86 @@
+"""Integration test: full project lifecycle through the API."""
+
+from pixelweaver.main import app
+from wesktop.testing import TestClient
+
+
+def test_project_lifecycle(client, tmp_path):
+    """Create, read, export, and delete a project."""
+    from pixelweaver.config import set_data_dir
+    set_data_dir(str(tmp_path))
+
+    # Create
+    resp = client.post("/api/projects", json={
+        "name": "integration-test",
+        "width": 16,
+        "height": 16,
+    })
+    assert resp.status_code == 201
+
+    # List
+    resp = client.get("/api/projects")
+    assert resp.status_code == 200
+    assert "integration-test" in resp.json()["projects"]
+
+    # Get
+    resp = client.get("/api/projects/integration-test")
+    assert resp.status_code == 200
+    data = resp.json()
+    assert "canvases" in data
+    assert len(data["canvases"]) > 0
+
+    # Export PNG
+    canvas_name = list(data["canvases"].keys())[0]
+    resp = client.get(f"/api/projects/integration-test/export/png/{canvas_name}/0")
+    assert resp.status_code == 200
+    assert resp.headers.get("content-type") == "image/png"
+    assert len(resp.content) > 0
+
+    # State endpoints (MCP bridge)
+    resp = client.get("/api/state/full")
+    assert resp.status_code == 200
+    state = resp.json()
+    assert "integration-test" in state.get("projects", {})
+
+    # Delete
+    resp = client.delete("/api/projects/integration-test")
+    assert resp.status_code == 204
+
+    # Verify deleted
+    resp = client.get("/api/projects/integration-test")
+    assert resp.status_code == 404
+
+
+def test_validation_errors(client):
+    """Test that invalid requests return proper error codes."""
+    # Invalid project name (special chars)
+    resp = client.post("/api/projects", json={
+        "name": "../evil",
+        "width": 16,
+        "height": 16,
+    })
+    assert resp.status_code == 422
+
+    # Width too large
+    resp = client.post("/api/projects", json={
+        "name": "too-big",
+        "width": 9999,
+        "height": 16,
+    })
+    assert resp.status_code == 422
+
+    # Missing fields
+    resp = client.post("/api/projects", json={"name": "incomplete"})
+    assert resp.status_code == 422
+
+    # Get nonexistent
+    resp = client.get("/api/projects/does-not-exist")
+    assert resp.status_code == 404
+
+    # Delete nonexistent
+    resp = client.delete("/api/projects/does-not-exist")
+    assert resp.status_code == 404
+
+    # Export from nonexistent
+    resp = client.get("/api/projects/nope/export/png/canvas-0/0")
+    assert resp.status_code == 404