pixelweaver 0.1.0

package/scripts/migrate-single-frame-to-multi.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+"""Migrate PixelWeaver projects from old single-frame format to multi-frame format.
+
+Old format (per canvas):
+    canvases/<canvas_name>/
+        canvas.json
+        frames/0/
+            layer-<id>.png
+
+New format (per canvas):
+    canvases/<canvas_name>/
+        canvas.json
+        frames.json           -- frame manifest with IDs, durations, playback state
+        frames/<uuid>/        -- UUID-named directory instead of "0"
+            layer-<id>.png
+
+This script is idempotent: canvases that already have a frames.json are skipped.
+It can safely be run multiple times against the same data directory.
+
+The default PixelWeaver data directory is "./projects" (relative to the server
+working directory), configurable via the --data-dir CLI flag when running the
+PixelWeaver server.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import uuid
+from pathlib import Path
+
+
+def find_projects(data_dir: Path) -> list[Path]:
+    """Return paths to all project directories (those containing project.json)."""
+    if not data_dir.is_dir():
+        return []
+    return sorted(
+        d for d in data_dir.iterdir()
+        if d.is_dir() and (d / "project.json").exists()
+    )
+
+
+def find_canvases(project_dir: Path) -> list[Path]:
+    """Return paths to all canvas directories within a project."""
+    canvases_dir = project_dir / "canvases"
+    if not canvases_dir.is_dir():
+        return []
+    return sorted(
+        d for d in canvases_dir.iterdir() if d.is_dir()
+    )
+
+
+def migrate_canvas(canvas_dir: Path, *, dry_run: bool) -> str | None:
+    """Migrate a single canvas from old format to new format.
+
+    Returns a description of what was done, or None if the canvas was skipped.
+    """
+    frames_json_path = canvas_dir / "frames.json"
+    old_frame_dir = canvas_dir / "frames" / "0"
+
+    # Already migrated -- frames.json exists
+    if frames_json_path.exists():
+        return None
+
+    # No old-format data to migrate
+    if not old_frame_dir.is_dir():
+        return None
+
+    frame_id = str(uuid.uuid4())
+    new_frame_dir = canvas_dir / "frames" / frame_id
+
+    frames_manifest = {
+        "frames": [{"id": frame_id, "duration_ms": None}],
+        "current_frame_index": 0,
+        "global_fps": 12.0,
+        "origin_x": 0,
+        "origin_y": 0,
+    }
+
+    if dry_run:
+        return (
+            f"  Would rename frames/0/ -> frames/{frame_id}/\n"
+            f"  Would create frames.json"
+        )
+
+    # Rename the directory first, then write the manifest.
+    # If the rename succeeds but the write fails, re-running the script
+    # won't find frames/0/ and will skip -- no data loss.
+    old_frame_dir.rename(new_frame_dir)
+    frames_json_path.write_text(json.dumps(frames_manifest, indent=2))
+
+    return (
+        f"  Renamed frames/0/ -> frames/{frame_id}/\n"
+        f"  Created frames.json"
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Migrate PixelWeaver projects from old single-frame (frames/0/) format "
+            "to the new multi-frame (frames/<uuid>/ + frames.json) format."
+        ),
+        epilog=(
+            "The default PixelWeaver data directory is './projects' (relative to the "
+            "server working directory), configurable via the --data-dir flag on the "
+            "PixelWeaver CLI."
+        ),
+    )
+    parser.add_argument(
+        "--data-dir",
+        type=Path,
+        required=True,
+        help="Base directory containing PixelWeaver projects (e.g. ./projects)",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Show what would be done without making any changes",
+    )
+    args = parser.parse_args(argv)
+
+    data_dir: Path = args.data_dir.expanduser().resolve()
+    dry_run: bool = args.dry_run
+
+    if not data_dir.is_dir():
+        print(f"Error: data directory does not exist: {data_dir}", file=sys.stderr)
+        return 1
+
+    if dry_run:
+        print("[DRY RUN] No changes will be made.\n")
+
+    projects = find_projects(data_dir)
+    if not projects:
+        print(f"No projects found in {data_dir}")
+        return 0
+
+    total_migrated = 0
+    total_skipped = 0
+
+    for project_dir in projects:
+        project_name = project_dir.name
+        canvases = find_canvases(project_dir)
+
+        if not canvases:
+            continue
+
+        print(f"Project: {project_name}")
+
+        for canvas_dir in canvases:
+            canvas_name = canvas_dir.name
+            result = migrate_canvas(canvas_dir, dry_run=dry_run)
+
+            if result is None:
+                total_skipped += 1
+            else:
+                total_migrated += 1
+                print(f"  Canvas: {canvas_name}")
+                print(result)
+
+    # Summary
+    print()
+    verb = "would be" if dry_run else "were"
+    print(f"Done. {total_migrated} canvas(es) {verb} migrated, {total_skipped} skipped.")
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/smoke-test.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Smoke test: start server, run CRUD checks, verify SPA serving
+# Usage: ./scripts/smoke-test.sh [--with-frontend]
+#
+# --with-frontend: also build the frontend and verify SPA/static serving
+
+PORT=7799
+BASE="http://127.0.0.1:$PORT"
+SERVER_PID=""
+
+cleanup() {
+    if [ -n "$SERVER_PID" ]; then
+        kill "$SERVER_PID" 2>/dev/null || true
+        wait "$SERVER_PID" 2>/dev/null || true
+    fi
+}
+trap cleanup EXIT
+
+WITH_FRONTEND=false
+if [ "${1:-}" = "--with-frontend" ]; then
+    WITH_FRONTEND=true
+fi
+
+echo "=== Building frontend ==="
+if $WITH_FRONTEND; then
+    npm run build
+fi
+
+echo "=== Starting server on port $PORT ==="
+uv run pixelweaver serve --port "$PORT" &
+SERVER_PID=$!
+
+# Wait for server
+for i in $(seq 1 30); do
+    if curl -sf "$BASE/health" > /dev/null 2>&1; then
+        break
+    fi
+    sleep 0.5
+done
+
+echo "=== Health check ==="
+curl -sf "$BASE/health" | python3 -c "import sys,json; d=json.load(sys.stdin); assert d['status']=='ok'; print('PASS')"
+
+echo "=== Create project ==="
+curl -sf -X POST "$BASE/api/projects" \
+    -H "Content-Type: application/json" \
+    -d '{"name":"smoke","width":32,"height":32}' > /dev/null
+echo "PASS"
+
+echo "=== List projects ==="
+curl -sf "$BASE/api/projects" | python3 -c "import sys,json; d=json.load(sys.stdin); assert 'smoke' in d['projects']; print('PASS')"
+
+echo "=== Get project ==="
+curl -sf "$BASE/api/projects/smoke" | python3 -c "import sys,json; d=json.load(sys.stdin); assert 'canvases' in d; print('PASS')"
+
+echo "=== Export PNG ==="
+STATUS=$(curl -sf -o /dev/null -w "%{http_code}" "$BASE/api/projects/smoke/export/png/canvas-0/0")
+[ "$STATUS" = "200" ] && echo "PASS" || (echo "FAIL: $STATUS"; exit 1)
+
+echo "=== Delete project ==="
+STATUS=$(curl -sf -o /dev/null -w "%{http_code}" -X DELETE "$BASE/api/projects/smoke")
+[ "$STATUS" = "204" ] && echo "PASS" || (echo "FAIL: $STATUS"; exit 1)
+
+if $WITH_FRONTEND && [ -f dist/index.html ]; then
+    echo "=== SPA root ==="
+    STATUS=$(curl -sf -o /dev/null -w "%{http_code}" "$BASE/")
+    [ "$STATUS" = "200" ] && echo "PASS" || (echo "FAIL: $STATUS"; exit 1)
+
+    echo "=== SPA fallback ==="
+    STATUS=$(curl -sf -o /dev/null -w "%{http_code}" "$BASE/unknown/path")
+    [ "$STATUS" = "200" ] && echo "PASS" || (echo "FAIL: $STATUS"; exit 1)
+fi
+
+echo ""
+echo "=== ALL SMOKE TESTS PASSED ==="

package/selfdoc.json

@@ -0,0 +1,10 @@
+{
+  "language": "python",
+  "source": [
+    "server/src/"
+  ],
+  "docs": "docs/",
+  "output": "docs/_build/",
+  "base_url": "https://pixelweaver.smmh.dev",
+  "root_files": ["docs/_README.md"]
+}

package/server/src/pixelweaver/__init__.py

@@ -0,0 +1 @@
+"""PixelWeaver collaboration server."""

package/server/src/pixelweaver/__main__.py

@@ -0,0 +1,4 @@
+"""Enable python -m pixelweaver."""
+from pixelweaver.cli import main
+
+main()

package/server/src/pixelweaver/autosave.py

@@ -0,0 +1,114 @@
+"""Auto-save: periodic flush of in-memory state to disk.
+
+The auto-saver runs as an asyncio background task. State is saved when:
+    - A debounce timer expires after the last state mutation, OR
+    - A fixed interval elapses since the last save
+
+Whichever fires first triggers a save, preventing both data loss and
+excessive I/O.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+
+from pixelweaver.state import ServerState
+from pixelweaver.storage import save_project
+
+logger = logging.getLogger(__name__)
+
+
+class AutoSaver:
+    """Periodically flushes server state to disk."""
+
+    def __init__(
+        self,
+        state: ServerState,
+        save_dir: str,
+        debounce_ms: int = 500,
+        interval_s: int = 30,
+    ) -> None:
+        self.state = state
+        self.save_dir = save_dir
+        self.debounce_ms = debounce_ms
+        self.interval_s = interval_s
+        self._dirty = False
+        self._last_save: float = 0
+        self._task: asyncio.Task[None] | None = None
+        self._debounce_task: asyncio.Task[None] | None = None
+
+    def mark_dirty(self) -> None:
+        """Called after any state change to schedule a debounced save."""
+        self._dirty = True
+        # Reset the debounce timer
+        if self._debounce_task is not None and not self._debounce_task.done():
+            self._debounce_task.cancel()
+        self._debounce_task = asyncio.ensure_future(self._debounce_save())
+
+    async def _debounce_save(self) -> None:
+        """Wait for the debounce period, then save if still dirty."""
+        try:
+            await asyncio.sleep(self.debounce_ms / 1000.0)
+            if self._dirty:
+                await self.save_now()
+        except asyncio.CancelledError:
+            pass  # Debounce was reset by a newer mutation
+
+    async def start(self) -> None:
+        """Start the auto-save background task (periodic interval saves)."""
+        self._task = asyncio.ensure_future(self._periodic_loop())
+        logger.info(
+            "Auto-saver started (debounce=%dms, interval=%ds, dir=%s)",
+            self.debounce_ms,
+            self.interval_s,
+            self.save_dir,
+        )
+
+    async def stop(self) -> None:
+        """Stop the background task gracefully, saving any pending changes."""
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        if self._debounce_task is not None:
+            self._debounce_task.cancel()
+        # Final save if dirty
+        if self._dirty:
+            await self.save_now()
+
+    async def _periodic_loop(self) -> None:
+        """Run periodic saves on a fixed interval."""
+        try:
+            while True:
+                await asyncio.sleep(self.interval_s)
+                if self._dirty:
+                    await self.save_now()
+        except asyncio.CancelledError:
+            pass
+
+    async def save_now(self) -> None:
+        """Flush all project state to disk immediately."""
+        if not self.state.projects:
+            self._dirty = False
+            return
+
+        # Track per-loop failures so a single failed project doesn't lose
+        # the dirty marker for the rest. _dirty is a single flag here, so
+        # if anything failed we leave it set and the next debounce/interval
+        # tick will retry the whole batch.
+        any_failed = False
+        for project in self.state.projects.values():
+            try:
+                await asyncio.to_thread(save_project, project, self.save_dir)
+            except Exception:
+                any_failed = True
+                logger.error("Failed to save project %s", project.name, exc_info=True)
+
+        if not any_failed:
+            self._dirty = False
+        self._last_save = time.monotonic()
+        logger.debug("Auto-saved %d project(s) to %s", len(self.state.projects), self.save_dir)

package/server/src/pixelweaver/bridge.py

@@ -0,0 +1,127 @@
+"""Desktop file I/O bridge for pywebview.
+
+Provides native file dialogs and filesystem access callable from JavaScript
+via pywebview's js_api mechanism.  All binary data is transferred as
+base64-encoded strings since the JS bridge serializes return values as JSON.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class DesktopBridge:
+    """File I/O bridge exposed to the frontend via pywebview js_api.
+
+    Methods on this class become callable from JavaScript as:
+        window.pywebview.api.method_name(args)
+    """
+
+    def save_file(
+        self,
+        data_b64: str,
+        default_name: str,
+        filter_name: str,
+        extensions: list[str],
+    ) -> str | None:
+        """Show a native Save dialog and write the file.
+
+        Returns the saved file path, or None if the user cancelled.
+        """
+        import webview
+
+        window = webview.windows[0]
+        file_types = (f"{filter_name} ({' '.join('*.' + e for e in extensions)})",)
+        result = window.create_file_dialog(
+            webview.SAVE_DIALOG,
+            save_filename=default_name,
+            file_types=file_types,
+        )
+        if not result:
+            return None
+        path = result if isinstance(result, str) else result[0]
+        try:
+            data = base64.b64decode(data_b64)
+            Path(path).parent.mkdir(parents=True, exist_ok=True)
+            Path(path).write_bytes(data)
+            return path
+        except Exception:
+            logger.exception("Failed to write file %s", path)
+            return None
+
+    def open_file(
+        self,
+        filter_name: str,
+        extensions: list[str],
+    ) -> dict | None:
+        """Show a native Open dialog and read the file.
+
+        Returns {"path": str, "data": base64_string} or None if cancelled.
+        """
+        import webview
+
+        window = webview.windows[0]
+        file_types = (f"{filter_name} ({' '.join('*.' + e for e in extensions)})",)
+        result = window.create_file_dialog(
+            webview.OPEN_DIALOG,
+            file_types=file_types,
+        )
+        if not result:
+            return None
+        path = result[0] if isinstance(result, (tuple, list)) else result
+        try:
+            data = Path(path).read_bytes()
+            return {
+                "path": str(path),
+                "data": base64.b64encode(data).decode("ascii"),
+            }
+        except Exception:
+            logger.exception("Failed to read file %s", path)
+            return None
+
+    def write_file(self, path: str, data_b64: str) -> bool:
+        """Write binary data to a specific path (no dialog)."""
+        try:
+            data = base64.b64decode(data_b64)
+            Path(path).parent.mkdir(parents=True, exist_ok=True)
+            Path(path).write_bytes(data)
+            return True
+        except Exception:
+            logger.exception("Failed to write file %s", path)
+            return False
+
+    def pick_directory(self) -> str | None:
+        """Show a native directory picker. Returns path or None if cancelled."""
+        import webview
+
+        window = webview.windows[0]
+        result = window.create_file_dialog(webview.FOLDER_DIALOG)
+        if not result:
+            return None
+        return result[0] if isinstance(result, (tuple, list)) else str(result)
+
+    def write_files_to_directory(
+        self,
+        dir_path: str,
+        files: list[dict],
+    ) -> bool:
+        """Write multiple files to a directory.
+
+        Each entry in files should be {"name": str, "data": base64_string}.
+        """
+        try:
+            base = Path(dir_path)
+            base.mkdir(parents=True, exist_ok=True)
+            for entry in files:
+                file_path = base / entry["name"]
+                file_path.parent.mkdir(parents=True, exist_ok=True)
+                data = base64.b64decode(entry["data"])
+                file_path.write_bytes(data)
+            return True
+        except Exception:
+            logger.exception("Failed to write files to %s", dir_path)
+            return False