feat: floor plan viewport rendering, per-canvas config, server media upload

- Render floor plan inside React Flow ViewportPortal so it pans/zooms with
  nodes (was screen-fixed, desynced on pan/zoom); zoom-stable resize handles.
- Move floor plan config from the left panel into the canvas (design) edit
  modal; attach per-design and fix cross-design bleed on load.
- Store images via a new generic backend media endpoint (POST/GET/DELETE
  /api/v1/media) on disk under <data_dir>/uploads, not base64 in the canvas.
- Disable floor plans in standalone mode (no backend to upload/serve); drop
  base64 localStorage persistence. See ADR-001 in CLAUDE.md.
- Tests: backend media route, DesignModal floor plan + upload, store floorMap.

ha-relevant: maybe

backend/app/api/routes/media.py

@@ -0,0 +1,89 @@
+"""Generic media upload/serve endpoint.
+
+Images are stored on disk (see `Settings.media_dir`) with server-generated
+UUID filenames — never in the DB, and the client filename is never trusted.
+Upload/delete require auth; GET is public so plain <img> tags and the read-only
+live view can load images (filenames are unguessable).
+
+Currently used by the floor-plan feature; kept deliberately generic so future
+raw-image uploads reuse the same endpoint.
+"""
+
+import re
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, status
+from fastapi.responses import FileResponse
+
+from app.api.deps import get_current_user
+from app.core.config import settings
+
+router = APIRouter()
+
+# content-type → extension. Also the allowlist of accepted uploads.
+ALLOWED_TYPES: dict[str, str] = {
+    "image/png": ".png",
+    "image/jpeg": ".jpg",
+    "image/webp": ".webp",
+}
+
+# Magic-byte signatures for defense-in-depth (don't trust content-type alone).
+_MAGIC: dict[str, tuple[bytes, ...]] = {
+    ".png": (b"\x89PNG\r\n\x1a\n",),
+    ".jpg": (b"\xff\xd8\xff",),
+    ".webp": (b"RIFF",),  # RIFF....WEBP; RIFF prefix is enough to reject non-images
+}
+
+MAX_BYTES = 10 * 1024 * 1024  # 10 MB
+
+# Only ever serve/delete files we created: 32 hex chars + known extension.
+_NAME_RE = re.compile(r"^[0-9a-f]{32}\.(png|jpg|webp)$")
+
+
+@router.post("/upload")
+async def upload_media(file: UploadFile, _user: str = Depends(get_current_user)) -> dict[str, str]:
+    ext = ALLOWED_TYPES.get(file.content_type or "")
+    if ext is None:
+        raise HTTPException(
+            status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
+            detail="Unsupported media type — PNG, JPEG, or WebP only",
+        )
+    # Read one byte past the cap so we can detect oversize without loading more.
+    data = await file.read(MAX_BYTES + 1)
+    if len(data) > MAX_BYTES:
+        raise HTTPException(
+            status_code=status.HTTP_413_CONTENT_TOO_LARGE,
+            detail="File too large (max 10 MB)",
+        )
+    if not data:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Empty file")
+    if not any(data.startswith(sig) for sig in _MAGIC[ext]):
+        raise HTTPException(
+            status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
+            detail="File content does not match its type",
+        )
+
+    media_dir = settings.media_dir()
+    media_dir.mkdir(parents=True, exist_ok=True)
+    name = f"{uuid.uuid4().hex}{ext}"
+    (media_dir / name).write_bytes(data)
+    return {"filename": name, "url": f"/api/v1/media/{name}"}
+
+
+@router.get("/{filename}")
+async def get_media(filename: str) -> FileResponse:
+    if not _NAME_RE.match(filename):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Not found")
+    path = settings.media_dir() / filename
+    if not path.is_file():
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Not found")
+    return FileResponse(path)
+
+
+@router.delete("/{filename}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_media(filename: str, _user: str = Depends(get_current_user)) -> None:
+    if not _NAME_RE.match(filename):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Not found")
+    path = settings.media_dir() / filename
+    if path.is_file():
+        path.unlink()

backend/app/core/config.py

@@ -24,6 +24,10 @@ class Settings(BaseSettings):
 
     secret_key: str  # Required — set SECRET_KEY in .env
     sqlite_path: str = "./data/homelab.db"
+    # Uploaded media (floor plans, and future raw image uploads) live on disk,
+    # not in the DB. Defaults to a `uploads/` folder next to the SQLite DB so it
+    # sits on the same persistent Docker volume. Override with UPLOAD_DIR.
+    upload_dir: str = ""
     cors_origins: list[str] = ["http://localhost:5173", "http://localhost:3000"]
 
     # JWT
@@ -79,6 +83,13 @@ class Settings(BaseSettings):
     def _override_path(self) -> Path:
         return Path(self.sqlite_path).parent / "scan_config.json"
 
+    def media_dir(self) -> Path:
+        """On-disk folder for uploaded media. Sits on the same persistent
+        volume as the SQLite DB unless UPLOAD_DIR is set."""
+        if self.upload_dir:
+            return Path(self.upload_dir)
+        return Path(self.sqlite_path).parent / "uploads"
+
     def load_overrides(self) -> None:
         """Load runtime scan config overrides written by the API."""
         try:

backend/app/main.py

@@ -7,7 +7,7 @@ from typing import Any
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
-from app.api.routes import auth, canvas, designs, edges, liveview, nodes, scan, stats, status, zigbee, zwave
+from app.api.routes import auth, canvas, designs, edges, liveview, media, nodes, scan, stats, status, zigbee, zwave
 from app.api.routes import settings as settings_routes
 from app.core.config import settings
 from app.core.scheduler import start_scheduler, stop_scheduler
@@ -59,6 +59,7 @@ app.include_router(liveview.router, prefix="/api/v1/liveview", tags=["liveview"]
 app.include_router(zigbee.router, prefix="/api/v1/zigbee", tags=["zigbee"])
 app.include_router(zwave.router, prefix="/api/v1/zwave", tags=["zwave"])
 app.include_router(stats.router, prefix="/api/v1/stats", tags=["stats"])
+app.include_router(media.router, prefix="/api/v1/media", tags=["media"])
 
 
 @app.get("/api/v1/health")

backend/tests/test_media.py

@@ -0,0 +1,94 @@
+import re
+
+import pytest
+
+from app.api.routes import media
+from app.core.config import settings
+
+PNG_BYTES = b"\x89PNG\r\n\x1a\n" + b"0" * 32
+
+
+@pytest.fixture
+def media_dir(tmp_path, monkeypatch):
+    """Point uploads at a temp folder for the duration of a test."""
+    monkeypatch.setattr(settings, "upload_dir", str(tmp_path))
+    return tmp_path
+
+
+async def _upload(client, headers, name="plan.png", data=PNG_BYTES, content_type="image/png"):
+    return await client.post(
+        "/api/v1/media/upload",
+        files={"file": (name, data, content_type)},
+        headers=headers,
+    )
+
+
+@pytest.mark.asyncio
+async def test_upload_requires_auth(client, media_dir):
+    res = await _upload(client, headers={})
+    assert res.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_upload_stores_file_and_returns_url(client, auth_headers, media_dir):
+    headers = await auth_headers()
+    res = await _upload(client, headers)
+    assert res.status_code == 200
+    body = res.json()
+    assert re.fullmatch(r"/api/v1/media/[0-9a-f]{32}\.png", body["url"])
+    # File written to disk with the server-generated name (client name ignored).
+    assert (media_dir / body["filename"]).read_bytes() == PNG_BYTES
+    assert body["filename"] != "plan.png"
+
+
+@pytest.mark.asyncio
+async def test_upload_rejects_unsupported_type(client, auth_headers, media_dir):
+    headers = await auth_headers()
+    res = await _upload(client, headers, name="a.txt", data=b"hello", content_type="text/plain")
+    assert res.status_code == 415
+
+
+@pytest.mark.asyncio
+async def test_upload_rejects_content_type_magic_mismatch(client, auth_headers, media_dir):
+    headers = await auth_headers()
+    # Claims PNG but bytes are not a PNG.
+    res = await _upload(client, headers, data=b"not-a-real-png", content_type="image/png")
+    assert res.status_code == 415
+
+
+@pytest.mark.asyncio
+async def test_upload_rejects_oversize(client, auth_headers, media_dir, monkeypatch):
+    monkeypatch.setattr(media, "MAX_BYTES", 8)
+    headers = await auth_headers()
+    res = await _upload(client, headers, data=PNG_BYTES)  # > 8 bytes
+    assert res.status_code == 413
+
+
+@pytest.mark.asyncio
+async def test_get_serves_uploaded_file(client, auth_headers, media_dir):
+    headers = await auth_headers()
+    up = await _upload(client, headers)
+    res = await client.get(up.json()["url"])  # public, no auth
+    assert res.status_code == 200
+    assert res.content == PNG_BYTES
+
+
+@pytest.mark.asyncio
+async def test_get_rejects_bad_filename(client, media_dir):
+    res = await client.get("/api/v1/media/..%2f..%2fetc%2fpasswd")
+    assert res.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_delete_requires_auth_and_removes_file(client, auth_headers, media_dir):
+    headers = await auth_headers()
+    up = await _upload(client, headers)
+    filename = up.json()["filename"]
+
+    assert (await client.delete(f"/api/v1/media/{filename}")).status_code == 401
+    assert (media_dir / filename).exists()
+
+    res = await client.delete(f"/api/v1/media/{filename}", headers=headers)
+    assert res.status_code == 204
+    assert not (media_dir / filename).exists()
+    assert (await client.get(up.json()["url"])).status_code == 404